Your MCP server builds but the host can't see its tools. What's the first debugging move?
Run `npx @modelcontextprotocol/inspector <server-command>` to launch the official browser-based MCP debugger, which acts as a full MCP client and lets you list and invoke tools through a web UI.
Imagine you built a small radio that is supposed to broadcast to a specific app, but the app says it cannot hear you. Instead of guessing what went wrong, you want a separate test receiver that listens on the same frequency, shows you exactly what the radio is sending, and lets you press each button one at a time to see what happens. mcp-inspector is that test receiver for MCP servers. You point it at your server, it shows every message in plain view, you click 'list tools' and 'call this tool with these arguments' on a web page, and any error shows up in readable format instead of buried in a host log.
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 browser-based debugging UI for MCP servers and the single most useful development tool in the MCP ecosystem in 2026. If you write MCP servers, you will use it daily. If you only configure servers, you will use it the first time something does not work. Either way, learning it early pays back immediately.
This walkthrough covers what the inspector is, how it launches, what its UI surfaces, the triage flow for the most common debugging scenario ('server not showing up in Claude Desktop'), and where the inspector's coverage ends.
What the inspector is and how to launch it
mcp-inspector is shipped by the MCP team as @modelcontextprotocol/inspector on npm and launched via npx so you never need a global install. The command pattern is:
npx @modelcontextprotocol/inspector <your-server-command>
The <your-server-command> is whatever you would put in your host config file as command + args. For the filesystem reference server scoped to /tmp, it is npx @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /tmp. For a Python server at ./server.py, it is npx @modelcontextprotocol/inspector python ./server.py. For a remote server, it is npx @modelcontextprotocol/inspector --url https://example.com/mcp.
The inspector spawns the server, connects as an MCP client (running the standard initialize handshake), and opens a local web UI in your browser. The URL is typically localhost:6274 or a similar local port. Everything stays on your machine.
The essential point: the inspector is a full MCP client. It speaks the same protocol Claude Desktop and Cursor speak. Any bug visible in the inspector will also appear in a real host. Any bug the inspector does not show will almost never appear in a real host. This shared-protocol property is why the inspector is so reliable as a debugger.
Situations where this technique stops working.
2–4 min · Everything important, quickly.
Real products, models, and research that use this idea.
- A junior writes their first FastMCP server in Python, runs the inspector, sees `tools/list` returning empty because the `@app.tool()` decorator was missing, and fixes it in 30 seconds.
- A team debugging a flaky 'resource not found' error uses the inspector to invoke the resource handler with edge-case URIs (trailing slashes, encoded characters) the LLM would never try organically.
What an interviewer would ask next. Try answering before peeking at the approach.
QWhy is invoking a tool through the inspector's form better than prompting an LLM to call it?
Deterministic argument control. The form lets you pass exactly the arguments you want, including edge cases, empty values, and malformed inputs. You test the server's behavior, not the LLM's tool selection. Test the tool first with the form; test the LLM's picking behavior second with a real host.
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.
Restarting Claude Desktop repeatedly to debug a missing server. The inspector connects directly to the server process and surfaces the actual error in seconds, without needing any host running.
60 second bullets to scan on the way to the call.
The exact npx command to launch the inspector
That the inspector is itself a full MCP client driving the server
Primary sources. Browse if you want the original framing.
Same topic, related formats. Practice these next.