Log inSubmit server
Codex Octopus logo

Codex Octopus

Run multiple independently configured Codex agents as separate MCP tools for review, testing, and coding tasks.

InstallRepository
Full README Compare alternatives Embed widget Claim this listing

Install Codex Octopus

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "codex-octopus": {
      "command": "npx",
      "args": [
        "codex-octopus@latest"
      ],
      "env": {
        "CODEX_API_KEY": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

The codex-octopus MCP server wraps the OpenAI Codex SDK and exposes configured Codex agents through MCP tools. Each instance can use its own model, sandbox mode, reasoning effort, working directory, and instructions. Run several instances to give an MCP client separate tools for code review, test writing, or quick coding help. Use the factory-only mode when you want an interactive tool to generate an MCP configuration entry.

Use cases

  • Run a read-only code review agent
  • Generate tests with workspace-write access
  • Route quick coding questions to a low-effort agent
  • Create specialized agent configurations with the factory tool

Key features

  • Expose Codex agents as MCP tools
  • Run multiple independently configured agents
  • Continue conversations with thread IDs
  • Configure models, sandboxes, effort, and instructions
  • Generate MCP entries with an agent factory
  • Restrict per-invocation security settings

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

4/4 checks healthy over the last 46d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8d ago via OSV.dev · codex-octopus@latest (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars20Stargazers on the source repository.
Last commit8d agoMost recent push to the default branch.

How Codex Octopus works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Codex Octopus

codex-octopus is an MCP server that connects MCP clients to the OpenAI Codex SDK and Codex CLI. Its main tools send tasks to configured Codex agents and continue conversations with thread IDs. Separate instances can expose specialized agents with different models, sandbox permissions, effort levels, working directories, and instructions.

Install it with npm or run it with npx from your MCP client configuration. The setup requires Node.js 18 or newer, the Codex CLI, and an OpenAI API key supplied through CODEX_API_KEY or inherited from the parent process.

Create multiple MCP server entries that each run codex-octopus and assign different environment variables. Set values such as CODEX_TOOL_NAME, CODEX_MODEL, CODEX_SANDBOX_MODE, CODEX_EFFORT, and CODEX_APPEND_INSTRUCTIONS to give each agent a distinct role.

Configure a stdio MCP entry that runs the package with npx, then set the desired environment variables for the Codex agent.

Related MCP servers

All in Coding Agents All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewCodex Octopus AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/codex-octopus?style=directory)](https://allmcps.com/mcp/codex-octopus)
HTML Embed
<a href="https://allmcps.com/mcp/codex-octopus"><img src="https://allmcps.com/api/badge/codex-octopus?style=directory" alt="Codex Octopus on AllMCPs" /></a>