Skip to main content
Glama
alejandro-technology

opencode-mcp

by alejandro-technology
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

opencode-mcp

CI coverage npm

An MCP (Model Context Protocol) server that lets any MCP host — Claude Code, Codex, Cursor, etc. — drive an OpenCode instance and delegate work to its subagents — so orchestrator models like Opus or Fable can hand off tasks to the other models OpenCode exposes.

Quick install

Requires Node.js 18+ and OpenCode 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-opencode

For Codex:

codex mcp add opencode -- npx -y mcp-server-opencode

See Installation for manual config, and from-source options.

Related MCP server: opencode-cc-tool

Tools

Tool

Description

opencode_start_server

Start a new OpenCode server instance in the MCP process working directory

opencode_stop_server

Stop a running OpenCode server instance

opencode_list_agents

List agents/models available on a server instance (optional directory selects a project)

opencode_start_task

Delegate a task to an agent by starting a new session and prompt (optional agent / model override)

opencode_continue_task

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

opencode_cancel_task

Abort a running delegated task by cancelling its session

opencode_cleanup_workspace

Explicitly remove an owned Git worktree after task reports finalize; dirty worktrees require opt-in discard

opencode_get_task_status

Poll the status of a delegated task (pending / running / completed / failed / empty / cancelled); optional include_progress adds a partial output snippet and the currently running tool while it's still running

opencode_get_task_result

Fetch the final result of a completed task

opencode_wait_for_task

Long-poll one or more delegated tasks until they finish (mode: "all" or "any") or the timeout elapses; optional include_progress best-effort enriches unfinished tasks within the same deadline, falling back to the last observed status/progress when time runs out

Prompt

Description

delegate_task

Guides the host through delegating one or more tasks to OpenCode agents (start/wait/result workflow), including a model selection guide that maps each OpenCode model tier to the task difficulty it should handle

How it works

opencode mcp architecture

Task delegation is asynchronous: starting a task returns immediately with a task_id instead of blocking until the subagent finishes. This lets hosts fire multiple opencode_start_task calls in parallel — each opens an isolated OpenCode Session — without hitting MCP client timeouts on long-running work. Tasks use the selected directory directly by default; managed Git worktrees are an explicit opt-in. Status and results are fetched separately via polling. If the prompt ACK transport is lost after OpenCode may have accepted the request, the tool returns dispatch_uncertain with task/run IDs and retains its lease; poll that task or cancel it rather than retrying the prompt as a new task. Definite HTTP 4xx rejection rolls back provisional run state and lease.

Each accepted start or continuation prompt also receives a run_id. Status, progress, and results are scoped to that prompt's explicit message ID, while progress evidence remains cumulative across turns in the same run. empty and cancelled are terminal outcomes. A cancelled task can be continued; the accepted continuation becomes the current run and clears the previous cancellation state. Concurrent continuation dispatches for the same task are rejected with dispatch_in_progress.

OpenCode 1.18.34 requires caller message IDs to start with msg; the MCP uses msg_${randomUUID()} for both start and continuation prompts. The opt-in harness also probes a bare UUID through the installed SDK/runtime using an invalid provider/model so the identifier contract can be checked without a paid request.

Execution reports and caller checks

opencode_start_task and opencode_continue_task accept optional expected_changes ([{ path, change }], where change is created, modified, or deleted) and checks ([{ executable, argv, cwd?, timeout_ms? }]). Paths and check working directories are relative to the server workspace; checks run directly with shell: false. Reports are additive on status/result as run_id, changes, verification, diagnostics, and evidence. opencode_get_task_result and opencode_get_task_status accept an optional run_id to retrieve a historical run; omitted means the current run.

Shared directories and managed worktrees

opencode_start_task accepts directory (relative to the server directory, defaulting to it), workspace_mode (shared by default or worktree), and base_ref (worktree mode only, default HEAD). The selected directory must already exist. Shared mode runs directly in that canonical directory. Worktree mode creates a unique detached Git worktree at the selected committed ref; source modifications and untracked files are neither copied nor altered. When the selected base does not contain the requested nested source directory, the request fails instead of silently changing the execution directory.

Start, status, result, wait, and historical-run payloads expose a workspace object with source and execution directories, mode, managed state, and (for worktrees) workspace_id, base commit, source dirty state, and lifecycle state. SDK requests are bound to the selected directory through OpenCode's directory routing. Permission responders are keyed by server and canonical directory and answer only sessions registered to that scope.

Accepted worktrees are retained after task completion. Call opencode_cleanup_workspace with the returned workspace_id after reports are finalized. Cleanup serializes against task continuation/dispatch, rejects unfinished reports and dirty worktrees, and removes only worktrees provisioned by this MCP process. Set discard_changes: true only when changes inside that owned worktree should be discarded. Cleanup never removes source files; cached results, usage, and historical runs remain readable after the worktree is removed.

Usage reporting

Status, wait, and result payloads include an additive usage snapshot. Its run summary selects direct assistant messages whose parentID matches that run's user-message ID; session summarizes all direct assistant messages observed in the session snapshot. Neither includes descendants or separate subagent sessions. Per-provider/model breakdowns preserve raw input, output, reasoning, cache-read, cache-write, and OpenCode-reported cost independently; token categories are not combined into a potentially overlapping total. Step-finish part metrics are excluded.

Each metric has a nullable value, complete flag, and missing_messages count. Missing, invalid, or negative values remain unknown; explicit zero is known. Empty snapshots do not claim zero consumption. Cost is labeled as OpenCode-reported, with currency unspecified; it is not an invoice total. captured_at and snapshot_kind identify the observation. A finalized run caches its own run and session snapshot, so retrieving an older run_id after a continuation returns the historical session snapshot from that run's finalization—not a current cumulative total. Failed message reads return report: null with a diagnostic.

The MCP server captures a bounded workspace inventory before accepted dispatch and after execution. The inventory recursively hashes workspace files except .git and node_modules; caller-declared expected paths are also checked explicitly, including paths inside otherwise skipped directories. Created/untracked, modified (including pre-existing dirty files changed since baseline), deleted, binary, and symlink entries are reported. Changes are labeled workspace_delta: concurrent or unmanaged writers can still make attribution uncertain. A verified run holds an exclusive lease across the canonical workspace and overlapping directories; it blocks verified and ordinary MCP task writers and conflicts fail fast with workspace_busy. Ordinary unverified runs may share a workspace. session.diff is not used as task provenance. Capture errors, missing expected changes, and scope limits are disclosed. opencode_wait_for_task supports until: "execution" (default) or until: "report"; report waits end on finalized failed, unavailable, or cancelled reports while respecting the whole-call timeout.

Each accepted run retains its own baseline, criteria, lease, result, report, and finalized usage snapshot. Checks are executed once by the background lifecycle observer after terminal execution. Their result includes exit code/signal, duration, bounded output and exact truncation flags; timeout/cancellation terminates the child process group. Verification may be not_requested, pending, running, passed, failed, unavailable, or cancelled; execution success alone does not mean verification passed. Final task text/progress, reports, and usage snapshots are cached, so result queries do not rerun checks and historical results remain available after a continuation or backend removal. Workspace inventories are capped at 20,000 entries and 32 MiB of file content; check output is capped at 16 KiB per stream. These limits and shared-workspace attribution mean the report is evidence, not proof of exclusive authorship.

Run the opt-in real OpenCode stdio smoke harness with pnpm smoke. It uses only openai/gpt-6-luna for its paid prompts, creates and removes temporary fixtures, and checks real reports/usage, historical retrieval, no-change and cancellation continuations, two detached worktrees editing the same relative file independently, an external read permission in a scoped worktree session, continuation in that worktree, dirty-cleanup refusal, explicit discard, and cached history after removal. The no-model identifier probe is also runnable with node --experimental-strip-types scripts/smoke.ts --message-id-only. The paid smoke is intentionally not part of default CI because it requires configured credentials.

Installation

Prerequisites

  • Node.js 18+

  • OpenCode installed and configured (opencode must be on your PATH, with at least one provider/model set up) — this server spawns and drives OpenCode instances.

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-opencode

Or 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 build

Then 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 can't block the MCP connection indefinitely. That maximum defaults to 300000 ms (5 minutes) and is configurable via MCP_TOOL_TIMEOUT.

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 300000 ms default.

Development

Project structure

src/
├── index.ts                   # MCP server entrypoint (stdio transport, shutdown handlers)
└── modules/
    ├── tools/                 # One file per MCP tool, registered in index.ts
    ├── prompts/               # One file per MCP prompt, registered in index.ts
    └── shared/                # Cross-tool infrastructure
        ├── server-registry.ts   # Tracks running OpenCode servers; killAllServers() on shutdown
        ├── task-registry.ts     # Maps task_id → OpenCode server + session
        ├── opencode-client.ts   # Builds SDK clients from the registries
        ├── config.ts            # MCP_TOOL_TIMEOUT resolution (env var / CLI arg)
        └── mcp-result.ts        # jsonResult / jsonError MCP output helpers

Each module ships with a *.test.ts Vitest suite under the parallel tests/ tree mirroring src/.

Getting started

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 typecheck)

Available Tools

7 tools
opencode_get_task_resultB

Get the final result of a completed task

NameRequiredDescriptionDefault
task_idYesId of the task to fetch the result for

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Does not disclose behavior for edge cases like non-existent task or incomplete task, nor any authorization requirements. Without annotations, the agent is left guessing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words, but could be slightly expanded without losing conciseness to add useful context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description omits critical details about return format and preconditions for using this tool on a completed task.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers the single parameter (task_id) with a description. The tool description adds no extra meaning beyond restating the purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the verb 'Get' and resource 'final result of a completed task', distinguishing it from sibling tools like get_task_status, start_task, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no explicit guidance on when to use this tool vs alternatives like wait_for_task, or when not to use it (e.g., if task is incomplete).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

opencode_get_task_statusB

Get the current status of a delegated task

NameRequiredDescriptionDefault
task_idYesId of the task to check

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must fully cover behavioral aspects. It only states 'get the current status' without explaining return behavior, error handling, whether it is a one-shot query or requires polling, or any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words. It could be slightly more informative but remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. However, it lacks details on possible status values, whether the call is idempotent, or prerequisites, leaving some questions for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers the single parameter task_id with a description ('Id of the task to check'), achieving 100% schema coverage. The description adds no extra meaning beyond the schema, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and the resource ('current status of a delegated task'), distinguishing it from sibling tools like opencode_get_task_result which retrieves results, and opencode_wait_for_task which is for waiting.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as opencode_wait_for_task or opencode_get_task_result. Usage context is entirely implied with no explicit when-to or when-not-to instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

opencode_list_agentsA

List agents (native and custom) and available models/providers on an OpenCode server instance

NameRequiredDescriptionDefault
server_idYesId of the server instance to query

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description only indicates a listing operation. It does not disclose behavioral traits such as read-only status, permission requirements, or error scenarios.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no extraneous words. It efficiently conveys the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple listing tool, the description is adequate but lacks completeness: no output schema and no mention of what the response contains or error handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully describes the single parameter. The description adds no additional meaning beyond what is in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists agents and models/providers on a server, using a specific verb and resource. It is distinct from sibling tools which focus on tasks and server lifecycle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for querying a server's agents and models, but offers no explicit guidance on when to use vs alternatives, nor prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

opencode_start_serverB

Start a headless OpenCode server instance in the current working directory

NameRequiredDescriptionDefault
portNoPort to bind the server on (default 4096)

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries full burden. It only mentions 'headless' and 'in the current working directory', but lacks detail on blocking vs async, return behavior, or failure conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words, front-loaded with action. Could be slightly more structured but efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Missing vital context for a server-starting tool: no info on return value, async behavior, prerequisites, or error handling. Incomplete despite low complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers the single parameter 'port' with description and default, so description adds no extra meaning beyond schema; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'Start' and resource 'headless OpenCode server instance', clearly distinguishing from sibling tools like opencode_stop_server and opencode_start_task.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, no prerequisites or context about server state (e.g., whether it can be restarted).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

opencode_start_taskB

Delegate a task to an OpenCode agent: create a session and start the prompt without waiting for it to finish

NameRequiredDescriptionDefault
agentNoAgent name to delegate to (e.g. 'build')
modelNoModel as 'providerID/modelID' (e.g. 'anthropic/claude-sonnet-4')
promptYesPrompt/instructions for the agent
server_idYesId of the server instance to run the task on

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It states the tool creates a session and starts the prompt asynchronously, but fails to mention return values (e.g., task ID), error conditions, authorization needs, or side effects. This leaves significant gaps for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the core action and async behavior. Every word contributes to understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no annotations and no output schema, the description does not explain prerequisites, error handling, or the format of the return value (e.g., a session ID). For a 4-parameter tool handling delegation, more contextual completeness is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the parameter descriptions in the schema. It does not clarify how to obtain the server_id or agent name, which would be helpful context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Delegate a task to an OpenCode agent: create a session and start the prompt without waiting for it to finish'. It uses a specific verb ('Delegate') and resource ('task to an OpenCode agent'), and clearly distinguishes from siblings like opencode_wait_for_task by noting the asynchronous nature.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when you want to start a task without waiting, contrasted with opencode_wait_for_task, but does not explicitly state when to use or avoid this tool. It omits prerequisites such as needing a running server (see opencode_start_server) or valid agent (opencode_list_agents).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

opencode_stop_serverB

Stop a running OpenCode server instance

NameRequiredDescriptionDefault
server_idYesId of the server instance to stop

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It only states 'Stop', but does not explain what stopping entails (e.g., immediate termination, impact on tasks, state changes). The minimal description is insufficient for the agent to understand side effects or prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It is appropriately concise for a simple tool, though slightly under-specified. A 5 would require more informative context without verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (1 required param, no output schema), the description still lacks completeness. It does not mention return behavior, error conditions, or prerequisites (e.g., server must be running). The sibling list indirectly provides context, but the description alone is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (one parameter with a description). The tool description does not add extra meaning beyond 'server_id' as the identifier. Baseline 3 is appropriate as the schema already documents the parameter adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Stop') and target ('running OpenCode server instance'). It is specific and distinguishes from siblings like opencode_start_server, which is the inverse operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing to stop a server, but provides no explicit guidance on when to use versus alternatives (e.g., opencode_start_server) or when not to use. Sibling names offer some context, but the description does not clarify.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

NameRequiredDescriptionDefault
modeNo'all': return when all tasks finish, 'any': return when one finishesall
task_idsYesIDs of tasks to wait for
timeout_msNoMax time to wait in milliseconds (default 120000)
poll_interval_msNoTime between status checks in milliseconds (default 2500)

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It mentions long-polling and timeout but lacks details on what happens on timeout (e.g., error, null return), error handling, and concurrency behavior. The polling interval is not addressed in the description, only in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences, covering the core purpose and modes without waste. Every sentence adds value, making it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, no output schema, and no annotations, the description is somewhat incomplete. It explains the waiting behavior and modes but does not describe the return type or error conditions. The agent would need additional context to fully understand the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds minimal value beyond the schema: it repeats the mode enum values and implies timeout, but does not explain poll_interval_ms or provide additional context for task_ids. The description does not significantly enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to long-poll one or more delegated tasks until completion or timeout. It distinguishes from siblings like opencode_get_task_status (single check) and opencode_get_task_result (retrieve results after completion), showing it's for waiting.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use this tool (to wait for task completion) and describes two modes (all and any), providing clear context. However, it does not explicitly state when not to use it or mention alternatives, leaving minor room for improvement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv1.0.0
    • First observedopencode_get_task_result
    • First observedopencode_get_task_status
    • First observedopencode_list_agents
    • First observedopencode_start_server
    • First observedopencode_start_task
    • First observedopencode_stop_server
    • First observedopencode_wait_for_task
Deploy Server
Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A3.7/5.0

Scored across 7 tools

Disambiguation5/5

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.

Naming Consistency5/5

All tools follow a consistent 'opencode_' prefix with verb_noun pattern (e.g., start_server, get_task_result). No mixing of conventions.

Tool Count5/5

Seven tools cover core server and task management appropriately. Neither too sparse nor too bloated for the domain.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches