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, 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
• Change values in your remote configurations — only if your client asks for it, and only if your role allows it. Changes to the primary configuration go live to game servers
• 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 at most what you can already do 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. A connection approved without the configuration-change line is read-only no matter what your role allows.

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, 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, 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 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.

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 the configuration-change permission.

• 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, update_dashboard (rename, 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.

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 the change permission.

• 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.

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 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.