opencode-mcp-server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| INIT_CWD | No | Fallback working directory for sessions when no directory is provided via the tool or MCP roots. | |
| OPENCODE_URL | No | The OpenCode v2 server URL, e.g. http://127.0.0.1:4096. | |
| OPENCODE_PASSWORD | No | The OpenCode Basic-auth password (username is always 'opencode'). | |
| CLAUDE_PROJECT_DIR | No | Fallback working directory for sessions when no directory is provided via the tool or MCP roots. | |
| OPENCODE_MCP_TOKEN | No | Bearer token for the HTTP transport; if unset, a token is generated at ~/.config/opencode-mcp/http-token. | |
| OPENCODE_MCP_DIRECTORY | No | Fallback working directory for sessions when no directory is provided via the tool or MCP roots. | |
| OPENCODE_MCP_ALLOWED_ROOTS | No | Allowed roots for path access, blocking path escapes (symlink-safe). |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server drives a local OpenCode v2 instance. Start with opencode_status; if it is not configured, call opencode_configure with the server address and password. Sessions are created in the client's workspace by default. Use opencode_task for one-shot delegated work and opencode_session_* for persistent conversations.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| opencode_statusA | Report whether this MCP bridge is configured and connected to an OpenCode v2 server. Works even when nothing is configured, so it is the first tool to call when something looks wrong. |
| opencode_configureA | Set or repair the OpenCode v2 server address and password from inside the chat. The values are validated against GET /api/info before they are applied; nothing changes on failure. The password is never echoed back, is kept in memory by default, and is only written to disk when persist=true. Prefer configuring OPENCODE_URL and OPENCODE_PASSWORD in the MCP client settings when possible. |
| opencode_workspaceA | Report which directory sessions will use, where that choice came from (argument, MCP roots, env, config, cwd), or persist a new default. Use this before creating a session when you are unsure about the working directory. |
| opencode_session_createA | Create a new OpenCode session in a directory. Defaults to the client's current workspace. Use agent='build' for implementation work, 'plan' for planning, and 'general'/'explore' for subagents. Pass parentSessionID to create a child (subagent) session. |
| opencode_session_promptA | Send a message to a session and (by default) wait for the answer. Returns the assistant text, new turns, tool calls and usage. Attach files with |
| opencode_session_historyA | Read a session's messages and totals. Useful for inspecting what an agent did, auditing tool calls, or exporting a transcript to another client. |
| opencode_modelA | List models, read the default, and assign models at four levels: session (immediate API switch), project (opencode.json in the workspace), global (~/.config/opencode/opencode.json), agent (agents..model). Session assignment wins for that conversation; project/global change the default for new sessions. Config edits preserve JSONC comments and are verified against model/default. |
| opencode_permissionB | Headless runs block when OpenCode asks for permission. Use action=list to see pending requests and action=reply to approve or reject them. action=policy reports the bridge profile, or applies its ruleset to a session (approximate: OpenCode evaluates rules in order, so profiles are best-effort). |
| opencode_taskA | One-shot delegation: create a session in a workspace, send a prompt, wait for the result, and return the answer plus the subagent transcript. Use this for 'have OpenCode do X in this repo' requests; use opencode_session_* when you need a persistent conversation. |
| opencode_session_listA | List sessions, newest first. Filter by directory, search text, archive state, or parent session. |
| opencode_session_getB | Fetch one session's metadata: title, agent, model, cost, tokens, timestamps and outcome. |
| opencode_session_moveC | Change the working directory of an existing session. |
| opencode_session_deleteC | Delete a session and its messages. |
| opencode_session_interruptA | Stop the current run in a session. The session stays usable afterwards. |
| opencode_session_compactB | Summarize older turns to free context. Returns the compaction inbox item and token totals before/after when the service reports them. |
| opencode_agentA | List available agents (primary and subagent), switch the agent of a session, or delegate a one-shot task to a subagent. Delegation creates a real child session and returns its transcript. |
| opencode_file_attachA | Upload a file into a session. Provide |
| opencode_mcpA | Inspect and manage the MCP servers that OpenCode itself uses (not this bridge). Actions: list (servers + connection status), resources (tool/resource catalog), add (local or remote), remove, connect, disconnect. Server enablement is global per OpenCode project; per-session tool filtering is done with session permissions. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 18 tools
Session-level tools are clearly separable, but three tools converge on one-shot delegation: opencode_task, opencode_agent (delegate action), and opencode_session_prompt with wait=false all fire a prompt and return an answer. opencode_file_attach with `text` also silently turns into a prompt, and opencode_session_move overlaps conceptually with opencode_workspace. The descriptions do offer cross-references ('use opencode_session_* for persistent conversations'), which keeps it workable but not clean.
There is a solid opencode_session_<verb> sub-family (create, prompt, list, get, move, delete, interrupt, compact, history), but the remaining ten tools are bare nouns (opencode_status, opencode_workspace, opencode_agent, opencode_model, opencode_task, opencode_mcp) or noun-first (opencode_file_attach). The shared opencode_ prefix keeps things scannable, but the verb placement convention flips between families.
Eighteen tools is on the heavy side but the surface genuinely spans several sub-domains: session lifecycle, config/credentials, workspace, models, agents, permissions, files, and MCP management. Session operations account for nine of them, which is defensible for a chat-oriented bridge, though a couple (compact, move) feel like lower-frequency add-ons.
The session lifecycle is essentially fully covered (create/list/get/prompt/history/interrupt/compact/move/delete), plus config, model assignment, permissions, and file attachment. Minor gaps: sessions can be filtered by archive state but there is no tool to archive or rename/retitle a session, and there is no message-level retry or edit operation. These are workarounds-possible rather than blocking.