把 Open Interpreter 作为编码代理接入 MCP：`interpreter mcp-server` 实战指南

Open Interpreter 内置了一个将自身作为 MCP（Model Context Protocol）服务端暴露给其他 Agent 框架的 stdio 服务器模式。本文以仓库中文档 docs/zh/mcp-server.md 为主体，结合本仓库中承载该能力的 Rust 实现 crate（codex-rs/mcp-server）逐步讲解：何时启用它、如何用 interpreter mcp-server 启动、如何在任意 MCP 客户端中注册，以及底层提供了哪些工具、参数与安全边界。读完你可以在自己的 MCP 客户端（例如其他编码代理、内部工具平台）里，以一条 stdio 配置把一个受沙箱约束的 Open Interpreter 会话当工具来启动和续跑。

MCP 服务器模式解决什么问题

Open Interpreter 通常以两种姿态出现：一是作为MCP 客户端，通过 interpreter mcp add ... 接入线性、文档、数据库等外部 MCP 服务器（见 docs/zh/mcp.md）；二是本文要讲的相反方向——它把自己变成一台 MCP 服务器，运行在 stdio 之上，让"另一个 MCP 客户端"能把它当作可调用的工具：

MCP 客户端（其他 Agent 框架 / 内部工具）──stdio──▶ interpreter mcp-server（Open Interpreter 会话）

这正对应官方文档的定位：当另一个代理框架或内部工具需要把 Open Interpreter 作为编码代理来调用时，使用 MCP 服务器模式。被调用的会话依然具备完整的 Open Interpreter 能力——运行工具、发起批准请求、按你配置的沙箱与权限修改工作空间。

三种调用方式的取舍

官方文档用"何时使用"明确划出了边界，帮你避免误用：

需求	正确姿势	依据
只需要一次性的命令行任务（单发任务）	interpreter exec	docs/zh/mcp-server.md
在 Python 或 TypeScript 应用里直接内嵌 Open Interpreter	SDK	docs/zh/mcp-server.md
由另一个 Agent 框架 / 内部工具按需反复把 Open Interpreter 当作编码代理调用	interpreter mcp-server（MCP 服务器模式）	本文主题

一句话判断标准：需要"会话"这种有状态、可继续的对象，并且调用方遵循 MCP 生态时选服务器模式；只是临时跑一次命令就选 exec；要深度编程式集成则选 SDK。

启动服务器

最小启动命令

MCP 服务器模式通过 CLI 子命令启动，与普通 interpreter 会话共用同一份配置与登录态：

interpreter mcp-server

启动后进程会进入标准 MCP stdio 服务循环：从 stdin 逐行读取 JSON-RPC 消息、处理、再向 stdout 写回结果。由于它不监听 TCP 端口，而是挂在进程的 stdin/stdout 上，它总是由某个 MCP 客户端作为子进程拉起——单独在终端里敲这个命令只会看到进程等待输入，因此绝大多数场景你并不需要手动执行它，而是把它写进客户端的配置里。

CLI 侧的实现落点

在本仓库中，interpreter mcp-server 的 CLI 分派发生在 codex-rs/cli/src/main.rs，它把子命令转交给真正的服务器实现 codex-rs/mcp-server/src/main.rs 中的 codex_mcp_server::run_main。McpServerCommand 子命令支持一个可选开关：

# 当 config.toml 中出现本版本无法识别的字段时报错退出（严格校验配置）
interpreter mcp-server --strict-config

服务器进程启动时也会继承 CLI 根层传入的配置覆盖项，并完成配置加载与 auth_config().validate() 校验、OTel/遥测初始化、状态数据库与沙箱运行时（EnvironmentManager）的准备工作，随后才进入消息循环——这意味着客户端进程的服务质量与 CLI 直接运行会话完全一致。

在 MCP 客户端中注册

一个 MCP 客户端通常只需要一条 stdio 命令条目，JSON 形如：

{
  "mcpServers": {
    "open-interpreter": {
      "command": "interpreter",
      "args": ["mcp-server"]
    }
  }
}

关键点：command 是 interpreter，args 里放 mcp-server。请确保 interpreter 已加入客户端进程能访问到的 PATH（安装方式参见 docs/zh/install.md）。

保存这类配置到支持 MCP 的客户端后，客户端即可在工具列表中发现并调用 Open Interpreter 暴露的 MCP 工具。若配置加载失败，可先单独运行 interpreter mcp-server --strict-config 确认配置能被本版本解析。

暴露出的工具与参数

服务器提供两个工具：启动会话的 codex 与续跑既有线程的 codex-reply。二者的工具定义（名称、描述、输入输出 JSON Schema）都由 codex-rs/mcp-server/src/codex_tool_config.rs 用 schemars 从 Rust 结构体自动生成，并配有固定 JSON Schema 的测试作为"可执行的文档"（见该文件中的 verify_codex_tool_json_schema 测试）。客户端可以通过标准的 tools/list 拿到精确 Schema。

工具一：codex（启动会话）

codex 的工具说明为 "Run a Codex session. Accepts configuration parameters matching the Codex Config struct."，即"工具参数与普通 Open Interpreter 的配置界面相同"。其输入 Schema 采用 kebab-case 命名、additionalProperties: false（未知字段会被拒绝）。主要参数如下：

参数	类型 / 取值	说明
prompt	string（必填）	启动会话的初始用户提示词
model	string（可选）	覆盖模型名，例如本仓库面向的开源模型 Kimi K3、GLM 5.3 等
cwd	string（可选）	会话工作目录；相对路径会基于服务器进程当前目录解析
approval-policy	untrusted / on-request / never	模型生成的 shell 命令的审批策略（见下文对照表）
sandbox	read-only / workspace-write / danger-full-access	沙箱模式（见下文对照表）
config	object	每次运行针对 config.toml 的单次覆盖键值对，工具调用时经 JSON→TOML 转换后合并进配置
base-instructions	string（可选）	用该组指令替代默认系统指令
developer-instructions	string（可选）	以 developer 角色消息注入的开发指令
compact-prompt	string（可选）	对话压缩（compact）时使用的提示词

一次典型的工具调用参数体大致形如：

{
  "prompt": "阅读本仓库 README 并总结其安装方式，然后为我修复其中的类型错误",
  "cwd": "/path/to/your/repo",
  "model": "kimi-k3",
  "sandbox": "workspace-write",
  "approval-policy": "on-request",
  "config": {
    "model_provider": "openai"
  }
}

调用成功后返回结构化输出：{ "threadId": "...", "content": "..." }——threadId 是本次会话的线程 ID，用于后续续跑。

工具二：codex-reply（续跑既有线程）

codex 每次启动都会开启新线程，而跨多轮任务的续跑由 codex-reply 完成：

{
  "threadId": "上个 codex 调用返回的线程 ID",
  "prompt": "继续：刚才说到的第二个问题还没修完"
}

从 codex-rs/mcp-server/src/codex_tool_config.rs 的 CodexToolCallReplyParam 可以看到：thread_id 是推荐必填字段，同时保留 conversation_id 仅作向后兼容（代码注释明确标注其已废弃），二者都解析为 codex_protocol::ThreadId。换句话说，一个"长任务"在 MCP 侧的惯用编排是：先用 codex 拿 threadId，再把后续每一轮追问以 codex-reply 发回同一线程，从而让 Open Interpreter 的会话历史、上下文压缩等机制跨多次工具调用保持生效。

审批策略与沙箱的安全边界

审批策略 approval-policy

它直接映射到底层会话的 AskForApproval 语义（见 codex-rs/mcp-server/src/codex_tool_config.rs 中的 From<CodexToolCallApprovalPolicy> for AskForApproval 实现）：

取值	行为	底层语义
untrusted	仅对未被信任的命令才发起批准	AskForApproval::UnlessTrusted
on-request	请求时即询问	AskForApproval::OnRequest
never	永不请求批准（自动执行）	AskForApproval::Never

沙箱模式 sandbox

对应 SandboxMode 的三个档位，与 docs/zh/sandbox.md、docs/zh/permissions.md 描述的权限体系一致：

取值	能力范围
read-only	只读，不能修改工作空间
workspace-write	允许在工作空间内写入
danger-full-access	完全访问，等同无沙箱

信任边界提示

官方文档特意强调：保持 MCP 客户端和 Open Interpreter 处于与 CLI 相同的信任边界。因为被调用的会话仍然可以运行工具、请求批准，并根据你配置的 sandbox 和权限修改工作空间。实操建议：

• 把 MCP 服务器条目配置在受信任的主机上，避免将 stdio 描述符暴露给不可信进程；
• 面向外部不可信调用方时，优先把默认 sandbox 收敛到 read-only / workspace-write，并把 approval-policy 留在 untrusted 或 on-request；
• 通过根级 CLI 配置（如 profile）限制模型、网络与权限，再配合单次调用的 config 覆盖做精细调整——从代码结构看，profile 这类属于 CLI 全局配置层的能力由 codex-rs/cli/src/main.rs 在拉起 run_main 时注入，而非写在每次工具调用里。

服务器内部的运行机制

如果你想知道"启动会话/续跑线程"背后发生了什么，可以读 codex-rs/mcp-server/src/lib.rs 的 run_main。它的骨架非常清晰，是三条通过有界/无界 channel 串联的 tokio 任务：

1. stdin 读取任务：逐行读取 stdin，把每行反序列化为 JSON-RPC 消息（JsonRpcMessage），送入容量为 128 的入站 channel；读到 EOF 后发送方 drop，从而触发级联关停。
2. 消息处理任务：MessageProcessor 对 Request / Response / Notification / Error 四类消息分别处理——工具调用在此被翻译成真正的会话执行，涉及 exec 审批（exec_approval.rs）、patch 审批（patch_approval.rs）等子模块。
3. stdout 写出任务：把出站消息序列化成 JSON 并追加换行写入 stdout。

也就是说，它复用的是 MCP 官方推荐的 stdio 逐行 JSON-RPC 约定，配合 rmcp（Rust MCP 库）提供的模型类型。服务启动时还会带上 OTEL_SERVICE_NAME = "codex_mcp_server" 遥测服务名，并依据配置构建日志/追踪/指标导出器（该文件内的测试 mcp_server_builds_otel_provider_with_logs_traces_and_metrics 验证了这一点），这意味着你沿用的 OTel 观测管线在 MCP 服务器模式下同样生效。服务器还通过 EnvironmentManager 绑定到 CODEX_HOME 下的沙箱运行时路径，与 exec 等模式共享同一套沙箱基础设施。

仓库中另有 codex-rs/mcp-server/tests 集成测试，用 mcp_process 拉起真实进程、mock_model_server 模拟模型服务来端到端验证工具调用路径，可作为你排查"工具为何未返回"时的对照样例。

常见问题排查思路

• 客户端连不上 / 工具列表为空：确认注册的是 command: "interpreter", args: ["mcp-server"]，且 interpreter 在客户端进程 PATH 内；再以 interpreter mcp-server --strict-config 手动运行一次，观察配置解析是否报错。
• 报"未知字段"：工具输入参数采用 kebab-case 且禁止未知字段，检查是否把 approvalPolicy 写成了 camelCase，或传入了 Schema 之外的参数。
• 会话状态丢失：确认使用 codex-reply 并回传首次 codex 返回的 threadId；不要为续跑重新调用 codex（那会开新线程）。
• 权限过宽/过窄：审视默认 profile 的沙箱与审批配置，并通过单次调用的 sandbox、approval-policy 覆盖为每次调用声明最小权限。

总结

interpreter mcp-server 把 Open Interpreter 的完整会话能力封装成标准的 MCP stdio 服务器：codex 工具负责开新会话、codex-reply 负责续跑线程，参数面完整覆盖模型、工作目录、审批策略、沙箱与单次配置覆盖。无论你的调用方是另一个 Agent 框架还是内部工具，都可以用一段 客户端注册 JSON 立刻接入。想进一步学习沙箱与权限组合、或了解作为 MCP 客户端接入外部服务器的反向用法，可以继续阅读 docs/zh/sandbox.md、docs/zh/permissions.md 与 docs/zh/mcp.md；其 Rust 实现全貌位于 codex-rs/mcp-server。