> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-zh.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置与 flag

> 目录 vs. 配置文件、哪个客户端拥有哪个 flag，以及每一个环境变量

`mcp-inspector` 二进制文件是一个启动器：它读取自己的两个 flag，并将其他所有参数转发给三个客户端之一（Web、CLI 或 TUI）。每个客户端定义自己的 flag，因此一个在某个客户端有效的 flag 对另一个可能是未知的（例如 `--method` 仅限 CLI）。本页按拥有 flag 和环境变量的客户端对它们进行分组。

## 启动器恰好掌管两样东西

| Flag                        | 行为                                                                                                                                  |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--web` / `--cli` / `--tui` | 选择客户端，默认 `--web`。传入多于一个会以 `Specify at most one of --web, --cli, or --tui.` 失败。启动器 flag 必须放在最前：解析在启动器不拥有的第一个参数处停止，从那一点起的一切都原样转发给客户端。 |
| `-h` / `--help`             | 无模式 flag 时，打印启动器自己的帮助并退出。带模式 flag 时它被转发，因此 `mcp-inspector --cli --help` 打印 CLI 的帮助。                                                 |

以下所有内容都归属某个客户端。

## 选择服务器

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

三个客户端都通过同一份共享代码解析 `--catalog` 和 `--config`，因此每个 flag 在 Web 应用、CLI 和 TUI 中行为相同。两者彼此之间的差异见下表。

|                    | `--catalog <path>`                                     | `--config <path>`    |
| ------------------ | ------------------------------------------------------ | -------------------- |
| **可写？**            | 是，Inspector 自己的服务器列表。                                  | 否。按原样提供，绝不写入、初始化或迁移。 |
| **文件缺失？**          | 被创建并初始化（见下文）。                                          | **报错。**              |
| **默认**             | `~/.mcp-inspector/mcp.json`，或 `MCP_CATALOG_PATH` 环境变量。 | 无；你必须传入它。            |
| **可在 Web UI 中编辑？** | 是。                                                     | 否。                   |
| **用途**             | 你自己的工作服务器集合。                                           | 针对他人配置文件的只读会话。       |

两者**互斥**，且都不与临时目标组合。传入两者会被三个客户端一模一样地拒绝。

<Note>
  **一个新初始化的目录包含什么取决于客户端。** Web 后端初始化两个示例服务器，这样首次启动就有可以立即连接的东西：

  ```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"]
      }
    }
  }
  ```

  CLI 和 TUI 则初始化一个空的 `{ "mcpServers": {} }`：它们是非交互式或列表驱动的，因此示例条目会是噪音而非起点。

  无论哪种方式，初始化仅在文件尚不存在时发生，而只读的 `--config` 根本不会被初始化。
</Note>

<Note>
  当把 Inspector 指向一个你没有编写的配置文件时——同事的、某个客户端应用的，或签入某个仓库的——`--config` 正是你想要的。它保证 Inspector 不会触碰该文件。
</Note>

### 临时目标

除了文件之外，你可以直接指定一个服务器，既可以作为位置命令（stdio），也可以作为一个 URL：

```bash theme={null}
mcp-inspector node build/index.js                              # stdio，位置参数
mcp-inspector --server-url https://api.example.com/mcp --transport http
```

### 共享的服务器选择 flag

由 **Web、CLI 和 TUI 各自单独**定义，因此它们在三者中都可用，差异已标注：

| Flag                     | 含义                             | 差异                                        |
| ------------------------ | ------------------------------ | ----------------------------------------- |
| `--catalog <path>`       | 可写目录文件。                        | 无                                         |
| `--config <path>`        | 只读会话文件。                        | 无                                         |
| `--server <name>`        | 从文件中挑选一个具名服务器。                 | **仅 Web 和 CLI。** TUI 加载文件中的每个服务器并让你交互式选择。 |
| `--transport <type>`     | `stdio`、`sse` 或 `http`。        | 仅临时目标。                                    |
| `--server-url <url>`     | SSE/HTTP 的服务器 URL。             | 仅临时目标。                                    |
| `--cwd <path>`           | stdio 服务器进程的工作目录。              | 无                                         |
| `-e <KEY=VALUE>`         | stdio 服务器的环境变量。可重复。            | 无                                         |
| `--header "Name: Value"` | HTTP/SSE 服务器的 HTTP header。可重复。 | 在 Web 客户端上需要一个临时 HTTP/SSE 服务器。            |
| `[target...]`            | 一个临时服务器的位置命令/URL。              | 无                                         |

### `--` 分隔符

**Web 和 CLI** 客户端在一个裸 `--` 处切分它们的参数，并将其后的一切作为目标命令自己的参数传递。这就是你传递一个否则会被 Inspector 吞掉的 flag 的方式：

```bash theme={null}
mcp-inspector node build/index.js -- --config /etc/myserver.conf --verbose
```

若没有该分隔符，`--config` 会被读作 Inspector 自己的只读会话 flag。

## 仅 Web 的 flag

| Flag    | 含义                                                 |
| ------- | -------------------------------------------------- |
| `--dev` | 运行 Vite dev 服务器而不是预构建的 bundle。在开发 Inspector 本身时有用。 |

## CLI 和 TUI：OAuth 客户端 flag

这五个仅由 **CLI 和 TUI** 定义。Web 客户端通过其 Client Settings 对话框获得相同的设置。

| Flag                          | 环境变量                     | 含义                                                                                                                                                               |
| ----------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--client-config <path>`      | `MCP_CLIENT_CONFIG_PATH` | 安装级别的客户端配置。默认 `~/.mcp-inspector/storage/client.json`。                                                                                                            |
| `--client-id <id>`            | 无                        | 用于静态客户端的 OAuth client ID。覆盖 `client.json`。                                                                                                                       |
| `--client-secret <secret>`    | 无                        | 用于机密客户端的 OAuth client secret。覆盖 `client.json`。                                                                                                                   |
| `--client-metadata-url <url>` | 无                        | CIMD 元数据 URL。覆盖 `client.json`。                                                                                                                                   |
| `--callback-url <url>`        | `MCP_OAUTH_CALLBACK_URL` | 发送给授权服务器的重定向 URI。默认 `http://127.0.0.1:6276/oauth/callback`。必须是一个 loopback 主机（`127.0.0.1` 或 `localhost`）：本地回调监听器通过明文 `http` 接收授权码，因此任何其他主机都会被拒绝，且没有 flag 可以覆盖这一点。 |

## 仅 CLI 的 flag

整个脚本化界面归属 CLI。用法参见 [CLI 客户端](/docs/2026-07-28/tools/inspector/cli)。

| 分组        | Flag                                                                                                                                          |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **调用什么**  | `--method`、`--tool-name`、`--tool-arg`、`--tool-args-json`、`--uri`、`--prompt-name`、`--prompt-args`、`--log-level`、`--metadata`、`--tool-metadata` |
| **如何运行它** | `--connect-timeout`、`--format`、`--app-info`                                                                                                   |
| **认证**    | `--use-stored-auth`、`--stored-auth-only`、`--relogin`、`--wait-for-auth`、`--list-stored-auth`、`--print-handoff`                                 |

## 环境变量

环境变量的划分方式与 flag 相同：两个由启动器本身读取，其余归属 CLI 和 TUI 或 Web 后端。

### 由启动器读取

| 变量          | 效果                                                                               |
| ----------- | -------------------------------------------------------------------------------- |
| `MCP_DEBUG` | 将错误堆栈附加到顶层失败。仅当设为一个有意义的值时：`0`、`false` 和空值读作关闭。                                   |
| `DEBUG`     | 相同，采用相同的有意义值规则，因此一个偶然的 `DEBUG=0` 不会开启堆栈跟踪，而 `DEBUG` 仍作为 npm `debug` 包的命名空间过滤器工作。 |

### CLI 和 TUI

| 变量                               | 效果                                                                                                     |
| -------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `MCP_CATALOG_PATH`               | `--catalog` 的回退。仅在没有给出临时目标时生效，因此一个导出它的 shell 仍然可以运行一次性的临时调用。                                           |
| `MCP_CLIENT_CONFIG_PATH`         | `--client-config` 的回退。                                                                                 |
| `MCP_OAUTH_CALLBACK_URL`         | `--callback-url` 的回退。                                                                                  |
| `MCP_STORAGE_DIR`                | OAuth 状态文件（`<dir>/oauth.json`）的目录。                                                                     |
| `MCP_INSPECTOR_OAUTH_STATE_PATH` | OAuth 状态路径的按文件覆盖。优先于 `MCP_STORAGE_DIR`。                                                                |
| `MCP_AUTO_OPEN_ENABLED`          | 控制浏览器自动打开，以及交互式 OAuth 是否可以在没有 TTY 的情况下运行。`true` 强制自动打开并允许无 TTY 的 OAuth 提示，`false` 从不打开，未设置时仅在 TTY 上打开。 |

### Web 后端环境变量

| 变量                                        | 效果                                                                               |
| ----------------------------------------- | -------------------------------------------------------------------------------- |
| `MCP_INSPECTOR_API_TOKEN`                 | 固定[会话令牌](/docs/2026-07-28/tools/inspector/web#the-session-token)，而不是每次启动生成一个随机的。 |
| `DANGEROUSLY_OMIT_AUTH`                   | 完全禁用 `/api/*` 令牌检查。                                                              |
| `HOST`                                    | 绑定主机。默认为 `localhost`。                                                            |
| `CLIENT_PORT`                             | Web UI 端口。默认为 `6274`。                                                            |
| `DANGEROUSLY_BIND_ALL_INTERFACES`         | 绑定通配符主机（`0.0.0.0`、`::` 或任何等价写法）所需的选择加入。                                          |
| `ALLOWED_ORIGINS`                         | 逗号分隔的 origin 允许列表。**替换**默认列表而非合并。                                                |
| `MCP_SANDBOX_PORT`                        | 固定默认为动态的 MCP 应用沙箱端口。                                                             |
| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | 出站 MCP 连接的标准代理路由。                                                                |

<Warning>
  切勿同时使用 `DANGEROUSLY_OMIT_AUTH` 和 `DANGEROUSLY_BIND_ALL_INTERFACES`。Web 后端会启动进程并持有 OAuth 令牌，因此任何能够到达它的人都可以驱动它。
</Warning>

## 目录文件格式

一个目录或配置文件是我们熟悉的 MCP 客户端配置形态（一个 `mcpServers` 对象），旁边带有按服务器的 Inspector 设置：

```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" }]
    }
  }
}
```

当 Inspector 将文件写回时，等于其默认值的字段会被省略，从而使 diff 保持最小。`protocolEra`（参见[协议时代](/docs/2026-07-28/tools/inspector/protocol-eras)）默认为 `legacy`，`modernLogLevel` 默认为 `debug`。

你不必手写这些；Web 客户端可以从 Claude Desktop、Cursor、Cline 或 VS Code，或一个注册表 `server.json`，[导入一个现有的客户端配置](/docs/2026-07-28/tools/inspector/recipes#importing-an-existing-client-config)。