Conectar un asistente de IA (MCP)

MoneyLights tiene un servidor MCP integrado, así que un asistente de IA — Claude Desktop, Claude Code, un agente de IDE, cualquier cosa que hable el protocolo — puede trabajar con los datos de tu organización a pedido.

Es la misma credencial que la API REST: una conexión MCP es una clave API, con los mismos alcances, los mismos límites y el mismo botón de revocación. No hay nada separado que gestionar.

Conectando

El endpoint es https://api.moneylights.app/mcp (HTTP transmitible). Una configuración típica del cliente:

{
  "mcpServers": {
    "moneylights": {
      "url": "https://api.moneylights.app/mcp",
      "headers": { "X-API-Key": "ml_sk_..." }
    }
  }
}

Con Claude Code es un solo comando:

claude mcp add --transport http moneylights https://api.moneylights.app/mcp \
  --header "X-API-Key: ml_sk_..."

Crea la clave en Configuración → Claves API y otórgale solo los alcances que necesita el asistente. Todo requiere la clave, incluyendo listar las herramientas.

Lo que el asistente puede hacer

La lista de herramientas se calcula a partir de los alcances de tu clave, en cada solicitud. Una clave sin un alcance nunca se entera de que la herramienta correspondiente existe.

Herramienta	Alcance	Lo que hace
get_cashflow_overview	cashflow:read	Ingresos/gastos/neto mensuales, saldo inicial, principales categorías
get_analytics_overview	analytics:read	Agregados por categoría, cliente, proyecto y persona
list_transactions	transactions:read	Transacciones, filtradas y paginadas, cada una con los documentos vinculados
list_documents	documents:read	Documentos y sus campos extraídos, cada uno con los movimientos vinculados
get_document_file	documents:read	El archivo original de un documento — el PDF o imagen que la app muestra
get_pending_distribution	profitpulse:read	Distribuciones pendientes de Seguro para Gastar
list_vendors	vendors:read	Proveedores, con el gasto total
list_clients	clients:read	Clientes, con los ingresos totales
list_projects	projects:read	Proyectos, con totales y objetivos
upload_document	documents:write	Archivos una factura o recibo en tus documentos

Ambas vistas se calculan sobre la misma base y lo dicen: cada respuesta lleva un basis — período, monedas, las cuentas cubiertas (todas las visibles, a menos que se solicite por id), y cómo se trataron las transferencias entre las propias cuentas de la organización. Por defecto, están excluidas de ingresos y gastos, pierna por pierna, exactamente como la vista de Flujo de Efectivo de la app las muestra; pasa includeInternalTransfers: true a cualquiera de las herramientas para el movimiento bancario bruto, que el basis luego etiqueta como tal y que no es comparable con el predeterminado. Compara cifras entre las dos herramientas solo cuando su basis coincide. netCashResult es ingresos menos gastos de movimientos bancarios — un resultado en efectivo, no una ganancia contable.

Qué documento va con qué movimiento

Ambas listas lo dicen, desde ambos lados, como la app lo muestra. Cada transacción lleva linkedDocuments y cada documento lleva linkedTransactions; cada entrada nombra el otro lado y un link:

• confirmed — el documento está emparejado con el movimiento, lo que cuenta como documentado.
• suggested — el emparejador propone el emparejamiento; nadie lo ha confirmado y el movimiento todavía está esperando su documento. La entrada lleva el score del emparejador.

Un asistente puede, por lo tanto, distinguir ninguna factura de una factura esperando ser confirmada de ya archivada — y no puede cambiar nada de ello, porque esta conexión no tiene herramienta para eso.

Un movimiento puede llevar varios documentos confirmados. Un documento se vincula a como máximo un movimiento, así que una factura pagada en varias partes muestra solo el movimiento al que fue emparejada. Un documento que aún está Processing no tiene enlaces todavía; None significa ninguno.

Los alcances aún se mantienen: el lado lejano de un enlace se describe (proveedor y número, o descripción y monto) solo a una clave que también puede leer ese recurso. Con un alcance obtienes el id del otro lado, el tipo de enlace y el score — suficiente para saber que un movimiento está documentado, no lo que dice la factura.

Leer un original

get_document_file toma un documentId de list_documents y devuelve el archivo almacenado en sí — el mismo PDF o imagen que la app abre — como un recurso embebido con su tipo MIME (application/pdf, image/jpeg, …), junto al id del documento, nombre del archivo y tamaño — archivos de hasta 10MB, el mismo límite que una carga. Así es como un asistente verifica si una diferencia proviene de la factura, de lo que se extrajo o del movimiento al que fue emparejado, sin exportar nada. Es una lectura: nada en el documento, sus campos extraídos o sus enlaces cambia. Un documento que no es tuyo simplemente no se encuentra.

Archivar documentos

upload_document es la única herramienta que escribe, y fue elegida para ese rol deliberadamente: solo agrega. El asistente envía el archivo (PDF o imagen, hasta 10MB) y MoneyLights lo procesa a través del mismo pipeline que una carga en la app — almacenado, sus campos extraídos (proveedor, fecha, número, montos) y emparejado automáticamente con tus transacciones bancarias.

Enviar el mismo archivo dos veces nunca duplica tus datos: la re-carga se registra como un duplicado marcado que apunta al original. Todo lo que el asistente archiva es visible — y eliminable — en la app.

Cada otra escritura (crear clientes, reclasificar transacciones, configurar sobres…) permanece en la app a propósito: esas acciones asumen que un humano las confirma.

Prompts curados

El servidor también ofrece puntos de partida listos para usar — una revisión mensual de flujo de efectivo, un análisis de gasto de proveedores, una limpieza de documentos faltantes — listados solo cuando tu clave puede ejecutar todas las herramientas que necesitan. Úsalos tal cual o edítalos libremente.

Seguridad

• El asistente está limitado por la clave, verificada en cada solicitud. Despromociona o elimina al creador de la clave y el asistente se restringe o detiene en la próxima llamada.
• Los datos financieros contienen texto escrito por extraños — referencias de pago, documentos enviados por correo. Los resultados de las herramientas se entregan dentro de un límite marcado que indica al modelo que los trate como datos, nunca como instrucciones. Trata eso como una mitigación, no como una garantía, y limita las claves estrictamente.
• Para desconectar un asistente, revoca su clave en Configuración → Claves API. Inmediato, siempre disponible.

Dale a cada asistente su propia clave — una por cliente significa que puedes cortar una sin perturbar al resto.