> ## 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
> Conecta Claude Code, Codex y otros agentes a los datos de tu organización mediante MCP.
El **MCP (Model Context Protocol)** de Bevits permite que tu agente consulte los
datos de tu organización directamente, sin copiar planillas ni pegar respuestas
de la API en el chat. En lugar de enseñarle al agente a usar la API REST, lo
conectas una vez y pasa a ver clientes, compras, segmentos, tags, atributos,
flows y campañas de correo como herramientas nativas.
**Endpoint:** `https://api.bevits.com/mcp` · **Transporte:** Streamable HTTP ·
**Autenticación:** OAuth 2.1 · **Acceso:** solo lectura · **20 tools**
La conexión usa OAuth: ninguna clave API queda pegada en la configuración del
agente. Inicias sesión en Bevits desde el navegador, eliges la organización y
apruebas el acceso. El token generado pertenece a **una sola organización** y
concede únicamente el permiso `mcp:read`.
## Conectar en Claude (claude.ai y app)
Este es el camino sin terminal. Claude se conecta al servidor de Bevits desde la
nube de Anthropic, así que solo necesitas la dirección pública del endpoint.
En Claude, desde el navegador o la app de escritorio, entra en
**Personalizar → Conectores**.
Haz clic en **+**, luego en **Añadir conector personalizado**, e indica la
URL del servidor MCP remoto de Bevits:
```text theme={null}
https://api.bevits.com/mcp
```
Deja **Configuración avanzada** en blanco: el servidor de Bevits publica sus
propios metadatos OAuth, así que no hace falta Client ID ni Client Secret.
Haz clic en **Añadir**.
Haz clic en **Conectar**, inicia sesión en Bevits desde el navegador, elige
la organización y aprueba el acceso de solo lectura.
En el chat, abre el botón **+**, elige **Conectores** y activa **Bevits**.
A partir de ahí solo pregunta, por ejemplo: “¿qué campañas de correo tuvieron
la mayor tasa de apertura?”.
En cuentas **Team** y **Enterprise**, un owner añade el conector en
**Configuración de la organización → Conectores** y luego cada persona hace
clic en **Conectar** para autenticarse con su propia cuenta de Bevits: cada una
ve solo los datos de la organización que autorizó. Los nombres de los menús
pueden cambiar con las actualizaciones de Claude; la
[documentación de conectores personalizados](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
siempre tiene los pasos más recientes.
## Conectar en la terminal (Claude Code y Codex)
Ejecuta el comando en la terminal. Los comandos exactos también están en
[Configuración → 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
```
Inicia OAuth, entra a Bevits en el navegador, elige la organización y aprueba
el acceso de solo lectura.
```text Claude Code theme={null}
/mcp
```
```bash Codex theme={null}
codex mcp login bevits
```
Verifica que el servidor aparezca conectado y que se hayan cargado las 20
tools.
```bash Claude Code theme={null}
claude mcp list
```
```bash Codex theme={null}
codex mcp list
```
Cualquier cliente compatible con MCP por Streamable HTTP y OAuth 2.1 puede
conectarse al mismo endpoint. Claude Code y Codex son solo los caminos
documentados.
## Qué puedes hacer
Encontrar clientes por correo, teléfono, tag, segmento o búsqueda libre, y
leer contacto, tags, atributos, dirección predeterminada y métricas de
consumo.
Listar y detallar pedidos, y agregar facturación, ticket promedio y clientes
únicos en una sola llamada — con ranking por UTM, plataforma, estado o día.
Localizar segmentos por nombre, ver su tamaño y listar sus clientes ordenados
por actualización o total gastado.
Medir un flow de carrito abandonado: tasa de recuperación, facturación
recuperada y conversiones por mensaje de la secuencia.
Campañas de correo con envío, entrega, apertura y clic; campañas de WhatsApp
y SMS con destinatarios, entregadas, leídas y fallidas por plantilla.
Preguntas que el agente responde por su cuenta una vez conectado:
* “¿Cuáles son las UTM que más vendieron en los últimos 7 días?”
* “¿Cuál es la tasa de recuperación y la facturación recuperada de mi flow de carrito abandonado?”
* “¿Qué mensaje de la secuencia de recuperación convierte más?”
* “¿Cuál fue el ticket promedio de este mes comparado con el mes pasado?”
* “¿Quiénes son los 20 clientes que más gastaron en el segmento VIP y qué compraron?”
* “¿Qué plantilla de WhatsApp tuvo la peor tasa de entrega?”
* “¿Este cliente está suscrito? ¿Qué tags y atributos tiene?”
* “¿Qué flows están activos y cuántas veces se ejecutó cada uno?”
## Catálogo de tools
Todas las tools son de lectura (`readOnlyHint`) e idempotentes. Ninguna crea,
modifica ni elimina datos, y ninguna acepta un ID de organización: el alcance
siempre proviene del token.
### Identidad
| Tool | Qué hace |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `bevits_get_identity` | Devuelve la organización y la credencial de la conexión. Sirve como primera llamada para confirmar en qué cuenta está el agente. |
### Clientes
| Tool | Qué hace |
| -------------------------------- | ------------------------------------------------------------------------------------------------- |
| `bevits_list_customers` | Lista clientes con filtros de CRM y paginación por cursor. |
| `bevits_get_customer` | Detalla un cliente por `customer_id` (`cus_...`), con tags, atributos y dirección predeterminada. |
| `bevits_list_customer_purchases` | Lista las compras de un cliente específico. |
### Compras
| Tool | Qué hace |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `bevits_list_purchases` | Lista compras con filtros de comercio y paginación por cursor. |
| `bevits_get_purchase` | Detalla una compra por `purchase_id` (`pur_...`). |
| `bevits_get_purchase_stats` | Agrega compras: pedidos, facturación, ticket promedio y clientes únicos, con ranking opcional por UTM, plataforma, estado, moneda o día. |
### Segmentos
| Tool | Qué hace |
| ------------------------------- | -------------------------------------------------------- |
| `bevits_list_segments` | Lista segmentos, con búsqueda opcional por nombre (`q`). |
| `bevits_get_segment` | Detalla un segmento por `segment_id` (`seg_...`). |
| `bevits_list_segment_customers` | Lista los clientes de un segmento, con orden opcional. |
### Tags y atributos
| Tool | Qué hace |
| ------------------------ | ---------------------------------------------------------- |
| `bevits_list_tags` | Lista las tags de cliente de la organización. |
| `bevits_get_tag` | Detalla una tag por `tag_id` (`tag_...`). |
| `bevits_list_attributes` | Lista los atributos personalizados de cliente y sus tipos. |
### Flows y campañas
| Tool | Qué hace |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bevits_list_flows` | Lista las automatizaciones de la organización. |
| `bevits_get_flow` | Detalla un flow por `flow_id` (`flw_...`). |
| `bevits_get_flow_metrics` | Métricas del flow en el período: entradas, envíos, conversiones, tasa de conversión, facturación recuperada y el mismo desglose por nodo de mensaje. |
| `bevits_list_email_campaigns` | Lista campañas de correo. |
| `bevits_get_email_campaign` | Detalla una campaña por `email_campaign_id` (`emc_...`). |
| `bevits_list_template_campaigns` | Lista campañas de WhatsApp y SMS creadas a partir de una plantilla. |
| `bevits_get_template_campaign` | Detalla una campaña de WhatsApp o SMS por `template_campaign_id` (`tcp_...`), con todas las variantes de plantilla usadas y las métricas de entrega. |
## Filtros disponibles
### `bevits_list_customers`
| Parámetro | Tipo | Descripción |
| --------------------------------- | -------------------------- | --------------------------------------------- |
| `q` | texto | Búsqueda libre por nombre, correo o teléfono. |
| `email` | correo | Búsqueda exacta por correo. |
| `phone` | texto | Búsqueda por teléfono. |
| `tag_id` | `tag_...` | Solo clientes con la tag. |
| `segment_id` | `seg_...` | Solo clientes del segmento. |
| `is_subscribed` | booleano | Filtra por estado de suscripción. |
| `created_since` / `created_until` | fecha ISO 8601 | Ventana de creación del cliente. |
| `updated_since` | fecha ISO 8601 | Modificados desde la fecha. |
| `sort` | `updated` \| `total_spent` | Orden del resultado. |
### `bevits_list_purchases`
| Parámetro | Tipo | Descripción |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
| `customer_id` | `cus_...` | Compras de un cliente. |
| `status` | `any`, `pending`, `authorized`, `paid`, `abandoned`, `refunded`, `voided` | Estado del pedido. |
| `platform` | `nuvemshop`, `shopify`, `woocommerce`, `bling`, `instagram`, `popup` | Origen del pedido. |
| `created_since` / `created_until` | fecha ISO 8601 | Ventana del pedido. |
| `min_value_in_cents` / `max_value_in_cents` | entero | Rango de valor, en centavos. |
| `utm_source` / `utm_medium` / `utm_campaign` / `utm_content` / `utm_term` | texto | Filtra por la atribución de marketing del pedido. |
### `bevits_get_purchase_stats`
Acepta exactamente los mismos filtros que `bevits_list_purchases` (UTM
incluidas) y dos parámetros más:
| Parámetro | Tipo | Descripción |
| ------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `group_by` | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `platform`, `status`, `currency`, `day` | Agrupa el resultado y devuelve el ranking de esa dimensión. |
| `group_limit` | entero | Máximo de grupos devueltos. Predeterminado `10`, máximo `50`. |
La respuesta trae los totales del período (`purchase_count`, `customer_count`,
`revenue_in_cents`, `average_ticket_in_cents`) y, cuando hay `group_by`, la
lista `groups` ordenada por facturación — los pedidos sin esa UTM aparecen con
`key: null`. `groups_truncated` avisa cuando existen más grupos más allá de
`group_limit`.
Si la tienda tiene pedidos en más de una moneda, `currency` llega como `null`
y `mixed_currencies` como `true`: en ese caso los totales son la suma bruta
de valores en monedas distintas. Separa por moneda
(`group_by: "currency"`) antes de comparar.
`bevits_list_segments` acepta `q`, y `bevits_list_segment_customers` acepta
`sort` (`updated` o `total_spent`).
Las fechas deben ser ISO 8601 con offset (por ejemplo
`2026-01-01T00:00:00-03:00`), y los valores monetarios siempre son enteros en
centavos.
## Métricas de recuperación de ventas
`bevits_get_flow_metrics` responde a las preguntas de recuperación de carrito a
partir de la atribución que Bevits ya registra en cada envío:
| Campo | Qué significa |
| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `entries` | Carritos abandonados distintos que recibieron mensaje en el período. |
| `sent` / `delivered` / `failed` | Volumen de mensajes del flow en el período. |
| `conversions` | Pedidos pagados atribuidos al flow (contados una vez, incluso con varios toques). |
| `conversion_rate` | `conversions ÷ entries` — la tasa de recuperación. |
| `revenue_in_cents` | Facturación recuperada en el período. |
| `average_ticket_in_cents` | Ticket promedio de los pedidos recuperados. |
| `nodes[]` | El mismo desglose por nodo de mensaje, para comparar el 1.º, el 2.º y el 3.º mensaje de la secuencia. |
La ventana predeterminada es de 30 días y el máximo es de 366; usa `since` y
`until` para otro período. Los números son los mismos que muestra el modo
**Desempeño** dentro del builder de flows.
La atribución es **last-touch, ventana de 7 días y alcance de carrito
abandonado**: solo los flows con disparador de abandono
(`eligibility: "recovery"`) registran conversión. Los pedidos pagados de
**Nuvemshop** y **Shopify** alimentan esa atribución. Los demás flows devuelven
`eligibility: "engagement_only"` y deben leerse solo por la entregabilidad.
## Paginación
Todas las tools de listado usan paginación por cursor:
* `limit` — elementos por página. Predeterminado `25`, máximo `50`.
* `starting_after` — ID del último elemento de la página anterior.
* La respuesta incluye `data`, `has_more` y, cuando hay más páginas,
`next_cursor`.
El agente continúa la lectura pasando `next_cursor` en `starting_after`. Como el
tamaño de página está limitado, las preguntas del tipo “tráeme todo” obligan al
agente a paginar muchas veces; usa filtros para obtener respuestas más rápidas.
## Seguridad y límites
El catálogo no expone ninguna operación de escritura. El agente no puede
crear, editar ni borrar clientes, pedidos, flows o campañas.
El token lleva la organización elegida al iniciar sesión. Ninguna tool acepta
un ID de organización, así que no es posible consultar otra cuenta.
La autenticación es OAuth 2.1 con callback local. Ninguna clave API de Bevits
queda guardada en los archivos de configuración del agente.
Las llamadas se limitan por cliente, token y operación (120 por minuto de
forma predeterminada). Las respuestas incluyen `X-RateLimit-Limit`,
`X-RateLimit-Remaining`, `X-RateLimit-Reset` y `Retry-After`.
Solo owners y administradores pueden abrir la página de MCP y autorizar la
conexión. Revisa quién tiene acceso al entorno donde corre el agente: quien use
el agente conectado ve los mismos datos de lectura que tú.
### Errores
Cuando una tool falla, el agente recibe un error estructurado con `code` y,
cuando está disponible, `request_id` y `retry_after`.
| Código | Significado |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| `authentication_error` | Token inválido o expirado, o sin el permiso de lectura. Repite el inicio de sesión OAuth. |
| `permission_denied` | La credencial no tiene permiso para el recurso. |
| `not_found` | El ID indicado no existe en esta organización. |
| `validation_error` | Se rechazó algún parámetro (prefijo de ID incorrecto, fecha inválida, rango invertido). |
| `rate_limited` | Se alcanzó el límite de llamadas. Espera el `retry_after`. |
| `upstream_unavailable` | La API de Bevits no respondió a tiempo o no está disponible. |
| `request_cancelled` | La llamada fue cancelada por el cliente. |
Al contactar al soporte, incluye el `request_id` del error: identifica la
llamada exacta.
## Solución de problemas
**El agente no lista las tools.** Confirma que el servidor aparece conectado
(`claude mcp list` o `codex mcp list`) y repite la autorización OAuth.
**Me conecté a la organización equivocada.** Elimina el servidor del cliente,
agrégalo de nuevo y elige la organización correcta en la pantalla de inicio de
sesión.
**Necesito escritura u otra integración.** El MCP es de solo lectura en esta
versión. Para otros flujos, usa la
[API REST](/es/api-reference/overview) o habla con el soporte.