MCP

Connect Growth Studio to your tools (MCP)

Growth Studio exposes a Model Context Protocol (MCP) server. Any MCP-compatible client — Claude Desktop, Cursor, or your own agent — can create ad batches, approve them, and query results with a bearer token.

Endpoint

POST https://vidvid.tv/api/mcp

Authentication

Create a token on the API Tokens page and send it as a bearer token. Tokens carry scopes: batch:read, batch:create, batch:approve. The plaintext token is shown once at creation — store it in your secret manager.

growth_approve_batch is the only call that charges credits. Create is free; queries are free. Approvals are idempotent.

Client configuration

Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "vidvid": {
      "url": "https://vidvid.tv/api/mcp",
      "headers": {
        "Authorization": "Bearer vv_live_YOUR_TOKEN"
      }
    }
  }
}

Tools

toolscopeargumentsreturns

growth_create_batchbatch:createproductName, imageUrl | assetId, sceneScript, aspectRatios, variantCount, model?, duration?batchId, batchNo, creditsEstimated, clamped

growth_approve_batchbatch:approvebatchIdstatus, creditsCharged, submitted, failed

growth_query_batchbatch:readbatchIdstatus, creditsCharged, variants[] (videoUrl, status)

Command line (curl)

Initialize

curl -s "$ORIGIN/api/mcp" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

List tools

curl -s "$ORIGIN/api/mcp" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Create batch (no charge)

curl -s "$ORIGIN/api/mcp" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"growth_create_batch","arguments":{"productName":"Ceramic Jar","imageUrl":"https://…/download_url","sceneScript":{"vertical":"general","hook":"Meet the jar","scenes":[{"shot":"Hero","prompt":"product: {product} on a bright shelf","negative_prompt":"text overlay","camera":"slow push-in"}]},"aspectRatios":["9:16","1:1"],"variantCount":6}}}'

Approve (charges credits)

curl -s "$ORIGIN/api/mcp" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"growth_approve_batch","arguments":{"batchId":123}}}'

Query results

curl -s "$ORIGIN/api/mcp" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"growth_query_batch","arguments":{"batchId":123}}}'

Notes

Rate limit: 60 requests per minute per token.
All monetary values are computed server-side; the protocol never accepts credit amounts from clients.
Revoke a token at any time from the API Tokens page — revocation is immediate.
Batch creation validates model, ratio and duration against the server whitelist before returning an estimate.