Codex MCP 配置：连接 HTTP 服务、检查工具与排查超时

先确定你拿到的是地址还是启动命令

MCP 为 Codex 提供外部工具和信息，不会替你配置模型 API。服务作者提供 URL 时通常选择 Streamable HTTP；提供可执行命令与参数时选择 STDIO。不要把网页首页当作 MCP 地址，也不要把模型 Base URL 填入 mcp_servers。

先用一个 HTTP 服务建立最小连接

~/.codex/config.toml · 地址和工具名需来自服务作者

[mcp_servers.team_docs]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "TEAM_DOCS_TOKEN"
enabled = true

mcp.example.com 是占位地址。若服务不使用 Bearer Token，就移除 bearer_token_env_var，并按服务实际要求配置；需要 OAuth 的服务可运行 codex mcp login team_docs。这里是 MCP 自身的认证，与模型供应商 Key 不要混用。

列出连接并查看本机支持的命令

codex mcp list
codex mcp --help

本地 STDIO 的重点是启动环境

本地服务示意 · 替换为已安装服务的真实路径

[mcp_servers.local_docs]
command = "/absolute/path/to/your-mcp-server"
args = ["--stdio"]
env_vars = ["TEAM_DOCS_TOKEN"]
startup_timeout_sec = 20

这不是一个可直接运行的服务安装命令。请换成你已安装、来源明确的服务及其参数。终端能找到的命令，图形客户端不一定能从 PATH 找到；必要时使用绝对路径，并确认客户端启动环境可用。

配置了服务，还要确认工具出现

保存用户配置并重新建立连接；客户端提供 Restart 时使用它，CLI 可启动新会话。
用 codex mcp list 检查配置记录，在交互 CLI 中用 /mcp 检查会话可用工具。
先选择一个只读操作，例如查询某份公开文档的标题。明确指定服务和工具用途。
检查结果是否来自目标服务，而不是模型凭记忆回答；同时确认服务侧请求成功。

按失败阶段排查

失败阶段	优先看什么
本地进程起不来	command 路径、args、运行时安装和启动环境
HTTP 401 / 403	MCP Token、OAuth 状态与服务侧权限
连接超时	端点、网络、代理和服务是否在线
已连接但没有预期工具	工具列表、enabled_tools / disabled_tools 与服务实现
工具调用超时	操作本身的耗时及 tool_timeout_sec，而不只是启动超时

只在确定服务器确实需要更长时间时才增加超时。startup_timeout_sec 和 tool_timeout_sec 对应不同阶段；盲目拉长两个值，只会让坏地址更晚失败。

先限制范围，再逐步扩展

要限定工具，使用服务实际公开的 enabled_tools 名称；禁用时可设 enabled = false，而不是删除整份用户配置。MCP 能否改外部系统取决于服务和账号权限，本地文件只读并不表示所有远程工具也只读。下一步看权限与审批，或回到配置文档。

依据与版本说明

依据以下官方文档整理。示例中的地址、模型和路径需按你的环境替换；旧版本与组织管理环境可能有不同限制。

资料核对日期：2026-10-22