{ "openapi": "3.1.0", "info": { "title": "TikTok Ads MCP Server", "description": "TikTok Marketing API for short-form video advertising", "version": "1.0.0", "contact": { "name": "Hopkin", "url": "https://hopkin.ai" } }, "servers": [ { "url": "https://tiktok.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/tiktok_ads_list_ad_groups": { "post": { "operationId": "tiktok_ads_list_ad_groups", "summary": "List TikTok Ad Groups", "description": "List TikTok ad groups for an advertiser. Shows name, status, targeting, and budget.", "tags": [ "ad-groups" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results to return (1–100). Default: 20." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "refresh": { "type": "boolean", "default": false, "description": "Force a fresh fetch bypassing the cache." }, "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "adgroup_id": { "type": "string", "description": "Fetch a single ad group by ID." }, "adgroup_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific ad groups by IDs." }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Filter by parent campaign IDs." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "STATUS_ALL", "STATUS_ON", "STATUS_OFF", "STATUS_BUDGET_EXCEED", "STATUS_DONE", "STATUS_DELETE" ] }, "description": "Filter by primary status." }, "search": { "type": "string", "description": "Search ad groups by name (case-insensitive)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "reason" ], "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" } } } } } } }, "/tools/tiktok_ads_get_ad_group": { "post": { "operationId": "tiktok_ads_get_ad_group", "summary": "Get TikTok Ad Group", "description": "Get details for a single TikTok ad group by ID.", "tags": [ "ad-group" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "adgroup_id": { "type": "string", "minLength": 1, "description": "Ad group ID." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "adgroup_id", "reason" ], "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" } } } } } } }, "/tools/tiktok_ads_list_ads": { "post": { "operationId": "tiktok_ads_list_ads", "summary": "List TikTok Ads", "description": "List TikTok ads for an advertiser. Shows name, status, creative, and ad group association.", "tags": [ "ads" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results to return (1–100). Default: 20." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "refresh": { "type": "boolean", "default": false, "description": "Force a fresh fetch bypassing the cache." }, "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "ad_id": { "type": "string", "description": "Fetch a single ad by ID." }, "ad_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific ads by IDs." }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Filter by parent campaign IDs." }, "adgroup_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Filter by parent ad group IDs." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "STATUS_ALL", "STATUS_ON", "STATUS_OFF", "STATUS_BUDGET_EXCEED", "STATUS_DONE", "STATUS_DELETE" ] }, "description": "Filter by primary status." }, "search": { "type": "string", "description": "Search ads by name (case-insensitive)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "reason" ], "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" } } } } } } }, "/tools/tiktok_ads_get_ad": { "post": { "operationId": "tiktok_ads_get_ad", "summary": "Get TikTok Ad", "description": "Get details for a single TikTok ad by ID.", "tags": [ "ad" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "ad_id": { "type": "string", "minLength": 1, "description": "Ad ID." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "ad_id", "reason" ], "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" } } } } } } }, "/tools/tiktok_ads_list_advertisers": { "post": { "operationId": "tiktok_ads_list_advertisers", "summary": "List TikTok Advertisers", "description": "List TikTok advertiser accounts accessible to the authenticated user. Shows name, ID, status, currency, and timezone.", "tags": [ "advertisers" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results to return (1–100). Default: 20." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "refresh": { "type": "boolean", "default": false, "description": "Force a fresh fetch bypassing the cache." }, "advertiser_id": { "type": "string", "description": "Fetch a single advertiser by ID." }, "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#" } } } }, "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/tiktok_ads_get_advertiser": { "post": { "operationId": "tiktok_ads_get_advertiser", "summary": "Get TikTok Advertiser", "description": "Get details for a single TikTok advertiser by ID.", "tags": [ "advertiser" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "reason" ], "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" } } } } } } }, "/tools/tiktok_ads_list_audiences": { "post": { "operationId": "tiktok_ads_list_audiences", "summary": "List TikTok Audiences", "description": "List custom and lookalike audiences for a TikTok advertiser.", "tags": [ "audiences" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results to return (1–100). Default: 20." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "refresh": { "type": "boolean", "default": false, "description": "Force a fresh fetch bypassing the cache." }, "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "reason" ], "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" } } } } } } }, "/tools/tiktok_ads_check_auth_status": { "post": { "operationId": "tiktok_ads_check_auth_status", "summary": "Check TikTok Ads Authentication Status", "description": "Check whether the user's TikTok Ads account is authenticated. Returns auth method and email. Use ONLY when the user asks about auth status or connectivity — to get advertiser accounts, use tiktok_ads_list_advertisers instead.", "tags": [ "auth" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "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#" } } } }, "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/tiktok_ads_get_login_url": { "post": { "operationId": "tiktok_ads_get_login_url", "summary": "Get TikTok Ads Login URL", "description": "Get the URL to connect a TikTok Ads account via OAuth.", "tags": [ "login-url" ], "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#" } } } }, "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/tiktok_ads_get_user_info": { "post": { "operationId": "tiktok_ads_get_user_info", "summary": "Get TikTok Ads User Info", "description": "Get detailed profile information about the authenticated TikTok Ads user (email, display name, role). Use this for user profile details — for checking auth status or listing advertiser IDs, use tiktok_ads_check_auth_status instead.", "tags": [ "user-info" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "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#" } } } }, "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/tiktok_ads_list_campaigns": { "post": { "operationId": "tiktok_ads_list_campaigns", "summary": "List TikTok Campaigns", "description": "List TikTok ad campaigns for an advertiser. Shows name, status, objective, and budget.", "tags": [ "campaigns" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of results to return (1–100). Default: 20." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "refresh": { "type": "boolean", "default": false, "description": "Force a fresh fetch bypassing the cache." }, "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "campaign_id": { "type": "string", "description": "Fetch a single campaign by ID." }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific campaigns by IDs." }, "status": { "type": "array", "items": { "type": "string", "enum": [ "STATUS_ALL", "STATUS_ON", "STATUS_OFF", "STATUS_BUDGET_EXCEED", "STATUS_DONE", "STATUS_DELETE" ] }, "description": "Filter by primary status." }, "search": { "type": "string", "description": "Search campaigns by name (case-insensitive)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "reason" ], "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" } } } } } } }, "/tools/tiktok_ads_get_campaign": { "post": { "operationId": "tiktok_ads_get_campaign", "summary": "Get TikTok Campaign", "description": "Get details for a single TikTok campaign by ID.", "tags": [ "campaign" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "campaign_id": { "type": "string", "minLength": 1, "description": "Campaign ID." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "campaign_id", "reason" ], "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" } } } } } } }, "/tools/tiktok_ads_list_connections": { "post": { "operationId": "tiktok_ads_list_connections", "summary": "List TikTok Connections", "description": "List the TikTok 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 TikTok 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/tiktok_ads_set_default_connection": { "post": { "operationId": "tiktok_ads_set_default_connection", "summary": "Set Default TikTok Connection", "description": "Set the TikTok connection that should be used by default for subsequent TikTok 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 TikTok 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 TikTok 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/tiktok_ads_share_connection": { "post": { "operationId": "tiktok_ads_share_connection", "summary": "Share TikTok Connection With Organization", "description": "Share an owned TikTok connection with all members of your organization, so teammates can use it without having to reconnect TikTok 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 TikTok 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/tiktok_ads_unshare_connection": { "post": { "operationId": "tiktok_ads_unshare_connection", "summary": "Unshare TikTok Connection From Organization", "description": "Stop sharing an owned TikTok 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 TikTok 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/tiktok_ads_rename_connection": { "post": { "operationId": "tiktok_ads_rename_connection", "summary": "Rename TikTok Connection", "description": "Rename the display name of an owned TikTok 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 TikTok 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/tiktok_ads_revoke_connection": { "post": { "operationId": "tiktok_ads_revoke_connection", "summary": "Revoke TikTok Connection", "description": "Revoke (soft-delete) an owned TikTok connection. Any defaults pointing to it are invalidated and shared org members lose access. The OAuth grant at TikTok is NOT revoked by this tool — the user must disconnect via the dashboard if they want to fully revoke at TikTok. 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 TikTok 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/tiktok_ads_preview_ads": { "post": { "operationId": "tiktok_ads_preview_ads", "summary": "Preview TikTok Ads", "description": "Preview TikTok ad creatives with visual content (images/videos) and configurable metrics in an interactive UI.", "tags": [ "ads" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser 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": [ "advertiser_id", "ads", "reason" ], "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" } }, "/tools/tiktok_ads_developer_feedback": { "post": { "operationId": "tiktok_ads_developer_feedback", "summary": "Submit Developer Feedback", "description": "Submit feedback about missing tools, improvements, bugs, or workflow gaps in the TikTok Ads 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#" } } } }, "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/tiktok_ads_ping": { "post": { "operationId": "tiktok_ads_ping", "summary": "Ping TikTok Ads MCP Server", "description": "Health check for the TikTok 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#" } } } }, "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/tiktok_ads_get_performance_report": { "post": { "operationId": "tiktok_ads_get_performance_report", "summary": "Get TikTok Ads Performance Report", "description": "Get a performance report for a TikTok advertiser. Returns spend, impressions, clicks, CPC, CPM, CTR, reach, frequency, conversions, cost_per_conversion, conversion_rate, result, and cost_per_result — broken down by day. Supports entity filters: pass campaign_id to get only ads/ad groups within a specific campaign, or adgroup_id to narrow to a specific ad group. This is the primary tool for standard delivery and conversion performance — use get_insights only for audience demographic breakdowns (age, gender, country).", "tags": [ "reporting" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "level": { "type": "string", "enum": [ "campaign", "adgroup", "ad" ], "description": "Reporting level — mapped to data_level internally." }, "date_preset": { "type": "string", "enum": [ "last_7d", "last_14d", "last_30d" ], "description": "Shortcut date range. Overridden by explicit start_date/end_date." }, "start_date": { "type": "string", "description": "Start date in YYYY-MM-DD format." }, "end_date": { "type": "string", "description": "End date in YYYY-MM-DD format." }, "campaign_id": { "type": "string", "description": "Filter results to a specific campaign by its ID. When the user asks about a specific campaign, always pass this parameter to scope the report." }, "adgroup_id": { "type": "string", "description": "Filter to a specific ad group." }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (1-indexed). Default: 1." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20, "description": "Results per page. Default: 20." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "level", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "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/tiktok_ads_get_insights": { "post": { "operationId": "tiktok_ads_get_insights", "summary": "Get TikTok Ads Insights", "description": "Get audience demographic breakdowns and custom dimension analysis for TikTok ads (age, gender, country, placement). Use this only when you need demographic or placement-level segmentation. For standard performance metrics (spend, clicks, conversions, CPC, CPM, CTR, cost_per_conversion, conversion_rate), use tiktok_ads_get_performance_report instead — it already includes all conversion metrics. For video/creative metrics, use tiktok_ads_get_creative_report.", "tags": [ "insights" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "report_type": { "type": "string", "enum": [ "BASIC", "AUDIENCE" ], "default": "BASIC", "description": "Type of report. AUDIENCE for demographic breakdowns (age, gender, country). Default: BASIC." }, "data_level": { "type": "string", "enum": [ "AUCTION_ADVERTISER", "AUCTION_CAMPAIGN", "AUCTION_ADGROUP", "AUCTION_AD" ], "description": "Granularity level for the report." }, "dimensions": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Grouping dimensions, e.g. [\"campaign_id\", \"stat_time_day\"]." }, "metrics": { "type": "array", "items": { "type": "string" }, "description": "Metrics to retrieve. Defaults to standard funnel metrics if omitted." }, "start_date": { "type": "string", "description": "Start date in YYYY-MM-DD format." }, "end_date": { "type": "string", "description": "End date in YYYY-MM-DD format." }, "lifetime": { "type": "boolean", "description": "If true, return lifetime metrics instead of date-ranged." }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (1-indexed). Default: 1." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20, "description": "Results per page. Default: 20." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "data_level", "dimensions", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "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/tiktok_ads_get_creative_report": { "post": { "operationId": "tiktok_ads_get_creative_report", "summary": "Get TikTok Ads Creative Report", "description": "Get video creative performance metrics for TikTok ads — video views, watch time, completion rates (p25/p50/p75/p100), engagement, and per-creative breakdowns. Supports filtering by campaign_id or adgroup_id to narrow results. Use this tool for video-specific metrics and creative-level analysis.", "tags": [ "creative-report" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser ID." }, "campaign_id": { "type": "string", "description": "Filter to a specific campaign." }, "adgroup_id": { "type": "string", "description": "Filter to a specific ad group." }, "start_date": { "type": "string", "description": "Start date in YYYY-MM-DD format." }, "end_date": { "type": "string", "description": "End date in YYYY-MM-DD format." }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (1-indexed). Default: 1." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20, "description": "Results per page. Default: 20." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "reason" ], "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" } } } } } } }, "/tools/tiktok_ads_get_smart_plus_report": { "post": { "operationId": "tiktok_ads_get_smart_plus_report", "summary": "Get TikTok Smart+ Creative Material Report", "description": "Get Smart+ creative material performance breakdown. Use this when analyzing Smart+ campaign creative variants — breaks down performance by creative material (video/image), text, and enhancement (CTA) combinations. Required for accurate Smart+ reporting, as the standard reporting tools only show parent ad-level data.", "tags": [ "smart-plus-report" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser account ID." }, "dimensions": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Creative dimensions to break down by. Examples: material/creative type, text, enhancement/CTA." }, "start_date": { "type": "string", "description": "Start date in YYYY-MM-DD format." }, "end_date": { "type": "string", "description": "End date in YYYY-MM-DD format." }, "metrics": { "type": "array", "items": { "type": "string" }, "description": "Metrics to retrieve. Defaults to spend, impressions, clicks, conversions, and cost metrics." }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by campaign IDs." }, "adgroup_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by ad group IDs." }, "smart_plus_ad_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by Smart+ ad IDs." }, "main_material_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by material (video/image) IDs." }, "main_material_types": { "type": "array", "items": { "type": "string" }, "description": "Filter by material types." }, "sort_field": { "type": "string", "default": "spend", "description": "Sort by field. Default: spend." }, "sort_type": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC", "description": "Sort direction. Default: DESC." }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (1-indexed). Default: 1." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20, "description": "Results per page. Default: 20." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "dimensions", "start_date", "end_date", "reason" ], "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" } } } } } } }, "/tools/tiktok_ads_get_smart_plus_overview": { "post": { "operationId": "tiktok_ads_get_smart_plus_overview", "summary": "Get TikTok Smart+ Creative Material Overview", "description": "Get Smart+ creative material overview. Returns aggregate performance summaries for Smart+ creative materials with optional lifetime queries. Use alongside tiktok_ads_get_smart_plus_report for full Smart+ creative analysis.", "tags": [ "smart-plus-overview" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser_id": { "type": "string", "minLength": 1, "description": "TikTok advertiser account ID." }, "dimensions": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Creative dimensions to group by." }, "start_date": { "type": "string", "description": "Start date in YYYY-MM-DD format." }, "end_date": { "type": "string", "description": "End date in YYYY-MM-DD format." }, "query_lifetime": { "type": "boolean", "description": "If true, return lifetime metrics instead of date-ranged." }, "metrics": { "type": "array", "items": { "type": "string" }, "description": "Metrics to retrieve." }, "campaign_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by campaign IDs." }, "adgroup_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by ad group IDs." }, "smart_plus_ad_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter by Smart+ ad IDs." }, "sort_field": { "type": "string", "default": "spend", "description": "Sort by field. Default: spend." }, "sort_type": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC", "description": "Sort direction. Default: DESC." }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (1-indexed). Default: 1." }, "page_size": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20, "description": "Results per page. Default: 20." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "advertiser_id", "dimensions", "reason" ], "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" } } } } } } } }, "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": "ad", "description": "Ad tools" }, { "name": "ad-group", "description": "Ad-group tools" }, { "name": "ad-groups", "description": "Ad-groups tools" }, { "name": "ads", "description": "Ads tools" }, { "name": "advertiser", "description": "Advertiser tools" }, { "name": "advertisers", "description": "Advertisers tools" }, { "name": "audiences", "description": "Audiences tools" }, { "name": "auth", "description": "Auth tools" }, { "name": "campaign", "description": "Campaign tools" }, { "name": "campaigns", "description": "Campaigns tools" }, { "name": "connections", "description": "Connections tools" }, { "name": "creative-report", "description": "Creative-report tools" }, { "name": "feedback", "description": "Feedback tools" }, { "name": "insights", "description": "Insights tools" }, { "name": "login-url", "description": "Login-url tools" }, { "name": "rename-connection", "description": "Rename-connection tools" }, { "name": "reporting", "description": "Reporting tools" }, { "name": "revoke-connection", "description": "Revoke-connection tools" }, { "name": "set-default-connection", "description": "Set-default-connection tools" }, { "name": "share-connection", "description": "Share-connection tools" }, { "name": "smart-plus-overview", "description": "Smart-plus-overview tools" }, { "name": "smart-plus-report", "description": "Smart-plus-report tools" }, { "name": "unshare-connection", "description": "Unshare-connection tools" }, { "name": "user-info", "description": "User-info tools" } ] }