BeatBandit, inside your own AI.

BeatBandit MCP server

A Model Context Protocol server for working on BeatBandit projects from any MCP client — Claude, ChatGPT, Cursor, VS Code and others. It exposes the same operations as the website: reading and editing story cards, scenes and screenplay pages, running the development and writing workflows, and generating shot lists, media and exports.

Endpoint

https://beatbandit.ai/api/mcpCopy

Transport

Streamable HTTP

Auth

OAuth 2.1 — browser sign-in on first use; per-project permissions

Billing

Your BeatBandit credits. Paid tools return a price quote before they start.

Surface

5 prompts · 41 tools · 41 resource templates · 24 error codes

Install

Add the endpoint to your client. The first tool call opens a browser window to sign in; the client stores the token.

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

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

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

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

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

Install guide — per-client steps and verification.

Authentication & billing

• Sign-in is the same account as the website. Every client and the website see the same projects.
• Read tools are free. Tools that run models are billed in credits from your balance.
• Paid tools follow quote → accept → start: the first call returns a price, and nothing is charged until the client starts the job with that quote.
• Write tools change project data directly; proposal tools (*_propose) return changes for review and apply nothing.

Long-running jobs

Development, writing, review and media tools run as background jobs. A typical call sequence:

# 1. quote
screenplay_generation_run(project_id=1567, scope="sequence", sequence_number=2)
  → { quote: { credits: 42, quote_hash: "…" } }
# 2. start with the accepted quote
screenplay_generation_run(project_id=1567, …, accept_quote="…")
  → { job_id: "job_…", status: "running" }
# 3. poll, then read the result
job_get(job_id="job_…")          → { status: "completed" }
screenplay_read(project_id=1567, mode="sequence", sequence_number=2)

Argument names shown are illustrative; each tool's reference page lists its exact schema.

Prompts

Prompts are ready-made instructions a client can load. Each one checks the project's state and chooses the next tool.

Tools

41 tools in 9 families. Kinds: read returns data, write changes project data, orchestration runs a workflow or proposes changes, export produces files.

Core Project 3

Discover, create, and read BeatBandit projects and templates.

Story Graph 3

Read and mutate the story-graph primitives: cards, scenes, and the graph itself.

Screenplay 9

Read, propose, and apply changes to structured screenplay documents.

Story Workflows 10

Run backend-owned parent workflows for development, revision, review, and screenplay generation.

Story Collaboration 1

Collaborate with BeatBandit through conversational guidance and persona-driven passes.

Shot / Media / Export 10

Generate shot lists, images, videos, and export artifacts.

Asset Query 2

Filter generated media and shot-element libraries without leaving the MCP surface.

Jobs 1

Poll async workflow progress through the canonical job surface.

Other 2

Resources

Resource URIs returned in tool results. Clients can read them directly for larger payloads such as full screenplays, canon summaries and assets.

Errors

Errors are structured: a stable code, an HTTP status, and whether a retry can succeed.