Codex mcp-server 被弃用：不是 MCP 退场，App Server、SDK 与 Claude Code 插件怎么选？

刘先生864

18人浏览 · 2026-08-26 18:33:42

刘先生864 · 2026-08-26 18:33:42 发布

关键词： Codex、mcp-server、App Server、Claude Code、MCP、Codex SDK、AI Coding Agent

最近更新 Codex CLI 或查看官方文档的开发者，可能会注意到这样一条变化：codex mcp-server 这个命令已经被标记为 deprecated。

但这里最容易产生一个误解：OpenAI 弃用的是“把 Codex 整体包装成 MCP Server”的旧集成方式，不是放弃 MCP 协议。

Codex 仍然可以连接外部 MCP Server。发生变化的是其他应用调用 Codex 的方式。

按照 OpenAI 当前给出的迁移方向：

在自己的产品中深度集成 Codex：使用 App Server
在 CI、脚本或后台任务中调用 Codex：使用 Codex SDK
在 Claude Code 中调用 Codex：使用官方 Codex 插件
让 Codex 调用数据库、浏览器等外部工具：继续使用 MCP

下面具体拆解这次变化。

一、deprecated 是否代表马上不能用？

不是。

deprecated 表示官方不再建议新项目采用这种方案，并准备将维护重心转向新架构。

OpenAI 当前仍然保留了旧命令的说明，主要用于兼容已有集成：

codex mcp-server

截至本文撰写时，官方文档没有给出明确的强制删除日期。

因此，已有系统不一定会立即报错，但新项目不应该继续围绕这个命令搭建架构。旧项目则需要提前梳理依赖，避免后续升级 Codex CLI 时被动迁移。

二、为什么不能只把命令改成 app-server？

表面看，旧命令是 codex mcp-server，新命令是 codex app-server，但这并不是一次简单的命令改名。

原来的 MCP Server 模式，会把 Codex 暴露成几个可以调用的工具。客户端通常通过 tools/list 获取工具，再通过 tools/call 启动或者继续一次 Codex 会话。

典型能力包括：

启动 Codex 任务
传入工作目录
指定模型
设置沙箱权限
继续已有会话

App Server 面向的却是完整的 Coding Agent 生命周期。它需要表达的内容包括：

Thread：可持续恢复的会话
Turn：用户发起的一轮任务
Item：消息、命令、文件修改和工具调用
Approval：命令或文件操作审批
Event：流式进度和状态变化
History：会话历史与恢复

两者的定位可以简单理解为：

Old architecture:

Claude Code / Agents SDK / MCP Client
                  |
                  v
         codex mcp-server
                  |
                  v
               Codex


New architecture:

IDE / Desktop client / Custom client
                  |
                  v
          codex app-server
                  |
                  v
       Thread / Turn / Approval / Event
                  |
                  v
               Codex

所以，如果你的程序原来依赖 tools/list、tools/call 和 codex-reply，不能只替换启动命令，还需要同步修改通信协议和状态管理。

三、四种场景分别怎么迁移？

场景一：在 Claude Code 里调用 Codex

过去常见的做法，是在 Claude Code 的 MCP 配置中加入：

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

这种配置利用 Claude Code 的 MCP Client，把 Codex 当成一个外部工具调用。

OpenAI 现在推荐改用 Codex plugin for Claude Code。官方插件底层使用 App Server，不需要开发者继续手动维护旧的 MCP 包装层。

迁移时建议检查：

找到 Claude Code 用户级和项目级 MCP 配置。
删除或者禁用旧的 codex mcp-server 项。
按照官方说明安装 Codex 插件。
重启 Claude Code。
检查是否出现重复的 Codex 工具。
用一个只读代码审查任务验证插件是否正常工作。

不要同时保留旧 MCP 配置和新插件，否则可能出现重复工具、会话混乱，甚至同一个任务被调用两次。

场景二：在自己的应用中嵌入 Codex

如果你正在开发 IDE、代码审查平台、桌面客户端或者内部研发工具，推荐使用 App Server。

启动方式为：

codex app-server

App Server 默认通过标准输入输出通信，适合由本地客户端启动和管理。

它更适合需要以下能力的产品：

显示实时执行过程
展示命令和文件修改
让用户确认高风险操作
创建、恢复或者分叉会话
获取结构化的任务状态
实现类似 IDE Agent 的交互界面

需要注意，App Server 不是普通的 HTTP Chat API。客户端需要理解它的 JSON-RPC 消息、通知事件和会话生命周期。

如果只是发送一句指令并等待最终结果，直接接入 App Server 反而可能增加不必要的复杂度。

场景三：在 CI 或脚本中运行 Codex

例如：

自动检查 Pull Request
批量修复代码格式问题
生成测试
分析构建失败日志
执行定时仓库巡检

这类任务通常不需要完整的图形界面和长期会话，官方建议使用 Codex SDK。

判断标准很简单：

需要完整交互界面、审批和会话恢复 → App Server

只需要启动任务、等待结果并读取输出 → Codex SDK

CI 中还应明确限制：

可访问的工作目录
网络权限
命令执行权限
最长运行时间
最大输出体积
API 消耗预算

不要因为迁移而把原来的沙箱和审批机制直接关闭。

场景四：Codex 调用外部 MCP 工具

这一类场景不受本次弃用直接影响。

例如 Codex 连接：

数据库 MCP Server
GitHub MCP Server
浏览器自动化工具
企业内部知识库
日志查询服务
工单和项目管理系统

这些工具仍然可以通过 MCP 提供给 Codex。

因此，“codex mcp-server 被弃用”和“Codex 不再支持 MCP”是两个完全不同的结论。前者是确定的官方变化，后者是不准确的扩大解读。

四、迁移前先做一次依赖排查

可以在项目中搜索以下关键词：

rg "codex mcp-server|mcp-server|codex-reply|tools/list|tools/call"

如果系统没有安装 rg，也可以使用：

grep -R "codex mcp-server" .

重点检查这些位置：

Claude Code 的 MCP 配置
桌面客户端配置
IDE 插件设置
Dockerfile
Shell 启动脚本
CI 工作流
Node.js 子进程代码
Python MCP Client
内部部署文档

然后记录原系统是否依赖以下信息：

工作目录 cwd
模型 model
沙箱 sandbox
审批策略 approval-policy
配置覆盖 config
会话 ID threadId
流式输出
错误恢复

这些能力不会凭空消失，但在 App Server 中需要通过新的生命周期和协议字段重新实现。

五、模型 API 接入和 App Server 迁移是两层问题

还有一个容易混淆的地方：App Server 解决的是“应用如何控制 Codex Agent”，而 API 地址、模型路由和 Key 管理属于模型调用层。

如果你的 Python 服务还需要调用兼容 OpenAI 接口的模型，可以继续通过 SDK 配置独立客户端：

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://genvis.xyz/v1",
)

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Review this code for concurrency safety issues and suggest fixes.",
)

print(response.output_text)

这样做的好处是把两层职责分开：

App Server 负责会话、工具、审批、文件修改和执行状态。

模型 API 负责模型调用、Key、路由、限额和请求协议。

如果后续需要切换模型供应方或者增加备用线路，只调整模型调用层，不必重写整个 Agent 客户端。

实际部署时，API Key 应通过环境变量或密钥管理服务注入，不要直接写进代码仓库。