Il server MCP collega gli avvisi di insolvenza tedeschi direttamente agli agenti di IA. Claude, Cursor o il tuo agente possono verificare un fornitore, leggere una procedura o monitorare un cliente nel corso di una conversazione, senza che nessuno scriva un client API.
Ultimo aggiornamento: 2026-09-29
Le chiavi vengono rilasciate a mano. Raccontaci in breve cosa vuoi realizzare e quale volume prevedi: di solito l’accesso è attivo entro un giorno lavorativo.
Il Model Context Protocol è uno standard aperto che definisce come un agente di IA accede a strumenti e dati esterni. Invece di programmare un’interfaccia, aggiungi il server una volta alla configurazione dell’agente. Da quel momento il modello sa quali strumenti esistono e li richiama da solo quando la conversazione lo richiede.
Il nostro server espone gli stessi dati dell’API REST: avvisi, profili aziendali, dati di bilancio, statistiche e watchlist. La differenza sta nell’impostazione. Le descrizioni degli strumenti sono scritte in modo che un modello capisca quando ha senso una verifica di insolvenza, quali dettagli deve chiedere e dove stanno i limiti dei dati.
L’indirizzo è https://germanyinsolvencies.com/api/mcp. Usa le stesse chiavi dell’API REST. Se usi entrambi in parallelo, vedrai la stessa watchlist in entrambi i mondi.
Domande tipiche a cui un agente risponde con questo server: «Il nostro fornitore è insolvente?», «Quali delle nostre 40 fatture aperte sono interessate da una procedura?», «Quante imprese edili sono fallite in Baviera in questo trimestre?»
La via è la stessa dell’API REST: le chiavi vengono rilasciate a mano. Usa il modulo di contatto oppure scrivi a [email protected] indicando in breve quale agente vuoi collegare e cosa deve fare.
Se hai già una chiave API, non te ne serve una seconda: la stessa chiave apre il server MCP. I team che vogliono dare accesso al server a più persone possono ottenere su richiesta più chiavi su un unico account, così resta tracciabile chi ha verificato cosa.
Il server parla MCP su Streamable HTTP, il trasporto che i client attuali usano per impostazione predefinita. Non serve alcun processo locale, non c’è nulla da installare.
L’autenticazione usa lo stesso header dell’API REST: X-API-Key, in alternativa Authorization: Bearer. I client che parlano solo stdio raggiungono il server tramite mcp-remote come ponte, vedi la configurazione di Claude Desktop qui sotto.
Client e server negoziano la versione del protocollo alla connessione. Supportiamo la revisione attuale e quella precedente, quindi un aggiornamento del client non porta mai a una rottura netta.
curl https://germanyinsolvencies.com/api/mcp/healthIn Claude Code basta un comando. La chiave dovrebbe provenire da una variabile d’ambiente, non dagli appunti.
claude mcp add --transport http insolvency \
https://germanyinsolvencies.com/api/mcp \
--header "X-API-Key: $INSOLVENCY_API_KEY"Claude Desktop legge l’elenco dei server da claude_desktop_config.json. La voce fa da ponte verso il trasporto HTTP tramite 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, Windsurf, Zed e la maggior parte degli altri client accettano direttamente l’URL del server e consentono header propri, quindi non serve alcun ponte.
{
"mcpServers": {
"insolvency": {
"url": "https://germanyinsolvencies.com/api/mcp",
"headers": { "X-API-Key": "${env:INSOLVENCY_API_KEY}" }
}
}
}Dopo l’aggiunta il client dovrebbe mostrare undici strumenti. Se l’elenco resta vuoto, quasi sempre il problema è l’header: una chiave scaduta o digitata male produce un elenco di strumenti vuoto invece di un errore visibile.
Il server mette a disposizione undici strumenti. Gli strumenti di scrittura sono contrassegnati come tali, così i client possono chiedere conferma dove lo desiderano.
| Strumento | Tipo | Descrizione |
|---|---|---|
| search_filings | read | Cerca avvisi per periodo, tipo, Land, tribunale o nome. Restituisce un breve riepilogo per ogni risultato, il testo completo tramite get_filing. |
| get_filing | read | Restituisce un avviso con testo completo, tribunale, numero di ruolo e tipo. |
| check_counterparty | read | Verifica un’azienda rispetto agli avvisi e restituisce stato, ultimo avviso e qualità della corrispondenza. Lo strumento più importante, vedi sotto. |
| search_companies | read | Trova profili aziendali per nome, città, numero di registro o status. |
| get_company | read | Restituisce un profilo aziendale con tutti gli avvisi collegati in ordine cronologico. |
| get_financials | read | Restituisce i dati di bilancio pubblicati degli ultimi esercizi. |
| get_stats | read | Conta gli avvisi per giorno, mese, Land, tribunale, tipo o forma giuridica. |
| list_filing_types | read | Elenca i nove tipi di pubblicazione con codice, alias e significato. Gli agenti dovrebbero richiamarlo una volta invece di indovinare i codici. |
| list_watchlist | read | Elenca le aziende monitorate con la data dell’ultimo riscontro. |
| watch_company | write | Aggiunge un’azienda alla watchlist. |
| unwatch_company | write | Rimuove un’azienda dalla watchlist. |
Tutti gli strumenti di lettura sono idempotenti e possono essere richiamati senza chiedere conferma. watch_company e unwatch_company modificano il tuo account e si annunciano al client come strumenti di scrittura.
Lo strumento che conta è check_counterparty. Il suo schema è volutamente stretto: un nome o un numero di registro, facoltativamente la città e una data di inizio. Meno decisioni deve prendere un modello, più raramente inventa valori.
{
"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"] } ]
}
}La descrizione dice esplicitamente al modello di preferire il numero di registro e di non indovinarne mai uno. Un numero di registro sbagliato porta a un sicuro «nessun avviso» per l’azienda sbagliata, il che è peggio di una risposta ambigua.
Se un nome non è univoco, lo strumento non ne sceglie uno ma restituisce un testo di errore con i candidati. Il modello chiede allora all’utente la città o il numero di registro. Questo comportamento è voluto ed è trattato nella sezione sulla gestione degli errori.
Senza since, lo strumento guarda indietro di tre anni. Le procedure più vecchie sono di solito chiuse e non più rilevanti per le decisioni attuali; se lo sono, passa una data precedente.
Gli strumenti rispondono su due binari: un blocco di testo per il modello e structuredContent per il client. Il blocco di testo è formulato in modo che il modello possa inoltrarlo all’utente senza doverlo prima interpretare: azienda, numero di registro, fase, tribunale, numero di ruolo, data.
{
"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
}I testi completi degli avvisi tornano come resource link, non incorporati. Un client che vuole mostrare il testo risolve il link; uno che non vuole mantiene piccola la propria finestra di contesto. Un singolo avviso può essere lungo diverse migliaia di caratteri.
Oltre agli strumenti, il server mette a disposizione risorse sotto lo schema insolvency://. I client che supportano le risorse possono visualizzarle o allegarle al modello senza richiamare uno strumento.
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 aliasesLa risorsa watchlist cambia quando un nuovo avviso riguarda un’azienda monitorata. Il server invia allora una notifica di modifica, così i client possono aggiornare la propria vista.
Per i compiti ricorrenti esistono prompt già pronti. Raccolgono ciò che serve al compito e poi richiamano gli strumenti appropriati. Nei client che supportano i prompt compaiono come comandi rapidi.
{
"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 }
]
}Al momento sono disponibili counterparty_check (verifica di un elenco di aziende), weekly_briefing (nuovi avvisi della settimana per Länder o settori selezionati) e proceeding_timeline (storia di una procedura spiegata in modo semplice). Se preferisci un flusso tuo, ignora i prompt e richiama direttamente gli strumenti.
Ecco come appare nella pratica. L’agente verifica tre debitori, spiega i risultati in termini semplici, chiede chiarimenti dove il nome è ambiguo e poi imposta il monitoraggio.
Utente: Puoi verificare le nostre tre fatture aperte più grandi? Musterbau GmbH
a Berlino, Nordlicht Handels GmbH e Beispiel Logistik ad Amburgo.
Agente: [check_counterparty name="Musterbau GmbH" city="Berlin"]
[check_counterparty name="Nordlicht Handels GmbH"]
[check_counterparty name="Beispiel Logistik" city="Hamburg"]
Agente: Musterbau GmbH: la procedura è stata aperta il 28 set 2026
(AG Charlottenburg, 36a IN 4711/26). I crediti vanno ora insinuati
presso il curatore, un pagamento diretto è improbabile.
Beispiel Logistik UG: misure cautelari dal 22 set 2026, è stato
nominato un curatore provvisorio.
Nordlicht Handels GmbH: due aziende con questo nome, nessuna ha
avvisi. Qual è la vostra città?
Utente: Amburgo. E per favore monitora tutte e tre da ora in poi.
Agente: [watch_company name="Nordlicht Handels GmbH" city="Hamburg"]
[watch_company company_id="cmp_3n8Kd2ZpQv"]
[watch_company company_id="cmp_7Yb3Rt5Mn"]
Fatto. Riceverete un webhook non appena comparirà un nuovo avviso.Il passaggio importante è il terzo: davanti a un nome ambiguo l’agente chiede invece di scegliere. È esattamente per questo che è pensato il testo di errore dello strumento.
Ogni chiave porta con sé dei permessi. Per impostazione predefinita può leggere avvisi, aziende e statistiche; la scrittura sulla watchlist va abilitata separatamente.
| Scope | Significato |
|---|---|
| filings:read | Cercare e leggere gli avvisi. |
| companies:read | Profili aziendali, dati di bilancio e verifica delle controparti. |
| stats:read | Statistiche aggregate. |
| watchlist:write | Aggiungere e rimuovere aziende dalla watchlist. |
Gli strumenti per cui la chiave non ha permessi non compaiono affatto nell’elenco degli strumenti. È più gradevole di un errore a metà conversazione, perché così il modello non propone mai qualcosa che comunque non può fare.
Gli errori tornano come normale risultato di uno strumento con isError: true, non come errore di protocollo. Il testo è rivolto al modello e dice cosa deve fare dopo, così l’agente può reagire in modo sensato all’interno della conversazione.
{
"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
}I veri errori di protocollo si verificano solo con una chiave non valida, un permesso mancante o una richiesta malformata. Tutto ciò che può andare storto sul piano dei contenuti, come un nome ambiguo, un ID sconosciuto o un periodo troppo lungo, torna come testo.
Valgono gli stessi limiti dell’API REST: 120 chiamate di strumenti al minuto per chiave, al massimo 31 giorni per ricerca negli avvisi, 24 mesi nelle statistiche. Per valori più alti basta un’email.
Il superamento di un limite non produce un errore netto ma un risultato testuale che indica quando si può proseguire. Gli agenti dovrebbero allora attendere invece di richiamare subito.
Il server restituisce avvisi pubblici, che però contengono dati personali. Valgono le stesse regole dell’API REST: termini di cancellazione del regolamento tedesco sugli avvisi di insolvenza, nessuna pubblicazione di avvisi su privati, nessuna decisione automatizzata su persone fisiche basata esclusivamente su questi dati.
Un agente può riassumere un avviso, ma questo non sostituisce la consulenza legale. I testi degli strumenti indicano quindi sempre tribunale e numero di ruolo, così l’utente può controllare l’originale. Consigliamo che il tuo agente lo faccia presente anche quando ricava raccomandazioni operative.
Ciò che l’agente invia al server (nomi di aziende, i tuoi riferimenti) viene usato solo per rispondere alla richiesta e non viene inoltrato. Se il tuo agente tratta dati sui tuoi clienti, è disponibile un contratto di trattamento dei dati.
Il server gira sulla stessa infrastruttura dell’API REST. Le finestre di manutenzione vengono comunicate via email all’indirizzo registrato e le modifiche agli schemi degli strumenti sono solo additive.
Quando viene aggiunto un nuovo strumento, il server invia una notifica di modifica. I client che vi reagiscono vedono lo strumento senza riavvio. Gli strumenti esistenti mantengono i loro nomi e i loro campi obbligatori.
Domande, limiti più alti, prompt o strumenti propri per un flusso di lavoro specifico: [email protected] oppure il modulo di contatto.
Se preferisci lavorare direttamente su HTTP, gli stessi dati sono documentati come interfaccia REST nella documentazione API. Entrambe le vie condividono chiavi, limiti e contratto.
Le chiavi vengono rilasciate a mano. Raccontaci in breve cosa vuoi realizzare e quale volume prevedi: di solito l’accesso è attivo entro un giorno lavorativo.