Debugging with MCP Inspector

The MCP Inspector is an essential debugging tool that lets you interactively test and troubleshoot your MCP servers without needing a full AI host application. Think of it as "Postman for MCP" - it provides a visual interface to send requests, view responses, and understand how your server behaves.

Why Use MCP Inspector?

When building MCP servers, you'll often encounter these challenges:

"Is my server even running?" - Inspector shows connection status
"Are my tools registered correctly?" - Inspector lists all available tools
"What's the response format?" - Inspector displays full JSON responses
"Why isn't this tool working?" - Inspector shows detailed error messages

Prerequisites

Node.js 18+ installed
npm (comes with Node.js)
An MCP server to test (see Module 3.1 - First Server)

Installation

Option 1: Run with npx (Recommended for Quick Testing)

npx @modelcontextprotocol/inspector

Option 2: Install Globally

npm install -g @modelcontextprotocol/inspector
mcp-inspector

Option 3: Add to Your Project

cd your-mcp-server-project
npm install --save-dev @modelcontextprotocol/inspector

Add to package.json:

{
  "scripts": {
    "inspector": "mcp-inspector"
  }
}

Connecting to Your Server

stdio Servers (Local Process)

For servers that communicate via standard input/output:

# 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

SSE/HTTP Servers (Network)

For servers running as HTTP services:

Start your server first:

python server.py  # Server running on http://localhost:8080

Launch Inspector and connect:

npx @modelcontextprotocol/inspector --sse http://localhost:8080/sse

Inspector Interface Overview

When Inspector launches, you'll see a web interface (typically at http://localhost:5173):

┌─────────────────────────────────────────────────────────────┐
│  MCP Inspector                              [Connected ✅]   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   🔧 Tools  │  │ 📄 Resources│  │ 💬 Prompts  │         │
│  │    (3)      │  │    (2)      │  │    (1)      │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │  📋 Message Log                                       │ │
│  │  ─────────────────────────────────────────────────── │ │
│  │  → initialize                                         │ │
│  │  ← initialized (server info)                          │ │
│  │  → tools/list                                         │ │
│  │  ← tools (3 tools)                                    │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Testing Tools

Listing Available Tools

Click the Tools tab
Inspector automatically calls tools/list
You'll see all registered tools with:
- Tool name
- Description
- Input schema (parameters)

Invoking a Tool

Select a tool from the list
Fill in the required parameters in the form
Click Run Tool
View the response in the results panel

Example: Testing a calculator tool

Tool: add
Parameters:
  a: 25
  b: 17

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

Debugging Tool Errors

When a tool fails, Inspector shows:

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

Common error codes:

Code	Meaning
-32700	Parse error (invalid JSON)
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error

Testing Resources

Listing Resources

Click the Resources tab
Inspector calls resources/list
You'll see:
- Resource URIs
- Names and descriptions
- MIME types

Reading a Resource

Select a resource
Click Read Resource
View the content returned

Example output:

Resource: file:///config/settings.json
Content-Type: application/json

{
  "config": {
    "debug": true,
    "maxConnections": 10
  }
}

Testing Prompts

Listing Prompts

Click the Prompts tab
Inspector calls prompts/list
View available prompt templates

Getting a Prompt

Select a prompt
Fill in any required arguments
Click Get Prompt
See the rendered prompt messages

Message Log Analysis

The message log shows all MCP protocol messages:

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":[...]}}

What to Look For

Request/Response pairs: Each → should have a matching ←
Error messages: Look for "error" in responses
Timing: Large gaps might indicate performance issues
Protocol version: Ensure server and client agree on version

VS Code Integration

You can run Inspector directly from VS Code:

Using launch.json

Add to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug with MCP Inspector",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npx",
      "runtimeArgs": [
        "@modelcontextprotocol/inspector",
        "python",
        "${workspaceFolder}/server.py"
      ],
      "console": "integratedTerminal"
    },
    {
      "name": "Debug SSE Server with Inspector",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:5173",
      "preLaunchTask": "Start MCP Inspector"
    }
  ]
}

Using Tasks

Add to .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start MCP Inspector",
      "type": "shell",
      "command": "npx @modelcontextprotocol/inspector node ${workspaceFolder}/build/index.js",
      "isBackground": true,
      "problemMatcher": {
        "pattern": {
          "regexp": "^$"
        },
        "background": {
          "activeOnStart": true,
          "beginsPattern": "Inspector",
          "endsPattern": "listening"
        }
      }
    }
  ]
}

Common Debugging Scenarios

Scenario 1: Server Won't Connect

Symptoms: Inspector shows "Disconnected" or hangs on "Connecting..."

Checklist:

✅ Is the server command correct?
✅ Are all dependencies installed?
✅ Is the server path absolute or relative to current directory?
✅ Are required environment variables set?

Debug steps:

# 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

Scenario 2: Tools Not Appearing

Symptoms: Tools tab shows empty list

Possible causes:

Tools not registered during server initialization
Server crashed after startup
tools/list handler returning empty array

Debug steps:

Check message log for tools/list response
Add logging to your tool registration code
Verify @mcp.tool() decorators are present (Python)

Scenario 3: Tool Returns Error

Symptoms: Tool call returns error response

Debug approach:

Read the error message carefully
Check parameter types match schema
Add try/catch with detailed error messages
Check server logs for stack traces

Example improved error handling:

@mcp.tool()
async def my_tool(param1: str, param2: int) -> str:
    try:
        # Tool logic here
        result = process(param1, param2)
        return str(result)
    except ValueError as e:
        raise McpError(f"Invalid parameter: {e}")
    except Exception as e:
        raise McpError(f"Tool failed: {type(e).__name__}: {e}")

Scenario 4: Resource Content Empty

Symptoms: Resource returns but content is empty or null