MCP tools reference
Every tool the Adrails MCP server registers, with its inputs, what it reads or changes and who can call it, then the rules every call follows, the rate limits and the errors.
The server has 63 tools. 43 are the tools the Adrails agent uses in the app; the other 20 cover accounts, integrations, campaign drafts, automations, Knowledge and job status.
tools/list returns a tool only when the connection's permissions and your role allow at least one of its operations. The same catalog, searchable, is on the MCP page in Adrails.
Calling a tool
The arguments of every call share one shape. The tool's own inputs go in input; the rest frames the call.
| Argument | Type | Required | What it is |
|---|---|---|---|
input | object | No, empty by default | The tool's inputs, listed under each tool below. |
idempotencyKey | string, 8 to 128 characters | For a change or a proposal | Your key for this call. Reuse it only to retry the exact same call. |
accountIds | array of string, 1 to 100 | No | Narrows an agent tool to some of the workspace's ad accounts. It can never add one. The 20 other tools refuse it and take accountId or adAccountId in input instead. |
userStatement | string, at most 8,000 characters | No | The person's own words, kept in the connection's history as an unverified statement. It is never a permission or evidence. |
Any other argument is refused. No tool takes a workspace or a user: both come from the connection.
{
"name": "performance_period",
"arguments": {
"input": { "accountId": "<account id>", "level": "campaign", "since": "2026-09-01", "until": "2026-09-30" }
}
}{
"name": "integrations_connect",
"arguments": { "input": { "provider": "shopify" }, "idempotencyKey": "connect-shopify-001" }
}The inputs below are the top-level fields of input. A field typed object follows the JSON Schema your client receives in tools/list.
What a call does
Each tool's Access line says what a call does, the permission it needs and the role it needs, operation by operation where they differ.
- read returns data and changes nothing.
- change acts at once, inside Adrails' own rules, with no approval step: a setup link, a sync, a draft, a template, a Knowledge entry, an automation, a channel message. It needs an
idempotencyKey. - proposal for approval prepares one exact advertising change and returns a link to approve it in Adrails. Nothing reaches Meta or Google Ads before you approve. It needs an
idempotencyKey.
Approving a proposal
A proposal comes back with status set to awaiting_approval, its actionId, a preview of the change, expiresAt and an approvalUrl, https://adrails.ai/oauth/actions/<actionId>. Its message says Review the exact change in Adrails. Nothing has been applied.
- Open the link. The Review advertising change page names the AI client, the workspace and the ad account, and shows the change field by field.
- Choose Approve this change or Decline.
Only you can approve it: the person who authorized the connection, signed in as yourself, still an owner or admin of the workspace, on an active plan, with the connection still allowed to prepare advertising changes and the ad account still in the workspace. On approval Adrails reads the platform again and applies the exact change once, or blocks it if the entity changed in the meantime, as Approvals and undo explains. A proposal expires 30 minutes after it is prepared.
Your AI client may ask you to allow a tool call. That is the client's own permission, not an approval, and neither is the consent you gave when connecting.
Retries and idempotency
- The same
idempotencyKeywith the same arguments returns the first result and does nothing twice. For a proposal, the retry reports where it stands now: applied, reverted, approved, closed or expired. - The same key with other arguments is refused.
- A call cut off before it finished keeps its key blocked. Check it with
jobs_status,kindset tooperation, before you use a new key. - Keys belong to one connection and one tool.
One call at a time
Calls on one connection run one after another. A call sent while another is running is refused without running: retry it once the first has finished, with the same idempotencyKey if it is a change.
Who can call what
- Permission. Each operation needs the permission its Access line names, and every call also needs Read workspace data. See Permissions.
- Role. Where the line says owner or admin, your current role in the workspace is checked at each call, not the role you had when you connected.
- Plan. A proposal needs an active plan: on Preview it is refused. Every other tool follows the plan rules it follows in the app, such as the limits on automations.
- Credits. A tool call does not run Adrails' AI model and uses no agent credit: your client's model does the reasoning. The exception is an automation run by
workflows_runthat contains an agent step, which uses credits as it does in the app. See The agent and credits.
Results
structuredContent.resultholds the exact data. Read this one in code.- The text content is the same result as readable Markdown: tables, chart series as tables, approval links. No AI model writes it.
- A result is at most 256,000 bytes. A larger one is refused whole, with no partial figures: ask for a shorter period, a narrower selection or a page.
- A request is at most 1 MB.
- Listings that page return
nextCursor: pass it asafter.
Rate limits
| Limit | Value |
|---|---|
| Calls, per access token | 60 per minute |
| Changes and proposals, per access token | 10 per minute |
| Calls, per person in the workspace | 180 per minute |
| Calls, per workspace | 600 per minute |
A call over a limit is refused with 429 and rate_limited. Its message says how many seconds to wait; the Retry-After header says 60.
Sign-in has its own limits, per IP address: 10 client registrations and 300 other OAuth requests a minute. They answer 429 with a Retry-After header.
Errors
Refused requests
A request refused before the tool runs gets an HTTP error with a JSON body, {"error": "<code>", "message": "<sentence>"}.
| Code | Status | When |
|---|---|---|
invalid_token | 401 | No token, or an invalid, expired or revoked one. The WWW-Authenticate header points to the discovery document: sign in again. |
insufficient_scope | 403 | The connection lacks the permission. WWW-Authenticate names it in scope: connect again and select it. |
forbidden | 403 | The operation needs an owner or admin, or you no longer belong to the workspace. |
invalid_arguments | 400 | The arguments do not match the tool's schema, or include an unknown one. |
unknown_tool | 400 | No tool has that name. |
rate_limited | 429 | A rate limit is reached. |
temporarily_unavailable | 503 | Adrails could not complete the request. Check the operation's status before retrying a change. |
request_failed | 400, 403, 413, 503 | Anything else, said in the message: a change without idempotencyKey, a body over 1 MB or not JSON, a browser origin that is not allowed, signing keys briefly unavailable. |
Errors inside a tool
Once a tool runs, an error comes back as a tool result with isError set to true and a sentence, over a normal HTTP 200.
| Message | Why |
|---|---|
| Another call is running on this connection. Retry when it finishes. | Calls on one connection run one at a time. Nothing ran. |
| This idempotency key was already used with different arguments. | Use a new key for a new call. |
| This operation is pending or its outcome requires review. Check its status before retrying. | The first call with this key did not finish. Check jobs_status with kind set to operation. |
| Advertising changes require a workspace administrator and an active plan. | A proposal needs an owner or admin, on a plan other than Preview. |
| Your workspace role no longer permits this operation. | Your role changed since the call was admitted. |
| A selected resource is outside this connection's access. | An accountIds value is not an ad account of the workspace. |
| Use this product tool’s input accountId or adAccountId selector instead of accountIds. | accountIds is for agent tools only. |
| This proposal is no longer available to this connection. | A retried proposal no longer belongs to this connection's workspace. |
| This result exceeds the response limit. Request a narrower period, selection or page. No partial figures are returned. | The result is over 256,000 bytes. |
| The operation could not complete. Check its status before retrying a mutation. | An unexpected failure. A change may or may not have happened: check before retrying. |
Adrails' own refusals, such as a validation error, a plan limit or a role rule, come back the same way, in Adrails' words.
Analysis and reporting
Reads over the connected ad accounts and the workspace's own rules. None of them changes anything.
reporting_overview
Spend, attributed revenue and named conversion events for the workspace's connected ad accounts, Meta and Google Ads alike. Without dates, each account's latest synchronized window, with entity settings and status. With entityIds, those campaigns, ad groups or ads, and for a campaign its last seven days against the seven before. On Meta, from and to together read an exact calendar period of at most 93 days, with gaps reported. Store orders are read with store_revenue.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
from | date | No |
to | date | No |
accountIds | array of string | No |
entityIds | array of string | No |
actionType | string | No |
performance_period
One ad account's figures for an exact date range, read from Meta or Google Ads at the account, campaign, ad set (ad group or asset group on Google) or ad level: spend, results, revenue, ROAS, CPA, impressions, clicks, CTR, CPC, CPM, and reach and frequency on Meta. compareSince and compareUntil read a second range and give each entity's change. Dates are YYYY-MM-DD in the account's time zone, 400 days at most.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
campaignIds | array of string | No |
compareSince | date | No |
compareUntil | date | No |
entityIds | array of string | No |
level | one of account, campaign, adset, ad | Yes |
since | date | Yes |
until | date | Yes |
performance_diagnose
Compares two equal-length, non-overlapping past periods of one Meta account, from its saved snapshot: coverage, changes, facts, unknowns and what to verify next. A missing row is never counted as zero.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
language | one of fr, en | Yes |
responseMode | one of evidence, answer | No |
accountId | string | Yes |
before | object | Yes |
after | object | Yes |
campaignId | string | No |
actionType | string | No |
metrics_daily
Daily series the integrations measure: traffic, sessions, conversion rate, sales and average order value on the store side; emails received, opened and clicked on the marketing side; net profit, CPA and ROAS on the analytics side. Without metrics it returns everything measured over the period, which is how to discover the names. breakdown splits by product, traffic source or country.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
from | date | No |
to | date | No |
breakdown | string | No |
metrics | array of string | No |
metric_compare
Compares one observed value with a positive target: signed difference, relative difference, attainment percentage, and above, below or equal. Arithmetic only.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
observed | number | Yes |
target | number | Yes |
portfolio_review
Reviews the selected accounts and campaigns against each campaign's actual objective, ad set events, budget owner and period coverage, with freshly evaluated rules. Separates provider issues, policy differences, hypotheses and unknowns, includes campaigns without findings, and gives at most three portfolio priorities. Paginated.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
language | one of fr, en | Yes |
responseMode | one of evidence, answer | No |
accountIds | array of string | No |
offset | integer | No |
limit | integer | No |
budget_recommend
For one account, evaluates the campaigns or ad sets that own a budget: maintain, increase, reduce or investigate, comparing the latest two complete seven-day windows in the account's time zone. Without entityId and entityType it finds the budget owners itself. It suggests no amount.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
language | one of fr, en | Yes |
responseMode | one of evidence, answer | No |
accountId | string | Yes |
entityId | string | No |
entityType | one of campaign, adset | No |
limit | integer | No |
offset | integer | No |
business_review
Checks a bounded business explanation or calculation, such as unit economics, revenue reconciliation or budget pacing, from explicit inputs. Every number must quote its source word for word, from the person's own statement or a tool result in this connection's history.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
language | one of fr, en | Yes |
responseMode | one of answer, evidence | No |
currency | string | No |
review | object | Yes |
planning_calculate
Budget pacing, budget allocation totals or first-order acquisition unit economics, computed from the inputs given, in one currency, with their sources and periods stated in evidence. Returns the arithmetic and its limits, not a forecast.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
currency | string | Yes |
evidence | string | Yes |
calculation | object | Yes |
changes_review
Reviews the actions recorded on one account: when they were applied, their baseline, and their observations, with pending, failed and skipped kept apart from measured results. Paginated.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
language | one of fr, en | Yes |
responseMode | one of evidence, answer | No |
accountId | string | Yes |
actionId | string | No |
limit | integer | No |
offset | integer | No |
findings_review
What the rule engine found on the selected Meta and Google Ads campaigns, against the workspace's own standard. Each finding carries its evidence, snapshot date, campaign objective, currency, budget owner and classification. Filter with family, minSeverity and limit.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
family | one of creative, targeting, tracking, fatigue, health | No |
limit | integer | No |
minSeverity | one of low, medium, high, critical | No |
Commerce and subscriptions
Reads over the connected stores, billing and product analytics.
store_revenue
Revenue of the connected stores over a period: gross, refunded and net kept apart, with the order count, in each store's own currency, never converted.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
from | date | No |
to | date | No |
store_orders
Orders one by one, newest first: totals, financial status, fulfilment status and line count. At most 50 per call.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
from | date | No |
to | date | No |
financialStatus | string | No |
limit | integer | No |
store_customers
Customers imported from the selected Stripe or commerce connection, newest first: name, email domain, country, creation date, order count and imported lifetime spend. Full email addresses are not stored. Paginated with offset.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
limit | integer | No |
offset | integer | No |
search | string | No |
store_products
Products of the connected stores: title, price range, inventory, status, type and vendor. search filters on the title.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
limit | integer | No |
search | string | No |
status | string | No |
saas_performance
Stripe billing, RevenueCat revenue metrics and PostHog product events: active subscriptions, trials, normalized MRR, ARR, collected payments, refunds and daily product events, with customer and subscription counts by billing cadence when customer-level data is available. Each source and currency stays separate.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
from | date | No |
to | date | No |
Creatives
Reads over creative assets and their results. None of them uploads or launches anything.
creative_insights
Groups Meta ads by the image or video asset they use, across ads and accounts: performance, winners, fatigue, repeated use, and missing metadata such as angle, offer, product, persona or creator.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
accountIds | array of string | No |
limit | integer | No |
creative_market_evidence
Per-ad performance, copy and media identifiers, and the parent ad set's configured countries, with the snapshot period and freshness. It is not a breakdown of delivery by country.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
accountIds | array of string | No |
adIds | array of string | No |
limit | integer | No |
creative_review
Reviews the creative evidence of selected ads: available copy, asset IDs, configured goal, period and limits. With focus set to copy_test it proposes one text-order test; with market_transfer it keeps the source asset and copy for the destination named. It prepares no campaign.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
language | one of fr, en | Yes |
responseMode | one of evidence, answer | No |
focus | one of review, copy_test, market_transfer | No |
destination | string | No |
accountIds | array of string | No |
adIds | array of string | No |
limit | integer | No |
offset | integer | No |
drive_folder
Reads a Google Drive folder of creatives: every image and video down to three levels, with its path, ratio, pixel size, duration and file size, and how Adrails would group them into ads. Without folderId, finds folders whose name contains query.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
folderId | string | No |
query | string | No |
Campaign setup and research
What a new campaign needs, read from the accounts and the platforms.
launch_brief
The first step of any new Meta launch. Pass only what the person said or chose; it returns what a clean launch still needs, as questions with options: the ad account, where the ads go, then objective, pixel and event, countries, languages, budget, dates, Page, EU beneficiary, link and copy. When nothing is missing it returns the complete brief for campaigns_launch. Adrails keeps the brief's answers for this connection, so the server counts the call as a change.
Access: change, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
accountId | string | No |
beneficiary | string | No |
conversionEvent | string | No |
copy | one of generate, reuse, provided | No |
countries | array of string | No |
dailyBudget | number | No |
destinationUrl | string | No |
folderId | string | No |
formats | one of send_missing, as_is | No |
languages | array of string | No |
layout | one of one_ad_set, ad_set_per_ad, campaign_per_ad | No |
objective | one of Sales, Traffic, Leads | No |
pageId | string | No |
pixelId | string | No |
purpose | string | No |
schedule | string | No |
source | one of drive_folder, images, reuse, none | No |
target | string | No |
campaigns_setup
Lists the selected Meta accounts with their accountId, currency, snapshot freshness and the Page IDs, pixel IDs and image hashes available. These are candidates, not confirmed choices. Without an account selection it returns a picker rather than choosing.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
accountIds | array of string | No |
campaigns_structure
How an account's campaigns are built, from the last sync, on either platform: campaigns with type, status, budget and bidding; ad sets or ad groups with their keywords; ads with format, copy, final URL and review. Read it before building under or editing what exists, and use its IDs. campaignId narrows it to one campaign.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
campaignId | string | No |
google_ads_library
A Google Ads account's picture library (asset ID, address, size) and audiences (ID, name), to reuse pictures in google_ads_build and to name an audience signal.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
google_keyword_planner
Google's Keyword Planner for a Google Ads account. With mode set to volumes, monthly searches and the top-of-page bid range of keywords; with ideas, keywords suggested by a few words or an https url. Counts are for the given countries and language, or everywhere.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
countries | array of string | No |
keywords | array of string | No |
language | string | No |
mode | one of volumes, ideas | Yes |
url | URL | No |
targeting_options
Looks up the real Meta or Google Ads IDs of custom audiences, interests, languages or locations. Candidates, not confirmed choices.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
platform | one of meta, google_ads | Yes |
accountId | string | Yes |
kind | one of custom-audience, interest, language, location | Yes |
query | string | No |
audience_estimate
Estimates Meta reach for proposed targeting with the account's audience service. An estimate, not measured performance.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
ageMinimum | integer | Yes |
ageMaximum | integer | Yes |
countries | array of string | No |
genders | array of 1 or 2 | No |
interests | array of object | No |
locations | array of object | No |
languages | array of object | No |
customAudiences | array of object | No |
Advertising changes
Every tool here but actions_recent prepares a proposal: the exact change, waiting for your approval in Adrails. See Approving a proposal.
actions_recent
Recent proposed and applied actions: IDs, evidence, execution state, whether undo is available, and 24-hour, 3-day and 7-day observations. At most 10 per call, paginated with offset. Actions prepared through this connection carry their Adrails review link.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
accountIds | array of string | No |
limit | integer | No |
offset | integer | No |
campaigns_pause
Pauses a campaign, ad group or ad on Meta or Google Ads, by the ID an earlier read returned.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
entityId | string | Yes |
entityType | one of campaign, ad_group, ad | Yes |
reason | string | Yes |
campaigns_set_status
Pauses or resumes one campaign, ad group or ad on Meta or Google Ads. Adrails reads the platform again before applying, refuses a concurrent change, and measures the result after 24 hours, 3 days and 7 days.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
entityId | string | Yes |
entityType | one of campaign, ad_group, ad | Yes |
reason | string | Yes |
status | one of ACTIVE, PAUSED | Yes |
campaigns_change_budget
Raises or lowers a campaign or ad group daily budget by an amount or a percentage, at most 30% in one change. An increase needs measured spend and results. Google Ads keeps budgets on campaigns and refuses a budget shared between campaigns.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
direction | one of increase, decrease | Yes |
entityId | string | Yes |
entityType | one of campaign, ad_group | Yes |
reason | string | Yes |
unit | one of amount, percent | Yes |
value | number | Yes |
campaigns_create_draft
A new Meta campaign with one website ad set and one image ad, for a standard Sales, Leads or Traffic objective, using an image already uploaded to the account (imageHash). Approval starts the build, and everything is created paused.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
name | string | Yes |
objective | one of Sales, Traffic, Leads | Yes |
currency | string | Yes |
dailyBudget | number | Yes |
countries | array of string | Yes |
ageMin | integer | Yes |
ageMax | integer | Yes |
startAt | string | Yes |
endAt | string | Yes |
placements | one of feeds, automatic | Yes |
specialAdCategory | None | Yes |
facebookPageId | string | Yes |
pixelId | string | No |
conversionEvent | one of Purchase, Lead, Complete_registration, Add_to_cart | No |
beneficiary | string | Yes |
destinationUrl | URL | Yes |
callToAction | one of Learn more, Shop now, Sign up, Contact us, Get offer, Book now | Yes |
imageHash | string | Yes |
headline | string | Yes |
primaryText | string | Yes |
description | string | No |
reason | string | Yes |
campaigns_launch
Launches the ads of a complete launch_brief: where the ads go, settings, copy and every creative. After approval Adrails sends the Drive files or images to the ad account, then builds the campaign, ad sets and ads, all paused.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
accountId | string | No |
beneficiary | string | No |
conversionEvent | string | No |
copy | one of generate, reuse, provided | No |
countries | array of string | No |
dailyBudget | number | No |
destinationUrl | string | No |
folderId | string | No |
formats | one of send_missing, as_is | No |
languages | array of string | No |
layout | one of one_ad_set, ad_set_per_ad, campaign_per_ad | No |
objective | one of Sales, Traffic, Leads | No |
pageId | string | No |
pixelId | string | No |
purpose | string | No |
schedule | string | No |
source | one of drive_folder, images, reuse, none | No |
target | string | Yes |
copies | array of object | No |
description | string | No |
endDate | date | No |
headline | string | No |
primaryText | string | No |
startDate | date | No |
campaigns_launch_activate
Switches on what a finished launch created: its ads, and the ad sets and campaign above them when they are paused. The proposal lists every budget that starts spending.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
launchId | string | Yes |
campaigns_duplicate_to_draft
Duplicates a Meta or Google Ads campaign, paused, with its targeting, bidding, budget, extensions, keywords and ads. On Meta, variants replaces one source ad with 3 to 5 copy variants. It needs fresh source data. Approval starts the build and never activates it.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
entityId | string | Yes |
reason | string | Yes |
sourceAdId | string | No |
variants | array of object | No |
campaigns_split_test
A split test from an ad set or ad that already runs, which stays variant A, with one to three new variants that each change only the tested variable. Approval creates the test with its new variants paused; launching it is a separate approval on the test's page in Adrails.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
durationDays | integer | No |
entityId | string | Yes |
metric | one of cpa, conversion_rate | No |
name | string | Yes |
reason | string | Yes |
shares | array of integer | No |
variable | one of audience, placements, bidding, ad_text, search_ad_text, creative, google_creative | Yes |
variants | array of object | Yes |
google_ads_build
Creates Google Ads: a new Search, Display, Demand Gen or Performance Max campaign with its ad groups, keywords and ads or its asset groups; new ad groups under an existing campaign; or new ads in an existing ad group. Google validates the request on approval, and everything is created paused.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
adGroups | array of object | No |
assetGroups | array of object | No |
campaign | object | Yes |
reason | string | Yes |
google_ads_edit
Changes what a Google Ads account already has: ad texts, paths and final URLs, keywords, names, campaign dates, target CPA or ROAS, asset group texts, extensions, places, languages, search themes and audience signals. Google validates every change when it is prepared and again when it is applied, all or nothing.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
changes | array of object | Yes |
reason | string | Yes |
findings_apply_to_draft
Applies the fixes that findings of one account propose for UTM tags, enhancements, placements or tracking. On Meta they go to new paused copies of the campaigns; on Google Ads they edit the live campaigns.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
findingIds | array of string | Yes |
reason | string | Yes |
campaigns_publish_draft
Recovery for a proposal already validated: creates every missing Meta entity, paused, and records the IDs Meta returns. New campaigns start this on their own after approval.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
draftId | string | Yes |
actions_undo
Undoes an applied, reversible action, only while the platform still matches the state Adrails wrote. A later direct change is never overwritten.
Access: proposal for approval, adrails:actions:prepare, owner or admin.
| Input | Type | Required |
|---|---|---|
actionId | string | Yes |
Campaign drafts, templates and media
The campaign editor's drafts, templates and media. Listing reads; everything else changes the workspace without an approval step, and launches nothing.
campaign_drafts
Lists, saves, validates or deletes the workspace's campaign drafts. save takes the Adrails campaign source in source. Publishing goes through campaigns_publish_draft and its approval.
Access: list: read, adrails:read, any member; save, validate, delete: change, adrails:campaigns:write, owner or admin.
| Operation | Input | Type | Required |
|---|---|---|---|
list | adAccountId | string | No |
list | campaignClientId | string | No |
save | draftId | string | No |
save | adAccountId | string | Yes |
save | source | object | Yes |
validate | draftId | string | Yes |
delete | campaignClientIds | array of string | Yes |
campaign_templates
Lists, creates, updates or deletes reusable campaign templates, with the template content in payload.
Access: list: read, adrails:read, any member; create, update, delete: change, adrails:campaigns:write, owner or admin.
| Operation | Input | Type | Required |
|---|---|---|---|
list | channel | one of Meta Ads, Google Ads | No |
list | view | string | No |
create | name | string | Yes |
create | channel | one of Meta Ads, Google Ads | Yes |
create | payload | object | Yes |
create | view | one of campaigns, adsets, ads | Yes |
update | name | string | Yes |
update | channel | one of Meta Ads, Google Ads | Yes |
update | payload | object | Yes |
update | templateId | string | Yes |
delete | templateId | string | Yes |
campaign_media
Lists an account's Meta or Google Ads images and videos, or uploads one PNG, JPEG or GIF image sent as base64, at most 512,000 bytes once decoded. Larger images and videos go through the uploader in Campaigns.
Access: list: read, adrails:read, any member; upload: change, adrails:campaigns:write, owner or admin.
| Operation | Input | Type | Required |
|---|---|---|---|
list | platform | one of meta, google_ads | Yes |
list | accountId | string | Yes |
list | kind | one of image, video | No |
upload | platform | one of meta, google_ads | Yes |
upload | accountId | string | Yes |
upload | fileName | string | Yes |
upload | mimeType | one of image/png, image/jpeg, image/gif | Yes |
upload | base64 | string | Yes |
Accounts and integrations
Connected ad accounts and data sources. Credentials are never asked for or returned: connecting and reconnecting go through a setup link you open in Adrails.
accounts_list
Connected ad accounts with platform, currency, time zone, last snapshot and whether they are enabled. 100 per page: pass nextCursor as after.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
after | string | No |
accounts_update
Enables or disables an ad account in the workspace. Disabling stops its polling and hides its data; it does not pause any ad.
Access: change, adrails:integrations:manage, owner or admin.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
enabled | boolean | Yes |
integrations_status
What the workspace has connected, what each source can do, and how fresh each of its data streams is.
Access: read, adrails:read, any member.
No inputs.
integrations_catalog
The providers Adrails can connect: Meta and every registered integration, with how each authenticates, what it provides and the fields its connection asks for.
Access: read, adrails:read, any member.
No inputs.
integrations_detail
One connection's imported data coverage, sync streams and trend. For a Meta connection: its profile name, token expiry, scopes, last error and up to 100 ad accounts.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
connectionId | string | Yes |
integrations_connect
Creates a setup link to connect a provider named as integrations_catalog names it. The link is valid for 10 minutes and usable once, by you, signed in to Adrails as an owner or admin of the connection's workspace. You authorize the provider or enter its credentials there.
Access: change, adrails:integrations:manage, owner or admin.
| Input | Type | Required |
|---|---|---|
provider | string | Yes |
integrations_update
Creates a setup link, on the same terms, to reconnect an existing connection and refresh its credentials or access.
Access: change, adrails:integrations:manage, owner or admin.
| Input | Type | Required |
|---|---|---|
connectionId | string | Yes |
integrations_sync
Queues a synchronization of one connection. For Meta, it refreshes the connection's enabled accounts, up to 10; beyond that, use meta_sync per account. A queued sync is not fresh data yet.
Access: change, adrails:integrations:manage, owner or admin.
| Input | Type | Required |
|---|---|---|
provider | string | Yes |
connectionId | string | Yes |
integrations_disconnect
Disconnects one connection: Adrails revokes it and stops importing its data. Connecting again needs the provider's authorization.
Access: change, adrails:integrations:manage, owner or admin.
| Input | Type | Required |
|---|---|---|
provider | string | Yes |
connectionId | string | Yes |
meta_sync
Queues a refresh of one Meta or Google Ads account. The refresh runs after the call returns and changes no campaign or spend.
Access: change, adrails:integrations:manage, owner or admin.
| Input | Type | Required |
|---|---|---|
accountId | string | Yes |
Automations
The workspace's automations and the channels they post to.
workflows_list
The workspace's automations with their definition, state and next run, and the templates available. 100 per page: pass nextCursor as after.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
after | string | No |
workflows_manage
Creates an automation from a template, or duplicates, saves, enables, disables or deletes one. An enabled automation can send messages and act on accounts within its product limits.
Access: create, duplicate, save, set_enabled, delete: change, adrails:workflows:manage, owner or admin.
| Operation | Input | Type | Required |
|---|---|---|---|
create | templateId | string | Yes |
create | timeZone | string | Yes |
create | adPlatform | one of meta, google_ads | No |
duplicate | automationId | string | Yes |
save | automationId | string | Yes |
save | name | string | Yes |
save | definition | object | Yes |
set_enabled | automationId | string | Yes |
set_enabled | enabled | boolean | Yes |
delete | automationId | string | Yes |
workflows_preview
Previews an automation (workflow) or one integration source of it (source) without sending messages or applying anything.
Access: workflow: read, adrails:read, owner or admin; source: read, adrails:read, any member.
| Operation | Input | Type | Required |
|---|---|---|---|
workflow | automationId | string | Yes |
workflow | definition | object | Yes |
source | node | object | Yes |
source | timeZone | string | Yes |
workflows_run
Runs a saved automation now, on the Adrails worker, and returns a background job to follow with jobs_status. The run can send messages and act on accounts, under the workspace's plan and limits.
Access: change, adrails:workflows:manage, owner or admin.
| Input | Type | Required |
|---|---|---|
automationId | string | Yes |
channels_manage
Lists, creates, updates, tests or deletes the Slack, Discord or email channels automations post to. Creating, testing or changing a webhook channel sends it a connection message; an email channel saves its recipients without sending a test. A listing never returns a channel's target.
Access: list: read, adrails:read, any member; create, update, test, delete: change, adrails:workflows:manage, owner or admin.
| Operation | Input | Type | Required |
|---|---|---|---|
list | after | string | No |
create | name | string | Yes |
create | kind | one of slack, discord, email | Yes |
create | target | string | No |
create | webhookUrl | URL | No |
update | name | string | Yes |
update | channelId | string | Yes |
update | target | string | No |
update | webhookUrl | URL | No |
test | channelId | string | Yes |
delete | channelId | string | Yes |
Knowledge, history and jobs
knowledge_skills
Finds and reads the workspace's Knowledge methods: by command key to read one in full, or by query, then skillId. A listing returns names and descriptions only, paginated with offset.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
skillId | string | No |
command | string | No |
query | string | No |
offset | integer | No |
knowledge_manage
Creates, updates, favorites or deletes a Knowledge entry. fields takes skillId, command, kind (skill or shortcut), name, description, prompt, metaScope, integrationScope, metaAccountIds, integrationConnectionIds and favorite. Any member can manage shortcuts; a skill, which the agent follows on its own, needs an owner or admin.
Access: change, adrails:knowledge:write, any member.
| Input | Type | Required |
|---|---|---|
operation | one of create, update, favorite, delete | Yes |
fields | object | Yes |
conversation_recall
Reads this connection's own history, never another conversation or workspace: past exchanges by keyword (messages), one turn in full (message), or the recorded actions (actions). History records what was said, not what was executed.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
mode | one of messages, message, actions | No |
query | string | No |
beforePosition | integer | No |
turnId | string | No |
part | one of user, assistant, entities | No |
offset | integer | No |
jobs_status
The stored state of background jobs, campaign publications, actions, automation runs, or this connection's own calls (operation, by tool and key): the 25 most recent, or one by id. Pending, applied and failed stay distinct.
Access: read, adrails:read, any member.
| Input | Type | Required |
|---|---|---|
kind | one of background, publication, action, workflow, operation | No |
id | string | No |
tool | string | No |
key | string | No |
Connect an AI client
Add the Adrails MCP server to Claude, Claude Code, ChatGPT, Codex or another remote MCP client, step by step, then check the connection.
MCP security
How the MCP server keeps a connection inside one workspace and the permissions you granted, what data leaves Adrails through it, and what Adrails records.