io.github.xiaolai/codex-octopus MCP Server
io.github.xiaolai/codex-octopus
Spawn multiple specialized Codex agents as MCP servers, each with custom models, sandboxes, and personalities.
What this kind of tool is for
- Hand your agent a structured way to call a model or an inference API.
- Compare outputs from two different providers on the same prompt.
- Wire retrieval, embeddings, or generation into an existing agent workflow.
How to compare servers like this
- Provider coverage:
- Match the tool's supported providers and models to the ones your project uses.
- Cost exposure:
- Model-backed tools spend real API budget; check how usage and limits are configured.
- Maintenance signal:
- The provider landscape shifts weekly; prefer tools updated within the last few months.
- Config surface:
- Prefer tools whose environment-variable or config keys are documented plainly.
This page carries your copy-paste config: pick your MCP client in the install section on this page and use the copy button.
What is the io.github.xiaolai/codex-octopus MCP server?
Codex Octopus is an MCP server that wraps the OpenAI Codex SDK, allowing you to run multiple specialized Codex agents—each independently configured with different models, sandbox modes, effort levels, and instructions—from a single MCP client. Each agent appears as a separate tool, enabling use cases like strict code review, test writing, and quick Q&A simultaneously.
Codex Octopus lets you configure and deploy multiple Codex agents with different personalities and constraints. Instead of one generic Codex instance, you can spin up a read-only code reviewer, a test-writing specialist, a cheap quick helper, and a deep-thinking expert—all at once. Each runs in its own sandbox with its own model and approval policy, giving you fine-grained control over what each agent can do.
How to install io.github.xiaolai/codex-octopus
Copy-paste configuration for popular MCP clients.
CODEX_API_KEYsecretOpenAI API key (leave unset to inherit from parent process)
CODEX_TOOL_NAMETool name prefix (default: codex)
CODEX_MODELModel: gpt-5-codex, o3, codex-1, or full ID
CODEX_SANDBOX_MODESandbox: read-only, workspace-write, danger-full-access
CODEX_APPROVAL_POLICYApproval: never, on-failure, on-request, untrusted
CODEX_APPEND_INSTRUCTIONSAdditional instructions appended to the default
CODEX_FACTORY_ONLYSet to true to expose only the factory wizard tool
{
"mcpServers": {
"codex-octopus": {
"command": "npx",
"args": [
"-y",
"codex-octopus"
],
"env": {
"CODEX_API_KEY": "<YOUR_CODEX_API_KEY>",
"CODEX_TOOL_NAME": "<YOUR_CODEX_TOOL_NAME>",
"CODEX_MODEL": "<YOUR_CODEX_MODEL>",
"CODEX_SANDBOX_MODE": "<YOUR_CODEX_SANDBOX_MODE>",
"CODEX_APPROVAL_POLICY": "<YOUR_CODEX_APPROVAL_POLICY>",
"CODEX_APPEND_INSTRUCTIONS": "<YOUR_CODEX_APPEND_INSTRUCTIONS>",
"CODEX_FACTORY_ONLY": "<YOUR_CODEX_FACTORY_ONLY>"
}
}
}
}Tools & capabilities
Tools this server exposes to the agent.
<name> (customizable)— Send a task to the agent and receive a response with a thread_id for conversation continuity.<name>_reply (customizable)— Continue a previous conversation with the agent by referencing its thread_id.create_codex_mcp (factory mode only)— Interactive wizard that generates .mcp.json configuration entries for new specialized agents.
Use cases
- Deploy a strict code reviewer with read-only sandbox to audit pull requests without risk of modification.
- Create a dedicated test-writing agent with workspace-write access and TDD-focused instructions.
- Run a minimal-effort quick-answer helper for fast coding questions at lower cost.
- Set up multiple agents with different reasoning effort levels (minimal to xhigh) for different complexity tiers.
- Use the factory wizard to interactively generate new agent configurations without manual .mcp.json editing.
io.github.xiaolai/codex-octopus MCP server FAQ
Codex Octopus is an MCP server that lets you run multiple specialized Codex agents simultaneously, each with its own model, sandbox mode, effort level, and custom instructions. Instead of one generic agent, you get purpose-built tools like a code reviewer, test writer, and quick helper.
Codex Octopus itself is free and open-source (ISC license), but it requires an OpenAI API key and will incur charges based on your Codex API usage.
Add an entry to your `.mcp.json` file with `command: npx` and `args: ["codex-octopus@latest"]`, optionally setting environment variables for model, sandbox mode, and instructions. You can run multiple instances with different configurations.
You need an OpenAI API key set as the `CODEX_API_KEY` environment variable. If not provided, it inherits from the parent process.
Yes. Each instance is configured via environment variables in `.mcp.json`: model selection, sandbox mode (read-only, workspace-write, danger-full-access), reasoning effort, approval policy, and custom instructions.
Set `CODEX_FACTORY_ONLY=true` to expose a single `create_codex_mcp` tool—an interactive wizard that generates `.mcp.json` entries for new agents based on your description.
README (reference)
Source of truth, from the repository.
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_KEYenv 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.
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 setworkspace-writeordanger-full-access. cwdoverrides preserve agent knowledge — when the host overridescwd, the agent's configured base directory is automatically added toadditionalDirectories.- Security overrides narrow, never widen — per-invocation
sandboxModeandapprovalPolicycan only tighten (e.g.,workspace-write→read-only), never loosen. _replytool respects persistence — not registered whenCODEX_PERSIST_SESSION=false.- API keys are redacted — the factory wizard never exposes
CODEX_API_KEYin 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
minimaleffort + web_search: OpenAI does not allowweb_searchtools withminimalreasoning effort. Uselowor higher if web search is needed.
Development
pnpm install
pnpm build # compile TypeScript
pnpm test # run tests (vitest)
pnpm test:coverage # coverage report
License
ISC - Xiaolai Li
Related MCP servers

io.github.xiaolai/claude-octopus
Spawn multiple specialized Claude Code agents as MCP servers, each with custom models, tools, and personalities.

NovelAI Image MCP
NovelAI image generation as MCP tools: txt2img, img2img, inpaint, upscale, Director, ControlNet.
AI agents get on-chain identity, credentials, reputation, escrow, and persistent memory on XRPL.

DeepSeek Visionary
DeepSeek web vision model as an MCP server with automatic browser login—no API key required.
Field-verified China travel facts for foreign visitors: booking walls, hotel registration, transit.
APIs and MCP for structured public data, web research, CAPTCHA, and source-bound data cleanup.
