mcp-opencode

An MCP server that lets an AI coding agent (Claude Code, Codex, or any MCP client) delegate implementation work to the OpenCode CLI — choosing an explicit provider + model on every call.

Use it to orchestrate with one model while offloading the actual code-writing to another: plan in Claude, implement with GLM 5.2, Kimi, DeepSeek, a local Ollama model, or anything else OpenCode can reach.

Provider-agnostic. This server contains no provider-specific logic. It passes your provider/model string straight to opencode run -m, so it works with every provider OpenCode supports (75+ via models.dev, plus local models). Whatever you've authenticated in OpenCode, you can use here.

Why

• Model per task. A cheap model for mechanical edits, a strong one for hard changes — decided per call, not baked into config.
• Real cost/token reporting returned with every run.
• Multi-turn. Continue a session to iterate on the same working tree.
• Safe by construction. cwd is confined to an allowlist; the child process tree is killed cleanly on timeout/abort/cost-cap; secrets are redacted from anything echoed back.

Prerequisites

• Node.js ≥ 20
• The OpenCode CLI installed and on PATH, with at least one provider authenticated (opencode auth login). Run opencode models to see what's available to you.

Register

No install step needed — npx fetches and runs the published package.

Claude Code:

claude mcp add -s user opencode \
  -e OPENCODE_MCP_ROOTS="$HOME/Projects" \
  -- npx -y mcp-opencode

Codex:

codex mcp add opencode \
  --env OPENCODE_MCP_ROOTS="$HOME/Projects" \
  -- npx -y mcp-opencode

Restart the client (or run claude mcp list / codex mcp list) to confirm it connects. The tools appear as opencode_run, opencode_reply, opencode_models.

Build from source (for development)

git clone https://github.com/shreeraman96/mcp-coding-agents.git
cd mcp-coding-agents
npm install
npm run build --workspace mcp-opencode
npm test --workspace mcp-opencode          # unit tests
npm run smoke --workspace mcp-opencode     # optional: live test against a real free OpenCode model

Then register with node /absolute/path/to/mcp-opencode/packages/mcp-opencode/dist/index.js instead of the npx command above.

Tools

opencode_run — start a new session

| field | type | notes | |---|---|---| | prompt | string | required — the task | | model | string | required — provider/model, e.g. fireworks-ai/accounts/fireworks/models/glm-5p2 | | cwd | string | required — must resolve inside an allowed root (see below) | | agent | 'build' \| 'plan' | default 'build' (plan is read-only) | | variant | string | optional model variant / reasoning effort (high, max, minimal) | | timeoutSec | int 30–3600 | default 900 | | maxCostUsd | number | optional — kill the run and return partial output if exceeded |

Returns status, sessionID, model, elapsed time, tokens/cost, a git-derived changed-files summary (when cwd is a repo), and the assistant output.

opencode_reply — continue a session

Takes a sessionID (ses_…) from a prior run plus a new prompt, model, cwd, and agent. model is required on every call — there is no silent inheritance from the original run, by design.

opencode_models

No input. Runs opencode models and returns the available list.

Example (Claude Code)

Delegate to OpenCode: call opencode_run with model fireworks-ai/accounts/fireworks/models/glm-5p2, cwd ~/Projects/myapp, agent build, and prompt "add input validation to routes/user.ts".

Swap the model string for anthropic/claude-sonnet-4-5, openai/gpt-oss-120b, opencode/big-pickle (free), or any local model — nothing else changes.

Configuration

| env var | default | purpose | |---|---|---| | OPENCODE_MCP_ROOTS | $HOME/Projects | colon-separated allowlist of directories cwd may resolve inside | | OPENCODE_MCP_ALLOW_AUTO | unset | set to 1 to add OpenCode's --auto flag for agent=build runs (see below) |

cwd allowlist

cwd is resolved with fs.realpath (symlinks followed) and must land inside one of the OPENCODE_MCP_ROOTS directories. Requests outside the allowlist are rejected before opencode is ever spawned.

Permission model

OpenCode's build agent already runs edit/bash/webfetch non-interactively; the plan agent is read-only. This server relies on those built-in agent defaults and does not inject a custom permission config.

Note: passing a custom permission block via OPENCODE_CONFIG was found to hang opencode run in a non-TTY environment (an unanswerable ask prompt), so that path is deliberately avoided. See src/policy.ts.

--auto (OpenCode's "auto-approve anything not explicitly denied", which the CLI itself flags as dangerous) is off by default and only added when you set OPENCODE_MCP_ALLOW_AUTO=1 and the call uses agent: 'build'.

Security posture — read before enabling

OPENCODE_MCP_ROOTS is a start-directory allowlist, not a filesystem sandbox. The default agent=build already allows edit/bash tool calls non-interactively — OPENCODE_MCP_ALLOW_AUTO=1 is not required for that, it only adds --auto, which the CLI documents as "dangerous". Under either mode, every successful run is an autonomous coding agent with tool approval already on. It can read and write any path the invoking user can — including files outside the configured roots, e.g. ~/.ssh, ~/.zshrc, or other projects. The roots check only constrains where the child process starts; it does not confine the reads, writes, or shell commands the agent performs afterward. Grant roots, models, and network access on that understanding, and run untrusted prompts only where that blast radius is acceptable.

On timeout or abort the server force-signals the child process group and the child pid, then finalizes. A grandchild that re-sessions itself with setsid into its own process group can outlive that signal; the server reports the run as timed out/aborted, but such a detached descendant may keep running. Treat a timeout/abort as "stop waiting", not "guaranteed nothing is still executing".

How it works

src/index.ts is a thin MCP shell; the runtime logic lives in the shared, unpublished @mcp-coding-agents/core package and is bundled into dist/ at build time, so the installed package stays self-contained (its only runtime dependencies are the MCP SDK and zod).

• The runner spawns opencode detached in its own process group, so the whole subprocess tree is killed as a unit (SIGTERM → 5s grace → SIGKILL) on timeout, client abort, or a maxCostUsd breach. Process exit is the authoritative completion signal.
• The stream parser reads --format json output line-by-line without ever buffering the raw stream; assistant text is capped to head(40k)+tail(10k) chars past 50k total. Structured provider error events are preserved with their name/statusCode (see Changelog).
• A per-cwd queue serializes runs that share the same resolved cwd; different working trees run concurrently.
• The policy layer holds the cwd allowlist, model/session validation, secret redaction, and error classification.

For long runs, the server emits MCP progress notifications every 15s (when the client supplies a progress token), which resets the client's idle timeout.

Changelog

0.1.1

• Fixed: provider error events (rate-limit / overloaded / quota) were collapsed to "[object Object]", discarding the error name and HTTP status. They are now surfaced with their name and statusCode, so capacity and auth failures are reported distinctly instead of as an opaque error.
• Fixed: AI-SDK retry-exhaustion ("Failed after N attempts. Last error: …") is now unwrapped to a meaningful capacity/transport message instead of an opaque Unknown.
• Internal: shared logic extracted into @mcp-coding-agents/core (bundled; no change to the published dependency set or behavior otherwise).

0.1.0

• Initial release.

License

MIT