Spawns multiple specialized Codex agents as independent MCP servers with custom models, sandboxes, and personalities.
Also known as xiaolai/codex-octopus
- Stars
- 20
- Tools
- 2
- Downloads, 30 days
- —
- Latest version
- 1.0.1
- Last commit
- Nov 13, 2026
- License
- ISC
What is codex-octopus MCP?
codex-octopus spawns multiple specialized Codex agents as independent MCP servers with custom models, sandboxes, and personalities. It exposes 2 tools, such as codex, codex_reply.
Summary generated from the project's README
About codex-octopus MCP server
Codex Octopus acts as a factory for creating multiple specialized coding agents that function as independent MCP servers. Instead of using a single generic assistant, developers can deploy several distinct instances, each configured with its own model, reasoning effort, and sandbox permissions. This allows you to run a strict reviewer in a read-only environment alongside a test writer that has workspace-write access. Each agent appears as a unique tool within your MCP client, such as Claude Desktop or Cursor.
To use this server, you need Node.js, the Codex CLI, and an OpenAI API key provided via the CODEX_API_KEY environment variable. Configuration is handled through environment variables in your .mcp.json file, where you can define specific behaviors like CODEX_SANDBOX_MODE or CODEX_EFFORT. The server also includes an agent-factory mode that provides an interactive wizard to generate these configurations automatically. Each agent provides two primary tools: one for sending tasks and another for continuing conversations using a thread ID.
What you can do with it
- 1Automated Code ReviewDeploy a specialized agent that only reads files to find bugs without modifying your source code.
- 2Test Suite GenerationCreate a dedicated agent with write permissions to automatically implement test files in your workspace.
- 3Rapid Coding AssistanceSet up a low-cost agent with minimal reasoning effort for answering quick programming questions.
- 4Interactive Agent ConfigurationUse the built-in wizard to describe an agent's role and receive a ready-to-use configuration file.
Written from the project's README. Every use case is checked against a quote from it.
How to install codex-octopus MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall codex-octopus MCP in Claude Code
$ claude mcp add --env 'CODEX_API_KEY=<YOUR_CODEX_API_KEY>' codex-octopus -- npx -y codex-octopusInstall codex-octopus MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"codex-octopus": {
"command": "npx",
"args": [
"-y",
"codex-octopus"
],
"env": {
"CODEX_API_KEY": "<YOUR_CODEX_API_KEY>"
}
}
}
}Install codex-octopus MCP in VS Code
.vscode/mcp.json
{
"servers": {
"codex-octopus": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"codex-octopus"
],
"env": {
"CODEX_API_KEY": "<YOUR_CODEX_API_KEY>"
}
}
}
}Install codex-octopus MCP in VS Code CLI
$ code --add-mcp '{"name":"codex-octopus","type":"stdio","command":"npx","args":["-y","codex-octopus"],"env":{"CODEX_API_KEY":"<YOUR_CODEX_API_KEY>"}}'Install codex-octopus MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"codex-octopus": {
"command": "npx",
"args": [
"-y",
"codex-octopus"
],
"env": {
"CODEX_API_KEY": "<YOUR_CODEX_API_KEY>"
}
}
}
}Install codex-octopus MCP in Codex
$ codex mcp add codex-octopus --env 'CODEX_API_KEY=<YOUR_CODEX_API_KEY>' -- npx -y codex-octopusInstall codex-octopus MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.codex-octopus] command = "npx" args = ["-y", "codex-octopus"] [mcp_servers.codex-octopus.env] CODEX_API_KEY = "<YOUR_CODEX_API_KEY>"
Install codex-octopus MCP in Gemini CLI
$ gemini mcp add -s user -e 'CODEX_API_KEY=<YOUR_CODEX_API_KEY>' codex-octopus npx -- -y codex-octopusInstall codex-octopus MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"codex-octopus": {
"command": "npx",
"args": [
"-y",
"codex-octopus"
],
"env": {
"CODEX_API_KEY": "<YOUR_CODEX_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for codex-octopus 1.0.1 in an isolated container with no network and no keys. It answered and listed 2 tools.
codex-octopus MCP tools 2
Read from the server with tools/listcodexSend 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_replyContinue a previous codex conversation by thread ID. Use this for follow-up questions, iterative refinement, or multi-step workflows that build on prior context.
| 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. |
Configuration
CODEX_API_KEYSecretOpenAI API key (leave unset to inherit from parent process)
CODEX_APPEND_INSTRUCTIONSAdditional instructions appended to the default
CODEX_APPROVAL_POLICYApproval: never, on-failure, on-request, untrusted
CODEX_DESCRIPTIONCODEX_EFFORTCODEX_FACTORY_ONLYSet to true to expose only the factory wizard tool
CODEX_MODELModel: gpt-5-codex, o3, codex-1, or full ID
CODEX_SANDBOX_MODESandbox: read-only, workspace-write, danger-full-access
CODEX_SERVER_NAMECODEX_TOOL_NAMETool name prefix (default: codex)
| Name | Description | |
|---|---|---|
| CODEX_API_KEY | OpenAI API key (leave unset to inherit from parent process) | Secret |
| CODEX_APPEND_INSTRUCTIONS | Additional instructions appended to the default | |
| CODEX_APPROVAL_POLICY | Approval: never, on-failure, on-request, untrusted | |
| CODEX_DESCRIPTION | — | |
| CODEX_EFFORT | — | |
| CODEX_FACTORY_ONLY | Set to true to expose only the factory wizard tool | |
| CODEX_MODEL | Model: gpt-5-codex, o3, codex-1, or full ID | |
| CODEX_SANDBOX_MODE | Sandbox: read-only, workspace-write, danger-full-access | |
| CODEX_SERVER_NAME | — | |
| CODEX_TOOL_NAME | Tool name prefix (default: codex) |
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablexiaolai/codex-octopus is public and reachablegithub.com/xiaolai/codex-octopus ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)ISCspdx.org/licenses/ISC.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/xiaolai/codex-octopus ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from codex-octopusPass
- No critical advisory in the package or its dependencies107 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model2 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCodex 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
codex-octopus MCP questions
How do I add codex-octopus MCP to Claude Code?
Run claude mcp add --env 'CODEX_API_KEY=<YOUR_CODEX_API_KEY>' codex-octopus -- npx -y codex-octopus in your terminal. Add --scope user to make it available in every project.
How do I add codex-octopus MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does codex-octopus MCP provide?
It exposes 2 tools, including codex, codex_reply.
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.