Alison AI MCP

Servidor Evo MCP

Aponte qualquer cliente MCP — Claude Code, Claude, Cursor, Codex — para o Evo e ele lê diretamente seu warehouse de performance criativa: gastos e KPIs, tags criativas, inteligência competitiva, pré-visualizações. Somente leitura, e limitado às contas que cada usuário já possui.

URL do servidor https://evo.alison.ai/mcp streamable-http somente leitura

14 ferramentas 13 de analytics + pré-visualizações criativas

Login SSO OAuth 2.1 — nenhum token para distribuir

Escopo no servidor a concessão decide, não o cliente

Visão geral

O que você obtém, e o que não pode fazer com ele.

A superfície MCP é o mesmo mecanismo de analytics que o próprio agente analista do Evo utiliza, exposto diretamente ao seu cliente. Cada ferramenta é uma leitura: nada nesta superfície grava, altera ou gasta orçamento de modelo. Não há SQL para escrever — as ferramentas aceitam argumentos estruturados (métricas, dimensões, filtros) e os compilam no servidor contra o registro de KPIs.

O servidor fala streamable-http em /mcp. Tanto /mcp quanto /mcp/ funcionam, então um cliente que não segue redirecionamentos ainda consegue se conectar.

---

Início rápido

Adicione o servidor sem credencial. Todo o resto acontece no seu navegador, uma única vez.

1. Adicione o servidor Um comando, apenas a URL — sem token, sem arquivo de configuração para editar.
2. Ele retorna não autorizado Ainda não conectado. O 401 indica onde autenticar, então o cliente abre essa página (ou entrega o link para você).
3. Entre e aprove Página do Evo: e-mail ou SSO, escolha qual produto este cliente pode ler, Aprovar.
4. O token é armazenado para você Gerado no servidor, mantido pelo cliente, reutilizado em cada chamada posterior. Ninguém precisa lidar com ele.

claude mcp add --transport http evo https://evo.alison.ai/mcp

Em seguida, execute /mcp, escolha evo e autentique — seu navegador abre na página de login do Evo, você escolhe um produto e aprova, e o Claude Code mantém o token que recebeu.

Pré-aprovar todas as ferramentas é seguro. Todas as 14 são somente leitura e nenhuma gasta orçamento de modelo, então não há nada aqui que valha um prompt de confirmação por chamada.

---

Autenticação

Seus usuários entram com a identidade que já possuem. Nada para provisionar, nenhuma credencial para distribuir.

O fluxo no navegador

A primeira chamada do cliente retorna 401 com um cabeçalho WWW-Authenticate apontando para /.well-known/oauth-protected-resource/mcp. A partir daí, o cliente se registra e abre o Evo, onde o usuário vê duas telas:

1. Entre no Evo — e-mail e senha, ou SSO do Google, Microsoft ou LinkedIn.
2. Conecte “<client name>” — escolha qual produto este cliente pode ler e, em seguida, Aprovar ou Negar.

Após a aprovação, o servidor gera um token e o devolve pelo redirecionamento. O cliente o armazena e reconecta sozinho; ele nunca é exibido, e o produto escolhido nessa tela é o teto do que o cliente pode ver. Alguns clientes abrem o navegador para você, outros imprimem a URL — as mesmas páginas de qualquer forma.

Por baixo dos panos

OAuth 2.1 com PKCE e registro dinâmico de cliente, então nenhum cliente é pré-provisionado em nenhum dos lados:

Etapa	Endpoint
Desafio	401 + WWW-Authenticate nomeando os metadados do recurso
Descoberta	/.well-known/oauth-protected-resource/mcp → /.well-known/oauth-authorization-server
Registro	POST /oauth/register — RFC 7591, cliente público, nenhum segredo emitido
Autorização	GET /oauth/authorize — as telas acima; PKCE S256 obrigatório, um redirect_uri não registrado é rejeitado sem redirecionamento
Token	POST /oauth/token — código de uso único, verificado por PKCE, TTL de 60s

Revogando acesso

GET /api/keys lista cada cliente conectado sob seu usuário — nome, produto, quando foi criado, quando foi usado pela última vez. DELETE /api/keys/{id} desconecta um. A revogação é imediata, não eventualmente consistente: a autorização é re-resolvida a partir do armazenamento em cada solicitação e nunca é armazenada em cache, então a próxima chamada desse cliente falha de forma segura.

---

Escopo e permissões

O cliente não pode ampliar seu próprio alcance. Somente o servidor decide o que é visível.

Cada solicitação resolve o token para as contas que seu usuário possui dentro do produto para o qual foi aprovado, e esse conjunto se torna a concessão de consulta. Um integration_ids fora da concessão retorna como um validation_error — nunca como dados, nunca como um resultado vazio silencioso. Um token cujas contas não possuem dados utilizáveis é recusado diretamente, em vez de receber zeros.

A mesma regra rege as ferramentas de produto, então get_creative não pode alcançar um ativo que as ferramentas de analytics recusariam.

draft_content — a ferramenta de redação do loop do agente — deliberadamente não está montada aqui: ela gasta uma chamada de modelo por invocação, então expô-la ampliaria o que um cliente conectado pode fazer, em vez de substituir qualquer coisa que as ferramentas de leitura já oferecem.

Cada chamada é registrada com o usuário que a fez, o token do cliente e o produto para o qual foi aprovado, então o tráfego nesta superfície é atribuível a uma pessoa, não a uma conta de serviço compartilhada.

---

Referência de ferramentas

O mapa, não a referência da API — seu cliente lê cada esquema de argumento pelo protocolo e os preenche sozinho. scope_overview é onde uma sessão começa: uma chamada que informa como essas contas podem ser medidas e agrupadas.

Ferramenta	O que faz
Orientação
scope_overview	Uma chamada para se orientar: o que você pode medir, o que pode agrupar e as regras aplicáveis. Comece aqui.
list_integrations	Conexões de redes de anúncios no escopo, com metadados.
describe_integrations	Cobertura por integração, atualização, MMP e métricas personalizadas.
list_kpis	KPIs disponíveis, métricas brutas e dimensões, em camadas para manter o contexto pequeno.
list_features	Recursos de anotação e seus valores de tag para integrações específicas.
discover_filters	Valores reais de filtro disponíveis para um escopo e intervalo de datas.
describe_marketing_entity	Metadados de campanha / grupo de anúncios / anúncio do catálogo de marketing.
get_asset_labels	Rótulos de anotação para ativos específicos.
Análise
run_report	Compor e executar um relatório: métricas × dimensões × filtros em um intervalo de datas.
run_recipe	Executar uma análise pré-composta do catálogo de receitas em uma chamada (pares de tags, tendência de KPI, principais desempenhos, cobertura de anotações, uplift em faixas).
Inteligência competitiva
list_competition_metrics	Medidas e dimensões do SensorTower / Pathmatics.
discover_competition_filters	Valores competitivos distintos: país, SO, tipo de anúncio, nome do concorrente.
run_competition_report	Consultar criativos de concorrentes e participação de voz.
Mídia
get_creative	URLs públicas de miniatura / pré-visualização para ids criativos que você já possui. Lote de até 25 por chamada.

As linhas de relatório carregam ids criativos, não imagens. Quando quiser ver os criativos, passe os ids de run_report, run_recipe ou run_competition_report em uma única chamada em lote de get_creative.

---

Erros e limites

Status	Significado	Correção
401	Token ausente, inválido, revogado ou expirado.	Reconecte — o cliente executa o fluxo de login novamente.
403	O token é válido, mas seu usuário não possui contas utilizáveis no produto para o qual foi aprovado.	Reconecte e escolha um produto diferente, ou conceda acesso à conta.
429	20 tentativas de autenticação rejeitadas de um IP em 15 minutos.	Corrija a credencial e aguarde o período. Tráfego autenticado nunca é limitado por taxa.
503	O armazenamento de credenciais está inacessível — dependência nossa, não sua solicitação.	Tente novamente com backoff.
validation_error	Argumentos fora da concessão, ou um relatório que o registro de KPIs não pode compilar.	Corrigível pelo chamador — a mensagem indica o que mudar.

Os códigos de status HTTP cobrem apenas transporte e autenticação. Uma ferramenta que recusa seus argumentos responde 200 com um error_kind no resultado, para que seu cliente possa se corrigir e tentar novamente, em vez de tratar como uma interrupção.

O raio de impacto por chamada é limitado a 150 ids de integração em uma lista, e get_creative aceita no máximo 25 ids por chamada. Nenhum deles é o limite de autorização — a concessão é.