Invoiso MCP-server

Invoiso spreekt het Model Context Protocol, zodat een MCP-client — Claude, ChatGPT of iets anders dat het spreekt — de facturen, inkopen, contacten, voorraad en rapporten in uw invoiso-werkruimte kan lezen en bewerken. Deze pagina is alles wat u nodig hebt om er een te verbinden.

Het eindpunt

https://www.invoiso.com/api/mcp

Transport   Streamable HTTP (POST, JSON-RPC 2.0)
Auth        OAuth 2.1 — see below
Server      invoiso 0.1.0
Protocol    2025-06-18, 2025-03-26, 2024-11-05

De meeste mensen hebben alleen de URL nodig. Voeg die toe als aangepaste connector in ChatGPT of als externe MCP-server in Claude en meld u daarna gewoon aan bij invoiso — een API-sleutel is niet nodig. De client ontdekt zelf hoe hij zich moet authenticeren: een niet-geauthenticeerde aanroep antwoordt 401 met een WWW-Authenticate-header die verwijst naar https://www.invoiso.com/.well-known/oauth-protected-resource, waar de autorisatieserver en de te vragen scopes staan.

Verbinden

1. Voeg https://www.invoiso.com/api/mcp toe aan uw client als externe MCP-server.
2. De client stuurt u naar de aanmeldpagina van invoiso. Meld u aan zoals u gewend bent.
3. Keur de toegang goed die het toestemmingsscherm beschrijft. Het noemt de werkruimte die u verbindt.
4. U bent verbonden. Vraag uw client iets over uw boeken — “wat heb ik vorige maand gefactureerd?” is een goede eerste vraag, want die vraagt geen rechten buiten lezen.

De gevraagde scopes zijn openid, email, profile en user:org:read. De laatste vertelt ons welke werkruimte u verbindt; zonder die weigert de server in plaats van te gokken — zie hieronder.

Met welke werkruimte u verbonden bent

U bent verbonden met de werkruimte die actief was in uw browser toen u de verbinding goedkeurde. Het toestemmingsscherm noemt die. Dit is dezelfde regel als in de browser — een sessie zit in één werkruimte tegelijk — en het betekent dat van werkruimte wisselen in invoiso verandert niet wat uw MCP-client ziet.

Wilt u een client op een andere werkruimte richten: schakel eerst in invoiso naar die werkruimte, verwijder daarna de verbinding in uw client en voeg hem opnieuw toe. U doorloopt de toestemming opnieuw en het nieuwe token draagt de nieuwe werkruimte.

Kan de server niet bepalen voor welke werkruimte een token geldt, dan antwoordt hij 403 met error="insufficient_scope" en noemt de aan te vragen scope, in plaats van er een te kiezen. Kiezen zou erger zijn dan weigeren: het plausibele foute antwoord is uw lege persoonlijke werkruimte, en u zou concluderen dat invoiso uw boeken kwijt is.

Wat uw abonnement kan

Voor de assistent binnen invoiso is alles beschikbaar, op elk abonnement. Wat verandert bij een externe MCP-client, is of die mag schrijven.

Een alleen-lezen-verbinding is geen uitgeklede client — het is elk hulpmiddel dat alleen rapporteert. Schrijven vanuit een externe client begint bij Business. Vraagt u een alleen-lezen-verbinding iets te wijzigen, dan zegt die dat in één zin en verandert niets, in plaats van onduidelijk te falen.

Wat de tools doen

Er zijn 167 tools. 63 daarvan rapporteren alleen; de rest schrijft. Elke tool draagt de drie annotaties die MCP definieert — readOnlyHint, destructiveHint en openWorldHint — zodat uw client het u kan vragen voordat hij iets onomkeerbaars doet. 15 ervan kunnen iets buiten invoiso wijzigen: een e-mail sturen, een betaalpagina publiceren, in Xero of QuickBooks schrijven. Dat zijn de tools die uw client beter kan laten bevestigen.

Bedragen staan er altijd twee keer

Een werkruimte kan documenten in meerdere valuta’s bevatten. Elke tool die een bedrag teruggeeft, geeft het in de eigen valuta van het document én in de rapportagevaluta van de werkruimte, omgerekend tegen de koers die aan dat document is vastgezet. Alleen de tweede is vergelijkbaar tussen documenten, en de instructies van de server zeggen het model nooit twee bedragen in verschillende valuta’s op te tellen. Waar geen wisselkoers een datum dekte, is het rapportagecijfer null in plaats van nul.

Totalen komen uit de rapportagetool

run_report beantwoordt “hoeveel”-vragen. Lijsttools maken lijsten; een lijst optellen is niet dezelfde rekensom — concepten en creditnota’s tellen anders — en de beschrijving van elke tool zegt welke het is.

Wat de server leest, en wat hij bewaart

Een toolaanroep leest en schrijft de eigen gegevens van uw werkruimte: uw facturen, inkopen, contacten, producten en instellingen. De antwoorden bevatten de gevraagde bedrijfsgegevens — voor een contact de naam, en mogelijk een e-mailadres, een postadres of een btw-nummer, want dat is wat op een factuur staat.

De server bewaart geen aparte kopie van een gesprek, stuurt geen enkel toolantwoord ergens anders heen dan terug naar de client die het vroeg, en geeft nooit inloggegevens, API-sleutels of OAuth-tokens terug — de uwe noch die van een gekoppelde dienst. Wat wij in het algemeen met gegevens doen, inclusief welke derden wat ontvangen, staat in het privacybeleid, en de voorwaarden gelden voor deze verbinding als voor elke andere.

Verbinding verbreken

Verwijder de verbinding in uw MCP-client. Dat is genoeg: het token is het enige dat toegang geeft, en aan onze kant blijft er zonder dat niets werken. Uw invoiso-account verwijderen verwijdert alles wat erachter zit — het privacybeleid zegt wat dat betekent en hoe lang het duurt.

Protocoldetails

De server onderhandelt 2025-06-18, 2025-03-26 en 2024-11-05 en antwoordt met de nieuwste versie die hij en de client allebei begrijpen. Op een onbekende versie antwoordt hij met de nieuwste die wij ondersteunen in plaats van te weigeren, wat de specificatie vraagt.

Autorisatie volgt OAuth 2.1 met PKCE. Discovery is RFC 9728 protected-resource-metadata op https://www.invoiso.com/.well-known/oauth-protected-resource, en de autorisatieserver publiceert zowel een RFC 8414- als een OpenID Connect-discoverydocument. Clients registreren zichzelf via dynamische clientregistratie (RFC 7591), en daarom vragen de stappen hierboven u niets dan een URL. Het registratie-eindpunt staat alleen op het RFC 8414-document; een client die alleen het OpenID Connect-document leest vindt het niet en heeft de vooraf gedefinieerde client-id hieronder nodig.

Kan uw client zich niet zelf registreren en vraagt hij om een client-id, mail dan support@invoiso.com en wij geven u er een. Laat het client secret leeg — de client is publiek en authenticeert met PKCE.

Tokens worden geverifieerd tegen de JWKS van onze eigen instantie en moeten onze issuer dragen plus de scope die uw werkruimte noemt. Een token dat door een andere invoiso-installatie of een andere Clerk-instantie is uitgegeven, wordt geweigerd. Een token van een andere applicatie die bij deze instantie is geregistreerd, is niet van het onze te onderscheiden en wordt geaccepteerd — dat is wat open registratie betekent, en daarom loont het om het toestemmingsscherm, dat de vragende applicatie noemt, te lezen voordat u goedkeurt.

Als er iets misgaat

Mail support@invoiso.com met wat uw client vroeg en wat er terugkwam. Een 401 betekent meestal dat de verbinding opnieuw moet worden goedgekeurd; een 403 die een scope noemt betekent dat de client die niet heeft gevraagd; en een weigering die uw abonnement noemt is de alleen-lezen-drempel hierboven, geen storing.