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
npm install codex-octopus
Or use npx directly in your .mcp.json (see Quick Start below).
Quick Start
Add to your .mcp.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:
{
"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:
{
"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.
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
┌─────────────────────────────────┐
│ 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
pnpm install
pnpm build
pnpm test
pnpm test:coverage
License
ISC - Xiaolai Li