Debugging

A practical toolkit for debugging MCP servers, clients and host configurations.

Adapted from Debugging. Pair with the MCP Inspector.

Inspector is usually the first debugging stop. Source: modelcontextprotocol/docs (mcp-inspector.png).

Executive summary

Separate failures into: process start, transport framing, capability discovery, tool execution and host UX/approval. Use Inspector for protocol checks and host logs for wiring issues.

Debugging layers

Layer	Symptoms	Tools
Process	Server never starts	Manual CLI run, env checks
Transport	Garbled messages / immediate disconnect	Inspector, protocol version header
Discovery	Empty capabilities	server/discover, capability flags
Tools	Wrong args / runtime errors	Inspector Tools tab, schema review
Host config	Server missing from UI	JSON config, absolute paths, restart
Auth	401/403 on remote	Token, OAuth redirect, scopes

Stdio-specific tips

• Never write logs to stdout — they corrupt JSON-RPC.
• Capture stderr (mcp-server-NAME.log in Claude Desktop).
• Reproduce with the exact command + args from host config.

Remote-specific tips

• Confirm TLS and URL path.
• Check MCP-Protocol-Version header negotiation.
• Reproduce with Inspector against the HTTP endpoint.

Workflow

1. Reproduce outside the host (CLI / Inspector).
2. Fix schema or runtime errors until Inspector calls succeed.
3. Reintroduce the host config.
4. Confirm approval UX and end-to-end LLM tool use.
5. Add regression tests for tool handlers.

Negative cases

• “It works in Inspector but not in the host” → almost always config path, env, or cwd differences.
• Intermittent remote failures → timeouts, load balancer idle limits, token expiry.
• Tool succeeds but model misuses it → improve description and schema enums, not only code.

Key takeaways

• Isolate layer by layer; Inspector before host.
• Stdio logging mistakes are the #1 beginner outage.
• Match host env exactly when promoting a fix.

What to do next

Deep-dive on the MCP Inspector.