Part 11 of 14 · 3 min read
Mistakes that break the host-client-server separation
Each one looks convenient until an isolation or trust test catches it.
Mistakes that break the host-client-server separation
- Passing the whole conversation into a tool call. Symptom: a server ends up with information it was never meant to see. Cause: it is easier to hand a server everything than to pick out exactly what one call needs. Fix: pass only the arguments that specific tool actually needs, and keep the conversation in the host.
- Believing a server's own annotation about its own tool. Symptom: a tool marked read-only turns out to change state, and no prompt was ever shown. Cause: the annotation is text written by the server's author, treated as fact instead of as a claim. Fix: trust read-only hints only from servers you have explicitly marked trusted, and ask a person about the rest.
- Showing the model tool names without a server prefix. Symptom: two servers that both expose a tool called
searchcollide, and one silently shadows the other. Fix: prefix every tool with its server id before it reaches the model's function list. - Writing a client that only speaks one protocol era. Symptom: the client works against servers you tested and fails, with no path forward, against others. Cause: the newer stateless era removed the handshake the client was written to expect, or an older server never implemented the newer probe. Fix: probe for the modern era first, fall back to the legacy handshake, and cache which era each server turned out to speak.
- Keeping state in the connection instead of behind a handle. Symptom: state that worked when tested on one connection disappears, or behaves unpredictably, on another. Cause: the newer era's servers remember nothing about a connection between calls. Fix: return an explicit handle from a creation tool and take it as an ordinary argument afterwards, exactly as the specification's state-without-sessions guidance describes.
What the example does not do
For the curious Why the spec changes under you
The protocol has two eras: a handshake with a session, and a newer stateless form. This module follows the specification pages read on 24 October 2026, which were under a draft path. Field and method names can move between revisions, so check them against the current specification before you build on them. A malformed message (params, id or tool name of the wrong type) gets an error reply, -32600 or -32602, never a crash.
Check yourself
A server returns isError: true with a message for a missing order. Is that a protocol error or a tool error, and who should see it?
Show answer
A tool error. The call worked; the tool failed. It goes back to the model so it can adjust. A protocol error means the request itself was malformed or unknown.
What you will use daily at work
| Practice | What it looks like |
|---|---|
| Reading JSON-RPC | Requests have an id; notifications do not; errors come back with a code. |
| Prefixing tool names | The host adds the server name so two servers cannot collide. |
| Consent before calling | The host shows the person what a tool will do before the first call. |