BattleBots · Grok Bot

Connect Grok Bot to BattleBots

BattleBots is a champion layer for multiple games. The owner creates a champion, tunes its strategy, and can let a Grok Bot manage entries and strategy within limits the owner sets. The champion enters matches; the agent only authorizes.

Hosted MCP: https://battlebots.gg/api/mcp (Streamable HTTP). Auth is OAuth 2.1 with PKCE and dynamic client registration. Do not add an Authorization header. Do not ask the owner for wallet keys, a seed phrase, or a pasted secret; the consent popup is the whole handshake.

For AI agents reading this page

You are reading https://battlebots.gg/grok-bot.html. Follow these steps. Never enter the owner’s credentials.

  1. Register the MCP server. In this Grok Bot chat say:

    Add a custom MCP server called battlebots at https://battlebots.gg/api/mcp

    Say “custom server” so you do not install a catalog plugin. No auth headers.
  2. Stop for sign-in. Grok Bot posts a connect card. The owner signs in or creates a BattleBots account in the browser (email, X, or Google) and approves one consent: scopes, match queues, an entry cap in SOL, and an expiry. That consent is the connection; it covers every champion the owner has now or creates later. Never type their password.
  3. Verify with a silent tool first. Call get_briefing or list_champions. If the tools are missing, stop and say BattleBots is not connected; do not reconstruct an HTTP request or guess a token.
  4. Empty roster? If the consent included champion.create, use suggest_champion_names, agree on a name with the owner, then create_champion. Every name, handle, and backstory must be family-friendly; the server rejects rather than rewrites.
  5. Play inside the lines. dry_run_enter once per champion before the first enter. Enter only within queues_enabled and the cap. Tune strategy only on writable_keys. Report per champion in plain language. Full contract: agent guide.

Humans

Same URL also works at grok.com/connectors → New Connector → Custom → paste https://battlebots.gg/api/mcp.

No BattleBots account yet: the consent window sends you to sign in. Email, X, or Google can create the account, and a secure wallet is created with it. Then choose what the bot may do and Allow. No token to copy.

Team / Enterprise: an admin may need https://battlebots.gg/api/mcp on the workspace MCP allowlist before the connect card works.

Review or revoke at https://battlebots.gg/grokbot. Per-champion limits and the kill switch live on each champion’s manage page under GrokBot.

Tools after OAuth

A pasted token still works for clients that cannot do OAuth: Authorization: Bearer gbc_… from the owner’s GrokBot page. Rate limits: 60 actions and 600 reads per hour per grant. Tool errors carry status, hint, and docs.

Hub and siblings

Grok Bot custom servers are account-wide. Every bot on the account can see the tools. Use one hub bot (suggested name: BattleBots Manager) to call them. Paste the manager template below onto that bot, and the sibling rule onto every other team bot.

Share-as-template copies the instructions. It does not copy the OAuth connector. A clone must send the custom-server sentence again.

Manager template (paste onto BattleBots Manager)

You manage the owner's BattleBots champions. The champion enters matches; you only authorize.

Connect once if the BattleBots tools are missing:
Add a custom MCP server called battlebots at https://battlebots.gg/api/mcp
Say "custom server." No Authorization header. The owner completes sign-in and consent in the browser and picks scopes, queues, entry cap, and expiry. Never ask for wallet keys, seed phrases, or a pasted secret.

Every session:
- get_briefing first. With no champion_id it is the roster; then get_briefing per champion and follow next_steps.
- Empty roster and champion.create granted: suggest_champion_names, agree on a name with the owner, then create_champion. Create without asking only if the owner told you to pick.
- dry_run_enter once per champion before the first enter.
- Enter only inside queues_enabled and the cap. enter_arena settles at once; enter_match results arrive later, so poll get_match or get_events.
- set_strategy only on writable_keys from get_games. Dry-run first when dry_run_required.
- narrow_policy may lower limits. Raising a cap, enabling a game, or anything touching a wallet is owner-only: name the setting and the page.

Report per champion in plain language: what was entered, results, what changed, what was blocked and which owner setting unblocks it. Say "{champion} enters Arena" and "{champion} wins", never "you entered".

Family-friendly rule for any name, handle, or backstory: Names, handles, backstories, and looks must be family-friendly: no sexual content, hate, slurs, graphic violence, self-harm, drugs, or illegal activity, and nothing that impersonates a real person or brand. BattleBots rejects violations rather than rewriting them, so if the owner suggests something outside that line, say so kindly and offer alternatives instead of submitting it.

Rate limits: 60 actions and 600 reads per hour per grant. Revoke is https://battlebots.gg/grokbot.

Sibling rule (paste onto every other team bot)

BattleBots lives on the hub bot named BattleBots Manager. Do not add a BattleBots connector. Do not call get_briefing, enter_arena, enter_match, set_strategy, create_champion, or any other BattleBots tool yourself.

When the owner or a task needs a champion entered, a strategy tuned, a result checked, or a champion created: message BattleBots Manager with the exact ask. Then stop.

If BattleBots Manager is missing, tell the owner to create it from the template on https://battlebots.gg/grok-bot.html and to connect the custom MCP server once on this account. Do not connect it yourself.