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.

Local server (Claude Code, Claude Desktop, Cursor)

Use the local server when files already live on your machine and you want bulk uploads or repeated workflows. It shares the CLI's credentials, so authenticate once with the CLI:

npm install -g @adsuploader/mcp @adsuploader/cli
ads login

ads login opens your browser to authenticate; the MCP server then reads those credentials, so it never runs its own OAuth. Then add the server to your host config:

{
  "mcpServers": {
    "ads-uploader": {
      "command": "ads-mcp"
    }
  }
}

Requires Node.js 18 or later. If your host only supports local stdio servers but you would rather use the hosted OAuth endpoint, bridge to it with npx mcp-remote https://adsuploader.com/api/mcp.

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.

Preview first. ads_create blocks until the job finishes (up to a 30-minute ceiling), so confirm a preview looks right before you ask the agent to create.

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): attach the files to the conversation and ask the agent to upload them. The hosted client cannot read your local disk, so files must be attached to the chat.
• Local server (Claude Code, Cursor, Codex, and other desktop agents): the agent reads files straight from your machine, so nothing needs attaching. This is the best route for bulk uploads, whole directories, and repeated creative workflows.

Small images can pass through the conversation itself; larger files and all video upload straight to Ads Uploader's storage. Some agent environments restrict outbound network access, so if a large upload fails with a blocked or forbidden network error, allow uploads.adsuploader.com (or *.adsuploader.com) in your agent's network allowlist and retry:

• Claude.ai: Settings → Capabilities → Allow network egress → add the domain under "Additional allowed domains"
• Claude Code: add the host to permissions.allowedHosts in .claude/settings.json

The upload tool reports the exact host as allowlistHost in its response, so if that value ever differs, trust the response.

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.