LLM Best Practices

MCP: Debugging and Failure Modes

3 min read

View markdown source

Overview

Most MCP server bugs fall into a small set of patterns: the server never starts, a tool leaks a stack trace, a downstream API rejects the call, a rate limit trips, or the output shape drifts from the schema. This page covers the interactive tool for catching them during development and the log signature of each one in production. It assumes the per-call structured log described in mcp-logging, since the signatures below refer to its error, duration_ms, and result_count fields.

Use MCP Inspector for interactive debugging during development

MCP Inspector is the official development tool for MCP servers. It provides a browser-based interface to: connect to a running server, list capabilities, call tools with custom arguments, inspect raw JSON-RPC messages, and view server-sent notifications in real time.

npx @modelcontextprotocol/inspector
# Opens the UI at http://localhost:6274 (default port)
# Connect to your server via stdio or HTTP

Use Inspector before wiring a server into Claude Code. Verify that tools/list returns the expected schema, that tools/call with edge-case inputs returns structured errors rather than stack traces, and that resources/list returns the expected URI set. Issues caught in Inspector cost nothing; issues caught mid-session cost context and time.

Know the five most common MCP failure modes

Each failure mode has a distinct log signature.

  1. Server fails to start. The client receives no initialize response. Log: no entries at all, or a process exit event. Fix: check the server command, binary path, and environment variables in settings.json.

  2. Tool returns an unstructured error. The server throws an exception and returns a JSON-RPC error object with a stack trace in the message field. Log: error field is non-null with a Python/Node traceback. Fix: wrap all tool handlers in try/except and return structured { "code": ..., "message": ... } errors.

  3. Auth failure on downstream API. The tool call succeeds at the MCP layer but the downstream API returns 401. Log: duration_ms is low, error contains “unauthorized” or “401”. Fix: check environment variable substitution and token expiry.

  4. Rate limit hit on downstream API. The tool starts returning 429 errors. Log: error contains “rate limit” or “429”, duration_ms is near-zero. Fix: add per-session rate limiting at the MCP layer before the downstream call. See mcp-security.

  5. Schema mismatch causes silent wrong results. The tool returns results but they do not match what the model expected. Log: result_count is unexpectedly 0, or response fields are missing. Fix: add schema validation on tool outputs and log a warning when the shape deviates from the declared schema.

Backlinks