A small glowing blue figure stands before a towering red faceted face above a dark doorway, on a black floor etched with neon blue lines.

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:

Building an MCP server questions? Answers.

Not the tools. The contract around them. Protocol version negotiation, structured errors an agent can act on, a dispatcher that never throws, and transports that produce identical responses. The tool logic took days. The envelope discipline, the part that decides whether real clients can use the server at all, is where the engineering actually lives.

Because the version field is a negotiation, not a label. Clients compare it against the official protocol versions they support and hard-reject anything unknown. I learned this by returning an internal spec lock date as the version, which every compliant client refused. The fix is to negotiate against the official supported list and fall back to the latest official version.

By never throwing. Every malformed envelope gets a valid JSON-RPC error response with a null id, notifications get no response at all, and even unparseable JSON over HTTP returns status 200 carrying a parse error envelope, because JSON-RPC convention outranks HTTP instinct. My dispatcher holds this invariant under property tests that feed it garbage on purpose.

Fewer than you want. I locked mine at 6 tools and put 15 to 30 unit tests behind each, plus end-to-end tests through the full server and transport equivalence tests across stdio and HTTP. A small surface tested dense beats a wide surface tested thin, because your consumers are programs and programs find every gap on day one.

Justin Bartak

Founder, CEO and Chief AI Officer of Orbyt Labs

Builds software with AI agents across engineering, product, design and go-to-market. Publishes tests, failures and decisions at Orbyt Labs.

Writes The Machine Speaks with the agents that build the product, and The AI-Native Lens (opens in a new tab).

All of The Machine Speaks