Turning Point Academy · MCP Engineering

MCP Inspector — Complete guide

Curso MCP Engineering · M2

A guide to keep next to you while you test your MCP server. The MCP Inspector is the official visual tool for testing and debugging a server before connecting it to a real client like Claude Desktop. Think of it as your server's oscilloscope: you plug it in, look inside it, and confirm that every tool responds correctly, without needing a model in the loop. It doesn't get installed: npx downloads it and runs it on the fly.

Why it exists (and why to use it first)

When you write your first server, the immediate question is: does it work? Do the tools I defined show up? Do they return what I expect? Inside a real client, an error is hard to see: you don't know whether your tool failed, the registration failed, or the model decided not to use it. The Inspector isolates that doubt. It shows you exactly what your server exposes and lets you run each tool by hand, so you separate "my server is wrong" from "the client didn't call it". Debugging is simply finding out why something doesn't do what you expected — and the Inspector puts it right in front of your eyes.

Launching it (a single line)

The pattern is always the same: you pass it the command that starts your server, as if you were typing it yourself in the terminal.

npx @modelcontextprotocol/inspector <command-to-start-your-server>

Local server over stdio (Python — the most common when starting out):

npx @modelcontextprotocol/inspector python server.py

The Inspector starts your server for you as a subprocess, connects to it and opens the interface in your browser (an address like http://localhost:...). A subprocess is simply a program that another program launches for you: here the Inspector launches your server.py and talks to it over stdio.

If your server is written in TypeScript, you pass it the command that starts it:

npx @modelcontextprotocol/inspector npx tsx index.ts

Server on the network over HTTP: you don't pass it a command. Open the Inspector "bare", and once inside, in the Transport panel, choose HTTP and paste your server's URL.

npx @modelcontextprotocol/inspector

The Inspector's panels

Once open, the interface has clear panels. This table is the one worth keeping on hand:

Panel	What it's for
Tools	List the tools your server declares; fill in their inputs in a form and run them to see the exact result
Resources	View and read the read-only data the server exposes
Prompts	Review the prompt templates the server offers
Notifications	Read the messages and logs the server emits while working — key to understanding what happened when something fails
Transport	Choose how to connect: stdio (local, via subprocess) or HTTP (on the network, via URL)

The panel you'll use most at first is Tools: you pick a tool, fill in its parameters (for example a = 6, b = 7), run it, and see the result exactly as your code returns it. If something goes wrong, your second stop is Notifications: that's usually where the clue to the error is.

The debugging loop (memorize this rhythm)

This is how you actually work when building a server:

You change the code (add a tool, fix a value, adjust an input).
You re-launch the Inspector (or reconnect) to load the new version. The Inspector doesn't detect your changes on its own: you have to reconnect for it to read the updated code.
You verify: you list, run with test inputs and confirm the result.

Repeat change → re-launch → verify until everything responds as you expect. Only then do you connect the server to a real client. Testing in the Inspector first saves you hours of guessing why it "doesn't work" inside Claude.

Practical tips

Always start by listing. If a tool you defined doesn't appear in the Tools panel, the problem is in your code or in the registration, not in the model. Check the decorator/registration and the name.
Test the edge cases. Don't just test 2 + 2. Put text where a number goes, or an empty field, and watch how your validation responds (Zod in TypeScript, the type hints in Python). That's how you discover errors before the model does.
When it fails, look at Notifications. The result in Tools tells you what it returned; the Notifications tell you why. Read the logs top to bottom.
For HTTP servers, verify the URL. A connection error is almost always a mistyped URL or a server that isn't running. Confirm that your uvicorn (or equivalent) is up before connecting.
With npx you don't install anything. It downloads and runs on the spot; the first time it may take a few seconds while it fetches the tool.

Common errors (and how to fix them)

The Inspector doesn't open / doesn't connect → check that your server's start command is correct and works on its own in the terminal before passing it to the Inspector.
The tool doesn't appear in the list → your server started, but the tool wasn't registered. Check the @mcp.tool decorator (Python) or server.tool(...) (TypeScript).
I changed the code but I see the old version → you didn't reconnect. Stop and re-launch the Inspector (step 2 of the loop).
A tool fails when run → open Notifications and read the log; it usually says exactly which input it didn't like or which line failed.

To remember

The Inspector is used before connecting to a client: it saves you guessing why it "doesn't work".
With npx you don't install anything: it downloads and runs on the spot.
stdio → you pass it the start command. HTTP → you choose the transport and paste the URL.
Debugging is finding out why something doesn't do what you expected; the Inspector shows it to you.
If a tool fails, look at Notifications: that's usually where the clue is.

Base command: npx @modelcontextprotocol/inspector <command-to-start-your-server>