MCP Inspector

What MCP Inspector does

Inspector is a thin web application that acts as an MCP client — it speaks the MCP protocol, negotiates capabilities, and lists tools just as Claude or any other LLM client would. The difference is that it renders the protocol traffic visually and lets you construct tool call arguments through a form UI rather than through a natural-language prompt.

Connecting to a stdio server

For servers that launch via a command (the most common MCP server type for local tooling), pass the server command as arguments to Inspector. Inspector spawns the process and connects via its stdin/stdout.

# TypeScript server run with tsx
npx @modelcontextprotocol/inspector tsx src/index.ts

# Compiled server
npx @modelcontextprotocol/inspector node dist/index.js

# With environment variables
npx @modelcontextprotocol/inspector \
  --env API_KEY=sk-test123 \
  --env DB_PATH=/tmp/test.db \
  node dist/index.js

# Python MCP server
npx @modelcontextprotocol/inspector uv run my_server.py

Inspector opens a browser window automatically (or prints the URL if the auto-open fails). The server process stays running until you close the Inspector tab or terminate the npx command. Environment variables passed via --env are available to the server process but not inherited from the parent shell — add any secrets or config paths the server needs to initialise successfully.

Connecting to an HTTP/SSE server

For servers that expose an HTTP endpoint (remote or locally running), launch Inspector without a server command and enter the connection details in the UI.

# Launch the Inspector UI without a target server
npx @modelcontextprotocol/inspector

# Inspector prints a URL like: http://localhost:6274
# Open it in a browser, then in the UI:
# - Select "SSE" transport
# - Enter the SSE endpoint URL, e.g.: http://localhost:3000/sse
# - Click Connect

For the newer Streamable HTTP transport (MCP spec 2025-03-26), select "Streamable HTTP" in the transport dropdown and enter the base URL (e.g., http://localhost:3000/mcp). Inspector handles the capability negotiation automatically.

If your server requires authentication headers, click "Add Header" to append Authorization: Bearer <token> before connecting. This is useful for testing your JWT validation or API key middleware during development.

Schema verification workflow

One of the most useful Inspector workflows is verifying your tool schemas before shipping. The MCP spec requires each tool's inputSchema to be a valid JSON Schema object. Common mistakes include missing type: 'object' at the top level, required fields listed that aren't in properties, and optional fields marked as required.

// A schema with a common mistake:
{
  inputSchema: {
    // Missing "type": "object" — Inspector will show the tool but the SDK
    // may reject tool calls with argument validation errors
    properties: {
      query: { type: 'string', description: 'Search query' }
    },
    required: ['query']
  }
}

// Correct:
{
  inputSchema: {
    type: 'object',   // required at the root
    properties: {
      query: { type: 'string', description: 'Search query' }
    },
    required: ['query']
  }
}

Inspector renders the schema in the tool list panel. If a tool does not appear, or appears with a broken input form, the schema is likely malformed. The protocol log shows the raw tools/list response — compare it against the MCP specification if a tool is missing.

Debugging tool call failures

When a tool call fails, the protocol log is the fastest way to diagnose the cause. Three distinct failure modes look different in Inspector:

For the third case — where the server crashes on startup — check the terminal window where you launched Inspector. The server process output (stdout + stderr) is printed there, which typically shows the exact startup error. Common startup failures are missing environment variables, failed database migrations, and port conflicts.

Inspector vs. automated tests vs. AliveMCP

These three tools cover different phases of the development and operations lifecycle:

A common pattern: use Inspector to verify a new tool during development, write unit tests to lock in the correct behavior, and rely on AliveMCP to alert when the deployed server's protocol health degrades — for example, when a bad deploy leaves the server returning a valid HTTP 200 but failing the initialize handshake.

Related questions

Further reading

• MCP server unit testing — InMemoryTransport for automated tests, complementing Inspector's manual testing
• MCP server Vitest — test runner to automate what Inspector verifies manually
• MCP server debugging — debugging patterns beyond what Inspector shows
• MCP server error handling — understanding isError vs. protocol errors Inspector distinguishes
• MCP server SDK — the SDK that ships Inspector as part of the ecosystem
• MCP server JWT validation — adding auth headers in Inspector for testing secured servers
• MCP server health check — the endpoint AliveMCP probes that Inspector cannot replace
• AliveMCP — automated production monitoring that runs the checks Inspector does manually, every 60 seconds