{
  "markdown": "# AGS API MCP Server\n\nA Model Context Protocol (MCP) server that gives AI assistants (VS Code Copilot, Cursor, Claude, Gemini, Antigravity) access to AccelByte Gaming Services (AGS) APIs through OpenAPI integration.\n\n## What It Does\n\n- **Search** AGS API operations by description, tags, method, or service\n- **Describe** specific operations — parameters, schemas, auth requirements\n- **Execute** API requests with your authenticated token\n- **Render** query results as charts, tables, and metrics (see [Analytics & Visualization](#analytics--visualization))\n\nAccelByte hosts the AGS API MCP Server for you — **you don't need to install or run anything locally**. Just point your AI assistant at your environment's MCP URL and sign in.\n\n---\n\n## Quick Install\n\nPaste this into your AI coding assistant — it will fetch the install guide, ask you a couple of questions, and configure everything for you:\n\n```\nInstall the AGS API MCP server for me. Fetch and follow the instructions at\nhttps://raw.githubusercontent.com/AccelByte/ags-api-mcp-server/refs/heads/master/INSTALL.md\n```\n\nWorks in **VS Code Copilot**, **Cursor**, **Claude Code**, **Antigravity**, and **Gemini CLI**.\n\n> **Claude Desktop users:** The simplest path is **Settings → Connectors → Add custom connector** (Name: `ags-api`, URL: your MCP URL) — no AI installer needed. See [Claude Desktop](#claude-desktop) below for the full instructions and the fallback for accounts where workspace policy blocks custom connectors.\n>\n> If you do want to use the Quick Install prompt above, switch to the **Code** tab first (Chat and Cowork can't edit your config file).\n>\n> ![Claude Desktop — Code tab](docs/images/claude-desktop-code.png)\n\nPrefer to do it yourself? See [Manual Install](#manual-install) below.\n\n---\n\n## Manual Install\n\n### Step 1: Find Your MCP Server URL\n\nThe URL depends on which AGS edition you're on:\n\n| Edition | URL format |\n|---|---|\n| **Shared Cloud** | `https://{studio}-{game}.prod.gamingservices.accelbyte.io/mcp/{studio}-{game}` |\n| **Private Cloud** | `https://{environment-name}.accelbyte.io/mcp` (or a custom domain) |\n\n- **Shared Cloud** customers receive `{studio}` and `{game}` namespaces at registration. Note that `{studio}-{game}` appears **twice** in the URL.\n- **Private Cloud** customers may need to coordinate with AccelByte support to enable the MCP endpoint or set up a custom domain.\n\nNot sure which edition you're on? Check with your AccelByte administrator.\n\n### Step 2: Configure Your Client\n\nThe deployed server uses **OAuth 2.0 with PKCE and Dynamic Client Registration (DCR)**. If your client supports DCR, you can connect to the URL directly. If not — or if your client only supports stdio transport — use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a bridge.\n\n> **Need `mcp-remote`?** It runs via `npx`. You need **Node.js 18+ with `npx` available** — verify with `npx --version`. Most installers (nodejs.org, Homebrew, `nvm`, official Windows installer) bundle `npx` via `npm` automatically, but minimal Linux distros sometimes ship Node without it; install `npm` from your package manager if that's the case. No global `mcp-remote` install required.\n\nSubstitute your URL from Step 1 wherever you see `<URL>` below.\n\n#### Visual Studio Code (Copilot)\n\n`.vscode/mcp.json` in your workspace (or user `settings.json`):\n\n```json\n{\n  \"servers\": {\n    \"ags-api\": {\n      \"type\": \"http\",\n      \"url\": \"<URL>\"\n    }\n  }\n}\n```\n\nIf you hit DCR errors, swap to: `{ \"command\": \"npx\", \"args\": [\"-y\", \"mcp-remote\", \"<URL>\"] }`.\n\nSee the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).\n\n#### Cursor\n\n`.cursor/mcp.json` in your workspace (or user settings):\n\n```json\n{\n  \"mcpServers\": {\n    \"ags-api\": {\n      \"type\": \"http\",\n      \"url\": \"<URL>\"\n    }\n  }\n}\n```\n\nIf you hit DCR errors, swap to: `{ \"command\": \"npx\", \"args\": [\"-y\", \"mcp-remote\", \"<URL>\"] }`.\n\nSee the [Cursor MCP documentation](https://cursor.com/docs/context/mcp#using-mcpjson).\n\n#### Claude Code\n\n```bash\nclaude mcp add --transport http ags-api <URL>\n```\n\nFallback: `claude mcp add ags-api -- npx -y mcp-remote <URL>`.\n\nSee the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp#installing-mcp-servers).\n\n#### Antigravity\n\n`mcp_config.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"ags-api\": {\n      \"type\": \"http\",\n      \"url\": \"<URL>\"\n    }\n  }\n}\n```\n\nIf you hit DCR errors, swap to: `{ \"command\": \"npx\", \"args\": [\"-y\", \"mcp-remote\", \"<URL>\"] }`.\n\nSee the [Antigravity MCP documentation](https://antigravity.google/docs/mcp#connecting-custom-mcp-servers).\n\n#### Gemini CLI\n\n```bash\ngemini mcp add --transport http ags-api <URL>\n```\n\nFallback: `gemini mcp add ags-api -- npx -y mcp-remote <URL>`.\n\nSee the [Gemini CLI MCP documentation](https://geminicli.com/docs/tools/mcp-server/#configure-the-mcp-server-in-settingsjson).\n\n#### Claude Desktop\n\nClaude Desktop has two install paths. Pick the first one that works for your account:\n\n**Option A — Custom Connector (recommended for personal / Pro accounts)**\n\n1. Open **Settings → Connectors → Add custom connector** (under the \"Customize\" area).\n2. Fill in:\n   - **Name**: `ags-api`\n   - **Remote MCP server URL**: your `<URL>` from Step 1\n3. Save. Claude Desktop handles OAuth (DCR + PKCE) natively — no config file edits, no `mcp-remote`.\n\n> **Don't see \"Add custom connector\"?** Some Team and Enterprise plans disable custom connectors via workspace policy. If the option is missing or greyed out, use Option B.\n\n**Option B — `mcp-remote` config file (fallback when custom connectors are blocked)**\n\nEdit `claude_desktop_config.json`:\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"ags-api\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-remote\", \"<URL>\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\n### Step 3: Sign In\n\nWhen your AI assistant first calls a tool, it will open a browser to AccelByte to complete OAuth. Approve the consent screen and you're connected.\n\n---\n\n## Using the Tools\n\nOnce connected, your assistant has access to these tools:\n\n### `get_token_info`\n\nReturns details about your authenticated session — user ID, namespace, roles, expiration.\n\n> *\"What's my current user information?\"*\n\n### `search-apis`\n\nSearch AGS operations by description, HTTP method, tags, or service.\n\n> *\"Find APIs for user management\"* · *\"Search for inventory endpoints\"*\n\n### `describe-apis`\n\nGet the full schema for a specific operation — parameters, request/response shapes, auth requirements.\n\n> *\"What parameters does the createItem endpoint need?\"*\n\n### `run-apis`\n\nExecute an API request. Write operations (POST/PUT/PATCH/DELETE) prompt for consent before running.\n\n> *\"Get my user profile\"* · *\"List all items in my inventory\"*\n\n## Analytics & Visualization\n\nThe server exposes 16 render tools for turning tabular data into charts, tables, and metrics inside MCP hosts that support app resources:\n\n- `render_bar_chart`, `render_line_chart`, `render_area_chart`, `render_scatter_chart`, `render_histogram_chart`, `render_box_chart`, `render_heatmap_chart`\n- `render_pie_chart`, `render_donut_chart`, `render_waterfall_chart`, `render_funnel_chart`, `render_gauge_chart`, `render_state_timeline_chart`\n- `render_table`, `render_metric`, `render_meter`\n\nAll render tools require a `provider`:\n\n- `provider=\"facade\"` reads Athena Facade results by `query_id` + `namespace`\n- `provider=\"direct\"` renders small inline datasets from `data_columns` + `data_rows`\n\nThe typical Athena Facade flow:\n\n1. Use `run-apis` to submit a query via `POST /afs/v1/admin/namespaces/{namespace}/queries`, preferably with `wait_ms=0` if you plan to render by `query_id`\n2. Poll `GET /afs/v1/admin/namespaces/{namespace}/queries/{id}` until `status=\"SUCCEEDED\"`\n3. Pass that `query_id` to a `render_*` tool with `provider=\"facade\"`\n\nIf the submit returns `200` with inline rows on the fast path, render those rows directly with `provider=\"direct\"`.\n\nSee [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#render-tools) for the render-tool input matrix and the Athena Facade operation list.\n\n### Workflow Prompts\n\nThe server also provides workflow resources and prompts. Ask your assistant about available workflows or invoke the `run-workflow` prompt.\n\n## Troubleshooting\n\n### `mcp-remote` opens a browser every time\n\n`mcp-remote` caches tokens under `~/.mcp-auth/`. If it's re-authenticating on every launch, that directory may be unwritable or hold stale entries.\n\nFirst, check permissions on `~/.mcp-auth/` (it needs to be writable by your user). If permissions look fine, the cache may be stale — back the directory up (e.g. `mv ~/.mcp-auth ~/.mcp-auth.bak`) and retry. Restore the backup if the move doesn't help. **Note:** removing the cache will sign you out of every MCP server you've authenticated with via `mcp-remote`, not just this one.\n\n### Native config fails with an OAuth or DCR error\n\nYour client may not yet support Dynamic Client Registration. Switch to the `mcp-remote` fallback config shown above.\n\n### Sign-in succeeds but tool calls fail with 403\n\nYour AccelByte user may not have permission for the operation you're calling. Check with your AGS administrator.\n\n### Authentication fails with \"Invalid Request\", \"invalid client ID\", or \"client ID not found\"\n\nIf your client connected before but now fails at sign-in — often with a generic IAM **Invalid Request** page mentioning an invalid redirect URI, client ID, or target path, or an \"invalid client ID\" / \"client ID not found\" error — the cached Dynamic Client Registration (DCR) is likely stale.\n\nClients that use DCR cache the IAM client ID they registered. If an administrator or an inactive-client cleanup job later removes that IAM client, the cached registration becomes invalid. The client keeps reusing the deleted client ID and authentication fails *before* a fresh DCR registration is ever attempted.\n\n**This is different from normal token expiry.** When only your access token has expired, the client silently refreshes it or reauthorizes against the *same* valid client ID and you may not notice. A deleted client can't be refreshed — you have to clear the cached registration so the client runs DCR again and registers a new one.\n\n**Recovery** — clear the cached authentication for the `ags-api` server, then sign in again:\n\n- **Claude Code:** run `/mcp`, select the `ags-api` server, and choose **Clear authentication**. Then reconnect (via `/mcp` or by restarting) to trigger a new sign-in.\n- **Codex:** run `codex mcp logout ags-api`, then `codex mcp login ags-api`.\n- **`mcp-remote` clients:** see [`mcp-remote` opens a browser every time](#mcp-remote-opens-a-browser-every-time) above for clearing the `~/.mcp-auth/` cache.\n\nClearing authentication only removes the **local OAuth state** (the cached registration and tokens) for this one server and requires you to sign in again — it creates a fresh DCR registration and restores access. You do **not** need to remove and re-add the MCP server, and you should **not** wipe all MCP credentials globally unless your client offers no way to clear a single server on its own.\n\n## Documentation\n\n- [Installation Guide](INSTALL.md) — followed by the Quick Install prompt; readable on its own\n- [Architecture](docs/ARCHITECTURE.md) — design, security mechanisms, render tools, AFS operations\n- [Environment Variables](docs/ENVIRONMENT_VARIABLES.md) — for self-hosters\n- [Self-Hosting & Development](docs/DEVELOPMENT.md) — build, run, test, deploy with Docker\n\n> Looking for V1? See [docs/v1/README.md](docs/v1/README.md) (legacy; stdio + server-managed OAuth).\n\n## Contributions\n\nThis repository is published as-is. We don't accept external pull requests at this time. For bug reports and questions, please open an issue.\n",
  "bytes": 11894,
  "sha": "2fb9bfab9dae9d2552ecc32a9f5f196ad6a94be5279ca78b14681e84fbb64808",
  "repo_slug": "accelbyte/ags-api-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_accelbyte_ags_api_mcp_server_5602cf06/readme"
}