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 eSIM packages, check country coverage, and get pricing for 190+ countries. No API key needed for browsing.

Endpoint

Setup Guides

Claude Desktop

Open Settings, then "Developer", then "Edit Config". Add to claude_desktop_config.json:

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

Restart Claude Desktop. You'll see PikaSim tools in the tool list.

Claude Desktop (with API key)

To enable purchasing and account management:

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

Claude Code

Add to your project's .mcp.json:

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

Cursor

Go to Settings > MCP Servers > Add Server. Enter:

• Name: pikasim
• Type: streamable-http
• URL: 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 the required Accept header.

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 eSIM package.

Japan 100MB 7Days | 100MB | 7 days | $0.75
Japan 500MB 7Days | 500MB | 7 days | $1.00
Japan 1GB 7Days | 1GB | 7 days | $1.75
Japan 3GB 15Days | 3GB | 15 days | $4.25
Japan 5GB 30Days | 5GB | 30 days | $7.50

Showing 5 packages. Browse all at https://pikasim.com
Direct link: https://pikasim.com/esim/jp

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

Japan (JP) eSIM Coverage
Data-only plans: 18
Price range: $0.75 - $42.50

Available data amounts:
  100MB: from $0.75 (7 days)
  500MB: from $1.00 (7 days)
  1GB: from $1.75 (7 days)
  3GB: from $4.25 (15 days)
  5GB: from $7.50 (30 days)
  10GB: from $12.50 (30 days)
  20GB: from $22.50 (30 days)

Browse: https://pikasim.com/esim/jp

Japan 3GB 15Days
Price: $4.25 USD
Payment: Card (Visa/MC/Amex/Apple Pay/Google Pay) or Crypto

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

Authenticated Tools (Reseller API Key)

These tools require a free PikaSim reseller account. Pass your 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.

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 here: https://btcpay.pikasim.com/i/abc123def456
Invoice ID: abc123def456

Accepted: Bitcoin (on-chain + Lightning), Monero, USDT (Tron), and 50+ altcoins via Trocador.
Balance updates automatically after payment confirms.

Authentication

Public tools

No authentication needed. The 4 public tools (search, details, coverage, pricing) work for any AI agent with no API key.

Authenticated tools

The 6 authenticated tools require a PikaSim reseller API key. Pass it in one of two ways:

// Option 1: Authorization header (recommended for MCP configs)
Authorization: Bearer pk_live_your_api_key_here

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

Getting an API key

1. Sign up at pikasim.com/reseller
2. Wait for account approval (usually same day)
3. Generate your API key from the reseller dashboard
4. Fund your wallet with crypto via the dashboard or create_deposit tool

API keys start with pk_live_ and are 32 characters long. Keep your key secret. If compromised, regenerate it from the dashboard.

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 pk_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 pk_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 reseller 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 a reseller API key. The purchase_esim tool deducts from your prepaid wallet, so purchases are instant. Fund your wallet first with create_deposit or via the reseller 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
• Reseller Program (get an API key)
• OpenAPI Specification
• LLM.txt (machine-readable instructions)
• Model Context Protocol specification