Connect Claude, ChatGPT, Grok, Grok Bot, or Cursor to mobile top-ups, travel eSIM, and gift cards in 200+ countries via the Model Context Protocol.
eu / ww / as)Remote connectors (Claude.ai, ChatGPT, Grok, Grok Bot) use OAuth Dynamic Client Registration + PKCE. Leave client ID/secret blank — the server issues a public client. Grok Bot: install guide.
| Setting | Value |
|---|---|
| MCP URL | https://api.doctorsim.com/mcp |
| OAuth issuer | https://www.doctorsim.com |
| API base | https://api.doctorsim.com/v2 |
| Auth guide | auth.md |
Full step-by-step registration flow: auth.md.
Guest catalog and checkout tools work without Authorization. PRO credit debit, order history, line lookup, and webhooks need OAuth. preview_esim_order / create_esim_order are aliases of preview_order / create_order with the same dual noauth + oauth2 schemes.
| Tool | REST equivalent | Auth |
|---|---|---|
get_countries | GET /v2/countries | guest (noauth) |
lookup_carrier | GET /v2/topup/carriers/lookup/{phone} | guest (noauth) |
get_operators | GET /v2/topup/operators | guest (noauth) |
get_operator_service_types | GET /v2/topup/operators/{id}/service-types | guest (noauth) |
get_operator_rates | GET /v2/topup/operators/{id}/rates | guest (noauth) |
search_products | GET /v2/products/search | guest (noauth) |
get_giftcard_brands | GET /v2/giftcards/brands | guest (noauth) |
get_giftcard_brand_products | GET /v2/giftcards/brands/{id}/products | guest (noauth) |
get_esim_destinations | GET /v2/esim/destinations | guest (noauth) |
get_esim_plans | GET /v2/esim/products | guest (noauth) |
get_esim_plan_detail | GET /v2/esim/products/{catalog_id} | guest (noauth) |
preview_order | POST /v2/orders/preview | guest + oauth orders:read |
create_order | POST /v2/orders | guest + oauth orders:write |
preview_esim_order | alias of preview_order (type=esim) | guest + oauth orders:read |
create_esim_order | alias of create_order (type=esim) | guest + oauth orders:write |
get_order_status | GET /v2/orders/{id} | guest + oauth orders:read |
get_esim_line | GET /v2/esim/lines/{iccid} | oauth orders:read |
get_esim_topup_plans | GET /v2/esim/lines/{iccid}/topup-plans | oauth orders:read |
create_esim_topup | POST /v2/esim/lines/{iccid}/topups | oauth orders:write |
list_orders | GET /v2/orders | oauth orders:read |
get_balance | GET /v2/balance | PRO oauth balance:read |
list_webhooks | GET /v2/webhooks | PRO oauth webhooks:read |
country_iso: ISO-2 (es, us) is a strict catalog match — requesting es does not include Europe (eu) or global (ww) plans. Use region slugs eu, ww, as for those destinations.lookup_carrier or get_countries + get_operators. Travel eSIM: get_esim_destinations then get_esim_plans.get_operator_rates (copy token). eSIM: copy catalog_id + price_token.create_order (or create_esim_order) as soon as the product is chosen. No Authorization header.preview_order first (mandatory), then create_order with OAuth. Debits prepaid credits.get_order_status with payment_link (preferred) or order_id. Do not show checkout_hash. Guest products arrive by email. PRO: list_orders / webhooks. Fulfilled eSIM (PRO): get_esim_line (OAuth).preview_order first — it is the debit breakdown before credits move. Guest: preview is optional; create the payment_link as soon as the product is chosen.| Account | create_order result | Payment | Order ID |
|---|---|---|---|
| PRO account | Credits debited; order placed immediately. Response always has order_id, status, credits_used. Pass idempotency_key (distinct per SKU). If order_id is missing, list_orders / get_order_status — never re-create. |
Prepaid PRO balance | order_id in response |
| Regular account | Returns payment_link and order_id when one exists (hash is machine-only) |
User pays on doctorsim.com (Stripe / PayPal / Bizum); enters email; delivery is email | Show order_id when present; otherwise poll via payment_link |
Consumer payment link formats:
https://www.doctorsim.com/en/mx/topup-phone/checkout/{64-char-hash}
https://www.doctorsim.com/en/esim/checkout/{64-char-hash}
Payment links expire in 6 hours.
| Method | Who | Scopes |
|---|---|---|
API keys (api_id:api_secret) | PRO with API access | Full (balance, webhooks, orders) |
| OAuth JWT | PRO | orders + balance (+ webhooks on request) |
| OAuth JWT | Regular consumer | orders:read orders:write only |
Full per-surface steps live on the Agentic Core roadmap §4. Public Grok Bot steps: grok-bot.md.
| Client | How to connect |
|---|---|
| Claude.ai | Customize → Connectors → Add custom connector → MCP URL. Leave Client ID / Secret blank (lazy auth). |
| ChatGPT | Private custom GPT / Apps MCP (same URL). Public directory waits on #10000 — do not create a new plugin. |
| Grok (grok.com) | grok.com/connectors → New → Custom. Headers empty. If Grok asks for OAuth credentials, paste the published public Client ID from grok-bot.md. |
| Grok Bot | Settings → Plugins → custom MCP (name doctorSIM, headers empty). Click Authenticate, then Sign in or Continue as guest. Do not paste an API key. Enable on any bot or @. |
| Grok Build marketplace | After the human xAI catalog PR: /plugin → search doctorSIM. Until then use custom MCP. |
| Cursor / Claude Desktop | Remote MCP or stdio — see SKILL.md. Cursor is connect-time: Authenticate on add. |
Verify with: “List the doctorSIM tools you have” then a guest catalog question (e.g. eSIM plans for Spain). Expect ~20 tools. Guest catalog has no login prompt on Claude / ChatGPT; Grok / Grok Bot choose Continue as guest on add.
PRO accounts: poll GET /v2/orders/{id} or register webhooks for async updates.
Consumer / guest: poll GET /v2/orders?payment_link={url} or ?checkout_hash={hash}. Show the buyer only the payment link and order id. Guest fulfillment is by email.