MCP
The MCP endpoint every pod serves, how clients authenticate to it, and what it exposes.
Every pod serves a Model Context Protocol (MCP) server at /mcp, for example https://pod.example.com/mcp. AI
clients use it to read your pod and to change it, under the permissions of their key and the agent's write mode.
Most people never configure it by hand: synap connect <client> writes the client's MCP configuration. See
Connect your AI.
Transport
MCP Streamable HTTP:
| Request | Purpose |
|---|---|
POST /mcp | A JSON-RPC 2.0 request. The answer is JSON or an SSE stream. |
GET /mcp | An SSE stream for messages the server initiates. |
DELETE /mcp | Ends the session. |
The server negotiates the protocol version with the client; it is not pinned to one revision.
Authentication
Send a key as a bearer token:
Authorization: Bearer <key>- A request without a valid key gets
401with aWWW-Authenticate: Bearer resource_metadata="…"header pointing at the pod's OAuth metadata (/.well-known/oauth-protected-resource). Clients such as claude.ai use it to sign in through the pod's own OAuth server and obtain a key, with no key to paste. - Too many requests get
429.
Scopes
The tools a key can call depend on its scopes:
| Key scope | MCP access |
|---|---|
mcp.read, hub-protocol.read or data.read | read tools |
mcp.write, hub-protocol.write or data.write | read and write tools |
hub-protocol.admin | read and write tools |
A key with none of these can call no tool. A key whose grant is narrower than full access can read only through the
tools whose reads its grant bounds; other read tools answer GRANT_DOOR_UNSUPPORTED. See
API keys.
Governance
Every write tool goes through the same permission check as any other write to the pod, then through the
validation policy. Under the default write mode, creates and edits apply directly
and can be undone; deletions, schema and structural changes, and admin actions become a proposal that a person
approves. A tool that answers status: "proposed" has succeeded: the change waits for review. No MCP tool can approve
a proposal with an agent's key.
Tools
All tool names start with synap_, for example synap_ask to ask the pod a question in natural language. A new
agent key lists a small entry set of tools and loads the others in groups. MCP tools
lists every tool with its parameters, generated from the backend's tool definitions.
Test the endpoint
synap mcp verifychecks that /mcp answers and that your key is valid.