Conectar un asistente de IA (MCP)

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

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 (Streamable HTTP). 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 gasto total
list_clients	clients:read	Clientes, con ingresos totales
list_projects	projects:read	Proyectos, con totales y objetivos
upload_document	documents:write	Archiva una factura o recibo en tus documentos

Ambas vistas se calculan sobre la misma base y lo indican: 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, movimiento por movimiento, exactamente como la vista de Flujo de Caja de la app las muestra; pasa includeInternalTransfers: true a cualquiera de las herramientas para obtener el movimiento bancario bruto, que luego el basis etiqueta como tal y que no es comparable con el valor por defecto. 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 indican, desde ambos lados, de la manera en que 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 la coincidencia; nadie lo ha confirmado y el movimiento aún carece de 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 siguen aplicándose: 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 fue extraído 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, de hasta 10MB) de exactamente una de dos maneras — sus bytes (contentBase64, con un fileName), o una url de la que MoneyLights lo descarga, como un enlace prefirmado que otro servicio entregó (fileName es entonces opcional: sin él, el archivo se nombra a partir de la descarga misma, nunca del enlace, que puede llevar su secreto) — 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 — ya sea que vino como bytes o por URL. Todo lo que el asistente archiva es visible — y eliminable — en la app.

Una url debe ser https, no llevar credenciales y apuntar a un host accesible públicamente; las redirecciones se siguen solo unas pocas veces y se vuelven a verificar en cada salto, y la descarga debe ser un PDF, PNG o JPEG de como máximo 10MB que llegue dentro de 30 segundos. Los rechazos indican qué arreglar sin repetir el enlace, y la parte secreta de un enlace firmado nunca se registra.

Cualquier 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 caja, 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. Degrada o elimina al creador de la clave y el asistente se restringe o detiene en la siguiente 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 los alcances de 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.