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.md

Or upload a .skill bundle to Claude Managed Agents:

https://gentic.co/meta/gentic-meta.skill

Download 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. 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.

5. 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.

6. Tool Reference

11 tools, rendered live from the Gentic MCP manifest. Parameter tables come directly from each tool's JSON Schema.

create_meta_ad

100¢ / call

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.