本文要点
- OpenAI 已弃用 `codex mcp-server` 命令；一般客户端集成应转向 Codex App Server，Claude Code 应使用官方 Codex 插件。
- 弃用不等于所有 MCP 服务都停用，也不等于 `codex mcp` 配置命令消失；受影响的是把 Codex 本身作为 MCP server 启动的旧入口。
- 迁移前先盘点启动命令、传输方式、线程恢复、认证、审批和事件处理，不能只把命令字符串替换成 `app-server`。
- 先在隔离项目验证启动、认证、单轮与续轮、工具审批、中断和退出，再切换真实工作流。
- 新旧路径输出或权限语义不一致、无法恢复线程、审批请求无人处理时应停手并回滚到已验证版本，而不是扩大文件或账号权限。
发生了什么：旧命令还能被脚本找到，但已经进入 Sunset
OpenAI 的产品发布说明在 2026 年 8 月 24 日把 `codex mcp-server` 标记为 deprecated，并明确给出两个去向：使用 Codex App Server；如果从 Claude Code 调用 Codex，则使用 Codex plugin for Claude Code。官方没有在该条目中给出地区、套餐或最终移除日期，因此不能把某次启动失败直接解释成地区封锁，也不能自行承诺旧命令还能维持多久。
具体场景是：团队的编辑器配置或自动化脚本仍写着 `codex mcp-server`，升级后出现弃用提示、握手失败或续接线程行为变化。代价是编码任务中断、审批被遗漏和脚本维护成本增加。错误直觉是只升级或降级 CLI；正确第一步是查启动日志和配置，确认调用方究竟依赖旧 MCP 工具外观，还是已经能够使用 App Server 的线程与事件协议。
先划清边界：MCP server、MCP 配置与 App Server 不是一件事
`codex mcp-server` 是让外部客户端通过 MCP 调用 Codex 的旧命令入口；`codex mcp` 用于管理 Codex 要连接的其他 MCP servers；App Server 则面向构建在 Codex 上的客户端，提供独立的线程、轮次、事件、审批和认证协议。发布说明弃用前者，不代表你在 Codex 中配置的所有第三方 MCP tools 都被删除。
迁移前把链路画成三段：谁启动 Codex、Codex 用哪种协议与宿主通信、Codex 又连接哪些外部工具。只在第一段看到旧命令时才属于本次迁移；若症状发生在某个下游 MCP 工具，先核对该工具的进程、传输和权限，不要把所有 MCP 故障归因于 Sunset。
按调用方选择迁移路径
Claude Code 用户优先走官方 Codex 插件路径，不要自行把 App Server 包装成未经验证的 MCP bridge。其他自建 IDE、桌面客户端或内部自动化若需要直接承载 Codex，应阅读 App Server 协议，确认客户端能处理 `thread/start`、`turn/start`、事件流、审批请求和线程恢复，而不是仅等待一次工具返回。
如果现有集成只需要一次性问答，不代表可以忽略生命周期。至少明确工作目录、模型和认证从哪里取得，用户取消如何传递，工具调用需要谁批准，宿主退出时子进程如何关闭。缺少这些责任时先保持在测试环境，不要直接替换团队所有人的启动配置。
迁移前盘点与最小验证步骤
第一，搜索编辑器配置、shell 脚本、服务定义和 CI 辅助脚本中的 `codex mcp-server`。第二，记录当前 Codex 版本、认证方式、工作目录、参数和环境变量，但不要把密钥写进迁移文档。第三，确定调用方是 Claude Code 还是自建客户端。第四，在隔离项目安装对应插件或启动 App Server 客户端。第五，用无敏感数据的任务验证一次新线程和一次续接。
随后验证工具审批、拒绝审批、中断、超时、错误事件、客户端重连和宿主退出。对会改文件或执行命令的流程，比较迁移前后的工作目录、权限提示和 diff；对长期运行集成，观察进程是否能正常回收。只有这些检查都符合预期，才把一个低风险项目切到新路径。
失败、回滚与停手条件
预先保留旧配置副本、已验证的 Codex 版本和切换负责人。新路径若无法认证、线程不能恢复、事件顺序无法解释、审批请求没有界面承接，或退出后进程持续残留，应停止扩大迁移，保存版本、启动参数、日志时间和最小复现，再回到已验证环境。
回滚的目标是恢复可控工作流，不是长期忽略 Sunset。不要为了让测试通过而关闭审批、授予更宽目录访问、把密钥硬编码到参数，或在生产机器上同时启动多套未知生命周期的 server。若问题只在公司网络出现，再检查 DNS、TLS、代理认证和 WebSocket/stdio 边界；网络正常也不能修复协议或权限不兼容。
常见误区与正确排错顺序
常见误区包括：把 deprecated 当成立即删除；把 App Server 当成标准 MCP server；认为 `codex mcp` 也被弃用；只改命令名而不处理线程和审批；把 Claude Code 插件资格问题归因于 IP；看到一次成功响应就跳过续接和退出测试。
正确顺序是确认官方状态和日期、定位实际启动命令、识别调用方、选择插件或 App Server、核对协议与权限、跑生命周期测试，最后才排查网络。若连接阶段有明确 DNS、TLS 或代理认证错误，可参考<a href="/resources/proxy-connection-troubleshooting-checklist">代理连接失败排查清单</a>；若模型、Base URL 或凭据混用，可参考<a href="/resources/ai-api-key-base-url-model-guide">AI API 配置指南</a>。
上线前检查表与复查时间
逐项确认：旧命令出现位置已盘点；调用方分类正确；官方迁移路径已选；认证和秘密值未扩散；线程开始、续接、中断都通过；审批允许和拒绝都可见；文件与命令权限未扩大；退出后进程正常回收；旧配置和回滚负责人明确。
OpenAI 尚未在发布说明中公布最终移除日期。迁移后 24 小时复查失败率、残留进程和审批积压，一周后重新核对 Release Notes、App Server 文档与 Claude Code 插件说明。若官方补充移除日期或协议兼容说明，应更新原页，不为“怎么装、怎么连、怎么排错”拆多个近义 URL。
资料来源
常见问题
codex mcp-server 什么时候被弃用？
OpenAI Release Notes 将该命令标记为 2026 年 8 月 24 日 Sunset。官方当前没有在该条目中公布最终移除日期。
以后所有 MCP 都不能在 Codex 中使用了吗？
不是。本次弃用针对把 Codex 本身作为 MCP server 启动的 `codex mcp-server` 命令，不等于 Codex 连接的第三方 MCP tools 或 `codex mcp` 配置能力全部取消。
Claude Code 应该改成什么？
OpenAI 的官方指引是使用 Codex plugin for Claude Code。先按插件说明验证账号、权限和工作目录，不要自行假设 App Server 可以直接替换为一个普通 MCP 配置。
自建客户端可以只把命令换成 codex app-server 吗？
不应只替换字符串。客户端还需要按 App Server 协议处理线程、轮次、事件、认证、审批、中断和退出生命周期。
看到弃用提示后可以继续临时使用旧命令吗？
deprecated 不等于官方已经公布立即删除，但也没有稳定期限。应尽快在隔离环境完成迁移验证，并保留可控回滚，而不是等待生产中断。
什么情况下应暂停迁移？
认证失败、线程无法恢复、事件或审批无人处理、权限范围扩大、进程不能回收或无法解释新旧行为差异时，应暂停扩大范围并保存最小复现。