MCP protocol reference

HTTP and JSON-RPC

Send JSON-RPC 2.0 requests to POST /api/mcp with Content-Type: application/json and Authorization: Bearer followed by the client credential. Requests from browsers also pass an origin check. This is an agent endpoint, not a way to place machine credentials in browser code.

The endpoint is stateless. initialize, ping, tools/list, tool calls and notifications all require a current credential. Notifications have no JSON-RPC response body.

Discover the available tools

Use tools/list after initialization. The reference pages below use the same SPECIFY_MCP_TOOLS definitions as the endpoint, including exact required fields and additionalProperties rules.

{
  "jsonrpc": "2.0",
  "id": "example_tools",
  "method": "tools/list",
  "params": {}
}

Check both protocol and tool outcomes

A JSON-RPC error describes a protocol or transport failure. A successful protocol response may contain a tool result with isError: true. Inspect both before treating work as completed.

Send x-correlation-id to correlate a request across the service boundary. The server generates one when it is absent. Correlation IDs identify a request; they do not make a repeated mutation idempotent.