JSON-RPC 2.0 Fundamentals

Why JSON-RPC?

MCP needs a tiny, well-understood message format that runs over any transport — stdio, HTTP, WebSockets. JSON-RPC 2.0 is exactly that: a one-page spec, native JSON, and bidirectional support for requests, responses, and one-way notifications.

One-line version: JSON-RPC defines the envelope; MCP defines what goes inside.

The four message types

Request shape

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_docs",
    "arguments": { "query": "MCP transports" },
    "_meta": { "progressToken": "abc123" }
  }
}

• jsonrpc MUST be the literal string "2.0".
• id is a string or integer — unique across all in-flight requests.
• params._meta.progressToken opts into progress notifications.

Response (success vs error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "Found 3 hits." }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

A response MUST contain exactly one of result or error — never both.

Standard error codes

Important: Tool execution failures (invalid input, business-rule violations) belong in CallToolResult.isError: true, NOT a JSON-RPC error. That distinction lets the LLM read the failure and self-correct.

Notifications

Notifications have no id and never get a reply. MCP uses them heavily — progress, cancellation, log messages, list-changed events, the initialized handshake.

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": { "progressToken": "abc123", "progress": 50, "total": 100 }
}