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.
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.
/mcp in
Claude Code (tool counts, connection status, re-auth), and read the server's own stderr logs.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
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
EXAM TRAPS
console.error / print(..., file=sys.stderr)) or you corrupt the transport.access_token you can paste into the connector's authorization_token for
testing (7.3).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.