# 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.

## Configuration

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

```text
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:

```text
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`:

```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):

```jsonc
"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

```bash
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.