Open Interpreter 集成 MCP（模型上下文协议）服务器实战指南：从 Stdio/HTTP 配置到审批、过滤与安全加固

导读

模型上下文协议（MCP，Model Context Protocol）让 Open Interpreter 能够以标准化的方式调用本地或远程服务器暴露的外部工具与数据。本文以 docs/zh/mcp.md 为主干，完整讲解在 ~/.openinterpreter/config.toml 中通过 [mcp_servers.*] 配置 Stdio 与流式 HTTP 两类 MCP 服务器、使用 interpreter mcp 命令族做生命周期与 OAuth 管理、按服务器和按工具设置审批模式、用工具白名单/黑名单做能力裁剪，以及超时、启动依赖与安全注意事项。读完本文，你将掌握一套可直接落地的“外部能力显式接入”配置方案，并能对照仓库源码理解每一项配置在底层数据结构中的实际映射。

MCP 在 Open Interpreter 中的定位：为什么不用 Shell 即兴实现

文档开篇就点明了 MCP 的价值边界：MCP 适用于问题追踪器、私有文档、数据库、内部 CLI，以及其他“应当显式提供、而非通过 Shell 命令即兴实现”的能力。两者对比的本质差异是：

• Shell 即兴实现：每次由模型猜测命令、拼装参数，行为不稳定，还可能踩到只读/破坏性边界；
• MCP 显式接入：服务器预先声明工具名称、参数 schema 与语义，模型在调用前即可看到结构化定义，行为可控、可审批、可审计。

MCP 的统一之处在于传输协议与工具描述格式，因此同一个客户端可以“插拔式”接入不同来源的工具生态，而不是为每个外部系统手写一套集成代码。

配置入口：[mcp_servers.*] 与全局配置文件

所有 MCP 服务器都在全局配置文件中通过 TOML 表声明，文件位置为 ~/.openinterpreter/config.toml：

[mcp_servers.<服务器名>]
# 配置项……

每添加一个表即声明一台服务器，表名就是后续 CLI 与配置引用的服务器标识。除本指南外，docs/config-reference.md（MCP Tables 一节）与 docs/zh/config-reference.md 也给出了完整的同构示例，可在修改全局配置前对照检查字段拼写。

从源码层面看，服务器配置对应 codex-rs/config/src/mcp_types.rs 中的 McpServerConfig 结构（定义于第 161 行附近）。该结构把“传输方式”与“行为策略”分开建模：

• transport：被折叠进同一张表内的传输字段，只能是 Stdio（command/args/env/env_vars/cwd）或 StreamableHttp（url/bearer_token_env_var/http_headers/env_http_headers），见同文件第 463–491 行的 McpServerTransportConfig 枚举；
• 行为策略：enabled、required、startup_timeout_sec、tool_timeout_sec、default_tools_approval_mode、enabled_tools、disabled_tools、tools（按工具的覆盖配置）等共享字段。

值得注意的默认值（源码 TryFrom<RawMcpServerConfig> 转换逻辑与 default_enabled 函数）：

• enabled 默认为 true（false 时跳过初始化该服务器）；
• required 默认为 false；
• startup_timeout_sec、tool_timeout_sec 未配置时不设限；
• 传输字段彼此互斥：给 stdio 服务器写 url、bearer_token_env_var、http_headers、oauth 等会触发“is not supported for stdio”的校验错误，反之亦然（见第 374–419 行的 throw_if_set 校验）。

添加 Stdio 服务器：本地子进程型 MCP

Stdio 服务器以“客户端启动一个子进程、通过标准输入/输出交换 JSON-RPC 消息”的方式运行，最适合本地 CLI、npx 包形式的工具服务器。

在 ~/.openinterpreter/config.toml 中配置，以 Linear 官方 MCP 服务器为例：

[mcp_servers.linear]
command = "npx"
args = ["-y", "@linear/mcp-server"]
env = { LINEAR_API_KEY = "env:LINEAR_API_KEY" }

关键字段：

字段	含义	示例值
command	要启动的可执行程序	npx、docs-mcp、my-mcp
args	传给命令的参数数组	["-y", "@linear/mcp-server"]
env	附加到子进程环境的键值表	{ LINEAR_API_KEY = "env:LINEAR_API_KEY" }

env 中出现的 env:VAR 形式（如 "env:LINEAR_API_KEY"）代表把名为 LINEAR_API_KEY 的宿主环境变量作为凭证来源，而不是把密钥明文写死在配置里——这与本文末尾“安全注意事项”中“避免在代码内联存储机密”的原则一致，是接入需要鉴权的服务器时的推荐写法。

也可以完全通过命令行完成同样的注册，无需手工编辑 TOML：

interpreter mcp add linear -- npx -y @linear/mcp-server

-- 之后的部分整体作为 command + args 写入。CLI 还支持追加环境变量：

interpreter mcp add linear --env LINEAR_API_KEY=xxx -- npx -y @linear/mcp-server

这些子命令在仓库中的实现位于 codex-rs/cli/src/mcp_cmd.rs：AddArgs 要求 --url 与裸命令二者必选其一（clap ArgGroup 约束），stdio 分支会把命令的首个 token 解析为 command、其余作为 args，--env 的 KEY=VALUE 对则合并进 env 表（第 116–133、298–445 行）。

添加 HTTP（流式 HTTP）服务器：远端托管型 MCP

对于部署在远端、走 HTTP 的 MCP 服务器，配置改用 url 字段。bearer_token_env_var 指定“从哪个环境变量读取 Bearer Token”，同样是间接引用，避免把令牌明文写进配置：

[mcp_servers.docs]
url = "https://mcp.example.com"
bearer_token_env_var = "DOCS_MCP_TOKEN"

对应的 CLI 写法：

interpreter mcp add docs --url https://mcp.example.com \
  --bearer-token-env-var DOCS_MCP_TOKEN

从 codex-rs/config/src/mcp_types.rs 的 StreamableHttp 变体（第 476–491 行）可以看到 HTTP 服务器还可选配更多传输级字段：

• http_headers：随每个请求发送的静态 HTTP 头（字面值）；
• env_http_headers：值来自环境变量的 HTTP 头（TOML 写法见下文“环境”小节）。

CLI 层的 AddMcpStreamableHttpArgs（codex-rs/cli/src/mcp_cmd.rs 第 136–157 行）还额外提供两个面向 OAuth 场景的开关：

# 为 OAuth 流程指定显式 client id 与 RFC 8707 resource 参数
interpreter mcp add remote --url https://mcp.example.com \
  --oauth-client-id my-client --oauth-resource api.example.com

管理服务器：list / get / remove / login / logout

Open Interpreter 提供完整的 MCP 服务器生命周期管理命令：

interpreter mcp list                # 列出所有已配置服务器及其状态
interpreter mcp get docs            # 查看单台服务器的详细配置
interpreter mcp remove docs         # 删除名为 docs 的服务器
interpreter mcp login docs          # 对支持 OAuth 的服务器执行登录
interpreter mcp logout docs         # 清除已保存的 OAuth 凭证

几点可落地的细节（均有源码佐证，见 codex-rs/cli/src/mcp_cmd.rs）：

• list 与 get 都支持 --json 输出，便于脚本化消费：interpreter mcp list --json 会给出每个服务器的 name、enabled、transport（含类型与全部传输字段）、startup_timeout_sec、tool_timeout_sec 与 auth_status；get --json 还会包含 enabled_tools/disabled_tools；
• list 的人读输出会按传输类型分两张表展示：stdio 表显示 Name / Command / Args / Env / Cwd / Status / Auth，HTTP 表显示 Name / Url / Bearer Token Env Var / Status / Auth；列表尾部会打印 auth_status，帮助你一眼看出哪台服务器尚未完成鉴权；
• get 会打印服务器级配置与提示命令 remove: ...，若服务器被禁用还会给出 disabled_reason；
• remove 在服务器不存在时会明确提示 No MCP server named '...' found.，不会误删其他条目；
• login 与 logout 仅对流式 HTTP 传输生效，对 stdio 服务器会直接报错：OAuth login is only supported for streamable HTTP servers。login 支持 --scopes a,b,c 显式声明所需 OAuth 范围；logout 会清除 keyring/凭证存储中的 OAuth 令牌。

OAuth 登录面向支持 OAuth 的流式 HTTP 服务器。在 add 阶段检测到服务器支持 OAuth 时会自动拉起登录流程；如果服务器无法明确判断是否需要登录，CLI 会提示你可以稍后手动执行 interpreter mcp login <name>。代码中还针对老式服务器做了一次兼容重试：当“按发现的作用域发起 OAuth”被服务端拒绝时，会无作用域重试一次（perform_oauth_login_retry_without_scopes，第 229–280 行）。

在 TUI 中查看已加载服务器

在 Open Interpreter 的 TUI 会话内，使用斜杠命令即可实时查看运行时已加载的 MCP 服务器，无需退出会话：

• /mcp：查看当前已加载的服务器列表；
• /mcp verbose：进一步展开查看每台服务器的工具明细。

审批模式：按服务器与按工具精细化授权

MCP 工具天然具备“可读、可写、可调用外部系统”的能力，因此接入时应当明确每个工具的审批策略。配置支持两个粒度：

1. 设置服务器默认值——该服务器下所有工具未单独配置时采用的模式：

[mcp_servers.docs]
command = "docs-mcp"
default_tools_approval_mode = "prompt"

2. 覆盖单个工具——按工具名精确覆盖，tools.<工具名> 的子表：

[mcp_servers.docs.tools.search]
approval_mode = "approve"

常用模式一览（源自文档表格）：

模式	行为
prompt	在工具运行前询问用户。
approve	自动允许该工具运行。
auto	让活动策略自行决定。

实现层面，审批模式在 codex-rs/config/src/mcp_types.rs 中对应 AppToolApproval 枚举（第 23–31 行），默认值为 Auto；单工具的覆盖由 McpServerToolConfig { approval_mode } 承载，并汇总在 McpServerConfig.tools: HashMap<String, McpServerToolConfig>（按工具名索引）。也就是说“服务器默认 + 工具覆盖”的分层在数据结构上是一等公民：未命中覆盖的工具回落到 default_tools_approval_mode，仍未设置则进一步回落活动策略。另：该枚举中还定义了一个 writes 档位，配置解析同样接受它，属于审批策略枚举的一部分，具体语义取决于当前生效策略对写入型操作的界定。

工具过滤：白名单与黑名单的组合裁剪

不是每台服务器暴露的所有工具都应当对模型可见。enabled_tools（白名单）与 disabled_tools（黑名单）可以组合使用：

[mcp_servers.docs]
command = "docs-mcp"
enabled_tools = ["search", "read"]
disabled_tools = ["delete"]

规则的执行顺序有明确约定：disabled_tools 在 enabled_tools 之后生效。也就是说：

• 设置了 enabled_tools 时，只有名单内的工具会被注册为可见工具；
• 随后 disabled_tools 再从结果中移除命中的工具。

源码中 enabled_tools 被注释为“显式允许名单，设置后仅注册这些工具”，而 disabled_tools 是“显式拒绝名单，在应用 enabled_tools 之后移除这些工具”（codex-rs/config/src/mcp_types.rs 第 209–215 行），与文档语义完全一致。

一个典型的组合用法：给某台文档 MCP 只开放只读能力（如 search、read），同时显式禁用其写路径（如 delete、write），把模型在推理过程中能触碰的表面压缩到最小必要集。

超时与启动控制

远端或重型 MCP 服务器在启动与调用时都可能卡住，因此提供了两组超时和一个启动依赖开关：

[mcp_servers.docs]
command = "docs-mcp"
startup_timeout_sec = 10
tool_timeout_sec = 60
required = true
enabled = true

字段	作用
startup_timeout_sec	初始化服务器并完成首次工具列表拉取的超时上限（秒），例如 10 秒。
tool_timeout_sec	通过该服务器发起的每次工具调用的超时上限（秒），例如 60 秒。
required	该服务器是否“必需”。required = true 时，若服务器无法初始化，会话启动或恢复会直接失败。
enabled	是否启用该服务器；false 时跳过初始化。

源码中两个超时字段以 Option<Duration> 存储，并通过 serde 的 option_duration_secs 适配器在 TOML 中读写（codex-rs/config/src/mcp_types.rs 第 199–203 行与第 493–517 行），同时兼容 startup_timeout_sec/startup_timeout_ms 两套旧字段名（毫秒写法仅作向后兼容）。

required 的语义在代码注释中同样明确：为 true 时，codex exec 在该 MCP 服务器初始化失败时会以错误退出（第 176–178 行）。因此合理的用法是：把“缺了它整个任务就无法开展”的服务器标为 required = true（如核心代码搜索索引），把“锦上添花型”的工具服务器保持默认的 required = false，避免因单台附属服务器故障阻塞整个会话。

环境与请求头配置

MCP 服务器往往需要注入密钥、指定工作目录，或透传宿主环境的部分变量。stdio 与 HTTP 两类服务器分别有自己的环境配置语法。

对 Stdio 服务器

[mcp_servers.local]
command = "my-mcp"
args = ["--stdio"]
cwd = "/Users/me/project"
env = { TOKEN = "env:MY_TOKEN" }
env_vars = ["PATH", "HOME"]

• cwd：子进程的工作目录，例如把服务器“锚定”到某个项目目录下；
• env：显式设置的键值环境变量；
• env_vars：希望从宿主进程透传给服务器的环境变量名列表，例如 ["PATH", "HOME"] 表示把宿主的 PATH 与 HOME 原样带过去。

值得补充的是，env_vars 在配置模型（McpServerEnvVar，codex-rs/config/src/mcp_types.rs 第 67–105 行）中还支持“带来源”的对象写法 { name = "...", source = "local" } 或 source = "remote"，用于区分变量取自本地还是远端执行环境；source 只接受 local/remote 两种取值，其余值会被配置校验拒绝。

对 HTTP 服务器

[mcp_servers.remote]
url = "https://mcp.example.com"
http_headers = { "X-Client" = "open-interpreter" }
env_http_headers = { "Authorization" = "MCP_AUTH_HEADER" }

• http_headers：字面值静态头，如示例中的 X-Client；
• env_http_headers：值从环境变量读取的头，示例表示 Authorization 头的值来自环境变量 MCP_AUTH_HEADER。它与 bearer_token_env_var 一样，把敏感材料留在进程环境中，而不是内联进配置文件。

安全注意事项：把 MCP 工具当作一等外部能力来管理

文档在结尾给出三条必须遵守的安全基线，接入任何服务器前都值得对照检查：

1. 把 MCP 工具视为任何其他能够读取、写入或调用外部系统的工具。MCP 工具一旦放行，其能力等同于本机命令或系统调用，不能因为“来自标准化协议”就降低警惕。
2. 对具破坏性的工具使用 prompt。删除、覆盖、发布、转账这类工具应保持在每次调用前询问用户的状态；只有经过评估的只读、低危工具才建议 approve 或交给策略 auto 处理。
3. 避免在代码中内联存储机密，并在为项目启用之前审查服务器配置。用 env:VAR 间接引用、bearer_token_env_var/env_http_headers 引用环境变量，都比把密钥明文写进 config.toml 安全得多；启用第三方 MCP 前还应确认它的来源可信、工具面是否过大，必要时用白名单/黑名单裁剪。

结合仓库源码快速查阅的路线图

• docs/zh/mcp.md：本文依据的官方中文指南原文（英文版见 docs/mcp.md）；
• docs/config.md 与 docs/config-reference.md：“MCP Servers”/“MCP Tables”小节给出含完整字段的全局配置示例；
• codex-rs/config/src/mcp_types.rs：McpServerConfig、McpServerTransportConfig、AppToolApproval、McpServerEnvVar 等全部 MCP 配置数据类型的权威定义，字段默认值、传输互斥校验与 env:VAR 形态的解析逻辑均在此实现；
• codex-rs/cli/src/mcp_cmd.rs：interpreter mcp 全部子命令（list/get/add/remove/login/logout）的命令行参数、OAuth 流程与配置读写实现；
• codex-rs/core/src/mcp.rs：会话运行时中 McpManager 对已配置服务器的解析、生效与加载入口。

接入 MCP 的本质，是把“让模型即兴调用外部系统”替换为“预先声明、按需授权、受控执行”的显式能力管道。掌握 [mcp_servers.*] 配置、interpreter mcp 命令族与“默认策略 + 单工具覆盖”的审批模型后，你就可以在 Open Interpreter 中稳定、安全地把私有文档检索、问题追踪、数据库查询等能力接入到对话流程中。