agent-delegate-bridge

An MCP server that lets Claude Code and Codex delegate tasks to each other.

Claude Code (or Codex, or any MCP-capable desktop tool) registers this server and calls the delegate tool. Claude tasks run through claude -p (which reads the provider proxy env from the cc-switch host-creds file, so it works from any caller); Codex tasks run through the Agent Client Protocol (ACP).

[Claude Code] --MCP(stdio)--> [agent-delegate-bridge] --claude -p-----> [Claude Code CLI]
[Codex]       --MCP(stdio)--> [agent-delegate-bridge] --ACP(stdio)-----> [codex-acp]

Install

npm install -g agent-delegate-bridge

After installing, the agent-delegate-bridge binary is on your PATH.

Register in Claude Code

claude mcp add bridge -- agent-delegate-bridge

Register in Codex

codex mcp add bridge -- agent-delegate-bridge

(For development from source, use node dist/index.js instead of agent-delegate-bridge.)

Usage

The delegate tool takes:

• target: "codex" or "claude" — which agent to delegate to
• task: the prompt for the target agent
• cwd (optional): working directory for the target agent
• timeoutMs (optional): max wait in milliseconds, 1000–600000 (default 120000) — raise it when the target is slow (e.g. a flaky network that retries before falling back)

Example prompt to Claude Code:

Use the delegate tool with target "codex" to ask Codex to write a unit test for src/util.ts.

Requirements

• Node.js 22+
• Codex CLI (for delegating to Codex)
• Claude Code (for delegating to Claude)
• The ACP adapters are fetched automatically via npx.

Troubleshooting

Codex delegation fails

• Ensure you are logged into Codex (codex CLI works and ~/.codex/auth.json exists).
• If codex-acp fails with authentication errors, run codex login (or re-authenticate) to refresh your session.
• The first npx run downloads the @agentclientprotocol/codex-acp package — this may take 30-60 seconds.
• If delegation fails with a network error, run codex doctor. If it reports provider endpoints as unreachable, your machine cannot access the ChatGPT API (you may need a proxy/VPN) — this is not a bridge issue.
• If delegation fails with "You've hit your usage limit", your ChatGPT/Codex account has run out of credits — wait for the quota reset or upgrade. This is an account-level limit, not a bridge issue.

Claude delegation fails

• Ensure Claude Code is installed and claude is on your PATH.
• If your Claude is behind a cc-switch proxy, make sure cc-switch is running — the bridge reads the proxy env (ANTHROPIC_BASE_URL, token) from the cc-switch host-creds file so delegation works from any caller.
• If the proxy env can't be found, delegation falls back to claude's own claude.ai login (OAuth must be valid).

Delegation times out

The default timeout is 120 seconds. If the agent takes longer (e.g., complex tasks or slow network), the call will fail with a timeout error. For longer tasks, pass a larger timeoutMs to the delegate tool.

Note: the Codex side can hit a 120s timeout even for short prompts when the adapter keeps waiting — the most common cause is an account/usage error that the adapter never surfaces as a clean response. See "Codex delegation fails" above (usage limit, auth, network) before assuming a real hang.

Publishing to npm

The npm package name is agent-delegate-bridge. (An older package, bridge-mcp-server, is deprecated — don't install it.)

From a clean checkout, npm publish builds dist/ automatically via the prepack script, so the published tarball always matches the source. Typical flow:

npm version patch     # bump version (0.1.10 -> 0.1.11)
npm run build && npm test   # sanity check
npm publish           # prepack runs `npm run build` automatically
git push --follow-tags

• dist/ is gitignored and not committed; the prepack hook rebuilds it on every publish, so you never ship a stale or empty build.
• When you change src/, bump the version and republish — otherwise the installed global binary keeps the old build.
• Verify the published contents before announcing: npm pack --dry-run lists the files that will go out.

License

MIT