# Quickstart: MCP (/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 [#connect]

<Steps>
  <Step>
    ### Add the server [#add-the-server]

    ```text title="Server URL"
    https://mcp.riffads.com
    ```

    <Tabs items="['Claude Code','Claude','Cursor','VS Code','ChatGPT']">
      <Tab value="Claude Code">
        ```bash title="Terminal"
        claude mcp add --transport http riffads https://mcp.riffads.com
        ```
      </Tab>

      <Tab value="Claude">
        Settings, Connectors, Add custom connector. Paste the URL, save.
      </Tab>

      <Tab value="Cursor">
        ```json title="Cursor MCP config"
        { "type": "http", "url": "https://mcp.riffads.com" }
        ```
      </Tab>

      <Tab value="VS Code">
        ```json title="VS Code MCP config"
        { "name": "riffads", "type": "http", "url": "https://mcp.riffads.com" }
        ```
      </Tab>

      <Tab value="ChatGPT">
        Settings, Connectors, paste the URL.
      </Tab>
    </Tabs>

    More clients and raw config: [Connect](/mcp/connect).
  </Step>

  <Step>
    ### Sign in and allow spending [#sign-in-and-allow-spending]

    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](https://app.riffads.com/connections), every tool returns `connection_not_configured`.
  </Step>

  <Step>
    ### Check it [#check-it]

    Ask your agent to run `riffads_ping`. Look for `"can_spend_credits": true`. `false` means a read-only connection.
  </Step>
</Steps>

## Make your first video [#make-your-first-video]

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.

```json title="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.

```json title="2. submit_generation"
{
  "capability_id": "veo_31",
  "config": { "prompt": "A barista slides a flat white across a marble counter." },
  "max_credits": 264
}
```

<Callout type="warn" title="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.
</Callout>

```json title="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.

## If a tool refuses [#if-a-tool-refuses]

| 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](/reference/errors).

## Next [#next]

<Cards>
  <Card title="Talking actor ads" href="/guides/talking-actor" description="An actor speaks your script." />

  <Card title="MCP tools" href="/mcp/tools" description="Every tool, args and outputs." />

  <Card title="Capabilities" href="/capabilities" description="Every id you can submit." />
</Cards>