MCP Configuration
MCP access is reserved for paid users and is not available on trials. It uses the same account and Facebook connection as the web app and CLI, and it is disabled whenever CLI access is disabled for an account.
The Ads Uploader MCP (Model Context Protocol) server hands your AI agent the same surface the CLI uses: browsing accounts, campaigns, ad sets, and ads, uploading media, saving presets, working with saved builds, previewing a build, and creating ads. If you already understand the web app or the CLI, the MCP tools map to the exact same workflow.
CLI or MCP?
Both run on the same infrastructure, so this is a workflow choice rather than a capability one. The CLI is the better fit when you want to run your entire operation through an AI agent: bulk uploads from disk, repeated launch workflows, and complete builds assembled end to end from the terminal.
The MCP is better for surgical jobs where the web interface stays in the loop. For example:
- Upload and proof all your media in the web uploader, then hand the build to the agent for one specific step
- Have Claude or another agent set up the ad set configuration
- Have the agent write or rewrite your ad text
- Marry up client ad copy from a spreadsheet against the file names of your uploads
Saved builds are the bridge between the two: the web uploader, CLI, and MCP all speak the same build references, so a configuration can pass back and forth mid-flight without anyone re-entering work. See Saved Builds for autosave, resuming, and live-update behavior.
There are two ways to connect, depending on your host.
Remote server (Claude.ai, Cursor remote connectors)
Use the hosted server when you work from a chat client and want to authenticate in the browser. Point a custom remote connector at:
https://adsuploader.com/api/mcp
Add it as a custom connector in your host (for example, Claude.ai → Settings → Connectors → Add custom connector), then complete the sign-in and consent screen in the browser - there is no token to copy or paste. Once connected, ask your agent to list your ad accounts to confirm it is working.
Coding agents (Claude Code, Claude Desktop, Cursor)
Coding agents connect to the same hosted server. Add https://adsuploader.com/api/mcp as a remote MCP server in your agent's configuration and complete the browser sign-in when prompted. If your host only speaks local stdio servers, bridge to the hosted endpoint with npx mcp-remote https://adsuploader.com/api/mcp.
If your workflow starts from files on your machine - a folder of creatives, bulk uploads, repeated launches - the CLI is the better tool: it reads your file system directly and runs the same launch pipeline end to end.
What your agent can do
The server exposes tools for the full build workflow. Your agent calls these on your behalf; you describe what you want in plain language.
| Area | What the agent can do |
|---|---|
| Identity | Confirm which Ads Uploader user the session is authenticated as before it touches anything |
| Accounts | List your Meta ad accounts; pass the right accountId to each tool call |
| Browsing | List campaigns, ad sets, ads, and pages; read an ad's full creative settings |
| Presets | List saved API and ad text presets; save an existing ad as a reusable preset |
| Builds | List, read, save, update, and delete saved builds; every build comes back with a URL that opens it directly in the web uploader |
| Media | Upload images and video to your ad account's media library; list recent upload batches |
| Preview | Preview exactly what would be created before anything is made |
| Create | Create ads from a preset, a copied ad, a saved build, or a full spec, then track or cancel the job |
Preview first. The hosted ads_create call watches the job for about 60 seconds. If the work is still running, it returns the job reference immediately and your agent continues checking it with ads_get_job; the server-side job never depends on one long connector request staying open.
Working with saved builds
Builds autosave as you work in the web uploader, and each one has a durable reference (build_...) shown at the bottom of the configuration step and in the Saved Builds modal. Give that reference to your agent and it can fetch the exact configuration you see on screen, change it, and save it back to the same build. If that build is already open, the uploader checks for the saved update and applies it automatically when you have no local edits waiting. You can also use the refresh button beside the build reference to check immediately. If the tab is closed, ask the agent for the build URL.
If you have unsaved local edits when an external update arrives, the uploader asks whether to load the external changes or keep yours instead of replacing either version silently.
The per-ad and per-ad-set text editors in the web uploader include Claude and ChatGPT buttons that open a session with your build reference prefilled, so handing over a text pass is one click. It also works in reverse: ask the agent to save its work as a build, then open the returned link to proof everything in the browser before any ads are created.
Uploading media
How files reach your ad account depends on where the agent runs:
- Hosted connector (Claude.ai and other chat clients): give the agent public HTTPS download links, a public Google Drive file link, or one public Drive folder link. Ads Uploader runs bounded parallel download, staging, and processing pipelines in the background. The agent only polls progress, so file bytes never pass through the conversation or connector request.
- Coding agents with local files (Claude Code, Cursor, Codex, and other desktop agents): use the CLI and
ads uploadfor folders on your machine - it reads the file system directly. The MCP connector is the better fit for browsing your account and editing builds.
After a URL or Drive upload starts, the agent checks ads_get_upload with the returned job reference. When it finishes, that status includes the usual batch summary for previews and ad creation. An unwanted import can be stopped with ads_cancel_job; completed media remains usable and the result reports completed, failed, and skipped counts. Images named *_thumbnail are attached to their matching video as custom thumbnails and reported as thumbnailsAttached rather than counted as separate media, so a folder's media total can be lower than its file count. If Google temporarily blocks a folder import, the result clearly reports what completed, failed, and was skipped so the agent can tell you to retry later. Public links do not need an Ads Uploader upload-domain allowlist. Drive links must be shared as Anyone with the link (Viewer); private Drive files remain a web-uploader feature.
Small images can still pass inline for convenience. A byte-capable coding agent can also deliberately request the older presigned upload path and PUT bytes directly to Ads Uploader storage. Only that presigned path may need uploads.adsuploader.com (or *.adsuploader.com) in the coding agent's outbound allowlist:
- Claude Code: add the host to
permissions.allowedHostsin.claude/settings.json
The presigned response reports the exact host as allowlistHost, so if that value ever differs, trust the response. Hosted URL ingestion does not return or require an upload host.
Sessions and access
Remote connections are authorized through OAuth and renew in the background, so you stay connected without re-authenticating each session. Access follows your account: it is paid-only, and disabling CLI access for an account also revokes its MCP access immediately.