Codex As Mcp

codex-as-mcp

中文版

codex-as-mcp は、MCP クライアント（Claude Code、Cursor など）から Codex CLI に作業を委任できる、小規模な Model Context Protocol (MCP) サーバーです。

サーバーの現在の作業ディレクトリで Codex を実行する 2 つのツールを公開します。

• spawn_agent(prompt: str)
• spawn_agents_parallel(agents: list[dict])

内部では、各エージェントが次のようなコマンドを実行します。 codex exec --cd <server cwd> --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox -.

プロンプトは stdin 経由で送信され、その後 stdin は閉じられます。これにより、コマンドラインでの引用符や長さに関する問題を回避し、Codex が MCP サーバーの JSON-RPC stdin パイプから誤って読み込むことを防ぎます。

注：--dangerously-bypass-approvals-and-sandbox はサンドボックスと確認プロンプトを無効にします。このサーバーは信頼できるリポジトリでのみ使用してください。

Claude Code で使用する

codex-as-mcp には 2 つのツールがあります。

プロンプトを使って、Codex のサブエージェントを並列で起動できます。

以下は、2 つのタスクを並列で委任する Codex セッションの例です。

クイックスタート

1. Codex CLI をインストールする

Codex CLI >= 0.46.0 が必要です

npm install -g @openai/codex@latest
codex login

# Verify installation
codex --version

Codex CLI がマシン上で非対話モードで実行できることを確認してください（~/.codex/config.toml にプロバイダーと認証情報を設定するか、参照先のプロバイダー固有の環境変数を設定します）。

例：サードパーティプロバイダーと env_key

サードパーティプロバイダーを使用する場合は、Codex の config.toml で設定し、model_provider でそのプロバイダーを指定します。プロバイダーが env_key を使用する場合、Codex CLI の実行時にその環境変数が設定されている必要があります。

例：

model_provider = "custom_provider"

[model_providers.custom_provider]
name = "custom_provider"
base_url = "https://..."
wire_api = "responses"
env_key = "PROVIDER_API_KEY"
show_raw_agent_reasoning = true

codex-as-mcp を使用するときは、MCP サーバープロセスにその環境変数が設定され、起動された codex プロセスに引き継がれるようにしてください。環境変数名は、上記の env_key の値と一致する必要があります（ここでは PROVIDER_API_KEY）。

オプション A（推奨）：MCP クライアントの設定で環境変数を設定する（対応している場合）

{
  "mcpServers": {
    "codex-subagent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-as-mcp@latest"],
      "env": {
        "PROVIDER_API_KEY": "KEY_VALUE"
      }
    }
  }
}

オプション B：サーバー引数経由で環境変数を渡す

uvx codex-as-mcp@latest --env PROVIDER_API_KEY=KEY_VALUE

オプション C：Codex CLI 経由で追加する（codex mcp add）

codex mcp add codex-subagent --env PROVIDER_API_KEY=KEY_VALUE -- uvx codex-as-mcp@latest

セキュリティに関する注意：コマンドライン引数でシークレットを渡すと、マシン上のプロセス一覧から見える可能性があります。可能であればオプション A を優先してください。

2. MCP を設定する

.mcp.json に追加します。

{
  "mcpServers": {
    "codex-subagent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-as-mcp@latest"]
    }
  }
}

または Claude Desktop のコマンドを使用します。

claude mcp add codex-subagent -- uvx codex-as-mcp@latest

Codex CLI を直接設定する場合（たとえば ~/.config/codex/config.toml）、次を追加します。

[mcp_servers.subagents]
transport = "stdio"
command = "uvx"
args = ["codex-as-mcp@latest"]
# Increase if you see ~60s tool-call timeouts when running longer Codex tasks.
# tool_timeout_sec = 600

ツール

• spawn_agent(prompt: str) – サーバーの作業ディレクトリを使用して、自律型の Codex サブエージェントを起動し、そのエージェントの最終メッセージを返します。
• spawn_agents_parallel(agents: list[dict]) – 複数の Codex サブエージェントを並列で起動します。各項目には prompt キーが必要で、結果には各エージェントの output または error が含まれます。

メンテナー向けのライブスモークテスト

デフォルトの CI では、認証情報なしで安全に実行できるよう、ユニットテストと偽のサブプロセス経路を使用します。メンテナーは、リポジトリのシークレット CODEX_LIVE_API_KEY を設定し、Responses 互換の base_url／model をワークフロー入力に指定することで、実際のプロバイダーを使用した手動実行の Live Codex smoke GitHub Actions ワークフローも実行できます。

注：現在の Codex CLI は wire_api = "chat" を拒否します。直接の DeepSeek API のような Chat Completions のみを提供するプロバイダーでは、その wire API に対する Codex のネイティブサポートか、Responses 互換プロキシが必要です。

トラブルシューティング

spawn_agent が約 60 秒後にタイムアウトする

次のようなエラーが表示される場合：

tool call failed for `subagents/spawn_agent`
timed out awaiting tools/call after 60s
deadline has elapsed

通常、これはクライアント側の MCP ツール呼び出しのタイムアウトです。spawn_agent は起動した codex exec プロセスが終了するまで戻らないため、60 秒以上かかることがあります。

対処法：MCP クライアントでツール呼び出しのタイムアウトを延長してください。

Codex CLI

Codex の設定（~/.codex/config.toml または ~/.config/codex/config.toml）で、MCP サーバーの tool_timeout_sec をより大きな値に設定します。

[mcp_servers.subagents]
transport = "stdio"
command = "uvx"
args = ["codex-as-mcp@latest"]
tool_timeout_sec = 600

MCP Inspector／mcp dev

MCP Inspector を使ってローカルでテストする場合は、リクエストのタイムアウトを延長してください（または、これらの値をエクスポートする ./test.sh を実行します）。

export MCP_SERVER_REQUEST_TIMEOUT=300000
export MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=true
export MCP_REQUEST_MAX_TOTAL_TIMEOUT=28800000