Servidor 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.

Abre Personalizar → Conectores

En Claude, desde el navegador o la app de escritorio, entra en Personalizar → Conectores.

Añade un conector personalizado

Haz clic en +, luego en Añadir conector personalizado, e indica la URL del servidor MCP remoto de Bevits:

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.

Conecta tu organización

Haz clic en Conectar, inicia sesión en Bevits desde el navegador, elige la organización y aprueba el acceso de solo lectura.

Activa el conector en la conversación

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 siempre tiene los pasos más recientes.

Conectar en la terminal (Claude Code y Codex)

Añade Bevits a tu cliente

Ejecuta el comando en la terminal. Los comandos exactos también están en Configuración → 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

Autoriza tu organización

Inicia OAuth, entra a Bevits en el navegador, elige la organización y aprueba el acceso de solo lectura.

/mcp

codex mcp login bevits

Confirma la conexión

Verifica que el servidor aparezca conectado y que se hayan cargado las 20 tools.

claude mcp list

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

CRM y clientes

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.

Compras y facturación

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.

Segmentos

Localizar segmentos por nombre, ver su tamaño y listar sus clientes ordenados por actualización o total gastado.

Recuperación de ventas

Medir un flow de carrito abandonado: tasa de recuperación, facturación recuperada y conversiones por mensaje de la secuencia.

Campañas

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

Solo lectura

El catálogo no expone ninguna operación de escritura. El agente no puede crear, editar ni borrar clientes, pedidos, flows o campañas.

Aislado por organización

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.

Sin clave en la configuración

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.

Límite de llamadas

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 o habla con el soporte.

Primeros pasos

Fundamentos

Referencia

Conectar en Claude (claude.ai y app)

Conectar en la terminal (Claude Code y Codex)

Qué puedes hacer

CRM y clientes

Compras y facturación

Segmentos

Recuperación de ventas

Campañas

Catálogo de tools

Identidad

Clientes

Compras

Segmentos

Tags y atributos

Flows y campañas

Filtros disponibles

`bevits_list_customers`

`bevits_list_purchases`

`bevits_get_purchase_stats`

Métricas de recuperación de ventas

Paginación

Seguridad y límites

Solo lectura

Aislado por organización

Sin clave en la configuración

Límite de llamadas

Errores

Solución de problemas

​Conectar en Claude (claude.ai y app)

​Conectar en la terminal (Claude Code y Codex)

​Qué puedes hacer

CRM y clientes

Compras y facturación

Segmentos

Recuperación de ventas

Campañas

​Catálogo de tools

​Identidad

​Clientes

​Compras

​Segmentos

​Tags y atributos

​Flows y campañas

​Filtros disponibles

​bevits_list_customers

​bevits_list_purchases

​bevits_get_purchase_stats

​Métricas de recuperación de ventas

​Paginación

​Seguridad y límites

Solo lectura

Aislado por organización

Sin clave en la configuración

Límite de llamadas

​Errores

​Solución de problemas

Conectar en Claude (claude.ai y app)

Conectar en la terminal (Claude Code y Codex)

Qué puedes hacer

Catálogo de tools

Identidad

Clientes

Compras

Segmentos

Tags y atributos

Flows y campañas

Filtros disponibles

`bevits_list_customers`

`bevits_list_purchases`

`bevits_get_purchase_stats`

Métricas de recuperación de ventas

Paginación

Seguridad y límites

Errores

Solución de problemas