codex-octopus — Claude Code MCP server: setup
Runs several separately configured Codex agents through MCP. Use it to split code review, test writing, and quick coding tasks.
claude mcp add --env CODEX_API_KEY=<CODEX_API_KEY> --env CODEX_TOOL_NAME=<CODEX_TOOL_NAME> --env CODEX_MODEL=<CODEX_MODEL> --env CODEX_SANDBOX_MODE=<CODEX_SANDBOX_MODE> --env CODEX_APPROVAL_POLICY=<CODEX_APPROVAL_POLICY> --transport stdio codex-octopus -- npx -y codex-octopusWhat codex-octopus does
codex-octopus exposes the OpenAI Codex SDK through an MCP server. Each server instance can have its own model, sandbox setting, reasoning effort, working directory, and extra instructions. An MCP client sees those instances as separate tools.
Configuration lives in environment variables inside .mcp.json. You can give one agent read-only access for review and another workspace-write access for tests. A factory mode provides the create_codex_mcp tool, which builds an MCP configuration entry from a requested agent setup. Calls can also override the directory, model, extra directories, network access, and web search mode.
The setup needs Node.js 18 or newer, the Codex CLI provided through @openai/codex, and an OpenAI key in CODEX_API_KEY or inherited from the parent process. Without Node.js 18 or newer, the server will not start.
What it helps with
- split code review and test writing across separate agents
- assign different models and reasoning effort to each agent
- keep a reviewer inside a
read-onlysandbox - give an agent access to extra project directories
- generate an MCP entry with the factory tool
Example prompts for the agent
- Ask the configured Codex tool to inspect this module and report concrete bugs, not style preferences.
- Have the test-focused agent write coverage for this code, including edge cases, with workspace write access.
- Use
create_codex_mcpto generate a read-only code review agent configuration.
How to install codex-octopus
Platform CLI
claude mcp add --env CODEX_API_KEY=<CODEX_API_KEY> --env CODEX_TOOL_NAME=<CODEX_TOOL_NAME> --env CODEX_MODEL=<CODEX_MODEL> --env CODEX_SANDBOX_MODE=<CODEX_SANDBOX_MODE> --env CODEX_APPROVAL_POLICY=<CODEX_APPROVAL_POLICY> --transport stdio codex-octopus -- npx -y codex-octopusReplace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
codex mcp add codex-octopus --env CODEX_API_KEY=<CODEX_API_KEY> --env CODEX_TOOL_NAME=<CODEX_TOOL_NAME> --env CODEX_MODEL=<CODEX_MODEL> --env CODEX_SANDBOX_MODE=<CODEX_SANDBOX_MODE> --env CODEX_APPROVAL_POLICY=<CODEX_APPROVAL_POLICY> -- npx -y codex-octopusReplace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"mcpServers": {
"codex-octopus": {
"command": "npx",
"args": [
"-y",
"codex-octopus"
],
"env": {
"CODEX_API_KEY": "<CODEX_API_KEY>",
"CODEX_TOOL_NAME": "<CODEX_TOOL_NAME>",
"CODEX_MODEL": "<CODEX_MODEL>",
"CODEX_SANDBOX_MODE": "<CODEX_SANDBOX_MODE>",
"CODEX_APPROVAL_POLICY": "<CODEX_APPROVAL_POLICY>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"servers": {
"codex-octopus": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"codex-octopus"
],
"env": {
"CODEX_API_KEY": "<CODEX_API_KEY>",
"CODEX_TOOL_NAME": "<CODEX_TOOL_NAME>",
"CODEX_MODEL": "<CODEX_MODEL>",
"CODEX_SANDBOX_MODE": "<CODEX_SANDBOX_MODE>",
"CODEX_APPROVAL_POLICY": "<CODEX_APPROVAL_POLICY>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
gemini mcp add -e CODEX_API_KEY=<CODEX_API_KEY> -e CODEX_TOOL_NAME=<CODEX_TOOL_NAME> -e CODEX_MODEL=<CODEX_MODEL> -e CODEX_SANDBOX_MODE=<CODEX_SANDBOX_MODE> -e CODEX_APPROVAL_POLICY=<CODEX_APPROVAL_POLICY> codex-octopus npx -y codex-octopusReplace <…> with your own values. 2 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about codex-octopus
How do I install codex-octopus in Claude Code?
Run claude mcp add codex-octopus -e CODEX_API_KEY=<CODEX_API_KEY> -- npx -y codex-octopus.
What does codex-octopus do?
It exposes separately configured Codex instances as MCP tools. Each instance can use its own model, sandbox, instructions, and reasoning effort.
What is required for codex-octopus to work?
You need Node.js 18 or newer, the Codex CLI through @openai/codex, and an OpenAI key in CODEX_API_KEY or inherited from the parent process.
