Codex CLI接入MCP服务全流程指南

前言

Model Context Protocol（MCP）正在快速拓展AI工具的能力边界，Claude、Cursor等主流工具均已支持。而Codex CLI则采用TOML格式配置MCP，这与主流编辑器通用的JSON格式存在明显差异。本文将从Codex的MCP完整落地流程入手，逐步拆解配置编写、连通性验证以及实际工具调用的具体方法。同时，深入剖析Codex核心配置文件中的全局设置、模型配置与多服务商模板配置，帮助开发者快速上手自定义工具拓展。

一、MCP配置方法

Codex CLI的MCP配置需要在 ~/.codex/config.toml 文件中定义 mcp_servers 部分。这一思路与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的核心配置文件，经过调试可找到以下几个关键配置项。

全局配置

全局配置选项需要放置在配置文件的开头部分：

# 模型选择（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则定义一组模型与提供商的配置组合，便于复用。

# 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 ；也可以使用 codex -m 覆盖默认模型（注意，默认AI提供商为OpenAI）。

总结

本文完整介绍了Codex CLI接入MCP服务的全流程，对比了Codex的TOML格式与其他客户端JSON格式的配置差异，给出了Context7和Puppeteer两个实用MCP配置示例，说明了故障排查方式与工具调用效果。同时，详细解析了config.toml中的全局权限、模型服务商以及多套配置模板的用法，借助profile参数可灵活切换模型，实现AI代码助手的功能拓展与自定义配置。