MCP endpoint

Cadence exposes its tools over the Model Context Protocol (MCP) as JSON-RPC over HTTP at POST /mcp. This is the same set of capabilities the HTTP API offers, addressed as MCP tools. Authenticate every call with a bearer token, exactly as for the HTTP API — see Authentication.

The tools listed to you are the ones your kind of principal can reach: an operator, who authenticates as a user, and a worker, which authenticates with a lease token, get different tool lists. Your space role — viewer, member, or admin — does not change the list, so it may include tools your role is not permitted to call. Naming a tool your kind of principal does not have returns unknown tool (code -32602); naming a tool your kind has but your role is not permitted to use is refused with -32002 (see Error codes).

Transport

Send JSON-RPC 2.0 requests to POST /mcp. The protocol version is 2025-06-18.

GET /mcp is not a message channel: it returns 405 with an Allow: POST header.

Methods

initialize

initialize returns the protocol version, the server's capabilities, and its server information:

{
  "protocolVersion": "2025-06-18",
  "capabilities": { "tools": { "listChanged": false } },
  "serverInfo": { "name": "…", "version": "…" }
}

Send the notifications/initialized notification after initializing; it is acknowledged with an empty 202 response.

tools/list

tools/list returns the tools available to you, each with its input schema. The list is scoped to your kind of principal — operator or worker — not to your space role, so it may hold tools your role is not permitted to call.

tools/call

tools/call runs a tool. Pass the tool name and its arguments. The result carries the tool's output both as text and as structured content:

{
  "content": [{ "type": "text", "text": "{ … }" }],
  "structuredContent": { "…": "…" },
  "isError": false
}

Error codes

Errors come back as JSON-RPC errors with these codes:

Code	Meaning
`-32700`	The request body could not be parsed. Returned with HTTP `400`.
`-32601`	The JSON-RPC method is not one this server handles.
`-32602`	The arguments are invalid — a missing or malformed field, or an invalid list filter.
`-32003`	The task changed while your write was in flight (`task changed concurrently; please retry`). Retry the call.
`-32002`	Authorization failed — your role does not permit the action. The human-readable reason is the JSON-RPC `message`; the error `data` carries a machine `code` and the target's type.
`-32001`	No valid token was presented. Returned with HTTP `401`.

Entity references

Many tool results include a ref for an entity, giving a stable id and a url you can open in the web interface:

Entity	`id`	`url` points at
Space	The space key	A path holding the space's numeric id, `/spaces/<id>`. This does not open the space; to open it, use the space key instead, `/spaces/:space_key`.
Workflow	The workflow slug	The workflow's permalink, `/spaces/:space_key/workflows/:id-:slug`, which opens the workflow. It still resolves after the workflow's slug is renamed or the workflow moves to another team. See Workflows and stages § Workflow URLs.
Stage	The stage's numeric id	Its workflow's permalink
Task	The task's `KEY-N` id	The task's own page. See Web interface § A task's page.
Lease	`lease:<id>`	The agents view

A user is referred to elsewhere by the string user:<id> — for example as a task's assignee — rather than by a ref object.