Connect to AI agents
Wire AdCrunch into Claude, Cursor, and ChatGPT via the MCP server. Tool reference and recipes.
On this page
Overview
- What is MCPHow the Model Context Protocol lets AI agents query AdCrunch in natural language.
- Bring your own creativeUpload images and video you own, then register them into an advertiser's provider-side library — from your AI agent, over MCP.
- Plan a campaignWrite down what you intend to run — channels, budgets, targeting, dates — as a structured Campaign Plan your agent can sum, approve, execute and record against.
Auth & scopes
Recipes
- Top campaigns yesterdayA one-line prompt to surface the best-spending campaigns of the previous day.
- Meta vs TikTok ROASSide-by-side ROAS comparison across two providers for the same window.
- Drill into one ad groupFind the underperforming creative inside a campaign.
- Save and run a SkillTeach the agent a workflow once, save it as a Skill, then run it by name on any future session.
- Upload and register a creativeHand the agent a file, and it uploads it, adds it to your library, and places it in an ad account — end to end.
Set up your AI client
- Claude DesktopInstall the AdCrunch MCP server in Claude Desktop and authorize your organization.
- Claude CodeInstall the AdCrunch MCP server in Claude Code and authorize your organization.
- CursorInstall the AdCrunch MCP server in Cursor and authorize your organization.
- ChatGPTInstall AdCrunch as a custom MCP connector in ChatGPT.
Tool reference
- list_advertisersList the advertisers (ad accounts) in your organization, optionally filtered by provider.
- list_entitiesList ad entities (campaigns, ad sets, ad groups, ads, creatives, …) under one advertiser, filtered by type or parent.
- get_entityFetch the full raw provider payload for one ad entity by provider, type, and id.
- query_insightsAggregate spend / impressions / clicks / conversions over a date range, by entity.
- meta_list_pagesList the Facebook Pages a Meta ad account can advertise from.
- meta_list_pixelsList the Meta Pixels installed on a Meta ad account.
- meta_create_campaignCreate a Meta campaign from a conversation. It always arrives PAUSED.
- meta_create_adsetCreate a Meta ad set under a campaign — budget, audience, and optimization goal.
- meta_create_creativeBuild a Meta ad creative from media you uploaded to AdCrunch. Image and video both work.
- meta_create_adCreate a Meta ad under an ad set, using a creative that already exists. Always paused.
- meta_set_statusPause, resume or archive a Meta campaign, ad set or ad on a live account. Runs asynchronously and returns a workflowId to poll.
- meta_update_budgetChange a Meta campaign or ad set's daily or lifetime budget, with a safety cap and a level guardrail.
- get_mutation_statusPoll a change started by a write tool and find out whether it succeeded, failed, or is still running.
- skill_listList your organization's ad-ops playbooks (Skills) by slug, name, and description.
- skill_getFetch one ad-ops playbook (Skill) by slug, including its full instructions and current revision.
- skill_createCreate a new ad-ops playbook (Skill) in your organization from an agent session.
- skill_updateUpdate an ad-ops playbook (Skill), guarded by base_revision so concurrent edits aren't clobbered.
- skill_deleteDelete an ad-ops playbook (Skill), guarded by base_revision.
- asset_listList the source media (images and video) your organization owns, each with where it has been registered.
- asset_getFetch one Asset with its Registrations — where it has been placed, and how each placement went. Also how you poll a running registration.
- asset_create_uploadReserve an Asset and get a short-lived URL to upload the file to. Step one of bringing your own creative in.
- asset_finalizeComplete an upload after the bytes have been PUT, validate the file, and add the Asset to your library — optionally registering it in the same call.
- asset_registerPlace an Asset in one advertiser's provider-side library so ads in that account can use it. Returns immediately; poll asset_get for readiness.
- brand_listList your organization's brands as slug + name + description, so an agent can pick one before loading its context.
- brand_getFetch one brand by slug — its identity, voice, guidelines, messaging and personas — so an agent knows who it is acting for.
- brand_resolveGiven an ad account, find which brands' context applies to it.
- brand_createCreate a brand in your organization. Every context section is optional — start with a name and fill it in over time.
- brand_updateEdit a brand's context, guarded by base_revision so a concurrent change can't be silently overwritten.
- brand_attach_advertiserAttach an ad account to a brand, so agents can resolve brand context from the account.
- brand_detach_advertiserRemove the link between an ad account and a brand, leaving the brand and its context untouched.
- brand_deleteDelete a brand and the context authored on it, guarded by base_revision.
- persona_getFetch one of a brand's personas — who it is talking to, in their own words — so an agent can write for someone in particular.
- document_create_uploadReserve a file against a brand and get a short-lived URL to upload the bytes to.
- persona_createAdd an audience archetype to a brand — who it is talking to — with as much or as little written up front as you have.
- persona_updateEdit a persona's sections, age range or handle, guarded against overwriting someone else's concurrent change.
- document_finalizeComplete a document upload once the bytes have landed — size and type are read from the stored file, not from what you declared.
- persona_deleteRemove a persona from a brand, guarded against deleting something someone else has since edited.
- document_getFetch one brand document — images come back as an image the assistant can actually look at.
- document_listList the files attached to a brand, each with a URL you can fetch.
- document_deleteDelete a file attached to a brand, along with its stored bytes.
- campaign_plan_listList the campaign plans in your organization, with the money figures you would rank them by.
- campaign_plan_getFetch one campaign plan with its line items in full, the money figures, and whatever each line has already created.
- campaign_plan_createWrite down what you intend to run — on which channels, for whom, for how much, over what period.
- campaign_plan_updateEdit a campaign plan. Any real change returns an approved plan to draft.
- campaign_plan_deleteDelete a campaign plan and its line items. What they already created is kept.
- campaign_plan_approveApprove a plan, validating every draft line on it and opening the execution gate.
- line_item_createAdd a row to a campaign plan: one thing being bought, with the envelope of an intent.
- line_item_updateEdit a line item. Any real change returns it to draft, and only it.
- line_item_deleteRemove a line item from a plan. What it already created is kept.
- line_item_validateValidate one line item, which is what lets it be executed.
- line_item_record_executionRecord one provider object a line item created, so the plan knows what came from where.