Codex app serverとは｜Codexの共通ハーネスをJSON-RPCで外部に開く仕組みとSDK・MCPの違い

Codex app server（コマンドとしては codex app-server）は、OpenAI の Codex を VS Code 拡張のような高機能なクライアントに組み込むためのインターフェースです。OpenAI は 2026 年 2 月 4 日の公式記事で、この仕組みを「すべての Codex 体験を支える共通の土台」として公開しました（OpenAI: Unlocking the Codex harness）。

01.結論：Codex app server とは何か

Codex には、ターミナルで動く CLI、VS Code 拡張、macOS アプリ、Web といった複数の入り口があります。これらはすべて、同じ「ハーネス」（エージェントループ）の上で動いています。その間をつなぐのが Codex app server で、OpenAI はこれを「クライアントから扱いやすい、双方向の JSON-RPC API」と説明しています（OpenAI, 2026-02-04）。

app server の実装は OSS として公開されており、GitHub の openai/codex（codex-rs/app-server）で中身を確認できます。使い方の公式ドキュメントは OpenAI Developers の App Server ページにまとまっています。

02.なぜ生まれたか：CLIのTUIから共通ハーネスへ

Codex CLI は、もともとターミナル上の TUI（テキストユーザーインターフェース）として始まりました。その後 VS Code 拡張を作るとき、IDE の画面から同じエージェントを動かす必要が出てきました。ここで OpenAI は、エージェントの中身（ハーネス）を拡張側で作り直すのではなく、CLI と同じハーネスをそのまま使う道を選びます（OpenAI: Unlocking the Codex harness）。

OpenAI はハーネスを「すべての Codex 体験の土台にある、エージェントループとロジック」と説明しています。Web・CLI・IDE 拡張・macOS アプリは見た目こそ違いますが、内部では同じハーネスが動いており、その共通の入り口が app server です。1 つのエージェントを作り込めば、複数のクライアントへ同時に届けられる構造になっています。

03.仕組み：双方向JSON-RPCとThread・Turn・Item

app server は MCP と同じく JSON-RPC 2.0 をベースにしています。会話の状態は、Thread・Turn・Item という 3 つの単位で表されます（openai/codex: app-server README）。

やり取りするのは、特別なファイルではなく、次のような 1 件ずつの JSON メッセージです。要求にはメソッド名（method）・引数（params）・識別子（id）を入れ、応答は同じ id に結果（result）かエラー（error）を返します。id を持たないメッセージは通知（notification）で、サーバーからクライアントへイベントを一方的に送るのに使います。app server はこの通知とサーバー起点の要求を組み合わせて、ストリーミングや承認といった双方向のやり取りを実現します。

// 要求（request）：id を付けてメソッドを呼ぶ
{ "method": "thread/start", "id": 10, "params": { "model": "gpt-5.4" } }

// 応答（response）：同じ id に結果が返る
{ "id": 10, "result": { "thread": { "id": "thr_123" } } }

// 通知（notification）：id なし。サーバーからイベントが届く
{ "method": "turn/started", "params": { "turn": { "id": "turn_456" } } }

起動と初期化：transportとinitialize

サーバーは codex app-server で起動します。既定の transport（通信路）は標準入出力（stdio）で、1 行 1 メッセージの JSON（JSONL）をやり取りします。ほかに WebSocket や Unix ソケット経由の起動もありますが、WebSocket は実験的かつ未サポートの位置づけで、利用できる範囲は Codex のバージョンによって変わります。

# 標準入出力（stdio）で起動する
codex app-server

接続の最初に、クライアントは initialize を 1 回だけ送ります。これは接続開始時の取り決め（ハンドシェイク）で、サーバーは構成情報を返し、クライアントは続けて initialized の通知を送ります。以降のやり取りはこの後に始まります。なお JSON-RPC の "jsonrpc": "2.0" ヘッダは、通信上は省略されます。

{
  "method": "initialize",
  "id": 0,
  "params": {
    "clientInfo": {
      "name": "my_app",
      "title": "My Codex Integration",
      "version": "0.1.0"
    }
  }
}

Thread・Turn・Item という3つの単位

やり取りは、次の 3 つの単位で組み立てられます。会話そのものを Thread、その中の 1 往復を Turn、ユーザー発言やコマンド実行・ファイル編集といった個々の出来事を Item として扱います。

• Thread（スレッド）：ユーザーと Codex の 1 つの会話です。新規作成のほか、過去のスレッドの再開や分岐もできます。
• Turn（ターン）：会話の 1 サイクルです。ユーザー入力から始まり、Codex の生成で終わります。
• Item（アイテム）：ターンの中で起きる個々の出来事です。ユーザー発言・推論・コマンド実行・ファイル編集などが該当します。

スレッドは保存されるので、後から再開したり、履歴を読み出したりできます。会話を保持して動かし続けるこの作りが、対話的なクライアントを支えています。

ストリーミングイベントと承認リクエスト

ターンの最中、サーバーは進行状況をイベントとして次々に送ります。ターンの開始、アイテムの開始、生成テキストの逐次追記、アイテムの完了、ターンの完了といった通知が届き、クライアントは途中経過をそのまま画面に流せます。

双方向である点が、ここで効いてきます。Codex がコマンドを実行したりファイルを変更したりする前に、サーバーは承認リクエストをクライアントへ送って処理を止めます。クライアントは「承認」または「拒否」を返し、その判断を受けてエージェントが先に進みます。危険なコマンドの前に人の確認を挟む、といった制御をこの仕組みで組み込めます。

WebSocket で動かす場合、サーバーが要求を受けきれないと、JSON-RPC のエラーコード -32001（「Server overloaded; retry later.」）が返ります。クライアント側は、待ち時間を少しずつ延ばしながら再試行する作りにしておくのが前提です。

04.app server・SDK・MCP の使い分け

OpenAI は VS Code 拡張を作る初期に、Codex を MCP サーバーとして公開する案も試しています。しかし、ワークスペースの探索・進行状況のストリーミング・差分の提示・承認フロー・スレッドの保存といった対話的なやり取りは、ツール呼び出しを基本とする MCP の形にきれいに収まりませんでした（OpenAI: Unlocking the Codex harness）。そこで、TUI のループをそのまま写した独自の JSON-RPC として app server が作られました。OpenAI はこの app server を、VS Code 拡張のようなリッチなクライアントを動かすための共通インターフェースと位置づけています（OpenAI Developers: App Server）。

Codex を外部から動かす手段は、app server のほかにも 2 つあります。用途で選ぶのが分かりやすいです。

app server と SDK は、対立する別物というより抽象度の違いです。SDK は「タスクを渡して結果を受け取る」高レベルのライブラリで、UI を描かないヘッドレスな用途（CI・バックエンド・定期実行）に向きます。app server は「作業の様子をストリーミングで受け取り、承認要求に答えながら進める」低レベルのインターフェースで、VS Code 拡張のような対話的なクライアントを自前で組むときに使います。分かれ目は、エージェントが動く過程をライブで見せて途中で介入する必要があるかどうかです。

SDK は JSON-RPC のクライアントを自前で作らずに済む手軽さがある一方、対応言語や扱える範囲は app server より狭くなります（OpenAI Developers: SDK）。MCP は逆向きにも使え、codex mcp-server で Codex 自体を MCP クライアントから呼び出せます（OpenAI Developers: MCP）。OpenAI は、簡単な使い方なら Codex を MCP サーバーとして動かす形も引き続きサポートしつつ、作り込んだ統合には app server を勧めています。

05.スキーマ生成とバージョンへの追従

app server のメッセージ定義は、CLI からそのまま書き出せます。TypeScript の型定義は codex app-server generate-ts、JSON Schema は codex app-server generate-json-schema で出力します。

# TypeScript の型定義を書き出す
codex app-server generate-ts --out ./schemas

# JSON Schema を書き出す
codex app-server generate-json-schema --out ./schemas

出力されるスキーマは、実行した Codex のバージョンに対応した内容になります。メソッド名や扱える transport は版によって変わるため、Codex を更新したらスキーマを取り直し、自分のクライアントを合わせるのが安全です。本記事の内容も 2026-05 時点のもので、最新の仕様は公式ドキュメントと、生成したスキーマで確認してください。

06.何に使えるか

app server が向くのは、Codex を自分たちの環境に組み込みたい場面です。独自のエディタやツールへの統合、社内のエージェント運用基盤、承認フローを挟んだ作業の自動化などが当てはまります。認証（ChatGPT ログインや API キーの管理）・会話履歴・ストリーミング・差分・承認が一通り使えるため、VS Code 拡張と同等のやり取りを自前のクライアントでも組めます。認証を app server 側が扱うため、クライアントはログインの仕組みを自作せずに済みます。

07.よくある質問（FAQ）

08.まとめ

Codex app server は、Codex のハーネス（エージェントループ）を双方向 JSON-RPC で外部に開くサーバーです。VS Code 拡張を作る過程で、同じハーネスを作り直さずに使うために生まれ、いまは CLI・IDE 拡張・macOS アプリ・Web が同じ土台を共有しています。Thread・Turn・Item でやり取りを表し、ストリーミングと承認リクエストでリッチなクライアントを支えます。Codex を自社プロダクトに深く組み込むなら app server、CI や自動化なら SDK、外部ツール接続なら MCP、という整理が出発点になります。仕様は版で変わるため、公式ドキュメントと生成したスキーマで自分のバージョンを確認しながら使ってください。