NBB Annual Accounts MCP

Documentatie

Drie tools, één asynchroon patroon, een vaste reeks foutcodes.

Verbinden

Endpoint https://test.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.

Instructies per client staan op de installatiepagina's. 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 asynchroon 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.
raw boolean nee True geeft de neerlegging precies zoals de NBB ze aanlevert (XBRL of JSON-XBRL, onbewerkt). Standaard false.

Geeft terug. Meestal {operation_id, status: "pending", poll_after_seconds} — poll daarna get_operation. Een neerlegging die al in de cache zit, komt onmiddellijk terug met status "completed" en de jaarrekening in result.

get_operation niet aanrekenbaar

Ga na of een asynchrone aanvraag klaar is en haal het resultaat op.

Parameter Type Verplicht Beschrijving
operation_id string ja Het id dat get_annual_accounts teruggaf. U kunt alleen operaties pollen die met uw eigen API-sleutel zijn aangemaakt.

Geeft terug. status pending/processing met poll_after_seconds, completed met result, of failed met error {code, message}.

Het asynchrone patroon

Een neerlegging ophalen betekent de Nationale Bank aanroepen, een neerlegging downloaden en XBRL verwerken — te traag om een tool-aanroep open te houden, en veel te traag wanneer de neerlegging een pdf is die een LLM nodig heeft. Daarom geeft get_annual_accounts een operatie terug die u polt.

  1. Roep get_annual_accounts aan. Normaal krijgt u {"operation_id": "…", "status": "pending", "poll_after_seconds": 3}.
  2. Wacht poll_after_seconds en roep dan get_operation aan met dat id. Herhaal zolang de status pending of processing is.
  3. Stop bij completed (de jaarrekening staat in result) of failed (er is een error-object met een code uit de tabel hieronder).

Er zitten twee kortere wegen in. Een neerlegging die al in de cache zit, komt onmiddellijk terug uit get_annual_accounts met status: "completed" en cached: true — zonder pollen. Een neerlegging uit de cache waarvan de JSON te groot is om mee te sturen (meer dan 100 KB, wat gebeurt met raw: true) komt terug als operatie met cached: true, en de eerste poll antwoordt onmiddellijk.

Vraag niet opnieuw aan terwijl een operatie loopt. Identieke aanvragen worden serverzijdig samengevoegd: opnieuw vragen geeft hetzelfde operation-id en kost nog een aanrekenbare aanroep voor niets.

Operaties horen bij de API-sleutel die ze aanmaakte. Het id van iemand anders pollen antwoordt precies zoals een onbestaand id pollen. Afgeronde operaties worden 30 dagen na hun einde opgeruimd.

Foutcodes

Een mislukte operatie 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. Een pdf-neerlegging lezen vereist de LLM-extractie van het betalende plan. Schakel over op /pricing; of de ruwe pdf beschikbaar is, wordt in elk geval gemeld.
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. De worker heeft het al automatisch opnieuw geprobeerd. Bereikt dit u, 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.
result_missing De operatie is afgerond, maar het bewaarde resultaat is weg (de bewaartermijn heeft het verwijderd). Roep get_annual_accounts opnieuw aan — het antwoord wordt opnieuw opgebouwd of uit de neerleggingscache geleverd.

Fouten die geen mislukte operatie zijn

Verkeerde invoer, een opgebruikt quotum en een onbekend operation-id komen terug als tool-fout (MCP isError: true) met een verklarende boodschap, en niet als een operatie die u kunt pollen — er loopt niets om te pollen.

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, op het gratis plan De operatie mislukt met pdf_fallback_required: een pdf-neerlegging lezen vereist de LLM-extractie van het betalende plan.
Maandelijks LLM-plafond bereikt (betalend plan) Tool-fout die zegt dat het plafond bereikt is. Eerder geëxtraheerde neerleggingen blijven geleverd worden — extracties uit de cache tellen nooit mee.
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 10 2 000
Nieuwe pdf-LLM-extracties per maand geen — die weg staat uit 50
Aanvragen per minuut per sleutel 30 30
Burst 10 10
get_operation polls gratis, alleen de snelheidslimiet gratis, alleen de snelheidslimiet

Quota gaan op de 1ste van elke maand terug op nul.

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 dezelfde vier talen; de taalkiezer staat in de navigatie en uw keuze wordt in een cookie 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
jsonxbrl Verwerkt uit de JSON-XBRL-weergave. Dezelfde gegevens, andere serialisatie; resultaten dragen een voorbehoud omdat deze payloadvorm minder in het wild gezien is dan de XBRL-vorm. Authentiek, met een voorbehoud
pdf_llm De neerlegging bestaat alleen als pdf en is door een LLM in dezelfde JSON-vorm gelezen. Rubriekcodes en waarden worden geëxtraheerd; het model vertaalt niets. Heuristisch — meta.confidence draagt een balanscontrolescore en meta.caveats zegt dat de cijfers uit een document gelezen zijn.

Bekende voorbehouden