D2 · Tool Design & MCP › Cluster 7 · Building & Consuming MCP Servers

7.5 · Testing & Debugging (MCP Inspector)

Exercise a server directly

CONCEPT Test the server in isolation before wiring it to a model

The MCP Inspector is an interactive tool that connects straight to your server and lets you exercise it without any LLM in the loop — list and call tools, browse resources, run prompts, and inspect the raw JSON-RPC. Run it with npx @modelcontextprotocol/inspector (Node.js required). This is the fastest way to answer "is it my server or my integration?" — if a tool works in the Inspector but fails through Claude, the bug is in wiring/schema/description, not the server logic.

In the Inspector: pick the Transport type (SSE / Streamable HTTP for remote, or stdio for a local command), enter the URL or command, connect, then invoke each capability by hand and read the exact request/response.

CONCEPT The Inspector also mints an OAuth token for testing

For an OAuth-protected remote server, the Inspector walks you through obtaining an access token — the same one the Messages API connector needs (7.3). Open Auth Settings → Quick OAuth Flow → authorize in the browser → step through OAuth Flow Progress → copy the access_token. Drop it into the connector's authorization_token or Claude Code and you're connected.

🔑 General debugging beyond the Inspector: check the host's view with /mcp in Claude Code (tool counts, connection status, re-auth), and read the server's own stderr logs.
⚠️ stdio logging trap: on a stdio server, stdout is the JSON-RPC transport (7.1). Logging to stdout corrupts the stream and the host reports a broken/parse error. Always log to stderr.

DIAGRAM Isolate the layer that's failing

flowchart TD START["Tool fails through Claude"] --> INS{"Works in MCP Inspector?"} INS -->|"no"| SERVER["🔴 Server bug
logic / crash / bad schema
→ read stderr logs"] INS -->|"yes"| WIRE{"Server connected in host?"} WIRE -->|"no / pending"| CONN["🟠 Connection or auth
→ /mcp, OAuth, scope, type field"] WIRE -->|"yes"| DESC["🔵 Model not calling it
→ weak description / wrong primitive"] classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef net fill:#cce5ff,stroke:#4a90d9,color:#0b3d66; class SERVER bad; class CONN gate; class DESC net;

CODE Launch the Inspector and check host-side status

Exercise the server directly, then confirm the host sees it.

# 1. Run the Inspector against your server
npx @modelcontextprotocol/inspector
#   Transport: stdio | SSE | Streamable HTTP
#   stdio  → enter command, e.g.  uv run weather.py
#   remote → enter URL,     e.g.  https://mcp.example.com/mcp
#   Then: list tools/resources/prompts, call a tool, read raw JSON-RPC

# 2. For an OAuth server: Auth Settings → Quick OAuth Flow
#    → authorize → copy access_token → use as authorization_token (7.3)
# 3. Confirm the HOST connected to it
claude mcp list          # ✓ connected  /  ⏸ Pending approval  /  ✗ Rejected
claude mcp get weather   # per-server config + status
# inside a Claude Code session:
/mcp                     # tool count per server, re-auth, health
# stdio server logging — stderr ONLY (stdout is the transport)
# Python
import sys
print("debug: forecast request received", file=sys.stderr)
# TypeScript
console.error("debug: forecast request received");  // console.log would corrupt stdio

TRADE-OFFS Inspector vs. testing through the model

✅ MCP Inspector

  • No LLM cost or nondeterminism — you drive the calls
  • Sees raw JSON-RPC, exact schemas, exact errors
  • Isolates server bugs from integration/description bugs

⚠️ Only testing end-to-end via Claude

  • Confounds three failure layers (server, connection, model choice)
  • Model may not call the tool — masking a working server
  • Slower, costs tokens, harder to reproduce
Use the Inspector to prove the server is correct, then test through Claude to tune descriptions (2.1) so the model calls the tool when it should.

EXAM TRAPS

Trap: Debugging only through Claude. → A working server can look broken if the model never calls it, or a broken server can look like a "prompt problem." The MCP Inspector exercises the server directly and isolates the failing layer.
Trap: Logging to stdout on a stdio server. → stdout is the JSON-RPC channel; log to stderr (console.error / print(..., file=sys.stderr)) or you corrupt the transport.
Trap: Forgetting the Inspector can obtain an OAuth token. → Its Quick OAuth Flow produces an access_token you can paste into the connector's authorization_token for testing (7.3).
Trap: Ignoring host-side status. → claude mcp list / claude mcp get and /mcp show whether a server is connected, pending approval, rejected, or needs re-auth — often the real problem when a tool "doesn't exist."

PRACTICE

Q1 · A tool fails through Claude. How do you tell whether the server or the integration is broken?

Run the server in the MCP Inspector and call the tool directly. If it works there, the server is fine and the problem is connection/auth or a weak description keeping the model from calling it; if it fails there, it's a server bug — read the stderr logs.

Q2 · Why must a stdio server log to stderr, not stdout?

On stdio, stdout is the JSON-RPC transport. Any write to stdout that isn't a protocol message corrupts the stream and breaks the connection. Logs go to stderr.

Q3 · How can the MCP Inspector help you set up the connector's authorization_token?

Its Quick OAuth Flow runs the browser authorization and yields an access_token. Copy that into authorization_token in the Messages API connector (7.3) to test an authenticated remote server.