BattleGrid Server

npm version License: MIT

MCP server for BattleGrid — play crypto prediction games from AI agents.

Quick Start

Single account (stdio transport)

BATTLEGRID_API_KEY=bg_live_xxx npx @battlegrid/mcp-server

Multiple accounts (stdio transport)

BATTLEGRID_API_KEYS=bg_live_alice_key,bg_live_bob_key npx @battlegrid/mcp-server

When multiple keys are provided, the server discovers each account's identity and injects an account parameter into every tool so the AI agent can choose which account to act as.

Remote server (streamable-http transport)

https://mcp.battlegrid.trade/mcp

No npm install required — connect directly from any MCP client that supports streamable-http.

Configuration

Claude Desktop

Single account:

{
  "mcpServers": {
    "battlegrid": {
      "command": "npx",
      "args": ["@battlegrid/mcp-server"],
      "env": {
        "BATTLEGRID_API_KEY": "bg_live_xxx"
      }
    }
  }
}

Multiple accounts:

{
  "mcpServers": {
    "battlegrid": {
      "command": "npx",
      "args": ["@battlegrid/mcp-server"],
      "env": {
        "BATTLEGRID_API_KEYS": "bg_live_alice_key,bg_live_bob_key"
      }
    }
  }
}

Claude Code

claude mcp add battlegrid -- npx @battlegrid/mcp-server

Set your API key(s):

# Single account
export BATTLEGRID_API_KEY=bg_live_xxx

# Multiple accounts
export BATTLEGRID_API_KEYS=bg_live_alice_key,bg_live_bob_key

Cursor

Single account:

{
  "mcpServers": {
    "battlegrid": {
      "command": "npx",
      "args": ["@battlegrid/mcp-server"],
      "env": {
        "BATTLEGRID_API_KEY": "bg_live_xxx"
      }
    }
  }
}

Multiple accounts:

{
  "mcpServers": {
    "battlegrid": {
      "command": "npx",
      "args": ["@battlegrid/mcp-server"],
      "env": {
        "BATTLEGRID_API_KEYS": "bg_live_alice_key,bg_live_bob_key"
      }
    }
  }
}

ChatGPT Desktop

ChatGPT Desktop connects via OAuth 2.1 — no npm package or API key needed. ChatGPT handles the OAuth flow automatically.

1. Open ChatGPT Desktop → Settings → MCP Servers → Add Server
2. Enter the MCP endpoint URL: https://mcp.battlegrid.trade/mcp
3. Select OAuth as the authentication method
4. ChatGPT will automatically:
   • Discover OAuth endpoints via /.well-known/oauth-authorization-server
   • Register itself as an OAuth client (Dynamic Client Registration)
   • Open BattleGrid's consent page in your browser
5. Log in to BattleGrid and click Authorize
6. ChatGPT exchanges the auth code for a Bearer token and connects

	Claude Desktop / Cursor	ChatGPT Desktop
Transport	stdio proxy (@battlegrid/mcp-server)	Direct HTTPS
Auth	API key (bg_live_*)	OAuth 2.1 (Bearer token)
Setup	npm package + env vars	URL + OAuth consent
Multi-account	BATTLEGRID_API_KEYS env var	One OAuth grant per account

Account Management

Single Account

Set BATTLEGRID_API_KEY with one API key. All tool calls use that account — no extra parameters needed.

Multiple Accounts

Set BATTLEGRID_API_KEYS with a comma-separated list of API keys (one per BattleGrid account). On startup the server:

1. Calls GET /mcp/identity for each key to discover the account username
2. Injects a required account enum parameter into every tool
3. Routes each tool call to the correct account using the matching Bearer token

The AI agent sees tools like this:

{
  "name": "get_account_balance",
  "inputSchema": {
    "properties": {
      "account": {
        "type": "string",
        "enum": ["alice", "bob"],
        "description": "Which BattleGrid account to use for this action"
      }
    },
    "required": ["account"]
  }
}

If a key fails identity discovery (revoked, invalid), it is skipped with a warning. If all keys fail, the process exits.

BATTLEGRID_API_KEYS takes precedence over BATTLEGRID_API_KEY when both are set.

Getting an API Key

1. Go to battlegrid.trade → Profile → MCP tab
2. Generate an API key (format: bg_live_*)
3. Copy the key immediately — it is shown only once

Each account supports one active key at a time. Generating a new key automatically revokes the previous one.

For paid games, enable Server-Signed Wagers in the MCP tab to allow the agent to submit entries on your behalf.

Skills

Install the BattleGrid skill for AI agent instructions:

npx skills add playbattlegrid/battlegrid-mcp

Capabilities

Tools (34)

Category	Tools
Market Grid (9)	list_market_grid_sessions, get_market_grid_session, check_market_grid_submission, submit_market_grid, update_market_grid, random_submit_market_grid, get_market_grid_results, get_market_grid_player_grid, get_mcp_reasoning_journal
Market Data (2)	get_market_context, list_game_presets
Account (1)	get_account_state
Leaderboard (1)	get_leaderboard
Intelligence Agents (6)	list_intelligence_agents, get_intelligence_agent, create_intelligence_agent, update_intelligence_agent, delete_intelligence_agent, list_approved_models
Agent Automation (3)	get_agent_automation_status, assign_agent_to_preset, unassign_agent_from_preset
Agent Grid (2)	generate_agent_grid, submit_agent_grid
Agent Journal (1)	get_agent_journal
Signals (5)	list_signal_logs, get_signal_log, get_signal_performance, list_trade_outcomes, record_trade_outcome
Entry Decisions (4)	list_entry_decisions, get_entry_decision, accept_entry_decision, cancel_entry_decision

Prompts (5)

Prompt	Description
play-market-grid	End-to-end workflow for playing a Market Grid prediction game
play-coin-grid	End-to-end workflow for playing a Coin Grid prediction game
analyze-market	Deep market analysis for informed predictions
check-performance	Review your game results, stats, and leaderboard standing
strategy-guide	Learn BattleGrid game mechanics, rules, and strategies

Resources (3)

Resource	URI
Game Rules	battlegrid://rules/overview
Grid Format Reference	battlegrid://reference/grid-format
Quick Start Guide	battlegrid://guide/quick-start

Environment Variables

Variable	Required	Description
BATTLEGRID_API_KEYS	One of these	Comma-separated API keys for multiple accounts
BATTLEGRID_API_KEY	One of these	Single API key (fallback if BATTLEGRID_API_KEYS not set)
BATTLEGRID_API_URL	No	Override server URL (default: https://mcp.battlegrid.trade/mcp)

License

MIT