Codex CLI接入MCP服务的完整教程

熟悉AI 代码助手的朋友应该都知道，MCP 协议是拓展工具能力的核心，不管是 Claude、Cursor 主流编辑器，都全面支持这个协议，能极大丰富 AI 的实操能力。但很多人踩坑发现，通用的 JSON 格式 MCP 配置，放到 Codex CLI 里完全不生效。

最核心的原因就是 Codex CLI 采用了独特的 TOML 配置格式

我自己实操调试了很久，踩遍了配置不生效、MCP 服务连接失败、模型切换异常等坑，今天把 Codex CLI 专属的 MCP 完整落地流程、核心配置写法、连通性验证方式，还有全套核心配置文件模板一次性整理出来，大家直接复制套用，就能快速给 Codex 自定义拓展各类实用工具。

一、配置 MCP

Codex CLI 可以通过在 ~/.codex/config.toml 中定义一个 mcp_servers 部分来配置 MCP，和 Claude 和 Cursor 在各自的 JSON 配置文件中定义 mcpServers 一样，但是 Codex 的格式略有不同，它使用 TOML，而不是 JSON。

比如我添加了以下几个 MCP：

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "test" = "123456" }

[mcp_servers.puppeteer]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-puppeteer"]
env = { "test" = "123456" }

二、验证 MCP

目前来说，Codex 还没有提供专门的命令来验证 MCP 服务器的集成情况，不像 Claude Code / Gemini CLI 能提供详细的 MCP 连接信息，相信后续迭代会添加上。

不过，要是在启动 Codex 时，如果连不上你配置的 MCP server，就会给出错误信息。比如我故意把 @upstash/context7-mcp 改成 @upstash/context7-mcp1 后，再执行 codex：

三、使用 MCP

例如，我来测试下使⽤ context7 这个 MCP Server：

如图所示，控制台已经显示成功调⽤ context7 ⼯具，并成功输出了代码。

四、关于~/.codex/config.toml

~/.codex/config.toml 是 Codex 核心配置文件，我调试了半天找到几个关键配置。

首先是全局配置，这些选项需要放在配置文件开头部分：

# 模型选择 (GPT-5 + High 推理)
model = "gpt-5"
model_reasoning_effort = "high"

# 默认模型提供商
model_provider = "openai"

# 沙盒策略 (支持 read-only、workspace-write、danger-full-access、elevated)
sandbox_mode = "workspace-write"

# 审批策略 (支持 on-failure、on-request、untrusted 以及 never)
approval_policy = "on-failure"

然后是模型配置，包含 Model Provider 和 Profile 配置。Model Provider 定义了 AI 提供商的配置，比如 API 类型、URL、API Key、Header 等；而 Profile 则定义了模型和 AI 提供商的一组配置，方便配置的复用。

# Model Providers
[model_providers.openrouter]
name = "Open Router"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "chat"
query_params = {}

[model_providers.openai]
name = "OpenAI using Chat Completions"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

# Profiles
[profiles.o3]
model = "o3"
model_provider = "openai"
approval_policy = "never"
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"

[profiles.gpt5]
model = "openai/gpt-5"
model_provider = "openrouter"

配置好之后，你可以通过 Codex 的命令行参数来选择，比如 codex -p <profile>；当然，也可以用 codex -m <model> 来覆盖默认模型（注意这里使用默认的 AI 提供商，即 OpenAI）。

总结

Codex CLI 的 MCP 配置门槛不高，最大的难点就是和主流工具的 JSON 配置格式不互通，很容易照搬配置踩坑。这篇文章帮大家理清了核心差异，同时给出了可直接落地的 Context7、Puppeteer 实用 MCP 配置，还有专属的故障排查思路。

除了 MCP 拓展，我也把 Codex 核心的全局权限、沙盒策略、审批规则、多模型服务商、多套 Profile 切换模板全部整理到位。通过这套配置，我们可以灵活切换 OpenAI、OpenRouter 等不同服务商和模型，按需调整工具权限，彻底实现 Codex 能力的自定义拓展。

整套配置都是我实测可用的落地方案，没有冗余内容。按照本文配置完成后，不仅能成功接入各类 MCP 工具，拓展 Codex 的实操能力，还能通过多 Profile 配置适配不同开发场景，兼顾实用性和灵活性，一劳永逸解决 Codex 自定义配置、工具拓展的各类问题。

以上关于Codex CLI接入MCP服务的完整教程的文章就介绍到这了，更多相关内容请搜索码云笔记以前的文章或继续浏览下面的相关文章，希望大家以后多多支持码云笔记。