Alison AI MCP
Creative intelligence from your ad accounts, inside your AI assistant.
Documentation
Evo MCP server
Point any MCP client — Claude Code, Claude, Cursor, Codex — at Evo and it reads your creative-performance warehouse directly: spend and KPIs, creative tags, competitor intelligence, previews. Read-only, and scoped to the accounts each user already has.
Server URL https://evo.alison.ai/mcp streamable-http read-only
16 tools 13 analytics + creative previews + Preflight
SSO sign-in OAuth 2.1 — no token to distribute
Server-side scope the grant decides, not the client
Overview
What you get, and what you can't do with it.
The MCP surface is the same analytics engine that Evo's own analyst agent runs on, exposed directly to your client. Every tool is a read: nothing on this surface writes, mutates, or spends model budget. There is no SQL to author — the tools take structured arguments (metrics, dimensions, filters) and compile them server-side against the KPI registry.
The server speaks streamable-http at /mcp. Both /mcp and /mcp/ work, so a client that doesn't follow redirects still connects.
Quickstart
Add the server with no credential. Everything else happens in your browser, once.
- Add the server One command, just the URL — no token, no config file to edit.
- It comes back unauthorized Not connected yet. The
401says where to authenticate, so the client opens that page (or hands you the link). - Sign in and approve Evo's page: Google or Microsoft SSO, pick which product this client may read, Approve.
- The token is stored for you Minted server-side, kept by the client, reused on every later call. Nobody has to handle it.
claude mcp add --transport http evo https://evo.alison.ai/mcp
Then run /mcp, pick evo, and authenticate — your browser opens on the Evo sign-in page, you choose a product and approve, and Claude Code keeps the token it's handed.
Pre-approving every tool is safe. All 16 are read-only and none spends model budget, so there is nothing here worth a per-call confirmation prompt.
Authentication
Your users sign in with the identity they already have. Nothing to provision, no credential to distribute.
The browser flow
The client's first call comes back 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource/mcp. From there the client registers itself and opens Evo, where the user sees two screens:
- Sign in to Evo — with your Alison account, through Google or Microsoft SSO.
- Connect “<client name>” — choose which product this client may read, then Approve or Deny.
On approval the server mints a token and hands it back through the redirect. The client stores it and reconnects on its own; it is never displayed, and the product chosen on that screen is the ceiling on what the client can ever see. Some clients open the browser for you, others print the URL — same pages either way.
Under the hood
OAuth 2.1 with PKCE and dynamic client registration, so no client is pre-provisioned on either side. A client that cannot register itself (Gemini Enterprise) is registered once with the same call, by hand — see its quickstart tab. A client running on your machine may call back to any loopback address; a hosted client, whose callback is a page on its vendor's servers, is admitted by exact URL only — Claude, Gemini Enterprise, ChatGPT (with Codex on the web) and Antigravity today:
| Step | Endpoint |
|---|---|
| Challenge | 401 + WWW-Authenticate naming the resource metadata |
| Discovery | /.well-known/oauth-protected-resource/mcp → /.well-known/oauth-authorization-server |
| Registration | POST /oauth/register — RFC 7591, public client, no secret issued |
| Authorization | GET /oauth/authorize — the screens above; PKCE S256 required, an unregistered redirect_uri is rejected without a redirect, and every redirect back names the issuer (iss, RFC 9207) |
| Token | POST /oauth/token — single-use code, PKCE-verified, 60s TTL |
Revoking access
GET /api/keys lists every client connected under your user — name, product, when it was created, when it was last used. DELETE /api/keys/{id} disconnects one. Revocation is immediate, not eventually consistent: authorization is re-resolved from the store on every single request and never cached, so the next call from that client fails closed.
Scope & permissions
The client cannot widen its own reach. Only the server decides what's visible.
Every request resolves the token to the accounts its user holds within the product it was approved for, and that set becomes the query grant. An integration_ids outside the grant comes back as a validation_error — never as data, never as a silent empty result. A token whose accounts carry no servable data is refused outright rather than handed zeroes.
The same rule governs the product tools, so get_creative cannot reach an asset the analytics tools would refuse, and a Preflight run is visible only through an account in the grant.
draft_content — the agent loop's copy-writing tool — is deliberately not mounted here: it spends a model call per invocation, so exposing it would widen what a connected client can do rather than replace anything the read tools already offer.
Every call is logged with the calling user, the client's token and the product it was approved for, so traffic on this surface is attributable to a person rather than to a shared service account.
Tool reference
The map, not the API reference — your client reads every argument schema over the protocol and fills them in itself. scope_overview is where a session starts: one call that reports what these accounts can be measured and grouped by.
| Tool | What it does |
|---|---|
| Orientation | |
scope_overview | One call to orient: what you can measure, what you can group by, and the rules that apply. Start here. |
list_integrations | Ad-network connections in scope, with metadata. |
describe_integrations | Per-integration coverage, freshness, MMP and custom metrics. |
list_kpis | Available KPIs, raw metrics and dimensions, tiered to keep context small. |
list_features | Annotation features and their tag values for given integrations. |
discover_filters | Real filter values available for a scope and date range. |
describe_marketing_entity | Campaign / ad-group / ad metadata from the marketing catalog. |
get_asset_labels | Annotation labels for specific assets. |
| Analysis | |
run_report | Compose and execute a report: metrics × dimensions × filters over a date range. |
run_recipe | Run a pre-composed analysis from the recipe catalog in one call (tag pairs, KPI trend, top performers, annotation coverage, banded uplift). |
| Competitive intelligence | |
list_competition_metrics | Competition measures and dimensions. |
discover_competition_filters | Distinct competition values: country, ad type, competitor name. |
run_competition_report | Query competitor creatives, counts and presence. |
| Media | |
get_creative | Public thumbnail / preview URLs for creative ids you already hold. Batch up to 25 per call. |
| Preflight | |
list_preflight_runs | Your completed Preflight runs — creatives scored before launch — newest first, paged. |
get_preflight_run | One run per creative × network: scores, every detected feature and tag, scored features and suggested edits. |
Report rows carry creative ids, not images. When you want to see the creatives, pass the ids from run_report, run_recipe or run_competition_report into one batched get_creative call.
Preflight scores uploaded creatives against best-practice rubrics, and optionally the account's own history, before they ever run. Its runs are not ad-performance data, so the report tools never see them, and a Preflight creative_id resolves in neither run_report nor get_creative — each run carries its own public media_url and thumbnail_url.
Errors & limits
| Status | Meaning | Fix |
|---|---|---|
| 401 | Missing, invalid, revoked or expired token. | Reconnect — the client runs the sign-in flow again. |
| 403 | The token is valid, but its user has no servable accounts in the product it was approved for. | Reconnect and choose a different product, or have account access granted. |
| 429 | 20 rejected auth attempts from one IP inside 15 minutes. | Fix the credential and wait out the window. Authenticated traffic is never rate-limited. |
| 503 | The credential store is unreachable — our dependency, not your request. | Retry with backoff. |
validation_error | Arguments outside the grant, or a report the KPI registry can't compile. | Caller-fixable — the message names what to change. |
HTTP status codes cover transport and authentication only. A tool that refuses its arguments answers 200 with an error_kind in the result, so your client can correct itself and retry rather than treating it as an outage.
Per-call blast radius is bounded at 150 integration ids in one list, and get_creative takes at most 25 ids per call, list_preflight_runs 50 runs per page and get_preflight_run 50 creatives per call. None is the authorization boundary — the grant is.
For Alison staff: one session per product
Reporting on several clients? Don't switch products inside one chat — a session that has seen one client's numbers can blend them into the next client's report, and no token swap fixes what is already in the model's context. Open one Claude Code session per product instead, side by side when you need two.
Set up your products (sign in with your alison.ai account). The page installs Claude Code once, then one pasted line per product creates a folder for it, connects it to https://evo.alison.ai/mcp/p/<product id> and to no other MCP server, and leaves a launcher on your desktop. The first time, Evo's consent page comes up already set to that product and you approve; every day after, double-click the launcher. The window runs unattended: that product's Evo tools and files in its folder need no approval, and auto mode handles the rest, so several clients can run side by side while you review.
The lock is Evo's own: a /mcp/p/<id> URL refuses every key bound to a different product, so a session can't be pointed at another client's data by a wrong pick at consent. The launcher starts Claude Code with --strict-mcp-config, which drops every other MCP server and every claude.ai connector, the plain /mcp from the quickstart above included. Use the terminal launcher for reporting, not the Claude Desktop app's Code tab or a claude.ai chat. The Code tab loads every connector on your account into every session, with no way to leave one out. A claude.ai chat lets you switch connectors off per chat, but nothing enforces the choice, and memory and past-chat search carry context across chats unless you turn them off.