OpenCode Codex MCP

Portable MCP bridge that lets an MCP-compatible host such as OpenCode drive the Codex CLI through codex app-server.

Requirements

• Python 3.10 or newer

• A supported Codex CLI installed on the same host, or a command that can launch it

• Codex authenticated before using codex_run

The bridge uses MCP stdio and does not open a network port. It is therefore portable across Linux, macOS, Windows, WSL, containers, and remote shells as long as the configured Codex command is reachable from the bridge process.

Related MCP server: engineering-bridge

Configuration

By default the bridge runs codex app-server --listen stdio:// and resolves codex through PATH. Override it with either variable:

CODEX_BIN=/absolute/path/to/codex
CODEX_COMMAND=/path/to/wsl.exe -d Ubuntu -- codex

CODEX_COMMAND is shell-split and should be used when the executable requires arguments. It also accepts a JSON string array when exact argument boundaries matter. CODEX_BIN is preferred for a single executable path.

If Codex runs in another OS and sees a different path namespace, configure an optional working-directory mapping:

CODEX_CWD_PREFIX=/home/user/project
CODEX_CWD_REPLACE=//wsl.localhost/Ubuntu/home/user/project

OpenCode configuration

Add the server to opencode.json or opencode.jsonc:

{
  "mcp": {
    "codex": {
      "type": "local",
      "command": ["/usr/bin/python3", "-m", "codex_mcp"],
      "cwd": "/absolute/path/to/opencode-codex-mcp",
      "environment": {
        "CODEX_BIN": "codex"
      },
      "enabled": true,
      "timeout": 10000
    }
  }
}

When using the checked-in launcher, the command can instead be (the launcher sets PYTHONPATH so it works regardless of the OpenCode project directory):

"command": ["/absolute/path/to/scripts/codex-mcp"]

The bridge requests workspace-write with the requested cwd as its writable root and approvalPolicy: "never". This is intentionally automated and has the same security implications as allowing Codex to execute commands and edit files in that workspace without interactive approval.

Tools

• codex_run: run a prompt, optionally continuing thread_id

• codex_status: inspect Codex availability and version

• codex_thread_list: list saved Codex threads

• codex_interrupt: interrupt a running turn

Development

python3 -m unittest discover -s tests -v
python3 -m codex_mcp

The schemas/ directory contains protocol schemas generated from the Codex version used during development. The bridge intentionally does not require those generated artifacts at runtime.