Configuration and flags

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 <path>`	`--config <path>`
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:

{
  "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:

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 <path>`	Writable catalog file.	None
`--config <path>`	Read-only session file.	None
`--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.
`--transport <type>`	`stdio`, `sse`, or `http`.	Ad-hoc targets only.
`--server-url <url>`	Server URL for SSE/HTTP.	Ad-hoc targets only.
`--cwd <path>`	Working directory for a stdio server process.	None
`-e <KEY=VALUE>`	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:

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 <path>`	`MCP_CLIENT_CONFIG_PATH`	Install-level client config. Default `~/.mcp-inspector/storage/client.json`.
`--client-id <id>`	None	OAuth client ID for a static client. Overrides `client.json`.
`--client-secret <secret>`	None	OAuth client secret for confidential clients. Overrides `client.json`.
`--client-metadata-url <url>`	None	CIMD metadata URL. Overrides `client.json`.
`--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.

CLI-only flags

The whole scripting surface belongs to the CLI. See CLI client 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 (`<dir>/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 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:

{
  "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) defaults to legacy and modernLogLevel to debug. You do not have to hand-write these; the web client can import an existing client config from Claude Desktop, Cursor, Cline, or VS Code, or a registry server.json.

Get started

About MCP

Develop with MCP

Developer tools

Examples

The launcher owns exactly two things

Choosing servers

`--catalog` vs. `--config`

Ad-hoc targets

Shared server-selection flags

The `--` separator

Web-only flags

CLI and TUI: OAuth client flags

CLI-only flags

Environment variables

Read by the launcher

CLI and TUI

Web backend environment variables

Catalog file format

​The launcher owns exactly two things

​Choosing servers

​--catalog vs. --config

​Ad-hoc targets

​Shared server-selection flags

​The -- separator

​Web-only flags

​CLI and TUI: OAuth client flags

​CLI-only flags

​Environment variables

​Read by the launcher

​CLI and TUI

​Web backend environment variables

​Catalog file format

The launcher owns exactly two things

Choosing servers

`--catalog` vs. `--config`

Ad-hoc targets

Shared server-selection flags

The `--` separator

Web-only flags

CLI and TUI: OAuth client flags

CLI-only flags

Environment variables

Read by the launcher

CLI and TUI

Web backend environment variables

Catalog file format