Build an MCP Server

What this book is

What the spec doesn’t cover

Implementing the Model Context Protocol correctly is a smaller problem than it looks. Accept a tool call, validate it against a schema, return a result — the specification covers that ground in a page or two, and a server that does exactly that will pass every conformance check anyone runs against it. The much larger problem sits one layer below the spec: a call that hangs, an exception with nowhere durable to land, a hundred callers arriving faster than one process can serve them cleanly. All of it decides whether a server survives contact with real use.

This book works from a real example rather than a constructed one: a production stdio MCP server, roughly 2,900 lines of Python built on the official protocol SDK, serving a live multi-agent system. Its tool registry runs to 89 entries. An "exempt vs. gated" distinction divides that registry into what's callable before a session completes a required handshake and what requires it first. A single, consistent error envelope is built from an explicit exception taxonomy — alongside one honest, unreconciled inconsistency: a separate outer timeout path that still returns a differently shaped error object, because it was added later under pressure and never brought in line with the rest. Nothing here is invented for the book's benefit. A server that had never gone wrong would be a worse teacher than one that has.

What you’ll learn

Ten chapters, from the tool registry to hooks as a second surface

• the-tool-registry — How a real tool registration is shaped: name, description, and JSON Schema input spec, across 89 entries.
• the-handshake-pattern — How a handshake divides a tool registry into what's callable before and after a session proves itself.
• the-transport-layer — How the stdio transport actually gets a call from the wire to a function and back.
• the-error-taxonomy — The exception taxonomy that turns an error into a structured response a caller can act on, and the one path that was never reconciled with it.
• the-event-loop-incident — A synchronous call that wedged the event loop for roughly sixteen minutes, and the worker-thread-plus-deadline fix that followed.
• the-invisible-exception — Unhandled exceptions visible only to a subprocess's default stderr handler, and the file-based log handler that fixed it.
• the-routing-layer — A routing layer that lets one entry point serve more than one backend, based on the calling session's working directory.
• telemetry-that-stays-out-of-the-way — A telemetry design built to fail without taking the server down with it.
• hooks-as-a-second-surface — A lifecycle-hook configuration that sits outside the protocol itself but shapes how a Claude tool actually behaves.
• conclusion — What "implements the protocol correctly" doesn't cover, and why a server that's gone wrong is a better teacher than one that hasn't.

From the book

A preview

A server that had never gone wrong would be a worse teacher than one that has.

Who it’s for

Anyone building a Claude tool that needs to survive real use

This is for anyone building a Claude tool who wants their server to survive contact with real callers, not just pass a conformance check — protocol mechanics grounded in a production system's actual tool registry, error taxonomy, incident history, and configuration surface.

A longer excerpt is available to newsletter subscribers.

Buy Ebook on Amazon