# codex-octopus [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/xiaolai/codex-octopus  
**GitHub Stars:** 20  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/codex-octopus

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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "codex-octopus": {
    "command": "npx",
    "args": ["codex-octopus@latest"],
    "env": {
      "CODEX_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `CODEX_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What codex-octopus MCP server does

The codex-octopus MCP server turns the OpenAI Codex SDK into an MCP interface. A standard instance exposes a task tool and a reply tool, with names derived from `CODEX_TOOL_NAME`. The task tool sends a prompt to a Codex agent and returns its response together with a `thread_id`; the reply tool continues an existing conversation by using that identifier.

Each server process represents one agent configuration. Running multiple processes lets an MCP client see separate tools such as a read-only reviewer, a test-writing agent, and a lower-effort coding assistant. Their models, permissions, instructions, and descriptions can differ.

## How it works

MCP clients communicate with each instance over JSON-RPC using stdio. Codex Octopus passes requests to the Codex SDK, which starts the Codex CLI and runs the configured agent. The client can provide a working directory, model, reasoning effort, additional directories, sandbox mode, approval policy, network access, web-search mode, and extra instructions for an individual invocation.

Server-level settings establish defaults. Per-invocation security settings can only make access more restrictive: a request may tighten the sandbox or approval policy, but cannot loosen the configured limits. Session persistence controls whether the reply tool is available for continuing conversations.

## Setup and configuration

Install the package with npm or run it through `npx` in an MCP configuration. Node.js 18 or newer, the Codex CLI, and an OpenAI API key are prerequisites. The key is supplied through `CODEX_API_KEY` or inherited from the parent process.

The codex-octopus MCP server is configured with environment variables in `.mcp.json`. Useful identity settings include `CODEX_TOOL_NAME`, `CODEX_DESCRIPTION`, and `CODEX_SERVER_NAME`. Agent behavior is controlled with variables such as `CODEX_MODEL`, `CODEX_CWD`, `CODEX_SANDBOX_MODE`, `CODEX_APPROVAL_POLICY`, `CODEX_EFFORT`, `CODEX_ADDITIONAL_DIRS`, `CODEX_NETWORK_ACCESS`, and `CODEX_WEB_SEARCH`.

Use `CODEX_INSTRUCTIONS` to replace the default instructions or `CODEX_APPEND_INSTRUCTIONS` to add to them. `CODEX_PERSIST_SESSION` controls session resume and defaults to enabled. The default sandbox is read-only; writing requires an explicit `workspace-write` or `danger-full-access` setting.

## Tools and capabilities

A regular instance provides:

- `<name>` for sending a task to the configured agent.
- `<name>_reply` for continuing a saved thread.

The `CODEX_FACTORY_ONLY=true` mode instead exposes `create_codex_mcp`. This factory wizard accepts a description of the desired agent and generates an `.mcp.json` entry. Generated configurations do not expose the API key.

## Limitations and notes

The codex-octopus MCP server depends on the Codex CLI being installed because the SDK launches it underneath. It does not provide a single shared agent configuration: each specialized agent requires its own MCP server entry and environment settings. Network access and file-writing permissions are disabled or restricted by default, and overrides cannot expand those permissions beyond the server configuration.

_Full upstream README: https://allmcps.com/mcp/codex-octopus/readme_