Debugging MCP Servers with the MCP Inspector

Debugging through a chat app is slow: you can't see the raw messages, and the model decides when to call your tool. The MCP Inspector is an official browser-based tool that connects to your server directly.

Run it

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

# Python server with FastMCP
uv run mcp dev server.py

# Pass environment variables
npx @modelcontextprotocol/inspector -e API_KEY=test node build/index.js

What you can do

• See the server's declared capabilities after the initialize handshake.
• List tools and inspect their generated JSON Schemas.
• Call a tool with hand-written arguments and see the exact result, including isError.
• Read resources and render prompts with arguments.
• Watch notifications and server logs.

Common problems and fixes

"Connection closed" immediately. The server crashed on start. Run the command directly in a terminal to see the stack trace.

Garbled or invalid JSON errors. Something is printing to stdout. Replace console.log with console.error (or Python's print with logging to stderr).

import logging, sys
logging.basicConfig(stream=sys.stderr, level=logging.INFO)

Tool works in the Inspector but the model never calls it. The description doesn't explain when to use it. Rewrite it from the model's point of view.

Works in the terminal but not in the desktop app. The app has a different PATH and working directory. Use absolute paths to node, uv and your script.

Write tests too

The SDKs include an in-memory transport, so you can connect a client and server inside a unit test and assert on callTool results without spawning processes.