ROAS.to Docs

MCP installation

Model Context Protocol lets an AI assistant connect to ROAS.to with a scoped bearer token, call approved tools, and receive structured account data without sharing your dashboard login.

Installing in Claude Desktop

Create an MCP token in Settings, store it safely, then add this server entry to your Claude Desktop MCP configuration.

{
  "mcpServers": {
    "roas": {
      "url": "https://mcp.roas.to/mcp",
      "headers": {
        "Authorization": "Bearer roas_mcp_..."
      }
    }
  }
}

Installing in ChatGPT

Use ChatGPT’s connector setup for custom MCP servers when it is available on your plan. Set the server URL to https://mcp.roas.to/mcp and use Authorization: Bearer roas_mcp_... as the authentication header.

Scopes

read:campaigns

Read Facebook campaigns, ad sets, ads, boosts, creatives, and account health.

read:analytics

Read spend, revenue, ROAS, profitability, hourly trends, and freshness data.

read:conversions

Read attributed conversions and tracker offer performance.

read:snippets

Read page tests, link tests, and landing-page experiment results.

read:automation

Read automation logs, budget alerts, and operational diagnostics.

write:status

Pause and activate campaigns, ad sets, and ads.

write:budgets

Scale or set campaign and ad set budgets.

write:bids

Update bid amounts where supported.

write:clone

Clone campaigns through approval-gated workflows.

write:create

Create campaigns, ad sets, and ads from scratch, and upload media.

write:delete

Delete or archive campaigns, ad sets, and ads.

write:automation

Create, edit, assign, and pause/resume automation, clone, and auto-boost rules.

write:snippets

Pause, activate, and archive page tests.

Launching ads

With the write:create scope an assistant can launch campaigns end-to-end using the same engine the Create Ads page uses:

  • list_ad_assets discovers the ad account, Page, and pixel ids a launch requires.
  • list_media / upload_media_from_url / upload_video_from_url to pick existing media or import a new image/video by URL (returns an image_id). Videos transcode asynchronously; wait until ready before launching.
  • create_facebook_ads creates the campaign, ad set, and ads (copy, headlines, media, targeting, budget). Created PAUSED unless start_immediately is set, and subject to your approval rules just like the dashboard.
  • clone_facebook_campaign (write:clone scope) duplicates an existing winner and lets you change anything before it launches — the MCP equivalent of the dashboard’s Duplicate-and-edit flow. By default it inherits the winner’s targeting, budget, structure and settings; pass any override to change just that part: creative (headlines, body_texts, image_ids, custom_cta, descriptions), budget, page, targeting (countries, age, genders, devices, placements), campaign settings (objective, optimization goal, bid strategy, Advantage+), and ad-set end date. Changing the ad copy is done this way because Meta ad copy is immutable — there is no edit-existing-ad path, so cloning with new creative is the supported route and preserves the original’s learning. Interest and custom-audience targeting always inherit the winner. Omit a field to copy the parent verbatim.

Automations

With write:automation an assistant can build the autonomous rules engine (condition → action: pause/activate, scale budget, duplicate, set budget schedule, send alert, or dayparting):

  • list_automation_rules reads rules + their ids.
  • create_automation_rule / update_automation_rule (full replace) / assign_automation_rule_to_campaign / update_automation_rule_status (on/off).
  • list_clone_rules / create_clone_rule / update_clone_rule manage auto-scaling clone rules (duplicate winners on a trigger/schedule; simple mode).
  • list_auto_boost_rules / create_auto_boost_rule / update_auto_boost_rule manage auto-boost organic posts that cross an engagement threshold.

Rules are created active by default and fire within ~1 minute; set is_active=false to stage one for review. Same validation, cooldowns, and per-day caps as the dashboard.

Idempotency

Write tools accept caller-provided idempotency keys. Keys are capped at 50 characters and should be unique per intended mutation so retries do not duplicate actions.

Rate limits

Read tools are limited to 240 calls per minute per token. Write tools are limited to 30 calls per minute per token and 120 calls per minute per tenant.

Error format

Errors use the shared API error envelope and the same code vocabulary as the dashboard API. See ApiErrorCode for the canonical union.