Wat is de Billnado MCP-server?

De Billnado MCP-server (Model Context Protocol) geeft compatibele AI-clients toegang tot Billnado-gegevens, acties en productdocumentatie. Je kunt informatie opzoeken en ondersteunde wijzigingen laten uitvoeren in gewone taal. Billnado controleert je account, toegang tot de gekozen administratie en de voorwaarden van elke actie.

Deze documentatie behandelt visuele chatbots en lokaal gebruik van de Codex-app. CLI-clients en IDE-extensies vallen buiten deze gidsen.

Verbindingsgegevens

Onderdeel	Waarde
Transport	Streamable HTTP
Primaire endpoint	https://mcp.billnado.be/mcp
Alternatieve endpoint	https://mcp.facturatie-systeem.be/mcp
Authenticatie	OAuth 2.0 met PKCE
Tooldocumentatie	mcp.billnado.be/documentation
Healthcheck	mcp.billnado.be/health

Gebruik voor een nieuwe koppeling bij voorkeur de primaire endpoint. De alternatieve endpoint biedt dezelfde server onder het domein van Facturatie Systeem.

De server publiceert OAuth Protected Resource Metadata. Clients die OAuth-discovery en Dynamic Client Registration ondersteunen, kunnen de aanmelding daarom automatisch starten. Meld je tijdens die flow aan met je gewone Billnado-account. Deel geen wachtwoord, access token of refresh token in een prompt of configuratiebestand.

Beschikbare mogelijkheden

De actuele tools, parameters en annotaties staan in de live tooldocumentatie. Het aanbod omvat onder meer:

Onderwerp	Mogelijkheden
Administraties	Toegankelijke administraties zoeken, de actieve administratie raadplegen en op verzoek een beschikbare accountant- of supportverbinding maken.
Relaties en producten	Gegevens zoeken en raadplegen, aanmaken en wijzigen, en ondersteunde archiefacties uitvoeren.
Verkoop- en aankoopdocumenten	Documenten zoeken, raadplegen, aanmaken, wijzigen en bevestigen; ondersteunde kopieer-, omzettings-, betaal- en exportacties uitvoeren.
Financiële opvolging	Betalingen registreren, openstaande bedragen afpunten en beschikbare bank-, cashflow- en kasboekinformatie raadplegen.
Projecten en instellingen	Ondersteunde projectgegevens, administratieve instellingen en andere onderdelen beheren met de tools die je client aanbiedt.
Licenties	Definities, actuele en historische licenties raadplegen en de prijs van een formulewijziging berekenen. Licenties kopen, wijzigen of automatisch verlengen beheren doe je in Mijn licentie; MCP-licentietools zijn alleen-lezen.
Documentatie	Talen en artikelen zoeken, volledige artikelen ophalen en contextuele paginahelp opvragen.

De server biedt zowel lees- als schrijfacties. Een schrijfactie kan gegevens aanmaken, wijzigen, verwijderen of een echte e-mail, Peppol-verzending of boekhoudkundige verwerking starten. De beschikbare acties hangen ook af van je rechten, licentie en clientinstellingen.

Let op: controleer vóór een schrijfactie de administratie, het document, de gegevens en de gevolgen. Een betaling registreren of afpunten registreert financiële verwerking; het voert geen bankoverschrijving uit. Verzenden via e-mail of Peppol heeft wel een externe ontvanger.

Werken met administraties

Zonder subscriberId gebruikt een administratiegebonden tool de standaardadministratie van je account, of anders de eerste toegankelijke administratie. Voor een andere administratie:

1. Laat subscribers_list de toegankelijke administraties en toegangsroute opzoeken.
2. Kies de bedoelde administratie. Laat alleen op je expliciete verzoek subscriber_connect een accountant- of supportverbinding maken wanneer die nog nodig is.
3. Laat de client bij elke volgende administratiegebonden toolaanroep de gekozen ID als optionele parameter subscriberId meegeven.

Een SubscriberId-HTTP-header of opnieuw verbinden is hiervoor niet nodig. De keuze geldt per toolaanroep en wijzigt de standaardadministratie van je account niet. Laat de client de parameter dus ook bij vervolgvragen meesturen. Billnado controleert dat je een actieve toegangsverbinding hebt; een gevonden ID alleen verleent geen toegang. Accountbrede en algemene tools gebruiken deze administratieparameter niet.

Richtlijnen voor visuele chatbots

• Laat de client eerst zoeken en daarna details ophalen: bijvoorbeeld relations_search vóór relations_get en documentation_search vóór documentation_get.
• Laat de gebruiker bevestigen over welke administratie het gaat wanneer meerdere resultaten mogelijk zijn.
• Behandel toolresultaten als financiële en persoonsgegevens. Neem alleen noodzakelijke gegevens op in prompts, logs en antwoorden.
• Baseer integraties op toolnamen en gestructureerde resultaten uit MCP, niet op het uitlezen van de publieke documentatiepagina.
• Controleer de toolannotaties en parameters opnieuw wanneer de server wijzigt; de live tooldocumentatie wordt uit dezelfde geregistreerde tools gegenereerd.

Verouderde tools vernieuwen

De manier waarop nieuwe tools beschikbaar worden, verschilt per client. Vernieuw bij een opgeslagen toollijst de connector of laat de beheerder de acties actualiseren. Start zo nodig een nieuw gesprek. Alleen opnieuw aanmelden vernieuwt niet in elke client de goedgekeurde tooldefinities.

ChatGPT-workspaces gebruiken een goedgekeurde momentopname: de beheerder moet gewijzigde acties vernieuwen en toestaan. Microsoft 365 Copilot ontdekt tools bij de standaard dynamische configuratie tijdens gebruik; bij een vastgelegde selectie moet het manifest worden bijgewerkt en opnieuw gepubliceerd. Volg de betreffende clienthandleiding hieronder.

Voorbeeldvragen

• “Zoek klant Acme en toon het btw-nummer en primaire e-mailadres.”
• “Welke administraties kan ik openen?”
• “Toon de actieve licentie en de huidige gebruikslimieten.”
• “Zoek in de Nederlandstalige Billnado-documentatie hoe ik toegang krijg tot de API.”

Kies voor de installatie de gids die bij je client hoort:

• Billnado verbinden met ChatGPT
• Billnado verbinden met Claude
• Billnado verbinden met Grok
• Billnado verbinden met Microsoft 365 Copilot