NBB Annual Accounts MCP

Documentation

Trois outils, un schéma asynchrone, un jeu stable de codes d'erreur.

Se connecter

Point d'entrée https://test.nbb-mcp.be/mcp
Transport MCP streamable HTTP (un seul point d'entrée, POST + SSE). Pas l'ancien transport SSE à deux points d'entrée.
Authentification Authorization: Bearer nbb_live_… à chaque requête
Session À état : le serveur attend la poignée de main initialize habituelle.

Les instructions client par client sont sur les pages d'installation. Une requête sans clé reçoit 401 avec un en-tête WWW-Authenticate ; une clé au-delà 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 une correspondance directe par numéro). Plus warnings[], qui explique un résultat vide ou un chiffre de contrôle mod-97 incorrect.

get_annual_accounts asynchrone facturable

Récupère les comptes annuels qu'une entreprise a déposés auprès de 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 civile où se termine l'exercice comptable. À omettre 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 toutes les langues.
raw boolean non True renvoie le dépôt exactement tel que la BNB le livre (XBRL ou JSON-XBRL, non analysé). Par défaut false.

Renvoie. En général {operation_id, status: "pending", poll_after_seconds} — interrogez ensuite get_operation. Un dépôt déjà en cache revient immédiatement avec le statut "completed" et les comptes dans result.

get_operation non facturable

Vérifie si une requête asynchrone est terminée et récupère son résultat.

Paramètre Type Obligatoire Description
operation_id string oui L'identifiant renvoyé par get_annual_accounts. Vous ne pouvez interroger que les opérations créées avec votre propre clé d'API.

Renvoie. status pending/processing avec poll_after_seconds, completed avec result, ou failed avec error {code, message}.

Le schéma asynchrone

Récupérer un dépôt veut dire appeler la Banque nationale, télécharger un dépôt et analyser du XBRL — trop lent pour garder un appel d'outil ouvert, et bien trop lent quand le dépôt est un PDF qui demande un LLM. C'est pourquoi get_annual_accounts renvoie une opération que vous interrogez.

  1. Appelez get_annual_accounts. Normalement vous recevez {"operation_id": "…", "status": "pending", "poll_after_seconds": 3}.
  2. Attendez poll_after_seconds, puis appelez get_operation avec cet identifiant. Répétez tant que le statut est pending ou processing.
  3. Arrêtez-vous à completed (les comptes sont dans result) ou failed (il y a un objet error avec un code du tableau ci-dessous).

Deux raccourcis sont intégrés. Un dépôt déjà en cache revient immédiatement de get_annual_accounts avec status: "completed" et cached: true — sans interrogation. Un dépôt en cache dont le JSON est trop gros pour être inclus (plus de 100 Ko, ce qui arrive avec raw: true) revient comme opération avec cached: true, et la première interrogation répond instantanément.

Ne relancez pas la requête pendant qu'une opération tourne. Les requêtes identiques sont dédupliquées côté serveur : redemander renvoie le même identifiant d'opération et dépense un appel facturable pour rien.

Les opérations appartiennent à la clé d'API qui les a créées. Interroger l'identifiant de quelqu'un d'autre répond exactement comme interroger un identifiant inexistant. Les opérations terminées sont nettoyées 30 jours après leur fin.

Codes d'erreur

Une opération en échec porte error.code, et ces chaînes sont stables — un client peut s'y brancher.

Code Signification Que faire
no_accounts_found La BNB n'a pas de dépôt accepté pour cette entreprise, ou aucun pour l'année demandée. Le message énumère 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 requête n'aidera pas.
pdf_fallback_required Le dépôt existe, mais uniquement en PDF (dépôts anciens ou non normalisés), ou dans une version de taxonomie que ce serveur ne sait pas encore cartographier. Lire un dépôt PDF demande l'extraction par LLM du plan payant. Passez au plan payant sur /pricing ; la disponibilité du PDF brut est signalée dans tous les cas.
nbb_unavailable Le service de la Banque nationale était injoignable ou a répondu 429/5xx, même après nos propres nouvelles 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 analysé comme du XBRL. Le worker a déjà réessayé automatiquement. Si cela vous parvient, c'est le dépôt lui-même qui pose problème.
nbb_not_configured Cette instance n'a aucune clé d'abonnement BNB configurée. Un client n'y peut rien ; cela veut dire que le déploiement est incomplet.
result_missing L'opération est terminée mais son résultat stocké a disparu (la durée de conservation l'a supprimé). Rappelez get_annual_accounts — la réponse sera reconstruite ou servie depuis le cache des dépôts.

Les erreurs qui ne sont pas des échecs d'opération

Une entrée invalide, un quota épuisé et un identifiant d'opération inconnu reviennent comme erreur d'outil (MCP isError: true) avec un message explicatif, et non comme une opération à interroger — il n'y a rien qui tourne.

Situation Réponse
Quota mensuel atteint Erreur d'outil nommant la limite et l'endroit où passer au plan payant (/pricing). L'appel refusé est enregistré mais pas facturé.
Dépôt uniquement en PDF sur le plan gratuit L'opération échoue avec pdf_fallback_required : lire un dépôt PDF demande l'extraction par LLM du plan payant.
Plafond LLM mensuel atteint (plan payant) Erreur d'outil indiquant que le plafond est atteint. Les dépôts déjà extraits continuent d'être servis — les extractions en cache ne comptent jamais.
Numéro d'entreprise invalide Erreur d'outil nommant le problème et suggérant search_company.
Clé d'API absente 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'outil facturables par mois civil 10 2 000
Nouvelles extractions PDF-LLM par mois aucune — cette voie est désactivée 50
Requêtes par minute et par clé 30 30
Rafale 10 10
get_operation interrogations gratuit, seule la limite de débit s'applique gratuit, seule la limite de débit s'applique

Les quotas sont remis à zéro le 1er de chaque mois.

Le JSON de résultat

Tout résultat terminé 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, avec la même forme de ligne.
unmapped_facts[] Les faits que nous n'avons pas pu rattacher à un code de rubrique. Jamais vide par facilité et jamais écarté en silence — s'il manque quelque chose dans les états, c'est ici.

Langues

language accepte nl, fr, de et en, et vaut nl par défaut. Les libellés proviennent des linkbases de libellés de taxonomie de la Banque nationale elle-même, pas d'un moteur de traduction : ils 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 → langue dans laquelle le dépôt a été introduit → 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 lui-même est publié dans les mêmes quatre langues ; le sélecteur est dans la navigation et votre choix est retenu dans un cookie.

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 cela veut dire Confiance
xbrl Analysé depuis l'instance XBRL déposée par l'entreprise. Les chiffres et les codes de rubrique sont exactement ce qui a été déposé. Authentique
jsonxbrl Analysé depuis la représentation JSON-XBRL. Mêmes données, sérialisation différente ; les résultats portent une réserve parce que cette forme de charge utile a été moins vue en pratique que la forme XBRL. Authentique, avec une réserve
pdf_llm Le dépôt n'existe qu'en PDF et a été lu par un LLM dans la même forme JSON. Les codes de rubrique et les valeurs sont extraits ; le modèle ne traduit rien. Heuristique — meta.confidence porte un score de contrôle d'équilibre et meta.caveats précise que les chiffres ont été lus dans un document.

Réserves connues