Fourteen MCP servers in production at Yaw Labs. tailscale-mcp taught us that the LLM-vs-human identity question has no good default. aws-mcp taught us that a tool list can grow to 40,000 tokens before anyone notices. npmjs-mcp taught us that "auth" is four different problems wearing the same coat. lemonsqueezy-mcp taught us that errors a model can act on are a different art form from errors a human reads.
This book is what we wrote down between server #2 and server #14, when the same surprises kept landing in different forms and we got tired of solving them from scratch.
Twelve chapters on what the spec doesn't tell you. The protocol is the easy part; the hard part is the one you only learn by running these things in production for six months and watching what breaks.
Prefer it offline? Download the PDF (860 KB) or the EPUB (380 KB). Edition 1.0.4. No email required for those either.
Table of contents
Every chapter is a full web page. Read them in order or jump to the one that matches the thing currently on fire.
npm init to npm publish. Every chapter from here forward refers back to this server when illustrating a point. Code is in TypeScript with notes for Python. By the end you have a server you could ship; the next nine chapters are about making sure you'd want to. Pairs with Chapter 2.
Ch 4
Auth, Secrets, and the npmrc Class of Bugs
The hardest part. The MCP spec mostly does not address auth, which is correct -- auth lives at the transport and application layers -- but it leaves a gap that every server has to fill. We cover the four common patterns (no-auth, shared-secret, per-user OAuth, per-user token), the identity-flow problem (the LLM is the proximate caller; the human is the actual principal), and what to do when your upstream API has a token model that doesn't match any of the above. Pairs with Chapter 5; auth and schemas are the two leakiest surfaces in production servers.
Ch 5
Schemas That Survive Users
The longest chapter in the book. Schema design IS the API. A bad schema -- too many tools, tools with overlapping purposes, parameters with cryptic names, descriptions written for humans not models -- can make a perfectly correct server unusable. A great schema makes a mediocre server feel magical. We cover naming, parameter modeling, description-writing, the tool-list size problem, and the schema-versioning problem you don't know you have until your second deploy. The @yawlabs/aws-mcp scar tissue lives here. Pairs with Chapter 4.
Ch 6
Tools that Compose
What happens when one tool's output is the next tool's input, and how to design that handoff so the model doesn't lose its place. We cover output-shape-as-input-shape, pagination as a composability problem, list-then-detail patterns, idempotency under model retries, the read-vs-write naming and confirmation discipline, sampling, the macro-tool anti-pattern, and cross-server composition (designing your tool outputs so other servers' tools can consume them). Closes with a four-tool flow on @yawlabs/aws-mcp that ties the patterns together. Builds on Chapter 5's schema lessons.
Ch 7
Errors that Help, Not Hide
Errors are a UI surface. A good error tells the model what went wrong, why, and what it should do next. A bad error is a stack trace that the model dutifully relays to the user. We cover the three error conventions MCP gives you (isError: true tool results, JSON-RPC errors, and unhandled throws), the throw-discipline rule for handlers, the trigger-phrase pattern that turns vague messages into recovery instructions, transient vs terminal retry guidance, network-layer error normalization, and a six-axis rubric for grading error handling before you ship. Pairs with Chapter 8.
Ch 8
Testing MCP Servers
Testing an MCP server is different from testing a REST API because your consumer is probabilistic. We cover unit tests (deterministic, easy), integration tests (deterministic upstream, fake the model), end-to-end tests (real model, expensive, flaky), and the harness pattern that makes E2E tests tolerable. Includes the golden-file approach I use for tools whose formatted output matters and what it caught. Pairs with Chapter 7.
Ch 9
Deployment and Hosting
Where the server runs. We start with the "if it's stdio, don't host it -- publish it" rule, then walk the six realistic hosting options for HTTP servers (managed MCP platforms, Cloudflare Workers, Fly.io, AWS ECS/Fargate, a self-hosted VPS, your own Kubernetes cluster) with the cost/complexity/availability trade-offs of each, and a decision tree for picking the most boring option that fits. We compare the major managed MCP platforms (glama.ai, Yaw MCP, Smithery) honestly, with a disclosure that I run one of them. Container packaging, reproducible builds off your laptop, and migrations on boot round it out. Pairs with Chapter 10.
Ch 10
Security
Your server will get a security review. We cover the threat model (prompt injection through tool output, credential exfiltration through tool input, data exfiltration through the upstream API), the mitigations (input validation, output sanitization, network egress control, audit logging), and the questions a competent security reviewer will ask. Includes a security-review checklist you can run against your own server before someone else does. Pairs with Chapter 9.
Ch 11
Case Studies
Four deep dives, one server each: @yawlabs/tailscale-mcp (the first one, what we got right and wrong), @yawlabs/npmjs-mcp (the auth-shaped one), @yawlabs/aws-mcp (the schema-design lessons), and @yawlabs/lemonsqueezy-mcp (the error-handling and money lessons). Each case study walks through the architecture, the surprises, the bugs that shipped, and what a v2 would look like. The case studies refer back to every previous chapter.
Ch 12
What Comes Next
Where MCP is going, where I think it's going, and where I'm not sure. We cover the in-flight spec changes, the ecosystem gaps that are likely to get filled in the next year, the gaps that probably won't, and the bets I'd make today if I were starting from scratch. Closes with a short list of follow-up reading and the people I trust to be early-but-right on this stuff. Pairs with Chapter 1; together they bracket the book.
What this MCP server book teaches you to fix
Each of these is a thing one of the @yawlabs/* servers has actually hit -- not a hypothetical. The book gives you the schema change, throw discipline, or hosting decision that catches the next one before it reaches a customer.
- The 40,000-token tool list. Your
aws-mcpships 200 tools; the model degrades on selection; the trace shows it grabbing the wrong one. Chapter 5 is the longest chapter for a reason. Chapter 5. - Auth that doesn't fit the LLM-vs-human pattern. Your upstream API expects a human at a browser; the agent isn't a human. The four common patterns and what to do when none of them fits. Chapter 4.
- Tools that fight each other instead of composing. Output-shape-as-input-shape. Pagination that survives a non-deterministic caller. List-then-detail done right. Cross-server composition without the joins falling apart. Chapter 6.
- Errors the model can't act on. A 500 with a stack trace is a useless signal to a model. Throw discipline + trigger phrases + transient-vs-terminal retry, with a six-axis grading rubric. Chapter 7.
- E2E tests that pass on Tuesday and fail on Thursday. The harness pattern that makes testing a probabilistic consumer tolerable, instead of accepting that "non-deterministic" means "untested." Chapter 8.
- The idle server that's burning more than the active one. Six hosting options, an honest comparison of managed MCP platforms, container packaging, reproducible builds off your laptop. Chapter 9.
- The security review you didn't know was coming. The threat model, the mitigations, the questions a competent reviewer will ask, and a checklist you can run yourself before they do. Chapter 10.
Who this MCP book is for
You ship code for a living. You have read the MCP spec and shipped at least one server. You know what tools/list and notifications/initialized are without looking them up. You want to know why your aws-mcp tool list is 40,000 tokens and what to do about it.
You're somewhere between mid and senior on the IC ladder, or a tech lead deciding how to invest your team's MCP work.
Not for: spec walkthroughs (modelcontextprotocol.io does that better), "what is MCP" introductions, or vendor-neutral tool surveys.
Formats
- The web edition -- every chapter linked above, free, no signup. This is the copy that gets revised first.
- PDF and EPUB -- the same text for offline reading and e-readers. Edition 1.0.4.
- Revisions as the MCP spec evolves and the
@yawlabs/*servers ship new lessons. The web edition is the live one. - Pointers into the live
@yawlabs/*server repositories the book references.
MCP in Production: FAQ
Is the whole book really free?
Yes. All twelve chapters and the front matter are on this site as plain web pages -- no signup, no email, no paywall on the last three chapters. The PDF and EPUB are free downloads on this page as well. There is nothing held back. The MCP Weekly newsletter linked at the foot of each page is a separate, optional opt-in -- no part of the book sits behind it.
Does this MCP book cover Anthropic's MCP spec, or only Claude-specific behavior?
The spec. MCP is a multi-client protocol and the book treats it that way -- the server you ship runs against Claude, Cursor, Cline, and anything else that speaks the protocol. Client-specific quirks (Claude's tool-list size sensitivity, Cursor's transport preferences) are noted at the point where they constrain a server-side decision.
What if the MCP spec changes?
Each chapter pins the spec version it was written against, and revisions ship as the spec moves. The protocol has been moving steadily; the disciplines (schema design, throw discipline, the four auth patterns, the testing harness) survive minor-version churn. When a load-bearing change lands, the affected chapter gets a revision and the web edition updates with it.
Do I need to know Claude Code or Cursor first?
No. This book is the server-side view -- you're shipping the tools, not operating the agent that calls them. If you have used any MCP client at all, you have enough context; every chapter builds from the protocol up rather than from a particular client's UI. The preface includes a short walkthrough of installing and using a server if you have not done that yet.
Do I need to ship a public MCP server to benefit?
No. Local and internal MCP servers are the larger use case -- the LLM-vs-human auth question, schema design, throw discipline, and testing patterns apply identically whether the server runs on your laptop, in your VPC, or as a published @yawlabs/* package. The hosting chapter covers all three deployment shapes.
How do the companion-repo invites work?
There are no invites -- the companion repo is public, so just clone it. Starter code, exercises, and worked solutions live at chapter-N-final tags for each hands-on chapter. No GitHub account or access request needed.
Read MCP in Production
Twelve chapters, free, no signup. Start at Chapter 1, or take the preface first for the two reading paths through the book.
Built on the same patterns as the Yaw MCP CLI (@yawlabs/mcp).