Use Adligator from an AI agent (MCP + Skill)

Adligator ships a remote MCP (Model Context Protocol) server, so any MCP client — Claude, or your own agent — can search Meta's Ad Library on your behalf. This guide connects the server and adds the companion Skill that teaches the agent to use it like an experienced media buyer instead of a first-timer.

Step 1 — get an API key

Open the Developer portal and create an API key (API access is included on eligible plans). The same key authenticates both the REST API and the MCP server.

Step 2 — connect the MCP server

The server runs in stateless Streamable HTTP mode at:

POST https://<your-adligator-host>/api/v1/mcp

Authenticate every request with either an Authorization: Bearer <token> header or X-API-Key: <your key>. Point your MCP client at that URL. Once connected, the agent sees the research toolset:

• search_ads — filter Meta's Ad Library, returns a paginated list of ads.
• search_ads_data — the same search without the visual gallery, for when the results are an intermediate step rather than something to browse.
• search_fb_pages — resolve a brand name to candidate Facebook pages, with ad counts and likes. The right first call whenever the user names an advertiser.
• get_ad_details — full info for one ad, including media descriptors.
• get_ad_download_url — the highest-resolution original file for a media item.
• find_related_brand_pages — given a confirmed page, the other pages the same brand advertises from (white-label, creator and sister-product pages).
• find_partnership_pages — the creators and influencer pages a brand runs partnership ads with. The API-side twin of the Partnerships tab.

They are meant to be chained: resolve the page → search → details → download.

Step 3 — add the adligator-ad-research Skill

Tools alone don't tell the agent how to search. The Skill does. It is a small, portable SKILL.md (plus two reference files) that encodes the same lessons as this Academy — in a form the model reads automatically:

• The keyword rule — search Plinko not iGaming, meet singles not Dating. (See find the right keywords.)
• The filter enum codes — the MCP expects displayFormat: "VIDEO" and buttonTypes: ["SHOP_NOW"], not the friendly labels in the web app. (See the filter reference.)
• Page resolution before page filtering — big brands run several pages, so the Skill resolves the name first rather than guessing an id.
• Tool chaining, recipes, and zero-result troubleshooting.

Install it the way your client loads Skills (for Claude, place the adligator-ad-research/ folder in your Skills directory). The agent loads it automatically when a request is about researching Meta ads.

Step 4 — ask in plain language

With both connected, natural requests just work:

"Find German video ads for weighted blankets that have been running 30+ days, then show me the top creative."

The Skill steers the agent to put the copy phrase in body, set countries: ["DE"], displayFormat: "VIDEO", fromActiveDays: 30, sort by longevity, then call get_ad_details on the best result.

What's next

• How to find the right keywords — the single most important habit, and the one the Skill enforces.
• Every filter explained — the human-label version of the enum codes the agent uses.
• Find long-running winners — the filter combination behind the "proven winners" recipe.