Developers: API & MCP — StageBuilder Pro

Quick start

In the app, open Account → Agents & API and create a key. It starts with sbp_ and is shown once, so copy it then.
Add the MCP server to your agent (below).
Ask for something: “Make a plot called Friday Club Show on a 28 × 20 stage. Drums on an 8 × 8 riser upstage centre, bass amp stage right, two guitar amps stage left, four wedges downstage, and a lead vocal mic downstage centre.”

Each result includes an editor_url that opens the plot. If you already have it open, the agent's changes show up live.

Connect an agent

MCP server URL: https://stagebuilderpro.com/mcp (Streamable HTTP). Send your key as a bearer token.

Claude Code

claude mcp add --transport http stagebuilder https://stagebuilderpro.com/mcp \
  --header "Authorization: Bearer sbp_YOUR_KEY"

Cursor, Windsurf and other JSON-configured clients

{
  "mcpServers": {
    "stagebuilder": {
      "url": "https://stagebuilderpro.com/mcp",
      "headers": { "Authorization": "Bearer sbp_YOUR_KEY" }
    }
  }
}

Codex

# ~/.codex/config.toml
[mcp_servers.stagebuilder]
url = "https://stagebuilderpro.com/mcp"
bearer_token_env_var = "SBP_API_KEY"

Then export SBP_API_KEY=sbp_YOUR_KEY in the shell you run Codex from.

Claude Desktop and other clients that only run local servers

{
  "mcpServers": {
    "stagebuilder": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://stagebuilderpro.com/mcp",
               "--header", "Authorization: Bearer sbp_YOUR_KEY"]
    }
  }
}

claude.ai and ChatGPT connectors sign in with OAuth rather than a key. Sign-in support for those is coming next; until then, use one of the clients above.

Tools

The MCP tools and the REST endpoints are the same operations.

Tool	REST	What it does
`list_plots`	`GET /plots`	Plots you own or collaborate on, with your role on each.
`get_plot`	`GET /plots/{id}`	Stage size, named stage positions, and every item with its id, position, rotation and size.
`create_plot`	`POST /plots`	A blank stage of a given size, or a copy of a template.
`update_plot`	`PATCH /plots/{id}`	Rename, describe, or resize the main stage deck.
`delete_plot`	`DELETE /plots/{id}`	Move a plot you own to Trash (restorable for 30 days).
`search_catalog`	`GET /catalog`	Find gear types: speakers, consoles, lights, LED walls, risers, drum kits, amps, keys, people.
`list_templates`	`GET /templates`	Starting plots: 3/4/5-piece band, DJ.
`add_items`	`POST /plots/{id}/items`	Place gear by type and position. Instruments, mics and speakers add their input/output-list rows.
`update_items`	`PATCH /plots/{id}/items`	Move, rotate, relabel, recolour, resize, hide or annotate items.
`remove_items`	`DELETE /plots/{id}/items`	Delete items and their input-list rows.
`get_input_list`	`GET /plots/{id}/inputs`	The input list and output list.
`update_input_list`	`PATCH /plots/{id}/inputs`	Set mics/DIs, stands, phantom power and descriptions by channel.
`whoami`	`GET /me`	The account and plan behind the key.

Positions and units

All distances are feet, whatever units the plot displays.
The origin is centre stage. +x is stage left (the performer's left), −x stage right, −z upstage, +z downstage toward the audience.
A position can be a name laid over the plot's stage: upstage_left, upstage_center, upstage_right, stage_left, center, stage_right, downstage_left, downstage_center, downstage_right, foh, house_left, house_right, or the short forms USL … DSR. Or exact coordinates: { "x": 6, "z": -4 }.
Heights are automatic. Gear rests on whatever is under it, whether that's the deck, a riser, a table or an amp, so place a riser before the kit that sits on it. Flown items stay at trim height unless you give an elevation.
rotation is absolute degrees about the vertical axis. Wedges default to 180° so they face the performer.

REST API

Base URL https://stagebuilderpro.com/api/v1. Machine-readable spec: /api/v1/openapi.json (OpenAPI 3.1).

curl https://stagebuilderpro.com/api/v1/plots \
  -H "Authorization: Bearer sbp_YOUR_KEY"

curl -X POST https://stagebuilderpro.com/api/v1/plots/PLOT_ID/items \
  -H "Authorization: Bearer sbp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[
        {"type":"drum_riser","position":"upstage_center","size":{"width":8,"depth":8,"height":1}},
        {"type":"drum_kit","position":"upstage_center"},
        {"type":"wedge_monitor","position":"downstage_center","label":"Vox wedge"}
      ]}'

Errors

Errors are JSON: { "error": { "code": "…", "message": "…" } }. The message says what to change.

Status	Meaning
400	Invalid arguments: an unknown item type (with suggestions), an unknown position, a field out of range.
401	Missing, malformed or revoked key.
402	The key's account isn't on Pro or Elite right now. The key works again after you resubscribe.
403	You can view the plot but not edit it, or the owner's plan has made it view-only.
404	No plot or item with that id that you can see.
409	The item is locked in the editor.
429	More than 120 requests a minute on one key. Wait and retry.

Keys and access

A key acts as you. It can see and change exactly what you can in the editor: your plots, and plots shared with you at your role. Viewers stay read-only.
Keys are stored hashed and shown once. Revoke one any time in Account → Agents & API, and it stops working immediately.
Deleting a plot moves it to Trash, so an agent's mistake can be undone for 30 days.
Keep keys out of shared repos and screenshots. If one leaks, revoke it and make another.