MCP Inspector: Debug Any MCP Server in Minutes (2026)

When an MCP server won't connect, Claude Code tells you almost nothing. MCP Inspector is the official tool for finding out what actually went wrong, it runs the server in isolation and shows you every tool, resource, and error.

Quick Answer: Run npx @modelcontextprotocol/inspector followed by your server command. It opens a local web UI where you can list the server's tools and resources, call them with your own arguments, and read the raw protocol messages. Use it before wiring a server into Claude Code, not after.

Launching the Inspector

Point it at the command that starts your server:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /Users/you/projects

For a server you're building:

npx @modelcontextprotocol/inspector node build/index.js

For a Python server:

npx @modelcontextprotocol/inspector uv run server.py

The Inspector starts a proxy and opens a browser tab. If the server crashes on startup, you see the stderr output immediately rather than a silent failure inside Claude Code.

What this gets you: the server running in isolation, with nothing else in the way.

Recommended skills

diagnosing-rag-failure-modes

by https://loreto.io · 5

RAG fails quietly. It retrieves documents, returns confident-looking answers, an…

$10

Multi Agent Coordinator

by Roy Yuen

Coordinate specialized AI agent roles for complex planning, implementation, and…

$7

env-doctor

by Samuel Rose · 155

Diagnoses why your project will not start. Checks runtime versions, dependencies…

Free

Browse all MCP skills

Reading the Tools tab

The Tools tab lists every tool the server exposes, with its input schema. This is the single most useful screen for debugging.

Check three things:

The tool appears at all. If it's missing, your server isn't registering it, the problem is in your code, not your Claude config.

The description is specific. Tool descriptions are what the model uses to decide when to call something. "Query the database" is too vague. "Run a read-only SQL query against the production Postgres instance. Returns up to 100 rows." is not.

The input schema matches what you expect. Wrong types and missing required fields cause silent failures where the model calls the tool with arguments the server rejects.

You can call any tool directly from this tab with your own arguments and see the raw response. That separates "the server is broken" from "the model is calling it wrong."

Why this matters: most MCP problems are description or schema problems, and both are visible here in seconds.

Reading the Resources and Prompts tabs

Resources are read-only data the server exposes, files, records, documents. The tab lists their URIs and lets you fetch one to see exactly what content comes back.

Prompts are reusable templates the server offers. Less commonly used, but if your server defines them, this is where you verify the arguments resolve correctly.

Finding connection failures

The Inspector shows the raw JSON-RPC messages between client and server. Three failures show up clearly here.

The server writes to stdout. MCP uses stdout for protocol messages, so any print() or console.log() in your server corrupts the stream. Log to stderr instead.

Environment variables aren't reaching the process. If your server needs an API key and it isn't set, the Inspector surfaces the error immediately.

The command path is wrong. A typo in the binary path produces a spawn error the Inspector reports directly, where Claude Code would just show the server as unavailable.

What this saves you: the guessing loop of editing config, restarting Claude Code, and checking whether anything changed.

Where skills fit

The Inspector verifies a server works. It doesn't verify the agent will use it well.

A working Postgres server plus no guidance means the model improvises queries. Add a skill defining your conventions and the same server produces consistent output. Debug the connection with the Inspector, then shape the behaviour with a skill.

Browse skills on Agensi.

The debugging sequence

1. Run the Inspector against your server command
2. Confirm the server starts without stderr errors
3. Open the Tools tab and confirm every expected tool is listed
4. Call one tool manually with real arguments
5. Only then add the server to ~/.claude.json and restart Claude Code

If it works in the Inspector and fails in Claude Code, the problem is your config file, not the server.

For building your own server, read How to Build an MCP Server That Serves SKILL.md Skills.