Home Glossary
HomeGlossaryJSON-RPC 2.0
MCP Glossary

JSON-RPC 2.0

TL;DR

JSON-RPC 2.0 is the wire format MCP uses for all messages between client and server. It's a lightweight, stateless protocol where requests carry a method name, parameters, and an id; responses echo the id with a result or error. MCP wraps every tool call, resource read, and notification in JSON-RPC.

In depth

JSON-RPC 2.0 is a 2010-era open standard for remote procedure calls encoded as JSON. Every MCP message is a JSON-RPC object. The protocol is spec-simple: a message is either a request (`method` + `params` + `id`), a response (`result` or `error` + matching `id`), or a notification (`method` + `params`, no `id`, no response expected).

MCP chose JSON-RPC because it's lightweight, debuggable (human-readable JSON), and widely implemented. Every MCP SDK includes a JSON-RPC codec. Debugging an MCP issue often means tailing the JSON-RPC frames and inspecting the method/params.

JSON-RPC supports batching (multiple messages in one array) and bidirectional calls (server → client, not just client → server). MCP uses bidirectional calls for sampling (server asks client for LLM completion) and roots (server asks client for allowed locations).

The format is transport-agnostic: JSON-RPC messages can ride stdio newlines, SSE events, or HTTP POST bodies. MCP uses whichever transport makes sense for the deployment.

Code example

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "location": "Paris" }
  }
}

// Success response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "content": [{ "type": "text", "text": "18°C" }] }
}

// Error response
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32602, "message": "Invalid location" }
}

// Notification (no id, no response)
{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": { "progressToken": "abc", "progress": 50 }
}

Examples

  • 1
    A `tools/call` request with method + args
  • 2
    A `tools/list` response listing all available tools
  • 3
    A `notifications/progress` notification (no response needed)
  • 4
    A bidirectional `sampling/createMessage` (server→client)
  • 5
    An error response with JSON-RPC error code -32602 (invalid params)

What it's NOT

  • ✗JSON-RPC is NOT the same as REST — it's method-based, not resource-based.
  • ✗JSON-RPC is NOT HTTP-specific — it runs over any bidirectional transport.
  • ✗JSON-RPC 2.0 is NOT backward-compatible with JSON-RPC 1.0 — they have different shapes.
  • ✗Notifications are NOT the same as requests — no `id`, no response expected.

Related terms

Model Context Protocol (MCP)Tool CallMCP TransportMCP Initialize

See also

  • JSON-RPC 2.0 Spec
  • MCP Base Protocol

Frequently asked questions

Why did MCP pick JSON-RPC?

Simplicity, bidirectionality, wide support, and debuggability. It's transport-agnostic and has been in production use for 15+ years.

Can I debug JSON-RPC traffic?

Yes — log every frame. Tools like `mcp-inspector` show them visually. For stdio, wrap your command to tee stdin/stdout.

What's the max message size?

No spec limit, but practical limits apply — LLMs have context limits, so avoid multi-MB tool results. Stream or paginate instead.

Build with MCP

Browse 300+ MCP servers, explore recipes, or continue learning the MCP vocabulary.

Browse MarketplaceAll terms