The MCP Handbook

Change history

What changed in this book, and why.

9 October 2026 — Version 2.2.0: Tasks extension (SEP-2663) & sub-agents

Chapters 19 and 20 aligned with the 2026-07-28 specification – the 27 September revision still described the experimental 2025-11-25 state:

  • Chapter 19 (Tasks): Tasks are now the io.modelcontextprotocol/tasks extension (SEP-2663). The server alone decides whether to create a task; only tasks/get, tasks/update and tasks/cancel remain. tasks/result and tasks/list are gone, mid-flight input uses inputRequests, push uses notifications/tasks. Go example rewritten as a task store, migration table added.
  • New: tasks as a shell for sub-agents (Chapter 19, section 8).
  • Chapter 20 (Agentic servers): Sampling is deprecated (SEP-2577) and delivered via multi round-trip requests. New main part "The Server as a Sub-Agent": a code-review guard that checks for duplicates and house standards with a local Qwen model – with findings from test runs against several local models and a comparison with the host's own sub-agents.
  • Tasks with the go-sdk: Chapter 19 explains why the go-sdk (v1.8.0) does not ship tasks yet, which extension points it offers and how the mcptasks package from the mcp-tester builds on them; plus checks with mcp-tester call --task and mcp-tester tasks. The review server from Chapter 20 runs as a task with it – tested against a local Qwen model.
  • New diagram of the task lifecycle (Chapter 19), hand-drawn as SVG.
  • Chapter 17 (Security) checked against specification 2026-07-28 and revised: new flow diagram with a five-step explanation; corrected: authorization is optional (the OAuth 2.1 profile for HTTP), RFC 9728 is Protected Resource Metadata (not DCR), Client ID Metadata Documents are preferred (DCR is deprecated), the resource lives in the aud claim, OAuth 2.1 drops the implicit and password grants, no more initialize/Mcp-Session-Id. New: PKCE S256 as a must, issuer validation (RFC 9207), scope negotiation with 403 insufficient_scope and step-up, the ban on token passthrough, annotations as hints rather than protection, extensions from ext-auth, checks with mcp-tester auth-check.
  • Chapter 16 (Transports) rewritten: since 2026-07-28 MCP is stateless – no initialize, no sessions, no GET stream, no Last-Event-ID. Covers stdio, Streamable HTTP with mandatory headers and HeaderMismatch, subscriptions/listen, cancellation by closing the stream, Origin validation, backward compatibility, HTTP/2 and proxy settings. Tested go-sdk example (Stateless, CrossOriginProtection) with mcp-tester http-check; found along the way: go-sdk v1.8.0 does not decode a Base64 Mcp-Name (fixed after v1.8.0). Glossary: Mcp-Session-Id, Last-Event-ID, Streamable HTTP, SSE updated.
  • Diagrams: the question flow (Chapter 21) is a graphic as well; ASCII diagrams in Chapters 19, 20 and 23 that were too wide now fit the code box. The graphics are generated by scripts in tools/diagrams/ (outside book/).
  • Chapter 21 (Elicitation) rewritten: since 2026-07-28, questions to the user go through multi round-trip requests – the flow is explained step by step. Form and URL mode with their security rules, the three responses, a tested Go example (deploy with a signed requestState), tests with mcp-tester and a migration table (-32042, elicitationId and notifications/elicitation/complete are gone). Glossary: new entry MRTR.
  • Glossary (new: Sub-Agent), introduction, table of contents and Chapter 14 updated accordingly.

27 September 2026 — Skills over MCP (SEP-2640) & Tasks (SEP-1686)

Comprehensive update for the latest 2026 specifications:

  • Chapter 23 (Agent Skills) thoroughly revised: Integrated the official specification io.modelcontextprotocol/skills (SEP-2640). Explained the dual model: local directories (.agents/skills/) and wire-protocol distribution via skills/list and skill:// resources.
  • Chapter 19 (Tasks) comprehensively expanded: In-depth coverage of the SEP-1686 "Call-Now, Fetch-Later" pattern, task state machine (including input_required for elicitation), full JSON-RPC methods (tasks/get, tasks/result, tasks/list, tasks/cancel, tasks/update), event-driven push reactivity via Streamable HTTP, new architecture diagram, and a production-ready Go worker pool with TTL garbage collection.
  • Why build custom MCP servers? Added dedicated sections in Chapter 1 and Chapter 4 explaining curated database gating and the "Compute Instead of Guessing" pattern (offloading to V8/CPU via wollmilchsau).
  • Tool repository links: Added direct GitHub links for mcp-tester and wollmilchsau across Chapters 1, 4, 14, 15, and the references appendix.
  • Prompt documentation for diagrams: Newly generated diagrams document their exact prompt directly in markdown comments (<!-- prompt used: ... -->).
  • Glossary, introduction, and Chapter 8 updated accordingly.

31 August 2026 — Two languages

The handbook is now available in German and English. Both editions carry all 24 chapters.

The translation was produced by machine, chapter by chapter, and reviewed. Where a term is established in German it was kept; where English is the origin — tool, prompt, sampling, elicitation — there was nothing to translate in the first place.

Chapter addresses now carry a language code as a result. Older links to individual chapters no longer resolve.

20 August 2026 — Revised for the current specification

The largest change in substance since the first edition.

  • New: security and authentication. OAuth 2.1 with PKCE has been mandatory since specification revision 2025-03-26 for any server reachable over the network. The topic was missing entirely until then — a serious gap for anyone going beyond stdio.
  • Transports instead of an appendix. What had been a side note on SSE and HTTP/2 became a chapter on transports as a whole, with Streamable HTTP as today's standard and SSE as legacy.
  • Agent Skills rewritten and roughly doubled in length. What had been a mention became a subject of its own.
  • The glossary was extended accordingly.

26 April 2026 — Agent Skills

A first chapter on Agent Skills, brief at the time.

22 April 2026 — First edition

The handbook becomes a project of its own. It had been part of the MCP Tester until then; a book explaining the protocol does not belong in the repository of a tool that tests it.

The book is maintained. What changes in the specification finds its way here — the current sources are listed under References.