Testing and Debugging with MCP Inspector

What MCP Inspector Is

MCP Inspector is a browser-based visual testing tool for MCP servers, built and maintained by Anthropic alongside the SDK. It connects to your server, displays all its capabilities, and lets you call every tool, read every resource, and invoke every prompt interactively — without needing Claude Desktop at all.

Inspector is the first tool to reach for when something is not working. Use it to verify your server is correct before you ever touch Claude Desktop config. It eliminates the guesswork of "is the problem in my server or in the client?"

Starting Inspector

No installation required. Run it with npx:

npx @modelcontextprotocol/inspector

This opens a browser window at http://localhost:5173. From there, you connect to your server by entering the command that launches it.

For a stdio server built with Node.js:

Command: node
Arguments: /absolute/path/to/build/index.js

For a Python FastMCP server:

Command: python
Arguments: /absolute/path/to/server.py

Inspector launches your server as a child process, connects via stdio, performs the MCP initialization handshake, and populates the UI with everything your server advertises.

Python Shortcut: mcp dev

If you're using the Python MCP SDK, there's a single command that starts both your server and Inspector simultaneously:

python -m mcp dev server.py

This is the fastest way to get into a test loop during development. Edit server.py, stop the session, re-run mcp dev, and your changes are live in Inspector immediately.

The Inspector UI: Five Tabs

Once connected, Inspector shows five tabs across the top.

Tools — lists every tool your server registered. Click a tool to expand its input schema, fill in values as JSON, hit "Call", and see the full response. The response includes the content array and an isError flag. Test both valid inputs and invalid inputs to verify your error handling.

Resources — lists static resources from resources/list and URI templates from resources/templates/list. For static resources, click "Read" to fetch the content. For templates, fill in the placeholder values to build the URI, then read it.

Prompts — lists all prompts from prompts/list. Click a prompt, fill in its arguments, and click "Get Prompt" to see the exact messages array your server returns. This is the fastest way to verify the message structure is correct before testing in Claude Desktop.

Notifications — shows any server-sent notifications and logging messages. If your server emits log notifications (using the MCP logging primitive), they appear here in real time.

JSON-RPC — the raw message stream. Every request your client sends and every response your server returns appears here in full JSON, including the initialization handshake. This is where protocol-level debugging happens.

The JSON-RPC Tab: Your Best Debugging Tool

When something is not working, open the JSON-RPC tab first. You will see:

1. The initialize request from the client and your server's initialize response — verify capabilities lists the primitives you expect
2. The tools/list, resources/list, and prompts/list requests and responses — verify your items appear with correct names and schemas
3. Every tool call request and response — check result.isError and result.content

A malformed JSON response, a missing field, or an unhandled exception will show up as a JSON-RPC error object here with an error code and message. This is far more informative than the generic errors Claude Desktop shows in its UI.

Environment Variables in Inspector

Many servers require environment variables (API keys, database URLs, config flags). Inspector has an Env panel in the connection settings where you can inject key-value pairs before connecting. These are passed to your server process's environment, just as they would be in a real deployment.

This means you can test your server with different API keys or configurations without modifying your code or shell environment. Add DATABASE_URL, API_KEY, or any other variable your server reads via process.env or os.environ.

CLI Mode for Automated Testing

Inspector includes a --cli flag that skips the browser UI and lets you call tools from the command line. This is useful for automated tests or CI/CD pipelines:

npx @modelcontextprotocol/inspector --cli node build/index.js 
  --tool get_alerts 
  --tool-arg state=CA

The CLI mode outputs the tool response as JSON to stdout, so you can pipe it into jq or compare it against expected output in a test script. Combine it with your existing test runner to catch regressions before deploying server changes.

A Systematic Debugging Workflow

Follow this sequence whenever something is not working:

1. Start with Inspector — connect to your server and check that it starts without errors. Look at the JSON-RPC tab to verify the initialize response has the expected capabilities.
2. Check the capability lists — verify your tools, resources, and prompts all appear with correct names, descriptions, and schemas.
3. Test with valid inputs — call each tool with a known-good input and verify the response content is correct.
4. Test with invalid inputs — call tools with missing required fields, wrong types, and out-of-range values. Verify your error handling returns informative messages rather than crashing.
5. Read the JSON-RPC stream — for any unexpected behavior, find the specific request/response pair and inspect the raw JSON.
6. Check stderr — Inspector shows your server's stderr output in the terminal pane. Python tracebacks and Node.js stack traces appear here.
7. Only then connect to Claude Desktop — once Inspector shows everything working correctly, add the server to Claude Desktop config and restart.

Common Issues Inspector Catches

Tool not appearing — open the JSON-RPC tab and find the tools/list response. If your tool is missing, check that registerTool (TypeScript) or @mcp.tool() (Python) is being called before server.connect().

Tool call returns an error — check the isError flag in the response and read the content[0].text error message. Common causes: unhandled exception in the handler, missing environment variable, failed external API call.

Server crash on startup — the Inspector terminal pane shows stderr. Python import errors, missing dependencies, and syntax errors all appear here immediately.

Schema validation failure — Inspector validates your input against the tool's schema before calling it and shows validation errors inline, before the request is even sent. This catches type mismatches and missing required fields instantly.

Resource not returning content — use the Resources tab to read the resource directly and check the raw response. Verify the uri in the response matches what you sent in the request.

Claude Desktop Log Files

After you've verified your server with Inspector and moved to Claude Desktop, use the log files for debugging connection issues:

• macOS: ~/Library/Logs/Claude/mcp-server-<name>.log
• Windows: %APPDATA%Claudelogsmcp-server-<name>.log

Replace <name> with the key you used in claude_desktop_config.json. These logs capture your server's stderr output when Claude Desktop launches it. If the server works in Inspector but not in Claude Desktop, the log almost always reveals the problem: wrong path, missing environment variable, or permission error.

The most common root cause when a server works in Inspector but fails in Claude Desktop: the command path in the config is wrong, or the server was not rebuilt after the last code change. Always use absolute paths and always rebuild before restarting Claude Desktop.

What to Try Next

Run Inspector against the weather server you built in lesson 6 (or any server you have available):

1. Connect Inspector, open the JSON-RPC tab, and read the full initialization handshake to understand what capability negotiation looks like at the protocol level
2. Call get_alerts with a valid state code, then call it with an empty string — observe how the error response differs from a successful response
3. Add --cli mode to your workflow: run a tool call from the command line and pipe the output to jq to extract just the text content