MCP Inspector: How to Test and Debug Any MCP Server

MCP Inspector is the official interactive developer tool for testing and debugging Model Context Protocol servers, maintained in the modelcontextprotocol/inspector repository and run with a single command: npx @modelcontextprotocol/inspector. It gives you a browser UI at localhost:6274 where you can connect to any MCP server, list its tools, resources, and prompts, call them with custom inputs, and watch the raw protocol messages, all without wiring the server into a full AI client first. This guide covers installing and running the Inspector, the debugging workflows that matter, CLI mode for scripting, and the security settings you should not touch, verified against the official docs as of July 2026.

What MCP Inspector Is

MCP Inspector is the Model Context Protocol project's own testing client: a visual tool that speaks MCP so you can exercise a server's capabilities directly instead of guessing why Claude Code or another client is not seeing your tools. Think of it as the Postman of the MCP world. The official Inspector documentation positions it as the first stop in the MCP debugging toolkit, and the current release is v0.22.0, published June 4, 2026.

You need it in three situations: you are building a server and want to test tools before connecting a real client (our build-your-own MCP server guide uses it at every step), you are evaluating a third-party server before granting it access to your agent, or a server that works elsewhere fails inside a client and you need to isolate whether the bug is in the server or the client configuration.

Install and Run With npx

The Inspector runs directly through npx with no installation, provided you have Node.js ^22.7.5. Pass the command that starts your server as arguments:

# Launch the Inspector UI (browser opens at http://localhost:6274)
npx @modelcontextprotocol/inspector

# Inspect a server, passing its launch command
npx @modelcontextprotocol/inspector node build/index.js

# With server arguments
npx @modelcontextprotocol/inspector node build/index.js --port 3000

On startup, the proxy prints a session URL containing a one-time token; open that URL rather than the bare localhost address so the browser is authorized automatically. A Docker image also exists (ghcr.io/modelcontextprotocol/inspector) if you prefer not to run Node directly. For remote servers, open the UI with no command, pick SSE or streamable HTTP in the connection pane, and enter the server URL.

Architecture: Ports, Proxy, and Auth Token

The Inspector is two cooperating processes: the MCP Inspector Client, a React web UI served on port 6274, and the MCP Proxy, a Node.js bridge on port 6277 that acts as an MCP client toward your server and an HTTP server toward the browser. This split is what lets a browser page talk to a stdio-based server process: the proxy spawns and manages your server, translating between the browser and whichever transport the server speaks (stdio, SSE, or streamable HTTP).

Security is baked in by default. Both ports bind to localhost only, the proxy generates a random session token on every startup and requires it as a Bearer token on all requests, and DNS rebinding protection is configurable via ALLOWED_ORIGINS. Ports and bind address are adjustable with CLIENT_PORT, SERVER_PORT, and HOST environment variables, and slow servers get headroom via the request timeout setting (default 300,000 ms). Remember that the proxy can launch arbitrary local processes; treat it as a development tool on a development machine.

Debugging an MCP Server: The Core Workflow

The Inspector organizes a server's surface into tabs that map one-to-one onto MCP capabilities, and an effective debugging session walks them in order:

• Connection pane: choose the transport, set command-line arguments and environment variables for local servers, and verify the handshake. If capability negotiation fails here, nothing else matters yet.
• Tools tab: lists every tool with its schema and description, and lets you call each one with custom inputs and see the execution result. This is where you catch schema mistakes, missing required fields, and unhelpful descriptions that will confuse an agent later.
• Resources tab: lists available resources with MIME types and metadata, lets you inspect content, and supports subscription testing.
• Prompts tab: shows prompt templates with their arguments and previews the generated messages.
• Notifications pane: presents server logs and notifications, which is usually where the actual error message lives when a tool call fails silently.

The official docs recommend an iterate-and-reconnect loop: launch the Inspector, verify connectivity, make server changes, rebuild, reconnect, retest the affected feature, then deliberately test edge cases (invalid inputs, missing prompt arguments, concurrent operations) to confirm the error responses are sane. When everything passes, the UI's export buttons hand you a ready-made mcp.json server entry to paste into a client config; from there, our Claude Code MCP guide covers installation on the client side.

Inspecting npm, PyPI, and Local Servers

The Inspector can launch any server it can reach a command for, which covers the three common cases:

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

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

# A local Python server in development
npx @modelcontextprotocol/inspector uv --directory path/to/server run package-name

This makes the Inspector a vetting tool, not just a development tool: before you add any of the servers from our best MCP servers roundup to a production agent, you can run them in the Inspector and see exactly which tools they expose and what each call actually returns. Pair that with our free MCP security scanner, which checks a server config for permission and exposure issues, and with the hardening steps in securing your MCP server connections.

CLI Mode and Config Files

CLI mode runs the same checks without a browser, which makes the Inspector scriptable for CI pipelines and smoke tests. Add the --cli flag with your server command, and use method flags to list or call capabilities programmatically:

# Programmatic interaction with a local server
npx @modelcontextprotocol/inspector --cli node build/index.js

# Drive a server defined in a config file
npx @modelcontextprotocol/inspector --config mcp.json --server myserver

The --config flag accepts a standard multi-server configuration file and --server selects which entry to launch; if the file has one server, or one named default-server, the Inspector picks it automatically. A practical pattern for server authors: run UI mode while developing, then encode the calls that matter into CLI-mode invocations that run on every commit, so a broken tool schema fails the build instead of surfacing when an agent misbehaves in production.

Limitations and Security Notes

MCP Inspector tests protocol correctness, not agent behavior: a server can pass every Inspector check and still perform badly with a real model because its tool descriptions are ambiguous or its results are too verbose for a context window. It also does not evaluate whether a server is safe to trust; it will happily connect to a malicious server and show you its tools. Three security rules from the maintainers and the official debugging guide: never set DANGEROUSLY_OMIT_AUTH=true (the repository calls disabling auth "incredibly dangerous," since a malicious website could drive your proxy and, through it, execute local processes), keep both ports bound to localhost unless you fully understand the exposure, and treat any server you inspect as untrusted code, because the proxy launches it on your machine. Finally, the tool moves fast and minor versions occasionally change flags; when something behaves unexpectedly, check the README for the release you are actually running.

Related Guides

• How to Build Your Own MCP Server
• Best MCP Servers in 2026: The Complete Ranked List
• Claude Code MCP: How to Add and Manage MCP Servers
• Securing Your MCP Server Connections