Claude Mcp Bridge

claude-mcp-bridge

MCP server that lets any agent or MCP host (Cursor, Codex, Antigravity, another Claude Code, your own app) escalate to Opus via Claude Code running headless (claude -p / claude --bg).

Opus is expensive but very capable — this bridge is deliberately narrow: complex reasoning, architecture questions, adversarial review, and autonomous work. Cheap mechanical work (mapping a repo, scanning files) should stay on the host agent's lighter model.

Nested MCP delegation is blocked: Opus sessions spawned by this bridge cannot call claude-mcp-bridge (or any MCP) again.

Tools

| Tool | Purpose | Model | |------|---------|-------| | ask | Read-only Q&A — architecture, explanation, planning (claudecode({ prompt: "..." })) | Opus (forced) | | delegate | Full autonomous task — edit, shell, tests (max turns, synchronous) | Opus (forced) | | fire | Fire-and-forget background task — returns session_id immediately | Opus (forced) | | check | Compact progress report for a fire session | read-only (no model) | | follow_up | Continue a prior session by session_id | Opus (forced) |

Parallel background tasks

fire({ prompt: "Refactor the auth module to use JWT" })
→ returns session_id immediately

check({ session_id: "..." })
→ check progress anytime

Examples

// Ask Opus to explain architecture (read-only)
{ "prompt": "Explain the architecture of this project" }

// Delegate autonomous work (waits for completion)
{ "prompt": "Refactor auth to JWT and fix all tests" }

// Background refactor — poll while you keep working
{ "prompt": "Refactor the auth module to use JWT", "name": "JWT refactor" }
// → session_id: ...
{ "session_id": "..." }

Every tool accepts: cwd (project root), effort (low \| medium \| high, default high).

Requirements

• Node ≥ 18
• claude CLI v2.1.139+ installed and authenticated (claude once to log in).

Background tasks (fire / check) require claude --bg and claude agents --json.

Install

git clone https://github.com/JaimeJunr/claude-mcp-bridge.git
cd claude-mcp-bridge
npm install
npm run build

Register in an MCP host

Claude Code:

claude mcp add claude-bridge -s user -- node /abs/path/to/claude-mcp-bridge/dist/index.js

Cursor / Codex / any host — add to its mcp.json:

{
  "mcpServers": {
    "claude-bridge": {
      "command": "node",
      "args": ["/abs/path/to/claude-mcp-bridge/dist/index.js"]
    }
  }
}

Configuration (env)

| Var | Default | Meaning | |-----|---------|---------| | CLAUDE_BIN | claude | Path to the claude binary. | | CLAUDE_BRIDGE_MODEL | opus | Model alias — always Opus in this bridge. | | CLAUDE_BRIDGE_EFFORT | high | Default reasoning effort. | | CLAUDE_BRIDGE_MAX_TURNS | 20 | Max agentic turns for delegate / fire. | | CLAUDE_BRIDGE_PERMISSION | acceptEdits | Permission mode for delegate/fire: plan \| default \| acceptEdits \| bypassPermissions. | | CLAUDE_BRIDGE_TIMEOUT_MS | 600000 | Per-call timeout for sync tools (ask, delegate). | | CLAUDE_BRIDGE_SHORT_TIMEOUT_MS | 30000 | Timeout for fire / check. |

> Security: acceptEdits lets delegated Opus edit files autonomously; bypassPermissions > additionally allows unrestricted shell. Only raise this for trusted workspaces. ask always > uses plan (read-only).

Develop

npm test       # vitest — unit tests for arg building / json parsing
npm run dev    # run from source via tsx

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JaimeJunr
• Source: JaimeJunr/claude-mcp-bridge
• License: MIT

Install and usage instructions live in the source repository linked above.