{
  "markdown": "<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/xiaolai/codex-octopus/main/assets/codex-octopus.svg\" alt=\"Codex Octopus\" width=\"200\" />\n</p>\n\n# Codex Octopus\n\nOne brain, many arms.\n\nAn MCP server that wraps the [OpenAI Codex SDK](https://www.npmjs.com/package/@openai/codex-sdk), letting you run multiple specialized Codex agents — each with its own model, sandbox, effort, and personality — from any MCP client.\n\n## Why\n\nCodex is powerful. But one instance does everything the same way. Sometimes you want a **strict code reviewer** in read-only sandbox. A **test writer** with workspace-write access. A **cheap quick helper** on minimal effort. A **deep thinker** on xhigh.\n\nCodex Octopus lets you spin up as many of these as you need. Same binary, different configurations. Each one shows up as a separate tool in your MCP client.\n\n## Prerequisites\n\n- **Node.js** >= 18\n- **Codex CLI** — the [Codex SDK](https://www.npmjs.com/package/@openai/codex-sdk) spawns the Codex CLI under the hood, so you need it installed (`@openai/codex`)\n- **OpenAI API key** (`CODEX_API_KEY` env var) or inherited from parent process\n\n## Install\n\n```bash\nnpm install codex-octopus\n```\n\nOr use `npx` directly in your `.mcp.json` (see Quick Start below).\n\n## Quick Start\n\nAdd to your `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"codex\": {\n      \"command\": \"npx\",\n      \"args\": [\"codex-octopus@latest\"],\n      \"env\": {\n        \"CODEX_SANDBOX_MODE\": \"workspace-write\",\n        \"CODEX_APPROVAL_POLICY\": \"never\"\n      }\n    }\n  }\n}\n```\n\nThis gives you two tools: `codex` and `codex_reply`. That's it — you have Codex as a tool.\n\n## Multiple Agents\n\nThe real power is running several instances with different configurations:\n\n```json\n{\n  \"mcpServers\": {\n    \"code-reviewer\": {\n      \"command\": \"npx\",\n      \"args\": [\"codex-octopus@latest\"],\n      \"env\": {\n        \"CODEX_TOOL_NAME\": \"code_reviewer\",\n        \"CODEX_SERVER_NAME\": \"code-reviewer\",\n        \"CODEX_DESCRIPTION\": \"Strict code reviewer. Read-only sandbox.\",\n        \"CODEX_MODEL\": \"o3\",\n        \"CODEX_SANDBOX_MODE\": \"read-only\",\n        \"CODEX_APPEND_INSTRUCTIONS\": \"You are a strict code reviewer. Report real bugs, not style preferences.\",\n        \"CODEX_EFFORT\": \"high\"\n      }\n    },\n    \"test-writer\": {\n      \"command\": \"npx\",\n      \"args\": [\"codex-octopus@latest\"],\n      \"env\": {\n        \"CODEX_TOOL_NAME\": \"test_writer\",\n        \"CODEX_SERVER_NAME\": \"test-writer\",\n        \"CODEX_DESCRIPTION\": \"Writes thorough tests with edge case coverage.\",\n        \"CODEX_MODEL\": \"gpt-5-codex\",\n        \"CODEX_SANDBOX_MODE\": \"workspace-write\",\n        \"CODEX_APPEND_INSTRUCTIONS\": \"Write tests first. Cover edge cases. TDD.\"\n      }\n    },\n    \"quick-qa\": {\n      \"command\": \"npx\",\n      \"args\": [\"codex-octopus@latest\"],\n      \"env\": {\n        \"CODEX_TOOL_NAME\": \"quick_qa\",\n        \"CODEX_SERVER_NAME\": \"quick-qa\",\n        \"CODEX_DESCRIPTION\": \"Fast answers to quick coding questions.\",\n        \"CODEX_EFFORT\": \"minimal\"\n      }\n    }\n  }\n}\n```\n\nYour MCP client now sees three distinct tools — `code_reviewer`, `test_writer`, `quick_qa` — each purpose-built.\n\n## Agent Factory\n\nDon't want to write configs by hand? Add a factory instance:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-factory\": {\n      \"command\": \"npx\",\n      \"args\": [\"codex-octopus@latest\"],\n      \"env\": {\n        \"CODEX_FACTORY_ONLY\": \"true\",\n        \"CODEX_SERVER_NAME\": \"agent-factory\"\n      }\n    }\n  }\n}\n```\n\nThis exposes a single `create_codex_mcp` tool — an interactive wizard. Tell it what you want (\"a strict code reviewer with read-only sandbox\") and it generates the `.mcp.json` entry for you.\n\n## Tools\n\nEach non-factory instance exposes:\n\n| Tool           | Purpose                                                |\n| -------------- | ------------------------------------------------------ |\n| `<name>`       | Send a task to the agent, get a response + `thread_id` |\n| `<name>_reply` | Continue a previous conversation by `thread_id`        |\n\nPer-invocation parameters (override server defaults):\n\n| Parameter        | Description                                        |\n| ---------------- | -------------------------------------------------- |\n| `prompt`         | The task or question (required)                    |\n| `cwd`            | Working directory override                         |\n| `model`          | Model override                                     |\n| `additionalDirs` | Extra directories the agent can access             |\n| `effort`         | Reasoning effort (`minimal` to `xhigh`)            |\n| `sandboxMode`    | Sandbox override (can only tighten, never loosen)  |\n| `approvalPolicy` | Approval override (can only tighten, never loosen) |\n| `networkAccess`  | Enable network access from sandbox                 |\n| `webSearchMode`  | Web search: `disabled`, `cached`, `live`           |\n| `instructions`   | Additional instructions (prepended to prompt)      |\n\n## Configuration\n\nAll configuration is via environment variables in `.mcp.json`. Every env var is optional.\n\n### Identity\n\n| Env Var              | Description                                   | Default          |\n| -------------------- | --------------------------------------------- | ---------------- |\n| `CODEX_TOOL_NAME`    | Tool name prefix (`<name>` and `<name>_reply`) | `codex`         |\n| `CODEX_DESCRIPTION`  | Tool description shown to the host AI         | generic          |\n| `CODEX_SERVER_NAME`  | MCP server name in protocol handshake         | `codex-octopus`  |\n| `CODEX_FACTORY_ONLY` | Only expose the factory wizard tool           | `false`          |\n\n### Agent\n\n| Env Var                    | Description                                           | Default       |\n| -------------------------- | ----------------------------------------------------- | ------------- |\n| `CODEX_MODEL`              | Model (`gpt-5-codex`, `o3`, `codex-1`, etc.)         | SDK default   |\n| `CODEX_CWD`                | Working directory                                     | `process.cwd()` |\n| `CODEX_SANDBOX_MODE`       | `read-only`, `workspace-write`, `danger-full-access`  | `read-only`   |\n| `CODEX_APPROVAL_POLICY`    | `never`, `on-failure`, `on-request`, `untrusted`      | `on-failure`  |\n| `CODEX_EFFORT`             | `minimal`, `low`, `medium`, `high`, `xhigh`           | SDK default   |\n| `CODEX_ADDITIONAL_DIRS`    | Extra directories (comma-separated)                   | none          |\n| `CODEX_NETWORK_ACCESS`     | Allow network from sandbox                            | `false`       |\n| `CODEX_WEB_SEARCH`         | `disabled`, `cached`, `live`                          | `disabled`    |\n\n### Instructions\n\n| Env Var                      | Description                                              |\n| ---------------------------- | -------------------------------------------------------- |\n| `CODEX_INSTRUCTIONS`         | Replaces the default instructions                        |\n| `CODEX_APPEND_INSTRUCTIONS`  | Appended to the default (usually what you want)          |\n\n### Advanced\n\n| Env Var                | Description                                              |\n| ---------------------- | -------------------------------------------------------- |\n| `CODEX_PERSIST_SESSION`| `true`/`false` — enable session resume (default: `true`) |\n\n### Authentication\n\n| Env Var         | Description                    | Default               |\n| --------------- | ------------------------------ | --------------------- |\n| `CODEX_API_KEY` | OpenAI API key for this agent  | inherited from parent |\n\n## Security\n\n- **Sandbox defaults to `read-only`** — the agent can't write files unless you explicitly set `workspace-write` or `danger-full-access`.\n- **`cwd` overrides preserve agent knowledge** — when the host overrides `cwd`, the agent's configured base directory is automatically added to `additionalDirectories`.\n- **Security overrides narrow, never widen** — per-invocation `sandboxMode` and `approvalPolicy` can only tighten (e.g., `workspace-write` → `read-only`), never loosen.\n- **`_reply` tool respects persistence** — not registered when `CODEX_PERSIST_SESSION=false`.\n- **API keys are redacted** — the factory wizard never exposes `CODEX_API_KEY` in generated configs.\n\n## Architecture\n\n```\n┌─────────────────────────────────┐\n│  MCP Client                     │\n│  (Claude Desktop, Cursor, etc.) │\n│                                 │\n│  Sees: code_reviewer,           │\n│        test_writer, quick_qa    │\n└──────────┬──────────────────────┘\n           │ JSON-RPC / stdio\n┌──────────▼──────────────────────┐\n│  Codex Octopus (per instance)   │\n│                                 │\n│  Env: CODEX_MODEL=o3            │\n│       CODEX_SANDBOX_MODE=...    │\n│       CODEX_APPEND_INSTRUCTIONS │\n│                                 │\n│  Calls: Codex SDK thread.run()  │\n└──────────┬──────────────────────┘\n           │ in-process\n┌──────────▼──────────────────────┐\n│  Codex SDK → Codex CLI          │\n│  Runs autonomously: reads files,│\n│  writes code, runs commands     │\n│  Returns result + thread_id     │\n└─────────────────────────────────┘\n```\n\n## Known Limitations\n\n- **`minimal` effort + web_search**: OpenAI does not allow `web_search` tools with `minimal` reasoning effort. Use `low` or higher if web search is needed.\n\n## Development\n\n```bash\npnpm install\npnpm build       # compile TypeScript\npnpm test        # run tests (vitest)\npnpm test:coverage  # coverage report\n```\n\n## License\n\n[ISC](https://github.com/xiaolai/codex-octopus/blob/main/LICENSE) - Xiaolai Li\n",
  "bytes": 9532,
  "sha": "6dfb9f25184cc36541f30d50be1c9470b02e52a6e878f4514eab6418730a8a1a",
  "repo_slug": "xiaolai/codex-octopus",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_xiaolai_codex_octopus_59e6f50d/readme"
}