@battlegrid/mcp-server

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

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)

Prompts (5)

Resources (3)

Environment Variables

License

MIT