opencode-mcp-bridge

A Model Context Protocol (MCP) server that lets any AI tool (Claude Code, Antigravity, VS Code, Cursor, Windsurf, JetBrains, Claude Desktop, etc.) delegate tasks to the OpenCode CLI as a subagent — driven entirely through OpenCode's own opencode serve HTTP/SSE API, with async push events, task contracts, context tracking, checkpoints, and multi-session orchestration.

Agent instructions live in AGENTS.md — or just call the opencode_guide tool once this server is registered; it returns the same guide live from the running server's actual state.

Architecture

The bridge talks to a single, long-lived opencode serve process over plain HTTP:

• One shared process, unlimited sessions. server-manager.ts spawns and singleton-manages opencode serve (state tracked in ~/.opencode-bridge/server.json); every opencode_start call just creates a lightweight session on that one server instead of launching a new CLI process per task. No node-pty native binding, no per-task re-authentication.
• One event stream, every session. A single SSE connection to /api/event carries events for all sessions, tagged by durable.aggregateID; http-bridge.ts fans them out to the right local session (session.next.step.started/ended/failed, session.next.tool.called, session.next.text.delta, …) and derives status (running / idle / waiting_input / error) from them — no ANSI scraping, no idle-timer heuristics.
• Self-healing. OpenCode's HTTP API does not surface session-runner failures (e.g. a model resolution error) as API-visible errors or events — a failed session just sits at running forever, indistinguishable from working. The bridge tails OpenCode's own internal log (~/.local/share/opencode/log/opencode.log) to detect these failures immediately, and runs a stall watchdog (zero tokens generated N seconds after a prompt) as a second line of defense. Because a single such failure has been observed to wedge that server process's entire turn queue, detecting one triggers an automatic restart of opencode serve so subsequent sessions aren't collateral damage.

Features

• ⚡ Async Events: Writes state transitions (running, idle, waiting_input, error, stale, contract_violated) to ~/.opencode-mcp-events.jsonl.
• 🔀 Multi-Session Orchestration: Run up to 3 concurrent OpenCode sessions with dependency ordering (opencode_batch).
• 🗂️ Context Bucket: Tracks every file creation/modification reported by the session's event stream.
• 🛡️ Task Contracts: Enforce duration limits, path scope restrictions, file count caps, and forbidden commands.
• 📸 Checkpoints & Recovery: Auto-save state snapshots every 60s and retry failed sessions from any checkpoint.
• 🎯 Pre-Flight Classifier: Score incoming tasks to decide whether to delegate and recommend the best model.
• 🩺 Failure visibility: opencode_health exposes last_error — the real underlying exception from OpenCode's runner, not just a generic hang.
• 🖥️ Server introspection: opencode_server_health / opencode_server_restart expose and control the underlying opencode serve process itself, separate from any individual session.
• 📖 Self-documenting: opencode_guide returns a complete, live behavioral guide (model selection, workflow, gotchas) generated from the running server's actual state — works identically in any MCP host.

Prerequisites

• Node.js v18+
• OpenCode CLI installed and authenticated (opencode auth login) — run opencode --version to confirm it's on PATH.

Quick Start

1. Clone and build:

   git clone https://github.com/Dheerax/opencode_mcp.git
   cd opencode_mcp
   npm install
   npm run build
   

2. Register as an MCP server:

   • Claude Code:

     claude mcp add -s user opencode-mcp-bridge -- node /absolute/path/to/opencode_mcp/dist/index.js
     

   • Antigravity / VS Code / Cursor / Windsurf: Add to your MCP server configuration:

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

3. Run Setup: Invoke the opencode_setup tool once from your host agent to generate workspace integration instructions, then call opencode_guide to get the full usage guide.

All tools

See AGENTS.md for the complete tool reference table and workflow guide — or call the opencode_guide MCP tool directly, which returns the same content live.

Troubleshooting

If a session's status stays error immediately and opencode_health's last_error mentions ModelUnavailableError for a provider you expect to work (e.g. a google/* model), the provider's cached OAuth token has likely expired. Re-authenticate it directly:

opencode auth logout <provider>
opencode auth login <provider>

This is an OpenCode/provider-auth issue, not something the bridge can fix by itself — it can only detect it, report it via last_error, and recover the server process so it doesn't stay wedged for other sessions.

License

MIT