# Cursor ACP → MCP bridge for Codex

> **Experimental implementation — use at your own risk.** This bridge is not an official Cursor or OpenAI product. It delegates file edits and shell commands to Cursor Agent via ACP. You must opt in explicitly, set allowed workspace roots, review every diff yourself, and read [SECURITY.md](./SECURITY.md) before use.

This local bridge exposes one MCP tool，`cursor_worker`，to Codex．Each tool call starts `agent acp` as a child process，creates one ACP session，lets Cursor modify the selected repository or Git worktree，and returns Cursor's final response plus Git status．

**Default: disabled.** The bridge does not spawn Cursor unless `CURSOR_BRIDGE_ENABLED=1` is set in the MCP server environment.

## Architecture

```text
Codex app／CLI／IDE extension
        │  MCP over stdio
        ▼
cursor-acp-mcp-bridge
        │  ACP over stdio，JSON-RPC／NDJSON
        ▼
Cursor CLI：agent acp
        │
        ▼
Repository or isolated Git worktree
```

Cursor Desktop may remain open，but the bridge does not click or control its GUI．Do not manually edit the same files while a worker is running．

## 1．Use one execution environment

The most reliable arrangement is one of the following．

- WSL：Codex CLI，Node.js，Git，Cursor CLI，bridge，and repository all run inside the same WSL distribution．
- Native Windows：all components run natively on Windows．
- Codex Windows app＋WSL worker：the Codex MCP command launches the bridge through `wsl.exe`．The tool accepts either `/mnt/c/...` or `C:\...` as `cwd`．

Do not install `agent` only in Windows and run the bridge in WSL，or the reverse，unless `CURSOR_AGENT_COMMAND` points to a working wrapper．

## 2．Verify prerequisites

Run in the environment where the bridge will execute：

```bash
node --version
npm --version
git --version
agent --version
agent login
```

Use Node.js 20 or later．After login，this command should start and wait silently for ACP input：

```bash
agent acp
```

Stop it with `Ctrl+C`．

## 3．Install bridge dependencies

From this project directory：

```bash
npm ci
```

Or, for a fresh install:

```bash
npm install
```

Keep the committed `package-lock.json`．

Run the test suite：

```bash
npm test
```

## 4．Test the MCP server directly

Start it：

```bash
npm start
```

The process should print the following to stderr and then wait：

```text
cursor-acp-mcp-bridge listening on stdio
```

Stop it with `Ctrl+C`．Never add `console.log` to the server because stdout is reserved for MCP JSON-RPC．Use `console.error` for logs．

For an interactive tool test，run：

```bash
npm run inspect
```

In MCP Inspector，connect and call `cursor_worker` with values such as：

```json
{
  "prompt": "Inspect this repository without editing it．Report the main entry point and test command．",
  "cwd": "/absolute/path/to/repository",
  "timeout_seconds": 300,
  "permission_policy": "reject-once",
  "approve_plans": true,
  "question_policy": "skip"
}
```

Set `CURSOR_BRIDGE_ENABLED=1` in the Inspector environment before calling the tool．

For the first write test，use a disposable Git worktree and `permission_policy: "allow-once"`．

## 5A．Register with Codex in the same WSL／Linux environment

Use an absolute path：

```bash
codex mcp add cursor_worker \
  --env CURSOR_BRIDGE_ENABLED=1 \
  --env CURSOR_ALLOWED_ROOTS=/home/USER/projects \
  -- node /home/USER/tools/cursor-acp-mcp-bridge/src/index.js
```

Then inspect：

```bash
codex mcp list
```

Edit `~/.codex/config.toml` and ensure the entry contains longer timeouts and tool-call approval：

```toml
[mcp_servers.cursor_worker]
command = "node"
args = ["/home/USER/tools/cursor-acp-mcp-bridge/src/index.js"]
startup_timeout_sec = 30
tool_timeout_sec = 1800
default_tools_approval_mode = "prompt"
required = false

[mcp_servers.cursor_worker.env]
CURSOR_BRIDGE_ENABLED = "1"
CURSOR_ALLOWED_ROOTS = "/home/USER/projects"
CURSOR_AGENT_COMMAND = "agent"
```

Multiple allowed roots use the operating system path delimiter．On Linux／WSL，separate them with `:`．

## 5B．Register with native Windows Codex and native Windows Cursor CLI

Edit `%USERPROFILE%\.codex\config.toml`：

```toml
[mcp_servers.cursor_worker]
command = "node"
args = ["C:\\Users\\USER\\tools\\cursor-acp-mcp-bridge\\src\\index.js"]
startup_timeout_sec = 30
tool_timeout_sec = 1800
default_tools_approval_mode = "prompt"
required = false

[mcp_servers.cursor_worker.env]
CURSOR_BRIDGE_ENABLED = "1"
CURSOR_ALLOWED_ROOTS = "C:\\Users\\USER\\source"
CURSOR_AGENT_COMMAND = "agent"
```

If `agent` is not found by a child process，set `CURSOR_AGENT_COMMAND` to the full `agent.exe` path．

## 5C．Register Windows Codex app with a WSL bridge

Edit the Windows Codex config file：

```toml
[mcp_servers.cursor_worker]
command = "wsl.exe"
args = [
  "-d",
  "Ubuntu",
  "--",
  "bash",
  "-lc",
  "exec node /home/USER/tools/cursor-acp-mcp-bridge/src/index.js"
]
startup_timeout_sec = 30
tool_timeout_sec = 1800
default_tools_approval_mode = "prompt"
required = false

[mcp_servers.cursor_worker.env]
CURSOR_BRIDGE_ENABLED = "1"
CURSOR_ALLOWED_ROOTS = "/home/USER/projects:/mnt/c/Users/USER/source"
CURSOR_AGENT_COMMAND = "agent"
```

Replace `Ubuntu` with the exact result of：

```powershell
wsl.exe --list --verbose
```

Restart the Codex app after changing MCP configuration．When Codex calls the tool，the `cwd` may be `/mnt/c/Users/...` or a Windows path such as `C:\Users\...`．The bridge converts Windows paths with `wslpath` when running inside WSL．

## 6．Confirm from Codex

In Codex，open `/mcp` and confirm that `cursor_worker` is connected．Then use this prompt in a disposable repository：

```text
Use the cursor_worker MCP tool for the implementation．Delegate only the bounded task below．After Cursor returns，inspect git diff yourself and run the tests yourself．

Task：Create a file named cursor_worker_test.txt containing exactly CURSOR_WORKER_OK．
Acceptance criteria：Only that file is added，and its content matches exactly．
```

Codex should request approval to call the MCP tool，Cursor should create the file，and Codex should independently inspect and verify it．

## 7．Add orchestration rules

Copy the contents of `AGENTS-snippet.md` into the repository's `AGENTS.md`．This makes Codex delegate bounded implementation work，then retain responsibility for diff review，tests，and acceptance．

## 8．Recommended worktree workflow

Create an isolated worktree before delegation：

```bash
cd /path/to/repository
git worktree add -b worker/cursor-test ../repository-cursor-test HEAD
```

Pass the new absolute path as `cwd`．After Codex validates the work：

```bash
git -C ../repository-cursor-test status --short
git -C ../repository-cursor-test diff
```

Do not let Codex and Cursor edit the same original worktree simultaneously．

## Tool parameters

- `prompt`：bounded task，constraints，and acceptance criteria．
- `cwd`：absolute repository or worktree path．
- `timeout_seconds`：30–3600 seconds．Default is 900．
- `permission_policy`：`allow-once` permits each requested operation，`allow-always` is broader，and `reject-once` is suitable for read-only checks．The bridge maps this policy to Cursor's advertised permission option kinds and returns the matching optionId．
- `approve_plans`：automatically accepts Cursor's plan request．
- `question_policy`：`skip` avoids interactive blocking．`first-option` is available but can choose an unsuitable answer．
- `model` (optional)：sets the Cursor model via ACP `session/set_config_option` when the session advertises a model config option．Omit to keep the session default．

## Security defaults

- **Opt-in required:** set `CURSOR_BRIDGE_ENABLED=1` in the MCP server environment．Without it, the tool fails closed and does not spawn `agent acp`．
- Keep `default_tools_approval_mode = "prompt"` until the workflow is trusted．
- Always set `CURSOR_ALLOWED_ROOTS`．
- Prefer a disposable Git worktree．
- Do not expose this stdio bridge over a network．
- Do not place API keys in task prompts．Use the existing `agent login` session．
- The bridge does not commit，push，publish，or deploy by design，but Cursor can still execute approved shell commands．Review every diff．See [SECURITY.md](./SECURITY.md)．

## Troubleshooting

### `Cursor worker failed: Failed to start Cursor CLI command 'agent'`

Run `which agent` on WSL／Linux or `Get-Command agent` on PowerShell．Set `CURSOR_AGENT_COMMAND` to the absolute executable path．Ensure Codex and the bridge inherit the same `HOME` and `PATH`．

### Authentication fails

Run `agent login` in the same Windows or WSL environment and under the same user account that starts the bridge．Then retry `agent acp` manually．

### MCP starts but a worker times out after 60 seconds

Increase `tool_timeout_sec` under `[mcp_servers.cursor_worker]` and restart Codex．The suggested value is 1800 seconds．

### Cursor blocks waiting for permission

Use `permission_policy: "allow-once"` for implementation tasks．The bridge answers each ACP permission request using the selected policy．

### Cursor blocks on a question or plan

Use `question_policy: "skip"` and `approve_plans: true`．The bridge handles Cursor's blocking extension methods．

### `cwd is outside CURSOR_ALLOWED_ROOTS`

Use a worktree beneath an allowed root，or add its parent to `CURSOR_ALLOWED_ROOTS`．Use `:` between roots in WSL／Linux and `;` on native Windows．

### MCP server shows disconnected

Run the exact configured command manually．Ensure it waits without writing ordinary text to stdout．Use `/mcp` or `codex mcp list` after restarting Codex．