Publieke alfa — alles is gratis en de maandquota worden niet afgedwongen. Krijg één mail wanneer het betalende plan start.
NBB Annual Accounts MCP

Documentatie

Drie tools, synchrone aanroepen, een vaste reeks foutcodes.

Verbinden

Endpoint https://nbb-mcp.be/mcp
Transport MCP streamable HTTP (één endpoint, POST + SSE). Niet het afgeschafte SSE-transport met twee endpoints.
Authenticatie Authorization: Bearer nbb_live_… bij elke aanvraag
Sessie Stateful: de server verwacht de gewone initialize-handshake.

De installatiegids per client staat op uw accountpagina, naast uw sleutel. Een aanvraag zonder sleutel krijgt 401 met een WWW-Authenticate-header; een sleutel boven de snelheidslimiet krijgt 429 met Retry-After.

Tools

search_company aanrekenbaar

Zet een bedrijfsnaam om in het Belgische ondernemingsnummer (KBO/BCE), of geef de namen die bij een nummer geregistreerd staan.

Parameter Type Verplicht Beschrijving
query string ja Een naam, een deel van een naam, of een ondernemingsnummer in welke notatie ook (0403.170.701, BE0403170701, 403170701). Tolerant voor typfouten en taalonafhankelijk; nummers slaan het fuzzy zoeken over.
language string nee nl, fr, de of en. Bepaalt alleen de volgorde van de teruggegeven namen; filtert niets weg.
limit integer nee Hoeveel bedrijven teruggegeven worden. Standaard 10, maximaal 25.

Geeft terug. Kandidaten, beste match eerst: kbo_number, elke geregistreerde naam met haar type en taal, en match_score (1.0 bij een rechtstreekse treffer op nummer). Plus warnings[], dat een leeg resultaat of een mislukt mod-97-controlecijfer uitlegt.

get_annual_accounts aanrekenbaar

Haal de jaarrekening op die een bedrijf bij de NBB heeft neergelegd: balans, resultatenrekening, resultaatverwerking, sociale balans en toelichting, elke lijn met haar officiële rubriekcode en een vertaald label.

Parameter Type Verplicht Beschrijving
kbo_number string ja Belgisch ondernemingsnummer in welke notatie ook. Niet de naam — roep eerst search_company aan.
year integer nee Het kalenderjaar waarin het boekjaar eindigt. Laat weg voor de meest recente neerlegging.
language string nee Taal van de labels: nl, fr, de of en. Standaard nl. De cijfers zijn in elke taal identiek.

Geeft terug. De jaarrekening in dezelfde aanroep: status "completed" met de verwerkte neerlegging in result, plus cached: true wanneer ze uit de cache kwam. Een aanvraag die niet bediend kan worden, geeft status "failed" met een vaste error {code, message}.

check_xbrl_availability aanrekenbaar

Som elke jaarrekening op die een bedrijf bij de NBB neerlegde en of ze machineleesbaar (XBRL) is of alleen als pdf bestaat — de jaren die get_annual_accounts kan leveren.

Parameter Type Verplicht Beschrijving
kbo_number string ja Belgisch ondernemingsnummer in welke notatie ook. Niet de naam — roep eerst search_company aan.
year integer nee Beperk de lijst tot één boekjaar. Laat weg om alles te tonen wat het bedrijf ooit neerlegde.

Geeft terug. Neerleggingen, nieuwste eerst, elk met fiscal_year, reference_number, model_type, deposit_type, deposit_date en xbrl_available. xbrl_available true betekent dat get_annual_accounts ze als gestructureerde gegevens levert; false betekent dat de NBB alleen een pdf heeft.

Hoe lang een aanroep duurt

get_annual_accounts antwoordt in de aanroep zelf: een neerlegging ophalen betekent de Nationale Bank aanroepen, de neerlegging downloaden en XBRL verwerken, en dat gebeurt allemaal terwijl uw client wacht.

Een nieuwe neerlegging duurt meestal enkele seconden, af en toe tot een minuut wanneer de Nationale Bank traag is. Wacht op het antwoord in plaats van opnieuw te proberen — opnieuw proberen is een tweede aanrekenbare aanroep voor hetzelfde werk.

Een neerlegging die al eens is opgehaald, komt onmiddellijk terug met status: "completed" en cached: true. Resultaten worden per neerlegging bewaard en verlopen nooit, want een neergelegde jaarrekening verandert niet meer — een correctie is een nieuwe neerlegging met haar eigen referentie, en die pikt de server op.

Foutcodes

Een mislukte aanroep van get_annual_accounts draagt error.code, en die strings staan vast — een client mag erop vertakken.

Code Betekenis Wat te doen
no_accounts_found De NBB heeft voor dit bedrijf geen aanvaarde neerlegging, of geen voor het jaar dat u vroeg. De boodschap somt de jaren op die wel bestaan. Probeer opnieuw met een van de jaren uit de boodschap, of zeg de gebruiker dat er niets te tonen is. Dezelfde aanvraag opnieuw doen helpt niet.
pdf_fallback_required De neerlegging bestaat, maar alleen als pdf (oudere of niet-gestandaardiseerde neerleggingen), of in een taxonomieversie die deze server nog niet kan koppelen. Pdf-neerleggingen met een LLM lezen is in de maak en nog niet beschikbaar. Roep check_xbrl_availability aan om de jaren te vinden die wel machineleesbaar zijn, en zeg de gebruiker dat de neerlegging bestaat maar nog niet gelezen kan worden.
nbb_unavailable De dienst van de Nationale Bank was onbereikbaar of antwoordde 429/5xx, ook na onze eigen nieuwe pogingen. Tijdelijk. Over een paar minuten opnieuw proberen is de moeite — dit is de enige code waarvoor dat geldt.
nbb_error De NBB antwoordde, maar met iets onbruikbaars (een 4xx die geen ontbrekend formaat is). Niet opnieuw proberen. Meld de boodschap; herhaalt ze zich voor een bedrijf dat een jaarrekening hoort te hebben, dan is het een fout aan onze kant.
deposit_unreadable De neerlegging is gedownload, maar kon niet als XBRL verwerkt worden. Dezelfde vraag opnieuw stellen is redelijk; blijft het mislukken, dan is de neerlegging zelf het probleem.
nbb_not_configured Deze instantie heeft geen NBB-abonnementssleutel geconfigureerd. Een client kan hier niets aan doen; het betekent dat de installatie onvolledig is.

Fouten die geen mislukte aanroep zijn

Verkeerde invoer en een opgebruikt quotum komen terug als tool-fout (MCP isError: true) met een verklarende boodschap, en niet als een failed-resultaat — er is geen vaste code om op te vertakken, alleen iets wat het model kan verbeteren of melden.

Situatie Antwoord
Maandquotum bereikt Tool-fout die de limiet noemt en waar u kunt overschakelen (/pricing). De geweigerde aanroep zelf wordt geregistreerd maar niet aangerekend.
Neerlegging die alleen als pdf bestaat De aanroep mislukt met pdf_fallback_required: pdf-neerleggingen met een LLM lezen is in de maak en nog niet beschikbaar. check_xbrl_availability toont welke jaren machineleesbaar zijn.
Geen geldig ondernemingsnummer Tool-fout die het probleem noemt en search_company voorstelt.
Ontbrekende of ongeldige API-sleutel HTTP 401, voor MCP de aanvraag ziet.
Te veel aanvragen HTTP 429 met Retry-After, bij 30 aanvragen per minuut (burst 10) per sleutel.

Limieten

Limiet Gratis Betalend
Aanrekenbare tool-aanroepen per kalendermaand 100 2 000
Neerleggingen die alleen als pdf bestaan (LLM-lezing) niet inbegrepen 50 nieuwe lezingen per maand — in de maak, komt er bij de start
Aanvragen per minuut per sleutel 30 30
Burst 10 10

Quota gaan op de 1ste van elke maand terug op nul. Tijdens de alfa worden de maandquota niet afgedwongen — aanroepen worden geteld, nooit geweigerd. De rate limit per sleutel blijft.

De result-JSON

Elk afgerond resultaat van get_annual_accounts heeft dezelfde vorm:

Veld Inhoud
meta Identificatiegegevens, taal van de neerlegging en van het antwoord, modeltype, taxonomieversie, data_source, confidence, caveats, en de data van het huidige en het vorige boekjaar.
identification Naam, adres en rechtsvorm zoals neergelegd.
statements[] Vaste id''s balance_sheet_assets, balance_sheet_liabilities, income_statement, appropriation, social_balance; lijnen zijn {code, label, level, current, previous}.
notes[] De toelichtingssecties van de neerlegging, met dezelfde lijnvorm.
unmapped_facts[] Feiten die we niet aan een rubriekcode konden koppelen. Nooit leeg uit gemakzucht en nooit stilzwijgend weggelaten — ontbreekt er iets in de staten, dan staat het hier.

Talen

language aanvaardt nl, fr, de en en, en staat standaard op nl. De labels komen uit de taxonomielabellinkbases van de Nationale Bank zelf, niet uit een vertaalmachine, zodat ze overeenkomen met de woorden op de officiële formulieren.

Ontbreekt een label in de gevraagde taal, dan valt het antwoord terug in deze orde: gevraagde taal → de taal waarin de neerlegging is ingediend → nl → fr → en. De cijfers veranderen nooit met de taal, en meta.response_language zegt wat u werkelijk gekregen hebt.

De website zelf verschijnt in het Nederlands, Frans en Engels. Hij volgt de taalvoorkeur van uw browser; de taalkiezer in de navigatie overschrijft die voor de pagina waar u op staat, en van die keuze wordt niets bewaard.

Gegevensbronnen en voorbehouden

meta.data_source zegt hoe een resultaat tot stand kwam, en dat is het veld dat u leest voor u een getal vertrouwt:

data_source Wat het betekent Betrouwbaarheid
xbrl Verwerkt uit de XBRL-instantie die het bedrijf neerlegde. Cijfers en rubriekcodes zijn precies wat er neergelegd is. Authentiek
pdf_llm Voorbehouden voor neerleggingen die door een LLM uit een pdf in dezelfde JSON-vorm gelezen zijn. Die functie is in de maak: geen enkel resultaat draagt deze waarde vandaag, en een neerlegging die alleen als pdf bestaat, mislukt met <code>pdf_fallback_required</code>. Heuristisch — meta.confidence zal een balanscontrolescore dragen en meta.caveats zal zeggen dat de cijfers uit een document gelezen zijn.

Bekende voorbehouden