AGS API MCP Server

A Model Context Protocol (MCP) server that issues AccelByte Gaming Services (AGS) API requests on behalf of the authenticated user.

Quickstart

Prerequisites

Cursor
Docker
Access to AGS environment.

a. Base URL:
- Sample URL for AGS Shared Cloud customers: https://testshooter.prod.gamingservices.accelbyte.io
- Sample URL for AGS Private Cloud customers: https://test.accelbyte.io
b. Create a Game Namespace if you don't have one yet. Keep the Namespace ID. Make sure this namespace is in active status.

c. Create an OAuth Client with confidential client type with the permissions you need. Keep the Client ID and Client Secret.
- The permission will limit what APIs this MCP server can call.
- We recommend to give the least amount of permissions as possible especially if you are planning to share the client credentials with others.

Note

The instructions below can be adapted for other MCP clients as well e.g. Claude Desktop, Gemini CLI, and Visual Studio Code.

Using STDIO transport

Pull the AGS Extend SDK MCP Server container image. For example, with image tag 2025.7.0.
```
docker pull ghcr.io/accelbyte/ags-extend-sdk-mcp-server:2025.7.0
```

Switch to your project directory and create .cursor/mcp.json with the following content.

{
  "mcpServers": {
    "ags-api-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "AB_BASE_URL",
        "-e",
        "OAUTH_CLIENT_ID",
        "-e",
        "OAUTH_CLIENT_SECRET",
        "ghcr.io/accelbyte/ags-api-mcp-server:2025.7.0"
      ],
      "env": {
        "AB_BASE_URL": "<your-base-url>",
        "OAUTH_CLIENT_ID": "<your-client-id>",
        "OAUTH_CLIENT_SECRET": "<your-client-secret>",
      }
    }
  }
}

Open your project directory in Cursor and open File > Preferences > Cursor Settings, In Cursor Settings, click MCP, and make sure ags-api-mcp-server is enabled.

Important

Use the ghcr.io/accelbyte/ags-api-mcp-server image tag that matches your AGS version. See the available image tags here.

Note

Other transport, http, is still under development and may not be working yet.

Development

Prerequisites

Node.js 20+
pnpm (install with: npm install -g pnpm)
IAM OAuth provider in an Accelbyte Environment

Setup

Clone the repository:

git clone <repository-url>
cd ags-api-mcp

Install dependencies:
```
pnpm install
```
Set up environment configuration:
```
pnpm run setup
```
This will create a .env file from the template.

Configure your AccelByte environment in .env:

# Base URL for AccelByte environment, e.g. https://test.accelbyte.io
AB_BASE_URL=<your_base_url>

# OAuth Configuration (optional - defaults will be derived from AB_BASE_URL)
OAUTH_CLIENT_ID=<your_client_id>
OAUTH_CLIENT_SECRET=<redacted>

# Server Configuration
PORT=3000
NODE_ENV=development

Note: OAuth URLs (OAUTH_AUTHORIZATION_URL, OAUTH_TOKEN_URL) and OIDC configuration (JWKS_URI, JWT_ISSUER) will automatically be derived from AB_BASE_URL if not explicitly set.

Usage

Stdio Mode (Default)

Development Mode

pnpm run dev:stdio

Production Mode

pnpm run build
pnpm start:stdio

HTTP Mode

Development Mode

TRANSPORT=http pnpm run dev

Production Mode

TRANSPORT=http pnpm run build
TRANSPORT=http pnpm start

Note: In stdio mode:

All logs are automatically redirected to stderr to avoid interfering with the MCP protocol on stdout
The server communicates via stdin/stdout using the MCP protocol
HTTP endpoints are not available in this mode
Client credentials flow is automatically used if OAUTH_CLIENT_ID is configured

📖 For detailed client configuration instructions, see STDIO_CLIENT_CONFIG.md

Claude Desktop Configuration

Add this to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "ags-api": {
      "command": "node",
      "args": ["/absolute/path/to/ags-api-mcp-server/dist/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "AB_BASE_URL": "https://yourgame.accelbyte.io",
        "OAUTH_CLIENT_ID": "your-client-id",
        "OAUTH_CLIENT_SECRET": "your-client-secret",
        "LOG_LEVEL": "info"
      }
    }
  }
}

After adding the configuration, restart Claude Desktop and the tools will be available.

Watch Mode (for development)

pnpm run watch

Testing

# Run the TypeScript unit tests (node:test via ts-node)
pnpm test

# Invoke the legacy integration harness
pnpm run test:integration

Environment Setup

# Set up environment variables
pnpm run setup

# Test with environment variables
pnpm run test:env

OpenAPI Spec Processing

# Process OpenAPI specs (filter APIs and clean up fields)
pnpm run process-specs

# With custom input folder
pnpm run process-specs -- /path/to/input/folder

# With custom input and output folders
pnpm run process-specs -- /path/to/input/folder /path/to/output/folder

The processing script performs the following cleanup operations:

Filters out operations: e.g. can be used to remove POST, PUT, PATCH, DELETE methods
Filters out deprecated APIs: Removes operations marked as deprecated
Removes documentation fields: Cleans up host, externalDocs, and x-docs fields
Removes environment-specific data: Removes realm field from x-version
Ignores specified services: Skips processing of buildinfo, challenge, differ, eventlog, matchmaking, sessionbrowser, ugc
Prettifies JSON: Formats output with proper indentation

Environment Variables

The server uses the following environment variables (configured in .env):

Required Variables

AB_BASE_URL - Base URL for AccelByte environment (e.g., https://test.accelbyte.io)

OAuth Variables (Optional)

OAUTH_CLIENT_ID - OAuth client ID
OAUTH_CLIENT_SECRET - OAuth client secret
OAUTH_AUTHORIZATION_URL - OAuth authorization URL (default: {AB_BASE_URL}/iam/v3/oauth/authorize)
OAUTH_TOKEN_URL - OAuth token URL (default: {AB_BASE_URL}/iam/v3/oauth/token)

OIDC Variables (Optional - derived from AB_BASE_URL)

JWKS_URI - JWKS endpoint for token signature verification (default: {AB_BASE_URL}/iam/v3/oauth/jwks)
JWT_ISSUER - Expected token issuer (default: {AB_BASE_URL})
JWT_AUDIENCE - Expected token audience (default: 0f8b2a3ecb63466994d5e4631d3b9fe7)
JWT_ALGORITHMS - Supported JWT algorithms (default: RS256)

Other Optional Variables

PORT - Server port (default: 3000)
NODE_ENV - Environment mode (development/production)
LOG_LEVEL - Logging level (debug, info, warn, error, fatal)
TRANSPORT - Transport mode (http or stdio; default: stdio)
- stdio - Run with stdin/stdout communication for MCP clients only (default)
- http - Run as HTTP server only

API Endpoints

MCP Protocol

POST /mcp - Main MCP endpoint (requires authentication)

Health Check

GET /health - Server health status

MCP Tools

The server includes tools for AccelByte API interaction:

1. Get Token Info

Get information about the authenticated token and user.

{
  "name": "get_token_info",
  "arguments": {}
}

2. OpenAPI Tools

The server also provides dynamically generated tools from OpenAPI specifications:

search-apis: Search across loaded OpenAPI operations
describe-apis: Get detailed information about specific API operations
run-apis: Execute API requests against endpoints with authentication

MCP Protocol Usage

Initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

List Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Call Tool

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_token_info",
    "arguments": {}
  }
}

OAuth Configuration

Simplified OAuth Flow

This MCP server uses a simplified OAuth 2.1 flow with static client credentials:

No Dynamic Registration: Uses pre-configured OAuth client credentials
Direct OAuth Flow: Client connects directly to AccelByte OAuth server
JWT Verification: Server validates tokens using AccelByte's JWKS
User Context: Authenticated user information passed to all tools

AccelByte OAuth Example

# Minimal configuration - URLs are automatically derived
AB_BASE_URL=https://test.accelbyte.io

Note: All OAuth and OIDC URLs are automatically derived from AB_BASE_URL. OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET are configured in your MCP client's environment.

Docker Deployment

The MCP server can be deployed using Docker for easy containerization and deployment.

Building the Docker Image

Build the Docker image from the project directory:

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

Running with Docker

Create a .env file with your configuration:

cp env.oidc.example .env

Edit .env with your AccelByte environment details:

# Base URL for AccelByte environment; REQUIRED
AB_BASE_URL=https://yourgame.accelbyte.io

# Server Configuration
PORT=3000
NODE_ENV=production
LOG_LEVEL=info

Run the container:

# Run in background
docker run -d \
  --name ags-api-mcp-server \
  --env-file .env \
  -p 3000:3000 \
  ags-api-mcp-server

# Or run interactively to see logs
docker run -it --rm \
  --name ags-api-mcp-server \
  --env-file .env \
  -p 3000:3000 \
  ags-api-mcp-server

Docker Container Management

# View logs
docker logs ags-api-mcp-server

# Follow logs in real-time
docker logs -f ags-api-mcp-server

# Stop and remove container
docker stop ags-api-mcp-server
docker rm ags-api-mcp-server

Health Check

The Docker container includes a built-in health check that monitors the /health endpoint:

# Check container health status
docker ps

# Manual health check
curl http://localhost:3000/health

Testing

Test the server using curl or any HTTP client:

Health Check:

curl http://localhost:3000/health

MCP Request (after authentication):

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=your_jwt_token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

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

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
openapi-specs		openapi-specs
src		src
tests		tests
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
Jenkinsfile		Jenkinsfile
Jenkinsfile.github		Jenkinsfile.github
README.md		README.md
STDIO_CLIENT_CONFIG.md		STDIO_CLIENT_CONFIG.md
commitlint.config.cjs		commitlint.config.cjs
env.example		env.example
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
process-openapi-specs.js		process-openapi-specs.js
setup-env.js		setup-env.js
test-server.js		test-server.js
tsconfig.json		tsconfig.json

Uh oh!

Uh oh!

AccelByte/ags-api-mcp-server

Folders and files

Latest commit

History

Repository files navigation

AGS API MCP Server

Quickstart

Prerequisites

Using STDIO transport

Development

Prerequisites

Setup

Usage

Stdio Mode (Default)

Development Mode

Production Mode

HTTP Mode

Development Mode

Production Mode

Claude Desktop Configuration

Watch Mode (for development)

Testing

Environment Setup

OpenAPI Spec Processing

Environment Variables

Required Variables

OAuth Variables (Optional)

OIDC Variables (Optional - derived from AB_BASE_URL)

Other Optional Variables

API Endpoints

MCP Protocol

Health Check

MCP Tools

1. Get Token Info

2. OpenAPI Tools

MCP Protocol Usage

Initialize

List Tools

Call Tool

OAuth Configuration

Simplified OAuth Flow

AccelByte OAuth Example

Docker Deployment

Building the Docker Image

Running with Docker

Docker Container Management

Health Check

Testing

Contributing

Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Languages

Packages