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.
https://evo.alison.ai/mcp
streamable-http
read-only
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 serverOne command, just the URL — no token, no config file to edit.
- It comes back unauthorizedNot connected yet. The
401says where to authenticate, so the client opens that page (or hands you the link). - Sign in and approveEvo's page: Google or Microsoft SSO, pick which product this client may read, Approve.
- 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.
In Settings → Connectors → Add custom connector, paste the server URL:
https://evo.alison.ai/mcp
Connecting opens the Evo sign-in page. Approve, and the connector is live in new chats.
Add to ~/.cursor/mcp.json (or .cursor/mcp.json to scope it to one
project), then use the Login action on the server in Cursor's MCP settings:
{
"mcpServers": {
"evo": { "url": "https://evo.alison.ai/mcp" }
}
}
codex mcp add evo --url https://evo.alison.ai/mcp
codex mcp login evo
login opens the same sign-in and consent pages and stores the token Codex is
handed. codex mcp logout evo disconnects it.
Gemini Enterprise neither registers itself nor reads the discovery metadata: its custom MCP server form takes the OAuth endpoints and a client ID typed in. A Gemini Enterprise admin registers Evo's side once, from any terminal — no sign-in needed, and the ID that comes back is stable (the same command returns the same ID, and it survives Evo restarts):
curl -s https://evo.alison.ai/oauth/register \
-H 'Content-Type: application/json' \
-d '{"client_name":"Gemini Enterprise","redirect_uris":["https://vertexaisearch.cloud.google.com/oauth-redirect"]}' \
| jq -r .client_id
Then, in Gemini Enterprise, add a custom MCP server with OAuth 2.0 and fill in:
| Field | Value |
|---|---|
| MCP Server URL | https://evo.alison.ai/mcp |
| Authorization URL | https://evo.alison.ai/oauth/authorize |
| Authorization URL Parameters | leave blank — Evo assumes response_type=code and S256 when a client omits them |
| Token URL | https://evo.alison.ai/oauth/token |
| Client ID | the value the command above printed |
| Client Secret | none — Gemini insists on a value; Evo issues no secret and ignores whatever is sent |
| Scopes | read — Evo has one access level and ignores the value; the form wants one |
| Enable PKCE Support | on — Evo requires PKCE (S256) |
| Use HTTP Basic Authentication | off — on, Gemini puts the client ID in an Authorization header, and the token call fails with invalid_client. Evo takes it in the request body. |
Verify Auth runs the browser flow above as you: Evo's sign-in (Google or Microsoft SSO, an Alison account), then the product this connection may read. Every user of the connection does the same the first time they use it, with their own Alison account, so each sees their own products and nothing is shared through the admin.
Authenticating is not the last step: Gemini imports every tool switched off. After the data store is created, open its Actions tab, Reload custom actions, select Evo's tools and Enable actions — until then the connection authenticates and offers nothing.
401, the
user signs in again from Gemini (reload the connection's actions, or the admin re-runs
Verify Auth). If your organisation restricts Gemini Enterprise's egress, allow
evo.alison.ai — the MCP, authorization and token URLs are all on it.In ChatGPT, open Plugins (chatgpt.com/plugins), click +, then
Add custom MCP server. Name it, paste the server URL, choose OAuth, accept the
third-party notice and create it:
https://evo.alison.ai/mcp
ChatGPT registers itself and opens the Evo sign-in page; approve, and the plugin is live in ChatGPT and in Codex on the web. In a Team or Enterprise workspace, adding custom MCP servers is governed by workspace policy, so an admin may have to allow it first.
Add the server to ~/.gemini/config/mcp_config.json (or through
MCP Servers → Add MCP Server in the app), then click Authenticate next to it:
{
"mcpServers": {
"evo": { "serverUrl": "https://evo.alison.ai/mcp" }
}
}
Antigravity registers itself and opens the Evo sign-in page in your browser. Approve, and when the page that follows shows an authorization code, paste it back into Antigravity. No client ID or secret to type.
Any MCP client that speaks streamable-http and OAuth connects the same way — give it the URL and let it authenticate. To sanity-check the connection from a terminal, using the token your client obtained:
curl -s https://evo.alison.ai/mcp \
-H "Authorization: Bearer $EVO_TOKEN" \
-H 'Accept: application/json, text/event-stream' \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq '.result.tools | length'
# 16
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. |
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.