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 je 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 intrekknop. Er is niets apart te beheren.

Verbinden

Het eindpunt 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 deze 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 je sleutel, bij elke aanvraag. Een sleutel zonder scope wordt nooit zelfs maar verteld 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`	Aggregaten per categorie, klant, project en persoon
`list_transactions`	`transactions:read`	Transacties, gefilterd en gepagineerd, elk met de documenten die eraan gekoppeld zijn
`list_documents`	`documents:read`	Documenten en hun geëxtraheerde velden, elk met de bewegingen die eraan gekoppeld zijn
`get_document_file`	`documents:read`	Het originele bestand van één document — de PDF of afbeelding die de app toont
`get_pending_distribution`	`profitpulse:read`	Veilig te besteden distributies in afwachting
`list_vendors`	`vendors:read`	Leveranciers, met totale uitgaven
`list_clients`	`clients:read`	Klanten, met totale omzet
`list_projects`	`projects:read`	Projecten, met totalen en doelen
`upload_document`	`documents:write`	Archiveert een factuur of ontvangstbewijs 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 (elke zichtbare, tenzij om id gevraagd), en hoe overboekingen tussen de eigen rekeningen van de organisatie zijn behandeld. Standaard zijn ze uitgesloten van inkomsten en uitgaven, beweging voor beweging, precies zoals de Cashflow-weergave van de app ze toont; geef includeInternalTransfers: true door aan een van de 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 minus uitgaven van bankbewegingen — een cashresultaat, geen boekhoudkundige winst.

Welk document bij welke beweging hoort

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

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

Een assistent kan daarom onderscheid maken tussen geen factuur, een factuur die wacht op bevestiging en al gearchiveerd — maar kan er niets van 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 van kracht: de verre kant van een link wordt beschreven (leverancier en nummer, of beschrijving en bedrag) alleen aan 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 leesoperatie: niets op het document, zijn geëxtraheerde velden of zijn links verandert. Een document dat niet van jou is, wordt gewoon niet gevonden.

Documenten archiveren

upload_document is de enige tool die schrijft, en deze is opzettelijk voor die rol gekozen: het voegt alleen maar toe. De assistent stuurt het bestand (PDF of afbeelding, tot 10MB) op precies één van twee manieren — zijn bytes (contentBase64, met een fileName), of een url waar MoneyLights het van downloadt, zoals een vooraf ondertekende link die een andere service heeft verstrekt (fileName is dan optioneel: zonder het, wordt het bestand genoemd naar de download zelf, nooit naar de link, die zijn geheim kan dragen) — 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 je banktransacties.

Het twee keer verzenden van hetzelfde bestand dupliceert je gegevens nooit: de her-upload wordt vastgelegd als een gemarkeerde duplicaat die naar het origineel verwijst — of het nu als bytes of via URL kwam. Alles wat de assistent archiveert is zichtbaar — en verwijderbaar — in de app.

Een url moet https zijn, geen inloggegevens bevatten en wijzen naar een publiek bereikbare host; omleidingen worden slechts een paar keer gevolgd en opnieuw gecontroleerd bij elke stap, en de download moet een PDF, PNG of JPEG van maximaal 10MB zijn die binnen 30 seconden arriveert. Weigeringen zeggen wat er moet worden opgelost zonder de link te herhalen, en het geheime deel van een ondertekende link wordt nooit gelogd.

Elke andere schrijfoperatie (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 analyse van leveranciersuitgaven, een opruiming van ontbrekende documenten — alleen vermeld wanneer je sleutel elke tool kan uitvoeren die ze nodig hebben. Gebruik ze zoals ze zijn of bewerk ze vrijelijk.

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 geleverd binnen een gemarkeerde grens die het model vertelt om ze als gegevens te behandelen, nooit als instructies. Beschouw dat als een mitigatie, geen garantie, en scope sleutels strak.
Om een assistent te ontkoppelen, trek je zijn sleutel in in Instellingen → API-sleutels. Onmiddellijk, altijd beschikbaar.

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