# Ad Machine for AI agents

> Ad Machine turns product photos into finished ad campaigns. Connect it to ChatGPT, Claude, Claude Code, Codex, Grok, Muse, Cursor, VS Code, Gemini CLI, or any MCP client, and make ads, 4K images, and video from a chat.

- MCP server: https://admachine.xyz/mcp (Streamable HTTP)
- Auth: OAuth 2.1 with PKCE, discovered from the 401 response, or `Authorization: Bearer am_live_…` with an API key from Settings → Agents
- Protected resource metadata: https://admachine.xyz/.well-known/oauth-protected-resource/mcp
- Authorization server metadata: https://admachine.xyz/.well-known/oauth-authorization-server
- Human page: https://admachine.xyz/agents
- Agent kit (plugin, skill, Gemini extension): https://github.com/slashimagine/ad-machine-agents

## Server instructions

Connected agents receive these on initialize. They are reproduced here so you can plan before connecting.

Ad Machine turns product photos into finished ad campaigns: studio, lifestyle, UGC, and cinematic images in every social format, 4K upscales, 1080p videos with sound, plus Imagine, an open studio with 19 image and video models.

How to work:
1. Call get_account first. It returns the team, token balance, whether the team can claim its free 7-ad campaign, and the next step.
2. Upload every image the person gives you with upload_image (a public image link, a chat attachment, or base64) or create_upload_url (local files), and use every one: product photos all go in productImages (up to 6; replicate_ad takes one), references in their own fields (styleImage, swipeImage, characterImage, adImage), and Imagine inputs take "asset:<key>". Don't leave one out or swap in other images (earlier uploads, stock, web finds, or generated ones) unless the person asks; reuse a photo from list_assets only when they point you to it.
3. Don't use a Nucleus unless the person asks for it: leave brandBrainId out by default. When they do ask, find it with list_brand_brains.
4. Create:
   - create_free_campaign: the team's one free campaign (7 ads), when get_account says it's eligible.
   - create_campaign: all 20 styles ("full"), AI concepts ("concepts"), or chosen templates ("templates").
   - direct_campaign: an 8-shot story from a creative brief.
   - replicate_ad: recreate an existing ad (search_ad_library finds proven ones) with the person's product.
   - imagine_quote, then imagine_submit: anything else, on a specific model. With the person's images, use a mode that takes them (edit, reference, or animate) and include every one; text mode uses none.
5. Generation is asynchronous. Create tools return at once. Where the host shows the campaign board, it updates itself: don't poll. Otherwise call get_campaign with waitSeconds (up to 25) until progress.done. Never call a create tool again to "retry" a render that's still going; that charges again.
6. Show results with their links, use view_ads to look at the images yourself, and offer next steps: edit_ad, upscale_ad (4K), animate_ad (video).

Costs and consent:
- Tokens: 10 per 2K image, 20 per 4K image or upscale, 75 per second of video. Failed renders are refunded automatically.
- Quoting is free and needs no permission. Before spending, state the exact cost (estimate_cost, imagine_quote) and wait for a yes, then pass that number as maxTokens so the price can't change underneath the person. Pass one stable idempotencyKey per paid action and reuse it for retries.
- If a tool says a plan or more tokens are needed, nothing was charged; relay the next step it gives.
- Delete tools can't be undone; confirm first.

Good to know:
- Image and video links are private and expire after about an hour; fetch fresh ones with get_campaign or get_ad.
- Aspect ratios: 4:5 (default, feed), 1:1, 9:16 (Stories, Reels, TikTok), 16:9, plus 2:3, 3:2, 3:4, 4:3, 21:9.
- Every tool accepts teamId; omit it to use the default team from get_account.
- Never invent results. Describe only ads you received, and don't claim performance numbers.

## Connect

### Chat apps

#### ChatGPT

Web, desktop, mobile, and dots. **Paste a URL.**

1. In ChatGPT, open Settings → Plugins → Add.
2. Choose Create custom MCP server and paste the server URL.
3. Sign in to Ad Machine and approve.
4. Attach a product photo and ask for ads.

Your dots can use Ad Machine too, once the plugin is enabled for them.

#### Claude

claude.ai, desktop, and mobile. **One click.**

1. Click Add to Claude.
2. Check the name and URL, then click Connect.
3. Sign in to Ad Machine and approve.
4. In any chat, turn on Ad Machine from the tools menu.

[Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Ad%20Machine&connectorUrl=https%3A%2F%2Fadmachine.xyz%2Fmcp)

Team and Enterprise owners can add it for everyone in Admin settings → Connectors.

#### Grok

grok.com and Grok Bot. **Paste a URL.**

1. On grok.com, open Connectors → New connector → Custom.
2. Paste the server URL and sign in to Ad Machine.
3. For Grok Bot, create an API key in Settings → Agents and add it as the Authorization header: Bearer am_live_…

If Grok asks for a client ID, use ad-machine-connector.

#### Muse

Meta’s personal agent. **Paste a URL.**

1. In Muse, open Settings → Connectors → Add custom connector.
2. Paste the server URL and sign in to Ad Machine.
3. Ask Muse to make ads for your product.

If Muse asks for a key instead, create one in Settings → Agents.

### Coding agents

#### Claude Code

Plugin with a skill, slash commands, and a creative director. **Two commands.**

1. Run these two commands in Claude Code.
2. Run /mcp, choose ad-machine, and sign in.
3. Try /ad-campaign ./product.jpg

Plugin:

```
/plugin marketplace add slashimagine/ad-machine-agents
/plugin install ad-machine@ad-machine
```

Server only:

```
claude mcp add --transport http ad-machine https://admachine.xyz/mcp
```

#### Codex

CLI and the ChatGPT desktop app. **Two commands.**

1. Add the server.
2. Sign in when Codex opens your browser.

Terminal:

```
codex mcp add ad-machine --url https://admachine.xyz/mcp
codex mcp login ad-machine
```

config.toml:

```
[mcp_servers.ad-machine]
url = "https://admachine.xyz/mcp"
tool_timeout_sec = 120
```

#### Cursor

Agent and chat. **One click.**

1. Click Add to Cursor.
2. Approve the install, then sign in to Ad Machine.

[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=ad-machine&config=eyJ1cmwiOiJodHRwczovL2FkbWFjaGluZS54eXovbWNwIn0%3D)

#### VS Code

GitHub Copilot agent mode. **One click.**

1. Click Add to VS Code.
2. Sign in when VS Code asks.

[Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22ad-machine%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fadmachine.xyz%2Fmcp%22%7D)

#### Grok Build

xAI’s coding agent. **One command.**

1. Add the server.
2. Sign in when prompted.

Terminal:

```
grok mcp add --transport http ad-machine https://admachine.xyz/mcp
```

Grok Build also reads Claude Code plugin marketplaces: slashimagine/ad-machine-agents.

#### Gemini CLI

Extension with Ad Machine’s playbook. **One command.**

1. Install the extension.
2. Run /mcp auth ad-machine to sign in.

Terminal:

```
gemini extensions install https://github.com/slashimagine/ad-machine-agents
```

### Agents and APIs

#### Your own agent

OpenAI, Anthropic, and xAI APIs. **API key.**

1. Create an API key in Ad Machine → Settings → Agents.
2. Attach the MCP server with the key as its bearer token.

OpenAI:

```
{
  "type": "mcp",
  "server_label": "ad-machine",
  "server_url": "https://admachine.xyz/mcp",
  "authorization": "am_live_YOUR_KEY",
  "require_approval": {
    "never": {
      "read_only": true
    }
  }
}
```

Anthropic:

```
{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://admachine.xyz/mcp",
      "name": "ad-machine",
      "authorization_token": "am_live_YOUR_KEY"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "ad-machine"
    }
  ]
}
```

xAI:

```
{
  "type": "mcp",
  "server_url": "https://admachine.xyz/mcp",
  "server_label": "ad-machine",
  "authorization": "am_live_YOUR_KEY"
}
```

Add it to your request: OpenAI and xAI take it in tools; Anthropic takes mcp_servers and tools, with the mcp-client beta.

#### Any MCP client

Streamable HTTP with OAuth 2.1. **Paste a URL.**

1. Point your client at the server URL. It discovers sign-in on its own.
2. Clients that can’t sign in can send an API key instead.

mcp.json:

```
{
  "mcpServers": {
    "ad-machine": {
      "type": "http",
      "url": "https://admachine.xyz/mcp"
    }
  }
}
```

With an API key:

```
{
  "mcpServers": {
    "ad-machine": {
      "type": "http",
      "url": "https://admachine.xyz/mcp",
      "headers": {
        "Authorization": "Bearer am_live_YOUR_KEY"
      }
    }
  }
}
```

## Tools (40)

Kinds: read (no changes), create (adds work; may spend tokens), update (changes existing work), delete (can't be undone). Full input schemas come from tools/list.

### Account and catalog

- `get_account` (read): Start here. Returns who is signed in, their teams (with the default team), the plan and token balance, whether the team can still claim its free 7-ad campaign, and…
- `get_catalog` (read): Everything Ad Machine can make and what it costs: campaign styles, the 20 ad templates (ids, names, looks), Director's 8-shot story arc, aspect ratios, 2K/4K sizes,…
- `estimate_cost` (read): Exact token cost of an action before you run it, compared with the team's balance.

### Uploads and assets

- `upload_image` (create): Use this for every product photo or reference image the person shares, one call per image.
- `create_upload_url` (create): Use this to upload a local file you can read from disk (for example in Claude Code, Codex, or a script), especially if it's over 3 MB.
- `list_assets` (read): The team's asset library: every uploaded product photo and reference image, newest first, with its key, type, size, and which campaigns use it.
- `delete_asset` (delete): Permanently delete one uploaded image from the asset library.

### Nuclei

- `list_brand_brains` (read): The team's Nuclei: saved brand identity, audience, voice, guardrails, and visual style.
- `get_brand_brain` (read): Every field of one Nucleus. Read it before writing prompts, briefs, or instructions so they match the brand.
- `create_brand_brain` (create): Save a new Nucleus when the person asks for one.
- `update_brand_brain` (update): Change fields of a Nucleus. Only the fields you pass change, and each replaces the old text entirely, so include everything you want to keep in that field.
- `delete_brand_brain` (delete): Permanently delete a Nucleus. Ads already made with it are kept.

### Campaigns

- `list_campaigns` (read): The team's campaigns, newest first, with ad counts and a thumbnail.
- `get_campaign` (read): A campaign with every ad, its status (generating, ready, failed), image link, and video.
- `create_campaign` (create): Make ads from product photos (10 tokens per ad at 2K, 20 at 4K).
- `create_free_campaign` (create): The fastest way to a first result: every new team can make one free campaign of 7 ads (4:5, 2K) from its product photos, with no plan or card.
- `direct_campaign` (create): Director mode: turns a creative brief into an 8-shot story (hook to closing hero) with one consistent look.
- `replicate_ad` (create): Recreate an existing ad (a competitor's, or one from search_ad_library) with the person's product, same idea and layout; brandMatch restyles type and colors.
- `rename_campaign` (update): Change a campaign's name. Nothing else changes.
- `delete_campaign` (delete): Permanently delete a campaign with all its ads, images, and videos.

### Ads

- `get_ad` (read): One ad with its full prompt, every image version, and video.
- `view_ads` (read): Look at up to 6 finished ads as small inline images, so you can judge them, compare them, or describe them to the person before deciding what to upscale, edit, or…
- `regenerate_ad` (create): Render a fresh take on an ad from the same prompt; the old image is kept as a version.
- `edit_ad` (create): Change an ad with words and get the new image back (usually 30–90 seconds).
- `upscale_ad` (create): Upscale a finished 2K ad to 4K (3840px) for print, billboards, or high-res placements, and return the new image (usually under a minute).
- `animate_ad` (create): 5), keeping the product true to the photo.
- `delete_ads` (delete): Permanently delete ads, or single versions of them (pass imageKey from get_ad).
- `enhance_prompt` (read): Rewrite a rough ad idea into a detailed image prompt (scene, camera, light, mood) with Ad Machine's prompt writer.

### Ad library and references

- `search_ad_library` (read): Search real ads running on Meta, TikTok, and more by keyword, brand, niche, format, or platform; order longest_running finds long-running ads.
- `list_ad_library_boards` (read): The boards in the team's Foreplay swipe file, so you can search one with search_ad_library (source saved, boardId).
- `save_swipe_reference` (create): Save an ad image from the ad library (search_ad_library imageUrl) to the team's references, returning a key you can pass to direct_campaign as styleImage or swipeImage,…
- `list_swipe_references` (read): Ads the team saved to its Swipe Ads library in Ad Machine, newest first, ready to replicate.

### Imagine studio

- `imagine_list_models` (read): Imagine is Ad Machine's open studio for any image or video idea, beyond ad templates: 19 models from OpenAI, Google, ByteDance, Kling, MiniMax, xAI, Ideogram, and more.
- `imagine_get_model` (read): The full input contract for one Imagine model and mode: every field with its type, allowed values, and default; media slots and their limits; how to cite references in…
- `imagine_enhance_prompt` (read): Improve a prompt for a specific Imagine model, mode, settings and references.
- `imagine_quote` (read): Validate an Imagine input and get its exact price: `tokens` is the most it can cost (reserved up front, never exceeded) and `typicalTokens` what it usually costs.
- `imagine_submit` (create): Create an image or video with an Imagine model.
- `imagine_get` (read): An Imagine job's status and outputs. Checking also saves finished media or refunds a failed job; it never starts another paid creation.
- `imagine_list` (read): The team's recent Imagine creations, newest first, 24 per page.

### Team

- `list_team_members` (read): Who is on the team (name, email, role) and which invitations are pending.

## Example requests

- Make a full Instagram campaign from this product photo.
- Read acme-skincare.com, save their brand, and make 4 on-brand ad concepts.
- Find supplement ads that have run for months and recreate the best one with my product.
- Direct an 8-shot story for our summer launch: playful, sun-drenched, Gen Z.
- Upscale my two best ads from yesterday’s campaign to 4K.
- Turn the cinematic ad into a 6-second Reel with sound.

## FAQ

**Do I need an Ad Machine account?**
Yes. You sign in with your Ad Machine account when you connect, and work happens in your team. New teams get one free 7-ad campaign, so you can try it before choosing a plan.

**Can my assistant spend tokens without asking?**
No. Quotes are free, but before anything paid your assistant states the exact cost and waits for your yes. It passes that number as a cap, so the price can’t change after you agree. Most apps also ask you to approve each paid action.

**What does it cost?**
It uses your team’s tokens, the same as the app: 10 per 2K image, 20 per 4K image or upscale, and 75 per second of video. Imagine models are quoted exactly before each render. Failed renders are refunded automatically.

**What can a connected app see and do?**
Only what you approve on the sign-in screen: view your campaigns and assets, create ads (which uses tokens), and optionally rename and delete. You pick the team it works in. Approve view-only if you just want it to look.

**How do I disconnect an app?**
Open Ad Machine → Settings → Agents. Every connected app and API key is listed there, and you can disconnect any of them at once.

**My app isn’t listed. Will it work?**
Probably. Any app that supports remote MCP servers can connect with the server URL. If it can’t sign in, create an API key in Settings → Agents and send it as a bearer token.

**Is the campaign board in every app?**
The live board appears in apps that support MCP Apps, including Claude and ChatGPT. Everywhere else, your assistant shares links to each ad and can look at the images to help you choose.

## Support

support@admachine.xyz · https://admachine.xyz/support · https://admachine.xyz/privacy-policy · https://admachine.xyz/tos