# codex-octopus

Runs several separately configured Codex agents through MCP. Use it to split code review, test writing, and quick coding tasks.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 20
- Author: xiaolai
- License: ISC · policy=link-only · description only; the file stays with the author
- Source: https://github.com/xiaolai/codex-octopus
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/codex-octopus

## What it does

codex-octopus exposes the OpenAI Codex SDK through an MCP server. Each server instance can have its own model, sandbox setting, reasoning effort, working directory, and extra instructions. An MCP client sees those instances as separate tools.

Configuration lives in environment variables inside `.mcp.json`. You can give one agent read-only access for review and another workspace-write access for tests. A factory mode provides the `create_codex_mcp` tool, which builds an MCP configuration entry from a requested agent setup. Calls can also override the directory, model, extra directories, network access, and web search mode.

The setup needs Node.js 18 or newer, the Codex CLI provided through `@openai/codex`, and an OpenAI key in `CODEX_API_KEY` or inherited from the parent process. Without Node.js 18 or newer, the server will not start.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `CODEX_API_KEY`, `CODEX_TOOL_NAME`, `CODEX_MODEL`, `CODEX_SANDBOX_MODE`, `CODEX_APPROVAL_POLICY`, `CODEX_APPEND_INSTRUCTIONS`, `CODEX_FACTORY_ONLY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env CODEX_API_KEY=<CODEX_API_KEY> --env CODEX_TOOL_NAME=<CODEX_TOOL_NAME> --env CODEX_MODEL=<CODEX_MODEL> --env CODEX_SANDBOX_MODE=<CODEX_SANDBOX_MODE> --env CODEX_APPROVAL_POLICY=<CODEX_APPROVAL_POLICY> --transport stdio codex-octopus -- npx -y codex-octopus
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add codex-octopus --env CODEX_API_KEY=<CODEX_API_KEY> --env CODEX_TOOL_NAME=<CODEX_TOOL_NAME> --env CODEX_MODEL=<CODEX_MODEL> --env CODEX_SANDBOX_MODE=<CODEX_SANDBOX_MODE> --env CODEX_APPROVAL_POLICY=<CODEX_APPROVAL_POLICY> -- npx -y codex-octopus
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "codex-octopus": {
            "command": "npx",
            "args": [
                "-y",
                "codex-octopus"
            ],
            "env": {
                "CODEX_API_KEY": "<CODEX_API_KEY>",
                "CODEX_TOOL_NAME": "<CODEX_TOOL_NAME>",
                "CODEX_MODEL": "<CODEX_MODEL>",
                "CODEX_SANDBOX_MODE": "<CODEX_SANDBOX_MODE>",
                "CODEX_APPROVAL_POLICY": "<CODEX_APPROVAL_POLICY>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "codex-octopus": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "codex-octopus"
            ],
            "env": {
                "CODEX_API_KEY": "<CODEX_API_KEY>",
                "CODEX_TOOL_NAME": "<CODEX_TOOL_NAME>",
                "CODEX_MODEL": "<CODEX_MODEL>",
                "CODEX_SANDBOX_MODE": "<CODEX_SANDBOX_MODE>",
                "CODEX_APPROVAL_POLICY": "<CODEX_APPROVAL_POLICY>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e CODEX_API_KEY=<CODEX_API_KEY> -e CODEX_TOOL_NAME=<CODEX_TOOL_NAME> -e CODEX_MODEL=<CODEX_MODEL> -e CODEX_SANDBOX_MODE=<CODEX_SANDBOX_MODE> -e CODEX_APPROVAL_POLICY=<CODEX_APPROVAL_POLICY> codex-octopus npx -y codex-octopus
```
Replace <…> with your own values. 2 more environment variables are in the server README

## When to use it
- split code review and test writing across separate agents
- assign different models and reasoning effort to each agent
- keep a reviewer inside a `read-only` sandbox
- give an agent access to extra project directories
- generate an MCP entry with the factory tool

## Example prompts
- Ask the configured Codex tool to inspect this module and report concrete bugs, not style preferences.
- Have the test-focused agent write coverage for this code, including edge cases, with workspace write access.
- Use `create_codex_mcp` to generate a read-only code review agent configuration.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md