Getting Started

Install the BeatBandit MCP server

BeatBandit exposes an HTTP MCP endpoint at https://beatbandit.ai/api/mcp. Most MCP clients need only the URL; the server handles OAuth, rate limits, credit accounting, and RLS using the same session backing beatbandit.ai.

Prerequisites

An active BeatBandit account. Sign up at beatbandit.ai.
An MCP-capable client: Cursor, Claude Code, Windsurf, VS Code with MCP, Cline, or any other client that speaks the Streamable HTTP or SSE MCP transport.
A project with available credits for tools that consume credits.

Cursor

Create or edit .cursor/mcp.json in your workspace root (or ~/.cursor/mcp.json for a user-wide install) and add the beatbandit server:

.cursor/mcp.json

{
  "mcpServers": {
    "beatbandit": {
      "url": "https://beatbandit.ai/api/mcp"
    }
  }
}

Restart Cursor after editing. The first tool call will open an OAuth consent window.
If your workspace already has an mcpServers map, merge the beatbandit entry in.

Claude Code

terminal

claude mcp add --transport http beatbandit https://beatbandit.ai/api/mcp

Claude Code persists the config to its MCP settings file automatically.

If you prefer editing the config directly, the equivalent JSON is:

mcp.json

{
  "mcpServers": {
    "beatbandit": {
      "type": "http",
      "url": "https://beatbandit.ai/api/mcp"
    }
  }
}

VS Code (GitHub Copilot Chat MCP)

VS Code's MCP settings live under settings.json. Add the server to the mcp.servers block:

settings.json

{
  "mcp": {
    "servers": {
      "beatbandit": {
        "url": "https://beatbandit.ai/api/mcp"
      }
    }
  }
}

Reload the window after editing. OAuth completes in the default browser.

Windsurf · Cline · other HTTP MCP clients

Any client that speaks the MCP Streamable HTTP transport can connect. Point it at https://beatbandit.ai/api/mcp. For clients that still expect a command-based stdio transport, use a generic HTTP-to-stdio bridge such as modelcontextprotocol/servers.

ChatGPT custom connectors

Configure BeatBandit as a custom MCP connector inside ChatGPT's connector admin:

chatgpt connector

Add a custom MCP server:
  Name: BeatBandit
  Server URL: https://beatbandit.ai/api/mcp
  Auth: OAuth 2.1 (browser consent on first tool call)

Authentication

The first MCP request from a client triggers a browser OAuth 2.1 consent flow. You sign in at beatbandit.ai, approve the client, and the client stores a short-lived token plus a refresh token. All subsequent tool calls carry the token in the Authorization header automatically; BeatBandit enforces the same session-scoped RLS rules as the product UI.

Already signed in on beatbandit.ai? The consent step is one click — the server reuses your existing Supabase session rather than asking for a password again.

Verify your install

In your MCP-capable client, ask the agent to run:

“List my BeatBandit projects.”

The agent should call project_query and return your project list. If you see a permissions error, revisit the OAuth consent page. If you see a network error, verify that the URL is exactly https://beatbandit.ai/api/mcp.

Next steps

Browse the tool reference to see what the agent can do.
Start a new story with story_development_run's story_bootstrap workflow.
For long-running jobs, poll job_get until completion rather than falling back to low-level mutations.