Gentic Meta — Documentation

Everything you need to manage Meta advertising through AI — browse accounts, analyze performance, create campaigns, and export reports.

1. Getting Started

Prerequisites

Before you can use Gentic Meta, you need:

A Meta Business account with access to at least one ad account
A Facebook Page to publish ads from
A Gentic API key to authenticate requests

Sign Up & Get Your API Key

Go to gentic.co/meta and create an account.
Create an organization from your dashboard. API keys, billing, and ad account data are all scoped to the organization.
Go to the API Keys section in your dashboard.
Click Create API Key. Give it a name (e.g. "Claude Code" or "n8n production").
Copy the key immediately — it starts with gentic_ and is only shown once.

Anyone on your team can generate their own key, and they'll all share the same ad account connections and billing.

Keep your key secure. Treat it like a password. Don't commit it to version control or share it publicly.

2. Connecting to the MCP Server

Gentic Meta uses the Model Context Protocol (MCP) — an open standard for connecting AI agents to external tools. You connect once, and your agent gets access to all Gentic Meta tools automatically.

Server URL: https://mcp.gentic.co/meta

Claude Code (CLI)

Option A — OAuth (no API key needed):

claude mcp add gentic-meta --transport http https://mcp.gentic.co/meta

Claude Code will prompt you to authenticate on first use.

Option B — API key:

claude mcp add gentic-meta --transport http https://mcp.gentic.co/meta --header "Authorization: Bearer <your-api-key>"

Replace <your-api-key> with a key from your dashboard.

Claude Web / Claude Desktop / Claude Mobile

Go to Settings → Connectors
Click Add custom connector at the bottom of the page
Enter the server URL: https://mcp.gentic.co/meta
Click Add — you'll be redirected to sign in and authorize access via OAuth

Custom connectors require a Claude Pro, Max, Team, or Enterprise plan.

ChatGPT

Go to Settings → Apps & Connectors → Advanced settings and enable developer mode
Go to Settings → Connectors → Create
Set the connector name to Gentic Meta and the URL to: https://mcp.gentic.co/meta
You'll see Gentic's tools listed if the connection is successful
In a new chat, click + near the message bar, select More, and choose Gentic Meta

ChatGPT Apps are available on Plus, Pro, Team, Business, Enterprise, and Education plans.

n8n

Add an MCP Client node to your workflow
Set the server URL to https://mcp.gentic.co/meta
Add your API key as a Bearer token in the authentication settings

Any Other MCP Client

Gentic Meta uses standard Streamable HTTP transport. Any client that supports MCP can connect using the server URL and either OAuth or API key Bearer token authentication.

Agent Skills (Recommended)

For the best results, pair the MCP server with the Gentic agent skill. The MCP server gives your agent access to the tools; the skill teaches it the optimal workflow order — browsing accounts, analyzing performance, creating campaigns, and exporting reports.

1. Add the MCP server (if you haven't already):

claude mcp add gentic-meta --transport http https://mcp.gentic.co/meta --header "Authorization: Bearer <your-api-key>"

2. Install the agent skill:

npx skills add gentic-co/agent-skills

Or add the skill directly via URL:

https://gentic.co/meta/SKILL.md

MCP server — provides tool access (browse accounts, insights, campaign creation, etc.)
Agent skill — teaches the optimal workflow order: browse accounts → analyze → create → export

Works with Claude Code, Cursor, Copilot, and 40+ other agents.

3. Browse Ad Accounts

Tool: get_meta_ids

Cost: Free

Navigate the Meta ad account hierarchy. Start at the top level to discover your ad accounts, then drill down into campaigns, ad sets, ads, and ad creatives.

Parameters

Parameter	Required	Default	Description
level	Yes	—	Hierarchy level: "adaccounts", "campaigns", "adsets", "ads", or "adcreatives"
parent_id	No*	—	Required for all levels except "adaccounts". E.g. "act_XXXXXX" for campaigns.
date_preset	No	—	Include performance data: "last_7d", "last_30d", etc.
time_range	No	—	Custom date range: {"since":"YYYY-MM-DD","until":"YYYY-MM-DD"}
limit	No	—	Max results to return

Hierarchy

Ad Account → Campaigns → Ad Sets → Ads → Ad Creatives

Example prompts

Discover accounts:

"Show me all my Meta ad accounts."

Drill down:

"List all campaigns in my ad account with last 30 days spend."

Important

All IDs must be passed as quoted strings (e.g. "120239005302490769"). JavaScript rounds large integers, causing silent failures with wrong IDs.

4. Get Facebook Pages

Tool: get_meta_pages

Cost: Free

List all Facebook Pages associated with the authenticated user. Page IDs are required when creating ads — the ad is published on behalf of the Page.

Parameters

This tool takes no parameters.

Example prompts

"What Facebook Pages do I have access to?"

Before ad creation:

"Show me my Pages so I can choose which one to run ads from."

5. Fetch Insights

Tool: fetch_meta_insights

Cost: 10¢ per call

Get performance metrics for campaigns, ad sets, or ads. Supports date filtering, custom fields, and demographic breakdowns.

Parameters

Parameter	Required	Default	Description
level	Yes	—	"campaign", "adset", or "ad"
ids	Yes	—	Comma-separated IDs as a quoted string (e.g. "120239005302490769,120239005302490770")
date_preset	No	—	today, yesterday, last_7d, last_14d, last_30d, this_month, last_month, maximum
time_range	No	—	Custom range as JSON: {"since":"YYYY-MM-DD","until":"YYYY-MM-DD"}
fields	No	impressions, spend, clicks, ctr, actions, conversions, action_values	Comma-separated metric fields
breakdowns	No	—	e.g. "age,gender", "platform_position", "country"

Example prompts

Performance overview:

"How did my campaigns perform over the last 30 days?"

Demographic breakdown:

"Break down last month's ad performance by age and gender."

Pro tip

Use date_preset OR time_range, not both. If neither is specified, Meta defaults to the lifetime of the object.

6. View Ad Creatives

Tool: fetch_meta_ad_creatives

Cost: 5¢ per call

Get ad creative details including copy, images, videos, and call-to-action. Use get_meta_ids with level: "adcreatives" first to find creative IDs.

Parameters

Parameter	Required	Default	Description
ad_creative_ids	Yes	—	Comma-separated ad creative IDs as a quoted string (e.g. "120212416035950769")

Example prompts

Review creatives:

"Show me the creative details for my top-performing ads."

Audit copy:

"What copy and CTA are my current ads using?"

7. Create Campaigns

Tool: create_meta_campaign

Cost: Free

Create a new Meta advertising campaign. Defaults to PAUSED status and OUTCOME_SALES objective.

Parameters

Parameter	Required	Default	Description
ad_account_id	Yes	—	Ad account ID (with or without act_ prefix)
name	Yes	—	Campaign name
objective	No	OUTCOME_SALES	OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_APP_PROMOTION
status	No	PAUSED	Campaign status
daily_budget	No	—	Budget in cents as string (e.g. "270000" for $2,700). Only with CBO enabled.
is_campaign_budget_optimization	No	false	Enable Campaign Budget Optimization (CBO)
bid_strategy	No	—	LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP
special_ad_categories	No	[]	e.g. ["CREDIT", "EMPLOYMENT", "HOUSING"]

Example prompts

Basic campaign:

"Create a new sales campaign called 'Summer Sale 2026' in my ad account."

With CBO:

"Create a traffic campaign with CBO enabled and a $50/day budget."

8. Create Ad Sets

Tool: create_meta_adset

Cost: Free

Create a new ad set within a campaign. Define targeting, budget, optimization goal, and scheduling.

Parameters

Parameter	Required	Default	Description
ad_account_id	Yes	—	Ad account ID
name	Yes	—	Ad set name
campaign_id	Yes	—	Parent campaign ID as a quoted string
targeting	Yes	—	Targeting spec as JSON (e.g. {"geo_locations":{"countries":["US"]},"age_min":25,"age_max":55})
daily_budget	No	—	Budget in cents as string. Required unless parent campaign has CBO.
optimization_goal	No	REACH	REACH, LINK_CLICKS, OFFSITE_CONVERSIONS, IMPRESSIONS, etc.
billing_event	No	IMPRESSIONS	Billing event type
start_time	No	—	ISO format start time
end_time	No	—	ISO format end time
promoted_object	No	—	e.g. {"pixel_id":"...","custom_event_type":"PURCHASE"}
status	No	PAUSED	Ad set status

Example prompts

Basic targeting:

"Create an ad set targeting US women ages 25-45 with a $20/day budget."

With scheduling:

"Create an ad set that runs from April 15 to May 15 targeting the UK."

9. Upload Media

Two tools for uploading creative assets to your ad account. Both require a publicly accessible URL (e.g. S3 pre-signed URL, public CDN link).

upload_meta_video

Upload a video to your ad account for use in video ads. Cost: Free.

Parameter	Required	Default	Description
ad_account_id	Yes	—	Ad account ID
file_url	Yes	—	Public URL of the video file
name	Yes	—	Name/description for the video

upload_meta_image

Upload an image to your ad account for use in static image ads. Returns an image_hash used when creating image ads. Cost: Free.

Parameter	Required	Default	Description
ad_account_id	Yes	—	Ad account ID
image_url	Yes	—	Public URL of the image (e.g. S3 pre-signed URL)
name	Yes	—	Name/description for the image

Example prompts

Upload video:

"Upload this video to my ad account: https://cdn.example.com/summer-sale.mp4"

Upload image:

"Upload this product image for my ads: https://cdn.example.com/product-hero.jpg"

10. Create Ads

Two tools for creating ads — one for video, one for static images. Both default to PAUSED status and automatically disable all Advantage+ creative enhancements.

create_meta_ad (Video)

Create a new video ad using a video_id from upload_meta_video. Cost: $1.00 per call.

Parameter	Required	Default	Description
ad_account_id	Yes	—	Ad account ID
name	Yes	—	Ad name
adset_id	Yes	—	Parent ad set ID as a quoted string
page_id	Yes	—	Facebook Page ID (from get_meta_pages)
video_id	Yes	—	Video ID (from upload_meta_video)
message	Yes	—	Ad copy/message text
call_to_action_type	Yes	—	SHOP_NOW, LEARN_MORE, SIGN_UP, DOWNLOAD, BOOK_NOW, CONTACT_US, GET_QUOTE, APPLY_NOW
call_to_action_link	Yes	—	Destination URL
title	No	—	Ad headline
link_description	No	—	Description below the headline
image_url	No	—	Thumbnail image URL
url_tags	No	—	URL tracking parameters (e.g. UTM tags)

create_meta_image_ad (Static Image)

Create a static image ad using image_hash from upload_meta_image (preferred) or a direct image_url. Cost: $1.00 per call.

Parameter	Required	Default	Description
ad_account_id	Yes	—	Ad account ID
name	Yes	—	Ad name
adset_id	Yes	—	Parent ad set ID as a quoted string
page_id	Yes	—	Facebook Page ID (from get_meta_pages)
message	Yes	—	Ad copy/message text
call_to_action_type	Yes	—	SHOP_NOW, LEARN_MORE, SIGN_UP, etc.
call_to_action_link	Yes	—	Destination URL
image_hash	No*	—	From upload_meta_image. Preferred over image_url.
image_url	No*	—	Direct image URL. Use image_hash when possible.
title	No	—	Ad headline
link_description	No	—	Description below the headline
url_tags	No	—	URL tracking parameters

Example prompts

Video ad:

"Create a video ad with the headline 'Summer Sale — 40% Off' and a Shop Now button linking to our website."

Image ad:

"Create an image ad using the product photo I just uploaded, with a Learn More CTA."

Key behaviors

All Advantage+ creative enhancements are automatically disabled
Ads are created in PAUSED status — activate them manually in Meta Ads Manager
Use image_hash over image_url for image ads when possible — it's more reliable

11. Export Reports

Tool: export_meta_report

Cost: Free

Export Meta ad performance data as a downloadable CSV. Uses Meta's Async Report API to handle large datasets. Returns a download link that expires in 1 hour.

Parameters

Parameter	Required	Default	Description
campaign_id	Yes	—	Campaign ID — auto-resolves the ad account and filters to this campaign
level	Yes	—	"campaign", "adset", or "ad"
date_preset	No	—	today, yesterday, last_7d, last_14d, last_30d, this_month, last_month, last_3_months, last_6_months, last_year, maximum
time_range	No	—	Custom range as JSON: {"since":"YYYY-MM-DD","until":"YYYY-MM-DD"}
time_increment	No	all_days	"1" for daily, "7" for weekly, "monthly", or "all_days"
breakdowns	No	—	e.g. "age,gender,country,platform_position,publisher_platform"
fields	No	campaign_id, campaign_name, adset_id, adset_name, ad_id, ad_name, impressions, spend, clicks, ctr, cpc, cpm, reach, frequency, actions, action_values, cost_per_action_type, conversions, conversion_values	Comma-separated metric fields

Example prompts

Monthly report:

"Export a CSV report for my campaign from last month, broken down by ad."

Daily breakdown:

"Export a daily performance report for my campaign over the last 30 days."

Demographic report:

"Export a report for my campaign broken down by age and gender."

Important

Download links expire in 1 hour. Save the CSV locally if you need it longer.

12. Tool Reference

Tool	Description	Cost
get_meta_ids	Browse the ad account hierarchy: accounts → campaigns → ad sets → ads → creatives.	Free
get_meta_pages	List Facebook Pages for the authenticated user. Returns page IDs needed for ad creation.	Free
fetch_meta_insights	Get performance metrics with date filtering, custom fields, and demographic breakdowns.	10¢
fetch_meta_ad_creatives	View ad creative details: copy, images, videos, and call-to-action.	5¢
create_meta_campaign	Create a new campaign with objective, budget, bid strategy, and special ad categories.	Free
create_meta_adset	Create an ad set with targeting, budget, optimization goal, and scheduling.	Free
upload_meta_video	Upload a video from a public URL for use in video ads.	Free
upload_meta_image	Upload an image from a public URL. Returns image_hash for ad creation.	Free
create_meta_ad	Create a video ad with copy, CTA, and destination URL. Advantage+ auto-disabled.	$1.00
create_meta_image_ad	Create a static image ad with copy, CTA, and destination URL. Advantage+ auto-disabled.	$1.00
export_meta_report	Export performance data as a downloadable CSV. Supports breakdowns and time increments.	$1.00

13. Pricing

Browsing, account setup, and media uploads are free. Insights and creatives cost 5–10¢. Ad creation and report exports cost $1.00 each.

Action	Cost
Browse ad accounts (get_meta_ids)	Free
Get Facebook Pages	Free
Fetch performance insights	10¢
View ad creatives	5¢
Create campaign	Free
Create ad set	Free
Upload video	Free
Upload image	Free
Create video ad	$1.00
Create image ad	$1.00
Export report (CSV)	$1.00

How it works

Credits are deducted per tool call. A typical full campaign setup (1 campaign + 1 ad set + 1 media upload + 1 ad) costs $1.00 — only the ad creation step is charged. Browsing accounts and uploading media are free.

Gentic Meta uses Meta Graph API v23.0. The batch API supports up to 50 requests per call. All IDs must be passed as quoted strings to avoid JavaScript large integer rounding.

Rate limit: 100 requests per minute per API key. Need higher limits? Contact us.