Overview
AI integrations (MCP)
Connect the official esimoa MCP server so AI assistants can search and compare eSIMs and share purchase links.
Server URL#
The official esimoa MCP server https://api.esimoa.com/mcp lets AI assistants search and compare eSIMs and share purchase links. It uses Streamable HTTP (stateless JSON) and works without a key (120 requests/min per IP).
https://api.esimoa.com/mcpTip
Adding your partner key#
Tip
https://api.esimoa.com/mcp?key=esk_live_your_key_hereClients that support headers can send X-API-Key or Authorization: Bearer instead. A wrong key is rejected with 401 — to use the server without a key, leave it out entirely.
Available tools#
| Field | Type | Description |
|---|---|---|
search_esims | tool | Search eSIMs — country (ISO code or name in any language) or countries (all at once), days, data_gb / max_data_gb, unlimited, data_type (daily|total), local_number, network (local|roaming), multi_country, min_price_krw / max_price_krw, provider, hotspot / five_g, sort, limit (≤10), lang |
get_esim | tool | eSIM details — id, lang |
compare_esims | tool | Compare 2–5 plans side by side — ids (from search_esims), lang. Tells you which has the lowest price, most data, longest validity and lowest price per GB |
list_countries | tool | Countries on sale — query, lang |
search / fetch | tool | ChatGPT-compatible tools — search {query} (free text; understands unlimited, daily, local phone number, local network, hotspot and 5G), fetch {id} |
In apps that support MCP Apps (such as Claude, ChatGPT and VS Code), results of search_esims, get_esim and compare_esims appear as plan cards. View plan opens the plan page on esimoa.com — the cards never take payment.
Rate limits#
Note
Public API and authenticated MCP share a per-partner hourly quota (default 20,000). Adding or rotating keys does not increase it.
The 3,600-second window starts on the first request; the per-minute limit also applies. Quotas count calls, not transferred MB. Operational settings may change the quota.
MCP batches accept up to 100 messages and count each message as one call. A batch that exceeds the available quota returns 429 before execution.
X-RateLimit-Hour-Limit · X-RateLimit-Hour-Remaining · X-RateLimit-Hour-Reset
These headers report the hourly limit, remaining calls and reset time (Unix seconds). Hourly exhaustion returns HTTP 429 and Retry-After in seconds. Calls rejected by the minute limit do not count toward the hourly quota.
Without a key the limit is 120 requests per minute per IP; with a partner key it is 600 per minute per key. Calls that Claude and ChatGPT make from their own servers are counted per platform, not per IP. Beyond that you get a JSON-RPC error (-32002) with HTTP 429.