OpenCode MCP Bridge

ホスト側のハーネス（Codex、Claude Code、またはMCP対応クライアント）が、別のマシン上のOpenCodeワーカーにリポジトリやシステム関連の作業を委任します。ホスト側のモデルがタスクの範囲を定め、ワーカーと連携し、結果を検証します。このブリッジはBearer認証を使用したStreamable HTTP経由のMCPで通信します（リモートHTTPのみ。ローカルのstdioトランスポートはありません）。OpenCodeワーカーと連携しますが、OpenCodeを置き換えるものではありません。

ブリッジはご自身で用意してください。OpenCodeサーバー、ご自身のブリッジのデプロイ、ご自身のトークン、そしてご自身のhttps://<your-domain>/worker-mcpが必要です。一般的なインストール設定から、他者のサーバーに接続することはありません。ManuOtelが運営する任意参加のコミュニティデモエンドポイントhttps://opencode-mcp.manuotel.com/worker-mcp（/worker-mcpのみ）は、利用を選択した場合に限り使用でき、専用のトークンが必要です。本番環境向けではありません。本番環境では、ご自身のトークンを使ってセルフホストしてください。.mcp.jsonに含まれるhttps://YOUR-BRIDGE-HOST/worker-mcpはプレースホルダーであり、利用可能なサーバーではありません。意図的に明確なエラーを返すようになっています。

ドキュメントの案内

• 初回利用：環境変数とクイック接続。
• エンドポイント：/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の形式が不正な場合（/mcpまたは/worker-mcpで終わる http(s)://...ではない場合）は、明確なエラーで停止します。 他者のサーバーにフォールバックすることはありません。

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

詳しい手順：docs/client-setup.md。 Copilotファミリー製品：docs/copilot-setup.md。

以下の例ではすべて、https://<your-domain>/worker-mcp（安全なデフォルトで、 推奨されるエンドポイント。8つのワーカーツール 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を使って、マシンごとにトランスポートを登録してください。

エンドポイント

2つのStreamable HTTPエンドポイントで、1つのBearerトークンを共有します。 GET /healthと、読み取り専用の GET／HEAD（/.well-known/oauth-protected-resourceおよびその /mcp、/worker-mcp配下のパス）、さらに /.well-known/mcp/server-card.jsonは、シークレットなしで利用できます。

エンドポイント	ツール	用途
/worker-mcp	ワーカーツールのみ（8個。exec_runは提供しません）	すべての新規クライアントのデフォルト。最小権限で、シェルはありません。
/mcp	完全な互換カタログ（19個のツール）	レガシー専用。ENABLE_EXEC_RUN=trueでない限り、exec_runはフェイルクローズします。
/health	なし（公開）	リバースプロキシの稼働確認。
/ready	なし（Bearerトークンが必要）	OpenCodeとレジストリの準備状態（200/503）。
/metrics	なし（Bearerトークンが必要）	機密データを含まない、上限付きカウンター。

Codex と Claude Code

エンドツーエンドテストが文書化されている場合を除き、プロトコルレベルの互換性 （Bearerヘッダーを使用する、Streamable HTTP経由のMCP）です。 マトリックス、ステータスラベル、初回呼び出しの仕様： 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 を使用します。Git マーケットプレイスから v0.6.0 に固定してインストールし、上記のとおり独自のトランスポートを登録してください（同梱の プレースホルダー 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

推奨トランスポート：type: http、 url: ${OPENCODE_MCP_URL}、ヘッダー Authorization: Bearer ${OPENCODE_MCP_BEARER_TOKEN} を指定したプロジェクトの .mcp.json エントリ （読み込み時に展開されるため、トークンはファイルに残りません）。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"

シェルで展開したヘッダーを使うと、シークレットがローカル設定に保存されます。設定ファイルが漏えいした場合は、トークンをローテーションしてください。推奨：このリポジトリの Claude マーケットプレイスにある 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 パッケージもありません。どちらのマーケットプレイスも、この 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}、8 つの 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_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 と、安全に再試行する場合は任意で requestID を指定して worker_run を実行します（同じ入力で再試行すると 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 を実行します。ワーカーの概要だけを信用してはいけません。
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 を公開しません。ワーカートークンが漏えいしても、 直接シェルを実行することはできません。シェルを使う想定がない環境では、 /mcp を公開したり ENABLE_EXEC_RUN=true を設定したりしないでください。
• ローテーション：MCP_BEARER_TOKEN_SECONDARY に一時的に併用するトークンを 1 つ設定します。クライアントを移行し、昇格して再起動します。空の値や 重複する値は安全側に失敗します。
• シークレットなしで公開されるのは、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

公開とディスカバリー

リポジトリ内でシークレットなしで設定する項目：io.github.ManuOtel/opencode-mcp-bridge 用の安全な /worker-mcp メタデータを含む server.json、ManuOtel の申請情報を 含む glama.json、およびダッシュボード／CLI 経由の Smithery。公開には所有者本人の ログインが必要です。チェックリスト：docs/registry.md。 レジストリエントリーはソフトウェアを掲載するものであり、アクセス権を付与したり、 トークンを提供したりするものではありません。デフォルトは /worker-mcp （ツール 8 個、シェルなし）です。/mcp（ツール 19 個、exec_run はオプトイン）は レガシーです。自分が運用していないエンドポイントを公開したり、トークンを コミットしたりしないでください。

コミュニティとライセンス

コードやドキュメントを変更する前に CONTRIBUTING.md を 読んでください。行動規範を遵守し、セキュリティ上の 問題は SECURITY.md に従って報告してください。 機能ブランチからイシューを作成 するか、プルリクエストを送信 してください。

ライセンス：PolyForm Noncommercial 1.0.0。非商用利用は無料です。 LICENSE.md を参照してください。商用利用には許可が必要です： [email protected]