MCP Inspector: Test & Debug Your MCP Server (The Right Way)

You cannot eyeball an MCP server. It speaks JSON-RPC over a pipe or an HTTP stream, and until something on the other end connects, negotiates capabilities, and calls a tool, you have no idea whether your server actually works. MCP Inspector is the official tool that plays that other end for you. This guide covers what it is, how to run it, UI mode versus CLI mode, testing auth and remote servers, and the failure modes it surfaces first, all verified against the modelcontextprotocol/inspector repo as of July 2026.

What MCP Inspector is

MCP Inspector is the official interactive developer tool for testing and debugging MCP servers, maintained by the modelcontextprotocol organization and described in its repo as a visual testing tool for MCP servers. You point it at a server, and it connects the way a real host would, then lets you drive that server by hand or by script.

Under the hood it is two parts. The MCP Inspector Client (MCPI) is a React web UI. The MCP Proxy (MCPP) is a Node.js server that bridges the browser to your target server over whichever transport you choose: stdio, SSE, or streamable HTTP. The browser cannot open a stdio pipe or spawn a process, so the proxy does that work and relays messages back to the UI. That split matters both for how you debug and, as we will see, for how the tool was once exploited.

Once connected, Inspector lets you list and invoke Tools, read Resources, exercise Prompts, watch server-side notifications and logs, and read the raw JSON-RPC exchange for every request. That last part is the point: MCP is just JSON-RPC over a transport, and Inspector is a window onto that traffic.

Why you cannot eyeball a server

An MCP server has no screen. It exposes capabilities through a negotiation handshake and answers method calls like tools/list and tools/call with JSON. If you registered a tool but forgot to wire it into the capability list, nothing crashes: the server starts fine and simply reports zero tools. If your tool handler blocks on synchronous I/O, the process runs, but the call never returns. None of these are visible from reading source alone.

You could wire the server into a full host like Claude Desktop and poke at it through a chat loop, but then a model sits between you and the failure, and you cannot tell a server bug from a prompting problem. Inspector removes the model. It is the difference between debugging your server and debugging a conversation about your server. When you are still deciding whether MCP is even the right shape for your integration, our MCP vs API piece frames that tradeoff; once you have committed, Inspector is how you verify the contract.

Install and first connection

There is nothing to install. Inspector runs through npx:

npx @modelcontextprotocol/inspector node build/index.js

That launches a local TypeScript server (node build/index.js) and connects Inspector to it over stdio. For a published npm server, wrap the launch command:

npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /path

For a Python server distributed on PyPI, run it through uv:

npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/your-repo

On launch, the proxy generates a random session token, prints it to your terminal (you will see a line like 🔑 Session token: <32-byte hex>), and opens your browser at the UI with that token already filled in:

http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>

The UI is served on port 6274 and the proxy on port 6277 (a T9 dialpad mnemonic: 6274 spells MCPI, 6277 spells MCPP). If either port is busy, override with the CLIENT_PORT and SERVER_PORT environment variables. Latest published version is 0.22.0 (npm, 2026-06-04), and it requires Node.js ^22.7.5.

In the UI you get a server-connection pane (pick the transport, and for local servers set the command-line args and environment), then four working areas: Resources for listing and inspecting content and testing subscriptions, Prompts for previewing templated messages with custom args, Tools for viewing input schemas and invoking with your own inputs, and a Notifications pane that streams server logs. The documented workflow is: confirm connectivity and capability negotiation first, then iterate (edit, rebuild, reconnect, retest, watch messages), then push edge cases like invalid inputs, missing prompt args, and concurrent operations.

UI mode vs CLI mode

Most tutorials treat Inspector as a UI toy. It also has a headless --cli mode that turns it into a scriptable client you can drop into CI. The table below maps each capability to both modes and, more usefully, to the concrete failure it surfaces. Cells marked below are where that mode is the one you actually reach for.

The decision rule is simple: use the UI to discover what your server does and why a call fails; use the CLI to prove it still does the same thing tomorrow. A one-line --cli --method tools/list check in a pipeline catches the day someone renames a tool or drops it from the capability list, which no amount of manual clicking will do reliably.

How a debug session flows

The diagram below traces a session from the command you type to the JSON-RPC you read. The token gate at the proxy is the security boundary added in 0.14.1; the transport branch is where local (stdio spawn) and remote (HTTP or SSE with headers) sessions diverge.

Testing auth and remote servers

Not every server is a local process. For a remote MCP server, pass a URL instead of a command and set the transport explicitly:

npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com \
  --transport http --method tools/list --header "X-API-Key: your-api-key"

Transport values are stdio (the default), sse, and streamable-http. The --header flag is repeatable, so you can send whatever custom auth your server expects, an API key, a bearer token, a tenant id. This is exactly the surface where remote servers break in ways local ones do not: a 401 from your server (not the proxy) means your header is wrong or missing; a CORS or origin rejection means the server does not trust the caller.

For repeated work, Inspector also supports a config file: --config path/to/config.json --server serverName loads a named server definition and auto-detects its transport, so you are not retyping long invocations. If your server enforces its own OAuth or scoped tokens, that logic belongs in the server, and our MCP security guide covers how to design it. Inspector's job is to let you present those credentials and watch the server accept or reject them.

Failure modes it surfaces

Because Inspector shows you the negotiation and the raw JSON-RPC, most MCP bugs announce themselves as a recognizable pattern. Read these as a triage table:

• tools/list comes back empty - the capability is not registered. Your handler exists but was never added to the advertised tool list.
• A tool call hangs and never returns - blocking or synchronous I/O in the handler, or a timeout. Adjust the request timeout in the UI Configuration panel (MCP_SERVER_REQUEST_TIMEOUT defaults to 300000ms) to distinguish a slow call from a dead one.
• 401 from the proxy on the UI - the session token is missing or wrong. You opened :6274 without the MCP_PROXY_AUTH_TOKEN that was printed at startup.
• Connection refused - wrong transport or wrong port. A stdio server will never answer an HTTP request, and a busy 6277 needs SERVER_PORT.
• CORS or origin rejection - the request origin is not in ALLOWED_ORIGINS. This is the origin check added for security, working as intended.
• Prompt errors on invoke - a required prompt argument is missing; the Prompts tab shows which one.

Understanding which side each error comes from, your server versus the Inspector proxy, is half the battle, and it is also the practical version of the MCP client vs server distinction.

The CVE-2025-49596 lesson

The debugging tool itself was once the vulnerability. CVE-2025-49596 was a critical remote-code-execution flaw in MCP Inspector versions before 0.14.1. Because there was no authentication between the Inspector client and the proxy, an unauthenticated request, including one originating from a web page in the developer's own browser, could reach the proxy and make it launch MCP commands over stdio. The proxy has permission to spawn local processes, so this was full RCE. Ratings ran to CVSS 4.0 base 9.4 (also cited as CVSS 3.x 9.8).

The 0.14.1 fix is exactly the token gate and origin check in the diagram above: a random session token is now generated at startup and required as a bearer token, and the proxy validates the request Origin against an allowed-origins list. That is why the browser opens with the token pre-filled and why an unauthenticated hit returns 401.

Three rules follow directly. Keep Inspector current (0.14.1 or later; latest is 0.22.0). Never set DANGEROUSLY_OMIT_AUTH=true, which the README flags as exposing your machine to browser-based RCE. And never expose the proxy to an untrusted network, because it can start processes on your host. The broader lesson connects straight to our MCP security work: a tool that can spawn processes on behalf of a browser is a capability, and capabilities need auth by default. If you are surveying the ecosystem, our best MCP servers roundup applies the same lens to what you connect.

FAQ