Relay

@relaygpu/mcp

Relay の MCP サーバーです。エージェントは Claude Code、Cursor、VS Code、Claude Desktop から、Relay のモデルの検索、入力スキーマの確認、実行、長時間タスクのポーリング、ファイルのアップロード、ワークフローの実行、Relay のドキュメントの検索を行えます。@relaygpu/client を基盤に構築されています。ツールは汎用的で、モデルを文字列として受け取るため、Relay にモデルが追加されても新しいリリースは必要ありません。

ホスト型サーバーに接続するか、ローカルで実行します。

	方法	認証情報
ホスト型（Streamable HTTP）	https://mcp.relaygpu.com/mcp。インストール不要です	X-API-Key: relay_sk_... ヘッダー、または Authorization: Bearer <relay key or dashboard JWT>
ローカル（stdio）	npx -y @relaygpu/mcp（Node ≥ 20）	実行環境に RELAY_API_KEY=relay_sk_... を設定します。RELAY_BASE_URL は任意です（デフォルトは https://relaygpu.com）

サーバーがキーを保存することはありません。ホスト型サーバーは各リクエストからキーを読み取り、そのリクエストにのみ使用します。ローカルサーバーは実行環境からキーを読み取ります。

インストール

Claude Code、Codex、Cursor、VS Code はホスト型サーバーに接続するため、Node も npx も不要です。Claude Desktop は OAuth 経由でのみリモートサーバーを利用できますが、v0 ではまだ対応していないため、ワンクリックバンドルを使ってローカルサーバーに接続します。どのクライアントでもローカルサーバーを実行できます。詳しくはローカルサーバーをご覧ください。

Claude Code

CLI と VS Code／JetBrains 拡張機能のどちらでも、ターミナルで次を実行します。

claude mcp add --transport http --scope user relay https://mcp.relaygpu.com/mcp --header "X-API-Key: relay_sk_..."

--scope user を指定すると、すべてのプロジェクトで利用できます。指定しない場合、サーバーはコマンドを実行したディレクトリでのみ利用できます。新しいセッションで /mcp を実行して確認してください。ターミナルに command not found: claude と表示される場合、拡張機能はインストールされていますが、CLI はインストールされていません。curl -fsSL https://claude.ai/install.sh | bash（または npm install -g @anthropic-ai/claude-code）でインストールしてください。

Codex

Codex は環境変数から Bearer トークンとしてキーを送信するため、キーは config.toml に保存されません。シェルのプロファイルに RELAY_API_KEY を設定してから、次を実行します。

codex mcp add relay --url https://mcp.relaygpu.com/mcp --bearer-token-env-var RELAY_API_KEY

Cursor

ボタンをクリックすると、下記のエントリーがプレースホルダーキー付きでインストールされます。その後、Cursor の MCP 設定で relay_sk_... を置き換えてください。手動で設定する場合は、~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1 つのプロジェクト）を編集します。

{
  "mcpServers": {
    "relay": {
      "url": "https://mcp.relaygpu.com/mcp",
      "headers": { "X-API-Key": "relay_sk_..." }
    }
  }
}

VS Code（Copilot エージェントモード）

この設定では、VS Code 独自のエージェント（Copilot Chat）にサーバーをインストールします。VS Code 内で Claude Code を使用する場合は、代わりに Claude Code のコマンドを使ってください。Claude Code 拡張機能は VS Code の MCP 設定を読み込みません。

VS Code はキーを一度だけ要求し、シークレットストレージに保存します。手動で設定する場合は、.vscode/mcp.json（1 つのワークスペース）を編集するか、MCP: Open User Configuration（すべてのワークスペース）を使用します。

{
  "inputs": [{ "type": "promptString", "id": "relay-key", "description": "Relay API key (relay_sk_...)", "password": true }],
  "servers": {
    "relay": {
      "type": "http",
      "url": "https://mcp.relaygpu.com/mcp",
      "headers": { "X-API-Key": "${input:relay-key}" }
    }
  }
}

Claude Desktop

1. relay.mcpb をダウンロードします。
2. ダブルクリックします。Claude Desktop にインストールダイアログが表示されたら、Install をクリックします。
3. 拡張機能はオフの状態でインストールされます。Settings → Extensions → Relay → Configure を開きます。
4. Relay キーを貼り付けて、Save をクリックします。キーは Claude Desktop のセキュアストレージに保存されます。
5. Relay をオンにします。

このバンドルは Claude Desktop に組み込まれた Node で動作するため、ほかに何もインストールする必要はありません。get_credits と get_usage はアカウント情報を読み取るため、ダッシュボード JWT またはカスタムティアのスーパーキーが必要です。通常のキーは使えません。それ以外のすべてのツールは通常のキーで動作します。

手動で設定する場合：Settings → Developer → Edit Config を開くと、既定のエディターで claude_desktop_config.json が開きます。以下のブロックを最上位に追加して保存し、Claude Desktop を終了（⌘Q）してから再起動します。

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "@relaygpu/mcp"],
      "env": { "RELAY_API_KEY": "relay_sk_..." }
    }
  }
}

ローカルサーバー（stdio）

代わりに、どのクライアントでもサーバーをお使いのマシン上で実行できます。そのためには、クライアントが参照する PATH に Node 20 以降が必要です（トラブルシューティングを参照）。

claude mcp add relay --scope user --env RELAY_API_KEY=relay_sk_... -- npx -y @relaygpu/mcp
codex mcp add relay --env RELAY_API_KEY=relay_sk_... -- npx -y @relaygpu/mcp

Cursor（~/.cursor/mcp.json）と VS Code では、上記の Claude Desktop のブロックと同じ command / args / env エントリーを使用します。VS Code では "type": "stdio" も追加し、"servers" の下に記述します。

すぐにコピーできるファイルは examples/ にあります。

トラブルシューティング

• 「Server disconnected」、「spawn npx ENOENT」、または「Executable not found: npx」（Claude Desktop、Cursor）：Dock やスタートメニューから起動したアプリはシェルのプロファイルを読み込まないため、nvm、Volta、Homebrew でインストールした Node は PATH に含まれません。Claude Desktop のバンドルを使うか、"command" にフルパスを指定します。ターミナルで which npx を実行し、結果を貼り付けてください（例：/Users/you/.nvm/versions/node/v22.22.0/bin/npx）。
• TypeError: Relay: no global fetch：クライアントが Node 16 以前を起動しています。Node 20 以降をインストールするか、"command" が新しい npx を指すようにしてください。
• Windows：クライアントが npx を起動できない場合は、"command": "cmd" を使い、"args": ["/c", "npx", "-y", "@relaygpu/mcp"] を指定してください。
• 初回の起動には数秒かかります：npx がパッケージを一度ダウンロードします（約 5 秒）。2 回目以降の起動は約 1 秒です。

ツール

keyless と記されたツールは、ローカルサーバー上で認証情報なしで動作します。それ以外は課金対象またはアカウント用のツールであり、認証情報が必要です。OAuth が有効なホスト型サーバー（セルフホスティングを参照）では、keyless ツールを含め、認証情報なしのリクエストは受け付けません。

ツール	機能	例
search_models keyless	タグやテキストでモデルを検索します。image-to-image では、入力画像を受け取るすべての画像モデル（accepts: ["image"]）も一覧表示します	「Kling の text-to-video モデルを探す」→ {tag: "text-to-video", query: "kling"}
get_model keyless	1つのモデルのルート、リクエストスキーマ、例、料金、ステータスを取得します	{model: "Qwen/qwen-image"}
get_pricing keyless	media_storage SKU を含む、1つまたはすべてのモデルの公開料金を取得します	{model: "KlingTeam/v3-T2V"}
estimate_cost keyless	公開料金表に基づいて見積もります（請求書ではありません）	{model: "KlingTeam/v3-T2V", usage: {duration_seconds: 5, quality_mode: "std"}}
run_model	名前を指定して任意のモデルを実行し、最大45秒待機します	{model: "Qwen/qwen-image", input: {prompt: "a red fox", size: "512x512"}}
check_task keyless	タスクの状態を確認します（最大30秒待機します）	{task_id: "direct:…", wait_seconds: 30}
upload_file	ファイルをホストして、任意の *_url 入力（または画像エディターの image）用の URL を取得するか、ホスト型サーバー上のローカルファイル用の1回限りのアップロードスロットを取得します	{path: "./clip.mp4", retention: "relay1d"} · {slot: true}
list_workflows	ワークフローテンプレートを一覧表示します	「実行できるワークフローは？」
run_workflow	ワークフローの実行を開始し、最大45秒待機します	{workflow_id: "script-voiceover", inputs: {messages: [{role: "user", content: "a lighthouse at dusk"}], voice: "Cherry"}}
check_workflow_run keyless	実行の状態を確認します（最大30秒待機します）	{run_id: "…", wait_seconds: 30}
cancel_workflow_run	進行中の実行をキャンセルします	{run_id: "…"}
get_credits	クレジット残高、プロモーション、消費量を取得します（JWT またはカスタムティアのスーパキー）	「クレジットはあといくつありますか？」
get_usage	使用状況の分析データを取得します（JWT またはカスタムティアのスーパキー）	{period: "7d"}
search_docs keyless	Relay のドキュメントを検索します	{query: "idempotency key"}

ローカルファイル

ホスト型サーバーは、お使いのコンピューター上のファイルを読み取れません。クライアントごとのローカルファイルからモデルへの受け渡し方法は次のとおりです。

クライアント	ローカルファイル → モデル
Claude Code、Cursor、VS Code、Codex（ホスト型サーバー）	upload_file({slot: true}) は curl の行を返します。エージェントがファイルのパスを指定してシェルで実行すると（シェルにキーは不要、1回限り、10分間有効）、ファイルの url が出力されます。その url を run_model に渡します（たとえば image として）。
claude.ai、Claude Desktop、ChatGPT	upload_file({slot: true}) はリンクを返します。リンクをブラウザーで開いて写真を選び、ページに表示されたリンクをチャットに貼り付けます。モデルがそのリンクを run_model に渡します。キーがチャットの外に出ることはなく、1回限りで10分間有効です。ファイルの公開 URL も使用できます。
ローカルサーバー（stdio）、任意のクライアント	upload_file({path: "./photo.png"}) はファイルをアップロードし、その url を返します。

画像エディター：search_models({tag: "image-to-image"}) は、入力画像を受け取るすべての画像モデルを、それぞれ accepts: ["image"] とともに一覧表示します。

メモ

• 認証。 ローカルサーバーと、OAuth なしのホストサーバーでは、tools/list と認証情報不要のツールは認証情報なしで応答します。OAuth が有効なホストサーバーでは、認証情報なしの /mcp リクエストすべてに 401 と WWW-Authenticate: Bearer resource_metadata="…", scope="relay" を返します。これにより、クライアントは「Connect Relay」のサインインを開始します。X-API-Key と Authorization: Bearer <relay key or dashboard JWT> は引き続き使用できます。課金対象のツールを認証情報なしで呼び出すと、設定すべき値（ホストサーバーでは X-API-Key ヘッダー、stdio では RELAY_API_KEY）を示す MISSING_CREDENTIALS ツールエラーが返ります。Relay からのエラーは、エラークラス、code、requestId、サーバーの詳細を含むツールエラーとして返されます。キーがツールの結果やログ行に表示されることはありません。
• 長時間タスク。 run_model は最大 45 秒待機します（wait_seconds、0～45）。その後もタスクが実行中の場合は、task_id と「Do not resubmit: call check_task with this task_id」という行を返します。各送信には Idempotency-Key が付与されるため、再試行しても二重に課金されません。エージェントが同じ送信を再度行う可能性がある場合は、独自の idempotency_key を渡してください。0.1.7 以降、入力スキーマで async を受け取るすべてのモデル（画像、動画、音声）はタスクとして送信されるため、長時間の画像生成では task_id が返され、524 は返されません。チャットモデルは引き続きその場で応答します。
• 有効期限。 各結果リンクには有効期限が付いており、「store_output が設定されていない場合、完了から 1 時間後に期限切れ」と示されます。結果をより長く保持するには、get_pricing の media_storage SKU（例：relay7d）を指定して store_output を渡してください。この SKU にはファイルごとの料金が加算されます。
• 画像リンク。 base64 を返す画像ルート（Gemini、gpt-image、FLUX-2-pro）は、Relay 独自のリンク（urls）も返します。サーバーは base64 の代わりにこれらのリンクを、1 時間または store_output の保持期間にわたって返します。Relay リンクを伴わない base64 を含む結果は、/v2/files 経由でアップロードされ（store_output の保持期間、未設定の場合は relay1h、日次クォータ内なら無料）、URL と file_id が返されます。画像コンテンツブロックはオプトインです。inline_images: true を渡すと、1 MB 以下の画像に適用されます。
• アップロード。 stdio では、upload_file により最大 100 MB のローカル path をストリーミングできます。ホストサーバーからディスクを読み取ることはできません。slot: true（ローカルファイルを参照）、最大 4 MB の base64、または公開 url を使用してください。保持期間のデフォルトは relay1h です。

セルフホスト

docker build -t relaygpu-mcp .
docker run -p 2300:2300 -e PORT=2300 -e RELAY_BASE_URL=https://relaygpu.com relaygpu-mcp

サーバーは PORT（デフォルトは 2300）でリッスンし、RELAY_BASE_URL で Relay を呼び出します。エンドポイント：

• POST /mcp：ステートレスな Streamable HTTP です。
• GET /healthz：{status, version} を返します。
• GET /metrics：mcp_tool_calls_total{tool,outcome} と mcp_tool_seconds{tool} を含む Prometheus 形式のテキストです。
• GET /.well-known/mcp/server-card.json：サーバーとそのツールを返します。
• GET /.well-known/oauth-protected-resource（および …/mcp）：OAuth が有効な場合のみ、RFC 9728 の保護対象リソースメタデータを返します。

OAuth（「Connect Relay」）

OAUTH_ISSUER と MCP_RESOURCE_URL の両方が設定されている場合、OAuth は有効です。どちらか一方でも未設定の場合、サーバーは上記と同じ動作をします（メタデータルートはなく、認証情報なしでキー不要のツールが応答します）。3 つの変数はすべて MCP アプリに属し、起動時に一度だけ読み込まれます。

変数	本番環境	ステージング（VPN）	備考
OAUTH_ISSUER	https://relaygpu.com	https://staging-back-c54ef4a.opengpu.network	Relay の認可サーバーです。JWKS は {issuer}/v2/oauth/jwks から読み込まれ、交換リクエストは {issuer}/v2/oauth/token に送信されます
MCP_RESOURCE_URL	https://mcp.relaygpu.com/mcp	http://relay-mcp-staging.internal.opengpu.network/mcp	このサーバーの公開 /mcp URL です。アクセストークンの aud はこの URL と一致する必要があります。メタデータ URL は、この URL のオリジンに /.well-known/oauth-protected-resource を付加したものです
OAUTH_MCP_CLIENT_SECRET	シークレット	シークレット	relay-mcp クライアントのシークレットです。同じ環境における Relay の OAUTH_MCP_CLIENT_SECRET と同じ値を設定してください。環境間で共有してはいけません。設定されていない場合、すべての交換が失敗します（503）

OAUTH_ISSUER が発行した JWT である Bearer 値はアクセストークンです。サーバーはそのトークンを検証し（発行者の JWKS を使用した ES256、aud、60 秒の許容誤差を含む exp）、Relay に送信して 5 分間有効な Relay 認証情報と交換します。その認証情報は、有効期限の 30 秒前までトークンハッシュごとにメモリ内に保持されます。不正、期限切れ、または失効したトークンには WWW-Authenticate: Bearer error="invalid_token", … を付けて 401 を返します。認可サーバーに到達できない場合は 503 を返します。トークン、認証情報、シークレットがログに記録されることはありません。

ログは stderr に JSON 行形式で出力され、デフォルトでは WARNING 以上です（LOG_LEVEL）。Docker を使わない場合は、npm ci && npm run build && node dist/http.js を実行してください。

ライセンス

MIT