# MCP server The upload.ad MCP server lets AI agents (Claude Code, Claude Desktop, Cursor, and any other MCP client) run your whole workspace through natural language, from the creative library and review to launching ads, moderating comments, and reading performance: "upload everything in ./renders and add a headline to each" becomes tool calls against your account. **Included in the free trial when your agent signs in through the browser.** Add the remote server (below), approve the connection, and it works on the trial as well as on a paid plan. API keys are the exception: keys, the REST API, the CLI, and the SDK are part of every paid plan, and a workspace without one is refused with `402 subscription_required` (`-32002` over MCP). On a trial the AI tools (`tag_creatives_ai`, `generate_copy`) are left out of `tools/list`, since they spend AI tokens a trial does not have; everything else is there. You can [subscribe](https://upload.ad/dashboard/settings/billing) at any time, including during the trial. The server ships with the [`uploadad` CLI](./cli.md) and runs locally over stdio: ```bash uploadad mcp ``` ## Authentication The easiest path is browser sign-in: ```bash uploadad login ``` This opens upload.ad in your browser, you approve the device, and the credential is stored in `~/.config/uploadad/config.json`. Every config below works with no `env` block after that. The remote server (see below) supports OAuth directly: clients like Claude and ChatGPT send you to upload.ad to sign in when you add the connector, no keys involved. For headless environments (CI, servers), use an API key instead: create one at [upload.ad/dashboard/settings/api-keys](https://upload.ad/dashboard/settings/api-keys) and set it as the `UPLOADAD_API_KEY` environment variable. Signing in through the browser works on any workspace with an active plan or a running trial; once a trial ends without a subscription, requests are refused until you subscribe. API keys and the local `uploadad mcp` server go through the REST API, which needs a paid plan: without one they are refused with HTTP 402 and a message asking you to subscribe. Most MCP clients report that only as a generic authorization failure, so check the plan first if a key-based connection fails. Tools act with the permissions of the member who created the key or signed in. A failed tool call comes back as an MCP error result (`isError: true`) whose text content is compact JSON of the form `{"error":{"code","message"}}`. The `code` is a stable machine code from the closed set documented in [the API docs](api.md#tool-error-codes) (`invalid_input`, `tool_error`, `limit_exceeded`, `not_connected`, `plan_required`, `forbidden`, `not_found`, `conflict`, `upstream_error`, `upstream_busy`), plus `internal_error` for anything unexpected; treat unknown codes as `tool_error`. Per-folder access scoping applies to the library, creatives, and uploads; ads, insights, and audiences are workspace-wide and governed by the Ads permissions. ## Claude Code Connect to the remote server; Claude Code opens the browser to sign you in: ```bash claude mcp add --transport http uploadad https://upload.ad/mcp ``` Or run the local server (uses your `uploadad login`, or an API key): ```bash claude mcp add uploadad -- npx uploadad mcp claude mcp add uploadad -e UPLOADAD_API_KEY=ua_live_... -- npx uploadad mcp ``` ## Claude Desktop Add to `claude_desktop_config.json`. After `uploadad login`, no `env` block is needed; add one with `UPLOADAD_API_KEY` to use an API key instead. ```json { "mcpServers": { "uploadad": { "command": "npx", "args": ["uploadad", "mcp"] } } } ``` ## Cursor Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global). Same rule: the `env` block is only needed if you authenticate with an API key instead of `uploadad login`. ```json { "mcpServers": { "uploadad": { "command": "npx", "args": ["uploadad", "mcp"] } } } ``` ## OpenClaw Connect to the remote server, then run the login command; it prints an authorization URL to approve in the browser: ```bash openclaw mcp set uploadad '{"url":"https://upload.ad/mcp","transport":"streamable-http","auth":"oauth"}' openclaw mcp login uploadad ``` Or run the local server (uses your `uploadad login`, or `UPLOADAD_API_KEY`): ```bash openclaw mcp set uploadad '{"command":"npx","args":["uploadad","mcp"]}' ``` ## Hermes Add to `~/.hermes/config.yaml`, then run `hermes mcp login uploadad` from a fresh terminal and approve the sign-in in the browser: ```yaml mcp_servers: uploadad: url: 'https://upload.ad/mcp' auth: oauth ``` Or run the local server (uses your `uploadad login`, or `UPLOADAD_API_KEY`): ```yaml mcp_servers: uploadad: command: npx args: ['uploadad', 'mcp'] ``` ## Remote server For clients that connect to MCP servers over HTTPS instead of launching a local process, upload.ad also hosts the same server at: ``` https://upload.ad/mcp ``` It speaks streamable HTTP and supports OAuth: add the URL to any OAuth-capable MCP client and it sends you to upload.ad to sign in and approve access. No keys to create or paste. The server is stateless and has no session id. It answers protocol revisions `2026-07-28`, `2025-06-18`, `2025-03-26` and `2024-11-05`, so both eras of client work against the same endpoint: newer clients declare their version in each request's `_meta` and can call `server/discover`, older ones still get the `initialize` handshake. Call `server/discover` for the current list. API keys still work for scripts and clients without OAuth support, either as a header (`Authorization: Bearer ua_live_...`) or, for clients that only take a URL, embedded in it: ``` https://upload.ad/mcp?key=ua_live_... ``` Treat a keyed URL like the key itself, and prefer the Authorization header whenever the client supports one: URLs (query strings included) routinely end up in access logs, browser history, and pasted configs, while headers do not. If you must use a keyed URL, consider a key limited to the scopes the agent actually needs, and rotate it if the URL may have leaked. The remote server exposes the same tools as the local one, with one difference: `upload_creatives` takes `urls` (publicly reachable file URLs, downloaded server side) instead of `filePaths`. ### ChatGPT ChatGPT connects to remote MCP servers through custom connectors: 1. Enable developer mode under Settings, Apps and connectors, Advanced settings. 2. Create a new connector, name it upload.ad, and set the MCP server URL to `https://upload.ad/mcp`. 3. Choose OAuth authentication and sign in when prompted. Alternatively, set authentication to none and use `https://upload.ad/mcp?key=ua_live_...` with the key in the URL. ## Tools The server exposes everything you can do in the app, grouped here by area. The catalog is served live from `GET /api/v1/tools` (each entry includes its JSON schema plus a `category` and `destructive`/`readOnly` flags, surfaced over MCP as `_meta["ad.upload/category"]` and the `destructiveHint`/`readOnlyHint` annotations; entries with a declared result shape also carry an MCP `outputSchema`), so a `tools/list` call always reflects the current surface. You can also call any tool directly over REST with `POST /api/v1/tools/{name}` and the tool's arguments as the JSON body (see the [REST tools reference](./api.md#tools)). Tool arguments are schema-validated (types, enums, array limits, numeric ranges); invalid input comes back with a message that starts `Invalid input:`. For calls that create ads or spend money, pass an `idempotencyKey` argument so a retry within 24 hours replays the stored result instead of running twice. | Area | Tools | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Account | `get_account`, `list_ad_accounts`, `set_default_ad_account`, `list_invoices` (your billing history with hosted invoice and PDF links; personal, not workspace-level), `send_notification` (in-app notification to the workspace owner's header bell; `href` makes it clickable, also usable as an automation action) | | Uploads | `upload_creatives`, `upload_creative_version` (new cut of an existing creative from a URL; takes over the spot, folder, and review flow, older cuts stay behind the version switcher), `list_versions` (a creative's whole version chain with the current head and per-version review status), `list_uploads`, `get_upload`, `retry_upload`, `dismiss_upload` | | Library | `list_creatives`, `search_library` (file names, folder names, copy text, and tags; optional `tags` filter), `rename_creative`, `assign_creative_editor` (owner/admin: set the member responsible for creatives, overriding the uploader; `editorId` null hands it back), `move_creatives`, `reorder_creatives`, `duplicate_creatives`, `trash_creatives`, `list_trash`, `restore_creatives`, `delete_creatives`, `set_creative_tags` (each tag is folded onto the closest tag the workspace already uses, so near-duplicates never accumulate; optional `category`), `list_tags` (whole vocabulary with categories, counts, and duplicate suggestions; read it before tagging), `merge_tags` (fold duplicates into one kept tag, leaving aliases behind), `tag_creatives_ai` (vision-based auto-tagging across the eleven tag categories, primed with the workspace's existing tags; 1 token per creative, subscribers only), `get_creative_performance` (per-creative spend/ctr/roas/frequency across Meta and TikTok from the hourly rollup, with winner/loser/fatigued signals), `refresh_creative_stats`, `set_creative_poster` (JPEG poster frame for a video creative, from a URL or inline base64 `data`), `get_creative_by_fingerprint` (resolve a Facebook `imageHash` or `videoId` back to a library creative) | | Canvas | `arrange_canvas`, `add_note`, `add_card`, `update_checklist`, `draw_shape`, `list_annotations`, `delete_annotations` | | Folders | `list_folders`, `create_folder`, `update_folder`, `delete_folder` | | Ad copy | `generate_copy`, `list_copy`, `save_copy`, `delete_copy`, `list_copy_templates`, `save_copy_template`, `delete_copy_template` (workspace-wide reusable sets of `primaryTexts`, `headlines` and `descriptions`, up to 5 each; pass `ifUpdatedAt` when updating to fail instead of overwriting a teammate's save; deleting is limited to admins and the creator; `create_ad` takes `copyTemplateId`) | | Publishing | `publish_creatives` (optional `adAccountIds` sends the same creatives to each named connected account on the platform; omit for the selected account) | | Performance | `get_ads_performance`, `get_account_series`, `get_ad`, `get_ad_insights`, `get_breakdown` | | Ad account | `get_campaigns`, `get_adsets`, `list_pixels`, `list_billing_limits` (Meta: both ceilings that stop delivery, each account's own spending limit (Graph's spend_cap field) and the business's extended credit lines, with limit, spent and available; either list is empty when that kind of ceiling is not in use, and they pair with the `spend_limit.threshold` and `credit.threshold` automation triggers), `list_audiences`, `search_interests`, `search_regions`, `list_languages`, `search_music`, `list_lead_forms`, `list_identities` (publishing identities: the TikTok accounts linked to the advertiser, Meta the Instagram accounts usable with a managed page including the page-backed one), `create_identity` (Meta only: the page-backed Instagram shadow account for a page), `list_partnership_content` (Meta: creator posts the business can boost as partnership ads), `list_leads` (submissions collected by Meta lead ads, pulled in hourly; filter by form or ad, bound by date, paginate with limit/offset; pairs with the `lead.received` automation trigger), `list_catalogs`, `list_product_sets`, `create_product_set` (Meta: new product set in a catalog from price/category/brand/availability conditions), `list_apps` | | Managing ads | `create_campaign`, `create_adset`, `create_ad`, `create_smart_ad`, `create_catalog_ad`, `update_ad_object`, `set_ad_status`, `duplicate_ad_object`, `delete_ad` | | Existing posts | `list_page_posts` (Meta page posts plus the posts behind existing ads: pass a post id as `existingPostId` to `create_ad` to keep its likes and comments), `authorize_tiktok_post`, `list_authorized_posts` (TikTok Spark Ads via `tiktokItemId` on `create_ad`) | | Audiences | `upload_customer_list` (hashed customer lists), `create_lookalike_audience`, `delete_audience` | | A/B tests | `list_ab_tests`, `create_ab_test` (Meta ad studies need a connected Business account; TikTok split-test campaigns take one variable plus 2 ad-group arms) | | Comments | `list_ad_comments`, `set_comment_visibility`, `reply_to_ad_comment`, `edit_ad_comment` (rewrites one of the page's own Facebook replies; Instagram and TikTok have no comment-edit endpoint), `delete_ad_comment` (both platforms; Meta covers the Facebook post and the Instagram media behind each ad, with each comment tagged `source: facebook \| instagram`, and moderation calls take that source back; TikTok moderation calls take the comment's `adId`), `set_comment_liked` (Facebook comments only: the Graph API writes just the Like reaction, and Instagram comments cannot be liked) | | Automations | `list_automations`, `get_automation_reference` (the YAML grammar plus every trigger's `when` keys and variables, every action's `with` args, metric names, and awaitable events; read it before writing a flow), `get_automation` (returns the flow as YAML code), `create_automation` (structured graph or a full `yaml` document), `update_automation` (edit via YAML; previous state kept in version history), `set_automation_enabled`, `delete_automation`, `test_automation` (dry run: conditions and variables evaluated with no actions executed; metric automations preview their real current matches), `run_automation_manually` (run a manual-trigger flow now against picked `creativeIds` or `adIds`, up to 50 items; actions execute for real, and the selection reaches the flow as creatives, ads, and selection.count), `list_automation_runs` (run history with per-node results, attempts, loop iterations, and errors), `replay_automation_run` (re-run against a past run's stored payload; actions execute for real), `list_automation_versions`, `get_automation_version` (a past version incl. its YAML), `restore_automation_version` (snapshot current, then apply). Trigger, condition, and action flows (the Automations tab). Triggers: review status changed, comment added or resolved, version or creative uploaded, share link viewed or commented on, ad published, ad rejected, lead received, publish failed, member joined, creative test started/finished/promoted/stopped, ad account connection lost, storage threshold crossed, budget pacing checks, inbound webhooks (POST to `/api/automations/hooks/`, with an Idempotency-Key header de-duplicating retries for 24 hours), daily/weekly/monthly schedules with a minute and an IANA time zone, ad-metric checks on a cadence of your own (as often as every 15 minutes, optionally confined to chosen hours and weekdays, measured over a calendar preset or a rolling `last_h` window, per-object or batched), and manual runs. Steps: conditions with nested groups and 14 operators, actions with up to 4 retries and an error branch, AI decision/generate steps (1 token per run), waits (relative up to 30 days, or until a clock time in a time zone), wait-for-event steps, for-each loops over up to 50 items, joins merging parallel branches, set-values steps that compute named `{{vars.*}}` values from templates, and request steps that call an outside https endpoint and expose the reply as `{{steps..body}}`. Each automation also carries rate control (a cooldown or a once-only rule, scoped by a template such as `{{ad.id}}`, plus a per-hour ceiling) and failure handling (alert on the first failure or after a streak, optionally by email, and optionally disable the automation), both set through the limit and on-failure blocks of the YAML document. Action tools include `send_notification`, `set_ad_status`, `update_ad_object`, `create_smart_ad`, `start_creative_test`, `publish_creatives`, plus engine actions for scaling and setting budgets, posting to a channel, emailing members, signed `automation.event` webhook deliveries, emailing or sheeting a performance report, and running another automation as a sub-flow | | Testing | `start_creative_test`, `list_creative_tests`, `promote_creative_test`, `kill_creative_test`, `get_test_pipeline`, `set_test_pipeline` — the creative testing pipeline: creatives launch as active ads in a designated testing ad set, get evaluated hourly against account benchmarks (thresholds + win rule, hard stop at maxSpend), winners promote into the scaling ad set (auto or manual) and losers pause. Lifecycle: queued, launching, testing, won, lost, promoted, killed | | Budgets | `set_budget_plan`, `list_budget_plans` (latest pace snapshot: spent, expected, pace percent, projected; `refresh: true` recomputes), `delete_budget_plan` — monthly spend targets per platform (whole account or picked campaigns), recomputed hourly; pair with a `budget.pacing` automation trigger to act on pace | | Analytics | `workspace_analytics` (workspace activity over 7, 30, or 90 days: creation, comment/review, versioning, publishing, testing, storage, and sharing metrics, each with a previous-window comparison and a per-day series, plus a per-member breakdown, share-link engagement, creative outcomes per platform (winner/loser/fatigued counts, top creatives by spend), and automation run stats) | | Reports | `list_reports` (the workspace's report list: the built-ins plus any it saved, with the metric columns they can return), `create_report` (save a report: what the rows are, what ranks them, which columns, and conditions rows must meet), `update_report`, `delete_report` (a saved report is deleted, a built-in is hidden and can be put back), `run_report` (fold the account's ad results for a period onto one dimension: ad, library creative, image, video, copy, headline, saved copy template, or landing page; ratio metrics are recomputed from the summed parts rather than averaged across ads, tracking parameters are folded into one landing page, and ads that spent nothing are left out unless asked for). Meta's copy, headline and landing page rows come from a creative snapshot refreshed hourly, so a freshly connected account fills them in over the first sweep; TikTok has no landing page report. Copy-template rows come from our own record of which saved copy an ad was built from, so ads written by hand or made in Ads Manager count as unattributed | | Client links | `create_report_link` (public client-facing performance page at `/p/`: platform, account or campaign scope, date range, optional password and expiry; data refreshes on view under the workspace's own connection), `list_report_links`, `revoke_report_link` | | Drafts | `list_drafts`, `save_draft`, `delete_draft`, `list_scheduled_ads`, `cancel_scheduled_ad` | | Review | `list_comments`, `add_comment` (video timecodes and ranges via durationSeconds, replies via parentId, @Name mentions, team-only notes via internal), `react_to_comment`, `edit_comment` (author-only rewrite; only newly added @Name mentions notify), `resolve_comment`, `set_review_status` (in_review, changes_requested, approved), `create_review_link` (optional password, downloads, comments, approvals, expiry) — a public URL where clients view, comment, approve or request changes, compare versions, and download everything as a zip, all without an account, `list_review_links`, `revoke_review_link` | | Diagnostics | `get_ads_issues` (ads needing attention: rejected, flagged, or blocked on billing, both platforms), `get_ads_activity` (recent Ads Manager change history; Meta only), `get_reach_estimate` (estimated monthly audience for an ad set's saved targeting via `adsetId`; Meta only) | | Webhooks | `get_webhook` (endpoint, events, last delivery; the signing secret is only returned by `set_webhook`), `set_webhook` (create or change the URL; the response includes the signing secret, which survives URL changes), `set_webhook_events` (subset of events, or all), `delete_webhook`, `test_webhook` (single signed test delivery), `list_webhook_deliveries` (7-day delivery log, cursor-paginated), `redeliver_webhook` (re-send one delivery by `deliveryId`, re-signed with the current secret) — reads are open to api-permitted members; everything else is owner/admin only | | Team & inbox | `list_members` (member roster: id, display name, avatar), `get_team_performance` (per-member creatives/publishes/ads and ad results with previous-period comparison and unattributed ads; owner/admin only), `assign_ad_member` (credit an ad to a member via `memberId`; owner/admin only), `list_notifications` (your header-bell inbox), `mark_notifications_read` | | Notifications | `list_notification_channels` (Discord/Slack/Teams channels plus email events), `set_notification_channel`, `set_notification_channel_events`, `delete_notification_channel`, `send_test_channel_message`, `set_email_notification_events` — all owner/admin only; deliveries key off the workspace owner | | Branding | `get_branding`, `update_branding` (brand name shown on branded review pages via `brandName`, attribution visibility via `hideAttribution`), `set_branding_logo` (from a public image URL or inline base64 `data` with `contentType`), `remove_branding_logo`, `set_custom_domain` (connect a review subdomain; returns the DNS records), `check_custom_domain`, `remove_custom_domain` — owner only; writes require the Agency plan | | Preferences | `get_preferences`, `set_preferences` (`stripMediaMetadata` removes AI generation markers, C2PA Content Credentials, generator prompts and camera EXIF/GPS from newly uploaded images without re-encoding them; `rangesIncludeToday` shifts the rolling last-N-day ranges onto today instead of ending yesterday, keeping their length) — owner only | | Integrations | `get_integration` (Drive/Dropbox connection status plus the address to share Drive folders with; connecting stays in the dashboard OAuth flow), `browse_integration` (one folder level of the connected Dropbox account; Drive files are picked in the dashboard), `import_from_integration` (up to 25 images/videos into the library, already-imported files skipped), `list_watched_folders`, `watch_folder` (auto-import new files: Dropbox via `remoteId`/`remoteName` from browse, Drive via a folder link shared with the watch address from get_integration; sync options `mirrorSubfolders`, `versionUpdates`, `deleteToRemote`, `deleteFromRemote` on both providers), `unwatch_folder`, `disconnect_integration` (owner/admin only; Drive watches survive) | | Shopify | `list_stores` (connected Shopify stores; connecting starts in Shopify Admin), `get_profit` (order revenue, cost of goods and profit per ad for a date range, with untraceable orders reported separately under `unattributed` and a count of orders whose cost of goods is unknown, so an overstated profit is visible as such), `disconnect_store` (owner/admin only; deletes that store's orders and profit history) | | Catalog | `search_tools` (search this catalog by keyword and/or category; returns matching tool names with one-line summaries and the category list; handy for agents that do not hold all schemas in context) | ### Ad platforms Every ad tool takes an optional `platform` argument: `meta` (Facebook/Instagram, the default) or `tiktok`. The tool surface is the same on both; the enums differ where the platforms do: - Objectives: Meta uses `OUTCOME_*` values; TikTok uses `REACH`, `TRAFFIC`, `VIDEO_VIEWS`, `ENGAGEMENT`, `LEAD_GENERATION`, `WEB_CONVERSIONS`, `APP_PROMOTION`, `PRODUCT_SALES`. - The middle level is an ad set on Meta and an ad group on TikTok; the `adset` level value addresses both. - Location targeting on `create_adset` is platform-conditional: Meta ad sets take ISO country codes, while TikTok ad groups take location ids from `search_regions`. - TikTok mutations on existing objects (`update_ad_object`, `set_ad_status`, `duplicate_ad_object`, `delete_ad`) also need `level` (`campaign`, `adset`, or `ad`) since TikTok ids do not encode their type. - `create_ad` on TikTok requires `displayName` and uses `primaryText` (or a saved copy variant) as the ad text; the creative must be published to TikTok first with `publish_creatives`. - Breakdown dimensions: Meta supports `age`, `gender`, `publisher_platform`, `platform_position`, `device_platform`, `country`; TikTok supports `age`, `gender`, `country_code`, `placement`. - Delivery estimates are Meta only; TikTok's API does not offer them. Ad previews come from the creative itself: the upload.ad dashboard renders its own TikTok-styled preview, and Meta ads show their creative directly. - Existing-post ads keep a post's social proof on both platforms: Meta ads expose their `postId` (the underlying page post) on reads, and `create_ad` accepts it back as `existingPostId`; TikTok Spark Ads use `tiktokItemId` from `list_authorized_posts`. `duplicate_ad_object` preserves Spark bindings, `deep` copies children on both platforms, and `toParentIds` rolls an ad out into up to 20 other ad sets (or an ad set into other campaigns) in one call. - Meta extras: `pageId` on `create_ad` picks the Facebook page the ad publishes under (any page the connected user manages; defaults to the last used page, and `list_page_posts` / `list_lead_forms` accept the same `pageId`), partnership (allowlisted) posts run under the creator's handle with `usePageActorOverride`, `instagramUserId` (from `list_identities`) sets the Instagram identity used on Instagram and Threads placements, partnership (branded content) ads discover boostable creator posts with `list_partnership_content` and run them via `sourceInstagramMediaId` (Instagram media) or `partnershipAdCode` with `partnershipAdCodePlatform` naming the platform that issued the code (Instagram and Facebook codes ride on different creative fields), with the sponsor tagged through `partnershipFbSponsorPageId` and `partnershipIgSponsorId` (pass both to deliver on both platforms; a side left untagged is not delivered there), EU DSA transparency rides on `create_adset` (`dsaBeneficiary`/`dsaPayor`, required when targeting the EEA), manual placements take per-platform `positions` on `create_adset` and `update_ad_object` targeting (e.g. `{"facebook":["feed","story"]}`; omit a platform for all its positions; `whatsapp` targets WhatsApp Status and rides on Instagram Stories) plus `devices` (`mobile`/`desktop`; omit for all), `leadFormId` (from `list_lead_forms`) makes a lead ad, and catalog ads flow through `list_catalogs` → `list_product_sets` → `create_campaign` (`catalogId`) → `create_adset` (`productSetId`) → `create_catalog_ad`. Catalog ads and A/B tests need a connected Business account or catalog first; the tools say so when missing. - TikTok extras: Spark Ads (`tiktokItemId` on `create_ad`), carousel ads (`carouselCards` + `musicId` from `search_music`), lead forms (`pageId` from `list_lead_forms`), a per-ad publishing identity (`identityId` + `identityType` from `list_identities`; defaults to the workspace identity), Smart Creative ads (`create_smart_ad` in an ad group created with `smartCreative`), audience building, and comment management. Catalog ads and app promotion need a TikTok catalog or a registered app first; `list_catalogs` and `list_apps` say so when none exist. - Meta app promotion: `list_apps` (platform meta) returns the ad account's advertisable apps; pass `promotedAppId` + one of its store URLs as `appStoreUrl` to `create_adset` inside an `OUTCOME_APP_PROMOTION` campaign (the `APP_INSTALLS` optimization goal requires them). Campaigns, ad sets, and ads created through tools always start paused unless you explicitly pass `activate` or schedule a launch. Destructive tools (deleting, activating, budget changes) carry the `destructive` flag in the catalog so agents know to confirm before acting. The assistant inside the app additionally has browser-side screen tools (reading and operating the dashboard in front of the customer). Those run in the customer's browser and are not exposed over MCP, the CLI, or the REST tools endpoint. ### Realtime behavior Mutations made through MCP tools sync to the dashboard live: any workspace member with the app open sees the change without reloading (same mechanism the app itself uses). There is no MCP-side event stream in return; to react to changes made elsewhere, poll the relevant list tool or subscribe the workspace [webhook](./api/webhooks.md) to the events you care about. ## Trying it out Once connected, ask your agent something like: ``` Upload banner.png and promo.mp4 to my ad account, wait for them to finish, then add the headline "Summer sale" to each new creative. ``` The agent will call `upload_creatives`, poll with `get_upload`, and finish with `save_copy`.