TL;DR

Wat: een open source Yuki MCP server waarmee je AI-agents via het Model Context Protocol koppelt aan de Yuki boekhouding (API-koppeling).

Voor wie: ondernemers, administratiekantoren en finance-teams die repeterende boekhoudtaken willen voorbereiden of automatiseren met AI-agents.

Waar: npm als @codemill-solutions/yuki-mcp en op GitHub.

De Yuki MCP server maakt het mogelijk om AI-agents te koppelen aan Yuki: een open source API-koppeling waarmee een agent via het Model Context Protocol veilig met je boekhouding praat. Voor ondernemers, administratiekantoren en finance-teams wordt Yuki daarmee een extra digitale collega die repeterende administratieve taken kan voorbereiden, controleren of uitvoeren — binnen duidelijke technische en functionele kaders.

Bij CodeMill onderzoeken we al langer hoe AI-agents praktisch ingezet kunnen worden binnen administratieve en financiële processen. Een belangrijk onderdeel daarvan is toegang tot betrouwbare bedrijfsdata, en voor veel organisaties zit een groot deel van die data in boekhoudsoftware. Daarom hebben we deze laag open source gepubliceerd.

De repository is beschikbaar op GitHub en het pakket is gepubliceerd via npm als @codemill-solutions/yuki-mcp. De server is gebouwd met Node.js, TypeScript en de officiële MCP SDK, en communiceert onder water met Yuki via de bestaande SOAP API.

Waarom een MCP server bovenop de Yuki API?

Yuki biedt al een publieke API-koppeling waarmee externe software informatie met Yuki kan uitwisselen. Via de beschikbare webservices kunnen onder andere financiële gegevens, verkoopfacturen, documenten, relaties, transacties en backoffice-informatie worden opgehaald of verwerkt.

Voor traditionele softwarekoppelingen is dat prima: je bouwt een applicatie, schrijft specifieke integratielogica en roept de juiste API-methodes aan.

Maar AI-agents werken anders.

Een agent moet niet alleen één vaste API-call kunnen doen, maar op basis van een opdracht kunnen bepalen welke tools nodig zijn.

Voorbeelden van wat je een agent kunt vragen:

Zoek alle openstaande verkoopfacturen op en geef me een overzicht van klanten die al langer dan 30 dagen te laat zijn.

Controleer of er nog documenten in de workflow staan die aandacht nodig hebben.

Zoek deze leverancier op, controleer de laatste transacties en geef aan of er nog openstaande posten zijn.

Daarvoor wil je geen losse, ongestructureerde API-calls aan een taalmodel geven. Je wilt duidelijke, afgebakende tools aanbieden met voorspelbare input, output en foutafhandeling. Precies daar is MCP geschikt voor.

Wat is MCP?

MCP staat voor Model Context Protocol. Je kunt het zien als een standaardmanier waarop AI-applicaties en agents externe tools kunnen gebruiken. In plaats van dat elke AI-client zijn eigen integratiepatroon moet bedenken, beschrijft een MCP server welke functies beschikbaar zijn, welke parameters ze accepteren en welke resultaten ze teruggeven.

In het geval van Yuki betekent dit dat een agent niet rechtstreeks hoeft te weten hoe de SOAP API werkt. De agent krijgt begrijpelijke tools aangeboden, zoals:

administraties ophalen;
relaties zoeken of bijwerken;
verkoop- en inkoopfacturen opvragen;
documenten uploaden of doorzoeken;
grootboekrekeningen en transacties raadplegen;
backoffice-workflow en openstaande vragen ophalen.

De complexiteit van authenticatie, SOAP-envelopes, XML, sessies en veldnamen blijft verborgen in de MCP server.

Wat doet onze Yuki MCP server?

Onze Yuki MCP server vormt een brug tussen AI-agents en de Yuki API. De server exposeert tools, verdeeld over onderdelen zoals administraties, relaties, verkoopfacturen, inkoopfacturen, transacties, accounting, documenten en backoffice.

Een paar representatieve voorbeelden per categorie:

Administraties — get_administrations, get_administration_id
Relaties — search_relations, upsert_contact
Facturen — get_sales_invoices, get_purchase_invoices, process_purchase_invoice
Documenten — upload_document, search_documents
Backoffice — get_workflow, get_outstanding_questions

De volledige, actuele lijst met tools staat in de README op GitHub — dat is de canonieke plek die we bij elke release bijwerken.

De server is daarmee niet bedoeld als “chatbot voor boekhouden”, maar als technische bouwsteen. Je kunt hem koppelen aan een MCP-compatible host, agent-framework of interne automatiseringslaag.

Voorbeeld: van opdracht naar workflow

Stel dat een finance-medewerker aan een interne agent vraagt:

Welke verkoopfacturen staan nog open en welke klanten moeten we deze week opvolgen?

De agent kan dan via de MCP server de juiste Yuki-tool aanroepen, de openstaande facturen ophalen, de resultaten groeperen, eventueel relaties opzoeken en een samenvatting maken. In een volgende stap zou zo’n agent zelfs een conceptmail kunnen voorbereiden of een taak in een intern systeem kunnen aanmaken.

Belangrijk is dat de agent niet onbeperkt “in de boekhouding rondklikt”. De beschikbare acties worden expliciet bepaald door de MCP server. Daardoor kun je veel beter sturen wat wel en niet mogelijk is.

Multi-administratie ondersteuning

Een belangrijk scenario voor administratiekantoren of organisaties met meerdere administraties is ondersteuning voor meerdere Yuki-administraties.

Daarom ondersteunt de server een configuratiebestand waarin per administrationId een eigen API key kan worden vastgelegd. De server kan vervolgens automatisch de juiste sleutel gebruiken voor administratie-specifieke tool calls. Ook is er een reload_keys tool beschikbaar, waarmee nieuwe of gewijzigde keys opnieuw kunnen worden ingeladen zonder de server volledig te herstarten.

Dat maakt de server praktischer voor omgevingen waarin meerdere administraties beheerd worden of waarin API keys dynamisch worden toegevoegd.

Technische keuzes

De server is gebouwd met:

Node.js 20+
TypeScript
@modelcontextprotocol/sdk
Yuki SOAP API
axios
fast-xml-parser

Yuki gebruikt een authenticatieflow waarbij eerst een tijdelijke sessionID wordt opgehaald via Authenticate(accessKey). Daarna wordt die sessie gebruikt voor vervolgrequests. De MCP server handelt dit intern af en cachet sessies per API key, zodat niet voor elke tool call opnieuw geauthenticeerd hoeft te worden.

Ook houdt de implementatie rekening met verschillen tussen Yuki-webservices. Sommige services gebruiken bijvoorbeeld sessionId, terwijl andere sessionID verwachten. Zulke details wil je niet in je agent-workflow hebben; die horen thuis in de integratielaag.

Rekening houden met API-limieten

Een belangrijk aandachtspunt bij agentic workflows is dat een agent soms geneigd kan zijn om veel losse tool calls te doen. Dat is niet altijd wenselijk.

Yuki hanteert standaard webservice-limieten per dag per domein, met uitbreidingsmogelijkheden voor omgevingen die meer calls nodig hebben.

Daarom is het verstandig om agent-workflows slim te ontwerpen. Laat een agent liever één brede lijst ophalen en daarmee verder redeneren, dan telkens opnieuw dezelfde informatie uit Yuki opvragen. De MCP server helpt daarbij door duidelijke tools aan te bieden, maar de workflow eromheen blijft belangrijk.

Open source gepubliceerd

We hebben de Yuki MCP server bewust open source gepubliceerd. Niet omdat we denken dat dit “af” is, maar juist omdat dit soort bouwstenen beter worden door gebruik, feedback en iteratie.

De code staat op GitHub en het pakket is beschikbaar via npm:

npm install @codemill-solutions/yuki-mcp

Daarna voeg je de server toe aan de configuratie van je MCP-host. Voor Claude Desktop ziet dat er bijvoorbeeld zo uit:

{
  "mcpServers": {
    "yuki": {
      "command": "npx",
      "args": ["@codemill-solutions/yuki-mcp"],
      "env": { "YUKI_ACCESS_KEY": "..." }
    }
  }
}

De GitHub-repository bevat de volledige installatie-instructies, configuratievoorbeelden (waaronder multi-administratie) en een overzicht van alle beschikbare tools.

Doorontwikkeling op basis van feedback

Een voordeel van open source publiceren is dat gebruikers snel kunnen aangeven welke functies in de praktijk nog ontbreken. Kort na publicatie kregen we bijvoorbeeld het verzoek om ondersteuning toe te voegen voor ontbrekende facturen: betalingen die Yuki in bankafschriften detecteert, maar waarvoor nog geen inkoopfactuur is aangeleverd.

In de Yuki webinterface is dit overzicht te vinden onder Postbus → Ontbrekende facturen. Voor accountants en ondernemers is dit een belangrijk controlepunt, omdat ontbrekende facturen de boekhouding onvolledig maken.

Op basis van deze feedback hebben we de tool get_missing_invoices toegevoegd. Deze is beschikbaar vanaf versie 1.4.0 van @codemill-solutions/yuki-mcp.

Daarmee kan een AI-agent nu dezelfde ontbrekende facturen ophalen die je normaal in de Yuki interface ziet. In combinatie met bestaande tools zoals upload_document en process_purchase_invoice ontstaat een praktische end-to-end workflow: ontbrekende facturen signaleren, het juiste document uploaden en de inkoopfactuur verder verwerken.

Voor ons is dit precies het soort use case waarvoor een MCP-laag waarde toevoegt. Niet door de boekhouding volledig te automatiseren zonder controle, maar door terugkerende administratieve signalen sneller zichtbaar en beter opvolgbaar te maken.

Waar zien we dit naartoe gaan?

Onze verwachting is dat administratieve software de komende jaren steeds vaker wordt benaderd door agents in plaats van alleen door klassieke user interfaces of vaste API-koppelingen.

Dat betekent niet dat mensen uit het proces verdwijnen. Integendeel: juist bij financiële processen blijven controle, autorisatie en context essentieel. Maar veel voorbereidende werkzaamheden kunnen wel slimmer:

openstaande posten analyseren;
ontbrekende documenten signaleren;
workflowvragen verzamelen;
relaties en transacties controleren;
conceptboekingen of conceptfacturen voorbereiden;
documenten uploaden en classificeren;
managementinformatie samenvatten.

Een MCP server is daarin geen eindproduct, maar een fundament. Het maakt bestaande software beter bereikbaar voor moderne AI-toepassingen.

Interesse in Yuki, MCP of AI-automatisering?

Bij CodeMill bouwen we maatwerksoftware, API-integraties en AI-oplossingen voor organisaties die hun processen slimmer willen inrichten. De Yuki MCP server is een voorbeeld van hoe we bestaande systemen ontsluiten voor nieuwe vormen van automatisering.

Gebruik je Yuki? Plan een gesprek over AI-automatisering →

Liever eerst zelf de techniek bekijken? De code staat open source op GitHub.

Yuki MCP: AI-agents koppelen aan je boekhouding