01572c31b9
The field table said this payload is "merged into every outgoing request", which is true of web and the TUI but not the CLI — it never passes the persisted value to its client, so the setting is inert for `--cli` runs (#2093). Scope the claim and point at the per-invocation `--metadata` flag as the CLI workaround, so a CLI user isn't told a setting works when it doesn't. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh Signed-off-by: cliffhall <cliff@futurescale.com>
236 lines
21 KiB
Markdown
236 lines
21 KiB
Markdown
# MCP server configuration
|
|
|
|
How to tell the Inspector **which MCP server(s) to connect to**. This model is shared by the Web, CLI, and TUI clients — the flags below are defined separately by each client but resolved by the same code in `core/mcp/node/config.ts`, so they behave identically everywhere except where noted.
|
|
|
|
Client-specific options (the web server port, the CLI method to invoke, TUI navigation) live in each client's README: [web](../clients/web/README.md) · [cli](../clients/cli/README.md) · [tui](../clients/tui/README.md).
|
|
|
|
## Two ways to specify a server
|
|
|
|
1. **From a file** — a catalog or session file listing one or more servers.
|
|
2. **Ad-hoc** — a command (stdio) or a URL (SSE / Streamable HTTP) on the command line.
|
|
|
|
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:
|
|
|
|
- **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.
|
|
- **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.
|
|
|
|
## From a file: `--catalog` vs. `--config`
|
|
|
|
These look interchangeable and are not. The difference is **who owns the file**.
|
|
|
|
| | `--catalog <path>` | `--config <path>` |
|
|
| ------------------------- | -------------------------------------------------- | ---------------------------------------------------- |
|
|
| Writable by the Inspector | Yes — this is the Inspector's own server list | No. Served as-is; never written, seeded, or migrated |
|
|
| When the file is missing | Created and seeded (see below) | **Errors** |
|
|
| Default path | `~/.mcp-inspector/mcp.json`, or `MCP_CATALOG_PATH` | none — must be passed |
|
|
| Editable in the web UI | Yes | No (catalog CRUD is hidden) |
|
|
| Use it for | your own working set of servers | a read-only session against a file you didn't write |
|
|
|
|
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.
|
|
|
|
### What a seeded catalog contains
|
|
|
|
A missing **writable** catalog is created on first use, but **what gets written differs by client**:
|
|
|
|
- **Web** seeds two sample servers (`DEFAULT_SEED_CONFIG` in `core/mcp/serverList.ts`) so a first launch has something to connect to immediately:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"filesystem-server-default": {
|
|
"type": "stdio",
|
|
"command": "npx",
|
|
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
|
|
},
|
|
"everything-server-default": {
|
|
"type": "stdio",
|
|
"command": "npx",
|
|
"args": ["-y", "@modelcontextprotocol/server-everything"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
- **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.
|
|
|
|
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.
|
|
|
|
## Ad-hoc servers
|
|
|
|
Instead of a file, name one server directly:
|
|
|
|
```bash
|
|
# stdio — everything positional is the command to spawn
|
|
mcp-inspector node build/index.js
|
|
|
|
# HTTP / SSE
|
|
mcp-inspector --server-url https://api.example.com/mcp --transport http
|
|
```
|
|
|
|
Those run as written in the default (web) mode. Under `--cli` two extra rules apply:
|
|
|
|
- A `--method` is required — a CLI invocation with no method exits with `Method is required.`
|
|
- **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:
|
|
|
|
```bash
|
|
mcp-inspector --cli node build/index.js --method tools/list # ✅ target, then flags
|
|
mcp-inspector --cli --method tools/list node build/index.js # ❌ target is dropped
|
|
```
|
|
|
|
The second form does not error — `node build/index.js` is silently discarded and the Inspector falls back to your catalog, so it "works" against the wrong server. `--tui` has no such rule; Commander parses its arguments in any order.
|
|
|
|
### The `--` separator
|
|
|
|
A bare `--` is meaningful on every surface, but **web/tui and cli split it in opposite directions**. Read the one you're using.
|
|
|
|
**Web and TUI — everything _after_ `--` goes to the target command.** This is how you pass a flag the Inspector would otherwise consume:
|
|
|
|
```bash
|
|
mcp-inspector node build/index.js -- --config /etc/myserver.conf --verbose
|
|
```
|
|
|
|
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 post-`--` tokens land in the same place.
|
|
|
|
They differ on **when you need it**, though. Web sets `allowUnknownOption()` + `allowExcessArguments()`, so a dash flag the Inspector does not define (`--verbose`) already falls through to the target without a separator — on web `--` is only needed for a flag the Inspector _does_ define. The TUI sets neither, so any unrecognized dash flag is a parse error: on the TUI you need `--` for **every** dash argument meant for the server.
|
|
|
|
**CLI — reversed: everything _before_ `--` is the server target, everything _after_ is the Inspector's own options.**
|
|
|
|
```bash
|
|
mcp-inspector --cli node build/index.js -- --method tools/list
|
|
```
|
|
|
|
So under `--cli` the separator does **not** protect an argument from the Inspector — it does the opposite, and the web example above, run verbatim, would have `--config /etc/myserver.conf` consumed as a read-only-session flag (then rejected as a catalog/ad-hoc conflict). Leading-dash arguments for the server still get through; they just go on the other side of the separator, where the whole pre-`--` run is taken as the target verbatim:
|
|
|
|
```bash
|
|
mcp-inspector --cli node build/index.js --config /etc/myserver.conf --verbose -- --method tools/list
|
|
```
|
|
|
|
Without a `--` on the line the target is only the leading run of **non-dash** tokens, so the separator is required whenever the server itself takes flags.
|
|
|
|
## The shared flags
|
|
|
|
| Flag | Meaning | Notes |
|
|
| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| `--catalog <path>` | Writable catalog file | Env fallback `MCP_CATALOG_PATH` |
|
|
| `--config <path>` | Read-only session file | Errors if absent |
|
|
| `--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 |
|
|
| `--transport <type>` | `stdio`, `sse`, or `http` | Ad-hoc targets only — enforced on cli/tui; web exempts `--transport stdio` (see above) |
|
|
| `--server-url <url>` | Server URL for SSE / Streamable HTTP | Ad-hoc targets only |
|
|
| `--cwd <path>` | Working directory for a stdio server process | |
|
|
| `-e <KEY=VALUE>` | Environment variable for a stdio server; repeatable | |
|
|
| `--header "Name: Value"` | HTTP header for an HTTP/SSE server; repeatable | On web, requires an ad-hoc HTTP/SSE server |
|
|
| `[target...]` | Positional command or URL for one ad-hoc server | |
|
|
|
|
**`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.
|
|
|
|
## File format
|
|
|
|
The file is the familiar MCP client-config shape — an `mcpServers` object keyed by server name — plus Inspector-specific per-server settings.
|
|
|
|
**stdio**
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"my-server": {
|
|
"type": "stdio",
|
|
"command": "node",
|
|
"args": ["build/index.js"],
|
|
"env": { "API_KEY": "…" },
|
|
"cwd": "/path/to/server"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Streamable HTTP / SSE**
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"my-http-server": {
|
|
"type": "http",
|
|
"url": "https://api.example.com/mcp",
|
|
"headers": { "X-Tenant": "acme" }
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
`type` may be `stdio`, `http` (Streamable HTTP), or `sse`.
|
|
|
|
### Inspector-specific per-server fields
|
|
|
|
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.
|
|
|
|
| Field | Default | Meaning |
|
|
| -------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `protocolEra` | `"legacy"` | `"legacy"` \| `"auto"` \| `"modern"` — which protocol era to negotiate, orthogonal to the transport |
|
|
| `modernLogLevel` | `"debug"` | Per-request log level stamped on modern connections, or `"off"`. Legacy connections ignore it |
|
|
| `roots` | — | Roots advertised via the `roots` client capability; each is `{ uri, name? }` |
|
|
| `metadata` | — | Default `_meta` payload merged into every outgoing request — a JSON object, values may be any JSON. Web and TUI only today; see the CLI note below |
|
|
| `connectionTimeout` / `requestTimeout` | — | Timeouts in ms |
|
|
| `taskTtl` | `60000` | TTL in ms for tasks created via "Run as task" (`DEFAULT_TASK_TTL_MS`) |
|
|
| `autoRefreshOnListChanged` | `false` | Refresh lists automatically on `*/list_changed` instead of only flagging the indicator |
|
|
| `paginatedLists` | `false` | Fetch tools/resources/prompts one page at a time instead of auto-aggregating |
|
|
| `advertisedExtensions` | — | Per-extension overrides for what the Inspector declares in `capabilities.extensions` |
|
|
| `maxFetchRequests` | `1000` | Network-log retention for this server (`DEFAULT_MAX_FETCH_REQUESTS`); `0` means unlimited |
|
|
| `oauth` | — | `{ clientId, clientSecret, scopes, authorizationParams, authorizationUrl, tokenUrl, enterpriseManaged, onInsufficientScope }` |
|
|
|
|
`metadata` is a JSON **object**, and its values may be any JSON — an object, an array, a number, a boolean, `null` — not only a string. Nothing in the MCP spec restricts `_meta` value types, and the SDK models the field as a passthrough object, so the Inspector does not narrow it either ([#1910](https://github.com/modelcontextprotocol/inspector/issues/1910)). Edit it in Server Settings → Request Metadata, which is a JSON editor rather than the key/value rows `headers` and `env` use; text that is not a JSON object is flagged inline and not applied.
|
|
|
|
```jsonc
|
|
"metadata": {
|
|
"tenant": "acme",
|
|
"trace": { "id": "abc123", "sampled": true },
|
|
"features": ["apps", "tasks"]
|
|
}
|
|
```
|
|
|
|
> **Not yet applied by the CLI.** The web client and the TUI both send this payload on every request. The CLI does not — it never passes the persisted value to its client, so a `metadata` entry is currently inert for `--cli` runs ([#2093](https://github.com/modelcontextprotocol/inspector/issues/2093)). Use the per-invocation `--metadata` flag there in the meantime.
|
|
|
|
> **Reading an older file.** Before #1910 this field was a `[{ "key": …, "value": … }]` pair array. That shape is still **read**, so an existing `mcp.json` keeps working unchanged; it is never written back, so the field is rewritten as an object the next time the Inspector saves the entry.
|
|
|
|
`oauth.authorizationParams` is a string→string record of extra query parameters merged into the OAuth **authorization request** URL only — never the token request. Use it for provider-specific hints the core specs don't standardize (Keycloak's `kc_idp_hint`, OIDC's `login_hint` / `prompt` / `acr_values`, Auth0's `audience`). The protocol-critical parameters — `client_id`, `code_challenge`, `code_challenge_method`, `redirect_uri`, `resource`, `response_type`, `scope`, `state` — are **reserved**: the web form rejects them inline, and any that reach the merge anyway are dropped with a warning rather than overriding what the flow set (overriding them breaks PKCE, the CSRF state binding, or RFC 8707). Edit them in Server Settings → Authorization ("Additional authorization parameters"), beside Scopes.
|
|
|
|
`oauth.authorizationUrl` and `oauth.tokenUrl` override the `authorization_endpoint` and `token_endpoint` that authorization-server metadata discovery resolved. The Inspector deliberately has no such fields by default — it resolves both from the AS's metadata document, exactly as a real MCP host does — but a server under development often advertises its _production_ authorization server while you want to hit staging. Set either (they are independent) to an absolute `http(s)` URL and it replaces what the metadata returned, for both the authorization request and the token request; leave blank to use discovery. A malformed value is flagged inline in the form and dropped with a warning at connect time rather than failing the connection. Edit them in Server Settings → Authorization ("Authorization URL override" / "Token URL override").
|
|
|
|
They redirect the **endpoints**, not the authorization server's identity: `issuer` is left exactly as discovery returned it, because that is what RFC 9207 / SEP-2352 validate the callback's `iss` against to defend against an authorization-server mix-up. So they fit alternate endpoints of the _same_ logical issuer — a staging deployment fronting the same issuer, a local proxy. Point one at an authorization server advertising a **different** issuer and the callback is rejected as an issuer mismatch before the code is redeemed; that is the mix-up defense working, and it is not disabled to make the override succeed.
|
|
|
|
They are **not applied under enterprise-managed authorization** (`oauth.enterpriseManaged`), for the same reason `oauth.authorizationParams` isn't: that flow authorizes against the enterprise IdP — a different authorization server, whose OIDC discovery would otherwise be rewritten too, pointing the IdP login (or the IdP code exchange) at the resource server's authorization server.
|
|
|
|
> Because the override is applied to the _discovered metadata document_, a server whose authorization server publishes no metadata at all is unaffected — there the SDK falls back to `/authorize` and `/token` on the AS origin, and there is nothing to override.
|
|
|
|
A catalog carrying these fields:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"my-modern-server": {
|
|
"type": "http",
|
|
"url": "https://api.example.com/mcp",
|
|
"protocolEra": "modern",
|
|
"modernLogLevel": "info",
|
|
"roots": [{ "uri": "file:///Users/me/project", "name": "project" }]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Per-client behavior
|
|
|
|
| | Web | CLI | TUI |
|
|
| ---------------------------- | ------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------ |
|
|
| Seeds a missing catalog with | two sample servers | `{}` | `{}` |
|
|
| `--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'` |
|
|
| `--` separator | yes — after `--` → target | **reversed** — before `--` → target | yes — after `--` → target (Commander default) |
|
|
| OAuth client flags | no (uses the Client Settings dialog) | yes | yes |
|
|
| Catalog CRUD | yes | read-only consumer | read-only consumer |
|
|
|
|
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).
|
|
|
|
## Related
|
|
|
|
- [Migrating from v1 to v2](./v1-to-v2-migration.md) — why `--config` means something narrower than it did in v1, and what `--catalog` replaced.
|
|
- [Launcher and config consolidation](./launcher-config-consolidation-plan.md) — how the launcher and the shared config processor fit together.
|
|
- [Reviewing an MCP App](./mcp-app-review.md) — the CLI-first App review recipe.
|