MIT Licensed · npm package available

Delegate work to AI subagents from any MCP host

An MCP server that lets any MCP host — Claude Code, Codex CLI, Cursor, and more — drive OpenCode instances and delegate tasks to AI subagents — asynchronously. Fire parallel tasks, poll for results, and orchestrate models like Opus and Fable without blocking.

$ claude mcp add opencode -- npx -y mcp-server-opencode
Get started View on GitHub
opencode-mcp

Architecture

How it works

Your MCP host delegates tasks through a clean pipeline. Each step is async — no blocking, no timeouts.

Any MCP Host

Claude Code, Codex CLI, Cursor…

MCP Server

opencode-mcp (this project)

OpenCode SDK

Sessions & async prompts

Subagents

Isolated AI workers

Async by design: opencode_start_task returns immediately with a task_id. No blocking. No MCP timeouts. Fire multiple tasks in parallel and poll for results when ready.

Features

Built for orchestration

Everything you need to delegate, parallelize, and manage AI subagent work from your MCP host.

Async Delegation

Fire-and-forget task creation. start_task returns instantly with a task_id — no blocking, no MCP timeouts.

Parallel Execution

Launch multiple tasks simultaneously. Each one opens an isolated OpenCode session — no interference between workers.

Isolated Sessions

Every task gets its own OpenCode session. Context stays clean, results stay separate, and failures don't cascade.

Status Polling

Check task progress anytime with get_task_status. Track pending, running, completed, or failed states.

Long-poll Wait

wait_for_task blocks efficiently until tasks finish. Supports "all" and "any" modes with configurable timeouts.

Server Lifecycle

Start, stop, and manage OpenCode server instances. List available agents and models. Clean shutdown with killAllServers() on exit.

Continue Conversation

Send follow-up prompts to an existing task's session. Iterative back-and-forth with subagents without starting a new session.

Cancel Tasks

Abort running tasks at any time with cancel_task. Clean session cancellation without leaving orphaned processes.

Tools

9 tools at your disposal

Every tool is registered as an MCP tool and available to your AI host immediately after setup.

Server lifecycle
Server

opencode_start_server

Start (or attach to) an OpenCode server instance.

Server

opencode_stop_server

Stop a running OpenCode server instance.

Server

opencode_list_agents

List agents/models available on a server instance.

Task delegation
Task

opencode_start_task CORE

Delegate a task to an agent by starting a new session and prompt. Optional agent / model override.

Task

opencode_continue_task

Send a follow-up prompt to an existing task's session for iterative back-and-forth with the subagent.

Task

opencode_cancel_task

Abort a running delegated task by cancelling its session.

pending
Task

opencode_get_task_status

Poll the status of a delegated task (pending / running / completed / failed). Optional include_progress adds partial output while running.

Task

opencode_get_task_result

Fetch the final result of a completed task.

Orchestration
pending
Wait

opencode_wait_for_task CORE

Long-poll one or more delegated tasks until they finish (mode: "all" or "any") or the timeout elapses. Optional include_progress enriches unfinished tasks with partial output. Server-side max configurable via MCP_TOOL_TIMEOUT (default: 300000 ms / 5 min).

Prompt

delegate_task

Guides the host through delegating one or more tasks to OpenCode agents — the full start/wait/result workflow in a single prompt.

Get started

Up and running in seconds

Install via npm or build from source. Works with Claude Code, Codex CLI, Cursor, and any MCP host. Requires Node.js 18+ and OpenCode on your PATH.

Claude Code — one command 
$ claude mcp add opencode -- npx -y mcp-server-opencode

Or add manually to your MCP config:

~/.claude.json 
{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "mcp-server-opencode"]
    }
  }
}
Codex — one command 
$ codex mcp add opencode -- npx -y mcp-server-opencode

Or add manually to ~/.codex/config.toml:

~/.codex/config.toml 
[mcp_servers.opencode]
command = "npx"
args = ["-y", "mcp-server-opencode"]
Terminal 
$ git clone https://github.com/alejandro-technology/opencode-mcp.git
$ cd opencode-mcp
$ pnpm install
$ pnpm build

Then point your MCP host at the built entrypoint:

mcp-config.json 
{
  "mcpServers": {
    "opencode": {
      "command": "node",
      "args": ["/path/to/opencode-mcp/build/src/index.js"]
    }
  }
}

Configuration

MCP_TOOL_TIMEOUT configures the server-side max for opencode_wait_for_task. Default: 300000 ms (5 min).

  • • Environment variable — set MCP_TOOL_TIMEOUT in your MCP server config's env block (takes precedence)
  • • CLI argument — pass MCP_TOOL_TIMEOUT=<ms> as an extra arg to the server process