When an MCP server misbehaves, the error you see is usually the last symptom, not the cause — a client that says “tool call failed” and nothing else, or a model that keeps calling the wrong tool for reasons you can’t see from the chat window. The MCP Inspector is the official tool for getting underneath that: it speaks MCP directly, so you can watch the exact handshake, tool list, and tool call your server sends and receives, with nothing translated or summarized by a model in between. Here’s how to actually use it.

What the Inspector is for

The Inspector is a small local app — a proxy plus a browser UI — maintained under the official modelcontextprotocol GitHub organization. You point it at a server, local or remote, and it does the same first moves any MCP client does — initialize, then tools/list — but shows you the raw request and response for each step instead of hiding them behind a chat interface. That distinction matters: a model can only tell you what it inferred from a tool’s description and the result it got back. The Inspector shows you what was actually sent.

Running it

The Inspector ships as an npm package and needs no separate install step:

npx @modelcontextprotocol/inspector

That opens a local web UI, usually on localhost:6274. For a local server running over stdio, you point the Inspector at the command that starts it (for example node server.js or uvx my-server). For a remote server — the kind this site is mostly about — you give it the server’s Streamable HTTP URL instead, and if the server requires OAuth, the Inspector will walk you through the authorization redirect the same way a real client would.

If you’d rather skip the local install entirely, a hosted alternative like gate’s browser-based MCP Inspector runs the same connect-and-list step from a page you paste a URL into — useful for a quick check on a remote server without touching a terminal, though it won’t walk a stdio server the way the local Inspector does.

Reading the tool list like a client does

Once connected, the Inspector’s Tools tab lists every tool your server exposes, exactly as tools/list returned it: name, description, and the full JSON Schema for its inputs. This is the view worth spending real time in, because it’s the same information — nothing more — that an AI client has when it decides whether and how to call a tool. If a description is vague or a required parameter is missing from the schema, you’ll see it here before a model ever mis-calls the tool in production. We went through what a good description looks like, versus one a model will misuse, in how to write MCP tool descriptions your AI will actually use correctly.

You can also call any tool directly from this tab, filling in the arguments by hand. This is the fastest way to find out what your server actually does with realistic input, missing input, and deliberately wrong input — a step that’s easy to skip when you’ve only ever tested the happy path yourself.

Watching notifications and errors

The Inspector also surfaces the parts of a session a chat UI usually swallows: raw JSON-RPC error codes, listChanged notifications if your server sends them, and any log messages your server emits over the protocol’s logging capability. If your server ever needs to change its tool list at runtime, this is where you’d confirm the notification actually fires and that a client would notice it. A raw error code is also the fastest way to tell a protocol-level failure (bad JSON-RPC framing, a missing capability) from an application-level one (your handler threw, your upstream API timed out) — the two look identical from inside a chat window but need completely different fixes.

What the Inspector won’t tell you

It’s a protocol tool, not a safety review. The Inspector will faithfully show you a tool description that contains hidden instructions aimed at a model, because from a pure JSON-RPC standpoint that description is perfectly valid — it just isn’t checking for that. It also won’t tell you whether a write tool is safe to call twice, or whether your readOnlyHint annotation actually matches what the tool does. Those are exactly the gaps a pre-publish checklist is meant to close; we laid one out in how to test an MCP server before you publish it, and a security pass — gate’s own free MCP security scanner or the Inspector paired with a manual read-through — is worth running alongside it, not instead of it.

A concrete workflow: build your server, connect it with the Inspector and confirm the tool list and a few real calls look right, run a security scan over the same server, then connect it to an actual AI client and watch the first few real conversations. Each step catches a different class of problem, and skipping straight to the last one is how a description that reads fine to you turns into a tool a model calls wrong in front of a user.

If you’re building the server, not just testing one

If you’re turning an existing API into an MCP server rather than debugging one you already wrote by hand, gate’s MCP server builder generates the tool definitions from an OpenAPI spec or a docs URL, flags each tool read or write, and runs the security scan automatically before it’s live — the Inspector is still worth pointing at the result afterward to confirm the generated tool list reads the way you expect.

The bottom line

The MCP Inspector shows you the protocol traffic a chat interface hides: the exact handshake, the raw tool list, and the request and response for every call. Run it before you trust your own descriptions, before you assume a notification fires, and before you publish anywhere. It won’t catch a hostile description or an unsafe retry on its own — pair it with a security scan and a manual read-through, and you’ll catch most of what actually breaks in production before a real client finds it for you.