What Shipping an MCP Server Taught Me.
The strategy case for MCP is its own post. This one is the grease under the fingernails: what actually broke, and what held, when I took the MCP server behind Orbyt Intelligence from spec to production. Six lessons, each paid for.
The short version: the tools were the easy part. The contract around them is the product.
Why did my first handshake fail?
Because I treated the protocol version as a label, and it is a negotiation.
My server had an internal spec lock date, and for a while it returned that date as its protocolVersion. Perfectly meaningful to me. Meaningless to every client on earth, and MCP (opens in a new tab) clients do not shrug at meaningless: they compare the version against the official versions they support and hard-reject anything unknown. The fix was structural, not cosmetic: negotiate against the official supported list, fall back to the latest official version, and keep internal dates internal.
A protocol is a promise to strangers. Your private vocabulary is not part of it.
Why are the errors the real API?
Because your consumers are programs, and programs read error data the way lawyers read contracts.
My tier and scope gates run before any tool executes. When a call fails the gate, the response carries a custom code, -32001, and structured data naming the reason: tier insufficient or scope insufficient, plus what exactly is missing. An agent inspects that shape and decides its next move, retry with auth, upgrade, or escalate to its human. The same discipline that governs metering for machine buyers governs refusals: a vague error ends the relationship, a structured one continues it.
Design your error catalogue with the same care as your success schema. For an agent consumer, they are the same surface.
What does never throwing actually take?
More than intention. My dispatcher holds one invariant: no input, however malformed, produces an exception. Every broken envelope gets a valid JSON-RPC error response with a null id. Notifications, requests without an id, produce no response at all.
The counterintuitive corner: over HTTP, unparseable JSON returns status 200 carrying a parse error envelope, because JSON-RPC convention outranks HTTP instinct, and clients parse the envelope, not the status line. Meanwhile non-POST methods get a clean 405 with an Allow header, and notifications get a 204.
None of this survives on good intentions. It survives on property tests that feed the dispatcher deliberate garbage, the same philosophy as tests being the spec: the invariant is real because a machine checks it, not because I remember it.
Where do the transports fit?
Nowhere important, and that is the design.
The server core is a function from JSON string to JSON string. The stdio transport feeds it newline-delimited JSON for Claude Code (opens in a new tab) to launch locally; the HTTP handler feeds it single-shot POST bodies for serverless deployment, one fresh server per request so no state leaks between callers. Both are thin pipes into the same function.
Two test families keep that true. Chunk-boundary tests prove stdio output is identical no matter how stdin arrives, split mid-message or ten messages in one chunk. Transport equivalence tests prove stdio and HTTP produce identical responses for the same inputs, success, error, scope failure, and malformed envelope alike. The day a transport starts adding its own opinions, a test fails before a client notices.
How do you keep a server honest?
Mechanically, because the temptation to be helpful is a bug factory.
When a data field is not ready, my tools return it as undefined and attach a limitation naming the dependency. Empty results return a count of 0 and say no data is available yet. Never a plausible guess, never a silent default. A human reader shrugs at a slightly wrong answer; an agent consumer propagates it into someone's decision at machine speed, with my name attached.
The same principle shapes the response format itself: every tool responds through one builder that attaches methodology and corrections URLs to every answer. The caveats travel with the data, because the reader on the other end will not go looking for them.
What to do Next
Lock your v1 surface small. Mine is 6 tools, and each carries 15 to 30 unit tests plus end-to-end coverage through the real server. A program will find every gap in a wide, thin surface on day one.
Write your error catalogue before your second tool. Codes, reasons, and the data an agent needs to act. It will shape your gates, your metering, and your support load more than any feature.
And put a property test on the dispatcher this week: garbage in, valid envelope out, every time. The server that never throws is the one that is still standing when the strangers arrive. The tools are what your server does. The contract is what it is.
Related reading:
- MCP Is the New API. the strategy case this post is the workbench for
- The Buyer Has No Hands. auth, limits, and metering for the same consumer
- Your Tests Are the Spec Now. why the invariants live in tests, not memory
- The Money Path Is a Protected File. the same contract discipline, applied to billing
- Every Tool Is a Door. the security model wrapped around this same server
- Building Orbyt, Part 8: The API the api layer built after shipping the mcp server
Building an MCP server questions? Answers.
Related research
- AI-Native Development, By the Numbers Aug 2026.
- 66 Failures. Counted, Classed, Published. Sep 2026.
- Governing an agent leadership team Sep 2026.
Follow the work.
I write these while the Machine runs. Get the next one wherever you already read.
- Subscribe on Substack (opens in a new tab)
- RSS feed
- Bluesky (opens in a new tab)
- Threads (opens in a new tab)
Add Orbyt Labs as a preferred source on Google (opens in a new tab)




