Ad Remixer MCP - Gooseworks

Everything you can do in the Ad Remixer web app — set up a brand, pick a starting ad, 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 — 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 <your-api-key>

The fastest path is the CLI, which registers the server for you:

npx gooseworks install --claude --mcp

Or wire it up by hand with a user-scoped mcp:access token:

{
  "mcpServers": {
    "gooseworks": {
      "type": "http",
      "url": "https://mcp.gooseworks.ai/mcp",
      "headers": {
        "Authorization": "Bearer cal_YOUR_TOKEN"
      }
    }
  }
}

{
  "mcpServers": {
    "gooseworks": {
      "type": "http",
      "url": "https://mcp.gooseworks.ai/mcp",
      "headers": {
        "Authorization": "Bearer cal_YOUR_TOKEN"
      }
    }
  }
}

See MCP Servers → Manual setup 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 ad skills

You don’t have to memorize the tool sequence. The MCP exposes search_skills and fetch_skill, including two entry recipes for ads:

fetch_skill("goose-ads") for static ads, brand research, and campaign analysis.
fetch_skill("goose-video") for video-ad projects and local final rendering.

These instructions come from the GooseWorks MCP at run time. A local goose-ads or goose-video skill file is optional and is not required for an MCP-connected client. npx gooseworks install --all can still install local copies and register the MCP for coding agents that support local setup. For a specific video project, use an explicit prompt such as: Use the GooseWorks MCP and call fetch_skill("goose-video") for project <project-id>. Follow the fetched instructions; no local goose-video skill file is required.

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 one product in the kit (max 100 per brand)
`upsert_brand_products`	Bulk create/update many products in one call (array); returns per-item `results` — for loading a full catalog
`add_brand_product_image` / `remove_brand_reference_image`	Attach or remove one product/reference image
`add_brand_product_images`	Bulk attach many images in one call (array of `workspace_path` / `image_url`); returns per-item `results`
`finalize_brand_research`	Complete a locally-run research pass

Templates

The starting image for a remix — one you uploaded, or one from the community.

Tool	What it does
`search_ad_templates`	Search the Community gallery by natural-language description — returns ranked `community_generation` matches to remix via `remix_community_ad`
`surprise_me_templates`	Pick brand-relevant ads at random from the Community gallery (the web “Surprise me” path); returns a ready-to-open `create_url`
`get_static_ad_template`	Fetch one of your own templates by uuid or slug — a Community ad you snapshotted, or a “bring your own ad” upload (source image, ratio, replicability hints)
`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. Set `rights_attested: true` only when you own or have the right to use the image (never for a competitor’s ad or an image found online)
`list_user_ad_templates` / `delete_user_ad_template`	Manage your uploaded templates (list accepts a `tags` filter)
`set_user_ad_template_tags`	Set the folder-like organization tags on one of your uploaded templates (replaces the whole set; `[]` clears)
`remix_community_ad`	Snapshot a 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 (accepts a `tags` filter)
`set_ad_creative_tags`	Set the folder-like organization tags on one creative (replaces the whole set; `[]` clears) — the same tags the gallery filters by
`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

Layers — split a creative for Figma, Canva, or code

Decompose a finished flat creative into editable transparent-PNG layers — the clean inpainted background plate plus each foreground element (product, text, logo, graphic) as its own layer with a normalized position box. Point your agent at both the GooseWorks MCP and your Figma MCP (or Canva/code) and it can rebuild the ad as real, movable layers with no plugin.

Tool	What it does
`get_creative_layers`	Return a creative decomposed into editable layers — the base plate plus each element’s transparent PNG, normalized `box` (`x,y,width,height` in `[0,1]`), `z_index`, `name`, `kind`, and (for text) the `text` string. If the creative isn’t split yet it starts the layerize job and returns `status: "processing"` — call again in ~2 minutes to fetch the layers

To place in Figma: create a frame at your target size, then for each layer paint bottom-to-top by z_index (the base plate is z 0 and fills the frame), positioning each image at box.x*frameW, box.y*frameH sized box.width*frameW × box.height*frameH. Text-kind layers that carry a text string can be created as real Figma text instead of the raster.
status values: processing (job started — poll again), complete (layers returned), not_layerized (call with layerize_if_missing: true or use the app’s Split into layers), failed (content-checker or unsplittable — try a different creative).
Billing: credits are charged only when the split actually runs; a failed split is never charged. Pass layerize_if_missing: false to fetch existing layers without triggering a new job.

Product photos

Generate clean, branded product photography (studio, lifestyle, on-model) for a product, then approve the ones you like so they enrich the brand kit and can feed the ad-generation flow. Generation runs through the same server-side pipeline the Product Photos studio uses (compose → generate → judge → retry) — your agent never renders images itself.

Tool	What it does
`list_brand_products`	List a brand’s imported products so you can pick a `product_id` (supports `search` + pagination). Get `brand_id` from `list_ad_brands`
`import_product`	Import a product (or a whole Shopify catalog) from a URL — `shopify_store`, `product_url`, or `image_url` (needs `product_name`). Returns an import row; poll `get_product_import` until `complete`
`get_product_import`	Poll an import by id until `status` is `complete` or `failed`, then use `list_brand_products` to find the new product
`estimate_product_photos`	Preview the credit cost of a generation (per-output + total) before submitting. Retries are included free; nothing is reserved
`generate_product_photos`	Reserve credits and start a generation for a product (`category`, optional `controls`/`prompt`, `count`, `quality`). Returns a generation id immediately — poll `get_product_photo_generation` until done. A human model (`controls.model.presence != none`) requires `attestation_accepted: true`
`get_product_photo_generation`	Poll a generation by id until `status` is `complete`/`partial_failure`/`failed`; read each `outputs[].final_image_url`
`list_product_photos`	List a brand’s generated outputs (`archived: false` = active, `true` = archived)
`approve_product_photo`	Approve an output — links it to the product and makes it available in the brand kit for ad generation
`archive_product_photo`	Archive an output (optional `reason`) — archived outputs are excluded from ad generation

Photos are not used in ads until you approve them, and archived photos are never used. Generate → poll → approve_product_photo the winners.

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

Pick or create a brand

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.

Read the brand kit

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.

Choose a starting ad

search_ad_templates or surprise_me_templates to find a Community ad, remix_community_ad to snapshot one for remixing, or create_user_ad_template to bring your own.

Estimate the cost

estimate_remix_batch returns the exact credit cost so you can confirm before spending.

Submit

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 and deliver

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 and How credits are used for the full model.

Next steps

MCP Servers

Full setup, tokens, and the files / chat / automations tools on the same server.

Creating ads

The web composer — the same generation settings, in the UI.

Brands & brand kit

What the brand kit holds and how research populates it.

CLI

Install the skill catalog and register the MCP in one command.

​Connect

​The ad skills

​Tools

​Brands & brand kit

​Templates

​Generate creatives

​Plan mode (review before you spend)

​Layers — split a creative for Figma, Canva, or code

​Product photos

​Feedback & credits

​End-to-end flow

​Billing

​Next steps

MCP Servers

Creating ads

Brands & brand kit

CLI

Connect

The ad skills

Tools

Brands & brand kit

Templates

Generate creatives

Plan mode (review before you spend)

Layers — split a creative for Figma, Canva, or code

Product photos

Feedback & credits

End-to-end flow

Billing

Next steps