The agent endpoint (/mcp)
What the agent-facing endpoint exposes, so you can reason about what an agent principal can and cannot do.
/mcp is the one surface an agent principal reaches. It is a Model Context
Protocol endpoint over streamable HTTP, and this page is here so that you — running
the server — can reason about exactly what an agent can do through it. An agent
reaches no /v1 route at all.
How it authenticates and scopes
/mcp authenticates each request with the same bearer token as /v1:
Authorization: Bearer <agent token>Every call reaches only the agent's own vault, runs in its own vault-scoped
transaction, and resolves every field through the same grants the /v1 surface uses.
So /mcp and /v1 disclose the same grant-filtered payload — the endpoint is a
different transport, not a different set of permissions.
The six tools, and no seventh
The endpoint exposes exactly six tools:
| Tool | What it does |
|---|---|
schema_describe | The vault's current schema version and the collections and fields the caller's grants reach. |
tokens_describe | A token's collection and field — and nothing else. |
records_search | Find records by an exact match on a searchable field. |
records_get | Read a record, grant-filtered, in the read-resolution envelope shape. |
records_create | Create a record. |
records_update | Update a record's named fields. |
records_get and records_create/records_update are the same read and write logic
the /v1 records routes use, so an agent's read or write
lands and refuses exactly as an operator's would — filtered to what its grants
permit. An agent cannot write a client_encrypted value: it holds no device to seal
one.
There is no detokenisation tool. An agent cannot turn a token back into a value
here — and, because /v1 (which carries token resolution) is closed to agents, it
cannot do so anywhere. This is the mechanism that keeps the values behind an agent's
tokens out of its reach: a leaked agent transcript is a list of tokens.
When the vault is rotating or its keys are destroyed
The two vault states that refuse every /v1 route
surface on the tool surface too. A tool call made while the vault is rotating its
master key, or after its keys are destroyed, halts legibly rather than with an
unexplained failure:
- the tool returns its own error result — an error tool result carrying the same
coded error envelope (
vault_rotation_in_progressorvault_keys_destroyed) the/v1surface returns, so an agent branching on the error flag reads a refusal, not a protocol error; - and the endpoint answers a non-200 status — the refusal's own
409, not the200a successful call rides out on — so transport-level health and retry logic reads it as the failure it is.
So an agent's read or write stops under a latch exactly as an operator's /v1 call
does. The Errors page carries both codes.
The handshake
On connecting, the endpoint identifies itself as custodian, version 1.0, and
tells the agent how to begin:
Custodian's per-vault encrypted store. Authenticate with your principal's bearer token in the Authorization header; every call reaches only your own vault and only the collections and fields your grants permit. Start with schema_describe to learn the vault's current schema version and the shape your grants reach.