MCP e agenti AI

Rulrr can be operated by an AI assistant. A business owner generates a personal API key for a profile, hands it to their AI (for example Claude via an MCP server), and the assistant can then read the account and manage campaigns on the owner's behalf — checking performance, surfacing insights, and making changes such as pausing a campaign or adjusting a budget.

Rulrr's Model Context Protocol (MCP) server is a thin, safe bridge that exposes Rulrr's account operations as tools an AI can call — scoped to exactly one profile and bounded by the permissions on the key.

The model in one picture

Business owner ──generates──▶  Personal API key (scoped to a profile)
        │
        └──pastes key into──▶  AI assistant / MCP client (e.g. Claude)
                                      │
                                      └──authenticated calls──▶  Rulrr account API
                                                                  (read + manage campaigns)

What an assistant can do

With a key, an assistant can, for the connected profile:

• Understand the account — list profiles, stores, connected social pages, and campaigns.
• Report on performance — pull campaign reports, store/profile statistics, daily breakdowns,

conversion stats and customer insights.

• Act on campaigns — pause or resume a campaign, change its budget, update targeting, swap the

content, or create a new campaign — subject to the key's permissions.

Each capability maps to a real Rulrr account operation. The Capabilities and Operations reference sections list them in detail; Authentication & API keys explains the key model; and Errors, limits & safety covers guardrails for write actions.

Why an AI-first interface

Campaign operations are exactly the kind of multi-step, judgment-heavy work an assistant is good at: "How did last week's campaign do, and should we shift budget?" becomes a short conversation instead of a dashboard session. The MCP layer makes those actions available to the owner's AI without ever exposing their Rulrr password — access is a revocable, scoped key.

Scope of this document. This section specifies the AI/MCP interface and the operations it exposes. The underlying operations are the same ones that power the Rulrr web and mobile apps; the personal-API-key layer is what makes them safely available to an AI agent.

Access for an AI assistant is granted through a personal API key that the business owner creates inside Rulrr. The key authenticates the assistant as that owner, scoped to a single profile.

Generating a key

In the Rulrr app, the owner opens the profile they want to connect and generates an API key. A key:

• is bound to one profile (and therefore its stores and campaigns);
• carries a permission scope (see below);
• is shown once at creation — the owner copies it into their AI/MCP client;
• can be revoked at any time, immediately cutting off access.

Keys are prefixed for easy identification (for example rulrr_pk_…) so they're recognisable in logs and client configuration.

Using a key

The assistant presents the key on every request as a bearer credential:

Authorization: Bearer rulrr_pk_live_xxxxxxxxxxxxxxxxxxxx

The key resolves to the owner and profile it was issued for; all operations are automatically limited to that profile's data. There is no need to pass a profile id for authentication — though many operations still take a groupId/storeId to target a specific store within the profile.

Permission scopes

A key is issued with one of two scopes so owners can choose how much autonomy to grant their AI:

Start assistants on read to explore safely; upgrade to manage when you want the AI to act. Spend-affecting actions are called out in Operations reference and should be gated behind explicit user confirmation — see Errors, limits & safety.

Security guidance

• Treat the key like a password. Anyone holding it can act on the profile within its scope.
• One key per assistant/integration, so you can revoke a single one without disrupting others.
• Rotate periodically and revoke immediately if a key may have leaked.
• Keys are profile-scoped: a key for Profile A can never see or touch Profile B.

To operate Rulrr, an assistant needs the account's object model. These are the entities it will read and act on, and how they relate.

User ──owns──▶ Profile (group) ──has──▶ Store(s) ──run──▶ Campaign(s) ──contain──▶ Ad Set(s) ──▶ Ad(s)
                    │                      │                                 │
                 Social pages          Consumers / Orders               Audiences (new / returning)

Profile (group)

A profile is a business account context — the top-level container the API key is scoped to. (Internally it is called a *group*; in the product it is a *profile*.) A profile owns stores and connected social pages, and is the boundary for all data an assistant can see.

• Key id in operations: groupId.

Store

A store is a physical or logical location under a profile, with its own address, currency, and (optionally) a connected POS or other integration partner. Campaigns and orders belong to a store.

• Key id in operations: storeId.

Campaign

A campaign is an automated advertising effort for a store. It has a budget, a status (active, paused, processing, failed, unpaid), targeting (gender, age range, area), a goal, and a call to action. Campaigns report spend, revenue, audience reach and engagement.

• Key id in operations: campaignId.

Ad Set

An ad set pairs an audience with content inside a campaign. Ad sets are typically split into new (prospecting) and returning (retargeting/look-alike) audiences, so performance can be read per audience type.

Audience

Audiences are who the ads target, built from:

• Store audiences — derived from the store's customers/orders (the data partners send).
• Social audiences — website/visitor retargeting via the connected Facebook/Instagram pixel.
• Shared audiences — reusable geo/segment audiences.

Consumer & Order

A consumer is a customer record (email/phone + history); an order is a transaction tied to a consumer and store. Orders classify conversions as new / returning / organic / anonymous, which drives revenue attribution and customer insights.

Statistics

Rulrr aggregates ad-network and conversion metrics into statistics at the store, profile and campaign level — impressions, reach, spend, clicks, conversions and revenue, with period-over-period comparisons. These power the reporting operations an assistant uses.

Connected social

A profile connects Facebook/Instagram pages (the channels ads run on) and pulls content (posts/creatives) that campaigns promote. Each piece of content carries engagement stats and a proprietary rulrr score indicating its suitability for promotion.

What an assistant can do with a key, grouped by intent. Read capabilities are available to any key; write capabilities require a manage key. The next section, Operations reference, gives the exact operation for each.

Discover the account (read)

• List the profiles the key can access and the stores under a profile.
• List connected social pages and available content to promote.
• List a store's campaigns with their status, budget, spend and revenue.

Report & analyse (read)

• Pull a campaign report (overview, performance, creatives, insights, daily breakdown).
• Get store and profile statistics over a date range, with period-over-period comparison.
• Get a daily performance breakdown for a campaign.
• Get conversion stats and customer insights (new vs returning, demographics, top placements).

Manage campaigns (write — manage key)

• Pause a campaign (with an optional reason) and resume it.
• Change the budget of a campaign.
• Update targeting (gender, age range, area).
• Update the content a campaign promotes.
• Edit other campaign attributes (name, goal, call to action).
• Create a new campaign for a store.

Out of scope for assistants

To keep AI access safe and focused, the following are intentionally not exposed as assistant operations: billing/payment-method changes, subscription changes, team/permission management, and account deletion. These remain owner-only in the Rulrr app.

Spend awareness. Creating a campaign, changing a budget, or resuming a paused campaign affect ad spend. Treat these as confirm-before-acting operations — see Errors, limits & safety.

The operations an assistant can call, with purpose, inputs and outputs. These map directly to Rulrr's account API (the same operations that power the web and mobile apps); the MCP server exposes them as tools. Scope indicates the minimum key scope required; Spend flags operations that can affect ad spend and should be confirmed with the user first.

Read operations

getProfile

Return the authenticated owner and the profiles they can access. — Scope: read. Returns: user + groups (profiles) with their stores and connected socials.

getStores(groupId)

List the stores under a profile. — Scope: read. Returns: [Store] (id, name, address, currency, POS status).

getCampaigns(groupId)

List a profile's campaigns with live status and headline numbers. — Scope: read. Returns: [Campaign] (id, name, budget, status, totalSpent, totalRevenue, audience, engagement, adsCount…).

getCampaignReport(campaignId, dateRange)

Full report for one campaign. — Scope: read. Returns: overview, performance, creatives, insights (audience sources, demographics, funnel), and daily performance.

getDailyPerformanceBreakdown(campaignId, dateRange)

Time-series performance for a campaign. — Scope: read. Returns: [DailyPerformance].

getStoreStatistics(storeId, dateFilter) · getGroupStatistics(groupId, dateFilter)

Aggregated campaign statistics for a store or whole profile, with period-over-period comparison. — Scope: read. Returns: [CampaignStatistic] (summary + comparison + per-ad-set breakdown by new/returning).

getConversionStats(groupId, dateFilter, conversionType)

Conversion totals and trends. — Scope: read. Returns: ConversionStats.

getCustomerInsights(groupId, dateFilter)

Customer-level insights (new vs returning, demographics). — Scope: read. Returns: CustomerInsights.

getRemarketingAudience(groupId) · getTopPerformingPlacements(groupId)

Audience sizing for retargeting; best-performing ad placements. — Scope: read.

getSocialContent(groupId) / getContent(groupId)

List promotable content (posts/creatives) with engagement stats and rulrrScore. — Scope: read.

Manage operations (manage key)

pauseCampaign(campaignId, pauseReason?)

Pause a running campaign. — Scope: manage. Spend: stops spend. Returns: PauseCampaignResponse.

resumeCampaign(campaignId)

Resume a paused campaign. — Scope: manage. Spend: resumes spend ⚠️ confirm first. Returns: ResumeCampaignResponse.

updateCampaignBudget(campaignId, priceId)

Change a campaign's budget tier. — Scope: manage. Spend: changes spend ⚠️ confirm first. Returns: Campaign.

updateCampaignTargeting(campaignId, targeting)

Update targeting (gender, age range, area). — Scope: manage. Returns: Campaign.

updateCampaignContent(campaignId, groupId, contentRemoteIds)

Swap the content/creatives a campaign promotes. — Scope: manage. Returns: [SocialContent].

editCampaign(campaignId, groupId, input)

Edit campaign attributes (name, goal, call to action…). — Scope: manage. Returns: Campaign.

createCampaign(...)

Create a new campaign for a store. — Scope: manage. Spend: starts spend ⚠️ confirm first. Key inputs: campaignName, storeId, groupId, contentRemoteIds, budget, paymentMethodId, optional targeting, campaignGoal, callToAction. Returns: CreateCampaignResponse.

Conventions

• Targeting the right scope. Most operations take a groupId (profile) and/or storeId;

campaign operations take a campaignId. The key already fixes *which* owner/profile.

• Dates. Reporting operations accept a dateRange / dateFilter; omit for sensible defaults.
• Money. Budgets and amounts are in the currency's minor unit (e.g. cents) where numeric.

This catalog lists the operations intended for assistant use. The full account API contains more (billing, teams, social connection, etc.) which are intentionally not exposed to assistants — see Capabilities → out of scope.

Guidance for building a reliable, safe assistant integration on top of the Rulrr account API.

Permission model recap

• A key is profile-scoped and carries a read or manage scope.
• read keys can never change anything; manage keys can run the write operations in

Operations reference.

• Revoking a key takes effect immediately.

Confirm before spending

Three operations move real money (ad spend) and should be gated behind explicit user confirmation in the assistant before they run:

• createCampaign — starts a new campaign.
• updateCampaignBudget — changes how much a campaign spends.
• resumeCampaign — restarts spend on a paused campaign.

A good assistant pattern: read first, summarise the intended change and its budget impact, ask the user to confirm, then call the write operation.

Errors

Operations fail with a clear error when a request is invalid or not permitted. Handle at least:

Rate limits

Keys are subject to fair-use rate limits. Design assistants to:

• Batch reads and cache within a conversation rather than re-fetching repeatedly.
• Back off on rate-limit responses (exponential, with jitter).
• Avoid tight polling loops; prefer on-demand reads triggered by the user.

Idempotency & safety

• Reads are always safe to repeat.
• Writes are not idempotent by default — don't auto-retry a write that may have succeeded;

re-read state to confirm before retrying.

• Prefer the smallest change that achieves the user's intent (e.g. adjust one campaign's budget

rather than recreating it).

Auditing

All actions are attributed to the owner the key belongs to and are visible in the Rulrr app's activity. Encourage owners to use one key per assistant so activity is traceable and a single key can be revoked without disrupting other integrations.

Need help?

For MCP server setup, scopes, or anything not covered here, reach Developer Support.