Inicio
Para asistentes de IA · servidor MCP

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/mcp

Qué 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.io

Inicio rápido

Añade BuyUKeSIM a la configuración MCP de tu agente de IA:

{
  "mcpServers": {
    "buyukesim": {
      "type": "streamableHttp",
      "url": "https://buyukesim.com/mcp"
    }
  }
}

Ya está. Tu agente ya puede buscar planes, cobertura y precios en 190+ países. No hace falta clave API para explorar.

¿Comprar también? Crea un agent wallet gratis (un saldo prepago financiado con cripto), copia su clave ak_live_ y añádela como cabecera Authorization: Bearer - o usa la URL /mcp/ak_live_…. Eso activa las herramientas de compra, saldo y pedidos.

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étodoEndpointPropósito
POSThttps://buyukesim.com/mcpEndpoint MCP principal. Todas las llamadas JSON-RPC (initialize, tools/list, tools/call) van aquí como POST.
GEThttps://buyukesim.com/mcpNo es una petición MCP válida - devuelve 405 Method Not Allowed. Usa POST.
POSThttps://buyukesim.com/mcp/ak_live_YOURKEYForma 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.

Claude Code (CLI)

# 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 list

Claude Desktop

Settings  ->  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).

ChatGPT

Settings  ->  Connectors  ->  Add  (Developer mode)

  Name:           buyukesim
  MCP server URL: https://buyukesim.com/mcp

Public browse tools are available immediately.

Cursor

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "buyukesim": {
      "type": "streamableHttp",
      "url": "https://buyukesim.com/mcp",
      "headers": {
        "Authorization": "Bearer ak_live_YOURKEY"
      }
    }
  }
}

VS Code (GitHub Copilot)

// .vscode/mcp.json
{
  "servers": {
    "buyukesim": {
      "type": "http",
      "url": "https://buyukesim.com/mcp",
      "headers": {
        "Authorization": "Bearer ak_live_YOURKEY"
      }
    }
  }
}

Gemini CLI

// ~/.gemini/settings.json
{
  "mcpServers": {
    "buyukesim": {
      "httpUrl": "https://buyukesim.com/mcp",
      "headers": {
        "Authorization": "Bearer ak_live_YOURKEY"
      }
    }
  }
}

Windsurf / Cline / Zed

// 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_plans

Encuentra 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.

Parameters

NameTypeRequired
countrystringoptional
limitintegeroptional
list_covered_countries

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

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_status

Consulta un pedido por su código corto. Devuelve solo el estado, nunca datos personales.

Parameters

NameTypeRequired
codestringrequired

Herramientas de monedero autenticadas

Estas necesitan una clave ak_live_. El monedero es prepago y se financia con cripto - 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.

create_wallet

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.

Parameters

NameTypeRequired
labelstringoptional
check_balance

Devuelve el saldo actual del monedero en USD.

create_deposit

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.

Parameters

NameTypeRequired
amount_usdnumberrequired
coinstringoptional
list_transactions

Lista el historial de transacciones del monedero - depósitos y compras.

purchase_esimLive

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.

Parameters

NameTypeRequired
package_codestringrequired
request_idstringoptional
purchase_uk_numberLive

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.

Parameters

NameTypeRequired
request_idstringoptional
get_one_time_codeLive

Poll a purchased One-Time Code for its SMS code. Returns the number, then the verification code once it lands (phase: waiting_code / code_ready / failed). Call every few seconds.

Parameters

NameTypeRequired
order_idintegerrequired

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_YOURKEY

2X-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_YOURKEY

3Key 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_YOURKEY

Modelo de seguridad

La cartera del agente está diseñada para que una clave expuesta cause un daño limitado y recuperable.

  • 1Autentícate con la cabecera Authorization: Bearer (o X-API-Key). Prefiere las cabeceras a poner la clave en una URL, para que nunca acabe en los registros de acceso.
  • 2Rota o revoca tu api_key en cualquier momento desde el panel de la cartera. Se emite una clave nueva al instante y la anterior deja de funcionar, así que una clave filtrada es fácil de anular sin perder tu saldo.
  • 3El saldo es prepago y solo puede gastarse en eSIM - nunca puede retirarse. Una clave comprometida no puede mover fondos a un atacante; el peor caso está limitado por el saldo que cargaste.
  • 4Las compras son idempotentes: pasa un request_id estable y un reintento devuelve el mismo pedido en lugar de cobrar dos veces. Los cargos se aplican de forma atómica con un bloqueo de fila, así que no hay doble gasto.
  • 5Nunca pedimos identidad: sin KYC, sin cuenta, sin datos personales ligados a la cartera o sus pedidos.

Ejemplos

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-4821

5. 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.
# 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);
Ejemplos ejecutables en GitHub

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ódigoSignificado
-32700Error de análisis - el cuerpo de la petición no era JSON válido.
-32600Petición inválida - el JSON no es una petición JSON-RPC 2.0 válida.
-32601Método no encontrado - método desconocido, o un nombre de herramienta que no existe.
-32602Parámetros inválidos - se llamó a una herramienta con argumentos faltantes o de tipo incorrecto.
-32603Error 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. 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.

@buyukesimbot

Endpoint: JSON-RPC 2.0 sobre HTTP POST (Streamable HTTP), versión de protocolo 2025-06-18. URL base https://buyukesim.com/mcp.