Published March 30, 2026

MCP Inspector CLI Tutorial: Debug and Test Your MCP Servers in 2026

Building an MCP server is one thing. Making sure it actually works — correctly, reliably, and without cryptic errors — is another. That is where the MCP Inspector CLI comes in. This official Anthropic tool is the fastest way to test-drive any MCP server, inspect its capabilities, and debug issues before connecting it to your AI host. In this guide, you will learn everything you need to go from zero to confident debug session.

mcp inspectormcp climcp debuggingmcp server testmodel context protocol

What Is MCP Inspector and Why Do You Need It?

The MCP Inspector CLI is an official command-line tool released by Anthropic that lets you interact with any MCP server directly — no AI client required. You pass it a server command, and it opens an interactive session where you can call tools, inspect resources, and read server responses in real time.

Think of it as a Postman for MCP servers. Before you trust a server with your AI workflow, you want to verify it handles requests correctly, returns the right schema, and does not throw unexpected errors. MCP Inspector gives you that confidence without the overhead of a full AI host setup.

Here is when MCP Inspector becomes essential:

Validating a new server — Confirm it loads, advertises the right tools, and responds correctly before connecting it to Claude or Cursor.
Debugging failures — When a server works in one host but not another, Inspector strips away the host layer to isolate the problem.
Schema verification — Inspect exactly what tools, resources, and prompts a server exposes before writing any integration code.
CI/CD validation — You can script Inspector calls to validate servers automatically in your deployment pipeline.

Installation and Requirements

MCP Inspector is distributed as an npm package and runs via npx, so you do not need to install it globally. The only hard requirement is Node.js 18 or later.

Prerequisites

Node.js 18+ — Check your version with node --version
npm or npx — Bundled with Node.js; verify with npx --version

Installation Command

No separate install step. Just run the following to launch Inspector with a server:

npx @anthropic-ai/mcp-inspector --server-command "node /path/to/your/server.js"

Replace the server command with whatever runs your specific MCP server (e.g., python server.py, ./your-server-binary, etc.)

If you want to install it globally for convenience:

npm install -g @anthropic-ai/mcp-inspector

Basic Usage: Testing an MCP Server Step by Step

Let us walk through a complete test session. We will use a fictional MCP server called example-mcp-server that exposes a file browsing tool. The same steps apply to any server.

Step 1: Launch the Inspector

Run the following in your terminal:

npx @anthropic-ai/mcp-inspector --server-command "node ./example-mcp-server.js"

Inspector will start, connect to your server, and print the server manifest — a list of all available tools, resources, and prompts.

Step 2: Read the Server Manifest

On launch, Inspector displays a manifest like this:

✓ Connected to example-mcp-server
Manifest:
  tools:
    - browse_files(path: string, recursive?: boolean): FileTree
    - read_file(path: string, start?: number, end?: number): string
  resources:
    - file:/// (root directory)
  prompts:
    - summarize_project: Summarizes the project structure

Review this carefully. If a tool you expected is missing, the server may not be registering it correctly — a good first clue for debugging.

Step 3: Call a Tool

In the Inspector prompt, type a tool call in the following format:

> tool: browse_files
> arguments: { "path": "/Users/me/projects", "recursive": true }

Inspector sends the request to the server and prints the raw JSON response. This is exactly what your AI host will receive — so you can verify the response shape matches what your integration expects.

Step 4: Inspect Multiple Tools in Sequence

Keep calling tools to build confidence in the server. Try error cases too:

> tool: read_file
> arguments: { "path": "/nonexistent/file.txt" }

Does it return a clean error? Or does it crash? You want clean, structured errors — not unhandled exceptions bubbling up.

Reading Server Response Logs

One of MCP Inspector\'s most valuable features is its verbose logging mode. By default, Inspector shows you tool calls and responses. With verbose mode enabled, you also see every JSON-RPC message going over the wire.

Enable verbose logging with the --verbose flag:

npx @anthropic-ai/mcp-inspector \
  --server-command "node ./example-mcp-server.js" \
  --verbose

Verbose output reveals the full request/response cycle:

Request ID — Correlate responses to specific calls.
Timestamps — Spot latency between request and response.
Full JSON payloads — Inspect exact schemas passed between client and server.
Error objects — See structured error codes and messages vs. raw stack traces.

For a production deployment workflow, consider using MCPize to host your server — it captures server-side logs while you use Inspector for client-side validation. Together they give you full observability.

Common Error Messages and How to Fix Them

MCP servers fail in predictable ways. Here are the most common errors you will encounter in Inspector, and what to do about them.

Error: Server process exited with code 1

Likely cause: The server command crashed on startup. Often a missing dependency or syntax error.

Fix: Run the server command directly in your terminal (outside Inspector) to see the full error output. Common fixes: npm install, check Node/Python version, verify file paths.

Error: Cannot connect to server — ECONNREFUSED

Likely cause: The server is not listening on the expected port or Unix socket.

Fix: Verify the server's --port flag matches what Inspector expects. Some servers use stdin/stdout by default instead of a network port.

Error: Method not found — tool "X" does not exist

Likely cause: The tool name in your call does not match the manifest. Likely a typo or version mismatch.

Fix: Re-check the manifest Inspector printed on startup. Tool names are case-sensitive.

Error: Invalid JSON in server response

Likely cause: The server returned malformed JSON. Usually a logging statement mixed into stdout.

Fix: Server debug output (console.log) and MCP protocol messages both go to stdout. Redirect debug logs to stderr so they do not corrupt the JSON stream.

Error: Timeout waiting for server response

Likely cause: The server took too long to respond. Could be a slow query, network issue, or an infinite loop in the handler.

Fix: Test the underlying operation outside MCP (e.g., run the SQL query directly). If it is genuinely slow, add a timeout parameter to the tool definition.

Advanced Tips

Custom Ports and Transport Modes

By default, MCP Inspector and servers communicate over stdin/stdout using JSON-RPC over stdio transport. Some servers expose HTTP endpoints. You can specify the transport mode:

# Stdio transport (default)
npx @anthropic-ai/mcp-inspector --server-command "node server.js"

# HTTP/SSE transport (if server exposes an endpoint)
npx @anthropic-ai/mcp-inspector --server-url "http://localhost:3000/mcp"

# Custom port for HTTP servers
npx @anthropic-ai/mcp-inspector --server-url "http://localhost:8080/mcp" --port 8080

Verbose Mode for Deep Debugging

As mentioned earlier, --verbose shows every JSON-RPC message. For even more detail, combine it with a log file:

npx @anthropic-ai/mcp-inspector \
  --server-command "node server.js" \
  --verbose \
  2>&1 | tee inspector-debug.log

This pipes all output (including verbose JSON-RPC messages) to both the terminal and a log file for later review.

Testing a Specific Server Build

If you have multiple versions of a server (e.g., staging vs. production), test each one:

# Test staging build
npx @anthropic-ai/mcp-inspector --server-command "node ./dist/staging/server.js"

# Test production build
npx @anthropic-ai/mcp-inspector --server-command "node ./dist/prod/server.js"

Compare the manifests between versions to catch capability regressions before deploying.

Environment Variables

Pass environment variables through to the server using your shell:

API_KEY=sk-test-123 npx @anthropic-ai/mcp-inspector \
  --server-command "node server.js"

Useful for testing servers that require API keys or other secrets without hardcoding them into your server code.

MCP Inspector vs. Testing Directly in Your AI Host

A natural question arises: why not just test in Claude Desktop or Cursor? The answer comes down to isolation and speed.

When you test directly in an AI host, the MCP server interacts with the full AI pipeline — including the model, the host\'s tool-calling logic, and prompt construction. If something goes wrong, you have to untangle all of those layers. MCP Inspector removes the AI model entirely. You are testing only the server and the protocol.

Scenario	Use Inspector?	Why
New server, first validation	✓ Yes	Fast, no AI host needed. Spot obvious issues instantly.
Debugging tool response format	✓ Yes	See exact JSON response without model interference.
Testing end-to-end AI workflow	⚠ Partial	Use Inspector first for schema; then test in host for UX.
Verifying error handling in context	⚠ Partial	Inspector shows raw errors; AI host shows how the model handles them.
CI/CD pipeline validation	✓ Yes	Scriptable. Combine with assert statements on manifest and tool responses.

For the fastest development loop, use Raycast as your AI productivity hub — it has solid MCP support and pairs well with Inspector for a tight local development workflow.

Quick Reference / Cheat Sheet

Launch Commands

# Basic launch (stdio transport)
npx @anthropic-ai/mcp-inspector --server-command "node server.js"

# With verbose logging
npx @anthropic-ai/mcp-inspector --server-command "node server.js" --verbose

# HTTP/SSE server
npx @anthropic-ai/mcp-inspector --server-url "http://localhost:3000/mcp"

# Custom port
npx @anthropic-ai/mcp-inspector --server-url "http://localhost:8080/mcp" --port 8080

# With environment variables
API_KEY=sk-xxx npx @anthropic-ai/mcp-inspector --server-command "node server.js"

# Global install
npm install -g @anthropic-ai/mcp-inspector
mcp-inspector --server-command "node server.js"

Inspector Prompt Commands

# Call a tool
> tool: tool_name
> arguments: { "param": "value" }

# List available tools
> list

# Exit Inspector
> exit

# Toggle verbose output (while running)
> verbose on
> verbose off

Common Issues

Server exit code 1 → Run server directly to see error
ECONNREFUSED → Check port / transport mode matches
Method not found → Verify tool name in manifest (case-sensitive)
Invalid JSON → Redirect debug logs (console.log) to stderr
Timeout → Test underlying operation separately; add timeouts to tool def

Requirements

Node.js 18 or later
npm/npx (bundled with Node.js)
No global install required — runs via npx