配置与 flag

社区译文；来源： MCP 80041ab0

mcp-inspector 二进制文件是一个启动器：它自己只读取两个 flag，并把其他所有参数转发给三个客户端之一（web、CLI 或 TUI）。每个客户端定义各自的 flag，因此在一个客户端可用的 flag 在另一个客户端可能无法识别（例如 --method 仅属于 CLI）。下面按所属客户端列出 flag 与环境变量。

启动器只拥有两件事

下面的一切都属于某个客户端。

选择服务器

--catalog 与 --config

CLI 和 TUI 通过相同的共享代码解析 --catalog 和 --config，web 客户端也应用同样的规则，因此每个 flag 在三个客户端中含义一致。两者的差异见下表。

两者互斥，且都不能与临时目标组合使用。同时传入两者会被三个客户端以相同方式拒绝。web 客户端在某一方面更严格：它会同时拒绝把 --header 和 --protocol-era 与文件一起使用，而 CLI 和 TUI 会把它们叠加在文件设置之上。

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

临时目标

除了文件，你也可以直接指定单个服务器：位置参数形式的命令（stdio）或一个 URL：

mcp-inspector node build/index.js                              # stdio, positional
mcp-inspector --server-url https://api.example.com/mcp --transport http

共享的服务器选择 flag

由 web、CLI 和 TUI 各自单独定义，因此在三者中都可使用，差异已在表中标注：

-- 分隔符

web 和 TUI 客户端会把裸 -- 之后的所有内容作为目标命令自身的参数传给目标。这是你传入那些否则会被 Inspector 吃掉的 flag 的方式：

mcp-inspector node build/index.js -- --config /etc/myserver.conf --verbose

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

CLI 的切分方式相反： -- 之前的一切是目标，之后的一切是 Inspector 自己的选项。没有 -- 时，CLI 的目标只是开头那一段不以短横线开头的参数，因此接受 flag 的服务器需要该分隔符：

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

仅 web 的 flag

CLI 与 TUI：OAuth 客户端 flag

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

仅 CLI 的 flag

整套脚本化能力都属于 CLI。用法参见 CLI 客户端。

环境变量

环境变量与 flag 的划分方式相同：两个由启动器自身读取，其余属于 CLI 和 TUI、web 后端，或所有客户端（机密存储）。

由启动器读取

CLI 与 TUI

其中一些也会被 web 后端读取，如下方 Read by 列所示。

Web 后端环境变量

关于 token 保护什么、不保护什么，见 Web 后端及其 API token。

机密存储变量

由所有客户端读取：web、CLI、TUI 以及 mcpdo。它们如何组合见机密存储于何处。

机密存储于何处

Inspector 会把凭据排除在 mcp.json、client.json 和 oauth.json 之外，这样共享、提交或同步这些文件时就不会泄露它们。这些内容改为存放在机密存储中：

• 已获取的 OAuth token（access、refresh 和 IdP 会话 token）；
• 每个服务器的 OAuth 客户端 secret，以及来自 Client Settings 的企业 IdP 客户端 secret；
• 每个 stdio 服务器的 env: 值。保存条目时，每个 env 键仍留在 mcp.json 中但值为空，真实值则进入存储。

headers 不会被移走。 它们会按写入原样保存在 mcp.json 中，因此携带凭据的 header 会留在文件里。

存储如何被选择

每个进程在第一次需要时选择一次存储：web 后端在启动时，CLI 和 TUI 在首次使用时。所有客户端使用相同顺序：

1. MCP_INSPECTOR_SECRET_STORE，如果设置为 keyring、file 或 memory。此时不做任何探测。
2. 操作系统钥匙串，如果探测能访问到：macOS 上的 Keychain、Windows 上的 Credential Manager、Linux 上的 Secret Service（libsecret，如 GNOME Keyring 或 KWallet）。条目存放在服务名 mcp-inspector 之下。大多数桌面安装到此为止。
3. 回退方案，会在 stderr 上通告：
   • 若容器中的机密目录未挂载在卷上，则为 memory，因为容器可写层中的文件无论如何都会丢失；
   • 其他情况均为 file。

mcpdo从不回退到 memory：它的命令与守护进程是不同进程，因此改用文件存储。

文件存储

文件位于 MCP_INSPECTOR_SECRET_FILE（若设置），否则为 MCP_STORAGE_DIR 中的 secrets.json（若设置），再否则为 ~/.mcp-inspector/secrets.json。默认位置在存储目录（~/.mcp-inspector/storage）旁边，而不是其中。

• 加密需要显式启用。 提供密钥后，文件以 AES-256-GCM 加密，口令经 scrypt 拉伸，盐值在每次写入时随机重新生成。请生成密钥而不是自行挑选，例如 (umask 077 && openssl rand -base64 32 > ~/.config/mcp-inspector/secret-key)，并让它远离机密文件、其备份以及任何仓库。
• 之后再添加密钥是安全的。 下一次写入会在原地升级明文文件。
• 更换或丢失密钥则不安全。 无法再解密的文件会被读作空，且 Inspector 拒绝覆盖它。请恢复密钥，或删除该文件并重新输入这些值。
• 权限会被强制执行。 文件以 0600 写入，并在启动时重新收紧。若无法做到（所有者不同、只读挂载），日志和设置页脚会说明情况。
• 并发的 Inspector 是安全的。 与 web 会话并行的 CLI 运行会在文件旁的锁上串行化，并通过回读来校验每次写入。

活动存储的报告位置

• 在 stderr 上，当存储被选择时：任何钥匙串回退都会给出警告，若文件未加密、权限过宽或不可读还会再给一条。两者都以指向 Inspector 的机密存储指南的链接结尾。web 客户端的启动横幅在每次运行时都有一行 Secrets:。
• 在 web 客户端中，Client Settings、Server Settings 以及 Add / Edit / Clone server 对话框中的页脚会指出当前存储，并在其仅为内存、未加密、权限过宽或不可读时变为警告。

迁回钥匙串

在原本使用文件存储的机器上安装 libsecret（或启动 Secret Service），下次启动就会选择钥匙串并把文件内容移入其中。钥匙串中已有的值优先于文件中的值。只有在每个条目都得到处置后才会删除文件，而无法解密的文件会原样保留。设置 MCP_INSPECTOR_SECRET_STORE=keyring 会触发同样的移交。选择 file 或 memory 则绝不会从钥匙串中复制出任何内容。

Catalog 文件格式

catalog 或配置文件就是常见的 MCP 客户端配置结构（一个 mcpServers 对象），并在旁边带有逐服务器的 Inspector 设置：

{
  "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 回写文件时会省略等于默认值的字段，从而保持差异最小。protocolEra（参见协议世代）默认为 legacy，modernLogLevel 默认为 debug。

你无需手写这些；web 客户端可以从 Claude Desktop、Cursor、Cline 或 VS Code，或从注册表中的 server.json 导入现有客户端配置。