MCP-Server

Einführung

Das Model Context Protocol ist ein offener Standard dafür, wie ein KI-Agent externe Werkzeuge und Daten erreicht. Statt eine Schnittstelle zu programmieren, tragen Sie den Server einmal in die Konfiguration des Agenten ein. Von da an weiß das Modell, welche Werkzeuge es gibt, und ruft sie selbst auf, wenn das Gespräch sie braucht.

Unser Server stellt dieselben Daten bereit wie die REST-API: Bekanntmachungen, Firmenprofile, Bilanzzahlen, Statistik und die Watchlist. Der Unterschied liegt in der Aufbereitung. Die Werkzeugbeschreibungen sind so geschrieben, dass ein Modell versteht, wann eine Insolvenzprüfung sinnvoll ist, welche Angaben es erfragen muss und wo die Grenzen der Daten liegen.

Die Adresse lautet https://insolvenztracker.de/api/mcp. Sie nutzt dieselben Schlüssel wie die REST-API. Wer beides parallel betreibt, sieht in beiden Welten dieselbe Watchlist.

Zugang

Der Weg ist derselbe wie bei der REST-API: Schlüssel vergeben wir von Hand. Nutzen Sie das Kontaktformular oder schreiben Sie an [email protected] und sagen Sie kurz, welchen Agenten Sie anbinden wollen und was er tun soll.

Wer schon einen API-Schlüssel hat, braucht keinen zweiten: Derselbe Schlüssel öffnet den MCP-Server. Teams, die den Server mehreren Personen geben wollen, erhalten auf Wunsch mehrere Schlüssel auf einem Konto, damit nachvollziehbar bleibt, wer was geprüft hat.

Verbindung und Transport

Der Server spricht MCP über Streamable HTTP, den Transport, den aktuelle Clients standardmäßig nutzen. Ein lokaler Prozess ist nicht nötig, es gibt nichts zu installieren.

Die Authentifizierung läuft über denselben Header wie bei der REST-API: X-API-Key, alternativ Authorization: Bearer. Clients, die nur stdio sprechen, erreichen den Server über mcp-remote als Brücke, siehe die Konfiguration für Claude Desktop weiter unten.

Client und Server handeln die Protokollversion beim Verbindungsaufbau aus. Wir unterstützen die aktuelle Revision und die davor, damit ein Client-Update nie zum harten Bruch führt.

curl https://insolvenztracker.de/api/mcp/health

Einrichtung

In Claude Code genügt ein Befehl. Der Schlüssel sollte aus einer Umgebungsvariable kommen, nicht aus der Zwischenablage.

claude mcp add --transport http insolvency \
  https://insolvenztracker.de/api/mcp \
  --header "X-API-Key: $INSOLVENCY_API_KEY"

Claude Desktop

Claude Desktop liest seine Serverliste aus claude_desktop_config.json. Der Eintrag überbrückt per mcp-remote zum HTTP-Transport.

{
  "mcpServers": {
    "insolvency": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://insolvenztracker.de/api/mcp",
        "--header", "X-API-Key:${INSOLVENCY_API_KEY}"
      ],
      "env": { "INSOLVENCY_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Cursor und andere Clients

Cursor, Windsurf, Zed und die meisten anderen Clients nehmen die Server-URL direkt an und erlauben eigene Header, eine Brücke ist dort nicht nötig.

{
  "mcpServers": {
    "insolvency": {
      "url": "https://insolvenztracker.de/api/mcp",
      "headers": { "X-API-Key": "${env:INSOLVENCY_API_KEY}" }
    }
  }
}

Nach dem Eintragen sollte der Client elf Werkzeuge anzeigen. Bleibt die Liste leer, liegt es fast immer am Header: Ein abgelaufener oder vertippter Schlüssel erzeugt eine leere Werkzeugliste statt eines sichtbaren Fehlers.

Werkzeuge

Der Server stellt elf Werkzeuge bereit. Schreibende Werkzeuge sind als solche markiert, damit Clients dort nachfragen können, wo sie es wollen.

Alle lesenden Werkzeuge sind idempotent und dürfen ohne Rückfrage aufgerufen werden. watch_company und unwatch_company verändern Ihr Konto und melden sich beim Client als schreibende Werkzeuge an.

check_counterparty im Detail

Das Werkzeug, auf das es ankommt, ist check_counterparty. Sein Schema ist bewusst schmal: ein Name oder eine Registernummer, optional der Ort und ein Startdatum. Je weniger Entscheidungen ein Modell treffen muss, desto seltener erfindet es Werte.

{
  "name": "check_counterparty",
  "description": "Check whether a German company appears in official insolvency announcements. Use before extending credit, signing a supplier or chasing an overdue invoice. Prefer register number over name when you have it. Never guess a register number.",
  "annotations": { "readOnlyHint": true },
  "inputSchema": {
    "type": "object",
    "properties": {
      "name":           { "type": "string", "description": "Company name as written on the invoice or contract." },
      "city":           { "type": "string", "description": "Registered seat, narrows ambiguous names." },
      "register":       { "type": "string", "description": "e.g. HRB 123456 B" },
      "register_court": { "type": "string", "description": "e.g. Charlottenburg (Berlin)" },
      "since":          { "type": "string", "format": "date", "description": "Only filings on or after this date. Default: 3 years ago." }
    },
    "anyOf": [ { "required": ["name"] }, { "required": ["register"] } ]
  }
}

Die Beschreibung sagt dem Modell ausdrücklich, die Registernummer zu bevorzugen und nie eine zu raten. Eine falsche Registernummer führt zu einem selbstsicheren "keine Bekanntmachung" für die falsche Firma, und das ist schlimmer als eine mehrdeutige Antwort.

Ist ein Name nicht eindeutig, wählt das Werkzeug keine Firma aus, sondern gibt einen Fehlertext mit den Kandidaten zurück. Das Modell fragt dann nach Ort oder Registernummer. Dieses Verhalten ist gewollt und im Abschnitt Fehlerbehandlung beschrieben.

Ohne since schaut das Werkzeug drei Jahre zurück. Ältere Verfahren sind meist abgeschlossen und für aktuelle Entscheidungen nicht mehr maßgeblich. Wenn doch, übergeben Sie ein früheres Datum.

Antwortformat

Werkzeuge antworten zweigleisig: ein Textblock für das Modell und structuredContent für den Client. Der Textblock ist so formuliert, dass das Modell ihn an den Nutzer weitergeben kann, ohne ihn erst deuten zu müssen: Firma, Registernummer, Verfahrensstand, Gericht, Aktenzeichen, Datum.

{
  "content": [
    {
      "type": "text",
      "text": "Musterbau GmbH (HRB 123456 B, Berlin): insolvency proceedings OPENED on 2026-09-28 by Amtsgericht Charlottenburg, case 36a IN 4711/26. Earlier: protective measures on 2026-08-14. Source: official announcement."
    },
    {
      "type": "resource_link",
      "uri": "insolvency://filing/fil_8Kq2Zp4RwT",
      "name": "Announcement 36a IN 4711/26",
      "mimeType": "application/json"
    }
  ],
  "structuredContent": {
    "match": "exact",
    "company_id": "cmp_3n8Kd2ZpQv",
    "status": "opened",
    "filings": [
      { "id": "fil_8Kq2Zp4RwT", "date": "2026-09-28", "type_code": "2" },
      { "id": "fil_2Hd7Vb1Xe", "date": "2026-08-14", "type_code": "0" }
    ]
  },
  "isError": false
}

Volltexte von Bekanntmachungen kommen als Ressourcen-Link zurück, nicht eingebettet. Ein Client, der den Text zeigen will, löst den Link auf. Einer, der es nicht will, hält sein Kontextfenster klein. Eine einzelne Bekanntmachung kann mehrere tausend Zeichen lang sein.

Ressourcen

Neben Werkzeugen stellt der Server Ressourcen unter dem Schema insolvency:// bereit. Clients, die Ressourcen unterstützen, können sie anzeigen oder dem Modell anhängen, ohne ein Werkzeug aufzurufen.

insolvency://filing/{id}             one announcement incl. full text
insolvency://company/{id}            company profile and status
insolvency://company/{id}/filings    all announcements of a company
insolvency://company/{id}/financials published balance sheet figures
insolvency://watchlist               your watched companies
insolvency://types                   filing types with codes and aliases

Die Watchlist-Ressource ändert sich, sobald eine neue Bekanntmachung eine beobachtete Firma betrifft. Der Server sendet dann eine Änderungsmeldung, damit Clients ihre Ansicht aktualisieren können.

Prompts

Für wiederkehrende Aufgaben gibt es fertige Prompts. Sie erfragen, was die Aufgabe braucht, und rufen danach die passenden Werkzeuge auf. In Clients, die Prompts unterstützen, erscheinen sie als Schnellbefehle.

{
  "name": "counterparty_check",
  "description": "Check a list of customers or suppliers for insolvency filings and summarise the risk.",
  "arguments": [
    { "name": "companies", "description": "One company per line: name, city or register number.", "required": true },
    { "name": "since",     "description": "Look-back start date, default 3 years.", "required": false }
  ]
}

Derzeit verfügbar sind counterparty_check (eine Liste von Firmen prüfen), weekly_briefing (neue Bekanntmachungen der Woche für ausgewählte Bundesländer oder Branchen) und proceeding_timeline (Verlauf eines Verfahrens in Alltagssprache erklärt). Wer einen eigenen Ablauf bevorzugt, ignoriert die Prompts und ruft die Werkzeuge direkt auf.

Beispielgespräch

So sieht es in der Praxis aus. Der Agent prüft drei Schuldner, erklärt die Ergebnisse in klaren Worten, fragt beim mehrdeutigen Namen nach und richtet danach die Überwachung ein.

Nutzer: Kannst du unsere drei größten offenen Rechnungen prüfen? Musterbau GmbH
        in Berlin, Nordlicht Handels GmbH und Beispiel Logistik in Hamburg.

Agent:  [check_counterparty name="Musterbau GmbH" city="Berlin"]
        [check_counterparty name="Nordlicht Handels GmbH"]
        [check_counterparty name="Beispiel Logistik" city="Hamburg"]

Agent:  Musterbau GmbH: Das Verfahren wurde am 28.09.2026 eröffnet
        (AG Charlottenburg, 36a IN 4711/26). Forderungen sind jetzt beim
        Insolvenzverwalter anzumelden, eine direkte Zahlung ist unwahrscheinlich.
        Beispiel Logistik UG: Sicherungsmaßnahmen seit 22.09.2026, ein
        vorläufiger Verwalter ist bestellt.
        Nordlicht Handels GmbH: Zwei Firmen tragen diesen Namen, keine hat
        eine Bekanntmachung. Welcher Sitz ist Ihrer?

Nutzer: Hamburg. Und bitte alle drei ab jetzt überwachen.

Agent:  [watch_company name="Nordlicht Handels GmbH" city="Hamburg"]
        [watch_company company_id="cmp_3n8Kd2ZpQv"]
        [watch_company company_id="cmp_7Yb3Rt5Mn"]
        Erledigt. Sie bekommen einen Webhook, sobald eine neue Bekanntmachung erscheint.

Entscheidend ist der dritte Schritt: Bei einem mehrdeutigen Namen fragt der Agent nach, statt zu wählen. Genau dafür ist der Fehlertext des Werkzeugs gebaut.

Berechtigungen

Jeder Schlüssel trägt Berechtigungen. Standardmäßig darf er Bekanntmachungen, Firmen und Statistik lesen. Das Schreiben auf die Watchlist muss gesondert freigeschaltet werden.

Werkzeuge, für die der Schlüssel keine Berechtigung hat, erscheinen gar nicht erst in der Werkzeugliste. Das ist freundlicher als ein Fehler mitten im Gespräch, weil das Modell dann nie etwas anbietet, das es ohnehin nicht kann.

Fehlerbehandlung

Fehler kommen als normales Werkzeugergebnis mit isError: true zurück, nicht als Protokollfehler. Der Text richtet sich an das Modell und sagt ihm, was es als Nächstes tun soll, damit der Agent im Gespräch sinnvoll reagieren kann.

{
  "content": [
    {
      "type": "text",
      "text": "No unique match: 2 companies are called \"Nordlicht Handels GmbH\" (Hamburg, Kiel). Ask the user for the city or the register number and call check_counterparty again. Do not pick one yourself."
    }
  ],
  "isError": true
}

Echte Protokollfehler gibt es nur bei ungültigem Schlüssel, fehlender Berechtigung oder fehlerhafter Anfrage. Alles, was inhaltlich schiefgehen kann, etwa ein mehrdeutiger Name, eine unbekannte ID oder ein zu langer Zeitraum, kommt als Text zurück.

Limits

Es gelten dieselben Limits wie bei der REST-API: 120 Werkzeugaufrufe pro Minute und Schlüssel, höchstens 31 Tage pro Suche in Bekanntmachungen, 24 Monate in der Statistik. Für höhere Werte genügt eine E-Mail.

Das Überschreiten eines Limits führt nicht zu einem harten Fehler, sondern zu einem Textergebnis, das sagt, ab wann es weitergeht. Agenten sollten dann warten, statt sofort erneut aufzurufen.

Daten und Verantwortung

Der Server liefert öffentliche Bekanntmachungen, die aber personenbezogene Daten enthalten. Es gelten dieselben Regeln wie bei der REST-API: Löschfristen der Insolvenzbekanntmachungsverordnung, keine Veröffentlichung von Bekanntmachungen über Privatpersonen, keine automatisierten Entscheidungen über natürliche Personen, die allein auf diesen Daten beruhen.

Ein Agent darf eine Bekanntmachung zusammenfassen, ersetzt aber keine Rechtsberatung. Die Werkzeugtexte nennen deshalb immer Gericht und Aktenzeichen, damit der Nutzer das Original prüfen kann. Wir empfehlen, dass Ihr Agent auch selbst darauf hinweist, wenn er Handlungsempfehlungen ableitet.

Was der Agent an den Server schickt (Firmennamen, Ihre Referenzen), nutzen wir nur zur Beantwortung der Anfrage und geben es nicht weiter. Verarbeitet Ihr Agent Daten über Ihre Kunden, steht ein Auftragsverarbeitungsvertrag bereit.

Betrieb

Der Server läuft auf derselben Infrastruktur wie die REST-API. Wartungsfenster kündigen wir per E-Mail an die hinterlegte Adresse an, Änderungen an Werkzeugschemas sind ausschließlich ergänzend.

Kommt ein neues Werkzeug hinzu, sendet der Server eine Änderungsmeldung. Clients, die darauf reagieren, sehen das Werkzeug ohne Neustart. Bestehende Werkzeuge behalten ihre Namen und ihre Pflichtfelder.

Support

Fragen, höhere Limits, eigene Prompts oder Werkzeuge für einen bestimmten Ablauf: [email protected] oder das Kontaktformular.

Wer lieber gegen schlichtes HTTP arbeitet, findet dieselben Daten als REST-Schnittstelle in der API-Dokumentation. Beide Wege teilen sich Schlüssel, Limits und Vertrag.