Evoby Alison MCP docs Open Evo →
Model Context Protocol

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 tools13 analytics + creative previews + Preflight
SSO sign-inOAuth 2.1 — no token to distribute
Server-side scopethe 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.

  1. Add the serverOne command, just the URL — no token, no config file to edit.
  2. It comes back unauthorizedNot connected yet. The 401 says where to authenticate, so the client opens that page (or hands you the link).
  3. Sign in and approveEvo's page: Google or Microsoft SSO, pick which product this client may read, Approve.
  4. The token is stored for youMinted 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:

  1. Sign in to Evo — with your Alison account, through Google or Microsoft SSO.
  2. 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:

StepEndpoint
Challenge401 + WWW-Authenticate naming the resource metadata
Discovery/.well-known/oauth-protected-resource/mcp → /.well-known/oauth-authorization-server
RegistrationPOST /oauth/register — RFC 7591, public client, no secret issued
AuthorizationGET /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)
TokenPOST /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.

ToolWhat it does
Orientation
scope_overviewOne call to orient: what you can measure, what you can group by, and the rules that apply. Start here.
list_integrationsAd-network connections in scope, with metadata.
describe_integrationsPer-integration coverage, freshness, MMP and custom metrics.
list_kpisAvailable KPIs, raw metrics and dimensions, tiered to keep context small.
list_featuresAnnotation features and their tag values for given integrations.
discover_filtersReal filter values available for a scope and date range.
describe_marketing_entityCampaign / ad-group / ad metadata from the marketing catalog.
get_asset_labelsAnnotation labels for specific assets.
Analysis
run_reportCompose and execute a report: metrics × dimensions × filters over a date range.
run_recipeRun 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_metricsCompetition measures and dimensions.
discover_competition_filtersDistinct competition values: country, ad type, competitor name.
run_competition_reportQuery competitor creatives, counts and presence.
Media
get_creativePublic thumbnail / preview URLs for creative ids you already hold. Batch up to 25 per call.
Preflight
list_preflight_runsYour completed Preflight runs — creatives scored before launch — newest first, paged.
get_preflight_runOne 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

StatusMeaningFix
401Missing, invalid, revoked or expired token.Reconnect — the client runs the sign-in flow again.
403The 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.
42920 rejected auth attempts from one IP inside 15 minutes.Fix the credential and wait out the window. Authenticated traffic is never rate-limited.
503The credential store is unreachable — our dependency, not your request.Retry with backoff.
validation_errorArguments 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.