教程
Codex mcp-server 退场：App Server 迁移指南
OpenAI 在 2026 年 8 月 24 日正式把 `codex mcp-server` 标记为 Deprecated，并给出明确迁移方向：需要把 Codex 深度嵌入自有产品时，改用 **Codex App Server**；如果是 CI、批处理或非交互自动化，优先使用 **Codex SDK**；如果希望从 Claude Code 调用 Codex，则使用官方 Codex plugin for Claude Code。App Server 不是 MCP Server 的简单改名，它提供的是面向富客户端的 Codex 控制协议：认证、Thread/Turn、审批、流式 Agent 事件、MCP Tool、配置与状态都通过双向 JSON-RPC 2.0 交互。本文给出从旧命令迁移到 App Server 的架构判断和安全清单。
# Codex mcp-server 退场：App Server 迁移指南
## 文章摘要
OpenAI 在 2026 年 8 月 24 日正式把 `codex mcp-server` 标记为 Deprecated，并给出明确迁移方向：需要把 Codex 深度嵌入自有产品时，改用 **Codex App Server**；如果是 CI、批处理或非交互自动化，优先使用 **Codex SDK**；如果希望从 Claude Code 调用 Codex，则使用官方 Codex plugin for Claude Code。App Server 不是 MCP Server 的简单改名，它提供的是面向富客户端的 Codex 控制协议：认证、Thread/Turn、审批、流式 Agent 事件、MCP Tool、配置与状态都通过双向 JSON-RPC 2.0 交互。本文给出从旧命令迁移到 App Server 的架构判断和安全清单。
---
8 月 24 日 OpenAI Release Notes 里有一个看起来很小的 Sunset：
```text
codex mcp-server
```
被正式标记为：
> Deprecated。
官方建议：
```text
Use the Codex app server instead.
```
这条更新值得开发者认真看。
因为它反映了 Codex 的扩展方式正在重新分层。
## 先解决一个最容易混淆的问题
### MCP Server 是给模型“提供工具”
典型关系：
```text
Agent Client
↓
MCP
↓
Tool Server
```
例如：
```text
search_docs
query_database
create_ticket
```
### Codex App Server 是“把 Codex 本身嵌进你的应用”
关系更像：
```text
Your Product
↓
Codex App Server Protocol
↓
Codex Runtime
↓
Models / Tools / Approvals / Threads
```
也就是说：
> MCP 是工具协议。
> App Server 是 Codex 客户端集成协议。
这两个方向不应该再混在一起。
## 为什么 `codex mcp-server` 会退场？
旧方案容易让人产生一种设计：
```text
Claude Code / Other Client
↓
把 Codex 当 MCP Server
↓
调用 Codex
```
但 Codex 本身现在已经包含：
- Conversation History；
- Thread；
- Turn；
- Approvals；
- File Change；
- Command Execution；
- Apps；
- MCP；
- Plugins；
- Sandbox；
- Authentication。
把这一整套能力压成一个 MCP Server，越来越不自然。
所以 OpenAI 把深度客户端集成收敛到：
> App Server。
## 三种场景应该怎么选？
这是迁移时最重要的问题。
### 场景一：我要做自己的 Codex UI / IDE / 桌面客户端
用：
```text
Codex App Server
```
官方明确指出，它适合 Rich Client Integration，包括：
- Authentication；
- Conversation History；
- Approvals；
- Streamed Agent Events。
VS Code Extension 本身也是这种思路的例子。
### 场景二：我要在 CI 里跑 Codex
例如：
```text
PR Review
Nightly Refactor
Automated Test Fix
Batch Migration
```
优先：
```text
Codex SDK
```
官方文档明确建议：
> Automating jobs or running Codex in CI → use Codex SDK.
不要为了批处理启动完整富客户端协议。
### 场景三：我在 Claude Code 里想调用 Codex
OpenAI Release Notes 给出的方向是：
```text
Codex plugin for Claude Code
```
不要继续围绕：
```text
codex mcp-server
```
搭新集成。
## App Server 的核心通信方式：双向 JSON-RPC
Codex App Server 使用双向 JSON-RPC 2.0 风格消息。
Request：
```json
{
"method": "thread/start",
"id": 10,
"params": {
"model": "gpt-5.6-terra"
}
}
```
Response：
```json
{
"id": 10,
"result": {
"thread": {
"id": "thr_123"
}
}
}
```
Notification：
```json
{
"method": "turn/started",
"params": {
"turn": {
"id": "turn_456"
}
}
}
```
关键是：
> 不只是 Request / Response。
App Server 会主动给 Client 发：
- Agent Event；
- Approval Request；
- Tool Request；
- Progress；
- State Change。
所以它更像一个：
> **双向 Agent Runtime Protocol。**
## 默认 stdio 其实很适合本地嵌入
最简单模式：
```bash
codex app-server
```
默认：
```text
stdio://
```
数据是：
```text
JSONL
```
你的应用可以直接：
```text
spawn codex process
↓
stdin 写 JSON
stdout 读事件
```
对：
- IDE Plugin；
- Desktop App；
- Local Tool；
非常合适。
## 一个 Node.js 最小结构
思路类似：
```javascript
const proc = spawn('codex', ['app-server'], {
stdio: ['pipe', 'pipe', 'inherit']
});
proc.stdin.write(JSON.stringify({
method: 'initialize',
id: 1,
params: {}
}) + '\n');
```
然后持续读取 stdout 的 JSONL Event。
App Server 初始化后：
```text
thread/start
↓
turn/start
↓
stream events
↓
approval requests
↓
turn complete
```
这比简单“发 Prompt，等一个字符串结果”丰富得多。
## Thread 和 Turn 为什么重要？
可以理解：
### Thread
一个长期工作上下文。
例如：
> “重构支付服务。”
### Turn
Thread 中的一次具体交互。
例如：
> “先分析数据库层。”
然后：
> “继续补测试。”
Rich Client 可以保留：
```text
Thread
├── Turn 1
├── Turn 2
└── Turn 3
```
这也是为什么 App Server 比普通 MCP Tool 更适合“完整 Codex 产品体验”。
## Approval 必须由 Client 正确处理
Codex 根据设置，执行命令或修改文件时可能需要审批。
App Server 会主动发起：
> Server-initiated JSON-RPC Request。
Client 需要返回：
```text
accept
acceptForSession
decline
cancel
```
命令场景还可能支持更细粒度的 Exec Policy Amendment。
这意味着自建 UI 时：
> **审批不是可选的边角功能。**
必须作为主流程实现。
## 不要因为自己做 UI 就偷偷自动 accept
最危险的实现是：
```javascript
if (request.type === 'approval') {
return 'accept';
}
```
这样等于：
> 把 Codex 原有安全边界直接绕掉。
正确做法：
```text
Low Risk
→ 可以按 Policy 自动通过
Medium Risk
→ 用户确认
High Risk
→ 强确认 / 禁止
```
规则应由应用层 Policy 控制，而不是 Agent 自己决定。
## App Server 也能管理 MCP
这是迁移后很容易误解的一点。
`codex mcp-server` 被弃用，不代表 Codex 不再支持 MCP。
相反，App Server 暴露了大量 MCP 相关能力，例如：
```text
mcpServerStatus/list
mcpServer/tool/call
mcpServer/resource/read
mcpServer/oauth/login
config/mcpServer/reload
```
架构变成：
```text
Your Client
↓
App Server
↓
Codex
↓
Configured MCP Servers
```
App Server 是控制面。
MCP Server 仍然是工具面。
## WebSocket 可以远程连，但现在要非常谨慎
App Server 支持：
```text
stdio
websocket
unix socket
```
其中 WebSocket 当前官方明确标注：
> Experimental and unsupported for production workloads.
本地可以：
```bash
codex app-server --listen ws://127.0.0.1:4500
```
远程则必须更谨慎。
官方建议：
- 远程使用 `wss://`；
- 配置 WebSocket Authentication；
- 通过 TLS；
- 不要把 Raw Token 直接写命令行。
## 为什么 `ws://0.0.0.0` 很危险？
因为非 Loopback Listener 在当前 rollout 中存在特殊安全注意事项。
如果开发者为了方便：
```bash
codex app-server --listen ws://0.0.0.0:4500
```
然后安全组又开放公网：
> 可能直接暴露 Agent 控制面。
这类接口具备：
- 读代码；
- 改文件；
- 执行命令；
- 调 MCP；
绝对不能当普通 Debug Port。
## 远程 App Server 推荐架构
```text
Client
↓
TLS / WSS
↓
Authenticated Reverse Proxy
↓
Codex App Server
↓
Sandbox / Repo / MCP
```
并增加：
```text
Network ACL
Rate Limit
Audit
Short-lived Credential
```
如果不是明确需要远程 Rich Client：
> 优先使用 Local stdio。
## App Server 有 Overload 机制
WebSocket 模式下使用 bounded queue。
当 ingress 满时，可能返回：
```text
-32001
Server overloaded; retry later.
```
Client 不应该：
> 无限立即重试。
推荐：
```text
Exponential Backoff
+
Jitter
```
这也是生产客户端必须自己处理的细节。
## Schema 最好跟 Codex 版本一起生成
App Server 可以生成：
```bash
codex app-server generate-ts --out ./schemas
```
或：
```bash
codex app-server generate-json-schema --out ./schemas
```
这非常重要。
因为每个 Codex 版本支持的方法和字段可能变化。
不要手写一份：
> “永远不会变的 TypeScript Interface”。
更合理：
```text
升级 Codex
↓
重新生成 Schema
↓
Type Check
↓
Integration Test
↓
Release
```
## 迁移前先判断：你真的需要 App Server 吗？
很多人看到新接口以后会立刻：
> 全部迁 App Server。
没有必要。
可以用这个判断：
### 只要执行自动任务？
用 SDK。
### 需要自己的 Rich UI？
用 App Server。
### 只是给 Codex 提供工具？
建 MCP Server。
### Claude Code 里调用 Codex？
用 Codex Plugin。
这种职责分离反而更清晰。
## 一个迁移检查清单
如果项目当前使用：
```text
codex mcp-server
```
建议检查：
### 1. 当前谁是 Client？
- Claude Code？
- 自研 IDE？
- 自动化脚本？
### 2. 真正需要什么？
- 单次 Task？
- 持久 Thread？
- Approval？
- Streaming？
- MCP Tool？
### 3. 选择目标接口
```text
CI / Automation → SDK
Rich Client → App Server
Claude Code → Plugin
Tool Provider → MCP Server
```
### 4. 实现初始化
```text
initialize
→ initialized
```
### 5. 实现 Thread / Turn
### 6. 实现 Notification
### 7. 实现 Approval
### 8. 实现 Timeout / Retry
### 9. 做 Sandbox 和权限测试
### 10. 再删除旧 `mcp-server` 依赖
## 最终判断
`codex mcp-server` 的弃用不是“OpenAI 不支持 MCP 了”。
恰恰相反。
它说明 Codex 的架构边界正在变得更明确：
```text
MCP Server
→ 给 Agent 提供外部工具
Codex App Server
→ 把 Codex Runtime 嵌进富客户端
Codex SDK
→ 自动化和 CI
Codex Plugin
→ 集成到其他 Agent Client
```
这种分层对长期生态更健康。
如果你的项目以前把 Codex 当成一个 MCP Tool 暴露出去，现在应该重新问：
> 我真正需要的是“调用一次 Codex”，还是“嵌入完整 Codex Agent Runtime”？
答案不同，迁移路径完全不同。
想继续了解 Codex、MCP、AI Coding Agent 和开发基础设施，可以访问 **智元选**：https://www.zyentorpicks.com/。我们会持续跟踪真正影响工程集成方式的产品变化。