AGS API

AGS API MCP 服务

一个模型上下文协议（MCP）服务，通过 OpenAPI 集成，让 AI 助手（VS Code Copilot、Cursor、Claude、Gemini、Antigravity）能够访问 AccelByte Gaming Services（AGS）API。

功能

• 搜索 AGS API 操作，可按描述、标签、方法或服务搜索
• 描述 特定操作，包括参数、架构和身份验证要求
• 使用已通过身份验证的令牌执行 API 请求
• 将查询结果呈现为图表、表格和指标（参见分析与可视化）

AccelByte 为你托管 AGS API MCP 服务——你无需在本地安装或运行任何内容。只需让 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 格式
公有云	https://{studio}.prod.gamingservices.accelbyte.io/mcp/{studio}
私有云	https://{domain}/mcp

• 公有云客户在注册时会获得一个 {studio} 命名空间——同一个值需要填写两次，分别作为子域名和路径。工作室管理员和游戏管理员使用相同的 URL；你可以访问哪些命名空间取决于分配给你的角色，而非连接的 URL。
• 私有云客户使用自己的环境域名，无论域名是什么——不包含命名空间路径段。你可能需要联系 AccelByte 支持团队以启用 MCP 端点。

“Shared Cloud” 与公有云相同——较早的文档和支持帖使用的是这个名称。

不确定自己使用的是哪个版本？请咨询 AccelByte 管理员。

第 2 步：配置客户端

已部署的服务使用 OAuth 2.0 和 PKCE 以及动态客户端注册（DCR）。如果你的客户端支持 DCR，可以直接连接到 URL。如果不支持，或者你的客户端仅支持 stdio 传输，则使用 mcp-remote 作为桥接。

需要使用 mcp-remote？ 它通过 npx 运行。你需要安装 Node.js 18+，且 npx 可用——使用 npx --version 验证。大多数安装程序（nodejs.org、Homebrew、nvm、官方 Windows 安装程序）都会通过 npm 自动附带 npx，但一些精简版 Linux 发行版有时只包含 Node，不包含 npx；如果遇到这种情况，请通过包管理器安装 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 提供两种安装方式。请选择适用于你账号的第一种方式：

选项 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 助手首次调用工具时，会打开浏览器前往 AccelByte 完成 OAuth。批准授权页面后即可连接。

---

使用工具

连接后，助手即可使用以下工具：

get_token_info

返回已认证会话的详细信息，包括主体、命名空间、角色 / 权限、令牌类型和过期时间。

“我当前的用户信息是什么？”

search-apis

按描述、HTTP 方法、标签或服务搜索 AGS 操作。

“查找用户管理相关的 API” · “搜索库存端点”

describe-apis

获取特定操作的完整架构，包括参数、请求 / 响应结构和身份验证要求。

“createItem 端点需要哪些参数？”

run-apis

执行 API 请求。写入操作（POST/PUT/PATCH/DELETE）运行前会请求授权。

“获取我的用户资料” · “列出我库存中的所有物品”

分析与可视化

此服务提供 16 个渲染工具，可在支持应用资源的 MCP 宿主中将表格数据转换为图表、表格和指标：

• 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 错误而失败

你的客户端可能尚不支持动态客户端注册。请切换到上文所示的 mcp-remote 备用配置。

登录成功，但工具调用因 403 失败

你的 AccelByte 用户可能没有执行所调用操作的权限。请联系你的 AGS 管理员。

身份验证失败，并显示“Invalid Request”、“invalid client ID”或“client ID not found”

如果你的客户端之前能够连接，但现在登录失败——通常会显示通用的 IAM Invalid Request 页面，其中提到无效的重定向 URI、客户端 ID 或目标路径，或显示“invalid client ID”/“client ID not found”错误——则缓存的动态客户端注册（DCR）很可能已过期。

使用 DCR 的客户端会缓存其注册时的 IAM 客户端 ID。如果管理员或非活动客户端清理任务之后删除了该 IAM 客户端，缓存的注册就会失效。客户端会继续重复使用已删除的客户端 ID，导致身份验证失败，而且在此之前不会尝试新的 DCR 注册。

这与令牌正常过期不同。 仅当访问令牌过期时，客户端会静默刷新令牌，或使用同一个有效客户端 ID 重新授权，你可能不会察觉。已删除的客户端无法刷新——你必须清除缓存的注册，让客户端重新运行 DCR 并注册新客户端。

恢复方法 — 清除 ags-api 服务的缓存身份验证，然后重新登录：

• Claude Code： 运行 /mcp，选择 ags-api 服务，然后选择 Clear authentication。之后重新连接（通过 /mcp 或重启）以触发新的登录。
• Codex： 运行 codex mcp logout ags-api，然后运行 codex mcp login ags-api。
• mcp-remote 客户端： 请参阅上文的 mcp-remote 每次都会打开浏览器，了解如何清除 ~/.mcp-auth/ 缓存。

清除身份验证只会移除此单个服务的本地 OAuth 状态（缓存的注册信息和令牌），并要求你重新登录——这会创建新的 DCR 注册并恢复访问权限。你无需移除并重新添加 MCP 服务；除非客户端没有提供单独清除某个服务身份验证的方式，否则不要清除所有 MCP 凭据。

文档

• 安装指南 — 后接“快速安装”提示词；可独立阅读
• 架构 — 设计、安全机制、渲染工具、AFS 操作
• 环境变量 — 供自托管用户参考
• 自托管与开发 — 使用 Docker 构建、运行、测试和部署

在寻找 V1 版本？请参阅 docs/v1/README.md（旧版；stdio + 服务端管理的 OAuth）。

贡献

此仓库按现状发布。目前我们不接受外部拉取请求。如需报告错误或提出问题，请提交 issue。