OpenCode MCP Bridge

宿主运行环境（Codex、Claude Code 或任何支持 MCP 的客户端） 会将仓库或系统任务委派给另一台机器上的 OpenCode 工作器。宿主模型负责界定任务、协调工作器并验证结果。该桥接服务通过 Streamable HTTP 提供 MCP，并使用 Bearer 身份验证（仅限远程 HTTP；不支持本地 stdio 传输）。它负责协调 OpenCode 工作器，不会取代 OpenCode。

自备桥接服务：你需要提供 OpenCode 服务、自行部署桥接服务、自备令牌，并使用自己的 https://<your-domain>/worker-mcp。通用安装不会指向他人的服务。由 ManuOtel 运营的可选社区演示端点 https://opencode-mcp.manuotel.com/worker-mcp （仅限 /worker-mcp）需主动选择使用、需要单独的令牌，且不适用于生产环境。生产环境请使用自己的令牌进行自托管。 https://YOUR-BRIDGE-HOST/worker-mcp（如 .mcp.json 中所示）是占位符，并非可用的服务；它会按设计明确报错。

文档导航

• 首次使用：环境变量和快速连接。
• 端点：/worker-mcp（推荐）与 /mcp（旧版）。
• Codex 和 Claude Code：简明设置说明。
• 更多运行环境：精简矩阵及 docs/harnesses.md。
• 工作器工作流：运行、等待、验证、清理。
• 安全、本地部署、 贡献者工作流、 发布与发现：请参阅下文的链接。
• 完整指南：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。

首次使用（60 秒）

你需要部署自己的桥接服务，并准备好其 Bearer 令牌。请将令牌保存在环境变量中。切勿将真实令牌粘贴到文件、聊天记录或提交中。上方的可选社区演示是独立的，可能需要专用令牌；以下通用步骤只使用你的桥接服务。

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

将 <your-domain> 替换为桥接服务的主机名，并将 <paste-token-here> 替换为该主机提供的 MCP_BEARER_TOKEN。使用 python3 -c "import secrets; print(secrets.token_urlsafe(48))" 生成新令牌。

快速连接（使用你自己的桥接服务）：./scripts/install-client.sh both 会根据 OPENCODE_MCP_URL 和 OPENCODE_MCP_BEARER_TOKEN 注册 Codex 和 Claude Code 传输配置。如果缺少其中任一变量，或 URL 格式错误（http(s)://...，且以 /mcp 或 /worker-mcp 结尾），脚本会明确报错；绝不会回退到其他人的服务。

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

完整步骤：docs/client-setup.md。 Copilot 系列产品：docs/copilot-setup.md。

以下所有示例均使用 https://<your-domain>/worker-mcp（安全的默认选项，推荐：包含八个工作器工具 worker_catalog、worker_run、worker_wait、worker_status、worker_verify、worker_cleanup、worker_decide、worker_resume；绝不包含 exec_run），或 https://<your-domain>/mcp（包含 19 个工具的旧版完整目录；仅当操作员设置 ENABLE_EXEC_RUN=true 时才包含 exec_run）。 Codex 插件包不会在服务器 URL 中插入环境变量，因此需要在每台机器上用实际 URL 注册传输配置。

端点

两个 Streamable HTTP 端点共用一个 Bearer 令牌。GET /health，以及对 /.well-known/oauth-protected-resource（及其 /mcp 和 /worker-mcp 子路径）和 /.well-known/mcp/server-card.json 的只读 GET/HEAD 请求，无需密钥即可访问。

端点	工具	用途
/worker-mcp	仅工作器工具（8 个，绝不包含 exec_run）	所有新客户端的默认选项。遵循最小权限原则；不提供 shell。
/mcp	完整兼容目录（19 个工具）	仅供旧版使用。除非设置 ENABLE_EXEC_RUN=true，否则 exec_run 会安全地拒绝执行。
/health	无（开放访问）	反向代理存活检查。
/ready	无（需要 Bearer 令牌）	就绪状态：OpenCode 加注册表（200/503）。
/metrics	无（需要 Bearer 令牌）	有界计数器，不含敏感数据。

Codex 和 Claude Code

除非有端到端测试文档，否则仅保证协议级兼容（通过 Streamable HTTP 使用 MCP，并携带 Bearer 请求头）。矩阵、状态标签和首次调用约定：docs/compatibility.md。

Codex

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

Codex 会在请求时从环境中读取令牌。 opencode-worker 插件会添加技能（先执行 delegate-to-opencode，然后执行 verify-opencode-work；失败时执行 recover-opencode-task；代码更改则遵循 opencode-git-workflow）。从固定为 v0.6.0 的 Git marketplace 安装，然后按上文 注册自己的传输方式（捆绑的占位 URL 不可用）：

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

详情：docs/client-setup.md 第 2 和第 6 节。 官方文档：https://developers.openai.com/codex/cli/reference

Claude Code

首选传输方式：在项目 .mcp.json 中添加一项，设置 type: http、 url: ${OPENCODE_MCP_URL} 和标头 Authorization: Bearer ${OPENCODE_MCP_BEARER_TOKEN}（在加载时展开，令牌不会保存在文件中）。CLI 替代方案，使用相同的引用形式：

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"

通过 shell 展开的标头会将密钥保存在本地配置中；如果配置文件泄露，请轮换令牌。 推荐使用此仓库 Claude marketplace 中的 opencode-worker 插件 （.claude-plugin/marketplace.json），它捆绑了传输方式和 coordinate-opencode-worker 技能。请先导出两个变量：

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

没有 npm 或 Brew 软件包；两个 marketplace 都从此 Git 仓库安装。详情：docs/client-setup.md 第 3 和第 7 节。官方文档：https://docs.anthropic.com/en/docs/claude-code/mcp

更多执行环境

不同产品的配置键各不相同；粘贴前请在链接的官方文档中确认键名。 可直接复制的完整配置块： docs/harnesses.md。所有场景均适用的安全模式：URL https://<your-domain>/worker-mcp，标头 Authorization: Bearer ${OPENCODE_MCP_BEARER_TOKEN}，以及八个 worker_* 工具（worker_wait 是有界的只读长轮询； worker_decide/worker_resume 需要审批）。

执行环境	位置	状态
ChatGPT Developer Mode / connectors	docs/harnesses.md	尚未通过静态 Bearer 标头验证
Cursor	docs/harnesses.md	协议层面
VS Code	docs/harnesses.md	协议层面
Gemini CLI	docs/harnesses.md	协议层面
OpenHands	docs/harnesses.md	未验证
Windsurf	docs/harnesses.md	协议层面
Cline	docs/harnesses.md	协议层面
Roo Code	docs/harnesses.md	协议层面
Pi	docs/harnesses.md	协议层面
Hermes Agent	docs/harnesses.md	协议层面
GitHub Copilot / Copilot Studio / M365 Copilot	docs/copilot-setup.md	单独指南
MCP Inspector	docs/harnesses.md	仅用于调试

OpenHands

openhands mcp add opencode-bridge --transport http \
  --header "Authorization: Bearer <paste-token-here>" \
  "https://<your-domain>/worker-mcp"

将 <paste-token-here> 替换为桥接主机上的 MCP_BEARER_TOKEN（键名参见 https://docs.openhands.dev/openhands/usage/cli/mcp-servers）。 尚未完成端到端验证；完整配置块： docs/harnesses.md。无需客户端时： ./scripts/smoke.sh。

Worker 工作流

worker_run 是异步的（会立即返回一个 taskID）。随后使用 worker_wait 在服务端限定时间内等待，或使用 worker_status 获取状态快照：

worker_catalog()
worker_run(message="Implement X in /path/to/repo", directory="/path/to/repo", title="feat-x")
worker_wait(taskID="<taskID>", directory="/path/to/repo", timeout_s=30)
worker_verify(taskID="<taskID>", directory="/path/to/repo")
worker_cleanup(taskID="<taskID>", directory="/path/to/repo")

1. worker_catalog（默认免费且已连接）。默认值： opencode/muse-spark-1.3-contributor-free。仅在明确请求时才使用付费备用项 opencode-go/muse-spark-1.3-contributor，并通过 providerID/modelID 传入。绝不自动选择。
2. 使用 message、directory、title 调用 worker_run，可选传入 requestID 以安全重试（相同输入重试时会设置 deduplicated=true）。保存 taskID 和 directory（状态读取的范围限定于目录）。
3. 使用 worker_wait（等待时间最长为 timeout_s，默认 30，限制在 1-120；状态变化时会提前返回，或返回 timed_out=true 和 next_action="worker_wait"），或使用 worker_status 获取单个快照。 running 表示需要再次等待，idle 表示需要验证，stale 表示需要清理， error/unknown 表示需要恢复（skills/recover-opencode-task/SKILL.md）。
4. 使用 worker_verify，然后检查确切的差异，并使用宿主自身的工具运行测试和 lint。 绝不要仅凭 Worker 摘要就轻信结果。
5. 使用 worker_cleanup（action=abort 会停止任务，action=delete 会移除任务）。

契约：docs/tool-api.md。协调器行为： docs/worker-operating-model.md。 .mcp.json 中的审批设置：worker_run/worker_cleanup 会提示审批； worker_wait/worker_status/worker_catalog/worker_verify 自动批准。

安全

• MCP_BEARER_TOKEN 等同于 root 权限：使用足够长的随机值，泄露后轮换，绝不要提交 .env 或令牌。
• /worker-mcp 绝不公开 exec_run；Worker 令牌泄露后也不能用于直接访问 shell。不要在不打算提供 shell 的环境中公开 /mcp 或设置 ENABLE_EXEC_RUN=true。
• 轮换：MCP_BEARER_TOKEN_SECONDARY 用于存放一个重叠令牌；将客户端迁移过去，然后提升该令牌并重启。值为空或重复时会安全拒绝。
• 无需密钥即可访问：GET /health，以及只读的 RFC 9728 发现接口和服务器信息卡。/mcp 和 /worker-mcp 下的所有内容都需要 Bearer 令牌。

本地部署

需要 Python 3.11+、uv，以及正在运行的 opencode serve 或 opencode web（服务器文档 ）。

git clone https://github.com/ManuOtel/opencode-mcp-bridge.git
cd opencode-mcp-bridge
uv sync
cp .env.example .env
# edit .env: OpenCode credentials + a fresh MCP_BEARER_TOKEN
uv run python -m opencode_mcp_bridge.server

curl http://127.0.0.1:8087/health 返回 {"ok": true}。不带令牌时，POST /mcp 和 POST /worker-mcp 会返回 401。关键变量： OPENCODE_BASE_URL、OPENCODE_SERVER_PASSWORD、MCP_BEARER_TOKEN、 ENABLE_EXEC_RUN（false）、TASK_STATE_PATH、MCP_MAX_BODY_BYTES、 MCP_ALLOWED_ORIGINS。在前面配置启用 TLS 的反向代理。发布、 检查、轮换、回滚、日志：docs/operations.md。

贡献者工作流

请先阅读 AGENTS.md（所有权、编辑、免费模型政策、 测试、密钥、工作树、提交、报告）。技能位于 skills/。

uv sync
uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
git diff --check

发布和发现

在仓库内，无需密钥：server.json（io.github.ManuOtel/opencode-mcp-bridge 的安全 /worker-mcp 元数据）、glama.json（ManuOtel 的认领信息），以及通过仪表板/CLI 使用 Smithery。发布需要由所有者本人登录。检查清单：docs/registry.md。注册表条目仅用于列出软件；它不会授予访问权限或提供令牌。 /worker-mcp（8 个工具，无 shell）是默认选项；/mcp（19 个工具， exec_run 需选择启用）为旧版。绝不要发布自己未运营的端点，也绝不要提交令牌。

社区和许可证

更改代码或文档前，请阅读 CONTRIBUTING.md。 遵守行为准则；根据 SECURITY.md 报告安全问题。可提交 问题 或从功能分支发起拉取 请求。

许可证：PolyForm Noncommercial 1.0.0——可免费用于非商业用途，详见 LICENSE.md。商业用途需获得许可： [email protected]