If you've built more than one MCP server, you've probably noticed a pattern: the first version takes an afternoon, and the second version — the one that actually has to survive real traffic, real auth flows, and real agent behavior — takes weeks. That gap is where most of the "MCP is overhyped" complaints come from. It's not that MCP is bad. It's that most public examples stop exactly where production work begins.
This post pulls together the lessons from two things we've built recently: a full minimal production-ready MCP server walkthrough covering auth, sessions, and error recovery, and a testing pyramid for MCP servers covering how to actually verify tool behavior instead of just eyeballing it. Rather than repeat either in detail, this is the condensed checklist — the thing you'd actually tape to the wall before a release.
Why a checklist instead of another tutorial
Tutorials show you one path through one server. A checklist works differently: it's a list of things that will bite you regardless of which framework, transport, or model you're using, because they're structural, not implementation details. If you can check every box below, you're in materially better shape than 90% of the MCP servers currently sitting in public repos.
Section 1: Authentication and identity
- Every tool call carries a verified identity, not just a token. Bearer tokens get forwarded; make sure your server validates scope and expiry on every call, not just on connection.
- Session tokens are short-lived and rotate. Long-lived sessions are the single most common way an MCP server turns into a standing liability.
- You have a clear answer for "what happens when auth expires mid-task." Does the agent get a clean, actionable error, or does it silently retry into a wall?
- Credentials never appear in tool descriptions, logs, or error messages returned to the model. This one gets missed constantly because error messages are usually the last thing anyone reviews before shipping.
Section 2: Session and state management
- Sessions are scoped per-connection, not global. A shared in-memory dict keyed by nothing is fine for a demo and a data leak in production.
- You've decided what happens on reconnect. Does the agent resume where it left off, or start clean? Both are valid — but only one should be true, deliberately.
- Idle sessions get cleaned up. Memory leaks in long-running MCP servers are almost always orphaned session state, not the tool logic itself.
- Concurrent calls from the same session are handled safely. Agents parallelize tool calls more than people expect; race conditions in session state are a quiet, nasty bug class.
Section 3: Error recovery
- Errors returned to the model are structured, not raw stack traces. The model has to use this information to decide what to do next — a Python traceback is not decision-useful.
- Retryable and non-retryable errors are distinguishable. Without this, agents either give up too early or retry forever on something that will never succeed.
- Partial failures in multi-step tools are handled explicitly. If a tool does three things and the second one fails, what state is the world left in, and does the model know?
- You have timeouts on every external call the tool makes. An MCP server is only as reliable as its slowest downstream dependency.
Section 4: Testing
This is the section most public MCP examples skip entirely, which is a shame because it's also the highest-leverage one.
| Layer | What it checks | Typical tooling |
|---|---|---|
| Unit | Tool logic in isolation, no protocol involved | Standard test framework for your language |
| Contract | Tool schemas match what the server actually returns | Schema validation against real responses |
| Integration | Server behaves correctly over the actual MCP transport | A real client hitting a real running server |
| Agent-eval | The agent, given the tool, produces correct outcomes | Scripted agent runs with known tasks and expected results |
The last layer is the one people underrate. A tool can pass every unit and integration test and still be unusable in practice because the model consistently misuses it — wrong argument shapes, wrong assumptions about return values, wrong retry behavior. You find that out by actually running an agent against the tool with realistic tasks, not by testing the tool in a vacuum.
Section 5: Observability
- Every tool call is logged with enough context to reconstruct what happened, without logging sensitive payloads.
- You can answer "how many times did this tool fail last week, and why" without grepping raw logs by hand.
- Latency per tool is tracked, because a slow tool doesn't just annoy users — it changes agent behavior, since models sometimes abandon or retry slow calls in ways that compound.
Section 6: Scope and permissions
- Tools expose the minimum surface area needed, not a general-purpose API wrapped in MCP clothing. The more a tool can do, the more damage a confused or manipulated agent can do through it.
- Destructive actions are gated — behind confirmation, behind a narrower scope, or behind a separate approval tool entirely.
- You've written down, explicitly, what the worst-case action this server can take is, and whether that's acceptable given who can reach it.
Using this as an actual pre-release gate
The realistic way to use this list isn't as an aspirational document — it's as a gate. Before a server goes anywhere near production traffic, someone (even just you, alone, with coffee) should go through each section and either check the box or write down why it's explicitly out of scope for this release. "We're not handling reconnect gracefully yet, and here's the ticket" is a fine thing to ship with. Silently not knowing is not.
If you want this in a form you can actually use instead of re-deriving it from blog posts every time, we packaged the checklist above along with a minimal working server template (the same one from the walkthrough post, stripped down to the essentials) and the agent-eval test scaffolding as a single pack: the MCP Production Checklist & Toolkit. It's meant to save you the week of scaffolding work, not replace the thinking — you still have to decide what your worst-case action is.
The honest summary
None of this is exotic engineering. It's the same discipline you'd apply to any service that takes untrusted input and takes real actions — auth, scoping, timeouts, structured errors, and tests that check outcomes, not just responses. The reason it feels new is that MCP made it very easy to skip straight to "it works in my terminal" and call that done. It's a good starting point. It's not a production system yet, and the gap between the two is exactly the six sections above.
Written with AI assistance and reviewed for accuracy.
Top comments (0)