Servidor MCP

Introducción

El Model Context Protocol es un estándar abierto que define cómo accede un agente de IA a herramientas y datos externos. En lugar de programar una interfaz, añades el servidor una vez a la configuración del agente. A partir de ahí el modelo sabe qué herramientas existen y las llama por sí mismo cuando la conversación lo requiere.

Nuestro servidor expone los mismos datos que la API REST: anuncios, perfiles de empresa, cifras de balance, estadísticas y la lista de seguimiento. La diferencia está en el enfoque. Las descripciones de las herramientas están escritas para que un modelo entienda cuándo tiene sentido una verificación de insolvencia, qué datos debe pedir y dónde están los límites de la información.

La dirección es https://germanyinsolvencies.com/api/mcp. Usa las mismas claves que la API REST. Si operas ambas en paralelo, verás la misma lista de seguimiento en los dos mundos.

Acceso

El camino es el mismo que para la API REST: las claves se conceden a mano. Usa el formulario de contacto o escribe a [email protected] e indica brevemente qué agente quieres conectar y qué debe hacer.

Si ya tienes una clave de API, no necesitas una segunda: la misma clave abre el servidor MCP. Los equipos que quieran ofrecer el servidor a varias personas pueden recibir, si lo piden, varias claves en una misma cuenta, de modo que siga siendo trazable quién verificó qué.

Conexión y transporte

El servidor habla MCP sobre Streamable HTTP, el transporte que usan por defecto los clientes actuales. No hace falta ningún proceso local ni instalar nada.

La autenticación usa la misma cabecera que la API REST: X-API-Key, o bien Authorization: Bearer. Los clientes que solo hablan stdio llegan al servidor mediante mcp-remote como puente, véase la configuración de Claude Desktop más abajo.

Cliente y servidor negocian la versión del protocolo al conectarse. Damos soporte a la revisión actual y a la anterior, de modo que una actualización del cliente nunca provoca una ruptura brusca.

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

Configuración

En Claude Code basta un comando. La clave debería venir de una variable de entorno, no del portapapeles.

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

Claude Desktop

Claude Desktop lee su lista de servidores de claude_desktop_config.json. La entrada hace de puente hacia el transporte HTTP mediante 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 y otros clientes

Cursor, Windsurf, Zed y la mayoría de los demás clientes aceptan la URL del servidor directamente y permiten cabeceras propias, así que no hace falta puente.

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

Tras añadirlo, el cliente debería mostrar once herramientas. Si la lista queda vacía, casi siempre es por la cabecera: una clave caducada o mal escrita produce una lista de herramientas vacía en lugar de un error visible.

Herramientas

El servidor ofrece once herramientas. Las que escriben están marcadas como tales, para que los clientes puedan pedir confirmación donde lo deseen.

Todas las herramientas de lectura son idempotentes y se pueden llamar sin preguntar. watch_company y unwatch_company modifican tu cuenta y se anuncian al cliente como herramientas de escritura.

check_counterparty en detalle

La herramienta que importa es check_counterparty. Su esquema es deliberadamente estrecho: un nombre o un número de registro y, opcionalmente, la ciudad y una fecha de inicio. Cuantas menos decisiones tenga que tomar un modelo, menos veces se inventa valores.

{
  "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 descripción indica expresamente al modelo que prefiera el número de registro y que nunca lo adivine. Un número de registro erróneo conduce a un «ningún anuncio» seguro de sí mismo sobre la empresa equivocada, lo cual es peor que una respuesta ambigua.

Si un nombre no es único, la herramienta no elige uno, sino que devuelve un texto de error con los candidatos. El modelo pide entonces al usuario la ciudad o el número de registro. Este comportamiento es intencionado y se trata en la sección de gestión de errores.

Sin since, la herramienta mira tres años atrás. Los procedimientos más antiguos suelen estar cerrados y ya no importan para las decisiones actuales; si importan, pasa una fecha anterior.

Formato de respuesta

Las herramientas responden por dos vías: un bloque de texto para el modelo y structuredContent para el cliente. El bloque de texto está redactado para que el modelo pueda pasárselo al usuario sin tener que interpretarlo antes: empresa, número de registro, fase, juzgado, número de expediente, fecha.

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

Los textos completos de los anuncios llegan como enlaces de recurso, no incrustados. Un cliente que quiera mostrar el texto resuelve el enlace; el que no, mantiene pequeña su ventana de contexto. Un solo anuncio puede tener varios miles de caracteres.

Recursos

Además de herramientas, el servidor ofrece recursos bajo el esquema insolvency://. Los clientes que admiten recursos pueden mostrarlos o adjuntarlos al modelo sin llamar a una herramienta.

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

El recurso de la lista de seguimiento cambia cuando un anuncio nuevo afecta a una empresa vigilada. El servidor envía entonces una notificación de cambio, para que los clientes puedan actualizar su vista.

Prompts

Para tareas recurrentes hay prompts ya preparados. Reúnen lo que la tarea necesita y después llaman a las herramientas adecuadas. En los clientes que admiten prompts aparecen como comandos rápidos.

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

Actualmente están disponibles counterparty_check (verificar una lista de empresas), weekly_briefing (anuncios nuevos de la semana para estados federados o sectores seleccionados) y proceeding_timeline (historial de un procedimiento explicado en lenguaje llano). Si prefieres tu propio flujo, ignora los prompts y llama directamente a las herramientas.

Conversación de ejemplo

Así se ve en la práctica. El agente verifica a tres deudores, explica los resultados en términos sencillos, pregunta de nuevo donde el nombre es ambiguo y después configura la vigilancia.

Usuario: ¿Puedes verificar nuestras tres facturas abiertas más grandes?
         Musterbau GmbH en Berlín, Nordlicht Handels GmbH y Beispiel
         Logistik en Hamburgo.

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

Agente:  Musterbau GmbH: el procedimiento se abrió el 28 de septiembre de
         2026 (AG Charlottenburg, 36a IN 4711/26). Los créditos ya deben
         comunicarse al administrador concursal, un pago directo es poco
         probable.
         Beispiel Logistik UG: medidas cautelares desde el 22 de septiembre
         de 2026, se ha nombrado un administrador provisional.
         Nordlicht Handels GmbH: hay dos empresas con ese nombre y
         ninguna tiene anuncios. ¿Cuál es la ciudad de la vuestra?

Usuario: Hamburgo. Y vigila las tres a partir de ahora, por favor.

Agente:  [watch_company name="Nordlicht Handels GmbH" city="Hamburg"]
         [watch_company company_id="cmp_3n8Kd2ZpQv"]
         [watch_company company_id="cmp_7Yb3Rt5Mn"]
         Hecho. Recibirás un webhook en cuanto aparezca un anuncio nuevo.

El paso importante es el tercero: ante un nombre ambiguo, el agente pregunta en lugar de elegir. Para eso está diseñado precisamente el texto de error de la herramienta.

Permisos

Cada clave lleva permisos. Por defecto puede leer anuncios, empresas y estadísticas; la escritura en la lista de seguimiento hay que habilitarla por separado.

Las herramientas para las que la clave no tiene permiso no aparecen en absoluto en la lista de herramientas. Es más amable que un error a mitad de conversación, porque así el modelo nunca ofrece algo que de todos modos no puede hacer.

Gestión de errores

Los errores llegan como un resultado de herramienta normal con isError: true, no como un error de protocolo. El texto está dirigido al modelo e indica qué debe hacer a continuación, de modo que el agente pueda reaccionar con sentido dentro de la conversación.

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

Los errores de protocolo propiamente dichos solo se producen con una clave no válida, un permiso ausente o una petición mal formada. Todo lo que pueda fallar en cuanto al contenido, como un nombre ambiguo, un ID desconocido o un periodo demasiado largo, llega como texto.

Límites

Se aplican los mismos límites que en la API REST: 120 llamadas a herramientas por minuto y clave, como máximo 31 días por búsqueda de anuncios y 24 meses en estadísticas. Para valores más altos basta un correo.

Superar un límite no produce un error duro, sino un resultado de texto que indica cuándo se puede continuar. Los agentes deberían esperar entonces en lugar de volver a llamar de inmediato.

Datos y responsabilidad

El servidor devuelve anuncios públicos, pero contienen datos personales. Se aplican las mismas reglas que en la API REST: plazos de supresión de la Ordenanza sobre Publicaciones Concursales (Insolvenzbekanntmachungsverordnung), ninguna publicación de anuncios sobre particulares y ninguna decisión automatizada sobre personas físicas basada únicamente en estos datos.

Un agente puede resumir un anuncio, pero eso no sustituye al asesoramiento jurídico. Por eso los textos de las herramientas nombran siempre juzgado y número de expediente, para que el usuario pueda comprobar el original. Recomendamos que tu agente lo señale también cuando derive recomendaciones de actuación.

Lo que el agente envía al servidor (nombres de empresa, tus referencias) se usa solo para responder a la petición y no se transmite a terceros. Si tu agente trata datos de tus clientes, hay disponible un contrato de encargo de tratamiento.

Operación

El servidor funciona sobre la misma infraestructura que la API REST. Las ventanas de mantenimiento se anuncian por correo a la dirección registrada, y los cambios en los esquemas de las herramientas son siempre aditivos.

Cuando se añade una herramienta nueva, el servidor envía una notificación de cambio. Los clientes que reaccionan a ella ven la herramienta sin reiniciar. Las herramientas existentes conservan sus nombres y sus campos obligatorios.

Soporte

Preguntas, límites más altos, prompts o herramientas propios para un flujo de trabajo concreto: [email protected] o el formulario de contacto.

Si prefieres trabajar con HTTP directo, los mismos datos están documentados como interfaz REST en la documentación de la API. Ambas vías comparten claves, límites y contrato.