MCP Inspector – Developer Guide

What is this about?

The MCP Inspector is the official interactive developer tool for testing and debugging Model Context Protocol (MCP) servers. It lets you connect to a server, list and call its tools, read its resources, render its prompts, and watch the raw protocol traffic — without wiring the server into a full LLM client first. This guide covers the architecture, every way to launch it, the configuration surface, and the security model.

Looking for a click-by-click walkthrough of the web UI fields instead? See the MCP Inspector User Guide.

Repository: https://github.com/modelcontextprotocol/inspector Package: @modelcontextprotocol/inspector (npm) Runtime requirement: Node.js ^22.7.5

1. What it is and when to use it

The Inspector sits between you and an MCP server and gives you a hands-on view of everything the server exposes over the protocol. Reach for it when you:

are building an MCP server and want to verify tools, resources, and prompts before connecting it to Claude, Cursor, or VS Code;
need to debug a connection — capability negotiation, transport errors, auth handshakes;
want to inspect a third-party server (npm/PyPI package) before trusting it;
need to exercise edge cases — invalid inputs, missing arguments, error responses — interactively or scripted.

It complements the broader MCP work covered in the MCP Connector Guide for Claude: that guide is about building and shipping connectors; this one is about inspecting and debugging them.

2. Architecture

The Inspector is two cooperating processes:

+----------------------+        +----------------------+        +------------------+
|  MCP Inspector       |  HTTP  |  MCP Proxy           | stdio  |  Your MCP server |
|  Client (MCPI)       | <----> |  (MCPP)              | SSE    |  (node/python/…) |
|  React web UI        |        |  Node.js bridge      | HTTP   |                  |
|  http://localhost:6274        |  http://localhost:6277        |                  |
+----------------------+        +----------------------+        +------------------+

Component	Name	Default port	Role
Inspector Client	MCPI	`6274`	React web UI you interact with in the browser
Inspector Proxy	MCPP	`6277`	Node.js bridge that spawns/connects the server and translates transports

Why two processes?

A browser tab cannot spawn a local process or open an arbitrary stdio pipe. The proxy (MCPP) does that on your machine and exposes it to the web UI (MCPI) over HTTP. The proxy is also what enforces the session-token authentication described in §8 below.

The port numbers are a T9 keypad mnemonic: MCPI → 6274, MCPP → 6277.

3. Prerequisites

Node.js ^22.7.5 (the Inspector enforces this engine).
The command needed to start your server locally (for STDIO), or a reachable URL (for SSE / Streamable HTTP).
Any secrets the server itself needs (API keys, tokens) — supplied as environment variables or headers, never hard-coded.

4. Quick start

The Inspector runs through npx with no install step.

Bare UI

npx @modelcontextprotocol/inspector

This starts both processes and opens http://localhost:6274 with a pre-authenticated session-token URL printed to the terminal.

Inspect a published package

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

# PyPI package (via uvx)
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/my-repo

Inspect a locally developed server

# TypeScript: pass the runtime + entrypoint + args
npx @modelcontextprotocol/inspector node build/index.js arg1 arg2

# Python (uv project)
npx @modelcontextprotocol/inspector uv --directory path/to/server run package-name args...

Pass environment variables and custom ports

# -e injects env vars into the spawned server process
npx @modelcontextprotocol/inspector -e API_KEY=value node build/index.js

# Override the UI and proxy ports
CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node build/index.js

Everything after the package name is the server command

In npx @modelcontextprotocol/inspector node build/index.js --flag, the Inspector treats node as the Command, and build/index.js --flag as the Arguments. These map directly to the UI fields documented in the User Guide.

Docker

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

5. UI mode vs. CLI mode

	UI mode (default)	CLI mode (`--cli`)
Best for	Exploration, manual testing, OAuth debugging	Scripting, CI, automation, quick one-shot calls
Output	Interactive browser UI	Plain text / JSON to stdout
Auth UX	Session token in the URL	No browser; token via env if needed

CLI mode runs the same proxy logic but skips the browser entirely.

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

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

# Talk to a remote HTTP server
npx @modelcontextprotocol/inspector --cli https://my-server.example.com \
  --transport http --method tools/list

# Send a custom header (e.g. an API key)
npx @modelcontextprotocol/inspector --cli https://my-server.example.com \
  --header "X-API-Key: value" --method tools/list

# Drive it from a config file entry
npx @modelcontextprotocol/inspector --cli --config ./mcp.json --server myserver --method tools/list

Common --method values mirror the MCP spec: tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get.

6. Configuration file (`mcp.json`)

Instead of retyping commands, store server definitions in a config file and select one by name. The format matches the familiar mcpServers shape used by Claude Desktop and other clients:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["build/index.js"],
      "env": { "API_KEY": "value" }
    },
    "sse-server": {
      "type": "sse",
      "url": "http://localhost:3000/sse"
    },
    "http-server": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Load it and pick a server:

npx @modelcontextprotocol/inspector --config ./mcp.json --server my-server

Round-trip with the UI

The UI's Server Entry and Servers File copy buttons emit exactly this JSON. Configure a server visually once, copy it out, and commit it to mcp.json for repeatable runs and CI.

7. Environment variables (at launch)

These are set on the process that starts the Inspector (not to be confused with the server's own env vars passed via -e):

Variable	Purpose	Notes
`CLIENT_PORT`	Port for the web UI (MCPI)	Default `6274`
`SERVER_PORT`	Port for the proxy (MCPP)	Default `6277`
`HOST`	Interface the proxy binds to	Default localhost; set `0.0.0.0` only on trusted networks
`MCP_PROXY_AUTH_TOKEN`	Pin the proxy session token to a known value	Otherwise auto-generated per run
`ALLOWED_ORIGINS`	Comma-separated allowlist for DNS-rebinding / origin checks	e.g. `http://localhost:6274`
`MCP_AUTO_OPEN_ENABLED`	Auto-open the browser on start	Set `false` for Docker / headless
`DANGEROUSLY_OMIT_AUTH`	Disable proxy auth entirely	Do not use — see §8

8. Authentication & the security model

By default the proxy generates a random session token on each launch and prints a pre-filled URL:

🔑 Session token: 3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4
🔗 http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=3a1c267f...

Open that URL and the UI is authenticated automatically. Opening a bare http://localhost:6274 instead will prompt you to paste the token under Configuration → Proxy Session Token.

Never disable authentication

The proxy can spawn local processes and connect to local servers. Setting DANGEROUSLY_OMIT_AUTH=true removes the token gate, which — per the project's own warning — leaves your machine open to remote compromise: "Visiting a malicious website or viewing a malicious advertisement could allow an attacker to remotely compromise your computer."

Keep the default token auth on. Keep the proxy bound to localhost. Only set HOST=0.0.0.0 on a network you fully trust, and pair it with ALLOWED_ORIGINS.

Auth to the server itself (a separate concern) is configured in the UI:

Custom Headers / Bearer Token — for SSE and Streamable HTTP servers that expect an Authorization: Bearer … header or an API-key header.
OAuth 2.0 Flow — the Inspector can run the full authorization-code flow, including metadata discovery and dynamic client registration, and inject the resulting access token. See the User Guide (section Authentication & Open Auth Settings) for the field-by-field walkthrough.

9. Developing on the Inspector itself

If you are hacking on the Inspector source (not just using it):

npm run dev      # run client + proxy in watch mode
npm run build    # production build
npm start        # serve the built app

To develop against a local checkout of the MCP SDK:

npm run dev:sdk "cd sdk && npm run examples:simple-server:w"

10. Typical workflow & troubleshooting

Iterative server development:

Launch the Inspector with your server.
Verify connectivity and capability negotiation (check the Notifications pane).
Make a change → rebuild the server → Reconnect in the UI.
Re-test the affected tools/resources and watch the message log.
Probe error handling with invalid inputs and missing arguments.

Common issues:

Symptom	Likely cause	Fix
"Connection Error — did you add the proxy session token?"	UI opened without the token	Use the printed URL, or paste the token in Configuration
"Error connecting to MCP Inspector Proxy"	Proxy not running / wrong port	Confirm MCPP on `6277`; check `SERVER_PORT`
Server starts then exits	Wrong Command/Arguments, missing env var	Re-check the spawn command; add vars via `-e` or the UI
Tool call times out	Long-running tool exceeds request timeout	Raise Request Timeout in the Configuration panel (see User Guide §7)

1. What it is and when to use it​

2. Architecture​

3. Prerequisites​

4. Quick start​

Bare UI​

Inspect a published package​

Inspect a locally developed server​

Pass environment variables and custom ports​

Docker​

5. UI mode vs. CLI mode​

6. Configuration file (mcp.json)​

7. Environment variables (at launch)​

8. Authentication & the security model​

9. Developing on the Inspector itself​

10. Typical workflow & troubleshooting​

Further reading​