Debugging MCP servers with MCP Inspector

Who this is for and what you will get

You have written an MCP server, and you want to test it on its own before connecting an AI app, or you have connected it but a tool behaves oddly. By the end you should be able to connect MCP Inspector to the server, test its tools, resources and prompts one by one, read the message log, and work through the common problems of a server that will not connect or a tool that does not appear. ^[1]

Check the protocol version first

Commands using --sse, and URLs ending in /sse, test the legacy HTTP+SSE transport. For a server on MCP 2026-07-28, use an Inspector version that supports Streamable HTTP and select that transport in the interface. ^[1]

What the Inspector is

MCP Inspector is a debugging tool. It lets you test and troubleshoot MCP servers interactively, without a full AI host application. Its visual interface sends requests and shows responses, so you can see how the server behaves. It answers four questions: is the server running, are the tools registered correctly, what does the response look like, and why is a given tool not working. ^[1]

Prerequisites and installation

You need Node.js 18 or newer, npm (which comes with Node.js), and an MCP server to test. ^[1]

There are three ways to install. For a quick test, run npx @modelcontextprotocol/inspector, which is recommended. For a global install, run npm install -g @modelcontextprotocol/inspector and then start it with mcp-inspector. To keep it in a project, run npm install --save-dev @modelcontextprotocol/inspector and add "inspector": "mcp-inspector" to the scripts section of package.json. ^[1]

Connecting to a server

A stdio server runs as a local process and communicates over standard input and output. The commands cover Python, Node.js and setting an environment variable:

# Python server
npx @modelcontextprotocol/inspector python -m your_server_module

# Node.js server
npx @modelcontextprotocol/inspector node ./build/index.js

# With environment variables
OPENAI_API_KEY=xxx npx @modelcontextprotocol/inspector python server.py

For a server that runs as an HTTP service, start the server first and then connect the Inspector with --sse. The example runs the server at http://localhost:8080:

python server.py  # Server running on http://localhost:8080
npx @modelcontextprotocol/inspector --sse http://localhost:8080/sse

The Inspector's web interface is typically at http://localhost:5173. ^[1]

Testing tools

Clicking the Tools tab makes the Inspector call tools/list, which lists each tool's name, description and input schema. Select a tool, fill in its parameters in the form, click Run Tool, and read the result in the results panel. ^[1]

The example is a calculator tool named add, with a set to 25 and b set to 17, which returns the text 42:

{
  "content": [
    {
      "type": "text",
      "text": "42"
    }
  ]
}

When a tool fails, the Inspector shows an error response. The example is error code -32602 with the message "Invalid params: 'b' is required", meaning parameter b is missing:

{
  "error": {
    "code": -32602,
    "message": "Invalid params: 'b' is required"
  }
}

There are five common error codes: -32700 for parse error (invalid JSON), -32600 for invalid request, -32601 for method not found, -32602 for invalid params, and -32603 for internal error. ^[1]

Testing resources and prompts

The Resources tab calls resources/list and shows each resource's URI, name, description and MIME type. Select a resource and click Read Resource to see the content. The example is file:///config/settings.json, with the content type application/json. ^[1]

The Prompts tab calls prompts/list. Select a prompt, fill in any required arguments, click Get Prompt, and see the rendered prompt messages. ^[1]

Reading the message log

The message log records every MCP protocol message. The transcript comes from a legacy 2025-11-25 server and includes the initialize handshake that the newer specification removes:

14:32:01 → {"jsonrpc":"2.0","id":1,"method":"initialize",...}
14:32:01 ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25",...}}
14:32:02 → {"jsonrpc":"2.0","id":2,"method":"tools/list"}
14:32:02 ← {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
14:32:05 → {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add",...}}
14:32:05 ← {"jsonrpc":"2.0","id":3,"result":{"content":[...]}}

A 2026-07-28 server uses self-contained request metadata and server/discover in place of the handshake. When you read the log, check four things: each request (→) should have a matching response (←); look for "error" in responses; large timing gaps can point to performance problems; and confirm that the server and client agree on the protocol version. ^[1]

Common debugging scenarios

The server will not connect. The Inspector shows "Disconnected" or hangs on "Connecting...". The checklist asks whether the server command is correct, whether all dependencies are installed, whether the server path is absolute or relative to the current directory, and whether required environment variables are set. ^[1]

To narrow it down, test the server on its own in a terminal, check for import errors, and confirm the MCP SDK is installed:

# Test server manually first
python -c "import your_server_module; print('OK')"

# Check for import errors
python -m your_server_module 2>&1 | head -20

# Verify MCP SDK is installed
pip show mcp

The tool list is empty. There are three possible causes: tools were not registered during initialization, the server crashed after startup, or the tools/list handler returned an empty array. Check the tools/list response in the message log, add logging to the tool registration code, and in Python confirm that the @mcp.tool() decorators are present. ^[1]

A tool returns an error. Read the error message carefully, check that parameter types match the schema, add exception handling with detailed messages, and check the server logs for stack traces. ^[1]

A resource is empty. Check that the file path or URI is correct, that the server can read the resource, and that the content is actually returned. ^[1]

Advanced use

For an SSE server that requires authentication, add --header, as in --header "Authorization: Bearer your-token". For more detailed logs, put DEBUG=mcp* in front of the command, as in DEBUG=mcp* npx @modelcontextprotocol/inspector python server.py. ^[1]

The Export Log button in the message panel saves the message log as a JSON file, which is useful for keeping a record or sharing it with a colleague. ^[1]

Running it from VS Code

There are two approaches. One adds a configuration to .vscode/launch.json whose runtimeExecutable is npx and whose runtimeArgs include @modelcontextprotocol/inspector, python and ${workspaceFolder}/server.py. The other adds a background task named "Start MCP Inspector" to .vscode/tasks.json, which runs a Node.js server's build output. ^[1]

Best practices

There are five tips: test early and often rather than only when something breaks; start with basic connectivity before complex tool calls; check the schema, since many errors come from parameter type mismatches; read the error messages; and keep the Inspector open while you develop. ^[1]

Next steps

Once the tools behave in the Inspector, connect the server to a real AI host and test it end to end. ^[1]

Adapted from lesson 13 of the introductory section of Microsoft's open-source course *mcp-for-beginners*, "Debugging with MCP Inspector"^[1], released under the MIT License.