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 177739e
Browse filesBrowse the repository at this point in the historyBrowse files
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
Copy file name to clipboardExpand all lines: docs/mcp-server-configuration.md
+53-43Lines changed: 53 additions & 43 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,19 +9,19 @@ 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 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.
13
13
14
14
## From a file: `--catalog` vs. `--config`
15
15
16
16
These look interchangeable and are not. The difference is **who owns the file**.
17
17
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 |
| 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|
25
25
26
26
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.
27
27
@@ -50,7 +50,7 @@ A missing **writable** catalog is created on first use, but **what gets written
50
50
51
51
-**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.
52
52
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.
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:
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.**
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.
|`--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 ||
90
100
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.
92
102
93
103
## File format
94
104
@@ -130,19 +140,19 @@ The file is the familiar MCP client-config shape — an `mcpServers` object keye
130
140
131
141
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.
132
142
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 |
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