MCP / API の仕様

Retro Game Gather（RGG）は、日本で発売されたレトロゲームのデータベースと、利用者の記録（マイライブラリ・ウィッシュリスト・プレイ記録など）を、MCP と REST API で提供します。どちらもツールを呼び出す形で、ツールの名前・引数・結果は共通です。REST API は 66 のツールを提供し、MCP はそのうちファイル出力の 2 つを除く 64 のツールを提供します。

RGG が提供するのは、ゲームの検索・参照、記録の追加・更新・削除、確定的な集計、ファイル出力（REST API のみ）です。紹介文の作成やおすすめは、呼び出し側（AIツールやプログラム）の役割です。

接続先

方式	接続先	認証
MCP	`https://game.retrogather.com/mcp`	OAuth 2.1、または APIキー
REST API	`https://game.retrogather.com/rest/v1`	APIキー

MCP はステートレスな Streamable HTTP で、POST だけを受け付けます（GET / DELETE は 405）。受け付けるプロトコルの版は 2026-07-28、2025-11-25、2025-06-18、2025-03-26 です。

REST API の呼び出し方はREST API、各ツールの一覧はツールリファレンス、引数と応答の詳細はAPI リファレンスを参照してください。

このドキュメントは、AIツール（コーディング用の AI など）に読ませるためのテキストでも公開しています。開発者向けのページだけなら developers.txt、全ページなら llms-full.txt を渡してください。一覧は llms.txt にあります。

認証

OAuth（MCP）

MCP クライアントは、RGG の認可サーバーで OAuth 2.1（認可コード + PKCE）の認可を受けます。認可サーバーのメタデータは /.well-known/oauth-authorization-server、保護リソースのメタデータは /.well-known/oauth-protected-resource で公開しています。クライアント登録は Client ID Metadata Document と動的クライアント登録の両方に対応します。

利用者は RGG にログインし、許可画面で許可する権限を選びます。アクセストークンはリフレッシュトークンで更新できます。

APIキー

APIキーは、利用者がユーザー設定の MCP / APIで発行します。Authorization: Bearer <APIキー> の形で送ります。REST API と MCP の両方で使えます。

キーは rgg_ で始まり、発行時に一度だけ表示されます
有効期限はありません。利用者が削除すると、数分以内に使えなくなります
権限は発行時に決まり、あとから変更できません。別の権限が必要なら発行し直します
1 人が持てる有効なキーは 10 件までです

権限（スコープ）

ゲーム情報・ライブラリ・プレイ記録の 3 つの区分に、閲覧（read）・編集（write）・削除（delete）があります。ゲームマスタの一括ダウンロードだけは games:bulk です。OAuth と APIキーで同じ権限の語彙を使います。

スコープ	対象
`games:read`	ゲームの検索・詳細、プラットフォーム・発売元・ジャンルの一覧、ニュース、利用者のカスタムデータの閲覧
`games:write`	利用者のカスタムデータ（プラットフォーム・発売元・ゲーム）の追加・変更
`games:delete`	利用者のカスタムデータの削除
`games:bulk`	ゲームマスタの一括ダウンロード（`exportMasterData`）。APIキーだけで使います
`library:read`	マイライブラリ、所有ソフト、ウィッシュリスト、ゲームタグ、マイコレクションの閲覧
`library:write`	上記の追加・変更
`library:delete`	上記の削除
`play:read`	プレイ記録、プレイログ、ゲーム機、メンテナンス記録の閲覧
`play:write`	上記の追加・変更
`play:delete`	上記の削除

write・delete・bulk は、同じ区分の read を含みます。delete は write を含みません
カスタムデータの write / delete で、RGG の公式データは変更できません
OAuth で最初に要求される権限は games:read library:read library:write play:read play:write です
許可画面では、削除の権限を既定でオフにして表示します。プレミアムプランの利用者には、games:write も表示します。クライアントが要求していない権限も、利用者が許可画面で選べます
既存のトークンに権限が後から加わることはありません。利用者が連携し直して選んだときだけ加わります
OAuth では games:bulk を発行しません
APIキーは、ゲーム情報の閲覧があれば games:bulk を含みます。プランが対応しているかは実行時に判定します

権限が足りない呼び出しは 403 になります。エラーの message は、足りない権限、連携し直す手順、何も変更していないことを英文で伝えます。data には reason と scopes（足りない権限）が入ります。

プラン

ツールごとに使えるプラン（FREE / LIGHT / PREMIUM）が決まっています。プランで使えないツールは、そのプランのツール一覧に出ません。プランは実行時に判定し、プランの変更は最大 5 分で反映されます。

プランごとの違いはMCP / APIとツールリファレンスを参照してください。登録件数の上限はアプリと共通で、getAccount で現在の件数と上限を取得できます。

利用上限

利用者ごとに、MCP と REST API を合わせた 1 日の利用上限があります。上限はプランによって異なり、日本時間の 0 時にリセットされます。呼び出しの種類によって消費する量が異なり、一覧・検索・分析・ダウンロードは単件の参照より多く消費します。

上限に達すると 429 と Retry-After を返します。日次の上限では、再開時刻（resetAt）も返します
短時間に集中した呼び出しも、一時的に 429 になります
応答ヘッダーの X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset で残量を確認できます
利用者は、設定画面と getAccount の usage で今日の使用率（%）を確認できます
本文を返せなかったダウンロードは、消費した分を戻します
削除の確認（1 回目の呼び出し）は日次の上限を消費しません

応答

MCP の結果

すべてのツールが inputSchema と outputSchema を公開しています。結果の本体は structuredContent です。content は、短い要約と、structuredContent と同じ内容の JSON 文字列の 2 つのテキストで構成します。次の操作の案内は structuredContent の hint に入ります。

REST の結果

REST API は、structuredContent と同じ内容を JSON の本文として返します。

値の表し方

MCP は、値が無い項目を省略します（null を返しません）
REST は、ゲームの情報（検索・詳細と、一覧に含まれるゲーム）の値が無い項目を null で返します。ファイル出力の値が無い列も null です。REST を使う場合は、項目が無いことと null を、どちらも値が無いものとして扱ってください
要求した配列グループが空の場合は、MCP・REST とも [] を返します
日付は YYYY-MM-DD、日時は日本時間のオフセット付き（+09:00）です
revision は照合用の値です。解釈せず、そのまま送り返してください
一覧の配列は items に入ります
ゲームの外部リンク（externalLinks）は、MCP では完成した URL、REST とファイル出力では外部サービスの ID で返します。REST の IGDB の ID はIGDB の識別子を参照してください

ページング

一覧は page と limit で取得します。続きがある場合は hasMore が true になります。条件・並び順・fields・limit を変えずに page を進めてください。取得中に更新されたデータの、時点を固定した取得は保証しません。

fields を指定すると、返すグループを選べます。省略するとツールごとの既定、[] は最小限の項目だけを返します。fields の内容によって 1 ページの上限件数が下がることがあり、その場合は effectiveLimit・limitReduced・limitReason で分かります。

更新と競合

更新では、省略した項目はそのまま残ります。null を送ると値を解除し、配列に [] を送ると全件を解除します
ゲームタグやマイコレクションのゲームの集合を置き換える操作、所有ソフトの操作では、読み取り時の revision が必要です。書き込みが成功したときに返る新しい revision は、次の書き込みに使えます
revision が合わない場合は競合として拒否します。最新の状態を取得し直し、更新内容を組み直してから送ってください

削除の確認

削除は 2 回の呼び出しで実行します。

1 回目は何も変更せず、削除する対象・一緒に消えるもの・confirmToken を返します
同じ引数に confirmToken を加えて呼び出すと、削除を実行します

confirmToken の有効期限は 10 分です。確認の間に対象が変わった場合は、実行せずに再確認を求めます。

1 回目の結果を利用者に示し、同意を得てから 2 回目を呼び出すのは、呼び出し側の責務です。 RGG は、利用者が確認したかどうかを検証しません。

削除すると一緒に消えるデータがあります。たとえば removeFromLibrary は、そのゲームのプレイ記録・プレイログ・所有ソフトも削除します。

エラーの後の確認

saved: true を含むエラーは、保存は完了しています。返された ID や結果を使い、同じ追加を送り直さないでください
応答が失われた場合も、未保存とは限りません。各ツールの説明にある読み取り先で状態を確かめてから、再送するかを決めてください
追加の直後に一覧に現れないことだけを理由に、再送しないでください。一覧への反映は遅れることがあります
プレミアムプランの再プレイ（addPlayRecord の replay: true）は、送るたびに新しい記録を作ります。結果が不明な場合は getGamePlayHistory で確かめてください
一時的な失敗は retryable: true と Retry-After を返します。この場合は同じ呼び出しを再試行できます

提供範囲

ゲームデータベースの対象は、日本で発売されたレトロゲームです。現行の家庭用ゲーム機は対象外です。公式データは日次で更新されるため、訂正の反映に最大 1 日かかります。

次の操作は提供していません。

画像の登録・取得
MCP でのファイル出力（REST API の exportMyData・exportMasterData を使います）
属性の定義の編集、公式タグの編集・コピー
マイライブラリ以外の一括登録（マイライブラリは addToLibraryBatch で 1 回 100 件まで）
ニュースの設定・ブックマーク、ユーザー設定の変更

利用条件

MCP・REST API で取得したゲームデータと、ダウンロードしたファイル（REST API のファイル出力、アプリのゲーム一覧のエクスポート）は、会員本人が次の範囲で利用できます。

個人での利用（自分の表計算での管理、AIツールでの分析など）
会員が作るアプリ・ツール・サイトへの組み込み。この場合は、データの出典が Retro Game Gather であることを明示してください

ダウンロードしたファイルそのもの、またはそれと実質的に同じ一覧を第三者に配布・公開することは、出典を明記した場合も含めて禁止しています（リポジトリやデータセットとしての公開を含みます）。アプリ・ツールに内包して画面に表示するのは、組み込みの範囲に含みます。

これらの条件の対象は、Retro Game Gather が提供するゲームデータ（ゲーム・プラットフォーム・発売元・ジャンル）です。自分で登録した記録や、プレミアムプランで追加したカスタムデータは自分のデータなので、exportMyData などで取得した場合も対象になりません。

外部サービスの ID・リンク先（IGDB、メディア芸術データベースなど）の利用は、各提供者の規約に従います

詳しくは利用規約を参照してください。