opencode-cli-mcp

by sandraschi

Overview Schema Source Related Servers Discussions Admin

Python

Local

OpenCode Runs

opencode_runs

Destructive

Manage opencode agent runs: start, poll status, list recent, or cancel.

Instructions

Manage opencode agent runs: start, poll status, list recent, or cancel.

Return Format

{"success": bool, "message": str, "data": dict} Fire-and-forget starts return a job_id; poll with action="status".

Examples

opencode_runs(action="start", prompt="Refactor main.py", wait=False) opencode_runs(action="start", prompt="Fix tests", model="deepseek/deepseek-flash", agent="build", auto=True) opencode_runs(action="start", prompt="Continue", session_id="ses_123", fork=True) opencode_runs(action="status", job_id="abc123") opencode_runs(action="list", limit=20, offset=0)

Input Schema

Name	Required	Description	Default
`auto`	No	Auto-approve permissions not explicitly denied (start, opencode --auto). Needed for unattended runs; without it a prompt stalls the run.
`fork`	No	Fork before continuing; requires session_id or continue_session (start)
`wait`	No	Block until done (start; default false = fire-and-forget)
`agent`	No	opencode agent name, e.g. 'build' or 'plan' (start)
`files`	No	Files to attach to the message (start). Must exist on disk.
`limit`	No	Page size (list)
`model`	No	Model as provider/model, e.g. 'deepseek/deepseek-flash' (start). Default: opencode's
`action`	Yes	start: launch an agent run. status: poll a run. list: recent runs. cancel: stop a run.
`job_id`	No	Job ID (required for status/cancel)
`offset`	No	Page offset (list)
`prompt`	No	Agent prompt (required for start)
`project`	No	Project directory (optional, start)
`timeout`	No	Max seconds for the run (start)
`variant`	No	Provider reasoning variant, e.g. 'high', 'max', 'minimal' (start)
`thinking`	No	Include thinking blocks in output (start)
`session_id`	No	Continue this session instead of a new one (start)
`output_format`	No	Output format (start)	text
`continue_session`	No	Continue the most recent session (start; ignored when session_id is set)

Output Schema

Name	Required	Description	Default
`data`	Yes
`message`	Yes
`success`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedv0.2.11Oct 21, 2026

addedInput schema / properties / agent

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "opencode agent name, e.g. 'build' or 'plan' (start)"
+}

addedInput schema / properties / auto

Added value: +{
+  "default": false,
+  "description": "Auto-approve permissions not explicitly denied (start, opencode --auto). Needed for unattended runs; without it a prompt stalls the run.",
+  "type": "boolean"
+}

addedInput schema / properties / continue_session

Added value: +{
+  "default": false,
+  "description": "Continue the most recent session (start; ignored when session_id is set)",
+  "type": "boolean"
+}

addedInput schema / properties / files

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Files to attach to the message (start). Must exist on disk."
+}

addedInput schema / properties / fork

Added value: +{
+  "default": false,
+  "description": "Fork before continuing; requires session_id or continue_session (start)",
+  "type": "boolean"
+}

addedInput schema / properties / model

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Model as provider/model, e.g. 'deepseek/deepseek-flash' (start). Default: opencode's"
+}

addedInput schema / properties / session_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Continue this session instead of a new one (start)"
+}

addedInput schema / properties / thinking

Added value: +{
+  "default": false,
+  "description": "Include thinking blocks in output (start)",
+  "type": "boolean"
+}

addedInput schema / properties / variant

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Provider reasoning variant, e.g. 'high', 'max', 'minimal' (start)"
+}

removedOutput schema / additionalProperties
```
Removed value: -true
```

addedOutput schema / properties

Added value: +{
+  "data": {
+    "type": "object"
+  },
+  "message": {
+    "type": "string"
+  },
+  "success": {
+    "type": "boolean"
+  }
+}

addedOutput schema / required

Added value: +[
+  "success",
+  "message",
+  "data"
+]

First observedv0.2.3Aug 5, 2026

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds useful async semantics (fire-and-forget returns job_id, poll to retrieve results) and a return-shape hint, but it never mentions that cancel terminates a running agent or what auto/timeout imply behaviorally beyond the schema text.

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 purpose line is front-loaded and the return-format block is compact. Five examples is on the generous side for an 18-parameter tool, but each demonstrates a distinct action or flag combination, so they largely earn their space.

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

Completeness4/5

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

An output schema exists, making the explicit return-format block somewhat redundant, and the async polling note plus examples cover the main calling patterns. The only real gap is the absence of any guidance distinguishing this tool from the single-action siblings that cover the same ground.

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 baseline is 3 regardless of description content. The examples do add value by showing which parameters pair with which action (model/agent/auto with start, job_id with status, limit/offset with list), but no format or constraint detail beyond the schema.

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

Purpose4/5

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

The description states specific verbs and the resource: 'start, poll status, list recent, or cancel' agent runs, and the action enum is labeled accordingly. It does not, however, distinguish this tool from direct siblings that appear to do the same individual jobs (opencode_run_agent, opencode_get_run_status, opencode_list_runs, opencode_cancel_run), so an agent has no signal for when to pick this multi-action tool over the narrow ones.

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?

Workflow guidance is implied through the note that fire-and-forget starts return a job_id which you poll with action="status", and the examples demonstrate realistic call shapes. There is no explicit when-to-use/when-not statement and no mention of the sibling alternatives, leaving the routing decision to inference.

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