AI Explainedby Milad Fahmy

MCP from A to Z · Episode 05 of 90

JSON-RPC 2.0 in MCP

Every MCP message is plain JSON-RPC 2.0. Requests, responses and notifications, ids, error codes and resultType, explained. Episode 5 of MCP from A to Z.

Milad FahmyNov 8, 20261 min read

On this page
  1. A tiny RPC format
  2. Requests
  3. Responses
  4. Errors
  5. Notifications
  6. _meta: every message stands alone

Every MCP message is plain JSON. Here's the format underneath all of it: JSON-RPC 2.0.

Last episode: what MCP adds to plain tool calls. Today: the messages that carry it.

A tiny RPC format

JSON-RPC 2.0 is a small remote procedure call format. It's transport agnostic: the same messages work over stdio or HTTP. There are only three kinds of messages: requests, responses and notifications.

Requests

A request sets jsonrpc to "2.0", then adds a method, optional params, and an id:

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

In MCP, the id must be a string or an integer. Unlike base JSON-RPC, it can never be null, and it's never reused while a request is still pending.

Responses

The response echoes the same id, so the client knows which request it answers. It holds a result or an error, never both.

{ "jsonrpc": "2.0", "id": 7,
  "result": { "resultType": "complete", "tools": [ ... ] } }

Since the 2026-07-28 spec, every MCP result has a resultType: complete, or input_required when the server needs more from the client.

Errors

An error has an integer code, a message, and optional data with details. Standard codes include:

Code Meaning
-32601 Method not found
-32602 Invalid params
-32022 (MCP) Unsupported protocol version, with the versions it does support

Notifications

A notification has no id, so the receiver must not reply. It's fire and forget:

{ "jsonrpc": "2.0", "method": "notifications/tools/list_changed" }

This one tells the client to refresh its tool list.

_meta: every message stands alone

Each MCP request's _meta carries the protocol version and client capabilities, so every message stands on its own, with no session state needed.

Next episode: how MCP is versioned, from 2024-11-05 to 2026-07-28.

Request, response, notification. That's the whole grammar.

Sources

#mcp#json-rpc#mcp a to z#protocols#mcp specification

Watch