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.
| Метод | Эндпоинт | Назначение |
|---|---|---|
| POST | https://buyukesim.com/mcp | Основной MCP-эндпоинт. Все вызовы JSON-RPC (initialize, tools/list, tools/call) идут сюда как POST. |
| GET | https://buyukesim.com/mcp | Не является корректным MCP-запросом - возвращает 405 Method Not Allowed. Используйте POST. |
| POST | https://buyukesim.com/mcp/ak_live_YOURKEY | Форма с ключом в URL. Тот же эндпоинт, но ваш API-ключ в пути, поэтому заголовок не нужен. |
Настройка клиента
Везде используйте один и тот же базовый URL: https://buyukesim.com/mcp. Публичный просмотр не требует ключа. Для инструментов кошелька добавьте заголовок Authorization: Bearer ak_live_YOURKEY (или используйте один из других способов ниже). Замените ak_live_YOURKEY на ключ из 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"Публичные инструменты
Четыре инструмента только для чтения. Без ключа и без движения денег - безопасно открывать любому ассистенту.
search_esim_planscountry?: 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_statuscode: stringПроверить заказ по короткому коду. Возвращает только статус, никогда - персональные данные.
Авторизованные инструменты кошелька
Им нужен ключ ak_live_. Кошелёк предоплаченный и пополняется криптой (через NOWPayments) - без аккаунта, без KYC. Вызовите create_wallet один раз, чтобы получить ключ, пополните через create_deposit, затем покупайте через purchase_esim.
| Инструмент | Параметры | Назначение |
|---|---|---|
create_wallet | label?: string -> returns api_key + wallet_code | Создать новый agent wallet и вернуть его api_key (секрет) и wallet_code. Единственный инструмент кошелька, которому сам ключ не нужен - он его создаёт. Храните api_key надёжно. |
check_balance | (none) | Вернуть текущий баланс кошелька в USD. |
create_deposit | amount_usd: number (min 10), coin?: string | Начать пополнение криптой. amount_usd - сумма пополнения (минимум 10). coin необязателен, например usdttrc20, btc, eth или trx. Возвращает адрес/ссылку для оплаты; баланс зачисляется после подтверждения пополнения. |
list_transactions | (none) | Показать историю транзакций кошелька - пополнения и покупки. |
purchase_esim | package_code: string, request_id?: string | Купить eSIM для путешествий/данных за баланс кошелька. package_code берётся из search_esim_plans. Это РАБОТАЕТ вживую и тратит реальный баланс. Передайте request_id, чтобы сделать вызов идемпотентным - повтор никогда не спишет дважды. Возвращает QR-код eSIM. |
purchase_uk_number | request_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_YOURKEY2X-API-Key header
Отправьте ключ в заголовке X-API-Key. Полезно для клиентов, которые дают задавать свои заголовки, но не поддерживают Bearer-авторизацию.
X-API-Key: ak_live_YOURKEY3Key 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-48215. Проверить баланс (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.
