{ "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 include _stored_preferences and optionally 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. 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" ] }, "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" } } } } } }, "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). A \"Landing Page URLs\" summary section at the end of the response lists all unique destination URLs found — use this to quickly answer landing page questions without reading every ad. Set include_assets=true to include resolved creative media URLs (adds latency for cache misses). Entities may include _stored_preferences, optionally 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 ad status: ACTIVE, PAUSED, DELETED, ARCHIVED" }, "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" } }, "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 include _stored_preferences, optionally 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 ad set status: ACTIVE, PAUSED, DELETED, ARCHIVED" }, "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" } }, "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 include _stored_preferences, optionally 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 campaign status: ACTIVE, PAUSED, DELETED, ARCHIVED" }, "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" } }, "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_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, or video metrics.", "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" ] }, "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" }, "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" } } } } } }, "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). Preferred over meta_ads_get_insights for standard analysis. Use get_insights only for custom fields, hourly/creative-asset breakdowns, or video metrics. 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" }, "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" ] }, "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" }, "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" } } } } } }, "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). Use this to diagnose tracking issues before analyzing ad performance — low ROAS could be a tracking problem, not a campaign problem.", "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" } } } } } } }, "/tools/meta_ads_store_preference": { "post": { "operationId": "meta_ads_store_preference", "summary": "Store Meta Ads Preference", "description": "Store a persistent preference for a Meta ad entity. Use when you infer a recurring preference about analysis, reporting, or management. Updates existing keys.", "tags": [ "preferences" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "ad_account", "campaign", "ad_set", "ad" ], "description": "Type of ad entity: ad_account, campaign, ad_set (Meta ad sets / Google ad groups), or ad" }, "entity_id": { "type": "string", "minLength": 1, "description": "The platform entity ID (e.g. act_123456, 23842453456789)" }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Preference key (e.g. preferred_conversion_metric, budget_alert_threshold)" }, "value": { "description": "Preference value — string, number, boolean, or JSON object" }, "source": { "type": "string", "enum": [ "agent", "user", "system" ], "default": "agent", "description": "Who set this preference: agent (default), user, or system" }, "note": { "type": "string", "maxLength": 500, "description": "Optional context about why this preference was set" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "entity_type", "entity_id", "key", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "set-metric": { "summary": "Set metric", "value": { "entity_type": "ad_account", "entity_id": "act_123", "key": "preferred_conversion_metric", "value": "ROAS", "reason": "User wants ROAS as default metric" } }, "set-threshold": { "summary": "Set threshold", "value": { "entity_type": "campaign", "entity_id": "456", "key": "budget_alert_threshold", "value": 0.8, "reason": "Alert at 80% budget" } } } } } }, "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_preferences": { "post": { "operationId": "meta_ads_get_preferences", "summary": "Get Meta Ads Preferences", "description": "Get all stored preferences for a Meta ad entity. Preferences are also auto-attached to list tool responses as _stored_preferences.", "tags": [ "preferences" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "ad_account", "campaign", "ad_set", "ad" ], "description": "Type of ad entity: ad_account, campaign, ad_set, or ad" }, "entity_id": { "type": "string", "minLength": 1, "description": "The platform entity ID" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "entity_type", "entity_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "get-prefs": { "summary": "Get prefs", "value": { "entity_type": "ad_account", "entity_id": "act_123", "reason": "Check stored preferences" } } } } } }, "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_delete_preference": { "post": { "operationId": "meta_ads_delete_preference", "summary": "Delete Meta Ads Preference", "description": "Delete a stored preference by key. No-op if it doesn't exist.", "tags": [ "preferences" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "ad_account", "campaign", "ad_set", "ad" ], "description": "Type of ad entity: ad_account, campaign, ad_set, or ad" }, "entity_id": { "type": "string", "minLength": 1, "description": "The platform entity ID" }, "key": { "type": "string", "minLength": 1, "description": "The preference key to delete" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "entity_type", "entity_id", "key", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "delete-pref": { "summary": "Delete pref", "value": { "entity_type": "campaign", "entity_id": "456", "key": "budget_alert_threshold", "reason": "User no longer wants budget alerts" } } } } } }, "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": "feedback", "description": "Feedback tools" }, { "name": "insights", "description": "Insights tools" }, { "name": "pixel-health", "description": "Pixel-health tools" }, { "name": "preferences", "description": "Preferences tools" }, { "name": "reporting", "description": "Reporting tools" }, { "name": "search-ad-library", "description": "Search-ad-library tools" } ] }