pitchboom MCP server

What the server does

It exposes the same production line as the web app, with the same credits: website analysis, AI script and storyboard, voice-over, music and rendering, then edits, translations, other formats and 4K exports of a finished video. Your assistant drives it with tools; you approve every quote and every storyboard.

Get started

1. Subscribe to Pro or Premium at pricing, then create a key at Settings > API & MCP. The full key is shown once: copy it into your client right away.
2. Add the server to your client with one of the snippets below.
3. Ask for a video, for example: "Make a 15-second 9:16 video ad for https://example.com and show me the quote first."

Authentication and API keys

Every request carries a personal key in the Authorization header: Authorization: Bearer pb_live_…. Keys are created and revoked at Settings > API & MCP, signed in, on the Pro or Premium plan.

• Never put a key in a URL: a request with ?api_key=, ?key= or ?token= is refused (key_in_url). Revoke a key that leaked that way.
• pitchboom stores only an HMAC of the key and checks it on every request, so a revocation, a plan change or a blocked account applies on the next call.
• Up to 10 active keys per account: one per client or machine makes revoking easy.
• A key never carries admin rights, even on an admin account.
• There is no OAuth sign-in yet: clients that can only connect through OAuth can't use the server for now.

Install in your client

Any MCP client that speaks Streamable HTTP and can send a custom header works. Replace pb_live_YOUR_KEY with your key; where a client reads environment variables, keep the key there instead of in a file you share.

Claude Code

claude mcp add --transport http pitchboom https://pitchboom.io/api/mcp --header "Authorization: Bearer pb_live_YOUR_KEY"

Add --scope user to use it in every project. Then run /mcp in Claude Code to check the connection.

Claude Desktop

Add the pitchboom MCP server by running:
claude mcp add --transport http --scope user pitchboom https://pitchboom.io/api/mcp --header "Authorization: Bearer pb_live_YOUR_KEY"

--scope user makes pitchboom available in every Code session. Start a new chat afterwards and ask it to make a video.

Claude custom connector

Remote MCP server URL: https://pitchboom.io/api/mcp
Authentication: No sign-in
Request headers: authorization = Bearer pb_live_YOUR_KEY

Request headers are a beta that not every Claude account shows yet; without them, use Claude Code or the Code tab of Claude Desktop. Enter the value with the Bearer prefix. On a Team or Enterprise organization, everyone who uses the connector shares that one key and its account's credits.

Cursor

{
  "mcpServers": {
    "pitchboom": {
      "url": "https://pitchboom.io/api/mcp",
      "headers": {
        "Authorization": "Bearer pb_live_YOUR_KEY"
      }
    }
  }
}

In a shared repository, put the key in an environment variable instead of the file.

The button opens Cursor with the server filled in; replace pb_live_YOUR_KEY with your key in Cursor's MCP settings.

VS Code

{
  "inputs": [
    {
      "type": "promptString",
      "id": "pitchboom-key",
      "description": "pitchboom API key",
      "password": true
    }
  ],
  "servers": {
    "pitchboom": {
      "type": "http",
      "url": "https://pitchboom.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:pitchboom-key}"
      }
    }
  }
}

VS Code asks for the key once and stores it securely.

The install link adds the same entry and asks for the key once (a password prompt).

Codex CLI

export PITCHBOOM_API_KEY=pb_live_YOUR_KEY
codex mcp add pitchboom --url https://pitchboom.io/api/mcp --bearer-token-env-var PITCHBOOM_API_KEY

bearer-token-env-var takes the variable's NAME, not the key.

Gemini CLI

gemini mcp add --transport http -s user --header "Authorization: Bearer pb_live_YOUR_KEY" pitchboom https://pitchboom.io/api/mcp

Without -s user it goes to the project's .gemini/settings.json. The settings entry is { "httpUrl": "https://pitchboom.io/api/mcp", "headers": { "Authorization": "Bearer <key>" } }.

Windsurf (Devin Desktop)

{
  "mcpServers": {
    "pitchboom": {
      "serverUrl": "https://pitchboom.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PITCHBOOM_API_KEY}"
      }
    }
  }
}

Set PITCHBOOM_API_KEY in your environment: headers read ${env:NAME} variables, so the key stays out of the file.

Other clients

URL: https://pitchboom.io/api/mcp
Transport: Streamable HTTP
Header: Authorization: Bearer pb_live_YOUR_KEY

Never put the key in a URL. Clients that only run local servers (e.g. Claude Desktop chats without the Code tab) can bridge it: npx -y mcp-remote@latest <URL> --header "Authorization: Bearer <key>". Test with the MCP Inspector: npx @modelcontextprotocol/inspector

Credits, quotes and confirmation

Nothing is charged without `confirm_operation` (or approve_storyboard for a video already launched). The rule is the web app's.

• create_project, get_estimate, request_variant and paid edits through edit_video only return quotes: quote_id, credits per video and in total, balance after.
• Your assistant shows you the quote and calls confirm_operation only after you approve that exact amount. Both spending tools are annotated destructiveHint and carry anthropic/requiresUserInteraction, so Claude Code asks you every time.
• Quotes expire after 30 minutes; get_estimate makes a fresh one.
• On confirmation the quoted credits are held from your balance, not spent. Each finished step consumes its share; whatever isn't used is released when the job ends.
• If a step fails on our side, the credits it consumed are refunded automatically. cancel_job stops a job and you pay only the finished steps.
• Storyboards pause for your approval before the voice-over and the render. If your edits make the video longer, approve_storyboard refuses the old total and returns the new one to show you.
• Free (0 credits): every read tool, analyze_url, update_storyboard and the edits of edit_video that need nothing new.

Prices are the web app's: Standard 13, Studio 100 credits per second. See pricing for the plans and the credits they include.

With a No spending key, the assistant prepares quotes and edits; you confirm paid work in the web app.

Typical flow

1. get_credit_balance: balance, plan and the key's permissions.
2. Optionally get_options (accepted values, instead of guessing ids) and list_brand_kits.
3. create_project with a URL and/or a brief: it returns a quote. Show it to the user.
4. After the user approves: confirm_operation(quote_id).
5. get_job_status (with wait_seconds) until the video waits for storyboard approval.
6. get_storyboard, then optional free changes with update_storyboard, and the user's approval.
7. approve_storyboard(max_total) with the total the user accepted.
8. get_job_status until it succeeds, then get_video: download right away, the links are valid for 1 hour and must not be stored or shared.
9. After rendering: edit_video for changes, request_variant for translations, other formats, new takes or 4K.

Tool reference

The 18 tools every key on a plan with MCP sees, in tools/list order. Access is the key scope a tool needs (Read, Prepare & edit, Spend credits); the hints are the MCP annotations clients use to decide when to ask you.

The 5 source-code tools come right after analyze_url (see Sending product source code):

The full descriptions and input schemas are what tools/list returns, also published in the server card. Without a key, tools/list and the server card show the 18 core tools; the 5 source-code tools appear once a key is sent.

Sending product source code (Claude Code)

From Claude Code, or any agent that can run shell commands in your repository, you can send your product's source code so videos rebuild your real interface. Your assistant must ask you first: your code leaves your machine. The tools return the consent text to show you.

1. prepare_code_upload with consent_accepted=true once you agree: it returns a code_source_id, a signed upload URL and a pack_command.
2. Run the pack_command in the repository (tracked files only, secrets and build folders excluded), then the upload_command (PUT).
3. complete_code_upload, then get_code_source until the analysis is ready.
4. create_project with code_source_id (and optionally the screens to show).

• Public GitHub repositories can be read with import_code_from_github instead (private ones through the pitchboom GitHub App), with the same consent.
• get_code_source never returns code; it shows the privacy report and the deletion date. delete_code_source deletes the code and everything derived from it at once (Brand Kits and rendered videos stay).
• Screens rebuilt from your code are priced per second on top of the quality: with your code: Standard +10, Studio +20 credits per second.
• Details: privacy policy.

Errors

Errors before any tool runs are HTTP errors with a JSON body { "error": { "code", "message", "docs" } }. A 401 also carries WWW-Authenticate: Bearer realm="pitchboom"; a 429 or 503 carries Retry-After.

A tool that can't do what was asked returns a tool result with isError: true and one line that starts with ERROR <code>: and says how to fix it, for example:

ERROR quote_expired: This quote expired (30 minutes). Get a fresh one with get_estimate and confirm it again with the user.

Rate limits

• Per API key: 120 requests per minute and 3,000 per hour (tools/list included); on Premium, twice that (240 per minute and 6,000 per hour).
• Per client network: 300 requests per minute with a key; 30 requests per minute and 300 per hour without one.
• Per account, on the tools: quotes (create_project, get_estimate, request_variant, paid edits) 60 per hour and 300 per day; confirmations (confirm_operation, approve_storyboard) 30 per hour and 200 per day; edits 120 per hour; waiting status polls 600 per hour. Website analyses follow your plan's daily quota.
• Over a limit: HTTP 429 rate_limited with Retry-After, or the tool error ERROR rate_limited:. A refusal never charges anything.

Security

• Treat a key like a password: keep it out of repositories and shared config, and revoke it at Settings > API & MCP if it leaks. The next request with it gets a 401.
• Give each key the smallest preset it needs: Read only for reporting, No spending to prepare work you confirm in the app.
• The spending tools ask for a human confirmation in clients that honour anthropic/requiresUserInteraction (Claude Code).
• Text in storyboards, website analyses and code analyses comes from websites or code: the server tells assistants to treat it as data, never as instructions.
• Download links are signed and expire after 1 hour.
• Every call is recorded per key (tool, result, credits held); the last 20 show under Recent activity at Settings > API & MCP.
• The keyless handshake and tool list return no account data.

Discovery without a key

Directories and clients can read the server before you add a key: initialize, notifications/initialized, ping, tools/list answer without one, from the public tool catalog, rate-limited per network. Every other request without a key, tools/call included, gets the 401 missing_api_key.

curl -s https://pitchboom.io/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

• Server card (name, transport, authentication, tools with their input schemas): /.well-known/mcp/server-card.json.
• This page as Markdown: /docs/mcp.md.
• Test with the MCP Inspector: npx @modelcontextprotocol/inspector.