opencode-mcp-bridge

A coordinator-facing MCP server for a self-hosted OpenCode instance.

First use in 60 seconds

Protocol-level compatibility (MCP over Streamable HTTP) - no official partnerships; some harnesses are unverified end-to-end, see docs/compatibility.md:

A host harness (Codex, Claude Code, or any MCP-capable client) delegates repository or system work to an OpenCode worker on another machine. The host model scopes the task, coordinates the worker, and verifies the result. The bridge speaks MCP over Streamable HTTP with Bearer authentication (remote HTTP only; there is no local stdio transport). It coordinates OpenCode workers; it does not replace OpenCode.

Bring your own bridge: you provide an OpenCode server, your own bridge deployment, your own token, and your own https://<your-domain>/worker-mcp. Generic installs never point at another person's server. The optional community demo endpoint operated by ManuOtel at https://opencode-mcp.manuotel.com/worker-mcp (/worker-mcp only) is opt-in only, requires its own token, and is not for production. Self-host for production with your own token. https://YOUR-BRIDGE-HOST/worker-mcp (as shipped in .mcp.json) is a placeholder, not a usable server; it fails loudly by design.

Documentation map

• First use: env vars and Quick connect.
• Endpoints: /worker-mcp (recommended) vs /mcp (legacy).
• Codex and Claude Code: concise setup.
• More harnesses: compact matrix plus docs/harnesses.md.
• Worker workflow: run, wait, verify, clean up.
• Security, Local deployment, Contributor workflow, Publish and discover: pointers below.
• Full guides: docs/client-setup.md, docs/copilot-setup.md, docs/harnesses.md, docs/compatibility.md, docs/tool-api.md, docs/worker-operating-model.md, docs/operations.md, docs/registry.md.

First use (60 seconds)

You need your own bridge deployment and its Bearer token. Keep the token in environment variables. Never paste a real token into a file, a chat log, or a commit. The optional community demo above is separate and may require its own token; generic steps below only use your bridge.

export OPENCODE_MCP_URL="https://<your-domain>/worker-mcp"
export OPENCODE_MCP_BEARER_TOKEN="<paste-token-here>"

Replace <your-domain> with your bridge host and <paste-token-here> with MCP_BEARER_TOKEN from that host. Generate a fresh token with python3 -c "import secrets; print(secrets.token_urlsafe(48))".

Quick connect (your own bridge): ./scripts/install-client.sh both registers Codex and Claude Code transports from OPENCODE_MCP_URL and OPENCODE_MCP_BEARER_TOKEN. It fails clearly when either is missing or the URL is malformed (http(s)://... ending in /mcp or /worker-mcp); it never falls back to anyone else's server.

./scripts/install-client.sh both --dry-run

Full steps: docs/client-setup.md. Copilot-family products: docs/copilot-setup.md.

Every example below uses https://<your-domain>/worker-mcp (safe default, recommended: the eight worker tools worker_catalog, worker_run, worker_wait, worker_status, worker_verify, worker_cleanup, worker_decide, worker_resume; never exec_run) or https://<your-domain>/mcp (legacy full catalog of 19 tools, with exec_run only when the operator sets ENABLE_EXEC_RUN=true). Codex plugin bundles do not interpolate env vars in the server URL, so register the transport per machine with your concrete URL.

Endpoints

Two Streamable HTTP endpoints share one Bearer token. GET /health plus read-only GET/HEAD on /.well-known/oauth-protected-resource (and /mcp and /worker-mcp children) and /.well-known/mcp/server-card.json stay open with no secrets.

Codex and Claude Code

Protocol-level compatibility (MCP over Streamable HTTP with a Bearer header) unless an end-to-end test is documented. Matrix, status labels, and first-call contract: docs/compatibility.md.

Codex

codex mcp add opencode --url "$OPENCODE_MCP_URL" --bearer-token-env-var OPENCODE_MCP_BEARER_TOKEN

Codex reads the token from the environment at request time. The opencode-worker plugin adds skills (delegate-to-opencode, then verify-opencode-work, on failure recover-opencode-task; code changes follow opencode-git-workflow). Install from the Git marketplace pinned at v0.6.0, then register your own transport as above (the bundled placeholder URL is not usable):

codex plugin marketplace add ManuOtel/opencode-mcp-bridge --ref v0.6.0

Details: docs/client-setup.md sections 2 and 6. Official docs: https://developers.openai.com/codex/cli/reference

Claude Code

Preferred transport: a project .mcp.json entry with type: http, url: ${OPENCODE_MCP_URL}, and header Authorization: Bearer ${OPENCODE_MCP_BEARER_TOKEN} (expanded at load time, token stays out of the file). CLI alternative, same reference form:

claude mcp add --transport http --header 'Authorization: Bearer ${OPENCODE_MCP_BEARER_TOKEN}' opencode "$OPENCODE_MCP_URL"
claude mcp add --transport http --header 'Authorization: Bearer ${OPENCODE_MCP_BEARER_TOKEN}' opencode-bridge "$OPENCODE_MCP_URL"

A shell-expanded header would persist the secret in local config; rotate the token if a config file leaks. Recommended: the opencode-worker plugin from this repo's Claude marketplace (.claude-plugin/marketplace.json), bundling the transport plus the coordinate-opencode-worker skill. Export both variables first:

claude plugin marketplace add ManuOtel/opencode-mcp-bridge
claude plugin install opencode-worker@opencode-mcp-bridge

There is no npm or Brew package; both marketplaces install from this Git repo. Details: docs/client-setup.md sections 3 and 7. Official docs: https://docs.anthropic.com/en/docs/claude-code/mcp

More harnesses

Config keys differ per product; confirm key names in the linked official docs before pasting. Full copy-ready blocks: docs/harnesses.md. Safe pattern everywhere: URL https://<your-domain>/worker-mcp, header Authorization: Bearer ${OPENCODE_MCP_BEARER_TOKEN}, the eight worker_* tools (worker_wait is the bounded read-only long-poll; worker_decide/worker_resume are approval-gated).