Buy eSIM
← Back to Home
For AI assistants · MCP server

BuyUKeSIM MCP Server

BuyUKeSIM runs a Model Context Protocol (MCP) server, so any MCP-capable AI assistant - Claude, ChatGPT, Cursor, VS Code Copilot, Gemini CLI and others - can work with our eSIM catalogue directly. Point your assistant at one endpoint and it can search plans, list coverage, explain the UK Number, and check an order, all in plain language.

The public tools need no key and move no money. A second, authenticated set of tools adds a prepaid, crypto-funded agent wallet so an assistant can fund a balance and buy a travel/data eSIM on your behalf. There is no account and no KYC. This page is the full reference: endpoints, setup per client, every tool, authentication, runnable examples, error handling and FAQ.

Base endpoint

https://buyukesim.com/mcp

What is MCP

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data. Instead of copy-pasting or building a one-off plugin, the assistant speaks a single protocol to any compliant server and discovers the tools it exposes.

Our server implements MCP over Streamable HTTP using JSON-RPC 2.0, protocol version 2025-06-18. In practice that means one HTTPS endpoint that accepts POST requests. The assistant calls initialize, then tools/list to learn what is available, then tools/call to run a tool. You almost never touch this by hand - your MCP client does it for you.

Read the MCP spec at modelcontextprotocol.io

Quick start

The fastest path is Claude Code. One command adds the server with public browsing tools - no key, no config file:

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

That is it. Ask your assistant something like "search UK eSIM plans" and it will call the tools. For other clients, see Client setup below. To use the wallet tools, add your key as a Bearer header (see Authentication).

Endpoints

There is a single MCP endpoint. Requests are HTTP POST with JSON-RPC bodies. A plain GET is not a valid MCP request and returns 405. As a convenience you can also embed your key directly in the URL path.

MethodEndpointPurpose
POSThttps://buyukesim.com/mcpMain MCP endpoint. All JSON-RPC calls (initialize, tools/list, tools/call) go here as POST.
GEThttps://buyukesim.com/mcpNot a valid MCP request - returns 405 Method Not Allowed. Use POST.
POSThttps://buyukesim.com/mcp/ak_live_YOURKEYKey-in-URL form. Same endpoint, but your API key is in the path, so no header is needed.

Client setup

Use the same base URL everywhere: https://buyukesim.com/mcp. Public browsing needs no key. For the wallet tools, add an Authorization: Bearer ak_live_YOURKEY header (or use one of the other auth methods below). Replace ak_live_YOURKEY with a key from 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"

Public tools

Four read-only tools. No key, no money movement - safe to expose to any assistant.

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

Find travel/data eSIM plans for a country. Returns data amount, validity in days, USD price and the package_code you pass to purchase_esim. country is a 2-letter ISO code (for example GB); limit caps the results.

list_covered_countries
(none)

List every country and region the travel eSIM covers, each with a from-price. Takes no arguments.

get_uk_number_info
(none)

Explain the UK Number (+44) eSIM - a real British mobile number for verification SMS and calls. Takes no arguments.

check_order_status
code: string

Look up an order by its short code. Returns status only, never personal data.

Authenticated wallet tools

These need an ak_live_ key. The wallet is prepaid and funded with crypto (via NOWPayments) - no account, no KYC. Call create_wallet once to mint a key, top it up with create_deposit, then buy with purchase_esim.

ToolParametersPurpose
create_walletlabel?: string -> returns api_key + wallet_codeCreate a new agent wallet and return its api_key (secret) and wallet_code. This is the only wallet tool that does not itself require a key - it mints one. Store the api_key safely.
check_balance(none)Return the current wallet balance in USD.
create_depositamount_usd: number (min 10), coin?: stringStart a crypto top-up. amount_usd is the deposit (minimum 10). coin is optional, for example usdttrc20, btc, eth or trx. Returns a payment address/link; balance is credited when the deposit confirms.
list_transactions(none)List the wallet transaction history - deposits and purchases.
purchase_esimpackage_code: string, request_id?: stringBuy a travel/data eSIM with wallet balance. package_code comes from search_esim_plans. This is LIVE and spends real balance. Pass a request_id to make it idempotent so a retry never double-charges. Returns the eSIM QR code.
purchase_uk_numberrequest_id?: stringBuy a UK Number (+44) eSIM from stock for about 25 USD with wallet balance. This is LIVE and returns the QR instantly. Pass a request_id to make it idempotent so a retry never double-charges.

The balance can only ever be spent on eSIMs - it is never withdrawable to cash or crypto. That is deliberate: it is a spending balance for an agent, not an exchange.

Authentication

The public tools need nothing. The wallet tools need your ak_live_ key, which you get from create_wallet. There are three equivalent ways to send it - pick whichever your client supports.

1Authorization header (recommended)

Send a standard Bearer token header. Works in Claude Code (--header), Cursor, VS Code, Gemini CLI and cURL. This is the recommended method.

Authorization: Bearer ak_live_YOURKEY

2X-API-Key header

Send the key in an X-API-Key header instead. Useful for clients that expose custom headers but not Bearer auth.

X-API-Key: ak_live_YOURKEY

3Key in the URL path

Put the key straight in the URL path. Handy for clients that only accept a URL and no headers. Treat this URL as a secret, since the key is in it.

https://buyukesim.com/mcp/ak_live_YOURKEY

Examples

Copy-paste cURL for the full flow. Note the Accept header: MCP over Streamable HTTP requires Accept: application/json, text/event-stream. Every id is just a request identifier you choose.

1. Initialize the session (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. List available tools.

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. Search UK (GB) plans, public - no key.

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. Create a wallet and receive a key.

# 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. Check balance (Bearer auth).

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. Start a crypto deposit.

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. Buy an eSIM (live, idempotent).

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. Buy a UK +44 number (live, idempotent).

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, using the official mcp client and the Streamable HTTP transport:

# 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, using the official @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);

Error handling

Protocol-level problems come back as standard JSON-RPC 2.0 errors with a numeric code and message. These are the ones you will see:

CodeMeaning
-32700Parse error - the request body was not valid JSON.
-32600Invalid request - the JSON is not a valid JSON-RPC 2.0 request.
-32601Method not found - unknown method, or a tool name that does not exist.
-32602Invalid params - a tool was called with missing or wrong-typed arguments.
-32603Internal error - something failed on our side while handling the call.

Tool-level failures are different. A tool that runs but cannot complete (for example insufficient balance, or an unknown package_code) does not throw a JSON-RPC error. It returns a normal tool result with isError: true and a human-readable message in the text content, so your assistant can read and explain it.

What is live vs coming

Being straight with you: buying is LIVE. purchase_esim for travel/data eSIMs really spends wallet balance and returns a working QR code, and purchase_uk_number now does the same for the UK Number (+44) eSIM - it buys one from stock for about 25 USD and returns the QR instantly. The get_uk_number_info tool still describes the product; purchase_uk_number is what actually buys it.

One more honest limit: no assistant can install the eSIM for you. Installation means scanning or tapping the QR profile on your own phone. The assistant can find the plan, buy it and hand you the QR - the final install is always yours.

FAQ

Is this real money?

The public tools move no money. The wallet tools do: create_deposit funds a real prepaid balance in crypto, and purchase_esim spends it for real. Everything read-only is free.

Can the assistant install the eSIM for me?

No. It can search, buy and return the QR code, but installing means scanning the QR on your own device. That final step is always yours.

Is it really no-KYC?

Yes. There is no account and no identity check. You create a wallet, fund it with crypto and spend it on eSIMs.

Is my balance safe? Can I withdraw it?

The balance can only be spent on eSIMs - it is never withdrawable to cash or crypto. It is a spending balance for an agent, not a wallet you cash out.

What about UK numbers?

get_uk_number_info explains the UK Number (+44) eSIM, and purchase_uk_number now buys one from stock for about 25 USD with your wallet balance, returning the QR instantly. It is live and idempotent via request_id, just like purchase_esim.

How does idempotency work?

Pass a stable request_id to purchase_esim. If the same request_id is retried, the purchase is not repeated, so a network retry never double-charges.

Which coins can I deposit?

Common ones like usdttrc20, btc, eth and trx via NOWPayments. Minimum deposit is 10 USD. Leave coin out to be offered a choice.

Do I need to run any server?

No. It is a hosted HTTP endpoint. Add the URL to your client and you are done - nothing to install or self-host.

Support

Questions, a key issue, or something not behaving? Message us on Telegram at @buyukesimbot and we will help.

@buyukesimbot

Endpoint: JSON-RPC 2.0 over HTTP POST (Streamable HTTP), protocol version 2025-06-18. Base URL https://buyukesim.com/mcp.