MCP Server

El MCP Server de IQX Lookup permite a los asistentes de IA (Claude, Cursor, Windsurf, Codex, etc.) invocar las 12 herramientas de validacion de forma nativa a traves del Model Context Protocol. Un solo comando npx, sin paso de compilacion, sin codigo de cliente HTTP, sin parseo de JSON.

Por que MCP?

La integracion tradicional con una API requiere configurar un cliente HTTP, headers de autenticacion, serializacion JSON y manejo de errores. Con MCP, el asistente de IA invoca las herramientas de validacion 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.

Configuracion

Requisitos previos

Node.js 18+
Una API key del dashboard

Claude Desktop / Claude Code

Anade lo siguiente a tu configuracion 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 configuracion en el archivo de configuracion MCP de tu editor (.cursor/mcp.json o equivalente).

Codex

Codex usa config.toml para la configuracion 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 extension IDE comparten la misma configuracion. Ver la documentacion 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 anadelo desde la linea 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

Despues de la configuracion, pregunta a tu asistente:

"Valida el email test@example.com"

Deberias ver una llamada a la herramienta validate_email con el resultado de la validacion.

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, anade 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 direccion de email: sintaxis, registros DNS MX/A, deteccion de proveedores desechables, deteccion de direcciones de rol e identificacion de proveedores de email gratuito.

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
`address`	string	Si	Direccion 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 numero de telefono: operador, tipo de linea (movil/fijo/VoIP), formato E.164, ubicacion y zona horaria.

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
`number`	string	Si	Numero de telefono en formato E.164 (`+34612345678`) o formato local (`612345678`)
`countryCode`	string	No	Codigo ISO 3166-1 alpha-2 (ej., `US`, `ES`). Obligatorio para numeros 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 direccion IP: pais, ciudad, coordenadas, ISP, ASN, zona horaria y pertenencia a la UE.

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
`ip`	string	Si	Direccion 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 publica del propio servidor. Devuelve los mismos campos que geolocate_ip. No requiere parametros.

validate_vat

Valida un numero de IVA europeo contra el servicio VIES de la UE. Devuelve el nombre de la empresa y la direccion cuando estan disponibles.

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
`countryCode`	string	Si	Codigo de pais UE de dos letras (ej., `DE`, `FR`, `ES`)
`number`	string	Si	Numero de IVA sin prefijo de pais (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 deteccion de bots.

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
`ua`	string	Si	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 pais), checksum MOD 97-10 e identificadores de banco/sucursal.

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
`iban`	string	Si	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 codigo BIC/SWIFT: formato, nombre de la institucion, pais e informacion de sucursal.

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
`bic`	string	Si	Codigo 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. Tambien realiza analisis de seguridad de email: SPF, DKIM y DMARC.

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
`domain`	string	Si	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 contrasena (zxcvbn) y la verifica contra filtraciones conocidas via Have I Been Pwned usando k-anonymity; la contrasena completa nunca se envia por la red, se registra ni se almacena.

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
`password`	string	Si	Contrasena 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).

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
`domain`	string	Si	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 numero de tarjeta de credito: algoritmo de Luhn, identificacion de red de tarjeta, consulta BIN. Solo validacion estructural; no procesa pagos. El numero completo de la tarjeta nunca se devuelve en la respuesta.

Parametros:

Parametro	Tipo	Obligatorio	Descripcion
`cardNumber`	string	Si	Numero 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 multiples herramientas en una sola conversacion. Estos son flujos de trabajo comunes:

Cualificacion de leads

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

El asistente invoca validate_email tres veces y luego resume: cuales son validos, cuales son desechables y cuales son direcciones de rol.

Auditoria de seguridad de dominio

"Ejecuta una verificacion 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, expiracion y politicas SPF/DKIM/DMARC.

Verificacion KYC

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

El asistente invoca validate_vat + validate_iban + validate_phone, cruza los codigos de pais e informa sobre la consistencia.

Evaluacion de politica de contrasenas

"Prueba estas contrasenas contra nuestra politica: 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 cuales cumplen tus requisitos.

Buenas practicas

Agrupa validaciones relacionadas — describe todos los datos que quieras validar en un solo mensaje. El asistente invocara multiples herramientas de forma eficiente.
Numeros de IVA — elimina siempre el prefijo de pais 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.
Limites de tasa — cada respuesta de herramienta incluye informacion de limite de tasa restante. La IA puede auto-regularse al acercarse a los limites.
Privacidad — las contrasenas y numeros de tarjeta de credito nunca se registran ni almacenan. Las verificaciones de filtracion de contrasenas usan k-anonymity (solo se envia un prefijo de hash a HIBP). Las respuestas de tarjetas de credito nunca incluyen el numero completo.

Manejo de errores

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

Codigo	Error	Significado
`401`	`UNAUTHORIZED`	API key ausente o invalida
`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 caido

Ejemplo de respuesta de error:

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

El asistente de IA normalmente esperara y reintentara automaticamente, o te informara de que se ha alcanzado el limite de tasa.

Por que MCP?​

Configuracion​

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​

Cualificacion de leads​

Auditoria de seguridad de dominio​

Verificacion KYC​

Evaluacion de politica de contrasenas​

Buenas practicas​

Manejo de errores​

Por que MCP?

Configuracion

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

Cualificacion de leads

Auditoria de seguridad de dominio

Verificacion KYC

Evaluacion de politica de contrasenas

Buenas practicas

Manejo de errores