MCP Inspector: Debug Your MCP Servers Like a Pro

Introduction

Building an MCP server is exciting — until something breaks and you have no idea why. Maybe your tool is returning the wrong schema, a resource isn’t being discovered, or your prompt template is silently failing. The challenge with debugging Model Context Protocol servers is that they communicate over stdio or HTTP using JSON-RPC 2.0 messages, which aren’t exactly human-readable in a terminal.

This is exactly the gap the MCP Inspector was built to fill. Maintained by the Model Context Protocol team at Anthropic, it’s the official interactive developer tool for testing and debugging MCP servers — think of it as the Postman of the MCP world. It gives you a live, browser-based window into your server’s behaviour: tools, resources, prompts, protocol handshakes, and all the JSON flowing between client and server.

In this guide you’ll learn how to get MCP Inspector running in minutes, explore every panel in the UI, use CLI mode for scripting and CI pipelines, understand the security model (including a critical CVE from 2025), and build a debugging workflow that actually saves time.

Architecture: How MCP Inspector Actually Works

Before diving into features, it helps to understand what you’re running. MCP Inspector is not a single process — it’s a two-component system.

MCPI (MCP Inspector Client) is the React-based web UI you interact with in the browser. MCPP (MCP Proxy) is a Node.js server that does the actual work: it connects to your MCP server using whatever transport your server speaks (stdio, Server-Sent Events, or Streamable HTTP), while simultaneously acting as an HTTP server that the browser UI can talk to.

The port numbers are a neat mnemonic: T9 dialpad mapping of “MCPI” = 6274, and “MCPP” = 6277.

Getting Started in Under Two Minutes

The fastest path is zero-install via npx:

# Start the UI with no server attached yet
npx @modelcontextprotocol/inspector

The UI opens automatically at http://localhost:6274 with a session token pre-filled in the URL. To connect directly to a server:

# TypeScript / Node.js server
npx @modelcontextprotocol/inspector node build/index.js

# Python server via uv
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/myrepo

# With environment variables passed to the server
npx @modelcontextprotocol/inspector -e API_KEY=your-key -e DEBUG=true node build/index.js

# Use -- to separate inspector flags from server flags
npx @modelcontextprotocol/inspector -e LOG_LEVEL=debug -- node build/index.js --port 8080

Need to use custom ports? Set them via environment variables before the command:

CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node build/index.js

Docker

If you prefer containers or want full isolation when testing untrusted servers:

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

Feature Deep-Dive: Every Panel Explained

Transport Types and Config Files

MCP Inspector supports all three MCP transport types. Which one you use depends on your server’s architecture:

For teams working across multiple servers, config files eliminate repetitive CLI flags:

{
  "mcpServers": {
    "my-api-server": {
      "command": "node",
      "args": ["build/index.js"],
      "env": {
        "DATABASE_URL": "postgres://localhost/mydb",
        "LOG_LEVEL": "debug"
      }
    },
    "remote-staging": {
      "type": "streamable-http",
      "url": "https://staging.example.com/mcp"
    }
  }
}

# Launch with a specific server from the config
npx @modelcontextprotocol/inspector --config mcp.json --server my-api-server

If the config has a single server or one named default-server, the --server flag can be omitted and it auto-selects.

CLI Mode: Automating Your Test Workflow

The UI is great for interactive debugging. CLI mode is for everything else: scripting, CI pipelines, and creating tight feedback loops with AI coding assistants like Claude Code.

# Launch in CLI mode
npx @modelcontextprotocol/inspector --cli node build/index.js

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

# Call a specific tool with arguments
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call \
  --tool-name search_documents \
  --tool-arg query="MCP protocol" \
  --tool-arg max_results=5

# Call a tool with a complex JSON argument
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call \
  --tool-name create_task \
  --tool-arg 'options={"priority": "high", "labels": ["bug", "urgent"]}'

# List 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

# Connect to a remote server with auth
npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com \
  --transport http \
  --method tools/list \
  --header "Authorization: Bearer your-token"

Here’s a comparison to help choose the right mode for the task:

Exporting Server Configurations

One of Inspector’s practical quality-of-life features is exporting your server configuration into formats compatible with Claude Code, Cursor, and other MCP-capable clients. After connecting to a server, two buttons appear in the sidebar:

Server Entry copies a single server block to your clipboard, ready to paste into an existing mcp.json:

{
  "command": "node",
  "args": ["build/index.js", "--production"],
  "env": {
    "API_KEY": "your-api-key"
  }
}

Servers File copies a complete mcp.json structure that you can save directly to disk and use immediately. This eliminates the need to hand-author configuration files during development.

Timeout and Configuration Settings

The Inspector UI exposes a Configuration panel (click the button in the sidebar) with several important settings that persist across sessions:

Security: What You Must Know

MCP Inspector’s proxy can spawn local processes and connect to arbitrary servers. This makes its security model critically important.

Authentication (Default: On)

When the proxy starts, it generates a random session token and prints it to the console:

🔑 Session token: 3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4

🔗 Open inspector with token pre-filled:
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=3a1c267...

The browser opens automatically with the token pre-filled. All proxy requests require this token as a Bearer token in the Authorization header. The token is saved in browser local storage for future sessions.

CVE-2025-49596: The Critical RCE

In June 2025, Oligo Security reported a critical Remote Code Execution vulnerability — CVE-2025-49596 with a CVSS score of 9.4 — affecting all Inspector versions below 0.14.1.

The flaw arose because the MCP Proxy accepted arbitrary stdio commands without authenticating or validating the source of requests from its browser client. When a victim visited a malicious website, the vulnerability allowed attackers to run arbitrary code on the host machine running MCP Inspector, without being on the same network.

Anthropic addressed CVE-2025-49596 with the release of version 0.14.1 on June 13, 2025. The fix introduced session tokens for all proxy requests and validates Host and Origin headers to block CSRF and DNS rebinding attacks.

Additional Security Posture

By default, Inspector binds only to localhost, preventing access from other devices on your network. DNS rebinding protection validates the Origin header on incoming requests. If you need to expose Inspector across a network (e.g., for a remote team member), use the HOST=0.0.0.0 and ALLOWED_ORIGINS variables only in trusted, isolated network environments.

When testing third-party or untrusted MCP servers, running Inspector inside a Docker container is the safest approach — it limits what a malicious server could do to your host system.

A Practical Debugging Workflow

Quick Reference: Common CLI Commands

# Zero-install UI startup
npx @modelcontextprotocol/inspector

# Inspect a locally built TypeScript server
npx @modelcontextprotocol/inspector node build/index.js

# Inspect a Python server
npx @modelcontextprotocol/inspector uv --directory ./my-server run my-server

# Inspect an npm package server (e.g. filesystem server)
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop

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

# CLI: call a tool
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call \
  --tool-name my_tool \
  --tool-arg param=value

# CLI: use a config file
npx @modelcontextprotocol/inspector --cli --config mcp.json --server my-server

# Custom ports
CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node build/index.js

# Check your installed version
npm list -g @modelcontextprotocol/inspector

Conclusion

MCP Inspector removes one of the biggest pain points in MCP server development: the opaque nature of JSON-RPC communication. Instead of printf-debugging your way through protocol messages, you get a browser UI that shows you exactly what your server is advertising and exactly what it returns.

The key mental model to keep: Inspector is a test client, not a wire tap. Use it during development to validate schemas, test tool calls, and catch protocol errors early. Pair CLI mode with your normal build loop or CI pipeline for regression coverage. And when you’re ready to connect Claude Code, Cursor, or Claude Desktop, use Inspector’s built-in config export to generate your mcp.json in one click.

References:

1. MCP Inspector GitHub Repository — Official source, README, architecture, CLI reference, and security advisories
2. MCP Inspector — Official Documentation — Feature overview and best practices from the MCP docs site
3. CVE-2025-49596: Critical RCE in MCP Inspector (Oligo Security) — Full technical disclosure of the RCE vulnerability and the 0.14.1 fix
4. MCP Inspector Testing & Debugging Guide (Stainless) — Practical debugging techniques and workflow patterns
5. Debugging MCP Servers: Tips and Best Practices (mcpevals.io) — Logging strategies, common error categories, and protocol debugging patterns