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 propose changes to it, under the permissions of their key.
Most people never configure it by hand: synap connect <client> writes the client's MCP configuration. See
Connect an agent.
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: the change is applied only where a rule allows it, and otherwise becomes a proposal that a person approves. 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.