MCP 与工具暴露

Codex 的 MCP 设计分成两步：先解析 runtime server config，再决定本轮哪些 MCP tools 对模型可见。

McpManager

codex-rs/core/src/mcp.rs 的 McpManager 负责生成 runtime MCP config：

  1. 从用户配置读取 MCP server。
  2. 从插件读取 MCP server。
  3. 从 extension registry 读取 McpServerContributor 的 overlay。
  4. 加入兼容性内置 server，例如 apps MCP。
  5. 解析冲突并生成 catalog。

它暴露三个层次：

  • configured_servers：配置和插件提供的 server。
  • runtime_servers：加上 runtime extension contribution。
  • effective_servers：再经过 auth gating 和兼容性内置逻辑。

Extension Overlay

扩展可以贡献：

  • Set：设置一个 server。
  • Remove：移除一个 server。
  • SelectedPlugin：线程选择的 executor plugin 对应的 MCP server。

overlay 带 contributor_id 和 contribution_order，用于冲突解析。这比“最后写入 wins”的配置合并更可审计。

工具暴露策略

codex-rs/core/src/mcp_tool_exposure.rs 负责 MCP tool exposure。它的核心策略是：

  • 非 apps MCP 且 model-visible 的工具可进入候选。
  • apps MCP 工具需要 connector 可用，并通过 app tool policy。
  • 如果启用 tool search 且 MCP 工具过多，或 feature 强制 defer，则不直接暴露所有工具，而是进入 deferred tools。
  • DIRECT_MCP_TOOL_EXPOSURE_THRESHOLD 当前是 100。

这解决了一个常见 agent 问题：工具太多会污染 prompt、增加选择难度和 token 成本。Codex 通过 tool_search 把“大工具集合”变成可检索工具集合。

MCP 工具执行

模型调用 MCP tool 后，仍然不是直接绕过核心 harness。MCP handler 会作为普通工具进入：

ToolRouter -> ToolRegistry -> hook -> handler -> post hook -> model-visible output

这保证 MCP 工具也受同样的生命周期、遥测和安全策略管理。

MCP Resources

Codex 还暴露 MCP resources 相关工具：

  • list_mcp_resources
  • list_mcp_resource_templates
  • read_mcp_resource

这些工具也在 codex-rs/core/src/tools/handlers/mcp_resource* 下作为普通 tool handler 接入。

可学习的设计

MCP 在 Codex 中不是“外部工具直通车”，而是被纳入两层控制：

  • server 层：配置、插件、扩展贡献、auth gating、冲突解析。
  • tool 层：可见性、defer/search、connector policy、统一工具 harness。