MCP Inspector: The Practical Guide to Testing MCP Servers

The MCP Inspector is the official developer tool for testing and debugging Model Context Protocol servers. Run npx @modelcontextprotocol/inspector to open a browser UI where you can connect to any stdio or Streamable HTTP server, call its tools, read its resources, render its prompts, and watch the raw JSON-RPC traffic. The same package also ships a scriptable CLI (--cli) for CI and a terminal UI (--tui).

This guide covers the current v2 line of the Inspector (2.11 at the time of writing). If you are following an older tutorial that mentions a proxy on port 6277 or MCP_PROXY_AUTH_TOKEN, it describes v1 — the differences are called out below.

What the MCP Inspector Is (and What Changed in v2)

The Inspector is a reference MCP client built for humans. Instead of wiring your server into Claude, Cursor or another host and guessing why a tool doesn't show up, you connect the Inspector directly and see exactly what the server advertises and returns.

According to the official docs, one package now provides three clients behind one binary:

Key v2 changes from the migration guide:

• Node 22.19.0 or newer is required. Older Node versions may install but fail later in confusing ways — check node -v first.
• The proxy is gone. v1 ran a UI on 6274 plus a proxy on 6277. v2 runs one web server on 6274 (plus an MCP Apps sandbox on 6275).
• Servers live in a catalog file at ~/.mcp-inspector/mcp.json, shared by the web UI, CLI and TUI, instead of browser localStorage.
• The auth token was renamed to MCP_INSPECTOR_API_TOKEN (the old name still works as a fallback).
• Need v1? Pin it with npx @modelcontextprotocol/inspector@v1-latest.

Run the Inspector

No install is needed. With Node 22.19+:

# Open the web UI with no server; add servers from the Servers tab
npx @modelcontextprotocol/inspector

# Open the web UI already pointed at a local stdio server
npx @modelcontextprotocol/inspector node build/index.js

The command prints a URL that contains a per-launch session token and opens it in your browser. Use that printed URL rather than typing localhost:6274 by hand — the backend can spawn processes on your machine, so every API call is guarded by that token. Set MCP_AUTO_OPEN_ENABLED=false if you don't want a browser tab to open automatically.

On first launch, the web client seeds the catalog with three sample servers (a filesystem server scoped to /tmp, the "everything" reference server, and a hosted example server), so you can click around before connecting your own.

Connect a stdio Server

For a local server, pass the command that starts it as positional arguments. Everything after the Inspector's own flags is the server command:

# A server you're building
npx @modelcontextprotocol/inspector node build/index.js

# A published npm server
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop

# A published Python server via uvx
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/my-repo

# Environment variables and server flags
npx @modelcontextprotocol/inspector -e API_KEY=xxx -- node build/index.js --verbose

Use -e KEY=value for environment variables and --cwd <path> to set the server's working directory. On the web and TUI clients, everything after -- goes to the server command. The Filesystem server is a good first target because it exercises tools, resources and the roots capability.

Connect a Streamable HTTP (Remote) Server

For a remote server, pass the URL. The Inspector infers the transport only from the path suffix:

# Path ends in /mcp, so Streamable HTTP is inferred
npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

# Any other path needs --transport
npx @modelcontextprotocol/inspector --cli https://api.example.com/v1 --transport http --method tools/list

# Static API key or bearer header
npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp \
  --header "Authorization: Bearer $TOKEN" --method tools/list

Note that a trailing slash (/mcp/) counts as ambiguous. v1 silently fell back to SSE here; v2 refuses to guess. You can also add the server from the Servers tab in the web UI and set headers, timeouts and OAuth in its Server Settings.

Test Tools, Resources and Prompts in the Web UI

Once connected, the tab bar shows only what the server's capabilities support:

A practical testing loop:

1. Open Tools, pick a tool, and try both a valid call and a deliberately bad one (missing required field, wrong type). A good server returns a clear tool error the model can recover from.
2. Watch Protocol while you click. Pin the monitoring group to keep it in a right-hand sidebar next to Tools.
3. Check Console (stdio) or Network (HTTP) when something fails silently — that's where stack traces and 401s show up.
4. In Resources, confirm MIME types and that templates resolve. If you're unsure whether something should be a resource or a tool, see MCP resources vs tools.

The Tools tab also flags schema portability problems — JSON Schema that is technically valid but that some real clients reject. That's worth checking before you publish a server.

Per-server Server Settings let you set roots, headers, timeouts, OAuth fields and a "Fetch Lists One Page at a Time" toggle for testing pagination — useful if your server exposes many tools (see MCP tool discovery).

Script It: CLI Mode for CI and Agents

CLI mode connects, runs one --method, prints the result and exits. The mode flag must come first:

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

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

# Pass arguments as one JSON object (no type coercion)
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name mytool --tool-args-json '{"id":"012"}'

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

# Machine-readable output for jq
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list --format json | jq '.result.tools[].name'

Supported methods include initialize, tools/list, tools/call, resources/list, resources/read, resources/templates/list, prompts/list and prompts/get. To pick a server from a config file you didn't write (for example a client's mcp.json), use the read-only --config flag with --server:

npx @modelcontextprotocol/inspector --cli --config ./mcp.json --server myserver --method tools/list

The CLI has stable exit codes, which makes it a good CI smoke test:

On failure it writes a one-line JSON error envelope to stderr. Note the v1 difference: a failing tool call used to exit 0; in v2 it exits 5, so CI pipelines that silently passed may start failing — correctly.

Authentication and OAuth

For servers that use MCP authorization, the Inspector runs the OAuth flow for you:

• Web UI: configure OAuth in Server Settings (client ID/secret, scopes, refresh token). The Redirect URI to register is shown there; it defaults to http://localhost:6274/oauth/callback.
• CLI and TUI: on a 401, the CLI starts a loopback callback at http://127.0.0.1:6276/oauth/callback, prints the authorization URL, opens your browser, and retries once you sign in. Override with --callback-url.
• CI: use --stored-auth-only so the run never waits on a browser and fails fast with auth_required (exit 3) instead.
• Static keys: just pass --header "Authorization: Bearer ...".

Tokens are stored in your OS keychain when available. On machines without one (headless Linux, containers), they fall back to ~/.mcp-inspector/secrets.json, which is unencrypted unless you supply a key — keep that in mind on shared machines, and read our MCP security best practices.

Common Errors and Fixes

For Docker, the official image is ghcr.io/modelcontextprotocol/inspector:latest; publish it on loopback only: docker run --rm -p 127.0.0.1:6274:6274 ghcr.io/modelcontextprotocol/inspector:latest.

When to Use the Inspector vs. Your Real Client

Use the Inspector to answer "is my server correct?" — schemas, results, errors, auth, pagination. Then move to a real host to answer "does the model use it well?" — tool descriptions, naming and context cost. Our setup guides for Claude Code, Codex and ChatGPT cover that second step. If a tool works in the Inspector but not in a client, the difference is almost always client-side: config, auth, or how the client handles schemas.

Next Steps

• Pick a server from the MCP.so directory and point the Inspector at it — the GitHub MCP Server, Playwright MCP or Context7 are good, well-documented targets.
• Add a CLI smoke test (--method tools/list --format json) to your server's CI.
• Building a server with many or changing tools? Read MCP tool discovery next.