Maintain a living document with your agent

A resource is content your agent reads over MCP — a runbook, a conventions doc, an API cheat-sheet, a decisions log. With the management tools the agent doesn't only read it; it maintains it — adding what it learns and correcting what's gone stale, so the context it relies on gets better over time.

It's the same loop as optimizing a prompt from a session, applied to knowledge instead of instructions: use what happened this session to improve what the agent reads next time.

The loop

1. Give the agent a document to work from. Create it with create_resource — a path (its address, e.g. reference/runbook.md) and some initial content. A client whose credential can reach the resource can then read it with resources/read.
2. Find before you write. grep_resource searches inside the resource and returns the matching lines with their line numbers and the document's current version — without pulling the whole file. Use it to check whether a fact is already recorded (so you don't duplicate it) and to locate where it belongs.
3. Record the change in place. patch_resource applies targeted edits — insert a line, replace a value, add a section — sending only the change instead of re-uploading the file. Pass the version you just read as expected_version so a change someone else made in the meantime is reported as a conflict rather than being silently overwritten.
4. Notify subscribed consumers. When the resource changes, the server sends a best-effort resources/updated notification to subscribed clients, so they can pick up the new knowledge without routine polling. If a client misses the notification, its next resources/read still returns the current content.

Example

Your agent just discovered that the staging deploy needs a flag. Instead of only using that this session, it writes it into the runbook.

First it searches — to confirm it isn't already noted, and to read the current version:

{ "path": "reference/runbook.md", "query": "staging deploy", "ignore_case": true }

{
	"path": "reference/runbook.md",
	"matches": [{ "line": 24, "text": "### Staging deploy" }],
	"truncated": false,
	"version": 7
}

Then it inserts a note right after that heading, guarded by the version it read:

{
	"path": "reference/runbook.md",
	"expected_version": 7,
	"edits": [
		{
			"after_line": 24,
			"new_string": "\n> Staging deploy needs `--skip-cache`, or the CDN serves stale assets.\n"
		}
	]
}

{ "path": "reference/runbook.md", "id": "018f...c2a1", "version": 8 }

The next agent to read the runbook starts with that knowledge already in it.

Instruct your agent

A short standing instruction turns this into a habit:

Treat reference/runbook.md as our shared runbook. When you learn something durable — a gotcha, a convention, a fix — record it there instead of only using it this session. First grep_resource to check it isn't already written and to read the current version; then patch_resource to add it, passing that version as expected_version. Never re-upload the whole file.

Good to know

• version is a safety guard, not history. Every content write bumps the resource's version, and reading it back as expected_version protects concurrent edits from clobbering each other. Unlike a prompt, a resource keeps no restorable version history — the latest content is the content. Keep your own backup if a document is precious.
• Text only for grep_resource and patch_resource. They work on text resources. A binary resource — an image, a PDF, an archive — is replaced as a whole with update_resource, passing the version read with it as the required expected_version.
• Small changes over MCP, large files in the dashboard. A tool call carries content as a single JSON string, so there's a per-call size cap; patch_resource sidesteps it for edits by sending only the diff. Seed or replace a large document in the dashboard.
• Personal and team spaces. With a credential that represents you, omit team to work in your own space. To work in a team space, name a team the credential is bound to and allowed to manage. A userless organization credential must name such a team. Publishing to the organization catalogue stays a dashboard action.
• Every call is metered — each grep_resource, patch_resource, or create_resource counts once against your plan's tool-invocation allowance.