Vanthal · MCP
Conectar ChatGPT, Claude u otro asistente con Vanthal
Vanthal tiene un servidor MCP (Model Context Protocol). Con él, ChatGPT, Claude u otro asistente de IA consulta los datos de tu empresa y, si lo permitís, carga ventas, turnos o tareas. Lo que responde sale de Vanthal, no de lo que el asistente supone.
Cómo se conecta
- Con un clic (OAuth): en Claude, entrá a Configuración › Conectores › Agregar conector personalizado y pegá https://vanthal.com/api/mcp. En ChatGPT, lo mismo en Configuración › Aplicaciones y conectores › Crear, con autenticación OAuth.
- El asistente te abre Vanthal: entrás con tu usuario de dueño, elegís solo consulta o consulta y carga, y permitís. No hay que copiar nada.
- Con una llave, para asistentes sin OAuth: en el módulo «Asistentes conectados» (o pidiéndoselo a Lumi) creá una llave y elegí el alcance. Se muestra una sola vez.
- Pegá la dirección que termina en tu llave, o mejor, si el asistente deja poner encabezados, usá https://vanthal.com/api/mcp y mandá la llave como Authorization: Bearer.
- Cada conexión, por OAuth o por llave, aparece en «Asistentes conectados» y se revoca ahí.
Qué puede y qué no
- La llave actúa con los permisos de quien la creó, y se revoca en el mismo módulo: deja de andar al instante.
- Con «carga» suma ventas, turnos, tareas, notas y registros. Las ventas y señas entran a la caja como ingreso, pero no saca plata, no anota gastos, no borra, no aprueba, no cobra con tarjeta ni Mercado Pago, no factura, no cambia etapas y no toca Finanzas, RR. HH., Legal ni Dirección.
- Lo que carga queda en «Lo que hizo Lumi», con su botón para deshacer.
- Cada llave tiene un tope de 300 llamadas por día, además de los topes de la empresa.
Ejemplos para preguntarle
- «¿Cuánto vendí hoy y cuánto me deben?»
- «¿Qué productos tengo que reponer?»
- «Anotá una venta de 2 cafés y 1 medialuna, en efectivo»
- «¿Qué turnos tengo mañana?»
- «¿Quién del equipo tiene tareas atrasadas?»
Herramientas de consulta
| Herramienta | Clase | Qué hace |
|---|---|---|
ver_negocio_hoy | Lectura | Solo para el dueño. |
ver_ventas | Lectura | Ventas de mostrador. |
ver_caja | Lectura | Devuelve la caja abierta de la persona (ventas, cobros por medio de pago, egresos, efectivo que tiene que haber) y, al dueño, los últimos turnos de todos con su diferencia. |
ver_variantes | Lectura | Stock y ventas por variante de los productos con talles o colores: cuáles están agotadas y cuáles no se venden. |
cuenta_corriente | Lectura | Cuentas corrientes de clientes (el fiado) y de proveedores (lo que la empresa les debe). |
ver_gestion | Lectura | Devuelve los departamentos de gestión disponibles (Ventas, Marketing, Finanzas...) con sus colecciones, los campos de cada una, sus etapas y cuántos registros tienen. |
listar_registros | Lectura | Lista los registros de una colección de un departamento (por ejemplo las oportunidades de ventas o los tickets de soporte), con su id, su etapa, la persona responsable y sus datos. |
buscar_registros | Lectura | Busca un texto en los registros de todos los departamentos a los que entra la persona (clientes, oportunidades, pedidos, facturas, productos, tickets...). |
ver_registro | Lectura | Devuelve la ficha completa de un registro: datos, etapa, responsable, historial de cambios y comentarios, de dónde se generó y qué generó. |
ver_turnos | Lectura | Turnos de un día o de varios seguidos (por defecto hoy), con su turno_id. |
ver_mi_dia | Lectura | Devuelve el día de la persona: por dónde conviene arrancar (ya ordenado por urgencia), cuántas tareas tiene, su agenda de hoy, sus objetivos con el avance y si ya cerró el día. |
ver_tareas_asignadas | Lectura | Solo para el dueño. |
ver_objetivos | Lectura | Lista los objetivos con su avance. |
ver_informe | Lectura | El informe semanal o mensual: qué objetivos se cumplieron, tareas y ventas comparadas con el período anterior, y cómo le fue a cada persona (a un empleado, solo lo suyo). |
ver_equipo | Lectura | Solo para el dueño. |
quien_falta | Lectura | Quién está de vacaciones o con licencia hoy y en los próximos 7 días; al dueño, también quién no fichó hoy. |
ver_pulso_equipo | Lectura | Solo para el dueño. |
ver_envios | Lectura | Los últimos envíos de la empresa con su estado y el enlace de seguimiento. |
cotizar_envio | Lectura | Cotiza un envío con Zipnova (varios correos y logísticas): devuelve opciones con precio y demora. |
buscar_marketplace | Lectura | Busca productos y servicios que ofrecen otras empresas de Vanthal. |
ver_avisos | Lectura | Devuelve los últimos avisos de la campanita de la persona y cuántos tiene sin leer. |
estado_factura_electronica | Lectura | Si la empresa factura por ARCA (factura electrónica con CAE), con qué CUIT y punto de venta, y cómo se conecta si no. |
ver_notas | Lectura | Devuelve todas las anotaciones guardadas, con sus ids. |
preguntar_a_lumi | Lectura | Le hace una pregunta a Lumi, la asistente de Vanthal, que conoce la empresa entera y busca la respuesta con sus herramientas (ventas, caja, stock, clientes, turnos, equipo). |
Herramientas de carga (solo con «carga»)
| Herramienta | Clase | Qué hace |
|---|---|---|
registrar_venta | Escritura | Registra una venta de mostrador en un solo paso: descuenta el stock de cada producto, la suma a la caja del turno y, si queda fiada, a la cuenta corriente del cliente. |
guardar_registro | Escritura | Crea un registro en una colección o actualiza uno existente (sus datos o su etapa). |
comentar_registro | Escritura | Deja un comentario en el historial de un registro, para el equipo. |
crear_tarea | Escritura | Crea una tarea (tarea) pendiente, opcionalmente programada para una fecha y hora. |
asignar_tarea | Escritura | Solo para el dueño. |
avisar_avance | Escritura | Marca cómo viene una tarea pendiente de la persona: empezada, trabada (con el motivo) o sin empezar. |
agendar_turno | Escritura | Da un turno a un cliente. |
cambiar_turno | Escritura | Cambia un turno: lo mueve, le cambia quién atiende, lo cancela, lo marca confirmado, atendido o ausente, le suma una seña o lo cobra (charge=true: entra a la caja a nombre de quien atendió). |
crear_evento | Escritura | Agrega al calendario un evento que no es una tarea: una reunión, un turno, un recordatorio. |
crear_nota | Escritura | Guarda una anotación: una idea, un dato, el resumen de una investigación. |
Errores y topes
- Una llave inválida o revocada responde 401 con el error JSON-RPC -32001.
- Una herramienta fuera del alcance de la llave responde el error -32602 y no corre.
- Lo que la herramienta rechaza (permisos, datos que faltan, un turno que se pisa) vuelve como resultado con isError: true y el motivo en texto, para que el asistente lo explique.
- Tope: 300 llamadas por día y por llave; al pasarlo, cada llamada vuelve con isError y el aviso de cuándo se renueva.
- Ninguna herramienta es sensible: ninguna paga, transfiere, manda correos ni mensajes afuera de Vanthal. Los avisos al equipo son internos.
Datos técnicos
- Dirección: https://vanthal.com/api/mcp/TU-LLAVE
- Transporte: HTTP «streamable», respuestas en application/json, sin SSE.
- Versiones del protocolo: 2025-06-18, 2025-03-26, 2024-11-05.
- Autenticación: OAuth 2.1 con PKCE S256 y registro dinámico de clientes (metadatos en /.well-known/oauth-protected-resource y /.well-known/oauth-authorization-server); tokens de acceso de una hora y de renovación que rotan. O una llave en la dirección o como Authorization: Bearer.
- Cada herramienta lleva readOnlyHint, así el asistente pide confirmación solo antes de cargar.