Codex CLI接入MCP服务的全流程

本文围绕Codex CLI接入MCP服务的全流程整理关键信息和实用建议，帮助读者快速了解主题重点。

前言 Model Context Protocol（MCP）可拓展 AI 工具能力，Claude、Cursor 均支持该协议，而 Codex CLI 采用 TOML 格式配置 MCP，与主流编辑器 JSON 配置存在差异。本文围绕 Code

前言

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 ；当然，也可以用 codex -m 来覆盖默认模型（注意这里使用默认的 AI 提供商，即 OpenAI）。

总结

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

以上内容可作为基础参考，实际处理时再结合具体场景灵活调整。