doctorSIM MCP Server

Connect Claude, ChatGPT, Grok, or Cursor to mobile top-ups 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
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

Tool	REST equivalent
`get_countries`	`GET /v2/countries`
`lookup_carrier`	`GET /v2/carriers/lookup/{phone}`
`get_operators`	`GET /v2/operators`
`get_operator_service_types`	`GET /v2/operators/{id}/service-types`
`get_operator_rates`	`GET /v2/operators/{id}/rates`
`search_products`	`GET /v2/products/search`
`preview_order`	`POST /v2/orders/preview`
`create_order`	`POST /v2/orders`
`get_order_status`	`GET /v2/orders/{id}`
`list_orders`	`GET /v2/orders`
`get_balance`	`GET /v2/balance` (PRO only)
`list_webhooks`	`GET /v2/webhooks` (PRO only)

How a purchase works

Discover — lookup_carrier or get_countries + get_operators
Price — get_operator_rates (copy the token field)
Preview — preview_order (mandatory before checkout)
Create — create_order after explicit user confirmation
Monitor — get_order_status, list_orders, or webhooks (PRO)

Checkout modes

Always call preview_order first. The response shows the exact price breakdown before any money moves.

Account	`create_order` result	Payment	Order ID
PRO account	Credits debited; order placed immediately	Prepaid PRO balance	`order_id` in response
Regular account	Returns `payment_link` + `checkout_hash`	User pays on doctorsim.com (Stripe / PayPal / Bizum)	`null` until payment completes; poll via `checkout_hash`

Consumer payment link format:

https://www.doctorsim.com/en/mx/topup-phone/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

Claude (claude.ai connector)
ChatGPT (custom MCP connector)
Grok
Cursor / Claude Desktop (stdio — see SKILL.md)

Order monitoring

PRO accounts: poll GET /v2/orders/{id} or register webhooks for async updates.

Consumer accounts: poll GET /v2/orders?checkout_hash={hash} or list_orders after payment.