Alpha publique — tout est gratuit et les quotas mensuels ne sont pas appliqués. Recevez un seul mail au lancement du plan payant.
NBB Annual Accounts MCP

Documentation

Trois 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). 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, 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.

Renvoie. Les comptes dans le même appel : statut "completed" avec le dépôt traité dans result, plus cached: true quand 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.

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 Gratuit Payant
Appels d'outils facturables par mois calendrier 100 2 000
Dépôts uniquement en PDF (lecture LLM) non inclus 50 nouvelles lectures par mois — en préparation, arrive avec le lancement
Requêtes par minute et par clé 30 30
Rafale 10 10

Les quotas repartent de zéro le 1er de chaque mois. Pendant l'alpha les quotas mensuels ne sont pas appliqués — les appels sont comptés, jamais refusés. La limite de débit par clé reste.

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. 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