How would you use mcp-inspector to debug a tools/call that returns unexpected output?
Describe what mcp-inspector is and walk through how you would use it to debug a `tools/call` that returns unexpected output.
mcp-inspector is the official browser tool that connects straight to an MCP server so you can list and call tools, read the raw JSON-RPC, and isolate bugs before wiring into a host.
Imagine you build a vending machine and want to test it before bolting it to the wall in a busy lobby. You'd press each button yourself, watch what drops out, and check the little display for errors. mcp-inspector is that test bench for an MCP server. You point it at your server, see the full menu of tools, press a button by sending the exact arguments yourself, and watch the raw message that comes back. If a tool misbehaves, you find out right there, with no chatbot guessing in the middle. You read the actual request you sent and the actual reply, so you can tell a broken tool from a broken connection in seconds.
Detailed answer & concept explanation~8 min readEverything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.
Everything important, quickly.
4 min: what the inspector is and why it isolates the server, the connect, list, call, read loop, the isError versus JSON-RPC error fork, and scripting the CLI into CI.
| Signal in the response | What it means | Where to fix |
|---|---|---|
| isError true in result | Tool handler ran and reported failure | Inside your tool logic |
| JSON-RPC error code | Request never reached the handler | Routing, transport, or method name |
| Unexpected content array shape | Handler returned the wrong result format | Result serialization in the tool |
| Wrong inputSchema in tools/list | Arguments coerced or rejected before call | Tool registration and schema |
Real products, models, and research that use this idea.
- A team building a Postgres MCP server runs mcp-inspector locally, calls tools/list, and catches a mistyped inputSchema before Claude Code ever connects.
- Cursor and Zed plugin authors use the inspector to verify a server over Streamable HTTP, then ship it knowing any MCP host can drive it.
- A CI pipeline scripts the mcp-inspector CLI to connect, enumerate tools, and assert the schema, failing the build when a tool is renamed.
What an interviewer would ask next. Try answering before peeking at the approach.
QHow do you debug a Streamable HTTP MCP server that needs OAuth before tools/list works?
QA tool works in the inspector but fails inside Claude Code. Where do you look next?
Don't say thisRed flags and common mistakes that signal junior thinking. Click to expand.
Red flags and common mistakes that signal junior thinking. Click to expand.
Debugging through the host LLM instead of the inspector. The model hides the raw JSON-RPC, so you cannot tell a tool logic error from a protocol error.
The night-before-the-interview bullets. Scan these on the way to the call.
Primary sources. Skim if you want the original framing.
Same topic, related formats. Practice these next.