MCP Server

El MCP Server de IQX Lookup permite a los asistentes de IA (Claude, Cursor, Windsurf, Codex, etc.) invocar las 12 herramientas de validación de forma nativa a través del Model Context Protocol. Un solo comando npx, sin paso de compilación, sin código de cliente HTTP, sin parseo de JSON.

¿Por qué MCP?

La integración tradicional con una API requiere configurar un cliente HTTP, headers de autenticación, serialización JSON y manejo de errores. Con MCP, el asistente de IA invoca las herramientas de validación de la misma forma que lee archivos o busca en la web: de forma nativa. Describes lo que necesitas en lenguaje natural y el asistente se encarga del resto.

Configuración

Requisitos previos

Node.js 18+
Una API key del dashboard

Claude Desktop / Claude Code

Añade lo siguiente a tu configuración MCP (claude_desktop_config.json o .claude.json):

{
  "mcpServers": {
    "iqx-lookup": {
      "command": "npx",
      "args": ["-y", "@neivi/iqx-lookup-mcp-server@latest"],
      "env": {
        "LOOKUP_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Cursor / Windsurf

Usa el mismo bloque de configuración en el archivo de configuración MCP de tu editor (.cursor/mcp.json o equivalente).

Codex

Codex usa config.toml para la configuración de servidores MCP, no un bloque JSON mcpServers. Puedes configurar servidores MCP globalmente en ~/.codex/config.toml o por proyecto en .codex/config.toml (solo proyectos de confianza). El CLI de Codex y la extensión IDE comparten la misma configuración. Ver la documentación oficial.

[mcp_servers.iqx_lookup]
command = "npx"
args = ["-y", "@neivi/iqx-lookup-mcp-server@latest"]

[mcp_servers.iqx_lookup.env]
LOOKUP_API_KEY = "YOUR_API_KEY"

O añádelo desde la línea de comandos:

codex mcp add iqx_lookup --env LOOKUP_API_KEY=YOUR_API_KEY -- npx -y @neivi/iqx-lookup-mcp-server@latest

Verificar que funciona

Después de la configuración, pregunta a tu asistente:

"Valida el email test@example.com"

Deberías ver una llamada a la herramienta validate_email con el resultado de la validación.

Self-hosted / On-premises

Por defecto, el MCP server se conecta a https://api.iqxlookup.neivi.es. Para apuntarlo a una instancia de IQX Lookup auto-alojada, establece la variable de entorno LOOKUP_BASE_URL:

{
  "mcpServers": {
    "iqx-lookup": {
      "command": "npx",
      "args": ["-y", "@neivi/iqx-lookup-mcp-server@latest"],
      "env": {
        "LOOKUP_API_KEY": "YOUR_API_KEY",
        "LOOKUP_BASE_URL": "http://localhost:8081"
      }
    }
  }
}

Para Codex, añade LOOKUP_BASE_URL al bloque de entorno:

[mcp_servers.iqx_lookup]
command = "npx"
args = ["-y", "@neivi/iqx-lookup-mcp-server@latest"]

[mcp_servers.iqx_lookup.env]
LOOKUP_API_KEY = "YOUR_API_KEY"
LOOKUP_BASE_URL = "http://localhost:8081"

Tus datos nunca salen de tu red cuando usas una instancia local.

Herramientas disponibles

validate_email

Valida una dirección de email: sintaxis, registros DNS MX/A, detección de proveedores desechables, detección de direcciones de rol e identificación de proveedores de email gratuito.

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`address`	string	Sí	Dirección de email a validar (ej., `user@company.com`)

Ejemplo de respuesta:

{
  "email": "admin@gmail.com",
  "user": "admin",
  "domain": "gmail.com",
  "validFormat": true,
  "mxRecord": true,
  "aRecord": true,
  "roleAddress": true,
  "disposableEmail": false,
  "freeEmailProvider": true
}

validate_phone

Valida y analiza un número de teléfono: operador, tipo de línea (móvil/fijo/VoIP), formato E.164, ubicación y zona horaria.

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`number`	string	Sí	Número de teléfono en formato E.164 (`+34612345678`) o formato local (`612345678`)
`countryCode`	string	No	Código ISO 3166-1 alpha-2 (ej., `US`, `ES`). Obligatorio para números locales.

Ejemplo de respuesta:

{
  "valid": true,
  "number": "+34612345678",
  "e164Format": "+34612345678",
  "internationalFormat": "+34 612 34 56 78",
  "nationalFormat": "612 34 56 78",
  "countryCode": "ES",
  "country": "Spain",
  "carrier": "Movistar",
  "phoneType": "MOBILE",
  "location": "Spain",
  "timezones": ["Europe/Madrid"]
}

geolocate_ip

Geolocaliza una dirección IP: país, ciudad, coordenadas, ISP, ASN, zona horaria y pertenencia a la UE.

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`ip`	string	Sí	Dirección IPv4 o IPv6 (ej., `8.8.8.8` o `2001:4860:4860::8888`)

Ejemplo de respuesta:

{
  "ip": "8.8.8.8",
  "country": "United States",
  "countryCode": "US",
  "region": "California",
  "city": "Mountain View",
  "latitude": 37.386,
  "longitude": -122.0838,
  "timezone": "America/Los_Angeles",
  "isEu": false,
  "isp": "Google LLC",
  "organization": "Google Public DNS",
  "asn": "AS15169"
}

geolocate_my_ip

Geolocaliza la IP pública del propio servidor. Devuelve los mismos campos que geolocate_ip. No requiere parámetros.

validate_vat

Valida un número de IVA europeo contra el servicio VIES de la UE. Devuelve el nombre de la empresa y la dirección cuando están disponibles.

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`countryCode`	string	Sí	Código de país UE de dos letras (ej., `DE`, `FR`, `ES`)
`number`	string	Sí	Número de IVA sin prefijo de país (ej., para `ESB87387775` pasa `B87387775`)

Ejemplo de respuesta:

{
  "valid": true,
  "countryCode": "ES",
  "vatNumber": "B87387775",
  "name": "NEIVI IT SOCIEDAD LIMITADA",
  "address": "CL EXAMPLE 1\n28001 MADRID"
}

parse_useragent

Analiza una cadena User-Agent: navegador, SO, tipo de dispositivo, marca/modelo y detección de bots.

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`ua`	string	Sí	Cadena raw del header User-Agent

Ejemplo de respuesta:

{
  "browserFamily": "Chrome",
  "browserVersion": "125.0.0",
  "osFamily": "Mac OS X",
  "osVersion": "14.5.0",
  "deviceFamily": "Mac",
  "deviceBrand": "Apple",
  "deviceModel": "Mac"
}

validate_iban

Valida un IBAN: estructura (longitud por país), checksum MOD 97-10 e identificadores de banco/sucursal.

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`iban`	string	Sí	IBAN con o sin espacios (ej., `DE89 3704 0044 0532 0130 00`)

Ejemplo de respuesta:

{
  "valid": true,
  "iban": "DE89370400440532013000",
  "countryCode": "DE",
  "checkDigits": "89",
  "bankCode": "37040044",
  "branchCode": "",
  "accountNumber": "0532013000",
  "bic": "COBADEFFXXX"
}

validate_bic

Valida un código BIC/SWIFT: formato, nombre de la institución, país e información de sucursal.

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`bic`	string	Sí	Código BIC/SWIFT, 8 u 11 caracteres (ej., `COBADEFFXXX`)

Ejemplo de respuesta:

{
  "valid": true,
  "bic": "COBADEFFXXX",
  "bankCode": "COBA",
  "countryCode": "DE",
  "locationCode": "FF",
  "branchCode": "XXX",
  "institution": "Commerzbank AG"
}

lookup_dns

Consulta registros DNS de un dominio. También realiza análisis de seguridad de email: SPF, DKIM y DMARC.

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`domain`	string	Sí	Nombre de dominio (ej., `example.com`, sin protocolo)
`types`	string	No	Tipos de registro separados por coma: `A`, `AAAA`, `MX`, `TXT`, `CNAME`, `NS`, `SOA`. Omitir para todos.

Ejemplo de respuesta:

{
  "domain": "example.com",
  "records": [
    { "type": "A", "value": "93.184.216.34", "ttl": 3600 },
    { "type": "MX", "value": "mail.example.com", "priority": 10, "ttl": 3600 }
  ],
  "queryTimeMs": 45,
  "emailSecurity": {
    "spf": { "found": true, "record": "v=spf1 -all", "qualifier": "fail" },
    "dkim": { "found": false },
    "dmarc": { "found": true, "policy": "reject", "reportingEmail": "dmarc@example.com" }
  }
}

check_password_strength

Analiza la fortaleza de una contraseña (zxcvbn) y la verifica contra filtraciones conocidas vía Have I Been Pwned usando k-anonymity; la contraseña completa nunca se envía por la red, se registra ni se almacena.

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`password`	string	Sí	Contraseña a analizar (nunca se registra ni almacena)

Ejemplo de respuesta:

{
  "score": 3,
  "crackTimeDisplay": "centuries",
  "crackTimeSeconds": 3.15e+15,
  "guesses": 1.0e+13,
  "warning": "",
  "suggestions": ["Add another word or two. Uncommon words are better."],
  "breached": false,
  "breachCount": 0
}

check_ssl_certificate

Inspecciona el certificado SSL/TLS de un dominio: cadena de certificados, fechas de validez, SANs, protocolo, suite de cifrado y asigna un grado (A+ a F).

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`domain`	string	Sí	Nombre de dominio (ej., `github.com`). No incluir `https://`.

Ejemplo de respuesta:

{
  "issuer": "Let's Encrypt",
  "subject": "example.com",
  "serialNumber": "04:AB:CD:...",
  "validFrom": "2025-01-01T00:00:00Z",
  "validTo": "2025-04-01T00:00:00Z",
  "daysUntilExpiry": 78,
  "signatureAlgorithm": "SHA256withRSA",
  "subjectAlternativeNames": ["example.com", "www.example.com"],
  "protocol": "TLSv1.3",
  "cipherSuite": "TLS_AES_256_GCM_SHA384",
  "chainLength": 3,
  "grade": "A+",
  "warnings": []
}

validate_credit_card

Valida un número de tarjeta de crédito: algoritmo de Luhn, identificación de red de tarjeta, consulta BIN. Solo validación estructural; no procesa pagos. El número completo de la tarjeta nunca se devuelve en la respuesta.

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
`cardNumber`	string	Sí	Número de tarjeta con espacios/guiones opcionales (ej., `4111 1111 1111 1111`)

Ejemplo de respuesta:

{
  "valid": true,
  "luhnValid": true,
  "brand": "Visa",
  "lastFourDigits": "1111",
  "cardType": "CREDIT",
  "issuingBank": "Example Bank",
  "country": "US",
  "category": "CLASSIC"
}

Ejemplos de flujos de trabajo multi-herramienta

Los asistentes de IA pueden encadenar múltiples herramientas en una sola conversación. Estos son flujos de trabajo comunes:

Cualificación de leads

"Valida estos emails y dime cuáles son reales: sales@acme.com, info@temp-mail.org, john@bigcorp.io"

El asistente invoca validate_email tres veces y luego resume: cuáles son válidos, cuáles son desechables y cuáles son direcciones de rol.

Auditoría de seguridad de dominio

"Ejecuta una verificación de seguridad en example.com: certificado SSL y seguridad de email DNS"

El asistente invoca check_ssl_certificate + lookup_dns y luego sintetiza un informe cubriendo el grado del certificado, expiración y políticas SPF/DKIM/DMARC.

Verificación KYC

"Verifica esta empresa: VAT ES-B87387775, IBAN ES91 2100 0418 4502 0005 1332, teléfono +34 912 345 678"

El asistente invoca validate_vat + validate_iban + validate_phone, cruza los códigos de país e informa sobre la consistencia.

Evaluación de política de contraseñas

"Prueba estas contraseñas contra nuestra política: Welcome1, Tr0ub4dor&3, correct-horse-battery-staple"

El asistente invoca check_password_strength tres veces, compara puntuaciones, estado de filtraciones y tiempos de descifrado, y luego recomienda cuáles cumplen tus requisitos.

Buenas prácticas

Agrupa validaciones relacionadas — describe todos los datos que quieras validar en un solo mensaje. El asistente invocará múltiples herramientas de forma eficiente.
Números de IVA — elimina siempre el prefijo de país antes de llamar. Pasa ES como countryCode y B87387775 como number, no ESB87387775.
Vista completa de DNS — usa types=A,MX,TXT para una consulta enfocada, u omite types para obtener todos los tipos de registro.
Límites de tasa — cada respuesta de herramienta incluye información de límite de tasa restante. La IA puede auto-regularse al acercarse a los límites.
Privacidad — las contraseñas y números de tarjeta de crédito nunca se registran ni almacenan. Las verificaciones de filtraciones de contraseñas usan k-anonymity (solo se envía un prefijo de hash a HIBP). Las respuestas de tarjetas de crédito nunca incluyen el número completo.

Manejo de errores

Cuando una llamada a una herramienta falla, el MCP server devuelve un error estructurado. Códigos de error comunes:

Código	Error	Significado
`401`	`UNAUTHORIZED`	API key ausente o inválida
`429`	`RATE_LIMIT_EXCEEDED`	Demasiadas solicitudes por minuto
`429`	`QUOTA_EXCEEDED`	Cuota mensual de solicitudes agotada
`503`	`UPSTREAM_UNAVAILABLE`	Servicio externo (VIES, HIBP, etc.) temporalmente caído

Ejemplo de respuesta de error:

{
  "error": "Rate limit exceeded",
  "retryAfter": 42,
  "status": 429
}

El asistente de IA normalmente esperará y reintentará automáticamente, o te informará de que se ha alcanzado el límite de tasa.

¿Por qué MCP?​

Configuración​

Requisitos previos​

Claude Desktop / Claude Code​

Cursor / Windsurf​

Codex​

Verificar que funciona​

Self-hosted / On-premises​

Herramientas disponibles​

validate_email​

validate_phone​

geolocate_ip​

geolocate_my_ip​

validate_vat​

parse_useragent​

validate_iban​

validate_bic​

lookup_dns​

check_password_strength​

check_ssl_certificate​

validate_credit_card​

Ejemplos de flujos de trabajo multi-herramienta​

Cualificación de leads​

Auditoría de seguridad de dominio​

Verificación KYC​

Evaluación de política de contraseñas​

Buenas prácticas​

Manejo de errores​

¿Por qué MCP?

Configuración

Requisitos previos

Claude Desktop / Claude Code

Cursor / Windsurf

Codex

Verificar que funciona

Self-hosted / On-premises

Herramientas disponibles

validate_email

validate_phone

geolocate_ip

geolocate_my_ip

validate_vat

parse_useragent

validate_iban

validate_bic

lookup_dns

check_password_strength

check_ssl_certificate

validate_credit_card

Ejemplos de flujos de trabajo multi-herramienta

Cualificación de leads

Auditoría de seguridad de dominio

Verificación KYC

Evaluación de política de contraseñas

Buenas prácticas

Manejo de errores