@accelbyte/ags-api-mcp-server

AGS API MCP Server

A simple Streamable HTTP-based MCP (Model Context Protocol) server built with TypeScript that issues Accelbyte AGS API requests on behalf of the authenticated user.

Features

• HTTP-based MCP Server: Implements the Model Context Protocol over HTTP
• OAuth 2.1 with PKCE: Secure authentication using OAuth 2.1 with Proof Key for Code Exchange
• JWT Token Verification: Secure token validation using JWKS (JSON Web Key Set)
• Static OAuth Client: Simplified OAuth flow using pre-configured client credentials
• User Context Propagation: Authenticated user context passed to all MCP tools
• Example Tools: Built-in tools for demonstration and testing

Prerequisites

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

Installation

• 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://development.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> # Not needed for mcp-remote mode
OAUTH_CLIENT_SECRET=<redacted>   # Not needed for mcp-remote mode
OAUTH_REDIRECT_URI=http://localhost:3334/oauth/callback  # Required for mcp-remote

# 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

Development Mode

pnpm run dev

Production Mode

pnpm run build
pnpm start

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 write operations: Removes 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

Development Mode (Skip Authentication)

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://development.accelbyte.io)
• PORT - Server port (default: 3000)
• NODE_ENV - Environment mode (development/production)
• LOG_LEVEL - Logging level (debug, info, warn, error, fatal)

OAuth Variables (Optional)

• OAUTH_CLIENT_ID - OAuth client ID (not needed for mcp-remote mode)
• OAUTH_CLIENT_SECRET - OAuth client secret (not needed for mcp-remote mode)
• OAUTH_REDIRECT_URI - OAuth redirect URI (default: http://localhost:3334/oauth/callback)
• 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)

API Endpoints

Authentication

• GET /auth/login - Initiate OAuth login
• GET /oauth/callback - OAuth callback handler
• GET /auth/logout - Logout and clear session

MCP Protocol

• POST /mcp - Main MCP endpoint (requires authentication)

Health Check

• GET /health - Server health status

Authentication Helper

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: mcp-remote 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 (mcp-remote mode)

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

Note: All OAuth and OIDC URLs are automatically derived from AB_BASE_URL. OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET are not needed in mcp-remote mode since mcp-remote handles OAuth using its own static credentials.

mcp-remote Configuration

Configure mcp-remote to use the same static OAuth credentials:

{
  "mcpServers": {
    "ags-api-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/mcp",
        "3334",
        "--host", "localhost",
        "--static-oauth-client-info",
        "{ \"client_id\": \"<your_client_id>\", \"client_secret\": \"<redacted>\" }"
      ]
    }
  }
}

Simplified OAuth Flow Sequence

• MCP Client connects to mcp-remote (port 3334)
• mcp-remote discovers OAuth server metadata from MCP Server
• mcp-remote uses static OAuth credentials to authenticate with AccelByte IAM
• AccelByte IAM redirects user for authentication
• User authenticates and authorizes the application
• AccelByte IAM returns authorization code to mcp-remote
• mcp-remote exchanges code for access token using static credentials
• mcp-remote forwards MCP requests to MCP Server with access token
• MCP Server validates JWT token using AccelByte's JWKS
• MCP Server passes user context to tools for authenticated API calls

Key Benefits:

• ✅ No Dynamic Registration - Uses pre-configured credentials
• ✅ Simplified Flow - Fewer steps and dependencies
• ✅ Better Performance - No unnecessary API calls
• ✅ Easier Configuration - Static credentials in one place

Security Features

• Helmet.js: Security headers
• CORS: Cross-origin resource sharing configuration
• JWT: Secure token-based authentication
• HTTP-only Cookies: Secure session management
• Input Validation: Tool parameter validation
• Error Handling: Comprehensive error handling

Development

Project Structure

src/
├── index.ts              # Main server entry point
├── mcp-server.ts         # MCP protocol implementation
├── oauth-middleware.ts   # OAuth authentication middleware
└── tools/
    └── static-tools.ts  # Example MCP tools

Adding New Tools

• Create a new tool class or add methods to StaticTools
• Register the tool in src/index.ts:

mcpServer.registerTool('tool_name', toolInstance.method.bind(toolInstance));

• Optionally, provide a schema for better tool discovery:

mcpServer.registerTool('tool_name', handler, {
  name: 'tool_name',
  description: 'Tool description',
  inputSchema: {
    type: 'object',
    properties: {
      param1: { type: 'string', description: 'Parameter description' }
    },
    required: ['param1']
  }
});

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

Option 1: Using Environment File

• 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

Option 2: Direct Environment Variables

docker run -d \
  --name ags-api-mcp-server \
  -e AB_BASE_URL=https://yourgame.accelbyte.io \
  -e PORT=3000 \
  -e NODE_ENV=production \
  -e LOG_LEVEL=info \
  -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

Docker Features

• Multi-stage build: Optimized image size with separate build and runtime stages
• Health checks: Built-in monitoring of server health
• Port exposure: Port 3000 is automatically exposed
• Production ready: Configured for production deployment
• Lightweight: Based on Node.js Alpine Linux image

Testing

Test the server using curl or any HTTP client:

• Health Check:

curl http://localhost:3000/health

• OAuth Login (redirects to OAuth provider):

curl -L http://localhost:3000/auth/login

• 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"
  }'

Clean up

With mcp-remote, clean up the token caches under ~/.mcp-auth, e.g.

rm -rf ~/.mcp-auth

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.