TRAE-AI编程
Codex 装 MCP 插件的核心只有三步：写好配置文件、把插件路径指给 Codex、再跑一次带工具的调用验证。多数人在第二步卡住——以为装了包就完事，其实 Codex 读的是它自己的配置目录，而不是项目里的 node_modules。本文从一份最小可用的配置讲起，覆盖配置落点、插件类型、首次调用排错，并用一次真实的「读文件」工具调用证明链路打通。适用范围：Codex CLI 0.30 之后版本，macOS 与 Windows 的路径差异会单独说明；具体字段以你所用版本的官方说明为准，文中对未公开实现的部分一律标注为推断。
先把结论说在前面：MCP 插件不是 pip 装一下就能用的库，它是按 Codex 约定的协议对外提供能力的独立进程。配置对了，Codex 会在启动时拉起这些进程并通过标准输入输出通信；配置错了，调用时只会得到一句「工具不存在」。所以排查的抓手始终是那份配置文件，而不是代码本身。
一、先把 MCP 在 Codex 里的位置看清（适用与边界）
第一步是确认你安装的是哪一个 Codex。不同分支对 MCP 的支持程度差异很大，有些版本把插件能力放在实验开关后面，有些则直接读取固定目录。先做一遍Codex 安装确认版本号，再去翻对应文档，能省掉大量无效排查。
配置落点的边界要记牢：Codex 读取的是用户级配置目录下的 settings.json 或专属的 mcp.json，而不是当前项目根目录。很多团队把配置误放进仓库，结果本机能跑、同事跑不起来，根因就是落点不一致。正确的边界是——全局能力放用户目录，项目私有能力才考虑跟随仓库并用相对路径。
权限边界也不能忽略。MCP 插件能读写文件、执行命令，开启后等于把一部分系统权限交给了外部进程。所以只装来源可信的Codex 插件，并在配置里显式声明它需要的能力范围，避免一次性放开全部权限。
二、最小配置：一段能直接用的 JSON（安装、配置、运行）
下面这段 mcp.json 只声明一个最朴素的 stdio 插件，作用是让 Codex 多出一个「读取本地文件」的工具。先保证它能加载，再谈扩展。
{
"mcpServers": {
"local-fs": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/workspace"],
"env": {}
}
}
}
把文件放到 Codex 的配置目录（macOS 通常是 ~/.codex/，Windows 是 %USERPROFILE%\.codex\），保存后重新启动会话。注意 Windows 上路径分隔符与命令名称不同，建议先单独在 PowerShell 里跑通 npx -y @modelcontextprotocol/server-filesystem <目录>，确认能启动再写进配置。
配置里最容易踩的坑是 command 写成相对路径。Codex 启动插件时的当前目录未必是你以为的目录，所以命令和参数里的可执行文件最好用绝对路径，或者确保它在系统 PATH 内。若你用其他编辑器也接 MCP，可以参考CodeBuddy IDE 配置 MCP的字段对照，概念是相通的。
三、两种插件形态：stdio 与 HTTP（对比与取舍）
stdio 插件随 Codex 一起拉起，通过标准输入输出通信，适合本机工具；HTTP 插件则是 Codex 去连一个已经跑起来的远程服务，适合团队共享或云端能力。两种形态在配置上只是 url 与 command 的区别，但运行边界完全不同。
stdio 的优点是隔离简单、随用随起；缺点是每个会话都要拉起进程，冷启动略慢。HTTP 的优点是常驻、可被多人复用；缺点是你要自己保证那条边车服务的鉴权与可用，链路更长也更易在中间环节失败。同一个Trae Ide Use Mcp Servers In Agents的接入思路，迁移到 Codex 时主要就是把「本地进程」换成「远程地址」。
选择建议很朴素：个人本机练习用 stdio，团队统一能力用 HTTP。不要为了「看起来高级」把本机工具也塞进 HTTP，那只会引入额外的网络与鉴权负担。
四、跑通第一次调用：用读文件工具验证链路（验证与输出）
配置就绪后，不要急着写复杂任务，先用一句话验证：让 Codex「读取工作区里的 README.md 并总结」。如果链路打通，你会看到它调用了 local-fs 提供的读文件工具并给出结果；如果只回一句「我没有可用的文件读取工具」，说明插件没加载成功。
预期结果（未在本机执行）：Codex 返回 README 的要点摘要，且日志里能看到 local-fs 进程被拉起。若没有出现工具调用，先检查配置目录是否放对、JSON 是否合法、命令是否能在终端独立运行。验证通过之后，再逐步加入更多插件。每一次新增都重跑一次最小调用，确保新插件没有把已有链路弄坏。这种「加一个、验一个」的节奏，比一次塞十个插件再整体排查要省心得多。
五、常见失败与修复（失败、边界、排错）
坑一，JSON 格式错误。多一个逗号、少了引号，整个配置就被丢弃，Codex 启动时静默忽略，表现就是「工具不存在」。修复方式是先用 python -m json.tool mcp.json 验证语法，再放进配置目录。
坑二，命令找不到。配置里写 npx 但系统 PATH 在 Codex 的启动环境里没继承，就会报 command not found。修复方式是改成绝对路径，或在 env 里显式补上 PATH 变量。
坑三，权限被拒。插件声明了读文件，但目标目录不在允许的列表内，调用时被拦下。修复方式是把目录写进插件的允许范围，而不是简单地把所有目录都放开。Windows 用户若遇到路径相关报错，可翻Windows 速查手册核对分隔符与环境变量写法。
坑四，版本不匹配。旧版 Codex 的字段名与新版不同，照着新文档配旧版本必然失败。修复方式是严格按当前版本的字段来，不要跨版本套用示例。
总结
Codex 装 MCP 插件的关键不在「装」，而在「配」：把插件声明进正确的配置目录、用绝对路径避免环境差异、stdio 与 HTTP 按是否本机来取舍，最后用一次最小调用证明链路打通。遇到问题时按 JSON 语法、命令可达性、权限范围、版本字段这四步依次排查，基本能覆盖绝大多数失败。把每次新增都当成一次独立验证，链路就会越来越稳。
常见问题
Q：Codex 的 MCP 配置到底放在哪个目录？
用户级配置通常位于 ~/.codex/（macOS / Linux）或 %USERPROFILE%\.codex\（Windows）下的 mcp.json 或 settings.json，具体文件名以你所用版本的官方说明为准；项目私有能力才考虑放进仓库。
Q：stdio 插件和 HTTP 插件该选哪种？
个人本机练习、随用随起的能力优先选 stdio；团队要共享、需要常驻复用的能力才选 HTTP，避免为本机工具引入额外的网络与鉴权负担。
Q：配置对了但调用时提示工具不存在怎么办？
先确认 Codex 版本是否支持 MCP，再用 python -m json.tool 校验配置语法，然后单独在终端跑通命令本身，最后检查命令是否用了绝对路径、目录是否在插件允许范围内。
延伸学习
- TRAE Django 后台课程 — 想在完整项目里练手 AI 辅助开发，可以跟一遍这套 TRAE 体系课程。
- Codex 插件是什么 — 用一篇笔记讲清 Codex 插件、MCP、应用与 Hook 的组合设计思路。
- 中文与Unicode互转 — 处理配置里的编码问题时，随时用来核对字符。
