JSON-RPC 2.0 Over Newline-Delimited Stdio
The transport between a model client and a tool server is JSON-RPC over stdio. Hand-rolling it once teaches you what every framing layer is paying for.
Learning Objectives
- Speak JSON-RPC 2.0 framed as newline-delimited JSON over stdin and stdout.
- Map the five standard error codes (-32700, -32600, -32601, -32602, -32603) and surface them with the right semantics.
- Distinguish requests, responses, notifications, and batches without inventing new envelope keys.
- Handle one parse error per line without poisoning the rest of the stream.
- Build a self-terminating demo using io.BytesIO so the lesson runs without spawning a child process.
Why JSON-RPC stays the lingua franca
A coding agent in 2026 talks to maybe twelve tool servers in a single session. Each server is a separate process or a remote endpoint. The wire format has been the same since 2013. JSON-RPC 2.0 is two-page spec. It survives because the alternatives (gRPC, HTTP per call, custom binary) all impose a tradeoff JSON-RPC does not: they pick either streaming or batching or transport-coupling. JSON-RPC is symmetric across stdio, sockets, websockets, and HTTP, and a client can drive a server it has never seen if both honor the spec.
This lesson builds the stdio variant. Newline-delimited JSON. Each request is one line. Each response is one line. The transport boundary is \n.
The wire shape
Four envelope shapes exist. Two are spoken by the client. Two are spoken by the server.
A notification has no id. The server must not respond to it. If a server returns a response to a notification, the client has no way to attach it to a call site. That single rule keeps the framing math simple.
A batch is a JSON array of requests or notifications. The server replies with an array of responses, in any order, one per non-notification entry. If every entry in the batch is a notification, the server sends nothing back.
The five error codes
-32700 Parse error JSON could not be parsed
-32600 Invalid Request Envelope shape is wrong
-32601 Method not found
-32602 Invalid params
-32603 Internal errorThe codes between -32000 and -32099 are reserved for server-defined errors. Everything else is application-defined. The lesson sticks to the five. If your handler raises, the transport wraps it as -32603 with the exception class name in data.exception.
A parse error has a special rule. The id in the response is nullbecause the request never parsed enough to extract an id.
Newline framing and the BytesIO demo
The transport reads one line at a time. A line is bytes up to and including \n. If a line cannot be parsed, the transport writes a -32700 response with id: null and continues. The stream is not poisoned. The next line gets parsed fresh.
For the lesson we wrap an io.BytesIO pair as stdin and stdout. The server reads requests until EOF, writes responses for each, and returns. The client reads the responses back. No process spawn. No timeouts. The transport behavior is identical to a real subprocess pipe because Python's io interface presents the same .readline() and .write() contract.
Method dispatch
The transport does not know which methods exist. It hands off to a callable handler(method, params) that the harness supplies. The handler returns a result or raises. Three exception classes surface specific codes.
MethodNotFound -> -32601
InvalidParams -> -32602
Anything else -> -32603 with exception name in dataThe transport never sees a tool registry. The registry sits behind the handler. This is the layering we want. The transport speaks JSON-RPC. The registry speaks tool shapes. The dispatcher (lesson twenty-three) stitches them together.
Stream behavior on errors
client writes server reads server writes
--------------- ----------- -------------
{...valid request...} parses ok {...response, id matches...}
{...broken json... parse fails {id:null, error: -32700}
{...valid request...} parses ok {...response, id matches...}
{...missing method...} invalid envelope {id:X, error: -32600}A broken JSON line does not stop the loop. A missing method field does not stop the loop. A handler exception does not stop the loop. The transport keeps reading until EOF.
Notifications and asymmetric flows
A notification is fire-and-forget. The harness uses notifications for progress events, cancellation signals, and log lines. Notifications are how a long-running tool can stream status updates without round-tripping for each one.
The lesson implements one outbound notification helper, write_notification. The server uses it to emit progress while a request is in flight. The demo shows the pattern: a request comes in, the handler emits two progress notifications, then writes the final response.
How to read the code
code/main.py defines StdioTransportthe parse helper (parse_request), the three write helpers (write_responsewrite_errorwrite_notification), and the dispatch loop serve. The error code constants live at module scope.
code/tests/test_transport.py covers the five error codes, notifications (no response written), batches (array in, array out, notifications skipped), broken JSON (parse error then continue), and the asymmetric flow where a handler writes a notification mid-call.
Going further
This transport is enough for the lessons that follow. Production transports add three things. A correlation id field that survives forwarding (your id is already this, but in a mesh you need an outer trace id too). A cancellation channel (a notification like $/cancelRequest with the id of the in-flight call). And a content-type negotiation handshake so the same socket can speak JSON-RPC and Streamable HTTP. None of those change the wire. They add metadata.
Check what you learned
7 questions. Answer each one to see why.
What distinguishes a JSON-RPC notification from a request on the wire?
The full code
Every file for this lesson. Copy it, run it, then change it.
"""JSON-RPC 2.0 over newline-delimited stdio.
Conceptual references:
- ./docs/en.md (this lesson)
- JSON-RPC 2.0 specification (https://www.jsonrpc.org/specification)
- RFC 8259 (JSON)
Stdlib only. Run: python3 code/main.py
"""
from __future__ import annotations
import io
import json
import sys
from dataclasses import dataclass
from typing import Any, BinaryIO, Callable, Iterable
ERR_PARSE = -32700
ERR_INVALID_REQUEST = -32600
ERR_METHOD_NOT_FOUND = -32601
ERR_INVALID_PARAMS = -32602
ERR_INTERNAL = -32603
class JsonRpcError(Exception):
code: int = ERR_INTERNAL
def __init__(self, message: str, data: Any | None = None) -> None:
super().__init__(message)
self.message = message
self.data = data
class MethodNotFound(JsonRpcError):
code = ERR_METHOD_NOT_FOUND
class InvalidParams(JsonRpcError):
code = ERR_INVALID_PARAMS
@dataclass
class Request:
method: str
params: Any
id: int | str | None
is_notification: bool
def _is_valid_envelope(msg: Any) -> bool:
if not isinstance(msg, dict):
return False
if msg.get("jsonrpc") != "2.0":
return False
if not isinstance(msg.get("method"), str):
return False
if "params" in msg and not isinstance(msg["params"], (dict, list)):
return False
if "id" in msg:
rid = msg["id"]
if isinstance(rid, bool):
return False
if not isinstance(rid, (int, str, type(None))):
return False
return True
def parse_request(raw: str) -> tuple[Request | None, dict | None]:
"""Parse one JSON line. Returns (Request, None) on success or (None, error_dict).
error_dict is a JSON-RPC error response ready to write out.
"""
try:
msg = json.loads(raw)
except json.JSONDecodeError as exc:
return None, _err_envelope(None, ERR_PARSE, f"parse error: {exc}")
if not _is_valid_envelope(msg):
rid = msg.get("id") if isinstance(msg, dict) else None
return None, _err_envelope(rid, ERR_INVALID_REQUEST, "invalid request envelope")
is_notif = "id" not in msg
return Request(
method=msg["method"],
params=msg.get("params"),
id=msg.get("id"),
is_notification=is_notif,
), None
def _err_envelope(rid: int | str | None, code: int, message: str, data: Any | None = None) -> dict:
err: dict[str, Any] = {"code": code, "message": message}
if data is not None:
err["data"] = data
return {"jsonrpc": "2.0", "id": rid, "error": err}
def _ok_envelope(rid: int | str | None, result: Any) -> dict:
return {"jsonrpc": "2.0", "id": rid, "result": result}
def _notification_envelope(method: str, params: Any | None) -> dict:
env: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
if params is not None:
env["params"] = params
return env
class StdioTransport:
"""Newline-delimited JSON-RPC 2.0 over a pair of byte streams."""
def __init__(self, stdin: BinaryIO, stdout: BinaryIO) -> None:
self._in: BinaryIO = stdin
self._out: BinaryIO = stdout
def read_line(self) -> bytes | None:
line = self._in.readline()
if not line:
return None
return line
def write_response(self, rid: int | str | None, result: Any) -> None:
self._write(_ok_envelope(rid, result))
def write_error(self, rid: int | str | None, code: int, message: str, data: Any | None = None) -> None:
self._write(_err_envelope(rid, code, message, data))
def write_notification(self, method: str, params: Any | None = None) -> None:
self._write(_notification_envelope(method, params))
def _write(self, obj: dict) -> None:
encoded = json.dumps(obj, separators=(",", ":"))
self._out.write((encoded + "\n").encode("utf-8"))
self._out.flush()
Handler = Callable[[str, Any], Any]
def _handle_one(handler: Handler, transport: StdioTransport, req: Request) -> dict | None:
"""Dispatch a single Request. Returns the response envelope (or None for notification)."""
try:
result = handler(req.method, req.params)
except MethodNotFound as exc:
return None if req.is_notification else _err_envelope(req.id, exc.code, exc.message, exc.data)
except InvalidParams as exc:
return None if req.is_notification else _err_envelope(req.id, exc.code, exc.message, exc.data)
except JsonRpcError as exc:
return None if req.is_notification else _err_envelope(req.id, exc.code, exc.message, exc.data)
except Exception as exc:
return None if req.is_notification else _err_envelope(
req.id, ERR_INTERNAL, "internal error",
{"exception": type(exc).__name__, "detail": str(exc)},
)
if req.is_notification:
return None
return _ok_envelope(req.id, result)
def _process_batch(handler: Handler, transport: StdioTransport, items: list) -> list | None:
out: list = []
for raw in items:
if not isinstance(raw, dict) or not _is_valid_envelope(raw):
rid = raw.get("id") if isinstance(raw, dict) else None
out.append(_err_envelope(rid, ERR_INVALID_REQUEST, "invalid request envelope"))
continue
is_notif = "id" not in raw
req = Request(
method=raw["method"], params=raw.get("params"),
id=raw.get("id"), is_notification=is_notif,
)
resp = _handle_one(handler, transport, req)
if resp is not None:
out.append(resp)
if not out:
return None
return out
def _write_raw(transport: StdioTransport, obj: Any) -> None:
encoded = json.dumps(obj, separators=(",", ":"))
transport._out.write((encoded + "\n").encode("utf-8"))
transport._out.flush()
def serve(handler: Handler, transport: StdioTransport) -> None:
"""Read requests from transport until EOF. Dispatch each through handler."""
while True:
line = transport.read_line()
if line is None:
return
text = line.decode("utf-8").rstrip("\n").strip()
if not text:
continue
try:
parsed = json.loads(text)
except json.JSONDecodeError as exc:
transport.write_error(None, ERR_PARSE, f"parse error: {exc}")
continue
if isinstance(parsed, list):
if not parsed:
transport.write_error(None, ERR_INVALID_REQUEST, "empty batch")
continue
batch_out = _process_batch(handler, transport, parsed)
if batch_out is not None:
_write_raw(transport, batch_out)
continue
req, err = parse_request(text)
if err is not None:
_write_raw(transport, err)
continue
resp = _handle_one(handler, transport, req)
if resp is not None:
_write_raw(transport, resp)
def _demo() -> None:
"""Self-terminating demo using io.BytesIO. No process spawn."""
def handler(method: str, params: Any) -> Any:
if method == "math.add":
if not isinstance(params, dict) or "a" not in params or "b" not in params:
raise InvalidParams("a and b required")
return params["a"] + params["b"]
if method == "echo":
return params
if method == "boom":
raise RuntimeError("intentional")
raise MethodNotFound(f"method {method!r}")
requests = [
{"jsonrpc": "2.0", "id": 1, "method": "math.add", "params": {"a": 2, "b": 3}},
{"jsonrpc": "2.0", "id": 2, "method": "math.add", "params": {"a": 5}},
{"jsonrpc": "2.0", "id": 3, "method": "missing"},
{"jsonrpc": "2.0", "id": 4, "method": "boom"},
{"jsonrpc": "2.0", "method": "log", "params": {"level": "info"}},
[
{"jsonrpc": "2.0", "id": 10, "method": "echo", "params": {"text": "hi"}},
{"jsonrpc": "2.0", "method": "log", "params": {"msg": "skip-me"}},
{"jsonrpc": "2.0", "id": 11, "method": "math.add", "params": {"a": 1, "b": 1}},
],
]
stdin = io.BytesIO()
for r in requests:
stdin.write((json.dumps(r) + "\n").encode("utf-8"))
stdin.write(b"{not json\n")
stdin.seek(0)
stdout = io.BytesIO()
transport = StdioTransport(stdin, stdout)
serve(handler, transport)
stdout.seek(0)
lines = [json.loads(line) for line in stdout.read().decode("utf-8").splitlines() if line]
print(json.dumps({"server_responses": lines}, indent=2))
if __name__ == "__main__":
_demo()