Evidence-first authority page
MCP Server Debugging Guide: Logs and Troubleshooting
A general troubleshooting approach for MCP server issues, covering logging conventions and the most common failure categories.
Direct answer
Debug an MCP server by first confirming it starts cleanly outside the client (directly in a terminal), checking stderr for startup errors (never stdout, which is reserved for protocol messages on stdio transport), and isolating whether the failure is in server startup, the handshake, or a specific tool call — each has a distinct signature.
Last reviewed 2026-08-29
This page remains noindex while its page-level source receipts are completed and verified. It is available for review, not presented as publication-ready authority.
The three failure categories
- Startup failure — the process doesn't run at all; check the launch command directly and any missing dependencies or environment variables.
- Handshake failure — the process starts but the client never sees a successful connection; check for stdout pollution (stdio) or TLS/auth issues (HTTP).
- Tool-call failure — the connection works but a specific tool call errors or returns unexpected results; check the tool's own input validation and handler logic in isolation, outside the full agent loop.
General debugging discipline
Reproduce the failure with the smallest possible test case — a direct tool call rather than a full multi-step agent task — before assuming the bug is in the model's reasoning rather than the server's implementation. Most reported 'the agent did something wrong' issues turn out to be a server returning an unexpected error format or an ambiguous tool description, not a reasoning failure.