{ "openapi": "3.1.0", "info": { "title": "Meta Ads MCP Server", "description": "Facebook and Instagram campaign management via Meta Marketing API v21.0", "version": "1.0.0", "contact": { "name": "Hopkin", "url": "https://hopkin.ai" } }, "servers": [ { "url": "https://meta.mcp.hopkin.ai", "description": "Production MCP endpoint" } ], "paths": { "/tools": { "get": { "operationId": "listTools", "summary": "List available tools", "description": "Returns all tools registered on this server with their names, descriptions, and input schemas.", "tags": [ "discovery" ], "responses": { "200": { "description": "Tool list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolList" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } } } } }, "/tools/meta_ads_get_account_summary": { "post": { "operationId": "meta_ads_get_account_summary", "summary": "Get Meta Ads Account Summary", "description": "Standardized account-level performance summary for cross-platform comparison. Normalized format identical to google_ads_get_account_summary. Includes conversion_detail breakdown from both Meta actions and conversions arrays. Preferred over get_insights or get_performance_report for quick account-level overviews. Always fetches fresh data.", "tags": [ "account-summary" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Meta ad account ID" }, "date_preset": { "type": "string", "enum": [ "today", "yesterday", "this_week_mon_today", "this_week_sun_today", "last_week_mon_sun", "last_week_sun_sat", "this_month", "last_month", "this_quarter", "last_quarter", "this_year", "last_year", "last_3d", "last_7d", "last_14d", "last_28d", "last_30d", "last_90d", "lifetime", "maximum" ], "description": "Predefined date range (e.g., last_7d, last_30d, this_month)" }, "time_range": { "type": "object", "properties": { "since": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "since", "until" ], "additionalProperties": false, "description": "Custom date range {since, until} in YYYY-MM-DD" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "last-30-days-summary": { "summary": "Last 30 days summary", "value": { "account_id": "act_123", "reason": "Quick performance overview" } }, "last-7-days": { "summary": "Last 7 days", "value": { "account_id": "act_123", "date_preset": "last_7d", "reason": "Weekly check-in" } }, "custom-date-range": { "summary": "Custom date range", "value": { "account_id": "act_123", "time_range": { "since": "2026-01-01", "until": "2026-01-31" }, "reason": "January performance review" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_get_activities": { "post": { "operationId": "meta_ads_get_activities", "summary": "Get Meta Ads Activities", "description": "Retrieve activity/change history for a Meta ad account or specific entity. Cached with 1-hour TTL; use refresh=true for fresh data. Meta's API only returns the last 7 days per call, but cached data accumulates for historical lookups.", "tags": [ "activities" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "The ad account ID (with or without act_ prefix)" }, "entity_id": { "type": "string", "minLength": 1, "description": "Filter activities to a specific entity (campaign, ad set, or ad ID). If omitted, returns account-level activities." }, "entity_type": { "type": "string", "enum": [ "ACCOUNT", "CAMPAIGN", "AD_SET", "AD" ], "description": "Type of entity: ACCOUNT, CAMPAIGN, AD_SET, AD. Used with entity_id for filtering." }, "start_date": { "type": "string", "description": "Start date for activity range (ISO 8601, e.g. 2024-01-01)" }, "end_date": { "type": "string", "description": "End date for activity range (ISO 8601, e.g. 2024-01-31)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of activities per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh activity data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "account-activities": { "summary": "Account activities", "value": { "account_id": "123456789", "reason": "View recent account changes" } }, "campaign-history": { "summary": "Campaign history", "value": { "account_id": "123456789", "entity_id": "23842453456789", "entity_type": "CAMPAIGN", "reason": "View campaign change history" } }, "date-range": { "summary": "Date range", "value": { "account_id": "123456789", "start_date": "2024-01-01", "end_date": "2024-01-31", "reason": "January activity" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_list_ad_accounts": { "post": { "operationId": "meta_ads_list_ad_accounts", "summary": "List Meta Ad Accounts", "description": "List Meta ad accounts with search, status filtering, single/multi-account lookup by ID, and pagination. Cached by default; pass refresh=true for latest data. Entities may optionally include recent activities.", "tags": [ "ad-accounts" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "search": { "type": "string", "minLength": 1, "description": "Search ad accounts by name (case-insensitive partial match)" }, "account_id": { "type": "string", "minLength": 1, "description": "Filter by exact account ID (without act_ prefix)" }, "account_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Get multiple accounts by ID. Mutually exclusive with account_id. When provided, ignores other filters/pagination." }, "status": { "type": "integer", "description": "Account status code (1=Active, 2=Disabled, etc.)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of accounts per page (default: 20, max: 100)" }, "include_activities": { "type": "boolean", "default": false, "description": "Include recent activity log (last 7 days of changes) for each entity" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-all": { "summary": "List all", "value": { "reason": "List all ad accounts" } }, "search-by-name": { "summary": "Search by name", "value": { "search": "marketing", "reason": "Find marketing accounts" } }, "filter-by-status": { "summary": "Filter by status", "value": { "status": 1, "reason": "List active accounts" } }, "get-by-id": { "summary": "Get by ID", "value": { "account_id": "123456789", "reason": "Get specific account" } }, "get-multiple-by-ids": { "summary": "Get multiple by IDs", "value": { "account_ids": [ "123456789", "987654321" ], "reason": "Get specific accounts" } }, "force-refresh": { "summary": "Force refresh", "value": { "refresh": true, "reason": "Get fresh data from Meta API" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_get_ad_creative_report": { "post": { "operationId": "meta_ads_get_ad_creative_report", "summary": "Get Meta Ads Creative Performance Report", "description": "Ad-level performance report with full funnel metrics, including video funnel (ThruPlays, 25/50/75/95/100% completions, avg watch time, cost per ThruPlay) for video creatives. All conversion types shown individually. Supports two grouping modes: ad_name (default, aggregates ads sharing the same name with a representative ad_id for preview) and ad_id (one row per ad). The representative ad_id can be passed to meta_ads_preview_ads. Always fetches fresh data.", "tags": [ "reporting" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Meta ad account ID" }, "time_range": { "type": "object", "properties": { "since": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "since", "until" ], "additionalProperties": false, "description": "Required date range {since, until} in YYYY-MM-DD" }, "level": { "type": "string", "enum": [ "ad_id", "ad_name" ], "default": "ad_name", "description": "Grouping level: ad_name (default, aggregate ads sharing the same name, providing a representative ad_id that can be passed to meta_ads_preview_ads) or ad_id (one row per ad)" }, "time_increment": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 90 }, { "type": "string", "const": "monthly" }, { "type": "string", "const": "all_days" } ], "description": "Time grouping: 1=daily, 7=weekly, or \"monthly\"" }, "breakdowns": { "type": "array", "items": { "type": "string", "enum": [ "age", "gender", "country", "region", "device_platform", "publisher_platform", "platform_position", "impression_device", "dma", "user_segment_key" ] }, "description": "Segment by dimension. Pass multiple values for cross-tabulated rows (e.g. [\"age\",\"gender\"] → one row per \"35-44 / female\" segment). Available: age, gender, country, region, device_platform, publisher_platform, platform_position, impression_device, dma" }, "filtering": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Field to filter on" }, "operator": { "type": "string", "enum": [ "EQUAL", "NOT_EQUAL", "GREATER_THAN", "LESS_THAN", "IN", "NOT_IN", "CONTAIN", "NOT_CONTAIN" ], "description": "Comparison operator" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "description": "Value(s) to compare against — numbers are coerced to strings automatically" } }, "required": [ "field", "operator", "value" ], "additionalProperties": false }, "description": "Filters as [{field, operator, value}]" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "time_range", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "all-ads-by-id": { "summary": "All ads by ID", "value": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "reason": "Review individual ad performance" } }, "aggregate-by-creative-name": { "summary": "Aggregate by creative name", "value": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "level": "ad_name", "reason": "Compare creative variants running across multiple ad sets" } }, "filter-by-campaign": { "summary": "Filter by campaign", "value": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "level": "ad_name", "filtering": [ { "field": "campaign.id", "operator": "IN", "value": [ "111111111" ] } ], "reason": "Creative performance within a specific campaign" } }, "creative-names-by-demographics": { "summary": "Creative names by demographics", "value": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "level": "ad_name", "breakdowns": [ "age", "gender" ], "reason": "Understand which creatives perform best per demographic" } }, "video-creative-thruplays": { "summary": "Video creative ThruPlays", "value": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "level": "ad_name", "reason": "Compare ThruPlay performance across Video Views campaign creatives" } } } } } }, "responses": { "200": { "description": "JSON report data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_search_ad_library": { "post": { "operationId": "meta_ads_search_ad_library", "summary": "Search Meta Ad Library", "description": "Search the Meta Ad Library for ads from any advertiser. Returns public transparency data including ad creative text, snapshot URLs, delivery dates, and platforms. For political/issue ads, also returns spend ranges, impressions, and demographics. Does NOT require an ad account — searches globally. Rate limit: 200 calls/hour. Each result includes an ad_snapshot_url that links to the ad's visual preview on Facebook.", "tags": [ "search-ad-library" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "search_terms": { "type": "string", "maxLength": 100, "description": "Keywords to search for in ad content. Spaces act as AND. Use the language the ad is written in." }, "search_type": { "type": "string", "enum": [ "KEYWORD_UNORDERED", "KEYWORD_EXACT_PHRASE" ], "description": "Search mode: KEYWORD_UNORDERED (default, any order) or KEYWORD_EXACT_PHRASE" }, "search_page_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 10, "description": "Filter by up to 10 Facebook Page IDs. Use this for competitor/brand lookups." }, "ad_reached_countries": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "REQUIRED. ISO country codes (e.g. [\"US\", \"GB\"]) or [\"ALL\"]. Warning: [\"ALL\"] may return very large result sets — use with small limit values." }, "ad_type": { "type": "string", "enum": [ "ALL", "EMPLOYMENT_ADS", "FINANCIAL_PRODUCTS_AND_SERVICES_ADS", "HOUSING_ADS", "POLITICAL_AND_ISSUE_ADS" ], "description": "Filter by ad category. Default: ALL" }, "ad_active_status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "ALL" ], "description": "Filter by delivery status. Default: ACTIVE" }, "ad_delivery_date_min": { "type": "string", "description": "Minimum delivery date (YYYY-MM-DD)" }, "ad_delivery_date_max": { "type": "string", "description": "Maximum delivery date (YYYY-MM-DD)" }, "media_type": { "type": "string", "enum": [ "ALL", "IMAGE", "MEME", "VIDEO", "NONE" ], "description": "Filter by media type" }, "publisher_platforms": { "type": "array", "items": { "type": "string", "enum": [ "FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER", "WHATSAPP", "THREADS" ] }, "minItems": 1, "description": "Filter by platform(s)" }, "languages": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Filter by language (ISO 639-1 codes)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Results per page (default: 25, max: 50). Note: 200 calls/hour rate limit — use larger pages to conserve quota." }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "ad_reached_countries", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "search-by-keyword": { "summary": "Search by keyword", "value": { "search_terms": "running shoes", "ad_reached_countries": [ "US" ], "reason": "Competitive research on running shoe ads" } }, "search-by-page-id": { "summary": "Search by page ID", "value": { "search_page_ids": [ "123456789" ], "ad_reached_countries": [ "US" ], "reason": "View competitor ads" } }, "political-ads": { "summary": "Political ads", "value": { "ad_type": "POLITICAL_AND_ISSUE_ADS", "ad_reached_countries": [ "US" ], "search_terms": "climate", "reason": "Political ad transparency research" } }, "video-ads-on-instagram": { "summary": "Video ads on Instagram", "value": { "search_terms": "fitness", "ad_reached_countries": [ "US" ], "media_type": "VIDEO", "publisher_platforms": [ "INSTAGRAM" ], "reason": "Creative research" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_preview_ads": { "post": { "operationId": "meta_ads_preview_ads", "summary": "Preview Meta Ads", "description": "Interactive UI for displaying Meta ad previews with creative content and metrics", "tags": [ "ads" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "The ad account ID" }, "ads": { "type": "array", "items": { "type": "object", "properties": { "ad_id": { "type": "string", "minLength": 1, "description": "The ad ID to preview" }, "metrics": { "type": "object", "additionalProperties": { "type": [ "string", "number" ] }, "description": "Metric name-value pairs to display" } }, "required": [ "ad_id" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20, "description": "Ads to preview (1-20)" }, "metric_labels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Display labels for metric keys" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "ads", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "single-ad": { "summary": "Single ad", "value": { "account_id": "act_123456789", "ads": [ { "ad_id": "12345" } ], "reason": "Preview ad creative" } }, "with-metrics": { "summary": "With metrics", "value": { "account_id": "act_123456789", "ads": [ { "ad_id": "12345", "metrics": { "spend": "150.00", "ctr": "2.5%" } } ], "metric_labels": { "spend": "Spend", "ctr": "Click Rate" }, "reason": "Preview ad with performance metrics" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } }, "x-mcp-tool-type": "app" } }, "/tools/meta_ads_list_ads": { "post": { "operationId": "meta_ads_list_ads", "summary": "List Meta Ads", "description": "List ads for a Meta ad account with ad set filtering, status, name search, single/multi-ad lookup by ID, and pagination. Each ad includes a Landing URL when available (extracted from object_story_spec, link_url, or asset_feed_spec depending on ad format) and a URL Tags line exposing the ad's tracking-template string — the URL parameters (UTMs / custom click-tracking) Meta appends to the destination URL at click time, with {{macro}} placeholders preserved verbatim. The ad-level url_tags field wins when set; otherwise the response falls back to creative-level url_tags / template_url_spec. A \"Landing Page URLs\" summary lists every unique destination URL; a \"URL Tags Audit\" summary lists the distinct templates in use and names every ad with a destination URL but no tracking template — use these to audit UTM coverage across an account without reading every ad. Set include_assets=true to include resolved creative media URLs (adds latency for cache misses). Entities may optionally include recent activities, and optionally automated rules (set include_rules=true to see which rules affect each ad).", "tags": [ "ads" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "The ad account ID (with or without act_ prefix)" }, "ad_id": { "type": "string", "minLength": 1, "description": "Get a specific ad by ID. When provided, returns only that ad and ignores other filters/pagination." }, "ad_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Get multiple ads by ID. Mutually exclusive with ad_id. When provided, ignores other filters/pagination." }, "adset_id": { "type": "string", "minLength": 1, "description": "Filter by ad set ID" }, "search": { "type": "string", "minLength": 1, "description": "Search ads by name (case-insensitive partial match)" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DELETED", "ARCHIVED" ] }, "description": "Filter by configured ad status (user-set): ACTIVE, PAUSED, DELETED, ARCHIVED" }, "effective_status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DELETED", "ARCHIVED", "IN_PROCESS", "WITH_ISSUES", "CAMPAIGN_PAUSED", "ADSET_PAUSED", "DISAPPROVED", "PENDING_REVIEW", "PENDING_BILLING_INFO", "PREAPPROVED" ] }, "description": "Filter by Meta-computed serving status: ACTIVE, PAUSED, DELETED, ARCHIVED, IN_PROCESS, WITH_ISSUES, CAMPAIGN_PAUSED, ADSET_PAUSED, DISAPPROVED, PENDING_REVIEW, PENDING_BILLING_INFO, PREAPPROVED" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of ads per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "include_activities": { "type": "boolean", "default": false, "description": "Include recent activity log (last 7 days of changes) for each entity" }, "include_assets": { "type": "boolean", "default": false, "description": "Include resolved creative asset URLs (asset_url, thumbnail_url, asset_type) for each ad. Uses cached GCS URLs when available." }, "include_rules": { "type": "boolean", "default": false, "description": "Include automated rules (from adrules_library) that affect each entity" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-all": { "summary": "List all", "value": { "account_id": "123456789", "reason": "List ads" } }, "filter-by-ad-set": { "summary": "Filter by ad set", "value": { "account_id": "123456789", "adset_id": "23842453456789", "reason": "List ads in ad set" } }, "filter-by-status": { "summary": "Filter by status", "value": { "account_id": "123456789", "status": [ "ACTIVE", "PAUSED" ], "reason": "List active/paused ads" } }, "find-disapproved-review-blocked": { "summary": "Find disapproved / review-blocked", "value": { "account_id": "123456789", "effective_status": [ "DISAPPROVED", "WITH_ISSUES", "PENDING_REVIEW" ], "reason": "Surface ads blocked by review" } }, "get-by-id": { "summary": "Get by ID", "value": { "account_id": "123456789", "ad_id": "23842453456789", "reason": "Get specific ad" } }, "get-multiple-by-ids": { "summary": "Get multiple by IDs", "value": { "account_id": "123456789", "ad_ids": [ "23842453456789", "23842453456790" ], "reason": "Get specific ads" } }, "search-by-name": { "summary": "Search by name", "value": { "account_id": "123456789", "search": "Summer", "reason": "Find summer ads" } }, "with-asset-urls": { "summary": "With asset URLs", "value": { "account_id": "123456789", "include_assets": true, "reason": "List ads with creative assets" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_list_adsets": { "post": { "operationId": "meta_ads_list_adsets", "summary": "List Meta Ad Sets", "description": "List ad sets for a Meta ad account with campaign filtering, status, name search, single/multi-adset lookup by ID, and pagination. Entities may optionally include recent activities, and optionally automated rules (set include_rules=true to see which rules affect each ad set).", "tags": [ "adsets" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "The ad account ID (with or without act_ prefix)" }, "adset_id": { "type": "string", "minLength": 1, "description": "Get a specific ad set by ID. When provided, returns only that ad set and ignores other filters/pagination." }, "adset_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Get multiple ad sets by ID. Mutually exclusive with adset_id. When provided, ignores other filters/pagination." }, "campaign_id": { "type": "string", "minLength": 1, "description": "Filter by campaign ID" }, "search": { "type": "string", "minLength": 1, "description": "Search ad sets by name (case-insensitive partial match)" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DELETED", "ARCHIVED" ] }, "description": "Filter by configured ad-set status (user-set): ACTIVE, PAUSED, DELETED, ARCHIVED" }, "effective_status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DELETED", "ARCHIVED", "IN_PROCESS", "WITH_ISSUES", "CAMPAIGN_PAUSED" ] }, "description": "Filter by Meta-computed serving status: ACTIVE, PAUSED, DELETED, ARCHIVED, IN_PROCESS, WITH_ISSUES, CAMPAIGN_PAUSED" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of ad sets per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "include_activities": { "type": "boolean", "default": false, "description": "Include recent activity log (last 7 days of changes) for each entity" }, "include_rules": { "type": "boolean", "default": false, "description": "Include automated rules (from adrules_library) that affect each entity" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-all": { "summary": "List all", "value": { "account_id": "123456789", "reason": "List ad sets" } }, "filter-by-campaign": { "summary": "Filter by campaign", "value": { "account_id": "123456789", "campaign_id": "23842453456789", "reason": "List ad sets in campaign" } }, "filter-by-status": { "summary": "Filter by status", "value": { "account_id": "123456789", "status": [ "ACTIVE", "PAUSED" ], "reason": "List active/paused ad sets" } }, "filter-by-serving-status": { "summary": "Filter by serving status", "value": { "account_id": "123456789", "effective_status": [ "CAMPAIGN_PAUSED", "WITH_ISSUES" ], "reason": "Find ad sets paused by parent or with issues" } }, "get-by-id": { "summary": "Get by ID", "value": { "account_id": "123456789", "adset_id": "23842453456789", "reason": "Get specific ad set" } }, "get-multiple-by-ids": { "summary": "Get multiple by IDs", "value": { "account_id": "123456789", "adset_ids": [ "23842453456789", "23842453456790" ], "reason": "Get specific ad sets" } }, "search-by-name": { "summary": "Search by name", "value": { "account_id": "123456789", "search": "Retargeting", "reason": "Find retargeting ad sets" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_check_auth_status": { "post": { "operationId": "meta_ads_check_auth_status", "summary": "Check Meta Ads Authentication Status", "description": "Troubleshoot authentication issues and get user profile info. Only use this tool when another tool fails with a permission or authentication error — do NOT call proactively.", "tags": [ "auth" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "check-auth": { "summary": "Check auth", "value": { "reason": "Another tool returned an auth error, checking account connection status" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_list_campaigns": { "post": { "operationId": "meta_ads_list_campaigns", "summary": "List Meta Ad Campaigns", "description": "List campaigns for a Meta ad account with status filtering, name search, single/multi-campaign lookup by ID, and pagination. Entities may optionally include recent activities, and optionally automated rules (set include_rules=true to see which rules affect each campaign).", "tags": [ "campaigns" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "The ad account ID (with or without act_ prefix)" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DELETED", "ARCHIVED" ] }, "description": "Filter by configured campaign status (user-set): ACTIVE, PAUSED, DELETED, ARCHIVED" }, "effective_status": { "type": "array", "items": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "DELETED", "ARCHIVED", "IN_PROCESS", "WITH_ISSUES" ] }, "description": "Filter by Meta-computed serving status: ACTIVE, PAUSED, DELETED, ARCHIVED, IN_PROCESS, WITH_ISSUES" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of campaigns per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Meta API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "campaign_id": { "type": "string", "minLength": 1, "description": "Get a specific campaign by ID. When provided, returns only that campaign and ignores other filters/pagination." }, "campaign_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Get multiple campaigns by ID. Mutually exclusive with campaign_id. When provided, ignores other filters/pagination." }, "search": { "type": "string", "minLength": 1, "description": "Search campaigns by name (case-insensitive partial match)" }, "include_activities": { "type": "boolean", "default": false, "description": "Include recent activity log (last 7 days of changes) for each entity" }, "include_rules": { "type": "boolean", "default": false, "description": "Include automated rules (from adrules_library) that affect each entity" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-all": { "summary": "List all", "value": { "account_id": "123456789", "reason": "List campaigns" } }, "filter-by-status": { "summary": "Filter by status", "value": { "account_id": "123456789", "status": [ "ACTIVE", "PAUSED" ], "reason": "List active/paused campaigns" } }, "filter-by-serving-status": { "summary": "Filter by serving status", "value": { "account_id": "123456789", "effective_status": [ "WITH_ISSUES" ], "reason": "Find campaigns with delivery issues" } }, "get-by-id": { "summary": "Get by ID", "value": { "account_id": "123456789", "campaign_id": "23842453456789", "reason": "Get specific campaign" } }, "get-multiple-by-ids": { "summary": "Get multiple by IDs", "value": { "account_id": "123456789", "campaign_ids": [ "23842453456789", "23842453456790" ], "reason": "Get specific campaigns" } }, "search-by-name": { "summary": "Search by name", "value": { "account_id": "123456789", "search": "Summer", "reason": "Find summer campaigns" } }, "paginate": { "summary": "Paginate", "value": { "account_id": "123456789", "limit": 10, "reason": "First page of campaigns" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_render_chart": { "post": { "operationId": "meta_ads_render_chart", "summary": "Render Chart", "description": "Interactive UI for rendering data visualizations (bar, scatter, timeseries, funnel, waterfall, choropleth)", "tags": [ "chart" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Brief explanation of why you are rendering this chart" }, "chart": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "bar" }, "data": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": [ "number", "null" ] } } }, "required": [ "label", "values" ], "additionalProperties": false } }, "metric": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" }, "tickFormat": { "type": "string" }, "labelFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "format": { "type": "string" }, "suffix": { "type": "string" } }, "required": [ "field" ], "additionalProperties": false } } }, "required": [ "field", "label" ], "additionalProperties": false }, { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" }, "tickFormat": { "type": "string" }, "labelFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "format": { "type": "string" }, "suffix": { "type": "string" } }, "required": [ "field" ], "additionalProperties": false } } }, "required": [ "field", "label" ], "additionalProperties": false } } ] }, "orientation": { "type": "string", "enum": [ "horizontal", "vertical" ], "default": "horizontal" }, "sort": { "type": "string", "enum": [ "asc", "desc", "none" ], "default": "desc" }, "colorBy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "threshold" }, "field": { "type": "string" }, "threshold": { "type": "number" }, "sentiment": { "type": "string", "enum": [ "above-positive", "above-negative" ], "default": "above-positive" } }, "required": [ "type", "field", "threshold" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "continuous" }, "field": { "type": "string" }, "scheme": { "type": "string" }, "reverse": { "type": "boolean", "default": false }, "muteZero": { "type": "boolean", "default": false }, "label": { "type": "string" } }, "required": [ "type", "field", "scheme" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "categorical" } }, "required": [ "type" ], "additionalProperties": false } ] }, "referenceLines": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "label": { "type": "string" }, "dash": { "type": "string", "enum": [ "solid", "dashed" ], "default": "dashed" } }, "required": [ "value" ], "additionalProperties": false } }, "table": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false } } }, "required": [ "columns" ], "additionalProperties": false }, "panelWidth": { "type": "number" }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 400 } }, "required": [ "type", "data", "metric" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scatter" }, "data": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "label", "values" ], "additionalProperties": false } }, "x": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "scale": { "type": "string", "enum": [ "linear", "log" ], "default": "linear" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false }, "y": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "scale": { "type": "string", "enum": [ "linear", "log" ], "default": "linear" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false }, "size": { "type": "object", "properties": { "field": { "type": "string" }, "range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "default": [ 3, 20 ] } }, "required": [ "field" ], "additionalProperties": false }, "color": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "continuous" }, "field": { "type": "string" }, "scheme": { "type": "string" }, "reverse": { "type": "boolean", "default": false } }, "required": [ "type", "field", "scheme" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "threshold" }, "field": { "type": "string" }, "threshold": { "type": "number" }, "sentiment": { "type": "string", "enum": [ "above-positive", "above-negative" ], "default": "above-positive" } }, "required": [ "type", "field", "threshold" ], "additionalProperties": false } ] }, "referenceLines": { "type": "object", "properties": { "medianX": { "type": "boolean", "default": false }, "medianY": { "type": "boolean", "default": false }, "targets": { "type": "array", "items": { "type": "object", "properties": { "slope": { "type": "number" }, "label": { "type": "string" } }, "required": [ "slope", "label" ], "additionalProperties": false } }, "regression": { "type": "boolean", "default": false } }, "additionalProperties": false }, "table": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false } } }, "required": [ "columns" ], "additionalProperties": false }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 450 } }, "required": [ "type", "data", "x", "y" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "timeseries" }, "data": { "type": "object", "properties": { "current": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "date", "values" ], "additionalProperties": false } }, "previous": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "date", "values" ], "additionalProperties": false } }, "projection": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "date", "values" ], "additionalProperties": false } } }, "required": [ "current" ], "additionalProperties": false }, "primaryAxis": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "mark": { "type": "string", "enum": [ "bar", "area", "line" ] }, "groupBars": { "type": "boolean" } }, "required": [ "field", "label", "mark" ], "additionalProperties": false }, "secondaryAxis": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "dash": { "type": "string", "enum": [ "solid", "dashed" ], "default": "solid" } }, "required": [ "field", "label" ], "additionalProperties": false }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 400 } }, "required": [ "type", "data", "primaryAxis" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "funnel" }, "data": { "type": "object", "properties": { "stages": { "type": "array", "items": { "type": "string" } }, "volume": { "type": "array", "items": { "type": "number" } }, "costPer": { "type": "array", "items": { "type": "number" } } }, "required": [ "stages", "volume" ], "additionalProperties": false }, "showConversionRates": { "type": "boolean", "default": true }, "showCostPer": { "type": "boolean", "default": true }, "colorScheme": { "type": "string", "default": "Blues" }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 350 } }, "required": [ "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "waterfall" }, "data": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "number" }, "colorValue": { "type": "number" } }, "required": [ "label", "value", "colorValue" ], "additionalProperties": false } }, "colorScheme": { "type": "string", "default": "RdYlGn" }, "colorLabel": { "type": "string", "default": "CPA ($)" }, "valueLabel": { "type": "string", "default": "Cumulative Spend ($)" }, "width": { "type": "number", "default": 700 }, "height": { "type": "number" } }, "required": [ "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choropleth" }, "data": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string" }, "value": { "type": "number" }, "meta": { "type": "object", "additionalProperties": { "type": [ "string", "number", "null" ] } } }, "required": [ "state", "value" ], "additionalProperties": false } }, "valueLabel": { "type": "string" }, "colorScheme": { "type": "string", "default": "YlOrRd" }, "colorType": { "type": "string", "enum": [ "quantize", "linear", "threshold" ], "default": "quantize" }, "reverse": { "type": "boolean", "default": false }, "tip": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false } } }, "required": [ "fields" ], "additionalProperties": false }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 450 } }, "required": [ "type", "data", "valueLabel" ], "additionalProperties": false } ] } }, "required": [ "reason", "chart" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } }, "x-mcp-tool-type": "app", "x-mcp-chart-types": [ "bar", "scatter", "timeseries", "funnel", "waterfall", "choropleth" ] } }, "/tools/meta_ads_list_connections": { "post": { "operationId": "meta_ads_list_connections", "summary": "List Meta Connections", "description": "List the Meta Ads connections available to you — both ones you own and ones shared with you via an organization. Use this to discover connection IDs for set_default / share / rename / revoke.", "tags": [ "connections" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-connections": { "summary": "List connections", "value": { "reason": "User asked which Meta accounts they have connected" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_set_default_connection": { "post": { "operationId": "meta_ads_set_default_connection", "summary": "Set Default Meta Connection", "description": "Set the Meta connection that should be used by default for subsequent Meta Ads tool calls. The default is scoped to the calling actor (your user account, or the API key being used).", "tags": [ "set-default-connection" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to mark as the actor's default Meta connection." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "set-default": { "summary": "Set default", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "reason": "User picked their primary Meta workspace" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_share_connection": { "post": { "operationId": "meta_ads_share_connection", "summary": "Share Meta Connection With Organization", "description": "Share an owned Meta connection with all members of your organization, so teammates can use it without having to reconnect Meta themselves. You must be the owner of the connection.", "tags": [ "share-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to share with your organization. You must be the owner." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "share-with-org": { "summary": "Share with org", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "reason": "User asked to share this Meta connection with their teammates" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_unshare_connection": { "post": { "operationId": "meta_ads_unshare_connection", "summary": "Unshare Meta Connection From Organization", "description": "Stop sharing an owned Meta connection with your organization. Teammates lose access immediately. You must be the owner.", "tags": [ "unshare-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to stop sharing with your organization. You must be the owner." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "stop-sharing": { "summary": "Stop sharing", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "reason": "User no longer wants the team to access this Meta connection" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_rename_connection": { "post": { "operationId": "meta_ads_rename_connection", "summary": "Rename Meta Connection", "description": "Rename the display name of an owned Meta connection. The OAuth grant and underlying account are unaffected — this only changes the human-readable label. You must be the owner.", "tags": [ "rename-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to rename. You must be the owner." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "New human-readable name for the connection." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "display_name", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "rename": { "summary": "Rename", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "display_name": "Acme — Production", "reason": "User wanted a clearer label for this Meta connection" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_revoke_connection": { "post": { "operationId": "meta_ads_revoke_connection", "summary": "Revoke Meta Connection", "description": "Revoke (soft-delete) an owned Meta connection. Any defaults pointing to it are invalidated and shared org members lose access. The OAuth grant at Meta is NOT revoked by this tool — the user must disconnect via the dashboard if they want to fully revoke at Meta. You must be the owner.", "tags": [ "revoke-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to revoke. You must be the owner." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "revoke": { "summary": "Revoke", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "reason": "User asked to disconnect this Meta account" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_list_custom_conversions": { "post": { "operationId": "meta_ads_list_custom_conversions", "summary": "List Meta Custom Conversions", "description": "List custom conversion definitions for a Meta ad account, including ID, name, custom_event_type, event_source_id, rule JSON, retention_days, default_conversion_value, and description. Use this to inspect tracking setup and understand URL/event matching rules behind conversions such as offsite_conversion.fb_pixel_custom.*.", "tags": [ "custom-conversions" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "The ad account ID (with or without act_ prefix)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Custom conversions per page (default: 100, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "audit-tracking-rules": { "summary": "Audit tracking rules", "value": { "account_id": "act_123456789", "reason": "Inspect custom conversion URL and event matching rules" } }, "find-surveyclick-rule": { "summary": "Find SurveyClick rule", "value": { "account_id": "123456789", "reason": "Brief PM on how SurveyClick custom conversion is triggered" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_developer_feedback": { "post": { "operationId": "meta_ads_developer_feedback", "summary": "Submit Developer Feedback", "description": "Submit feedback about missing tools, improvements, bugs, or workflow gaps in the MCP toolset. Not for user-facing issues like auth or API errors.", "tags": [ "feedback" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "feedback_type": { "type": "string", "enum": [ "new_tool", "improvement", "bug", "workflow_gap" ], "description": "Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow)" }, "title": { "type": "string", "minLength": 5, "maxLength": 200, "description": "Concise title summarizing the feedback" }, "description": { "type": "string", "minLength": 20, "maxLength": 2000, "description": "What is needed and why" }, "current_workaround": { "type": "string", "maxLength": 1000, "description": "Current workaround, if any" }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue)" }, "interface": { "type": "string", "enum": [ "MCP", "CLI" ], "default": "MCP", "description": "Interface the feedback originated from: MCP (default) or CLI" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "feedback_type", "title", "description", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "missing-tool": { "summary": "Missing tool", "value": { "feedback_type": "new_tool", "title": "Bulk campaign status toggle", "description": "Need to pause/enable multiple campaigns at once", "priority": "high", "reason": "User asked to pause 12 campaigns individually" } }, "workflow-gap": { "summary": "Workflow gap", "value": { "feedback_type": "workflow_gap", "title": "Campaign cloning with hierarchy", "description": "No way to duplicate a campaign including adsets and ads", "current_workaround": "Read and recreate each level one by one", "reason": "User wanted to duplicate campaign structure" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_get_insights": { "post": { "operationId": "meta_ads_get_insights", "summary": "Get Meta Ads Insights", "description": "Retrieve performance metrics from Meta Ads with date presets/custom ranges, time grouping, entity-level aggregation, dimensional breakdowns, and filtering. Always fetches fresh data. Provide date_preset or time_range. For standard full-funnel analysis, prefer meta_ads_get_performance_report; use this for custom fields, hourly/creative-asset breakdowns, video metrics, or the \\", "tags": [ "insights" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Meta ad account ID" }, "date_preset": { "type": "string", "enum": [ "today", "yesterday", "this_week_mon_today", "this_week_sun_today", "last_week_mon_sun", "last_week_sun_sat", "this_month", "last_month", "this_quarter", "last_quarter", "this_year", "last_year", "last_3d", "last_7d", "last_14d", "last_28d", "last_30d", "last_90d", "lifetime", "maximum" ], "description": "Predefined date range: today, yesterday, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, this_month, last_month, this_quarter, last_quarter, this_year, last_year, lifetime, maximum" }, "time_range": { "type": "object", "properties": { "since": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "since", "until" ], "additionalProperties": false, "description": "Custom date range {since, until} in YYYY-MM-DD" }, "time_increment": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 90 }, { "type": "string", "const": "monthly" }, { "type": "string", "const": "all_days" } ], "description": "Time grouping: 1=daily, 7=weekly, or \"monthly\"" }, "level": { "type": "string", "enum": [ "account", "campaign", "adset", "ad" ], "description": "Aggregation level: account, campaign, adset, ad" }, "fields": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Metrics to retrieve (defaults to standard set)" }, "breakdowns": { "type": "array", "items": { "type": "string", "enum": [ "age", "gender", "country", "region", "dma", "device_platform", "publisher_platform", "platform_position", "impression_device", "hourly_stats_aggregated_by_advertiser_time_zone", "hourly_stats_aggregated_by_audience_time_zone", "frequency_value", "place_page_id", "product_id", "ad_format_asset", "body_asset", "call_to_action_asset", "description_asset", "image_asset", "link_url_asset", "title_asset", "video_asset", "user_segment_key" ] }, "description": "Dimensions to segment data by. Pass multiple values in a single call to get cross-tabulated rows (e.g. [\"age\",\"gender\"] → one row per \"35-44 / female\" segment). Do NOT make separate calls for each dimension. Available: age, gender, country, region, dma, device_platform, publisher_platform, platform_position, impression_device, frequency_value, place_page_id, product_id, ad_format_asset, body_asset, call_to_action_asset, description_asset, image_asset, link_url_asset, title_asset, video_asset, user_segment_key. Note: `frequency_value` is compatible only with `fields: [\"reach\"]` and cannot be combined with other breakdowns or with action_breakdowns; the tool rejects incompatible calls. Note: `user_segment_key` is the Advantage+ Shopping Campaigns \"Audience Segments\" breakdown. Returned values: prospecting, engaged, existing, unknown (lowercase). Cross-tabulation with demographic breakdowns like age is rejected by Meta's API — combine with country if needed; use separate calls for demographic splits." }, "action_breakdowns": { "type": "array", "items": { "type": "string", "enum": [ "action_type", "action_target_id", "action_destination", "action_reaction", "action_video_sound", "action_video_type", "action_carousel_card_id", "action_carousel_card_name" ] }, "description": "Action breakdown dimensions: action_type, action_target_id, action_destination, action_reaction, action_video_sound, action_video_type, action_carousel_card_id, action_carousel_card_name" }, "filtering": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Field to filter on" }, "operator": { "type": "string", "enum": [ "EQUAL", "NOT_EQUAL", "GREATER_THAN", "LESS_THAN", "IN", "NOT_IN", "CONTAIN", "NOT_CONTAIN" ], "description": "Comparison operator" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "description": "Value(s) to compare against — numbers are coerced to strings automatically" } }, "required": [ "field", "operator", "value" ], "additionalProperties": false }, "description": "Filters as [{field, operator, value}]" }, "action_attribution_windows": { "type": "array", "items": { "type": "string", "enum": [ "1d_click", "7d_click", "28d_click", "1d_view", "7d_view", "28d_view", "1d_ev", "default" ] }, "description": "Attribution windows for action/conversion metrics. Controls which click/view windows are reported. Common: [\"7d_click\"] for 7-day click only. Default (when omitted): [\"7d_click\",\"1d_view\"]. Available: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view, 1d_ev, default" }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Maximum number of rows per page (default: 100, max: 500)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "7-day-click-only-conversions": { "summary": "7-day click only conversions", "value": { "account_id": "act_123456789", "date_preset": "last_7d", "action_attribution_windows": [ "7d_click" ], "reason": "Isolate 7-day click attribution conversions for accurate ROAS measurement" } }, "age-and-gender-breakdown": { "summary": "Age and gender breakdown", "value": { "account_id": "act_123", "date_preset": "last_7d", "breakdowns": [ "age", "gender" ], "reason": "Demographic breakdown not available in performance report" } }, "publisher-platform-breakdown": { "summary": "Publisher platform breakdown", "value": { "account_id": "act_123", "date_preset": "last_7d", "level": "adset", "breakdowns": [ "publisher_platform", "platform_position" ], "reason": "Placement breakdown by publisher and position" } }, "video-asset-metrics": { "summary": "Video asset metrics", "value": { "account_id": "act_123", "date_preset": "last_7d", "level": "ad", "fields": [ "video_p25_watched_actions", "video_p50_watched_actions", "video_p75_watched_actions", "video_p100_watched_actions", "video_avg_time_watched_actions" ], "reason": "Video completion funnel for creative analysis" } }, "frequency-bucket-reach": { "summary": "Frequency-bucket reach", "value": { "account_id": "act_123", "date_preset": "last_30d", "breakdowns": [ "frequency_value" ], "fields": [ "reach" ], "reason": "Distribution of unique users by exposure frequency (1×, 2×, 3+); frequency_value is reach-only per Meta" } }, "asc-audience-segment-split-prospecting-vs-engaged-vs-existing-vs-unknown": { "summary": "ASC audience-segment split (prospecting vs engaged vs existing vs unknown)", "value": { "account_id": "act_123", "date_preset": "last_7d", "level": "campaign", "breakdowns": [ "user_segment_key" ], "filtering": [ { "field": "campaign.objective", "operator": "EQUAL", "value": "OUTCOME_SALES" } ], "reason": "Weekly WoW report for Advantage+ Shopping Campaign — split spend/conversions by acquisition (prospecting) vs retargeting (engaged) vs existing customers" } } } } } }, "responses": { "200": { "description": "JSON report data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_get_performance_report": { "post": { "operationId": "meta_ads_get_performance_report", "summary": "Get Meta Ads Performance Report", "description": "Full impression-to-conversion funnel report with delivery, engagement, actions, conversions, ROAS, and quality rankings. Supports breakdowns by device (impression_device), demographics (age, gender), geography (country, region, dma), and platform (device_platform, publisher_platform, platform_position). For Advantage+ Shopping Campaigns, supports \\", "tags": [ "reporting" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "Meta ad account ID" }, "time_range": { "type": "object", "properties": { "since": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "since", "until" ], "additionalProperties": false, "description": "Required date range {since, until} in YYYY-MM-DD" }, "time_increment": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 90 }, { "type": "string", "const": "monthly" }, { "type": "string", "const": "all_days" } ], "description": "Time grouping: 1=daily, 7=weekly, or \"monthly\"" }, "level": { "type": "string", "enum": [ "account", "campaign", "adset", "ad" ], "description": "Aggregation level (default: account): account, campaign, adset, ad" }, "breakdowns": { "type": "array", "items": { "type": "string", "enum": [ "age", "gender", "country", "region", "device_platform", "publisher_platform", "platform_position", "impression_device", "dma", "user_segment_key" ] }, "description": "Dimensions to segment data by. Pass multiple values in a single call to get cross-tabulated rows (e.g. [\"age\",\"gender\"] → one row per \"35-44 / female\" segment). Do NOT make separate calls for each dimension. Available: age, gender, country, region, device_platform, publisher_platform, platform_position, impression_device, dma, user_segment_key. Note: `user_segment_key` is the Advantage+ Shopping Campaigns \"Audience Segments\" breakdown. Returned values: prospecting, engaged, existing, unknown (lowercase). Cross-tabulation with demographic breakdowns like age is rejected by Meta's API — combine with country if needed; use separate calls for demographic splits." }, "filtering": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "description": "Field to filter on" }, "operator": { "type": "string", "enum": [ "EQUAL", "NOT_EQUAL", "GREATER_THAN", "LESS_THAN", "IN", "NOT_IN", "CONTAIN", "NOT_CONTAIN" ], "description": "Comparison operator" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "description": "Value(s) to compare against — numbers are coerced to strings automatically" } }, "required": [ "field", "operator", "value" ], "additionalProperties": false }, "description": "Filters as [{field, operator, value}]" }, "action_attribution_windows": { "type": "array", "items": { "type": "string", "enum": [ "1d_click", "7d_click", "28d_click", "1d_view", "7d_view", "28d_view", "1d_ev", "default" ] }, "description": "Attribution windows for action/conversion metrics. Controls which click/view windows are reported. Common: [\"7d_click\"] for 7-day click only. Default (when omitted): [\"7d_click\",\"1d_view\"]. Available: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view, 1d_ev, default" }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Maximum number of rows per page (default: 100, max: 500)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "time_range", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "account-overview": { "summary": "Account overview", "value": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "reason": "Monthly performance review" } }, "campaign-comparison": { "summary": "Campaign comparison", "value": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "level": "campaign", "reason": "Compare campaign performance" } }, "daily-trend": { "summary": "Daily trend", "value": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-07" }, "time_increment": 1, "reason": "Daily performance trend" } }, "demographics": { "summary": "Demographics", "value": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "breakdowns": [ "age", "gender" ], "reason": "Demographic analysis" } }, "device-breakdown": { "summary": "Device breakdown", "value": { "account_id": "act_123", "date_preset": "last_30d", "level": "campaign", "breakdowns": [ "impression_device" ], "reason": "Device performance analysis" } }, "7-day-click-attribution-report": { "summary": "7-day click attribution report", "value": { "account_id": "act_123456789", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "action_attribution_windows": [ "7d_click" ], "reason": "Full-funnel report scoped to 7-day click attribution only" } }, "asc-audience-segment-performance-report": { "summary": "ASC audience-segment performance report", "value": { "account_id": "act_123", "time_range": { "since": "2024-01-01", "until": "2024-01-31" }, "level": "campaign", "breakdowns": [ "user_segment_key" ], "filtering": [ { "field": "campaign.objective", "operator": "EQUAL", "value": "OUTCOME_SALES" } ], "reason": "ASC audience segments — full-funnel report split by prospecting vs engaged vs existing vs unknown" } } } } } }, "responses": { "200": { "description": "JSON report data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_ping": { "post": { "operationId": "meta_ads_ping", "summary": "Ping Meta Ads MCP Server", "description": "Health check for the Meta Ads MCP server.", "tags": [ "auth" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 100, "description": "Optional message to echo back" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "health-check": { "summary": "Health check", "value": { "reason": "Verify server is running" } }, "with-message": { "summary": "With message", "value": { "message": "hello", "reason": "Test connectivity" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/meta_ads_get_pixel_health": { "post": { "operationId": "meta_ads_get_pixel_health", "summary": "Get Meta Pixel Health", "description": "Comprehensive pixel health check: metadata, CAPI connection status, event volume stats, automatic matching config, and diagnostic checks (including event match quality indicators). capi.connected is true when an active CAPI Gateway config exists or server events were observed in the lookback window (capi.server_event_count), false when both signals were readable and showed neither, and \"unknown\" when the signals could not be read — NEVER report CAPI as disconnected when it is \"unknown\"; tell the user to verify in Meta Events Manager instead. Use this to diagnose tracking issues before analyzing ad performance — low ROAS could be a tracking problem, not a campaign problem. When event_stats_status is \"permission_denied\", surface event_stats_message to the user — the rest of the pixel health audit is still valid.", "tags": [ "pixel-health" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1, "description": "The ad account ID (with or without act_ prefix)" }, "pixel_id": { "type": "string", "minLength": 1, "description": "Specific pixel ID to check. If omitted, checks all pixels on the account." }, "event_names": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Filter event stats to these event names (e.g. [\"Purchase\", \"Lead\"])" }, "days_back": { "type": "integer", "minimum": 1, "maximum": 90, "default": 28, "description": "Number of days of event stats to include (default: 28, max: 90)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5, "description": "Max pixels per page (default: 5, max: 20)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "account_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "all-pixels-for-account": { "summary": "All pixels for account", "value": { "account_id": "act_123", "reason": "Audit tracking setup" } }, "specific-pixel": { "summary": "Specific pixel", "value": { "account_id": "act_123", "pixel_id": "456", "reason": "Check pixel firing status" } }, "filter-to-key-events": { "summary": "Filter to key events", "value": { "account_id": "act_123", "event_names": [ "Purchase", "Lead" ], "days_back": 7, "reason": "Check tracking health for key events" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Supabase JWT or hpk_live_... API key" } }, "schemas": { "McpToolResult": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "resource_link" ] }, "text": { "type": "string" } } } }, "structuredContent": { "type": "object", "additionalProperties": true }, "isError": { "type": "boolean" } } }, "McpError": { "type": "object", "properties": { "isError": { "type": "boolean", "const": true }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } }, "RestError": { "type": "object", "description": "Error response from REST tool endpoints (mapped from JSON-RPC error codes)", "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "integer", "description": "JSON-RPC error code" }, "data": { "description": "Additional error context" } }, "required": [ "error", "code" ] }, "ToolList": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": true } } } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "discovery", "description": "Tool discovery and introspection" }, { "name": "account-summary", "description": "Account-summary tools" }, { "name": "activities", "description": "Activities tools" }, { "name": "ad-accounts", "description": "Ad-accounts tools" }, { "name": "ads", "description": "Ads tools" }, { "name": "adsets", "description": "Adsets tools" }, { "name": "auth", "description": "Auth tools" }, { "name": "campaigns", "description": "Campaigns tools" }, { "name": "chart", "description": "Chart tools" }, { "name": "connections", "description": "Connections tools" }, { "name": "custom-conversions", "description": "Custom-conversions tools" }, { "name": "feedback", "description": "Feedback tools" }, { "name": "insights", "description": "Insights tools" }, { "name": "pixel-health", "description": "Pixel-health tools" }, { "name": "rename-connection", "description": "Rename-connection tools" }, { "name": "reporting", "description": "Reporting tools" }, { "name": "revoke-connection", "description": "Revoke-connection tools" }, { "name": "search-ad-library", "description": "Search-ad-library tools" }, { "name": "set-default-connection", "description": "Set-default-connection tools" }, { "name": "share-connection", "description": "Share-connection tools" }, { "name": "unshare-connection", "description": "Unshare-connection tools" } ] }