Verbind een AI-assistent (MCP)

MoneyLights heeft een ingebouwde MCP server, zodat een AI-assistent — Claude Desktop, Claude Code, een IDE-agent, alles wat het protocol spreekt — op verzoek met de gegevens van jouw organisatie kan werken.

Het is dezelfde inloggegevens als de REST API: een MCP-verbinding is een API-sleutel, met dezelfde scopes, dezelfde limieten en dezelfde intrekknoop. Er is niets apart te beheren.

Verbinden

De endpoint is https://api.moneylights.app/mcp (Streamable HTTP). Een typische clientconfiguratie:

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

Met Claude Code is het één commando:

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

Maak de sleutel aan in Instellingen → API-sleutels en geef alleen de scopes die de assistent nodig heeft. Alles vereist de sleutel, inclusief het opsommen van de tools.

Wat de assistent kan doen

De lijst met tools wordt berekend op basis van de scopes van jouw sleutel, bij elke aanvraag. Een sleutel zonder scope krijgt nooit te horen dat de bijbehorende tool bestaat.

Tool	Scope	Wat het doet
get_cashflow_overview	cashflow:read	Maandelijkse inkomsten/uitgaven/netto, openingsbalans, topcategorieën
get_analytics_overview	analytics:read	Geaggregeerd per categorie, klant, project en persoon
list_transactions	transactions:read	Transacties, gefilterd en gepagineerd, elk met de documenten die eraan zijn gekoppeld
list_documents	documents:read	Documenten en hun geëxtraheerde velden, elk met de bewegingen die eraan zijn gekoppeld
get_document_file	documents:read	Het originele bestand van één document — de PDF of afbeelding die de app toont
get_pending_distribution	profitpulse:read	In afwachting zijnde Safe-to-Spend distributies
list_vendors	vendors:read	Leveranciers, met totale uitgaven
list_clients	clients:read	Klanten, met totale inkomsten
list_projects	projects:read	Projecten, met totalen en doelen
upload_document	documents:write	Bestanden een factuur of bon in je documenten

Beide overzichten worden berekend op de zelfde basis en geven dat aan: elke reactie bevat een basis — periode, valuta’s, de gedekte rekeningen (iedere zichtbare, tenzij om id gevraagd), en hoe overboekingen tussen de eigen rekeningen van de organisatie zijn behandeld. Standaard zijn ze exclusief van inkomsten en uitgaven, per leg, precies zoals de Cashflow-weergave van de app ze toont; geef includeInternalTransfers: true door aan een van beide tools voor de ruwe bankbeweging, die de basis dan als zodanig labelt en die niet vergelijkbaar is met de standaard. Vergelijk cijfers tussen de twee tools alleen wanneer hun basis overeenkomt. netCashResult is inkomsten min uitgaven van bankbewegingen — een cashresultaat, geen boekhoudkundig winst.

Welk document hoort bij welke beweging

Beide lijsten geven het aan, van beide kanten, zoals de app het toont. Elke transactie bevat linkedDocuments en elk document bevat linkedTransactions; elke vermelding noemt de andere kant en een link:

• confirmed — het document is gekoppeld aan de beweging, wat telt als gedocumenteerd.
• suggested — de matcher stelt de koppeling voor; niemand heeft het bevestigd en de beweging mist nog zijn document. De vermelding bevat de score van de matcher.

Een assistent kan daarom geen factuur onderscheiden van een factuur die wacht op bevestiging van al reeds ingediend — en kan daar niets aan veranderen, omdat deze verbinding geen tool daarvoor heeft.

Een beweging kan meerdere bevestigde documenten bevatten. Een document linkt naar maximaal één beweging, dus een factuur die in meerdere delen is betaald toont alleen de beweging waarmee het is gekoppeld. Een document dat nog Processing is heeft nog geen links; None betekent geen.

Scopes blijven gelden: de verre kant van een link wordt beschreven (leverancier en nummer, of beschrijving en bedrag) alleen voor een sleutel die die bron ook kan lezen. Met één scope krijg je de id van de andere kant, het soort link en de score — genoeg om te weten dat een beweging gedocumenteerd is, niet wat de factuur zegt.

Een origineel lezen

get_document_file neemt een documentId van list_documents en retourneert het opgeslagen bestand zelf — dezelfde PDF of afbeelding die de app opent — als een ingesloten bron met zijn MIME-type (application/pdf, image/jpeg, …), naast de id van het document, bestandsnaam en grootte — bestanden tot 10MB, dezelfde limiet als een upload. Dat is hoe een assistent controleert of een verschil komt van de factuur, van wat is geëxtraheerd of van de beweging waarmee het is gekoppeld, zonder iets te exporteren. Het is een leesbewerking: niets op het document, zijn geëxtraheerde velden of zijn links verandert. Een document dat niet van jou is, wordt gewoon niet gevonden.

Documenten indienen

upload_document is de enige tool die schrijft, en die is opzettelijk voor die rol gekozen: het voegt alleen maar toe. De assistent stuurt het bestand (PDF of afbeelding, tot 10MB) en MoneyLights verwerkt het via dezelfde pijplijn als een upload in de app — opgeslagen, zijn velden geëxtraheerd (leverancier, datum, nummer, bedragen) en automatisch gekoppeld aan jouw banktransacties.

Het twee keer verzenden van hetzelfde bestand dupliceert nooit jouw gegevens: de her-upload wordt opgenomen als een gemarkeerde duplicaat die naar het origineel wijst. Alles wat de assistent indient is zichtbaar — en verwijderbaar — in de app.

Elke andere schrijfactie (klanten aanmaken, transacties herclassificeren, enveloppen configureren…) blijft opzettelijk in de app: die acties veronderstellen een menselijke bevestiging.

Curated prompts

De server biedt ook kant-en-klare startpunten — een maandelijkse cashflow review, een leveranciersuitgavenanalyse, een opruiming van ontbrekende documenten — alleen vermeld wanneer jouw sleutel elke tool kan uitvoeren die ze nodig hebben. Gebruik ze zoals ze zijn of bewerk vrij.

Beveiliging

• De assistent is gebonden aan de sleutel, opnieuw gecontroleerd bij elke aanvraag. Verlaag of verwijder de maker van de sleutel en de assistent wordt beperkter of stopt bij de volgende oproep.
• Financiële gegevens bevatten tekst geschreven door vreemden — betalingsreferenties, gemailde documenten. Toolresultaten worden binnen een gemarkeerde grens geleverd die het model vertelt om ze als gegevens te behandelen, nooit als instructies. Beschouw dat als een mitigatie, geen garantie, en scope sleutels nauw.
• Om een assistent te ontkoppelen, intrek zijn sleutel in Instellingen → API-sleutels. Onmiddellijk, altijd beschikbaar.

Geef elke assistent zijn eigen sleutel — één per klant betekent dat je er één kunt intrekken zonder de rest te verstoren.