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

Everything below belongs to a client.

Choosing servers

--catalog vs. --config

The 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.

The 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.

{
  "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"]
    },
    "example-server-default": {
      "type": "streamable-http",
      "url": "https://example-server.modelcontextprotocol.io/mcp"
    }
  }
}

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:

The -- separator

The 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:

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.

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:

mcp-inspector --cli node build/index.js --config /etc/myserver.conf --verbose -- --method tools/list

Web-only flags

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.

CLI-only flags

The whole scripting surface belongs to the CLI. See CLI client for usage.

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, to the web backend, or to every client (the secret store).

Read by the launcher

CLI and TUI

Some of these are read by the web backend too, as the Read by column shows.

Web backend environment variables

What the token does and does not protect is laid out under The web backend and its API token.

Secret store variables

Read by every client: web, CLI, TUI, and mcpdo. How they combine is described under Where secrets are stored.

Where secrets are stored

The 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:

• acquired OAuth tokens (access, refresh and IdP session tokens);
• each server’s OAuth client secret, and the enterprise IdP client secret from Client Settings;
• 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.

headers are not moved. They are saved in mcp.json exactly as written, so a header that carries a credential stays in the file.

How the store is chosen

Each 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:

1. MCP_INSPECTOR_SECRET_STORE, if set to keyring, file or memory. Nothing is probed.
2. 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.
3. A fallback, announced on stderr:
   • 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;
   • file everywhere else.

mcpdo never falls back to memory: its commands and its daemon are separate processes, so it uses the file store instead.

The file store

The 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.

• 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.
• Adding a key later is safe. The next write upgrades a plaintext file in place.
• 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.
• 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.
• 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.

Where the active store is reported

• 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. The web client’s startup banner has a Secrets: line on every run.
• 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.

Moving back to a keychain

Install 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.

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.