MCP in Production · Front matter
By Jeff Yaw
yawlabs.com / Yaw MCP
I did not plan to write a book about the Model Context Protocol. I planned to ship a few servers, learn the rough edges, and write about what I learned in my newsletter. The book happened because the rough edges kept multiplying, and the questions I got -- from customers of Yaw MCP, from readers of Token Limit News, from people I'd never met asking me on Discord why their tool kept timing out at 28 seconds -- kept landing in the same shape. There was a spec. There were tutorials. There was a 200-line "hello world" server in every blog post on the open web. And then there was the gap.
The gap is everything between "my server returns a tool list" and "my server has been running in production for six months, it serves real users, it costs me predictable money, the auth model survives a security review, and when it breaks I know within four minutes." That gap is what this book is about.
I've been doing Linux for sixteen years, AWS for twelve, and Kubernetes for five. I'm CKAD-certified, Terraform-certified, and I was quoted in O'Reilly's Seeking SRE book by David Blank-Edelman years back -- which, I'll be honest, is a big part of why I felt qualified to take a swing at writing my own. David's book is the model in my head every time I sit down to write a chapter: practitioners talking about what actually happened, not vendors talking about what's supposed to happen.
When MCP shipped in November 2024, I had been a daily Claude Code user for months. I'd already been writing little adapters and shell scripts to bridge the LLM and my actual work -- AWS lookups, npm package metadata, my Tailscale tailnet, my ticket queue. The protocol arrived and gave that scaffolding a shape. Within a week I had a prototype. Within a month I had a server I was running on a side machine. Within a quarter I had three servers, and I'd realized the only way to keep them running cleanly was to host them somewhere that wasn't my laptop -- which is how Yaw MCP started.
By the time I sat down to write this book I had fourteen servers in the @yawlabs scope on npm, each of which taught me something different.
Each server in the portfolio represents a problem I hit and a lesson the book now encodes:
Plus another eight I won't enumerate here. Every chapter in this book has at least one "this happened to me on server X" anecdote, and the X is real.
The MCP spec is good. The reference implementations are good. The tutorials on building your first server are good. None of them tell you:
Those are the chapters. The book is the answer to the question "I shipped a server, now what?"
You've shipped backend code in a real job. You know what a 502 looks like in your logs, you've debugged a flaky test at 11pm before a release, you've written a Dockerfile that you weren't proud of but it worked. You've used Claude Code or Cursor or Cline or one of the other AI coding tools enough that "tool call" is a word you use without thinking. You're somewhere between mid and senior on the IC ladder, or you're a tech lead who needs to make a build-vs-buy call on MCP servers for your team.
You don't need to know the MCP spec cold. Chapter 1 covers the parts that matter and points you at the spec for the rest.
If you're looking for a vendor-neutral treatment of every LLM tooling protocol -- OpenAI's function calling, Google's tool use, the dozen smaller frameworks -- this isn't that book. I use Claude Code daily, I host my servers for Anthropic-flavored clients first, and the examples reflect that. The protocol is open and most of the lessons port, but I'm not going to pretend I've used every client equally.
If you're looking for "build your first MCP server in 30 minutes," the official Anthropic docs do that better than I would. Start there, come back here when the 30-minute version stops being enough.
I started writing this book in early 2026 with twelve chapters planned. The chapter count survived; one of the slots didn't. The original Chapter 11 was a chapter on multi-tenant servers with shared state, and it got cut around the third draft because every example I wrote turned into "here's why you don't actually want to do this." The lessons got absorbed into Chapter 9 (hosting) and Chapter 10 (security). The slot was filled with case studies, which had been growing in the margins of every other chapter and finally earned a chapter of their own.
Three other chapters got rewritten end-to-end after the 2025-03-26 spec revision landed. The Streamable HTTP transport replaced the SSE-based one and broke a third of my examples. I kept the old examples in the legacy/ directory of the companion repo for anyone maintaining a pre-revision server, but the chapter text is current.
Two spec revisions show up by date in this book and they are not interchangeable. 2025-03-26 is the revision that introduced Streamable HTTP and made OAuth 2.1 with PKCE mandatory for HTTP transports; it is the one Chapter 9's hosting examples target. 2025-06-18 refines the auth model on top of that foundation -- Protected Resource Metadata (RFC 9728), the resource parameter (RFC 8707), and the formal separation between resource server and authorization server -- and is the version Chapter 4's auth examples and Chapter 8's integration-test pins reference. Both are still active in the field; if you copy an initialize block out of one chapter, make sure it matches the revision the surrounding section is anchored to. The protocolVersion you echo on the wire is the version you commit to support; do not pin one version in code and another in your tests.
The schema chapter (Chapter 5) is the longest one in the book and it almost got split in two. I left it as one chapter because the thesis -- schema design IS the API -- only lands if you read it through.
This book is free to everyone -- enter your email at yaw.sh/books and the PDF and EPUB download instantly (you'll join Token Limit News in the process; unsubscribe anytime). When I revise a chapter, the download page serves the new files and I email the fresh links to the list, so you always have the current version. That matches how I work. If a chapter ships with a bug in an example, you'll see the fix within the week, not the next edition.
I'm in conversations with O'Reilly about a print edition. If that happens, it will be later, and the free PDF + EPUB will keep getting updates either way. The downloadable bundle is the canonical living version. The print edition, if it ships, will be a snapshot.
The book is structured to read linearly, but the chapters are designed so that most of them work on their own. Pick the path that matches what you need.
Read straight through, Chapter 1 to Chapter 12. This is the path I'd recommend if you're new enough to MCP that you haven't shipped a server yet, or if you've shipped one and you suspect there are gaps you don't know you have.
The arc goes: why MCP exists and what it is (Ch1), the architecture (Ch2), a worked example you build alongside the chapter (Ch3), auth (Ch4), schemas (Ch5), tool composition (Ch6), errors (Ch7), testing (Ch8), hosting (Ch9), security (Ch10), case studies from my own portfolio (Ch11), and where this is all going (Ch12).
If you're a fast reader, you can do this in a weekend. If you're stopping to try things, budget two weeks of evenings.
Each chapter from 4 onward is designed to read standalone. If you have a specific problem -- "my server's auth model is a mess," "my tools are timing out," "I'm about to get a security review and I want to be ready" -- skip to the chapter that solves it.
The exceptions are Chapter 1 and Chapter 2. If you skip Chapter 1, you'll miss the vocabulary the rest of the book uses. If you skip Chapter 2, you'll miss the architecture diagrams that the worked example in Chapter 3 depends on. Don't skip 1 or 2.
Some chapters are stronger together. If you have time for two, read these as pairs:
For errata or questions about specific chapters, email contact@yaw.sh with the chapter and section in the subject -- "Ch5, schema versioning, question about X" -- and I'll get to it. Errata land in the next revision on the download page, and I email the refreshed links to the Token Limit News list when the updated files go live.
If you find a bug in an example, the fastest path is a PR against the relevant @yawlabs/* server's GitHub repo (linked from each chapter). I review those weekly.
Six chapters have a paired hands-on exercise -- Chapters 1, 2, 3, 4, 9, and 10. Each pairs to a numbered module in the companion GitHub repo: Ch1 -> module-1, Ch2 -> module-2, Ch3 -> module-3, Ch4 -> module-4, Ch9 -> module-5, Ch10 -> module-6. Modules 1-2 are usage-focused; modules 3-6 are build-focused, with a directory of starter code, a module-N-final git tag carrying a working solution, and a short prompt at the end of the chapter pointing at both. Chapters 5, 6, 7, 8, 11, and 12 are reading-only -- their lessons are reinforced through the build modules rather than carrying their own. The repo is public -- just clone it, no invite needed.
Getting the code: clone https://github.com/YawLabs/mcp-in-production-companion directly -- it's a public repo, so there's nothing to wait for. Once you've cloned it, check out any module-N-final tag and run the same code I run on my laptop.
The book stands on its own as the reading experience. The companion repo is the do-the-work surface -- the place where you build alongside the chapters, hit the same bugs I hit, and ship the same shape of artifact at the end. If you only read the book you will still get the lessons; if you also work the exercises you will internalize them. Either path is a legitimate way to use the book.
Two practical notes:
main. The exercises live in exercises/module-{1..6}/; the working solution for each is at the corresponding module-{N}-final tag (modules 1-2 are usage-focused with no code; modules 3-6 are build-focused). Checkout the tag, do the work in your own branch, diff against the tag when you're stuck.If git clone of the companion repo fails, double-check the URL (https://github.com/YawLabs/mcp-in-production-companion) -- the repo is public, so a clone should just work. If it still won't, email contact@yaw.sh and I'll take a look.
Most of this book is for engineers building MCP servers. But the first chapter you should read isn't about building -- it's about using. If you've never installed an MCP server in a client and watched a model call a tool you didn't write, the rest of the book is harder to ground. Three pages, no code, written for an engineer who has Claude Desktop or Claude Code installed and ten minutes.
The model is good at text in, text out. By itself it cannot read your filesystem, query your AWS account, search your Slack, or look up a customer in your CRM. An MCP server is a small program that gives the model new abilities -- "tools" -- it didn't have before. Install the GitHub MCP server and the model can search repos, fetch metadata, list issues. Install the filesystem server and it can read and write files on your machine. Install three servers in the same client and the model uses all of them in the same conversation.
Three properties of MCP servers are worth pinning down before you install one:
Claude Desktop reads its MCP configuration from a JSON file. The file lives at:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonIf it doesn't exist, create it. A minimal config with one server installed:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@yawlabs/github-tools-mcp"],
"env": {}
}
}
}
Save, quit Claude Desktop fully (not just close the window), reopen. The server icon should appear in the chat bar. Click it to see the tools the server registered.
To pass a token, fill in env:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@yawlabs/github-tools-mcp"],
"env": {
"GITHUB_TOKEN": "ghp_..."
}
}
}
}
Restart again. The token is now in the spawn environment of that one server -- not in your shell, not in any other process.
Claude Code uses a CLI:
claude mcp add github -- npx -y @yawlabs/github-tools-mcp
To pass a token:
claude mcp add github -e GITHUB_TOKEN=ghp_... -- npx -y @yawlabs/github-tools-mcp
claude mcp list shows what's installed; claude mcp remove <name> removes a server. No restart needed. The -e flag pattern is documented thoroughly in Chapter 4 -- it is the canonical way to plumb credentials to a stdio server, scoped to that one server's spawn config rather than your shell.
Some servers run as a service on someone else's infrastructure (Yaw MCP hosts the @yawlabs servers this way, for example). Connecting to one looks slightly different. In Claude Code:
claude mcp add github-remote --transport http https://github-mcp.example.com/
In Claude Desktop, the JSON config takes a url field instead of command + args:
{
"mcpServers": {
"github-remote": {
"url": "https://github-mcp.example.com/"
}
}
}
Bearer-token auth -- if the server requires it -- is configured per client; check the client's docs for the current header-injection pattern, since the exact shape has shifted across releases.
These overlap with the Chapter 4 deep dive but matter to anyone installing a server, builder or not:
ReadOnlyAccess, scoped Slack bot tokens. A token that can do too much is a liability; a token that can do exactly the listed operations is a defense.The MCP ecosystem in 2026 is the early-WordPress-plugins era of agentic tooling -- thousands of packages, signal varies wildly. The places worth looking, in order of signal quality:
github.com/modelcontextprotocol/servers. Vetted, maintained, follows the spec.@modelcontextprotocol/*, @yawlabs/*, vendor-published @<vendor>/* first-party servers.The flags to walk away from: install instructions that say "clone and build from source" instead of npx; tokens with overly broad scopes ("admin access" when read-only would do); no LICENSE; not updated in over six months; no README at all.
Three failure modes account for almost every "the server isn't working" report I've debugged:
claude mcp list show the server? Is node -v 20 or higher?console.log in the server's code corrupts the JSON-RPC stream and crashes the connection. File an issue. (We cover why this happens in Chapter 2.)Claude Desktop logs MCP traffic to ~/Library/Logs/Claude/ on macOS and %APPDATA%\Claude\logs\ on Windows (the exact path varies by version). Claude Code prints errors in the terminal where you launched it. Both surfaces are good first stops when something is silently broken.
That's the user-side primer. The rest of the book is about being on the other side of that experience -- the person whose server gets installed, whose tokens scopes get scrutinized, whose error messages get read at 11pm on a Tuesday. Chapter 1 picks up the why.
A book like this is a long list of debts.
Anthropic, for shipping MCP and for being unusually open about how the spec has evolved. The Streamable HTTP revision in the 2025-03-26 spec was painful for everyone running servers, but the way it was communicated -- with a long-running RFC, a deprecation window, and clear migration notes -- is the kind of standards work I wish I saw more often. Several of the people on that team have answered direct questions of mine in the public Discord, and the book is better for it.
David Blank-Edelman, who put me in Seeking SRE before I had any business being in a book. That experience -- watching how he assembled forty practitioners into a coherent narrative -- is most of why I had any idea where to start when I sat down to write my own. David, if you're reading this, I owe you a coffee and a long conversation about what's changed in the eight years since.
The first cohort of readers and beta reviewers. You read drafts that were rough, you filed issues that were patient, and you caught mistakes I would have shipped without you. This list is rolling -- names are added by first name (alphabetically) in each revision pushed to readers as I confirm each reader is happy to be credited, and there will be more in the next update than there are today. If you read a draft and want to be credited -- or specifically not credited -- email contact@yaw.sh and I'll get it right. I'd rather over-credit than miss someone.
The MCP community on Discord and GitHub. A protocol is only as good as the people who show up and use it in earnest, and the MCP community has been unusually high signal from day one. Special thanks to the maintainers of the SDKs in TypeScript, Python, and Go -- I have read your source code more times than I have read most of my own.
Customers of Yaw MCP, especially the early ones who paid for a service that was held together with shell scripts and good intentions for the first two months. Your support tickets are the index for the chapter outline of this book. I can't list you by name without permission, but if you're reading this you know who you are.
My family, for putting up with the writing. A book takes hours that come from somewhere, and they came from you. Thank you.
My day-job employer -- in general terms, because corporate communications would prefer I not name them in a side project -- for the policy that lets me keep Yaw Labs running on the side. The arrangement is the reason any of this exists.
Yaw Labs ships the @yawlabs/* line of MCP servers (fourteen and counting), runs the Yaw MCP platform, and publishes the Token Limit News newsletter. Everything in this book came out of building those servers, hosting them, and answering support tickets when they broke.
Reach Yaw Labs at contact@yaw.sh.
Copyright (c) 2026 Yaw Labs. All rights reserved.
This book is published under the Yaw Labs Personal Reading License. You may read this book, share short excerpts (under 300 words) with attribution, and quote the code samples for any purpose -- the code samples in this book are CC0 / public domain. You may not redistribute the full text, sell it, or include it in a training corpus without written permission.
Errata, corrections, and reader contributions are accepted via the per-chapter @yawlabs/* server repositories on GitHub or by email to contact@yaw.sh. Reader-submitted corrections are reviewed weekly and contributors are credited in the Acknowledgments of the next revision.
This is the first edition, published May 2026. The companion repo is YawLabs/mcp-in-production-companion; the companion site is Yaw MCP.