# codex-octopus MCP server

> Spawns multiple specialized Codex agents as independent MCP servers with custom models, sandboxes, and personalities.

- Repository: https://github.com/xiaolai/codex-octopus
- Page: https://hostedmcp.org/servers/xiaolai/codex-octopus
- Transport: stdio
- Stars: 20
- License: ISC
- Latest version: 1.0.1

## Install

### Claude Code

```sh
claude mcp add --env 'CODEX_API_KEY=<YOUR_CODEX_API_KEY>' codex-octopus -- npx -y codex-octopus
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "codex-octopus": {
      "command": "npx",
      "args": [
        "-y",
        "codex-octopus"
      ],
      "env": {
        "CODEX_API_KEY": "<YOUR_CODEX_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "codex-octopus": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "codex-octopus"
      ],
      "env": {
        "CODEX_API_KEY": "<YOUR_CODEX_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"codex-octopus","type":"stdio","command":"npx","args":["-y","codex-octopus"],"env":{"CODEX_API_KEY":"<YOUR_CODEX_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "codex-octopus": {
      "command": "npx",
      "args": [
        "-y",
        "codex-octopus"
      ],
      "env": {
        "CODEX_API_KEY": "<YOUR_CODEX_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add codex-octopus --env 'CODEX_API_KEY=<YOUR_CODEX_API_KEY>' -- npx -y codex-octopus
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.codex-octopus]
command = "npx"
args = ["-y", "codex-octopus"]

[mcp_servers.codex-octopus.env]
CODEX_API_KEY = "<YOUR_CODEX_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'CODEX_API_KEY=<YOUR_CODEX_API_KEY>' codex-octopus npx -- -y codex-octopus
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "codex-octopus": {
      "command": "npx",
      "args": [
        "-y",
        "codex-octopus"
      ],
      "env": {
        "CODEX_API_KEY": "<YOUR_CODEX_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `CODEX_API_KEY` | no | yes | OpenAI API key (leave unset to inherit from parent process) |
| `CODEX_APPEND_INSTRUCTIONS` | no | no | Additional instructions appended to the default |
| `CODEX_APPROVAL_POLICY` | no | no | Approval: never, on-failure, on-request, untrusted |
| `CODEX_DESCRIPTION` | no | no |  |
| `CODEX_EFFORT` | no | no |  |
| `CODEX_FACTORY_ONLY` | no | no | Set to true to expose only the factory wizard tool |
| `CODEX_MODEL` | no | no | Model: gpt-5-codex, o3, codex-1, or full ID |
| `CODEX_SANDBOX_MODE` | no | no | Sandbox: read-only, workspace-write, danger-full-access |
| `CODEX_SERVER_NAME` | no | no |  |
| `CODEX_TOOL_NAME` | no | no | Tool name prefix (default: codex) |

## Tools (2)

- `codex`: Send a task to an autonomous Codex agent. It reads/writes files, runs shell commands, searches codebases, and handles complex software engineering tasks end-to-end. Returns the result text plus a thread_id for follow-ups via codex_reply.
- `codex_reply`: Continue a previous codex conversation by thread ID. Use this for follow-up questions, iterative refinement, or multi-step workflows that build on prior context.

## FAQ

### How do I create multiple specialized agents?

You can run multiple instances of the server in your .mcp.json configuration, each with unique environment variables for model, sandbox mode, and instructions.

### Can I use an interactive wizard to generate configurations?

Yes, by enabling the agent-factory mode, you can use the create_codex_mcp tool to generate .mcp.json entries through an interactive wizard.

### Is the sandbox secure by default?

Yes, the sandbox defaults to read-only mode, meaning the agent cannot write files unless you explicitly change the configuration.
