Servidor MCP

O MCP (Model Context Protocol) da Bevits deixa o seu agente consultar os dados da sua organização diretamente, sem você copiar planilhas ou colar resultados de API no chat. Em vez de ensinar o agente a usar a API REST, você conecta uma vez e ele passa a enxergar clientes, compras, segmentos, tags, atributos, flows e campanhas de e-mail como ferramentas nativas.

Endpoint: https://api.bevits.com/mcp · Transporte: Streamable HTTP · Autenticação: OAuth 2.1 · Acesso: somente leitura · 20 tools

A conexão é feita por OAuth: nenhuma API key é colada na configuração do agente. Você entra na Bevits pelo navegador, escolhe a organização e aprova o acesso. O token gerado vale para uma única organização e concede apenas o escopo mcp:read.

Conectar no Claude (claude.ai e app)

Este é o caminho sem terminal. O Claude se conecta ao servidor da Bevits a partir da nuvem da Anthropic, então basta informar o endereço público do endpoint.

Abra Personalizar → Conectores

No Claude, pelo navegador ou pelo app de desktop, vá em Personalizar → Conectores.

Adicione um conector personalizado

Clique em +, depois em Adicionar conector personalizado, e informe a URL do servidor MCP remoto da Bevits:

https://api.bevits.com/mcp

Deixe Configurações avançadas em branco: o servidor da Bevits publica os próprios metadados OAuth, então não é necessário informar Client ID nem Client Secret. Clique em Adicionar.

Conecte sua organização

Clique em Conectar, entre na Bevits pelo navegador, escolha a organização e aprove o acesso somente leitura.

Ative o conector na conversa

No chat, abra o botão +, escolha Conectores e ative Bevits. A partir daí é só perguntar, por exemplo: “quais campanhas de e-mail tiveram a maior taxa de abertura?”.

Em contas Team e Enterprise, um owner adiciona o conector em Configurações da organização → Conectores e cada pessoa depois clica em Conectar para autenticar com a própria conta Bevits — cada uma enxerga apenas os dados da organização que autorizou. Os nomes dos menus podem mudar conforme o Claude é atualizado; a documentação de conectores personalizados tem sempre o passo a passo mais recente.

Conectar no terminal (Claude Code e Codex)

Adicione a Bevits ao seu cliente

Rode o comando no terminal. Os comandos exatos também ficam em Configurações → MCP.

claude mcp add --transport http --scope user \
  --client-id https://app.bevits.com/.well-known/oauth-client/claude-code \
  --callback-port 3118 \
  bevits https://api.bevits.com/mcp

codex mcp add bevits --url https://api.bevits.com/mcp

Autorize sua organização

Inicie o OAuth, faça login na Bevits pelo navegador, escolha a organização e aprove o acesso somente leitura.

/mcp

codex mcp login bevits

Confirme a conexão

Verifique se o servidor aparece conectado e se as 20 tools foram carregadas.

claude mcp list

codex mcp list

Qualquer cliente compatível com MCP via Streamable HTTP e OAuth 2.1 pode se conectar ao mesmo endpoint. Claude Code e Codex são apenas os caminhos documentados.

O que dá para fazer

CRM e clientes

Encontrar clientes por e-mail, telefone, tag, segmento ou busca livre, e ler contato, tags, atributos, endereço padrão e métricas de consumo.

Compras e faturamento

Listar e detalhar pedidos, e agregar faturamento, ticket médio e clientes únicos em uma chamada — com ranking por UTM, plataforma, status ou dia.

Segmentos

Localizar segmentos pelo nome, ver o tamanho de cada um e listar seus clientes ordenados por atualização ou total gasto.

Recuperação de vendas

Medir um flow de carrinho abandonado: taxa de recuperação, faturamento recuperado e conversões por mensagem da sequência.

Campanhas

Campanhas de e-mail com envio, entrega, abertura e clique; campanhas de WhatsApp e SMS com destinatários, entregues, lidas e falhas por template.

Exemplos de perguntas que o agente responde sozinho depois de conectado:

“Quais as UTMs que mais venderam nos últimos 7 dias?”
“Qual a taxa de recuperação e o faturamento recuperado do meu flow de carrinho abandonado?”
“Qual mensagem da sequência de recuperação converte mais?”
“Qual foi o ticket médio deste mês comparado ao mês passado?”
“Quem são os 20 clientes que mais gastaram no segmento VIP e o que compraram?”
“Qual template de WhatsApp teve a pior taxa de entrega?”
“Este cliente está inscrito? Quais tags e atributos ele tem?”
“Quais flows estão ativos e quantas vezes cada um rodou?”

Catálogo de tools

Todas as tools são de leitura (readOnlyHint) e idempotentes. Nenhuma delas cria, altera ou remove dados, e nenhuma aceita um ID de organização — o escopo vem sempre do token.

Identidade

Tool	O que faz
`bevits_get_identity`	Retorna a organização e a credencial ativas da conexão. Útil como primeira chamada para confirmar em qual conta o agente está.

Clientes

Tool	O que faz
`bevits_list_customers`	Lista clientes com filtros de CRM e paginação por cursor.
`bevits_get_customer`	Detalha um cliente por `customer_id` (`cus_...`), com tags, atributos e endereço padrão.
`bevits_list_customer_purchases`	Lista as compras de um cliente específico.

Compras

Tool	O que faz
`bevits_list_purchases`	Lista compras com filtros de comércio e paginação por cursor.
`bevits_get_purchase`	Detalha uma compra por `purchase_id` (`pur_...`).
`bevits_get_purchase_stats`	Agrega compras: pedidos, faturamento, ticket médio e clientes únicos, com ranking opcional por UTM, plataforma, status, moeda ou dia.

Segmentos

Tool	O que faz
`bevits_list_segments`	Lista segmentos, com busca opcional por nome (`q`).
`bevits_get_segment`	Detalha um segmento por `segment_id` (`seg_...`).
`bevits_list_segment_customers`	Lista os clientes de um segmento, com ordenação opcional.

Tags e atributos

Tool	O que faz
`bevits_list_tags`	Lista as tags de cliente da organização.
`bevits_get_tag`	Detalha uma tag por `tag_id` (`tag_...`).
`bevits_list_attributes`	Lista os atributos personalizados de cliente e seus tipos.

Flows e campanhas

Tool	O que faz
`bevits_list_flows`	Lista as automações da organização.
`bevits_get_flow`	Detalha um flow por `flow_id` (`flw_...`).
`bevits_get_flow_metrics`	Métricas do flow no período: entradas, envios, conversões, taxa de conversão, receita recuperada e o mesmo detalhamento por nó de mensagem.
`bevits_list_email_campaigns`	Lista campanhas de e-mail.
`bevits_get_email_campaign`	Detalha uma campanha por `email_campaign_id` (`emc_...`).
`bevits_list_template_campaigns`	Lista campanhas de WhatsApp e SMS feitas a partir de um template.
`bevits_get_template_campaign`	Detalha uma campanha de WhatsApp ou SMS por `template_campaign_id` (`tcp_...`), com todos os templates usados e as métricas de entrega.

Filtros disponíveis

`bevits_list_customers`

Parâmetro	Tipo	Descrição
`q`	texto	Busca livre por nome, e-mail ou telefone.
`email`	e-mail	Busca exata por e-mail.
`phone`	texto	Busca por telefone.
`tag_id`	`tag_...`	Somente clientes com a tag.
`segment_id`	`seg_...`	Somente clientes do segmento.
`is_subscribed`	booleano	Filtra por status de inscrição.
`created_since` / `created_until`	data ISO 8601	Janela de criação do cliente.
`updated_since`	data ISO 8601	Alterados a partir da data.
`sort`	`updated` \| `total_spent`	Ordenação do resultado.

`bevits_list_purchases`

Parâmetro	Tipo	Descrição
`customer_id`	`cus_...`	Compras de um cliente.
`status`	`any`, `pending`, `authorized`, `paid`, `abandoned`, `refunded`, `voided`	Situação do pedido.
`platform`	`nuvemshop`, `shopify`, `woocommerce`, `bling`, `instagram`, `popup`	Origem do pedido.
`created_since` / `created_until`	data ISO 8601	Janela do pedido.
`min_value_in_cents` / `max_value_in_cents`	inteiro	Faixa de valor, em centavos.
`utm_source` / `utm_medium` / `utm_campaign` / `utm_content` / `utm_term`	texto	Filtra pela atribuição de marketing do pedido.

`bevits_get_purchase_stats`

Aceita exatamente os mesmos filtros de bevits_list_purchases (inclusive os UTM) e mais dois parâmetros:

Parâmetro	Tipo	Descrição
`group_by`	`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `platform`, `status`, `currency`, `day`	Agrupa o resultado e devolve o ranking da dimensão.
`group_limit`	inteiro	Máximo de grupos retornados. Padrão `10`, máximo `50`.

A resposta traz os totais do período (purchase_count, customer_count, revenue_in_cents, average_ticket_in_cents) e, quando há group_by, a lista groups ordenada por faturamento — pedidos sem aquela UTM aparecem com key: null. groups_truncated avisa quando existem mais grupos além do group_limit.

Se a loja tem pedidos em mais de uma moeda, currency vem null e mixed_currencies vem true: nesse caso os totais são a soma bruta dos valores. Filtre por moeda (group_by: "currency") antes de comparar.

bevits_list_segments aceita q, e bevits_list_segment_customers aceita sort (updated ou total_spent).

Datas devem ser ISO 8601 com offset (por exemplo 2026-01-01T00:00:00-03:00), e valores monetários são sempre inteiros em centavos.

Métricas de recuperação de vendas

bevits_get_flow_metrics responde às perguntas de recuperação de carrinho a partir da atribuição que a Bevits já grava em cada envio:

Campo	O que significa
`entries`	Carrinhos abandonados distintos que receberam mensagem no período.
`sent` / `delivered` / `failed`	Volume de mensagens do flow no período.
`conversions`	Pedidos pagos atribuídos ao flow (contados uma vez, mesmo com vários toques).
`conversion_rate`	`conversions ÷ entries` — a taxa de recuperação.
`revenue_in_cents`	Faturamento recuperado no período.
`average_ticket_in_cents`	Ticket médio dos pedidos recuperados.
`nodes[]`	O mesmo recorte por nó de mensagem, para comparar a 1ª, a 2ª e a 3ª mensagem da sequência.

A janela padrão é de 30 dias e o máximo é de 366 dias; use since e until para outro período. Os números são os mesmos exibidos no modo Desempenho dentro do builder de flows.

A atribuição é last-touch, janela de 7 dias e escopo de carrinho abandonado: só flows com gatilho de abandono (eligibility: "recovery") registram conversão. Pedidos pagos da Nuvemshop e da Shopify alimentam essa atribuição. Os demais flows retornam eligibility: "engagement_only" e devem ser lidos só pela entregabilidade.

Paginação

Todas as tools de listagem usam paginação por cursor:

limit — quantidade de itens por página. Padrão 25, máximo 50.
starting_after — ID do último item da página anterior.
A resposta traz data, has_more e, quando há mais páginas, next_cursor.

O agente continua a leitura passando next_cursor em starting_after. Como o limite por página é fixo, perguntas do tipo “traga tudo” fazem o agente paginar várias vezes; seja específico com filtros para respostas mais rápidas.

Segurança e limites

Somente leitura

O catálogo não expõe nenhuma operação de escrita. O agente não consegue criar, editar ou apagar clientes, pedidos, flows ou campanhas.

Isolado por organização

O token carrega a organização escolhida no login. Nenhuma tool aceita um ID de organização como parâmetro, então não há como consultar outra conta.

Sem chave na configuração

A autenticação é OAuth 2.1 com callback local. Nenhuma API key da Bevits é gravada nos arquivos de configuração do agente.

Rate limit

As chamadas são limitadas por cliente, token e operação (padrão: 120 por minuto). As respostas trazem X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e Retry-After.

Apenas owners e administradores conseguem abrir a página de MCP e autorizar a conexão. Revise quem tem acesso ao ambiente em que o agente roda: quem usa o agente conectado enxerga os mesmos dados de leitura que você.

Erros

Quando uma tool falha, o agente recebe um erro estruturado com code e, quando disponível, request_id e retry_after.

Código	Significado
`authentication_error`	Token inválido, expirado ou sem o escopo de leitura. Refaça o login OAuth.
`permission_denied`	A credencial não tem permissão para o recurso.
`not_found`	O ID informado não existe nesta organização.
`validation_error`	Algum parâmetro foi rejeitado (ID com prefixo errado, data inválida, intervalo invertido).
`rate_limited`	Limite de chamadas atingido. Aguarde o `retry_after`.
`upstream_unavailable`	A API da Bevits não respondeu a tempo ou está indisponível.
`request_cancelled`	A chamada foi cancelada pelo cliente.

Ao pedir ajuda ao suporte, informe o request_id retornado no erro — ele permite localizar a chamada exata.

Solução de problemas

O agente não lista as tools. Confirme que o servidor aparece conectado (claude mcp list ou codex mcp list) e refaça a autorização OAuth.

Conectei na organização errada. Remova o servidor do cliente, adicione novamente e escolha a organização correta na tela de login.

Preciso de escrita ou de outra integração. O MCP é somente leitura nesta versão. Para outros fluxos, use a API REST ou fale com o suporte.

Primeiros passos

Fundamentos

Referência

Conectar no Claude (claude.ai e app)

Conectar no terminal (Claude Code e Codex)

O que dá para fazer

CRM e clientes

Compras e faturamento

Segmentos

Recuperação de vendas

Campanhas

Catálogo de tools

Identidade

Clientes

Compras

Segmentos

Tags e atributos

Flows e campanhas

Filtros disponíveis

`bevits_list_customers`

`bevits_list_purchases`

`bevits_get_purchase_stats`

Métricas de recuperação de vendas

Paginação

Segurança e limites

Somente leitura

Isolado por organização

Sem chave na configuração

Rate limit

Erros

Solução de problemas

​Conectar no Claude (claude.ai e app)

​Conectar no terminal (Claude Code e Codex)

​O que dá para fazer

CRM e clientes

Compras e faturamento

Segmentos

Recuperação de vendas

Campanhas

​Catálogo de tools

​Identidade

​Clientes

​Compras

​Segmentos

​Tags e atributos

​Flows e campanhas

​Filtros disponíveis

​bevits_list_customers

​bevits_list_purchases

​bevits_get_purchase_stats

​Métricas de recuperação de vendas

​Paginação

​Segurança e limites

Somente leitura

Isolado por organização

Sem chave na configuração

Rate limit

​Erros

​Solução de problemas

Conectar no Claude (claude.ai e app)

Conectar no terminal (Claude Code e Codex)

O que dá para fazer

Catálogo de tools

Identidade

Clientes

Compras

Segmentos

Tags e atributos

Flows e campanhas

Filtros disponíveis

`bevits_list_customers`

`bevits_list_purchases`

`bevits_get_purchase_stats`

Métricas de recuperação de vendas

Paginação

Segurança e limites

Erros

Solução de problemas