Use MCP Inspector to debug and test tools without needing Claude Desktop.
The MCP Inspector is the official debugging tool for MCP servers. It’s a web interface that connects to your server and lets you view all registered tools, resources, and prompts, run tools manually with custom parameters, and inspect responses — all without needing Claude Desktop.
O MCP Inspector acts as a visual MCP client. It starts your server, establishes a connection via STDIO, and presents an interactive web interface where you can: see the complete list of tools (with descriptions and parameters), resources (with URIs and types) and prompts (with arguments). You can run any tool by filling in the parameters in the interface and see the formatted response in real time. This is essential during development.
The Inspector is maintained by the official MCP team in the repository modelcontextprotocol/inspector on GitHub. It supports all versions of the MCP protocol and is updated alongside the specification. Developers who use Inspector during development report 50% reduction in debugging time compared with testing directly through Claude Desktop, because the feedback loop is instant.
Use the Inspector as your first testing step — even before configuring Claude Desktop. If your tool works in Inspector, it will work in Claude. If it doesn't work in Inspector, the problem is with your server, not the client configuration. Inspector is your troubleshooting tool.
Installing the MCP Inspector is surprisingly simple—just one command npx that downloads and runs everything automatically. There’s no need to install anything globally or configure anything. The interface opens in your browser and is ready to use.
The command to run the Inspector is:
O npx temporarily downloads the package and runs it without a global installation. The Inspector opens automatically in the browser at http://localhost:5173 (default port). The first run may take a few seconds to download the dependencies.
Make sure you have Node.js installed (version 18 or higher). Check with node --version.
Execute npx @modelcontextprotocol/inspector uv run server.py — this starts the Inspector AND your server simultaneously.
The browser opens automatically. If it doesn't, go to http://localhost:5173.
Node.js is required to run Inspector. If you don't have Node.js installed, go to nodejs.org and install the LTS version. On Linux, you can use sudo apt install nodejs npm or install via nvm to manage multiple versions.
The Inspector needs to know how to start your MCP server. You specify the server’s run command, and the Inspector starts the process, establishes the STDIO connection, and keeps communication active throughout the debugging session.
The complete command to connect to your server:
The Inspector starts the process uv run server.py as a subprocess and connects via STDIO — the same mechanism Claude Desktop uses. This means that if it works in Inspector, it will work in Claude. Any output your server sends to stdout is interpreted as MCP messages; logs should go to stderr.
If you use python directly instead of uv, the command would be npx @modelcontextprotocol/inspector python server.py. Inspector accepts any command that starts an MCP process via STDIO. Make sure the correct virtual environment is activated if you're using Python directly.
The Inspector interface shows all the tools registered on your server, along with their descriptions and parameters. You can fill in the parameter fields, run the tool, and see the response immediately—a fast feedback loop that greatly speeds up development.
In the tab "Tools" In Inspector, you can see the server’s full list of tools. Each tool shows its name, description (from the docstring), and expected parameters (from the type hints). Click a tool to see form fields for each parameter. Fill in the values and click "Run Tool" and the response appears formatted below—including the returned content, MIME type, and any errors. This lets you test each tool in isolation with different parameter combinations.
In the "Tools" tab, find the tool you want to test in the list. Check that the name and description are correct.
Fill in the parameter fields with test values. Start with valid values, then test edge cases.
Click "Run Tool" and observe the response. Check the format, content, and error handling.
Update the server code and save the file. Reconnect the Inspector to test the changes.
Create a list of test scenarios for each tool: typical valid values, empty values, values at the edge of the range, special characters, very long strings. Run each scenario through Inspector and verify that the response is appropriate in every case. This is especially important for tools that make HTTP requests or access files.
The Inspector shows tool responses in a structured format, including the raw JSON from MCP communication. This lets you verify not only the response content, but also whether the format and types are correct — essential information for ensuring the model interprets the response correctly.
When you run a tool in the Inspector, the response appears in two views: the formatted view (readable text, rendered images) and the Raw JSON (the exact MCP message that would be sent to the client). The raw JSON shows the array of content with each block having type e text. Comparing the raw JSON with the expected result is the most reliable way to verify that your tool works correctly.
A well-formatted MCP response follows this structure: {"content": [{"type": "text", "text": "..."}]}. The field isError indicates whether the tool encountered an error. When it returns True, the model knows it should report the error to the user instead of using the response as valid data. The Inspector shows this visually with different colors.
When something doesn't work as expected, the Inspector is your best ally for diagnosing the problem. From servers that won't connect to tools that return unexpected errors, there's a systematic debugging process that resolves most problems in just a few minutes.
The most common problems and their solutions: Server won't connect — check that the command is correct and the dependencies are installed. Tool doesn't appear in the list — check that the decorator @mcp.tool() is present and the function has no syntax errors. Tool returns an error — check the server logs in the terminal where Inspector is running; the server's stderr appears there. Empty response — check whether the function returns something (not None).
Does the Inspector show “Connected” at the top? If not, the server command is wrong or the server has an import error.
Does the "Tools" tab show your tools? If not, check the decorators, imports, and whether the server crashes on startup.
Are the parameters correct in the interface? If any are missing, check the function signature’s type hints.
If the tool runs but returns an error, check the logs in the terminal. The server’s stderr has the full stack trace.
After editing the code, you need to reconnect the Inspector for the changes to take effect.
The most common and hardest-to-diagnose error: print() in the server code. Because MCP uses stdout for communication, any print() in your code corrupts the protocol and causes an immediate disconnection. Replace all print statements with logging.info() or logging.debug() that go to stderr.
npx @modelcontextprotocol/inspector — requires Node.js.
This is the final module of Track 3! Next Track: Track 4 — Real-World Projects