如果你最近在折腾 Codex 和 MCP，大概率和我遇到的情况差不多：教程翻了不少，照着贴了一堆配置，结果 Codex 要么不认这些 server，要么直接报错。上周我帮一个朋友排查“配好了 filesystem server 但模型始终说没有这个工具”的问题，折腾半天最后发现他用的是三个月前装的 Codex 旧版本，压根没带完整的 MCP 支持。
我写这篇不是想做概念复读，就按实际使用顺序讲清楚三件事：配置写在哪儿、Server 怎么接进去、出了问题按什么链路查。文末会专门拆一个最近很热的报错——cc switch local proxy failed while handling codex endpoint /responses，这类错看着吓人，其实定位起来并不复杂。
1. MCP 在 Codex 里不是插件，是一套“工具外挂协议”
1.1 先把 Host / Server / Client 三个角色分清
很多人一上来就搜“MCP 是什么”，然后看到一堆术语直接劝退。其实用插座和电器来理解就通了：MCP 是一个开放协议，规定了“想要给智能体外接工具的进程”和“智能体本体”之间怎么对话、怎么传递请求、怎么返回结果。
在 Codex 的语境里，Codex 本体就是 MCP Host，它负责发起会话、调度模型、决定什么时候需要外部工具。MCP Server 则是独立运行的进程，它可以是本地的 Python 脚本、Node.js 包，也可以是远程的 HTTP 服务。Codex 内部会有一个 MCP Client 组件，负责按照协议和各个 Server 建立连接、收发消息。
这三个角色必须分清，因为后面所有配置和报错定位都建立在“你到底在配哪个角色”之上。比如你配的是mcp_servers，改变的是 Codex 能调用哪些外部能力；而你改model_provider，改变的是 Codex 用哪个模型来思考。前者是给智能体装手臂和眼睛，后者是给智能体换大脑，完全是两件事。
1.2 调用链是什么样：从一句指令到工具返回结果
理解调用链，比你记住一百条配置项都重要。实际发生过的一次完整调用是这样的：
你给 Codex 发一句“帮我把当前目录下所有大于 10MB 的文件列出来”。Codex 内部先把这句话交给模型推理，模型判断“我需要遍历目录、看文件大小”，于是向 Codex 发出一个调用某 MCP 工具的信号。Codex 的 MCP Client 把这个请求翻译成协议格式，通过 stdio 传给对应的 MCP Server 进程。Server 执行完文件扫描，把结果作为文本内容块返回。Codex 把结果拼回上下文，模型基于这个结果生成给你的最终回答。
这条链路里最关键的一点是：MCP Server 只负责执行和返回数据，不负责“思考”。最终决定“要不要用这个工具、拿到结果后怎么理解”的，是模型本身。所以我经常跟人说，别指望挂上一个 MCP Server 模型就会自动变聪明，工具只是提供了数据通道和操作通道，推理质量还得看模型。
传输方式上，绝大多数本地 MCP Server 用的是 stdio，也就是 Codex 把 Server 当子进程拉起来，通过标准输入输出通信。另一些远程 MCP Server 通过 HTTP 或 SSE 暴露端点，Codex 以客户端身份连接。两种方式在配置文件里的写法差别很大，后面会分别给示例。
1.3 Codex 对 MCP 支持的范围与边界
先说结论：Codex 目前对 MCP 的支持是“可用，但还在快速迭代”。不同版本之间的字段名、行为可能有差异，我下面写的内容以我当前在用的版本为准，如果你发现某些字段不识别，先考虑是不是版本太旧。
几个边界问题需要心里有数。比如，一个 MCP Server 启动失败不会让 Codex 整体崩溃，只是那个工具在本次会话里不可用，模型会告诉你“没有这个工具”或者“调用失败”。再比如，MCP Server 的进程权限和 Codex 基本一致，等于你本机用户的权限，所以给 Server 配 token、配目录、配数据库连接串的时候，要想清楚它一旦被乱调用会造成什么后果。
还有一个常见的认知误区：Codex 的 IDE 插件（比如 VS Code 扩展）和命令行工具，读的其实是同一份配置文件。很多人以为插件里有一套独立的 MCP 设置面板，找了半天没找到，其实配置入口就是那份config.toml。
2. 配置文件的位置与权限：全局、项目级和 IDE 是同一份
2.1 config.toml 才是真正的入口
Codex 的 MCP 配置不是存在 UI 界面里，而是写在一个叫config.toml的 TOML 格式文件里。全局配置文件在 Linux/macOS 下位于~/.codex/config.toml，Windows 下位于%USERPROFILE%\.codex\config.toml。注意是 TOML 格式，不是 JSON，网上很多示例直接贴 JSON 进去，Codex 解析必挂。
一个最小可用的全局 MCP 配置长这样：
model = "gpt-5-codex" model_provider = "openai" [mcp_servers.filesystem] command = "npx" args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]这里[mcp_servers.filesystem]表示注册一个名为filesystem的 MCP Server，command是启动命令，args是传给命令的参数。Codex 在需要时就会去执行npx -y @modelcontextprotocol/server-filesystem /Users/yourname/projects这个命令，把进程拉起来通信。
如果你要给某个 Server 传环境变量，用env字段，里面用 TOML 的键值对形式写：
[mcp_servers.github] command = "npx" args = ["-y", "@modelcontextprotocol/server-github"] env = { "GITHUB_PERSONAL_ACCESS_TOKEN" = "ghp_xxx" }修改完配置文件之后，一定要重启 Codex 会话或者重开 IDE 窗口，配置才会生效。这个“重启”动作很多人漏掉，后面会专门说。
2.2 全局 MCP 与项目级 MCP 的取舍
除全局配置外，Codex 还支持项目级配置。你可以在某个项目的根目录下创建.codex/config.toml，把只针对这个项目生效的 MCP Server 放进去，字段名用的是project_mcp_servers：
[project_mcp_servers.buildtools] command = "python" args = ["/path/to/project/tools/build_server.py"]全局配置适合放通用工具，比如 filesystem、github、数据库客户端，因为你不管打开哪个项目都可能用到。项目级配置适合放绑定特定项目的脚本，比如这个项目独有的构建检查工具、内部接口封装，项目里每个人都用得上，但别的项目完全不需要。
两个层级同时配置同一个名字的 Server 时，项目级会覆盖全局，这个行为可以用来做局部定制。比如全局挂了一个默认的数据库 MCP，某个项目需要连另一套库，就在项目级配一个同名 Server，指向另一个地址。
从权限角度考虑，项目级配置一般不应该放入敏感 token，因为它是跟着代码仓库走的，一旦提交到 Git 就会泄密。即使放在.codex/config.toml里，也要确保.gitignore把.codex/目录或者至少其中的配置备份排除掉。
2.3 改了配置不生效？先别怪 Codex
我见过太多人改了配置文件之后对着 Codex 喊“为什么没有”，最离谱的一次是发现自己把配置写进了auth.json——那是存登录凭证的文件，根本不是配置入口。排查“配置不生效”时，按下面这个顺序来，基本能覆盖九成的情况：
第一，确认 TOML 语法没问题。TOML 对缩进和括号的要求比 JSON 宽松，但它有自己的坑，比如字符串里出现特殊字符要加引号，数组用中括号。一个快速验证方法是把配置片段丢到任意 TOML 校验工具里跑一遍。
第二，确认你改完配置后重新开了会话。Codex 只会启动时读取配置，不会热加载。如果你是在命令行里敲codex，那要退出再进；如果你用的是 IDE 插件，最好把窗口整个关掉重开。
第三，确认 npx 真的把包拉下来了。npx -y @modelcontextprotocol/server-filesystem首次运行需要联网下载，如果网络状态不好或者 npm registry 很慢，会卡很久，看起来像配置失败，实际上是在默默下载。可以先在终端里手动跑一遍这个命令，确认能正常进入 server 的等待状态，再回来配 Codex。
第四，确认没有其他工具在“帮倒忙”。现在有很多第三方配置切换工具会重写config.toml，它们认识老字段，但未必认识最新的mcp_servers段落。你配好 MCP 后，切了一下模型供应商配置，MCP 段落就没影了。这个问题下文讲 cc-switch 时会展开。
3. 把第一个 MCP Server 跑起来：三种典型接入方式
3.1 filesystem 官方参考实现，最适合试水
如果你想验证 Codex 的 MCP 链路通不通，别第一个就上复杂的自定义服务，先用官方维护的 filesystem server 试水，它能读文件、列目录、看文件信息，足够验证配置和调用链。
配置就三段，写在全局config.toml：
[mcp_servers.filesystem] command = "npx" args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]这里要注意两个细节。第一个，目录参数要写绝对路径，MCP Server 启动后只会向你授权的目录提供服务，授权范围就是 args 里列出的那几条路径，想访问多个目录就多写几个。第二个，Windows 下如果npx直接执行失败，改成：
[mcp_servers.filesystem] command = "cmd" args = ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\projects"]配好之后重启 Codex，新开会话，直接问一句“你能用哪些工具”，模型会把它当前可见的工具列表告诉你，里面应该包括 filesystem 暴露的read_file、list_directory、get_file_info这些条目。更直接的验证方式是让它“帮我列出 /Users/yourname/projects 下的所有文件”，如果它能正确返回目录结构，说明整条链路已经通了。
3.2 自定义 Python 脚本：把内部接口变成 MCP 工具
filesystem 只是官方示例，真正让 MCP 值钱的是把你自己内部的接口、脚本、数据源封装成工具。比如你有个内部服务只在公司内网暴露，没有现成的 API 网关，那就可以写一个小 MCP Server 把它包起来，让 Codex 能直接查数据、发命令。
用 Python 官方 SDK 写一个最小 server 非常简单。先装依赖：
pip install mcp然后写一个my_tools_server.py：
from mcp.server.fastmcp import FastMCP mcp = FastMCP("MyTools") @mcp.tool() def get_stock_price(code: str) -> str: """查询指定股票代码的当前价格，code 例如 600519""" # 这里替换成你实际的内部接口调用逻辑 return f"{code}: 100.00" @mcp.tool() def health_check() -> str: """检查本地服务是否存活""" return "alive" if __name__ == "__main__": mcp.run()这里面每个被@mcp.tool()装饰的函数，都会对外暴露成一个可供 Codex 调用的工具。函数名、参数、docstring 会被作为工具的元信息发给模型，所以 docstring 一定要写清楚这个工具是干嘛的，参数含义是什么。因为模型是靠这些描述来决定“要不要用这个工具、传什么参数”的。
然后在config.toml里注册它：
[mcp_servers.mytools] command = "python" args = ["/path/to/my_tools_server.py"] env = { "INTERNAL_API_URL" = "http://127.0.0.1:8080", "INTERNAL_API_KEY" = "xxx" }env里传的就是这个 Python 进程能读到的环境变量，你的脚本里用os.environ.get("INTERNAL_API_URL")就能取到。这种方式比把密钥硬编码在代码里安全得多，也比写在 args 里好，因为 args 里的内容会出现在进程列表里，容易被其他进程看到。
热词里有人搜“codex 如何接入 python”，大概率想的是让 Codex 执行 Python 代码。这里顺便说清楚：Codex 本身就能在本地执行 shell 命令和 Python 脚本，这是它作为本地智能体的基础能力，不通过 MCP 实现。MCP 用于的是“把一段特定逻辑封装成可复用工具”，两者场景不一样。比如你直接让 Codex“运行 app.py 并修复报错”，它自己就能做到；但你想让 Codex“调用公司内部的上线平台接口”，那写个 MCP Server 包一层会更稳。
3.3 远程 HTTP Server：连一个可以直接访问的 MCP 服务
除了本地进程，Codex 也支持连接远程 MCP Server，也就是通过 HTTP 协议暴露的 MCP 端点。配置写法不是command，而是url加可选的headers：
[mcp_servers.remote_tools] url = "https://example.com/mcp" headers = { "Authorization" = "Bearer xxxx" }这种模式适合几种场景：MCP Server 跑在另一台机器或容器里，通过内网地址访问；使用了某个 SaaS 平台提供的 MCP 端点；或者本地起了一个 HTTP 模式的 MCP Server，Codex 用 HTTP 而不是 stdio 去连它。
远程模式有一个容易踩的坑：新版 MCP 协议规范要求远程端点实现 Streamable HTTP 传输，老一点的 SSE 端点 Codex 不一定支持。所以如果你连接一个第三方 MCP 服务失败，先确认它的传输方式是不是新版标准，别在 Codex 这边反复改配置。最简单的验证方法是用curl自己请求一下那个 URL，看返回的响应头、协议协商结果是否正常。
4. 顺着热搜词看真实场景：DeepSeek、Burp 和 Figma 到底连什么
4.1 接入 DeepSeek 是模型配置，不是 MCP 配置
“codex 接入 deepseek”最近是大热门，但这个需求本质上和 MCP 没关系，它是模型供应商的配置问题。可它为什么会和 MCP 混在一起？因为都写在同一个config.toml里，很多人改着改着就分不清哪段管什么了。
接入 DeepSeek，你改的是model_provider字段和新增的一个model_providers段落：
model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com" env_key = "DEEPSEEK_API_KEY"这里env_key表示 Codex 会从环境变量DEEPSEEK_API_KEY里读取你的 API Key。你在启动 Codex 的终端里先export DEEPSEEK_API_KEY=sk-xxx，或者写进 shell 配置文件，就行了。
请记住一个心智模型：这组配置决定的是“Codex 的大脑是谁”，而mcp_servers决定的是“Codex 的手和眼睛有哪些”。大脑换成 DeepSeek 之后，MCP Server 完全不受影响，该用还是能用。反过来也一样，你挂了十个 MCP Server，也不影响你要用哪个模型来调度它们。
实践中很多人遇到的情况是：把 DeepSeek 的 API Key 填到了某个 MCP Server 的env里，或者把 MCP Server 的 token 填到了model_providers里，两边串了之后症状非常奇怪——Codex 能启动，但一调用就 401。真遇到这种，先检查每份密钥是不是在自己该待的位置。
4.2 Codex 联动 Burp：安全测试场景怎么串起来
“codex 联动 burp mcp”这个热搜词说明安全测试圈子里已经有人在实践这条路了。简单说，Burp Suite 是一个本地运行的抓包与安全测试工具，它本身有 REST API 和扩展接口，MCP Server 可以封装这些接口，让 Codex 能读取当前代理捕获的请求、提交新的测试请求、查询扫描进度。
大致的配置方式是在本地把 Burp 跑起来，开启它的 API 端口，然后让写好的 MCP Server 通过 HTTP 和它通信，Codex 这边用command模式拉起这个 MCP Server，并在env里传入 Burp API 的地址和密钥：
[mcp_servers.burp] command = "python" args = ["/path/to/burp_mcp_server.py"] env = { "BURP_API_URL" = "http://127.0.0.1:8081", "BURP_API_KEY" = "xxx" }实际使用中，Codex 可以做这些事：从 MCP 工具里拿到 Burp 捕获的原始请求，分析请求头、参数、Cookie 结构；把模型给出的测试建议拼成新的 HTTP 请求，再通过 MCP 工具交给 Burp 转发出去；读取扫描结果，帮你判断哪些是误报。它本质上是把“人的分析助手”变成了“有执行能力的分析助手”。
这里必须提醒一句：被抓包的流量里经常带着真实用户会话和敏感数据，把这些数据直接抛给外部大模型，等于把公司的内部数据往外送。如果你一定要做这个场景，要么用本地部署的模型，要么对流经的数据做脱敏处理。工具是好的，但数据边界要自己守住。
4.3 Figma 的 token 放到哪一层才算对
搜“figma mcp token 在哪获取”的人，很多是卡在 token 生成这一步。Figma 的 Personal Access Token 在 Figma 账户设置里的 Security 页面生成，生成时要勾选files:read之类的权限范围。拿到的是figd_xxx开头的一长串。
这个 token 应该放在哪个位置？答案是 MCP Server 的env里，因为它是给 Figma 那个 Server 用的，不是给 Codex 的模型提供商用的：
[mcp_servers.figma] command = "npx" args = ["-y", "figma-mcp-server"] env = { "FIGMA_API_KEY" = "figd_xxx" }npm 上叫 figma mcp server 的包不止一个，有的维护活跃，有的一年不更新。建议优先选带官方标识、GitHub stars 较高的项目，然后先手动在终端单独跑一遍这个 server，确认它能正常读 Figma API，再配进 Codex。否则你会分不清是 token 问题、包问题，还是 Codex 集成的问题。
5. 从“cc switch local proxy failed”看一类报错的排查方法
5.1 这个报错到底发生在哪一层
最近搜 Codex 相关报错的人，很多都撞到过cc switch local proxy failed while handling codex endpoint /responses这串英文。它的特征是：看起来很深奥，里面还带着codex endpoint /responses，很容易让人以为是 Codex 本身坏了，或者是 MCP 出了问题。
先解释一下上下文。cc-switch 这类工具的作用是帮你管理多份 Codex 配置，比如同时维护 OpenAI 官方、DeepSeek、其他兼容服务好几套模型供应商配置，需要哪个就“切换”到哪个，它会重写config.toml。有些配置里包含了一个本地网关服务，Codex 通过这个网关转发模型请求，报错文本里的“local proxy”指的就是这个本地 API 网关/中转服务，不是 Codex 的一部分。
所以这个报错的本质是：Codex 把一个请求发到了本地某个服务的/responses端点，那个服务在转发/处理请求时返回了失败。它发生在模型请求层，和 MCP 工具调用是两条线。之所以很多人把它和 MCP 混在一起，是因为 cc-switch 在重写配置的时候，可能顺手把mcp_servers段落也覆盖掉了，于是模型配置和 MCP 配置同时坏了，表现成“一启动 Codex 就报这个错，MCP 工具也没了”。
5.2 逐步排查链路：从配置到服务到请求
遇到这类报错，别慌，按下面这个链路一步步来，每一步都能帮你缩小问题范围。
第一步，复现报错并确认边界。新开一个 Codex 会话，不调用任何 MCP 工具，只问一个简单问题，比如“1+1等于几”。如果这个普通对话本身就报local proxy failed，那基本可以确定问题在模型请求链路，MCP server 是无辜的。如果普通对话正常，只有涉及 MCP 操作时才报错，才需要考虑 MCP 配置的问题。
第二步，检查当前生效的配置。打开~/.codex/config.toml，重点看model_providers段落里当前 provider 的base_url指向哪里。如果它指向http://127.0.0.1:xxxx或http://localhost:xxxx，那这个本地网关服务就是报错的主角。
第三步，确认本地网关服务还活着。看对应的进程有没有在跑、监听端口是否正常。直接拿 curl 打一下：
curl -X POST http://127.0.0.1:8080/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $KEY" \ -d '{"model":"deepseek-chat","input":"hello"}'如果 curl 本身返回错误，说明是网关服务挂了或者路径不对，问题不在 Codex；如果 curl 正常但 Codex 报错，说明 Codex 传给这个服务的请求格式或鉴权头有问题，继续往下查。
第四步，检查密钥是否有效。看model_providers里配置的env_key对应的环境变量是否设置、是否过期。很多“local proxy failed”其实是上游 API 鉴权失败，网关把 401 或 403 原样返回给 Codex，Codex 只能用一句笼统的“local proxy failed”告诉你。
第五步，检查 MCP 段落有没有被覆盖。config.toml里搜一下mcp_servers，如果整个段落消失了，那就是 cc-switch 这类工具重写配置时把 MCP 配置冲掉了。如果你有备份，直接 diff 一下两个版本，很快就能确认是谁改掉的。
第六步，修复并固化。把mcp_servers段落补回去，把model_providers修正到正确指向。然后建议你把自己常用的 MCP 配置段单独备份成一个文件，之后每次切换供应商配置后，核对一下配置，别依赖工具自动合并。
5.3 容易被误判成 MCP 问题的其他症状
在排障过程中，有些症状看起来像 MCP 坏了，实际是其他部分的问题，这里列几个容易误判的。
Codex 能启动，但模型说“没有可用工具”，同时你明明配置了 MCP Server。这种情况一般不是 MCP 的问题，而是当前模型不支持工具调用，或者wire_api配置不对。不同模型对 tools 的支持程度不一样，换成不支持工具的模型，Codex 自然就没有工具可用。
MCP Server 进程启动了，但一调用就返回空结果或报错。这个问题要去看 Server 自己的日志，而不是盯着 Codex 的界面。你在配置的时候给 Server 起一个独立终端窗口手动跑一遍，就能看到它到底在报什么错。很多 Python 脚本在本地直接跑没问题，被 Codex 拉起来就报错，多半是环境变量没传进去，或者工作目录不对。
响应非常慢，每次调用工具都像卡死。一个常见原因是 npx 每次都在重新解析和下载包，可以提前用npm install -g @modelcontextprotocol/server-xxx全局装好，然后把command改成直接调用全局包路径，省去 npx 的动态下载步骤，速度和稳定性都会改善。
Windows 上的坑更多一些，很多人报“codex windows 安装未完成”，然后 MCP 也配不起来。安装问题先确认 PATH 是否正确、是否装了新版，再回头看 MCP。Windows 下启动 MCP Server 时，command里的解释器路径、cmd /c的用法都要格外注意，路径里的反斜杠也要按 TOML 字符串规则转义。
6. 用了 MCP 之后，这几件事越早知道越好
MCP 配置本身不难，但真正用好需要建立几个习惯。
第一，代码仓库要管理好你的配置。我现在的做法是把~/.codex/config.toml的常用模板放进 dotfiles 仓库，新机器克隆下来就能用。要注意的是，里面不要有明文密钥，用一个# 请设置环境变量 XXX的注释代替，环境变量单独在 shell 配置里维护。这样既方便同步，又不会泄密。
第二，MCP Server 不是越多越好。每挂一个 Server，Codex 在每次会话里都会多出一批工具描述，这些描述会占用模型的上下文窗口。工具太多不仅增加 token 成本，还会稀释模型对关键工具的注意力。我的体会是保持在三到五个以内，真正高频使用、真正解决问题才值得挂上去。临时需要的功能，用完就摘掉。
第三，指令要明确。别指望模型每件事都自己想起来去调用工具。你给 Codex 说“帮我看下这个 token 的余额”，它可能不知道要调用哪个 MCP 工具。但你说“用 mytools 里的 get_token_balance 查一下 0x1234 的余额”，它就知道该干什么了。工具调用是模型的一种选择，而你的指令是影响这个选择的最大因素。
第四，Server 返回的内容质量决定工具效果。MCP Server 给你返回一段杂乱无章的巨大 JSON，模型很难从中提取出有用信息；如果你在 Server 端做好格式化、精简、只返回必要字段，模型的分析质量会明显上升。工具返回内容本身就是给模型的“上下文”，垃圾进垃圾出这个道理，在 MCP 场景下同样成立。
第五，保持 Codex 本体更新。MCP 支持迭代非常快，旧版本可能缺少新字段、不支持新的传输协议。你遇到一些莫名其妙的配置不识别、远程连接失败，先升级到最新版再排查，往往能省掉大量时间。
最后分享一个我自己的排查习惯：遇到任何 MCP 相关疑难杂症，先在终端手动把那个 server 命令原样执行一遍。这个动作能帮你区分至少一半的问题——是 Codex 不会连，还是 Server 起不来，又或者是 upstream 接口本身有问题。把这个做熟了，MCP 对你来说就不再是玄学，而是有清晰边界的工程问题。
