opencode-mcp-bridge

# opencode-mcp-bridge

A coordinator-facing MCP server for a self-hosted
[`OpenCode`](https://opencode.ai) instance.

A host harness (Codex, Claude Code, Cursor, 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.

This is not a hosted OpenCode service for production. Each user should
self-host for production: provide an OpenCode server, or use one they
control, plus their own bridge deployment and token. The project includes
an optional community demo endpoint operated by ManuOtel at
`https://opencode-mcp.manuotel.com/worker-mcp` (`/worker-mcp` only); it
requires its own token and is not for production. Placeholder URLs such as
`https://YOUR-BRIDGE-HOST/worker-mcp` are not usable servers.

## Section map

1. [Quick start (60 seconds)](#quick-start-60-seconds)
2. [Endpoints](#endpoints)
3. [Harness setup](#harness-setup)
4. [Worker workflow](#worker-workflow)
5. [Tools](#tools)
6. [Security](#security)
7. [Local deployment](#local-deployment)
8. [Contributor workflow](#contributor-workflow)
9. [Publish and discover](#publish-and-discover)
10. [Community and license](#community-and-license)

## Quick start (60 seconds)

You need your own bridge deployment ([Local deployment](#local-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.

```bash
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 the value of `MCP_BEARER_TOKEN` on that host. Then register the
transport in your harness (see [Harness setup](#harness-setup)).

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`. Full steps live in
[docs/client-setup.md](docs/client-setup.md). The maintainer demo is
opt-in only and may require its own token; generic installs never point
at another person's server.

Rules for every example in this file:

- `https://<your-domain>/worker-mcp` is the safe default. It exposes
  exactly five worker tools and never includes `exec_run`.
- `https://<your-domain>/mcp` exposes the full legacy catalog, including
  `exec_run` when the operator enables it. Use it only for legacy clients.
- `https://YOUR-BRIDGE-HOST/worker-mcp` (as shipped in `.mcp.json`) is a
  placeholder. It fails loudly by design. Always register your own URL
  per machine for production. The optional community demo endpoint
  `https://opencode-mcp.manuotel.com/worker-mcp` (`/worker-mcp` only) is
  operated by ManuOtel, requires its own token, and is not for production.
- Generate a fresh token with
  `python3 -c "import secrets; print(secrets.token_urlsafe(48))"`.

The helper `./scripts/install-client.sh --help` registers Codex or Claude
Code transports from these variables. It requires both variables and
fails clearly when either is missing or the URL is malformed (it must be
`http(s)://...` ending in `/mcp` or `/worker-mcp`); it never falls back
to anyone else's server. Full Codex and Claude Code steps live in
[docs/client-setup.md](docs/client-setup.md). Copilot-family products
have their own guide at [docs/copilot-setup.md](docs/copilot-setup.md).
For the public registry metadata and publication checklist, see
[docs/registry.md](docs/registry.md). The registry entry describes the
software and advertises the optional community demo endpoint operated by
ManuOtel; it never supplies a token. Self-host for production with your
own token.

## Endpoints

Two Streamable HTTP endpoints share one Bearer token.
`GET /health` is the only unauthenticated endpoint. Remote HTTP only;
there is no local stdio command.

| Endpoint | Tools | Use |
| --- | --- | --- |
| `/worker-mcp` | Exactly five: `worker_catalog`, `worker_run`, `worker_status`, `worker_verify`, `worker_cleanup` | Default for all new clients. Least privilege; no shell. |
| `/mcp` | Full 16-tool catalog: the five worker tools plus `list_*`, session tools, `get_diff`, `exec_run` | Legacy clients only. `exec_run` stays listed but fails closed unless `ENABLE_EXEC_RUN=true`. |
| `/health` | None (open) | Reverse-proxy checks. |

There is no global tool-profile switch. Both endpoints are always served
from the same process.

## Harness setup

Compatibility is protocol-level (MCP over Streamable HTTP with a Bearer
header) unless an end-to-end test is documented in this repo. Client
config keys differ per product; confirm key names in the linked official
docs before pasting.

| Harness | How to connect | Status |
| --- | --- | --- |
| OpenAI Codex CLI | `codex mcp add` with `--bearer-token-env-var` | Protocol-level, syntax from official docs |
| Claude Code | `claude mcp add --transport http` or `opencode-worker` plugin | Protocol-level, syntax from official docs |
| ChatGPT Developer Mode | Remote MCP connector, URL mode + Bearer token | Protocol-level; needs an eligible plan and workspace, plus admin approval where required |
| Cursor | Project `.cursor/mcp.json`, `url` + `headers` | Protocol-level |
| Gemini CLI | `~/.gemini/settings.json`, `httpUrl` + `headers` | Protocol-level |
| Windsurf | `~/.codeium/windsurf/mcp_config.json`, `serverUrl` + `headers` | Protocol-level, key names from official docs |
| Cline | `cline_mcp_settings.json`, `type: streamableHttp` + `url` + `headers` | Protocol-level, key names from official docs |
| Roo Code | `mcpServers` entry, `url` + `Authorization` header | Protocol-level, client-specific shape |
| Pi | `pi-mcp-adapter`, shared `~/.config/mcp/mcp.json` | Protocol-level, syntax from official docs |
| Hermes Agent | YAML `mcp_servers` entry + `tools.include` | Protocol-level, syntax from official docs |
| GitHub Copilot / Copilot Studio / M365 Copilot | See [docs/copilot-setup.md](docs/copilot-setup.md) | Separate guide, three distinct cases |
| MCP Inspector | Streamable HTTP transport + `Authorization` header | Debugging only |

The safe pattern in every client-specific block below: URL
`https://<your-domain>/worker-mcp`, header
`Authorization: Bearer ${OPENCODE_MCP_BEARER_TOKEN}`, tools
`worker_catalog`, `worker_run`, `worker_status`, `worker_verify`,
`worker_cleanup`.

### OpenAI Codex CLI

```bash
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. Codex plugin
bundles do not interpolate environment variables in the server URL, so
register the transport per machine with your concrete URL. There is also
an `opencode-worker` plugin with worker skills, installed from a Git
marketplace pinned at `v0.2.0`:

```bash
codex plugin marketplace add ManuOtel/opencode-mcp-bridge --ref v0.2.0
```

Then install `opencode-worker` from that marketplace and register your
own transport as above (required: the bundled placeholder URL is not
usable). Details: [docs/client-setup.md](docs/client-setup.md) sections
2 and 6. Official docs:
https://developers.openai.com/codex/cli/reference

### Claude Code

Preferred transport (no skills): a project `.mcp.json` entry. Claude
Code expands `${VAR}` references in `url` and `headers` at load time,
so the token stays in the environment and out of the file:

```json
{
  "mcpServers": {
    "opencode": {
      "type": "http",
      "url": "${OPENCODE_MCP_URL}",
      "headers": {
        "Authorization": "Bearer ${OPENCODE_MCP_BEARER_TOKEN}"
      }
    }
  }
}
```

CLI alternative (transport only, no skills). Double quotes let the shell
expand the token before Claude Code sees it:

```bash
claude mcp add --transport http opencode "$OPENCODE_MCP_URL" --header "Authorization: Bearer $OPENCODE_MCP_BEARER_TOKEN"
```

Warning: `claude mcp add` writes the resolved header into its local MCP
config, which can persist the token on disk. Prefer the `.mcp.json`
form above on shared hosts, and rotate the token if a config file
leaks.

Prefer the env-var reference form so the token value never lands in
config (see [docs/client-setup.md](docs/client-setup.md) section 3):

```bash
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"
```

Recommended path: the `opencode-worker` plugin from this repo's Claude
marketplace (`.claude-plugin/marketplace.json`). It bundles the MCP transport
(URL `${OPENCODE_MCP_URL}`, token `${OPENCODE_MCP_BEARER_TOKEN}`) plus
the `coordinate-opencode-worker` skill. Export both variables before
installing:

```bash
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](docs/client-setup.md) sections 3
and 7. Official docs: https://docs.anthropic.com/en/docs/claude-code/mcp

### ChatGPT Developer Mode

Developer Mode ON, then Connectors, Create connector, URL mode with
`https://<your-domain>/worker-mcp` plus your Bearer token, then Scan
Tools. Select `https://<your-domain>/mcp` only when you explicitly need
the full legacy catalog or `exec_run`.
Remote MCP connectors need an eligible plan and workspace, and may need
admin approval. Availability depends on your account, not on this repo.

### Cursor

Add to `.cursor/mcp.json` in your project (key names per
https://cursor.com/docs/context/mcp):

```json
{
  "mcpServers": {
    "opencode-bridge": {
      "url": "https://<your-domain>/worker-mcp",
      "headers":