opencode-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@opencode-mcp-server start a session in my project and ask the agent to fix the failing tests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 purposeThe 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 passwordFind 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 --helpPin 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 statusOption 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 |
| Health, version, workspace, agents, default model. Works while unconfigured. |
| Validate and apply URL + password in-chat. |
| Show/persist the working directory, list MCP roots. |
| New session in a directory (agent, model, parent, permissions). |
| List sessions by directory/search/archive/parent. |
| Session metadata, tokens, cost. |
| Change a session's directory. |
| Delete a session. |
| Stop the current run. |
| Summarize history to free context. |
| Prompt with text + files, wait for the answer, return tools/usage. |
| Messages as JSON or markdown transcript. |
| List models, read the default, assign at session/project/global/agent scope. |
| List agents, switch agent, delegate to a subagent. |
| One-shot delegation: create session → prompt → wait → return transcript. |
| Attach a path or base64 bytes to a session (optionally prompt immediately). |
| Inspect/add/connect/remove OpenCode's own MCP servers. |
| 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 |
| immediate switch for that conversation | OpenCode DB |
Project |
| default for new sessions in that workspace |
|
Global |
| default everywhere |
|
Agent |
| model for that agent's runs |
|
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 answer2. 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-onlydisables prompts, compaction, deletes, moves, uploads and permission replies.allowedRoots(config file orOPENCODE_MCP_ALLOWED_ROOTS) blocks path escapes, symlink-safe.Passwords never appear in logs, errors, or tool output; the audit-friendly paths redact them.
opencode_configurecannot changeallowedRootsor 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 toolsopencode_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 sessionCDestructive
Delete a session and its messages.
Inputs: sessionID (required).
opencode_session_getGet OpenCode sessionBRead-only
Fetch one session's metadata: title, agent, model, cost, tokens, timestamps and outcome.
Inputs: sessionID (required).
opencode_session_historyRead session historyARead-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 sessionsARead-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 statusARead-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
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.
Maintenance
Related MCP Connectors
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Query, browse, and automate OmegaAI workspaces from any MCP client. Streamable HTTP with OAuth 2.0.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Chat, image, video, and audio models from many vendors behind one remote MCP server and one key.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceConnects 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceConnects 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceConnects 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 npmMIT