Skip to content
Back to blog

How to Debug Your MCP Server (MCP Inspector Guide)

MCP servers fail silently in ways that REST APIs don't. Here's how to use the MCP Inspector to test tools, catch protocol errors, and diagnose the most common issues.

Debugging an MCP server is different from debugging a REST API. HTTP requests can be inspected with ordinary network tools, but MCP Inspector provides a convenient interface for initialization, discovery, and tool calls. The official Inspector helps isolate protocol errors from application errors.

Start with MCP Inspector

The Inspector connects to your server, runs the MCP handshake, and gives you a UI to call tools manually, inspect protocol messages, and see exactly what your server returns.

Shell

Replace node build/index.js with however you start your server. The Inspector opens at http://localhost:6274. From there you can:

  • See the full tools/list response — every tool your server advertises
  • Call any tool with custom inputs and see the raw response
  • Inspect the JSON-RPC traffic between client and server
  • Watch notifications/message log entries in real time

For HTTP servers, pass the URL instead:

Shell

The most common silent failure: writing to stdout

If you have any console.log() calls in your MCP server, remove them.

MCP's stdio transport uses stdout exclusively for JSON-RPC messages. Any other output — debug logs, startup messages, anything — corrupts the protocol stream. The AI client receives garbled JSON and the tool call fails with a parse error, often silently.

The fix:

TypeScript

This can cause "my MCP server works in isolation but fails in Claude Desktop."

Common errors and what they mean

MCP error -32700: Parse error Your server sent something to stdout that isn't valid JSON-RPC. Check for console.log calls, startup banners, or any library that writes to stdout.

MCP error -32601: Method not found The client is calling a method your server doesn't implement. Usually happens when the client tries a transport feature (like resources/list) that your server doesn't expose.

Tool call returns undefined Your tool handler returned undefined instead of a string or object. MCP tool results must be non-null — return an empty string or a valid MCP content result instead.

Connection closes immediately Your server process is crashing on startup. Run it directly (node build/index.js) and check stderr for the actual error before wrapping it in Inspector.

Debugging xmcp servers

If you're using xmcp, run the dev server for a live-reloading development environment:

Shell

For STDIO, enable stdio: { silent: true } to redirect console methods to stderr; do not write application output directly to stdout. Use the Inspector against the HTTP transport during development:

Shell

For tool-level issues, add temporary console.error() calls in your tool handler — inspect stderr or the server terminal; console output is not automatically an MCP logging notification.

Testing tool inputs systematically

The Inspector lets you call tools with arbitrary inputs — use this to verify your Zod schemas are working correctly before connecting a real AI client:

  1. Open the Tools tab in Inspector
  2. Select the tool you want to test
  3. Fill in the input form (Inspector generates it from your schema)
  4. Hit Call Tool and inspect the response

Test edge cases: empty strings, missing optional fields, out-of-range numbers. Your schema validation errors should return clean MCP error responses, not crashes.

Next steps

One framework to rule them all