Codex mcp-server 已棄用怎麼辦？改用 app-server 與 Claude Code Plugin
如果你在 IDE、桌面工具或自己的啟動腳本裡執行 codex mcp-server，現在不應該只把指令字串換成另一個名稱。OpenAI 已在 release notes 將 codex mcp-server 標為 deprecated；新的整合方式要看你要連接的是 rich client、Claude Code，還是 CI／自動化流程。
先講結論：需要對話歷史、審批和串流事件的應用程式，評估 Codex app-server；想在 Claude Code 裡使用 Codex，安裝官方 Codex Plugin for Claude Code；純自動化與 CI 則優先看 Codex SDK。app-server 是 JSON-RPC 介面，不是 MCP server 的相容替代端點，舊 MCP client 不能只靠改 command 就直接接上。
先找出舊的 mcp-server 整合
先在 repository、啟動腳本和 CI 設定裡找出實際的啟動位置：
rg -n --hidden --glob '!node_modules' 'codex mcp-server|mcp-server' .接著記錄這四件事：
- 舊 client 用的是 MCP 的哪種 transport，以及它期待哪些 tool 或 resource。
- 認證、工作目錄、環境變數和 process 權限從哪裡注入。
- client 是否依賴對話歷史、審批、串流事件或長駐 process。
- CI 是否只需要一次性執行，還是需要持續接收 agent event。
這份盤點會決定遷移方向。若只把 codex mcp-server 改成 codex app-server，client 仍送 MCP handshake，就會遇到協定不符或初始化失敗。
如果舊整合還依賴 MCP 的 Roots、Sampling 或 Logging capability，也可以先參考 MCP 棄用能力的盤點與遷移清單，把協定層的相容性工作和 Codex process 遷移分開處理。
三種整合方式怎麼選
| 需求 | 建議方向 | 原因 |
|---|---|---|
| IDE、桌面工具或自建 rich client | codex app-server | 提供 thread、turn、審批與串流 agent event 的 JSON-RPC 介面 |
| 在 Claude Code 裡呼叫 Codex | Codex Plugin for Claude Code | 由 plugin 處理 Claude Code 內的 Codex 使用流程 |
| CI、批次工作或應用程式後端 | Codex SDK | 官方 app-server 文件把 SDK 列為 automation／CI 的整合方向 |
app-server 與 SDK 的分界很重要：前者適合需要互動狀態的 client，後者比較適合你掌控工作佇列、重試、輸出格式和生命週期的自動化程式。
用 app-server 取代舊 command 的正確方式
本機 stdio：先跑通 JSONL lifecycle
codex app-server 預設使用 stdio 傳送 JSONL。官方協定要求先完成一次 initialize／initialized，再開始 thread/start 和 turn/start；在初始化完成前送其他 request，server 會拒絕。
啟動方式很簡單：
codex app-server下面是 lifecycle 的精簡形狀。實際 client 應讀取 thread/start 的回應取得 threadId，再把它帶入下一個 request；server 也會在執行期間送出串流 notification。
{"method":"initialize","id":1,"params":{}}{"method":"initialized","params":{}}{"method":"thread/start","id":10,"params":{"model":"gpt-5.6-terra"}}{"method":"turn/start","id":11,"params":{"threadId":"<thread-id>","input":[{"type":"text","text":"Summarize this repo."}]}}把這段當成協定順序示意，不要把 <thread-id> 原樣送出。正式 client 還要處理 response、notification、錯誤、審批事件和 process 結束，不能只等待一個最後的 stdout 字串。
WebSocket：先限制在本機或 SSH forwarding
需要分離 client 和 server process 時，可以讓 app-server 監聽本機 WebSocket：
codex app-server --listen ws://127.0.0.1:4500codex --remote ws://127.0.0.1:4500官方文件建議把明文 ws:// 限制在 localhost 或 SSH port forwarding。若要讓非本機 client 連線，應使用 TLS、認證和適當的網路邊界，例如文件列出的 capability token 或 signed bearer token 選項；不要把未驗證的 WebSocket 綁到公網。app-server 的 command／WebSocket transport 目前仍屬 experimental，官方不建議直接拿來承擔 production workload。
先生成 schema，再寫 client
如果你要自己實作 JSON-RPC client，可以先把 TypeScript 或 JSON Schema 生成到 repository：
codex app-server generate-ts --out ./schemascodex app-server generate-json-schema --out ./schemas把 schema 產物納入版本控管，並在 Codex CLI 更新時重新檢查 diff。這比在 client 裡散落手寫的 event type 更容易發現協定變更。
Claude Code 應該安裝 Plugin，不是接 MCP endpoint
如果目標是在 Claude Code 裡使用 Codex，官方 plugin repository 提供的安裝流程是：
/plugin marketplace add openai/codex-plugin-cc/plugin install codex@openai-codex/reload-plugins/codex:setup官方 repository 目前要求 Node.js 18.18 以上，並且需要 ChatGPT 訂閱或 API key。若使用手動 CLI 方式，文件也列出：
npm install -g @openai/codex接著在 Claude Code 裡執行 !codex login。Plugin 的用途是把 Codex 帶進 Claude Code；它不是把舊 MCP client 轉成 app-server client，也不代表所有既有 MCP tools 會自動搬過去。原本依賴自建 tool server 的部分，仍要逐項測試。
建議用小批次 rollout 驗證遷移
遷移第一版可以用一個最小 repository 和一條可重現的 prompt 開始，依序確認：
- 認證能使用正確的 ChatGPT account 或 API key，且不會把 token 寫進 log。
initialize完成後才建立 thread 和 turn，錯誤能被 client 正確處理。- 串流文字、tool event、審批 request 和拒絕結果都能被保存或顯示。
- 對話歷史、工作目錄、sandbox／權限邊界與舊流程一致。
- client 能在成功、失敗、取消和 server 重啟時清理 process。
- CI 若不需要互動協定，改用 SDK 後仍能控制 timeout、重試和輸出格式。
正式切換前，保留舊整合的設定快照與一組固定測試案例。新舊結果不必逐字相同，但至少要比較完成率、tool call、審批行為、錯誤處理和敏感資料是否外洩。
常見問題
Q: 可以把 codex mcp-server 直接替換成 codex app-server 嗎？
A: 不行。兩者的協定和 client lifecycle 不同。你需要先判斷 client 是要 app-server 的 JSON-RPC thread／turn，還是其實只需要 SDK 的一次性呼叫；若是 Claude Code，則應安裝官方 plugin。
Q: app-server 適合 production CI 嗎？
A: 官方 app-server 文件把 Codex SDK 指向 automation／CI，並說 app-server command／WebSocket transport 仍是 experimental、unsupported for production。CI 應優先用 SDK；若有特殊理由使用 app-server，至少要自行承擔版本、認證、重連與協定相容性驗證。
Q: 為什麼一送 request 就得到 Not initialized？
A: 先確認同一條 transport 已完成 initialize request 和 initialized notification，再送 thread/start。也要確認 client 沒有把 server 的 JSONL response 當成一般文字輸出吞掉，並保留 request id 來對應錯誤。
參考資料：
回報錯字、失效連結，或告訴我你想看的延伸主題。