Integração MCP

O Model Context Protocol (MCP) permite que assistentes de IA consultem sua análise do Zenovay diretamente. Faça perguntas como "Quantos visitantes recebi esta semana?" ou "Quais são minhas principais páginas?" e obtenha dados ao vivo do seu painel — sem sair do seu IDE ou chat.

Início rápido

Conectar leva menos de um minuto. Basta adicionar a URL do servidor ao seu cliente MCP — o OAuth cuida do resto.

1. Adicione o servidor MCP

Adicione a URL do servidor Zenovay ao seu cliente de IA. Nenhuma chave de API ou configuração manual necessária.

{
"mcpServers": {
  "zenovay-analytics": {
    "url": "https://api.zenovay.com/mcp"
  }
}
}

{
"mcpServers": {
  "zenovay-analytics": {
    "url": "https://api.zenovay.com/mcp"
  }
}
}

{
"servers": {
  "zenovay-analytics": {
    "type": "http",
    "url": "https://api.zenovay.com/mcp"
  }
}
}

{
"mcpServers": {
  "zenovay-analytics": {
    "serverUrl": "https://api.zenovay.com/mcp"
  }
}
}

Você também pode adicioná-lo via Claude Code CLI:

claude mcp add --transport http zenovay-analytics https://api.zenovay.com/mcp

2. Autorize o acesso

Quando você se conectar pela primeira vez, seu cliente MCP abrirá uma janela do navegador mostrando a página de autorização do Zenovay. Lá você pode:

• Selecionar sua equipe (se você pertencer a várias equipes)
• Definir permissões para cada categoria de ferramentas (Nenhum / Leitura / Escrita)
• Clicar em Autorizar para conceder acesso

Esta é uma configuração única. Seu cliente MCP armazena o token OAuth e o atualiza automaticamente.

3. Comece a consultar

Após a autorização, você pode fazer perguntas ao seu assistente de IA como:

• "Liste meus sites"
• "Quantos visitantes zenovay.com recebeu esta semana?"
• "Quais são as 10 páginas com mais tráfego?"
• "Compare a taxa de rejeição desta semana com a da semana passada"
• "Mostre-me quaisquer anomalias no meu tráfego"
• "Exporte os últimos 30 dias de análises como CSV"
• "Crie uma nova meta para minha página de cadastro"
• "Mostre todas as minhas metas e suas taxas de conversão"
• "Adicione uma exclusão de IP para a rede do nosso escritório"

Como funciona a Autorização OAuth

Quando seu cliente MCP se conecta a https://api.zenovay.com/mcp, o seguinte acontece automaticamente:

1. Descoberta — O cliente busca os metadados OAuth em /.well-known/oauth-authorization-server
2. Registro — O cliente se registra (uma única vez) via Registro Dinâmico de Cliente
3. Autorização — Uma janela do navegador abre mostrando a página de consentimento do Zenovay
4. Troca de tokens — Após você autorizar, o cliente troca o código por um token de acesso
5. Conectado — Todas as solicitações MCP usam o token OAuth. Ele é atualizado automaticamente quando expira.

Você pode visualizar e revogar aplicações conectadas em Configurações > Uso no seu painel do Zenovay.

Detalhes de conexão

Permissões

Durante a autorização, você escolhe o nível de acesso para cada categoria de ferramentas:

Categorias de ferramentas

Limites de taxa

Os limites diários de consulta são por equipe (compartilhados entre todas as aplicações conectadas):

A maioria das ferramentas custa 1 consulta. A ferramenta de linguagem natural query_analytics custa 3 consultas devido ao seu processamento de IA.

O uso é redefinido diariamente às 00:00 UTC. Verifique sua cota restante a qualquer momento com a ferramenta get_api_usage ou em Configurações > Uso no seu painel.

Aplicação dos planos

Algumas ferramentas MCP estão restritas a planos pagos. Ferramentas como get_session_replays, get_heatmap_data, get_revenue e get_retention_data exigem uma assinatura Pro ou superior, enquanto export_data exige Scale ou superior. As consultas de análise são automaticamente limitadas à janela de retenção de dados do seu plano (por exemplo, 1 ano para Free, 2 anos para Pro).

{
"jsonrpc": "2.0",
"id": 1,
"error": {
  "code": -32002,
  "message": "This feature requires a paid plan. Upgrade at https://app.zenovay.com/plans"
}
}

Gerenciando aplicações conectadas

Você pode visualizar e revogar tokens OAuth para clientes MCP conectados:

1. Acesse Configurações > Uso no seu Painel do Zenovay
2. Role até a seção Requisições MCP
3. Visualize o uso diário, limites de taxa e quantidade de aplicações conectadas
4. Para revogar o acesso, vá em Chaves de API e gerencie os tokens a partir de lá

Revogar um token desconecta imediatamente o cliente MCP. O cliente precisará reautorizar para se reconectar.

Tratamento de erros

Quando algo dá errado, o servidor retorna um erro JSON-RPC:

Solução de problemas

"Needs authentication" no Claude Code

Isso significa que o fluxo OAuth ainda não foi concluído. Execute claude mcp list para verificar o status e, em seguida, inicie uma nova sessão — ela solicitará que você autorize no navegador.

O navegador não abre para autorização

Certifique-se de que seu cliente MCP suporte OAuth 2.1. Se estiver usando um cliente mais antigo, verifique se há atualizações. Apenas a URL do servidor (https://api.zenovay.com/mcp) deve acionar a descoberta automática de OAuth.

"Invalid or expired OAuth token"

Seu token expirou e a atualização automática falhou. Remova o servidor e adicione-o novamente:

claude mcp remove zenovay-analytics
claude mcp add --transport http zenovay-analytics https://api.zenovay.com/mcp

Erros de limite de taxa

Verifique seu uso atual com get_api_usage ou em Configurações > Uso. A ferramenta query_analytics custa 3 consultas — use ferramentas específicas como get_visitors (1 consulta) quando possível.

Prompt para assistentes de IA

Se o seu assistente de IA não detectar automaticamente o servidor MCP, você pode colar este prompt para ajudá-lo a se conectar:

Connect to the Zenovay Analytics MCP server at https://api.zenovay.com/mcp

Authentication: OAuth 2.1 (automatic). When you first connect, a browser window will open for me to authorize access. No API key is needed.

Setup:
- Server URL: https://api.zenovay.com/mcp
- Transport: HTTP (Streamable HTTP, JSON-RPC 2.0)
- OAuth discovery: https://api.zenovay.com/.well-known/oauth-authorization-server

After connecting, call list_websites first to get my website IDs — every analytics tool requires a website_id parameter.

Available tool categories:
- Analytics (8 tools): visitors, pages, traffic sources, geographic data, real-time
- Advanced (13 tools): funnels, goals, sessions, heatmaps, errors, revenue, uptime
- AI Insights (4 tools): AI-generated insights, anomalies, weekly digest, recommendations
- Management (29 tools): website settings, goals, funnels, tracking, reports
- Settings (16 tools): IP exclusions, notifications, team members, domains
- Webhooks (6 tools): webhook CRUD, deliveries, automation rules

Rate limits: Free 25/day, Pro 100/day, Scale 500/day, Enterprise 10,000/day. The query_analytics tool costs 3 queries; all others cost 1.

Próximos passos

• Referência de Ferramentas — Documentação completa de todas as ferramentas com parâmetros e exemplos
• Permissões e Limites — Modos de acesso, limites de taxa e códigos de erro