{ "openapi": "3.1.0", "info": { "title": "ChatGPT Ads MCP Server", "description": "ChatGPT Ads (OpenAI Ads) API for campaign structure and delivery reporting — read-only", "version": "1.0.0", "contact": { "name": "Hopkin", "url": "https://hopkin.ai" } }, "servers": [ { "url": "https://chatgpt.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/chatgpt_ads_get_ad_account": { "post": { "operationId": "chatgpt_ads_get_ad_account", "summary": "Get ChatGPT Ads Account", "description": "Get details of the ChatGPT Ads account: name, status, currency, timezone, website, and review status.\n\nEach ChatGPT Ads API key is scoped to exactly one ad account, so this returns the account behind the resolved connection. Use chatgpt_ads_list_ad_accounts to see every account you can reach, and pass connection_id to pick one.\n\nWorth calling before reporting: every spend figure is in this account's currency, and every insights date bucket is a day in this account's timezone.", "tags": [ "ad-account" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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": { "account-details": { "summary": "Account details", "value": { "reason": "Check account currency and timezone before reporting" } }, "specific-connection": { "summary": "Specific connection", "value": { "connection_id": "00000000-0000-0000-0000-000000000000", "reason": "Inspect a particular connected 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/chatgpt_ads_check_auth_status": { "post": { "operationId": "chatgpt_ads_check_auth_status", "summary": "Check ChatGPT Ads Auth Status", "description": "Check whether a ChatGPT Ads API key is connected and still accepted by the platform.\n\nDo NOT call this proactively — call the tool you actually need. Use this only after another tool fails with a permission or authentication error.", "tags": [ "auth" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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": { "verify-connection": { "summary": "Verify connection", "value": { "reason": "A tool call failed with a permission error" } } } } } }, "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/chatgpt_ads_list_ad_accounts": { "post": { "operationId": "chatgpt_ads_list_ad_accounts", "summary": "List ChatGPT Ads Accounts", "description": "List the ChatGPT Ads accounts you can reach.\n\nEach ChatGPT Ads API key is scoped to exactly one ad account, and the platform has no account-listing endpoint — so this lists your connected accounts, one per API key you have added. Use the returned connection_id to target a specific account in other tools, and chatgpt_ads_get_ad_account for live details (currency, timezone, review status).", "tags": [ "ad-accounts" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "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/chatgpt_ads_list_connections": { "post": { "operationId": "chatgpt_ads_list_connections", "summary": "List ChatGPT Ads Connections", "description": "List the ChatGPT Ads connections available to you — both those you own and those shared with you by your organization. Shows each connection's display name, id, and whether it is your default.", "tags": [ "connections" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "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/chatgpt_ads_set_default_connection": { "post": { "operationId": "chatgpt_ads_set_default_connection", "summary": "Set Default ChatGPT Ads Connection", "description": "Set which ChatGPT Ads connection other tools use when no connection_id is passed. Call chatgpt_ads_list_connections first to get a valid connection_id — do not guess one.", "tags": [ "set-default-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "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 ChatGPT Ads 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#" } } } }, "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/chatgpt_ads_rename_connection": { "post": { "operationId": "chatgpt_ads_rename_connection", "summary": "Rename ChatGPT Ads Connection", "description": "Change a connection's display name. Owner-only.", "tags": [ "rename-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "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 ChatGPT Ads 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#" } } } }, "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/chatgpt_ads_share_connection": { "post": { "operationId": "chatgpt_ads_share_connection", "summary": "Share ChatGPT Ads Connection", "description": "Share an owned connection with your organization so teammates can report on that ad account. Owner-only. Note the ChatGPT Ads API has no reduced-scope keys, so sharing grants full read access to the whole ad account.", "tags": [ "share-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "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 ChatGPT Ads 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#" } } } }, "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/chatgpt_ads_unshare_connection": { "post": { "operationId": "chatgpt_ads_unshare_connection", "summary": "Unshare ChatGPT Ads Connection", "description": "Stop sharing an owned connection with your organization. Owner-only.", "tags": [ "unshare-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "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 ChatGPT Ads 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#" } } } }, "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/chatgpt_ads_revoke_connection": { "post": { "operationId": "chatgpt_ads_revoke_connection", "summary": "Revoke ChatGPT Ads Connection", "description": "Remove a stored ChatGPT Ads connection. Owner-only.\n\nThis deletes Hopkin's stored copy of the API key only. The key stays valid on the ChatGPT Ads platform — the API has no revocation endpoint — so tell the user to delete it in ChatGPT Ads Manager → Settings if they want it to stop working everywhere.", "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 mark as the actor's default ChatGPT Ads 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#" } } } }, "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/chatgpt_ads_developer_feedback": { "post": { "operationId": "chatgpt_ads_developer_feedback", "summary": "Submit Developer Feedback", "description": "Submit feedback about missing tools, improvements, bugs, or workflow gaps in the ChatGPT Ads MCP toolset. Not for user-facing issues (auth errors, API errors).\n\nArgs:\n feedback_type: new_tool, improvement, bug, workflow_gap\n title: Short description (5-200 chars)\n description: What is needed and why (20-2000 chars)\n current_workaround (optional): How you're working around the gap\n priority (optional): low, medium (default), high\n\nReturns: confirmation that feedback was recorded.", "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": "Custom audience listing", "description": "Need a tool to list ChatGPT Ads custom audiences and their match rates", "priority": "medium", "reason": "User asked to audit audience targeting" } }, "workflow-gap": { "summary": "Workflow gap", "value": { "feedback_type": "workflow_gap", "title": "Account-wide ad listing", "description": "Listing every ad in an account requires walking campaigns then ad groups then ads", "current_workaround": "Traverse the hierarchy tool by tool", "reason": "User asked for all ads at once" } } } } } }, "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/chatgpt_ads_list_campaigns": { "post": { "operationId": "chatgpt_ads_list_campaigns", "summary": "List ChatGPT Ads Campaigns", "description": "List campaigns in the ChatGPT Ads account, with optional status and name filtering.\n\nBudget and bid amounts are integer micros (1,000,000 micros = 1 unit of the account currency — see chatgpt_ads_get_ad_account).\n\nPass campaign_ids to resolve specific campaigns by ID instead of listing.\n\nCache-first: pass refresh: true to force a live fetch.", "tags": [ "campaigns" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "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." }, "campaign_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific campaigns by ID instead of listing, e.g. [\"cmpn_abc123\"]. Other filters are ignored when set." }, "status": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 20, "description": "Filter by status: active, paused or archived. Case-insensitive. Applied client-side — the API has no status filter." }, "search": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Filter by name (case-insensitive substring match)." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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": { "all-campaigns": { "summary": "All campaigns", "value": { "reason": "Show the account structure" } }, "active-only": { "summary": "Active only", "value": { "status": [ "active" ], "reason": "Review what is currently delivering" } }, "by-id": { "summary": "By ID", "value": { "campaign_ids": [ "cmpn_abc123" ], "reason": "Resolve a campaign id from an insights row" } } } } } }, "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/chatgpt_ads_list_ad_groups": { "post": { "operationId": "chatgpt_ads_list_ad_groups", "summary": "List ChatGPT Ads Ad Groups", "description": "List ad groups in a campaign. campaign_id is required — the ChatGPT Ads API has no account-wide ad group listing, so start from chatgpt_ads_list_campaigns and drill down.\n\nPass ad_group_ids to resolve specific ad groups by ID instead of listing.\n\nEach returned ad group carries the campaign_id you requested; the API itself does not return it on the ad group object.", "tags": [ "ad-groups" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "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." }, "campaign_id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "Campaign to list ad groups for (e.g. \"cmpn_abc123\"). Required — the API has no account-wide ad group listing. Get one from chatgpt_ads_list_campaigns." }, "ad_group_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific ad groups by ID instead of listing, e.g. [\"adgrp_abc123\"]. Other filters are ignored when set." }, "status": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 20, "description": "Filter by status: active, paused or archived. Case-insensitive. Applied client-side — the API has no status filter." }, "search": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Filter by name (case-insensitive substring match)." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "campaign_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "for-a-campaign": { "summary": "For a campaign", "value": { "campaign_id": "cmpn_abc123", "reason": "Drill into a campaign" } }, "by-id": { "summary": "By ID", "value": { "campaign_id": "cmpn_abc123", "ad_group_ids": [ "adgrp_abc123" ], "reason": "Resolve a specific ad group" } } } } } }, "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/chatgpt_ads_list_ads": { "post": { "operationId": "chatgpt_ads_list_ads", "summary": "List ChatGPT Ads Ads", "description": "List ads in an ad group, including creative and review status. Either ad_group_id or ad_ids is required — the API has no account-wide or campaign-wide ad listing, so drill down via chatgpt_ads_list_ad_groups.\n\nAn ad only delivers when it is approved AND its ad group and campaign are both active, so check review_status when an ad is not spending — filter on it with review_status: [\"rejected\"].\n\nPass ad_ids to resolve specific ads by ID without knowing their ad group. That is the way back from an insights row, which carries ad_id but no other context.\n\nEach returned ad carries the ad_group_id you requested; the API does not return it on the ad object.", "tags": [ "ads" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "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." }, "ad_group_id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "Ad group to list ads for (e.g. \"adgrp_abc123\"). Required unless ad_ids is given — the API has no account-wide or campaign-wide ad listing. Get one from chatgpt_ads_list_ad_groups." }, "ad_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "minItems": 1, "maxItems": 50, "description": "Fetch specific ads by ID instead of listing, e.g. [\"ad_abc123\"]. Works without ad_group_id, and other filters are ignored when set." }, "status": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 20, "description": "Filter by status: active, paused or archived. Case-insensitive. Applied client-side — the API has no status filter." }, "review_status": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "minItems": 1, "maxItems": 10, "description": "Filter by review status: approved, in_review or rejected. Case-insensitive. An ad only delivers once approved. Applied client-side." }, "search": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Filter by name (case-insensitive substring match)." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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": { "for-an-ad-group": { "summary": "For an ad group", "value": { "ad_group_id": "adgrp_abc123", "reason": "Review creatives and review status" } }, "by-id": { "summary": "By ID", "value": { "ad_ids": [ "ad_abc123" ], "reason": "Resolve an ad id from an insights row" } }, "not-approved": { "summary": "Not approved", "value": { "ad_group_id": "adgrp_abc123", "review_status": [ "rejected", "in_review" ], "reason": "Find ads blocked from delivering" } } } } } }, "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/chatgpt_ads_get_insights": { "post": { "operationId": "chatgpt_ads_get_insights", "summary": "Get ChatGPT Ads Insights", "description": "Delivery reporting for the ChatGPT Ads account: impressions, clicks, spend, ctr, cpc, cpm. These six are the only metrics the API exposes.\n\nThis is the performance report for ChatGPT Ads — there is no separate report tool on this server.\n\nScope vs rows: \\", "tags": [ "insights" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "ad_account", "campaign", "ad_group", "ad" ], "default": "ad_account", "description": "Scope of the report. \"ad_account\" covers the whole account; the others need entity_id." }, "entity_id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "Campaign, ad group, or ad ID to scope to. Required unless level is \"ad_account\"." }, "aggregation_level": { "type": "string", "enum": [ "ad_account", "campaign", "ad_group", "ad" ], "description": "What each row represents. Must be at or below level. Defaults to level." }, "time_granularity": { "type": "string", "enum": [ "hourly", "daily", "monthly", "none" ], "description": "Time bucket per row. \"none\" returns one row per entity for the whole window. Segmented requests do not support \"hourly\"." }, "date_since": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD) in the ad account timezone. Defaults to 30 days before date_until." }, "date_until": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD) in the ad account timezone. Defaults to today." }, "fields": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "minItems": 1, "maxItems": 50, "description": "Canonical dotted field names, e.g. [\"campaign.name\",\"campaign.spend\"]. Defaults to ids, name, and all six metrics for the aggregation level." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "operator": { "type": "string", "enum": [ "IN", "GREATER_THAN", "LESS_THAN" ] }, "value": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "number" } ] } }, "required": [ "field", "operator", "value" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20, "description": "Filters, ANDed together. E.g. [{\"field\":\"campaign.id\",\"operator\":\"IN\",\"value\":[\"cmpn_1\"]}]." }, "sort": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "direction": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "field", "direction" ], "additionalProperties": false }, "minItems": 1, "maxItems": 5, "description": "Sort order, applied before pagination. E.g. [{\"field\":\"campaign.spend\",\"direction\":\"desc\"}]." }, "segment": { "type": "string", "enum": [ "product", "country", "device" ], "description": "Extra breakdown dimension. Only available on enabled ad accounts; segmented requests cannot use hourly granularity." }, "include_zero_impressions": { "type": "boolean", "default": false, "description": "Include entities with no impressions in the window." }, "include_conversions": { "type": "boolean", "default": false, "description": "Also fetch attributed conversion totals per entity. Whole-window totals only, not per time bucket. Account-gated: if unavailable the delivery data is still returned." }, "limit": { "type": "integer", "minimum": 1, "maximum": 2000, "default": 100, "description": "Maximum rows to return (1–2000). Default: 100." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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": { "last-30-days-by-campaign": { "summary": "Last 30 days by campaign", "value": { "level": "ad_account", "aggregation_level": "campaign", "reason": "Monthly performance review" } }, "specific-window": { "summary": "Specific window", "value": { "level": "ad_account", "aggregation_level": "campaign", "date_since": "2026-07-01", "date_until": "2026-07-31", "reason": "July report" } }, "top-ads-by-clicks": { "summary": "Top ads by clicks", "value": { "level": "ad_account", "aggregation_level": "ad", "sort": [ { "field": "ad.clicks", "direction": "desc" } ], "limit": 10, "reason": "Find best performing creatives" } }, "with-conversions": { "summary": "With conversions", "value": { "level": "ad_account", "aggregation_level": "campaign", "include_conversions": true, "reason": "Calculate cost per conversion" } } } } } }, "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/chatgpt_ads_list_conversion_event_settings": { "post": { "operationId": "chatgpt_ads_list_conversion_event_settings", "summary": "List ChatGPT Ads Conversion Event Settings", "description": "List the conversion events configured for the account — what each one counts, its attribution window, and which campaigns use it. Useful for interpreting the conversion totals returned by chatgpt_ads_get_insights.\n\nReturns a \"not enabled\" error on accounts without conversion tracking.", "tags": [ "conversion-event-settings" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "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." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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-events": { "summary": "List events", "value": { "reason": "Understand what conversions are being counted" } } } } } }, "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/chatgpt_ads_list_custom_audiences": { "post": { "operationId": "chatgpt_ads_list_custom_audiences", "summary": "List ChatGPT Ads Custom Audiences", "description": "List the custom audiences on the account — name, status, and how many identifiers matched.\n\nIts main use is resolving identity: chatgpt_ads_list_campaigns returns targeting.custom_audiences.ids as bare IDs, so pass those to custom_audience_ids here to find out who a campaign actually targets.\n\nAudience sizes come back as privacy-bucketed ranges (e.g. \"5000-10000\"), never exact counts — report them as ranges.", "tags": [ "custom-audiences" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": false }, "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." }, "custom_audience_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "minItems": 1, "maxItems": 50, "description": "Resolve specific audiences by ID instead of listing. Use this to turn the opaque IDs in a campaign's targeting.custom_audiences into names." }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." }, "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-audiences": { "summary": "List audiences", "value": { "reason": "See what audiences exist" } }, "resolve-targeting-ids": { "summary": "Resolve targeting IDs", "value": { "custom_audience_ids": [ "ca_abc123" ], "reason": "Name the audiences a campaign targets" } } } } } }, "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/chatgpt_ads_ping": { "post": { "operationId": "chatgpt_ads_ping", "summary": "Ping ChatGPT Ads MCP Server", "description": "Health check. Returns server status, version, and timestamp. Does not contact the ChatGPT Ads API.", "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" } } } } } } } }, "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-account", "description": "Ad-account tools" }, { "name": "ad-accounts", "description": "Ad-accounts tools" }, { "name": "ad-groups", "description": "Ad-groups tools" }, { "name": "ads", "description": "Ads tools" }, { "name": "auth", "description": "Auth tools" }, { "name": "campaigns", "description": "Campaigns tools" }, { "name": "connections", "description": "Connections tools" }, { "name": "conversion-event-settings", "description": "Conversion-event-settings tools" }, { "name": "custom-audiences", "description": "Custom-audiences tools" }, { "name": "feedback", "description": "Feedback tools" }, { "name": "insights", "description": "Insights tools" }, { "name": "rename-connection", "description": "Rename-connection 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": "unshare-connection", "description": "Unshare-connection tools" } ] }