Get started

Integrate with AI agents

Bonus Round is built so your coding agent can do the whole integration: register the game, add the SDK, find the natural breaks in your game loop, load the game to verify it's live, and report back. You review the diff.

The fastest way

Paste this to Claude Code, Cursor, Codex or any agent that can edit your project and fetch a URL:

Integrate Bonus Round into this three.js game. Follow https://bonusround.io/integrate.md exactly.
My Bonus Round publisher id is pub_XXXXXXXX. Verify the SDK is live, then tell me what you changed.

Don't have a publisher id yet? Leave that line out and connect the MCP server below: the agent will create the game for you. Your exact prompt, with your id filled in, is on the Developers page.

The MCP server

With the Bonus Round MCP server connected, your agent can manage games directly instead of asking you to copy ids from the dashboard. Create an API key on the Developers page first.

Hosted server, nothing to install:

claude mcp add --transport http bonusround https://bonusround.io/mcp --header "Authorization: Bearer br_sk_…"

Or run it locally over stdio:

claude mcp add --transport stdio --env BONUSROUND_API_KEY=br_sk_… bonusround -- npx -y @bonusround/mcp

Then start a session in your game's folder and run the prompt: /mcp__bonusround__integrate-bonus-round, or just say “Integrate Bonus Round”.

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (this project; don't commit the key):

{
  "mcpServers": {
    "bonusround": {
      "url": "https://bonusround.io/mcp",
      "headers": { "Authorization": "Bearer br_sk_…" }
    }
  }
}

Or the local stdio server:

{
  "mcpServers": {
    "bonusround": {
      "command": "npx",
      "args": ["-y", "@bonusround/mcp"],
      "env": { "BONUSROUND_API_KEY": "br_sk_…" }
    }
  }
}

From the terminal:

codex mcp add bonusround --env BONUSROUND_API_KEY=br_sk_… -- npx -y @bonusround/mcp

Or in ~/.codex/config.toml:

[mcp_servers.bonusround]
command = "npx"
args = ["-y", "@bonusround/mcp"]
env = { BONUSROUND_API_KEY = "br_sk_…" }

Any MCP client that speaks streamable HTTP can use https://bonusround.io/mcp with the header Authorization: Bearer br_sk_…. Stdio clients run npx -y @bonusround/mcp with BONUSROUND_API_KEY in the environment. Point BONUSROUND_URL somewhere else to use a different server. If you've run npx bonusround login, the stdio server reads that saved key too.

Tools

Tool	What it does
`bonusround_integration_guide`	Returns integrate.md, the step-by-step recipe. Agents call this first.
`bonusround_list_games`	Your games with their `pub_` ids, status, test mode and when the SDK was last seen.
`bonusround_create_game`	Registers a game by URL; returns its pub id and snippet.
`bonusround_get_snippet`	The exact script tag, attach line, break/rewarded examples and ads.txt line.
`bonusround_integration_status`	Has the SDK been seen (`integration.lastSeenAt`)? Is the agent learning? With `waitSeconds` it polls until the SDK shows up.
`bonusround_start_learning`	(Re)starts the play agent that learns your game.
`bonusround_get_stats`	Requests, fill rate, impressions, engagements, clicks, earnings, eCPM.
`bonusround_update_settings`	Name, test mode, rating, categories, formats, triggers, interval, floors, blocked categories, frequency cap.

There's also a prompt, integrate-bonus-round, that loads the recipe into the conversation. The server's instructions tell agents never to turn off test mode or change floors unless you ask.

The recipe: integrate.md

/integrate.md is written for AI agents: how to detect the three.js setup, where to put the tag, how to find the renderer, scene and camera, how to recognise natural breaks in a game loop, and how to verify the install by loading the game and checking GET /api/games/:id until integration.lastSeenAt is set. It ends with the report the agent should give you.

Also for agents: /llms.txt (an index in the llms.txt format) and /llms-full.txt (all of these docs in one plain-text file).

Claude Code skill

Prefer a skill to an MCP server? Install the integrate-bonus-round skill and Claude Code will pick it up whenever you ask to add Bonus Round or ads to a three.js game:

mkdir -p ~/.claude/skills/integrate-bonus-round
curl -fsSL https://bonusround.io/docs/skill/SKILL.md -o ~/.claude/skills/integrate-bonus-round/SKILL.md

The CLI

Agents that prefer shell commands (and humans) can use the CLI. init shows a diff and asks before writing; --yes skips the question, which is what an agent should use after showing you the diff with --dry-run.

npx bonusround login --key br_sk_…        # saved to ~/.config/bonusround/credentials (0600)
npx bonusround init --dry-run             # show the changes
npx bonusround init --yes                 # write them
npx bonusround status --wait 60           # wait for the first SDK ping

Keys and safety

An API key can do anything your account can, including turning test mode off. Create one key per agent or machine, name it (“Claude Code laptop”), and revoke it on the Developers page when you're done.
Never put a br_sk_ key in client-side code. The game only ever needs its public pub_ id.
Keys are stored hashed. We can't show a key again after it's created.