MCP Inspector - Debug Model Context Protocol Servers Cheatsheet
MCP Inspector is the official visual testing and debugging tool for Model Context Protocol servers. When you are building an MCP server, you need to see what it actually exposes and how it responds — Inspector connects to your server, lists its tools, resources, and prompts, lets you invoke each one with arbitrary arguments, and shows the raw JSON-RPC messages flowing in both directions. It is the fastest way to verify a server works before wiring it into Claude, Cursor, or another client.
Running It
| Method | Command |
|---|
| npx (no install) | npx @modelcontextprotocol/inspector |
| With your server | npx @modelcontextprotocol/inspector node build/index.js |
| Python server | npx @modelcontextprotocol/inspector uv run server.py |
| Remote/SSE server | launch, then enter the URL in the UI |
| UI | opens in the browser (default http://localhost:6274) |
Connection Types
| Transport | Use |
|---|
| STDIO | Local server run as a subprocess (most common) |
| SSE | Remote server over Server-Sent Events |
| Streamable HTTP | Modern remote transport |
# Inspect a local stdio server, passing args and env
npx @modelcontextprotocol/inspector \
-e API_KEY=abc123 \
node build/index.js --verbose
The Interface
| Tab | Shows |
|---|
| Tools | Every tool, its JSON schema, and a form to call it |
| Resources | Exposed resources and their contents |
| Prompts | Prompt templates and their arguments |
| Notifications | Server-initiated messages/logs |
| History | Every request/response pair |
| Step | Action |
|---|
| 1 | Open the Tools tab; confirm your tool is listed |
| 2 | Check the input schema renders correctly (types, required fields) |
| 3 | Fill the generated form and click to invoke |
| 4 | Inspect the returned content and any isError flag |
| 5 | Read the raw JSON-RPC in History to debug shape issues |
This loop catches the most common MCP bugs: a malformed schema, a tool that returns the wrong content shape, or an unhandled error.
What to Verify Before Shipping
| Check | Why |
|---|
| Tool names are unique/descriptive | Clients surface them to the model |
| Descriptions explain when to use the tool | Drives correct model selection |
| Input schema is precise | Prevents malformed calls |
Errors return isError with a message | Model can recover |
| Large outputs are paginated/truncated | Avoids blowing the context window |
| Resources have stable URIs | Clients cache/reference them |
Debugging Tips
| Symptom | Look at |
|---|
| Server won’t connect | Command/args; stderr in the launching terminal |
| Tool missing | Registration code; restart the server |
| Schema renders oddly | JSON Schema types in the tool definition |
| Client behaves differently | Compare raw JSON-RPC in History |
| Env-dependent bug | Re-launch Inspector with -e KEY=value |
Common Workflows
# Develop-and-test loop for a TypeScript MCP server
npm run build && npx @modelcontextprotocol/inspector node build/index.js
# Test a Python server with uv
npx @modelcontextprotocol/inspector uv run my_server.py
# Verify a remote SSE server before adding it to a client
npx @modelcontextprotocol/inspector # choose SSE, paste the URL
MCP Inspector vs Alternatives
| Approach | Trade-off |
|---|
| MCP Inspector | Purpose-built, visual, shows raw protocol |
| Wiring into a real client | Realistic but slow feedback loop |
| Hand-written JSON-RPC | Full control, tedious |
| Unit tests | Fast and repeatable; pair with Inspector for exploration |
Use Inspector while building, then add automated tests; see MCP servers for server implementation patterns.
Resources
