Evo MCP server

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: email or 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

https://evo.alison.ai/mcp

{
  "mcpServers": {
    "evo": { "url": "https://evo.alison.ai/mcp" }
  }
}

codex mcp add evo --url https://evo.alison.ai/mcp
codex mcp login evo

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'
# 14

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 — email and password, or Google, Microsoft or LinkedIn 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:

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.

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.

Errors & limits

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. Neither is the authorization boundary — the grant is.