doctorSIM MCP Server

Connect Claude, ChatGPT, Grok, or Cursor to mobile top-ups, travel eSIM, and gift cards in 200+ countries via the Model Context Protocol.

MCP endpoint auth.md SKILL.md REST API v2

What you can do

Mobile airtime, data, and bundle top-ups
Travel eSIM plans (country ISO-2 or region slugs eu / ww / as)
Digital gift cards (gaming, streaming, retail)
Carrier lookup from phone numbers
Catalog search across 200+ countries and 1,600+ carriers

Connecting to MCP

Remote connectors (Claude.ai, ChatGPT) use OAuth Dynamic Client Registration + PKCE. Leave client ID/secret blank — the server issues a public client.

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.

Available tools

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`
`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`

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

How a purchase works

Discover — top-up: lookup_carrier or get_countries + get_operators. Travel eSIM: get_esim_destinations then get_esim_plans.
Price — top-up: get_operator_rates (copy token). eSIM: copy catalog_id + price_token.
Guest / consumer — skip preview. Call create_order (or create_esim_order) as soon as the product is chosen. No Authorization header.
PRO credits — preview_order first (mandatory), then create_order with OAuth. Debits prepaid credits.
Monitor — guest: 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).

Checkout modes

PRO: always call 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.

Authentication summary

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

Supported clients — install before you demo

Full per-surface steps (Claude.ai, ChatGPT, grok.com, Grok Bot, Cursor) live on the Agentic Core roadmap §4. Summary:

Claude.ai — Settings → Connectors → Add custom connector → MCP URL. Leave client ID blank.
ChatGPT — Custom GPT / Apps MCP connector (same URL). Public directory listing waits on G-3 / #10000.
grok.com — Custom MCP / plugin, same URL. Guest catalog needs no OAuth.
Grok Bot — Plugin package on PR #824; until merge, point the bot at the MCP URL + SKILL.md prompt.
Cursor / Claude Desktop — stdio or remote MCP; see SKILL.md.

Verify with: “List the doctorSIM tools you have” then a guest catalog question (e.g. eSIM plans for Spain). Expect ~20 tools and no login prompt on catalog.

Order monitoring

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.