> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bevits.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Servidor MCP
> Conecte Claude Code, Codex e outros agentes aos dados da sua organização via 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.
No Claude, pelo navegador ou pelo app de desktop, vá em
**Personalizar → Conectores**.
Clique em **+**, depois em **Adicionar conector personalizado**, e informe a
URL do servidor MCP remoto da Bevits:
```text theme={null}
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**.
Clique em **Conectar**, entre na Bevits pelo navegador, escolha a
organização e aprove o acesso somente leitura.
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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
tem sempre o passo a passo mais recente.
## Conectar no terminal (Claude Code e Codex)
Rode o comando no terminal. Os comandos exatos também ficam em
[Configurações → MCP](https://app.bevits.com/settings/mcp).
```bash Claude Code theme={null}
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
```
```bash Codex theme={null}
codex mcp add bevits --url https://api.bevits.com/mcp
```
Inicie o OAuth, faça login na Bevits pelo navegador, escolha a organização e
aprove o acesso somente leitura.
```text Claude Code theme={null}
/mcp
```
```bash Codex theme={null}
codex mcp login bevits
```
Verifique se o servidor aparece conectado e se as 20 tools foram carregadas.
```bash Claude Code theme={null}
claude mcp list
```
```bash Codex theme={null}
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
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.
Listar e detalhar pedidos, e agregar faturamento, ticket médio e clientes
únicos em uma chamada — com ranking por UTM, plataforma, status ou dia.
Localizar segmentos pelo nome, ver o tamanho de cada um e listar seus
clientes ordenados por atualização ou total gasto.
Medir um flow de carrinho abandonado: taxa de recuperação, faturamento
recuperado e conversões por mensagem da sequência.
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
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.
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.
A autenticação é OAuth 2.1 com callback local. Nenhuma API key da Bevits é
gravada nos arquivos de configuração do agente.
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](/pt-BR/api-reference/overview) ou fale com o suporte.