MCP server

The upload.ad MCP server lets AI agents (Claude Code, Claude Desktop, Cursor, and any other MCP client) manage your creatives and ad copy through natural language: "upload everything in ./renders and add a headline to each" becomes tool calls against your account.

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. MCP access requires an active subscription either way.

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.

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. 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 and a destructive flag), 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.

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.
• Meta ad sets target ISO country codes; TikTok ad groups need 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 or partnershipAdCode with the sponsor tagged through partnershipFbSponsorPageId / partnershipIgSponsorId, 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.

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.