About this site

Agent Protocols Explained follows how agents talk to tools at the level of messages on the wire: why a protocol, JSON-RPC and the life cycle of a session, tools, resources and prompts, transports, and the server asking the user or a model. Every chapter is built around an animation. It is the second of a family of agent sites, after Agent Harnesses Explained and followed by Agent Context Explained and Agent Orchestration Explained, next to the LLM-systems sites (the Transformer Decoder Explainer, LLM Inference Explained, Inference Trade-offs Explained and others, all in the header's switch).

The protocol revision

The site describes MCP revision 2026-07-28, the current one on the specification's versioning page when it was written (accessed 2026-10-08), and the handshake era it replaced (2024-11-05 to 2025-11-25). Where the two differ, every animation can show both.

The engine

Every animation is a run of Agent_Loop_Sim's protocols module, vendored into this site at commit 46b445c (VENDORED.json records each file's SHA-256). Its Python reference and the TypeScript port the site runs produce the same messages and frames; the site's CI regenerates its fixtures from the Python reference installed at that commit and requires the port to match them. It has:

• an MCP client and server as state machines over JSON-RPC 2.0, in both eras: the handshake and capability negotiation, tools, resources and prompts, progress, errors, elicitation and sampling (requests from the server, or input_required and a retry), plus pagination, cancellation and list changes;
• transports: stdio and Streamable HTTP framing, byte for byte for a minimal header set, a latency model, and a broken SSE stream resumed or sent again;
• authorisation: the OAuth 2.1 flow MCP requires, as a state machine with mis-configured variants (chapter 6);
• A2A 1.0 (since engine 1.3.0): an orchestrating agent and a remote research agent over the JSON-RPC binding with SSE, the agent card, the task life cycle, multi-turn input, in-task authorisation, cancellation and the error codes (chapter 8);
• an MCP gateway over four servers with three naming policies, and three attacks with and without their defences (chapters 7 and 9).

Checked against the official SDK

The protocol is not modelled from the specification alone. A small server written with the official MCP Python SDK (mcp 2.3.0) and the SDK's own client play 18 sessions over stdio while a tee records every line; the engine must produce the same 160 messages, compared as JSON with request IDs renumbered. The engine's CI re-records the SDK live on every change. The conformance page shows the recordings.

A2A is checked the same way: an agent written with the official A2A Python SDK (a2a-sdk 1.2.2) is driven, in process, by the engine's own A2A client through 8 sessions; the engine's agent must send the same 56 messages once IDs and timestamps are normalised.

What is real and what is illustrative

• Real: every message's content and size (equal to the SDK's for the recorded sessions), the HTTP header bytes for the header set shown, and the token counts (Qwen2.5's tokenizer).
• Illustrative: transport latencies and rates, server work times, and the user's and model's answer times; the scripted answers themselves; the resuming server of chapter 4 (resumption was optional). Engine-only behaviour (pagination, cancellation, list changes) follows the specification and is marked in the chapters.
• Illustrative too: the A2A agents' scripted replies and times, the gateway's four servers, and every host, token, handle and "secret" in the OAuth and attack walk-throughs (invented, under example.com).

How it is checked

• Engine: Python tests, the live SDK recording, and exact TS parity on every session and frame (in Agent_Loop_Sim's CI).
• Site: the vendored files' hashes; every chapter's sessions and frames against the Python reference (unit tests); key frames' captions on the page (end-to-end); every number in the prose is computed by the engine at build time; every code block is cut from the vendored engine, and every JSON message shown is one the engine sends.
• Every animation plays, pauses, steps, scrubs and resets from the keyboard, with no console errors, in light and dark mode at 1,280 and 390 px wide; nothing plays by itself with reduced motion; axe finds no accessibility violations; Lighthouse scores at least 0.9.

Go deeper

The slides behind the chapters: the MCP series, OAuth for MCP and the Agents hub. Source and issues: GitHub.