Codex MCPサーバー非推奨で変わる接続方法と移行手順を解説

8月24日の公式告知で何が変わったか

今回の起点は、OpenAIの公式リリースノートに2026年8月24日付で掲載された「Codex MCP server command deprecated」です。告知は、codex mcp-server コマンドが非推奨になったこと、代わりに Codex app server を使うこと、Claude CodeからCodexを利用する場合はCodexプラグインを使うことを短く示しています。日付と対象コマンドが明記されているため、MCPを使う開発者にとっては、設定を急いで壊すニュースではなく、次の接続先を決めるための確認材料です。

「非推奨」は、現在の版でただちにプロセスが起動しなくなる、という表現ではありません。通常は、既存の利用を残しつつ、今後の説明や新しい機能の中心を別の方法へ移す合図です。ただし、いつまで動くか、どの版で削除されるかまでは、今回のリリースノートだけでは断定できません。したがって、古い命令が動いているから安心とも、告知を見たから即日切り替えるとも考えず、使っている版と接続先を照合します。

非推奨と停止を混同しない

非推奨化を見たときに最初に行うべきことは、古い接続をその場で削除することではありません。現在のCodexの版で codex mcp-server が呼ばれているか、呼び出し元がどのクライアントなのか、実際の作業がどこまで進むのかを記録します。告知に停止日や削除された版の番号が書かれていないなら、記事で「この日から使えない」と断定せず、将来の移行が必要になったという範囲にとどめます。

反対に、停止日が明記されていないことを理由に確認を先延ばしにするのも危険です。接続方式が古いままだと、次回のアップデートでエラーの場所が変わったときに、命令の問題なのか、クライアントの問題なのか、モデルの問題なのかを切り分けにくくなります。いま動く状態を比較対象として残し、新しい接続を別の場所で試せるようにしておくと、変更の影響を小さくできます。

移行対象を判定する

対象になるのは、CodexをMCPサーバーとして起動し、別のMCPクライアントからCodexのスレッドやターンを操作している構成です。設定ファイルにMCPサーバーの登録があるだけでは、今回の告知対象とは限りません。Codexが外部のMCPサーバーを呼ぶ側なのか、Codex自身を外部から呼ぶ側なのかで、確認する命令と移行先が変わるからです。

判定は、設定名ではなく実際の起動経路で行います。クライアントの設定、起動ログ、プロセスの引数、接続に使う通信方式を順番に見て、codex mcp-server という文字列がどこに現れるかを探します。見つからない場合でも、アプリや拡張機能が内部で呼び出している可能性があるため、利用している製品の公式説明と、手元で表示される版番号を合わせて確認します。

旧 codex mcp-server と Codex app serverの役割

OpenAI Codexリポジトリの旧インターフェース資料では、旧方式を「experimental」とし、codex mcp-server をサーバー実行の入口、stdio上のJSON-RPC 2.0を通信と説明しています。対象はスレッドやターン、アカウント、設定、モデル一覧、承認です。つまり外部MCPクライアントがCodexエンジンを操作するための、かなり直接的な接続です。

一方、Codex app serverの公式READMEは、codex app-server をCodexの豊かなインターフェースを支える面として説明し、CodexのVS Code拡張も利用例に挙げています。JSON-RPC 2.0を使う点は似ていますが、初期化、スレッドの開始や再開、ターンの開始、イベントの受信、承認への応答というライフサイクルを、連携するクライアントが明確に扱う設計です。

両者の差を「古い実行ファイルと新しい実行ファイルの差」だけで読むと、移行時の不具合を見落とします。旧方式で動いていたクライアントが、起動したプロセスへ文字列を渡すだけの作りなら、app serverの初期化通知やイベント処理まで実装し直す必要があります。逆に、すでにthreadとturnを扱うクライアントなら、通信先と初期化条件を照合することで移行範囲を絞れる可能性があります。

通信方式だけでなくライフサイクルが違う

旧資料は、MCP transport上でJSON-RPCを流し、Codexの機能を外部クライアントへ公開する考え方を示しています。利用する側は、呼び出し可能なメソッドと結果の形式を理解していれば、目的の操作へ進めます。しかし、起動直後に何を送るのか、接続が終わる前に何を受け取るのかが、利用するクライアント側の前提になっていると、別のサーバーへ置き換えたときに接続はできても会話が始まらないことがあります。

app serverのREADMEは、接続後に initialize を一度送って initialized を通知し、その後に thread/start や thread/resume を呼ぶ順番を示しています。ターンを開始したあとも、結果だけを待つのではなく、進行中のイベントを受け取り、最後に turn/completed を確認します。移行の成否はプロセスが起動したかではなく、この一連の流れが最後まで成立するかで判断します。

Codexから外部MCPを呼ぶ設定は別物

Codexが外部のMCPサーバーを呼び出す構成と、CodexをMCPサーバーとして公開する構成は、言葉が似ていても向きが逆です。旧資料でも、codex mcp サブコマンドは設定ファイルに登録したMCPサーバーの起動管理に使うものとして説明されています。今回の非推奨化を見て、外部サービスの登録まで一括して削除する必要はありません。

まず自分の構成を「Codexから外部へ接続する」「外部クライアントからCodexを呼ぶ」のどちらか一文で書きます。前者なら現在のMCP登録と利用範囲を確認し、後者なら codex mcp-server からapp serverへ移る設計を確認します。この区別を先に付けるだけで、変更しなくてよい設定を触るリスクを減らせます。

移行前に現状を記録する

移行で最も時間を使うのは、新しい命令を知ることより、いま何が動いているかを正確に説明することです。クライアント名だけでは、背後でどのCodexバイナリが起動され、どの設定を読み、どの通信路を使っているか分かりません。変更前の状態を短い記録にまとめ、同じ入力を新方式へ渡せるようにしておくと、差分を判断しやすくなります。

記録には、利用中のCodexの版、呼び出し元のアプリや拡張機能、起動命令、作業場所、選択したモデル、通信方式、初期化の順番、承認が必要な操作の扱いを含めます。認証に関する値そのものをメモへ貼り付ける必要はありません。値ではなく、どの認証状態を参照する構成かだけを残し、検証用の記録が別の場所へ広がらないようにします。

Step 1: 起動経路を確認する

まず、クライアントの設定や起動スクリプトを読み、codex mcp-server を直接指定しているかを確認します。直接書かれていなくても、別の名前の補助プログラムが内部で呼んでいる場合があります。起動ログに出るプロセス名、引数、作業ディレクトリを一つの記録へまとめ、手動で起動した場合とアプリから起動した場合で差がないかを見ます。

この段階では、設定の書き換えを行わず、読み取りだけにします。旧方式を使っているか分からない状態で新しい命令を追加すると、二つのプロセスが同じ作業場所を扱い、どちらの結果か判定できなくなることがあります。起動経路が分からない場合は、まずクライアントの公式ドキュメントにある接続名と、手元のログに出る実際の命令を照合します。

Step 2: クライアントと通信方式を記録する

次に、接続する側のクライアントが何か、stdio、WebSocket、Unixソケットのどれを使うかを記録します。app serverのREADMEでは、stdioが標準で、WebSocketとUnixソケットは用途や状態が異なる接続方式として説明されています。旧方式のクライアントがstdioの行区切りJSONだけを前提にしているなら、通信方式を変えない移行と、通信方式まで変える移行を分けて考えます。

通信方式の記録には、接続を開く人、入力を送る場所、出力を読む場所、切断を判断する条件を含めます。画面に返答が出たかだけを見ると、途中のイベントや承認要求が捨てられている可能性があります。最初の接続で取得した初期化応答、スレッドID、ターンID、完了イベントを、個人情報や認証値を含めない形で残すと比較に使えます。

Step 3: スレッドと承認の扱いを確認する

旧方式では、スレッドやターンを操作するメソッドと、変更やコマンド実行の承認要求が同じインターフェース資料に並んでいます。現在のクライアントが承認要求を画面へ出しているのか、拒否を返せるのか、接続が切れたときに作業をどの状態として保存するのかを確認します。単純な質問への返答だけでは、ここまでの互換性は分かりません。

検証用の入力は、ファイルを読むだけの依頼、差分を提案する依頼、承認が必要な変更の三つに分けます。新方式へ切り替えたあと、それぞれの結果、イベント順、承認画面、エラー文が旧方式と同じ意味で届くかを見ます。内容が少し違うこと自体は問題ではありませんが、利用者が確認すべき境界が消えていないことが重要です。

Step 4: 版番号と公式資料をそろえる

CodexはCLI、アプリ、拡張機能で表示される版番号が異なる場合があります。codex --version などでCLIの版を確認したうえで、利用している入口の「About」画面や拡張機能の情報も記録します。公開済みの版はOpenAI Codexの公式Releasesで確認し、記事や相談では系列名だけでなく完全な版番号を使います。

古いインターフェース資料が残っているからといって、今後も同じ方法が推奨されるとは限りません。公式リリースノート、app server README、利用中の版のリリースページを同じ日に開き、どの資料が現在の判断を支えるのかを明記します。資料の更新日が分からない場合は、その不確かさも記録しておくと、後で新しい説明が追加されたときに見直しやすくなります。

Codex app serverで確認する基本動作

移行先を確認するなら、まずapp serverを一つの通信面として理解します。公式READMEは、codex app-server がCodexの豊かなインターフェースを支えること、JSON-RPC 2.0を使うこと、stdioを標準にWebSocketやUnixソケットなどの接続方式を持つことを説明しています。ここで重要なのは、旧MCPサーバーの名前をapp serverへ置換することではなく、接続から完了までの契約を新しい資料に合わせることです。

アダプターやクライアントを作る場合は、最初からすべての機能を移そうとせず、初期化、スレッド開始、短いターン、完了イベントの順に確かめます。CodexのVS Code拡張など、公式READMEが想定する利用面に近い構成を参考にしつつ、自分のクライアントが必要とする操作だけを選びます。使わないモデル一覧や設定変更まで先に扱うと、失敗箇所が増えて比較が難しくなります。

initializeで接続を確定する

app serverの接続直後に必要なのは、initialize リクエストと initialized 通知です。公式READMEは、初期化より前に別の要求を送ると「Not initialized」として拒否され、同じ接続で初期化を繰り返すと「Already initialized」になると説明しています。旧方式で接続直後にいきなりスレッド操作を送っていたクライアントは、この順番を最初に見直します。

初期化時にはクライアント情報と対応能力を伝えますが、宣言した能力と実際に処理できる能力を一致させる必要があります。イベントを受け取れないのに対応済みと伝える、承認要求を表示できないのに操作を進める、といった状態は、接続成功に見えても利用者の確認を失わせます。最初の試験では、初期化要求と応答を保存し、どの項目が必須だったかを確認します。

threadとturnを分けて検証する

公式READMEでは、threadは会話、turnは一回の指示とその結果、itemはその中の入力や出力として整理されています。新しい会話を始める場合は thread/start、続きから再開する場合は thread/resume、指示を送る場合は turn/start を使うという順序です。旧クライアントが一つの呼び出しでまとめて扱っていたなら、どのIDを保存し、次の要求へ渡すのかを分けて確認します。

試験では、同じthreadで二つのturnを続ける場合と、新しいthreadを作る場合を別々に実行します。前のターンの文脈が残ること、再開したターンが別の会話として扱われないこと、割り込み後に状態を読めることを確認します。返答文だけを比較せず、thread ID、turn ID、完了状態、利用量など、クライアントが後から判断に使う情報も確認対象にします。

イベントと承認を受け取る

turn/start の直後に最終回答だけが返るとは限りません。app serverは、ターン開始、項目の開始と完了、テキストの差分、ツールの進行、ターン完了などの通知を送ります。公式READMEにあるイベントの流れを読み、画面へ表示するもの、ログへ残すもの、利用者の判断を待つものを分けてください。途中の通知を捨てるクライアントは、処理が止まったのか、まだ進んでいるのかを伝えられません。

ファイル変更やコマンド実行の承認では、サーバーからクライアントへ承認要求が届き、クライアントは許可または拒否を返します。移行試験では、許可だけでなく拒否、入力の不備、途中切断も確認します。旧方式で見えていた承認の境界が新方式で見えなくなっていないこと、拒否後にターンが適切な状態で完了することが、採用前の重要な条件です。

接続 → initialize → initialized → thread/start または thread/resume
     → turn/start → 進行イベント → 承認への応答 → turn/completed

実際の移行手順

接続の違いを理解したら、変更範囲を小さく保ったまま移行します。普段使いの設定を一度に置き換えるのではなく、旧方式を比較対象として残し、同じクライアントが新方式へ接続できる場所を別に用意します。検証用のプロジェクトは、結果を人が読みやすく、問題が起きても影響を限定できるものを選びます。

app serverを使う場合の具体的な引数や対応方式は、利用しているCodexの版で変わる可能性があります。以下の手順は、公式READMEの初期化とthread/turnの考え方に沿った確認順です。コマンドやメッセージ形式は、必ず公式app server READMEと手元の版の資料を照合してください。

Step 1: 旧設定を保存する

現在の設定ファイル、クライアント側の接続定義、利用中のCodexの版を保存します。保存するのは再現に必要な項目であり、認証に使う値そのものや、リポジトリの内容を丸ごとコピーする必要はありません。旧方式へ戻す可能性がある場合は、ファイル名と保存日時を記録し、どの設定が現行かを分かるようにします。

ここで保存した内容は、変更後の比較に使います。旧接続を停止してから記録すると、ログやプロセスの情報が失われることがあるため、起動中の状態も含めて先に確認します。共有する記録には、作業場所や個人情報を必要以上に含めず、版番号、命令、通信方式、結果の要約に絞ると、相談時にも安全に扱えます。

Step 2: app serverの接続面を用意する

公式READMEが示す入口は codex app-server です。stdioで試す場合は、利用版で標準の接続方式が何か、--stdio を明示できるか、JSONLの入出力をどこで読むかを確認します。旧方式のMCPクライアントへ新しい入口をそのまま渡せるとは限らないため、初期化とイベントを扱えるアダプター、または対応済みの公式クライアントを使います。

接続を開いたら、いきなりファイルを変更する指示を送らず、まず initialize を送り、応答と initialized 通知を受け取ります。初期化前の要求、二重初期化、対応能力の宣言ミスは、後のターンの問題に見えることがあります。ログには要求の種類と結果を残し、認証値や入力の全文は記録対象から外します。

Step 3: 読み取りだけのthreadで試す

次に、テスト用の小さなプロジェクトで thread/start と turn/start を使い、ファイルの読み取りや構成の説明だけを依頼します。ここでは、thread IDとturn IDが返ること、進行イベントが届くこと、最後に turn/completed を受け取ることを確認します。回答の内容が旧方式と完全に同じかよりも、会話の開始から完了までの状態が欠けずに伝わることを重視します。

同じthreadで追加のturnを送ったときに、前の文脈が意図どおり残るかも見ます。新しいthreadを作る場合は、前の会話と混ざらないことを確認します。接続が切れたとき、再開できるIDが保存されるか、失敗が利用者へ明確に伝わるかまで試すと、短い成功例だけでは見えない差を把握できます。

Step 4: 承認と失敗時の動きを試す

読み取りが成立したら、差分を提案する依頼、ファイル変更の承認を求める依頼、拒否する依頼を順に試します。app serverの公式資料にある applyPatchApproval や execCommandApproval の考え方と、実際にクライアントへ表示される内容を照合します。承認の理由、対象、引数が利用者に見え、拒否した結果がターンへ正しく反映されることが条件です。

エラー試験では、存在しないthread ID、初期化前の要求、切断、応答の遅延を確認します。失敗時にクライアントが同じ要求を何度も送り続けないか、途中の変更が残ったと誤解させないか、再接続後に古いIDを誤って使わないかを見ます。通常の返答が一度成功しただけでは、移行の安全性を判断できません。

Step 5: 比較結果を残して切り替える

旧方式と新方式で同じテストを行い、起動、初期化、thread、turn、イベント、承認、完了の各項目を比較します。違いがあった場合は、回答文の差、イベント名の差、画面表示の差、利用者の操作が必要な場所の差を分けます。差が説明でき、必要な確認が失われていなければ、切り替えの判断材料になります。

普段の環境へ広げるときも、対象をまとめて変えず、まず一つのクライアント、一つのプロジェクト、一つの接続方式から始めます。問題が出たときに旧方式へ戻せるよう、保存した設定と検証結果を残します。なお、非推奨化の解除や停止日が公式に示されるまでは、古い設定を保管する意味がありますが、通常利用を旧方式へ戻す判断は、利用する版の公式案内を確認してから行います。

Claude CodeからCodexを利用する場合

OpenAIのリリースノートは、Claude CodeからCodexを利用する場合にCodexプラグインを使う案内も加えています。公式リポジトリのCodex plugin for Claude Codeは、Claude Code内からCodexのレビューやタスク委譲を行うためのプラグインで、READMEではCodex app serverを包み、同じCodex CLIの設定を利用すると説明しています。

この案内は、Claude CodeとCodexを同じ作業場所で使う人にとって、旧 codex mcp-server を自分で呼び出す接続を新規に組む前に確認すべき選択肢です。ただし、プラグインを追加すれば利用中の設定がすべて正しく移るとは限りません。Codex CLIの版、ローカルの認証状態、プロジェクトの信頼設定、利用者へ表示される承認を、導入前後で分けて確認します。

公式プラグインを使う意味

公式プラグインのREADMEは、Codex CLIとCodex app serverを同じ端末上で使い、Codex側の設定を参照する構成を説明しています。これにより、旧MCPサーバーの実験的な仕様を前提に、Claude Codeから呼び出すための橋渡しを独自に作る必要があるかを見直せます。まず公式の連携方法で、レビュー、調査、修正提案が期待どおり返るかを確認します。

一方、独自のクライアントや社内の画面からCodexを呼びたい場合は、プラグインの導入だけで要件を満たせないことがあります。その場合はapp serverのREADMEを直接読み、初期化、thread/turn、イベント、承認をどこで扱うかを設計します。公式プラグインの動作を見たからといって、同じ内部処理を説明なしに再現できると考えないことが大切です。

既存MCP設定をそのまま持ち込まない

Claude Code向けの公式プラグインを試す場合でも、既存のMCPサーバー登録を一度に移す必要はありません。Codexから外部のMCPサーバーを呼ぶ設定と、Claude CodeからCodexを呼ぶ入口は別の層です。まずCodex単体でapp serverの初期化と短いturnを確認し、その後にClaude Codeから同じ作業場所を開いて結果を比べます。

二つの入口を並べて試すときは、同じthreadを同時に操作しないようにします。クライアントごとに新しいthreadを使い、表示される承認、完了状態、変更差分を別々に確認します。もし片方だけが失敗したなら、Codex本体の問題ではなく、プラグインの版、クライアント情報、接続の保持方法に原因がある可能性があります。公式リポジトリのIssueやリリース情報を確認し、手元の版と照合してください。

互換性を見極めるチェックポイント

旧方式からapp serverへ移るとき、互換性を一つの「動いた、動かない」で判断しないことが重要です。起動できても、初期化が完了していない、イベントが欠けている、承認を表示できない、切断後に再開できないという状態は、実際の開発では問題になります。接続、会話、操作、結果の四つに分けて、確認した範囲を残します。

また、app serverの仕様は利用するCodexの版に結び付きます。公式READMEにある機能が、手元の安定版やアプリの入口ですべて同じように表示されるとは限りません。版を上げるときは、接続方式の移行と版の更新を同時に行わず、片方を固定してもう片方の差分を見ます。問題の原因を一つずつ分けられる状態を維持することが、移行期間の負担を減らします。

版番号と資料の更新日を残す

記事やチーム内の記録に「最新のCodex」とだけ書くと、後で同じ結果を再現できません。CLIの版、アプリの版、拡張機能の版を分け、確認した日時を日本時間で残します。公式Releases、公式リリースノート、app server READMEのどれを根拠にしたかもリンクで示し、後日内容が変わったときに再確認できるようにします。

先行版を検証に使う場合は、安定版と同じ扱いにしないことも必要です。先行版で動く機能が安定版へまだ含まれないこと、逆に先行版の変更で接続の挙動が変わることがあります。移行の判断は、機能が見えたことだけでなく、普段の版で初期化から完了までの確認が終わったかで決めます。

エラー時の切り分け順

エラーが出たら、最初に起動命令と版番号、次に初期化、続いてthreadとturn、最後にイベントと承認を見ます。接続自体が開いていない状態でメッセージ形式を直しても意味がありません。初期化が通っていない状態でモデルや作業内容を変えても、原因は狭まりません。段階ごとに最小の入力を使い、最初に失敗した場所を固定します。

同じエラーが再現したら、入力の全文ではなく、要求の種類、返ったエラーコード、利用した版、接続方式、発生した段階を記録します。認証に関する値やプロジェクトの内容を含めずに、公式リポジトリのIssueや相談先へ共有できる形にします。公式資料に記載がない挙動は、仕様として断定せず、手元で確認した事実として扱います。

まとめ：今すぐ行うべき確認

2026年8月24日のOpenAI公式リリースノートで、codex mcp-server は非推奨となり、Codex app serverへ移る方向が示されました。これは既存接続をその場で消す指示ではありませんが、MCPサーバーとしてCodexを呼び出している人は、次の更新で困らないように、いまの接続経路を確認するタイミングです。旧方式の公式資料が「experimental」と記している点も、今後の基準をapp serverへ置く理由として読めます。

移行の要点は、コマンドを置き換えることではなく、初期化、thread、turn、進行イベント、承認、完了までの意味を新しい接続面で再確認することです。特に、Codexから外部MCPを呼ぶ設定と、外部クライアントからCodexを呼ぶ設定は別物なので、影響範囲を先に分けます。迷ったときは、OpenAI公式リリースノート、旧MCPインターフェース資料、app server READMEを同じ版番号と照合してください。

1. codex mcp-server を実際に起動しているか調べる。
2. 現在の版、クライアント、通信方式、承認の扱いを記録する。
3. codex app-server を検証用の場所で初期化し、読み取りだけのthreadを完了させる。
4. threadの再開、イベント、承認、拒否、切断後の状態を確認する。
5. 公式資料と比較結果を残してから、対象を一つずつ新方式へ切り替える。