VERIDEX MCP server

veridex-mcp

Servidor MCP (Model Context Protocol) para VERIDEX: verificación de empresas españolas por CIF contra el BORME, con puntuación de riesgo explicable y el ciclo de pago x402 resuelto paso a paso.

Una vez configurado, cualquier agente (Claude Desktop, Cursor, VS Code, Claude Code…) puede descubrir y usar la verificación sin que tú escribas una línea de HTTP.

Agente  ──MCP (stdio)──▶  veridex-mcp  ──HTTPS──▶  https://api.veridexia.es/v1/verify
                              │
                              └── no firma pagos: entrega el reto x402 y espera
                                  un X-PAYMENT que produzca una wallet tuya

Qué es y qué no es

Es un cliente MCP fino sobre la API pública de VERIDEX: tres herramientas, tipos explícitos, errores tipados y el reto de pago x402 decodificado para que el agente sepa exactamente cuánto cuesta, en qué red, en qué activo y a qué dirección.

No es una wallet. Este servidor no firma, no custodia claves y no envía transacciones. No puede pagar por ti — y eso es deliberado: un servidor MCP que pudiera mover fondos en nombre del usuario sería una wallet sin dueño. Lo que hace es entregar al agente una petición de pago completa y exacta, y dejar que la settle una wallet que tú controlas.

Tampoco modifica la API: es un consumidor puro de api.veridexia.es.

Las tres herramientas

verifycompanyby_cif

// Entrada
{ "cif": "A58818501", "x_payment": null, "idempotency_key": null }

// Salida (ok = true)
{
  "ok": true,
  "cif": "A58818501",
  "company": {
    "cif": "A58818501",
    "name": "…",
    "legal_form": "Sociedad Anónima",
    "status": "active",
    "status_label": "Activa sin incidencias",
    "province": "Málaga",
    "incorporation_date": "2015-10-02",
    "last_borme_deposit": "2025-08-09",
    "administrator": "…",
    "share_capital_cents": 4500000,
    "insolvency_published_on": null
  },
  "risk": {
    "value": 15,                    // 0 = más seguro, 100 = más arriesgado
    "band": "low",                  // low | medium | high | critical
    "reasons": ["…"],
    "signals": [{ "code": "status_active", "points": 15, "description": "…" }],
    "confidence": "high",
    "assurance": "high",            // cuánto se SABE, no cuánto de malo es
    "conclusive": true
  },
  "recent_acts": [{ "date": "2026-08-28", "section": "Sección Primera", "description": "…" }],
  "mock": false,
  "provenance": { "source": "prometiam", "fetched_at": "…", "from_cache": false, "confidence": "high" },
  "payment": null,
  "error": null,
  "guidance": ""
}

risk.assurance es el campo que más se malinterpreta: assurance: "none" con value: 0 significa no sabemos nada de esta empresa, no esta empresa es segura. El servidor lo dice explícitamente en guidance cuando ocurre.

Instalación

Requiere Python 3.10+.

pip install -e mcp-server

Eso instala el paquete veridex-mcp en modo editable junto con sus dependencias (mcp>=1.9,<2 y httpx), y deja disponible el ejecutable veridex-mcp.

Comprueba que arranca:

veridex-mcp --version
python -m veridex_mcp --version     # equivalente, más portable en Windows

Windows: si el host lanza el servidor con un intérprete concreto, usa

python -m veridex_mcp con la ruta completa al Python del entorno virtual. Es la

forma más fiable de que el proceso correcto arranque.

Shortened. The full README is on GitHub.