MCP Inspector v2 Stuck on Connecting? Use CLI or TUI

If MCP Inspector v2 stays on Connecting... while the same MCP server works in Claude Code or another client, test the exact server with Inspector's current CLI or TUI before changing the server. A successful initialize or tools/list from the same package proves the server is reachable and narrows the failure to the web path, configuration handoff, or browser state.

The safest workaround is to keep using the current v2 package in CLI or TUI mode. Pinning the legacy v1 UI can confirm a version-specific regression, but it should be a short-lived diagnostic fallback because v1 receives bug fixes only and is not the current general-use line.

Match the Exact Symptom

Use this guide when all of these are true:

• npx @modelcontextprotocol/inspector launches the v2 web client;

• the web UI remains on Connecting... without a useful error;

• the target is a known MCP server over stdio, SSE, or Streamable HTTP; and

• another client, Inspector v1, or a direct server check can reach the same target.

This pattern became visible after Inspector v2 shipped. One report reproduced the silent hang with Streamable HTTP while Claude Code and Inspector 1.0.1 connected to the same server. Independent users then reproduced it with other servers and stdio. A second report said v2 could not connect to either HTTP or stdio servers while v1 still worked.

A browser request that remains open is not proof by itself. SSE and Streamable HTTP can intentionally keep a response open. Classify the failure by comparing clients against the same target and configuration.

Prerequisites

Before testing:

• use Node.js 22.19.0 or later, the current Inspector v2 floor;

• preserve the exact server command, URL, transport, working directory, headers, and environment;

• remove credentials before copying logs or configuration into an issue; and

• choose a harmless check such as initialize or tools/list.

Record the runtime and Inspector help output:

node --version
npx @modelcontextprotocol/inspector@latest --help

Expected result: Node meets the supported floor and the help output lists web, CLI, and TUI modes. If Node is older, update it before treating the connection failure as the v2 regression.

Step 1: Freeze One Test Target

Do not compare different server commands, ports, or credentials. Put the working target in one MCP configuration file when possible:

{
  "mcpServers": {
    "test-server": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

For stdio, preserve the actual command and arguments:

{
  "mcpServers": {
    "test-server": {
      "type": "stdio",
      "command": "node",
      "args": ["build/index.js"]
    }
  }
}

Use --config for a read-only diagnostic session. Inspector will read that file without seeding, migrating, or editing it.

Step 2: Test the Current v2 TUI

Run the same package and configuration without the browser client:

npx @modelcontextprotocol/inspector@latest --tui --config mcp.json

The TUI loads every server in the file. Select test-server and press C to connect.

Expected result: the connection completes and the Resources, Tools, Prompts, Protocol, Network, or Console views become available. Open Tools and confirm that the expected tool names appear. Do not call a write-capable tool just to test connectivity.

For a one-off stdio process, you can pass the command directly:

npx @modelcontextprotocol/inspector@latest --tui node build/index.js

If the server needs a flag that Inspector also recognizes, place a bare -- before the server's flags. This prevents the TUI from consuming them as its own options.

Step 3: Get a Deterministic CLI Result

The CLI is better evidence than a spinner because it exits with a stable status and can print JSON.

For a configured server:

npx @modelcontextprotocol/inspector@latest --cli \
  --config mcp.json \
  --server test-server \
  --method initialize \
  --format json

Then list tools:

npx @modelcontextprotocol/inspector@latest --cli \
  --config mcp.json \
  --server test-server \
  --method tools/list \
  --format json

Expected result: initialize returns server information, protocol version, and capabilities; tools/list returns the expected tool definitions and exits 0.

For a remote Streamable HTTP server, the equivalent one-off check is:

npx @modelcontextprotocol/inspector@latest --cli \
  https://example.com/mcp \
  --transport http \
  --method tools/list \
  --format json

Do not put bearer tokens or API keys directly in shell history. Use the server's supported OAuth flow or a protected configuration source.

Step 4: Interpret the Comparison

This comparison works because v2 ships web, CLI, and TUI clients in one package. It changes one surface at a time while keeping the target and release constant.

Step 5: Capture a Minimal Upstream Report

Include:

1. Inspector version and Node version;

2. operating system;

3. transport type;

4. a redacted target configuration;

5. whether web, TUI, CLI, and v1 connect;

6. the last relevant Protocol, Network, or Console event; and

7. a minimal server or public fixture when safe.

State the expected result and the observed result separately. If a request remains pending, name the method and URL path, but do not assume a long-lived stream is the root cause.

Never attach tokens, OAuth state, provider API keys, private headers, or a full environment dump. The Inspector proxy can spawn local processes, so keep it bound to loopback and do not expose it to an untrusted network for reproduction.

When a Temporary v1 Pin Is Reasonable

If both current v2 interactive surfaces fail and you need to confirm the older behavior, run the exact legacy version only long enough to reproduce:

npx @modelcontextprotocol/inspector@1.0.1

If v1 connects to the same target, record that result and return to current v2 CLI or TUI for ongoing work. Do not replace @latest with an unbounded old version in team documentation or CI. Do not expose the legacy proxy beyond localhost.

Common Failure Modes

Why This Workaround Works

Inspector v2 has three clients but shares the server-resolution and MCP runtime underneath. The CLI removes browser rendering and interactive state from the path. The TUI keeps interactive exploration while removing the browser and web proxy presentation layer.

When either one connects to the identical target, you have not fixed the server. You have isolated the failing layer and preserved a productive way to inspect tools, resources, prompts, and protocol traffic while the web issue is unresolved.

For a broader server checklist, use the MCP Inspector testing guide. If calls connect but arguments arrive as strings, follow the empty JSON schema fix.

Reduce the Integration Surface You Own

If the MCP server exists only to reach a third-party API, decide whether maintaining its local process, provider authentication, transport compatibility, and Inspector setup is part of your product advantage. A managed integration layer can expose a typed capability while keeping provider credentials out of the repository.

Give your coding agent this instruction:

Follow https://aident.ai/SETUP.md

Then ask it to search for one connected read-only Action, inspect the exact schema, preflight the request, and execute one narrow call. The measurable success condition is one typed provider response without copying the provider API key into source code, shell history, or the task transcript.

For the security boundary, read how to give AI agents API access without exposing keys and how to reduce MCP token usage.

Ready to test it? Set up Aident Loadout, run one read-only Action, and keep the provider credential out of the project.

Sources

• MCP Inspector v2 hangs silently with Streamable HTTP, opened July 29 and updated August 4, 2026

• Independent v2 web and TUI connection report, opened August 3, 2026

• Official MCP Inspector repository and v2 client overview, accessed August 4, 2026

• Official MCP Inspector TUI guide, accessed August 4, 2026

• Official MCP Inspector CLI guide, accessed August 4, 2026

• Official MCP server configuration guide, accessed August 4, 2026

• Official MCP debugging guide, accessed August 4, 2026

This article reflects the public v2 reports and official Inspector documentation available on August 4, 2026. Recheck the open issues, current package requirements, and release notes before choosing a long-lived workaround.