Debug an MCP server with the MCP Inspector.
Stop debugging through a chat window. The Inspector calls your server's tools directly, shows the raw JSON-RPC both ways, and turns 'the agent isn't using my tool' into a diagnosable problem.
Testing an MCP server through Claude or Cursor is slow and ambiguous: when something fails, you can't tell whether the bug is in your schema, your handler, the transport, or the model's choice not to call you at all. The MCP Inspector removes the model from the loop.
It's the official debugging tool — a browser UI plus a local proxy that connects to your server over any transport and lets you invoke tools, read resources, and render prompts by hand, with every JSON-RPC message visible. Most 'my server doesn't work' mysteries die within five minutes of opening it.
Launch it against your server
The Inspector runs straight from npx — no install. Point it at the command that starts your server, and it spawns the process over stdio, performs the MCP handshake, and opens the UI in your browser (the interface serves on localhost:6274, with the proxy on 6277).
# Your built server
npx @modelcontextprotocol/inspector node build/index.js
# A Python server via uv
npx @modelcontextprotocol/inspector uv run my-server
# Pass env vars your server needs
npx @modelcontextprotocol/inspector -e API_KEY=sk-test node build/index.jsExercise tools by hand
The Tools tab lists everything your server advertises. Two checks before you run anything: are the names and descriptions what you intended (this is the text a model will read), and did your input schema serialize correctly — a wrong zod-to-JSON-Schema mapping is a top cause of agents passing garbage arguments.
Then call each tool with the form the Inspector generates from your schema. Try the happy path, then deliberately bad input: a missing required field should produce a clear validation error, not a stack trace. The response pane shows exactly what an agent would receive, including whether errors come back as proper tool results or as protocol-level failures.
Resources, prompts, and notifications
The Resources tab lists declared resources and lets you read each by URI — the quickest way to catch a resource that's declared but returns empty content or the wrong MIME type. The Prompts tab renders prompt templates with arguments you supply, so you can see the final message structure a client would inject.
Keep an eye on the notifications and logging pane while you work: anything your server writes as MCP log messages lands there. One classic bug it catches — a stdio server printing debug output to stdout, which corrupts the JSON-RPC stream and disconnects the client. Log to stderr instead.
Debugging remote servers
The Inspector also connects by URL: choose the Streamable HTTP (or legacy SSE) transport in the UI and enter your endpoint. This is the right way to verify a deployment before any client touches it — handshake, tool list, and live calls against the real hosted instance, headers included if it needs auth.
For x402-gated endpoints, expect tool calls to come back 402 with payment requirements attached; the Inspector won't pay, but seeing the correct price quoted in the response is itself the test that your payment gate is wired right. The handler shouldn't have run — with x402, payment settles before execution.
Test before you list
An Inspector pass is the cheapest pre-listing QA there is. Loomal listings can publish a server's live tool list, so the names, descriptions, and schemas you just verified are exactly what buyers and agents will see — and a server that fails its own handshake makes a poor storefront.
Make the full sweep — every tool called once, every resource read, errors readable — part of release, not something you do after a user reports the breakage.
FAQ
Do I need to install the Inspector?
No — npx @modelcontextprotocol/inspector runs it on demand. It starts a local proxy and opens a browser UI; the proxy is what actually speaks MCP to your server over stdio, Streamable HTTP, or SSE.
My server works in the Inspector but not in Claude Desktop. What now?
The Inspector just proved your server is protocol-correct, so the problem is client-side configuration: the config file's command or paths, environment variables the client doesn't inherit, or a restart that didn't happen. Check the client's MCP logs rather than your server code.
Can the Inspector test a deployed remote server?
Yes. Pick the Streamable HTTP transport in the UI and enter the endpoint URL — you get the same tools, resources, and prompts tabs against the live deployment. It's worth doing right after every deploy, before any agent depends on the endpoint.
Why does my stdio server disconnect the moment it starts?
Almost always something writing to stdout. In stdio transport, stdout carries the JSON-RPC stream, so a console.log or print corrupts framing and kills the session. Route all logging to stderr; the Inspector surfaces stderr output so you don't lose visibility.
Tested clean? List it.
Servers on the Loomal Index show live tool lists — yours is ready to publish.