Debugging MCP

Read these first

• Building a server

What you will know

• Use an inspector to exercise a server without an agent

  A direct call isolates server behavior from agent orchestration, though it may not expose client-side serialization or timeout handling.

• Read a protocol trace and locate a failure

  Correlating request IDs, lifecycle messages, and timing distinguishes malformed responses from stalls, retries, and failures on the opposite side.

• Diagnose a capability mismatch, a transport hang, and a schema rejection

  These faults require different evidence: negotiated capabilities, connection and timeout state, and the exact payload or schema path that was rejected.

• Reproduce a client-specific bug against the raw protocol

  A minimal raw exchange reveals whether the client adds invalid fields, omits required initialization, or mishandles an otherwise valid server response.

• Compare agent-mediated debugging with direct protocol debugging and record the extra variables introduced

  The agent path adds planning, retries, hidden transformations, and timing variation that can obscure a deterministic protocol defect.

Chapters

1. 1

   Agent transcripts as debugging evidence

   A teammate's evidence that a tool \"doesn't work\" is a transcript in which the model tried it twice, got something unhelpful and moved on. That establishes a run went badly and nothing about the server: the arguments were the model's, may have differed between attempts, and an unhelpful result can be a correct response to a call nobody would have made. The variables the agent adds — planning, retries, rewriting, timing — are what hide deterministic faults, and they are why a transcript is a source of hypotheses rather than a reproduction.

   Read chapter
2. 2

   Debugging with the MCP Inspector

   An inspector drives your server directly, which removes both the agent and the client from the picture. That makes one particular result informative in the negative: when the server behaves perfectly under the inspector and fails as soon as a real client connects, you have localised the defect to that client's serialisation or its timeouts. This chapter covers what to exercise this way, the transport-matching condition the inference depends on, and what a direct call still cannot see about your own read loop.

   Read chapter
3. 3

   Tracing JSON-RPC frames

   When an agent stops making progress right after a tools/call, no error appears, no timeout fires, and the server's application log is silent for that call, the evidence that locates the fault is a frame log from both directions carrying request ids and timestamps. If the id went out and nothing came back, the stall is the server or the connection; if a response with that id was emitted and never read, the fault is your client's read loop or framing. This chapter covers how to record frames without touching the server, the four positions the trace distinguishes, and why cross-host timestamps are not latency.

   Read chapter
4. 4

   Timeouts, progress and cancellation

   A frame log tells you which side of the wire stopped; it does not tell you what was supposed to stop waiting. The deadline lives on the client, a progress notification legitimately extends it, and a cancellation notification tells the server an in-flight request no longer has a reader — so connection and timeout state, not the trace, is the evidence a transport hang actually needs. A global timeout converts an unbounded stall into a bounded failure the agent can react to, and it destroys the distinction between a server that never answered and a client that never read, turning a deterministic protocol defect into an apparently intermittent one.

   Read chapter
5. 5

   Capability mismatch and schema rejection

   A call that never returns, an invalid-argument complaint for a request your logs never received, and a notification one client silently ignores each need different evidence. The third is the trap: a capability mismatch produces a completely conforming trace whose interesting event is a message that was never sent, so anyone hunting for something wrong finds nothing and calls the report invalid. Check the initialize declarations, and read the client's log for schema rejections — the emptiness on your side of the wire is itself the signature.

   Read chapter
6. 6

   Settling a conformance dispute

   Your server works with two clients and fails with a third whose vendor insists you are non-conforming. Prevalence is not conformance — clients share SDKs, so two of three can be one implementation voting twice. Construct the minimal raw exchange the specification requires, run it by hand against your server, then replay the failing client's exact frames and point at the one that departs. This chapter also covers what permitted-but-unexpected behaviour obliges you to accept, and how to ship a workaround that somebody can still remove.

   Read chapter
7. 7

   Intermittent failures and frame replay

   A tool fails one run in twenty, always under the agent, never when you call it yourself, and the standing theory after two days is a race in the server. The same symptoms fit a specific input shape the model produces occasionally and a handler that mishandles it deterministically. Design the experiment that separates them before locking goes in, because a lock changes timing and reads as confirmation either way — as does the failure vanishing once you add logging.

   Read chapter