Skip to content
Tutorials

Debugging MCP Servers with MCP Inspector v2: Modes, CI Smoke Tests and Common Failures

AIDToolStack EditorialNovember 7, 20269 min read
MCPMCP InspectorDebuggingTesting
Share:Twitter

Your MCP server runs fine when you start it by hand. Then you add it to a client and get a red dot, an empty tool list, or a tool that "fails" with no message you can act on. The client is hiding the wire from you, and guessing at what went over it is slow.

MCP Inspector is the tool for putting yourself on that wire. If you last used it in 2025, a lot of what you remember is now wrong: the Inspector was rewritten as v2, and the protocol itself changed shape in the 2026-07-28 spec revision. This post covers the current versions, how to use each Inspector mode, and the failures I'd check first, grouped by symptom and by client. If you haven't built a server yet, start with our guide to building a custom MCP server and come back.

What changed in 2026

Two things moved under your feet this year.

The Inspector is v2. As of 7 November 2026 the npm latest tag for @modelcontextprotocol/inspector is 2.14.0, published on 5 November. The v1 → v2 migration guide calls v2 a rewrite and says v1 gets security fixes only, on the v1-latest tag. The differences that trip people up:

v1v2
Node>=22.7.5^22.23.4 || ^24.22.1 || >=26.12.1
PortsUI on 6274, MCP proxy on 6277one web server on 6274, plus an MCP Apps sandbox on 6275
Modesweb, --cliweb, --cli, --tui (plus an experimental mcpdo)
Server listper-browser localStoragea catalog file, ~/.mcp-inspector/mcp.json
Auth token envMCP_PROXY_AUTH_TOKENMCP_INSPECTOR_API_TOKEN (old name still read as a fallback)
CLI exit codes0 / 10 to 6, plus a JSON error line on stderr

The Node floor is stricter than it looks. Since v2.14 it's the patched release on each line from the October 2026 Node.js security releases, and the migration guide warns that npm only warns about an engines mismatch, so an old Node fails later and obscurely. Run node -v before anything else.

The protocol went stateless. The current spec revision is 2026-07-28. Its changelog removes the initialize handshake and the Mcp-Session-Id header, puts the protocol version and client capabilities in every request's _meta, adds a mandatory server/discover RPC, removes ping and logging/setLevel, and deprecates the Logging, Roots and Sampling features plus the old HTTP+SSE transport. Our MCP explainer covers the concepts; for debugging, what matters is that a client and server can now disagree about which era of the protocol they're speaking.

The Inspector exposes that as a per-server setting. The server configuration docs list protocolEra as "legacy" (the default), "auto" or "modern", settable from the command line with --protocol-era. If your server was built against 2026-07-28 and the Inspector talks to it the old way, that's the first thing to fix.

Flow chart: the client sends server/discover; a DiscoverResult means a modern server, an UnsupportedProtocolVersionError means modern but retry with a listed version, any other error or a timeout means a legacy server and a fallback to initialize
Flow chart: the client sends server/discover; a DiscoverResult means a modern server, an UnsupportedProtocolVersionError means modern but retry with a listed version, any other error or a timeout means a legacy server and a fallback to initialize

That chart is the probe the stdio transport page tells dual-era clients to run. Note the rule in the footer: the fallback can't key off one error code, because legacy servers answer unknown pre-initialize requests however they like.

Pick a mode

npx @modelcontextprotocol/inspector          # web UI (default)
npx @modelcontextprotocol/inspector --cli    # scriptable, for CI
npx @modelcontextprotocol/inspector --tui    # terminal UI, good over SSH

The mode flag has to come first, straight after the binary name. My rule: the web UI while you're building, the TUI when you're on a remote box or in tmux, and the CLI for anything a machine runs.

Architecture: a browser tab talks to the Inspector backend on port 6274, which spawns stdio servers and calls Streamable HTTP servers; the CLI and TUI connect directly with no web server; all three share the catalog file
Architecture: a browser tab talks to the Inspector backend on port 6274, which spawns stdio servers and calls Streamable HTTP servers; the CLI and TUI connect directly with no web server; all three share the catalog file

The web UI and TUI give you the same three monitors, per the TUI README: Protocol (JSON-RPC request, response and notification history), Network (HTTP traffic for SSE and Streamable HTTP servers) and Console (the stdio server's stderr). Most bugs show up in one of those three before you've finished reading your own code.

Walkthrough: a local stdio server

  1. Build, then point the Inspector at the command that starts your server:
   npx @modelcontextprotocol/inspector node build/index.js
  1. Pass environment variables with -e, and put your server's own flags after --:
   npx @modelcontextprotocol/inspector -e API_KEY=test -- node build/index.js --verbose
  1. If the server targets the 2026-07-28 revision, add --protocol-era modern (or auto if you're not sure which era it speaks).
  1. Open the Console monitor and keep it open. Anything your server writes to stderr lands there.
  1. In the Tools tab, check for portability flags. The Inspector lints each tool's input schema and marks constructs that a shipping client refuses or handles unevenly, with the path, the problem and a suggested fix. The same check runs from the CLI as tools/list --strict.
  1. Call each tool with realistic arguments, including the ones a model is likely to get wrong. A tool that returns isError: true is a different failure from a protocol error, and the Protocol monitor shows you which one you got.

Walkthrough: a remote Streamable HTTP server

npx @modelcontextprotocol/inspector --cli \
  --transport http --server-url https://example.com/mcp \
  --header "Authorization: Bearer $TOKEN" --method tools/list

v2 only infers the transport from the URL's last path segment: /mcp means Streamable HTTP, /sse means SSE, anything else stops with Transport type not specified and could not be determined from URL. A trailing slash (…/mcp/) counts as ambiguous too. v1 quietly fell back to SSE, so old scripts that "worked" against /api now fail. Pass --transport http explicitly and move on.

For OAuth-protected servers, the CLI supports real flows now (v1's CLI had none). The smoke-testing guide recommends --stored-auth-only in CI: it never opens a browser and fails fast with auth_required instead of hanging on a loopback callback. The default callback is http://127.0.0.1:6276/oauth/callback.

The CLI in CI

The CLI is where the Inspector earns its keep, because v2 gives you stable exit codes and a machine-readable error line. A minimal smoke job:

set -euo pipefail
I="npx --yes @modelcontextprotocol/[email protected] --cli"

# 1. Is it alive and speaking MCP?
$I node build/index.js --method initialize --format json > /dev/null

# 2. Does the tool we depend on exist?
$I node build/index.js --method tools/list --format json \
  | jq -e '.result.tools | map(.name) | index("get_temp")' > /dev/null

# 3. Does a safe, read-only call still work?
$I node build/index.js --method tools/call --tool-name get_temp \
  --tool-args-json '{"city":"Paris","units":"C"}' --format json \
  | jq -e '.result.structuredContent.unit == "C"' > /dev/null

Three details from the docs that are easy to miss:

  • Pin the version. @2 isn't a pin, because npx will resolve a newer 2.x tomorrow. --yes stops the first-run install prompt from hanging an unattended job.
  • Prefer --tool-args-json for typed arguments. --tool-arg zip=10001 JSON-parses the value and sends the number 10001, which a string schema rejects. --tool-args-json sends exactly what you wrote.
  • Never pipe stderr into jq. stdout is the result; stderr carries diagnostics, with the one-line error envelope last.
Exit codeMeaning
0Success
1Usage or unexpected error
2No MCP App on the tool (--app-info probe)
3Server requires authentication
4Server unreachable (DNS, refused, timeout)
5Tool error: isError: true, or tool not found
6--strict found an error-severity schema problem

Exit 5 is the one that surprises people migrating from v1, where a failing tool call exited 0. If your pipeline "broke" after upgrading, a tool was probably failing all along. Read the class with tail -1 on the captured stderr and jq -r '.error.code'; our JSON formatter helps when you're staring at a big tools/list payload by hand.

Failures by symptom

Garbage on stdout. The spec says a stdio server MUST NOT write anything to stdout that isn't a valid MCP message, and messages are newline-delimited with no embedded newlines. A stray console.log in Node or a print() in Python breaks the stream. Log to stderr instead; the client may capture or ignore it, and per the spec it shouldn't treat stderr output as an error.

Works in the Inspector, fails in the client. Almost always environment. The MCP debugging guide points out that a client-launched server's working directory may be undefined (like / on macOS), so relative paths break, and that stdio servers inherit only a limited, platform-dependent set of environment variables. Use absolute paths for command and any file arguments, and pass secrets through the client's env block. The Filesystem MCP server config is a good example of an absolute directory argument.

Version or capability errors. The same guide lists the codes to look for: UnsupportedProtocolVersionError (-32022) lists the server's supported versions in its data field; a request missing io.modelcontextprotocol/protocolVersion or clientCapabilities in _meta gets -32602; and a server that needs a capability you didn't declare returns MissingRequiredClientCapabilityError (-32021). Check the request's _meta in the Protocol monitor against the server/discover response.

The Apps tab is blank in Docker or over SSH. The sandbox listens on 6275 and the browser reaches it directly, so you have to publish or forward that port as well as 6274.

Failures by client

Claude Desktop. Logs live in ~/Library/Logs/Claude on macOS, %APPDATA%\Claude\logs on Windows and ~/.config/Claude/logs on Linux. Follow them with tail -n 20 -F ~/Library/Logs/Claude/mcp*.log. After changing server code, fully quit and reopen the app; the guide notes that closing the window isn't enough.

Claude Code. claude mcp list and claude mcp get <name> show what's configured, and /mcp inside a session shows status and handles OAuth. The Claude Code MCP docs document MCP_TIMEOUT for slow-starting servers (MCP_TIMEOUT=10000 claude is a 10-second timeout) and say output over 10,000 tokens triggers a warning, with a default cap of 25,000 tokens adjustable through MAX_MCP_OUTPUT_TOKENS. They also explain that -- separates Claude's own options from the server command; forget it and your server's flags get parsed as Claude's. More habits are in our Claude Code tips post and on the Claude Code page.

VS Code. Run MCP: List Servers, pick the server and choose Show Output to open its output channel, per Manage MCP servers. The same page warns not to run a Docker stdio server in detached mode (-d), because the client needs the stdio connection. And don't paste a portable mcpServers file into VS Code's own format, which uses a servers key.

Don't expose the Inspector

The Inspector spawns processes and holds your OAuth tokens, so treat it like a shell. The web client README is blunt: the API token stops other origins from driving the backend through your browser, but GET / embeds the token, so anyone who can load the page can act as you. v2 refuses HOST=0.0.0.0 unless you set DANGEROUSLY_BIND_ALL_INTERFACES=true. In Docker, publish to loopback only:

docker run --rm -p 127.0.0.1:6274:6274 ghcr.io/modelcontextprotocol/inspector:latest

Secrets go to the OS keychain where one exists; on headless Linux, SSH sessions and containers they fall back to ~/.mcp-inspector/secrets.json, unencrypted unless you supply a key, according to the README. Our MCP security guide covers the server side of the same problem.

A checklist before you blame the client

  • node -v satisfies ^22.23.4 || ^24.22.1 || >=26.12.1.
  • The server connects in the Inspector with the right --protocol-era.
  • Nothing but JSON-RPC reaches stdout; logs go to stderr and show in Console.
  • tools/list --strict exits 0.
  • Each tool works with --tool-args-json and realistic inputs.
  • The client config uses absolute paths and passes every env var the server reads.
  • You've read the client's own log (Claude Desktop's mcp*.log, VS Code's output channel, /mcp in Claude Code) before changing code.
AE

Written by AIDToolStack Editorial

Researched from official documentation, specifications and vendor pages, listed under Sources below. Last checked November 2026.

Sources

  1. github.com/modelcontextprotocol/inspector
  2. github.com/modelcontextprotocol/inspector/blob/main/docs/v1-to-v2-migration.md
  3. github.com/modelcontextprotocol/inspector/blob/main/docs/mcp-server-configuration.md
  4. github.com/modelcontextprotocol/inspector/blob/main/docs/cli-smoke-testing.md
  5. github.com/modelcontextprotocol/inspector/blob/main/clients/tui/README.md
  6. github.com/modelcontextprotocol/inspector/blob/main/clients/web/README.md
  7. registry.npmjs.org/@modelcontextprotocol/inspector
  8. nodejs.org/en/blog/vulnerability/october-2026-security-releases
  9. modelcontextprotocol.io/specification/versioning
  10. modelcontextprotocol.io/specification/2026-07-28/changelog
  11. modelcontextprotocol.io/specification/2026-07-28/basic/transports
  12. modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio
  13. modelcontextprotocol.io/legacy/tools/debugging
  14. code.claude.com/docs/en/mcp
  15. code.visualstudio.com/docs/agents/run/manage-mcp-servers
  16. code.visualstudio.com/docs/copilot/customization/mcp-servers

Related Posts

Explore on AIDToolStack

Discover tools and servers featured in our directory.

MCP Servers

Trigger.dev Jobs MCP ServerManage Trigger.dev background jobs from your AI coding assistant. Monitor job runs, trigger tasks manually, inspect execution logs, manage schedules, and debug failed runs. The server provides operational visibility into your background job infrastructure — see which tasks are running, queued, or failed, and take action. Your AI can help diagnose job failures from execution logs, retry failed tasks, and optimize concurrency configurations for better throughput.Tailscale Network MCP ServerManage your Tailscale mesh VPN network from your AI coding assistant. View connected devices, manage ACLs, configure exit nodes, check device status, and manage DNS settings. The server provides visibility into your Tailscale network — see which machines are online, troubleshoot connectivity issues, manage network access policies, and configure routes. Useful for developers managing distributed infrastructure where Tailscale provides secure networking between services.Portainer Docker MCP ServerManage Docker environments through Portainer's API from your AI coding assistant. Control containers, images, networks, and volumes across multiple Docker hosts and Kubernetes clusters. The server provides tools for container lifecycle management, image pulling and building, stack deployment, and resource monitoring. Portainer's multi-environment management makes this server particularly valuable for teams managing containers across development, staging, and production environments.

Reviews

Sign in to leave a review.

No reviews yet. Be the first!

Comments

Sign in to leave a comment.

No comments yet. Be the first!

Sponsor Our Newsletter

Reach thousands of developers who are actively evaluating AI tools, MCP servers, and dev infrastructure. Our weekly newsletter goes to engaged technical decision-makers.

Growing subscriber baseHigh open rates

All sponsored content is clearly labeled per our editorial policy.