Codex Octopus

Spawn multiple specialized Codex agents as MCP servers, each independently configured.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "codex-octopus": {
      "command": "npx",
      "args": [
        "-y",
        "codex-octopus"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Codex Octopus

One brain, many arms.

An MCP server that wraps the OpenAI Codex SDK, letting you run multiple specialized Codex agents — each with its own model, sandbox, effort, and personality — from any MCP client.

Why

Codex 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.

Codex 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.

Prerequisites

Node.js >= 18
Codex CLI — the Codex SDK spawns the Codex CLI under the hood, so you need it installed (@openai/codex)
OpenAI API key (CODEX_API_KEY env var) or inherited from parent process

Install

Terminal

npm install codex-octopus

Or use npx directly in your .mcp.json (see Quick Start below).

Quick Start

Add to your .mcp.json:

config.json

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

This gives you two tools: codex and codex_reply. That's it — you have Codex as a tool.

Multiple Agents

The real power is running several instances with different configurations:

config.json

{
  "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"
      }
    }
  }
}

Your MCP client now sees three distinct tools — code_reviewer, test_writer, quick_qa — each purpose-built.

Agent Factory

Don't want to write configs by hand? Add a factory instance:

config.json

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

This 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.

Tools

Each non-factory instance exposes:

Tool	Purpose
`<name>`	Send a task to the agent, get a response + `thread_id`
`<name>_reply`	Continue a previous conversation by `thread_id`

Per-invocation parameters (override server defaults):

Parameter	Description
`prompt`	The task or question (required)
`cwd`	Working directory override
`model`	Model override
`additionalDirs`	Extra directories the agent can access
`effort`	Reasoning effort (`minimal` to `xhigh`)
`sandboxMode`	Sandbox override (can only tighten, never loosen)
`approvalPolicy`	Approval override (can only tighten, never loosen)
`networkAccess`	Enable network access from sandbox
`webSearchMode`	Web search: `disabled`, `cached`, `live`
`instructions`	Additional instructions (prepended to prompt)

Configuration

All configuration is via environment variables in .mcp.json. Every env var is optional.

Identity

Env Var	Description	Default
`CODEX_TOOL_NAME`	Tool name prefix (`<name>` and `<name>_reply`)	`codex`
`CODEX_DESCRIPTION`	Tool description shown to the host AI	generic
`CODEX_SERVER_NAME`	MCP server name in protocol handshake	`codex-octopus`
`CODEX_FACTORY_ONLY`	Only expose the factory wizard tool	`false`

Agent

Env Var	Description	Default
`CODEX_MODEL`	Model (`gpt-5-codex`, `o3`, `codex-1`, etc.)	SDK default
`CODEX_CWD`	Working directory	`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 default
`CODEX_ADDITIONAL_DIRS`	Extra directories (comma-separated)	none
`CODEX_NETWORK_ACCESS`	Allow network from sandbox	`false`
`CODEX_WEB_SEARCH`	`disabled`, `cached`, `live`	`disabled`

Instructions

Env Var	Description
`CODEX_INSTRUCTIONS`	Replaces the default instructions
`CODEX_APPEND_INSTRUCTIONS`	Appended to the default (usually what you want)

Advanced

Env Var	Description
`CODEX_PERSIST_SESSION`	`true`/`false` — enable session resume (default: `true`)

Authentication

Env Var	Description	Default
`CODEX_API_KEY`	OpenAI API key for this agent	inherited from parent

Security

Sandbox defaults to read-only — the agent can't write files unless you explicitly set workspace-write or danger-full-access.
cwd overrides preserve agent knowledge — when the host overrides cwd, the agent's configured base directory is automatically added to additionalDirectories.
Security overrides narrow, never widen — per-invocation sandboxMode and approvalPolicy can only tighten (e.g., workspace-write → read-only), never loosen.
_reply tool respects persistence — not registered when CODEX_PERSIST_SESSION=false.
API keys are redacted — the factory wizard never exposes CODEX_API_KEY in generated configs.

Architecture

Code

┌─────────────────────────────────┐
│  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     │
└─────────────────────────────────┘

Known Limitations

minimal effort + web_search: OpenAI does not allow web_search tools with minimal reasoning effort. Use low or higher if web search is needed.

Development

bash

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

License

ISC - Xiaolai Li

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Codex Octopus

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "codex-octopus": { "command": "npx", "args": ["-y", "codex-octopus"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/codex-octopus?style=directory)](https://allmcps.com/mcp/codex-octopus)

HTML Embed

<a href="https://allmcps.com/mcp/codex-octopus"><img src="https://allmcps.com/api/badge/codex-octopus?style=directory" alt="Codex Octopus on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Codex Octopus →Install in Claude Desktop Install in Cursor Install in VS Code

Codex Octopus

Spawn multiple specialized Codex agents as MCP servers, each independently configured.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "codex-octopus": {
      "command": "npx",
      "args": [
        "-y",
        "codex-octopus"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Codex Octopus

One brain, many arms.

An MCP server that wraps the OpenAI Codex SDK, letting you run multiple specialized Codex agents — each with its own model, sandbox, effort, and personality — from any MCP client.

Why

Codex 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.

Prerequisites

Node.js >= 18
Codex CLI — the Codex SDK spawns the Codex CLI under the hood, so you need it installed (@openai/codex)
OpenAI API key (CODEX_API_KEY env var) or inherited from parent process

Install

Terminal

npm install codex-octopus

Or use npx directly in your .mcp.json (see Quick Start below).

Quick Start

Add to your .mcp.json:

config.json

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

This gives you two tools: codex and codex_reply. That's it — you have Codex as a tool.

Multiple Agents

The real power is running several instances with different configurations:

config.json

{
  "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"
      }
    }
  }
}

Your MCP client now sees three distinct tools — code_reviewer, test_writer, quick_qa — each purpose-built.

Agent Factory

Don't want to write configs by hand? Add a factory instance:

config.json

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

This 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.

Tools

Each non-factory instance exposes:

Tool	Purpose
`<name>`	Send a task to the agent, get a response + `thread_id`
`<name>_reply`	Continue a previous conversation by `thread_id`

Per-invocation parameters (override server defaults):

Parameter	Description
`prompt`	The task or question (required)
`cwd`	Working directory override
`model`	Model override
`additionalDirs`	Extra directories the agent can access
`effort`	Reasoning effort (`minimal` to `xhigh`)
`sandboxMode`	Sandbox override (can only tighten, never loosen)
`approvalPolicy`	Approval override (can only tighten, never loosen)
`networkAccess`	Enable network access from sandbox
`webSearchMode`	Web search: `disabled`, `cached`, `live`
`instructions`	Additional instructions (prepended to prompt)

Configuration

All configuration is via environment variables in .mcp.json. Every env var is optional.

Identity

Env Var	Description	Default
`CODEX_TOOL_NAME`	Tool name prefix (`<name>` and `<name>_reply`)	`codex`
`CODEX_DESCRIPTION`	Tool description shown to the host AI	generic
`CODEX_SERVER_NAME`	MCP server name in protocol handshake	`codex-octopus`
`CODEX_FACTORY_ONLY`	Only expose the factory wizard tool	`false`

Agent

Env Var	Description	Default
`CODEX_MODEL`	Model (`gpt-5-codex`, `o3`, `codex-1`, etc.)	SDK default
`CODEX_CWD`	Working directory	`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 default
`CODEX_ADDITIONAL_DIRS`	Extra directories (comma-separated)	none
`CODEX_NETWORK_ACCESS`	Allow network from sandbox	`false`
`CODEX_WEB_SEARCH`	`disabled`, `cached`, `live`	`disabled`

Instructions

Env Var	Description
`CODEX_INSTRUCTIONS`	Replaces the default instructions
`CODEX_APPEND_INSTRUCTIONS`	Appended to the default (usually what you want)

Advanced

Env Var	Description
`CODEX_PERSIST_SESSION`	`true`/`false` — enable session resume (default: `true`)

Authentication

Env Var	Description	Default
`CODEX_API_KEY`	OpenAI API key for this agent	inherited from parent

Security

Sandbox defaults to read-only — the agent can't write files unless you explicitly set workspace-write or danger-full-access.
cwd overrides preserve agent knowledge — when the host overrides cwd, the agent's configured base directory is automatically added to additionalDirectories.
Security overrides narrow, never widen — per-invocation sandboxMode and approvalPolicy can only tighten (e.g., workspace-write → read-only), never loosen.
_reply tool respects persistence — not registered when CODEX_PERSIST_SESSION=false.
API keys are redacted — the factory wizard never exposes CODEX_API_KEY in generated configs.

Architecture

Code

┌─────────────────────────────────┐
│  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     │
└─────────────────────────────────┘

Known Limitations

minimal effort + web_search: OpenAI does not allow web_search tools with minimal reasoning effort. Use low or higher if web search is needed.

Development

bash

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

License

ISC - Xiaolai Li

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Codex Octopus

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "codex-octopus": { "command": "npx", "args": ["-y", "codex-octopus"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/codex-octopus?style=directory)](https://allmcps.com/mcp/codex-octopus)

HTML Embed

<a href="https://allmcps.com/mcp/codex-octopus"><img src="https://allmcps.com/api/badge/codex-octopus?style=directory" alt="Codex Octopus on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Codex Octopus →Install in Claude Desktop Install in Cursor Install in VS Code