Skip to main content
Glama

opencode-mcp-server

An MCP server that exposes a running OpenCode v2 instance to any MCP client — Codex, Claude Code, Claude Desktop, Anti-Gravity, Cursor, or your own agent. Sessions, inference, agents, files, MCP servers and history all become tools in the client's chat.

The bridge does not reimplement anything: it translates MCP tool calls into OpenCode v2 API calls through the official @opencode/client SDK.

Codex / Claude / Anti-Gravity  ──MCP──▶  opencode-mcp-server  ──@opencode/client──▶  OpenCode v2 (:4096)

Requirements

  • Node.js ≥ 20

  • A running OpenCode v2 server (opencode serve, or the TUI) — v1 is rejected on purpose

  • The server address and password (username is always opencode)

Related MCP server: opencode-mcp

Setup

The bridge needs two values:

OPENCODE_URL       e.g. http://127.0.0.1:4096
OPENCODE_PASSWORD  the OpenCode Basic-auth password

Find the password in ~/.config/opencode/service.json (or ~/.local/state/opencode/service.json).

Install / run

No npm release required — this runs straight from GitHub:

npx -y github:shivrajansingh/opencode-mcp-server --help

Pin to a release or commit for stability: github:shivrajansingh/opencode-mcp-server#v0.1.0.

Option A — configure once, from the terminal

npx -y github:shivrajansingh/opencode-mcp-server configure --url http://127.0.0.1:4096
# prompts for the password without echoing it, validates it, writes ~/.config/opencode-mcp/config.json (0600)

Check it:

npx -y github:shivrajansingh/opencode-mcp-server status

Option B — configure in the MCP client

# ~/.codex/config.toml
[mcp_servers.opencode]
command = "npx"
args = ["-y", "github:shivrajansingh/opencode-mcp-server"]
env = { OPENCODE_URL = "http://127.0.0.1:4096", OPENCODE_PASSWORD = "…" }
# Claude Code
claude mcp add opencode -e OPENCODE_URL=http://127.0.0.1:4096 -e OPENCODE_PASSWORD=… \
  -- npx -y github:shivrajansingh/opencode-mcp-server
// Claude Desktop / Anti-Gravity MCP config
{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "github:shivrajansingh/opencode-mcp-server"],
      "env": { "OPENCODE_URL": "http://127.0.0.1:4096", "OPENCODE_PASSWORD": "…" }
    }
  }
}

Option C — configure from the chat

Start the server with no credentials. It still lists its tools and opencode_status explains what is missing. Then ask the model to call:

opencode_configure({ "url": "http://127.0.0.1:4096", "password": "…" })

Values are validated before they are applied, the password is never echoed, and nothing is written to disk unless you pass persist: true.

Precedence

runtime (opencode_configure) → environment → ~/.config/opencode-mcp/config.json → unconfigured. There is no silent auto-discovery; --discover exists for development only.

Tools (18)

Tool

What it does

opencode_status

Health, version, workspace, agents, default model. Works while unconfigured.

opencode_configure

Validate and apply URL + password in-chat.

opencode_workspace

Show/persist the working directory, list MCP roots.

opencode_session_create

New session in a directory (agent, model, parent, permissions).

opencode_session_list

List sessions by directory/search/archive/parent.

opencode_session_get

Session metadata, tokens, cost.

opencode_session_move

Change a session's directory.

opencode_session_delete

Delete a session.

opencode_session_interrupt

Stop the current run.

opencode_session_compact

Summarize history to free context.

opencode_session_prompt

Prompt with text + files, wait for the answer, return tools/usage.

opencode_session_history

Messages as JSON or markdown transcript.

opencode_model

List models, read the default, assign at session/project/global/agent scope.

opencode_agent

List agents, switch agent, delegate to a subagent.

opencode_task

One-shot delegation: create session → prompt → wait → return transcript.

opencode_file_attach

Attach a path or base64 bytes to a session (optionally prompt immediately).

opencode_mcp

Inspect/add/connect/remove OpenCode's own MCP servers.

opencode_permission

List/reply to permission requests (required for headless runs).

--profile minimal registers 9 tools: status, configure, workspace, session create/prompt/history, model, task, permission.

Model assignment

Four levels, all through opencode_model:

Scope

Call

Effect

Storage

Session

{ action:"set", sessionID, model }

immediate switch for that conversation

OpenCode DB

Project

{ action:"set", scope:"project", directory, model }

default for new sessions in that workspace

opencode.json (comments preserved)

Global

{ action:"set", scope:"global", model }

default everywhere

~/.config/opencode/opencode.json

Agent

{ action:"set", scope:"agent", agent:"build", model }

model for that agent's runs

agents.<id>.model in the nearest config

Precedence: session → agent → project → global. scope defaults to session when sessionID is given, otherwise project.

Project/global writes use a JSONC-aware editor (comments and unrelated keys survive), then trigger an OpenCode config reload and verify the result against model/default. Agent-level writes are verified by reading the file back, because OpenCode does not expose the resolved per-agent model through the API.

// opencode.json
{
  "model": { "providerID": "opencode", "model": "iceman-free" },
  "agents": { "build": { "model": { "providerID": "opencode", "model": "inkling-2-small-free" } } }
}

A model can also be passed at creation time: opencode_session_create({ model: { providerID, id, variant? } }).

How a client actually runs OpenCode

There are two entry points, both of which hand real work to OpenCode:

1. Persistent session — the chat keeps going:

opencode_session_create({ directory })
opencode_session_prompt({ sessionID, text: "Fix the failing test in src/auth.ts" })
// → OpenCode's own agent (build) runs the model, edits files, runs commands, and returns the answer

2. One-shot delegation — "do this task and give me the result":

opencode_task({
  directory: "/repo",
  agent: "build",            // or plan / general / explore
  prompt: "Create hello.txt with 'hello from opencode', then cat it",
  timeoutMs: 250000
})

opencode_task creates the session, sends the prompt, waits for the run to finish, and returns the assistant text, every tool call (write, shell, …), token/cost usage, and the child sessionID. Subagents work the same way: pass agent: "explore" or parentSessionID to attach the run as a child.

The MCP client never touches the model. It sends text; OpenCode does inference through its own providers, runs the agentic loop with its own tools and permissions, and the bridge only translates the request/response. That means the client gets OpenCode's tools, MCP servers, skills, and models for free.

If OpenCode asks for permission mid-run, the run blocks; use opencode_permission { action: "list" } and { action: "reply" } to approve or reject headlessly.

Verified end to end: npm run agentic-smoke asks the build agent to write a file and run cat, then asserts the file exists on disk with the right content and that write + shell appear in the transcript.

Workspace resolution

Sessions are created in, in order: the tool's directory argument → MCP roots → CLAUDE_PROJECT_DIR / OPENCODE_MCP_DIRECTORY / INIT_CWD → configured defaultDirectory → process cwd. The home directory and / are never used as a silent fallback; the bridge returns an actionable error instead.

HTTP transport

OPENCODE_MCP_TOKEN=… npx opencode-mcp-server --http --port 7777
# POST http://127.0.0.1:7777/mcp  with  Authorization: Bearer <token>

If OPENCODE_MCP_TOKEN is unset, a token is generated at ~/.config/opencode-mcp/http-token (0600). Health check: GET /healthz. The same token protects a settings endpoint:

curl -X POST http://127.0.0.1:7777/configure \
  -H "Authorization: Bearer $OPENCODE_MCP_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"url":"http://127.0.0.1:4096","password":"…"}'

Security notes

  • The bridge can run an agent with shell access — treat it as remote code execution by design.

  • Loopback binding, bearer token, and loopback-only OpenCode URLs by default.

  • --read-only disables prompts, compaction, deletes, moves, uploads and permission replies.

  • allowedRoots (config file or OPENCODE_MCP_ALLOWED_ROOTS) blocks path escapes, symlink-safe.

  • Passwords never appear in logs, errors, or tool output; the audit-friendly paths redact them.

  • opencode_configure cannot change allowedRoots or the permission profile.

Development

npm install
npm run typecheck
npm test              # unit tests (vitest)
npm run build
OPENCODE_URL=… OPENCODE_PASSWORD=… npm run smoke   # live end-to-end (stdio)
node scripts/http-smoke.mjs                        # live end-to-end (HTTP, after starting --http)

Status

Working: all 18 tools, stdio + HTTP transports, config/status/configure, workspace resolution, model assignment at session/project/global/agent scope, attachments, delegation, compaction, permissions, MCP administration.

Not yet implemented from docs/plan.md: audit log file, OS keychain storage, artifact resources (opencode://…), progress notifications, and per-client smoke tests against Codex/Anti-Gravity.

Available Tools

18 tools
opencode_agentAgents and subagentsA

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.

Inputs: action (required), agent, prompt, directory, +3 more.

opencode_configureConfigure OpenCode connectionA

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.

Inputs: url, test, clear, persist, +2 more.

opencode_file_attachAttach a file to a sessionA

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.

Inputs: sessionID (required), data, mime, name, +4 more.

opencode_mcpOpenCode MCP serversA

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.

Inputs: action (required), types, config, server, +1 more.

opencode_modelModelsA

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.

Inputs: action (required), type, agent, model, +3 more.

opencode_permissionPermission requestsB

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).

Inputs: action (required), message, profile, decision, +3 more.

opencode_session_compactCompact OpenCode sessionB

Summarize older turns to free context. Returns the compaction inbox item and token totals before/after when the service reports them.

Inputs: sessionID (required), wait.

opencode_session_createCreate OpenCode sessionA

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.

Inputs: agent, model, title, directory, +2 more.

opencode_session_deleteDelete OpenCode sessionC
Destructive

Delete a session and its messages.

Inputs: sessionID (required).

opencode_session_getGet OpenCode sessionB
Read-only

Fetch one session's metadata: title, agent, model, cost, tokens, timestamps and outcome.

Inputs: sessionID (required).

opencode_session_historyRead session historyA
Read-only

Read a session's messages and totals. Useful for inspecting what an agent did, auditing tool calls, or exporting a transcript to another client.

Inputs: sessionID (required), limit, order, cursor, +3 more.

opencode_session_interruptInterrupt OpenCode runA

Stop the current run in a session. The session stays usable afterwards.

Inputs: sessionID (required).

opencode_session_listList OpenCode sessionsA
Read-only

List sessions, newest first. Filter by directory, search text, archive state, or parent session.

Inputs: limit, cursor, search, archived, +2 more.

opencode_session_moveMove OpenCode sessionC

Change the working directory of an existing session.

Inputs: directory (required), sessionID (required).

opencode_session_promptPrompt an OpenCode sessionA

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.

Inputs: text (required), sessionID (required), wait, files, +3 more.

opencode_statusOpenCode statusA
Read-only

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.

Inputs: no named parameters.

opencode_taskDelegate a task to OpenCodeA

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.

Inputs: prompt (required), wait, agent, model, +4 more.

opencode_workspaceResolve workspace directoryA

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.

Inputs: action, directory.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP clients such as Claude, Cursor, and VS Code to delegate coding tasks to an OpenCode server, including asking questions, running background jobs, monitoring progress, responding to input/permissions, and reviewing changes across projects.
      23,789 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Connects MCP clients to OpenCode's headless API so users can delegate coding work, ask questions, implement features, monitor background jobs, respond to prompts and permissions, and review changes across projects.
      23,789 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Connects MCP clients such as Claude, Cursor, and VS Code to an OpenCode server's headless API so coding work can be delegated, answered, and monitored. It supports asking questions, launching foreground or background jobs, supplying required input and permissions, and reviewing resulting changes across projects.
      23,789 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Connects MCP clients to OpenCode's headless API so users can delegate coding tasks, ask questions, monitor background work, respond to input and permission requests, and review changes across projects.
      23,789 npm
      MIT