> ## Documentation Index > Fetch the complete documentation index at: https://modelcontextprotocol.io/llms.txt > Use this file to discover all available pages before exploring further. # Configuration and flags > Catalog vs. config files, which client owns which flag, and every environment variable The `mcp-inspector` binary is a launcher: it reads two flags of its own and forwards every other argument to one of three clients (web, CLI, or TUI). Each client defines its own flags, so a flag that works in one can be unknown to another (`--method`, for example, is CLI-only). This page groups flags and environment variables by the client that owns them. ## The launcher owns exactly two things | Flag | Behavior | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--web` / `--cli` / `--tui` | Selects the client, `--web` by default. Passing more than one fails with `Specify at most one of --web, --cli, or --tui.` Launcher flags must come first: parsing stops at the first argument the launcher does not own, and everything from that point on is forwarded to the client unchanged. | | `-h` / `--help` | With no mode flag, prints the launcher's own help and exits. With a mode flag it is forwarded, so `mcp-inspector --cli --help` prints the CLI's help. | Everything below belongs to a client. ## Choosing servers ### `--catalog` vs. `--config` All 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. | | `--catalog ` | `--config ` | | --------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------- | | **Writable?** | Yes, the Inspector's own server list. | No. Served as-is, never written, seeded, or migrated. | | **Missing file?** | Created and seeded (see below). | **Errors.** | | **Default** | `~/.mcp-inspector/mcp.json`, or the `MCP_CATALOG_PATH` environment variable. | None; you must pass it. | | **Editable in the web UI?** | Yes. | No. | | **Use it for** | Your own working set of servers. | A read-only session against someone else's config file. | The two are **mutually exclusive**, and neither combines with an ad-hoc target. Passing both is rejected identically by all three clients. **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: ```json theme={null} { "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"] } } } ``` The CLI and TUI seed an empty `{ "mcpServers": {} }` instead: they are non-interactive or list-driven, so sample entries would be noise rather than a starting point. Either way, seeding happens only when the file does not exist yet, and a read-only `--config` is never seeded at all. `--config` is what you want when pointing the Inspector at a config file you didn't write: a coworker's, a client application's, or one checked into a repo. It guarantees the Inspector will not touch the file. ### Ad-hoc targets Instead of a file you can name one server directly, either as a positional command (stdio) or a URL: ```bash theme={null} mcp-inspector node build/index.js # stdio, positional mcp-inspector --server-url https://api.example.com/mcp --transport http ``` ### Shared server-selection flags Defined **separately by each of web, CLI, and TUI**, so they're available in all three, with the divergences noted: | Flag | Meaning | Divergence | | ------------------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `--catalog ` | Writable catalog file. | None | | `--config ` | Read-only session file. | None | | `--server ` | 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. | | `--transport ` | `stdio`, `sse`, or `http`. | Ad-hoc targets only. | | `--server-url ` | Server URL for SSE/HTTP. | Ad-hoc targets only. | | `--cwd ` | Working directory for a stdio server process. | None | | `-e ` | Environment variables for a stdio server. Repeatable. | None | | `--header "Name: Value"` | HTTP headers for an HTTP/SSE server. Repeatable. | Requires an ad-hoc HTTP/SSE server on the web client. | | `[target...]` | Positional command/URL for one ad-hoc server. | None | ### The `--` separator The **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: ```bash theme={null} 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-only flags | Flag | Meaning | | ------- | ----------------------------------------------------------------------------------------------------- | | `--dev` | Run the Vite dev server instead of the pre-built bundle. Useful when working on the Inspector itself. | ## CLI and TUI: OAuth client flags These five are defined by the **CLI and TUI** only. The web client obtains the same settings through its Client Settings dialog. | Flag | Environment variable | Meaning | | ----------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--client-config ` | `MCP_CLIENT_CONFIG_PATH` | Install-level client config. Default `~/.mcp-inspector/storage/client.json`. | | `--client-id ` | None | OAuth client ID for a static client. Overrides `client.json`. | | `--client-secret ` | None | OAuth client secret for confidential clients. Overrides `client.json`. | | `--client-metadata-url ` | None | CIMD metadata URL. Overrides `client.json`. | | `--callback-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. | ## CLI-only flags The whole scripting surface belongs to the CLI. See [CLI client](/docs/draft/tools/inspector/cli) for usage. | Group | Flags | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **What to invoke** | `--method`, `--tool-name`, `--tool-arg`, `--tool-args-json`, `--uri`, `--prompt-name`, `--prompt-args`, `--log-level`, `--metadata`, `--tool-metadata` | | **How to run it** | `--connect-timeout`, `--format`, `--app-info` | | **Auth** | `--use-stored-auth`, `--stored-auth-only`, `--relogin`, `--wait-for-auth`, `--list-stored-auth`, `--print-handoff` | ## Environment variables Environment 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. ### Read by the launcher | Variable | Effect | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | | `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. | ### CLI and TUI | Variable | Effect | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | | `MCP_CLIENT_CONFIG_PATH` | Fallback for `--client-config`. | | `MCP_OAUTH_CALLBACK_URL` | Fallback for `--callback-url`. | | `MCP_STORAGE_DIR` | Directory for the OAuth state file (`/oauth.json`). | | `MCP_INSPECTOR_OAUTH_STATE_PATH` | Per-file override of the OAuth state path. Takes precedence over `MCP_STORAGE_DIR`. | | `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. | ### Web backend environment variables | Variable | Effect | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `MCP_INSPECTOR_API_TOKEN` | Pin the [session token](/docs/draft/tools/inspector/web#the-session-token) instead of generating a random one per launch. | | `DANGEROUSLY_OMIT_AUTH` | Disable the `/api/*` token check entirely. | | `HOST` | Bind host. Defaults to `localhost`. | | `CLIENT_PORT` | Web UI port. Defaults to `6274`. | | `DANGEROUSLY_BIND_ALL_INTERFACES` | Required opt-in to bind a wildcard host (`0.0.0.0`, `::`, or any equivalent spelling). | | `ALLOWED_ORIGINS` | Comma-separated origin allow-list. **Replaces** the default list rather than merging. | | `MCP_SANDBOX_PORT` | Pin the MCP Apps sandbox port, which is dynamic by default. | | `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | Standard proxy routing for outbound MCP connections. | Never combine `DANGEROUSLY_OMIT_AUTH` and `DANGEROUSLY_BIND_ALL_INTERFACES`. The web backend spawns processes and holds OAuth tokens, so anyone who can reach it can drive it. ## Catalog file format A catalog or config file is the familiar MCP client config shape (a `mcpServers` object) with per-server Inspector settings alongside: ```json theme={null} { "mcpServers": { "my-stdio-server": { "command": "node", "args": ["build/index.js"], "env": { "API_KEY": "..." } }, "my-modern-server": { "type": "http", "url": "https://api.example.com/mcp", "protocolEra": "modern", "modernLogLevel": "info", "headers": { "X-Tenant": "acme" }, "roots": [{ "uri": "file:///Users/me/project", "name": "project" }] } } } ``` Fields that equal their default are omitted when the Inspector writes the file back, keeping diffs minimal. `protocolEra` (see [Protocol eras](/docs/draft/tools/inspector/protocol-eras)) defaults to `legacy` and `modernLogLevel` to `debug`. You do not have to hand-write these; the web client can [import an existing client config](/docs/draft/tools/inspector/recipes#importing-an-existing-client-config) from Claude Desktop, Cursor, Cline, or VS Code, or a registry `server.json`.