На главную
Для ИИ-ассистентов · MCP-сервер

MCP-сервер BuyUKeSIM

BuyUKeSIM работает как MCP-сервер (Model Context Protocol), поэтому любой совместимый ИИ-ассистент - Claude, ChatGPT, Cursor, VS Code Copilot, Gemini CLI и другие - может работать с нашим каталогом eSIM напрямую. Укажите ассистенту один эндпоинт, и он сможет искать тарифы, показывать покрытие, объяснять номер Великобритании и проверять заказ - всё обычным языком.

Публичным инструментам не нужен ключ, и они не двигают деньги. Второй, авторизованный набор добавляет предоплаченный agent wallet на крипте, чтобы ассистент мог пополнить баланс и купить eSIM для путешествий/данных от вашего имени. Без аккаунта и без KYC. Эта страница - полный справочник: эндпоинты, настройка по клиентам, каждый инструмент, авторизация, готовые примеры, обработка ошибок и FAQ.

Базовый эндпоинт

https://buyukesim.com/mcp

Что такое MCP

Model Context Protocol (MCP) - это открытый стандарт для подключения ИИ-ассистентов к внешним инструментам и данным. Вместо копирования-вставки или разового плагина ассистент говорит на едином протоколе с любым совместимым сервером и обнаруживает предоставляемые им инструменты.

Наш сервер реализует MCP поверх Streamable HTTP на базе JSON-RPC 2.0, версия протокола 2025-06-18. На практике это один HTTPS-эндпоинт, принимающий POST-запросы. Ассистент вызывает initialize, затем tools/list, чтобы узнать доступное, потом tools/call, чтобы запустить инструмент. Вручную вы это почти никогда не делаете - за вас всё делает MCP-клиент.

Читайте спецификацию MCP на modelcontextprotocol.io

Быстрый старт

Самый быстрый путь - Claude Code. Одна команда добавляет сервер с публичными инструментами просмотра - без ключа и без файла конфигурации:

claude mcp add --transport http buyukesim https://buyukesim.com/mcp

Вот и всё. Попросите ассистента что-то вроде "найди тарифы eSIM для Великобритании", и он вызовет инструменты. Для других клиентов смотрите Настройку клиента ниже. Чтобы использовать инструменты кошелька, добавьте свой ключ как заголовок Bearer (см. Авторизацию).

Эндпоинты

Есть единственный MCP-эндпоинт. Запросы - HTTP POST с телом JSON-RPC. Обычный GET не является корректным MCP-запросом и возвращает 405. Для удобства вы также можете встроить свой ключ прямо в путь URL.

МетодЭндпоинтНазначение
POSThttps://buyukesim.com/mcpОсновной MCP-эндпоинт. Все вызовы JSON-RPC (initialize, tools/list, tools/call) идут сюда как POST.
GEThttps://buyukesim.com/mcpНе является корректным MCP-запросом - возвращает 405 Method Not Allowed. Используйте POST.
POSThttps://buyukesim.com/mcp/ak_live_YOURKEYФорма с ключом в URL. Тот же эндпоинт, но ваш API-ключ в пути, поэтому заголовок не нужен.

Настройка клиента

Везде используйте один и тот же базовый URL: https://buyukesim.com/mcp. Публичный просмотр не требует ключа. Для инструментов кошелька добавьте заголовок Authorization: Bearer ak_live_YOURKEY (или используйте один из других способов ниже). Замените ak_live_YOURKEY на ключ из 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"

Публичные инструменты

Четыре инструмента только для чтения. Без ключа и без движения денег - безопасно открывать любому ассистенту.

search_esim_plans
country?: string (2-letter ISO), limit?: int

Найти тарифы eSIM для путешествий/данных по стране. Возвращает объём данных, срок в днях, цену в USD и package_code, который вы передаёте в purchase_esim. country - двухбуквенный код ISO (например, GB); limit ограничивает число результатов.

list_covered_countries
(none)

Показать все страны и регионы, которые покрывает eSIM для путешествий, каждый с ценой "от". Аргументов не принимает.

get_uk_number_info
(none)

Объяснить eSIM с номером Великобритании (+44) - настоящий британский мобильный номер для SMS-подтверждений и звонков. Аргументов не принимает.

check_order_status
code: string

Проверить заказ по короткому коду. Возвращает только статус, никогда - персональные данные.

Авторизованные инструменты кошелька

Им нужен ключ ak_live_. Кошелёк предоплаченный и пополняется криптой (через NOWPayments) - без аккаунта, без KYC. Вызовите create_wallet один раз, чтобы получить ключ, пополните через create_deposit, затем покупайте через purchase_esim.

ИнструментПараметрыНазначение
create_walletlabel?: string -> returns api_key + wallet_codeСоздать новый agent wallet и вернуть его api_key (секрет) и wallet_code. Единственный инструмент кошелька, которому сам ключ не нужен - он его создаёт. Храните api_key надёжно.
check_balance(none)Вернуть текущий баланс кошелька в USD.
create_depositamount_usd: number (min 10), coin?: stringНачать пополнение криптой. amount_usd - сумма пополнения (минимум 10). coin необязателен, например usdttrc20, btc, eth или trx. Возвращает адрес/ссылку для оплаты; баланс зачисляется после подтверждения пополнения.
list_transactions(none)Показать историю транзакций кошелька - пополнения и покупки.
purchase_esimpackage_code: string, request_id?: stringКупить eSIM для путешествий/данных за баланс кошелька. package_code берётся из search_esim_plans. Это РАБОТАЕТ вживую и тратит реальный баланс. Передайте request_id, чтобы сделать вызов идемпотентным - повтор никогда не спишет дважды. Возвращает QR-код eSIM.
purchase_uk_numberrequest_id?: stringКупить eSIM с номером Великобритании (+44) со склада примерно за 25 USD за баланс кошелька. Это РАБОТАЕТ вживую и возвращает QR мгновенно. Передайте request_id, чтобы сделать вызов идемпотентным - повтор никогда не спишет дважды.

Баланс можно потратить только на eSIM - его нельзя вывести в наличные или крипту. Это сделано намеренно: это баланс для трат агента, а не биржа.

Авторизация

Публичным инструментам ничего не нужно. Инструментам кошелька нужен ваш ключ ak_live_ из create_wallet. Есть три равнозначных способа его передать - выберите тот, который поддерживает ваш клиент.

1Authorization header (recommended)

Отправьте стандартный заголовок Bearer-токена. Работает в Claude Code (--header), Cursor, VS Code, Gemini CLI и cURL. Это рекомендуемый способ.

Authorization: Bearer ak_live_YOURKEY

2X-API-Key header

Отправьте ключ в заголовке X-API-Key. Полезно для клиентов, которые дают задавать свои заголовки, но не поддерживают Bearer-авторизацию.

X-API-Key: ak_live_YOURKEY

3Key in the URL path

Поместите ключ прямо в путь URL. Удобно для клиентов, которые принимают только URL без заголовков. Считайте такой URL секретом, ведь ключ - внутри него.

https://buyukesim.com/mcp/ak_live_YOURKEY

Примеры

Готовый к копированию cURL для всего сценария. Обратите внимание на заголовок Accept: MCP поверх Streamable HTTP требует Accept: application/json, text/event-stream. Каждый id - просто выбранный вами идентификатор запроса.

1. Инициализировать сессию (рукопожатие).

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. Получить список доступных инструментов.

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. Найти тарифы Великобритании (GB), публично - без ключа.

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. Создать кошелёк и получить ключ.

# 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. Проверить баланс (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. Начать пополнение криптой.

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. Купить eSIM (вживую, идемпотентно).

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. Купить номер Великобритании +44 (вживую, идемпотентно).

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, с официальным клиентом mcp и транспортом 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, с официальным @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);

Обработка ошибок

Проблемы на уровне протокола возвращаются как стандартные ошибки JSON-RPC 2.0 с числовым кодом и сообщением. Вот те, что вы встретите:

КодЗначение
-32700Ошибка разбора - тело запроса не является корректным JSON.
-32600Некорректный запрос - JSON не является корректным запросом JSON-RPC 2.0.
-32601Метод не найден - неизвестный метод или несуществующее имя инструмента.
-32602Некорректные параметры - инструмент вызван с отсутствующими или неверно типизированными аргументами.
-32603Внутренняя ошибка - что-то сломалось на нашей стороне при обработке вызова.

Ошибки на уровне инструмента - другое. Инструмент, который выполнился, но не смог завершиться (например, недостаточный баланс или неизвестный package_code), не бросает ошибку JSON-RPC. Он возвращает обычный результат с isError: true и человекочитаемым сообщением в текстовом содержимом, чтобы ассистент мог его прочитать и объяснить.

Что работает vs скоро

Честно: покупка РАБОТАЕТ вживую. purchase_esim для eSIM путешествий/данных действительно тратит баланс кошелька и возвращает рабочий QR-код, а purchase_uk_number теперь делает то же самое для eSIM с номером Великобритании (+44) - покупает его со склада примерно за 25 USD и возвращает QR мгновенно. Инструмент get_uk_number_info по-прежнему описывает продукт; фактически покупает его purchase_uk_number.

Ещё одно честное ограничение: ни один ассистент не может установить eSIM за вас. Установка - это сканирование или нажатие на QR-профиль на вашем собственном телефоне. Ассистент может найти тариф, купить его и передать вам QR - финальная установка всегда за вами.

FAQ

Это реальные деньги?

Публичные инструменты не двигают деньги. Инструменты кошелька - да: create_deposit пополняет реальный предоплаченный баланс криптой, а purchase_esim по-настоящему его тратит. Всё, что только для чтения, бесплатно.

Может ли ассистент установить eSIM за меня?

Нет. Он может найти, купить и вернуть QR-код, но установка - это сканирование QR на вашем собственном устройстве. Этот последний шаг всегда за вами.

Это действительно без KYC?

Да. Нет аккаунта и нет проверки личности. Вы создаёте кошелёк, пополняете его криптой и тратите на eSIM.

Мой баланс в безопасности? Можно вывести?

Баланс можно потратить только на eSIM - его нельзя вывести в наличные или крипту. Это баланс для трат агента, а не кошелёк для вывода средств.

А как насчёт номеров Великобритании?

get_uk_number_info объясняет eSIM с номером Великобритании (+44), а purchase_uk_number теперь покупает его со склада примерно за 25 USD за баланс вашего кошелька и возвращает QR мгновенно. Он работает вживую и идемпотентен через request_id, как и purchase_esim.

Как работает идемпотентность?

Передайте стабильный request_id в purchase_esim. Если тот же request_id повторяется, покупка не выполняется заново, поэтому сетевой повтор никогда не спишет дважды.

Какие монеты можно вносить?

Распространённые: usdttrc20, btc, eth и trx через NOWPayments. Минимальное пополнение - 10 USD. Не указывайте coin, чтобы вам предложили выбор.

Нужно ли запускать какой-то сервер?

Нет. Это размещённый HTTP-эндпоинт. Добавьте URL в клиент - и готово, ничего устанавливать или хостить самому не нужно.

Поддержка

Вопросы, проблема с ключом или что-то ведёт себя не так? Напишите нам в Telegram @buyukesimbot, и мы поможем.

@buyukesimbot

Эндпоинт: JSON-RPC 2.0 через HTTP POST (Streamable HTTP), версия протокола 2025-06-18. Базовый URL https://buyukesim.com/mcp.