AGS API MCP Server

Description

The AGS API MCP Server is a Model Context Protocol (MCP) server that provides AI assistants with access to AccelByte Gaming Services APIs through OpenAPI integration.

Note: V2 is HTTP-only and uses Bearer token authentication. For stdio transport or server-managed OAuth, see V1 documentation.

What It Is

An MCP server built with TypeScript that bridges AI assistants (VS Code Copilot, Cursor, Claude) with AccelByte Gaming Services APIs. It implements the Model Context Protocol to expose AccelByte APIs as tools that AI assistants can discover and use.

What It's For

Enable AI assistants to interact with AccelByte APIs by:

• Searching for available AccelByte API operations
• Getting detailed information about specific APIs
• Executing API requests with proper authentication
• Retrieving token information

What It Does

• Exposes AccelByte APIs as MCP Tools: Provides access to AccelByte APIs through MCP tools
• Provides Semantic Search: Search across OpenAPI operations by description, tags, or path
• Executes API Requests: Runs API calls with proper authentication and validation
• Provides Token Information: Retrieves information about authenticated tokens

Prerequisites

• Docker - Container runtime (required)
• AccelByte Environment URL (AB_BASE_URL) - Your AccelByte environment base URL

Running the Server

Note: MCP clients require the server to be running before configuration. Start the server first, then configure your MCP client (see Quick Start below).

Start the server using 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

Note: Replace https://yourgame.accelbyte.io with your actual AccelByte environment URL.

Verify the server is running:

curl http://localhost:3000/health

You should see: {"status":"ok","timestamp":"..."}

See Docker Deployment Guide for detailed Docker instructions.

Quick Start

V2 uses HTTP transport, which requires the server to be running before configuring MCP clients. Follow these steps:

Step 1: Start the Server

Start the server using the Docker command in Running the Server above.

Step 2: Configure Your MCP Client

Once the server is running, configure your MCP client to connect via HTTP:

Visual Studio Code

Create or edit .vscode/mcp.json in your workspace (or configure in user settings):

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

Location:

• Workspace: .vscode/mcp.json
• User settings: VS Code settings UI or settings.json

See the VS Code MCP documentation for more details.

Cursor

Create or edit .cursor/mcp.json in your workspace (or configure in user settings):

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

Location:

• Workspace: .cursor/mcp.json
• User settings: Cursor settings UI

See the Cursor MCP documentation for more details.

Claude Desktop

Edit your Claude Desktop configuration file:

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

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

After configuration: Restart Claude Desktop to load the MCP server.

See the Claude Desktop MCP documentation for more details.

Claude Code

Claude Code uses a different configuration system than Claude Desktop. You can configure MCP servers either via CLI command or by creating a .mcp.json file.

Option 1: Using CLI Command

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

Option 2: Using .mcp.json File

Create or edit .mcp.json in your project root:

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

Location: .mcp.json in your project root directory

See the Claude Code MCP documentation for more details.

Antigravity

Create or edit mcp_config.json in your project root:

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

Location: mcp_config.json in your project root directory

See the Antigravity MCP documentation for more details.

Gemini CLI

Gemini CLI uses a different configuration system. You can configure MCP servers either via CLI command or by editing settings.json.

Option 1: Using CLI Command

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

Option 2: Using settings.json File

Edit your Gemini CLI settings file:

User scope: ~/.gemini/settings.json
Project scope: .gemini/settings.json (in your project root)

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

Location:

• User scope: ~/.gemini/settings.json
• Project scope: .gemini/settings.json in your project root

See the Gemini CLI MCP documentation for more details.

Advanced: Running Locally

If you want to build and run the server yourself instead of using the pre-built image from ghcr.io.

Option 1: Docker (Local Build)

Build the image from source and run it:

git clone <repo-url> 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

Option 2: pnpm

Run directly with Node.js:

git clone <repo-url> ags-api-mcp-server
cd ags-api-mcp-server
pnpm install
cp env.example .env

Edit .env and set at minimum:

AB_BASE_URL=https://yourgame.accelbyte.io

Then start the server:

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

Using the Tools

Once configured, your AI assistant can use the following MCP tools to interact with AccelByte APIs:

get_token_info

Get information about the authenticated user and token (if available). Returns details such as:

• User ID and display name
• Namespace
• Roles and permissions
• Token expiration information

Example usage: Ask your AI assistant "What's my current user information?" or "Show me my token details".

search-apis

Search for AccelByte API operations by:

• Description or summary text
• HTTP method (GET, POST, PUT, DELETE, etc.)
• API tags
• Service name

Example usage: "Find APIs for user management" or "Search for inventory-related endpoints".

describe-apis

Get detailed information about a specific API operation, including:

• Request parameters and schemas
• Response schemas
• Authentication requirements
• Example requests

Example usage: "Show me details about the getUserProfile API" or "What parameters does the createItem endpoint need?".

run-apis

Execute API requests against AccelByte endpoints. The server handles:

• Authentication with your token
• Request validation
• Response formatting

Note: For write operations (POST, PUT, PATCH, DELETE), the server may request your consent before executing.

Example usage: "Get my user profile" or "List all items in my inventory".

Workflow Support

The server also provides workflow resources and prompts for running predefined workflows. Ask your AI assistant about available workflows or use the run-workflow prompt.

Troubleshooting

OAuth Authorization Server Not Found

Some MCP clients may fail to discover the OAuth authorization server when it lives on a different host than the MCP server. This typically manifests as an error when the client tries to fetch /.well-known/oauth-authorization-server from the MCP server's URL.

To work around this, set MCP_AUTH_SERVER_DISCOVERY_MODE to make the MCP server proxy OAuth discovery and registration requests to 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

This makes the MCP server:

1. Serve /.well-known/oauth-authorization-server by proxying the document from AccelByte
2. Rewrite the registration_endpoint in that document to point to the MCP server
3. Proxy POST /oauth/register requests to AccelByte's actual registration endpoint

Available modes:

Mode	Behavior
none	Standard discovery (default)
redirect	307 redirect to AccelByte's discovery endpoint
proxy	Proxy the discovery document
proxyRegister	Proxy discovery + registration endpoint (recommended)

Note: This is a temporary workaround until MCP clients properly support cross-origin OAuth authorization server discovery.

VS Code users: VS Code Copilot is a known affected client. If you see OAuth errors when connecting, use proxyRegister mode.

Port 3000 Already in Use

If port 3000 is already in use by another application, you'll see an error like Bind for 0.0.0.0:3000 failed: port is already allocated. Map to a different host port using -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

Then update your MCP client configuration to use the new port (e.g., http://localhost:8080/mcp).

Documentation

For detailed documentation, see:

• Quick Start Guide - Detailed setup instructions
• API Reference - Complete API documentation
• Environment Variables - Configuration options
• Docker Deployment - Advanced Docker configuration
• Development Guide - Contributing and extending the server

Support

For issues and questions, please open an issue in the repository.