Connecter un assistant IA (MCP)

MoneyLights a un serveur MCP intégré, donc un assistant IA — Claude Desktop, Claude Code, un agent IDE, tout ce qui parle le protocole — peut travailler avec les données de ton organisation sur demande.

C’est le même identifiant que l’API REST : une connexion MCP est une clé API, avec les mêmes portées, les mêmes limites et le même bouton de révocation. Il n’y a rien de séparé à gérer.

Connexion

L’endpoint est https://api.moneylights.app/mcp (Streamable HTTP). Une configuration client typique :

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

Avec Claude Code, c’est une seule commande :

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

Crée la clé dans Paramètres → Clés API et accorde-lui uniquement les portées dont l’assistant a besoin. Tout nécessite la clé, y compris la liste des outils.

Ce que l’assistant peut faire

La liste des outils est calculée à partir des portées de ta clé, à chaque demande. Une clé sans portée n’est même pas informée de l’existence de l’outil correspondant.

Outil	Portée	Ce qu’il fait
get_cashflow_overview	cashflow:read	Revenus/dépenses/net mensuels, solde d’ouverture, principales catégories
get_analytics_overview	analytics:read	Agrégats par catégorie, client, projet et personne
list_transactions	transactions:read	Transactions, filtrées et paginées, chacune avec les documents qui lui sont liés
list_documents	documents:read	Documents et leurs champs extraits, chacun avec les mouvements qui lui sont liés
get_document_file	documents:read	Le fichier original d’un document — le PDF ou l’image que l’application affiche
get_pending_distribution	profitpulse:read	Distributions de Safe-to-Spend en attente
list_vendors	vendors:read	Fournisseurs, avec dépenses totales
list_clients	clients:read	Clients, avec revenus totaux
list_projects	projects:read	Projets, avec totaux et objectifs
upload_document	documents:write	Classe une facture ou un reçu dans tes documents

Les deux aperçus sont calculés sur la même base et le disent : chaque réponse porte un basis — période, devises, les comptes couverts (tous visibles, sauf demande par id), et comment les transferts entre les propres comptes de l’organisation ont été traités. Par défaut, ils sont exclus des revenus et des dépenses, mouvement par mouvement, exactement comme l’affiche la vue Flux de Trésorerie de l’application ; passe includeInternalTransfers: true à l’un ou l’autre outil pour le mouvement bancaire brut, que le basis étiquettera alors comme tel et qui n’est pas comparable avec le défaut. Compare les chiffres entre les deux outils uniquement lorsque leur basis correspond. netCashResult est le revenu moins les dépenses des mouvements bancaires — un résultat de trésorerie, pas un bénéfice comptable.

Quel document va avec quel mouvement

Les deux listes le disent, des deux côtés, comme l’affiche l’application. Chaque transaction porte linkedDocuments et chaque document porte linkedTransactions ; chaque entrée nomme l’autre côté et un link :

• confirmed — le document est associé au mouvement, ce qui compte comme documenté.
• suggested — le système de correspondance propose l’appariement ; personne ne l’a confirmé et il manque encore son document au mouvement. L’entrée porte le score du système de correspondance.

Un assistant peut donc distinguer aucune facture d’une facture en attente de confirmation de déjà classée — et ne peut rien changer, car cette connexion n’a pas d’outil pour cela.

Un mouvement peut porter plusieurs documents confirmés. Un document est lié au maximum à un mouvement, donc une facture payée en plusieurs parties n’affiche que le mouvement auquel elle a été associée. Un document encore Processing n’a pas de liens encore ; None signifie aucun.

Les portées continuent de s’appliquer : le côté éloigné d’un lien est décrit (fournisseur et numéro, ou description et montant) uniquement à une clé qui peut lire cette ressource aussi. Avec une portée, tu obtiens l’id de l’autre côté, le type de lien et le score — suffisamment pour savoir qu’un mouvement est documenté, pas ce que dit la facture.

Lire un original

get_document_file prend un documentId de list_documents et renvoie le fichier stocké lui-même — le même PDF ou image que l’application ouvre — comme une ressource intégrée avec son type MIME (application/pdf, image/jpeg, …), à côté de l’id du document, du nom du fichier et de la taille — fichiers jusqu’à 10 Mo, le même plafond qu’un téléversement. C’est ainsi qu’un assistant vérifie si une différence provient de la facture, de ce qui a été extrait ou du mouvement auquel elle a été associée, sans exporter quoi que ce soit. C’est une lecture : rien sur le document, ses champs extraits ou ses liens ne change. Un document qui n’est pas le tien est simplement non trouvé.

Classer des documents

upload_document est le seul outil qui écrit, et il a été choisi pour ce rôle délibérément : il ne fait qu’ajouter. L’assistant envoie le fichier (PDF ou image, jusqu’à 10 Mo) de exactement l’une des deux manières — ses octets (contentBase64, avec un fileName), ou une url que MoneyLights télécharge, comme un lien pré-signé qu’un autre service a distribué (fileName est alors optionnel : sans lui, le fichier est nommé à partir du téléchargement lui-même, jamais à partir du lien, qui peut porter son secret) — et MoneyLights le fait passer par le même pipeline qu’un téléversement dans l’application — stocké, ses champs extraits (fournisseur, date, numéro, montants) et auto-apparié avec tes transactions bancaires.

Envoyer le même fichier deux fois ne duplique jamais tes données : le nouveau téléversement est enregistré comme un doublon signalé pointant vers l’original — qu’il soit venu sous forme d’octets ou par URL. Tout ce que l’assistant classe est visible — et supprimable — dans l’application.

Une url doit être https, ne porter aucun identifiant et pointer vers un hôte accessible publiquement ; les redirections sont suivies seulement quelques fois et vérifiées à chaque étape, et le téléchargement doit être un PDF, PNG ou JPEG d’au plus 10 Mo qui arrive dans les 30 secondes. Les refus indiquent ce qu’il faut corriger sans répéter le lien, et la partie secrète d’un lien signé n’est jamais enregistrée.

Chaque autre écriture (création de clients, reclassement de transactions, configuration d’enveloppes…) reste dans l’application par choix : ces actions supposent qu’un humain les confirme.

Prompts sélectionnés

Le serveur propose également des points de départ prêts à l’emploi — un examen mensuel du flux de trésorerie, une analyse des dépenses des fournisseurs, un nettoyage des documents manquants — listés uniquement lorsque ta clé peut exécuter tous les outils dont ils ont besoin. Utilise-les tels quels ou édite-les librement.

Sécurité

• L’assistant est limité par la clé, vérifiée à chaque demande. Rétrograde ou supprime le créateur de la clé et l’assistant se restreint ou s’arrête lors de l’appel suivant.
• Les données financières contiennent du texte écrit par des inconnus — références de paiement, documents envoyés par e-mail. Les résultats des outils sont livrés à l’intérieur d’une limite marquée indiquant au modèle de les traiter comme des données, jamais comme des instructions. Considère cela comme une atténuation, pas une garantie, et limite les clés strictement.
• Pour déconnecter un assistant, révoque sa clé dans Paramètres → Clés API. Immédiat, toujours disponible.

Donne à chaque assistant sa propre clé — une par client signifie que tu peux en couper une sans perturber les autres.