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.

Related MCP server: mcp-opencode

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