When an MCP server misbehaves, the host usually tells you almost nothing. A tool quietly vanishes from the list, or a call comes back with a terse error and no transcript to explain it. The MCP Inspector cuts through that by connecting to your server directly and showing every request, response, and notification on the wire. The short version: run npx @modelcontextprotocol/inspector <your server command>, open the URL it prints, then drive the tools, resources, and prompts by hand while you watch the raw JSON-RPC.
Key Takeaways
- Launch the Inspector with
npx @modelcontextprotocol/inspector node build/index.jsfor a local stdio server; nothing to install, and it prints a URL carrying a one-time session token. - Point it at a remote server with
--server-url https://host/mcp --transport http; the client picks the transport, so a mismatch here is the most common connection failure. - A capability tab (Tools, Resources, Prompts) only appears when the server actually reported that capability at connect, so a missing tab is a signal, not a bug in the Inspector.
- The Protocol tab shows the paired JSON-RPC requests and responses; the Console tab shows a stdio server's stderr, which is where most diagnostics land.
- The same checks script cleanly in CI with
--cli --method tools/list, and non-zero exit codes tell you whether the failure was auth, an unreachable host, or a tool error.
What You Need Before You Start
The Inspector runs straight through npx, so the only hard requirement is a current Node runtime. Per the MCP Inspector documentation, the web client needs Node 22.19.0 or newer and a Chromium or Firefox browser to open the printed URL.
- Node 22.19.0 or newer (the Inspector refuses to launch on older runtimes).
- A working MCP server to point it at. If you do not have one yet, stand up a minimal server first; a Python starting point is in how to build an MCP server in Python with FastMCP.
- The exact command that launches your server (for stdio) or its URL and transport (for remote HTTP or SSE). Read your server's own README first, because every server takes different arguments.
Debug an MCP Server With the MCP Inspector in Six Steps
This is the whole procedure. Each step is one action, and you can finish a debugging session from these six alone.
- Launch against your local stdio server. Pass the command that starts your server as the Inspector's arguments:
The launcher prints a URL that contains a one-time session token. Open that exact URL; do not retypenpx @modelcontextprotocol/inspector node build/index.jslocalhost:6274from memory, because the token guards a backend that can spawn processes on your machine. - Or connect to a remote server. For an HTTP endpoint, give the URL and the transport explicitly:
For a published package the pattern is the same, you just hand the Inspector the launch command, for examplenpx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport httpnpx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/repo.git. - Confirm the handshake and the capability tabs. Once connected, the tab bar shows a tab per reported capability: Tools, Prompts, and Resources each appear only when the server advertised that capability. If a tab you expect is missing, the server never registered it, so start there.
- Call a tool and read the result. Open the Tools tab, select a tool to see its input schema rendered as a form, fill the arguments, and call it. The response renders below the form with structured content, embedded resources, and images handled natively. A long or noisy tool list is itself a finding worth acting on, as covered in fixing MCP tool bloat.
- Read the raw JSON-RPC. Open the Protocol tab to see each request paired with its response and any notifications inline. Pin the monitor group and it moves into a resizable right-hand column so the transcript stays visible while you work in Tools. For a stdio server the Console tab shows the process's stderr; for an HTTP or SSE server the Network tab shows status codes, headers, and bodies.
- Script the same checks from the CLI. When you want a repeatable check instead of clicking, drive the same connection headless:
Call a tool and pipe the JSON straight intonpx @modelcontextprotocol/inspector --cli node build/index.js --method tools/listjq:npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp --transport http \ --method tools/call --tool-name get_weather --tool-arg city=Boston --format json | jq .result
How the Three Inspector Clients Compare
The package ships three clients behind one binary, and they share transports, config files, and OAuth state, so a connection behaves the same across all three. Pick the surface that fits the task.
| Client | Invocation | Best for |
|---|---|---|
| Web | npx @modelcontextprotocol/inspector | Interactive debugging with the full graphical transcript; the default and richest surface. |
| CLI | npx @modelcontextprotocol/inspector --cli | Scripted, machine-readable checks in CI and shell pipelines. |
| TUI | npx @modelcontextprotocol/inspector --tui | An interactive terminal UI for when a browser is not available. |
The mode flag has to come first on the command line. The first token that is not --web, --cli, or --tui ends launcher parsing, and everything after it is forwarded to the client unchanged.
Where to Read the Raw Protocol Traffic
The Inspector separates traffic into three views at different levels of detail, and which ones appear depends on the transport. Knowing which tab answers which question saves a lot of guessing.
- Protocol shows the JSON-RPC transcript: requests paired with responses, notifications inline, and spec errors rendered by class. This is where you confirm a tool call sent the arguments you expected and see the exact error object that came back.
- Network appears for HTTP and SSE servers and shows the HTTP layer, including status codes and request and response headers. Reach for it when a connection fails before any JSON-RPC is exchanged.
- Console appears for stdio servers and streams the server process's stderr, which is where most stdio servers write their own diagnostics.
Secrets are masked across these views, and entries can be cleared or exported when you need to attach a transcript to an issue.
How to Script Server Checks in CI
The CLI connects, runs the single method you name, prints the result, and exits, which makes it a clean fit for a pipeline. Every method takes its own companion flags, listed in the Inspector's CLI reference: tools/call needs --tool-name plus --tool-arg or --tool-args-json, resources/read needs --uri, and prompts/get needs --prompt-name.
One coercion detail bites people: --tool-arg JSON-parses each value, so count=1 becomes a number and "012" becomes 12. When you need a string preserved verbatim, pass the whole object with --tool-args-json '{"zip":"10001"}' instead.
Because each run maps its outcome to a stable exit code, a caller can branch on why a check failed without scraping text.
| Exit code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Usage or unexpected error (the catch-all). |
| 3 | Server requires authentication (401 or 403, or an OAuth challenge). |
| 4 | Server unreachable (DNS failure, connection refused, timeout, or fetch failed). |
| 5 | Tool error: the call returned isError: true, or the tool was not found. |
On any non-zero exit the CLI also writes a single JSON line to stderr, so 2>&1 | tail -1 | jq .error gives you the machine-readable reason.
Troubleshooting Common MCP Inspector Failures
A Server Tab or Tool Is Missing
If the Tools, Resources, or Prompts tab never appears, the server did not report that capability during the handshake. Open the Console tab (stdio) or Network tab (HTTP) to confirm the connection actually succeeded, then check that your server registers the capability before it starts serving. A tool that is present but greyed out or absent from the list usually means a registration ran after connect or threw during setup, which the Console stderr will show.
Transport Mismatch and Connection Refused
Pointing a stdio launch at a URL, or omitting --transport http when the endpoint speaks Streamable HTTP, produces a connection that never completes. The CLI reports this as exit code 4 with a fetch failed message. Match the transport to the server: a positional command for stdio, and --server-url with --transport http (or sse) for a remote server.
Schema Validation Errors
When a tool call returns an invalid-params error, the culprit is almost always argument typing. Confirm in the Protocol tab that the arguments you sent match the tool's input schema. If a value that should be a string is arriving as a number because --tool-arg coerced it, switch that call to --tool-args-json so the object passes through without coercion.
Auth 401s and OAuth Failures
A remote server that needs authorization answers the first connect with a 401 and a WWW-Authenticate header. As described in the Inspector's authorization flow, the web client then discovers the authorization server, runs the OAuth login in your browser, and retries the request once tokens land. In the CLI an unattended run exits with code 3 (auth_required) rather than hanging on a callback nobody will complete, so for CI sign in once in the web client and then pass --stored-auth-only to reuse the stored token. If the UI itself refuses to load, you opened a bare localhost:6274 without the session token; go back to the URL the launcher printed.
What to Do Next
- Wire a
tools/listcheck into your build so a broken server fails CI before it ships; the recipes in the modelcontextprotocol/inspector repository show the exact pipeline shape. - Read the broader MCP debugging guide for strategies beyond the Inspector, including host-side logs.
- Once the server passes inspection, connect it to a real host and confirm the same tools resolve there.