Codex Octopus

Codex Octopus

1つの頭脳に、たくさんの腕。

OpenAI Codex SDKをラップするMCP サーバーです。モデル、サンドボックス、労力、個性がそれぞれ異なる複数の特化型Codexエージェントを、あらゆるMCPクライアントから実行できます。

その理由

Codexは強力です。しかし、1つのインスタンスではすべてを同じやり方で処理します。読み取り専用サンドボックスで動く厳格なコードレビュアーが必要なこともあります。ワークスペースへの書き込みアクセス権を持つテスト作成者が必要なこともあります。最小限の労力で動く低コストで手早いヘルパーや、xhighで動く深く考えるエージェントが必要なこともあります。

Codex Octopusを使えば、必要なだけインスタンスを起動できます。同じバイナリでも、設定はそれぞれ異なります。それぞれがMCPクライアント上で個別のツールとして表示されます。

前提条件

• Node.js >= 18
• Codex CLI — Codex SDKは内部でCodex CLIを起動するため、インストールが必要です（@openai/codex）
• OpenAI APIキー（CODEX_API_KEY環境変数）または親プロセスから継承したキー

インストール

npm install codex-octopus

または、.mcp.jsonでnpxを直接使用してください（下記のクイックスタートを参照）。

クイックスタート

.mcp.jsonに追加します。

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["codex-octopus@latest"],
      "env": {
        "CODEX_SANDBOX_MODE": "workspace-write",
        "CODEX_APPROVAL_POLICY": "never"
      }
    }
  }
}

これにより、codexとcodex_replyの2つのツールが利用可能になります。これだけで、Codexをツールとして使えます。

複数のエージェント

異なる設定のインスタンスを複数実行することで、真価を発揮します。

{
  "mcpServers": {
    "code-reviewer": {
      "command": "npx",
      "args": ["codex-octopus@latest"],
      "env": {
        "CODEX_TOOL_NAME": "code_reviewer",
        "CODEX_SERVER_NAME": "code-reviewer",
        "CODEX_DESCRIPTION": "Strict code reviewer. Read-only sandbox.",
        "CODEX_MODEL": "o3",
        "CODEX_SANDBOX_MODE": "read-only",
        "CODEX_APPEND_INSTRUCTIONS": "You are a strict code reviewer. Report real bugs, not style preferences.",
        "CODEX_EFFORT": "high"
      }
    },
    "test-writer": {
      "command": "npx",
      "args": ["codex-octopus@latest"],
      "env": {
        "CODEX_TOOL_NAME": "test_writer",
        "CODEX_SERVER_NAME": "test-writer",
        "CODEX_DESCRIPTION": "Writes thorough tests with edge case coverage.",
        "CODEX_MODEL": "gpt-5-codex",
        "CODEX_SANDBOX_MODE": "workspace-write",
        "CODEX_APPEND_INSTRUCTIONS": "Write tests first. Cover edge cases. TDD."
      }
    },
    "quick-qa": {
      "command": "npx",
      "args": ["codex-octopus@latest"],
      "env": {
        "CODEX_TOOL_NAME": "quick_qa",
        "CODEX_SERVER_NAME": "quick-qa",
        "CODEX_DESCRIPTION": "Fast answers to quick coding questions.",
        "CODEX_EFFORT": "minimal"
      }
    }
  }
}

MCPクライアントには、code_reviewer、test_writer、quick_qaという用途に特化した3つのツールが表示されます。

エージェントファクトリー

設定を手作業で書きたくない場合は、ファクトリーインスタンスを追加してください。

{
  "mcpServers": {
    "agent-factory": {
      "command": "npx",
      "args": ["codex-octopus@latest"],
      "env": {
        "CODEX_FACTORY_ONLY": "true",
        "CODEX_SERVER_NAME": "agent-factory"
      }
    }
  }
}

これにより、対話型ウィザードであるcreate_codex_mcpツールが1つ公開されます。「読み取り専用サンドボックスの厳格なコードレビュアー」のように希望を伝えると、.mcp.jsonのエントリーを自動で生成します。

ツール

ファクトリーではない各インスタンスは、次のツールを公開します。

ツール	用途
<name>	エージェントにタスクを送信し、応答とthread_idを取得します
<name>_reply	thread_idを指定して、前の会話を続けます

呼び出しごとのパラメーター（サーバーのデフォルト設定を上書きします）。

パラメーター	説明
prompt	タスクまたは質問（必須）
cwd	作業ディレクトリの上書き
model	モデルの上書き
additionalDirs	エージェントがアクセスできる追加ディレクトリ
effort	推論の労力（minimalからxhighまで）
sandboxMode	サンドボックスの上書き（制限の強化のみ可能。緩和はできません）
approvalPolicy	承認ポリシーの上書き（制限の強化のみ可能。緩和はできません）
networkAccess	サンドボックスからのネットワークアクセスを有効にする
webSearchMode	ウェブ検索：disabled、cached、live
instructions	追加の指示（プロンプトの先頭に追加されます）

設定

設定はすべて.mcp.jsonの環境変数で行います。すべての環境変数は省略可能です。

識別情報

環境変数	説明	デフォルト
CODEX_TOOL_NAME	ツール名のプレフィックス（<name>と<name>_reply）	codex
CODEX_DESCRIPTION	ホストAIに表示されるツールの説明	汎用
CODEX_SERVER_NAME	プロトコルのハンドシェイクで使用するMCPサーバー名	codex-octopus
CODEX_FACTORY_ONLY	ファクトリーウィザードツールのみを公開する	false

エージェント

環境変数	説明	デフォルト
CODEX_MODEL	モデル（gpt-5-codex、o3、codex-1など）	SDK のデフォルト
CODEX_CWD	作業ディレクトリ	process.cwd()
CODEX_SANDBOX_MODE	read-only、workspace-write、danger-full-access	read-only
CODEX_APPROVAL_POLICY	never、on-failure、on-request、untrusted	on-failure
CODEX_EFFORT	minimal、low、medium、high、xhigh	SDK のデフォルト
CODEX_ADDITIONAL_DIRS	追加ディレクトリ（カンマ区切り）	なし
CODEX_NETWORK_ACCESS	サンドボックスからのネットワークアクセスを許可	false
CODEX_WEB_SEARCH	disabled、cached、live	disabled

指示

環境変数	説明
CODEX_INSTRUCTIONS	デフォルトの指示を置き換えます
CODEX_APPEND_INSTRUCTIONS	デフォルトの指示に追加します（通常はこちらを使用します）

詳細設定

環境変数	説明
CODEX_PERSIST_SESSION	true／false — セッションの再開を有効にします（デフォルト：true）

認証

環境変数	説明	デフォルト
CODEX_API_KEY	このエージェント用の OpenAI API キー	親から継承

セキュリティ

• サンドボックスのデフォルトは read-only です — workspace-write または danger-full-access を明示的に設定しない限り、エージェントはファイルを書き込めません。
• cwd の上書き時もエージェントの知識は維持されます — ホストが cwd を上書きすると、エージェントに設定されたベースディレクトリが自動的に additionalDirectories に追加されます。
• セキュリティ設定の上書きは制限を強めるだけで、緩めることはありません — 呼び出しごとの sandboxMode と approvalPolicy は、制限を強めること（例：workspace-write → read-only）のみ可能で、緩めることはできません。
• _reply ツールは永続化設定に従います — CODEX_PERSIST_SESSION=false の場合は登録されません。
• API キーはマスキングされます — ファクトリーウィザードで生成される設定に CODEX_API_KEY が露出することはありません。

アーキテクチャ

┌─────────────────────────────────┐
│  MCP Client                     │
│  (Claude Desktop, Cursor, etc.) │
│                                 │
│  Sees: code_reviewer,           │
│        test_writer, quick_qa    │
└──────────┬──────────────────────┘
           │ JSON-RPC / stdio
┌──────────▼──────────────────────┐
│  Codex Octopus (per instance)   │
│                                 │
│  Env: CODEX_MODEL=o3            │
│       CODEX_SANDBOX_MODE=...    │
│       CODEX_APPEND_INSTRUCTIONS │
│                                 │
│  Calls: Codex SDK thread.run()  │
└──────────┬──────────────────────┘
           │ in-process
┌──────────▼──────────────────────┐
│  Codex SDK → Codex CLI          │
│  Runs autonomously: reads files,│
│  writes code, runs commands     │
│  Returns result + thread_id     │
└─────────────────────────────────┘

既知の制限事項

• minimal の推論レベルと web_search の併用：OpenAI では、推論レベルが minimal の場合、web_search ツールを使用できません。ウェブ検索が必要な場合は、low 以上を使用してください。

開発

pnpm install
pnpm build       # compile TypeScript
pnpm test        # run tests (vitest)
pnpm test:coverage  # coverage report

ライセンス

ISC - Xiaolai Li