Skip to content

Commit 177739e

Browse files
cliffhallclaude
andcommitted
docs: correct the -- separator, MCP_CATALOG_PATH scope, and two field defaults
Review of #1812 caught a real inversion: the `--` separator section described web's semantics as if they were shared with the CLI, but the two are opposite. Web (and, via Commander's default end-of-options handling, the TUI) append everything *after* `--` to the target command; the CLI treats everything *before* `--` as the target and everything *after* as the Inspector's own options. The doc's copy-pasteable example therefore did the opposite of what its prose promised under `--cli`. Split into the two forms with a correct example for each, and note that the CLI has no way to pass a leading-dash argument to a stdio server on the command line. Also: - Scope the `MCP_CATALOG_PATH` ad-hoc guard to the CLI. Web and TUI read the env var unconditionally, so an ad-hoc invocation with it exported trips the catalog/ad-hoc conflict there. - Reword "all three clients reject the combination identically": they share the source-selection rules, but web uses its own inline matrix and is stricter, additionally rejecting `--header` with `--catalog`/`--config`. - Fill in the real defaults for `taskTtl` (60000) and `maxFetchRequests` (1000), which the surrounding text needs in order to explain omit-on-default writes. - Note that seeding is once per *file*, not per client: all three surfaces default to the same path, so whichever runs first decides the contents. - Correct the per-client `--` row, which claimed the TUI has no support. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01Txmv2qqv3yeKgRzoqXytzD
1 parent d2f772c commit 177739e

1 file changed

Lines changed: 53 additions & 43 deletions

File tree

‎docs/mcp-server-configuration.md‎

Lines changed: 53 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,19 @@ 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 reject the combination identically (`serverSourceConflict`).
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.
1313

1414
## From a file: `--catalog` vs. `--config`
1515

1616
These look interchangeable and are not. The difference is **who owns the file**.
1717

18-
| | `--catalog <path>` | `--config <path>` |
19-
| --- | --- | --- |
20-
| Writable by the Inspector | Yes — this is the Inspector's own server list | No. Served as-is; never written, seeded, or migrated |
21-
| When the file is missing | Created and seeded (see below) | **Errors** |
22-
| Default path | `~/.mcp-inspector/mcp.json`, or `MCP_CATALOG_PATH` | none — must be passed |
23-
| Editable in the web UI | Yes | No (catalog CRUD is hidden) |
24-
| Use it for | your own working set of servers | a read-only session against a file you didn't write |
18+
| | `--catalog <path>` | `--config <path>` |
19+
| ------------------------- | -------------------------------------------------- | ---------------------------------------------------- |
20+
| Writable by the Inspector | Yes — this is the Inspector's own server list | No. Served as-is; never written, seeded, or migrated |
21+
| When the file is missing | Created and seeded (see below) | **Errors** |
22+
| Default path | `~/.mcp-inspector/mcp.json`, or `MCP_CATALOG_PATH` | none — must be passed |
23+
| Editable in the web UI | Yes | No (catalog CRUD is hidden) |
24+
| Use it for | your own working set of servers | a read-only session against a file you didn't write |
2525

2626
Use `--config` when pointing the Inspector at a config file belonging to something else — a coworker's, a client application's, one checked into a repo. It guarantees the Inspector will not touch the bytes on disk, including any plaintext secrets in them.
2727

@@ -50,7 +50,7 @@ A missing **writable** catalog is created on first use, but **what gets written
5050

5151
- **CLI and TUI** seed an empty `{ "mcpServers": {} }` (`seedEmptyCatalog` in `core/mcp/node/config.ts`). They are non-interactive or list-driven, so sample entries would be noise rather than a starting point.
5252

53-
Seeding happens **once**, only when the file is absent. An existing catalog is never re-seeded, and a read-only `--config` is never seeded on any surface.
53+
Seeding happens **once per file**, only when that file is absent — not once per client. All three surfaces default to the _same_ path (`~/.mcp-inspector/mcp.json`, `getDefaultMcpConfigPath()` in `core/storage/store-io.ts`), so whichever client runs first decides the contents: run `--cli` first and a later `--web` opens the empty catalog it wrote, with no sample servers. An existing catalog is never re-seeded, and a read-only `--config` is never seeded on any surface.
5454

5555
## Ad-hoc servers
5656

@@ -66,29 +66,39 @@ mcp-inspector --cli --server-url https://api.example.com/mcp --transport http
6666

6767
### The `--` separator
6868

69-
The **web and cli** clients split their arguments at a bare `--` and forward everything after it to the target command as its own arguments. This is how you pass a flag the Inspector would otherwise consume:
69+
A bare `--` is meaningful on every surface, but **web/tui and cli split it in opposite directions**. Read the one you're using.
70+
71+
**Web and TUI — everything _after_ `--` goes to the target command.** This is how you pass a flag the Inspector would otherwise consume:
7072

7173
```bash
7274
mcp-inspector node build/index.js -- --config /etc/myserver.conf --verbose
7375
```
7476

75-
Without the separator, `--config` would be read as the Inspector's own read-only-session flag.
77+
Without the separator, `--config` would be read as the Inspector's own read-only-session flag. Web splits explicitly (`clients/web/server/run-web.ts`); the TUI has no split of its own but Commander's default end-of-options handling appends the remainder to the target, so the effect is the same.
78+
79+
**CLI — reversed: everything _before_ `--` is the server target, everything _after_ is the Inspector's own options.**
80+
81+
```bash
82+
mcp-inspector --cli node build/index.js -- --method tools/list
83+
```
84+
85+
So under `--cli` the separator does **not** protect an argument from the Inspector — it does the opposite, and the web example above would have `--config /etc/myserver.conf` consumed as a read-only-session flag (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.
7686

7787
## The shared flags
7888

79-
| Flag | Meaning | Notes |
80-
| --- | --- | --- |
81-
| `--catalog <path>` | Writable catalog file | Env fallback `MCP_CATALOG_PATH` |
82-
| `--config <path>` | Read-only session file | Errors if absent |
83-
| `--server <name>` | Select one named server from the file | **Web and CLI only.** The TUI loads every server in the file and you pick interactively |
84-
| `--transport <type>` | `stdio`, `sse`, or `http` | Ad-hoc targets only |
85-
| `--server-url <url>` | Server URL for SSE / Streamable HTTP | Ad-hoc targets only |
86-
| `--cwd <path>` | Working directory for a stdio server process | |
87-
| `-e <KEY=VALUE>` | Environment variable for a stdio server; repeatable | |
88-
| `--header "Name: Value"` | HTTP header for an HTTP/SSE server; repeatable | On web, requires an ad-hoc HTTP/SSE server |
89-
| `[target...]` | Positional command or URL for one ad-hoc server | |
89+
| Flag | Meaning | Notes |
90+
| ------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------- |
91+
| `--catalog <path>` | Writable catalog file | Env fallback `MCP_CATALOG_PATH` |
92+
| `--config <path>` | Read-only session file | Errors if absent |
93+
| `--server <name>` | Select one named server from the file | **Web and CLI only.** The TUI loads every server in the file and you pick interactively |
94+
| `--transport <type>` | `stdio`, `sse`, or `http` | Ad-hoc targets only |
95+
| `--server-url <url>` | Server URL for SSE / Streamable HTTP | Ad-hoc targets only |
96+
| `--cwd <path>` | Working directory for a stdio server process | |
97+
| `-e <KEY=VALUE>` | Environment variable for a stdio server; repeatable | |
98+
| `--header "Name: Value"` | HTTP header for an HTTP/SSE server; repeatable | On web, requires an ad-hoc HTTP/SSE server |
99+
| `[target...]` | Positional command or URL for one ad-hoc server | |
90100

91-
`MCP_CATALOG_PATH` is honored **only when no ad-hoc target is given** (no 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.
101+
**`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.
92102

93103
## File format
94104

@@ -130,19 +140,19 @@ The file is the familiar MCP client-config shape — an `mcpServers` object keye
130140

131141
These have no analog in the broader `mcp.json` ecosystem. Each is **omitted on write when it equals its default**, so a round-trip through the Inspector keeps the file diff minimal.
132142

133-
| Field | Default | Meaning |
134-
| --- | --- | --- |
135-
| `protocolEra` | `"legacy"` | `"legacy"` \| `"auto"` \| `"modern"` — which protocol era to negotiate, orthogonal to the transport |
136-
| `modernLogLevel` | `"debug"` | Per-request log level stamped on modern connections, or `"off"`. Legacy connections ignore it |
137-
| `roots` | — | Roots advertised via the `roots` client capability; each is `{ uri, name? }` |
138-
| `metadata` | — | Default `_meta` keys merged into every outgoing request |
139-
| `connectionTimeout` / `requestTimeout` | — | Timeouts in ms |
140-
| `taskTtl` | — | TTL in ms for tasks created via "Run as task" |
141-
| `autoRefreshOnListChanged` | `false` | Refresh lists automatically on `*/list_changed` instead of only flagging the indicator |
142-
| `paginatedLists` | `false` | Fetch tools/resources/prompts one page at a time instead of auto-aggregating |
143-
| `advertisedExtensions` | — | Per-extension overrides for what the Inspector declares in `capabilities.extensions` |
144-
| `maxFetchRequests` | — | Network-log retention for this server; `0` means unlimited |
145-
| `oauth` | — | `{ clientId, clientSecret, scopes, enterpriseManaged, onInsufficientScope }` |
143+
| Field | Default | Meaning |
144+
| -------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------- |
145+
| `protocolEra` | `"legacy"` | `"legacy"` \| `"auto"` \| `"modern"` — which protocol era to negotiate, orthogonal to the transport |
146+
| `modernLogLevel` | `"debug"` | Per-request log level stamped on modern connections, or `"off"`. Legacy connections ignore it |
147+
| `roots` | — | Roots advertised via the `roots` client capability; each is `{ uri, name? }` |
148+
| `metadata` | — | Default `_meta` keys merged into every outgoing request |
149+
| `connectionTimeout` / `requestTimeout` | — | Timeouts in ms |
150+
| `taskTtl` | `60000` | TTL in ms for tasks created via "Run as task" (`DEFAULT_TASK_TTL_MS`) |
151+
| `autoRefreshOnListChanged` | `false` | Refresh lists automatically on `*/list_changed` instead of only flagging the indicator |
152+
| `paginatedLists` | `false` | Fetch tools/resources/prompts one page at a time instead of auto-aggregating |
153+
| `advertisedExtensions` | — | Per-extension overrides for what the Inspector declares in `capabilities.extensions` |
154+
| `maxFetchRequests` | `1000` | Network-log retention for this server (`DEFAULT_MAX_FETCH_REQUESTS`); `0` means unlimited |
155+
| `oauth` | — | `{ clientId, clientSecret, scopes, enterpriseManaged, onInsufficientScope }` |
146156

147157
A catalog carrying these fields:
148158

@@ -162,13 +172,13 @@ A catalog carrying these fields:
162172

163173
## Per-client behavior
164174

165-
| | Web | CLI | TUI |
166-
| --- | --- | --- | --- |
167-
| Seeds a missing catalog with | two sample servers | `{}` | `{}` |
168-
| `--server` | yes (currently warns — the UI lists every server) | yes | no — all servers are listed |
169-
| `--` separator | yes | yes | no |
170-
| OAuth client flags | no (uses the Client Settings dialog) | yes | yes |
171-
| Catalog CRUD | yes | read-only consumer | read-only consumer |
175+
| | Web | CLI | TUI |
176+
| ---------------------------- | ------------------------------------------------- | ----------------------------------- | --------------------------------------------- |
177+
| Seeds a missing catalog with | two sample servers | `{}` | `{}` |
178+
| `--server` | yes (currently warns — the UI lists every server) | yes | no — all servers are listed |
179+
| `--` separator | yes — after `--` → target | **reversed** — before `--` → target | yes — after `--` → target (Commander default) |
180+
| OAuth client flags | no (uses the Client Settings dialog) | yes | yes |
181+
| Catalog CRUD | yes | read-only consumer | read-only consumer |
172182

173183
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).
174184

0 commit comments

Comments
 (0)