The endpoint
POST /mcp/v1/context is an MCP server over Streamable HTTP (JSON-RPC 2.0, protocol 2024-11-05). It is a full path, outside /api/v1, served behind the same authentication as the API: the caller is the signed-in person, and an anonymous request is 401. Every tool call runs as that person, with their permissions.
Tools
| Tool | Arguments | What it does |
|---|---|---|
keystone_context_retrieve | query, repo_url?, project_path?, token_budget (default 2048) | Runs the regular retrieval: authorisation per space, DLP, budget and attribution. token_budget must be positive and is capped at 32000 |
keystone_policy_check | action, resource? | Asks the governance decision point for the caller: {"decision": "allow"} or {"decision": "deny"}. An error fails closed |
keystone_context_attribute | attribution_id, request_id? | Records that an AI response used a retrieval: a context_attribution_link record in the same evidence chain, idempotent per attribution and response |
repo_url (an https, ssh or scp-like git remote) selects the project space that has a codebase source for that repository; with none, the organisation space is used. When two projects hold the repository, the tool answers context.space.repo_ambiguous instead of guessing. project_path is local to the agent and not used by the server.
Only the person who retrieved, or a context:space:admin of the space, may link an attribution. The record is written asynchronously, so keystone_context_attribute called immediately after a retrieval may answer context.attribution.not_found: retry.
Tokens
MCP access tokens are a person's tokens. There is no long-lived user-level token for an MCP client: API keys are organisation-level and carry no person, so per-person space authorisation would not be possible with them.
Other ways to the same retrieval
| Caller | Route | Authentication |
|---|---|---|
| The Editor, the Agents app, the CLI | POST /api/v1/context/retrieve | The person's access token; X-Keystone-Client: name/version recorded in the attribution |
| MCP clients | POST /mcp/v1/context | The person's access token |
| The endpoint agent | POST /api/v1/context/agent/retrieve, GET /api/v1/context/agent/project | The device token; the server runs the request as the device's bound user, with that user's own permissions |
Local tools never call the agent routes themselves and never get a token: they ask the endpoint agent over its local socket, which accepts only processes of the agent's own operating system user (by peer credentials), and the agent forwards the request with its device token. A revoked device is 410; an unbound device 403.
Capabilities for first-party apps
GET /api/v1/context/capabilities (any signed-in member) tells an app which features to offer, without administrator rights. It returns booleans and limits only: retrieval, retrievalMaxTokenBudget, retrievalDefaultTokenBudget, retrievalMaxPerLevel, embeddings, indexing, attribution, collaboration, events, memory, presence, lensSharing, handoffs, pairSessions, workRegistry, agentFiles, agentFilesMaxSizeBytes, customShares, customSharesMaxFiles, customSharesMaxFileSizeBytes.
A member is true only when the deployment serves the feature and the caller's own collaboration policy allows it. A policy that cannot be resolved is 503 context.collab_policy.unavailable, never a guess. The answer names no URL, key, model or identifier. A client treats a member it does not know as false.