🧰 Tools
The tools mcp-opencode exposes — query a model, list models, and talk to a live opencode session.
mcp-opencode exposes five tools: query and list_models for one-off
questions, and list_sessions, send and read for holding a conversation with
a live opencode session.
⚡ query
Send a prompt to an opencode model and return the response.
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | yes | The prompt to send. |
model | string | no | Model in provider/model format. Defaults to github-copilot/gpt-4.1. |
Each call creates a temporary opencode session, sends the prompt, returns the text response, and deletes the session. If the requested model is blocked by your allow/block filters, the call returns an error explaining the model isn't allowed — see Model filtering.
The tool description surfaced to your assistant includes the default model and a summary of the active filters, so the assistant always knows what's available.
🔍 list_models
List the models available for use.
| Parameter | Type | Required | Description |
|---|---|---|---|
provider | string | no | Provider name to filter by (e.g. anthropic, openai). Omit for all. |
Returns one provider/model ID per line. The list reflects your opencode
configuration — exactly what opencode models prints in your terminal — passed
through your allow/block filters. Pass a provider to narrow the list to a
single provider.
If no models match (for example, an unknown provider name), the tool returns a
clear No models found message rather than an empty response.
🗂️ list_sessions
List the sessions across every discovered opencode window, most recently
updated first. Windows are found automatically: any opencode started with
--port on this machine.
| Parameter | Type | Required | Description |
|---|---|---|---|
directory | string | no | Only list sessions for this project directory. |
Returns one session per line: ID, title, directory, the port(s) of the windows it is open in, and last update. Use it to find the session you have open in the opencode TUI.
💬 send
Send a message to an existing session and return its reply.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session ID from list_sessions. |
prompt | string | yes | The message to send. |
agent | string | no | opencode agent to handle the message (e.g. build, plan). |
port | number | no | Window to use. Defaults to the window that owns the session (lowest port if several). |
timeout_seconds | number | no | How long to wait for the reply. Defaults to MCP_OPENCODE_SEND_TIMEOUT (600). |
The session keeps its history and its own model, and the exchange appears live
in any TUI attached to the same server. send never creates or deletes a
session. Model allow/block filters don't apply here: the session already has
its model.
If the reply takes longer than the timeout, send returns a "still running"
note instead of hanging. opencode keeps working; call read later for the
answer.
📜 read
Read a session's recent messages as a condensed transcript.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session ID from list_sessions. |
limit | number | no | Number of most recent messages to return. Default 20. |
port | number | no | Window to read from. Defaults to the one that owns the session. |
Each message is headed by its role, with text in full and tool calls summarised
as [tool: name (status)].