Docs

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). The AI tools (tag_creatives_ai, generate_copy) work on the trial too, spending the tokens that come with it. You can subscribe at any time, including during the trial.

The server ships with the uploadad CLI 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 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.

Connecting needs the workspace's AI permission (the same one that turns on the in-app assistant); a member without it is refused at sign-in and with a 403 on /mcp. The local stdio server (npx uploadad mcp) goes through the REST API, so it needs API access instead. Tools act with the permissions of the member who created the key or signed in, and the server instructions list any permissions the member lacks so the client can say why an action is unavailable. 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 (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"]
		}
	}
}

Codex

Connect to the remote server, then sign in; Codex opens the browser to approve it:

bash
codex mcp add uploadad --url https://upload.ad/mcp
codex mcp login uploadad

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.

A connection signed in from ChatGPT follows ChatGPT's directory rules on commerce: list_invoices is not offered, and plan or token errors state the fact without pointing at a subscribe or purchase page. The server recognises ChatGPT by the OAuth client's redirect address; key-based connections from ChatGPT behave like any other client.

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).

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.

AreaTools
Accountget_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)
Uploadsupload_creatives (pushes to the ad account's media library by default; libraryOnly adds to the library only), 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), add_soundtrack (lay a library MP3 onto a video as its next version, replacing its sound or mixed under it; an MP3 cannot be published or used in an ad on its own), 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
Librarylist_creatives (one folder with folderId, or the whole library, a page at a time either way by passing each returned next cursor back as cursor), 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), 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 Meta imageHash or a Meta/TikTok videoId back to a library creative)
Canvasget_canvas_layout (everything on one folder's board: creatives, subfolders, cards, columns, labels and drawings with their boxes and stacking order; items in a column say which one), arrange_canvas (move and restack any of those; placing an item that is in a column takes it out), add_note, add_card (note with an optional align, to-do list, link, or a column with a title, a tint and its contents), update_column (rename, recolour, collapse, or set the full top-to-bottom contents of a column; added items leave any other column), update_annotation (edit a note, card, label or shape in place: text, a note's align (left, center, right), checklist items, link, card size, shape corners, colour, folder; optional version refuses a stale edit; moving and restacking go through arrange_canvas), update_checklist, draw_shape (rectangle, ellipse, arrow or line), list_annotations, delete_annotations (a column takes the notes and cards in it along; its creatives stay on the board). Notes and docs highlight with ==text== (yellow) or <mark data-color="COLOR">text</mark> in danger, success, blue, purple, orange, teal, pink or fg (gray)
Folderslist_folders, create_folder, update_folder, delete_folder, duplicate_folders (up to 20 folders with everything in them, into targetFolderId or beside each original; the files show as importing until they finish copying), list_folder_templates, save_folder_as_template (a folder's whole board, with an empty slot wherever a creative sat; replaceId saves over one), create_folder_from_template (a new folder from a template with a name, or the template put down on parentId's board at x, y without one), rename_folder_template, delete_folder_template, list_bookmarks, set_bookmark (the signed-in person's own shortcuts to folders, files and pages, listed under Library in their sidebar; bookmarked: false takes one off), set_workspace_bookmark (owners and admins bookmark a folder, file or page for the whole workspace, listed above everyone's own bookmarks; bookmarked: false takes it off), set_bookmark_order (the person's own bookmarks in order, or with workspace: true the workspace's, owners and admins only), create_shortcut (a file, folder or page shows in one more folder, folderId or the top level, without being copied; it opens the original, follows renames, and a folder cannot hold a shortcut to itself or a folder above it), remove_shortcuts (only the shortcuts go, never the originals)
Pageslist_pages, get_page (a doc's markdown, a task list's tasks with names rather than ids, a sheet's cells as typed), create_page (a doc, task list or sheet, from a template or filled with markdown or cells), write_doc (mode replace or append), add_tasks, update_tasks and delete_tasks (statuses, properties and teammates by name; library files for a Creatives property or the task's creatives by file name, folder path, id or link), rename_page, move_page (to a folder, or null for the top level), delete_pages (asks for approval first; deleted pages can be brought back for 30 days), list_deleted_pages, restore_pages (back to the folder and spot they were in, or the top level when that folder is gone), comment_on_task, set_cells (a tab by name; live formulas such as =ADS("spend","last_7d") work; a cell given as an object also sets its style: bold, italic, underline, strike, size 8 to 48, align, valign, text color and fill from the folder colors plus orange, teal, pink, black and white, and a number fmt), edit_page (raw ops for statuses, properties, saved views, tabs, conditional formats and charts; a library property links docs, task lists, sheets, folders and library files, and can carry a folderId so it only links what is inside that folder; a view the owner locked changes only for the owner), get_my_tasks (open tasks assigned to you across every task list you can see, past due first, plus the pages edited most recently)
Ad copygenerate_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)
Publishingpublish_creatives (optional adAccountIds sends the same creatives to each named connected account on the platform; omit for the selected account)
Performanceget_ads_performance (campaigns, ad sets or ads with metrics for a period; campaignId / adsetId or the plural campaignIds / adsetIds scope it to chosen campaigns or ad sets, ids picks rows by id, status keeps active, paused, issue or archived rows (the default all includes an archived row only when it spent or delivered in the period, as the Ads Manager does), search matches names across the hierarchy, filters applies metric thresholds such as spend gte 100, sort / dir rank by any metric, and limit / offset page through an account of any size with total saying how many rows matched), get_account_series, get_ad, get_ad_insights, get_breakdown, get_hit_rate (ad and landing page hit rates for a period, as the Analytics Ads tab shows, with no setup: of the ads past the workspace's minimum impressions and spend, the share that cleared its winner tiers, or without any, landed at least 1.2 times the median ROAS (CTR with no purchases) of the period's ads; each landing page is judged on all the ads that link to it, and bar says which bar applied)
Ad accountget_campaigns, get_adsets (optional campaignId returns only that campaign's ad sets), list_pixels, list_custom_conversions (TikTok: the Custom Conversions on a pixel, so an ad group can optimize towards one of the advertiser's own events and report it on its own), 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, list_app_events (TikTok: the in-app events an app can optimize towards, with whether each is available yet, how many postbacks TikTok received in 30 days and how many it still needs; an ad group optimizing towards one reports that event alone, which is how an advertiser's own in-app event becomes a column)
Managing adscreate_campaign, create_adset, create_ad, queue_ads (a whole batch created in the background, one entry per ad with the same fields as create_ad; returns at once with a batchId), list_queued_ads (progress of queued batches with each ad's platform id once created), list_naming_conventions, save_naming_convention, delete_naming_convention (workspace-wide ad name patterns with {creative}, {name}, {adset}, {campaign}, {date}, {nn} tokens, used by the builder and by bulk rename), create_smart_ad, create_catalog_ad, update_ad_object, set_ad_status, duplicate_ad_object, delete_ad
Existing postslist_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; a TikTok Smart+ ad group holds at most 30 ads, so tiktokExtraPosts puts up to 50 posts in one ad there)
Audiencesupload_customer_list (hashed customer lists), create_lookalike_audience, delete_audience
A/B testslist_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)
Commentslist_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)
Automationslist_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; also lists the built-in templates), get_automation_template (a built-in recipe such as surf scaling as YAML, ready to adapt and pass to create_automation), 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 of a saved automation by id, or of an unsaved draft by yaml: 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, task completed, assigned, or overdue in a task list, budget pacing checks, inbound webhooks (POST to /api/automations/hooks/<token>, 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_<n>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.<id>.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, running another automation as a sub-flow, and page steps that create a task, add a row to a sheet, or comment on the triggering task
Testingstart_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
Budgetsset_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
Analyticsworkspace_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)
Reportslist_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, landing page, or editor, the member behind each creative; 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; campaignId / adsetId or campaignIds / adsetIds restrict the report to chosen campaigns or ad sets, search matches row labels, filters adds metric thresholds, editorId keeps only ads whose creative belongs to one member (a saved report can carry the same scope, which is how an editor gets a report of their own work), and page walks past the first rows). 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 linkscreate_report_link (public client-facing performance page at /p/<token>: 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
Draftslist_drafts, save_draft, delete_draft, list_scheduled_ads, cancel_scheduled_ad
Reviewlist_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
Diagnosticsget_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)
Webhooksget_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 & inboxlist_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; people who left show as former: true; owner/admin only), assign_ad_member (credit an ad to a member via memberId; owner/admin only), remove_former_member_stats (clear a former member's credit so their ads become unattributed; owner/admin only), list_notifications (your header-bell inbox), mark_notifications_read
Team managementlist_team (roles, emails, effective permissions, folder and ad-account scope, pending invitations, seats; owner/admin only), invite_member (invite by email as member or admin, with permissions switches (the tool lists the Team page's job presets as switches), folderIds, and adAccountIds; re-inviting renews the pending invitation), cancel_invitation (by invitationId), set_member_access (change a member's permissions, resetPermissions, and scope), set_member_role (promote to admin or demote to member; resets access), remove_member (by memberId or email; revokes their workspace API keys). All changes are owner only and refuse scoped API keys
Notificationslist_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
Brandingget_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
Preferencesget_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; uploadsNeedApproval starts creatives uploaded or imported by members without the review permission In review and notifies everyone who can approve them; performanceRules is the whole rule set that labels library creatives winners and losers, or null for the built-in rules: evidence floors, percentile ranking, fatigue thresholds, and up to 8 ordered custom tiers, each a name, a kind of winner or loser, and conditions on a metric against an absolute value or a multiple of the account median; the first matching tier's name rides on the status as tier, and saving relabels the stored rollup at once) — owner only
Integrationsget_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)
Shopifylist_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)
Catalogsearch_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.
  • Ad rows from get_ad and get_ads_performance carry the creative's platform identifiers: videoId (the Meta or TikTok video the ad plays) and imageHash (Meta image ads). Pass either to get_creative_by_fingerprint to find the library creative behind an ad, including ads made outside upload.ad. On the listing, Meta video ids are read from the creative's classic field, story spec, and asset feed; get_ad re-checks a single ad.
  • A workspace can define up to three of its own conversion columns (an event such as a first purchase, on Meta, TikTok, or both). Their numbers ride on every metrics row as custom1..custom3, with costPerCustom1..costPerCustom3: ads and campaigns from get_ads_performance and the other performance tools, per-member results from get_team_performance, per-creative rollups from get_creative_performance, and top creatives from workspace_analytics. Those results, and get_preferences, return customColumns naming each one (key, costKey, label). The keys work in filters and sort, in automation conditions, in performance rule tiers and ranking (custom1..3 or costPerCustom1..3), and as a creative test win metric in set_test_pipeline (costPerCustom1..3). Which way a custom column wins is the workspace's choice, never assumed: lowerWins on the ranking and on the test win rule. When a test's column wins low the multipliers read the other way: win at or under winMultiplier 0-1 times the account benchmark, lose at or over loseMultiplier 1-10 times it. An unconfigured slot is absent from customColumns, and rules and tests never match on it.
  • 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), the same ad set declares Meta's regional regulated categories automatically from its targeted countries (Singapore, Taiwan, Thailand and Brazil each refuse an ad set without theirs) with regulationBeneficiary/regulationPayer naming who is behind the ads and financialServices: true adding the further declaration Taiwan, Australia and India want from investment ads, 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), an app promotion ad set optimizing for app events names one of Meta's app events in conversionEvent, or the app's own event in customEventName (spelled as the app or its measurement partner sends it, e.g. first_purchase; needs promotedAppId and appStoreUrl, and update_ad_object takes the same three to change it), 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.
  • Meta placement sizes: pass other aspect-ratio cuts of the creative as placementCreativeIds on create_ad (or each queue_ads entry) and one ad shows every placement the cut that fits it: 9:16 in Stories and Reels, 4:5 (else 1:1) in feeds and everything else, 16:9 in in-stream video, 1:1 in the right column and Audience Network. One file per ratio (9:16, 4:5, 1:1, 16:9, 1.91:1, read from each creative's width and height), all images or all videos, up to five in all. Such an ad takes one headline, primary text and description, needs linkUrl, and needs an ad set without Dynamic Creative.
  • 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 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.