Quickstart: MCP

Connect your AI agent to RiffAds and make one video. No API key: you sign in with OAuth in the browser.

You need: a RiffAds workspace on a paid plan and any MCP client that speaks streamable HTTP.

Connect

Server URL

https://mcp.riffads.com

Terminal

claude mcp add --transport http riffads https://mcp.riffads.com

More clients and raw config: Connect.

The consent screen asks for a workspace and whether the agent may spend. Pick spend, or the agent can browse but not generate.

Several workspaces? Until you pick one at app.riffads.com/connections, every tool returns connection_not_configured.

Ask your agent to run riffads_ping. Look for "can_spend_credits": true. false means a read-only connection.

Just ask: "Make an 8 second RiffAds video of a barista sliding a flat white across a marble counter."

The agent should call these tools in order. veo_31 is text-to-video: one prompt, one generation.

1. estimate_generation

{
  "capability_id": "veo_31",
  "config": { "prompt": "A barista slides a flat white across a marble counter." }
}

The result's credits is the number to base max_credits on.

2. submit_generation

{
  "capability_id": "veo_31",
  "config": { "prompt": "A barista slides a flat white across a marble counter." },
  "max_credits": 264
}

max_credits must be above the estimate

Send at least ceil(estimate * 1.1), or the submit is refused with max_credits_exceeded. 264 is only an example.

3. wait_for_generation

{ "generation_id": "gen_9f2c8d1a4b6e" }

Each call blocks up to 20 seconds. Call again while still_running is true.
Done: generation.outputs[0].url is a signed link, also sent as a resource_link.
Links last 600 seconds. Read the generation again for a fresh one.

Not sure of a field? get_capability_schema returns the JSON Schema and an example_config. Unknown keys are refused.

Code	Fix
`connection_not_configured`	Pick a workspace at `/connections`.
`read_only_connection`	Reconnect with spending allowed. Owners and admins can widen it.
`max_credits_exceeded`	Send at least `ceil(estimate * 1.1)`.
`spend_limit_exceeded`	A workspace cap blocked it. Ask an owner.
`insufficient_credits`	Top up in the app.
`submission_in_flight`	One job at a time. Wait for the first.

All codes: Errors.