Documentation

Huit outils, des appels synchrones, une série stable de codes d'erreur.

Se connecter

Point d'accès	`https://nbb-mcp.be/mcp`
Transport	MCP streamable HTTP (un seul point d'accès, POST + SSE). Pas le transport SSE à deux points d'accès, déprécié.
Authentification	`Authorization: Bearer nbb_live_…` sur chaque requête
Session	Stateful : le serveur attend la poignée de main `initialize` habituelle.

Le guide d'installation par client est sur votre page de compte, à côté de votre clé. Une requête sans clé reçoit 401 avec un en-tête WWW-Authenticate ; une clé au-dessus de la limite de débit reçoit 429 avec Retry-After.

Outils

`search_company` facturable

Convertit un nom d'entreprise en son numéro d'entreprise belge (BCE/KBO), ou liste les noms enregistrés pour un numéro.

Paramètre	Type	Obligatoire	Description
`query`	string	oui	Un nom, une partie de nom, ou un numéro d'entreprise dans n'importe quelle notation (0403.170.701, BE0403170701, 403170701). Un numéro d'unité d'établissement (2.xxx.xxx.xxx) renvoie l'entreprise à laquelle elle appartient. Tolérant aux fautes de frappe et indépendant de la langue ; les numéros contournent la recherche floue.
`language`	string	non	nl, fr, de ou en. Ordonne seulement les noms renvoyés ; ne filtre rien.
`limit`	integer	non	Combien d'entreprises renvoyer. Par défaut 10, maximum 25.

Renvoie. Les candidats, meilleure correspondance d'abord : kbo_number, chaque nom enregistré avec son type et sa langue (un nom d'une de ses unités d'établissement porte l'establishment_number de cette unité), et match_score (1.0 pour un numéro trouvé directement). Plus warnings[], qui explique un résultat vide ou un chiffre de contrôle mod-97 erroné.

`get_annual_accounts` facturable

Récupère les comptes annuels qu'une entreprise a déposés à la BNB : bilan, compte de résultats, affectation du résultat, bilan social et annexes, chaque ligne avec son code de rubrique officiel et un libellé traduit.

Paramètre	Type	Obligatoire	Description
`kbo_number`	string	oui	Numéro d'entreprise belge dans n'importe quelle notation. Pas le nom — appelez d'abord search_company.
`year`	integer	non	L'année calendrier où se termine l'exercice comptable. Omettez pour le dépôt le plus récent.
`language`	string	non	Langue des libellés : nl, fr, de ou en. Par défaut nl. Les chiffres sont identiques dans chaque langue.
`detail`	string	non	Quantité renvoyée : kpis pour les chiffres clés et ratios seulement (assez pour comparer des entreprises), statements (par défaut) pour chaque ligne des états et annexes, full pour y ajouter unmapped_facts.

Renvoie. Les comptes dans le même appel : statut "completed" avec le dépôt analysé dans result (ou, avec detail kpis, les chiffres clés, ratios et signaux dans kpis), plus cached: true s'il vient du cache. Une demande impossible à servir renvoie le statut "failed" avec une erreur stable {code, message}.

`check_xbrl_availability` facturable

Liste chaque compte annuel qu'une entreprise a déposé à la BNB et si chacun est lisible par machine (XBRL) ou n'existe qu'en PDF — les années que get_annual_accounts peut servir.

Paramètre	Type	Obligatoire	Description
`kbo_number`	string	oui	Numéro d'entreprise belge dans n'importe quelle notation. Pas le nom — appelez d'abord search_company.
`year`	integer	non	Restreint la liste à un seul exercice. Omettez pour tout ce que l'entreprise a jamais déposé.

Renvoie. Les dépôts, les plus récents d'abord, chacun avec fiscal_year, reference_number, model_type, deposit_type, deposit_date et xbrl_available. xbrl_available true signifie que get_annual_accounts le sert en données structurées ; false que la BNB n'a qu'un PDF.

`get_company_activities` facturable

Liste chaque activité NACE qu'une entreprise a enregistrée au niveau de l'entreprise : le code, la version de nomenclature, la classification et un libellé lisible.

Paramètre	Type	Obligatoire	Description
`kbo_number`	string	oui	Numéro d'entreprise belge dans n'importe quelle notation. Pas le nom — appelez d'abord search_company.
`language`	string	non	Langue du libellé : nl, fr, de ou en. Par défaut nl. Les quatre sont essayées ; un libellé manquant retombe sur le néerlandais.

Renvoie. Chaque activité enregistrée : code, version de nomenclature (2003, 2008 ou 2025), classification (activité principale, secondaire ou auxiliaire) et un libellé. Les activités enregistrées sur une unité d'établissement n'y figurent pas, seulement celles au niveau de l'entreprise. Plus warnings[], qui explique un résultat vide ou un repli de langue.

`get_registered_office` facturable

Récupère l'adresse du siège social d'une entreprise sous forme de champs structurés.

Paramètre	Type	Obligatoire	Description
`kbo_number`	string	oui	Numéro d'entreprise belge dans n'importe quelle notation. Pas le nom — appelez d'abord search_company.
`language`	string	non	nl, fr, de ou en. Par défaut nl. Seuls le néerlandais et le français existent dans les données sources : de et en reçoivent une réponse en néerlandais, et warnings le signale.

Renvoie. Rue, numéro, boîte, code postal, commune, pays et informations complémentaires. Le pays est null pour les adresses belges. Un siège radié est quand même renvoyé, signalé dans warnings[].

`list_establishments` facturable

Liste les unités d'établissement qu'une entreprise exploite actuellement, chacune avec son numéro d'unité d'établissement, sa date de début et son adresse structurée.

Paramètre	Type	Obligatoire	Description
`kbo_number`	string	oui	Numéro d'entreprise belge dans n'importe quelle notation. Pas le nom — appelez d'abord search_company.
`language`	string	non	nl, fr, de ou en. Par défaut nl. Seuls le néerlandais et le français existent dans les données sources : de et en reçoivent une réponse en néerlandais, et warnings le signale.

Renvoie. Chaque unité d'établissement actuellement en activité, avec son numéro d'unité d'établissement, sa date de début et son adresse structurée. Les unités d'établissement dont l'adresse a été radiée sont exclues. Plus warnings[], qui explique un résultat vide ou un repli de langue.

`list_nace_codes` non facturable

Parcourt la nomenclature d'activités NACEBEL niveau par niveau, pour trouver le code qui décrit une activité comme « boulangerie ». Gratuit : le seul outil qui ne compte pas dans votre quota.

Paramètre	Type	Obligatoire	Description
`nace_code`	string	non	Le code dont il faut lister les codes enfants, uniquement des chiffres et sans points, par exemple 47 ou 4711. Omettez-le pour partir des divisions au sommet de la nomenclature.
`nace_version`	string	non	Quelle nomenclature parcourir : 2025 (par défaut), ou 2008 ou 2003 pour les plus anciennes sous lesquelles une entreprise peut encore être classée.
`language`	string	non	nl ou fr, par défaut nl. La BCE ne publie les libellés NACE que dans ces deux langues ; de et en reçoivent une réponse en néerlandais, et warnings le signale.

Renvoie. nace_version, parent_code (le code exploré, absent au sommet), level (ce que contient codes[], soit division, group, class, subclass ou detail) et codes[] avec code, level et description. Plus warnings[], qui explique un repli ou un résultat vide.

`find_companies_by_activity` facturable

Cherche des entreprises par code d'activité NACE, code postal ou commune — l'inverse des outils par entreprise. Au moins un de nace_code, zipcode ou municipality est obligatoire ; plusieurs donnés ensemble se combinent tous, et une entreprise correspond dès qu'une de ses adresses (siège social ou une unité d'établissement) se trouve dans la zone. Seules les entreprises actuellement actives dans le registre reviennent.

Paramètre	Type	Obligatoire	Description
`nace_code`	string	non	Code d'activité NACEBEL, uniquement des chiffres et sans points, par exemple 4711, issu de list_nace_codes. Facultatif à lui seul, mais au moins un de nace_code, zipcode ou municipality doit être donné.
`nace_version`	string	non	De quelle nomenclature vient le code : 2025 (par défaut), 2008 ou 2003.
`zipcode`	string	non	Code postal belge, quatre chiffres. Facultatif à lui seul, mais au moins un de nace_code, zipcode ou municipality doit être donné.
`municipality`	string	non	Nom de commune en néerlandais ou en français (Gent, Gand), ou un des quelques noms anglais (Ghent, Antwerp, Brussels, Ostend, Mechlin, Tournai) ; résolu vers les codes postaux qu'elle couvre. Facultatif à lui seul, mais au moins un de nace_code, zipcode ou municipality doit être donné.
`activity_role`	string	non	main pour ne renvoyer que les entreprises dont nace_code est une activité principale, any (par défaut) pour inclure les activités secondaires et auxiliaires.
`entity_type`	string	non	legal pour les sociétés et autres personnes morales, natural pour les personnes physiques, any (par défaut).
`location_match`	string	non	Quelle adresse doit se trouver dans le lieu recherché : seat (siège), establishment (une unité d'établissement) ou any (par défaut).
`page`	integer	non	Page à renvoyer, en comptant à partir de 1. Par défaut 1.
`page_size`	integer	non	Entreprises par page. 10 par défaut, 100 au maximum.
`language`	string	non	nl, fr, de ou en. Détermine seulement quel nom enregistré est affiché ; n'a aucune influence sur les entreprises trouvées.

Renvoie. filters (reprenant nace_code, nace_version, zipcodes[] — les codes postaux réellement recherchés, c'est ainsi qu'un nom de commune est renvoyé — municipality, activity_role, entity_type et location_match), page, page_size, has_more et companies[] : kbo_number, name, entity_type, legal_form, start_date, main_activities[], matched_activity_role, match_source (enterprise ou establishment), seat_zipcode et matched_zipcode. Pas de total : compter chaque résultat coûte un second passage et n'apprend rien d'utile à qui lit une page. Plus warnings[].

Combien de temps prend un appel

get_annual_accounts répond dans l'appel lui-même : récupérer un dépôt signifie appeler la Banque nationale, télécharger le dépôt et traiter le XBRL, et tout cela se passe pendant que votre client attend.

Un nouveau dépôt prend en général quelques secondes, parfois jusqu'à une minute quand la Banque nationale est lente. Attendez la réponse au lieu de réessayer — réessayer est un deuxième appel facturable pour le même travail.

Un dépôt déjà récupéré revient instantanément avec status: "completed" et cached: true. Les résultats sont gardés par dépôt et n'expirent jamais, car un compte annuel déposé est immuable — une correction est un nouveau dépôt avec sa propre référence, et c'est elle que le serveur reprend.

Codes d'erreur

Un appel get_annual_accounts échoué porte error.code, et ces chaînes sont stables — un client peut s'y brancher.

Code	Signification	Quoi faire
`no_accounts_found`	La BNB n'a aucun dépôt accepté pour cette entreprise, ou aucun pour l'année demandée. Le message liste les années qui existent.	Réessayez avec une des années du message, ou dites à l'utilisateur qu'il n'y a rien à montrer. Refaire la même demande n'aidera pas.
`pdf_fallback_required`	Le dépôt existe, mais uniquement en PDF (dépôts plus anciens ou non standardisés), ou dans une version de taxonomie que ce serveur ne couvre pas encore.	La lecture des dépôts PDF par un LLM est en préparation et pas encore disponible. Appelez check_xbrl_availability pour trouver les années lisibles par machine, et dites à l'utilisateur que le dépôt existe mais ne peut pas encore être lu.
`nbb_unavailable`	Le service de la Banque nationale était injoignable ou a répondu 429/5xx, même après nos propres tentatives.	Passager. Réessayer dans quelques minutes en vaut la peine — c'est le seul code pour lequel c'est vrai.
`nbb_error`	La BNB a répondu, mais avec quelque chose d'inutilisable (un 4xx qui n'est pas un format manquant).	Ne réessayez pas. Signalez le message ; s'il se répète pour une entreprise qui devrait avoir des comptes, c'est un bug de notre côté.
`deposit_unreadable`	Le dépôt a été téléchargé mais n'a pas pu être traité comme XBRL.	Reposer la même question est raisonnable ; si ça continue d'échouer, le dépôt lui-même est le problème.
`nbb_not_configured`	Cette instance n'a pas de clé d'abonnement BNB configurée.	Un client ne peut rien y faire ; cela signifie que le déploiement est incomplet.

Les erreurs qui ne sont pas des appels échoués

Une mauvaise entrée et un quota épuisé reviennent comme erreur d'outil (MCP isError: true) avec un message explicatif, pas comme un résultat failed — il n'y a pas de code stable sur lequel se brancher, seulement quelque chose que le modèle peut corriger ou signaler.

Situation	Réponse
Quota mensuel atteint	Erreur d'outil nommant la limite et où passer au plan supérieur (`/pricing`). L'appel refusé est enregistré mais pas facturé.
Dépôt disponible uniquement en PDF	L'appel échoue avec `pdf_fallback_required` : la lecture des dépôts PDF par un LLM est en préparation et pas encore disponible. `check_xbrl_availability` montre quelles années sont lisibles par machine.
Pas un numéro d'entreprise valide	Erreur d'outil nommant le problème et suggérant `search_company`.
Clé API manquante ou invalide	HTTP `401`, avant que MCP ne voie la requête.
Trop de requêtes	HTTP `429` avec `Retry-After`, à 30 requêtes par minute (rafale 10) par clé.

Limites

Limite	Valeur
Requêtes par minute et par clé	30
Rafale	10

Pendant l'alpha aucun quota mensuel n'est en vigueur : les appels sont comptés, jamais refusés. La limite de débit par clé ci-dessus reste, parce qu'elle protège la source des données et non le chiffre d'affaires. Les quotas qui s'appliqueront au lancement ne sont pas encore décidés.

Le JSON du résultat

Chaque résultat abouti de get_annual_accounts a la même forme :

Champ	Contenu
`meta`	Identifiants, langue du dépôt et de la réponse, type de modèle, version de taxonomie, `data_source`, `confidence`, `caveats`, et les dates de l'exercice courant et du précédent.
`identification`	Nom, adresse et forme juridique tels que déposés.
`statements[]`	Identifiants stables `balance_sheet_assets`, `balance_sheet_liabilities`, `income_statement`, `appropriation`, `social_balance` ; les lignes sont `{code, label, level, current, previous}`.
`notes[]`	Les sections d'annexes du dépôt, même forme de ligne.
`unmapped_facts[]`	Les faits que nous n'avons pas pu rattacher à un code de rubrique, renvoyés avec detail full (le niveau par défaut, statements, ne fait que les compter dans meta.unmapped_fact_count). Jamais vide par paresse et jamais supprimé en silence — si quelque chose manque dans les états, c'est ici.

Langues

language accepte nl, fr, de et en, avec nl par défaut. Les libellés viennent des linkbases de libellés de la taxonomie de la Banque nationale elle-même, pas d'un moteur de traduction, et correspondent donc aux termes des formulaires officiels.

Si un libellé manque dans la langue demandée, la réponse retombe dans cet ordre : langue demandée → la langue du dépôt → nl → fr → en. Les chiffres ne changent jamais avec la langue, et meta.response_language vous dit ce que vous avez réellement reçu.

Le site web lui-même est publié en néerlandais, français et anglais. Il suit la préférence de langue de votre navigateur ; le sélecteur dans la navigation la remplace pour la page où vous êtes, et rien de ce choix n'est conservé.

Sources des données et réserves

meta.data_source dit comment un résultat a été produit, et c'est le champ à lire avant de faire confiance à un chiffre :

`data_source`	Ce que ça signifie	Fiabilité
`xbrl`	Traité depuis l'instance XBRL que l'entreprise a déposée. Les chiffres et les codes de rubriques sont exactement ce qui a été déposé.	Authentique
`pdf_llm`	Réservé aux dépôts lus depuis un PDF par un LLM vers la même forme JSON. Cette fonction est en préparation : aucun résultat ne porte cette valeur aujourd'hui, et un dépôt uniquement en PDF échoue avec <code>pdf_fallback_required</code>.	Heuristique — `meta.confidence` portera un score de contrôle du bilan et `meta.caveats` dira que les chiffres ont été lus depuis un document.

Réserves connues

Seuls les dépôts acceptés par la Banque nationale sont servis. Un dépôt corrigé plus tard mène à la correction, pas à l'original.
La recherche par nom utilise le fichier de dénominations des données ouvertes BCE/KBO, rafraîchi chaque mois. Une entreprise créée ces dernières semaines peut être trouvable par numéro avant de l'être par nom.
Plusieurs entreprises peuvent partager un nom. search_company renvoie des candidats avec un score de correspondance et attend de l'appelant qu'il tranche plutôt que de deviner.
Les dépôts plus anciens utilisent des générations de taxonomie antérieures. Là où une génération n'est pas encore couverte, la réponse le dit (pdf_fallback_required) au lieu de renvoyer des chiffres partiels.
Ce service n'est pas affilié à la Banque nationale de Belgique et n'ajoute aucune interprétation : ce qui est déposé est ce que vous recevez, y compris les erreurs du déposant.