AGS API

AGS API MCP Server

AI アシスタント（VS Code Copilot、Cursor、Claude、Gemini、Antigravity）が OpenAPI 統合を通じて AccelByte Gaming Services（AGS）API にアクセスできるようにする、Model Context Protocol（MCP）サーバーです。

できること

• 検索：説明、タグ、メソッド、サービスから AGS API の操作を検索します
• 詳細表示：特定の操作のパラメーター、スキーマ、認証要件を確認します
• 実行：認証済みトークンを使って API リクエストを実行します
• 表示：クエリ結果をチャート、テーブル、メトリクスとして表示します（分析と視覚化を参照）

AccelByte が AGS API MCP Server をホストするため、ローカルにインストールしたり実行したりする必要はありません。AI アシスタントに環境の MCP URL を指定して、サインインするだけです。

---

クイックインストール

これを AI コーディングアシスタントに貼り付けると、インストールガイドを取得し、いくつか質問したうえで、すべてを設定します。

Install the AGS API MCP server for me. Fetch and follow the instructions at
https://raw.githubusercontent.com/AccelByte/ags-api-mcp-server/refs/heads/master/INSTALL.md

VS Code Copilot、Cursor、Claude Code、Antigravity、Gemini CLIで使用できます。

Claude Desktop ユーザーの場合： 最も簡単な方法は、Settings → Connectors → Add custom connector（名前：ags-api、URL：MCP URL）です。AI インストーラーは必要ありません。詳しい手順と、ワークスペースポリシーによってカスタムコネクターがブロックされているアカウント向けの代替方法については、以下のClaude Desktopを参照してください。

上記のクイックインストール用プロンプトを使う場合は、先にCodeタブに切り替えてください（Chat と Cowork では設定ファイルを編集できません）。

自分で設定しますか？ 以下の手動インストールを参照してください。

---

手動インストール

ステップ 1：MCP サーバーの URL を確認する

URL は利用している AGS エディションによって異なります。

エディション	URL の形式
Public Cloud	https://{studio}.prod.gamingservices.accelbyte.io/mcp/{studio}
Private Cloud	https://{domain}/mcp

• Public Cloudのお客様には、登録時に {studio} 名前空間が割り当てられます。この値はサブドメインとパスの両方に、2 回指定します。スタジオ管理者とゲーム管理者は同じ URL を使用します。アクセスできる名前空間は接続先の URL ではなく、割り当てられたロールによって決まります。
• Private Cloudのお客様は、名前空間のセグメントを含めず、それぞれの環境ドメインを使用します。MCP エンドポイントを有効にするため、AccelByte サポートとの調整が必要になる場合があります。

**「Shared Cloud」**は Public Cloud と同じものです。古いドキュメントやサポートスレッドでは、この名称が使われています。

利用しているエディションがわからない場合は、AccelByte 管理者に確認してください。

ステップ 2：クライアントを設定する

デプロイ済みのサーバーは、**OAuth 2.0 と PKCE、Dynamic Client Registration（DCR）**を使用します。クライアントが DCR に対応している場合は、URL に直接接続できます。対応していない場合、または stdio トランスポートのみをサポートしている場合は、ブリッジとして mcp-remote を使用してください。

mcp-remote が必要ですか？ npx を使って実行します。Node.js 18 以降と、利用可能な npx が必要です。npx --version で確認してください。多くのインストーラー（nodejs.org、Homebrew、nvm、Windows 公式インストーラー）では、npm を介して npx が自動的にバンドルされますが、最小構成の Linux ディストリビューションでは、npx を含まずに Node が提供されることがあります。その場合は、パッケージマネージャーから npm をインストールしてください。mcp-remote をグローバルにインストールする必要はありません。

以下に <URL> がある場合は、ステップ 1 で確認した URL に置き換えてください。

Visual Studio Code（Copilot）

ワークスペース内の .vscode/mcp.json（またはユーザーの settings.json）：

{
  "servers": {
    "ags-api": {
      "type": "http",
      "url": "<URL>"
    }
  }
}

DCR エラーが発生する場合は、次の設定に置き換えてください：{ "command": "npx", "args": ["-y", "mcp-remote", "<URL>"] }。

VS Code MCP ドキュメントを参照してください。

Cursor

ワークスペース内の .cursor/mcp.json（またはユーザー設定）：

{
  "mcpServers": {
    "ags-api": {
      "type": "http",
      "url": "<URL>"
    }
  }
}

DCR エラーが発生する場合は、次の設定に置き換えてください：{ "command": "npx", "args": ["-y", "mcp-remote", "<URL>"] }。

Cursor MCP ドキュメントを参照してください。

Claude Code

claude mcp add --transport http ags-api <URL>

フォールバック：claude mcp add ags-api -- npx -y mcp-remote <URL>。

Claude Code の MCP ドキュメントを参照してください。

Antigravity

プロジェクトのルートにある mcp_config.json：

{
  "mcpServers": {
    "ags-api": {
      "type": "http",
      "url": "<URL>"
    }
  }
}

DCR エラーが発生した場合は、次の設定に切り替えてください：{ "command": "npx", "args": ["-y", "mcp-remote", "<URL>"] }。

Antigravity の MCP ドキュメントを参照してください。

Gemini CLI

gemini mcp add --transport http ags-api <URL>

フォールバック：gemini mcp add ags-api -- npx -y mcp-remote <URL>。

Gemini CLI の MCP ドキュメントを参照してください。

Claude Desktop

Claude Desktop には2つのインストール方法があります。ご利用のアカウントで使える最初の方法を選んでください：

オプションA — カスタムコネクタ（個人アカウント／Pro アカウントに推奨）

1. Settings → Connectors → Add custom connector（「Customize」エリア内）を開きます。
2. 次の項目を入力します：
   • Name：ags-api
   • Remote MCP server URL：ステップ1の <URL>
3. 保存します。Claude Desktop は OAuth（DCR + PKCE）をネイティブに処理するため、設定ファイルの編集や mcp-remote は不要です。

「Add custom connector」が表示されませんか？ 一部の Team プランと Enterprise プランでは、ワークスペースポリシーによってカスタムコネクタが無効になっています。このオプションが見つからないか、グレー表示になっている場合は、オプションBを使用してください。

オプションB — mcp-remote 設定ファイル（カスタムコネクタがブロックされている場合のフォールバック）

claude_desktop_config.json を編集します：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ags-api": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "<URL>"]
    }
  }
}

保存後、Claude Desktop を再起動します。

ステップ3：サインイン

AI アシスタントが初めてツールを呼び出すと、OAuth を完了するためにブラウザーで AccelByte が開きます。同意画面を承認すると、接続されます。

---

ツールの使用

接続すると、アシスタントは次のツールを利用できます：

get_token_info

認証済みセッションの詳細（subject、namespace、ロール／権限、トークンの種類、有効期限）を返します。

「現在のユーザー情報を教えてください」

search-apis

説明、HTTP メソッド、タグ、サービスで AGS オペレーションを検索します。

「ユーザー管理用の API を見つけてください」 · 「インベントリエンドポイントを検索してください」

describe-apis

特定のオペレーションの完全なスキーマ（パラメーター、リクエスト／レスポンスの形式、認証要件）を取得します。

「createItem エンドポイントにはどのパラメーターが必要ですか？」

run-apis

API リクエストを実行します。書き込み操作（POST/PUT/PATCH/DELETE）では、実行前に同意を求めます。

「自分のユーザープロフィールを取得してください」 · 「インベントリ内のすべてのアイテムを一覧表示してください」

分析と可視化

このサーバーは、アプリリソースに対応した MCP ホスト内で、表形式のデータをチャート、テーブル、メトリクスに変換する16個のレンダーツールを公開します：

• render_bar_chart、render_line_chart、render_area_chart、render_scatter_chart、render_histogram_chart、render_box_chart、render_heatmap_chart
• render_pie_chart、render_donut_chart、render_waterfall_chart、render_funnel_chart、render_gauge_chart、render_state_timeline_chart
• render_table、render_metric、render_meter

すべてのレンダーツールで provider が必要です：

• provider="facade" は、query_id + namespace を使って Athena Facade の結果を読み込みます
• provider="direct" は、data_columns + data_rows から小規模なインラインデータセットを描画します

Athena Facade の一般的なフロー：

1. run-apis を使って POST /afs/v1/admin/namespaces/{namespace}/queries 経由でクエリを送信します。query_id で描画する予定がある場合は、wait_ms=0 を指定することを推奨します
2. GET /afs/v1/admin/namespaces/{namespace}/queries/{id} をポーリングし、status="SUCCEEDED" になるまで待ちます
3. その query_id を provider="facade" に設定した render_* ツールに渡します

送信が高速パスでインラインの行を含む 200 を返した場合は、provider="direct" でそれらの行を直接描画します。

レンダーツールの入力項目一覧と Athena Facade のオペレーション一覧については、docs/ARCHITECTURE.mdを参照してください。

ワークフロープロンプト

サーバーはワークフローのリソースとプロンプトも提供します。利用可能なワークフローについてアシスタントに尋ねるか、run-workflow プロンプトを呼び出してください。

トラブルシューティング

mcp-remote を起動するたびにブラウザーが開く

mcp-remote はトークンを ~/.mcp-auth/ にキャッシュします。起動のたびに再認証される場合、このディレクトリに書き込み権限がないか、古いエントリが残っている可能性があります。

まず、~/.mcp-auth/ の権限を確認してください（ユーザーが書き込み可能である必要があります）。権限に問題がない場合、キャッシュが古くなっている可能性があります。ディレクトリのバックアップを取り（例：mv ~/.mcp-auth ~/.mcp-auth.bak）、再試行してください。移動しても解決しない場合は、バックアップを復元してください。注： キャッシュを削除すると、このサーバーだけでなく、mcp-remote 経由で認証したすべての MCP サーバーからサインアウトします。

ネイティブ設定で OAuth または DCR エラーが発生する

お使いのクライアントは、まだ Dynamic Client Registration に対応していない可能性があります。上記の mcp-remote フォールバック設定に切り替えてください。

サインインは成功するが、ツールの呼び出しが 403 で失敗する

お使いの AccelByte ユーザーには、呼び出している操作を実行する権限がない可能性があります。AGS 管理者に確認してください。

「Invalid Request」、「invalid client ID」、または「client ID not found」で認証に失敗する

以前はクライアントが接続できていたのに、サインイン時に失敗するようになった場合（無効なリダイレクト URI、クライアント ID、またはターゲットパスについて記載された一般的な IAM の Invalid Request ページが表示される場合や、「invalid client ID」／「client ID not found」エラーが表示される場合など）は、キャッシュされた Dynamic Client Registration（DCR）が古くなっている可能性があります。

DCR を使用するクライアントは、登録した IAM クライアント ID をキャッシュします。その後、管理者または非アクティブなクライアントのクリーンアップジョブによってその IAM クライアントが削除されると、キャッシュされた登録は無効になります。クライアントは削除済みのクライアント ID を再利用し続けるため、新たな DCR 登録が試みられる前に認証が失敗します。

これは通常のトークンの有効期限切れとは異なります。 アクセストークンだけの有効期限が切れた場合、クライアントはトークンをサイレントに更新するか、同じ有効なクライアント ID で再認証するため、気付かないこともあります。削除されたクライアントは更新できません。クライアントが DCR を再実行して新しい登録を行えるよう、キャッシュされた登録をクリアする必要があります。

復旧方法 — ags-api サーバーの認証キャッシュをクリアしてから、再度サインインします。

• Claude Code： /mcp を実行し、ags-api サーバーを選択して、認証をクリアを選びます。その後、（/mcp を使うか再起動して）再接続し、新たにサインインします。
• Codex： codex mcp logout ags-api を実行してから、codex mcp login ags-api を実行します。
• mcp-remote クライアント： ~/.mcp-auth/ キャッシュをクリアする方法については、上記の「mcp-remote を起動するたびにブラウザーが開く」を参照してください。

認証をクリアすると、この 1 台のサーバーのローカル OAuth 状態（キャッシュされた登録とトークン）だけが削除され、再度サインインする必要があります。これにより、新しい DCR 登録が作成され、アクセスが復旧します。MCP サーバーを削除して追加し直す必要はありません。また、クライアントでサーバーごとの認証をクリアできない場合を除き、すべての MCP 認証情報を一括消去しないでください。

ドキュメント

• インストールガイド — クイックインストールプロンプトに続く内容です。単独でも読めます
• アーキテクチャ — 設計、セキュリティ機構、レンダリングツール、AFS 操作
• 環境変数 — セルフホストする方向け
• セルフホスティングと開発 — Docker を使ったビルド、実行、テスト、デプロイ

V1 をお探しですか？docs/v1/README.md をご覧ください（レガシー版。stdio とサーバー管理の OAuth を使用）。

貢献

このリポジトリは現状のまま公開されています。現在、外部からのプルリクエストは受け付けていません。バグの報告や質問は、issue を開いてお知らせください。