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
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.
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.
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 listClaude 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_plansEncuentra 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
| Name | Type | Required |
|---|---|---|
| country | string | optional |
| limit | integer | optional |
list_covered_countriesLista cada país y región que cubre la eSIM de viaje, cada uno con un precio desde. No recibe argumentos.
get_uk_number_infoExplica 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_statusConsulta un pedido por su código corto. Devuelve solo el estado, nunca datos personales.
Parameters
| Name | Type | Required |
|---|---|---|
| code | string | required |
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_walletCrea 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
| Name | Type | Required |
|---|---|---|
| label | string | optional |
check_balanceDevuelve el saldo actual del monedero en USD.
create_depositInicia 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
| Name | Type | Required |
|---|---|---|
| amount_usd | number | required |
| coin | string | optional |
list_transactionsLista el historial de transacciones del monedero - depósitos y compras.
purchase_esimLiveCompra 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
| Name | Type | Required |
|---|---|---|
| package_code | string | required |
| request_id | string | optional |
purchase_uk_numberLiveCompra 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
| Name | Type | Required |
|---|---|---|
| request_id | string | optional |
get_one_time_codeLivePoll 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
| Name | Type | Required |
|---|---|---|
| order_id | integer | required |
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_YOURKEYModelo 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-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.
# 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. 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.
