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 2803866
Browse filesBrowse the repository at this point in the historyBrowse files
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
Copy file name to clipboardExpand all lines: docs/mcp-server-configuration.md
+23-20Lines changed: 23 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,10 @@ Client-specific options (the web server port, the CLI method to invoke, TUI navi
9
9
1.**From a file** — a catalog or session file listing one or more servers.
10
10
2.**Ad-hoc** — a command (stdio) or a URL (SSE / Streamable HTTP) on the command line.
11
11
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.
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:
68
71
69
72
- A `--method` is required — a CLI invocation with no method exits with `Method is required.`
70
73
-**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
|`--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 ||
|`--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 ||
114
117
115
118
**`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.
116
119
@@ -186,13 +189,13 @@ A catalog carrying these fields:
| 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 |
| 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 |
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).
0 commit comments