Flujos de Clau con MCP

Estos flujos usan las herramientas del MCP de Clau. Primero conecta tu cliente y verifica el negocio con cuenta_actual.

Los correos, UID, grupos, fechas y cantidades de los ejemplos son ilustrativos. El asistente resuelve los identificadores reales con las herramientas de consulta. Cada flujo indica los permisos que debe tener la conexión.

Resumen de ventas

Permiso: compras:read.

ventas_resumen calcula en el servidor el total, los impuestos, las transacciones y el ticket promedio de un rango de hasta 31 días. Da el desglose por tienda y por forma de pago, y separa las compras en otros estados. Las fechas son días completos en la zona horaria del negocio.

Dame el resumen de ventas de ayer por tienda y forma de pago.
Compáralo con el mismo día de la semana pasada.

Consultar un cliente y su historial de puntos

Permisos: clientes:read y puntos:read.

Paso	Herramienta	Qué comprobar
1	`clientes_buscar` con `email`	Que la coincidencia corresponda al cliente solicitado
2	`clientes_obtener` con el `uid`	Datos del cliente, nivel y saldo
3	`clientes_puntos_historial` con el `uid`	Movimientos del historial, sin alterar el saldo

Busca en Clau al cliente con correo [email protected].
Si hay una coincidencia inequívoca, consulta su ficha y su historial
de puntos. Resume el saldo disponible y los movimientos recientes.
Si no aparece o hay varias coincidencias, indícalo antes de continuar.
No modifiques datos.

Los puntos se expresan en la misma unidad que muestra el dashboard.

Preparar un reporte de lealtad

Permiso: reportes:read.

Paso	Herramienta	Qué comprobar
1	`reportes_catalogo`	Datasets, campos y métricas disponibles
2	`reportes_ejecutar`	Configuración con campos del catálogo y un período explícito
3	`reportes_job`	Si el reporte quedó en proceso, consulta el trabajo hasta obtener el resultado o un error

Prepara un reporte de movimientos de puntos del 1 al 31 de agosto de 2026.
Consulta primero el catálogo de reportes de Clau y selecciona los campos
disponibles para cliente, puntos y fecha. Muéstrame la configuración.
Cuando te indique que lo ejecutes, si queda en proceso conserva el jobId
y consulta su estado; no crees otro reporte para comprobar si terminó.
Al resumir, indica si el resultado está limitado a una cantidad de filas.

El reporte síncrono admite hasta 5000 filas; con async: true se ejecuta como trabajo asíncrono. Para preguntas frecuentes también hay reportes listos, que no necesitan configuración. Por ejemplo, reportes_clientes_inactivos, reportes_puntos_por_vencer y reportes_cupones_usados.

Agregar puntos a un cliente

Permisos: clientes:read para identificarlo y puntos:write para el ajuste. puntos:write incluye puntos:read, así que se puede verificar el historial.

Identifica al cliente con clientes_buscar y confirma su uid.
Prepara clientes_puntos_agregar con uid, puntos y un motivo reconocible. El motivo queda en la auditoría.
Cuando se autorice el ajuste, ejecútalo con un idempotency_key nuevo (por ejemplo, un UUID).
Revisa la respuesta y consulta clientes_puntos_historial para verificar el movimiento.

Prepara un ajuste de 150 puntos para [email protected] por el caso SOP-4412.
Muéstrame el cliente, la cantidad y el motivo, y espera mi indicación
antes de aplicarlo. Si hay que reintentar, usa el mismo idempotency_key.
Después comprueba el movimiento en el historial.

Una cantidad negativa resta puntos. El límite es de 10000 puntos por llamada. Si el asistente repite la misma operación con el mismo idempotency_key, Clau devuelve el resultado original en vez de aplicarla dos veces.

Simular puntos para un grupo y luego aplicarlos

Permisos: segmentos:read para formar el grupo, clientes:read para revisar sus integrantes y puntos:write para la acción.

Paso	Herramienta	Resultado esperado
1	`segmentos_evaluar` (con un filtro) o `segmentos_por_lista` (con identificadores)	Un grupo de clientes y su `grupoId`
2	`segmentos_grupo_clientes`	Los integrantes del grupo
3	`grupos_puntos` con `dryRun: true`	Cuántos clientes afecta y el costo estimado, sin aplicar nada
4	`grupos_puntos` con `dryRun: false`	La acción aplicada, con un `idempotency_key` distinto al de la simulación

Arma un grupo con los clientes de nivel Oro y muéstrame cuántos son. Luego simula agregar 50 puntos a cada uno con
dryRun: true y muéstrame la estimación. Solo aplica la acción cuando
la autorice, con dryRun: false y un idempotency_key nuevo.

dryRun solo simula la acción de puntos. Formar el grupo sí lo guarda en el negocio. La simulación no reserva saldo ni garantiza que los datos sigan igual al aplicar: si el grupo o los datos cambiaron, revisa de nuevo el alcance.

Cómo interpretar el resultado

Si una herramienta falla, su mensaje explica qué pasó: un permiso que falta, un dato inválido o una regla de negocio. El asistente debe mostrar ese mensaje tal cual y no presentarlo como un problema de conexión si la conexión funciona.

Cuando un flujo aplica puntos, asigna un beneficio o inicia un trabajo asíncrono, el asistente debe reportar la etapa que Clau confirmó: simulación, operación aplicada o trabajo pendiente.

Consulta también la guía de API v3, los códigos de respuesta y la solución de problemas del MCP.