OpenAI已将codex mcp-server标记为弃用。若在Claude Code中调用Codex，官方建议改用Codex插件；若要把Codex深度集成进自建产品，则应迁往Codex App Server；CI和批处理任务还应优先评估Codex SDK。本文讲清三者边界，并给出旧配置识别、迁移、审批处理和验收清单

如果你曾把Codex CLI注册成一个MCP服务器，让Claude Code、OpenAI Agents SDK或其他MCP客户端通过codex和codex-reply两个工具调用它，现在需要检查这套集成了。

OpenAI在2026年8月24日正式将下面这个命令标记为弃用：

codex mcp-server

官方给出的方向很明确：

• 自建产品需要深度集成Codex：使用Codex App Server；
• Claude Code需要调用Codex：使用Codex官方的Claude Code插件；
• 自动化脚本或CI任务：优先评估Codex SDK，而不是自行维护一套App Server客户端。

最容易误解的一点是：codex app-server并不是把旧命令换了一个名字。旧方案向外暴露的是MCP工具，新方案提供的是面向完整客户端集成的双向JSON-RPC协议。迁移时如果只把配置中的mcp-server改成app-server，多数情况下并不能工作。

一、弃用不等于今天立即删除，但应该停止新增依赖

“Deprecated”表示这条集成路径已经不再是推荐方向，并不等于旧命令在公告当天必然消失。

OpenAI目前仍保留旧MCP Server文档，目的主要是帮助已有集成理解和维护现状。该文档也明确写明：页面记录的是旧命令，新的集成应转向App Server或Claude Code插件。

因此，合理做法不是今天立刻删除所有旧配置，而是：

1. 不再给新项目接入codex mcp-server；
2. 找出哪些客户端仍依赖它；
3. 按真实使用场景选择迁移路径；
4. 新旧方案短期并行验证；
5. 确认线程、审批、文件修改和异常处理正常后，再下线旧入口。

二、先找出项目里有没有旧依赖

可以在仓库、用户配置和自动化脚本中搜索这些特征：

codex mcp-server
"args": ["mcp-server"]
MCPServerStdio
codex-reply
conversationId
threadId

典型旧配置可能类似：

{
  "command": "codex",
  "args": ["mcp-server"]
}

也可能藏在Python或Node.js代码里，由MCP客户端启动Codex子进程。

旧服务器主要提供两个工具：

• codex：创建一次新的Codex会话；
• codex-reply：根据threadId继续已有会话。

如果代码依赖这两个工具名、MCP的tools/list或tools/call返回结构，就不能只替换启动命令。客户端协议、状态管理和审批处理都要重新核对。

三、两条主要迁移路径怎么选？

路径一：在Claude Code里调用Codex

如果你的目标只是让Claude Code把代码审查、排错或某项任务交给Codex，官方建议直接使用Codex的Claude Code插件。

这条路径更合理，因为插件已经负责Claude Code与Codex之间的适配，并在内部使用App Server。你不需要继续把Codex伪装成一个通用MCP服务器，也不必自己维护codex、codex-reply工具和会话ID映射。

迁移重点不是“安装完插件就结束”，而是核对下面四件事：

1. 旧Claude Code MCP配置是否仍会启动codex mcp-server；
2. 新插件与旧服务器是否同时暴露了名称相近的功能；
3. 代码审查和任务委派是否使用正确的仓库工作目录；
4. Codex触发命令、文件修改或下游MCP工具时，审批能否正常传递。

建议先安装并验证官方插件，再删除旧配置。不要先删除旧入口，然后才发现新插件无法读取项目、无法获得审批或无法继续原会话。

路径二：把Codex嵌入自己的产品

如果你正在开发IDE、桌面客户端、内部研发门户或需要持续展示Agent过程的工具，迁移目标应该是Codex App Server。

App Server提供的不只是一次工具调用，而是一套完整的客户端协议，包括：

• 身份验证与账号状态；
• 对话线程的创建、恢复和分叉；
• Turn的启动、引导与中断；
• 命令、文件修改和工具调用的增量事件；
• 命令执行和文件修改审批；
• 模型、工作目录、沙箱策略等会话配置。

它默认通过stdio传输换行分隔的JSON消息，协议形式是双向JSON-RPC 2.0。连接建立后，客户端必须先发送initialize，再发送initialized通知，然后才能创建Thread和启动Turn。

最小生命周期可以概括为：

启动 codex app-server
        ↓
initialize → initialized
        ↓
thread/start 或 thread/resume
        ↓
turn/start
        ↓
持续读取 item、tool、file change 等事件
        ↓
处理审批请求
        ↓
turn/completed

这和旧MCP服务器的“列出工具—调用工具—取得结果”模型并不相同。

四、为什么不能把旧MCP配置原样改名？

假设原配置是：

{
  "command": "codex",
  "args": ["mcp-server"]
}

直接改成：

{
  "command": "codex",
  "args": ["app-server"]
}

问题在于，MCP客户端期待收到MCP初始化、工具列表和工具调用结果；App Server等待的却是Codex自己的初始化、Thread、Turn和事件协议。

两边虽然都使用JSON-RPC思想，但消息方法、生命周期和能力模型并不一样。协议不匹配时，常见结果包括：

• 客户端一直等待工具列表；
• 初始化阶段直接失败；
• 可以启动进程，却无法创建会话；
• 文件或命令审批无人响应；
• 任务执行到一半挂起；
• 原来的threadId无法按预期继续。

迁移的本质是更换集成协议，不是更换一个参数。

五、如果只是跑自动化或CI，要不要自己接App Server？

不一定。

OpenAI在App Server官方文档中明确区分了使用场景：App Server用于需要深度客户端集成的产品；自动化任务或CI更适合Codex SDK。

可以按下面的判断方式选择：

使用场景	优先方案	原因
Claude Code里调用Codex	Codex官方Claude Code插件	已处理Claude Code与App Server之间的适配
自建IDE、桌面端或内部研发工具	Codex App Server	需要线程、审批、流式事件和完整客户端状态
CI、批处理、后台自动任务	Codex SDK	不必自行实现完整交互式客户端协议
仍在维护旧MCP工作流	短期保留并安排迁移	旧命令尚有兼容文档，但不应继续扩展依赖

不要因为App Server是新推荐方向，就让所有脚本都直接操作底层JSON-RPC。能用SDK完成的自动化，通常没有必要自行实现连接、状态、审批和事件循环。

六、App Server迁移时要实现哪些核心步骤？

1. 启动与初始化

默认stdio方式可以启动：

codex app-server

客户端连接后，先发送initialize请求并携带客户端名称、标题和版本，再发送initialized通知。初始化之前发送其他请求，服务器会拒绝。

2. 建立Thread

新会话使用thread/start；继续既有会话使用thread/resume；需要从历史分支出新方向时，可使用thread/fork。

不要把旧MCP返回的会话字段直接假定为App Server可无缝复用。迁移阶段应建立明确的旧ID与新Thread ID映射，或者接受新系统从新Thread开始。

3. 启动Turn并消费事件

用户请求通过turn/start进入指定Thread。执行过程中，App Server会持续发送Agent消息增量、命令执行、文件修改、工具调用和状态变化等通知。

客户端不能只等最后一条文本结果，还需要持续读取事件流，否则可能错过进度、审批和错误信息。

4. 正确处理审批

根据Codex设置，命令执行和文件修改可能需要用户批准。App Server会向客户端发起请求，客户端需要返回接受、会话内接受、拒绝或取消等决定。

这是迁移中最值得测试的一环。简单地把审批策略设成“永不询问”并不能替代完整的安全设计，更不能为了让流程跑通就默认放开危险权限。

5. 固定协议版本

App Server可以根据当前安装的Codex版本生成TypeScript类型或JSON Schema：

codex app-server generate-ts --out ./schemas
codex app-server generate-json-schema --out ./schemas

生成结果与运行该命令的Codex版本对应。升级Codex CLI后，应重新生成并比较Schema，而不是假设协议字段永久不变。

七、WebSocket可以直接用于生产远程服务吗？

目前不建议这样做。

官方文档将App Server的WebSocket传输标记为实验性且不受支持。若只是本机客户端，默认stdio最直接；如果是本地或SSH端口转发场景，可以谨慎测试WebSocket；非本机连接则必须考虑TLS、身份验证、令牌存储和网络暴露风险。

尤其不要把未认证的监听地址直接暴露到公网。App Server能够执行命令、修改文件并调用工具，暴露风险远高于普通只读接口。

八、推荐的渐进迁移顺序

第一步：盘点调用方

列出所有会启动codex mcp-server的地方：Claude Code配置、Agents SDK脚本、IDE插件、内部工具、CI脚本和开发者个人配置。

第二步：按用途分流

• Claude Code调用：迁到官方Codex插件；
• 自建交互式客户端：迁到App Server；
• CI与无人值守任务：评估Codex SDK；
• 暂时无法迁移的旧系统：锁定版本和变更范围，不再新增能力。

第三步：先并行验证

保留旧入口，使用同一个小型测试仓库对比新旧结果。测试任务应至少包含读取文件、修改文件、运行一条安全命令、触发一次审批和继续一次会话。

第四步：检查安全边界

确认工作目录、沙箱模式、网络访问、命令审批和文件修改审批与原系统一致。不要因为协议变化意外扩大权限。

第五步：切换并保留回退窗口

先让少量用户或单一工作流切到新路径，观察日志和失败原因。稳定后再移除旧MCP配置，并保留可恢复的配置备份。

九、迁移验收清单

完成迁移后，至少核对下面十项：

• 系统中不再新增codex mcp-server配置；
• Claude Code只保留一条Codex调用路径；
• App Server连接完成initialize与initialized；
• 新建Thread和继续Thread都正常；
• Turn执行过程中的增量事件没有丢失；
• 命令执行审批能展示并返回决定；
• 文件修改审批和最终Diff能够复核；
• cwd、沙箱与网络权限符合预期；
• CLI升级后重新生成并比较协议Schema；
• 新路径失败时有明确日志和可用回退方案。

十、常见问题

codex mcp-server现在还能运行吗？

弃用不等于公告当天立即删除，现有版本中可能仍可运行，官方也暂时保留了旧文档。但它已不再是新集成的推荐方案，应开始迁移并停止新增依赖。

App Server还是MCP服务器吗？

不是同一个协议入口。App Server使用自己的双向JSON-RPC方法和Thread/Turn生命周期，不能当成普通MCP服务器直接注册。

Claude Code应该自己连接App Server吗？

普通用户不需要自己实现连接。官方建议使用Codex的Claude Code插件，该插件内部使用App Server。

旧的codex和codex-reply工具还能原样保留吗？

App Server并不以这两个MCP工具作为核心接口。迁移后的客户端应使用Thread和Turn相关方法，或由官方插件、SDK负责适配。

自动化脚本也必须迁到App Server吗？

不一定。对于CI和后台任务，官方更建议评估Codex SDK；App Server主要适合需要身份验证、对话历史、审批和流式Agent事件的深度产品集成。

结语

codex mcp-server弃用真正释放的信号，不是“MCP不能用了”，也不是“Codex不再支持外部集成”，而是Codex开始为不同场景提供更明确的入口：

• Claude Code通过官方插件调用；
• 自建交互式产品使用App Server；
• 自动化和CI优先使用SDK。

迁移前先确认谁在调用Codex、需要哪些状态和审批，再选择入口。不要把旧MCP配置中的命令名称机械替换，否则最可能出现的不是立即报错，而是进程启动了、任务却卡在初始化或审批阶段。

官方资料

• OpenAI：ChatGPT与Codex更新日志
• OpenAI：Codex App Server
• OpenAI：Running Codex as an MCP server（已弃用方案说明）