relay-mcp

relay-mcp

このリポジトリは、オープンソースのリファレンス実装です。作者は別の URL で非公開のデプロイ済みインスタンスを運用していますが、本番環境ではご自身のインスタンスをデプロイしてください。

Claude 用のセルフホスト可能なセッションリレーです。複数の Claude の利用環境（Code、Cowork、Claude.ai コネクター）をまたいで作業する場合、各環境はそれぞれ独自のコンテキストウィンドウで動作します。このリレーは、すべての環境が投稿や読み取りをできる共有メッセージスレッドを提供します。そのため、Code セッションから Chat セッションへ状態を引き継いだり、スケジュールされた Cowork タスクがメモを残し、それを朝の Chat セッションで確認したりできます。ログやメモリーストアではなく、軽量なホワイトボードです。

ツール

サーバーは 6 つの MCP ツールを公開します。

ツール	説明
relay_list_threads	最終アクティビティとメッセージ数を含むスレッド一覧を取得します。
relay_create_thread	名前付きスレッドを作成します。
relay_post_message	スレッドにメッセージを投稿します。スレッドがない場合は自動的に作成します。
relay_read_thread	新しい順に最近のメッセージを読み込みます。カーソルの更新は任意です。
relay_check_new	この読み手が前回確認してからのメッセージのみを返します。
relay_archive_thread	スレッドをソフトアーカイブします。履歴は保持されます。

すべてのメッセージには surface フィールド（chat、cowork、code、other）と、任意のフリーテキスト session_tag が含まれるため、多数の並行セッション間でもスレッドを判別できます。

アーキテクチャ

• src/index.ts の Cloudflare Worker。ステートレスです。/mcp でストリーミング可能な HTTP MCP を提供します。

• スレッド、メッセージ、読み取りカーソルの保存には Supabase Postgres を使用します。テーブルは 3 つで、すべて relay_ がプレフィックスです。RLS は有効ですがポリシーはなく、読み書きできるのは Worker のサービスロールキーのみです。

• 同一サーバー上の 2 つの認証方式：

  • Claude Code と Cowork 向けの 静的 Bearer：Authorization: Bearer <RELAY_API_KEY>。可能な限りシンプルで、ブラウザフローはありません。
  • Claude.ai カスタムコネクター向けの Dynamic Client Registration を使用する OAuth 2.1。Worker は /.well-known/oauth-authorization-server、/register、/authorize、/token を公開します。アクセストークンは RELAY_API_KEY で署名された HS256 JWT です。ステートレスで、KV や Durable Objects は不要です。アクセストークンの有効期間は 90 日、リフレッシュトークンは 365 日です。

  認証、ローテーション、脅威モデルをまとめた説明については、Security を参照してください。

• v1 では シングルテナントです。Worker は RELAY_USER_ID シークレットからハードコードされたユーザー UUID を読み込みます。マルチユーザー対応は、src/oauth.ts の 1 ファイルの変更と RLS ポリシーのマイグレーションで実現できます。スキーマにはすでに user_id カラムがあります。

独自のインスタンスをデプロイする

セルフホストには約 10 分かかります。Cloudflare アカウント（Workers の無料プランで問題ありません）、Supabase プロジェクト、ローカル環境の Node 20 以降が必要です。

1. クローンしてインストール

git clone https://github.com/zhowe-designs/relay-mcp.git
cd relay-mcp
npm install

2. Supabase プロジェクトを作成してマイグレーションを実行する

supabase.com で新しいプロジェクトを作成します。SQL エディターに migrations/001_initial.sql を貼り付けて実行してください。これにより relay_threads、relay_messages、relay_read_cursors が作成され、インデックスが設定され、ポリシーなしで RLS が有効になり、anon と authenticated の権限が取り消されます。

Project Settings → API から、次の値をコピーします。

• Project URL（https://abcdef.supabase.co のような形式）。
• service_role キー。データベースのパスワードと同様に扱ってください。

3. テナント UUID を選ぶ

UUID を生成します（uuidgen、crypto.randomUUID()、または任意の UUID v4 ジェネレーターを使用します）。これは v1 サーバーが紐付けられる唯一のユーザーです。後から変更できますが、ある UUID で投稿された内容は、別の UUID では表示されません。

4. Worker シークレットを設定する

npx wrangler login
npx wrangler secret put RELAY_API_KEY        # any random 32+ char string, your bearer
npx wrangler secret put SUPABASE_URL          # https://<project-ref>.supabase.co
npx wrangler secret put SUPABASE_SERVICE_KEY  # service_role key from step 2
npx wrangler secret put RELAY_USER_ID         # UUID from step 3

5. デプロイする

npx wrangler deploy

Wrangler にデプロイ済み URL（https://relay-mcp.<your-subdomain>.workers.dev のような形式）が表示されます。この URL に /mcp を付けたものが MCP エンドポイントです。

6. 任意：カスタムドメイン

wrangler.toml を編集し、routes ブロックのコメントを解除して、relay-mcp.example.com を所有する Cloudflare ゾーン内のホスト名に置き換えます。npx wrangler deploy を再実行してください。Wrangler が CNAME を自動的に作成します。

7. スモークテスト

RELAY_URL=https://relay-mcp.<your-subdomain>.workers.dev RELAY_API_KEY=<your-key> \
  node --experimental-strip-types scripts/smoke.ts

OAuth フローを含む40個のアサーションです。すべて成功すれば、稼働しています。

クライアントの設定

<RELAY_URL> をデプロイした URL に、<RELAY_API_KEY> を上記で設定したシークレットに置き換えてください。

Claude Code

プロジェクトルートの .mcp.json に追加するか、グローバルにアクセスする場合は ~/.claude.json に追加してください。

{
  "mcpServers": {
    "relay": {
      "type": "http",
      "url": "<RELAY_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <RELAY_API_KEY>"
      }
    }
  }
}

Claude Code を再起動し、/mcp を実行して、6つのツールとともに relay が表示されることを確認してください。

Cursor

プロジェクトルートの .cursor/mcp.json に追加するか、グローバルにアクセスする場合は ~/.cursor/mcp.json に追加してください。

{
  "mcpServers": {
    "relay": {
      "type": "http",
      "url": "<RELAY_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <RELAY_API_KEY>"
      }
    }
  }
}

Cursor を再起動し、MCP の設定を開いて、6つのツールとともに relay が表示されることを確認してください。

注意点：relay ブロックは mcpServers オブジェクトの内側に配置する必要があります。Cursor はファイルのトップレベルで定義されたサーバーを無視します。ツールが表示されない場合は、まずここを確認してください。

Cowork のスケジュール済みタスク

relay へのアクセスが必要なタスクのプロンプトに、mcp_servers ブロックを追加してください。

mcp_servers:
  relay:
    type: http
    url: <RELAY_URL>/mcp
    headers:
      Authorization: "Bearer <RELAY_API_KEY>"

Claude Desktop

Claude Desktop の MCP サポートでは、リモート HTTP URL ではなく stdio コマンドが必要です。リモート relay に接続するには、stdio で起動したプロセスをリモート HTTP MCP サーバーに適合させるブリッジ、mcp-remote を使用してください。

claude_desktop_config.json を開き（Windows の場合：%APPDATA%\Claude\claude_desktop_config.json、macOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json）、次を追加してください。

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<RELAY_URL>/mcp",
        "--header",
        "Authorization: Bearer <RELAY_API_KEY>"
      ]
    }
  }
}

Claude Desktop を完全に終了し（ウィンドウを閉じるだけではなく）、再度開いてください。ツールメニューに6つのツールとともに relay が表示されます。

注意点：Claude Desktop は、一部のセッションライフサイクルイベントで claude_desktop_config.json を書き換えるため、手動で追加した mcpServers の設定を予告なく消去することがあります。セッション間で relay が表示されなくなった場合は、ブロックを再追加し、Claude Desktop の設定ディレクトリ外にバックアップを保存して、貼り戻せるようにしてください。以下の Claude.ai カスタムコネクターを使えばこの問題を回避できるため、利用可能であればこちらがおすすめです。

Claude.ai カスタムコネクター

Claude.ai は、relay がサポートする Dynamic Client Registration を使用した OAuth 2.1 を利用します。

1. Claude.ai で 設定 → コネクター → カスタムコネクターを追加 を開きます。
2. 名前：任意の名前（例：Relay）。
3. リモート MCP サーバー URL：<RELAY_URL>/mcp。
4. Advanced OAuth のフィールドは空欄のままにします。登録は Claude.ai が自動的に処理します。
5. 「追加」をクリックします。ブラウザータブで Worker の /authorize ページが開きます。
6. RELAY_API_KEY を入力欄に貼り付け、「Authorize」をクリックします。
7. ブラウザーが Claude.ai にリダイレクトします。コネクターに6つのツールが表示されます。

アクセストークンの有効期間は90日で、自動更新されるため、再認証が必要になることはほとんどありません。認証に失敗した場合は、コネクターを削除して追加し直してください。

トラブルシューティング

実際のデプロイでよくある失敗パターンと、それぞれ最初に確認すべきことを紹介します。

スモークテストが 401 Unauthorized で失敗する。 ローカル環境の RELAY_API_KEY が Worker にデプロイされたシークレットと一致していません。npx wrangler secret put RELAY_API_KEY を再実行し、スモークテストを実行するシェルで同じ値を再度エクスポートしてください。Wrangler はシークレットを設定した後に値を表示しないため、不明な場合は、両方で新しい値にローテーションしてください。

どのツール呼び出しでも Worker が 5xx を返す。 ほとんどの場合、Supabase の service-role キーが設定されていないか、誤って anon キーが設定されています。Supabase の Project Settings -> API -> service_role にある値を使って、npx wrangler secret put SUPABASE_SERVICE_KEY を再実行してください。また、SUPABASE_URL がプロジェクト URL（末尾に /mcp がなく、パスも含まない）であることと、RELAY_USER_ID が有効な UUID v4 であることを確認してください。

カスタムドメインが 530 を返す。 Cloudflare の 530 は DNS 解決エラーです。通常は CNAME の反映がまだ完了していません。数分待ってから再試行してください。問題が解決しない場合は、wrangler.toml のホスト名が実際に所有している Cloudflare ゾーンに属していることと、npx wrangler deploy でルートが関連付けられたと表示されたことを確認してください。

Cursor にリレーのツールが表示されない。 relay ブロックが .cursor/mcp.json のトップレベルにあり、mcpServers オブジェクトの中にありません。Cursor はトップレベルのエントリーを無視します。ブロックを mcpServers の中に移動し、Cursor を再起動してください。

Claude Desktop にリレーのツールが表示されない。 考えられる原因は 2 つあります。1 つ目は、mcp-remote がないか、起動時に npx が取得できないことです（Claude Desktop は stderr を表示しません）。ターミナルで npx -y mcp-remote --help を一度実行して、キャッシュを準備し、インストールエラーがあれば確認してください。2 つ目は、Claude Desktop が claude_desktop_config.json を上書きし、mcpServers のエントリーが消えていることです。バックアップから再度追加し、アプリを完全に終了してから開き直してください。

Claude.ai の OAuth フローで認証ページに戻り続ける。 ブラウザーが Worker ドメインのサードパーティー Cookie をブロックしているか、RELAY_API_KEY の前後に空白を付けて貼り付けています。新しいブラウザープロファイルを試し、キーを慎重に貼り付けて、Worker のログ（npx wrangler tail）で実際のエラーを確認してください。

使用方法

接続したら、意図を伝えます。モデルが適切なツールを選びます。次のような文が使えます。

• 「最後のエラー、マイグレーションの差分、そして自分の仮説を relay スレッド migration-debug に投稿して、surface は code にしてください。」
• 「daily-standup を読んで、今朝 Cowork が投稿した内容をすべて見せてください。」
• 「migration-debug から最後の 10 件のメッセージを取得してください。」

スレッドの命名

短く、ハイフンで区切り、トピックに沿った名前にします。april_migration_issues_2026 ではなく、migration-debug にします。1 日ごとではなく、トピックごとに 1 つのスレッドを使います。スレッドは蓄積され、会話は数週間にわたって続きます。何かを投稿するとスレッドは自動的に作成されるため、開始時に特別な手続きは必要ありません。

適切な例：migration-debug、daily-standup、pricing-notes、scratch。

不適切な例：april-18-bugs、thread-1、general。

surface のタグ付けは必須です

surface には必ず chat、cowork、code、other のいずれかを設定してください。半年後にスレッドを見返すとき、メッセージがスケジュールされた Cowork タスクから届いたのか、進行中の Chat 会話から届いたのかによって、重要度の判断が変わります。surface 内で自由にグループ分けするには、session_tag を使ってください（例：デバッグセッションごとに 1 つのタグを付けます）。

使わなくなったスレッドをアーカイブする

トピックが完了したら、relay_archive_thread を呼び出してください。アーカイブされたスレッドはデフォルトの list_threads の出力には表示されなくなりますが、include_archived を使えば引き続き検索できます。Git ブランチではなく、Slack チャンネルのように考えてください。アーカイブしても履歴は保持され、削除はされません。

境界のルール：一時的なレイヤーであり、正規の状態ではありません

リレーはセッション間の会話レイヤーです。ログでも、意思決定の記録でも、メモリーストアでもありません。来週も必要になる情報はすべて、実際の記録システム（意思決定ログ、タスクトラッカー、ドキュメント、コードコメントなど）に残してください。リレーに記録されるのはその場で話されたことであり、決定されたことではありません。リレーへの投稿に実際の決定事項が含まれる場合は、先に永続的な場所へ記録してから先へ進んでください。

秘密情報は絶対にリレーに投稿しないでください

通常のチャットと同じルールです。API キー、サービスロールトークン、OAuth シークレット、データベースの認証情報は、Wrangler secrets またはパスワードマネージャーに保管してください。リレーのメッセージには絶対に記載しないでください。リレーのデータベースは保管庫ではありません。投稿してはいけない情報の一覧については、セキュリティを参照してください。

セキュリティ

このセクションでは、リレーの認証モデル、キーのローテーション手順、コンテンツのルール、脅威モデルをまとめています。

認証モデル

静的 Bearer。 Claude Code と Cowork は、Authorization: Bearer <RELAY_API_KEY> で認証します。Worker はリクエストごとに、ヘッダーと RELAY_API_KEY シークレットを照合します。ブラウザーフローも、トークン交換も、更新もありません。キーを持っている人は、設定された RELAY_USER_ID のすべてのスレッドに完全にアクセスできます。

DCR を使用した OAuth 2.1。 Claude.ai のカスタムコネクターは、/register、/authorize、/token に対する Dynamic Client Registration を使用した OAuth 2.1 で認証します。ユーザーは RELAY_API_KEY を一度だけ Worker の認証ページに貼り付けます。Worker はこれを検証し、同じ RELAY_API_KEY で署名した HS256 JWT を発行します。アクセストークンの有効期間は 90 日、リフレッシュトークンは 365 日です。サーバー側のセッションストア、KV、Durable Objects はありません。

キーのローテーション手順

次のコマンドで RELAY_API_KEY をローテーションします。

npx wrangler secret put RELAY_API_KEY

想定される影響：

• すべての OAuth トークンが無効になります。 トークンは RELAY_API_KEY で署名された JWT であるため、シークレットを変更すると既存の署名がすべて無効になります。Claude.ai コネクターのすべてのユーザーは、コネクターを削除して再追加し、新しいキーで再認証する必要があります。
• 静的 Bearer クライアントは、再設定するまで動作しなくなります。 .mcp.json、.cursor/mcp.json、claude_desktop_config.json、および Cowork タスク内の mcp_servers ブロックを新しいキーに更新してください。更新されるまで、そのクライアントは 401 を返します。

キーが漏えいした疑いがある場合、アクセス権を持つチームメイトが離れた場合、または脅威モデルに応じた定期的なスケジュールでローテーションしてください。

投稿してはいけない情報

スレッドは Supabase に保存され、RELAY_API_KEY を持つ人なら誰でも閲覧できます。リレーは共有ホワイトボードとして扱い、保管庫として扱わないでください。次の情報は投稿しないでください。

• API キー、サービスロールトークン、OAuth クライアントシークレット、リフレッシュトークン。
• データベースのパスワード、または認証情報が埋め込まれた接続文字列。
• 顧客の個人識別情報（PII）、規制対象データ、または NDA の対象となる情報。
• リレーのバックエンド、Supabase プロジェクト、または API キーを保持するクライアント設定が侵害された場合に問題となる情報。

シークレットは Wrangler secrets またはパスワードマネージャーに保管してください。リレーのデータベースは保管庫ではありません。

脅威モデル

リレーは v1 ではシングルテナントです。RELAY_API_KEY を持つすべてのセッションを運用者が信頼することを前提としています。キーを持つ人は、設定された RELAY_USER_ID のすべてのスレッドを読み書きできるためです。セッションごとのスコープ設定はなく、監査証跡は Worker のログに限られ、Worker と Supabase の間にポリシーレイヤーもありません。マルチユーザーまたはマルチテナントのデプロイには、追加の認証レイヤー（ユーザーごとのキー、スコープ付きトークン、user_id に基づく RLS ポリシー）が必要ですが、ここでは提供されていません。スキーマには拡張を容易にするため、すでに user_id 列が用意されていますが、実装は自分で行う必要があります。

開発

# Typecheck
npm run typecheck

# Local dev (requires .dev.vars, see .dev.vars.example)
npx wrangler dev

# Smoke test
RELAY_URL=<your-url> RELAY_API_KEY=<your-key> npm run smoke:remote

# Rotate a secret (see Security for consequences)
npx wrangler secret put RELAY_API_KEY

スキーマ

relay_ で始まる3つのテーブルがあります。マイグレーションは migrations/001_initial.sql にあります。

• relay_threads。ユーザーごとに、名前付きスレッド1つにつき1行です。
• relay_messages。投稿されたメッセージ1件につき1行です。(thread_id, created_at desc) にインデックスがあります。
• relay_read_cursors。(thread_id, reader_tag) ごとに1行です。このリーダーが最後に確認した時刻を記録します。

サービスロールからのみアクセスできます。RLS は有効ですがポリシーはなく、anon と authenticated の権限は取り消されています。読み書きできるのは Worker のサービスロールキーのみです。

ディレクトリ構成

src/
  index.ts         Worker entry, MCP JSON-RPC protocol, routes
  oauth.ts         OAuth 2.1 facade (metadata, register, authorize, token)
  jwt.ts           HS256 JWT sign, verify, PKCE check
  db.ts            Supabase client factory
  types.ts
  tools/
    threads.ts     list, create, archive, get_or_create
    messages.ts    post, read, check_new
migrations/
  001_initial.sql  three tables + indexes + RLS lockdown
scripts/
  smoke.ts         end-to-end smoke test, includes OAuth
wrangler.toml
package.json
server.json        MCP Registry metadata

コントリビューション

このプロジェクトは、コミュニティによって積極的に保守されているものではありません。バグ修正、ドキュメントの改善、明らかに利便性を高める追加機能については、プルリクエストを歓迎します。機能追加や大規模なリファクタリングは、対象範囲を小さく保つため、却下される可能性が高いです。大きな変更について相談したい場合は、まずイシューを作成してください。

ライセンス

MIT です。LICENSE を参照してください。