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/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代码助手的功能拓展与自定义。