---
title: "MCP: Debugging and Failure Modes"
slug: "mcp-debugging"
category: "ai-agents"
tags: ["mcp", "ai-agents", "debugging", "mcp-inspector", "troubleshooting", "observability"]
status: "stable"
last_updated: 2026-09-27
summary: "Debug MCP servers with MCP Inspector before wiring them into a client, and recognize the five common failure modes by their log signatures."
related: ["[[ai-agents/mcp-logging]]", "[[ai-agents/mcp-servers]]", "[[ai-agents/mcp-security]]", "[[ai-agents/claude-code-mcp]]", "[[ai-agents/mcp-tool-design]]", "[[howto/build-an-mcp-server]]"]
---

## 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 [[ai-agents/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.

```bash
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 [[ai-agents/claude-code-mcp|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 [[ai-agents/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.

## Related

- [[ai-agents/mcp-logging]]
- [[ai-agents/mcp-servers]]
- [[ai-agents/mcp-security]]
- [[ai-agents/claude-code-mcp]]
- [[ai-agents/mcp-tool-design]]
- [[howto/build-an-mcp-server]]