Vanthal · MCP
Vanthal MCP server
Vanthal is a business management platform with AI for small and medium companies in Latin America. Its MCP (Model Context Protocol) server lets an AI assistant read the company's data and, if the owner allows it, log sales, appointments or tasks. Answers come from Vanthal, not from the assistant's guesses. Data and tool descriptions are in Spanish.
How to connect
- One click (OAuth): in Claude, go to Settings › Connectors › Add custom connector and paste https://vanthal.com/api/mcp. In ChatGPT, the same under Settings › Apps & Connectors › Create, with OAuth authentication.
- The assistant opens Vanthal: the company owner signs in, chooses read only («consulta») or read and write («carga»), and approves. Nothing to copy.
- With an API key, for clients without OAuth: in the «Asistentes conectados» module (or by asking Lumi, the built-in assistant) create a key and choose its scope. It is shown only once.
- Paste the URL ending with the key, or better, if the client supports custom headers, use https://vanthal.com/api/mcp and send the key as Authorization: Bearer.
- Every connection, OAuth or key, appears in «Asistentes conectados» and can be revoked there.
What it can and cannot do
- A key acts with the permissions of the person who created it. It can be revoked from the same module and stops working immediately.
- With write scope it logs sales, appointments, tasks, notes and records. Sales and deposits are recorded as income, but it never withdraws cash, records expenses, deletes, approves, charges a card or wallet, issues invoices, changes pipeline stages, or touches Finance, HR, Legal or Management records.
- Everything written through a key appears in the owner's activity log («Lo que hizo Lumi») with an undo button.
- Each key is limited to 300 calls per day, on top of the company's own limits.
Example prompts
- «How much did I sell today, and who owes me money?»
- «Which products do I need to restock?»
- «Log a cash sale of 2 coffees and 1 croissant»
- «What appointments do I have tomorrow?»
- «Who on my team has overdue tasks?»
Read tools
| Tool | Class | What it does |
|---|---|---|
ver_negocio_hoy | Read | Today's summary: income, money owed to the business, products to restock, pending team tasks. |
ver_ventas | Read | Sales for a period, by product, payment method or seller. |
ver_caja | Read | Cash register status for the current shift and its movements. |
ver_variantes | Read | Stock of a product that comes in variants (sizes, colors). |
cuenta_corriente | Read | Customer accounts: who owes what. Write scope also allows adding a charge (cargo) to an account; never records payments. |
ver_gestion | Read | Live records of the company's modules (stock, orders, jobs, courses). |
listar_registros | Read | Lists records of a department (customers, suppliers, orders, leads). |
buscar_registros | Read | Searches records by text. |
ver_registro | Read | One record with its history and comments. |
ver_turnos | Read | Appointments for a day or range, free slots, or a customer's history. |
ver_mi_dia | Read | The key owner's day: tasks, appointments and reminders. |
ver_tareas_asignadas | Read | Tasks assigned across the team and their status. |
ver_objetivos | Read | Individual and team goals and their progress. |
ver_informe | Read | Weekly or monthly report. |
ver_equipo | Read | Team members and roles. |
quien_falta | Read | Who is absent or on leave today. |
ver_pulso_equipo | Read | Team workload and mood indicators. |
ver_envios | Read | Shipments and their tracking status. |
cotizar_envio | Read | Quotes a shipment with the connected carrier. Read only: nothing is booked. |
buscar_marketplace | Read | Searches products and services offered by other companies in the Vanthal Ecosystem. |
ver_avisos | Read | Alerts: prices behind inflation, overdue accounts, tax category limits. |
estado_factura_electronica | Read | Status of e-invoicing (Argentina's ARCA). Read only: never issues invoices. |
ver_notas | Read | The key owner's notes. |
preguntar_a_lumi | Read | Asks Lumi, Vanthal's assistant, an open question; it answers using only the tools this key allows. |
Write tools (write scope only)
| Tool | Class | What it does |
|---|---|---|
registrar_venta | Write | Records a counter sale: decreases stock and adds the income to the cash register, or to the customer's account if unpaid. Can also create a quote. |
guardar_registro | Write | Creates or edits a record (customer, order, lead). Cannot change pipeline stages or touch Finance, HR, Legal or Management. |
comentar_registro | Write | Adds a comment to a record; notifies its owner inside Vanthal. |
crear_tarea | Write | Creates a personal task or reminder. |
asignar_tarea | Write | Assigns a task to a team member; they are notified inside Vanthal. |
avisar_avance | Write | Updates the status of a pending task (started, blocked, not started). |
agendar_turno | Write | Books an appointment for a customer; rejects overlaps. A deposit, if given, is recorded as income. |
cambiar_turno | Write | Moves, reassigns, confirms or cancels an appointment, or records its payment as income. |
crear_evento | Write | Adds an event to the company calendar. |
crear_nota | Write | Saves a note. |
Errors and rate limits
- An invalid or revoked key returns HTTP 401 with JSON-RPC error -32001.
- A tool outside the key's scope returns error -32602 and does not run.
- When a tool refuses (permissions, missing data, an overlapping appointment) it returns a result with isError: true and the reason as text, so the assistant can explain it.
- Rate limit: 300 calls per day per key; past that, calls return isError with the reset time.
- No tool is a sensitive write: none pays, transfers money, or sends email or messages outside Vanthal. Team notifications stay inside the product.
- Read tools are idempotent. Write tools are not: registrar_venta returns the sale id, so check ver_ventas before retrying a failed call.
Technical details
- Endpoint: https://vanthal.com/api/mcp/YOUR-KEY
- Transport: streamable HTTP, responses as application/json, no SSE stream.
- Protocol versions: 2025-06-18, 2025-03-26, 2024-11-05.
- Authentication: OAuth 2.1 with PKCE S256 and dynamic client registration (metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server); one-hour access tokens and rotating refresh tokens. Alternatively, a per-company API key in the URL path or as Authorization: Bearer.
- Every tool carries readOnlyHint, so clients ask for confirmation only before writing.
- Availability: Vanthal accounts in any country; the product is in Spanish, English, Portuguese, French, German and Italian.