How an AI assistant can buy a travel eSIM: a look at doctorSIM's public MCP server

doctorSIM — Wed, 11 Nov 2026 13:41:27 +0000

If you have built an agent that plans trips, the last step is usually where it stalls. The assistant can pick a destination and compare options, then it has to hand the user a link and hope. We run doctorSIM, an online store for travel eSIMs, prepaid top-ups and digital gift cards, and we publish a remote MCP server so an assistant can go further: read the live catalog, check a phone number, and create an order. This post walks through what the server does and how the calls fit together.

What the server is

The endpoint is https://api.doctorsim.com/mcp. It speaks MCP over Streamable HTTP, so any client that supports remote servers can connect without a local process. For guest checkout it needs no API key and no headers. OAuth 2.0 exists for PRO accounts that want to pay from prepaid credit, but you can ignore it for the flow below.

The server exposes 23 tools. They cover eSIM destinations and plans, carrier lookup, operator rates, gift card brands, orders and, for linked accounts, balance and webhooks. Prices are never stored in the model's memory or in your prompt: the assistant reads them from the catalog in the same conversation.

Buying a travel eSIM

The eSIM flow needs no phone number. It goes in five calls:

get_esim_destinations lists the countries and regions we cover. A country is an ISO-2 code such as es or it; regions use slugs like eu and ww.
get_esim_plans takes a country_iso and returns the plans for it. The match is strict, so a query for es gives Spain plans only. If the trip crosses several countries, query the region slug too and compare.
create_order takes the catalog_id and price_token copied from the plan the user picked. Both values come from the previous result and are never typed by the model from memory.
The result includes a payment_link. The assistant shows it to the user.
get_order_status takes that link and reports progress. Once the order is fulfilled, the result carries the fields needed to install the eSIM.

Between steps 2 and 3 the assistant should repeat the choice to the user: destination, plan and currency. Creating an order is the one step worth a pause.

Topping up a prepaid phone

The top-up flow starts from a phone number in E.164 format, the + followed by country code and number.

lookup_carrier takes the number and returns the operator and the country.
get_operator_rates takes the operator id and lists what can be bought. The optional q parameter searches product descriptions.
create_order takes the price_token of the chosen product plus the phone.

A wrong digit sends credit to a stranger, so the assistant should read the number back before the last call. If the carrier lookup fails, get_countries and get_operators let the user pick the operator by hand. When a service has several types, get_operator_service_types shows which operator id applies to which type.

Why payment goes through a link

We could have let the assistant take card details. We did not, on purpose. A guest order returns a link on doctorsim.com, the user opens it, enters an email and pays on our checkout. The product is sent to that email after payment.

That keeps card data out of the chat, the model's context and your logs, and the user gets a normal checkout. The link expires after six hours; if the user comes back later, create the order again from the same selection.

One practical rule follows from this. For guest orders, the assistant should not promise a QR code in the conversation. It arrives by email. The status call is there so the assistant can answer "did it go through?" without guessing.

A client configuration

Most MCP clients accept a block like this one. Field names differ a little between clients, so check your client's documentation for the exact key:

{
  "mcpServers": {
    "doctorsim": {
      "type": "http",
      "url": "https://api.doctorsim.com/mcp"
    }
  }
}

Leave headers empty. In clients that ask for an OAuth client ID and secret, leave both blank for guest use.

Then try a prompt such as "I'm going to Japan for ten days, find me an eSIM with plenty of data". A well-behaved assistant will call get_esim_destinations, then get_esim_plans, show a short list and wait for your choice before creating anything.

Things to get right in your agent

Copy catalog_id, price_token and operator ids from tool results. Do not let the model produce them.
Show the user the current price from the result and say it is the current price.
If a tool returns an error, read the Next: hint in the message and follow it.
Do not create an order twice. If a result has no order id, check the order list or the status call first.

Where to read more

The agent documentation is at https://www.doctorsim.com/en/developers-agents.html and the MCP guide is at https://www.doctorsim.com/api-docs/mcp.html. If you want to see the customer side of the product, the eSIM catalog is at https://www.doctorsim.com/en/esim/.

If your client hits a case we did not describe here, tell us through the contact page.

DEV Community: doctorSIM