# Test and debug an MCP server from the command line or a UI with npx @modelcontextprotocol/inspector

> The MCP Inspector runs from npx as a web UI, a scriptable --cli mode and a terminal UI, and the CLI mode can list tools, call one and fail a CI job on a wrong answer.

## Answer

Run `npx @modelcontextprotocol/inspector <command>` to open a web UI for your server, or add `--cli --method tools/list` to list its tools from a script. One package provides three clients: web (the default), `--cli` and `--tui`. It needs Node 22.19.0 or newer. Checked 2026-09-28 against the Inspector documentation for MCP specification 2026-07-28. For connection failures, see [[mcp-connection-errors]]. This page is about testing.

## Details

### 1. Use the web UI

```sh
npx @modelcontextprotocol/inspector node build/index.js
```

The command prints a URL that contains a one-time session token. Open that URL rather than typing `localhost:6274` yourself, because the backend rejects requests without the token. In the UI, connect, open **Tools**, pick a tool, fill the form and call it.

### 2. Call a tool from the command line

The CLI connects, sends the one request named by `--method`, prints the result and exits.

```sh
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list
```

For a remote server, use a URL and `--transport http`. This is the live endpoint of this wiki (tools `search_answers` and `get_answer`), which we ran on 2026-09-28:

```sh
npx @modelcontextprotocol/inspector --cli https://wiki.drfritzi.at/mcp --transport http \
  --method tools/call --tool-name search_answers --tool-arg query=inspector --format json
```

It printed one JSON object of the form `{"result":{"content":[{"type":"text","text":"[...]"}],"isError":false}}` and exited 0. `--tool-arg key=value` parses the value as JSON, so `count=1` is a number. `--tool-args-json '{"zip":"10001"}'` passes the object as is.

The mode flag (`--web`, `--cli`, `--tui`) is only recognised at the front of the command line. Everything after the first other token goes to the client, so a later `--cli` reaches your server as its own argument.

### 3. Choose the protocol era

The Inspector connects as a legacy client by default and does not probe. Our run of `--method initialize` against the endpoint above reported `protocolVersion` `2025-11-25`. To test the 2026-07-28 behaviour, put `"protocolEra": "auto"` (probe `server/discover`, fall back to `initialize`) or `"modern"` (pin 2026-07-28, no fallback) on the server entry in a config file:

```json
{ "mcpServers": { "wiki": { "type": "http", "url": "https://wiki.drfritzi.at/mcp", "protocolEra": "auto" } } }
```

Then run `--cli --config ./servers.json --server wiki --method initialize`. With `auto` we got `2026-07-28` back.

### 4. Fail a CI job on a wrong answer

`--format json` prints a single JSON object with no banners, so it pipes into `jq`. Exit codes are stable: `3` needs authentication, `4` server unreachable, `5` tool error or tool not found. A close variant of this script (with two extra `jq` checks) passed when we ran it on 2026-09-28. To test your own server, replace `URL` and start your server before it (for example with `node build/index.js &`, or use the stdio form from step 2).

```sh
#!/usr/bin/env bash
set -euo pipefail
URL="https://wiki.drfritzi.at/mcp"   # placeholder: your server
INSPECT="npx -y @modelcontextprotocol/inspector --cli $URL --transport http"

$INSPECT --method tools/list --format json \
  | jq -e '.result.tools | map(.name) | index("search_answers")' > /dev/null

$INSPECT --method tools/call --tool-name search_answers --tool-arg query=inspector --format json \
  | jq -e '.result.isError == false' > /dev/null

set +e; $INSPECT --method tools/call --tool-name no_such_tool >/dev/null 2>err.json; code=$?; set -e
[ "$code" -eq 5 ] || { echo "expected exit 5, got $code"; exit 1; }
```

On a non-zero exit the CLI also writes one JSON line to stderr, such as `{"error":{"code":"tool_not_found","message":"Tool 'no_such_tool' not found on server."}}`. For servers behind OAuth, add `--stored-auth-only` so CI fails fast instead of waiting for a browser.

### Which view shows which symptom

| Symptom | Where to look |
|---|---|
| Tool missing from the list | `--method tools/list`, or the **Tools** tab |
| Wrong arguments or schema | **Tools** tab: schema form and rendered result |
| A stdio server crashes or prints diagnostics | **Console** tab (the process's stderr) |
| HTTP status, header or body problem | **Network** tab (HTTP and SSE servers only) |
| Malformed JSON-RPC or a spec error | **Protocol** tab (JSON-RPC transcript) |
| Server logs missing on a 2026-07-28 connection | **Logs** tab: the log level is set per request, and `Off` sends none |
| CI needs to branch on failure | CLI exit code 3, 4 or 5 |

### Common mistakes

- Putting `--cli` after your server command. It must come first.
- Testing only the default legacy era, then shipping to 2026-07-28 clients.
- Piping the default `--format text` output into `jq`. Use `--format json`.
- Opening `localhost:6274` without the token from the printed URL.
- Debugging a "Not connected" tool error (for example [issue 1082](https://github.com/modelcontextprotocol/servers/issues/1082)) inside the client. Run the server alone in the Inspector first, to separate a server fault from client configuration.

## See also

- [[mcp-connection-errors]]
- [[mcp-server-typescript-minimal]]
- [[mcp-transports-stdio-vs-http]]
- [[mcp-2026-07-28-changes]]
- [[what-is-mcp]]

## Sources

- [MCP Inspector (overview)](https://modelcontextprotocol.io/docs/tools/inspector)
- [MCP Inspector — CLI client](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/cli)
- [MCP Inspector — Web client](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/web)
- [MCP Inspector — Protocol eras](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/protocol-eras)
- [MCP Inspector — Configuration and flags](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/configuration)
- [modelcontextprotocol/servers issue 1082](https://github.com/modelcontextprotocol/servers/issues/1082)

## Sources

- [MCP Inspector (overview)](https://modelcontextprotocol.io/docs/tools/inspector)
- [MCP Inspector — CLI client](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/cli)
- [MCP Inspector — Web client](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/web)
- [MCP Inspector — Protocol eras](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/protocol-eras)
- [MCP Inspector — Configuration and flags](https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector/configuration)
- [modelcontextprotocol/servers issue 1082: Error executing MCP tool: Not connected](https://github.com/modelcontextprotocol/servers/issues/1082)