KRONENWERK MCP-server: een AI-agent aan uw boekhouding koppelen

KRONENWERK biedt een Model Context Protocol-server (MCP) aan op https://kronenwerk.org/api/extern/mcp. Een AI-agent die MCP over Streamable HTTP spreekt, authenticeert met OAuth 2.1 (Claude, ChatGPT en andere gehoste assistenten) of met dezelfde Bearer-API-sleutel als de REST-API, leest de klanten, facturen, transacties en rapporten van één bedrijf en maakt concepten, transacties en notities aan. Of hij ook een factuur mag uitreiken, versturen of een betaling mag boeken, beslist het bedrijf: standaard blijven dat handelingen van een persoon, en het bedrijf kan ze onder Instellingen → AI-assistenten toestaan tot een bedragsgrens die het zelf stelt, waarbij elke handeling wordt vastgelegd. De MCP-server maakt deel uit van het abonnement Enterprise.

Wat MCP is

Het Model Context Protocol is een open specificatie, gepubliceerd op modelcontextprotocol.io, die definieert hoe een AI-toepassing (de client) tools ontdekt en aanroept die door een extern systeem (de server) worden aangeboden. Berichten zijn JSON-RPC 2.0. De server publiceert een lijst van tools met namen, beschrijvingen en JSON-invoerschema's; het model leest die beschrijvingen, beslist wat het aanroept, en de client stuurt namens het model een tools/call-verzoek. Het resultaat komt terug als inhoud die het model kan lezen en, optioneel, als gestructureerde JSON.

Twee transporten zijn gestandaardiseerd: stdio voor een server die als lokaal subproces wordt gestart, en Streamable HTTP voor een server die via het netwerk wordt bereikt. KRONENWERK is een netwerkdienst en implementeert dus uitsluitend Streamable HTTP. Het protocol wordt per datum geversioneerd. Op 2026-09-03 noemt de specificatie 2026-07-28 als de huidige revisie; eerdere revisies (2025-11-25, 2025-06-18, 2025-03-26) openen een verbinding met een initialize-handshake, terwijl de huidige revisie de protocolversie en de clientidentiteit in een _meta-object op elk verzoek meedraagt en een server/discover-methode toevoegt. Een server mag meer dan één revisie op hetzelfde endpoint bedienen, en KRONENWERK doet dat.

Endpoint, transport en authenticatie

Alles gebeurt op één adres met één HTTP-methode: POST https://kronenwerk.org/api/extern/mcp, body application/json, één JSON-RPC-bericht per verzoek.

Authenticatie

Ofwel Authorization: Bearer greif_oauth_… — een OAuth 2.1-toegangstoken via authorization code + PKCE op /oauth/authorize en /oauth/token, met dynamische clientregistratie op /oauth/register en discovery onder /.well-known/oauth-authorization-server (zo verbinden Claude en ChatGPT: de eigenaar van het bedrijf meldt zich één keer aan en stemt toe) — ofwel Authorization: Bearer greif_live_… / greif_test_…, dezelfde API-sleutel die de REST-API accepteert, aangemaakt in de instellingen van KRONENWERK en gebonden aan precies één bedrijf. Een verzoek zonder geldig bewijs krijgt 401 met WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource", dat MCP-clients volgen om de aanmelding te starten. Zie authenticatie.

Tenant

De onderneming die een agent bereikt, is de onderneming van de sleutel. Er is nergens in het protocol een organisatieparameter, dus een agent kan geen ondernemingen selecteren of opsommen.

Sessie

Geen. De server houdt geen sessie bij en geeft geen MCP-Session-Id uit. Elk verzoek draagt zijn eigen referentie en zijn eigen protocolversie. GET (de optionele server-naar-clientstream) en DELETE (sessiebeëindiging) antwoorden met 405 Method Not Allowed, wat de specificatie voorschrijft voor servers die deze niet aanbieden.

Protocolversies

2026-07-28 (_meta per verzoek), en de op handshake gebaseerde 2025-11-25, 2025-06-18 en 2025-03-26. Een verzoek dat een andere versie noemt, ontvangt JSON-RPC-fout -32022 met de ondersteunde lijst in data.supported. Een verzoek dat helemaal geen versie noemt, wordt als legacy-client bediend.

Methoden

server/discover, initialize, tools/list, tools/call, ping. Geen resources, prompts, sampling of notificaties; de server opent nooit een stream. Batches worden niet aanvaard; elk verzoek is één bericht.

Origin

Een verzoek met een Origin-header van een andere site wordt geweigerd met 403, zoals de specificatie vereist tegen DNS-rebinding. Niet-browserclients sturen geen Origin en worden niet beïnvloed.

Rate limit

Het MCP-endpoint zit in dezelfde filterketen als de REST-API, dus het budget van de sleutel van 240 verzoeken, dat met ongeveer twee per seconde wordt aangevuld, geldt voor beide samen. Boven het budget is het antwoord 429 met Retry-After. Zie rate limits.

Plan

Een geldige sleutel waarvan de onderneming niet op het Enterprise-plan zit, ontvangt 403 met toepassingsfoutcode 1402 en een zin die dat zegt. De plannen worden beschreven op de prijspagina.

Voor clients op de huidige revisie controleert de server ook de gespiegelde headers die de specificatie heeft ingevoerd — MCP-Protocol-Version, Mcp-Method en, bij tools/call, Mcp-Name — tegen de body, en beantwoordt een afwijking met fout -32020 en HTTP 400. Clients die op een onderhouden MCP-SDK zijn gebouwd, doen dit automatisch.

De tools

Er zijn tweeëntwintig tools in drie klassen: leestools, die niets veranderen; concepttools, die iets inerts aanmaken waarop een persoon nog moet handelen; en handelingstools, die een financieel feit waar maken en alleen worden aangeboden aan bedrijven die het niveau Handelen binnen een grens hebben gekozen. tools/list geeft alleen de tools terug die de rechten van het bewijs en het niveau van het bedrijf toestaan; een sleutel met alleen invoices:read ziet de factuurlezers en niets anders, en een bedrijf op het standaardniveau ziet nooit een handelingstool. De rechten zijn dezelfde als die van de REST-API.

Bedragen worden teruggegeven als een aantal kleinste eenheden met een valutacode — {"minor": 105910, "currency": "EUR"} is 1.059,10 EUR — nooit als opgemaakte tekst. Datums zijn kalenderdagen in YYYY-MM-DD. Elk object dat een concepttool aanmaakt, wordt vastgelegd als aangemaakt door die API-sleutel, en de onderneming ziet die toewijzing in het product. Een model kan zijn werk niet laten doorgaan voor dat van een persoon.

Niveaus en veiligheidsgrenzen

Het bedrijf — niet de agent en niet KRONENWERK — beslist hoe ver software mag gaan. Onder Instellingen → AI-assistenten stelt de eigenaar een van drie niveaus in, en dat geldt gelijk voor elke verbonden assistent en elke sleutel:

• Alleen lezen — de twaalf leestools. Concepten staan uit; een conceptaanroep krijgt een zin die dat zegt.
• Lezen en voorstellen (standaard) — leestools plus de zeven concepttools. Niets wat een agent op dit niveau doet, is een financieel feit; een persoon reikt uit, verstuurt en boekt.
• Handelen binnen een grens — voegt issue_invoice, send_invoice en record_payment toe. Elke afzonderlijke handeling wordt getoetst aan een brutobedragsgrens in de basisvaluta van het bedrijf, binnen de eigen transactie, zodat een factuur boven de grens in haar geheel wordt teruggedraaid: geen nummer verbruikt, geen record, geen e-mail.

Op geen enkel niveau annuleert of corrigeert een tool een uitgereikt document, keurt of betaalt het een inkoopfactuur, maakt het een journaalpost, sluit het een periode af, of maakt, roteert of trekt het bewijzen en instellingen in. Dat blijft bij een persoon die in KRONENWERK is aangemeld.

Vraagt een model om een handeling die het bedrijf niet heeft toegestaan — record_payment op het standaardniveau, cancel_invoice op elk niveau — dan antwoordt de server niet met „onbekende tool”, wat een model leest als een naamprobleem en omzeilt. Hij antwoordt met een normaal resultaat gemarkeerd isError: true, waarvan de tekst de regel noemt, zegt dat geen deel van het verzoek is uitgevoerd, en de instelling noemt die een persoon zou wijzigen. Het model geeft iets waars door en stopt.

Elke handeling en elk concept wordt met tool, verbinding en tijd in het auteursregister van het bedrijf geschreven, en de onderliggende diensten schrijven hun gewone auditregels onder de verbinding in plaats van onder een persoon, zodat het spoor altijd zegt welke assistent wat deed. Andere eigenschappen volgen uit het transport: lezen valt onder dezelfde rechten als het overeenkomstige scherm; identificaties van een ander bedrijf worden gemeld als niet gevonden in plaats van verboden; interne fouten worden beschreven in één vaste zin zonder stacktrace, zodat tabelnamen en bestandspaden nooit in de context van een model komen; en een verbinding kan op elk moment in de instellingen worden ingetrokken, wat de toegang van die agent bij het volgende verzoek beëindigt. Dezelfde regels als voor de REST-API gelden — zie API-beveiliging.

Een client aansluiten

De meeste MCP-clients aanvaarden een JSON-configuratie die externe servers benoemt. Een generieke vermelding voor KRONENWERK ziet er zo uit; de sleutelnamen van het buitenste object verschillen per client, de binnenste velden niet:

{
  "mcpServers": {
    "kronenwerk": {
      "type": "http",
      "url": "https://kronenwerk.org/api/extern/mcp",
      "headers": {
        "Authorization": "Bearer greif_live_XXXXXXXXXXXXXXXXXXXXXXXX"
      }
    }
  }
}

Gebruik tijdens het bouwen een greif_test_-sleutel. Die bereikt hetzelfde endpoint in testmodus voor de onderneming die hem heeft aangemaakt; er is geen afzonderlijke sandbox-host. Maak de sleutel aan met alleen de scopes die de agent nodig heeft: een assistent die "wie is ons geld verschuldigd" beantwoordt, heeft reports:read en customers:read nodig en niets meer.

Zonder client kan het endpoint met curl worden uitgeprobeerd. Een handshake in legacy-stijl en een toolaanroep:

curl -s https://kronenwerk.org/api/extern/mcp \
  -H "Authorization: Bearer greif_test_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-11-25","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1"}}}'

curl -s https://kronenwerk.org/api/extern/mcp \
  -H "Authorization: Bearer greif_test_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"list_receivables","arguments":{"as_of":"2026-09-03"}}}'

Het resultaat van de tweede aanroep bevat het rapport zowel als leesbare tekst in content als als JSON in structuredContent. Een client op de huidige revisie stuurt dezelfde berichten met de versie in params._meta["io.modelcontextprotocol/protocolVersion"] en de gespiegelde headers; de server beantwoordt beide vormen.

MCP of REST: wat te gebruiken

Gebruik MCP wanneer een taalmodel tijdens de uitvoering beslist wat het vraagt. Gebruik de REST-API wanneer uw eigen code beslist. De twee oppervlakken lezen dezelfde gegevens onder dezelfde sleutel en scopes, dus niets dwingt tot een keuze, en een systeem kan beide gebruiken.

Het REST-oppervlak wordt beschreven in het overzicht van de boekhoud-API, de referentie en de snelstart. Integratiepatronen op toepassingsniveau komen aan bod in uw SaaS koppelen.

Hoe KRONENWERK dit aanpakt

SUPPORTED De MCP-server is live op https://kronenwerk.org/api/extern/mcp voor bedrijven op het abonnement Enterprise, spreekt Streamable HTTP voor de protocolrevisies 2026-07-28, 2025-11-25, 2025-06-18 en 2025-03-26, authenticeert met OAuth 2.1 of een API-sleutel, en biedt elk bedrijf de twaalf leestools en zeven concepttools en de bedrijven die onder Instellingen → AI-assistenten handelen hebben toegestaan de drie handelingstools — elke handeling begrensd door de eigen grens van het bedrijf en vastgelegd. Annuleren, corrigeren, leveranciers betalen, boeken, afsluiten en configureren blijven bewust zonder tool. Dezelfde server werkt met een greif_test_-sleutel in testmodus. De MCP-server, de REST-API, webhooks en de integratiegids maken deel uit van het abonnement Enterprise; zie prijzen en het ontwikkelaarsoverzicht.