v3.1.0 — OpenChamber and bearer-token auth

Works with OpenCode 1.x (tested with 1.18.31 and 1.19.3). OpenCode 2.x support is planned for 4.0 (#35).

Added

• Bearer-token auth with OPENCODE_SERVER_TOKEN.
• OpenChamber sign-in with OPENCODE_OPENCHAMBER_PASSWORD (requires OpenChamber 1.12–1.24). Thanks @Rahulsharma0810 (#34)!

Fixed

• opencode_events_poll now keeps the base-URL path prefix, so it works behind proxies such as OpenChamber's /api.
• A refused OpenChamber sign-in is no longer retried on every call, so it can't trigger OpenChamber's lockout (#36).

Security

• Raised the minimum versions of @modelcontextprotocol/server/core (2.4.0) and zod (4.6.6) to clear the published advisories (#36).

Full details: CHANGELOG

v3.0.0 — Durable async jobs, MCP Tasks, and structured output

Breaking changes

• Require Node.js 22 or newer. Upgrade the runtime used by your MCP client before installing 3.0.0.
• Move the MCP implementation to the split SDK v2 packages. Keep legacy stdio clients supported through protocol negotiation; native Tasks and interactive input depend on client capabilities.

Added

• Durable local job handles and result storage, with get/list/cancel/input tools and default 24-hour retention. Override the storage directory with OPENCODE_TASK_STORE.
• Native MCP Tasks support for opencode_run through the stdio adapter, with explicit polling and ordinary fire/check/wait fallback.
• Pending question list/reply/reject tools and explicit permission/question responses for jobs. Supporting clients can present interactive input; permissions are never silently approved.
• Optional full and essential tool profiles selected with OPENCODE_TOOL_PROFILE.
• Structured MCP outputs alongside readable text, plus optional OpenCode JSON-schema response formats for prompts.
• Project/session resource templates with encoded absolute server paths; static resources retain their default-project scope.

Fixed

• Recognize completed JSON-schema tool responses, show the validated JSON in readable output, and recover correlated async results from OpenCode 1.18.31 response-format history serialization failures. Document the required StructuredOutput permission.
• Correlate async observation with submitted work and report accepted, running, input-required, completed, failed, cancelled, and unknown states accurately. Observation timeouts preserve progress and do not imply cancellation.
• Preserve request deadlines and cancellation, avoid unsafe automatic mutation retries, and scope event streams to the requested project.
• Redact sensitive configuration/provider fields and preserve valid JSON when responses are truncated.
• Make tool annotations and generated documentation match the registered public surface.
• Replace unsafe smoke-test session fallback with a disposable project and owned-session cleanup. Unexpected backend errors now fail verification; inference requires an explicit provider/model opt-in and skipped tools are reported honestly.
• Refresh client configuration examples, remote path guidance, resource capabilities, development checks, and release verification instructions.

Migration notes

• Keep OpenCode running externally if work must continue after MCP disconnect. Persisted job records allow resumed observation; they do not checkpoint inference or restart an auto-started child that was closed with MCP.
• Clients should inspect structured state and identifiers rather than parse status text. A timeout means observation ended, not that the job failed. Check existing work before retrying an ambiguous submission.
• The essential profile reduces advertised tools but is not a sandbox. OpenCode's project permission policy still controls delegated coding operations.

Validation

• 503 tests passed, 3 skipped; npm audit reports zero vulnerabilities.
• Linux and Windows CI with Node.js 22 and 24 passed.
• Production-only archive installation passed legacy and July 2026 MCP discovery, health, and shutdown checks.
• Live OpenCode 1.18.31 fixture checks: 24 passed, 64 intentionally skipped, zero failures. Authenticated OpenAI inference and structured-output workflows were verified before release.

Install: npm install -g opencode-mcp@3.0.0

v2.0.1 — OpenCode compatibility and explicit server startup

Breaking changes

• Automatic server startup is now opt-in. To retain the previous behavior, set OPENCODE_AUTO_SERVE=true in your MCP client configuration. Otherwise, start OpenCode explicitly with opencode serve --port 4096 or share a TUI started with opencode --port 4096.

Changed

• Upgrade @opencode-ai/sdk to 1.18.31 and refresh compatible dependencies.

• Automatic server startup is now opt-in with OPENCODE_AUTO_SERVE=true. By default, connect to an explicitly managed server or a TUI started with opencode --port 4096. This prevents MCP from silently launching a second instance alongside existing TUI sessions (#18).

• Auto-start only supports loopback HTTP endpoints; remote servers must be started on their own host.

Fixed

• Normalize local project-init protection checks on Windows, including drive roots, native system directories and case differences.

• Forward model variants at the prompt body top level, and remove the unsupported shell variant option (community PR #15, @AveryanAlex). Slash commands now send their model as a provider/model string.

• Format current OpenCode tool-state and diff-patch responses, and recognize tool-only activity without reporting a false credentials failure.

• Handle stdin closure and SIGHUP when MCP clients disconnect (community PR #16, @potch8228).

• Preserve POSIX, Windows drive and UNC project paths across client/server OS boundaries. Reject ambiguous relative paths instead of resolving against the MCP process (#13).

• Let OpenCode validate project directory existence on its own machine, enabling remote servers and containers (#14).

• Use the asynchronous prompt endpoint in opencode_fire and opencode_run, so dispatch does not wait for inference before returning or polling (#20).

Validation

• Linux and Windows CI on Node 22 and 24.
• 370 tests passed; 3 skipped.
• Dependency audit: zero vulnerabilities.
• Installed npm tarball smoke test: MCP handshake reports 2.0.1 with 80 tools, 10 resources, and 6 prompts.

Install with npx opencode-mcp@latest.

Version 2.0.0 was unavailable because npm retains a historical publication of that version; 2.0.1 is the published release.

v1.11.0 — SDK migration, parallel projects tool, security hardening

Architectural release. Migrates server lifecycle to the official @opencode-ai/sdk, adds a tool for parallel project initialization, and lands a substantial security/correctness pass on the HTTP and SSE layers.

Added

• opencode_project_init tool — initialize or open a project directory to host an independent OpenCode session. Designed for MCP clients orchestrating parallel multi-project workloads. Creates the directory (mkdir -p, idempotent on existing dirs), then pings the OpenCode server at that path to register it as a project. Returns the canonical (realpath'd) absolute path so downstream calls can rely on it.

Changed

• Server lifecycle now uses @opencode-ai/sdk's createOpencodeServer instead of spawn("opencode serve"). The HTTP server still runs on a port (default 127.0.0.1:4096), but it's hosted in-process rather than as a child process. Eliminates zombie processes, port-binding races, and the binary-discovery code path. OPENCODE_SERVE_ARGS is now silently ignored (the SDK manages config in-process).
• Reconnect logic rebinds baseUrl from ensureServer() result — when the managed server comes up on a different URL than expected, the client rebuilds its SDK instance against the new endpoint before retrying.
• reconnectAttempts budget now resets on successful requests — previously the counter grew monotonically, so a long-lived client permanently exhausted its auto-heal capacity after three reconnects.
• Startup serialization keyed by baseUrl — concurrent ensureServer() calls targeting different URLs each get their own startup promise.

Security

• Symlink escape in opencode_project_init closed — path.resolve only canonicalizes ../. lexically. A symlink at e.g. /tmp/safe → /etc would have passed the forbidden-roots check, then OpenCode would scope its session into /etc. The tool now calls realpath after mkdir and re-runs the deny-list against the canonical path. Forbidden roots are also realpath'd at module load so macOS-style symlinks (/etc → /private/etc) match in either form.
• /var removed from the project_init forbidden-roots list — macOS user-temp directories live under /var/folders and many /var subtrees are legitimately user-writable. The original deny-list rejected os.tmpdir() paths on macOS; a latent bug uncovered while writing the new regression tests.
• CRLF/NUL guard in normalizeDirectory — Node's undici already rejects CRLF in header values, so this isn't currently exploitable, but normalizeDirectory now explicitly rejects NUL and CR/LF so the contract is independent of the runtime.
• Basic auth header now propagated to /global/health probe — when OPENCODE_SERVER_PASSWORD was set, the probe was rejected with 401, isServerRunning reported unhealthy, and ensureServer looped trying to auto-start an already-running server.
• x-opencode-directory header sent raw, no longer URI-encoded — the OpenCode server treats the header as a literal absolute filesystem path; URI-encoding turned /tmp/proj into %2Ftmp%2Fproj and broke project scoping for every multi-project tool call.
• opencode_project_init validates isAbsolute, rejects NUL bytes, rejects \r/\n, denies system roots (/, /etc, /usr, /bin, /sbin, /sys, /proc, /dev).

Fixed

• SSE event parser dropped events when the server used CRLF line endings — the parser split on \"\\n\" only, leaving \\r on every line. Event names came out as \"message\\r\" and the blank-line dispatcher never fired, silently corrupting opencode_events_poll and any downstream SSE consumers.
• Per-call timeouts now propagated to the HTTP dispatcher via AbortSignal.

Install

```bash
npx -y opencode-mcp@1.11.0
```

Or pin in your MCP client config:

```json
{
"command": "npx",
"args": ["-y", "opencode-mcp@1.11.0"]
}
```

Stats

• 80 tools (up from 79)
• 328 tests passing

Full Changelog: v1.10.2...v1.11.0

v1.10.2 — Windows path fix, OPENCODE_SERVE_ARGS, model variant

User-facing bugfix release. Three commits sat unreleased on main since v1.10.1; cutting v1.10.2 unblocks Windows clients without dragging the larger SDK migration (PR #11) along.

Fixed

• normalizeDirectory rejected valid Windows absolute paths (#5, #6, #13) — the resolved-path check used startsWith("/"), which only matches POSIX. On Windows hosts (including npx-spawned MCPs talking to a WSL OpenCode), path.resolve("/mnt/d/Projects/foo") returns "\\mnt\\d\\Projects\\foo", failing the check and rendering every tool's directory parameter unusable for Windows clients.

  Switched to the platform-aware path.isAbsolute from node:path, which accepts both POSIX (/home/user/project) and Windows (C:\Users\me\project, \\server\share) absolute paths. Updated the error message to show both forms.

Added

• OPENCODE_SERVE_ARGS environment variable (#7, #9) — pass custom arguments to the opencode serve subprocess at auto-start. Useful for advanced server configuration. Thanks @xpufx for the issue.
• Model variant parameter on all model-accepting tools (#8, #10) — opencode_ask, opencode_run, opencode_fire, opencode_reply, opencode_message_send* now accept an optional `variant` to target a specific model variant. Thanks @iamabigartist for the issue.

Install

```bash
npx -y opencode-mcp@1.10.2
```

Or pin in your MCP client config:

```json
{
"command": "npx",
"args": ["-y", "opencode-mcp@1.10.2"]
}
```

Stats

• 79 tools
• 321 tests passing

Full Changelog: v1.10.1...v1.10.2

v1.10.1

[1.10.1] - 2026-04-10

Changed

• Instruction examples now use discovered/default provider and model values instead of hardcoded Anthropic examples. This avoids steering MCP clients toward unavailable providers and aligns the startup guidance with opencode_setup.

Fixed

• Health checks for authenticated OpenCode servers now propagate HTTP basic auth through the full auto-start path, including startup polling and reconnection flows.
• ensureServer() now forwards configured server credentials during startup so remote protected servers no longer fail the health probe while coming online.

Stats

• Tool count: 79
• Tests: 320