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.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
mcp-inspector is the official, interactive debugging client for the Model Context Protocol. The fastest mental model is Postman for MCP: it connects directly to a server, lets you list and call its tools, read its resources, and pull its prompts, and it shows you every JSON-RPC message on the wire as it happens. Crucially, there is no LLM and no host application in the loop.
That last point is the entire value proposition. When an MCP tool returns something wrong inside a real host, the failure could come from three different places: the model chose bad arguments, the host mangled the transport, or the server's own tool logic is broken. You cannot tell which from inside the host, because the host renders a polished result and discards the raw protocol traffic. The inspector collapses that ambiguity by removing everything except you and the server, so every observed behavior is attributable to the server alone.
This matters because MCP development has a wide gap between writing a server and seeing it work inside an agent. The inspector fills that gap. It is where you confirm the server even starts, where you sanity-check the schema before a model ever sees it, and where you reproduce a production complaint deterministically. This deep dive covers what the inspector is, how it connects, the standard inner dev loop, how to read a failed tools/call response, and how to promote the same checks into automated CI so regressions never reach production.
What mcp-inspector actually is
The inspector is a developer tool that speaks the MCP wire protocol directly to a server. You launch it, give it a command to start your server or a URL to connect to, and a browser UI opens. From there it performs the initialize handshake, negotiates capabilities, and then lets you browse everything the server exposes. The handshake step alone is informative: if capability negotiation fails, the server and the inspector disagree about the protocol version, which is a class of bug you would otherwise only discover deep inside a host.
The UI surfaces the three MCP primitives separately. You see a tools panel listing every callable function with its inputSchema, a resources panel listing readable data references by URI, and a prompts panel listing the parameterized templates. Each one is interactive: you can call a tool, read a resource, or render a prompt by hand. Keeping the primitives separate matters, because a common confusion is expecting read-only data to come back from a tool call when it should be exposed as a resource instead.
Underneath the friendly panels sits a raw message log. Every request you trigger and every response the server sends is shown as the literal JSON-RPC payload, including the method name, the request id, and the full params and result objects. That raw view is what makes the inspector a debugger rather than just a demo client. You are never guessing about what crossed the wire, because you can read it byte for byte, copy it into a bug report, or diff it against an earlier run.
Situations where this technique stops working.
2–4 min · Everything important, quickly.
| 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.
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?
Configure the bearer token in the inspector's connection settings, confirm the auth handshake succeeds, then list tools. A 401 at connect time is an auth-layer bug, not a tool bug.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Red flags & common mistakes
The phrases 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.
60 second bullets to scan on the way to the call.
What mcp-inspector is and why it isolates the server
The connect, list, call, read inner loop
Primary sources. Browse if you want the original framing.
Same topic, related formats. Practice these next.