MCP-server

Inleiding

Het Model Context Protocol is een open standaard voor de manier waarop een AI-agent externe tools en data bereikt. In plaats van een interface te programmeren voegt u de server één keer toe aan de configuratie van de agent. Vanaf dat moment weet het model welke tools er zijn en roept het ze zelf aan wanneer het gesprek erom vraagt.

Onze server biedt dezelfde data als de REST API: bekendmakingen, bedrijfsprofielen, balanscijfers, statistieken en de watchlist. Het verschil zit in de framing. De toolbeschrijvingen zijn zo geschreven dat een model begrijpt wanneer een insolventiecontrole zinvol is, welke gegevens het moet navragen en waar de grenzen van de data liggen.

Het adres is https://germanyinsolvencies.com/api/mcp. Het gebruikt dezelfde sleutels als de REST API. Gebruikt u beide naast elkaar, dan ziet u in beide werelden dezelfde watchlist.

Toegang

De route is dezelfde als bij de REST API: sleutels worden handmatig verstrekt. Gebruik het contactformulier of schrijf naar [email protected] en geef kort aan welke agent u wilt koppelen en wat die moet doen.

Hebt u al een API-sleutel, dan hebt u geen tweede nodig: dezelfde sleutel opent de MCP-server. Teams die de server aan meerdere mensen willen geven, kunnen op aanvraag meerdere sleutels op één account krijgen, zodat traceerbaar blijft wie wat heeft gecontroleerd.

Verbinding en transport

De server spreekt MCP via Streamable HTTP, het transport dat actuele clients standaard gebruiken. Een lokaal proces is niet nodig, er valt niets te installeren.

Authenticatie gebruikt dezelfde header als de REST API: X-API-Key, alternatief Authorization: Bearer. Clients die alleen stdio spreken, bereiken de server via mcp-remote als brug, zie de Claude Desktop-configuratie hieronder.

Client en server onderhandelen bij het verbinden over de protocolversie. Wij ondersteunen de actuele revisie en de voorgaande, zodat een clientupdate nooit tot een harde breuk leidt.

curl https://germanyinsolvencies.com/api/mcp/health

Setup

In Claude Code volstaat één commando. De sleutel hoort uit een omgevingsvariabele te komen, niet van het klembord.

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

Claude Desktop

Claude Desktop leest zijn serverlijst uit claude_desktop_config.json. De vermelding overbrugt naar het HTTP-transport via mcp-remote.

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

Cursor en andere clients

Cursor, Windsurf, Zed en de meeste andere clients nemen de server-URL rechtstreeks en staan eigen headers toe, dus een brug is niet nodig.

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

Na het toevoegen hoort de client elf tools te tonen. Blijft de lijst leeg, dan ligt het bijna altijd aan de header: een verlopen of verkeerd getypte sleutel geeft een lege toollijst in plaats van een zichtbare fout.

Tools

De server biedt elf tools. Schrijvende tools zijn als zodanig gemarkeerd, zodat clients om bevestiging kunnen vragen waar ze dat willen.

Alle lezende tools zijn idempotent en mogen zonder vragen worden aangeroepen. watch_company en unwatch_company wijzigen uw account en melden zich bij de client aan als schrijvende tools.

check_counterparty in detail

De tool waar het om draait is check_counterparty. Het schema is bewust smal: een naam of een registernummer, optioneel de plaats en een begindatum. Hoe minder beslissingen een model moet nemen, hoe minder vaak het waarden verzint.

{
  "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"] } ]
  }
}

De beschrijving zegt het model uitdrukkelijk dat het het registernummer moet verkiezen en er nooit een mag raden. Een verkeerd registernummer leidt tot een stellig "geen bekendmaking" voor het verkeerde bedrijf, en dat is erger dan een dubbelzinnig antwoord.

Is een naam niet uniek, dan kiest de tool er niet zelf een uit maar geeft een fouttekst met de kandidaten terug. Het model vraagt de gebruiker dan om de plaats of het registernummer. Dit gedrag is bedoeld en wordt behandeld in de sectie foutafhandeling.

Zonder since kijkt de tool drie jaar terug. Oudere procedures zijn meestal afgesloten en niet meer relevant voor actuele beslissingen; zijn ze dat wel, geef dan een eerdere datum mee.

Antwoordformaat

Tools antwoorden op twee sporen: een tekstblok voor het model en structuredContent voor de client. Het tekstblok is zo geformuleerd dat het model het aan de gebruiker kan doorgeven zonder het eerst te hoeven interpreteren: bedrijf, registernummer, stadium, rechtbank, zaaknummer, 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
}

Volledige teksten van bekendmakingen komen terug als resource-links, niet ingebed. Een client die de tekst wil tonen, lost de link op; een client die dat niet doet, houdt zijn contextvenster klein. Eén bekendmaking kan enkele duizenden tekens lang zijn.

Resources

Naast tools biedt de server resources onder het schema insolvency://. Clients die resources ondersteunen, kunnen ze tonen of aan het model koppelen zonder een tool aan te roepen.

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

De watchlist-resource verandert wanneer een nieuwe bekendmaking een gevolgd bedrijf betreft. De server stuurt dan een wijzigingsmelding, zodat clients hun weergave kunnen bijwerken.

Prompts

Voor terugkerende taken zijn er kant-en-klare prompts. Ze verzamelen wat de taak nodig heeft en roepen daarna de passende tools aan. In clients die prompts ondersteunen verschijnen ze als snelle commando's.

{
  "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 }
  ]
}

Momenteel beschikbaar zijn counterparty_check (een lijst bedrijven controleren), weekly_briefing (nieuwe bekendmakingen van de week voor geselecteerde deelstaten of branches) en proceeding_timeline (verloop van een procedure in gewone taal uitgelegd). Geeft u de voorkeur aan een eigen werkwijze, negeer de prompts dan en roep de tools rechtstreeks aan.

Voorbeeldgesprek

Zo ziet het er in de praktijk uit. De agent controleert drie debiteuren, legt de resultaten in gewone taal uit, vraagt na waar de naam dubbelzinnig is en zet daarna de monitoring op.

Gebruiker: Kun je onze drie grootste openstaande facturen controleren?
           Musterbau GmbH in Berlijn, Nordlicht Handels GmbH en
           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: de procedure is geopend op 28 sep 2026
           (AG Charlottenburg, 36a IN 4711/26). Vorderingen moeten nu
           bij de insolventiebewindvoerder worden ingediend, directe
           betaling is onwaarschijnlijk.
           Beispiel Logistik UG: beschermingsmaatregelen sinds 22 sep
           2026, er is een voorlopige bewindvoerder aangesteld.
           Nordlicht Handels GmbH: twee bedrijven met die naam, geen van
           beide heeft een melding. Welke plaats is de uwe?

Gebruiker: Hamburg. En volg alle drie voortaan graag.

Agent:     [watch_company name="Nordlicht Handels GmbH" city="Hamburg"]
           [watch_company company_id="cmp_3n8Kd2ZpQv"]
           [watch_company company_id="cmp_7Yb3Rt5Mn"]
           Klaar. U ontvangt een webhook zodra er een nieuwe bekendmaking verschijnt.

De belangrijke stap is de derde: bij een dubbelzinnige naam vraagt de agent het na in plaats van te kiezen. Daar is de fouttekst van de tool precies voor ontworpen.

Rechten

Elke sleutel heeft rechten. Standaard kan hij bekendmakingen, bedrijven en statistieken lezen; schrijven naar de watchlist moet apart worden geactiveerd.

Tools waarvoor de sleutel geen rechten heeft, verschijnen helemaal niet in de toollijst. Dat is vriendelijker dan een fout midden in het gesprek, omdat het model dan nooit iets aanbiedt wat het toch niet kan.

Foutafhandeling

Fouten komen terug als normaal toolresultaat met isError: true, niet als protocolfout. De tekst is aan het model gericht en zegt wat het vervolgens moet doen, zodat de agent binnen het gesprek zinvol kan reageren.

{
  "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 protocolfouten treden alleen op bij een ongeldige sleutel, een ontbrekend recht of een misvormd verzoek. Alles wat inhoudelijk mis kan gaan, zoals een dubbelzinnige naam, een onbekende ID of een te lange periode, komt als tekst terug.

Limieten

Dezelfde limieten gelden als bij de REST API: 120 toolaanroepen per minuut en sleutel, maximaal 31 dagen per zoekopdracht in bekendmakingen, 24 maanden bij statistieken. Voor hogere waarden volstaat een e-mail.

Het overschrijden van een limiet levert geen harde fout op, maar een tekstresultaat dat aangeeft wanneer het kan doorgaan. Agents horen dan te wachten in plaats van meteen opnieuw aan te roepen.

Data en verantwoordelijkheid

De server geeft openbare bekendmakingen terug, maar die bevatten persoonsgegevens. Dezelfde regels gelden als bij de REST API: verwijdertermijnen van de Duitse verordening inzake insolventiebekendmakingen, geen publicatie van bekendmakingen over particulieren, geen geautomatiseerde beslissingen over natuurlijke personen die uitsluitend op deze data berusten.

Een agent mag een bekendmaking samenvatten, maar dat vervangt geen juridisch advies. De teksten van de tools noemen daarom altijd rechtbank en zaaknummer, zodat de gebruiker het origineel kan controleren. Wij raden aan dat uw agent hier ook op wijst wanneer hij aanbevelingen voor handelen afleidt.

Wat de agent naar de server stuurt (bedrijfsnamen, uw referenties) wordt alleen gebruikt om het verzoek te beantwoorden en niet doorgegeven. Verwerkt uw agent gegevens over uw klanten, dan is een verwerkersovereenkomst beschikbaar.

Beheer en bedrijfsvoering

De server draait op dezelfde infrastructuur als de REST API. Onderhoudsvensters worden per e-mail aan het opgeslagen adres aangekondigd en wijzigingen aan toolschema's zijn uitsluitend aanvullend.

Wanneer er een nieuwe tool bijkomt, stuurt de server een wijzigingsmelding. Clients die daarop reageren, zien de tool zonder herstart. Bestaande tools behouden hun namen en hun verplichte velden.

Support

Vragen, hogere limieten, eigen prompts of tools voor een specifieke workflow: [email protected] of het contactformulier.

Werkt u liever met gewoon HTTP, dan zijn dezelfde data als REST-interface gedocumenteerd in de API-documentatie. Beide routes delen sleutels, limieten en contract.