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

Per-user API key. A user signs in to Mockingbird, opens Account, 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

Six 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'.
Returns:: job_id to poll with get_remake_status, and a short message.
Effect:: Spends one ad credit from the user's plan. Runs in under 60 seconds. Failed jobs 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, the final ad image URLs (4:5 portrait PNG) ready to download and upload to Meta.
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.

get_account

The user's plan, credits used and remaining this period, and active brand.

Input:: None.
Returns:: plan, ads used, ads remaining, period end, brand name.
Effect:: Read only.

upgrade_plan

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

Input:: to_plan (one of hatchling, nestling, flock, aviary; 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 or free trial. 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: Hatchling 30, Nestling 100, Flock 500, Aviary 2000 ads a month. The free trial includes three ads.
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.