Part 11 of 14 · 2 min read
Mistakes that break a transport
Each one looks convenient until a dropped connection or a hostile page finds it.
Mistakes that break a transport
- Printing to stdout for debugging. Symptom: a tool call that otherwise succeeded makes the client crash on a
json.loadsof an unrelated line. Cause: a strayprintshares the frame the protocol is using. Fix: send every diagnostic to stderr, never stdout. - Keying a legacy fallback to one error code. Symptom: the client works against the legacy servers it was tested on and hangs or fails against others. Cause: legacy servers answer an unrecognised pre-handshake request with whatever they like, including silence past a timeout. Fix: fall back on any unrecognised error or on silence, not on a specific code.
- Trusting a mirrored header without checking the body. Symptom: a gateway blocks the tool it meant to block, yet the tool still runs. Cause: the gateway decided from
Mcp-Namealone while the server acted on a differing body. Fix: have the server reject any request whose headers disagree with its own body, with HeaderMismatch. - Retrying a side-effecting call with no idempotency key. Symptom: a dropped connection after a successful write leaves two holds, two charges, two rows instead of one. Cause: the server has no way to recognise the second attempt as a repeat. Fix: attach a key to every intended write and have the server remember results by key.
- Treating
Originvalidation as sufficient security. Symptom: a local endpoint stays reachable by any plain program with no header at all. Cause: the check only ever stops a browser carrying a hostile page's request. Fix: bind to loopback and require authentication in addition, not instead.
What the example does not do
For the curious What a transport does not change
A transport carries messages and decides framing, cancellation and shutdown. It never changes what a message means, so a server written once can be put behind stdio or HTTP. The HTTP side adds duties that stdio does not have: checking Origin, binding to localhost by default, authentication, and comparing mirrored headers with the body. The message shapes follow the specification's draft pages read on 24 October 2026 (revision 2026-07-28) and the 2025-11-25 transports page for the earlier form. Where those pages gave no rule, a choice was made and marked in the code. Timings depend on this machine and loopback networking, so treat them as direction, not fact.
Check yourself
A tool call runs for 90 seconds, the connection drops at 80, and the server finishes the work at 85. What can the client safely do, and what must the tool support?
Show answer
Retry only if the tool is idempotent or takes a request id the server remembers. Otherwise a retry repeats the work.
What you will use daily at work
| Practice | What it looks like |
|---|---|
| stdio for local tools | The host starts the server as a child process and talks over its pipes. |
| HTTP for shared servers | One endpoint with authentication, behind your normal gateway. |
| Timeouts and cancellation | Every call has a limit and a way to stop it. |