给 Codex 接一个 MCP server 的完整流程：配置、启动超时与工具审批怎么调

2026-08-09

给 Codex（OpenAI Codex）接一个 MCP server，网上流传的做法通常就是甩一段配置让你贴进去。贴完能跑当然好，跑不起来的时候你会发现自己完全不知道该看哪里——是配置没加载、server 启动太慢被掐了，还是工具被审批弹窗挡在门口。这篇把整条链路按配置键拆开讲，配置怎么写、写完之后产出物长什么样、人工验收要盯哪几处、以及什么情况下别用这套路子。

下面所有配置键都来自 Codex 官方的《Configuration Reference》页（核对日 2026-08-09），标注「本机实测」的部分来自 codex-cli 0.147.0（Windows 11）上执行的只读命令。需要提前说清楚：本文写作过程中没有发起过任何模型对话请求，所以你不会在这里看到”我让它调了个工具、返回了什么”的描述——那部分得你自己在真机上验。

一、先认清两种形态：stdio 和 streamable HTTP

Codex 的 MCP 配置都挂在 config.toml 的 mcp_servers.<id> 下面，<id> 是你自己起的名字，后面 codex mcp list 里显示的 Name 就是它。

官方参考页把这一节的键分成两类：

stdio 型：command、args、env、env_vars、cwd。你本地起一个进程，Codex 通过标准输入输出跟它说话。
streamable HTTP 型：url。指向一个远端地址。

配套的认证相关键有：auth（默认 oauth，也可以设 chatgpt）、bearer_token_env_var、http_headers、env_http_headers、scopes、oauth_resource。CLI 侧 codex mcp 有 list / get / add / remove / login / logout 六个子命令，其中 login / logout 这两条本机没跑过（跑了就等于发起真实认证流程），只能说它们存在。

二、配置怎么写：可直接复制的两段

先给 stdio 型的完整写法：

[mcp_servers.my_local_tool]
command = "node"
args = ["./mcp/server.js"]
cwd = "./mcp"
enabled = true
required = false
startup_timeout_sec = 120
tool_timeout_sec = 180
enabled_tools = ["search_docs", "read_note"]
disabled_tools = ["read_note"]

[mcp_servers.my_local_tool.env]
MY_TOOL_API_KEY = "<YOUR_API_KEY>"

逐键说为什么在这：

command / args：启动进程的可执行文件与参数。这里分开写而不是拼成一行字符串，是因为参数是数组，含空格的路径不会被切碎。
cwd：进程的工作目录。很多 server 会按相对路径找自己的资源文件，不设 cwd 就会按 Codex 的当前目录去找，然后报一个跟 MCP 毫无关系的”文件找不到”。
enabled：官方标默认 true。写出来是为了让”临时停掉某个 server”这件事有个明确开关，而不用整段注释掉。
required：官方说明是——启用的 server 初始化失败时，整个启动就失败。CI 里建议开，因为你宁可红一次也不想让任务在缺工具的情况下悄悄跑完；本地日常调试建议关。
startup_timeout_sec：官方默认只有 10 秒。这是接 MCP 最常见的翻车点，下一节单独说。
tool_timeout_sec：官方默认 60 秒，单个工具调用的超时。
enabled_tools / disabled_tools：白名单与黑名单。官方明确写了 disabled_tools 在 enabled_tools 之后生效，所以上面这段示例的实际效果是只剩 search_docs——read_note 虽然进了白名单，还是被后一步 deny 掉了。这个顺序容易踩，两个都配的时候以 deny 为准。
env：给子进程注入环境变量。密钥这类东西正文里一律写占位符，真机上换成你自己的值。

streamable HTTP 型要短得多：

[mcp_servers.my_remote_tool]
url = "https://example.com/mcp"
auth = "oauth"
bearer_token_env_var = "MY_REMOTE_TOKEN"
startup_timeout_sec = 60
tool_timeout_sec = 120

bearer_token_env_var 存的是环境变量名，不是 token 本身——这是个设计得比较克制的地方，配置文件里从头到尾不出现凭据明文。

以上两段为按官方文档键位组合的示例，未逐项实测，以官方文档为准。

不想改文件的话，CLI 顶层的 -c, --config <key=value> 可以临时覆盖，点号表示嵌套路径。要注意它的解析规则：value 按 TOML 解析，解析失败则按字面字符串处理——所以打错括号不一定报错，可能默默变成一个字符串塞进去了。

三、超时：默认值决定了你会不会白折腾一晚上

startup_timeout_sec 默认 10 秒这件事，值得单拎出来。任何需要装依赖、拉索引、连数据库、冷启动虚拟机的 server，10 秒都不够。它超时之后你看到的现象通常不是”超时”三个字，而是这个 server 干脆不在工具列表里——很容易被误判成”配置没写对”。

本机 codex-cli 0.147.0 的 config.toml 里，就有一个启动较慢的 stdio server 把 startup_timeout_sec 显式设成了 120。这个值不是官方推荐值，只是一个实际存在的取法，说明”默认 10 秒不够用”是真实会发生的情况。

官方参考页同时列了 startup_timeout_ms（毫秒版）。两个都有的时候用哪个、谁优先，参考页没写，别猜——挑一个用，然后按下一节的办法去验收它有没有生效。

tool_timeout_sec 默认 60 秒管的是单次工具调用。跑长任务的工具（大目录扫描、批量拉取）需要调大；反过来，如果你希望坏掉的工具早点失败而不是一直吊着，也可以调小。

另外提醒一句：features.skill_mcp_dependency_install 官方标默认 true，含义是允许提示并安装 MCP 依赖。这解释了为什么有些环境下你会被问”要不要装依赖”——那是这个开关在起作用，不是 server 本身的行为。

四、审批调优：字符串档位不够用就换表

审批相关的键分两层。

第一层是全局的 approval_policy。它有两种写法：写成字符串就是粗粒度三档 untrusted / on-request / never；写成表就能拿到细粒度开关。跟 MCP 直接相关的是 approval_policy.granular.mcp_elicitations——官方说明是”MCP elicitation 弹窗允许还是自动拒绝”。想只放行某一类弹窗，就必须用表形式，字符串档位做不到。

这里有个容易理解反的地方：never 的官方释义是”从不询问，执行失败直接回传给模型”。它是”不问你”，不是”什么都放行”——被沙箱挡住的操作照样失败，只是失败结果直接甩给模型自己处理。

第二层是 server 级别的 default_tools_approval_mode 和 tools.<tool>.approval_mode，前者给这个 server 的所有工具定基调，后者针对单个工具覆盖。官方参考页在 MCP 这一节只给了键名、没有列取值枚举，所以本文不替它编一份；要用的话去官方页确认当前版本接受哪些值。

五、产出物长什么样

接完之后能拿到的东西，本机在 codex-cli 0.147.0（Windows 11）上实测是这两处：

codex doctor --summary 的 Configuration 分组里有一行 mcp，本机格式是 N server (N stdio) · N disabled。数量对不上就说明有 server 没被算进来。doctor 结尾会打一行统计，形如 17 ok · 1 idle · 1 notes · 0 warn · 0 fail，状态符号有四种：✓（ok）、○（idle）、⚠（notes/warn）、✗（fail）。codex doctor --json 的官方说明是”Emit a redacted machine-readable report”，同样是脱敏的，可以直接贴给别人看。

六、怎么验收：四步，以及每步最容易错在哪

第一步，确认配置真的加载了。 这一步优先级最高，因为本机实测过一个很有价值的现象：故意给 -c 传语法不合法的 TOML（codex -c 'features=[unclosed' doctor --summary），命令没有崩溃退出，doctor 照常跑完，只是 Notes 区多了一行：

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

也就是说配置整个坏掉的时候，Codex 不会拦着你，它照常启动、照常干活，只是你新加的 MCP server 完全不存在。所以”改完配置没生效”的第一反应应该是跑 codex doctor --summary 看这一行，而不是回去反复改配置。

第二步，看数量。 doctor 里 mcp 那行的 server 数与 disabled 数，跟你的预期对得上吗？对不上，先怀疑 enabled 写成了 false，或者 server id 写重了被后一段覆盖。

第三步，看 codex mcp list。 你的 server 出现在 Name 列里没有？Command / Args / Cwd 回显的是不是你写的那些？Env 列的键名齐不齐（值看不到是正常的，那是脱敏）？

第四步，才是真机上调用工具。 前三步是纯只读的，几秒钟就能跑完；第四步要花额度、要等模型，所以顺序别倒过来。本文没做第四步，你自己做的时候重点看两件事：工具是不是按 enabled_tools / disabled_tools 的最终结果出现（记住 deny 优先），以及有没有在超时边界上被掐。

关于 --strict-config 的一个边界，本机实测值得单说：执行 codex -c model_reasoning_effortt=high --strict-config exec --help（注意键名故意多打了一个 t），结果正常打印 help，没有报未知字段错误。说明这个校验发生在真正加载配置去跑会话的时候，--help 这类不进入会话的路径不触发。所以别把它当成”任何情况下都能帮我拦住拼写错误”的保险；拼错的 mcp_servers 子键，得走真实会话路径才可能被它抓到。

七、什么情况不适用

想验证工具的实际行为，光靠上面这套只读验收不够。前四步只能证明”Codex 认识你这个 server”，证明不了工具调用的正确性——那必须真跑，而且要人工看结果。
插件自带的 MCP server 不走 mcp_servers 这一套。官方参考页给的是另一组键 plugins.<plugin>.mcp_servers.<server>.*，管插件自带 server 的启停与工具审批。本机 codex plugin list 实测的输出结构也是另一套（按 marketplace 分组，列 PLUGIN | STATUS | VERSION | PATH），跟 codex mcp list 不是一回事，别混着排查。
experimental_environment（取值 local / remote） 这个键名字里就带 experimental_，属于还在动的东西，别把它写进团队要长期维护的配置里。
桌面应用、Codex cloud、IDE 扩展上的 MCP 配置方式本文完全没有实测，官方文档给的做法请以官方页面为准，别把 CLI 这套路径直接套过去。
凭据管理别偷懒。env 里写明文 key 只适合你自己机器上的临时验证；配置要进仓库的话，用 bearer_token_env_var 这类”存变量名”的键。顺带一提，shell_environment_policy.ignore_default_excludes 官方标默认 true，含义是保留（不是排除）含 KEY、SECRET、TOKEN 的变量——这个键名读起来容易理解反，配环境变量前值得确认一下自己理解的方向对不对。

最后，版本号这件事：本机采集时开头 codex --version 是 0.131.0，十几分钟后再执行同一命令就变成了 0.147.0，which -a codex 全程只有一个可执行文件。Codex 有自更新能力（config 里 check_for_update_on_startup 默认 true），默认值和键名都可能随版本变。所以排查 MCP 问题时，第一件事是跑一次 codex --version 看实时输出，别用记忆里的版本号，也别拿别人半年前的配置当模板照抄。