> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gooseworks.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Ad Remixer MCP
> Drive the whole Ad Remixer from Claude Code, Cursor, Codex, or any MCP client
Everything you can do in the [Ad Remixer](/ad-remixer/overview) web app — set up a brand, pick a template, generate branded creatives, re-roll and edit them — is also exposed as tools on the **GooseWorks MCP server**. Point any MCP-aware agent at it and your agent can run the full ad pipeline for you, in your own account, billed to your own credits.
The generation itself runs through the **same cloud workflow the web app uses**. Your agent never renders images locally or calls an image provider directly — it submits a batch, GooseWorks reserves credits and runs the pipeline server-side, and your agent polls for the finished creatives and hands you the links.
This is the same `gooseworks` MCP server documented in [MCP Servers](/concepts/mcp-servers) — one connection, one token. That page covers files, chat history, and automations; this page covers the ad-remixing tools on the same server.
## Connect
The Ad Remixer tools live on the standard GooseWorks MCP server, so if you've already connected it, you're done — the ad tools are already available. If not:
* **URL:** `https://mcp.gooseworks.ai/mcp`
* **Transport:** HTTP (streamable)
* **Auth:** `Authorization: Bearer `
The fastest path is the CLI, which registers the server for you:
```bash theme={null}
npx gooseworks install --claude --mcp
```
Or wire it up by hand with a user-scoped `mcp:access` token:
```json Claude Code (~/.claude.json) theme={null}
{
"mcpServers": {
"gooseworks": {
"type": "http",
"url": "https://mcp.gooseworks.ai/mcp",
"headers": {
"Authorization": "Bearer cal_YOUR_TOKEN"
}
}
}
}
```
```json Cursor (~/.cursor/mcp.json) theme={null}
{
"mcpServers": {
"gooseworks": {
"type": "http",
"url": "https://mcp.gooseworks.ai/mcp",
"headers": {
"Authorization": "Bearer cal_YOUR_TOKEN"
}
}
}
}
```
See [MCP Servers → Manual setup](/concepts/mcp-servers#manual-setup-without-the-cli) for how to create the token and rotate/revoke it.
Use a **user-scoped** token. The MCP resolves your current workspace/organization on every request, so ad tools operate on the right account automatically. Ad data is organization-scoped — every tool accepts an optional `target` to point at a specific org, but you can omit it to use the token's default.
## The goose-ads skill
You don't have to memorize the tool sequence — GooseWorks ships a **`goose-ads` skill** that documents the exact recipe (which tool to call, in what order, and how to interpret results). Your agent should fetch and follow it before starting any ad task.
* **CLI users:** `npx gooseworks install` writes the skill to `~/.agents/skills/` so your coding agent discovers it automatically.
* **Hosted MCP clients** (e.g. Claude connectors) with no local filesystem: the MCP server's own instructions point your agent at the skill's public URL, and it fetches it on demand.
Either way, a good prompt is simply: *"Use GooseWorks to make three ads for my brand."* The agent loads the skill and drives the tools below.
## Tools
All tools are prefixed `mcp__gooseworks__*` when your client namespaces them. They fall into a few families.
### Brands & brand kit
A **brand kit** is the reusable source of truth for every remix — logo, colors, fonts, products, audience, and voice. Generation is blocked until a brand's research is complete.
| Tool | What it does |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_ad_brands` | List the org's brands (lean rows; filter by name) |
| `get_ad_brand` | Fetch one brand row |
| `get_brand_kit` | Read a brand's full canonical kit — the read model the pipeline uses (products, reference images, palette, voice) plus a `brand_kit_url` to share |
| `create_ad_brand` | Create a brand. With a `website_url` it kicks off backend **light research** (logo/colors/fonts + baseline kit) — poll `get_brand_kit` until `researchStatus` is `complete` |
| `update_ad_brand` | Update brand fields / research status |
| `update_brand_kit` | Enrich the kit — positioning, audience, voice, value props, standing instructions, brand type, palette |
| `upsert_brand_product` / `delete_brand_product` | Manage products in the kit (max 12) |
| `add_brand_product_image` / `remove_brand_reference_image` | Attach or remove product/reference images |
| `finalize_brand_research` | Complete a locally-run research pass |
### Templates
The starting image for a remix — a proven ad from the catalog, one you uploaded, or one from the community.
| Tool | What it does |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `list_static_ad_templates` | Browse the curated static (image) template catalog — filter by industry, style, ratio, featured |
| `get_static_ad_template` | Fetch one template by uuid or slug (source image, ratio, replicability hints) |
| `surprise_me_templates` | Pick brand-relevant templates at random (the web "Surprise me" path); returns a ready-to-open `create_url` |
| `list_ad_templates` / `get_ad_template` | The ad-sample library (includes video samples like the iMessage format) |
| `create_user_ad_template` | **Bring your own ad** — upload one of your own images as a private, org-scoped remixable template |
| `list_user_ad_templates` / `delete_user_ad_template` | Manage your uploaded templates |
| `remix_community_ad` | Snapshot a [Community](/ad-remixer/community) creative into a private template you can then remix |
### Generate creatives
The core loop. `estimate` → `submit` → poll `get_remix_batch` → deliver the links.
| Tool | What it does |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `estimate_remix_batch` | Preview the credit cost **before** submitting — image count, per-image and total credits, available balance. No credits reserved |
| `submit_remix_batch` | Generate branded ads from one or more templates. Reserves credits up front, runs the cloud pipeline (compose → generate → persist → judge), bills only completed images. Returns a batch with a `links` block |
| `get_remix_batch` | Poll a batch by id. Done when **every creative's `pending` is 0** |
| `list_brand_creatives` | The brand's gallery feed — an alternative poll target, and how you show the user everything they've made |
| `regenerate_creative` | Edit or re-roll a single creative — `variation` (re-roll), `edit` (targeted change to one render), or `exact` (run a prompt verbatim) |
Defaults mirror the web composer: `variants: 1`, `ratios: ["4:5"]`, `engine: gpt_image_2`, `quality: medium`, `preserve_source_styling: true`.
* **Ratios:** `1:1`, `4:5`, `9:16`
* **Engines:** `gpt_image_2`, `nano_banana_2`, `nano_banana_pro`, `fal_flux_kontext`
* **Quality:** `low`, `medium`, `high` (gpt\_image\_2 only)
Poll `get_remix_batch` until each creative's `pending` count reaches 0 — **not** `current_render_url`, which keeps pointing at the prior image during a regenerate. A render is only failed when its `status` is `"failed"`; a slow render is not a stuck one, so don't re-submit (that double-bills). Most images finish in a few minutes.
### Plan mode (review before you spend)
Submit with `requires_approval: true` to **compose each creative's plan and pause** — no credits are reserved and nothing renders until you approve.
| Tool | What it does |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `list_ad_approvals` | List creatives whose plans are composing or awaiting review, with the frozen plan (prompt, reference images, quality/ratios) |
| `revise_ad_plan` | Recompose an awaiting plan from a natural-language steer — iterate for free before generating |
| `approve_ad_plan` | Approve one creative (`project_id`) or a whole batch (`batch_id`) — **this is the step that reserves credits and starts the render** |
### Feedback & credits
| Tool | What it does |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_ad_credits` | The org's current ad credit balance |
| `set_creative_feedback` | Record happy / neutral / sad + comment on a render (feeds the generation-quality learning loop). Takes a **render** id, not a project or batch id |
## End-to-end flow
Call `list_ad_brands`, or `create_ad_brand` with a `website_url` for a new one. Poll `get_brand_kit` until `researchStatus` is `complete` — generation is blocked until then.
`get_brand_kit` gives your agent the products, reference images, palette, and voice the pipeline will use. Don't research the brand yourself — the backend owns that.
`list_static_ad_templates` to browse, `surprise_me_templates` to auto-pick, `create_user_ad_template` to bring your own, or `remix_community_ad` to start from a community creative.
`estimate_remix_batch` returns the exact credit cost so you can confirm before spending.
`submit_remix_batch` with the brand, the templates, and any steering prompt. (Add `requires_approval: true` to review the plan first via `list_ad_approvals` → `approve_ad_plan`.)
Poll `get_remix_batch` until every creative's `pending` is 0, then hand back the `links` — the brand gallery and each creative's page. Re-roll or edit any of them with `regenerate_creative`.
## Billing
Ad generation is credit-billed through your GooseWorks wallet, exactly like the web app:
* `submit_remix_batch` / `approve_ad_plan` **reserve** credits up front and error with `insufficient_credits` if the wallet is short.
* Only **completed** images are billed on finalize — failed renders don't cost credits.
* Use `estimate_remix_batch` to preview cost, and `get_ad_credits` to check the balance.
See [Credits & billing](/help-center/credits-and-billing) and [How credits are used](/help-center/how-credits-are-used) for the full model.
## Next steps
Full setup, tokens, and the files / chat / automations tools on the same server.
The web composer — the same generation settings, in the UI.
What the brand kit holds and how research populates it.
Install the skill catalog and register the MCP in one command.