# AdRecast MCP Server

AdRecast remakes proven e-commerce video ads for your product: it maps a reference ad's shots, pacing and hook, writes a script you confirm, and generates a full multi-scene ad with your product and cast, checked for product accuracy in every frame.

## Endpoint

- URL: `https://adrecast.com/api/mcp`
- Transport: Streamable HTTP.
- Authentication: API key only. Send it as a Bearer token: `Authorization: Bearer rk_live_...`
  - Create a key in Settings → API keys. Choose scopes from `read`, `write` and `spend`.
  - Keys are shown once. Store the key somewhere safe when you create it.
  - OAuth is not supported.

## What it does

The MCP server runs the same remake flow as the web app: find a template → upload product images → review the script → estimate → generate → poll → export.

Tools (46 in total), grouped by area. The grouping is this README's own; the docs list the tools by endpoint.

- Templates & uploads: `search_templates`, `create_upload_url`
- Projects: `create_project`, `list_projects`, `get_project`, `get_script`, `update_script`, `rewrite_script`, `get_rewrite`, `add_line`, `delete_line`, `reorder_lines`, `confirm_script`
- Generation & export: `estimate_cost`, `generate_video`, `list_jobs`, `list_clips`, `get_job`, `export_video`, `get_export`
- Characters & voices: `create_character`, `list_characters`, `delete_character`, `update_character`, `clone_character_voice`, `keep_character_voice`, `list_voices`, `set_project_character`
- Variants: `list_hook_formulas`, `list_variant_styles`, `create_hook_variant`, `estimate_variants`, `create_variants`, `list_variants`, `get_variant_manifest`, `add_variant_product`, `cancel_variant_batch`
- Studio: `studio_quote`, `create_studio_generation`, `list_studio_generations`, `list_studio_assets`, `get_studio_generation`, `confirm_studio_video`, `discard_studio_video`, `save_studio_output`
- Account: `get_balance`

Video is generated per scene, with the same actor, product and voice across shots. Captions, voice-over or a song, and music are included. You can fix one shot without redoing the whole video.

## Spending safety

- Pricing is in credits. 100 credits = $1. Analysis, script, storyboard stills and pre-video script edits are free.
- Video is billed per generated second. 720p is 40 credits/s, 1080p is 50 and 2K is 60. The resolution is fixed when the project is created.
- `generate_video` and `export_video` only spend with `confirm: true`. Without it, they return the estimate (`402 confirmation_required`). Call `estimate_cost` and show the estimate to the user before you set `confirm: true`.
- `export_video` with a 1:1 or 16:9 re-frame costs 20 credits/s. A 9:16 export is free.
- Revising a shot after its video exists costs 80% of the video price per redone second.
- `clone_character_voice` spends a fixed 1000 credits. It also needs `confirm: true`.
- Creating a project requires the $1 trial or a top-up first (`402 payment_required` otherwise).
- Auto generation (`auto_generate=true` on `create_project`) needs the `spend` scope.
- Studio prices are 0.8× the matching remake price.
- Failed jobs release their frozen credits.
- For REST calls, send an `Idempotency-Key` on every POST that creates or spends, so retries never double-charge.

## Quick start

Create an API key in Settings → API keys, then export it in the shell where your client runs:

```sh
export ADRECAST_API_KEY=rk_live_...
```

### Generic MCP client

Use this JSON for any client that accepts `url` and `headers`:

```json
{
  "mcpServers": {
    "adrecast": {
      "url": "https://adrecast.com/api/mcp",
      "headers": { "Authorization": "Bearer ${ADRECAST_API_KEY}" }
    }
  }
}
```

### Claude Code

```sh
claude mcp add --transport http adrecast https://adrecast.com/api/mcp --header "Authorization: Bearer $ADRECAST_API_KEY"
```

### Cursor

Add this to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "adrecast": {
      "url": "https://adrecast.com/api/mcp",
      "headers": { "Authorization": "Bearer ${ADRECAST_API_KEY}" }
    }
  }
}
```

### Codex

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.adrecast]
url = "https://adrecast.com/api/mcp"
bearer_token_env_var = "ADRECAST_API_KEY"
```

The `examples/` folder contains these snippets as separate files.

## Example prompts

- "Find a car-selfie skincare UGC template and estimate a 1080p remake for my product."
- "Upload these three product photos, start a project from the Problem → Agitate → Solve template, and show me the script before we generate anything."
- "Rewrite the script so it leads with the guarantee and targets 30 seconds, then show me the updated lines."
- "Plan three hook variants for this project and show me the estimate. Don't run them until I approve."
- "Check my credit balance and tell me whether a 2K export of this project fits in it."

## Links

- Website: https://adrecast.com/en
- Pricing: https://adrecast.com/en/pricing
- Templates: https://adrecast.com/en/templates
- Use cases: https://adrecast.com/en/use-cases
- Cases (real outputs and reference ads): https://adrecast.com/en/cases
- API & MCP docs: https://adrecast.com/en/docs/api
- Contact: https://adrecast.com/en/contact
- Full page index: https://adrecast.com/llms-full.txt

## License

The server is a hosted service operated by AdRecast. This repository contains documentation and configuration examples only (MIT).