Codex CLI 接入 MCP 服务器：config.toml 配置全字段手册

Codex CLI 通过 ~/.codex/config.toml 里的 [mcp_servers] 表声明 MCP 服务器——每个子表是一个命名服务器，stdio（本地进程）与远程 HTTP 两种形态共用一套字段集合。本文按 codex-rs 源码里的 RawMcpServerConfig 结构逐项核对字段，不凭印象写。

1. stdio 形态：本地进程

[mcp_servers.wave]
command = "python"
args = ["-m", "wave_mcp.server", "--session", "/abs/path/to/session"]
env = { "API_KEY" = "..." }
cwd = "/path/to/workdir"

stdio 形态五个字段：

• command：启动服务器进程的命令
• args：参数数组
• env：写进进程环境的字面量键值对
• env_vars：从宿主环境变量名列表取值（不把秘密写进配置）
• cwd：服务器进程的工作目录

env 与 env_vars 的区别在于秘密是否落盘：token 优先放 env_vars 指向环境变量。

2. 远程形态：HTTP 服务器

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
bearer_token_env_var = "LINEAR_TOKEN"

远程形态的关键字段：

• url：服务器端点
• bearer_token / bearer_token_env_var：直接 token 或从环境变量取
• http_headers / env_http_headers：自定义请求头（后者从环境变量取值）
• http_headers_helper：用辅助命令产 header 值的形态

3. 通用控制面

两种形态共享的控制字段：

required = true 的语义值得注意：它不是"优先尝试"，而是"缺了就让会话失败"——适合强依赖的工作流，不适合锦上添花的服务器。

4. OAuth 与 auth

auth 字段的枚举值为 oauth / chatgpt / ema_auth。需要完整 OAuth 流程的服务器用 [mcp_servers.<name>.oauth] 块，字段含 client_id、callback_url、callback_port、authorization_server_issuer。

5. 常见错误与排查

• 服务器起不来：先查 command 的绝对路径（npx/uvx 在 GUI 启动的 Codex 里 PATH 可能不同），再调大 startup_timeout_sec
• 工具看不见：检查是否被 disabled_tools 或 requirements 层过滤——Codex 有 plugin/requirements 层的 MCP 过滤机制，管理员侧 required 也会反向约束
• 秘密进了仓库：bearer_token 与 env 是明文；项目级 .codex/config.toml 会进 git，秘密一律走 *_env_var 形态

6. 下一步

• Codex CLI 沙箱模式详解：sandbox_mode 与 approval_policy 怎么配 — MCP 之外的安全边界
• OpenAI Codex CLI 入门：从零配置到日常编码流 — 基础安装与登录