doctorsim

---
name: doctorsim
description: Helps a user buy a travel eSIM for a country, top up a prepaid mobile phone abroad, or buy a digital gift card from doctorSIM, using its public MCP server (https://api.doctorsim.com/mcp) or REST API v2. Use when someone needs mobile data for a trip, wants to send credit to a phone in another country, or asks for a gift card. Prices are always read live from the catalog.
homepage: https://www.doctorsim.com/en/developers-agents.html
metadata:
  author: doctorSIM
  version: "1.0.0"
  license: MIT
---

# doctorSIM: travel eSIM, international top-ups and gift cards

doctorSIM sells three things online: travel eSIMs, mobile top-ups for prepaid phones in 200+ countries, and digital gift cards. It works in 10 site locales (see "Pick the locale" below). This skill covers what doctorSIM documents for agents and nothing else. When something is not documented, send the user to the website in their locale instead of guessing.

## Ground rules

1. Never state a price from memory. Read it from the catalog tool in the same conversation and say that it is the current price.
2. Never invent a carrier, a `price_token`, a `catalog_id` or a URL. Copy values from tool results only.
3. Confirm with the user before creating an order: destination or phone number, the exact plan or denomination, and the currency.
4. Guest checkout is the default. The assistant creates a payment link, the user opens it on doctorsim.com and pays there. Never ask for card numbers or passwords in the chat.
5. Show the buyer the `payment_link` and the `order_id` (when there is one). Never show `checkout_hash`.
6. Guest products arrive by email after payment. Do not promise a code or a QR in the chat for guest orders.
7. A payment link expires after 6 hours. If it has expired, create a new order from the same selection.
8. If a tool returns an error, read the `Next:` part of the message and follow it. If the destination or product is not in the catalog, say so and point to the locale's catalog page.

## Connect

Remote MCP, Streamable HTTP, no key needed for guest use:

```
https://api.doctorsim.com/mcp
```

Leave headers empty. In Claude or ChatGPT leave OAuth client ID and secret blank. Account linking (PRO credits, order history) is optional and only needed if the user asks for it. Full details: https://www.doctorsim.com/auth.md

Without MCP the same catalog is available over REST at `https://api.doctorsim.com/v2` (OpenAPI: https://www.doctorsim.com/api-docs/openapi.yaml). Health check: `GET https://api.doctorsim.com/v2/status`.

## Pick the locale

doctorSIM runs 10 locales. Use the one that matches the user's country and language for every link you give them.

| Locale path | Use for |
|---|---|
| `/es-es/` | Spain |
| `/es/` | Spanish speakers outside Spain |
| `/en-us/` | United States |
| `/en/` | English speakers elsewhere, and the fallback when unsure |
| `/fr/` | French |
| `/it/` | Italian |
| `/pt/` | Portuguese |
| `/de/` | German |
| `/nl/` | Dutch |
| `/ar/` | Arabic |

Base URL: `https://www.doctorsim.com`. For the MCP tools, pass `lang` as `es` for Spanish-speaking users and `en` otherwise (the tool schema accepts those two values).

## Buy a travel eSIM

No phone number is needed.

1. Ask where the user is travelling and, if relevant, whether they want unlimited or limited data.
2. `get_esim_destinations` lists countries and regions. Pick `country_iso` as ISO-2 (`es`, `it`) or a region slug: `eu`, `ww`, `as`.
3. `get_esim_plans` with `country_iso`. The match is strict: `es` returns Spain plans only, not Europe or global plans. If the user visits several countries, query the region slug as well and compare. Optional `data_type`: `all`, `unlimited` or `limited`. Optional `currency`: `EUR` or `USD`.
4. Show a short list (data, days, price from the result). Copy `catalog_id` and `price_token` from the plan the user picks. `get_esim_plan_detail` gives one plan in full.
5. After the user confirms, `create_order` (alias `create_esim_order`) with `catalog_id` and `price_token`. For a guest it returns a `payment_link` of the form `https://www.doctorsim.com/{locale}/esim/checkout/{hash}`.
6. Give the user the link. They enter their email on the checkout page, pay, and the eSIM is emailed to them.
7. To follow the order, `get_order_status` with the `payment_link`. When the status is `fulfilled`, the result also carries `iccid`, `lpa_string`, an Apple `install_url` and a `qr_code_url`; show those fields to the user.

Remind the user that the phone must support eSIM. Point them to the eSIM page of their locale, for example `https://www.doctorsim.com/en/esim/`.

## Top up a prepaid phone

1. Ask for the full number in E.164 format (`+` country code, then number). Confirm it back to the user: a wrong digit sends the credit to someone else.
2. `lookup_carrier` with the number. It returns `id_operator` and the country. If the lookup fails, ask which carrier the number is on, or use `get_countries` then `get_operators` for that country.
3. Ask whether the user wants airtime, a bundle or data. For a bundle or data ask what they need (for example a size or an app).
4. `get_operator_service_types` for the operator. Airtime and bundles can have different operator ids, so use the id for the type the user chose.
5. `get_operator_rates` with that id. Use `q` to search descriptions. Copy the `token` of the chosen product.
6. After confirmation, `create_order` with `price_token` (the token) and `phone`. Do not send `country_id` together with a token.
7. Share the `payment_link`. For a top-up it looks like `https://www.doctorsim.com/{locale}/{country}/topup-phone/checkout/{hash}`.
8. Follow up with `get_order_status`.

Do not use `search_products` on its own for a phone top-up. It browses the whole country catalog by brand.

## Buy a gift card

No phone and no `country_id` in the order.

1. Ask for the brand and the country of the card.
2. `get_giftcard_brands` with `country` (ISO-2 such as `es`, or numeric id) and optionally `q` for the brand name. Results are paginated: when `meta.has_more` is true, pass `cursor=meta.cursor` to get more.
3. `get_giftcard_brand_products` with the brand id. Show the denominations and copy the `token` of the one chosen.
4. After confirmation, `create_order` with `price_token` only.
5. Share the `payment_link`. The code is emailed after payment.
6. For several denominations, make one `create_order` call per card, each with a different `idempotency_key`. If a result has no `order_id`, check `list_orders` or `get_order_status` before trying again. Never create the order twice.

## Accounts, credits and machine payments

Guest checkout needs no account. Two other modes exist, and both are documented by doctorSIM, not by this skill:

- PRO accounts with prepaid credits: OAuth or an API key, and `preview_order` is mandatory before `create_order`. See https://www.doctorsim.com/auth.md and the order flow reference.
- Machine payments (x402 with USDC, MPP with a Stripe Shared Payment Token): see https://api.doctorsim.com/v2/x402/discovery.json and https://api.doctorsim.com/v2/mpp/openapi.json.

Only go down these paths if the user asks. Sandbox keys start with `test_` and place no real orders.

## When something is not covered

Anything not described here (order disputes, refunds, delivery problems, device compatibility, a product that the catalog does not list) goes to the website in the user's locale: the contact page, the order tracking page or the product pages of that locale. Do not promise outcomes for those.

## References

- doctorSIM's own skill: https://www.doctorsim.com/agents/SKILL.md
- MCP guide: https://www.doctorsim.com/api-docs/mcp.html
- Order flow: https://www.doctorsim.com/agents/references/order-flow.md
- Error codes: https://www.doctorsim.com/agents/references/errors.md