opencode-samcp

Sub-Agent MCP — an MCP server that lets an AI agent (Devin, Codex, Claude Code, Cursor, …) spawn opencode sessions as sub-agents and hand them coding work.

The parent agent calls opencode_run with a prompt and a directory; opencode does the work headlessly (opencode run --format json --auto) and the result comes back as structured data: final message, tool-call summary, errors, token usage and cost. Sessions can be continued, forked, run in parallel in the background, inspected and deleted.

Requirements

• opencode installed and authenticated (opencode on PATH, or set OPENCODE_BIN)
• uv (or pip install)

Install / run

The server is Python; every option below needs uv and opencode on the machine.

The npm package is a thin launcher: it bundles the Python server and runs it through uvx. If uv or opencode is missing, it exits with a clear "not installed on machine" error.

Configure your client

Devin

Settings → MCP Marketplace → Add Your Own (STDIO):

Devin runs in its own VM, so opencode must be installed and logged in there (add it to the machine setup / snapshot).

Codex (~/.codex/config.toml)

[mcp_servers.opencode]
command = "npx"
args = ["-y", "opencode-samcp"]

Claude Code

claude mcp add opencode -- npx -y opencode-samcp

Generic JSON

{ "mcpServers": { "opencode": { "command": "npx", "args": ["-y", "opencode-samcp"] } } }

HTTP transport

For clients that only speak remote MCP:

opencode-samcp --transport streamable-http --host 127.0.0.1 --port 8765   # endpoint: /mcp
opencode-samcp --transport sse ...                                         # endpoint: /sse

There is no authentication and the sub-agent can edit files and run commands — keep it on localhost or behind an authenticated tunnel/proxy.

Tools

Parallel work: start several jobs with wait_seconds=0, each in its own git worktree so they don't clash, then poll with opencode_job.

Environment variables

Security

auto_approve defaults to true (required for headless runs): the sub-agent can modify files and run shell commands in the given directory. Only expose this server to agents you trust, and point it at disposable checkouts/worktrees where possible.

Notes

• Job state is in-memory; it is lost when the server process restarts (opencode sessions themselves persist and can be resumed by session_id).

Publishing (maintainers)

Releases are automated: pushing a vX.Y.Z tag runs .github/workflows/publish.yml, which publishes to PyPI and npm (both via trusted publishing, no tokens). Use the helper so versions and tag never drift apart:

scripts/release.sh 0.0.4

It bumps pyproject.toml, package.json and uv.lock, runs the tests, commits, pushes main, then tags and pushes v0.0.4.

Development

uv run --group dev pytest

MIT licensed.