MCP Inspector: How to Use It, CLI Mode and Fixes (v2 Tested)

MCP Inspector is the reference debugging tool for Model Context Protocol servers, and you run it with npx @modelcontextprotocol/inspector. That command starts a local web UI at http://127.0.0.1:6274, where you connect a server, call its tools, read its resources and test its prompts. Add --cli to get a scriptable client instead of the browser, or --tui for a terminal UI. No install step is needed, but the current release needs Node 22.19.0 or newer (Source: MCP Inspector docs).

The version matters. The npm latest tag is 2.9.0, a v2 rewrite published on 2026-09-30, while many tutorials still describe v1 and its "proxy session token" errors (Source: npm registry). We ran 2.9.0 against a Python FastMCP server over stdio, Streamable HTTP and SSE; every command below comes from that run.

Key takeaways

• Run it: npx @modelcontextprotocol/inspector <command that starts your server>, then open the printed URL, which carries the session token.
• Script it: npx @modelcontextprotocol/inspector --cli <server> --method tools/list; the server target must come before any flags.
• Transports: a URL ending in /mcp means Streamable HTTP, /sse means SSE, and anything else needs --transport.
• v1 errors are a version signal: v2 has no proxy on port 6277 and renames the token variable to MCP_INSPECTOR_API_TOKEN.

What MCP Inspector is and which version you are running

MCP Inspector is a developer client for the Model Context Protocol (MCP), the open protocol that lets AI applications call tools and read data from external servers. It ships as one npm package, @modelcontextprotocol/inspector, with three front ends behind one mcp-inspector binary: web (the default), CLI and TUI (Source: MCP Inspector docs).

Version 2 changed the parts people search for. The table below is the short version of the official migration guide (Source: Inspector migration guide).

To stay on v1, pin it with npx @modelcontextprotocol/inspector@v1-latest; v1 now receives security fixes only (Source: Inspector migration guide).

Measured in our test: npm resolved latest to 2.9.0 and v1-latest to 1.0.2. On Node v22.18.0, one patch below the floor, a cold npx install printed 2 EBADENGINE warnings (for the Inspector and undici), yet the stdio tools/list call still exited 0. The migration guide warns that an older Node "fails later, obscurely", so upgrade anyway.

How to use MCP Inspector with a Python FastMCP server

The Inspector is a Node tool, but it inspects servers written in any language because it only needs the command that starts them. FastMCP is the most common Python framework for this, and its mcp.run() call defaults to stdio (Source: FastMCP docs).

This is the whole server we tested: one tool, one resource and one prompt.

import sys
from fastmcp import FastMCP

mcp = FastMCP("inspector-demo")

@mcp.tool
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

@mcp.resource("config://app")
def app_config() -> str:
    """Static app configuration."""
    return '{"env": "dev", "version": "1.0"}'

@mcp.prompt
def review_code(code: str) -> str:
    """Ask for a code review."""
    return f"Review this code and list bugs:\n\n{code}"

if __name__ == "__main__":
    if len(sys.argv) > 1 and sys.argv[1] == "http":
        mcp.run(transport="http", host="127.0.0.1", port=8000)
    else:
        mcp.run()

Install FastMCP in a virtual environment, then hand the Inspector the Python command:

uv venv venv && uv pip install --python venv/bin/python fastmcp
npx @modelcontextprotocol/inspector venv/bin/python server.py

FastMCP also has its own development launcher, fastmcp dev inspector server.py, which starts your server together with the MCP Inspector (Source: FastMCP docs).

Measured in our test: FastMCP 4.0.10 pulled in the mcp SDK 2.2.0. Its fastmcp dev inspector --help still describes --server-port as the "Port for the MCP Inspector Proxy server", and the source sets SERVER_PORT. The package spec it passes to npx has no version pin, so it launches the v2 Inspector.

Inference: in v2, SERVER_PORT only moves the MCP Apps sandbox, so that flag no longer changes anything you browse. Choosing a library? See our FastMCP vs MCP Python SDK comparison.

Connecting over stdio, Streamable HTTP or SSE

Stdio is the default: the positional command is what the Inspector spawns. For a running server, pass its URL. With no --transport flag, v2 infers the transport from the URL's last path segment and nothing else (Source: Inspector migration guide).

Measured in our test: we ran the same FastMCP server with transport="http" on port 8000 and transport="sse" on port 8001, then pointed the CLI at each URL shape. Nothing listened on port 8999.

One documentation trap: the CLI README still says a bare remote URL defaults to SSE. In 2.9.0 it does not; the bare-host row above failed. Prefer Streamable HTTP for new servers, since FastMCP calls SSE a legacy transport kept for older clients (Source: FastMCP docs).

MCP Inspector CLI mode: tools, resources and prompts

CLI mode connects, runs one --method, prints the result and exits, which suits terminals, CI jobs and coding agents. Add --format json to get one {"result": ...} object with no banners, ready for jq (Source: MCP Inspector CLI docs).

These are the calls we ran against the stdio server, with what came back:

--tool-arg JSON-parses each value, so count=1 arrives as a number; use --tool-args-json '{"zip":"10001"}' when a string must stay a string (Source: MCP Inspector CLI docs).

Argument order is the classic mistake. Under --cli, the leading run of non-dash tokens is the server, so --cli --method tools/list venv/bin/python server.py drops the target and falls back to your catalog. When the server itself takes flags, put them before a -- and the Inspector's options after it (Source: Inspector migration guide).

Measured in our test: the wrong-order command exited 1 with "No servers found in config file", and left an empty {"mcpServers":{}} catalog behind. A warm CLI round trip took a median of 1413 ms over stdio, which includes spawning Python, and 834 ms over HTTP against a running server (n=5, Apple M1).

Exit codes for CI and scripts

Every non-zero exit maps to a fixed failure class. The CLI also writes one JSON line to stderr, so a script can branch on the cause instead of parsing prose (Source: MCP Inspector CLI docs).

Measured in our test: tools/call with a=x printed the result with isError true on stdout and still exited 5 with {"error":{"code":"tool_is_error"}}. A missing tool returned tool_not_found, also exit 5. That is a v1 change: v1 exited 0 for a failing tool call (Source: Inspector migration guide).

A minimal CI check is mcp-inspector --cli <server> --method tools/list --format json | jq -e '.result.tools | length > 0'. For OAuth-protected servers, add --stored-auth-only so the job fails fast instead of waiting on a browser login (Source: MCP Inspector CLI docs).

Using a config file: --config vs --catalog

Both flags take the familiar mcpServers JSON shape, but they behave differently. --config is a read-only session file that must exist; --catalog is the Inspector's own writable list, created if missing, with ~/.mcp-inspector/mcp.json as the default (Source: Inspector migration guide).

This is the file we used, with one stdio entry and one Streamable HTTP entry:

{ "mcpServers": {
  "demo-stdio": { "type": "stdio", "command": "/path/to/venv/bin/python", "args": ["/path/to/server.py"] },
  "demo-http":  { "type": "streamable-http", "url": "http://127.0.0.1:8000/mcp" }
} }

Select an entry with --server, which only works under --cli:

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

Measured in our test: both entries connected, --method servers/list returned demo-http and demo-stdio without connecting, and the file's hash was unchanged after the runs. A missing file failed with "Config file not found". Combining --config with a positional server failed with "--config cannot be combined with an ad-hoc server URL/command".

Ports, the session token and Docker

The web launcher binds to 127.0.0.1 by default and guards every /api/* route with a bearer token in the x-mcp-remote-auth header. The token is random per launch unless you set MCP_INSPECTOR_API_TOKEN (Source: Inspector environment variables).

Measured in our test: the web process listened on 127.0.0.1 ports 6274, 6275 and 6278, and the v1 proxy port did not answer. The banner printed a 64-character token both in the URL and on its own line. GET / returned 200 and embedded the token in the page, while /api/config returned 401 without the header or with a wrong token, and 200 with it. Setting MCP_INSPECTOR_API_TOKEN made the banner use our fixed value. HOST=0.0.0.0 exited 1 with "Refusing to bind".

Because the page itself carries the token, anyone who can reach port 6274 can drive a backend that spawns processes. Keep it on loopback, as the official container recipe does (Source: Inspector migration guide):

docker run --rm -p 127.0.0.1:6274:6274 ghcr.io/modelcontextprotocol/inspector:latest

Publish 6275 as well if you test MCP Apps, and never set DANGEROUSLY_OMIT_AUTH on a reachable host (Source: Inspector environment variables).

Fixing common MCP Inspector errors

Most "MCP Inspector not connecting" reports fit a few patterns. The first three messages come from v1; a Stack Overflow question on the proxy error has over 14,000 views and no accepted answer.

The v2 causes come from the migration guide, and the last four messages are the exact text our run produced (Source: Inspector migration guide). On Windows, a 2026 "Cannot find native binding" failure after an update was tracked in issue #1852 and closed as fixed, so update before debugging further.

FAQ

What is an MCP inspector?

An MCP inspector is a client for testing Model Context Protocol servers. The official one, @modelcontextprotocol/inspector, connects to a server over stdio, Streamable HTTP or SSE. It lets you list and call tools, read resources and render prompts from a web UI, a terminal UI, or a scriptable CLI with fixed exit codes (Source: MCP Inspector docs).

How do I run the MCP Inspector on Windows?

Use the same command as on macOS or Linux: install Node 22.19.0 or newer, then run npx @modelcontextprotocol/inspector from PowerShell or Command Prompt, followed by your server's start command. We tested on macOS, not Windows. If you hit a native-binding error, update to the latest release (Source: MCP Inspector docs).

Can I use the MCP Inspector in Python?

Yes, as a target. The Inspector runs on Node, but it inspects Python servers by spawning them: npx @modelcontextprotocol/inspector venv/bin/python server.py. FastMCP users can also run fastmcp dev inspector server.py, which launches the same npm package. There is no separate Python build of the official Inspector (Source: FastMCP docs).

How to access MCP inspector?

Open the URL the launcher prints, http://127.0.0.1:6274 plus a MCP_INSPECTOR_API_TOKEN query parameter. Without that token the page loads but API calls are refused. Set MCP_INSPECTOR_API_TOKEN yourself for a stable URL, and keep the server on loopback. The official tool runs locally, not as a hosted website (Source: Inspector environment variables).

What does MCP stand for?

MCP stands for Model Context Protocol, an open standard for connecting AI applications to external tools, data and prompts through MCP servers. The Inspector is the protocol project's reference tool for testing those servers. Use it before a real AI client, such as an IDE or chat app, depends on them (Source: MCP Inspector docs).

Related coverage

• FastMCP vs MCP Python SDK: Which to Use in 2026
• FastMCP vs FastAPI-MCP: Which Python MCP Library?
• MCP vs RAG: Differences, Use Cases, and a 12-Query Test

References

• FastMCP docs - https://gofastmcp.com/deployment/running-server
• Inspector environment variables - https://github.com/modelcontextprotocol/inspector/blob/main/docs/environment-variables.md
• Inspector migration guide - https://github.com/modelcontextprotocol/inspector/blob/main/docs/v1-to-v2-migration.md
• MCP Inspector CLI docs - https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/cli
• MCP Inspector docs - https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector
• npm registry - https://www.npmjs.com/package/@modelcontextprotocol/inspector