MCP server

Aggregator.gg ships a hosted Model Context Protocol server, so an AI agent can browse the catalog, launch-prepare, and read integration state through tools instead of hand-written HTTP calls. It uses the same API and forwards your own key on each request.

Overview

• Endpoint: https://mcp.aggregator.gg/mcp
• Transport: stateless JSON-RPC 2.0 over HTTPS POST. One message per request, the reply comes back in the response body. There are no sessions, no server-push streams, and no JSON-RPC batching.
• Auth: an Authorization: Bearer header carrying your agg_ key on every request, the same key as the rest of the machine API.
• Health: public GET / and GET /healthz return fixed service metadata. The reported 0.1.0 version is not a build identifier. /mcp still requires authentication.

A quick identity check, no key required:

curl -sS https://mcp.aggregator.gg/healthz

{"name":"aggregator-mcp","version":"0.1.0","transport":"streamable-http","endpoint":"/mcp","documentation":"https://docs.aggregator.gg"}

The Worker is deployed separately from npm. Do not use the npm stdio package @aggregator-gg/mcp-server (current latest is 1.0.2) for this integration: its remote actions, including create_session and run_readiness_check, call the API without the call-time denial described on this page, its create_session text still describes a test sandbox that current agg_ keys do not have, and its README passes the API key as a command-line argument. Publishing SDK 1.1.0 or deploying this Worker does not change installed npm copies.

Connection

Use a client that supports this stateless HTTP lane and protected Bearer injection. No universal MCP-client compatibility or Cabinet sign-in flow is certified here. The human configures the key without putting it in chat, shell arguments, logs or committed files. Read tools can return organization data to the client and its model, so confirm that destination before connecting. These credential-free terminal checks show the method and authentication boundary:

GET is refused, POST is the only lane:

curl -sS -i https://mcp.aggregator.gg/mcp | head -4

HTTP/2 405
allow: POST, OPTIONS

{"error":"method_not_allowed","message":"This MCP endpoint is stateless: POST one JSON-RPC message to /mcp. There are no sessions or server-push streams."}

A POST without a key is challenged:

curl -sS -i -X POST https://mcp.aggregator.gg/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -4

HTTP/2 401
www-authenticate: Bearer realm="aggregator-mcp", error="invalid_token"

{"error":"unauthorized","message":"Provide an Aggregator API key as 'Authorization: Bearer <key>'. Create one in the cabinet under API; this server only forwards it and never stores it."}

With the header supplied, the same tools/list call returns the catalog below. Auth is Bearer-only: there is no OAuth discovery on this endpoint (/.well-known/oauth-protected-resource returns 404), so configure your MCP client with the static Bearer header rather than an OAuth flow.

Step check: the two curls above reproduce the 405 with allow: POST, OPTIONS and the 401 with the Bearer challenge; with your key added, tools/list answers with named tools.

Available tools

Ten remote reads, five denied remote actions, and two local advisories are registered. Discovery alone does not prove that a key can read a tenant resource.

Remote reads, subject to your key’s permissions and the evidence available:

• list_games: list games from the aggregator catalog with optional filters.
• list_provider_games: list games for a specific provider, for operator-side launch preparation.
• list_truelabs_games: shortcut for listing TRUE LABS games from the catalog.
• get_game: full details for one game by its catalog ID.
• get_session: details for an existing session by its ID.
• list_readiness_scenarios: every scenario the readiness exam will fire at your wallet endpoint, with severity, so you build the wallet to the list before running the check.
• list_readiness_runs: your recent readiness runs with their final states.
• get_readiness_evidence: per-scenario evidence for one run, which scenario failed and what your wallet answered.
• list_transactions: the operator’s transactions, paged like GET /v1/transactions.
• list_providers: registered game providers with supported currencies and blocked countries.

Remote actions, visible but unavailable on this Worker (descriptions name their intended operation):

• create_session: create a real-money player session for a game.
• create_demo_session: create a free-play session; no money moves, but remote state is created.
• run_readiness_check: run the real pre-live diagnostics suite against your configured wallet endpoint, launch, bet, win, refund, duplicates and security scenarios, synchronously.
• probe_provider_games: list the games actually enabled on the provider’s own stand, the launchable subset when the catalog is ahead of the provider’s casino.
• provider_health: run a live health check against one game provider and report its status.

Local advisories, computed from caller-supplied facts without touching the platform:

• assess_operator_readiness: an unverified local readiness advisory; never a go-live decision.
• plan_port_adaptation: an unverified local plan for reusing your existing integration with another aggregator.

For platform accounts, create brands with POST /v1/sub-operators first and pass an existing ref: a catalog read with an unknown ref can create a brand. The transactions tool has no brand selector, like GET /v1/transactions.

The read tools can inspect existing readiness evidence. A human runs the supported check described in Getting started, step 6; this Worker cannot start it. A local advisory, a demo and a verified API and wallet test are different evidence.

Safety boundaries

• The hosted server is read-only. The five remote actions are listed but always refused. Run tests and launches from the cabinet or your backend.
• Output protection has limits. The Worker holds the key in request-scoped memory and uses the shared SDK redactor on outgoing messages, including its timeout reply. It does not persist keys; its redacted, argument-free audit records do persist in Workers Logs. This is not a guarantee about all client logs or Cloudflare telemetry. Never paste raw errors, headers or credentials into a conversation.
• Human control remains required. Registration, keys, callback configuration, tests, payment and Go live stay with the operator. MCP explains the next step and reads available evidence; missing evidence means not yet verified. See Agent guidelines.

Troubleshooting

405 method_not_allowed. You sent GET or connected with a client that expects a server-push stream. This endpoint is stateless: POST one JSON-RPC message per request.

401 unauthorized. The Authorization: Bearer header is missing or malformed, or the credential is refused. The Worker accepts the issued shape (agg_ plus 43 Base62 characters) and older key shapes that still work; the API decides whether the key is valid. Keys come from the operator cabinet; the header goes on every POST.

400 with a JSON-RPC error. The body was not valid JSON, was a batch array (unsupported: send one message per POST), or was not a JSON-RPC 2.0 message.

A remote action returns a denial. Expected on the hosted endpoint: mutations are off and the key-tier gates still apply. The denial text comes from the tool code this Worker runs and can mention a setting or a test key; neither turns actions on here. A human uses the supported cabinet or approved backend integration for tests and launches.

HTTP 413, JSON-RPC -32600. The Worker limits a request body to 64 KiB, including streamed requests. Reduce the request; do not split one JSON-RPC message into a batch.

Timeout answer with a JSON-RPC error. A request that takes longer than 150 seconds gets a JSON-RPC error, with your key removed from it. For a failed read, retry a bounded number of times and check rate limiting. A timeout is not business success.