MCP Inspector: How to Run It and Use It to Check a Server (Nov 2026)

The MCP Inspector is the official tool for testing and debugging MCP servers. Run npx @modelcontextprotocol/inspector, connect a server, and a web UI shows every tool it offers, what each one says it does, and how it signs you in. There's nothing to install. It's the quickest way to check a server before an agent uses it.

Everything below is checked against the Inspector's GitHub README and the official docs, as of version 2.13.0 (released 28 October 2026).

What the MCP Inspector is: web UI, CLI and TUI

It's a client, like Claude or Cursor, except it doesn't use the tools on its own. It connects to a server and shows you what the server sends back.

One npm package, @modelcontextprotocol/inspector, gives you three ways to use it:

Mode	Command	Good for
Web UI (default)	npx @modelcontextprotocol/inspector	Clicking through tools, resources and prompts in the browser
CLI	npx @modelcontextprotocol/inspector --cli	Scripts, CI, saving output to a file
TUI	npx @modelcontextprotocol/inspector --tui	A terminal UI when you don't want a browser

The package also includes mcpdo, an experimental client that keeps one connection open across many commands. You won't need it to check a server.

The mode flag must come first, right after the package name.

How to install the MCP Inspector (Node and version)

There's nothing to install. npx downloads and runs it. You need Node 22.19.0 or newer; check with node -v. An older Node often installs with only a warning and then fails later in confusing ways.

Use 2.12.0 or later. On 21 October 2026 the Inspector published a batch of security advisories, including remote code execution through a malicious server's OAuth link on Windows and WSL (fixed in 2.12.0). Plain npx picks up the latest release, but a pinned version in a script or a global install won't update itself. More on this under Is the Inspector itself safe to run?

The old v1 line is deprecated and gets security fixes only. If an old tutorial mentions a proxy on port 6277 or MCP_PROXY_AUTH_TOKEN, it's describing v1.

How to run the MCP Inspector with npx (web UI)

A local (stdio) server

Put the command that starts the server after the Inspector:

npx @modelcontextprotocol/inspector node build/index.js

A published npm server and a Python (PyPI) server, from the docs:

npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git

If the server needs an API key, pass it with -e. Anything after -- goes to the server:

npx @modelcontextprotocol/inspector -e KEY=value -- node build/index.js

A remote (HTTP) server

npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

Open the URL it prints

The terminal prints a link with a one-time token in it and opens your browser. Use that link. Don't type localhost:6274 by hand. The token is what stops other things on your machine from using the Inspector to start programs as you.

You can also run it with no server and add servers from the Servers tab. Your list is saved to ~/.mcp-inspector/mcp.json.

What the tabs show

Tab	What you check there
Tools	Each tool's description, input form and annotations. Call a tool and see the result
Resources	Files and data the server offers, read on click
Prompts	Prompt templates and the messages they produce
Protocol	Every JSON-RPC message, in order
Network	HTTP status codes, headers and bodies (remote servers)
Console	The server's own error output (local servers)

Tabs only appear when the server supports them. Apps, Skills, Tasks and Logs show up for servers that use those features.

MCP Inspector CLI: test a server from the terminal

The CLI connects, runs one method, prints the result and exits. Same server commands as above, plus --method:

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

Remote server:

npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com/mcp --method tools/list

The CLI works out the transport from the URL only when the path ends in /mcp (HTTP) or /sse (SSE). Any other URL needs --transport http or --transport sse. If the server wants a key in a header, add it:

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

Call a tool:

npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name mytool --tool-arg key=value

Useful flags, all from the CLI README:

Flag	What it does
--method initialize	A connect-only probe: connects, prints the server's name, protocol version, capabilities and instructions, and exits. The cheapest "is it alive?" check (see the note below the table)
--protocol-era <era>	Which protocol the run speaks: legacy (the default), auto or modern
--format json	One clean JSON object on stdout, ready for jq
--output <file>	Writes the result to a file instead of the screen
--connect-timeout <ms>	How long to wait for the connection (15 seconds by default for a one-off server)
--strict	With tools/list: lists tool schemas some clients will reject, and fails if any are errors
--stored-auth-only	Never opens a browser for OAuth. Use it in CI so a job fails fast instead of hanging

The CLI's exit code tells a script what went wrong: 3 means the server wants sign-in, 4 means it couldn't be reached, 5 means a tool call failed or the tool doesn't exist.

A note on initialize. The 2026-07-28 MCP spec removed the initialize handshake: each request now carries the client's protocol version and capabilities in _meta, and servers describe themselves through a new server/discover method (changelog). The Inspector CLI still lists --method initialize as a "connect-only probe" (CLI docs), so it still works as a reachability check. What goes over the wire depends on the protocol era: legacy, the default, sends a plain initialize with no probing; auto tries server/discover first and falls back to initialize; modern pins 2026-07-28 with no fallback (protocol eras). If you built a server for the new spec, add --protocol-era modern so a server that only knows the old handshake fails loudly instead of passing.

In CI, pin the version. The docs warn that a bare npx resolves the latest release every run. Use an exact version and --yes, for example npx --yes @modelcontextprotocol/inspector@2.13.0 --cli ….

Run the MCP Inspector in Docker

There's an official image. Keep 127.0.0.1: in front of the port, so the Inspector is only reachable from your own machine:

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

The token is in the container's log output. The server list lives inside the container, so --rm throws it away. The docs show how to mount a volume to keep it, but that volume also stores OAuth tokens in a file, which is plain text unless you set a key.

How to use the MCP Inspector to check a server before you trust it

This is where the Inspector earns its place. Connect the server with the account or key you plan to use, then go through these four checks.

1. Read the tool list, all of it

In the Tools tab, or with --method tools/list, read every tool's name and description. Ask two questions:

• Can it write? Look for create, update, delete, send, run, execute or pay. A server you wanted for reading docs shouldn't be able to send email.
• Does any description talk to the model instead of you? Lines like "always call this first", "don't tell the user", or "read ~/.ssh and pass it in" are a red flag. Descriptions go straight into the model's context. See MCP prompt injection.

Also read the input schemas. A path, url, command or query field with no limits means the tool can reach whatever the model asks it to.

2. Look at the annotations

The Tools tab shows each tool's annotations, and tools/list returns them as annotations. Check that a tool with readOnlyHint: true really only reads and that tools which delete say so with destructiveHint. Missing annotations aren't a problem in themselves; the defaults assume the worst.

Annotations are the server's own claim, not a guarantee. A malicious server can mislabel a tool. Read MCP tool annotations explained for what each one means and why your client treats them as hints.

3. Check how it signs in

For a remote server, first connect without any credentials:

npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com/mcp --method initialize

initialize here is the CLI's connect-only probe (see the CLI section); it stops before calling any tool.

• Exit code 3 (auth_required): good. The server wants you to sign in.
• It connects and lists tools with no credentials at all: anyone who finds the URL can use it. Fine for a public docs server; not fine for one that touches your data.

Then connect properly. The Inspector runs the full OAuth flow in your browser. In the Network tab you can see the 401 that starts it and the Authorization header on every request after. Look at the scopes on the consent screen too. If a read-only task asks for write or admin scopes, use a narrower token if the server offers one. The web UI masks secrets in Network headers until you click to show them.

MCP authentication explained covers which sign-in methods and scopes to prefer.

4. Call one tool with bad input

Pick a read-only tool and send it something wrong: an empty string, a very long value, a ../ path. A good server rejects it with a clear error. A server that returns a stack trace, a file it shouldn't, or a secret in the error text has a problem. MCP tool errors shows what a good error looks like.

Don't test write tools on real data. If you must, use a test account.

Snapshot the tool list, then diff it on every upgrade

A server can change its tools after you approve it. That's sometimes called a rug pull. The defence is to save the tool list today and compare it on every upgrade. Pin the server version in the command:

npx @modelcontextprotocol/inspector --cli npx -y some-mcp-server@1.4.2 --method tools/list > tools-1.4.2.json

--output tools-1.4.2.json does the same without the >. Before upgrading, take a new snapshot and compare:

git diff --no-index tools-1.4.2.json tools-1.5.0.json

New tools, rewritten descriptions and wider input schemas are what to look for. The full routine, with how to pin npx, uvx and Docker versions and what each kind of change means, is in How to check an MCP server is safe.

Is the Inspector itself safe to run?

Mostly, if you keep it current and local. Four things to know, all from its own security docs:

• A local server runs as you. Connecting a stdio server means starting it on your machine, with your user's access to your files. The Inspector shows you a server; it doesn't sandbox it. For a server you don't trust yet, the docs suggest running it in a container with no network, for example docker run -i --rm --network none <image> as the server command. A remote server runs no code on your machine.
• Keep it on localhost. It listens on 127.0.0.1 by default and refuses to listen on every network interface unless you opt in. Never set DANGEROUSLY_OMIT_AUTH=true on a machine others can reach: anything that reaches the port could then start programs as you.
• Secrets are stored on disk. OAuth tokens and server API keys go to your OS keychain. With no keychain (headless Linux, SSH sessions, containers with a volume) they go to ~/.mcp-inspector/secrets.json, which is plain text unless you set a key.
• It has had serious bugs. CVE-2025-49596 (critical, fixed in 0.14.1) and CVE-2025-58444 (high, fixed in 0.16.6) let a malicious page or server run commands through older versions. The October 2026 batch was fixed in 2.12.0 and, for the old line, 1.0.3. Update before you point it at a server you don't know.

MCP Inspector errors and fixes

What you see	Usual cause	Fix
An EBADENGINE warning on install, then a confusing failure	Node older than 22.19.0	Upgrade Node, check node -v
Transport type not specified and could not be determined from URL	URL path doesn't end in /mcp or /sse (a trailing / counts)	Add --transport http (or sse)
Connection refused, timeout, CLI exit 4	Server isn't running, wrong port, or localhost means the container when you're in Docker	Start the server, check the port, raise --connect-timeout for slow starts
401, auth_required, CLI exit 3	Server needs sign-in	Add --header, finish OAuth in the browser, or use --stored-auth-only in CI
Local server connects then breaks, or JSON parse errors	The server prints logs to stdout, which carries the protocol	Log to stderr; read it in the Console tab
Page loads but every connect fails with 403	You opened the UI at a different address than the one printed	Use the printed link, or set ALLOWED_ORIGINS if you're behind a proxy
Port 6274 already in use	Another Inspector or app on that port	Close it, or set CLIENT_PORT to another fixed port
CI step fails with exit 5	A tool call returned isError: true (v1 exited 0 here)	Fix the tool, or handle exit 5 in the script
CLI talks to the wrong server	Releases before 2.11 ignored a server command placed after the flags	Upgrade, or put the server command first

Slow tools that time out are a separate problem; see MCP tool call timeouts.

Frequently asked questions

What is the MCP Inspector?

The official developer tool for testing and debugging MCP servers, made by the MCP project. It connects to a server and shows its tools, resources and prompts, lets you call them, and shows the raw messages. It runs as a web UI, a CLI or a terminal UI from one npm package.

How do I install the MCP Inspector?

You don't need to. Run npx @modelcontextprotocol/inspector and npx fetches it. You need Node 22.19.0 or newer. For CI, pin an exact version, such as @modelcontextprotocol/inspector@2.13.0.

Is there an MCP Inspector online?

The official Inspector runs on your own machine; its docs don't describe a hosted version. That's deliberate: it holds your tokens and can start local programs, so it's built to stay on localhost. A remote server can still be checked from your machine with --server-url.

Where is the MCP Inspector on GitHub?

At github.com/modelcontextprotocol/inspector, in the official MCP organisation. The npm package is @modelcontextprotocol/inspector, and the Docker image is ghcr.io/modelcontextprotocol/inspector.

What port does the MCP Inspector use?

The web UI runs on port 6274, on 127.0.0.1 only. Set CLIENT_PORT to use a different port. If a tutorial mentions port 6277, it's describing the old v1 proxy.

Why won't the MCP Inspector connect to my server?

Most often the server isn't running, the port is wrong, or (in Docker) localhost points at the container. For a remote URL that doesn't end in /mcp or /sse, add --transport http. A 403 on every connect means you opened the UI at a different address than the printed link. See MCP Inspector errors and fixes for the full list.

Does the MCP Inspector work with Python servers?

Yes. It speaks the protocol, so the server's language doesn't matter. Pass the command that starts it, for example npx @modelcontextprotocol/inspector uv --directory /path/to/my-server run server.py.

Is it safe to connect a server I don't trust?

A remote server: fairly safe on an up-to-date Inspector (2.12.0 or later). A local stdio server: the Inspector starts it as you, so it can read what you can read. Read its code first, or run it in a container with no network.

Can the Inspector tell me whether a server is safe?

It shows you the facts: tools, descriptions, annotations, sign-in. You still make the call. How TrustedMCP grades servers covers the public signals (maintenance, CVEs, auth, transport), and the MCP server directory lists every graded server. Building your own? Start with how to create an MCP server securely.

More: Is this MCP server safe to install? · MCP security best practices · MCP tool annotations · Filesystem MCP server