Get Started

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.

90 minutesBuildPythonFree lesson

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

Text
-32700  Parse error      JSON could not be parsed
-32600  Invalid Request  Envelope shape is wrong
-32601  Method not found
-32602  Invalid params
-32603  Internal error

The 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.

Text
MethodNotFound -> -32601
InvalidParams  -> -32602
Anything else  -> -32603 with exception name in data

The 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

Text
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.

Question 1 of 70 correct

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.

main.py
"""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()