Give your AI agent a global eSIM in five minutes

Most "AI buys something for you" demos are smoke. The agent fills a form, or hands you off to a checkout page, or quietly assumes a human is standing by to scan a code. Connectivity is one of the few categories where the whole loop actually closes inside the chat — and this is the tutorial that gets you there.

By the end you will have an agent that can answer "what would data in Japan cost me?" and, when you ask it to, mint you a real eSIM and hand you a QR code and a payment link — without you ever creating a Roamzy account. Two setup paths follow. Pick one; they reach the same place.

Thirty seconds of context before you wire anything up

It helps to know what you are connecting to, because it is not shaped like the eSIM products you may have used:

• One product, not a catalogue. A single universal eSIM that works in all 193 countries. There are no per-country bundles to choose and nothing to pick a size or duration for.
• Per megabyte, no expiry. You fund a balance in stablecoins; data debits it at the local per-MB rate wherever the device is; unused balance carries over forever. The model is covered in depth in pay-per-MB explained.
• Anonymous by default. The agent does not need an account or a token to start. The first authenticated call mints an anonymous Roamzy account automatically. Identity is opt-in, later.
• Twelve tools. Read tools (status, catalog, country detail, cost estimate, your eSIMs and orders) are open; the purchase tool is the only one that moves money, and it is bounded by spending caps you will see below.

If the broader "why connectivity is the natural first thing an agent buys" argument is what you are after rather than the wiring, start with agentic commerce and connectivity and come back here.

Path A — Remote endpoint, zero install (about 2 minutes)

This is the fastest path and needs nothing installed. It works with Claude.ai and any client that speaks remote (Streamable HTTP) MCP.

1. Open your client's connector settings. In Claude.ai that is Settings → Connectors → Add custom connector.
2. Paste the endpoint URL: https://roamzy.io/mcp
3. Save. The twelve Roamzy tools appear. You are connected.

That is the entire install. There is no token to paste and no package to download. The endpoint is anonymous-first by design — it never returns a 401, so a client connects without an OAuth dance and acts against a fresh anonymous account. (An OAuth identity layer exists for clients that want named sign-in, but you do not need it to begin.) Skip to the five-minute payoff below.

Path B — Local install via npm (about 5 minutes)

Use this for desktop and editor clients: Claude Desktop, Cursor, Continue, Cline, Windsurf, Zed, or anything else that runs a local MCP server over stdio.

Add one block to your client's MCP config file — for Claude Desktop on macOS that is ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "roamzy": {
      "command": "npx",
      "args": ["-y", "@roamzy/mcp-server"]
    }
  }
}

No environment block is needed — leaving ROAMZY_API_TOKEN unset is what puts the server in anonymous mode. If you already run other MCP servers, merge the roamzy key into your existing mcpServers object rather than overwriting the file. Then fully restart the client (on Claude Desktop, quit with Cmd-Q, not just the window). The first authenticated tool call mints your anonymous account.

Three optional environment variables exist, none required for the anonymous flow:

• ROAMZY_API_TOKEN — set this to a token from your dashboard to act as a named account instead of an anonymous one.
• ROAMZY_ENABLE_PURCHASE — defaults to false for a named token (read-only until you opt in), but is on automatically in anonymous mode. With a named token, the purchase tool stays hidden until you set this to true — defence in depth against a config typo spending money.
• ROAMZY_API_BASE — override the API base for staging or self-hosted backends.

The five-minute payoff: ask it to buy

Before the sample conversation, one mental model that trips people up. Because Roamzy is a single global eSIM billed per megabyte, there are two things you should not tell the agent, and a well-behaved agent will not ask you for them:

• Not a country. The eSIM works everywhere; you do not buy "a Japan eSIM."
• Not a data amount. There is no bundle to size. You are not buying gigabytes; you are funding a balance.

What the agent does need from you is a top-up amount (minimum $20 USDT) and which stablecoin and network you want to pay with. Here is the flow end to end:

You: I'm heading to Thailand next week — set me up with data.

Agent: Roamzy is one universal eSIM that works in 193 countries, billed per MB at the local rate — no packages, no expiry. How much would you like to top up? Minimum is $20 USDT. And which stablecoin and network do you want to pay with — for example USDT on TRON, BSC, or TON, or USDC on Solana?

You: $20, USDC on Solana.

Agent: Done. Your eSIM number is 2040XXXXXX. Pay here: [payment link]. Save this recovery link so you can reach this eSIM from another chat: [claim link]. I'll fetch your QR once the payment confirms.

What happened under the hood, tool by tool:

1. roamzy_status — a quick liveness and policy check (is the service up, are purchases enabled).
2. roamzy_estimate(country_slug, mb_estimated) — optional, only if you asked "what would X cost." This is a reference calculation, not a purchase input; it does not commit anything.
3. roamzy_payment_options — fetches the live list of stablecoins and networks, so the agent offers you real choices instead of guessing. This step is mandatory before a purchase: picking a network for you would lock the checkout to a chain you might not hold.
4. roamzy_create_order(amount_usdt, pay_currency, country_slug) — mints the eSIM and the invoice. country_slug here is only an invoice tag (defaults to a low-rate reference); it does not restrict where the eSIM works. Returns your phone number (MSISDN), a payment URL, and — in anonymous mode — a claim URL.
5. roamzy_order_status(order_id) — polled until the USDT payment confirms, typically one to fifteen minutes depending on the network.
6. roamzy_get_esim(esim_id) — returns the activation surfaces once paid: a QR image to render in chat, the raw QR payload, and a one-tap install link for when the agent and the phone are the same device.

The guardrails you get without configuring anything

Autonomy is only reasonable if it is bounded, so the bounds are on by default. Every agent token — including the anonymous one created for you — carries:

• Spending caps. An anonymous session is held to $30 per day, $100 per month, a $30 cool-off ceiling on a brand-new token, a single active eSIM, and any transaction over $50 bounced back for human confirmation. A named (claimed) account gets $50/day, $500/month, a $50 cool-off, a $200 big-transaction gate, and up to five eSIMs.
• A budget the agent can see. Remaining limits come back on every call, so the agent reasons about what it has left rather than discovering a cap by hitting it.
• Kill switches. Three independent ones — revoke a single token, block an individual account's agent access, or pause all agent purchasing globally — with current state readable at roamzy_status.

You do not switch any of this on. It is the default, and the deeper design rationale is in the developer guide.

Upgrading from anonymous to a named account

An anonymous eSIM works fully — it can be topped up and used indefinitely. When you want to tie it to a real identity (to raise the caps, manage it in a browser, or simply not depend on a saved link), claim it. Open the claim link, sign in with Google or Telegram, and enter the one-time code; the eSIM and its balance move onto your named account. It is entirely optional and happens after the purchase, never before it. Paid in USDT or USDC, the balance does not care which account holds it.

When something does not work

• No Roamzy tools appear. Almost always a JSON typo in the config or an incomplete restart. Validate the JSON, and on Claude Desktop quit fully with Cmd-Q rather than closing the window.
• The agent can read but not buy. Anonymous mode exposes the purchase tool automatically. With a named token you need both purchase scope on the token and ROAMZY_ENABLE_PURCHASE set to true.
• The agent asks "which country?" That is the anti-pattern from earlier — the eSIM is global. A correct agent asks only for a top-up amount and a payment method. If yours insists on a country, it is reasoning from a bundle model that does not apply here.
• Payment seems stuck. USDT and USDC confirmations take roughly one to fifteen minutes depending on the network; the agent should poll roamzy_order_status rather than assume failure.

Where to go next

You now have an agent that can buy connectivity. For the architecture behind the MCP server and the API design choices, read the developer guide. For how this stacks up against the incumbent consumer marketplace, the Roamzy vs Airalo comparison is candid about where each wins. The one-page overview of the whole agent surface lives at agents.html, the REST API is documented at /api/v1/docs, and long-form guidance written for engines is at /llms-full.txt. If you get stuck, the support bot is @roamzy_support_bot.