Herramientas

Hay una herramienta por cada operación de la API, con el mismo nombre en snake_case y exactamente el mismo permiso. No hay herramientas «de alto nivel» que junten varias consultas: si existiera un resumen_del_mes con su propia forma de sumar, tarde o temprano el asistente diría 4,2 millones y el panel diría 4,1, y nadie sabría cuál tiene razón.

Lo que tu llave no puede hacer, no aparece

El catálogo se arma con los permisos de tu llave. Con una de solo lectura, el asistente ni siquiera sabe que create_expense existe: no es que se le niegue al intentarlo, es que no está en la lista. Un modelo que ve una herramienta asume que puede usarla, y media conversación se va en intentarlo, fallar y explicar un permiso que nunca tuvo.

🪪 Identidad

Herramienta	Permiso	Qué hace
`whoami`	—	Alias de la llave, permisos, negocios a los que entra y plan. La primera que conviene llamar.
`get_plan`	`plan.read`	Plan, funciones incluidas, límites y cuánto cupo de verificaciones queda este mes.

✅ Verificación

Herramienta	Permiso	Qué hace
`verify_receipt`	`verifications.write`	Registra un comprobante con sus datos (monto, referencia, teléfono de alguien del equipo) y devuelve el veredicto: `REGISTERED` o `DUPLICATE`. Consume cupo si se registra. Verificar mandando solo la imagen es de la API (`POST /v1/verifications`, ver guía).

💵 Ingresos

Herramienta	Permiso	Qué hace
`list_incomes`	`incomes.read`	Pagos por fecha, estado, origen, sucursal, monto, cuenta o texto libre. Responde «¿cuánto entró ayer?».
`get_income`	`incomes.read`	El detalle de un pago, con sus comprobantes y por qué canal lo respaldó el banco.
`get_income_receipt`	`incomes.read`	Muestra el comprobante como imagen, dentro del propio chat. Si el pago tiene varios, enumera el resto.
`declare_income`	`incomes.write`	Anota un pago en el libro. Nace `DECLARED` y no consume cupo.
`update_income`	`incomes.write`	Corrige un pago declarado a mano. Los demás son inmutables.
`delete_income`	`incomes.delete`	Borra un pago declarado a mano.

El comprobante viaja como imagen, no como enlace

get_income_receipt devuelve la foto ya reducida y el asistente la pinta en la conversación. No se firma ninguna URL de descarga: una dirección así serviría a cualquiera que la tuviera, desde cualquier máquina, hasta que venciera. Aquí el permiso se comprueba en cada llamada y, si quitas la conexión desde el panel, deja de funcionar en la siguiente.

Dos consecuencias prácticas: un comprobante en PDF no se puede pintar (te responde con los datos del archivo y dónde abrirlo), y la imagen queda dentro de la conversación — trátala como lo que es, el comprobante en el chat.

🧾 Egresos

Herramienta	Permiso	Qué hace
`list_expenses`	`expenses.read`	Gastos por fecha, categoría, sucursal, monto, forma de pago o beneficiario.
`get_expense`	`expenses.read`	El detalle de un gasto.
`create_expense`	`expenses.write`	Registra un gasto. Pide `categoryId`, así que suele ir después de `list_expense_categories`.
`update_expense`	`expenses.write`	Corrige un gasto.
`delete_expense`	`expenses.delete`	Borra un gasto.
`list_expense_categories`	`categories.read`	Las categorías del negocio, con su emoji y si están activas.
`create_expense_category`	`categories.write`	Crea una categoría propia. Nombre y emoji obligatorios; descripción opcional.
`update_expense_category`	`categories.write`	Renombra, cambia el emoji o desactiva una categoría.
`delete_expense_category`	`categories.write`	Borra una categoría. Falla si ya tiene gastos: en ese caso se desactiva.

🏪 Negocio

Herramienta	Permiso	Qué hace
`get_company`	`companies.read`	Nombre, categoría (con etiqueta legible), ciudad y cuántas sucursales tiene.
`list_branches`	`branches.read`	Las sucursales, con cuál es la principal.
`list_business_categories`	`companies.read`	El catálogo de «a qué se dedica un negocio».
`list_payment_accounts`	`payment_accounts.read`	Cuentas de recaudo, por alias y últimos cuatro. Nunca el número completo.

👥 Equipo

Herramienta	Permiso	Qué hace
`list_team_members`	`team.read`	Quién trabaja aquí, con qué rol y en qué sucursal, más el cupo de usuarios del plan. Sin correos.
`list_roles`	`team.read`	Los roles que se pueden asignar.

🚨 Pagos sospechosos

Herramienta	Permiso	Qué hace
`list_suspicious_attempts`	`suspicious.read`	Comprobantes repetidos (`DUPLICATE`) y comprobantes que el banco nunca respaldó (`NOT_FOUND`).
`get_suspicious_attempt`	`suspicious.read`	El detalle de un intento.

🏦 Bancos y reportes

Herramienta	Permiso	Qué hace
`get_connections`	`connections.read`	Si los avisos del banco siguen entrando. Responde «¿se cayó algo?».
`get_metrics`	`metrics.read`	Totales del periodo y del anterior, serie por día, perfil por hora y ranking por persona y por cuenta. Acepta turnos.

📒 Cuentas por cobrar

El cuaderno de fiados (guía). Mismas reglas que la API: montos en pesos con hasta 2 decimales, el saldo se recalcula solo y lo que escribe el asistente queda firmado como API.

Herramienta	Permiso	Qué hace
`list_receivables`	`receivables.read`	Los clientes que deben, con saldo, etapa y si están vencidos. Por defecto, quien más debe primero; busca por nombre o teléfono sin importar tildes.
`get_receivables_summary`	`receivables.read`	Cuánto le deben al negocio en total, cuánto está vencido, lo fiado y abonado en el mes y los cinco que más deben. Sumado en la base, no en la página.
`get_receivable`	`receivables.read`	La ficha de un cliente con sus últimos 50 movimientos.
`list_receivable_entries`	`receivables.read`	El historial completo de un cliente, paginado, filtrable por tipo.
`create_receivable`	`receivables.write`	Abre la cuenta de un cliente con lo que debe y lo que ya abonó. Busca antes que no exista.
`update_receivable`	`receivables.write`	Cambia datos, fecha acordada o la etapa del tablero. No sirve para dar una cuenta por pagada.
`record_receivable_charge`	`receivables.write`	Anota un fiado. Si la cuenta estaba saldada, la reabre.
`record_receivable_payment`	`receivables.write`	Anota un abono. Si pasa del saldo, responde `RECEIVABLE_OVERPAYMENT` y el asistente te pregunta en vez de ajustar el monto.
`settle_receivable_balance`	`receivables.write`	«Pagó todo»: un abono por el saldo exacto, leído en el momento.
`archive_receivable`	`receivables.write`	Saca a un cliente del tablero y de los totales, sin perdonarle nada.
`restore_receivable`	`receivables.write`	Devuelve un archivado al tablero, tal como estaba.
`write_off_receivable_balance`	`receivables.write_off`	Condona. Con `amount`, esa parte; sin `amount`, todo el saldo. Queda como condonación, no como pago.
`void_receivable_entry`	`receivables.void`	Anula un movimiento mal registrado: queda en el historial y el saldo se recalcula sin él.

Así se le pregunta:

«¿Quién me debe más?»

«¿Quiénes están vencidos?»

«Gloria Restrepo abonó 50 mil.»

«Anota que Hernán se llevó 120 mil en materiales, y que paga el 15.»

«¿Cuánto me abonaron este mes y cuánto me siguen debiendo?»

Perdonar una deuda pide su propio permiso

La API decide el permiso de «registrar un movimiento» según el tipo; aquí cada cosa es una herramienta aparte con un permiso. Por eso, con una llave sin receivables.write_off, el asistente ni siquiera ve una forma de condonar — no una que falla a medias. Y aunque la tenga, write_off_receivable_balance y void_receivable_entry están marcadas como destructivas: los clientes que lo respetan te piden confirmar antes de ejecutarlas.

🧮 Conciliación bancaria

Las mismas operaciones de /v1/bank-statements, para conciliar el mes conversando: «sube el extracto de septiembre», «¿qué entradas faltan en Verifika?», «registra todas las que faltan».

Herramienta	Permiso	Qué hace
`upload_bank_statement`	`reconciliation.write`	Sube un extracto por URL o base64. Espera hasta 20 s; si no alcanza, vuelve con `status: processing`.
`list_bank_statements`	`reconciliation.read`	Los extractos leídos, con su avance.
`get_bank_statement`	`reconciliation.read`	El resumen: cuadre con el banco, % resuelto, lo que falta y lo que solo está en Verifika.
`list_bank_statement_lines`	`reconciliation.read`	Las filas, con los mismos filtros de la tabla del panel.
`get_bank_statement_line`	`reconciliation.read`	Una fila.
`match_bank_statement_line`	`reconciliation.write`	Concilia una fila con un ingreso o egreso que ya está en el libro.
`register_bank_statement_line`	`reconciliation.write`	Registra una fila en el libro (una salida pide además `expenses.write`).
`ignore_bank_statement_line` · `reset_bank_statement_line`	`reconciliation.write`	«No va en el libro» / deshacer.
`bulk_bank_statement_lines`	`reconciliation.write`	La misma acción sobre muchas filas, por ids o por filtro, con `remaining`.
`rematch_bank_statement`	`reconciliation.write`	Vuelve a cruzar el extracto.
`delete_bank_statement`	`reconciliation.delete`	Borra el extracto (lo registrado en el libro se queda).

Y para los gastos con la foto de la factura (guía):

Herramienta	Permiso	Qué hace
`scan_expense_receipt`	`expenses.scan`	Lee una factura y devuelve el borrador del gasto y los parecidos que ya existen. No crea nada.
`get_expense_scan`	`expenses.scan`	Una lectura, con los duplicados al día.
`create_expense_from_scan`	`expenses.write`	Crea el gasto con la factura adjunta.

🪝 Webhooks

Herramienta	Permiso	Qué hace
`list_webhook_event_types`	`webhooks.read`	Los eventos a los que se puede suscribir, y cuáles permite el plan.
`list_webhook_endpoints`	`webhooks.read`	Los webhooks configurados y su salud reciente.
`list_webhook_deliveries`	`webhooks.read`	El historial: qué se mandó y qué respondió tu servidor. Depurar sin abrir logs.
`create_webhook_endpoint`	`webhooks.write`	Da de alta una URL y devuelve el secreto de firma.
`update_webhook_endpoint`	`webhooks.write`	Cambia URL, eventos o descripción; lo apaga y lo enciende.
`delete_webhook_endpoint`	`webhooks.write`	Lo borra, con todo su historial.
`rotate_webhook_secret`	`webhooks.write`	Secreto nuevo, con ventana de gracia en la que firmamos con los dos.
`test_webhook_endpoint`	`webhooks.write`	Dispara un `webhook.test` para comprobar que responde.
`retry_webhook_delivery`	`webhooks.write`	Reencola una entrega fallida sin esperar al reintento automático.

🎬 Guiones listos

Además de las herramientas, el servidor trae prompts: tareas de varios pasos ya escritas. En Claude Desktop salen como comandos con /; en otros clientes, en un menú aparte.

Guion	Qué hace
`cierre-de-caja`	Totales del día, pagos que quedaron pendientes, gastos y sospechosos. Acepta una fecha.
`revisar-sospechosos`	Separa los repetidos de los que el banco nunca respaldó — y comprueba antes que el canal del banco no se hubiera caído, porque si se cayó, esos «falsos» pueden ser pagos buenos.
`diagnosticar-webhook`	Por qué no llegan los eventos, y de qué lado está el problema.

🚫 Cosas que ninguna herramienta puede hacer

No es que estén restringidas: no existen, por las mismas razones que en la API.

Marcar un pago como verificado. Solo el cruce con el aviso real del banco cambia ese estado. Si un asistente pudiera decir «esto está verificado», el dato dejaría de significar algo — y ese dato es el producto.
Editar un pago que nació de un comprobante o de un aviso del banco. Su fuente de verdad está fuera del libro.
Crear, rotar o revocar API keys. Eso exige una sesión de una persona en el panel: una llave que puede emitir llaves convierte cualquier fuga en una fuga total.
Borrar una categoría con gastos. Se desactiva; el histórico se conserva.
Invitar gente al equipo o cambiarle el rol a nadie. Se lee el equipo, no se administra.
Borrar un cliente o un movimiento del cuaderno de fiados. Un movimiento se anula y un cliente se archiva; en los dos casos el historial se conserva.

Las llaves de prueba no entran al MCP

Una llave vk_test_ se rechaza con 403 TEST_MODE_UNAVAILABLE: las herramientas escriben en el libro real, y el modo de prueba solo existe en la API. Mejor un «no» claro que un asistente registrando pagos reales con una llave que el dueño cree inofensiva.

En esta página