How to debug MCP tool errors

Debugging MCP tool errors starts with a hard truth: many failures return a 200 OK. MCP puts tool errors in the response body, so your first job is to look at the payload, not the status code.

Step 1: separate transport from tool errors

Count HTTP/transport failures separately from tool-level failures flagged with isError. A server that looks healthy at the transport layer can still be failing most of its tool calls.

Step 2: rank tools by failure

Sort tools by call volume and success rate. A high-volume, low-success tool is your top priority, because it is breaking the most sessions.

Step 3: read the error text

Open the failing calls and read the actual error. The pattern is usually a shape or type the model keeps getting wrong.

// schema wants:  { "to": ["a@x.com"] }
// agents send:    { "to": "a@x.com" }  → validation error

Step 4: make the tool forgiving

Coerce common shapes, accept synonyms for enum values, and return errors that tell the agent exactly what to change. Most tool errors are fixed by tolerance, not by new features.