You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 20527dc
Browse filesBrowse the repository at this point in the historyBrowse files
docs: address Copilot review on the v1 → v2 migration guide
- Sandbox port: the Apps tab needs a second, dynamic listener, so
"no second port" was wrong for Docker/remote deployments. Qualify the
architecture section, add a pinned-port Docker recipe, and add a
troubleshooting entry.
- Node floor: npm only warns EBADENGINE unless engine-strict is set, so
npx does not refuse to run on an older Node.
- v1 default list: the web UI persisted its list in localStorage; only
the on-disk default catalog is new.
- The v1→v2 --server example needs --cli (and a --method) to select an
entry; note there is no one-entry web equivalent.
- New behavior change #4: an ambiguous URL path (neither /mcp nor /sse)
now errors instead of falling back to SSE.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01SFXDQBEjvjCEBhmYkmw79a
Copy file name to clipboardExpand all lines: docs/v1-to-v2-migration.md
+41-10Lines changed: 41 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,7 +30,7 @@ The three changes most likely to bite an existing setup:
30
30
31
31
## Requirements
32
32
33
-
v2 requires **Node `>=22.19.0`** (v1 required `>=22.7.5`). The floor comes from `undici@^8`, used for HTTP proxy support. `npx` will refuse to run on an older Node rather than fail obscurely later.
33
+
v2 requires **Node `>=22.19.0`** (v1 required `>=22.7.5`). The floor comes from `undici@^8`, used for HTTP proxy support. npm only _warns_ about an `engines` mismatch (`EBADENGINE`) unless you have `engine-strict=true` set, so an older Node won't stop you at install time — it fails later, obscurely. Check `node -v` first.
34
34
35
35
## What no longer ships
36
36
@@ -58,13 +58,15 @@ If you depend on one of them directly, drop it and use the root package's `mcp-i
58
58
59
59
v1 ran **two** processes: a React client on `6274` and an "MCP Proxy" on `6277` that held the actual MCP connections. The browser talked to the proxy over HTTP, authenticating with `MCP_PROXY_AUTH_TOKEN`.
60
60
61
-
v2 runs **one** web server on `6274`. It serves the SPA and exposes `/api/*`, which the browser calls with `x-mcp-remote-auth: Bearer <MCP_INSPECTOR_API_TOKEN>`. There is no second port to expose, forward, or allow through a firewall.
61
+
v2 runs **one** web server on `6274`. It serves the SPA and exposes `/api/*`, which the browser calls with `x-mcp-remote-auth: Bearer <MCP_INSPECTOR_API_TOKEN>`. The proxy port is gone: nothing needs `6277` exposed, forwarded, or allowed through a firewall.
62
62
63
63
Consequences:
64
64
65
65
- `SERVER_PORT` no longer selects a port you browse. (It is read as a fallback for the MCP Apps sandbox server's port — see `MCP_SANDBOX_PORT` below.)
66
66
- `MCP_PROXY_FULL_ADDRESS` has no v2 equivalent and is ignored. It existed to tell the browser where a non-default proxy lived; there is no proxy.
67
-
- Docker only needs `-p 6274:6274`. The v1 recipe published `6277` as well.
67
+
- Docker needs `-p 6274:6274` for the UI, where the v1 recipe published `6277` as well.
68
+
69
+
⚠️ **`6274` is not the only listener.** The web backend also starts a **separate MCP Apps sandbox server**, on a dynamic port by default. It is only used by the Apps tab, and on plain loopback it needs no attention — but the browser reaches it directly, so anywhere the Inspector is _not_ served from the browser's own machine (Docker, a remote host, an SSH tunnel) you must pin it with `MCP_SANDBOX_PORT` and expose/forward that port too, or the Apps tab won't load. This is a different port from v1's proxy — it carries no MCP traffic — but it is still a second port. See [MCP Apps caveats](../clients/web/README.md#hosting-on-a-network).
68
70
69
71
## Launching
70
72
@@ -102,7 +104,7 @@ So:
102
104
103
105
- **`--config`in v2 is the read-only role.** Point it at a file you didn't write — a coworker's, a client application's, one checked into a repo — and the Inspector guarantees it won't touch the bytes, including any plaintext secrets in them. This is close to v1's behavior, minus the write-back that never existed anyway.
104
106
- **`--catalog` is new** and is what you want if you'd like the web UI to add, edit, and remove servers.
105
-
-**Neither is required.** With no source flag, v2 uses the default catalog `~/.mcp-inspector/mcp.json`, creating it if absent. v1 had no such default — it started empty every time.
107
+
- **Neither is required.** With no source flag, v2 uses the default catalog `~/.mcp-inspector/mcp.json`, creating it if absent. v1 had no default file: the CLI started with nothing unless you passed `--config`, and the web UI's list lived in the browser's `localStorage` — per-browser, and invisible to the CLI.
⚠️ One caveat on that last line: **`--server` only selects under `--cli`.**On the web client it is a no-op that logs a warning, and the TUI rejects it as an unknown option. In the web UI you pick the server from the list after it loads.
121
+
⚠️ **`--server` only selects under `--cli`**, which is why the v2 line above gains the mode flag (and, being a CLI invocation, a `--method`). On the web client `--server` is a no-op that logs a warning and the UI loads **every** entry in the file; the TUI rejects it as an unknown option. There is no web equivalent of "open just this one entry" — you pick the server from the list after it loads.
120
122
121
123
```bash
122
124
# v2 — let the Inspector manage the file (web UI can edit it)
@@ -153,7 +155,7 @@ Every v1 CLI flag still exists in v2 and means the same thing. Nothing was renam
153
155
| `-e KEY=VALUE` | same | |
154
156
| `--config <path>` | same flag, **narrower meaning** | see [above](#--config-vs---catalog) |
155
157
| `--server <name>` | same | now `--cli`-only |
156
-
|`[target...]`| same | but see the target-ordering rule below |
158
+
| `[target...]` | same | but see the target-ordering **and** URL-transport rules below |
157
159
158
160
New in v2, with no v1 equivalent:
159
161
@@ -175,7 +177,7 @@ See the [CLI README](../clients/cli/README.md) for the full surface.
So the web example above, run under `--cli`, would have `--config /etc/myserver.conf` consumed as the Inspector's read-only-session flag (and then rejected as a catalog/ad-hoc conflict). There is currently no way to pass a leading-dash argument through to a stdio server on the `--cli` command line — put it in the server entry's `args`in a catalog or config file instead.
236
238
239
+
### 4. An ambiguous URL path no longer guesses a transport
240
+
241
+
With no `--transport`, v2 infers it from the URL's path suffix — and **only** from that:
Transport type not specified and could not be determined from URL: <url>.
251
+
```
252
+
253
+
v1 fell back to SSE for an unrecognized path, so a server at e.g. `https://example.com/api` connected without a flag. In v2 the same command stops with the error above; pass `--transport http` (or `sse`) explicitly. The suffix match is exact, so a trailing slash (`…/mcp/`) is ambiguous too.
254
+
255
+
This applies to every client's command line — CLI, TUI, and `--web` (which prints the message and exits `1`). The **browser deep link** is the one exception: `?serverUrl=…` with no `transport` param defaults to `http`.
256
+
237
257
Stdout is otherwise compatible: the default `text` format still pretty-prints the result as `JSON.stringify(result, null, 2)`, exactly as v1 did.
# v2 — one port; the image already sets the wildcard-bind opt-in
316
+
# v2 — no proxy port; the image already sets the wildcard-bind opt-in
297
317
docker run --rm -p 6274:6274 ghcr.io/modelcontextprotocol/inspector:latest
298
318
```
299
319
300
320
Notes:
301
321
322
+
- **The Apps tab needs one more published port.** The sandbox server is dynamic by default and the `Dockerfile` `EXPOSE`s only `6274`, so the recipe above covers everything _except_ MCP Apps. To use them, pin and publish the sandbox port as well:
323
+
324
+
```bash
325
+
docker run --rm -p 6274:6274 -p 6280:6280 -e MCP_SANDBOX_PORT=6280 \
326
+
ghcr.io/modelcontextprotocol/inspector:latest
327
+
```
328
+
302
329
- The v2 image sets `DANGEROUSLY_BIND_ALL_INTERFACES=true` internally (a container must bind `0.0.0.0` to be reachable through `-p`). Setting a bare `HOST=0.0.0.0` **outside** a container now exits with an error.
303
330
- **If you remap the published port** (`-p 8080:6274`), the browser's origin no longer matches the in-container port, so set`ALLOWED_ORIGINS=http://localhost:8080,http://127.0.0.1:8080` (or run `-e CLIENT_PORT=8080 -p 8080:8080`) or connects will 403.
304
331
- The image runs as non-root and has a `HEALTHCHECK` that assumes `--web`; add `--no-healthcheck` when running `--cli` / `--tui`.
@@ -314,6 +341,10 @@ Notes:
314
341
315
342
**"The Inspector connects to a different server than I named."** Check flag order — under `--cli` the target must precede all flags, or it is silently dropped in favor of the catalog.
316
343
344
+
**"`Transport type not specified and could not be determined from URL`."** The path ends in neither `/mcp` nor `/sse`, so v2 refuses to guess where v1 fell back to SSE. Pass `--transport http` or `--transport sse`.
345
+
346
+
**"The Apps tab is blank in Docker / over SSH."** The MCP Apps sandbox is a second, dynamic port. Pin it with `MCP_SANDBOX_PORT` and publish/forward it too — see [MCP Apps caveats](../clients/web/README.md#hosting-on-a-network).
347
+
317
348
**"`HOST=0.0.0.0` exits with an error."** That's the wildcard-bind guard. Bind a specific address instead, or set`DANGEROUSLY_BIND_ALL_INTERFACES=true`if you genuinely need all interfaces. See [Host binding & the origin allow-list](../clients/web/README.md#host-binding--the-origin-allow-list).
318
349
319
350
**"I need v1 back."**`npx @modelcontextprotocol/inspector@v1-latest`.
0 commit comments