AGS API MCP Server

AGS API MCP服务器

描述

AGS API MCP服务器是一个模型上下文协议（MCP）服务器，通过OpenAPI集成为AI助手提供对AccelByte游戏服务API的访问。

注： V2是 仅限HTTP 并使用承载令牌认证。有关stdio传输或服务器管理的OAuth，请参阅 V1文档.

它是什么

使用TypeScript构建的MCP服务器，将AI助手（VS Code Copilot、Cursor、Claude）与AccelByte游戏服务API连接起来。它实现了模型上下文协议，将AccelByte API作为AI助手可以发现和使用的工具。

它的用途

通过以下方式使AI助手能够与AccelByte API交互：

• 正在搜索可用的AccelByte API操作
• 获取特定API的详细信息
• 使用正确的身份验证执行API请求
• 正在检索令牌信息

它的作用

• 将AccelByte API作为MCP工具公开：通过MCP工具提供对AccelByte API的访问
• 提供语义搜索：通过描述、标签或路径在OpenAPI操作中搜索
• 执行API请求：使用正确的身份验证和验证运行API调用
• 提供令牌信息：检索有关已验证令牌的信息

先决条件

• 码头工人 -容器运行时（必需）
• AccelByte环境URL (AB_BASE_URL)-您的AccelByte环境基础URL

运行服务器

备注：MCP客户端要求服务器在配置之前运行。首先启动服务器，然后配置MCP客户端（请参阅 快速开始 在......下面

使用Docker启动服务器：

docker run -d \
  --name ags-api-mcp-server \
  -e AB_BASE_URL=https://yourgame.accelbyte.io \
  -p 3000:3000 \
  ghcr.io/accelbyte/ags-api-mcp-server:2026.2.0

备注：替换 https://yourgame.accelbyte.io 使用您的实际AccelByte环境URL。

验证服务器是否正在运行：

curl http://localhost:3000/health

您应该看到： {"status":"ok","timestamp":"..."}

看 了解详细的Docker说明。

快速开始

V2使用HTTP传输，这要求服务器在配置MCP客户端之前运行。请按照以下步骤操作：

步骤1：启动服务器

使用Docker命令启动服务器 运行服务器 上面。

步骤2：配置MCP客户端

服务器运行后，将MCP客户端配置为通过HTTP连接：

Visual Studio Code

创建或编辑 .vscode/mcp.json 在您的工作区中（或在用户设置中配置）：

{
  "servers": {
    "ags-api": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

位置:

• 工作区： .vscode/mcp.json
• 用户设置：VS代码设置UI或 settings.json

请参阅 VS代码MCP文档 了解更多详情。

光标

创建或编辑 .cursor/mcp.json 在您的工作区中（或在用户设置中配置）：

{
  "mcpServers": {
    "ags-api": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

位置:

• 工作区： .cursor/mcp.json
• 用户设置：光标设置UI

请参阅 光标MCP文档 了解更多详情。

克劳德桌面

编辑您的Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\ 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ags-api": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

配置后：重新启动Claude Desktop以加载MCP服务器。

请参阅 Claude Desktop MCP文档 了解更多详情。

克劳德代码

Claude Code使用与Claude Desktop不同的配置系统。您可以通过CLI命令或创建 .mcp.json 文件。

选项1：使用CLI命令

claude mcp add --transport http ags-api http://localhost:3000/mcp

选项2：使用.mcp.json文件

创建或编辑 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "ags-api": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

位置: .mcp.json 在项目根目录中

请参阅 克劳德代码MCP文档 了解更多详情。

反重力

创建或编辑 mcp_config.json 在项目根目录中：

{
  "mcpServers": {
    "ags-api": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

位置: mcp_config.json 在项目根目录中

请参阅 反重力MCP文件 了解更多详情。

双子星命令行工具

Gemini CLI使用不同的配置系统。您可以通过CLI命令或编辑来配置MCP服务器 settings.json.

选项1：使用CLI命令

gemini mcp add --transport http ags-api http://localhost:3000/mcp

选项2：使用settings.json文件

编辑Gemini CLI设置文件：

用户范围: ~/.gemini/settings.json\ 项目范围: .gemini/settings.json （在项目根目录中）

{
  "mcpServers": {
    "ags-api": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

位置:

• 用户范围： ~/.gemini/settings.json
• 项目范围： .gemini/settings.json 在项目根目录中

请参阅 Gemini CLI MCP文档 了解更多详情。

高级：本地运行

如果您想自己构建和运行服务器，而不是使用来自的预构建映像 ghcr.io.

选项1:Docker（本地构建）

从源构建映像并运行它：

git clone  ags-api-mcp-server
cd ags-api-mcp-server

docker build -t ags-api-mcp-server .

docker run -d \
  --name ags-api-mcp-server \
  -e AB_BASE_URL=https://yourgame.accelbyte.io \
  -p 3000:3000 \
  ags-api-mcp-server

选项2:pnpm

直接使用Node.js运行：

git clone  ags-api-mcp-server
cd ags-api-mcp-server
pnpm install
cp env.example .env

编辑 .env 并设置为最小值：

AB_BASE_URL=https://yourgame.accelbyte.io

然后启动服务器：

pnpm build && pnpm start
# Or use watch mode for development:
pnpm dev

使用工具

配置后，您的AI助手可以使用以下MCP工具与AccelByte API进行交互：

get_token_info

获取有关已验证用户和令牌的信息（如果可用）。返回详细信息，例如：

• 用户ID和显示名称
• 命名空间
• 角色和权限
• 令牌过期信息

示例用法问你的人工智能助手“我当前的用户信息是什么？”或“显示我的令牌详细信息”。

search-apis

按以下方式搜索AccelByte API操作：

• 描述或摘要文本
• HTTP方法（GET、POST、PUT、DELETE等）
• API标记
• 服务名称

示例用法：“查找用户管理API”或“搜索与库存相关的端点”。

describe-apis

获取有关特定API操作的详细信息，包括：

• 请求参数和模式
• 响应模式
• 身份验证要求
• 请求示例

示例用法：“显示有关getUserProfile API的详细信息”或“createItem端点需要什么参数？”。

run-apis

针对AccelByte终结点执行API请求。服务器处理：

• 使用您的令牌进行身份验证
• 请求验证
• 响应格式

备注：对于写入操作（POST、PUT、PATCH、DELETE），服务器可能会在执行之前请求您的同意。

示例用法：“获取我的用户资料”或“列出我的库存中的所有项目”。

工作流支持

服务器还提供工作流资源和运行预定义工作流的提示。向您的AI助手询问可用的工作流程或使用 run-workflow 提示。

故障排除

找不到OAuth授权服务器

当OAuth授权服务器位于与MCP服务器不同的主机上时，一些MCP客户端可能无法发现该服务器。当客户端尝试获取时，这通常表现为错误 /.well-known/oauth-authorization-server 从MCP服务器的URL。

要解决此问题，请设置 MCP_AUTH_SERVER_DISCOVERY_MODE 使MCP服务器代理OAuth发现和注册请求到AccelByte。

Docker：

docker run -d \
  --name ags-api-mcp-server \
  -e AB_BASE_URL=https://yourgame.accelbyte.io \
  -e MCP_AUTH_SERVER_DISCOVERY_MODE=proxyRegister \
  -p 3000:3000 \
  ags-api-mcp-server

pnpm(.env):

MCP_AUTH_SERVER_DISCOVERY_MODE=proxyRegister

这使得MCP服务器：

1. 服务 /.well-known/oauth-authorization-server 通过从AccelByte代理文档
2. 重写 registration_endpoint 在该文档中指向MCP服务器
3. 代理 POST /oauth/register 对AccelByte实际注册端点的请求

可用模式：

注： 这是一种临时解决方法，直到MCP客户端正确支持跨源OAuth授权服务器发现。

VS代码用户： VS Code Copilot是一个已知的受影响客户端。如果您在连接时看到OAuth错误，请使用 proxyRegister 模式。

端口3000已在使用中

如果端口3000已被其他应用程序使用，您将看到以下错误 Bind for 0.0.0.0:3000 failed: port is already allocated.使用映射到其他主机端口 -p:

docker run -d \
  --name ags-api-mcp-server \
  -e AB_BASE_URL=https://yourgame.accelbyte.io \
  -p 8080:3000 \
  ghcr.io/accelbyte/ags-api-mcp-server:2026.2.0

然后更新MCP客户端配置以使用新端口（例如。， http://localhost:8080/mcp).

文档

有关详细文档，请参阅：

• 快速入门指南 -详细的设置说明
• API 参考 -完整的API文件
• 环境变量 -配置选项
• -高级Docker配置
• 开发指南 -贡献和扩展服务器

支持

有关问题和疑问，请在存储库中打开问题。