Skip to content

Commit 2803866

Browse files
cliffhallclaude
andcommitted
docs: note the --transport stdio divergence and scope the web --server warning
Third review pass on #1812. All markdown, all one-clause precision edits. - Added the second conflict-matrix divergence. The doc enumerated only the `--header` axis, where web is stricter; there is a second where web is looser: cli/tui count any `--transport` as an ad-hoc marker (`hasAdHocServerOptions`), while web exempts `--transport stdio`. So `--catalog c.json --transport stdio` errors on cli/tui and is silently accepted on web. Noted alongside the `--header` divergence and on the `--transport` row, whose "Ad-hoc targets only" read as universal. - Scoped the web `--server` warning. It fires only in the catalog and config branches; with an ad-hoc target the flag is dropped with no output at all, which is where a reader is most likely to have expected it to work. - Dropped the "both consequences of how it splits argv" framing: the target-first rule is, but `--method` is a plain validation unrelated to the split, and the claim invited the reader to look for a link that isn't there. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01Txmv2qqv3yeKgRzoqXytzD
1 parent ae1e4c4 commit 2803866

1 file changed

Lines changed: 23 additions & 20 deletions

File tree

‎docs/mcp-server-configuration.md‎

Lines changed: 23 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,10 @@ Client-specific options (the web server port, the CLI method to invoke, TUI navi
99
1. **From a file** — a catalog or session file listing one or more servers.
1010
2. **Ad-hoc** — a command (stdio) or a URL (SSE / Streamable HTTP) on the command line.
1111

12-
The two do not mix. `--catalog` and `--config` are mutually exclusive with each other, and neither combines with an ad-hoc target. All three clients apply the same **source-selection** rules — the CLI and TUI through the shared `serverSourceConflict` helper (`core/mcp/node/config.ts`), web through an equivalent inline matrix in `clients/web/server/run-web.ts`. Web is deliberately stricter on one axis: it also rejects `--header` alongside `--catalog`/`--config`, because the CLI and TUI merge `--header` into per-server settings and web does not.
12+
The two do not mix. `--catalog` and `--config` are mutually exclusive with each other, and neither combines with an ad-hoc target. All three clients apply the same **source-selection** rules — the CLI and TUI through the shared `serverSourceConflict` helper (`core/mcp/node/config.ts`), web through an equivalent inline matrix in `clients/web/server/run-web.ts`. The two implementations diverge on two narrow axes, in opposite directions:
13+
14+
- **Web is stricter on `--header`:** it also rejects `--header` alongside `--catalog`/`--config`, because the CLI and TUI merge `--header` into per-server settings and web does not.
15+
- **Web is looser on `--transport stdio`:** the CLI and TUI treat _any_ `--transport` as an ad-hoc marker, so `--catalog c.json --transport stdio` is rejected as a catalog/ad-hoc conflict there; web excludes `stdio` from that test and accepts the same combination, silently ignoring the flag.
1316

1417
## From a file: `--catalog` vs. `--config`
1518

@@ -64,7 +67,7 @@ mcp-inspector node build/index.js
6467
mcp-inspector --server-url https://api.example.com/mcp --transport http
6568
```
6669

67-
Those run as written in the default (web) mode. Under `--cli` two extra rules apply, both consequences of how it splits argv (see the `--` separator section below):
70+
Those run as written in the default (web) mode. Under `--cli` two extra rules apply:
6871

6972
- A `--method` is required — a CLI invocation with no method exits with `Method is required.`
7073
- **The target must come first.** The CLI reads the leading run of non-dash tokens as the target, so anything after the first flag is no longer part of it:
@@ -100,17 +103,17 @@ So under `--cli` the separator does **not** protect an argument from the Inspect
100103

101104
## The shared flags
102105

103-
| Flag | Meaning | Notes |
104-
| ------------------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
105-
| `--catalog <path>` | Writable catalog file | Env fallback `MCP_CATALOG_PATH` |
106-
| `--config <path>` | Read-only session file | Errors if absent |
107-
| `--server <name>` | Select one named server from the file | **Selects only under `--cli`.** Web accepts it, warns, and ignores it (the UI lists every server); the TUI does not define it and rejects it as an unknown option |
108-
| `--transport <type>` | `stdio`, `sse`, or `http` | Ad-hoc targets only |
109-
| `--server-url <url>` | Server URL for SSE / Streamable HTTP | Ad-hoc targets only |
110-
| `--cwd <path>` | Working directory for a stdio server process | |
111-
| `-e <KEY=VALUE>` | Environment variable for a stdio server; repeatable | |
112-
| `--header "Name: Value"` | HTTP header for an HTTP/SSE server; repeatable | On web, requires an ad-hoc HTTP/SSE server |
113-
| `[target...]` | Positional command or URL for one ad-hoc server | |
106+
| Flag | Meaning | Notes |
107+
| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
108+
| `--catalog <path>` | Writable catalog file | Env fallback `MCP_CATALOG_PATH` |
109+
| `--config <path>` | Read-only session file | Errors if absent |
110+
| `--server <name>` | Select one named server from the file | **Selects only under `--cli`.** Web ignores it — warning with `--catalog`/`--config`, silently with an ad-hoc target; the TUI does not define it and rejects it as an unknown option |
111+
| `--transport <type>` | `stdio`, `sse`, or `http` | Ad-hoc targets only — enforced on cli/tui; web exempts `--transport stdio` (see above) |
112+
| `--server-url <url>` | Server URL for SSE / Streamable HTTP | Ad-hoc targets only |
113+
| `--cwd <path>` | Working directory for a stdio server process | |
114+
| `-e <KEY=VALUE>` | Environment variable for a stdio server; repeatable | |
115+
| `--header "Name: Value"` | HTTP header for an HTTP/SSE server; repeatable | On web, requires an ad-hoc HTTP/SSE server |
116+
| `[target...]` | Positional command or URL for one ad-hoc server | |
114117

115118
**`MCP_CATALOG_PATH` and ad-hoc targets differ by client.** The **CLI** ignores the env var when an ad-hoc target is given (a positional command, `--server-url`, or `--transport`), so a shell that exports it can still run one-off ad-hoc invocations without tripping the catalog/ad-hoc conflict. **Web and TUI read it unconditionally** — with it exported, an ad-hoc invocation such as `mcp-inspector --tui node build/index.js` is rejected as `--catalog cannot be combined with an ad-hoc server URL/command`. Unset the variable for that invocation on those two surfaces.
116119

@@ -186,13 +189,13 @@ A catalog carrying these fields:
186189

187190
## Per-client behavior
188191

189-
| | Web | CLI | TUI |
190-
| ---------------------------- | ------------------------------------------------ | --------------------------------------- | ------------------------------------------------ |
191-
| Seeds a missing catalog with | two sample servers | `{}` | `{}` |
192-
| `--server` | accepted but a no-op — warns, lists every server | yes — the only surface where it selects | not defined — `error: unknown option '--server'` |
193-
| `--` separator | yes — after `--` → target | **reversed** — before `--` → target | yes — after `--` → target (Commander default) |
194-
| OAuth client flags | no (uses the Client Settings dialog) | yes | yes |
195-
| Catalog CRUD | yes | read-only consumer | read-only consumer |
192+
| | Web | CLI | TUI |
193+
| ---------------------------- | ------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------ |
194+
| Seeds a missing catalog with | two sample servers | `{}` | `{}` |
195+
| `--server` | a no-op — warns with a file source, silent with an ad-hoc one | yes — the only surface where it selects | not defined — `error: unknown option '--server'` |
196+
| `--` separator | yes — after `--` → target | **reversed** — before `--` → target | yes — after `--` → target (Commander default) |
197+
| OAuth client flags | no (uses the Client Settings dialog) | yes | yes |
198+
| Catalog CRUD | yes | read-only consumer | read-only consumer |
196199

197200
The CLI and TUI do not perform catalog CRUD yet — they are read consumers — so the writable/read-only split currently surfaces there only as **seed-if-missing** (`--catalog` / default) vs. **error-if-missing** (`--config`). Full writable persistence is tracked in [#1482](https://github.com/modelcontextprotocol/inspector/issues/1482) / [#1432](https://github.com/modelcontextprotocol/inspector/issues/1432).
198201

0 commit comments

Comments
 (0)