HTTP mcp

The OpenAPI 3.1 document is generated beside this preview as openapi.json. Schemas document current behavior; they never validate runtime requests. The built-in server is loopback/host-guarded and has no authentication.

These routes carry MCP JSON-RPC messages. Bodies are documented at the JSON-RPC envelope level only; the arguments and results of each tool are on the generated MCP tool pages.

mcpPost

Send MCP JSON-RPC messages

mcpPost description

Accepts one JSON-RPC 2.0 message or a non-empty batch array and answers with the matching response or array of responses. Notifications (messages without an id) get no response; a payload made only of notifications answers 204 with no body. An empty batch, or a message without jsonrpc 2.0 and a string method, answers 200 with a JSON-RPC Invalid Request (-32600) error. Methods are initialize, notifications/initialized, resources/list, resources/read, tools/list and tools/call; any other method answers a Method not found (-32601) error. Tool arguments and results are documented on the MCP tool pages. A successful initialize sent without an Mcp-Session-Id header returns a new session id in the Mcp-Session-Id response header. A session id is not access control: any client can open one, and with it a fresh device-start budget.

mcpPost contract

POST /mcp

Responses: 200, 204 (no body), 404; middleware can also return 403, 408 or 429.

Response headers on 200: Mcp-Session-Id.

mcpPost headers.Mcp-Session-Id

Session id an rk server on this machine issued on initialize. Optional; when present it must be one this machine issued, or the request answers 404 MCP_SESSION_UNKNOWN and the client should initialize again without it. Ids are signed with a per-machine key, so they stay valid across server restarts. Without it, requests from the same address share one session key.

mcpGet

Open the MCP server-to-client stream

mcpGet description

Opens the Server-Sent Events stream the Streamable HTTP transport uses for server-initiated messages. The server sends none, so the stream carries only SSE comments: one when it opens and a keepalive every 25 seconds. It stays open until the client disconnects or the server stops. Requires an Mcp-Session-Id header: without one the route answers 400, and with an id this machine did not issue it answers 404 MCP_SESSION_UNKNOWN.

mcpGet contract

GET /mcp

Responses: 200 (text/event-stream), 400, 404; middleware can also return 403, 408 or 429.

mcpGet headers.Mcp-Session-Id

Session id an rk server on this machine issued on initialize. Required for this route.

mcpDelete

End an MCP session (not supported)

mcpDelete description

Always answers 405 with no body. Sessions hold no server state, so there is nothing to end; a client can simply stop sending its session id.

mcpDelete contract

DELETE /mcp

Responses: 405 (no body); middleware can also return 403, 408 or 429.

mcpRootPost

Send MCP JSON-RPC messages (root alias)

mcpRootPost description

Alias of POST /mcp at the base URL, for MCP clients that post there. Same request, headers, responses and behavior as mcpPost.

mcpRootPost contract

POST /

Responses: 200, 204 (no body), 404; middleware can also return 403, 408 or 429.

Response headers on 200: Mcp-Session-Id.

mcpRootPost headers.Mcp-Session-Id

Session id an rk server on this machine issued on initialize; as for mcpPost.

mcpRootGet

Open the MCP server-to-client stream (root alias)

mcpRootGet description

Alias of GET /mcp at the base URL, for MCP clients that open the stream there. Same headers, responses and behavior as mcpGet. There is no DELETE alias at the root.

mcpRootGet contract

GET /

Responses: 200 (text/event-stream), 400, 404; middleware can also return 403, 408 or 429.

mcpRootGet headers.Mcp-Session-Id

Session id an rk server on this machine issued on initialize; required, as for mcpGet.