Which integrations are available for this server?

Wraps the OpenAI Codex SDK to provide specialized AI agents for coding tasks, allowing for the configuration of specific models, sandbox environments, and reasoning effort levels for use cases like code review and test generation.

How do I use Codex Octopus?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Codex Octopus write thorough unit tests for the user authentication logic in auth.js" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Codex Octopus

by xiaolai

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

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.

Related MCP server: Codex MCP Server

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.

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 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       # compile TypeScript
pnpm test        # run tests (vitest)
pnpm test:coverage  # coverage report

License

ISC - Xiaolai Li

Available Tools

2 tools

codexA

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.

Inputs: prompt (required), cwd, model, additionalDirs, +6 more.

codex_replyA

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.

Inputs: thread_id (required), prompt (required), cwd, model.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored 2026-04-06 06:29 across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: `codex` initiates a new autonomous task and returns a thread_id, while `codex_reply` explicitly requires that thread_id to continue an existing conversation. No functional overlap exists.

Naming Consistency4/5

Both tools share the `codex` prefix which groups them logically, and `codex_reply` clearly indicates its action. However, the base tool `codex` lacks a descriptive action verb (e.g., `codex_send` or `codex_start`) despite its description emphasizing sending tasks, creating a minor inconsistency in the naming pattern.

Tool Count3/5

With only 2 tools, the set is borderline thin for a server claiming to handle 'complex software engineering tasks end-to-end.' While the initiate-respond loop is functional, the lack of supporting operations (list threads, check status, cancel) makes the surface feel constrained rather than comprehensively scoped.

Completeness3/5

The core conversational workflow is covered (start thread, continue thread), but significant lifecycle operations are missing: there is no way to list active threads, retrieve thread history without continuing, cancel running tasks, or delete threads. These gaps limit agent ability to manage long-running or parallel autonomous tasks.

Maintenance

ActivityActive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
https://api.anotherai.dev/mcp
greadA
io.github.NitroRCr
An MCP server that gives your AI access to the source code and docs of all public github repos
Version Control Code Analysis Documentation Access
5365
https://api.gread.dev/mcp
Server4AgentA
com.server4agent
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
App Automation Cloud Platforms Developer Tools
343
https://mcp.server4agent.com
microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21
https://api.microservices.sh/mcp

Related MCP Servers

Agentic Developer MCP
Developer Tools Code Analysis Version Control
teabranch
A
license
Not graded
quality
D
maintenance
An MCP server that wraps OpenAI's Codex CLI to automate repository cloning and code analysis tasks. It enables users to execute complex coding requests on specific Git branches and subfolders using standardized MCP tools.
Updated a year ago (2025-06-29 13:43 UTC)
9 npm
45
MIT
Codex MCP Server
Code Analysis Developer Tools Coding Agents
tom-wahl
F
license
B
quality
Not graded
maintenance
An MCP server for the OpenAI Codex CLI that provides coding assistance with multi-turn session management and reasoning depth control. It enables users to perform code analysis, generation, and refactoring through Claude with native resume support for conversational context.
Updated 8 months ago (2026-03-02 03:28 UTC)
4
1,352 npm
1
-
AgentSpawnMCP
Agent Orchestration AI & Machine Learning Code Execution
sandsaber
A
license
Not graded
quality
C
maintenance
A universal MCP server for spawning agents with any OpenAI-compatible LLM, supporting cloud and local models, and integrating with Claude Code, OpenCode, and Codex CLI.
Updated 6 months ago (2026-05-14 18:13 UTC)
31 PyPI
MIT
codex-cli-architect-mcp
Code Analysis Developer Tools AI & Machine Learning
itto-ki
A
license
A
quality
D
maintenance
An MCP server that provides technical consultation, code review, and code explanation by integrating with OpenAI's Codex CLI, enabling AI-powered coding assistance in a sandboxed, read-only environment.
Updated a year ago (2025-08-10 07:19 UTC)
3
40 npm
1
MIT

Codex Octopus

Why

Prerequisites

Install

Quick Start

Multiple Agents

Agent Factory

Tools

Configuration

Identity

Agent

Instructions

Advanced

Authentication

Security

Architecture

Known Limitations

Development

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Agentic Developer MCP

Codex MCP Server

AgentSpawnMCP

codex-cli-architect-mcp