JSON-RPC 2.0 in depth

Four kinds of message

You met JSON-RPC briefly in Phase 1. Here's the full picture, and a busy restaurant is a good way to see it.

A waiter writes an order on a numbered ticket. The kitchen sends back a dish with that number, or a note saying "we're out of that", also with the number on it. Now and then someone calls out "table six is leaving", and nobody answers, because nobody asked anything.

JSON-RPC works the same way. Every message is a JSON object with "jsonrpc": "2.0", and there are exactly four shapes:

{"jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": {"name": "get_campaign", "arguments": {"id": "cmp_103"}}}
{"jsonrpc": "2.0", "id": 7, "result": {"resultType": "complete", "content": [{"type": "text", "text": "..."}]}}
{"jsonrpc": "2.0", "id": 8, "error": {"code": -32601, "message": "Method not found: tools/delete"}}
{"jsonrpc": "2.0", "method": "notifications/progress", "params": {"progressToken": "t1", "progress": 40, "total": 100}}

The receiver tells them apart by which keys are present. A message with method and id is a request. With method and no id, it's a notification, and the receiver must not reply, not even with an error. Answering a notification is a classic bug: the other side gets a response for an id it never sent.

The id is how answers find their questions. Like tickets in a kitchen, a client can have many requests in flight at once, over one connection, and replies can come back in any order. So the id is the only link.

In plain words: an id means "someone is waiting for an answer to this". No id means nobody is, so stay quiet.

Error codes

Error codes are like the stamps on returned mail: "address unreadable", "no such person", "wrong postage". JSON-RPC reserves a few codes for problems with the message itself:

The range -32000 to -32099 is for implementations. MCP takes -32020 to -32099 for itself, with names such as UnsupportedProtocolVersion (-32022), which the next lesson uses.

Two subtle rules. First, for a parse error the server can't read the id, so the error response has "id": null. If a letter arrives soaked and unreadable, you can't tell who to answer. Second, an error has a message for people and an optional data field for machines, like the list of supported versions.

import json

METHODS = {"tools/list": {"params": []}, "tools/call": {"params": ["name"]}}

def check(raw):
    try:
        msg = json.loads(raw)
    except ValueError:
        return -32700, "parse error"
    if not isinstance(msg, dict) or msg.get("jsonrpc") != "2.0" or "method" not in msg:
        return -32600, "invalid request"
    if msg["method"] not in METHODS:
        return -32601, "method not found"
    for needed in METHODS[msg["method"]]["params"]:
        if needed not in msg.get("params", {}):
            return -32602, "invalid params"
    return 0, "ok"

for raw in ['{"jsonrpc": ',
            '{"id": 1, "method": "tools/list"}',
            '{"jsonrpc": "2.0", "id": 2, "method": "tools/delete"}',
            '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {}}',
            '{"jsonrpc": "2.0", "id": 4, "method": "tools/list"}']:
    print(check(raw))

MCP's extra rules

MCP adds a few rules on top of plain JSON-RPC:

• Ids must be a string or an integer, never null, and never reused while that request is still waiting. Watch out for true: Python's isinstance(True, int) is True, but a boolean id is invalid.
• params is always an object with named fields. JSON-RPC also allows a list, but MCP never uses one.
• No batches. Plain JSON-RPC lets you send a list of requests at once. MCP removed batching in 2025, so every message is a single object.
• Both directions are allowed in JSON-RPC. In current MCP, clients send requests and servers answer them. Servers also send notifications, such as progress, while working on a request.

A dispatcher that never falls over

A dispatcher turns one incoming message into at most one outgoing message. Think of a mailroom clerk. Every envelope goes through the same steps in the same order, and whatever goes wrong, the clerk sends back a proper note instead of walking out. A good dispatcher has a fixed order of checks, and every failure becomes a proper error response:

1. Parse the JSON. Failure: -32700, id null.
2. Check the shape: an object, jsonrpc is "2.0", method is a string, and the id (if present) is a string or an integer. Failure: -32600.
3. If there's no id, it's a notification: run it, ignore any error, and return nothing.
4. Check params is an object (or missing). Failure: -32602.
5. Look up the method. Failure: -32601.
6. Call it. Errors your code raises on purpose keep their code and message. Anything unexpected becomes -32603 with a generic message, logged privately but never sent with the traceback.

That last step is the framework idea from Phase 8 again: expected errors pass through, and surprises are caught and hidden.

import json

def handle(raw, methods):
    try:
        msg = json.loads(raw)
    except json.JSONDecodeError:
        return {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "Parse error"}}
    if "id" not in msg:
        if msg.get("method") in methods:
            methods[msg["method"]](msg.get("params", {}))
        return None                                  # notifications get no reply
    fn = methods.get(msg.get("method"))
    if fn is None:
        return {"jsonrpc": "2.0", "id": msg["id"], "error": {"code": -32601, "message": f"Method not found: {msg.get('method')}"}}
    return {"jsonrpc": "2.0", "id": msg["id"], "result": fn(msg.get("params", {}))}

seen = []
methods = {
    "echo": lambda p: {"you_said": p.get("text")},
    "notifications/log": lambda p: seen.append(p["line"]),
}
for raw in ['{"jsonrpc": "2.0", "id": 1, "method": "echo", "params": {"text": "hi"}}',
            '{"jsonrpc": "2.0", "method": "notifications/log", "params": {"line": "started"}}',
            '{"jsonrpc": "2.0", "id": 2, "method": "missing"}',
            '{"jsonrpc": "2.0", "id": 3, "method": ']:
    print(handle(raw, methods))
print("logged:", seen)

import json

msg = json.loads('{"jsonrpc": "2.0", "method": "notifications/progress", "params": {"progress": 5}}')
print("id" in msg)

Rules that are easy to get wrong

Never answer a notification. You don't reply to a "wet paint" sign. A notification has no id, which means nobody is waiting for a reply. Sending one anyway confuses clients, since they have nothing to match it against. Even when a notification's method is unknown, stay silent.

Be strict about ids. An id is a string or a whole number. In Python, True counts as an integer, so a careless isinstance(id, int) lets true through as a valid id. Check for booleans first.

A handler's crash must not end the connection. One burned dish shouldn't close the restaurant. Wrap every handler. If it raises, reply with a generic internal error, and put the details in your own logs. The exception text can contain paths or secrets, so it doesn't belong in the reply.

Replies can arrive in any order. A salad can beat a steak to the table, even if it was ordered later. A slow request can finish after a fast one sent later. That's what ids are for. Match on the id, and never assume the next reply belongs to the last request.