OpenAI Codex 是运行在终端里的轻量编码 Agent，MCP（Model Context Protocol，模型上下文协议）是它接入外部工具与数据源的标准协议——通过在 ~/.codex/config.toml 中配置 MCP 服务器，Codex 就能调用文档检索、浏览器、设计工具等外部能力。配置方式有两种：命令行 codex mcp add 一键添加，或手写 config.toml 的 [mcp_servers.NAME] 表；传输类型支持本地 stdio（启动本地进程）和远程 streamable HTTP（连接远程服务）两种。本文基于 OpenAI Codex 官方文档，从安装、认证讲起，逐步覆盖 stdio 与 HTTP 两种 MCP 服务器的完整配置、环境变量与密钥传递、工具审批控制和调试方法，给出可直接复制的 TOML 示例。

 

一、Codex 和 MCP 分别是什么

OpenAI Codex 是一款运行在终端里的轻量编码 Agent（官方定义：“Lightweight coding agent that runs in your terminal”），本地运行、可读写文件、执行命令。MCP（Model Context Protocol）则是一套开放协议，让 Codex 能以标准方式接入外部工具和数据源。

两者的关系可以这样理解：

● Codex 是执行主体，负责理解需求、调用工具、写代码

● MCP 是"扩展接口"，把文档检索、浏览器控制、设计文件读取等外部能力标准化地接进来

● 配置一个 MCP 服务器后，Codex 就能在对话中直接调用该服务器暴露的工具

二、第一步：安装并认证 Codex

配置 MCP 之前，先装好 Codex CLI。官方提供多种安装方式，任选其一：

 

# 方式一：官方安装脚本（macOS / Linux）
curl -fsSL https://chatgpt.com/codex/install.sh | sh
 
# 方式二：npm 全局安装
npm install -g @openai/codex
 
# 方式三：Homebrew（macOS）
brew install --cask codex

安装完成后，在终端运行 codex 并选择 Sign in with ChatGPT 完成认证（支持 Plus、Pro、Business、Edu、Enterprise 套餐）；也可使用 API Key 方式接入，需按官方文档做额外配置。

三、MCP 配置文件在哪：config.toml

Codex 的 MCP 配置存放在 TOML 文件中，分全局与项目两个作用域：

作用域

路径

说明

全局

~/.codex/config.toml

对所有项目生效

项目级

.codex/config.toml

仅对当前项目生效，且仅限受信任项目

配置 MCP 服务器有两条路径：用 codex mcp add 命令自动写入，或手动编辑 config.toml。前者适合快速添加，后者适合精细控制。

四、第二步：添加一个 MCP 服务器（stdio 本地方式）

最常见的是 stdio 传输——Codex 启动一个本地进程作为 MCP 服务器。以接入 Context7 文档检索服务为例。

方法 A：命令行一键添加

 

# 语法：codex mcp add <名称> --env 变量=值 -- <启动命令>
codex mcp add context7 -- npx -y @upstash/context7-mcp
 
# 查看所有 MCP 相关命令
codex mcp --help

方法 B：手写 config.toml

 

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
 
# 为该服务器单独设置环境变量
[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

stdio 服务器的主要字段：

字段

必填

说明

command

✅

启动服务器的命令

args

❌

传给服务器的参数

env

❌

服务器专用环境变量

env_vars

❌

从本地/远程环境转发的变量名

cwd

❌

工作目录

五、第三步：接入远程 HTTP MCP 服务器

如果 MCP 服务器是远程托管的（如 Figma），使用 streamable HTTP 传输，通过 url 指向服务地址：

 

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

HTTP 服务器的主要字段：

● url（必填）：服务器地址

● bearer_token_env_var：存放 Bearer Token 的环境变量名（密钥不写死在配置里）

● http_headers：静态请求头

● env_http_headers：从环境变量取值的请求头

对于需要 OAuth 登录的远程服务器，用 codex mcp login <server-name> 完成授权。

六、密钥与环境变量：安全传递凭证

MCP 服务器常需要 API Key 或 Token，正确做法是通过环境变量传递，绝不把密钥硬编码进 config.toml。

stdio 服务器可用 env_vars 从本地或远程环境转发变量：

 

# 字符串条目和 source = "local" 从 Codex 本地环境读取
# source = "remote" 从远程执行器读取
env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

HTTP 服务器则用 bearer_token_env_var 指定存放 Token 的环境变量名，Codex 运行时自动读取并注入请求头，这样密钥只存在于环境变量中，配置文件可安全提交版本库。

七、进阶：控制工具暴露范围与审批模式

一个 MCP 服务器可能暴露很多工具，你可以按需限制，并控制哪些工具需要人工确认。stdio 和 HTTP 服务器都支持以下通用选项：

 

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled = true
required = false
startup_timeout_sec = 20        # 启动超时，默认 10 秒
tool_timeout_sec = 45           # 工具调用超时，默认 60 秒
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # 在 enabled_tools 之后应用
default_tools_approval_mode = "prompt"  # auto | prompt | approve
 
# 单独为某个工具设置审批模式
[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"

审批模式三档含义：

● auto：自动执行，不弹窗

● prompt：每次调用弹窗确认（最安全，推荐用于有副作用的工具）

● approve：需明确批准

八、第四步：查看与调试已加载的 MCP

配置完成后，需要确认服务器是否正常加载。在 Codex 的 TUI 界面中，输入斜杠命令查看当前活跃的 MCP 服务器：

 

/mcp

如果服务器没起来，优先检查三点：command 路径是否正确、所需环境变量是否已设置、startup_timeout_sec 是否够长（默认 10 秒，对首次 npx 拉包的服务器可能偏短，可调到 20 秒以上）。

常见问题

Q：Codex 的 MCP 配置文件到底在哪？

全局配置在 ~/.codex/config.toml，对所有项目生效；项目级配置在项目目录下的 .codex/config.toml，仅对当前项目且仅限受信任项目生效。MCP 服务器写在 [mcp_servers.名称] 这样的 TOML 表下。

Q：codex mcp add 和手写 config.toml 有什么区别？

codex mcp add <名称> -- <命令> 会自动把配置写入 config.toml，适合快速添加；手写 config.toml 则能精细控制 enabled_tools、startup_timeout_sec、审批模式等高级字段。两者最终都落到同一个配置文件，可混用。

Q：stdio 和 streamable HTTP 传输怎么选？

stdio 适合本地运行的 MCP 服务器（Codex 启动一个本地进程，用 command/args 指定），HTTP 适合远程托管的服务器（用 url 指向地址）。本地工具选 stdio，云端服务选 HTTP。

Q：怎么给 MCP 服务器安全地传 API Key？

不要把密钥写进 config.toml。stdio 服务器用 env_vars 从环境转发，HTTP 服务器用 bearer_token_env_var 指定存放 Token 的环境变量名，Codex 运行时自动读取，配置文件本身不含明文密钥。

Q：MCP 服务器加载失败怎么排查？

先在 TUI 里用 /mcp 查看服务器状态，再依次检查 command 路径、环境变量是否就绪、startup_timeout_sec 是否过短（默认 10 秒，首次拉包建议调大）。

结语

Codex + MCP 的配置可以归纳为一条主线：在 ~/.codex/config.toml 里用 [mcp_servers.NAME] 声明服务器，本地工具走 stdio、远程服务走 HTTP，密钥一律通过环境变量传递，用审批模式控制工具风险。据 OpenAI Codex 官方文档，codex mcp add 命令和手写 TOML 是等价的两条路径，/mcp 是最直接的调试入口。开发者在国内接入 MCP 生态时，也可借助标准化的 MCP 服务编排平台无需本地部署即可构建 Agent 应用，例如七牛云 MCP 服务就提供了国内可直接访问的模型能力编排能力。

本文内容基于 2026 年 7 月 OpenAI Codex 官方文档，配置字段可能随版本更新变化，建议以官方文档最新说明为准。

延伸资源

● MCP 服务编排与 Agent 构建指南：https://developer.qiniu.com/aitokenapi/12984/mcp-user-manual