Configuration and flags changeddocs/2026-07-28/tools/inspector/configuration
Nearest release: v2.1.295, published 5 hours after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 8 Oct 2026 12:58 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 8 Oct 2026 13:07 UTC.
Upstream edited
Recorded here
Lines+129added
Lines−25removed
From line
13
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits3to this page, all time
### Secret store variables ## Where secrets are stored ### How the store is chosen ### The file store ### Where the active store is reported ### Moving back to a keychain
The whole hunk
from line 13, old and new numbered
/
from line 13
1313
1414Everything below belongs to a client.
1515
16<Note>
17 The package also installs a second, separate bin, `mcpdo`, the experimental
18 [connection client](/docs/2026-07-28/tools/inspector/mcpdo). It is not reached
19 through the launcher and takes no mode flag.
20</Note>
21
1622## Choosing servers
1723
1824### `--catalog` vs. `--config`
1925
20All three clients resolve `--catalog` and `--config` through the same shared code, so each flag behaves the same in the web app, the CLI, and the TUI. Where the two differ from each other is the table below.
26The CLI and TUI resolve `--catalog` and `--config` through the same shared code, and the web client applies the same rules, so each flag means the same thing in all three. Where the two differ from each other is the table below.
2127
2228| | `--catalog <path>` | `--config <path>` |
2329| - | - | - |
from line 33
2733| **Editable in the web UI?** | Yes. | No. |
2834| **Use it for** | Your own working set of servers. | A read-only session against someone else's config file. |
2935
30The two are **mutually exclusive**, and neither combines with an ad-hoc target. Passing both is rejected identically by all three clients.
36The two are **mutually exclusive**, and neither combines with an ad-hoc target. Passing both is rejected identically by all three clients. The web client is stricter in one respect: it also rejects `--header` and `--protocol-era` alongside a file, where the CLI and TUI apply them on top of the file's settings.
3137
3238<Note>
33 **What a freshly seeded catalog contains depends on the client.** The web backend seeds two sample servers, so a first launch has something to connect to immediately:
39 **What a freshly seeded catalog contains depends on the client.** The web backend seeds three sample servers, so a first launch has something to connect to immediately:
3440
3541 ```json theme={null}
3642 {
from line 50
4450 "type": "stdio",
4551 "command": "npx",
4652 "args": ["-y", "@modelcontextprotocol/server-everything"]
53 },
54 "example-server-default": {
55 "type": "streamable-http",
56 "url": "https://example-server.modelcontextprotocol.io/mcp"
4757 }
4858 }
4959 }
from line 87
7787| - | - | - |
7888| `--catalog <path>` | Writable catalog file. | None |
7989| `--config <path>` | Read-only session file. | None |
80| `--server <name>` | Pick one named server out of the file. | **Web and CLI only.** The TUI loads every server in the file and lets you choose interactively. |
90| `--server <name>` | Pick one named server out of the file. | **Selects only in the CLI.** The web client accepts it but ignores it with a note, listing every server. The TUI doesn't define it (an unknown-option error) and lets you choose interactively. |
8191| `--transport <type>` | `stdio`, `sse`, or `http`. | Ad-hoc targets only. |
8292| `--server-url <url>` | Server URL for SSE/HTTP. | Ad-hoc targets only. |
8393| `--cwd <path>` | Working directory for a stdio server process. | None |
8494| `-e <KEY=VALUE>` | Environment variables for a stdio server. Repeatable. | None |
8595| `--header "Name: Value"` | HTTP headers for an HTTP/SSE server. Repeatable. | Requires an ad-hoc HTTP/SSE server on the web client. |
96| `--protocol-era <era>` | `legacy`, `auto`, or `modern`: the [protocol era](/docs/2026-07-28/tools/inspector/protocol-eras) to negotiate. | Requires an ad-hoc target on the web client. The CLI and TUI also let it override a file's `protocolEra`. |
97| `--skill-catalog-max-skills <n>` / `--skill-catalog-max-bytes <n>` | Budget for a skills verification run (most skills, most bytes read). | **CLI and TUI only.** Overrides the file's `skillCatalogMaxSkills` / `skillCatalogMaxBytes`. |
8698| `[target...]` | Positional command/URL for one ad-hoc server. | None |
8799
88100### The `--` separator
89101
90The **web and CLI** clients split their arguments at a bare `--` and pass everything after it to the target command as its own arguments. This is how you pass a flag that the Inspector would otherwise eat:
102The **web and TUI** clients pass everything after a bare `--` to the target command as its own arguments. This is how you pass a flag that the Inspector would otherwise eat:
91103
92104```bash theme={null}
93105mcp-inspector node build/index.js -- --config /etc/myserver.conf --verbose
from line 107
95107
96108Without the separator, `--config` would be read as the Inspector's own read-only-session flag.
97109
110**The CLI splits the other way:** everything *before* `--` is the target, and everything after it is the Inspector's own options. Without a `--`, the CLI's target is only the leading run of arguments that don't start with a dash, so a server that takes flags needs the separator:
111
112```bash theme={null}
113mcp-inspector --cli node build/index.js --config /etc/myserver.conf --verbose -- --method tools/list
114```
115
98116## Web-only flags
99117
100118| Flag | Meaning |
from line 129
111129| `--client-id <id>` | None | OAuth client ID for a static client. Overrides `client.json`. |
112130| `--client-secret <secret>` | None | OAuth client secret for confidential clients. Overrides `client.json`. |
113131| `--client-metadata-url <url>` | None | CIMD metadata URL. Overrides `client.json`. |
114| `--callback-url <url>` | `MCP_OAUTH_CALLBACK_URL` | The redirect URI sent to the authorization server. Default `http://127.0.0.1:6276/oauth/callback`. Must be a loopback host (`127.0.0.1` or `localhost`): the local callback listener receives the authorization code over plaintext `http`, so any other host is rejected and there is no flag to override this. |
132| `--callback-url <url>` | `MCP_OAUTH_CALLBACK_URL` | The redirect URI sent to the authorization server. Default `http://127.0.0.1:6276/oauth/callback`. Must be a loopback host (`localhost`, `127.0.0.1` or any other `127.x.x.x` address, or `[::1]`): the local callback listener receives the authorization code over plaintext `http`, so any other host is rejected and there is no flag to override this. |
115133
116134## CLI-only flags
117135
from line 137
119137
120138| Group | Flags |
121139| - | - |
122| **What to invoke** | `--method`, `--tool-name`, `--tool-arg`, `--tool-args-json`, `--uri`, `--prompt-name`, `--prompt-args`, `--log-level`, `--metadata`, `--tool-metadata` |
123| **How to run it** | `--connect-timeout`, `--format`, `--app-info` |
124| **Auth** | `--use-stored-auth`, `--stored-auth-only`, `--relogin`, `--wait-for-auth`, `--list-stored-auth`, `--print-handoff` |
140| **What to invoke** | `--method`, `--tool-name`, `--tool-arg`, `--tool-args-json`, `--uri`, `--cursor`, `--prompt-name`, `--prompt-args`, `--log-level`, `--metadata`, `--tool-metadata`, `--rename` |
141| **How to run it** | `--connect-timeout`, `--format`, `-q` / `--quiet`, `--output`, `--output-format`, `--app-info`, `--advertise-apps`, `--strict`, `--verify`, `--require-digests`, `--completion <shell>` (`bash`, `zsh`, or `fish`) |
142| **Auth** | `--use-stored-auth`, `--stored-auth-only`, `--relogin`, `--no-revoke`, `--wait-for-auth`, `--list-stored-auth`, `--print-handoff` |
125143
126144## Environment variables
127145
128Environment variables split the same way as flags: two are read by the launcher itself, and the rest belong to the CLI and TUI or to the web backend.
146Environment variables split the same way as flags: two are read by the launcher itself, and the rest belong to the CLI and TUI, to the web backend, or to every client (the secret store).
129147
130148### Read by the launcher
131149
132150| Variable | Effect |
133151| - | - |
134| `MCP_DEBUG` | Append the error stack to a top-level failure. Only when set to a meaningful value: `0`, `false`, and empty read as off. |
152| `MCP_DEBUG` | Append the error stack to a top-level `--web` or `--tui` failure (a `--cli` failure always prints its [JSON error envelope](/docs/2026-07-28/tools/inspector/cli#exit-codes-and-error-envelopes) instead). Only when set to a meaningful value: `0`, `false`, and empty read as off. |
135153| `DEBUG` | Same, with the same meaningful-value rule, so a stray `DEBUG=0` doesn't turn stack traces on and `DEBUG` still works as the npm `debug` package's namespace filter. |
136154
137155### CLI and TUI
138156
139| Variable | Effect |
140| - | - |
141| `MCP_CATALOG_PATH` | Fallback for `--catalog`. Honored only when no ad-hoc target is given, so a shell that exports it can still run one-off ad-hoc invocations. |
142| `MCP_CLIENT_CONFIG_PATH` | Fallback for `--client-config`. |
143| `MCP_OAUTH_CALLBACK_URL` | Fallback for `--callback-url`. |
144| `MCP_STORAGE_DIR` | Directory for the OAuth state file (`<dir>/oauth.json`). |
145| `MCP_INSPECTOR_OAUTH_STATE_PATH` | Per-file override of the OAuth state path. Takes precedence over `MCP_STORAGE_DIR`. |
146| `MCP_AUTO_OPEN_ENABLED` | Controls browser auto-open and whether interactive OAuth may run without a TTY. `true` forces auto-open and allows OAuth prompts without a TTY, `false` never opens, and unset opens only on a TTY. |
157Some of these are read by the web backend too, as the **Read by** column shows.
147158
159| Variable | Read by | Effect |
160| - | - | - |
161| `MCP_CATALOG_PATH` | Web, CLI, TUI | Fallback for `--catalog`. The CLI honors it only when no ad-hoc target is given, so a shell that exports it can still run one-off ad-hoc invocations. The web client and TUI apply it regardless, so combining it with an ad-hoc target is rejected there. |
162| `MCP_CLIENT_CONFIG_PATH` | CLI, TUI | Fallback for `--client-config`. |
163| `MCP_OAUTH_CALLBACK_URL` | CLI, TUI | Fallback for `--callback-url`. |
164| `MCP_STORAGE_DIR` | Web, CLI, TUI | Storage directory. Relocates the OAuth state file (`<dir>/oauth.json`) and the secrets file (`<dir>/secrets.json`). |
165| `MCP_INSPECTOR_OAUTH_STATE_PATH` | CLI, TUI | Per-file override of the OAuth state path. Takes precedence over `MCP_STORAGE_DIR`. |
166| `MCP_AUTO_OPEN_ENABLED` | Web, CLI | Controls browser auto-open. `false` never opens one. In the CLI, `true` forces auto-open and lets interactive OAuth run without a TTY, and unset opens only on a TTY. In the web client, unset opens the UI at launch. The TUI does not read it. |
167
148168### Web backend environment variables
149169
150170| Variable | Effect |
151171| - | - |
152172| `MCP_INSPECTOR_API_TOKEN` | Pin the [session token](/docs/2026-07-28/tools/inspector/web#the-session-token) instead of generating a random one per launch. |
153| `DANGEROUSLY_OMIT_AUTH` | Disable the `/api/*` token check entirely. |
154| `HOST` | Bind host. Defaults to `localhost`. |
173| `DANGEROUSLY_OMIT_AUTH` | Disable the `/api/*` token check entirely. Only `true` or `1` turn it off. |
174| `HOST` | Bind host. Defaults to `127.0.0.1`. |
155175| `CLIENT_PORT` | Web UI port. Defaults to `6274`. |
156176| `DANGEROUSLY_BIND_ALL_INTERFACES` | Required opt-in to bind a wildcard host (`0.0.0.0`, `::`, or any equivalent spelling). |
157177| `ALLOWED_ORIGINS` | Comma-separated origin allow-list. **Replaces** the default list rather than merging. |
158| `MCP_SANDBOX_PORT` | Pin the MCP Apps sandbox port, which is dynamic by default. |
178| `MCP_PROXY_AUTH_TOKEN` | Deprecated v1 name for `MCP_INSPECTOR_API_TOKEN`, used only when the new name is unset. |
179| `MCP_SANDBOX_PORT` | MCP Apps sandbox port. Defaults to `6275`; `0` asks the OS for a free port. |
180| `SERVER_PORT` | v1's proxy port, now only a fallback for the sandbox port when `MCP_SANDBOX_PORT` is unset or invalid. |
181| `MCP_APP_ORIGIN_PORT` | Port of the app-origin server used by MCP Apps that declare `_meta.ui.domain`. Defaults to `6278`; `0` asks the OS. |
182| `MCP_SANDBOX_FULL_ADDRESS` | Public URL of the MCP Apps sandbox proxy, for running behind a reverse proxy. |
183| `MCP_APP_ORIGIN_FULL_ADDRESS` | Public origin that `_meta.ui.domain` app documents are served from, for running behind a reverse proxy. |
184| `MCP_LOG_FILE` | Append the backend's structured (JSON lines) log to this file. |
185| `MCP_AUTO_OPEN_ENABLED` | `false` stops the browser from opening at launch. See [CLI and TUI](#cli-and-tui). |
186| `MCP_CATALOG_PATH`, `MCP_STORAGE_DIR` | As described under [CLI and TUI](#cli-and-tui). |
159187| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | Standard proxy routing for outbound MCP connections. |
160188
161189<Warning>
from line 191
163191 The web backend spawns processes and holds OAuth tokens, so anyone who can
164192 reach it can drive it.
165193</Warning>
194
195What the token does and does not protect is laid out under [The web backend and its API token](/docs/2026-07-28/tools/inspector/security#the-web-backend-and-its-api-token).
196
197### Secret store variables
198
199Read by **every** client: web, CLI, TUI, and [mcpdo](/docs/2026-07-28/tools/inspector/mcpdo). How they combine is described under [Where secrets are stored](#where-secrets-are-stored).
200
201| Variable | Effect |
202| - | - |
203| `MCP_INSPECTOR_SECRET_STORE` | `keyring`, `file`, or `memory` (case-insensitive) picks the store outright and skips the keychain probe. Empty counts as unset; any other value is ignored with a warning. |
204| `MCP_INSPECTOR_SECRET_FILE` | Path of the file store. Defaults to `secrets.json` in `MCP_STORAGE_DIR` when that is set, else `~/.mcp-inspector/secrets.json`. |
205| `MCP_INSPECTOR_SECRET_KEY_FILE` | Path of a file holding the passphrase that encrypts the file store (trailing line breaks removed). **Preferred**, and what Docker and Compose secrets are for. If the file is missing, unreadable or empty, the store refuses to read or write. |
206| `MCP_INSPECTOR_SECRET_KEY` | The passphrase itself. Use a generated, high-entropy value. Setting both key variables (with a non-blank `MCP_INSPECTOR_SECRET_KEY`) is an error. |
207| `MCP_INSPECTOR_PERSIST_TOKENS` | Which acquired OAuth tokens are persisted: `all` (default), `access` (no refresh tokens), or `none` (re-authorize every run). Client secrets are always persisted. |
208
209## Where secrets are stored
210
211The Inspector keeps credentials out of `mcp.json`, `client.json` and `oauth.json`, so that sharing, committing or syncing those files does not leak them. These are stored in a **secret store** instead:
212
213* acquired OAuth tokens (access, refresh and IdP session tokens);
214* each server's OAuth client secret, and the enterprise IdP client secret from Client Settings;
215* each stdio server's `env:` values. When an entry is saved, each `env` key stays in `mcp.json` with an empty value and the real value goes to the store.
216
217**`headers` are not moved.** They are saved in `mcp.json` exactly as written, so a header that carries a credential stays in the file.
218
219### How the store is chosen
220
221Each process picks one store, once, the first time it needs it: the web backend at startup, the CLI and TUI on first use. All clients use the same order:
222
2231. **`MCP_INSPECTOR_SECRET_STORE`**, if set to `keyring`, `file` or `memory`. Nothing is probed.
2242. **The OS keychain**, if a probe reaches it: Keychain on macOS, Credential Manager on Windows, the Secret Service (libsecret, such as GNOME Keyring or KWallet) on Linux. Entries go under the service name `mcp-inspector`. Most desktop installs stop here.
2253. **A fallback**, announced on stderr:
226 * `memory` in a container whose secrets directory is **not** on a mounted volume, because a file in the container's writable layer would be lost anyway;
227 * `file` everywhere else.
228
229| Where you run it | Store | Survives a restart? |
230| - | - | - |
231| Desktop macOS or Windows, or Linux with a Secret Service running | OS keychain | Yes |
232| Linux without libsecret or a Secret Service | File (`secrets.json`, mode `0600`) | Yes |
233| Headless server or SSH session with no D-Bus session | File | Yes |
234| Android/Termux | File | Yes |
235| Container with **no volume** on the secrets directory | Memory | No, this session only |
236| Container **with** a volume on the secrets directory | File | Yes |
237
238<Warning>
239 **With no keychain, secrets go to a plaintext file, and you did not have to ask for it.** On a host where the keychain probe fails (Linux without libsecret or a running Secret Service, a headless server or SSH session with no D-Bus session, Android/Termux), the Inspector **automatically** stores secrets in `~/.mcp-inspector/secrets.json`. Unless you supply a key, that file is **unencrypted**. Mode `0600` keeps out other non-root users, but not root, not backups or copies of your home directory, and not any program running as you, including the stdio servers the Inspector starts.
240
241 Pick one:
242
243 * **Get a keychain back:** install libsecret and run a Secret Service (for example `gnome-keyring`), or run the Inspector inside a desktop session. On the next start the Inspector moves the file's secrets into the keychain and deletes the file.
244 * **Encrypt the file:** supply a generated key with `MCP_INSPECTOR_SECRET_KEY_FILE` (preferred) or `MCP_INSPECTOR_SECRET_KEY`.
245 * **Don't write secrets to disk at all:** `MCP_INSPECTOR_SECRET_STORE=memory`, and re-enter them each session.
246
247 Even encrypted, secrets on disk carry moderate risk. See [what the file store protects against](/docs/2026-07-28/tools/inspector/security#what-the-file-store-protects-against).
248</Warning>
249
250[mcpdo](/docs/2026-07-28/tools/inspector/mcpdo) never falls back to `memory`: its commands and its daemon are separate processes, so it uses the file store instead.
251
252### The file store
253
254The file lives at `MCP_INSPECTOR_SECRET_FILE` if set, else `secrets.json` inside `MCP_STORAGE_DIR` if that is set, else `~/.mcp-inspector/secrets.json`. The default sits **beside** the storage directory (`~/.mcp-inspector/storage`), not inside it.
255
256* **Encryption is opt-in.** With a key, the file is encrypted with AES-256-GCM, the passphrase stretched by scrypt against a random salt regenerated on every write. Generate the key rather than choosing it, for example `(umask 077 && openssl rand -base64 32 > ~/.config/mcp-inspector/secret-key)`, and keep it away from the secrets file, its backups and any repository.
257* **Adding a key later is safe.** The next write upgrades a plaintext file in place.
258* **Changing or losing the key is not.** A file that no longer decrypts reads as empty, and the Inspector refuses to overwrite it. Restore the key, or delete the file and enter the values again.
259* **Permissions are enforced.** The file is written `0600` and re-tightened at startup. If it can't be (another owner, a read-only mount), the log and the settings footer say so.
260* **Concurrent Inspectors are safe.** A CLI run next to a web session serializes on a lock beside the file and verifies each write by reading it back.
261
262### Where the active store is reported
263
264* **On stderr**, when the store is selected: a warning on any keychain fallback, and another if the file is unencrypted, loosely permissioned or unreadable. Both end with a link to the Inspector's [secret storage guide](https://github.com/modelcontextprotocol/inspector/blob/main/docs/secret-storage.md). The web client's startup banner has a `Secrets:` line on every run.
265* **In the web client**, a footer in the **Client Settings**, **Server Settings** and **Add / Edit / Clone server** dialogs names the store, and turns into a warning when it is memory-only, unencrypted, loosely permissioned or unreadable.
266
267### Moving back to a keychain
268
269Install libsecret (or start a Secret Service) on a machine that was using the file store, and the next start selects the keychain and **moves the file's contents into it**. A value already in the keychain wins over the file's. The file is deleted only once every entry is accounted for, and a file that can't be decrypted is left in place. Setting `MCP_INSPECTOR_SECRET_STORE=keyring` triggers the same hand-off. Choosing `file` or `memory` never copies anything out of the keychain.
166270
167271## Catalog file format
168272
No line in this hunk matches that.