Mockingbird MCP server

Mockingbird exposes its ad library and remake pipeline as a hosted Model Context Protocol (MCP) server, so an AI assistant or agent can find winning Meta ads and remake them in a user's brand from a conversation. This page is the technical reference. For the three-step setup in Claude, see Connect Claude.

Endpoint

Transport: MCP Streamable HTTP (JSON-RPC 2.0 over HTTPS, POST for requests, GET for the optional event stream, DELETE to end a session). The server is stateless: every request is authenticated on its own and no session has to be kept between calls. Server name mockingbird, version 1.0.0.

Header-authenticated endpoint (recommended for connectors and agents): https://www.mockingbirdhouse.com/api/mcp
Path-authenticated endpoint (for clients with no header field, such as the claude.ai custom connector form): https://www.mockingbirdhouse.com/api/mcp/{key}

Both serve the same server and accept the same key. Hosted on Vercel; tool calls return in a few seconds, and the remake itself runs in a background pipeline that the status tool reports on.

Authentication

OAuth 2.1 (recommended, and what Claude and ChatGPT use). The MCP endpoint is an OAuth 2.1 resource server and Mockingbird is its authorization server. Discovery follows the MCP authorization spec: an unauthenticated request gets HTTP 401 with a WWW-Authenticate header pointing at https://www.mockingbirdhouse.com/.well-known/oauth-protected-resource, which names the authorization server; its metadata is at https://www.mockingbirdhouse.com/.well-known/oauth-authorization-server.

Dynamic client registration (RFC 7591) at /oauth/register; public clients only.
Authorization code flow with PKCE S256 at /oauth/authorize. The user signs in to Mockingbird and approves the app on a consent page.
Tokens from /oauth/token: access tokens last 1 hour, refresh tokens 30 days and rotate on every use. Revoke at /oauth/revoke.
Scope mcp. Tokens are bound to the resource https://www.mockingbirdhouse.com/api/mcp (RFC 8707) and rejected anywhere else.

Personal API key (for clients without OAuth). Per-user API key. A user signs in to Mockingbird, opens /integrations (Connect in the app menu), and presses Generate connector URL. The key has the form mb_ followed by 48 hex characters. It is stored hashed (SHA-256), one active key per account, and can be regenerated or revoked at any time from the same page.

Header: Authorization: Bearer mb_... (or X-API-Key: mb_...) against https://www.mockingbirdhouse.com/api/mcp
Path: the key as the last path segment of https://www.mockingbirdhouse.com/api/mcp/{key}

A missing, malformed or revoked key returns HTTP 401 with a JSON errormessage. There is no OAuth flow: the key is the credential, and it identifies exactly one user, so every tool acts on that user's own brand, credits and remakes only.

Tools

Ten tools, discoverable with the standard tools/list request. Inputs are validated with JSON Schema; every tool returns a single text content block containing JSON.

search_library

Search the hand-curated library of winning Meta ads.

Input:: query (string, max 120, optional): free text over advertiser name and ad copy. industry (string, optional): exact industry filter; call once without it to see the valid values. limit (integer 1 to 20, default 8).
Returns:: A list of ads with library_ad_id, advertiser, industry, hook type and remakeability score, plus the list of valid industry filters.
Effect:: Read only. No credit is spent.

remake_ad

Queue a remake of a library ad in the user's brand voice, colours and real product photos.

Input:: library_ad_id (uuid, required): from search_library. notes (string, max 1000, optional): creative direction such as 'lead with the discount'. brand (string, optional): a brand name or brand_id from list_brands; pass it whenever the account has more than one brand, otherwise the default brand is used. sizes (array of "4:5", "1:1", "9:16", optional, default ["4:5"]): any one, two or all three.
Returns:: job_id to poll with get_remake_status, the brand it will be made for, the sizes, the credits spent and a short message.
Effect:: Spends one credit per size from the user's plan. The first size runs in under 60 seconds; extra sizes are made from it, so they keep the same copy and product, and take about a minute more. Failed jobs and failed sizes do not spend a credit.

make_ads

Make 1 to 10 brand-new ads from scratch for a brand, with no source ad.

Input:: count (integer 1 to 10, default 4). notes (string, max 1000, optional): an offer, audience, product to feature or claim to avoid, treated as brand data. brand (string, optional): brand name or brand_id; required in practice when the account has several brands. sizes (same as remake_ad, default ["4:5"]).
Returns:: batch_id, the brand, and one queued job per ad (job_id) to follow with list_my_remakes or get_remake_status. Concepts are distinct in angle, pattern and layout.
Effect:: Spends one credit per size of each ad (3 ads in 2 sizes is 6), checked for the whole batch up front. Allow 1 to 3 minutes, plus about a minute for extra sizes. Failed ads and failed sizes do not spend a credit.

get_remake_status

Poll a remake job.

Input:: job_id (uuid, required): from remake_ad.
Returns:: The current pipeline step while generating; when finished, one PNG per size in finished_ads (4:5 at 1080x1350, 1:1 at 1080x1080, 9:16 at 1080x1920) ready to download and upload to Meta. A size that failed is listed in sizes_failed.
Effect:: Read only.

list_my_remakes

The user's most recent remakes, newest first.

Input:: limit (integer 1 to 20, default 5).
Returns:: Recent remakes with status and finished image URLs where available.
Effect:: Read only.

list_brands

Every brand on the user's account, so a remake can target the right one.

Input:: None.
Returns:: brands (brand_id, name, website, is_default) and default_brand_id.
Effect:: Read only.

get_account

The user's plan, credits used and remaining this period, and their brands.

Input:: None.
Returns:: plan, ads used, ads remaining, period end, the default brand and the full brand list.
Effect:: Read only.

heart_ad

Heart or unheart a library ad, the same list as the heart button in the web app.

Input:: library_ad_id (uuid, required). hearted (boolean, required).
Returns:: library_ad_id and the resulting hearted state.
Effect:: Writes to the user's hearts. No credit is spent.

upload_ad

Open an upload widget so the user can drop their own or a competitor's ad to remake.

Input:: None.
Returns:: A 15-minute upload_url the widget posts the image to, accepted types and size limit, and the user's brands. The uploaded ad is analysed and filed privately to the account with a library_ad_id for remake_ad.
Effect:: Writes a private library ad. No credit is spent until remake_ad is called.

upgrade_plan

Prepare an upgrade link when the user is out of ads or wants more.

Input:: to_plan (one of starter, pro, elite; optional): omit to offer the next sensible step.
Returns:: current_plan, target_plan, monthly_price_usd, ads_per_month, what_happens and an upgrade_url for the user to open and confirm.
Effect:: Never charges anything itself. The user must open the link and confirm; only then is the card already on their account charged.

Typical flow: search_library, then remake_ad with a chosen id, then poll get_remake_status until the image URLs arrive.

Access requirements, credits and limits

A Mockingbird account with a brand set up (website, colours, product photos) and an active plan. Every plan includes MCP access. Accounts with no subscription, a lapsed subscription or a declined card get a clear error from remake_ad and can still read.
Remakes spend the same monthly ad credits as the web app, one per size: Starter 30, Pro 100, Elite 300 ads a month.
Rate limit: 60 remake_ad calls per user per hour, with a short window that de-duplicates identical repeat calls. Read tools are not credit-metered.
Scope: the library returns only approved, curated ads plus the user's own uploads, never another user's private uploads. Status and list tools return the calling user's jobs only.
No regional restrictions. English interface; ad copy follows the user's own brand voice.
The server never deletes data, never posts to Meta, and never charges a card. Publishing an ad is done by the user in Meta Ads Manager with the downloaded file.

Errors

Transport-level failures use HTTP status codes (401 for key problems). Tool-level failures return a normal MCP result with isError: true and a JSON body { "error": "..." } written for the user, for example out of credits, no brand set up, unknown library ad, or a rate limit.

Data handling and support

Tool inputs (search text, optional creative notes) and outputs (ad metadata, image URLs) are processed to fulfil the request and stored with the user's remakes in their account. See the Privacy Policy and Terms of Service. Support: hello@mockingbirdhouse.com.