MCP JSON-RPC over Streamable HTTP
Requires Authorize (x-api-key) and a JSON-RPC body. Use Accept: application/json, text/event-stream and Content-Type: application/json. First call is usually initialize; response includes mcp-session-id — send it on later requests as header mcp-session-id.
Authorizations
User JWT access token issued by POST /api/auth/verify or POST /api/auth/social/verify. Routes that accept both auth modes declare api-key and bearer-jwt security schemes.
Headers
Must list both application/json and text/event-stream (MCP Streamable HTTP).
HMAC-SHA256 signature: HMAC-SHA256(secretKey, timestamp + METHOD + path + body). Required for API-key authenticated requests (JWT/OAuth session auth is exempt).
Request timestamp in epoch milliseconds. Required with x-signature for API-key auth. Rejected if drift exceeds 5 minutes.
Body
Single JSON-RPC request or batch array.
- object
- object[]
The body is of type object.
Response
JSON or SSE per MCP transport. Response headers may include mcp-session-id (after initialize) and X-Mcp-Instance-Id (which replica served the request; use with load balancer sticky sessions). See MCP_DEPLOYMENT_SCALING.md.