MCP Server Documentation

Quick Start

Get started in under a minute. Add PikaSim to your AI agent's MCP config:

{
  "mcpServers": {
    "pikasim": {
      "type": "streamable-http",
      "url": "https://pikasim.com/mcp"
    }
  }
}

That's it. Your AI agent can now search data eSIM and phone-number eSIM plans, check country coverage, and get pricing for 190+ countries. No API key needed for browsing.

Endpoint

Setup Guides

PikaSim is a remote MCP server (Streamable HTTP) with two URLs: https://pikasim.com/mcp for keyless browsing, and https://pikasim.com/mcp/wallet for purchasing (it connects a prepaid agent wallet via OAuth, or a Bearer key on CLI clients). Steps differ per client; use the matching one below.

Claude Desktop

Remote servers are added as connectors, not via claude_desktop_config.json (that file is for local stdio servers). Go to Settings → Connectors → Add custom connector and paste the URL.

To purchase (recommended): add https://pikasim.com/mcp/wallet, then click Connect. Claude opens a PikaSim consent page; paste your 32-character wallet code (from your agent wallet) and authorize. Claude receives a revocable access token bound to that wallet (no key pasted into a URL, no account, no email). After connecting, enable the connector for your chat from the tools menu.

https://pikasim.com/mcp/wallet   ← Connect → paste wallet code

To browse only (no wallet), add the keyless URL instead:

https://pikasim.com/mcp

Claude Code

One command (the flag value is http for Streamable HTTP):

# browse only
claude mcp add --transport http pikasim https://pikasim.com/mcp

# with purchasing via OAuth (recommended): add the wallet URL, then run /mcp
# inside Claude Code and pick "Authenticate" — a browser opens the PikaSim
# consent page where you paste your wallet code
claude mcp add --transport http pikasim https://pikasim.com/mcp/wallet

# with purchasing via key (scriptable alternative)
claude mcp add --transport http pikasim https://pikasim.com/mcp \
  --header "Authorization: Bearer ak_live_your_api_key_here"

ChatGPT

On a paid plan (Plus, Pro, Business, Enterprise, or Edu): Settings → Apps → Advanced settings → enable Developer mode, then Create app and enter the URL. Use https://pikasim.com/mcp to browse, or https://pikasim.com/mcp/wallet to purchase — the wallet URL triggers OAuth, so you authorize by pasting your wallet code on the PikaSim consent page (no key in the URL). Open the app to enable individual tools.

Deep Research: the plain https://pikasim.com/mcp endpoint also exposes search and fetch tools, so you can add PikaSim as a Deep Research source and have ChatGPT look up eSIM plans, prices, and coverage while researching a trip.

Grok (xAI)

On a paid plan: grok.com/connectors → New Connector → Custom, then paste the URL: https://pikasim.com/mcp to browse, or https://pikasim.com/mcp/ak_live_your_api_key_here to also purchase.

Gemini CLI

Edit ~/.gemini/settings.json. Gemini CLI uses the httpUrl key for Streamable HTTP and passes the key as a header. (The consumer Gemini app has no custom-connector option; use the CLI.)

{
  "mcpServers": {
    "pikasim": {
      "httpUrl": "https://pikasim.com/mcp",
      "headers": { "Authorization": "Bearer ak_live_your_api_key_here" }
    }
  }
}

Cursor

Settings → Tools & MCP → New MCP Server, or add to ~/.cursor/mcp.json:

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

To purchase, use https://pikasim.com/mcp/wallet as the URL instead — Cursor detects the OAuth requirement and opens the PikaSim consent page (paste your wallet code). A key URL (https://pikasim.com/mcp/ak_live_…) also works.

VS Code (GitHub Copilot)

Add to .vscode/mcp.json (note the top-level key is servers and the type is http):

{
  "servers": {
    "pikasim": {
      "type": "http",
      "url": "https://pikasim.com/mcp"
    }
  }
}

Windsurf / Cline / Zed

• Windsurf (~/.codeium/windsurf/mcp_config.json): mcpServers with "serverUrl": "https://pikasim.com/mcp"
• Cline: mcpServers with "type": "streamableHttp", "url": "https://pikasim.com/mcp"
• Zed: context_servers, or bridge with npx -y mcp-remote https://pikasim.com/mcp

Any MCP Client

Any agent or tool that supports MCP Streamable HTTP transport can connect to https://pikasim.com/mcp. Send JSON-RPC messages via POST with Accept: application/json, text/event-stream. For authenticated tools pass Authorization: Bearer ak_live_… or X-API-Key: ak_live_….

Public Tools (No Auth Required)

These tools are available to any AI agent with no API key. Use them to help users find the right data eSIM or phone-number eSIM plan.

DATA eSIMs (35):
  United States 100MB 7Days [P3YTYXBRV] | 100MB | 7 days | $0.75
  United States 1GB 7Days [PHAJHEAYP] | 1GB | 7 days | $2.25
  ...showing 10 of 35

PHONE-NUMBER eSIMs (15): real carrier number, voice + SMS + data:
  Phone-number plan [change-plus-7days-1gb]: 10 min + 10 SMS + 1GB data | 7 days | $X.XX | real carrier number
  ...showing 10 of 15

The code in [brackets] is the packageCode: pass it to purchase_esim (data) or purchase_phone_plan (phone).
(Prices above are illustrative. The tool returns live current prices.)

Phone-number eSIMs: a real carrier number with voice + SMS + data (not VoIP):
  Phone-number plan [change-plus-7days-1gb]: 10 min + 10 SMS + 1GB data | 7 days | $X.XX | real carrier number
  Phone-number plan [change-plus-15days-2gb]: 20 min + 20 SMS + 2GB data | 15 days | $X.XX | real carrier number
  ...showing 10 of 15

The code in [brackets] is the packageCode: pass it to purchase_phone_plan.
(Prices above are illustrative. The tool returns live current prices.)

Package: Japan 3GB 15Days
Code: CKH123
Data: 3GB
Duration: 15 days
Price: $4.25 USD
Coverage: Japan (JP)
Speed: 3G/4G
Top-up: Supported

Networks:
  Japan: NTT Docomo (LTE), SoftBank (LTE)

Purchase: https://pikasim.com/esim/japan-3gb-15days

US (US) eSIM Coverage

DATA eSIMs (50): price range $0.75 - $224.20
  Available data amounts:
    100MB: from $0.75 (7 days)
    1GB: from $2.07 (7 days)
    5GB: from $8.28 (30 days)
    ...

PHONE-NUMBER eSIMs (15): a real +1 number on AT&T / T-Mobile, voice + SMS + data
  Cheapest: 1 GB - 10 SMS - 10 Mins - 7 days [change-plus-7days-1gb]
  Use search_phone_plans for the full list and live prices, then purchase_phone_plan.

Browse data plans: https://pikasim.com/esim/us
Browse phone plans: https://pikasim.com/usa-data-sms-call-plans

Japan 3GB 15Days [CKH123]
Price: $4.25 USD
Type: Data eSIM
Data: 3GB
Payment: Card (Visa/MC/Amex/Apple Pay/Google Pay) or Crypto

Purchase: https://pikasim.com/esim/japan-3gb-15days

1 GB - 10 SMS - 10 Mins - 7 days [change-plus-7days-1gb]
Price: $X.XX USD (live current price returned by the tool)
Type: Phone-number plan, real carrier number + voice + SMS + data
Voice: 10 minutes
SMS: 10
Data: 1GB
Phone Number: Included (assigned by the carrier on activation)
Payment: Card (Visa/MC/Amex/Apple Pay/Google Pay) or Crypto

Purchase: https://pikasim.com/esim/us-change-plus-7days-1gb

Authenticated Tools (PikaSim Wallet API Key)

These tools require a free PikaSim agent wallet. Pass your ak_live_ API key via the Authorization header. If no key is provided, these tools return a signup prompt instead of an error.

Wallet Balance: $47.50 USD
Credit Limit: $0.00 USD
Available: $47.50 USD

Fund your wallet: https://pikasim.com/reseller/dashboard

Order placed successfully!
Order ID: ord_abc123def456
Package: CKH123
Status: completed
Cost: $3.83

eSIM Details:
  ICCID: 8901234567890123456
  SM-DP+: smdp.example.com
  Activation: LPA:1$smdp.example.com$ACTIVATION_CODE

Use get_esim_status to check activation status.

Phone-number eSIM ordered successfully!
Order ID: ord_xyz789
Plan: change-plus-7days-1gb
Status: completed
Cost: $4.59

eSIM Details:
  ICCID: 8901234567890999888
  SM-DP+: smdp.example.com
  Activation: LPA:1$smdp.example.com$ACTIVATION_CODE

The phone number is assigned by the carrier when the eSIM registers on the network; it appears in the device settings after activation.
Use get_esim_status to check activation status.

eSIM Status: 8901234567890123456
Status: IN_USE
Package: CKH123
Data Used: 0.45GB / 3.00GB
Remaining: 2.55GB
Expires: 2026-06-15T00:00:00Z

Top-up successful!
ICCID: 8901234567890123456
Package: CKH123
Cost: $3.83

Use get_esim_status to verify the top-up was applied.

Orders (3):

ord_abc123 | CKH123 | completed | $3.83 | 2026-05-13
ord_def456 | PZN25QW0P | completed | $7.50 | 2026-05-12
ord_ghi789 | CKH456 | completed | $12.50 | 2026-05-10

Page 1 of 1

Deposit invoice created!
Amount: $50.00 USD

Pay it yourself (no human needed if you hold crypto — pay the amount above to any ONE of these):
  Lightning invoice (BTC, fastest + cheapest): lnbc500...
  USDT (TRC-20 / Tron) address: TXk9...
  Monero (XMR) address: 89Ux...
  Bitcoin on-chain address: bc1q...

Or hand this off to a human / use another coin:
  Payment page (card + all crypto): https://pikasim.com/wallet/deposit/abc123
  Invoice ID: abc123

Balance updates automatically after payment confirms.

Top-up options for 8901234567890123456 (4 packages):

CKH123 | Japan 1GB 7 Days | 1GB | 7 days | $1.58
CKH456 | Japan 3GB 15 Days | 3GB | 15 days | $3.83
CKH789 | Japan 5GB 30 Days | 5GB | 30 days | $6.75
CKH012 | Japan 10GB 30 Days | 10GB | 30 days | $11.25

Use topup_esim with the packageCode to apply a top-up.

eSIM 8901234567890123456 cancelled.
Refund: $3.83
New Balance: $51.33
eSIM cancelled successfully. Refund added to your balance.

Quick SMS number ordered!
Order ID: 6a4c...ae4d
Phone number (use this on the target service): +1 909 555 0123
Service: Discord | Country: United States
Cost: $X.XX | New balance: $XX.XX
Expires: 20 minutes from order

Now poll check_sms_verification with the Order ID every 15-30 seconds.

Authentication

Public tools

No authentication needed. The public browsing tools (search, phone search, details, coverage, pricing) work for any AI agent with no API key, and always show retail prices.

OAuth (recommended for app clients)

PikaSim's MCP server supports OAuth 2.1 with Dynamic Client Registration and PKCE. There are two URLs:

• Browse (no auth): https://pikasim.com/mcp — search, coverage, pricing. Connect with no key.
• Purchase (OAuth): https://pikasim.com/mcp/wallet — connect this to buy. Clients that speak MCP OAuth (Claude and ChatGPT connectors) detect the OAuth requirement automatically and send you to a PikaSim consent page, where you paste your wallet code (the 32-character code from your agent wallet) to authorize. Your client then holds a revocable access token bound to that wallet.

The wallet code and your ak_live_ key never leave PikaSim, and no account, email, or KYC is involved. This is the cleanest way to connect for purchasing: no secret pasted into a URL, and you can disconnect at any time from your MCP client.

Authenticated tools (manual key)

For CLI clients or power users who prefer to manage the key directly, the purchasing/management tools also accept a PikaSim agent wallet API key (ak_live_). Pass it in one of these ways:

// Option 1: Authorization header (recommended for CLI configs)
Authorization: Bearer ak_live_your_api_key_here

// Option 2: X-API-Key header
X-API-Key: ak_live_your_api_key_here

// Option 3: key in the URL path (for connector UIs that only take a URL,
//            e.g. Claude Desktop, ChatGPT)
https://pikasim.com/mcp/ak_live_your_api_key_here

Treat the key URL like a password: anyone with it can spend the wallet balance. It is kept in your client's connector config and is never written to our server logs.

Fully autonomous (no browser, no human) — create_wallet

A terminal or headless agent does not need the browser flow at all. Connect the keyless endpoint https://pikasim.com/mcp and call the create_wallet tool with acceptTos: true. It returns a wallet code + an ak_live_ key + a spend-only welcome credit in one call. Reconnect with the key and buy:

1. create_wallet { "acceptTos": true }
   → wallet code, ak_live_… key, $1 welcome credit
2. reconnect:  Authorization: Bearer ak_live_…   (or URL https://pikasim.com/mcp/ak_live_…)
3. order_sms_verification / purchase_esim   → buys on the welcome credit, no deposit

No account, no email, no KYC, no browser, no human. Save the wallet code and key from the response — each is shown once.

Getting an API key (browser)

1. Create an agent wallet at pikasim.com/agent-wallet (accept the terms of service, no account or KYC)
2. Fund it with crypto (from $1) via the dashboard or the create_deposit tool — or skip this: a new wallet's spend-only welcome credit covers a first sub-$1 purchase
3. Generate your ak_live_ API key from the dashboard

Agent-wallet keys start with ak_live_. Keep your key secret; if compromised, rotate it from the dashboard. Existing reseller pk_live_ keys also work here and bill at the reseller's wholesale pricing.

Examples

Test with cURL

Initialize the MCP connection:

curl -X POST https://pikasim.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-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0"
      }
    }
  }'

List available tools

curl -X POST https://pikasim.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Search packages for Japan

curl -X POST https://pikasim.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_packages",
      "arguments": { "country": "JP" }
    }
  }'

Check balance (authenticated)

curl -X POST https://pikasim.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ak_live_your_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "check_balance",
      "arguments": {}
    }
  }'

Purchase an eSIM (authenticated)

curl -X POST https://pikasim.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ak_live_your_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "purchase_esim",
      "arguments": { "packageCode": "CKH123" }
    }
  }'

Python MCP Client

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client("https://pikasim.com/mcp") as (
        read_stream, write_stream, _
    ):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()

            # List tools
            tools = await session.list_tools()
            print(f"Available: {[t.name for t in tools.tools]}")

            # Search packages
            result = await session.call_tool(
                "search_esim_packages",
                arguments={"country": "JP"}
            )
            print(result.content[0].text)

import asyncio
asyncio.run(main())

Node.js MCP Client

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport }
  from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://pikasim.com/mcp")
);

const client = new Client(
  { name: "my-agent", version: "1.0" },
  { capabilities: {} }
);

await client.connect(transport);

// Search for Japan eSIMs
const result = await client.callTool(
  "search_esim_packages",
  { country: "JP" }
);
console.log(result.content[0].text);

await client.close();

Rate Limits

The MCP endpoint rate limit applies to all requests (including initialize and tools/list). Authenticated tool calls additionally count against your wallet rate limit.

Rate limit headers are included in responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error Handling

Errors follow standard JSON-RPC error codes:

Tool-level errors (e.g., invalid package code, insufficient balance) are returned as successful tool responses with descriptive error text, not as JSON-RPC errors. This lets the AI agent understand and explain the issue to the user.

FAQ

Can my AI agent purchase eSIMs automatically?

Yes, with an agent-wallet API key. The purchase_esim and purchase_phone_plan tools deduct from your prepaid wallet, so purchases are instant. Fund your wallet first with create_deposit or via the agent wallet dashboard.

Is there a sandbox or test mode?

Not currently. All purchases use real money. Use check_balance before purchasing and start with small packages to verify your integration.

What countries are covered?

190+ countries. Use check_country_coverage with any ISO country code to see what's available. Global packages cover 120+ countries in a single plan.

Can the AI agent install the eSIM on my device?

No. The AI agent can purchase and retrieve the QR code / activation details, but the user must scan the QR code or enter the activation details on their device. Purchase responses include all necessary installation info.

What's the difference between this and the REST API?

The REST API is read-only (browsing packages). The MCP server adds tool-call semantics that AI agents understand natively, plus authenticated tools for purchasing and account management. Use the REST API for traditional integrations; use MCP for AI agent integrations.

Does the endpoint support SSE / long-lived sessions?

No. This is a stateless endpoint. Each POST creates a fresh server instance, processes the request, and responds. No session IDs, no SSE reconnection. This is the simplest and most reliable setup for remote MCP servers.

My agent gets "Not Acceptable" errors

You must include both content types in the Accept header: Accept: application/json, text/event-stream. This is required by the MCP Streamable HTTP transport specification. Most MCP client libraries handle this automatically.

Support

Questions about the MCP integration? Submit a support ticket or chat with us at pikasim.com/help.

Related Resources

• REST API Documentation (read-only package data)
• AI Assistants Recommendation Guide
• Agent Wallet (get an API key to purchase)
• OpenAPI Specification
• LLM.txt (machine-readable instructions)
• Model Context Protocol specification