codex-as-mcp

codex-as-mcp is a Model Context Protocol (MCP) server that allows MCP clients (such as Claude Code or Cursor) to delegate tasks to the Codex CLI.

It works by spawning Codex agents in the server's current working directory using the following command structure: codex exec --cd <server cwd> --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox -.

Security Warning: The server uses the --dangerously-bypass-approvals-and-sandbox flag, which disables sandboxing and confirmation prompts. Only use this server in repositories you trust.

You can integrate codex-as-mcp into your MCP client using one of the following methods:

Method 1: Edit .mcp.json directly

Add the codex-subagent configuration to your mcpServers object.

Method 2: Use Claude Desktop CLI

Run the claude mcp add command to register the server.

Method 3: Configure via Codex CLI

If you are configuring Codex CLI directly (e.g., in ~/.config/codex/config.toml), add the server under the [mcp_servers.subagents] section.

{
  "mcpServers": {
    "codex-subagent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-as-mcp@latest"]
    }
  }
}

claude mcp add codex-subagent -- uvx codex-as-mcp@latest

[mcp_servers.subagents]
command = "uvx"
args = ["codex-as-mcp@latest"]

Before using the MCP server, you must install the Codex CLI (version 0.46.0 or higher) and authenticate.

# Install the latest Codex CLI
npm install -g @openai/codex@latest

# Authenticate
codex login

# Verify installation
codex --version

Ensure that the Codex CLI can run non-interactively. This requires your provider credentials to be present in ~/.codex/config.toml or via the appropriate environment variables.

If your Codex configuration uses an env_key for a custom provider, the MCP server process must have that environment variable set so it can pass it to the spawned codex process.

For example, if your config.toml defines env_key = "PROVIDER_API_KEY", you must provide PROVIDER_API_KEY to the MCP server.

Option A: Set in MCP client config (Recommended)

{
  "mcpServers": {
    "codex-subagent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-as-mcp@latest"],
      "env": {
        "PROVIDER_API_KEY": "KEY_VALUE"
      }
    }
  }
}

Option B: Pass via server arguments

uvx codex-as-mcp@latest --env PROVIDER_API_KEY=KEY_VALUE

Option C: Add via Codex CLI

codex mcp add codex-subagent --env PROVIDER_API_KEY=KEY_VALUE -- uvx codex-as-mcp@latest

To use the server, add it to your MCP client configuration.

Claude Desktop / .mcp.json configuration

Add the following to your configuration file:

{
  "mcpServers": {
    "codex-subagent": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-as-mcp@latest"]
    }
  }
}

Alternatively, use the Claude CLI to add it:

claude mcp add codex-subagent -- uvx codex-as-mcp@latest

Before using codex-as-mcp, you must install the Codex CLI (version 0.46.0 or higher).

1. Install the package globally via npm.
2. Log in to your Codex account.
3. Verify the installation by checking the version.

npm install -g @openai/codex@latest
codex login

# Verify installation
codex --version

The server is designed to be run using uv. It exposes the spawn_agent and spawn_agents_parallel tools via the Model Context Protocol (MCP).

Command:

uv run python -m codex_as_mcp

Prerequisites:

• The codex CLI must be installed and available in your PATH (e.g., via npm i -g @openai/codex).

You can launch the MCP server implementation using the Python module interface. This is useful for running the server directly from your environment.

python -m codex_as_mcp

If you encounter a timeout error (e.g., timed out awaiting tools/call after 60s), it is because spawn_agent waits for the codex exec process to finish, which often exceeds the default 60s client timeout.

Fix for Codex CLI

In your Codex configuration (~/.codex/config.toml or ~/.config/codex/config.toml), increase the tool_timeout_sec for the MCP server:

[mcp_servers.subagents]
transport = "stdio"
command = "uvx"
args = ["codex-as-mcp@latest"]
tool_timeout_sec = 600

Fix for MCP Inspector / mcp dev

If testing locally with the MCP Inspector, export the following environment variables to increase request timeouts:

export MCP_SERVER_REQUEST_TIMEOUT=300000
export MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=true
export MCP_REQUEST_MAX_TOTAL_TIMEOUT=28800000

The codex-as-mcp server provides two primary tools for generating autonomous Codex sub-agents that run within the server's current working directory using codex e --dangerously-bypass-approvals-and-sandbox - via stdin.

• spawn_agent(prompt: str): Generates a single autonomous Codex sub-agent and returns its final message.
• spawn_agents_parallel(agents: list[dict]): Generates multiple Codex sub-agents in parallel. Each dictionary in the agents list must contain a prompt field. The return value is a list containing either the output (final message) or an error for each sub-agent, indexed to match the input.

The server exposes two primary tools for delegating work to Codex agents:

• spawn_agent(prompt: str): Spawns an autonomous Codex subagent using the server's working directory and returns the agent's final message.
• spawn_agents_parallel(agents: list[dict]): Spawns multiple Codex subagents in parallel. Each dictionary in the agents list must include a prompt key. Results include either an output or an error per agent.