opencode-cli-mcp

by sandraschi

Overview Schema Source Related Servers Discussions Admin

Python

Local

opencode_run_agent

Run an opencode agent with a prompt, model, agent, and permission mode.

Instructions

Run an opencode agent with a prompt, model, agent, and permission mode.

Launches as background job; returns job_id for polling. Set wait=true to block until done. Unattended runs usually need auto=true - otherwise a permission prompt stalls the run until the timeout.

Return Format

{"success": bool, "message": str, "data": {"job_id": str, "status": str, "options": dict}}

Examples

opencode_run_agent(prompt="Refactor main.py", wait=False) opencode_run_agent(prompt="Summarize README", format="json", wait=True, timeout=120) opencode_run_agent(prompt="Fix tests", model="deepseek/deepseek-flash", agent="build", auto=True) opencode_run_agent(prompt="Continue the migration", session_id="ses_123", fork=True)

Input Schema

Name	Required	Description	Default
`auto`	No	Auto-approve permissions that are not explicitly denied (opencode --auto). Required for unattended runs that would otherwise block on an approval prompt.
`fork`	No	Fork the session before continuing (requires session_id or continue_session)
`wait`	No	Wait for completion (true) or return immediately with job_id (false)
`agent`	No	Agent to use (opencode agent name, e.g. 'build' or 'plan'). Omit for the default agent
`files`	No	File paths to attach to the message (opencode --file). Must exist on disk.
`model`	No	Model as provider/model (e.g. 'deepseek/deepseek-flash'). Omit for opencode's default
`format`	No	Output format: 'text' or 'json'	text
`prompt`	Yes	The prompt/message to send to the opencode agent
`project`	No	Project directory path (optional)
`timeout`	No	Max seconds to wait when wait=true (default 300)
`variant`	No	Provider-specific reasoning variant, e.g. 'high', 'max', 'minimal'
`thinking`	No	Include thinking blocks in the output
`session_id`	No	Continue this session instead of starting a new one (opencode --session)
`continue_session`	No	Continue the most recent session (opencode --continue); ignored when session_id is set

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv0.2.11Oct 21, 2026

addedInput schema / properties / agent

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

addedInput schema / properties / auto

Added value: +{
+  "default": false,
+  "description": "Auto-approve permissions that are not explicitly denied (opencode --auto). Required for unattended runs that would otherwise block on an approval prompt.",
+  "type": "boolean"
+}

addedInput schema / properties / continue_session

Added value: +{
+  "default": false,
+  "description": "Continue the most recent session (opencode --continue); 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": "File paths to attach to the message (opencode --file). Must exist on disk."
+}

addedInput schema / properties / fork

Added value: +{
+  "default": false,
+  "description": "Fork the session before continuing (requires session_id or continue_session)",
+  "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'). Omit for opencode's default"
+}

addedInput schema / properties / session_id

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

addedInput schema / properties / thinking

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

addedInput schema / properties / variant

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

changedOutput schema / (root)

Previous value: -{
-  "additionalProperties": true,
-  "type": "object"
-}New value: +null

First observedv0.2.3Aug 5, 2026

TDQS

A4.3/5.0

Behavior5/5

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

The only annotation is readOnlyHint=false, so the description must carry the behavioral load and it does: asynchronous background execution, job_id polling contract, wait/timeout interaction, and the specific unattended-run stall risk from permission prompts. It also spells out the return envelope (success/message/data.job_id/status/options), which the annotations do not cover at all.

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?

Front-loaded correctly: purpose and launch semantics come first, then the unattended-run caveat, then a clearly headed Return Format block, then examples. Each of the four examples demonstrates a distinct parameter combination rather than repeating the same call, so the length is justified. It is still a fairly long block for a tool whose core contract fits in two sentences.

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

Completeness5/5

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

For a 14-parameter mutation tool with no output schema, the description supplies the missing return shape, the async lifecycle entry point, and the timeout/permission pitfall that would otherwise cause silent failures. An agent can construct a correct call and know how to follow up on the job_id from the description alone; remaining gaps (status vocabulary, cancellation via opencode_cancel_run) are minor and covered by siblings.

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

Parameters4/5

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

Schema coverage is 100%, so a 3 is the baseline and the schema already explains each of the 14 parameters. The description adds compositional meaning the schema cannot convey: the wait/timeout pairing, auto=true as the fix for unattended stalls, and worked examples showing session_id+fork and model+agent+auto together. It does not clarify the relationship between continue_session and fork or what status values appear in data.status.

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 first line names a specific verb and resource ('Run an opencode agent') plus the key knobs (prompt, model, agent, permission mode), and the second line clarifies that it launches a background job returning a job_id. This implicitly separates it from the polling siblings (opencode_get_run_status, opencode_list_runs), but no sibling is ever named, so the differentiation is inferential rather than explicit.

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?

It gives concrete conditional guidance: set wait=true to block, unattended runs usually need auto=true or a permission prompt will stall the run until timeout. That is real when-to-use advice tied to failure modes. It stops short of a 5 because it never says when to prefer opencode_send_message (continue an existing session) or opencode_launch_ui over starting a new agent run, even though session_id/continue_session/fork make that choice relevant.

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