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 at any time, including during the trial.

The server ships with the uploadad CLI and runs locally over stdio:

uploadad mcp

Authentication

The easiest path is browser sign-in:

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.

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 (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:

claude mcp add --transport http uploadad https://upload.ad/mcp

Or run the local server (uses your uploadad login, or an API key):

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.

{
	"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.

{
	"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:

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

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:

mcp_servers:
  uploadad:
    url: 'https://upload.ad/mcp'
    auth: oauth

Or run the local server (uses your uploadad login, or UPLOADAD_API_KEY):

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

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.

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