Adrails Docs

MCP server

Connect Claude, ChatGPT or another AI assistant to your Adrails workspace through MCP, with OAuth sign-in and permissions for reads and proposed changes.

Adrails runs a remote MCP server. An AI assistant that supports remote MCP with OAuth connects to it, signs in with your Adrails account, and works in the one workspace you choose: it reads your accounts, figures and findings, prepares campaigns and advertising changes that you apply in Adrails, and, if you allow it, manages integrations, automations, Knowledge and campaign drafts.

The assistant's own model does the reasoning. Adrails returns data, prepares changes and applies nothing to an ad account without your approval in Adrails.

No Adrails account yet? Start the free preview: 10 free credits, no card. Connect your ad accounts, then add the server URL below to your assistant.

Server URL

https://adrails.ai/api/mcp

  • Transport: Streamable HTTP, POST only, JSON responses. GET and DELETE answer 405: there is no event stream and no session.
  • Authentication: an OAuth 2.1 bearer token, obtained through the sign-in below.
  • Tools: 78, described in the tools reference.

In Adrails, MCP connection settings give the same URL with setup steps for each client, your connections and the tool catalog. Settings > Account > AI connections links there too.

Before connecting an AI client, connect your ad accounts in Adrails: Meta Ads setup or Google Ads setup.

How connecting works

  1. You add the server URL to your client. See Connect an AI client.
  2. The client identifies itself to Adrails, with its published metadata document or by registering itself, then opens Adrails in your browser. There is no client ID or secret to copy.
  3. You sign in to Adrails if you are not already.
  4. The consent screen, titled with the client's name, such as Connect Claude to Adrails, asks for the Workspace and the Permissions this client receives. The workspace list shows your role in each.
  5. Allow access sends you back to the client, connected. Cancel refuses.

You cannot give consent in an impersonated session, or before you belong to a workspace.

Permissions

The consent screen lists only the permissions your client asked for. A client that asks for nothing in particular gets read access only.

PermissionScopeWhat it allowsSelected at firstWho can use it
Read workspace dataadrails:readRead accounts, analysis, campaigns, commerce and Knowledge. Required.YesAny member
Stay connectedoffline_accessRenew access without signing in again, until you revoke the connection.YesAny member
Prepare advertising changesadrails:actions:preparePrepare advertising changes, launches and undos for your approval in Adrails.NoRoles with that right
Manage integrationsadrails:integrations:manageConnect, synchronize and disconnect integrations, enable or disable ad accounts.NoRoles with that right
Manage automationsadrails:workflows:manageManage automations and their channels, and run them, including message delivery.NoRoles with that right
Edit Knowledgeadrails:knowledge:writeCreate, update, favorite and delete workspace Knowledge.NoAny member
Manage campaign assetsadrails:campaigns:writeManage campaign drafts, templates and media.NoRoles with that right
  • Any member allowed to connect AI clients can select any permission the client asked for. A permission never goes beyond the member's role: a tool the role cannot use stays hidden from the client. Owners and admins hold every write permission by default.
  • Read access cannot be left out: consent without it is refused.
  • Select a write permission only for what you want the assistant to do.
  • A permission never goes beyond your role. A member who connects with Edit Knowledge still cannot change skills, and a tool stops working the day your role no longer allows what it needs. Which tool needs what: Who can call what.

One workspace per connection

  • The connection works in the workspace you chose on the consent screen, for as long as it lasts. Switching workspace in Adrails does not move it.
  • To work in another workspace, connect again and choose it. Each workspace is a separate connection.
  • Read access covers the whole workspace: every ad account and integration it has. A call can narrow to some accounts, never reach past them.

Tokens

TokenLifetime
Access token10 minutes
Authorization code10 minutes, single use
Refresh token30 days, replaced at every use
  • The client renews its access token with a refresh token only if you granted Stay connected. Without it, the client sends you through sign-in again once the access token expires.
  • A refresh token used a second time is refused.
  • A connection left unused for 30 days has to be authorized again.

Revoke access

Open MCP in Adrails and go to Your connections, at https://adrails.ai/mcp/access#mcp-connections. It lists every AI client you authorized, in all your workspaces, each with its workspace and its Allowed access. Revoke access asks you to confirm.

Once revoked:

  • The next request from that client is refused, and its tokens cannot be renewed.
  • Its setup links and approval links stop working.
  • Calls already running, changes already applied and automations already started are not undone.

Removing Adrails from your AI client does not revoke the connection in Adrails: revoke it here too.

Access also ends when you leave the workspace or are removed from it, and when the refresh token goes unused for 30 days. A client can revoke its own tokens at the revocation endpoint below.

Plans and credits

The connection uses your workspace's plan, roles and limits, the same as the app. MCP tool calls cost 0 credits, reads and changes alike: your AI client does the thinking, so there is no AI message of Adrails to count. Applying a proposal needs an active paid plan. See Who can call what.

For client developers

Clients find everything below through discovery; it is listed for checking a setup.

Document or endpointURL
Protected resource metadatahttps://adrails.ai/.well-known/oauth-protected-resource
Authorization server metadatahttps://adrails.ai/.well-known/oauth-authorization-server
Issuerhttps://adrails.ai/api/auth
Client registrationhttps://adrails.ai/api/auth/oauth2/register
Authorizationhttps://adrails.ai/api/auth/oauth2/authorize
Tokenhttps://adrails.ai/api/auth/oauth2/token
Revocationhttps://adrails.ai/api/auth/oauth2/revoke
  • A request without a valid token gets 401 with WWW-Authenticate: Bearer resource_metadata="https://adrails.ai/.well-known/oauth-protected-resource".
  • Clients register dynamically, with no credentials. Client ID metadata documents are not supported.
  • The grant is the authorization code with PKCE, method S256, then the refresh token.
  • The authorization request and the token request both carry resource=https://adrails.ai/api/mcp. Tokens are issued for that resource only.
  • The protected resource metadata lists the six Adrails scopes. Add offline_access to receive a refresh token.

Launch briefs ask their open questions in your AI conversation and accept free-text answers; they do not render an Adrails card in your AI client. Proposal review links stay valid for 24 hours and any current workspace owner or admin may review them. A grant without adrails:actions:prepare must reconnect with that permission before preparing advertising changes.

On this page