Servidor MCP de BuyUKeSIM
BuyUKeSIM tiene un servidor MCP (Model Context Protocol), así que cualquier asistente de IA compatible - Claude, ChatGPT, Cursor, VS Code Copilot, Gemini CLI y otros - puede trabajar con nuestro catálogo de eSIM directamente. Apunta tu asistente a un endpoint y podrá buscar planes, listar cobertura, explicar el Número UK y consultar un pedido, todo en lenguaje natural.
Las herramientas públicas no necesitan clave y no mueven dinero. Un segundo conjunto, autenticado, añade un monedero de agente prepago financiado en cripto, para que un asistente pueda cargar saldo y comprar una eSIM de viaje/datos en tu nombre. Sin cuenta, sin KYC. Esta página es la referencia completa: endpoints, configuración por cliente, cada herramienta, autenticación, ejemplos ejecutables, manejo de errores y preguntas frecuentes.
Endpoint base
https://buyukesim.com/mcpQué es MCP
El Model Context Protocol (MCP) es un estándar abierto para conectar asistentes de IA con herramientas y datos externos. En lugar de copiar y pegar o crear un plugin a medida, el asistente habla un único protocolo con cualquier servidor compatible y descubre las herramientas que este expone.
Nuestro servidor implementa MCP sobre Streamable HTTP con JSON-RPC 2.0, versión de protocolo 2025-06-18. En la práctica es un endpoint HTTPS que acepta peticiones POST. El asistente llama a initialize, luego a tools/list para conocer lo disponible, y luego a tools/call para ejecutar una herramienta. Casi nunca lo haces a mano: tu cliente MCP lo hace por ti.
Lee la especificación de MCP en modelcontextprotocol.ioInicio rápido
El camino más rápido es Claude Code. Un comando añade el servidor con las herramientas públicas de exploración - sin clave, sin archivo de configuración:
claude mcp add --transport http buyukesim https://buyukesim.com/mcpYa está. Pídele a tu asistente algo como "busca planes eSIM del Reino Unido" y llamará a las herramientas. Para otros clientes, mira Configuración del cliente más abajo. Para usar las herramientas de monedero, añade tu clave como cabecera Bearer (ver Autenticación).
Endpoints
Hay un único endpoint MCP. Las peticiones son HTTP POST con cuerpos JSON-RPC. Un GET simple no es una petición MCP válida y devuelve 405. Por comodidad, también puedes incrustar tu clave directamente en la ruta de la URL.
| Método | Endpoint | Propósito |
|---|---|---|
| POST | https://buyukesim.com/mcp | Endpoint MCP principal. Todas las llamadas JSON-RPC (initialize, tools/list, tools/call) van aquí como POST. |
| GET | https://buyukesim.com/mcp | No es una petición MCP válida - devuelve 405 Method Not Allowed. Usa POST. |
| POST | https://buyukesim.com/mcp/ak_live_YOURKEY | Forma con clave en la URL. Mismo endpoint, pero tu clave API va en la ruta, así que no hace falta cabecera. |
Configuración del cliente
Usa la misma URL base en todas partes: https://buyukesim.com/mcp. La exploración pública no necesita clave. Para las herramientas de monedero, añade una cabecera Authorization: Bearer ak_live_YOURKEY (o usa uno de los otros métodos de abajo). Sustituye ak_live_YOURKEY por una clave de create_wallet.
# Public tools (browsing, no key)
claude mcp add --transport http buyukesim https://buyukesim.com/mcp
# Authenticated (wallet) - pass your key as a Bearer header
claude mcp add --transport http buyukesim https://buyukesim.com/mcp \
--header "Authorization: Bearer ak_live_YOURKEY"
# Verify
claude mcp listSettings -> Connectors -> Add custom connector
Name: buyukesim
URL: https://buyukesim.com/mcp
Public tools work with no key. For the wallet tools,
use a client that lets you send an Authorization header
(Claude Code, Cursor, VS Code, Gemini CLI).Settings -> Connectors -> Add (Developer mode)
Name: buyukesim
MCP server URL: https://buyukesim.com/mcp
Public browse tools are available immediately.// ~/.cursor/mcp.json
{
"mcpServers": {
"buyukesim": {
"type": "streamableHttp",
"url": "https://buyukesim.com/mcp",
"headers": {
"Authorization": "Bearer ak_live_YOURKEY"
}
}
}
}// .vscode/mcp.json
{
"servers": {
"buyukesim": {
"type": "http",
"url": "https://buyukesim.com/mcp",
"headers": {
"Authorization": "Bearer ak_live_YOURKEY"
}
}
}
}// ~/.gemini/settings.json
{
"mcpServers": {
"buyukesim": {
"httpUrl": "https://buyukesim.com/mcp",
"headers": {
"Authorization": "Bearer ak_live_YOURKEY"
}
}
}
}// mcpServers block (Windsurf, Cline, Zed and similar)
{
"mcpServers": {
"buyukesim": {
"serverUrl": "https://buyukesim.com/mcp"
}
}
}
// Fallback for stdio-only clients, via the mcp-remote bridge:
npx mcp-remote https://buyukesim.com/mcp \
--header "Authorization: Bearer ak_live_YOURKEY"Herramientas públicas
Cuatro herramientas de solo lectura. Sin clave, sin movimiento de dinero - seguras para exponer a cualquier asistente.
search_esim_planscountry?: string (2-letter ISO), limit?: intEncuentra planes eSIM de viaje/datos para un país. Devuelve cantidad de datos, validez en días, precio en USD y el package_code que pasas a purchase_esim. country es un código ISO de 2 letras (por ejemplo GB); limit acota los resultados.
list_covered_countries(none)Lista cada país y región que cubre la eSIM de viaje, cada uno con un precio desde. No recibe argumentos.
get_uk_number_info(none)Explica la eSIM de Número UK (+44) - un número móvil británico real para SMS de verificación y llamadas. No recibe argumentos.
check_order_statuscode: stringConsulta un pedido por su código corto. Devuelve solo el estado, nunca datos personales.
Herramientas de monedero autenticadas
Estas necesitan una clave ak_live_. El monedero es prepago y se financia con cripto (vía NOWPayments) - sin cuenta, sin KYC. Llama a create_wallet una vez para acuñar una clave, recárgalo con create_deposit y luego compra con purchase_esim.
| Herramienta | Parámetros | Propósito |
|---|---|---|
create_wallet | label?: string -> returns api_key + wallet_code | Crea un nuevo monedero de agente y devuelve su api_key (secreta) y wallet_code. Es la única herramienta de monedero que no requiere clave por sí misma - acuña una. Guarda la api_key de forma segura. |
check_balance | (none) | Devuelve el saldo actual del monedero en USD. |
create_deposit | amount_usd: number (min 10), coin?: string | Inicia una recarga en cripto. amount_usd es el depósito (mínimo 10). coin es opcional, por ejemplo usdttrc20, btc, eth o trx. Devuelve una dirección/enlace de pago; el saldo se acredita cuando el depósito se confirma. |
list_transactions | (none) | Lista el historial de transacciones del monedero - depósitos y compras. |
purchase_esim | package_code: string, request_id?: string | Compra una eSIM de viaje/datos con el saldo del monedero. package_code viene de search_esim_plans. Esto está EN VIVO y gasta saldo real. Pasa un request_id para hacerlo idempotente, así un reintento nunca cobra dos veces. Devuelve el código QR de la eSIM. |
purchase_uk_number | request_id?: string | Compra una eSIM de Número UK (+44) de stock por unos 25 USD con el saldo del monedero. Esto está EN VIVO y devuelve el QR al instante. Pasa un request_id para hacerlo idempotente, así un reintento nunca cobra dos veces. |
El saldo solo puede gastarse en eSIM - nunca es retirable a efectivo ni a cripto. Es deliberado: es un saldo de gasto para un agente, no un exchange.
Autenticación
Las herramientas públicas no necesitan nada. Las de monedero necesitan tu clave ak_live_, que obtienes de create_wallet. Hay tres formas equivalentes de enviarla - elige la que soporte tu cliente.
1Authorization header (recommended)
Envía una cabecera estándar de token Bearer. Funciona en Claude Code (--header), Cursor, VS Code, Gemini CLI y cURL. Es el método recomendado.
Authorization: Bearer ak_live_YOURKEY2X-API-Key header
Envía la clave en una cabecera X-API-Key en su lugar. Útil para clientes que exponen cabeceras propias pero no auth Bearer.
X-API-Key: ak_live_YOURKEY3Key in the URL path
Pon la clave directamente en la ruta de la URL. Práctico para clientes que solo aceptan una URL y no cabeceras. Trata esa URL como secreta, ya que la clave va en ella.
https://buyukesim.com/mcp/ak_live_YOURKEYEjemplos
cURL para copiar y pegar del flujo completo. Fíjate en la cabecera Accept: MCP sobre Streamable HTTP requiere Accept: application/json, text/event-stream. Cada id es solo un identificador de petición que tú eliges.
1. Inicializa la sesión (handshake).
curl -s https://buyukesim.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": { "name": "curl", "version": "1.0" }
}
}'2. Lista las herramientas disponibles.
curl -s https://buyukesim.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'3. Busca planes del Reino Unido (GB), público - sin clave.
curl -s https://buyukesim.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "search_esim_plans",
"arguments": { "country": "GB", "limit": 5 }
}
}'4. Crea un monedero y recibe una clave.
# No key needed - this call mints one. Save the api_key it returns.
curl -s https://buyukesim.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "create_wallet",
"arguments": { "label": "my-agent" }
}
}'
# Result contains, for example:
# api_key: ak_live_9f3c... (store this secret)
# wallet_code: WLT-48215. Consulta el saldo (auth Bearer).
curl -s https://buyukesim.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer ak_live_YOURKEY" \
-d '{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": { "name": "check_balance", "arguments": {} }
}'6. Inicia un depósito en cripto.
curl -s https://buyukesim.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer ak_live_YOURKEY" \
-d '{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "create_deposit",
"arguments": { "amount_usd": 20, "coin": "usdttrc20" }
}
}'
# Returns a crypto payment address / link (NOWPayments).
# Balance is credited once the deposit confirms on-chain.7. Compra una eSIM (en vivo, idempotente).
curl -s https://buyukesim.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer ak_live_YOURKEY" \
-d '{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "purchase_esim",
"arguments": {
"package_code": "GB_5GB_30D",
"request_id": "order-2026-07-10-001"
}
}
}'
# LIVE: spends wallet balance and returns the eSIM QR code.
# request_id makes it idempotent - retrying never double-charges.8. Compra un número UK +44 (en vivo, idempotente).
curl -s https://buyukesim.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer ak_live_YOURKEY" \
-d '{
"jsonrpc": "2.0",
"id": 8,
"method": "tools/call",
"params": {
"name": "purchase_uk_number",
"arguments": { "request_id": "uknum-2026-07-10-001" }
}
}'
# LIVE: buys a UK +44 Number eSIM from stock (~25 USD) and
# returns the QR instantly. request_id makes it idempotent.Python, con el cliente oficial mcp y el transporte Streamable HTTP:
# pip install mcp
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
URL = "https://buyukesim.com/mcp"
HEADERS = {"Authorization": "Bearer ak_live_YOURKEY"} # omit for public tools
async def main():
async with streamablehttp_client(URL, headers=HEADERS) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
print([t.name for t in tools.tools])
result = await session.call_tool(
"search_esim_plans", {"country": "GB", "limit": 5}
)
print(result.content)
asyncio.run(main())Node.js, con el oficial @modelcontextprotocol/sdk:
// npm i @modelcontextprotocol/sdk
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const transport = new StreamableHTTPClientTransport(
new URL("https://buyukesim.com/mcp"),
{ requestInit: { headers: { Authorization: "Bearer ak_live_YOURKEY" } } } // omit for public
);
const client = new Client({ name: "buyukesim-demo", version: "1.0.0" });
await client.connect(transport);
const tools = await client.listTools();
console.log(tools.tools.map((t) => t.name));
const res = await client.callTool({
name: "search_esim_plans",
arguments: { country: "GB", limit: 5 },
});
console.log(res.content);Manejo de errores
Los problemas a nivel de protocolo vuelven como errores estándar JSON-RPC 2.0 con un código numérico y un mensaje. Estos son los que verás:
| Código | Significado |
|---|---|
-32700 | Error de análisis - el cuerpo de la petición no era JSON válido. |
-32600 | Petición inválida - el JSON no es una petición JSON-RPC 2.0 válida. |
-32601 | Método no encontrado - método desconocido, o un nombre de herramienta que no existe. |
-32602 | Parámetros inválidos - se llamó a una herramienta con argumentos faltantes o de tipo incorrecto. |
-32603 | Error interno - algo falló de nuestro lado al procesar la llamada. |
Los fallos a nivel de herramienta son distintos. Una herramienta que se ejecuta pero no puede completarse (por ejemplo, saldo insuficiente o un package_code desconocido) no lanza un error JSON-RPC. Devuelve un resultado normal con isError: true y un mensaje legible en el contenido de texto, para que tu asistente pueda leerlo y explicarlo.
En vivo vs. próximamente
Siendo francos: comprar está EN VIVO. purchase_esim para eSIM de viaje/datos de verdad gasta saldo del monedero y devuelve un código QR funcional, y purchase_uk_number ahora hace lo mismo con la eSIM de Número UK (+44) - compra una de stock por unos 25 USD y devuelve el QR al instante. La herramienta get_uk_number_info sigue describiendo el producto; purchase_uk_number es la que realmente lo compra.
Otro límite honesto: ningún asistente puede instalar la eSIM por ti. Instalar significa escanear o tocar el perfil QR en tu propio teléfono. El asistente puede encontrar el plan, comprarlo y entregarte el QR - la instalación final siempre es tuya.
Preguntas frecuentes
¿Esto es dinero real?
Las herramientas públicas no mueven dinero. Las de monedero sí: create_deposit financia un saldo prepago real en cripto, y purchase_esim lo gasta de verdad. Todo lo de solo lectura es gratis.
¿El asistente puede instalar la eSIM por mí?
No. Puede buscar, comprar y devolver el código QR, pero instalar significa escanear el QR en tu propio dispositivo. Ese paso final siempre es tuyo.
¿De verdad es sin KYC?
Sí. Sin cuenta y sin verificación de identidad. Creas un monedero, lo financias con cripto y lo gastas en eSIM.
¿Mi saldo está seguro? ¿Puedo retirarlo?
El saldo solo puede gastarse en eSIM - nunca es retirable a efectivo ni a cripto. Es un saldo de gasto para un agente, no un monedero del que sacar dinero.
¿Y los números UK?
get_uk_number_info explica la eSIM de Número UK (+44), y purchase_uk_number ahora compra una de stock por unos 25 USD con el saldo de tu monedero, devolviendo el QR al instante. Está en vivo y es idempotente vía request_id, igual que purchase_esim.
¿Cómo funciona la idempotencia?
Pasa un request_id estable a purchase_esim. Si se reintenta el mismo request_id, la compra no se repite, así un reintento de red nunca cobra dos veces.
¿Qué monedas puedo depositar?
Comunes como usdttrc20, btc, eth y trx vía NOWPayments. El depósito mínimo es 10 USD. Omite coin para que se te ofrezca elegir.
¿Tengo que ejecutar algún servidor?
No. Es un endpoint HTTP alojado. Añade la URL a tu cliente y listo - nada que instalar ni autoalojar.
Soporte
¿Preguntas, un problema con una clave o algo que no se comporta bien? Escríbenos por Telegram a @buyukesimbot y te ayudamos.
@buyukesimbotEndpoint: JSON-RPC 2.0 sobre HTTP POST (Streamable HTTP), versión de protocolo 2025-06-18. URL base https://buyukesim.com/mcp.
