MCP Server

Gamebeast runs an MCP server, so AI coding agents — Cursor, Claude Code, Claude Desktop, and anything else that speaks MCP — can read your analytics, configurations, experiments, deeplinks, and community sentiment directly.

It is read-only. Nothing the agent does through MCP can change your configurations, experiments, or data.

ConnectCopy Anchor Link

Go to Settings → MCP & API access, pick a project and environment, and copy the generated config. It looks like this:

{
  "mcpServers": {
    "gamebeast-my-game-production": {
      "url": "https://api.gamebeast.gg/mcp/123/production"
    }
  }
}

In Cursor that goes in ~/.cursor/mcp.json. In Claude Desktop, use Settings → Connectors → Add custom connector and paste the name and URL.

No token to copy and no headers to set. The client opens a browser, you sign in with your existing Gamebeast account, and you confirm the project. Most MCP clients cannot send custom headers at all, which is why this is the easier path for all of them.

What you approve on that screen is exactly this:

• Read your analytics, configurations, experiments, and players — read-only
• See who you are: your user id
• See your name, email, and profile picture
• Stay connected when you are not present, until you disconnect it

The agent gets exactly what you can already see in the project the URL names, and nothing more. That isn't a soft phrasing of a broader permission — your own role and project access are re-checked on every single request, so the connection narrows the moment your access does.

If the browser doesn't open, or your client doesn't support OAuth, use a personal access token instead.

One connection, one projectCopy Anchor Link

The project and environment are part of the URL — …/mcp/<project-id>/<environment> — so a connection is pinned to one of each. The agent never passes a project or environment argument, and there is no way for it to act on the wrong one.

To work in a second project, add a second entry with its own URL:

{
  "mcpServers": {
    "gamebeast-my-game-production": {
      "url": "https://api.gamebeast.gg/mcp/123/production"
    },
    "gamebeast-other-game-production": {
      "url": "https://api.gamebeast.gg/mcp/456/production"
    }
  }
}

Each entry is authorized separately and holds its own access, so they work at the same time and independently — authorizing one never affects another. The distinct URLs also matter practically: Claude Desktop refuses to add two connectors with the same URL.

The server name is what your agent sees, so make it say which project it points at. The dashboard suggests one.

Why pinned connectionsCopy Anchor Link

Pinning is worth it even when you only have one project:

• The agent can't act on the wrong project. A pinned connection doesn't accept a project argument at all, so there is no way for the model to pass the wrong id.
• Fewer tokens and fewer mistakes. The agent doesn't have to discover projects or decide which to use before doing what you asked.
• Your permissions are checked up front. A pinned connection validates your access when it connects, rather than discovering the problem mid-task.

Personal access tokensCopy Anchor Link

A personal access token still works, and is the better choice for scripts and automation where no browser is available.

{
  "mcpServers": {
    "gamebeast-my-game-production": {
      "url": "https://api.gamebeast.gg/mcp/123/production",
      "headers": {
        "Authorization": "Bearer gb_pat_your_token_here"
      }
    }
  }
}

The dashboard writes this for you: go to Settings → MCP & API access, create a personal access token, pick a project and environment, and copy the generated config.

Tokens must start with gb_pat_. SDK keys and server keys are rejected — MCP acts as you, so every call is checked against both the token's permissions and your own current access.

Several projects with one tokenCopy Anchor Link

One token can back every entry. A personal access token can be scoped to as many projects and organizations as you have access to, so you rarely need more than one — the separate entries exist so the agent knows which project it's working in, not because each needs its own credential:

{
  "mcpServers": {
    "gamebeast-my-game-production": {
      "url": "https://api.gamebeast.gg/mcp/123/production",
      "headers": { "Authorization": "Bearer gb_pat_your_token_here" }
    },
    "gamebeast-my-game-development": {
      "url": "https://api.gamebeast.gg/mcp/123/development",
      "headers": { "Authorization": "Bearer gb_pat_your_token_here" }
    },
    "gamebeast-other-game": {
      "url": "https://api.gamebeast.gg/mcp/456/production",
      "headers": { "Authorization": "Bearer gb_pat_your_token_here" }
    }
  }
}

Environment namesCopy Anchor Link

The URL takes an environment name, not a number — production or development by default. Copy the exact name from the dashboard: open the environment switcher in the top bar, hover an environment, and use Copy environment name.

Use the name exactly as the dashboard gives it: the URL is an identifier, so …/mcp/123/Production is not the same address as …/mcp/123/production and is refused. (The older environment header is more forgiving — studio is accepted as a synonym for development there, and case and punctuation are ignored.)

If the URL names an environment the project doesn't define, the connection is refused with a message naming it, rather than quietly falling back to letting the agent choose.

Without pinsCopy Anchor Link

With a token you can leave the project out of the URL entirely:

{
  "mcpServers": {
    "gamebeast": {
      "url": "https://api.gamebeast.gg/mcp",
      "headers": { "Authorization": "Bearer gb_pat_your_token_here" }
    }
  }
}

The connection then spans everything the token can reach, and the agent calls list_projects to discover project ids and environment names before each request. This is convenient for exploration but means the agent chooses the project — prefer pinned entries for real work.

The older header form of pinning is still accepted on the unpinned URL:

Each is also accepted as a query parameter (?project_id=123&environment=production). A header wins over a query parameter when both are set. The query form is accepted on the MCP endpoint only — elsewhere in the API these are headers.

The URL wins over both. On a pinned URL, a project-id or environment that contradicts it is refused rather than silently losing, because guessing which one you meant could point the agent at the wrong project. Matching values are fine.

These headers cannot retarget an OAuth connection. Its project comes from the URL it was authorized for, and a header can't change that — deliberately, so nothing can point an approved connection somewhere you didn't approve.

What the agent can doCopy Anchor Link

Tools cover analytics (saved queries, ad-hoc insights, funnels, cohorts), configurations, experiments, deeplinks, heatmaps, and community sentiment.

Experiments are covered by two pairs of tools, because Gamebeast has two experiment systems. list_experiments_v2 / get_experiment_v2 read the current one; list_experiments / get_experiment read the legacy one. Ask for whichever your project uses — if you're not sure, try the _v2 tools first and they'll tell you if that system isn't enabled for your project. Experiment ids are not interchangeable between the two.

You only see the tools you can use. The tool list is filtered by your own access to the project — and, for a personal access token, by that token's permissions too — so an agent is never offered something it will be refused. If a tool you expected is missing, check your role on that project and (for a token) its permissions in Settings → MCP & API access.

Permissions and safetyCopy Anchor Link

Every MCP call is checked against your live access — your current role and project grants, re-checked on every request. A personal access token is checked twice: against the token's own permissions as well.

The effect is the same either way: a connection can never do more than you can, and it stops working the moment your access does. If you're removed from a project or your role narrows, connections and tokens you created lose that access immediately — no revocation needed.

Scope tokens narrowly. A token for an analytics agent needs analytics read access and nothing else.

TroubleshootingCopy Anchor Link

401 Unauthorized, and no browser opened — your client didn't act on the OAuth challenge. Either it doesn't support OAuth, or it cached a failed attempt; restart the client, and if it still doesn't prompt, use a personal access token.

The browser opened but the page wasn't found — you're signed out of an account that the link expects, or the link was stale. Sign in to the dashboard first, then reconnect from the client.

The agent is reading the wrong project — check the project id in the connection's URL. If the URL has no project in it (the older …/mcp form), your project is stored per user and authorizing a second connection moved it; re-copy a pinned config from Settings → MCP & API access.

invalid_target when authorizing — the URL was hand-written rather than copied from the dashboard. A connection URL has to be generated there, because that is what registers it with the sign-in server. Copy it from Settings → MCP & API access.

Claude Desktop says the connector already exists — two entries cannot share a URL. Make sure each names its own project (…/mcp/123/production, …/mcp/456/production), not the same one twice.

401 Unauthorized with a token — the token is wrong, expired, or not a personal access token. Tokens start with gb_pat_, and the header must be Authorization: Bearer gb_pat_….

403 Forbidden on a project — you no longer have access to it, or (with a token) the token isn't scoped to it. Check your role on the project, and the token in Settings → MCP & API access.

403 Forbidden on an environment — the environment name is wrong for that project, or (with a token) the token wasn't granted it. Copy the name from the dashboard's environment switcher.

A tool is missing — your role, or the token, lacks the permission it requires. See Permissions and safety.