We used MCP Inspector to find several of the OAuth quirks documented in our OAuth deep dive — it was the tool that showed us the token exchange was happening at all, before we had any other way to see inside the flow. This post is the tool itself: how to install it, connect it to a local server and then a remote one, exercise tools, and read what it tells you when something’s wrong.

What MCP Inspector is

MCP Inspector (@modelcontextprotocol/inspector, maintained in the official modelcontextprotocol/inspector repo) is a developer tool for connecting to any MCP server and poking at it directly, without wiring it into Claude, ChatGPT, or Cursor first. It speaks both of MCP’s standard transports — stdio for local subprocess servers, and Streamable HTTP for remote ones — and gives you a UI (or a CLI, for scripting) to list tools, resources, and prompts, call them with arbitrary arguments, and see the raw JSON-RPC response.

The practical value: MCP clients hide almost everything. If a connector shows “0 tools” or a tool call silently fails, the client UI rarely tells you why. Inspector talks to your server the same way a real client would, but shows you every request and response, so you can tell whether the problem is your server, the transport, or the auth layer. If you haven’t set up a client connection yet and just want the user-facing steps, our Claude MCP setup guide covers that side; this post is for people building or debugging the server itself.

Install and run

No install step — npx pulls the latest published version and runs it:

npx @modelcontextprotocol/inspector

This opens the browser-based UI at http://localhost:6274. A companion proxy process listens on localhost:6277 — the UI talks to your MCP server through this proxy, not directly. Both ports matter later when you’re reading error messages, so keep this pairing in mind: 6274 is the UI, 6277 is the proxy.

(We could not directly confirm the exact latest published npm version number as of this writing — the npm package page returned a 403 to our automated check — but the package name and command syntax below are corroborated by the GitHub README and independent 2026 guides, so treat the commands as current even if the version number isn’t pinned down here.)

Connecting to a local stdio server

If you’re developing an MCP server that runs as a local subprocess (the stdio transport — client launches the server, talks over stdin/stdout), point Inspector at the launch command directly:

npx @modelcontextprotocol/inspector node build/index.js

Inspector starts your server as a child process and opens the UI connected to it. Whatever your server prints to stderr shows up in Inspector’s own logs, which is often the fastest way to catch a crash on startup — a client like Claude Desktop will usually just show “server disconnected” with no detail, Inspector shows you the stack trace.

Connecting to a remote server (Streamable HTTP)

Once your server is deployed and reachable over HTTP, connect the same UI to it in the connection panel: enter the URL, set transport to Streamable HTTP, connect. Under the hood this is the same --transport http flag family used by CLI mode (below).

Streamable HTTP is the current standard transport for remote MCP servers — a single endpoint handling POST and GET, with optional SSE streaming for multi-message responses. The older plain HTTP+SSE transport (from the 2024-11-05 protocol revision) is deprecated as of the 2025-03-26 revision; it’s kept in the spec only as a documented backwards-compatibility path. If you’re building new, target Streamable HTTP.

Auth against the target server. If your server requires a bearer token — an OAuth access token, or a static API key — Inspector’s connection panel has a field for it, or you can pass custom headers for API-key-style auth. Whatever you enter gets sent as Authorization: Bearer <token> (or your custom header) to the remote server on every request. This is a completely separate thing from the proxy session token described next, and mixing the two up is the single most common point of confusion using this tool.

The two tokens: proxy session token vs. server bearer token

Every time Inspector’s proxy process (port 6277) starts, it generates a random session token and prints it to the console. This token authenticates requests to Inspector’s own local proxy — it has nothing to do with your MCP server’s auth. It exists because the proxy is a local HTTP listener; without some check, any other local process or browser tab could hit port 6277 and drive your Inspector session, which is a real local RCE-adjacent risk if that port is reachable. The browser UI Inspector opens for you normally has this token pre-filled in the URL, or you can supply it yourself via the MCP_PROXY_AUTH_TOKEN environment variable.

There is a DANGEROUSLY_OMIT_AUTH=true env var that disables this proxy check. The README is explicit that this reintroduces a real remote-code-execution risk if the proxy port is reachable by anything untrusted — the documented attack (CVE-2025-49596) is a drive-by from a malicious webpage hitting localhost, so “no inbound ports” does not protect you. Only use it on a machine where no web browser runs — a throwaway CI runner or isolated container — never on your dev laptop.

So: two tokens, two jobs. The proxy session token (MCP_PROXY_AUTH_TOKEN) protects Inspector itself, running on your machine. The bearer token you type into the connection panel protects your remote MCP server. Confusing which one goes where is the fastest way to burn twenty minutes debugging a “connection failed” that’s actually just the wrong token in the wrong box.

Exercising tools and reading results

Once connected, the UI lists everything your server declares via tools/list, resources/list, and prompts/list at session start — this is the same capability negotiation a real client does during initialize. Pick a tool, fill in its argument schema, call it, and Inspector shows you the raw JSON-RPC response: the structured content the model would receive, plus any error object if the call failed server-side. This is the fastest way to check that a tool’s outputSchema actually matches what the tool returns, before a stricter client complains about it for you.

Debugging auth flows with Inspector

If your server is behind OAuth (mandatory for Anthropic’s and OpenAI’s connector directories), Inspector is the tool that lets you see the handshake instead of guessing at it from a client’s “connector failed” message. Watch for: whether the authorization redirect actually completes, whether the subsequent request to your token endpoint happens at all, and what token_type and scopes come back. We wrote up the specific quirks we hit doing exactly this — 302 vs. 303 on the consent redirect, lowercase bearer, dropping the iss parameter, and eight more — in the OAuth deep dive. That post is the “why it broke silently” companion to this one’s “here’s how to see it break.”

CLI mode for scripting

For CI or one-off scripted checks, add --cli:

npx @modelcontextprotocol/inspector --cli node build/index.js

And against a remote server:

npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com \
  --transport http --method tools/list

This prints the JSON-RPC response and exits — no browser, no persistent proxy — which is what you want in a pipeline that just needs to assert “tools/list returns N tools” as a smoke test after deploy.

Common errors and what they mean

  • “Failed to connect” with no other detail, on a URL that used to work. Check whether the server is HTTP+SSE-only (deprecated transport) while you’re connecting with --transport http (Streamable HTTP) — these are not interchangeable; an old SSE-only server needs the legacy detection path, not the Streamable HTTP transport.
  • Auth appears to succeed but tool calls 401. Almost always the two-token mix-up above: you supplied the proxy session token where the server’s bearer token belongs, or vice versa.
  • Inspector dies at startup while trying to auto-launch a browser. On Windows this was a tracked spawn failure (inspector #794, since closed upstream, so recheck on a current version before assuming it) — a bug in the browser-launch step, not in your server. The same auto-launch step is also the first thing to suspect if Inspector won’t start in a headless or sandboxed environment.
  • Tool call succeeds in Inspector but the same tool fails from Claude or ChatGPT. That’s a strong signal the bug is client-specific (auth flow, CORS preflight, response shape) rather than in your tool logic — Inspector proved the server side works.

Testing against a live server

If you want to see all of this against a real, working remote MCP server rather than a toy stdio example, point Inspector at ours: https://mcp-analytics.com/mcp. It’s OAuth 2.1 with PKCE, 23 tools, and free to connect — sign up free (100,000 hits/month, no credit card) and you’ll have a live endpoint to run tools/list and a few real tool calls against in the next five minutes. It’s also a decent way to see what a spec-compliant Streamable HTTP + OAuth server looks like from Inspector’s side, if you’re mid-build on your own — and if you’re weighing whether a live MCP tool surface is even the right shape for what you’re building versus a plain REST API, see MCP vs. API.