Codex app serverとは？できること・起動方法・MCPとの違いを解説

「codex app-serverというコマンドを見かけたが、何のことか分からない」「Codexのドキュメントに、MCPサーバーの代わりにapp serverを使うと書いてあった」と戸惑っている方は多いのではないでしょうか。

Codex app serverは、Codexを自分で作ったアプリや社内ツールの中から操作するための接続口です。公式ドキュメントでは、Codexが自社のリッチなクライアント（たとえばVS Code拡張機能）を動かすために使っているインターフェースで、認証、会話履歴、承認、エージェントの動きのリアルタイム配信を扱えると説明されています。

この記事では、app serverの仕組み、できること、起動方法と最初の通信の流れ、別のマシンからの接続、認証と承認の注意点、MCPサーバーやSDKとの違いまでを順に解説します。内容は2026年10月時点のOpenAI公式ドキュメントにもとづいています。app serverは実験的な機能で、仕様が変わることがあるので、実際に組み込む前には公式ページもあわせて確認してください。

Codex app serverとは

app server（codex app-server）は、Codexを裏側で動かすための「受け口」となるプログラムです。自作のアプリがこの受け口にメッセージを送ると、Codexが作業を進め、その経過と結果が順次返ってきます。やりとりには、MCPと同じくJSON-RPC 2.0という形式のメッセージが使われます。

実装はオープンソースで、GitHubのCodexのリポジトリ（openai/codexのcodex-rs/app-server）で公開されています。

3つの基本単位

app serverでは、やりとりを次の3つの単位で扱います。この3つが分かれば、ドキュメントの大半が読めるようになります。

アプリ側は、スレッドを作り、ターンを開始し、流れてくるアイテムの通知を読んで画面に表示する、という流れで使います。

誰が使うものか

結論から言うと、Codexを使うだけの人は、app serverを意識する必要はありません。CLIやアプリ、IDE拡張機能からふつうに使っていれば、裏側の仕組みとして動いているだけです。

できること

公式ドキュメントのAPI一覧から、業務に置き換えて分かりやすいものを抜き出すと、次のようになります。メソッド名は代表的なものだけを載せています。

ほかにも、スキルの呼び出し、アプリ（コネクタ）の一覧、ファイルの変更監視、ChatGPTの利用上限の取得などが用意されています。メソッドの全一覧は、公式ドキュメントの「API overview」にあります。

通信の方式

app serverには、クライアントとの接続方式がいくつかあります。--listenオプションで切り替えます。

起動して動かす

ここでは、手元のマシンでapp serverを起動して、最初の依頼を送るまでの流れを説明します。CLIが入っていることが前提です。入れ方は「Codex CLIのインストール」の記事で解説しています。

1. app serverを起動するターミナルでcodex app-serverを実行します。何も指定しなければ標準入出力で待ち受けます。ネットワーク越しにつなぐなら--listen ws://127.0.0.1:4500のように指定します。
2. 初期化する接続したら、最初にinitializeリクエストを送り、続けてinitialized通知を送ります。clientInfoに自分のアプリの名前とバージョンを入れます。この手順より前に送ったリクエストはNot initializedエラーになります。
3. スレッドを作るthread/startで新しい会話を作ります。返ってくるthread.idを、以降のリクエストで使います。
4. ターンを開始するturn/startにスレッドIDと入力（テキストなど）を渡します。依頼ごとに、作業フォルダや承認ポリシー、サンドボックスの設定を上書きできます。
5. 通知を読み続ける作業の経過はitem/started、item/agentMessage/delta、item/completedなどの通知として流れてきます。turn/completedが来たら、そのターンは終了です。

公式ドキュメントにある、メッセージの形の例を紹介します。リクエストにはmethod、params、idがあり、通知にはidがありません。

{ "method": "initialize", "id": 0, "params": { "clientInfo": { "name": "my_product", "title": "My Product", "version": "0.1.0" } } }
{ "method": "initialized", "params": {} }
{ "method": "thread/start", "id": 1, "params": {} }
{ "method": "turn/start", "id": 2, "params": { "threadId": "thr_123", "input": [ { "type": "text", "text": "Summarize this repo." } ] } }

上の例は、公式の例をもとに、モデル名の指定を省いたものです。公式の例にはモデル名の指定がありますが、使えるモデルはアカウントやワークスペースによって異なるため、model/listで確認するよう案内されています。省略した場合は、設定済みの既定のモデルが使われます。

型定義を生成する

自分のアプリをTypeScriptなどで書く場合は、使っているCodexのバージョンに合った型定義を、CLIから生成できます。

codex app-server generate-ts --out ./schemas
codex app-server generate-json-schema --out ./schemas

出力はCodexのバージョンごとに固有なので、アップデートしたら作り直します。実験的なメソッドも含めたい場合は--experimentalを付けます。

実験的なAPIは明示的に有効にする

一部のメソッドや項目は、initializeのときにcapabilities.experimentalApiをtrueにしないと使えません。有効にせずに使うと、「requires experimentalApi capability」というエラーで拒否されます。安定したAPIだけで作りたい場合は、この指定を入れないままにします。

別のマシンから接続する

app serverには、Codexのターミナル画面（TUI）を別のマシンのapp serverにつなぐ使い方もあります。たとえば、社内のサーバーでCodexを動かしておき、手元のPCから操作する、といった形です。

1. 接続を受け付ける側で起動するcodex app-server --listen ws://127.0.0.1:4500を実行します。
2. 操作する側で接続する別のターミナルでcodex --remote ws://127.0.0.1:4500を実行します。

--remoteには、ws://、wss://、unix://、unix://パスの指定ができます。

ネットワーク越しにつなぐときの認証

ローカル以外から接続を受け付ける場合は、WebSocketの認証を設定し、TLS（wss://）で暗号化された接続の内側に置くよう案内されています。使えるオプションは次のとおりです。

公式は、トークンをコマンドラインに直接書くのではなく、ファイルや環境変数を使うことを勧めています。接続側の例は次のとおりです。

export CODEX_REMOTE_TOKEN="$(cat "$HOME/.codex/app-server-token")"
codex --remote wss://remote-host:4500 --remote-auth-token-env CODEX_REMOTE_TOKEN

WebSocketで待ち受けているときは、同じポートで簡易の死活確認も使えます。GET /readyzは接続を受け付けられる状態になると200を返し、GET /healthzはOriginヘッダーのないリクエストに200を返します。Originヘッダー付きのリクエストは403で拒否されます。

なお、codex remote-controlというコマンドもありますが、公式ではこれは管理されたバックグラウンドのサーバーを使うリモート操作用で、自作のプロトコルクライアントを作るときのcodex app-server --listenの代わりにはならないと説明されています。

認証・承認・安全面

Codexはファイルを書き換え、コマンドを実行します。自作のアプリに組み込むときは、承認の確認を画面に出す責任がアプリ側にある点に注意が必要です。

承認の仕組み

Codexの設定によっては、コマンドの実行やファイルの変更に承認が必要になります。そのときapp serverは、クライアントに向けて承認を求めるリクエストを送ります。クライアントは、次のような判断を返します。

承認の要求には、どのコマンドをどのフォルダで実行しようとしているかの情報が付いてきます。アプリ側では、これを利用者に分かる形で表示し、判断を受け付ける画面を用意することになります。ネットワークへのアクセスを求める承認では、接続先のホストとプロトコルが示されます。

そのほか、MCPサーバーが利用者に入力を求める「エリシテーション」や、追加の権限を求めるリクエストも、同じようにクライアントが応答します。副作用のあるアプリ（コネクタ）のツール呼び出しでも承認が求められることがあり、破壊的な操作を示すツールには、常に承認が求められると公式に書かれています。

サンドボックスと、注意が必要な操作

依頼（turn/start）ごとに、approvalPolicy（承認のポリシー）とsandboxPolicy（サンドボックスの設定）を指定できます。たとえばworkspaceWriteは、指定した作業フォルダの中への書き込みを許す設定です。

一方で、次のような操作はサンドボックスの外で動くと公式に書かれています。組み込むアプリで公開する範囲は慎重に決めてください。

認証の方式

app serverが扱う認証の方式は、次のとおりです。account/readで、いまの方式とアカウントの情報を確認できます。

また、企業で使う新しい連携を作る場合は、initializeのclientInfo.nameで自分のクライアントを識別します。OpenAIのコンプライアンスログで使われる名前で、企業向けに作る場合はOpenAIに連絡して既知のクライアントとして登録してもらうよう案内されています。

管理者が設定した要件は、configRequirements/readで確認できます。requirements.tomlやMDM（端末管理）から読み込まれた、実際に有効な制限が返ってきます。

mcp-server・SDKとの違い

app serverに近い名前や役割のものがいくつかあるので、違いを整理します。

codex mcp-serverは削除された

以前は、Codex自体をMCPサーバーとして動かすcodex mcp-serverというコマンドがありました。現在は、このコマンドとスタンドアロンのcodex-mcp-serverは削除されています。これらを起動する連携を作っている場合は、Codexをアップデートする前に移行する必要があります。

移行先がapp serverですが、公式は、app serverはMCPサーバーではなく、MCPクライアントの置き換えとしてそのまま使えるものでもないと説明しています。独自のJSON-RPCプロトコルを使うため、MCPのツール呼び出しではなく、app serverのプロトコルを使うように連携を作り直す必要があります。

どれを選ぶか

SDKとapp serverの関係についても補足します。公式によると、Python SDKはローカルのCodex app-serverをJSON-RPCで制御する仕組みで、公開されているSDKにはバージョンを固定したCodex CLIが同梱されます。つまり、Pythonから使う場合は、SDKがapp serverの起動と通信を代わりに行ってくれます。自分でプロトコルを組み立てる必要がなければ、SDKの方が手間は少なくて済みます。

うまくいかないとき

公式ドキュメントに載っているエラーを、症状ごとに整理しました。

プロトコルの動きを手元で確かめたいときは、codex debug app-server send-message-v2というデバッグ用のコマンドが使えます。内蔵のテスト用クライアントで、スレッドの作成からターンの送信、通知の受信までを実行して表示します。

よくある質問

まとめ

app serverは、Codexを自社の画面や業務の流れに組み込むための部品です。ただし実験的な機能で、承認や認証の設計を誤ると、意図しない操作や情報の持ち出しにつながります。SDKで足りるのか、app serverまで必要なのかは、作りたいものによって変わります。

INTERCREATE JAPANでは、Claude CodeやCodexの導入から、社内ツールづくり、運用のルール決めまでをお手伝いしています。社内の業務にCodexを組み込む前に、どの方法が合うかを整理したい場合はご相談ください。