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, apart from configurations and experiments: an agent can change values inside a remote configuration, create or delete configurations, choose the primary configuration, make keys private or public, and create, end, or assign experiments, if you allowed it when connecting and your role permits it. It cannot change anything else. See Changing configurations and Running experiments.

The MCP server offers the same tools and skills as the in-dashboard AI assistant. The difference is where the model runs. Over MCP, it runs in your own client and is billed by that client's provider, so MCP calls don't use your Gamebeast AI credits. Analytics tools do need your organization's billing to be in good standing, just like the dashboard.

ConnectCopy Anchor Link

Go to Settings → MCP & API access and copy the config. It looks like this:

{
  "mcpServers": {
    "gamebeast": {
      "url": "https://api.gamebeast.gg/mcp"
    }
  }
}

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 choose what the connection can reach and do. Most MCP clients cannot send custom headers at all, which is why this is the easier path for all of them.

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

Choosing accessCopy Anchor Link

The sign-in screen has two parts.

Access decides which organizations and projects the connection can reach:

• All access (the default) — every organization and project you can access, including ones you join or create later.
• Scoped access — only what you pick. Turn on All projects for an organization to include every current and future project in it, or tick individual projects, across as many organizations as you like.

Permissions decides what the connection can do there, using the same permission list as personal access tokens. Everything is ticked by default; use Read only for a connection that should never change anything. If your client asked only for read access, only read permissions are offered.

The connection reaches every environment of the projects it can access. The agent calls list_projects to see project ids and environment names, then passes a projectId and environment on each call.

The agent gets at most what you can already do, 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. A permission you leave unticked stays off no matter what your role allows.

Each time you connect a client you are asked again, and each connection keeps its own choice. Connecting a second client with narrower access never changes the first.

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 or widen an OAuth connection. Its reach comes from what you chose when you connected (or, on a per-project URL, 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, dashboards, and ad-hoc insights, funnels, retention, heatmaps, and cohorts), configurations, experiments, deeplinks, and community sentiment.

Heatmaps come in two parts, and the tools treat them separately. A heatmap is the map your game registers through the Studio plugin — a region's bounds and its top-down image — which you manage on the Data page. A heatmap query is a chart of where one event happens on that map. list_heatmaps lists the maps and get_heatmap_image returns a map's image to the agent as an image, so it can describe hotspots by place. run_heatmap_query builds a heatmap query and returns a summary of the busiest spots in world coordinates. Agents can't create or edit the maps themselves; those come from the Studio plugin.

The agent can also read these docs. search_docs searches every page — feature guides, the Roblox, Unity, Unreal, Godot, JavaScript and Node.js SDK reference, the HTTP API reference, the changelog, and newsletters — and read_doc returns a page (or one section of it) as markdown. They need no project or permissions, so they're available on every connection, and they're the best way to ask an agent how a Gamebeast feature, SDK method, or endpoint works.

Experiment tools cover the current experiments system: list_experiments and get_experiment to find and inspect experiments, get_experiment_results to measure groups against the control (lift, a 95% confidence interval, a p-value, and a sample-ratio check), and list_experiment_members to see which group a player or server is in.

You only see the tools you can use. The tool list is filtered by the connection's permissions (what you ticked when connecting, or a personal access token's permissions), and each call is checked against your own access to the project it names — so an agent is never offered something the connection can't do. If a tool you expected is missing, check the permissions you approved (reconnect to change them), your role on that project, and (for a token) its permissions in Settings → MCP & API access.

SkillsCopy Anchor Link

The server also ships skills: step-by-step instructions for tasks where the tools alone aren't enough, such as building an insight or funnel query, filtering by an experiment group, or reading a cohort definition. They're the same skills the Gamebeast assistant in the dashboard uses.

An agent can get a skill two ways:

• load_skill, a tool that takes a skill name and returns its instructions. This works in every MCP client. The server's instructions list the available skills, and tool descriptions name the skill to load first when there is one.
• As MCP resources, following the Skills Over MCP extension: each skill is at skill://<name>/SKILL.md, and skill://index.json lists them all. Clients that support the extension can show these next to your local skills. In other clients, you can attach one to a conversation as a resource.

Skills contain no project data and need no permissions, so every connection has all of them.

Slash commandsCopy Anchor Link

The commands you can run from the assistant's composer in the dashboard are MCP prompts too, so you can start the same playbook from your coding agent. In Cursor, type / in Agent and pick one (/instrument, /weekly-review, …). In Claude Code they're namespaced by the server name: /mcp__gamebeast__instrument.

Each takes an optional notes argument (anything you'd type after the command in the dashboard — a focus, a period, an experiment). /instrument and /fix-instrumentation also take a planId. If your client doesn't support MCP prompts, ask the agent to load_skill the playbook instead (for example instrument-game).

Changing configurationsCopy Anchor Link

update_configuration sets or removes specific keys inside an existing configuration. It is offered only when the connection can write configurations: your role must allow editing configurations, and a personal access token must also be granted configurations write; an OAuth connection must have been approved with configurations write ticked.

• Changes are saved as soon as the tool runs: there's no separate approval step on the Gamebeast side. Your MCP client's tool-confirmation prompt is where you approve them.
• The agent can call preview_configuration_change first to show you each change's before and after value. It's optional, and nothing is saved by a preview.
• Every change carries a reason, and is rejected if the configuration changed since the agent read it, so it can't overwrite someone else's edit.
• Paths reserved by a running experiment can't be changed. The agent can change private keys' values, and make keys private or public. Private keys are hidden from players, not from your team, so use them for values like a random seed, not for secrets.
• Saving the project's primary configuration pushes it to connected game servers immediately.
• The tool is marked destructive, so MCP clients that support it ask you before each call. Keep that confirmation on.

Three more tools manage configurations themselves. They're offered under the same conditions:

• create_configuration creates a configuration, optionally with initial JSON content. Names must be unique. A new configuration isn't primary, so nothing reaches game servers until you make it primary.
• delete_configuration deletes a configuration. The primary configuration can't be deleted, and neither can one that a scheduled or running experiment is based on.
• set_primary_configuration makes a configuration the one game servers receive. It is pushed to them immediately, replacing the current primary. Your role must also allow managing project settings.

Describing configurationsCopy Anchor Link

update_configuration_descriptions documents a configuration and its keys: what a key controls, its units, and valid ranges. It's offered under the same conditions as update_configuration.

• Descriptions are documentation only. They don't change any value, aren't sent to game servers, and saving them doesn't deploy anything, so the tool isn't marked destructive.
• Only object keys can be described, not array items. An empty description removes it.
• get_configuration returns descriptions alongside the configuration, and search_configuration can search them, so agents can find a key by what it does.
• You can also edit descriptions in the dashboard, where they appear next to each key.

Running experimentsCopy Anchor Link

Three tools change experiments. Each needs the same permission as the matching dashboard action:

• create_experiment starts an A/B test on a configuration: each group applies its own changes to the players (or servers) assigned to it. Your role must allow creating experiments and reading configurations; a personal access token must be granted experiments write. The experiment starts as soon as the tool runs. The agent can call preview_experiment first to show you every group, the split, and each change against the current configuration. It's optional, and nothing is saved by a preview. An experiment can't be edited after it starts, and the keys it changes are locked against other experiments and configuration edits until it ends.
• terminate_experiment stops an experiment for every player immediately; they go back to the base configuration and it can't be restarted. The agent has to name the experiment exactly, as a check that it's ending the right one.
• assign_experiment_unit pins one player or server to a group (for QA), removes a pin, or takes it out of the experiment. It needs the experiments assign permission.

All three run as soon as they're called. All three are marked destructive (assignment is not), so MCP clients that support it ask you before each call. That prompt is your approval step over MCP.

Inside the Gamebeast dashboard, the assistant never makes a change on its own: each one appears in the chat as a card with the reason and what will change, and runs only when you click Approve.

Building dashboardsCopy Anchor Link

The agent can save the charts it builds and organize them into dashboards. Each tool needs the same permission as the matching dashboard action: saving or editing queries needs queries write, and changing dashboards needs boards write (a personal access token must be granted them too).

• create_insight_query, create_funnel_query, create_retention_query, and create_heatmap_query save a chart — the same definition the agent just ran — and can add it to a dashboard. Each checks that the dashboard can draw the chart before saving it. get_query reads a saved query's definition; update_insight_query, update_funnel_query, update_retention_query, and update_heatmap_query change it everywhere it appears, and update_query renames it. delete_query deletes it from every dashboard.
• create_dashboard (optionally in a folder), update_dashboard (rename, describe, set its icon and color, or set which queries it shows and in what order), duplicate_dashboard (copies the queries too), and delete_dashboard (keeps its queries).
• add_query_to_dashboard and remove_query_from_dashboard put an existing query on a dashboard or take it off, without deleting it.
• update_dashboard_layout moves and resizes panels on the dashboard's 24-column grid; panels it doesn't name keep their place, and the rest flow around them.
• add_heading_panel and update_heading_panel add or change a section heading (one line of plain text). add_markdown_panel and update_markdown_panel add or change a markdown note. remove_panel takes any panel off; a query panel's saved query is kept.
• list_dashboard_folders, create_dashboard_folder, update_dashboard_folder (rename, restyle, or move under another folder), delete_dashboard_folder (its dashboards and subfolders move up a level) and move_dashboard organize the sidebar. Agents can't upload images, pin dashboards, or change anyone's private sort order.

They run as soon as they're called, and the deletes and edits are marked destructive so MCP clients that support it ask you first. The manage-dashboards skill walks the agent through them.

Instrumenting your gameCopy Anchor Link

A coding agent connected over MCP can implement a tracking plan, the list of events the assistant designed for your game. In the dashboard, click Implement with… on the plan card for setup steps for your tool, or ask your agent directly:

• get_tracking_plan reads the plan: each event, its properties, and where in the game it should fire. Leave out the id to get the project's latest open plan.
• update_tracking_plan_items reports progress per event: implemented once the code is written, verified after list_event_types and get_property_values show it arriving as planned, or mismatch if the data disagrees. An event can't be marked verified until Gamebeast has actually received it.
• ensure_sdk_key creates an SDK key when the game has none. Your MCP client asks you before each call, and the agent is told to keep the key out of client code (on Roblox: server scripts only). It only works if your role lets you manage API keys.
• create_tracking_plan saves a new plan, for example after the agent finds events your game is missing.

The /instrument and /fix-instrumentation commands load the full step-by-step playbook, and take an optional planId. See Slash commands for the rest.

Managing cohortsCopy Anchor Link

The agent can save, edit, document, and delete user cohorts. All three tools need cohorts write: your role must allow creating, editing, or deleting queries in the project, a personal access token must be granted cohorts write, and an OAuth connection must have been approved with cohorts write ticked.

• create_cohort saves a cohort from a definition, with an optional description of who is in it. Names must be unique in the project. The agent should run the definition with run_cohort_definition first so you can see how many players match.
• update_cohort renames a cohort, sets or clears its description, or replaces its definition. Only the fields it names change. Changing a definition changes membership everywhere the cohort is used: saved queries, dashboards, and experiment targeting.
• delete_cohort deletes a cohort. It's refused while an active or upcoming experiment targets the cohort; queries and cohorts that reference a deleted cohort stop matching anyone.

list_cohorts returns each cohort's description, and its search matches descriptions as well as names. Cohort conditions can use All time ({ "operation": "All time" }) for "ever" segments like "made at least 5 purchases ever".

They run as soon as they're called. delete_cohort and update_cohort are marked destructive, so MCP clients that support it ask you first. The manage-cohorts skill walks the agent through them.

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. An OAuth connection is likewise checked against the access and permissions you chose when connecting.

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; only grant configurations write (or experiments write, or cohorts write) to a token whose agent should change configurations (or run experiments, or manage cohorts).

TroubleshootingCopy Anchor Link

401 "This connection has been disconnected" — the connection's access was revoked. Reconnect from your client.

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 — ask it to call list_projects and name the project it should use. To stop it reaching a project at all, reconnect and choose Scoped access. On an older per-project URL, check the project id in the URL.

invalid_target when authorizing — a per-project URL was hand-written rather than generated. Use https://api.gamebeast.gg/mcp instead, from Settings → MCP & API access.

Claude Desktop says the connector already exists — you already have a Gamebeast connector. One connection can reach all your projects, so you don't need a second one.

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.