@boomstream/mcp

MCP server (Model Context Protocol) providing Boomstream API as tools for LLM agents: Claude Desktop, claude.ai, VS Code MCP extension, and any compatible client.

Status: stdio transport is live on npm (@boomstream/mcp@latest). SSE transport is live at mcp.boomstream.com — connect from claude.ai or any MCP client with a URL (v0.3.0). Per-user OAuth is Stage 3. Release history is in the CHANGELOG.md file bundled with the npm package.

Connection guide: See https://mcp.boomstream.com/ for the canonical connection guide (auth, endpoints, client setup, quick-start examples).

What it does

LLM agents call tools like boomstream_media_info, boomstream_ppv_list_buyers, boomstream_live_create — the server translates them to HTTP calls against https://boomstream.com/api/, parses the responses, and returns structured JSON. ~100 tools across 17 API sections: media, live, ppv, conference, folder, playlist, stats, chat, screenshot, subtitles, timecodes, webhook, project, record-live, live-ipcamera, player-api, general.

Transports:

• stdio — for Claude Desktop (local child process). Shipped.
• SSE — for claude.ai web and remote clients (hosted at mcp.boomstream.com). Available in v0.3.0.

Quick start

BOOMSTREAM_API_KEY=your-key npx -y @boomstream/mcp@latest stdio

Or install globally:

npm install -g @boomstream/mcp@latest
BOOMSTREAM_API_KEY=your-key boomstream-mcp

@latest always resolves to the newest published version. Pin a specific version (e.g., @boomstream/[email protected]) if you need reproducible installs.

Available tools

| Section | Tools | Description | Examples | |---|---:|---|---| | media | 6 | Recorded media (VOD): info, create, upload, bulk-info | boomstream_media_bulkinfo, boomstream_media_info | | live | 7 | Live broadcast streams: create, manage, schedule | boomstream_live_info, boomstream_live_list | | ppv | 13 | Pay-per-view subscriptions: create, buyers, media access | boomstream_ppv_create, boomstream_ppv_update | | conference | 10 | Video conference sessions: create, manage, participants | boomstream_conference_info, boomstream_conference_list | | media_folder | 4 | Folder hierarchy for VOD media assets | boomstream_media_folder, boomstream_media_folder_create | | live_folder | 4 | Folder hierarchy for live broadcast assets | boomstream_live_folder, boomstream_live_folder_create | | materials_folder | 4 | Folder hierarchy for materials assets | boomstream_materials_folder, boomstream_materials_folder_create | | playlist | 7 | Playlists of media items: create, update, reorder | boomstream_playlist_create, boomstream_playlist_update | | stats | 3 | Viewing statistics per project, target, or session | boomstream_stats_project, boomstream_stats_target | | chat | 5 | Chat settings and messages for broadcasts | boomstream_chat_init, boomstream_chat_info | | screenshot | 4 | Thumbnail and screenshot management for media | boomstream_screenshot_info, boomstream_screenshot_create | | subtitles | 6 | Subtitle tracks: enable, upload, set default | boomstream_subtitles_info, boomstream_subtitles_enable | | timecodes | 4 | Chapter/timecode markers for video navigation | boomstream_timecodes_info, boomstream_timecodes_enable | | webhook | 6 | Webhook endpoint management: list, create, update, delete | boomstream_webhook_list, boomstream_webhook_info | | app | 5 | Project (app) settings, users, and configuration | boomstream_app_create, boomstream_app_info | | recordLive | 9 | Record-live sessions: create and manage recordings | boomstream_recordLive_info, boomstream_recordLive_list | | cameraLive | 7 | IP camera stream integration for live broadcasts | boomstream_cameraLive_info, boomstream_cameraLive_list | | general | 1 | General API utilities (server info, capabilities) | boomstream_general_info |

The full schema is in schemas/boomstream.json. Regenerate with pnpm build-schema.

Tool catalog

Group tools by resource for quick lookup. Read = safe/idempotent; Write = state-mutating (create/update/delete); Upload = multipart POST; Actions = other operations.

Media (VOD)

• Read: boomstream_media_bulkinfo, boomstream_media_info
• Write: boomstream_media_create, boomstream_media_update, boomstream_media_delete
• Upload: boomstream_media_upload

Live broadcast

• Read: boomstream_live_info, boomstream_live_list
• Write: boomstream_live_create, boomstream_live_update, boomstream_live_delete
• Actions: boomstream_live_record, boomstream_live_restream

PPV (pay-per-view)

• Read: boomstream_ppv_list, boomstream_ppv_listmedia, boomstream_ppv_listbuyers, boomstream_ppv_contacts
• Write: boomstream_ppv_create, boomstream_ppv_update, boomstream_ppv_delete, boomstream_ppv_addmedia, boomstream_ppv_deletemedia, boomstream_ppv_addbuyer, boomstream_ppv_updatebuyer, boomstream_ppv_deletebuyer, boomstream_ppv_updatecontacts

Conference

• Read: boomstream_conference_info, boomstream_conference_list, boomstream_conference_client_list, boomstream_conference_client_info
• Write: boomstream_conference_create, boomstream_conference_update, boomstream_conference_client_update, boomstream_conference_client_delete, boomstream_conference_delete
• Actions: boomstream_conference_invite

Media folders

• Write: boomstream_media_folder_create, boomstream_media_folder_update, boomstream_media_folder_delete
• Actions: boomstream_media_folder

Live folders

• Write: boomstream_live_folder_create, boomstream_live_folder_update, boomstream_live_folder_delete
• Actions: boomstream_live_folder

Materials folders

• Write: boomstream_materials_folder_create, boomstream_materials_folder_update, boomstream_materials_folder_delete
• Actions: boomstream_materials_folder

Playlists

• Read: boomstream_playlist_list, boomstream_playlist_listmedia
• Write: boomstream_playlist_create, boomstream_playlist_update, boomstream_playlist_delete, boomstream_playlist_addmedia, boomstream_playlist_deletemedia

Statistics

• Read: boomstream_stats_project, boomstream_stats_target, boomstream_stats_session

Chat

• Read: boomstream_chat_info
• Actions: boomstream_chat_init, boomstream_chat_create_message, boomstream_chat_update_message, boomstream_chat_delete_message

Screenshots

• Read: boomstream_screenshot_info
• Write: boomstream_screenshot_create, boomstream_screenshot_update, boomstream_screenshot_delete

Subtitles

• Read: boomstream_subtitles_info, boomstream_subtitles_download
• Upload: boomstream_subtitles_upload
• Actions: boomstream_subtitles_enable, boomstream_subtitles_enabledefault, boomstream_subtitles_enableautoplay

Timecodes

• Read: boomstream_timecodes_info, boomstream_timecodes_download
• Upload: boomstream_timecodes_upload
• Actions: boomstream_timecodes_enable

Webhook

• Read: boomstream_webhook_list, boomstream_webhook_info, boomstream_webhook_events
• Write: boomstream_webhook_update, boomstream_webhook_create, boomstream_webhook_delete

Project (app)

• Read: boomstream_app_info, boomstream_app_list
• Write: boomstream_app_create, boomstream_app_update, boomstream_app_delete

Record-live

• Read: boomstream_recordLive_info, boomstream_recordLive_list
• Write: boomstream_recordLive_update, boomstream_recordLive_delete
• Actions: boomstream_recordLive_create_record_live, boomstream_recordLive_upcoming_live, boomstream_recordLive_start_upcoming_live, boomstream_recordLive_stop_upcoming_live, boomstream_recordLive_remove_upcoming_live

Live IP camera

• Read: boomstream_cameraLive_info, boomstream_cameraLive_list
• Write: boomstream_cameraLive_create, boomstream_cameraLive_update, boomstream_cameraLive_delete
• Actions: boomstream_cameraLive_record, boomstream_cameraLive_toggle

General

• Read: boomstream_general_info

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "boomstream": {
      "command": "npx",
      "args": ["-y", "@boomstream/mcp", "stdio"],
      "env": {
        "BOOMSTREAM_API_KEY": "your-api-key"
      }
    }
  }
}

After saving, restart Claude Desktop.

claude.ai / SSE

Connect from claude.ai (web), VS Code MCP extension, or any SSE-capable MCP client — no local install required.

Auth: pass your Boomstream API key as a Bearer token. Each server instance is single-tenant (one project per pod, Phase A).

claude.ai

1. Go to Settings → Integrations (or Settings → MCP Servers depending on your plan).
2. Add a new server:
   • URL: https://mcp.boomstream.com/sse
   • Authorization: Bearer <your-boomstream-api-key>
3. Claude will discover ~100 boomstream_* tools automatically.

VS Code MCP extension

// settings.json
{
  "mcp.servers": {
    "boomstream": {
      "type": "sse",
      "url": "https://mcp.boomstream.com/sse",
      "headers": {
        "Authorization": "Bearer <your-boomstream-api-key>"
      }
    }
  }
}

curl smoke test

curl -sI -H "Authorization: Bearer <apikey>" https://mcp.boomstream.com/sse | head -5
# HTTP/2 200, content-type: text/event-stream

See examples/claude_ai_setup.md for a full raw MCP handshake walkthrough.

CLI reference

boomstream-mcp [stdio]         Start MCP server (stdio transport)
boomstream-mcp --version, -v   Print version
boomstream-mcp --help, -h      Show help

boomstream-mcp with no arguments is equivalent to boomstream-mcp stdio.

To self-host the SSE server:

BOOMSTREAM_API_KEY=your-key boomstream-mcp-sse
# Listens on PORT (default 9090). Set PORT env var to override.

Requirements

• Node.js >= 20
• A Boomstream account with API access. Get your API key in your project settings.

Security model

The SSE deployment at mcp.boomstream.com runs Phase A authentication: one Boomstream apikey per tenant, passed as Authorization: Bearer <apikey>. Before you point a production project at the hosted server, read this section — the trust model is documented openly so you can decide if it matches your risk tolerance.

Blast radius — a single apikey grants the full 101-tool surface

A Boomstream apikey carries no per-tool or per-endpoint sub-scope. A client that holds a valid apikey can call any of the ~100 tools listed under § «Available tools» above. By impact category:

| Category | Tool count | Reversibility | |---|---:|---| | Read-only (*_info, *_list, stats_*) | 56 | Mass-export of catalog metadata. No data loss, but inventory disclosure. | | State-mutating create | 23 | Creates PPV / playlist / project records. May generate billing events. Reversible by reviewing the audit log and rolling back. | | State-mutating update | 12 | Modifies metadata. Reversible. | | State-mutating delete | 10 | Irreversible without a backup restore. boomstream_media_delete, boomstream_ppv_delete, etc. |

This is a known Phase A limitation. The Stage 3 OAuth rollout introduces sub-scopes (scope=read, scope=write:media, etc.) that let clients mint Bearer tokens with constrained server-side claims. Until Stage 3 ships, treat every apikey as full-tenant-blast-radius and follow the mitigation chain below.

Mitigation chain — detect, rotate, reconstruct

The trust model is documented as accept-risk because the practical exposure is bounded by three layers working together:

1. Detect (planned — not present in v0.4.x). The Stage 2 SSE threat model specifies an apikey-fingerprint audit field: every tools/call is to be logged with apikey_fp = sha256(apikey).slice(0, 8), the session id, the tool name, and the duration — enough to attribute a call to one apikey without storing the secret. Implementation is tracked under the project's R-1 follow-up and will land in a future release; until then, detection relies on the Boomstream-side billing/audit endpoint plus operator-side network monitoring.
2. Rotate — when a leak is suspected, the 15-minute SLA rotation procedure (below) closes the window: mint a replacement apikey, roll the deployment secret, restart the deployment, revoke the old apikey at the Boomstream side.
3. Reconstruct — after revoke, the Boomstream-side billing/audit endpoint gives a bounded forensic window. State-mutating calls during the exposure are enumerable; the project owner decides on reversal. Once the pod-side fingerprint log lands, that becomes a second forensic surface alongside the Boomstream-side endpoint.

Apikey rotation — 15-minute procedure

The audience is the Boomstream project owner or the on-call operator. Steps 1–4 are ~5 minutes if everything is staged; step 5 is bounded by how much log you have to scan. Practise rotation on a sandbox project periodically to keep muscle memory intact.

1. Mint a replacement apikey. Project owner signs into the Boomstream control panel → Settings → API → «Generate new apikey». Copy the new apikey to a vault or password manager. Do not paste it into chat, email, or a support ticket.
2. Roll the deployment secret. Update the secret holding the apikey in place (do not delete and recreate — recreate breaks the rolling restart in step 3). For the hosted mcp.boomstream.com SSE deployment, the operator updates the Kubernetes secret; for a self-hosted SSE deployment, update the equivalent secret in your platform of choice (Docker secret, systemd EnvironmentFile, etc.).
3. Rolling restart. Force every running pod to pick up the new secret. Active SSE sessions terminate; clients reconnect on their own — they already handle this for normal pod restarts. Stdio clients (npx @boomstream/mcp stdio) read the apikey from their environment and are restarted by the human who manages that environment (Claude Desktop config, etc.).
4. Revoke the old apikey at the source. In the same Boomstream Settings → API UI, locate the old apikey → «Mark as revoked» → confirm. From this point upstream returns Status: "InvalidApiKey" for any request signed with the old apikey. This step is what actually closes the blast-radius window — without revoke, the old apikey continues to work against boomstream.com/api/ directly (e.g. via any stdio clients still using the old env var).
5. Audit the exposed window. Query the Boomstream-side billing/audit endpoint for any billing events the old apikey could have triggered between the suspected exfil time and the revoke timestamp. If state-mutating tools were called (the 23 creates, 12 updates, 10 deletes — see § «Blast radius» above), the project owner decides on reversal (restore from backup, refund billing events, recreate deleted media). Pod-side audit-log forensics via the apikey_fp field will become available once R-1 lands; until then, the Boomstream-side endpoint is the primary forensic surface.

Stage 3 lift-path

Stage 3 OAuth replaces the apikey-as-Bearer model with per-user OAuth tokens that carry server-side scopes (scope=read, scope=write:media, scope=admin). A leaked Stage 3 Bearer would be partially-blast-radius instead of full-tenant. The blast-radius row in this section is what Stage 3 specifically lifts.

Threat model

The complete STRIDE table, CORS allow-list, rate-limit numbers, apikey-hygiene audit (G-1..G-4 redact paths), and ingress-side hardening posture are maintained in-repo as docs/threat-model-sse.md. That document is binding for the SSE transport and is signed off by the CSO; project owners and operators with repo access should consult it before changing the deployment posture. If you need the binding artefact and do not have repo access, contact the project maintainer.

How tool schemas are generated

JSONSchema for each tool is not hand-written. The source of truth is the Boomstream API documentation database. The script scripts/build-schema.mjs parses the markdown and produces schemas/boomstream.json covering all ~100 methods in a single run. The generated file is committed to the repository and shipped in the npm package.

Development

pnpm install             # install dependencies
pnpm dev:stdio           # run server locally (stdio transport)
pnpm test                # run unit/integration tests (vitest)
pnpm build-schema        # regenerate schemas/boomstream.json from markdown corpus
pnpm build-readme-tools  # regenerate the Available tools table in this README
pnpm build               # TypeScript compile → dist/
pnpm dev:sse             # run SSE server locally (port 9090 default)
pnpm test:smoke          # end-to-end smoke cycle (requires BOOMSTREAM_TEST_API_KEY)
pnpm test:smoke:sse      # SSE smoke cycle against a running SSE server

Offline test runs use fixtures in tests/fixtures/. To pull a fresh schema from the database, run pnpm build-schema:db (requires the mariadb-mcp MCP server).

To run the smoke cycle you need:

• BOOMSTREAM_TEST_API_KEY — an API key from a sandbox Boomstream project (create one at https://boomstream.com/ and copy the key from project settings → API). Use a dedicated sandbox project, not your production project — the smoke cycle creates and deletes test media. Never paste a real production key into your shell history or CI logs.
• BOOMSTREAM_TEST_MEDIA_CODE — a known media code in that sandbox project.

Troubleshooting

BOOMSTREAM_API_KEY is not set

The server exits immediately with:

Error: BOOMSTREAM_API_KEY env required for Phase A

Set it before starting:

BOOMSTREAM_API_KEY=your-key npx -y @boomstream/mcp stdio
# or in Claude Desktop config under "env": { "BOOMSTREAM_API_KEY": "…" }

Network timeout or 5xx from boomstream.com/api/

The client retries up to 3 times with exponential backoff (100 ms → 400 ms → 1 600 ms). If all attempts fail, the tool returns an error. Check your network connectivity and boomstream.com status.

Invalid API key (401/403)

Verify your key in Boomstream project settings → API. Keys are project-scoped; make sure the key matches the project you intend to query.

Claude Desktop doesn't list any Boomstream tools

1. Check the MCP server logs:
   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%\Claude\logs\
2. Confirm BOOMSTREAM_API_KEY is set in the env block of your claude_desktop_config.json.
3. Restart Claude Desktop after any config change.
4. Run the server manually to verify it starts without errors:

   BOOMSTREAM_API_KEY=your-key npx -y @boomstream/mcp stdio

Releases

Full release notes are in the CHANGELOG.md file bundled with the npm package. Recent changes include POST+JSON transport (apikey sent in the request body, never in the URL), defence-in-depth scrubs for apikey/token/signature in tool-result content, and automated CI publish on v* tags. The full release timeline is available via npm view @boomstream/mcp time --json.

GitLab CI publishes to npm automatically when a maintainer pushes a tag of the form v\d+.\d+.\d+(-…)? (protected tag, Maintainer+ only). The job checks that package.json version matches the tag, runs pnpm build + pnpm test, and then pnpm publish --access public using a protected NPM_TOKEN. See .gitlab-ci.yml.

Roadmap

Stage 2 — SSE transport ✅ Done in v0.3.0. mcp.boomstream.com/sse is live. Phase A auth (apikey-as-Bearer). Single-tenant per pod.

Stage 3 — OAuth: per-user authentication so each Boomstream account holder can connect with their own credentials instead of a shared API key. Depends on Stage 2 infrastructure.

License

MIT — see LICENSE.