Blog

MCP Inspector: The Complete Guide to Testing and Debugging MCP Servers

Cover Image for MCP Inspector: The Complete Guide to Testing and Debugging MCP Servers
Daniel Kim
Daniel Kim

What Is MCP Inspector?

MCP Inspector is the official interactive developer tool for testing and debugging Model Context Protocol servers, maintained by the Model Context Protocol team at github.com/modelcontextprotocol/inspector. If you're building or maintaining an MCP server and you're still verifying it by wiring it into Claude Desktop or another client and hoping for the best, you're doing it the hard way. MCP Inspector gives you a direct line to your server: call tools, read resources, run prompts, and watch raw protocol traffic, all without a full client in the loop.

This guide walks through everything you need to actually use MCP Inspector day to day: quick start, the UI panes, CLI mode for scripting and CI, and how to debug the failures you'll actually run into — servers that won't connect, tools that throw, and auth that silently breaks. By the end you'll know how to use MCP Inspector as your primary feedback loop while developing a server, not just a one-off sanity check.

If you haven't built an MCP server before, it's worth reading our guide to getting started with MCP first — this post assumes you already have a server (or a package name) to point Inspector at.

Quick Start

MCP Inspector runs directly through npx with no separate install step. The basic form is:

npx @modelcontextprotocol/inspector <command>

For a locally developed TypeScript server:

npx @modelcontextprotocol/inspector node build/index.js

For a Python server run through uv:

npx @modelcontextprotocol/inspector \
  uv \
  --directory path/to/server \
  run \
  package-name \
  args...

You can also point Inspector at a published package without cloning anything, which is the fastest way to try out a server someone else wrote:

# npm package
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /Users/username/Desktop

# PyPI package
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git

Running the command starts two components, as documented in the Inspector README:

  • MCPI (client) — a React web UI, served on port 6274
  • MCPP (proxy) — a Node.js process on port 6277 that speaks MCP to your server and HTTP to the browser UI

The proxy is what lets the browser-based UI talk to a server that only understands stdio, SSE, or streamable HTTP — it bridges the transport for you. When Inspector starts, it prints a URL with a session token baked in; open that link and you're connected.

The UI Walkthrough

Once the UI loads, you land on the server connection pane, where you pick a transport (stdio, SSE, or streamable HTTP) and, for local servers, adjust the command, arguments, and environment before connecting. After connecting, the interface splits into a few functional areas, described in the official Inspector docs:

Pane What it's for
Server connection Choose transport, edit command/args/env, connect or reconnect
Tools List tools, view their JSON schemas, fill a generated form, execute, inspect results
Resources Browse available resources hierarchically, view metadata (MIME types, descriptions), inspect content, test subscriptions
Prompts List prompt templates, see their arguments, run them with custom values, preview the generated messages
Notifications Live feed of server logs and protocol notifications as they arrive

This is the core loop for using MCP Inspector day to day: open the Tools tab, pick a tool, fill in the form Inspector generates from the tool's input schema, hit run, and read the result pane. Because the form is generated straight from your server's declared schema, a wrong or missing field type in your tool definition shows up immediately as a broken or confusing form — which is itself a useful bug signal before any LLM ever touches your server.

The Notifications pane deserves more attention than it usually gets. Any logging/message notifications, progress updates, or resource change notifications your server emits land here in real time, which makes it the fastest way to confirm your server is actually sending the signals you think it is, rather than inferring it from client behavior.

CLI Mode

For scripting, CI, and quick one-off checks, pass --cli to run Inspector without launching the browser UI at all:

npx @modelcontextprotocol/inspector --cli node build/index.js

CLI mode exposes MCP methods directly on the command line. A few common ones:

# List available tools
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# List resources
npx @modelcontextprotocol/inspector --cli node build/index.js --method resources/list

# List prompts
npx @modelcontextprotocol/inspector --cli node build/index.js --method prompts/list

# Call a tool with arguments
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name mytool --tool-arg key=value

Arguments can carry structured JSON too, which matters once your tools take objects or arrays instead of flat strings:

npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name mytool \
  --tool-arg 'options={"format": "json", "max_tokens": 100}'

CLI mode also works against remote servers over HTTP or SSE, including with custom headers for authenticated endpoints:

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

This is the piece that makes MCP Inspector genuinely useful beyond manual poking: you can drop a tools/list or tools/call check into a pre-commit hook or CI pipeline and catch a broken schema or a regressed tool before it ships, without maintaining a bespoke test harness that reimplements the MCP client.

Passing Environment Variables, Arguments, and Config Files

Most real servers need environment variables (API keys, config paths) or extra CLI arguments to run correctly, and Inspector has explicit support for both.

Environment variables use -e, and a -- separator disambiguates Inspector's own flags from arguments meant for your server:

npx @modelcontextprotocol/inspector -e API_KEY=$API_KEY -- node build/index.js --verbose

Arguments without any special environment handling just pass straight through:

npx @modelcontextprotocol/inspector node build/index.js arg1 arg2

For servers you test repeatedly, or when you're juggling several servers at once, Inspector also supports a config file in the same shape as mcp.json:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-everything"],
      "env": { "hello": "Hello MCP!" }
    }
  }
}

Launch a named server from that file:

npx @modelcontextprotocol/inspector --config path/to/config.json --server server-name

Config entries support a "type" field for the transport — stdio (the default), sse, or streamable-http — with an accompanying "url" for the latter two. Once you've got a server configured and working in Inspector, the UI's export feature will hand you back a config snippet (either a single server entry to merge into an existing mcp.json, or a complete servers file) so you don't have to hand-transcribe it into your client of choice.

Debugging Real-World Scenarios

Server Won't Connect

This is the most common first failure, and it's almost always one of a few things:

  • Wrong command or path. If you're launching a local server, confirm the exact command works standalone in your shell before handing it to Inspector — node build/index.js should print or run without Inspector in the loop.
  • Missing environment variables. A server that silently exits because a required API_KEY isn't set looks identical to a connection failure from Inspector's side. Check the Notifications pane and your terminal output for stderr from the server process.
  • Port conflicts. The proxy defaults to port 6277 and the UI to 6274. If something else is already bound to those ports, override them:
CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node build/index.js
  • Transport mismatch. If you're testing a remote server, make sure you've selected the transport it actually speaks — SSE and streamable HTTP are not interchangeable, and picking the wrong one produces a connection error that looks like a server bug.

Tool Calls Returning Errors

When a tool call fails inside Inspector, check three things in order: the request payload matches the schema (the Tools tab shows you the exact schema so you can compare field names and types), the Notifications pane for any server-side log lines emitted during the call, and the raw result pane for whether the server returned a proper MCP error object versus just crashing. A tool that throws an unhandled exception in your server code often surfaces in Inspector as a vague failure with no useful message — that's your cue to add explicit error handling and structured error responses in the tool implementation itself, not a problem with Inspector.

Auth and Session Token Issues

Session token authentication is enabled by default when you launch Inspector. On startup, the proxy prints something like:

🔑 Session token: 3a1c9f...
🔗 Open inspector with token pre-filled:
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=3a1c9f...

If you open the bare localhost:6274 URL without the token and get an auth error, that's expected — use the printed link, or set the token explicitly via environment variable:

MCP_PROXY_AUTH_TOKEN=$(openssl rand -hex 32) npm start

By default both the client and proxy bind to localhost only. If you need Inspector reachable from another machine (for example, testing from a container or a second device), you can override this with HOST=0.0.0.0, but treat that as strictly a local development convenience, never something you leave on. Inspector also validates the Origin header as DNS rebinding protection; if you're proxying through a custom domain or port during development, add it explicitly with ALLOWED_ORIGINS:

ALLOWED_ORIGINS=http://localhost:6274,http://localhost:8000 npx @modelcontextprotocol/inspector node build/index.js

The docs are explicit that disabling auth entirely with DANGEROUSLY_OMIT_AUTH=true leaves your machine open to attack via the browser — don't reach for it just to get past a token prompt, fix the token flow instead.

For remote servers that require their own auth, pass headers directly on the command line in CLI mode, as shown earlier with --header "X-API-Key: your-api-key", or configure them in the server connection pane when using the UI.

Tips and Best Practices

A few habits make MCP Inspector far more useful once you're using it regularly to test and debug MCP servers rather than just poking at one:

  • Treat Inspector as your inner dev loop. Start it once, then reconnect after every server rebuild rather than restarting the whole Inspector process — it's faster and keeps your Notifications history around for comparison.
  • Watch capability negotiation on connect. The first thing that happens after a successful connection is a capabilities exchange; if a tab you expect (Resources, Prompts) is empty or missing, your server likely isn't declaring that capability, not that Inspector failed to find it.
  • Script your smoke tests with CLI mode. A tools/list check that fails loudly in CI beats discovering a broken tool schema when a user's client throws a cryptic error.
  • Use Docker for a clean, reproducible environment when you want to isolate Inspector from your local Node setup, especially useful in CI:
docker run --rm -p 127.0.0.1:6274:6274 -p 127.0.0.1:6277:6277 \
  -e HOST=0.0.0.0 -e MCP_AUTO_OPEN_ENABLED=false \
  ghcr.io/modelcontextprotocol/inspector:latest
  • Test edge cases deliberately, not just the happy path: invalid tool inputs, missing required prompt arguments, and concurrent tool calls all surface real bugs that a single manual "does it basically work" pass will miss.
  • Adjust timeouts for slow tools. If a tool legitimately takes a while, raise MCP_SERVER_REQUEST_TIMEOUT (default 300000ms) in the UI settings rather than assuming a timeout means your server is broken.

Conclusion

MCP Inspector is the closest thing the MCP ecosystem has to a REPL for server development. The UI gives you fast, visual feedback while you're actively building — schema-generated forms for tools, a real resource browser, prompt previews, and a live notification feed — while CLI mode turns the exact same checks into something you can run unattended in CI. Learning how to use MCP Inspector properly, from basic connection through auth troubleshooting, will save you far more time than it costs: most "my MCP server doesn't work" reports turn out to be schema mismatches, missing environment variables, or transport confusion, and all three show up clearly the moment you point Inspector at the server directly instead of debugging through a full client.

If you're actively developing an MCP server, keep an Inspector session open next to your editor. It's the fastest way to catch a broken tool before your users do.