Servidor MCP

Zelnum ofrece un servidor MCP público en https://mcp.zelnum.com/mcp. Cualquier cliente compatible con MCP — Claude, Cursor, un agente de tu IDE — puede listar productos, consultar el precio de una verificación, ejecutarla y leer el resultado sin escribir código de integración. Una sola URL sirve a todos los clientes: te conectas con tu propia clave de API y cada cargo se descuenta de tu propio saldo.

Punto de acceso

Ajuste	Valor
URL	https://mcp.zelnum.com/mcp
Transporte	Streamable HTTP
Credenciales	Authorization: Bearer YOUR_KEY_HERE

La credencial es la misma clave de API que usan tus llamadas REST. Créala, renuévala y revócala en API Center de la consola.

Conectar un cliente

Tres pasos y nada que instalar.

1. Crea una clave. Genera una clave de API en API Center de la consola — la misma que usan tus llamadas REST. Consulta Authentication.

2. Añade el servidor. Cursor y otros clientes que leen el mapa estándar mcpServers pueden usar esta entrada tal cual:

{
  "mcpServers": {
    "zelnum": {
      "url": "https://mcp.zelnum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY_HERE"
      }
    }
  }
}

Claude recibe esos mismos dos valores en su diálogo de conector personalizado — la URL y una cabecera Authorization con tu clave.

3. Comprueba la conexión. Pide al agente que diga qué productos en tiempo real puede verificar. Si la conexión funciona, responderá llamando a list_products, que es de solo lectura y gratis, así que la comprobación no cuesta nada. Un 401 significa en cambio que la clave falta, está revocada o la plataforma no la acepta.

Herramientas

Herramienta	Qué hace	Con cargo
list_products	Catálogo de productos activos con ID, slug y serie. Solo lectura.	No
get_balance	Saldo de la cuenta con la que se autentica la conexión. Solo lectura.	No
quote_realtime_check	Precio oficial de una verificación. La única fuente de precios en la que un agente debería confiar.	Gratis
check_realtime	Ejecuta una verificación en tiempo real contra un máximo de diez productos.	Sí
create_bulk_task	Envía una lista en línea para una tarea masiva asíncrona.	Sí
get_task_status	Progreso y contadores de facturación de una tarea masiva.	No
get_task_result	Metadatos del resultado y enlace de descarga autenticado de una tarea terminada.	No

Lo que puedes decirle

Esas son las herramientas; estas son las frases que escribes tú. Todas las atiende una herramienta que ya existe — ninguna redacción está tratada como caso especial.

Di esto	Qué ocurre
¿Qué productos puedo verificar en tiempo real?	Llama a list_products y responde con los ID que debes usar. Gratis.
¿Cuál es mi saldo?	Llama a get_balance para la clave con la que te conectaste. Gratis.
¿Cuánto costaría verificar +14155550123 en WhatsApp?	Llama a quote_realtime_check y muestra el precio. Gratis, y no se cobra nada.
Adelante, a ese precio.	Llama a check_realtime con los productos del presupuesto y cobra el importe presupuestado.
Verifica estos 200 números en WhatsApp y avísame cuando termine.	Llama a create_bulk_task y luego consulta get_task_status para informar del progreso.
¿Ya terminó esa tarea? Mándame el enlace de descarga.	Llama a get_task_result y devuelve el enlace autenticado.

Dos hábitos que conviene mantener:

• Pregunta el precio primero. Toda herramienta con cargo responde con un presupuesto antes de cobrar, así que preguntar cuánto cuesta es siempre gratis. Solo la confirmación mueve dinero.
• Indica el campo country cuando el número no sea E.164. +14155550123 ya lleva su país; 0812345678 no, y la pasarela se niega a adivinarlo.

Confirmar un cargo

Una herramienta con cargo nunca cobra en su primera llamada. Si se invoca sin confirmed, devuelve en su lugar un payload de confirmación — los productos, la cantidad y el coste estimado — junto con un quote_token que firma la entrada exacta. Confirma repitiendo la misma llamada con:

1. confirmed en true
2. el quote_token de ese payload
3. quoted_total, exactamente el importe que se te mostró
4. el mismo identificador, los mismos productos y el mismo campo country

Un agente nunca aporta su propia clave de idempotencia: la pasarela la deriva del presupuesto firmado, así que un mismo presupuesto aprobado conserva la misma clave entre reintentos, reconexiones y reinicios de la pasarela. Un cargo distinto exige un presupuesto nuevo. Ante un tiempo de espera agotado que deje el resultado sin determinar, repite la llamada idéntica en lugar de cambiar parámetros.

Nunca confirmes en silencio

Un agente debe mostrar el coste estimado y obtener una aprobación explícita antes de activar la marca de confirmación. Un presupuesto caduca a los cinco minutos, y un presupuesto cuyo precio de referencia se ha movido se rechaza en lugar de cobrarse al precio nuevo.

Identificadores

Las reglas de identificador reproducen el contrato REST, así que lo que un agente valida es lo que la API acepta:

• Sin el campo country — el identificador debe ser un número E.164 con prefijo +.
• Con el campo country — un código ISO de dos letras en mayúsculas; el identificador es entonces el número nacional o un número E.164.
• El país nunca se deduce de un número nacional ambiguo como 0812345678, que coincide con varios países. Omite el campo country solo cuando el número ya sea un E.164 completo.
• Las tareas masivas sobre productos de teléfono exigen el campo country de forma explícita.

Barreras de dinero

Cuatro barreras se interponen entre un agente y tu saldo:

1. Presupuestos firmados. La plataforma lee los precios en vivo y devuelve un presupuesto cifrado que vincula la cuenta, la entrada exacta, los productos y la instantánea de precios. Una entrada modificada, un presupuesto caducado o un precio que se ha movido se rechazan antes de facturar nada.
2. Idempotencia determinista. La clave de idempotencia procede del presupuesto firmado y no del modelo, de modo que ninguna redacción de una petición puede convertir una aprobación en dos cargos.
3. Límites por clave. Un techo de gasto diario y un suelo de saldo se aplican por clave de API, y cada reserva se serializa antes de la llamada al proveedor, así que los agentes concurrentes no pueden saltárselos.
4. Fallo cerrado. Si el saldo no puede leerse o llega malformado, las llamadas con cargo se rechazan en lugar de ejecutarse sin protección.

Errores y límites

• Una credencial ausente o malformada se rechaza con HTTP 401 antes de que la petición llegue a la plataforma.
• Una clave que la plataforma no acepta vuelve como error de herramienta con el estado y el cuerpo del proveedor, de modo que el agente lo reporta en lugar de reintentar a ciegas.
• Los límites de peticiones, los códigos de error y la descarga de resultados se comportan igual que sobre REST — la pasarela no añade un segundo contrato que aprender.

Siguientes pasos

• Authentication — crea la clave con la que te conectarás.
• Realtime check — el endpoint detrás de check_realtime.
• Bulk workflow — la ruta asíncrona detrás de create_bulk_task.
• Error codes — los códigos que devuelve la plataforma.