How to use MCP Inspector to debug your MCP server

MCP Inspector is the official debugging tool for the Model Context Protocol (MCP). It lets you connect to a running MCP server, list its tools and resources, invoke them with arbitrary inputs, and watch the raw JSON-RPC traffic on the wire. If you're building or integrating an MCP server, it's the fastest way to find out why a tool call isn't behaving the way your agent expects.

This guide walks through installing the inspector, connecting it to a local server, exercising tools and resources, and reading the protocol logs to diagnose failures. By the end you'll be able to debug an MCP server end-to-end without writing a client.

Prerequisites: Node.js 22 or later (check the current engines field on the npm package if you're on an older version), an MCP server you can run locally (stdio or HTTP), and a terminal.

Time required: about 30 minutes.

Step 1 — Launch the inspector

MCP Inspector is published as an npm package by Anthropic and the MCP working group. You don't need to install it globally — npx will fetch and run it on demand.

Run it from the directory where your server lives:

npx @modelcontextprotocol/inspector

The command prints a local URL (usually http://localhost:6274) and opens a browser tab. The UI has a connection panel on the left and a tabbed workspace on the right for Tools, Resources, Prompts, and Notifications.

If the tab doesn't open, paste the URL into your browser manually.

Step 2 — Connect to your MCP server

The inspector supports three transports: stdio, Streamable HTTP, and the older SSE transport. Pick the one your server uses.

For a stdio server, fill in the connection panel like this:

• Transport type: STDIO
• Command: the executable, e.g. node or python
• Arguments: the path to your server entry point, e.g. dist/server.js

For an HTTP server, switch to Streamable HTTP and enter the full URL, e.g. http://localhost:3000/mcp.

Click Connect. The status indicator should turn green and the Tools, Resources, and Prompts tabs should populate with whatever your server advertises.

If the connection fails, check the terminal where you ran npx — for a stdio server, child-process stderr surfaces there (the MCP spec deliberately keeps logs off the stdio protocol stream). The History pane in the UI will also show the failed JSON-RPC exchange.

Step 3 — List and inspect tools

Open the Tools tab. You should see one row per tool your server exports, each with a name, description, and input schema.

Click a tool to expand it. The right-hand panel shows the full JSON Schema for the tool's input. This is the same schema your agent's foundation model sees — if a field's description is vague or its type is loose, that's a real signal the model will struggle to call the tool reliably.

A quick checklist while you're here:

• Every tool has a clear, single-sentence description.
• Every parameter has a description, not just a name and type.
• Required fields are marked required.
• Enums are used where the input is one of a fixed set.

Fix any gaps in the server before moving on. A debugger can't make up for a tool whose schema doesn't tell the model what it does.

Step 4 — Invoke a tool with test inputs

With a tool selected, the inspector renders an input form derived from the schema. Fill in values and click Run Tool.

Three things appear:

1. The rendered result — the tool's response content, formatted.
2. The raw response — the full JSON-RPC payload, including the content array, any isError flag, and metadata.
3. The request payload — exactly what was sent over the wire.

Run the tool with a known-good input first to confirm the happy path. Then try the cases that matter for production:

• Missing a required field. Does the server return a structured error, or crash?
• An out-of-range value. Does the server validate, or pass it through to a downstream API?
• A field at the edge of its type — empty string, very long string, zero, negative number.

The response panel shows whether errors are returned as proper JSON-RPC errors or smuggled into a successful response with isError: true. Both are valid in MCP, but your agent has to handle whichever one your server picks — be consistent.

Step 5 — Test resources and prompts

The Resources tab lists everything your server exposes via resources/list. Click a resource to fetch its contents and see the MIME type, URI, and body. If you implement resource templates, the tab also lets you fill in template variables and resolve a concrete URI.

The Prompts tab does the same for prompt templates — fill in arguments, click Get Prompt, and the inspector renders the resulting message list.

For both, the same pattern applies: check the wire-level response, not just the rendered preview. A prompt that looks fine in the UI can still ship malformed role fields that confuse a downstream model.

Step 6 — Read the protocol log

The History pane shows every JSON-RPC request/response in both directions, with timestamps. This is where most real debugging happens. The Server Notifications pane is a separate stream — it captures server-emitted log notifications (notifications/message, controlled via logging/setLevel), not the full protocol traffic.

What to look for in History:

• Initialisation handshake. The first exchange should be initialize followed by the notifications/initialized notification. If your server doesn't complete this handshake correctly, clients will refuse to enter normal operation at all — they won't silently degrade.
• Capability mismatches. If you don't declare tools: { listChanged: true }, you shouldn't emit notifications/tools/list_changed, and clients will assume your tool list is static — they won't pick up runtime changes. The same applies to any advertised-but-unsupported sub-capability.
• Latency. The timestamps make it obvious when a tool call is slow. Anything over a couple of seconds will frustrate an agent loop — fix it at the source, not in the client.
• Error shapes. Confirm errors include a code, message, and where useful, a data field with structured detail.

Common pitfalls

Stale tool definitions. The inspector caches the tool list at connect time. If you change a schema in your server, disconnect and reconnect — don't trust the cached view.

Auth that works locally and fails in production. The inspector typically connects without auth or with a static token. That tells you nothing about how the server behaves under a real per-user OAuth flow. Test auth separately before declaring the server done.

Treating the inspector as a test suite. It's a debugger, not a test runner. Once a tool works in the inspector, write an automated test that runs in CI — manual clicks don't catch regressions.

Schemas that look fine to humans. A tool's schema reads cleanly to you because you wrote it. The model has no such context. If a parameter description could mean two things, it will mean both, intermittently. Tighten the wording until it can't.

Debugging the wrong layer. If a tool call works in the inspector but fails when an agent invokes it, the problem is upstream — in the agent's prompt, the model's tool-selection logic, or the framework's argument handling. The inspector has already proven the server is fine.

How Pontil fits

MCP Inspector is the right tool for debugging an MCP server you've already built. The harder question, for most B2B SaaS teams, is getting to a server worth debugging — one that exposes the full surface of an existing product, stays current as the product changes, and runs tool calls as the authenticated user rather than a shared service account.

That's the gap Pontil closes. We generate connectors directly from your existing codebase, keep them aligned with your SDLC as the product evolves, and run the resulting tools in a managed runtime with per-user auth. Once those tools exist, MCP Inspector — or any MCP client — works exactly the way this guide describes. If you're earlier in the journey and your APIs only cover a fraction of what your product can do, book a demo and we'll show you what generation looks like against a real codebase.

What to do next

With the inspector working, the next step is to harden the server: add automated tests around each tool, wire structured logging into your existing observability stack, and run the inspector against a staging deployment with real auth. The bugs you'll find from there are the ones that actually matter in production.