Docs: MCP server
Connect your AI agent
Banner Buddy includes an MCP server, so an AI agent can research your audience, generate scratch-to-win banner sets and export them for you, using the same credits as the editor. Included on every plan.
What this is
MCP (Model Context Protocol) is an open standard that lets AI assistants use outside tools. Once connected, you can ask your agent something like "make a scratch-to-win banner set for my coffee shop's free latte giveaway" and it creates the campaign, runs the research, generates every state and hands you the export.
| Setting | Value |
|---|---|
| Server URL | https://www.bannerbuddy.app/api/mcp |
| Transport | Streamable HTTP |
| Auth header | Authorization: Bearer bb_... |
Use the www address exactly as shown. The bare domain redirects, and some clients drop the request on a redirect.
Get an API key
- Create a free account (25 credits, no card) or sign in.
- Open Settings, find API keys and create a key. Name it after the device or agent, for example "Cursor on my laptop".
- Copy the key right away. It starts with
bb_and is shown only once. - Treat it like a password. Anyone with the key can spend your credits. Revoke it in Settings at any time and create a new one.
Connect your client
Pick your client. Each one needs the server URL and your key; nothing else to install unless noted.
Claude Code
Close Claude Code, then run this in Terminal. It asks for your key without showing it on screen:
printf "Paste your bb_ key, then press Enter: "; read -s BBKEY; echo; claude mcp add --scope user --transport http banner-buddy https://www.bannerbuddy.app/api/mcp --header "Authorization: Bearer $BBKEY"; unset BBKEY
Check it with claude mcp list: Banner Buddy should say Connected. Then start claude. In a session, the built-in prompts create_banner_set and create_multi_format_campaign are under /.
Claude Desktop
Claude Desktop connects to remote servers through a small bridge called mcp-remote, which needs Node.js installed. Open Settings > Developer > Edit Config (or the file directly), add this, and replace bb_YOUR_KEY:
{
"mcpServers": {
"banner-buddy": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://www.bannerbuddy.app/api/mcp", "--header", "Authorization:${BB_AUTH}"],
"env": { "BB_AUTH": "Bearer bb_YOUR_KEY" }
}
}
}- Mac:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Quit and reopen Claude Desktop. Banner Buddy appears in the tools menu of a new chat.
Cursor
Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in one project:
{
"mcpServers": {
"banner-buddy": {
"url": "https://www.bannerbuddy.app/api/mcp",
"headers": { "Authorization": "Bearer ${env:BANNER_BUDDY_KEY}" }
}
}
}It reads the key from an environment variable so it never sits in a file you might commit. Set BANNER_BUDDY_KEY to your key in your shell profile, then restart Cursor. Banner Buddy shows under Settings > MCP.
VS Code (Copilot agent mode)
Run MCP: Open User Configuration from the Command Palette and add the server below. VS Code asks for the key once and stores it securely:
{
"inputs": [
{ "type": "promptString", "id": "banner-buddy-key", "description": "Banner Buddy API key (bb_...)", "password": true }
],
"servers": {
"banner-buddy": {
"type": "http",
"url": "https://www.bannerbuddy.app/api/mcp",
"headers": { "Authorization": "Bearer ${input:banner-buddy-key}" }
}
}
}If the file already has servers or inputs, add these entries to them. Start the server from the file, then use agent mode in Chat.
Any other MCP client
Most clients take a JSON entry like this. Field names vary a little (some use serverUrl or streamable-http), so check your client's docs:
{
"mcpServers": {
"banner-buddy": {
"type": "http",
"url": "https://www.bannerbuddy.app/api/mcp",
"headers": { "Authorization": "Bearer bb_YOUR_KEY" }
}
}
}A client that only supports local (stdio) servers can use the same mcp-remote bridge shown for Claude Desktop.
Tools and credit costs
One credit is one generated image. A complete set (six states plus the campaign image) is 7 credits. Everything else is free.
| Tool | What it does | Cost |
|---|---|---|
| list_formats | Ad sizes, the six banner states and the 300x300 campaign image | Free |
| list_campaigns | Your recent campaigns | Free |
| create_campaign | New campaign with brand, audience, prize and art direction | Free |
| update_campaign | Change a campaign's brief, color or logo | Free |
| run_research | Live audience research: sentiment, trends, prizes, copy | Free |
| generate_banner | One image for one state of a banner set, or the campaign image | 1 credit |
| get_campaign | Campaign details and every image link | Free |
| export_campaign | ZIP of final 2x PNGs (6 banners + campaign image) plus config.json | Free |
Prompt templates
Fill in the brackets and paste into your agent. Specific art direction is what makes the images feel like your campaign instead of generic.
One banner set (one size, 7 credits)
Build a complete Banner Buddy scratch-to-win banner set. Follow these steps exactly and do not skip any. INPUTS - Brand: [brand name] - Product / offer: [what is being promoted, concretely] - Audience: [who the ad is for] - Industry: [industry] - Prize: [exact prize, e.g. free 16oz pumpkin spice latte] - Format: Mobile Banner (320x50) - Art direction: [setting, mood, palette, props, illustration or photo style] BRAND KIT (applied to every image; the primary color is also the CTA button color) - Primary color: [hex, e.g. #C2410C] - Secondary color: [hex, e.g. #FDE68A] - Visual style: [flat-illustration | photo | 3d | minimal | hand-drawn | retro] - Mood: [3-5 words, e.g. cozy, upbeat, student-friendly] - Logo URL: none STEPS 1. create_campaign with: name, brandName, targetAudience, industry, giveaway = prize, productDescription = product, bannerDescription = art direction, and the brand kit: brandColor, secondaryColor, visualStyle, brandMood = mood. 2. run_research on the campaign. From the results choose ONE headline (2-5 words) and ONE CTA (1-3 words). Neither may contain these words: scratch, win, wins, won, winner, prize, play, reveal, lucky, jackpot. They appear on the Brand and Fallback banners, which run outside the game, and the server drops game copy there. 3. generate_banner for "scratch" in Mobile Banner (320x50) WITHOUT a creativeId. Keep the creativeId it returns. 4. generate_banner for win, lose, redeem, brand, fallback, each WITH that creativeId, at the same time (parallel tool calls if your client allows; otherwise in that order). When those are done, one more generate_banner with state "campaign" and the same creativeId: the separate 300x300 campaign image (the redeem-page picture and campaign logo; it ignores the format). 7 images in all. 5. For every generate_banner call pass: headline, cta and styleNotes (brandColor only to override the kit). styleNotes must name the concrete scene, main subject, palette and mood for that state in under 40 words, using the art direction: - scratch: the teaser: brand-world scene with the product on the left and calm space for the words - win: the prize itself, large and front and center, in a celebration moment - lose: the brand's default look with the product as hero subject, warm and upbeat; no prize, no sad imagery - redeem: the prize as hero subject in a rewarding, claim-it moment - brand: a tight premium close-up of the product on a soft warm glow; no game elements - fallback: a wider lifestyle shot of the product in its setting on a bold brand-color field, clearly different from Default; no scratch panels, coins, tickets or other game cues - campaign: the 300x300 campaign image (redeem-page picture and campaign logo): the product alone, centred like an app icon in the upper three quarters of a flat brand-color field, bottom fifth left plain for the logo; no scene, no game cues. Always square, whatever the format LAYOUT for Mobile Banner (320x50): text sits in the middle and right of the banner, so the hero goes in the LEFT third. Put that in every banner state's styleNotes, keep the hero object whole (no cropped people), and keep the text area plain background. The campaign image is square: hero centred, no layout note. 6. If a state fails, read the error, retry that state once, then report it. Never create a second banner set unless asked. 7. export_campaign for the banner set. Reply with: the ZIP link, the editor link, each state's image link, and credits used. RULES: one banner set per run. styleNotes describe the picture only, never words: the server draws each state's text on top, sized to fit (scratch: 'Win <prize>!' + Scratch Now; win: 'You Won <prize>!'; lose: brand + Try Again Next Time; redeem: 'Your <prize>' + Tap to Redeem!; brand and fallback: brand + your CTA; campaign: brand name only, and nothing when a logo is set). Long prizes are shortened automatically for thin formats (e.g. 'free 16oz pumpkin spice latte' becomes 'Free Latte').
One campaign in several sizes
Default sizes are 320x50, 728x90 and 300x250, so 21 credits. Up to 5 sizes per campaign.
Build a Banner Buddy scratch-to-win campaign with 3 complete banner sets (one per format: six banner states plus the 300x300 campaign image), 21 images total.
Use only the banner-buddy MCP tools. Follow every step in order. Do not skip, merge or reorder steps.
========================================
INPUTS
========================================
Campaign name: [campaign name]
Brand: [brand name]
Industry: [industry]
Audience: [who the ad is for: age, situation, what they care about]
Campaign goal: [what the campaign should achieve]
Product: [what is being promoted, concretely]
Prize (exact wording): [exact prize, e.g. free 16oz pumpkin spice latte]
Hero object: [the one hero object, e.g. a steaming orange latte cup]
Setting: [the setting, e.g. a cozy campus cafe in autumn]
Art direction: [setting, light, palette, props, illustration or photo style]
BRAND KIT (applies to every image; the primary color is also the CTA button color)
- brandColor: [hex, e.g. #C2410C]
- secondaryColor: [hex, e.g. #FDE68A]
- visualStyle: [flat-illustration | photo | 3d | minimal | hand-drawn | retro]
- brandMood: [3-5 words, e.g. cozy, upbeat, student-friendly]
- Logo URL: none
FORMATS (use these exact names; build them in this order)
1. "Mobile Banner" (320x50) layout: STRIP
2. "Leaderboard" (728x90) layout: STRIP
3. "Medium Rectangle" (300x250) layout: BOX
========================================
STEP 1: CAMPAIGN (free)
========================================
1a. Call list_campaigns. If a campaign named "[campaign name]" already exists, reuse its campaignId and call update_campaign
with the fields below instead of creating a new one.
1b. Otherwise call create_campaign with: name, brandName, targetAudience = Audience, industry, campaignGoal,
productDescription = Product, giveaway = Prize (exact wording), bannerDescription = Art direction,
brandColor, secondaryColor, visualStyle, brandMood. Save the campaignId.
========================================
STEP 2: RESEARCH AND COPY (free, 20-50 seconds)
========================================
2a. Call run_research on the campaignId once. Do not call it again.
2b. From the copy suggestions choose ONE headline and ONE CTA, and use the same pair for every call:
- Headline: 2 to 5 words.
- CTA: 1 to 3 words, an action (e.g. "Order Now", "Grab Yours").
- NEITHER may contain these words: scratch, win, wins, won, winner, prize, play, reveal, lucky, jackpot.
(They appear on the Brand and Fallback banners, which run outside the game; game words get dropped.)
- If no suggestion fits these rules, write your own that does.
2c. Tell me the headline and CTA you chose, then continue without waiting.
========================================
STEP 3: GENERATE (1 credit per call, 10-40 seconds each)
========================================
For EACH format in the order listed, build one full set of seven images:
3a. generate_banner with state "scratch", format = the exact format name, and NO creativeId.
Save the creativeId it returns. This is that format's banner set.
3b. generate_banner for "win", "lose", "redeem", "brand", "fallback", each WITH that creativeId
(do not pass format again). Send these five at the same time if your client allows parallel
tool calls (a set then takes about 30 seconds instead of 80); otherwise in that order.
3c. Wait for 3b to finish: the campaign image is styled after the Default (brand) banner.
3d. generate_banner with state "campaign" WITH that creativeId: the separate 300x300 campaign image
(the redeem-page picture and campaign logo). It ignores the format and is always square.
3e. Finish all seven images of one format before starting the next format.
Every generate_banner call passes: campaignId, state, headline, cta, styleNotes.
Do NOT pass prizeText or brandColor (they come from the campaign).
styleNotes: copy the text for the state AND the format's layout exactly from the tables below.
styleNotes describe the picture only. Never put words, slogans, prices or button labels in styleNotes:
the server draws all text (brand name, prize, headline, CTA button) on top of the image afterwards.
STRIP layout styleNotes (Mobile Banner, Leaderboard; text sits in the middle and right of the banner, so the hero goes in the LEFT third):
- scratch: Teaser scene in [the setting, e.g. a cozy campus cafe in autumn]. [the one hero object, e.g. a steaming orange latte cup], whole and fully in frame, in the left third. Right two-thirds: soft blurred background, plain and empty. Festive, inviting.
- win: Celebration. The prize, [the one hero object, e.g. a steaming orange latte cup], shown whole and slightly larger, in the left third, with a warm glow and a few festive accents. Right two-thirds: soft gradient, plain and empty. Joyful, rewarding.
- lose: The brand's default look in [the setting, e.g. a cozy campus cafe in autumn]. [the one hero object, e.g. a steaming orange latte cup], whole, in the left third. Right two-thirds: calm blurred background, plain and empty. Warm and upbeat; no prize, confetti or sad imagery.
- redeem: Claim-it moment. The prize, [the one hero object, e.g. a steaming orange latte cup], shown whole, in the left third, with a warm spotlight glow. Right two-thirds: plain gradient, empty. Rewarding and inviting.
- brand: Tight premium close-up of [the one hero object, e.g. a steaming orange latte cup], large, in the left third, soft warm glow and bokeh behind it. Right two-thirds: soft glow, empty. Brand-forward; no game elements.
- fallback: Wider lifestyle shot: camera pulled back to show [the one hero object, e.g. a steaming orange latte cup] in [the setting, e.g. a cozy campus cafe in autumn], smaller in frame, in the left third, on a bold brand-color field. Right two-thirds: flat brand color, empty. Must look clearly different from Default. No scratch panels, coins, tickets, confetti or game cues.
BOX layout styleNotes (Medium Rectangle; text sits in a band along the bottom, so the hero goes in the UPPER half):
- scratch: Teaser scene in [the setting, e.g. a cozy campus cafe in autumn]. [the one hero object, e.g. a steaming orange latte cup], whole and fully in frame, in the upper half, centered. Lower half: soft blurred background, plain and empty. Festive, inviting.
- win: Celebration. The prize, [the one hero object, e.g. a steaming orange latte cup], shown whole and slightly larger, in the upper half, centered, with a warm glow and a few festive accents. Lower half: soft gradient, plain and empty. Joyful, rewarding.
- lose: The brand's default look in [the setting, e.g. a cozy campus cafe in autumn]. [the one hero object, e.g. a steaming orange latte cup], whole, in the upper half, centered. Lower half: calm blurred background, plain and empty. Warm and upbeat; no prize, confetti or sad imagery.
- redeem: Claim-it moment. The prize, [the one hero object, e.g. a steaming orange latte cup], shown whole, in the upper half, centered, with a warm spotlight glow. Lower half: plain gradient, empty. Rewarding and inviting.
- brand: Tight premium close-up of [the one hero object, e.g. a steaming orange latte cup], large, in the upper half, centered, soft warm glow and bokeh behind it. Lower half: soft glow, empty. Brand-forward; no game elements.
- fallback: Wider lifestyle shot: camera pulled back to show [the one hero object, e.g. a steaming orange latte cup] in [the setting, e.g. a cozy campus cafe in autumn], smaller in frame, in the upper half, centered, on a bold brand-color field. Lower half: flat brand color, empty. Must look clearly different from Default. No scratch panels, coins, tickets, confetti or game cues.
CAMPAIGN IMAGE styleNotes (every format, always 300x300):
- campaign: App-icon style tile. [the one hero object, e.g. a steaming orange latte cup] alone, whole and large, centred left-to-right in the upper three quarters of a flat brand-color field with a soft glow behind it; the bottom fifth is plain flat background only (the logo goes there). No scene, props, people or game cues. Must read as a small thumbnail.
========================================
STEP 4: ERRORS
========================================
- If a call fails, read the error and retry that SAME state once with the same inputs.
- If it fails a second time, record the state, format and error message, then continue with the next state.
- If "scratch" fails twice for a format, skip that whole format (there is no creativeId to add to) and move on.
- Never start a second banner set for a format that already has one. Never re-run completed states.
- If an error mentions credits or the API key, stop and tell me.
========================================
STEP 5: VERIFY (free)
========================================
Call get_campaign on the campaignId. Confirm each of the 3 banner sets has an image for all six banner states AND a campaignImage.
If any state is missing and was not already retried twice, generate it now (same creativeId, same inputs).
========================================
STEP 6: EXPORT (free)
========================================
Call export_campaign with the campaignId and NO creativeId (exports every set, one ZIP each).
========================================
STEP 7: REPORT
========================================
Reply with:
1. Headline and CTA used.
2. A table: Format | Size | ZIP link | Images done (x/7, campaign image included) | Failed states and errors
3. Every image link, grouped by format, in state order (scratch, win, lose, redeem, brand, fallback, campaign).
4. The editor link.
5. Credits used (expected 21) and credits left.What goes on each banner
The image model paints art only. The server draws the words afterwards, sized to fit every format:
| State | Headline | Button |
|---|---|---|
| Scratch | Win <prize>! | Scratch Now |
| Win | You Won <prize>! | (prize in a button if the line is too long) |
| Lose | Brand name | Try Again Next Time |
| Redeem | Your <prize> | Tap to Redeem! |
| Brand | Brand name | Your CTA |
| Fallback | Your headline (or brand name without a logo) | Visit Us |
| Campaign Image | Brand name (nothing with a logo) | None: a logo tile, not an ad |
Long prizes are shortened on small sizes ("free 16oz pumpkin spice latte" becomes "Free Latte"). Keep headlines and CTAs free of game words (scratch, win, wins, won, winner, prize, play, reveal, lucky, jackpot); the Brand and Fallback states run outside the game and drop them.
Tips for better banners
- Be concrete in the art direction: setting, time of day, palette, props, and illustration or photo style.
- Name one hero object (the product or prize). On thin strips, skip people: faces get cropped.
- Match the layout: on wide strips the hero goes in the left third; on rectangles in the upper half.
- No words in the art direction: prices and button labels are drawn by the server.
- Run research first so the prize wording and copy match the audience.
- Generate scratch first, then pass its creativeId for the other five states, then once more for the campaign image.
Troubleshooting
- 401 or "Invalid or revoked API key": the key is wrong or was revoked. Create a new key and update your client.
- "Missing or malformed API key": the header must be exactly
Authorization: Bearer bb_.... - Out of credits: generate_banner stops when your balance is empty. Add credits in Plan & billing.
- Too many requests: agents are rate-limited to protect your credits. Wait a few minutes and retry.
- Claude Desktop shows no tools: check that Node.js is installed, the JSON is valid, and you fully quit and reopened the app.
- Claude Code change disappeared: it was open while you edited. Close it, run the command again, then start it.
- "Failed to generate": the message ends with the image model's reason. Retry once; if it repeats, send us the message.
Still stuck? Email contact@skratchads.com with your client name and Account ID (Settings > Account). Never send your API key.