Vault over MCP

Read, search and edit the environment's knowledge Vault from any MCP client: four tools, one revision rule.

The Vault is part of the default connection, so these four tools work without any ?tools= selection.

Tool	Does
`browse_vault`	List or search documents. `query`, `pathPrefix`, `cursor`, `limit`.
`read_vault_documents`	Read up to 10 documents. Returns the `revision` an edit will need.
`create_vault`	Build the environment's first Vault from a public website URL.
`apply_vault_changes`	Create, update, move or delete up to 20 documents, atomically.

The Write Contract

apply_vault_changes takes a commitMessage and a list of operations. Each operation is one of four shapes, keyed on op:

{ "op": "create", "path": …, "title": …, "body": … }
{ "op": "update", "path": …, "title": …, "body": …, "revision": … }
{ "op": "move",   "fromPath": …, "toPath": …, "revision": … }
{ "op": "delete", "path": …, "revision": … }

Field	Rule
`commitMessage`	Required, 1 to 200 characters after trimming.
`operations`	1 to 20 per call. A path may appear only once in a batch.
`path` / `fromPath` / `toPath`	1 to 512 characters, a `.md` file inside a folder. New folders are created implicitly with their first document.
`title`	Required on create and update, 1 to 200 characters.
`body`	100,000 characters per operation, 200,000 across the batch.
`revision`	Required on update, move and delete. Format `sha256:` plus 64 hex characters, exactly as `read_vault_documents` returned it.

Two things that catch agents out:

Surface composes the frontmatter. That is why title is a separate field and not something you write into body. An agent that hand-writes a --- block gets it twice.
Uploads/ and root-level files are read-only, enforced in code rather than by prompt. brand-book.md is rejected; brand/voice.md is fine.

The Read-then-write Rule

Every update, move and delete must carry the revision returned by read_vault_documents. If the document changed since you read it, the whole call is rejected and nothing is partly applied.

read_vault_documents {
  "documents": [{ "path": "brand/voice.md" }]
}
→ { "documents": [{
    "path": "brand/voice.md",
    "title": "How We Write",
    "body": "…",
    "totalChars": 4120,
    "nextOffset": null,
    "revision": "sha256:9f2b…"
  }] }

apply_vault_changes {
  "commitMessage": "Ban 'seamless'",
  "operations": [{
    "op": "update",
    "path": "brand/voice.md",
    "title": "How We Write",
    "revision": "sha256:9f2b…",
    "body": "…\nseamless is banned.\n"
  }]
}

When It Fails

Every failure comes back as a code. One of them is not a failure:

Code	What to do
`MIRROR_STALE`	Nothing. The commit succeeded and only the Postgres read mirror lagged. Retrying duplicates the work.
`REVISION_CONFLICT`	Someone else wrote first. Re-read the document and reapply on the new revision.
`READ_ONLY_PATH`	The path is root-level or under `Uploads/`. Put it in a folder.
`INVALID_PATH`	Not a `.md` file in a folder, or the same path appears twice in one batch.
`DESTINATION_EXISTS`	A create or move target is already there. Update it instead.
`NOT_FOUND`	No document at that path.
`CONTENT_TOO_LARGE`	The batch is over 200,000 characters of `body`. Split it.
`VAULT_NOT_FOUND`	The environment has no Vault yet. Call `create_vault`.

Reading Less

browse_vault returns paths, titles and body snippets, enough to decide what is relevant. To keep context small:

Scope by prefix

browse_vault { "pathPrefix": "competitors/" } rather than listing everything. This is what folder structure is for.

Read the two or three that matter

It takes up to 10, but 10 long documents is usually more context than the task needs.

Use offset and maxChars on long documents

Both are per-document, so a 6,000-word file can be read in the region you care about.

create_vault takes one websiteUrl and builds the environment's first Vault from it: Surface crawls the public site and writes a first pass of what you do, who it is for and how you talk, for you to correct. See getting docs in.

Batching Edits

apply_vault_changes is transactional across up to 20 operations, so a restructure is one call rather than twenty:

apply_vault_changes {
  "commitMessage": "Split the brand book",
  "operations": [
    { "op": "move", "fromPath": "uploads-archive/brand-book.md",
      "toPath": "brand/voice.md", "revision": "sha256:1a04…" },
    { "op": "create", "path": "brand/boilerplate.md",
      "title": "Boilerplate", "body": "…" },
    { "op": "delete", "path": "old/legacy-tone.md", "revision": "sha256:9c77…" }
  ]
}

Write a real commitMessage.

A read-only connection (?readonly=1) exposes browse_vault and read_vault_documents only. That is how you let an agent read your positioning without editing it.

Vault overview · Tool reference · Tool bundles

The Write Contract

The Read-then-write Rule

When It Fails

Reading Less

Creating the First Vault

Batching Edits

On this page