Codex CLI接入MCP服务的全流程

前言

Model Context Protocol（MCP）可拓展 AI 工具能力，Claude、Cursor 均支持该协议，而 Codex CLI 采用 TOML 格式配置 MCP，与主流编辑器 JSON 配置存在差异。本文围绕 Codex 的 MCP 完整落地流程展开，讲解配置写法、连通性验证方法与工具实操调用，同时拆解 Codex 核心配置文件的全局、模型、多服务商模板配置，帮助开发者快速完成 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 服务的全流程，对比了 Codex TOML 格式与其他客户端 JSON 格式的配置区别，给出 Context7、Puppeteer 两类实用 MCP 配置示例，说明了故障排查方式与工具调用效果。同时详解config.toml全局权限、模型服务商、多套配置模板用法，借助 profile 参数可灵活切换模型，实现 AI 代码助手的功能拓展与自定义。

以上就是Codex CLI接入MCP服务的全流程的详细内容，更多关于Codex CLI接入MCP服务流程的资料请关注脚本之家其它相关文章！