opencode-executor-mcp

MCP server exposing an ask_opencode tool that delegates a prompt to an OpenCode agent session. Lets a Claude Code orchestrator hand off executor-role / bulk work to a cheaper backend instead of spawning another Claude subagent.

Not tied to any specific provider: by default it uses OpenCode's own bundled Zen free models (only needs opencode auth login, no company gateway required). If you have a company/paid gateway configured in OpenCode, pass it explicitly per-call.

Claude Code (orchestrator)
   -> MCP tool call: ask_opencode(prompt, provider?, model?, sessionId?)
   -> this server
   -> opencode serve (localhost:4096) REST API
   -> whichever provider is selected (default: OpenCode Zen free tier)

Prerequisites

Node.js 18+ (global fetch required)
OpenCode CLI installed
opencode auth login run once (sets up the bundled Zen free-tier credentials used as the default)
Optional: any additional provider configured in OpenCode (company gateway, other API key, etc.) if you want to target something other than the default free models

Setup

Install dependencies:
```
npm install
```
Authenticate OpenCode's default (Zen) provider, if you haven't:
```
opencode auth login
```
Start the OpenCode server (must stay running while you use the tool):
```
opencode serve --port 4096
```
Verify at least one provider is live:
```
curl -s http://127.0.0.1:4096/config/providers | jq
```
You should see a provider with id opencode (the bundled Zen models). Any additional provider you've configured will show up alongside it.
Register this server with Claude Code. Add to ~/.claude.json under mcpServers (see docs/claude-code-integration.md for the exact block):
```
"opencode-executor": {
  "type": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/opencode-mcp/index.js"]
}
```
Restart Claude Code. The ask_opencode and list_opencode_models tools are now available.

Usage

list_opencode_models()
# -> [{ providerID: "opencode", modelID: "big-pickle", name: "Big Pickle", bundled: true }, ...]

ask_opencode({ prompt: "summarize this log file" })
# uses the default bundled Zen model

ask_opencode({ prompt: "...", provider: "my-provider", model: "some-model-id" })
# targets a specific configured provider instead

Omit sessionId for a fresh one-off session (no memory of prior calls). Pass the sessionId returned by a previous ask_opencode call to continue that same conversation — OpenCode retains the history, so the model sees prior turns. This is still call-and-response driven by Claude Code calling the tool each turn; OpenCode never initiates on its own.

Calls can be issued concurrently (fan-out / swarm) since each session is independent unless you deliberately reuse a sessionId; see docs/architecture.md.

Configuration

Env var	Default	Purpose
`OPENCODE_URL`	`http://127.0.0.1:4096`	Base URL of the running `opencode serve` instance
`OPENCODE_PROVIDER` / `OPENCODE_MODEL`	unset	Pin a default provider/model for every call that doesn't specify one, instead of auto-picking the bundled Zen provider

Troubleshooting

See docs/troubleshooting.md.

Docs

docs/architecture.md — how the pieces fit together, why this shape
docs/claude-code-integration.md — wiring into Claude Code's mcpServers config
docs/troubleshooting.md — common failures and fixes