Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
INIT_CWDNoFallback working directory for sessions when no directory is provided via the tool or MCP roots.
OPENCODE_URLNoThe OpenCode v2 server URL, e.g. http://127.0.0.1:4096.
OPENCODE_PASSWORDNoThe OpenCode Basic-auth password (username is always 'opencode').
CLAUDE_PROJECT_DIRNoFallback working directory for sessions when no directory is provided via the tool or MCP roots.
OPENCODE_MCP_TOKENNoBearer token for the HTTP transport; if unset, a token is generated at ~/.config/opencode-mcp/http-token.
OPENCODE_MCP_DIRECTORYNoFallback working directory for sessions when no directory is provided via the tool or MCP roots.
OPENCODE_MCP_ALLOWED_ROOTSNoAllowed 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

CapabilityDetails
tools
{
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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 files (path or data: URI). Set wait=false for fire-and-forget.

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 path (server-side file) or data (base64 bytes). When text is supplied the file is sent immediately as a prompt and the answer is returned; otherwise the attachment descriptor and stored path are returned for a later prompt.

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

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

B3.4/5.0

Scored across 18 tools

Disambiguation3/5

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.

Naming Consistency3/5

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.

Tool Count4/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessOutdated data