NBB Annual Accounts MCP

Dokumentation

Drei Tools, ein asynchrones Muster, ein feststehender Satz Fehlercodes.

Verbinden

Endpunkt https://test.nbb-mcp.be/mcp
Transport MCP streamable HTTP (ein Endpunkt, POST + SSE). Nicht der abgelöste SSE-Transport mit zwei Endpunkten.
Authentifizierung Authorization: Bearer nbb_live_… bei jeder Anfrage
Sitzung Zustandsbehaftet: der Server erwartet den üblichen initialize-Handshake.

Anleitungen je Client stehen auf den Einrichtungsseiten. Eine Anfrage ohne Schlüssel erhält 401 mit einem WWW-Authenticate-Header; ein Schlüssel über der Ratenbegrenzung erhält 429 mit Retry-After.

Tools

search_company abrechenbar

Ermittelt aus einem Firmennamen die belgische Unternehmensnummer (ZDU/KBO) oder listet die zu einer Nummer eingetragenen Namen auf.

Parameter Typ Pflicht Beschreibung
query string ja Ein Name, ein Namensteil oder eine Unternehmensnummer in beliebiger Schreibweise (0403.170.701, BE0403170701, 403170701). Tippfehlertolerant und sprachunabhängig; Nummern umgehen die unscharfe Suche.
language string nein nl, fr, de oder en. Ordnet nur die zurückgegebenen Namen; filtert nichts heraus.
limit integer nein Wie viele Unternehmen zurückgegeben werden. Standard 10, Maximum 25.

Gibt zurück. Kandidaten, bester Treffer zuerst: kbo_number, jeder eingetragene Name mit Typ und Sprache, und match_score (1.0 bei einem direkten Nummerntreffer). Dazu warnings[], das ein leeres Ergebnis oder eine fehlgeschlagene Mod-97-Prüfziffer erklärt.

get_annual_accounts asynchron abrechenbar

Holt den Jahresabschluss, den ein Unternehmen bei der NBB eingereicht hat: Bilanz, Ergebnisrechnung, Ergebnisverwendung, Sozialbilanz und Anhang, jede Zeile mit ihrem amtlichen Rubrikcode und einer übersetzten Beschriftung.

Parameter Typ Pflicht Beschreibung
kbo_number string ja Belgische Unternehmensnummer in beliebiger Schreibweise. Nicht der Name — rufen Sie zuerst search_company auf.
year integer nein Das Kalenderjahr, in dem das Geschäftsjahr endet. Weglassen für die jüngste Einreichung.
language string nein Sprache der Beschriftungen: nl, fr, de oder en. Standard nl. Die Zahlen sind in jeder Sprache identisch.
raw boolean nein True gibt die Einreichung genau so zurück, wie die NBB sie liefert (XBRL oder JSON-XBRL, unverarbeitet). Standard false.

Gibt zurück. Meist {operation_id, status: "pending", poll_after_seconds} — fragen Sie danach get_operation ab. Eine Einreichung, die schon im Cache liegt, kommt sofort mit Status "completed" und dem Abschluss in result zurück.

get_operation nicht abrechenbar

Prüft, ob eine asynchrone Anfrage fertig ist, und holt ihr Ergebnis ab.

Parameter Typ Pflicht Beschreibung
operation_id string ja Die von get_annual_accounts zurückgegebene ID. Sie können nur Operationen abfragen, die mit Ihrem eigenen API-Schlüssel erstellt wurden.

Gibt zurück. status pending/processing mit poll_after_seconds, completed mit result, oder failed mit error {code, message}.

Das asynchrone Muster

Eine Einreichung zu holen bedeutet, die Nationalbank aufzurufen, eine Einreichung herunterzuladen und XBRL zu verarbeiten — zu langsam, um einen Tool-Aufruf offen zu halten, und weit zu langsam, wenn die Einreichung ein PDF ist, das ein LLM braucht. Darum gibt get_annual_accounts eine Operation zurück, die Sie abfragen.

  1. Rufen Sie get_annual_accounts auf. Normalerweise erhalten Sie {"operation_id": "…", "status": "pending", "poll_after_seconds": 3}.
  2. Warten Sie poll_after_seconds und rufen Sie dann get_operation mit dieser ID auf. Wiederholen Sie, solange der Status pending oder processing ist.
  3. Halten Sie bei completed (der Abschluss steht in result) oder failed (es gibt ein error-Objekt mit einem Code aus der Tabelle unten).

Zwei Abkürzungen sind eingebaut. Eine Einreichung, die schon im Cache liegt, kommt sofort aus get_annual_accounts mit status: "completed" und cached: true zurück — ohne Abfragen. Eine Einreichung aus dem Cache, deren JSON zu groß ist, um mitgesendet zu werden (über 100 KB, was mit raw: true vorkommt), kommt als Operation mit cached: true zurück, und die erste Abfrage antwortet sofort.

Stellen Sie die Anfrage nicht erneut, während eine Operation läuft. Identische Anfragen werden serverseitig zusammengeführt: erneut fragen gibt dieselbe Operations-ID zurück und verbraucht umsonst einen weiteren abrechenbaren Aufruf.

Operationen gehören zu dem API-Schlüssel, der sie erstellt hat. Die ID eines anderen abzufragen antwortet genau wie eine nicht existierende ID abzufragen. Abgeschlossene Operationen werden 30 Tage nach ihrem Ende aufgeräumt.

Fehlercodes

Eine fehlgeschlagene Operation trägt error.code, und diese Zeichenketten sind stabil — ein Client darf darauf verzweigen.

Code Bedeutung Was zu tun ist
no_accounts_found Die NBB hat für dieses Unternehmen keine angenommene Einreichung, oder keine für das gefragte Jahr. Die Meldung listet die Jahre auf, die es gibt. Versuchen Sie es mit einem der Jahre aus der Meldung, oder sagen Sie dem Nutzer, dass es nichts zu zeigen gibt. Dieselbe Anfrage zu wiederholen hilft nicht.
pdf_fallback_required Die Einreichung gibt es, aber nur als PDF (ältere oder nicht standardisierte Einreichungen), oder in einer Taxonomieversion, die dieser Server noch nicht abbilden kann. Eine PDF-Einreichung zu lesen braucht die LLM-Auslesung des bezahlten Tarifs. Wechseln Sie auf /pricing; ob das rohe PDF verfügbar ist, wird in jedem Fall gemeldet.
nbb_unavailable Der Dienst der Nationalbank war nicht erreichbar oder antwortete 429/5xx, auch nach unseren eigenen Wiederholungen. Vorübergehend. Es in einigen Minuten erneut zu versuchen lohnt sich — das ist der einzige Code, bei dem das stimmt.
nbb_error Die NBB hat geantwortet, aber mit etwas Unbrauchbarem (ein 4xx, das kein fehlendes Format ist). Nicht wiederholen. Melden Sie die Meldung; wiederholt sie sich bei einem Unternehmen, das einen Abschluss haben sollte, ist es ein Fehler auf unserer Seite.
deposit_unreadable Die Einreichung wurde heruntergeladen, konnte aber nicht als XBRL verarbeitet werden. Der Worker hat es schon automatisch erneut versucht. Erreicht es Sie, ist die Einreichung selbst das Problem.
nbb_not_configured Diese Instanz hat keinen NBB-Abonnementschlüssel konfiguriert. Daran kann ein Client nichts ändern; es bedeutet, dass die Installation unvollständig ist.
result_missing Die Operation ist abgeschlossen, aber ihr gespeichertes Ergebnis ist weg (die Aufbewahrungsfrist hat es gelöscht). Rufen Sie get_annual_accounts erneut auf — die Antwort wird neu aufgebaut oder aus dem Einreichungs-Cache geliefert.

Fehler, die keine fehlgeschlagene Operation sind

Falsche Eingaben, ein aufgebrauchtes Kontingent und eine unbekannte Operations-ID kommen als Tool-Fehler (MCP isError: true) mit einer erklärenden Meldung zurück und nicht als Operation, die Sie abfragen können — es läuft nichts, was abgefragt werden könnte.

Situation Antwort
Monatskontingent erreicht Tool-Fehler, der die Grenze nennt und wo man wechseln kann (/pricing). Der abgewiesene Aufruf selbst wird erfasst, aber nicht berechnet.
Nur als PDF vorliegende Einreichung im kostenlosen Tarif Die Operation schlägt mit pdf_fallback_required fehl: eine PDF-Einreichung zu lesen braucht die LLM-Auslesung des bezahlten Tarifs.
Monatliche LLM-Grenze erreicht (bezahlter Tarif) Tool-Fehler, der sagt, dass die Grenze erreicht ist. Früher ausgelesene Einreichungen werden weiter geliefert — Auslesungen aus dem Cache zählen nie mit.
Keine gültige Unternehmensnummer Tool-Fehler, der das Problem nennt und search_company vorschlägt.
Fehlender oder ungültiger API-Schlüssel HTTP 401, bevor MCP die Anfrage sieht.
Zu viele Anfragen HTTP 429 mit Retry-After, bei 30 Anfragen pro Minute (Burst 10) je Schlüssel.

Grenzen

Grenze Kostenlos Bezahlt
Abrechenbare Tool-Aufrufe pro Kalendermonat 10 2 000
Neue PDF-LLM-Auslesungen pro Monat keine — dieser Zweig ist abgeschaltet 50
Anfragen pro Minute je Schlüssel 30 30
Burst 10 10
get_operation Abfragen kostenlos, nur die Ratenbegrenzung gilt kostenlos, nur die Ratenbegrenzung gilt

Kontingente werden am 1. jedes Monats zurückgesetzt.

Das Ergebnis-JSON

Jedes abgeschlossene Ergebnis von get_annual_accounts hat dieselbe Form:

Feld Inhalt
meta Kennungen, Sprache der Einreichung und der Antwort, Modelltyp, Taxonomieversion, data_source, confidence, caveats sowie die Daten des laufenden und des vorherigen Geschäftsjahres.
identification Name, Adresse und Rechtsform wie eingereicht.
statements[] Feste IDs balance_sheet_assets, balance_sheet_liabilities, income_statement, appropriation, social_balance; Zeilen sind {code, label, level, current, previous}.
notes[] Die Anhangabschnitte der Einreichung, mit derselben Zeilenform.
unmapped_facts[] Fakten, die wir keinem Rubrikcode zuordnen konnten. Nie aus Bequemlichkeit leer und nie stillschweigend verworfen — fehlt etwas in den Abschlüssen, steht es hier.

Sprachen

language nimmt nl, fr, de und en an und steht standardmäßig auf nl. Die Beschriftungen stammen aus den Taxonomie-Beschriftungs-Linkbases der Nationalbank selbst, nicht aus einer Übersetzungsmaschine, und entsprechen daher den Formulierungen auf den amtlichen Formularen.

Fehlt eine Beschriftung in der gewünschten Sprache, fällt die Antwort in dieser Reihenfolge zurück: gewünschte Sprache → Sprache, in der die Einreichung erfolgte → nl → fr → en. Die Zahlen ändern sich mit der Sprache nie, und meta.response_language sagt Ihnen, was Sie tatsächlich bekommen haben.

Die Website selbst erscheint in denselben vier Sprachen; die Sprachauswahl steht in der Navigation, und Ihre Wahl wird in einem Cookie behalten.

Datenquellen und Vorbehalte

meta.data_source sagt, wie ein Ergebnis entstanden ist, und das ist das Feld, das man liest, bevor man einer Zahl traut:

data_source Was es bedeutet Verlässlichkeit
xbrl Aus der XBRL-Instanz verarbeitet, die das Unternehmen eingereicht hat. Zahlen und Rubrikcodes sind genau das, was eingereicht wurde. Authentisch
jsonxbrl Aus der JSON-XBRL-Darstellung verarbeitet. Dieselben Daten, andere Serialisierung; die Ergebnisse tragen einen Vorbehalt, weil diese Nutzdatenform in der Praxis seltener gesehen wurde als die XBRL-Form. Authentisch, mit Vorbehalt
pdf_llm Die Einreichung liegt nur als PDF vor und wurde von einem LLM in dieselbe JSON-Form gelesen. Rubrikcodes und Werte werden ausgelesen; das Modell übersetzt nichts. Heuristisch — meta.confidence trägt einen Bilanzprüfwert, und meta.caveats sagt, dass die Zahlen aus einem Dokument gelesen wurden.

Bekannte Vorbehalte