Gentic Meta — Documentation
Connect any AI agent to manage Meta advertising campaigns, ad sets, creatives, and performance reporting through the Meta Graph API — create campaigns, upload media, launch ads, and export reports — all through the Model Context Protocol.
1. Getting Started
Sign Up & Get Your API Key
Before you can use Gentic Meta, you need an API key to authenticate your requests.
- Go to gentic.co/meta and create an account.
- Create an organization from your dashboard. API keys and billing are scoped to the organization.
- Generate an API key and use it as a Bearer token in your MCP client.
2. Connecting to the MCP Server
The server is available at https://mcp.gentic.co/meta. For Claude Code:
claude mcp add gentic-meta \
--transport http \
https://mcp.gentic.co/meta \
--header "Authorization: Bearer YOUR_API_KEY"For Claude Web and ChatGPT you can also connect via OAuth — no API key needed. See the connect section on the landing page for other MCP clients (n8n, OpenClaw).
3. Agent Skill
For the best results, pair the MCP server with the Gentic Meta agent skill. The MCP server gives your agent tool access; the skill teaches it the optimal workflow order. Both the raw SKILL.md and a ready-to-upload .skill bundle are generated on demand from the live manifest, so they always reflect the current tools and pricing.
Add the skill directly via URL:
https://gentic.co/meta/SKILL.mdOr upload a .skill bundle to Claude Managed Agents:
https://gentic.co/meta/gentic-meta.skillDownload this file and upload it wherever Claude Managed Agents asks for a .skill file. It's a zip bundle generated on demand from the latest SKILL.md.
4. Tool Reference
18 tools, rendered live from the Gentic MCP manifest. Parameter tables come directly from each tool's JSON Schema.
create_meta_ad
Create a new Meta video ad. All Advantage+ creative enhancements are automatically disabled. IMPORTANT: All IDs (adset_id, page_id, video_id) MUST be quoted strings, NEVER bare numbers.
This tool takes no parameters.
create_meta_adset
Create a new Meta ad set within a campaign. Define targeting, budget, optimization, and scheduling. IMPORTANT: All IDs (campaign_id, ad_account_id, bid_amount, daily_budget) MUST be quoted strings, NEVER bare numbers.
This tool takes no parameters.
create_meta_campaign
Create a new Meta advertising campaign. Defaults to PAUSED status and OUTCOME_SALES objective. IMPORTANT: All IDs (ad_account_id, daily_budget) MUST be quoted strings, NEVER bare numbers.
This tool takes no parameters.
create_meta_image_ad
Create a new Meta static image ad. Provide image_hash (from upload_meta_image) or image_url. All Advantage+ enhancements are disabled. IMPORTANT: All IDs (adset_id, page_id) MUST be quoted strings, NEVER bare numbers.
This tool takes no parameters.
create_meta_partnership_ad
Create a Partnership Ad from a creator's Instagram post: builds the ad creative and the ad, into an ad set you already have. The post must be AD_READY. Pass `ad_eligibility` and `permission_status` from the list_meta_creator_advertisable_media row you picked (its `partnership_info`) and the check costs nothing; otherwise this reads that one post from Meta first. A post that is not ad-ready, or a creator who has not approved, is refused before anything is created. Meta's own answer is final for everything else. Defaults to PAUSED so nothing spends until you review it.
This tool takes no parameters.
export_meta_report
Export Meta ad performance data as a downloadable CSV. Uses Meta's Async Report API to handle large datasets. Supports campaign, adset, and ad level reports. Returns a download link (expires in 1 hour). IMPORTANT: campaign_id MUST be a quoted string.
This tool takes no parameters.
fetch_meta_ad_creatives
Get ad creative details including copy, images, videos, and call-to-action from the Meta Graph API. IMPORTANT: All IDs MUST be quoted strings, NEVER bare numbers.
This tool takes no parameters.
fetch_meta_insights
Get Meta ad performance insights for campaigns, ad sets, or ads. Supports date filtering, custom fields, and breakdowns. IMPORTANT: All IDs MUST be quoted strings (e.g. ids: "120239005302490769"), NEVER bare numbers — JavaScript rounds large integers.
This tool takes no parameters.
get_ad_history
Read the org's ad mutation log. Returns one row per past ad-platform mutation (campaigns/ad sets/ads/keywords created, or status/bid/budget changed, or images/videos uploaded) across Google Ads and Meta. Use this to learn what's already been built for the brand before proposing new ads. Filters by platform, entity_type, account_id, tool_name, and timestamp range. Newest first; default limit 50, max 500.
| Parameter | Type | Description |
|---|---|---|
platform | string | — enum: google_ads, meta |
entity_type | string | — enum: campaign, ad_group, adset, ad, keyword, negative_keyword, budget, image, video |
account_id | string | — |
tool_name | string | — |
since | string | — |
until | string | — |
limit | integer | — 1 – 500 |
get_ad_performance_trends
Read the org's accumulated ad performance snapshots across Google Ads and Meta. Each row is a (campaign|ad_group|adset|ad|keyword|search_term) × date_range fact: impressions, clicks, spend (micros), conversions, ctr, cpc, cpm, plus platform-specific extras. Use this to see how ads have performed over time and surface patterns the live API view alone can't (week-over-week deltas, multi-platform comparisons). Spend/cpc/cpm are in MICROS — divide by 1,000,000 for dollars. Filters by platform, account, entity, and date range. Default limit 200, max 2000.
| Parameter | Type | Description |
|---|---|---|
platform | string | — enum: google_ads, meta |
account_id | string | — |
entity_type | string | — enum: campaign, ad_group, adset, ad, keyword, search_term |
entity_id | string | — |
since | string | — |
until | string | — |
limit | integer | — 1 – 2000 |
get_meta_connected_account
Show which Facebook Page and Instagram Business account this organization has connected — Page name, Instagram username, profile picture and follower count — plus the connected user's ROLES that gate Partnership Ads: `page_tasks` on the Page, the owning `business` and their `business_role` in it. When the Page role is too narrow to advertise from (e.g. only CREATE_CONTENT), `page_role_note` says so: Meta then returns EMPTY content-discovery results instead of an error. Use this first when Partnership Ads tools return nothing. FREE.
This tool takes no parameters.
get_meta_ids
Get Meta Ad IDs hierarchically. Start with level="adaccounts" to discover accounts, then drill down: campaigns → adsets → ads → adcreatives. IMPORTANT: All IDs MUST be passed as quoted strings (e.g. "120239005302490769"), NEVER as bare numbers — JavaScript rounds large integers and the call will fail silently with a wrong ID.
This tool takes no parameters.
get_meta_pages
Get list of Facebook Pages associated with the authenticated user. Returns page IDs needed for creating ads.
This tool takes no parameters.
list_meta_creator_advertisable_media
List Instagram posts you can build a Partnership Ad from — a creator's posts once they have approved your permission request, or specific posts you name by `permalinks` (post URLs) or `ad_codes` (the partnership ad code a creator shares). Give `creator_username` (or `creator_ig_id`), and/or `permalinks` / `ad_codes`. EVERY post Meta returns is listed, including ones you CANNOT advertise yet — each carries `has_permission_for_partnership_ad` and, when it is not ad-ready, Meta's `ad_eligibility` verbatim as `ineligible_reason`. `usable_count` is the number actually available. Pass a post's `media_id` to create_meta_partnership_ad. An EMPTY list can mean the connected user's Page role is too narrow (Meta returns nothing rather than an error); when that is detected, `page_role_note` says so. FREE.
This tool takes no parameters.
list_meta_creator_permissions
List the Instagram creators who have been asked for Partnership Ads permission, and where each one stands, ONE PAGE AT A TIME: a brand can have thousands. Each row has `permission_status` exactly as Meta and the creator's Instagram app word it ("Approved", "Pending Approval", "Revoked"), plus `status` normalised to APPROVED / PENDING / REVOKED for filtering, and the creator's `creator_ig_id` and `permission_url`. Returns up to `limit` rows (default 10, max 100; each 10 rows is one call to Meta, so ask for what you need); pass the returned `next_cursor` back as `cursor` for the next page — `next_cursor: null` means the list is complete. With `status` set, rows are filtered as pages are read, so a page may hold fewer rows than `limit` while `next_cursor` is still set. To check ONE creator, use request_meta_creator_permission or create_meta_partnership_ad, which look the creator up directly. FREE.
This tool takes no parameters.
request_meta_creator_permission
Ask an Instagram creator for permission to run Partnership Ads (branded-content ads) using their posts. The creator receives the request in the Instagram app and approves it there — this call only SENDS it, and their status stays PENDING until they tap approve. One quick check runs first: a creator Meta confirms is already pending or approved is returned as-is WITHOUT re-sending. Meta cannot always confirm this; then the request is sent and `precheck: "unverified"` says so. Check list_meta_creator_permissions before asking the same creator twice. FREE.
This tool takes no parameters.
upload_meta_image
Upload an image to a Meta ad account for use in static image ads. Provide a public URL — we download the bytes and upload them to Meta as multipart form data.
| Parameter | Type | Description |
|---|---|---|
ad_account_idrequired | string | Ad account ID |
image_urlrequired | string | Public URL of the image (e.g. AWS S3 pre-signed URL) |
namerequired | string | Name/description for the image |
upload_meta_video
Upload a video to a Meta ad account for use in ads.
| Parameter | Type | Description |
|---|---|---|
ad_account_idrequired | string | Ad account ID |
file_urlrequired | string | Public URL of the video file |
namerequired | string | Name/description for the video |
5. Pricing
Pricing is pulled live from the Gentic MCP manifest. All prices are per call and deducted from your Gentic credits.
| Tool | Cost |
|---|---|
| create_meta_ad | 100¢ / call |
| create_meta_adset | Free |
| create_meta_campaign | Free |
| create_meta_image_ad | 100¢ / call |
| create_meta_partnership_ad | 100¢ / call |
| export_meta_report | 100¢ / call |
| fetch_meta_ad_creatives | 5¢ / call |
| fetch_meta_insights | 10¢ / call |
| get_ad_history | Free |
| get_ad_performance_trends | Free |
| get_meta_connected_account | Free |
| get_meta_ids | Free |
| get_meta_pages | Free |
| list_meta_creator_advertisable_media | Free |
| list_meta_creator_permissions | Free |
| request_meta_creator_permission | Free |
| upload_meta_image | Free |
| upload_meta_video | Free |
6. Notes
- **All IDs must be quoted strings.** JavaScript rounds large integers and causes silent mis-targeting — never pass a bare number for ad account / campaign / ad set / ad / creative IDs.
- `fetch_meta_insights` is 10¢/call. `fetch_meta_ad_creatives` is 5¢/call. `create_meta_ad`, `create_meta_image_ad`, and `export_meta_report` are **$1/call** — surface the cost before running.
- All campaigns, ad sets, and ads are created in `PAUSED` status by default. The user must manually activate them.
- Budgets are specified in **cents as quoted strings** (`"500000"` = $5,000).
- Advantage+ creative enhancements are automatically disabled when creating ads, for full creative control.
- Export report download links expire in **1 hour**. Meta Graph API v23.0.
- All tools are organization-scoped — users only see their own ad accounts.
7. When to Apply
- User wants to view, analyze, or compare Meta ad performance (spend, clicks, conversions, CTR, CPA).
- User wants to create Meta campaigns, ad sets, or ads — including video ads, image ads, and creative uploads.
- User wants to upload images or videos to an ad account from a public URL.
- User wants to export ad performance reports as CSV.
- User wants to browse their Meta ad account hierarchy (accounts → campaigns → ad sets → ads → creatives).
- User asks about their Facebook or Instagram ads, or needs their Facebook Page ID for ad creation.
8. Workflow
1. Start at the top of the hierarchy with `get_meta_ids`
Navigate top-down: `level: "adaccounts"` → `"campaigns"` (with `parent_id: "act_XXXXXX"`) → `"adsets"` → `"ads"` → `"adcreatives"`. Pass `date_preset` (e.g. `"last_30d"`) or `time_range` to include spend/performance inline. **Critical**: all IDs must be passed as **quoted strings** — JavaScript rounds large integers and causes silent mis-targeting. Never pass a bare number.
2. Pull insights with `fetch_meta_insights` (10¢/call)
Key params: `level` (`campaign`/`adset`/`ad`), `ids` as a comma-separated quoted string, and either `date_preset` OR `time_range` (never both). Add `breakdowns` like `"age,gender"` or `"platform_position"` when the user asks to slice. Default `fields` cover impressions, spend, clicks, CTR, actions, conversions, action_values — only override when the user needs something specific. Mention the 10¢ cost before running many insight calls.
3. Create campaigns in PAUSED state
`create_meta_campaign` defaults to `status: PAUSED` and `objective: OUTCOME_SALES`. Never un-pause automatically — always leave that to the user. Key knobs: objective (sales/traffic/awareness/engagement/leads/app), `is_campaign_budget_optimization` + `daily_budget` for CBO, bid strategy (`LOWEST_COST_WITHOUT_CAP` / `LOWEST_COST_WITH_BID_CAP` / `COST_CAP`), and `special_ad_categories` if the vertical requires it (credit, employment, housing, issues). **Budgets are in cents as quoted strings** — `"270000"` = $2,700.
4. Ad sets inherit or override budget
`create_meta_adset` is where targeting lives. `targeting` is a JSON object with `geo_locations`, `age_min`, `age_max`, `interests`, etc. If the parent campaign has CBO enabled, don't pass `daily_budget` on the ad set; otherwise it's required. `optimization_goal` drives delivery (`OFFSITE_CONVERSIONS`, `LINK_CLICKS`, `REACH`, etc.). Use `promoted_object` with a pixel_id + `custom_event_type` for conversion optimization. Defaults to PAUSED.
5. Upload media before creating ads
`upload_meta_image` returns an `image_hash` — use it with `create_meta_image_ad` (preferred over `image_url`, which re-uploads). `upload_meta_video` returns a `video_id` — use it with `create_meta_ad`. Both upload tools need `ad_account_id` + a **publicly accessible** URL (S3 pre-signed, public CDN). If the URL is private, the upload will fail — ask the user to host it publicly first.
6. Create ads carefully — $1/call
`create_meta_ad` (video) and `create_meta_image_ad` (static) both cost **$1 per call**, so confirm inputs before firing. Required: `adset_id`, `page_id` (from `get_meta_pages`), `ad_account_id`, `message` (body copy), `title`, `link_description`, `call_to_action_type` (`SHOP_NOW` / `LEARN_MORE` / `SIGN_UP` / `DOWNLOAD` / `BOOK_NOW` / `CONTACT_US` / `GET_QUOTE` / `APPLY_NOW`), and `call_to_action_link`. Add `url_tags` for UTM tracking. **All Advantage+ creative enhancements are automatically disabled** for full creative control. Ads default to PAUSED.
7. Export reports with `export_meta_report` ($1/call)
Returns a CSV download link that expires in **1 hour** — tell the user that up front and remind them if the conversation stretches. Required: `campaign_id` (ad account is auto-resolved). Key params: `level`, `date_preset`/`time_range`, `time_increment` (`"1"` daily, `"7"` weekly, `"monthly"`, `"all_days"` default), and `breakdowns` like `"age,gender,country"`. Use this over `fetch_meta_insights` when the user wants a downloadable file rather than inline results.
8. Present results clearly
For insights: lead with the headline (spend, CTR, top performer), show a ranked table by the metric the user cares about, and call out outliers. For campaign/ad creation: echo back the IDs you just created plus the exact objective, budget (in dollars, not cents), targeting summary, and the fact that everything is **PAUSED — needs manual activation**. For exports: show the download URL and the 1-hour expiry clearly.