opencode-mcp
An MCP server for orchestrating OpenCode: it manages headless OpenCode server instances and delegates prompts to OpenCode agents asynchronously.
Start and stop headless OpenCode server instances, optionally choosing a port.
List available agents and models/providers on a running server.
Start delegated tasks/prompts on an OpenCode agent or model without waiting for completion.
Check task status and fetch final results for completed tasks.
Long-poll one or more tasks until all or any finish, or until a timeout elapses.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@opencode-mcp Delegate a task to OpenCode agent to optimize database queries"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
opencode-mcp
Keep your lead agent lean and save tokens by delegating heavy tasks to background subagents.
opencode-mcp is a Model Context Protocol (MCP) server that connects orchestrator hosts (Claude Code, Codex, Cursor, Antigravity, Pi) with OpenCode subagents. Instead of polluting your orchestrator's context window with large file reads, extensive search outputs, and repetitive test runs, you delegate those tasks to isolated subagents and receive only concise, structured results.
Why this matters (Context Window Economics)
π§ Prevent Context Rot & Bloat: Monolithic agents suffer reasoning degradation as the context fills up. Keeping your lead agent as an orchestrator preserves high reasoning quality.
π° Slash Token Costs: Running large exploratory reads or test-fix loops directly inside your primary (Fable/Opus, Astra/Sol) session repeatedly bills for thousands of cached tokens on every follow-up turn. Subagents run in isolated sessions using optimal models.
β‘ Asynchronous Parallel Execution: Dispatch multiple investigation or implementation tasks in parallel without blocking the orchestrator.
Quick install
Requires Node.js 18+ and OpenCode 1.x installed and configured (opencode must be on your PATH, with at least one provider/model set up) β this server spawns and drives OpenCode instances.
For Claude Code:
claude mcp add opencode -- npx -y mcp-server-opencodeFor Codex:
codex mcp add opencode -- npx -y mcp-server-opencodeSee Installation for manual config, and from-source options.
Related MCP server: opencode-cc-tool
Tools
Tool | Description |
| Start a new OpenCode server instance in the MCP process working directory |
| Stop a running OpenCode server instance |
| List agents/models available on a server instance (optional |
| Delegate a task to an agent by starting a new session and prompt (optional |
| Send a follow-up prompt to an existing task's session for iterative back-and-forth with the subagent |
| Abort a running delegated task by cancelling its session |
| Explicitly remove an owned Git worktree after task reports finalize; dirty worktrees require opt-in discard |
| Poll the status of a delegated task ( |
| Fetch the final result of a completed task |
| Long-poll one or more delegated tasks until they finish ( |
Delegation workflow and model-selection guidance are provided through the MCP server instructions.
How it works
Task delegation is asynchronous: opencode_start_task returns a task_id and run_id without waiting, so hosts can start tasks in parallel. Tasks use the selected directory by default; managed Git worktrees are optional. Poll for status and retrieve results separately. If dispatch is uncertain, use the returned IDs to check or cancel the task instead of retrying it.
Execution reports and caller checks
Start and continuation calls can include expected_changes and checks. Status and result responses report workspace changes, verification, diagnostics, and evidence; pass a run_id to retrieve a historical run. Workspace changes are best-effort evidence, since concurrent writers can make attribution uncertain.
Shared directories and managed worktrees
Tasks run in the selected existing directory (shared, the default), or in an isolated managed Git worktree based on a commit. Worktrees are kept after execution; use opencode_cleanup_workspace with its workspace_id after reports are finalized. Cleanup only removes worktrees managed by this server, and dirty worktrees require explicit discard.
Usage reporting
Status, wait, and result responses include run and session usage snapshots, with metrics broken down by provider and model. Missing metrics remain unknown rather than zero, and cost is OpenCode-reportedβnot an invoice total. Finalized runs retain their snapshots for historical retrieval.
Task, run, server, workspace, and usage records live in a SQLite database shared by every MCP process on the host (OPENCODE_MCP_HISTORY_DB overrides the location). Records survive restarts: retained worktrees are rediscovered for cleanup, and finalized runs remain retrievable by run_id.
Installation
Prerequisites
Node.js 18+
OpenCode 1.x installed and configured (
opencodemust be on yourPATH, with at least one provider/model set up) β this server spawns and drives OpenCode instances.
The current adapter uses the OpenCode v1 SDK/API and was validated against OpenCode 1.18.34 , 1.19.5. OpenCode 2.x is not yet supported.
Option 1 β npm (recommended)
The package is published as mcp-server-opencode. No cloning or building needed β point your MCP host at npx:
For Claude Code, one command does it:
claude mcp add opencode -- npx -y mcp-server-opencodeOr manually
{
"mcpServers": {
"opencode": {
"command": "npx",
"args": ["-y", "mcp-server-opencode"]
}
}
}For Codex, add the server to ~/.codex/config.toml:
[mcp_servers.opencode]
command = "npx"
args = ["-y", "mcp-server-opencode"]Or install it globally and use the binary directly:
npm install -g mcp-server-opencode{
"mcpServers": {
"opencode": {
"command": "opencode-mcp"
}
}
}Option 2 β from source
git clone https://github.com/alejandro-technology/opencode-mcp.git
cd opencode-mcp
pnpm install
pnpm buildThen point your MCP host at the built entrypoint:
{
"mcpServers": {
"opencode": {
"command": "node",
"args": ["/path/to/opencode-mcp/build/src/index.js"]
}
}
}Restart your MCP host after editing the config; the opencode_* tools should appear in its tool list.
Configuration
MCP_TOOL_TIMEOUT
opencode_wait_for_task accepts a timeout_ms input, but it's clamped to a server-side maximum so a single call stays inside the calling host's own MCP request timeout. That maximum defaults to 55000 ms and is configurable via MCP_TOOL_TIMEOUT.
The default is deliberately low: MCP hosts abort long tool requests with MCP error -32001: Request timed out before the tool can answer (observed on OpenCode hosts and the MCP Inspector at 100s+), so a graceful timed_out: true payload at 55s always beats a dead transport. Loop the wait β call opencode_wait_for_task again while timed_out is true β instead of raising timeout_ms. Raise this only when your host demonstrably tolerates longer tool requests.
MCP_TOOL_TIMEOUT can be set two ways:
Environment variable β set it in the MCP server config:
{ "mcpServers": { "opencode": { "command": "node", "args": ["/path/to/opencode-mcp/build/src/index.js"], "env": { "MCP_TOOL_TIMEOUT": "1200000" } } } }CLI argument β pass
MCP_TOOL_TIMEOUT=<ms>as an extra arg to the server process:{ "mcpServers": { "opencode": { "command": "node", "args": [ "/path/to/opencode-mcp/build/src/index.js", "MCP_TOOL_TIMEOUT=1200000" ] } } }
If both are present, the environment variable takes precedence over the CLI argument. Invalid or non-numeric values fall back to the 55000 ms default.
Permissions and trust
Headless tasks automatically answer permission prompts. Set OPENCODE_MCP_EXTERNAL_DIR to read-only (default), allow, or deny to control external-directory requests. An environment variable takes precedence over an OPENCODE_MCP_EXTERNAL_DIR=<policy> CLI argument; explicit OpenCode deny rules remain in effect.
Use this server only with trusted hosts and repositories. Git worktrees isolate source changes, not OS permissions: agents and caller-provided checks run as your local user, not in a security sandbox.
Development
Project structure
src/
βββ index.ts # MCP server entrypoint (stdio transport, shutdown handlers)
βββ modules/
βββ tools/ # One file per MCP tool, registered in index.ts
βββ shared/ # Cross-tool infrastructure (selected modules below)
βββ server-registry.ts # Tracks running OpenCode servers
βββ task-registry.ts # Task/session identity and per-run history
βββ opencode-client.ts # SDK clients, status derivation, and progress
βββ run-observer.ts # Background run finalization and result caching
βββ execution-report.ts # Workspace evidence and executable checks
βββ execution-usage.ts # Run/session usage aggregation
βββ workspace-manager.ts # Managed Git worktree lifecycle
βββ permissions.ts # Headless permission decisions and responses
βββ instructions.ts # Delegation workflow and model-selection guidance
βββ config.ts # MCP_TOOL_TIMEOUT resolution
βββ mcp-result.ts # JSON tool result helpersEach module ships with a *.test.ts Vitest suite under the parallel tests/ tree mirroring src/.
Getting started
Use Node.js 22.18+ for development and smoke tests (native TypeScript execution); CI checks Node.js 22 and 24. The published server retains its Node.js 18+ runtime requirement.
pnpm install
pnpm dev # runs the server through the MCP Inspector (tsx, no build needed)Other scripts:
pnpm test # vitest run
pnpm test:coverage # vitest run --coverage
pnpm lint # biome check
pnpm lint:write # biome check --write
pnpm build # clean tsc build to ./build (also the source typecheck)Real OpenCode smoke tests
The opt-in smoke harness starts a real OpenCode server and removes its temporary fixtures afterward. It is not part of default CI.
pnpm smoke --message-id-only # non-billable message-ID contract probe
pnpm smoke # full smoke; requires credentials and may incur model chargesThe full smoke covers reports, usage, continuation, cancellation, isolated worktrees, and cleanup. Its default model is openai/gpt-6-luna; override it with an exact enabled model ID:
OPENCODE_MCP_SMOKE_MODEL=provider/model pnpm smokeAvailable Tools
7 toolsopencode_get_task_resultB
Get the final result of a completed task
Inputs: task_id (required).
opencode_get_task_statusB
Get the current status of a delegated task
Inputs: task_id (required).
opencode_list_agentsA
List agents (native and custom) and available models/providers on an OpenCode server instance
Inputs: server_id (required).
opencode_start_serverB
Start a headless OpenCode server instance in the current working directory
Inputs: port.
opencode_start_taskB
Delegate a task to an OpenCode agent: create a session and start the prompt without waiting for it to finish
Inputs: prompt (required), server_id (required), agent, model.
opencode_stop_serverB
Stop a running OpenCode server instance
Inputs: server_id (required).
opencode_wait_for_taskA
Long-poll one or more delegated tasks until they finish or the timeout elapses. Use mode 'all' to wait for all tasks, or 'any' to return as soon as one completes.
Inputs: task_ids (required), mode, timeout_ms, poll_interval_ms.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 7 tools
Each tool targets a distinct action: server lifecycle (start/stop), task lifecycle (start, wait, get result, get status), and agent listing. No overlap or ambiguity.
All tools follow a consistent 'opencode_' prefix with verb_noun pattern (e.g., start_server, get_task_result). No mixing of conventions.
Seven tools cover core server and task management appropriately. Neither too sparse nor too bloated for the domain.
Covers server start/stop, agent listing, and task delegation with status/result retrieval. Missing a cancel_task or list_tasks tool, but core workflows are well-supported.
Related MCP Connectors
Hosted coding agent: start, follow up on and stop tasks that can open GitHub pull requests.
Authenticated async Opus 5.5 agent with status polling and artifact results.
Multiplayer for the coding agents your team already uses: shared tasks, decisions, skills and tools.
Task tracking built for coding agents. Work is leased, so two agents never take the same SubTask.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Codex to offload expensive code reading, editing, and checking to a worker agent via Claude Code, supporting async jobs and long-running tasks.MIT
- AlicenseAqualityBmaintenanceEnables Claude Code to dispatch opencode CLI tasks as background processes with immediate task handle return, status polling, and result retrieval, avoiding tmux and log parsing issues.613 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code and Claude Desktop to delegate coding tasks to any model available in OpenCode while Claude remains the orchestrator, planning work, reviewing diffs, and running tests. Supports synchronous and async delegation, model selection, session continuation, and permission-aware execution.6MIT
- AlicenseAqualityBmaintenanceEnables Claude Code to delegate software-engineering tasks to OpenCode agents working in the same workspace.727 npm1MIT