Codex MCP 配置：给 Codex CLI 和 IDE 扩展添加远程 MCP 服务器

一句话概括：Codex 从 ~/.codex/config.toml 读取 MCP 服务器，CLI 会替你编辑这个文件。对远程服务器，一条命令就够了：codex mcp add unifapi --url https://mcp.unifapi.com。运行 codex mcp list 确认它已注册；如果首次使用时 OAuth 登录页没有自动打开，运行 codex mcp login unifapi。Codex IDE 扩展读的是同一个文件，所以服务器添加一次，在终端和 VS Code 里都能用。

Codex 是 OpenAI 的编程 Agent，在 CLI 和 IDE 扩展里都支持 Model Context Protocol。配置就是一个 TOML 文件，这让它成为最容易配置的客户端之一，也是最容易悄悄配错的客户端之一：服务器加到了错误的表里，或者把 stdio 服务器声明成了 URL，都不会报错，直到你真的去调用工具。本指南以 UnifAPI MCP 服务器（https://mcp.unifapi.com，来自社交平台和 SEO 技术栈的实时公开数据）为例，步骤对任何远程服务器都一样。

你需要准备什么

• Codex CLI（npm install -g @openai/codex 或 brew install codex），或者 VS Code、Cursor、Windsurf 里的 Codex 扩展。两者读的都是 ~/.codex/config.toml。
• 一个已登录的 Codex（codex login）。MCP 在 ChatGPT 登录和 API 密钥两种方式下都能用。
• 对 UnifAPI：OAuth 提示弹出时需要一个 UnifAPI 账户，首次计费调用之前需要工作区积分。浏览目录是免费的。

用 codex mcp add 添加远程服务器

远程（streamable HTTP）服务器就是一个 URL。注册它：

codex mcp add unifapi --url https://mcp.unifapi.com

确认已写入：

codex mcp list
codex mcp get unifapi

codex mcp list 会打印每个已配置的服务器及其传输方式和鉴权状态。Codex 第一次用受 OAuth 保护的服务器启动会话时，会在浏览器里打开登录页。如果没有发生，或者你在一台没有浏览器的机器上，自己触发它：

codex mcp login unifapi
# headless: print the URL instead of opening a browser
codex mcp login unifapi --no-browser

OAuth 登录只对 streamable HTTP 服务器提供；stdio 服务器没有登录这一步。令牌存在你的 keyring（或 Codex 退而使用的凭据文件）里，跨会话复用。codex mcp logout unifapi 清除令牌，codex mcp remove unifapi 删除服务器。

背后的 config.toml

CLI 写入的所有内容都是 [mcp_servers.<name>] 下的普通 TOML。UnifAPI 的条目只有一行：

[mcp_servers.unifapi]
url = "https://mcp.unifapi.com"

另外两个可选字段对其他远程服务器有用：

[mcp_servers.example]
url = "https://mcp.example.com"
# Read a static bearer token from this environment variable instead of OAuth
bearer_token_env_var = "EXAMPLE_TOKEN"
# Extra headers, literal or sourced from the environment
http_headers = { "X-Client" = "codex" }
env_http_headers = { "X-Tenant" = "EXAMPLE_TENANT" }

UnifAPI 接受带工作区 API 密钥的 bearer_token_env_var，但推荐走 OAuth：不用往 dotfile 里粘任何东西，而且令牌是只读的。

本地 stdio 服务器用 command 和 args 代替 url。两种写法互斥；混用的表会被拒绝：

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Projects"]
env = { "NODE_OPTIONS" = "--max-old-space-size=512" }

按项目配置服务器

Codex 会把项目级的 .codex/config.toml（位于仓库根目录，项目被信任时生效）合并覆盖到你的主目录配置之上。只有一个仓库需要某个服务器时，把它放在那里，并提交这个文件，让同事拿到同样的工具。codex mcp login 从合并后的配置里解析名字，所以项目作用域的 OAuth 服务器登录方式相同。

确认工具已加载

在项目里开一个会话，问一个只有服务器才能回答的问题：

用 unifapi MCP 服务器列出 Reddit 可用的操作。

在回答之前，你应该看到一次对 list_operations 的工具调用。在 IDE 扩展里，MCP 服务器及其工具列在扩展的设置面板中；那里显示红色状态的服务器，通常意味着缺少 OAuth 令牌（codex mcp login）或 URL 写错了（codex mcp get）。

取决于你的审批模式（codex --ask-for-approval，或你在 IDE 里选的模式），Codex 可能在每次工具调用前询问。对 UnifAPI 这样的只读服务器，在本会话内放行是安全的；一次调用能花掉的只有工作区积分，而且 get_operation 会在 call_api 运行之前显示每条记录的价格。

值得花这点积分的第一个任务

UnifAPI 的 MCP 服务器通过三个工具暴露一个庞大的目录：list_operations 用于发现，get_operation 用于查看 schema 和调用示例，call_api 用于执行。Codex 很擅长这种形态，因为这和它用 CLI 的循环一样：查命令、读帮助、运行。一个有边界的首个提示词：

用 unifapi MCP 工具，找到“OpenAI Developers”对应的 X 账号，拉取它最近 20 条公开帖子，给我一张表，列出帖子、点赞数、转发数和一句话主题。在 call_api 之前先调用 list_operations 和 get_operation。

计费按公开数据记录计，以工作区积分结算（每积分 $0.001；大多数记录为 1 积分，最低消耗更高的操作会在目录里标明）。模型 token 仍算在你的 OpenAI 套餐上。新工作区在首次充值之前没有积分，首次充值附带一次性赠送，所以在第一次 call_api 之前先去 UnifAPI 控制台充值一次。

对任务型的工作，平台 Agents 和 SEO Agent 给 Codex 提供了现成的提示词，以及它会用到的操作列表。

故障排查

已核查的来源

本文写于 2026 年 10 月 14 日，依据 Codex CLI 的 MCP 配置参考、当前版本中的 codex mcp 子命令（add、list、get、login、logout、remove），以及 OpenAI 开发者文档中关于 Codex MCP 的部分。config.toml 中的字段名取自 CLI 自己的 schema。

接下来可以读什么

MCP 配置 —— 每个客户端的托管连接器说明。

如何给 Claude 添加 MCP 服务器 —— 连接器、claude_desktop_config.json 和 claude mcp add。

Cursor MCP 配置 —— mcp.json 和一键安装链接。

MCP 目录工具设计 —— 为什么服务器暴露三个工具，而不是每个端点一个。