# Vault over MCP



The [Vault](/platform/vault/overview) 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 Read-then-write Rule [#the-read-then-write-rule]

Every update operation 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" }]
}
→ { "path": "brand/voice.md", "revision": "r_8f21…", "content": "# How we write\n…" }

apply_vault_changes {
  "commitMessage": "Ban 'seamless'",
  "operations": [{
    "type": "update",
    "path": "brand/voice.md",
    "revision": "r_8f21…",
    "content": "# How we write\n…\nseamless is banned.\n"
  }]
}
```

## Reading Less [#reading-less]

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

<Steps>
  <Step title="Scope by prefix">
    `browse_vault { "pathPrefix": "competitors/" }` rather than listing
    everything. This is what
    [folder structure](/platform/vault/structure) is for.
  </Step>

  <Step title="Read the two or three that matter">
    It takes up to 10, but 10 long documents is usually more context than the
    task needs.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Creating the First Vault [#creating-the-first-vault]

`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](/platform/vault/getting-docs-in).

## Batching Edits [#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": [
    { "type": "move",   "from": "brand-book.md", "to": "brand/voice.md", "revision": "r_1…" },
    { "type": "create", "path": "brand/boilerplate.md", "content": "…" },
    { "type": "delete", "path": "old/legacy-tone.md", "revision": "r_9…" }
  ]
}
```

Write a real `commitMessage`.

<Warning>
  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.
</Warning>

[Vault overview](/platform/vault/overview) ·
[Tool reference](/mcp-server/tools#vault) ·
[Tool bundles](/mcp-server/tool-bundles)