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

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：

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：

agent acp

Stop it with Ctrl+C．

3．Install bridge dependencies

From this project directory：

npm ci

Or, for a fresh install:

npm install

Keep the committed package-lock.json．

Run the test suite：

npm test

4．Test the MCP server directly

Start it：

npm start

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

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：

npm run inspect

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

{
  "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：

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：

codex mcp list

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

[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：

[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：

[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：

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：

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：

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：

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．

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．