Describe what mcp-inspector is and walk through how you would use it to debug a `tools/call` that returns unexpected output.
Free · 2 AI evals / day
**mcp-inspector** is the official tool for testing an MCP server by hand. You run it, point it at your server, and a browser UI opens. From there you can see every tool, resource, and prompt the server offers, and you can call any of them yourself.
The big idea: it talks to the server directly, with no LLM and no host app in the middle. That matters when something breaks. If you debug through a chatbot, you cannot tell whether the model picked bad arguments or the tool itself is broken. The inspector removes that guessing.
To debug a bad `tools/call`, you connect, click the tool, type the same arguments that failed, and run it. The inspector shows the raw JSON-RPC message that came back. You read it directly.
The first thing to check is the `isError` flag on the result. If it is true, the tool ran but reported a problem. If instead you get a JSON-RPC error code, the call never reached your tool logic. That single distinction usually points you at the bug.
mcp-inspector is the official interactive client for MCP servers. Think Postman for MCP.
It connects straight to a server over stdio or Streamable HTTP, with no host and no model in the loop. You list tools, resources, and prompts, call any of them with arguments you choose, and watch the raw JSON-RPC traffic in real time. That isolation is the whole point. It lets you test a server before wiring it into a host like Claude Code.
To debug an unexpected result, connect to the server first. Then call `tools/list` and confirm the tool's inputSchema and description match what you expect. Next, invoke the tool with the exact arguments that failed in your app. Now read the raw response carefully.
The key signal is where the failure lives. A set `isError` flag with a message in the content array means your tool ran but failed internally. A JSON-RPC error code means the call never reached your handler, so it is a protocol or routing problem. That fork tells you which side to fix.
The inspector also ships a CLI mode. You script it into CI as a smoke test, so a broken `tools/list` or a renamed argument fails the build instead of surfacing in production.
Quick reference
TL;DR
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.
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.
The bug clearly lives in how the host selects or coerces arguments The inspector tests the server in isolation; a host-side argument or prompt bug will not reproduce there, so you debug inside the host instead.
You need to reproduce a multi-server tool naming collision The inspector connects to one server at a time, so cross-server shadowing and disambiguation only appear once the host fans out to several servers.
The failure is intermittent under production concurrency Manual single-call inspection rarely reproduces race conditions; you need load testing and server-side tracing instead of an interactive client.
Quick scan · 2–4 min
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.
Side-by-side
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-world examples
Real products, models, and research that use this idea.
1A team building a Postgres MCP server runs mcp-inspector locally, calls tools/list, and catches a mistyped inputSchema before Claude Code ever connects.
2Cursor and Zed plugin authors use the inspector to verify a server over Streamable HTTP, then ship it knowing any MCP host can drive it.
3A CI pipeline scripts the mcp-inspector CLI to connect, enumerate tools, and assert the schema, failing the build when a tool is renamed.
Interviewer follow-ups
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?
Sign in or go Pro to see the approach for this follow-up.
QA tool works in the inspector but fails inside Claude Code. Where do you look next?
Sign in or go Pro to see the approach for this follow-up.
QHow would you turn an inspector session into a regression guard?
Sign in or go Pro to see the approach for this follow-up.
Don't say this
Red flags and common mistakes that signal junior thinking. Click to expand.
Most common mistake
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.