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 weiss das Modell, welche Tools es gibt, und ruft sie selbst auf, wenn das Gespräch es verlangt.

Unser Server stellt dieselben Daten bereit wie die REST-API: Meldungen, Firmenprofile, Finanzkennzahlen, Konkursämter, Statistiken und die Watchlist. Der Unterschied liegt in der Aufbereitung. Die Tool-Beschreibungen 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://konkursradar.ch/api/mcp. Sie verwendet dieselben Schlüssel wie die REST-API. Betreiben Sie beide nebeneinander, sehen Sie in beiden 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 möchten und was er tun soll.

Wenn Sie bereits einen API-Schlüssel haben, brauchen Sie keinen zweiten: Derselbe Schlüssel öffnet den MCP-Server. Teams, die den Server an mehrere Personen weitergeben möchten, können mehrere Schlüssel auf einem Konto erhalten, damit nachvollziehbar bleibt, wer was geprüft hat.

Verbindung und Transport

Der Server spricht MCP über Streamable HTTP, den Transport, den aktuelle Clients standardmässig verwenden. Es braucht keinen lokalen Prozess, es gibt nichts zu installieren.

Die Authentifizierung nutzt denselben Header wie die REST-API: X-API-Key, alternativ Authorization: Bearer. Wie der API-Schlüssel selbst ist auch der Server an seinen Markt gebunden: Der Server auf konkursradar.ch antwortet zu Firmen in der Schweiz. Clients, die nur stdio sprechen, erreichen ihn über mcp-remote als Brücke, siehe die Claude-Desktop-Konfiguration weiter unten.

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

curl https://konkursradar.ch/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 konkursradar \
  https://konkursradar.ch/api/mcp \
  --header "X-API-Key: $KONKURS_API_KEY"

Claude Desktop

Claude Desktop liest seine Serverliste aus claude_desktop_config.json. Der Eintrag verbindet sich über mcp-remote mit dem HTTP-Transport.

{
  "mcpServers": {
    "konkursradar": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://konkursradar.ch/api/mcp",
        "--header", "X-API-Key:${KONKURS_API_KEY}"
      ],
      "env": { "KONKURS_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Cursor und andere Clients

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

{
  "mcpServers": {
    "konkursradar": {
      "url": "https://konkursradar.ch/api/mcp",
      "headers": { "X-API-Key": "${env:KONKURS_API_KEY}" }
    }
  }
}

Nach dem Hinzufügen sollte der Client elf Tools anzeigen. Bleibt die Liste leer, liegt es fast immer am Header: Ein abgelaufener oder falsch eingetippter Schlüssel führt zu einer leeren Tool-Liste statt zu einem sichtbaren Fehler.

Tools

Der Server stellt elf Tools bereit. Schreibende Tools sind entsprechend gekennzeichnet, damit Clients dort eine Bestätigung einholen können.

Alle lesenden Tools 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 Tools an.

check_counterparty im Detail

Das Tool, auf das es ankommt, ist check_counterparty. Sein Schema ist bewusst schmal: ein Name oder eine Firmennummer, 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 company in Switzerland appears in official insolvency filings. Use before extending credit, signing a supplier or chasing an overdue invoice. Prefer the company number over the name when you have it. Never guess a company 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 town, narrows ambiguous names." },
      "company_number": { "type": "string", "description": "National register number, e.g. CHE-123.456.789" },
      "since":          { "type": "string", "format": "date", "description": "Only filings on or after this date. Default: 3 years ago." }
    },
    "anyOf": [ { "required": ["name"] }, { "required": ["company_number"] } ]
  }
}

Die Beschreibung weist das Modell ausdrücklich an, die Firmennummer zu bevorzugen und nie eine zu raten. Eine falsche Nummer führt zu einem selbstsicheren „keine Meldung“ für die falsche Firma, und das ist schlimmer als eine mehrdeutige Antwort.

Ist ein Name nicht eindeutig, wählt das Tool keinen aus, sondern liefert einen Fehlertext mit der Zahl der Kandidaten. Das Modell fragt dann die Nutzerin oder den Nutzer nach dem Ort oder der Firmennummer. Dieses Verhalten ist beabsichtigt und im Abschnitt Fehlerbehandlung beschrieben.

Ohne since schaut das Tool drei Jahre zurück. Ältere Verfahren sind meist abgeschlossen und für aktuelle Entscheidungen nicht mehr relevant; falls doch, übergeben Sie ein früheres Datum.

Antwortformat

Tools antworten auf zwei Spuren: ein Textblock für das Modell und structuredContent für den Client. Der Textblock ist so formuliert, dass das Modell ihn weitergeben kann, ohne ihn erst zu interpretieren: Firma, Firmennummer, Verfahrenstyp, Datum, Amt oder Register, Referenz und Quelle.

{
  "content": [
    {
      "type": "text",
      "text": "Beispiel Holzbau AG (CHE-123.456.789, Winterthur): Konkurseröffnung filed on 2026-09-28. Issued by Konkursamt Winterthur, reference KK01-0000312845. Source: SHAB."
    },
    {
      "type": "resource_link",
      "uri": "konkurs://company/CHE-123.456.789/filings",
      "name": "Filings of Beispiel Holzbau AG",
      "mimeType": "application/json"
    }
  ],
  "structuredContent": {
    "match": "exact",
    "company_number": "CHE-123.456.789",
    "status": "bankruptcy",
    "filings": [
      { "date": "2026-09-28", "type_code": "KK01", "case_number": "KK01-0000312845" }
    ]
  },
  "isError": false
}

Umfangreiches Material wie die vollständige Meldungshistorie kommt als Ressourcenlink zurück, nicht eingebettet. Ein Client, der sie anzeigen will, löst den Link auf; einer, der das nicht will, hält sein Kontextfenster klein.

Ressourcen

Zusätzlich zu den Tools stellt der Server Ressourcen unter dem Schema konkurs:// bereit. Clients, die Ressourcen unterstützen, können sie anzeigen oder dem Modell anhängen, ohne ein Tool aufzurufen.

konkurs://company/{number}              company profile and status
konkurs://company/{number}/filings      all filings of a company
konkurs://company/{number}/financials   published accounts figures
konkurs://practitioner/{id}             appointed practitioner or office
konkurs://watchlist                     your watched companies
konkurs://types                         filing types with keys and aliases

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

Prompts

Für wiederkehrende Aufgaben gibt es vorgefertigte Prompts. Sie sammeln, was die Aufgabe braucht, und rufen dann die passenden Tools 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, town or company 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 Meldungen der Woche für ausgewählte Kantone oder Branchen) und company_timeline (die Insolvenzgeschichte einer Firma in einfachen Worten erklärt). Wenn Sie lieber Ihren eigenen Ablauf haben, ignorieren Sie die Prompts und rufen die Tools direkt auf.

Beispielgespräch

So sieht es in der Praxis aus. Der Agent prüft drei Kunden, erklärt die Ergebnisse in einfachen Worten, fragt nach, wo der Name mehrdeutig ist, und richtet dann die Überwachung ein.

Nutzer: Prüfe diese drei Kunden, bevor wir ihre Kreditlinien erneuern:
        Beispiel Holzbau AG, Muster Transporte GmbH, Seeblick Gastro GmbH.

Agent:  [check_counterparty name="Beispiel Holzbau AG"]
        [check_counterparty name="Muster Transporte GmbH"]
        [check_counterparty name="Seeblick Gastro GmbH"]

Agent:  Beispiel Holzbau AG (CHE-123.456.789, Winterthur): Konkurseröffnung
        erfasst am 2026-09-28, Referenz KK01-0000312845, Konkursamt Winterthur.
        Ich würde die Kreditlinie nicht erneuern.

        Muster Transporte GmbH: keine Insolvenzmeldung in den letzten drei Jahren.

        Seeblick Gastro GmbH: Zwei Firmen tragen diesen Namen. In welchem Ort
        sitzt Ihr Kunde?

Nutzer: Luzern.

Agent:  [check_counterparty name="Seeblick Gastro GmbH" city="Luzern"]
        Keine Meldung zur Firma in Luzern.
        Soll ich alle drei auf die Watchlist setzen, damit Sie von
        jeder neuen Meldung sofort erfahren?

Nutzer: Ja.

Agent:  [watch_company company_number="CHE-123.456.789" ref="Beispiel Holzbau AG"]
        [watch_company name="Muster Transporte GmbH"]
        [watch_company name="Seeblick Gastro GmbH" city="Luzern"]
        Erledigt. Alle drei stehen auf der Watchlist.

Der wichtige Schritt ist der dritte: Bei einem mehrdeutigen Namen fragt der Agent nach, statt zu wählen. Genau dafür ist der Fehlertext des Tools gedacht.

Berechtigungen

Jeder Schlüssel trägt Berechtigungen. Standardmässig darf er Meldungen, Firmen, Verfahrensführende und Statistiken lesen; das Schreiben auf die Watchlist muss gesondert freigeschaltet werden.

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

Fehlerbehandlung

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

{
  "content": [
    {
      "type": "text",
      "text": "No unique match: 2 companies are called \"Seeblick Gastro GmbH\". Ask the user for the town or the company number and call check_counterparty again. Do not pick one yourself."
    }
  ],
  "isError": true
}

Echte Protokollfehler treten nur bei einem ungültigen Schlüssel, einer fehlenden Berechtigung oder einer fehlerhaften Anfrage auf. Alles, was inhaltlich schiefgehen kann, etwa ein mehrdeutiger Name, eine unbekannte Firmennummer, ein unbekannter Verfahrenstyp oder ein Zeitraum von mehr als 31 Tagen, kommt als Text zurück.

Limits

Es gelten dieselben Limits wie bei der REST-API: 120 Tool-Aufrufe pro Minute und Schlüssel, höchstens 31 Tage und 10 000 Zeilen pro Suche in Meldungen, 24 Monate bei Statistiken. Für höhere Werte genügt eine E-Mail.

Wird ein Limit überschritten, gibt es keinen harten Fehler, sondern ein Textergebnis, das sagt, ab wann es weitergeht. Agenten sollten dann warten, statt sofort erneut aufzurufen.

Daten und Verantwortung

Der Server liefert öffentliche SHAB-Meldungen, die Personendaten enthalten können. Es gelten dieselben Regeln wie für die REST-API: DSG und DSGVO, kein Weiterverkauf der Rohdaten, keine automatisierten Entscheidungen über natürliche Personen, die sich allein auf diese Daten stützen.

Ein Agent darf eine Meldung zusammenfassen, ersetzt aber keine Rechtsberatung. Die Tool-Texte nennen deshalb immer das Amt oder Register und die Referenz, damit die Nutzerin oder der Nutzer das Original prüfen kann. Wir empfehlen, dass Ihr Agent auch darauf hinweist, wenn er Handlungsempfehlungen ableitet.

Was der Agent an den Server sendet (Firmennamen, Ihre Referenzen), wird nur zur Beantwortung der Anfrage verwendet und nicht weitergegeben. Wenn Ihr Agent Daten über Ihre Kunden verarbeitet, ist ein Auftragsbearbeitungsvertrag erhältlich.

Betrieb

Der Server läuft auf derselben Infrastruktur wie die REST-API. Wartungsfenster kündigen wir per E-Mail an die hinterlegte Adresse an, und Änderungen an Tool-Schemas sind ausschliesslich additiv.

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

Support

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

Wenn Sie lieber direkt über HTTP arbeiten, ist dieselbe Datenbasis als REST-Schnittstelle in der API-Dokumentation beschrieben. Beide Wege teilen sich Schlüssel, Limits und Vertrag.