Buy an eSIM through Claude Desktop in 60 seconds

The hardest part about agent commerce is that most products were never built for agents. Card-on-file flows assume a human is squinting at a billing screen. eSIM apps assume a phone with the camera ready to scan a QR code. Stripe assumes a checkout page tied to a session cookie, which an MCP server cannot supply.

Roamzy was rebuilt from the API layer down to remove those assumptions. The result is a five-minute install that lets Claude Desktop query, estimate, and (with your explicit opt-in) purchase a global eSIM in USDT — and an explicit security model that bounds the blast radius of a leaked token.

What you will end up with

After this tutorial:

• Claude Desktop with eight Roamzy tools registered (catalog, country detail, estimate, status, plus authenticated read tools for your own eSIMs and orders)
• An API token in your Claude config that lets the agent act as you, scoped to read-only by default
• The ability to enable purchases by flipping a single env var when you are ready

Total time: about 60 seconds of installation and 4 minutes of asking Claude to do interesting things.

Step 1: Create an API token in the Roamzy dashboard

Sign in at roamzy.io/dashboard with Google or Telegram. Open Settings → API & Agents. Click Create new token.

The token plain text appears once and only once — copy it immediately into a password manager. The server never stores the plain text after this screen closes; it keeps a SHA-256 hash for verification and a 12-character prefix-hint (rk_live_abc1…) for display.

Leave the Allow purchases checkbox unchecked for your first install. Read-only tokens cannot spend USDT — they can only query catalogs and check status. This is the right default. You can always create a second token later with purchase scope enabled.

Step 2: Find your Claude Desktop config file

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%\Claude\claude_desktop_config.json

If the file does not exist yet, create it. It is plain JSON.

Step 3: Add the Roamzy MCP server

{
  "mcpServers": {
    "roamzy": {
      "command": "npx",
      "args": ["-y", "https://roamzy.io/mcp/roamzy-mcp-latest.tgz"],
      "env": {
        "ROAMZY_API_TOKEN": "rk_live_xxx",
        "ROAMZY_ENABLE_PURCHASE": "false"
      }
    }
  }
}

Replace rk_live_xxx with your actual token. The npx command will download the tarball directly from our domain — no GitHub or NPM credentials needed.

If you already have other MCP servers configured, merge the roamzy key into your existing mcpServers object rather than replacing the whole file.

Step 4: Restart Claude Desktop

Quit Claude Desktop completely (Cmd-Q on Mac, not just close the window) and reopen it. On startup, Claude reads the config file once and spins up each MCP server as a subprocess.

You should see the Roamzy tools appear in the tools menu (the little icon in the bottom-right of the input area). If they do not appear within ten seconds, check Claude Desktop's log for errors — usually a typo in the JSON config or a wrong token.

Step 5: Ask Claude something interesting

Try this prompt:

I am flying to Tokyo next week for a 10-day trip. How much will an eSIM through Roamzy cost me if I expect to use about 2 GB total?

What Claude does behind the scenes:

1. Calls roamzy_country_detail(country_slug="esim-japan") to confirm Japan is covered and to get the current per-MB rate.
2. Calls roamzy_estimate(country_slug="esim-japan", mb_estimated=2048) to project the USDT cost.
3. Returns a concise answer with the projected cost and the minimum top-up.

For 2 GB in Japan at our current rate of $0.0033/MB, the projected cost is around $7 USDT. The minimum top-up on Roamzy is $20, so Claude will tell you to top up at least $20 to be safe.

Enabling purchases (when you are ready)

To let Claude actually buy an eSIM rather than just estimate one, two things have to be true:

1. The token must have purchase scope enabled. Edit the token in the dashboard or revoke and create a new one with the Allow purchases checkbox.
2. The MCP server config must have ROAMZY_ENABLE_PURCHASE: "true". This is a separate flag from the token scope — even with a purchase-enabled token, the MCP server will not expose purchase tools unless this env var is set. Defense in depth against config typos.

Once both are true, restart Claude Desktop and try:

Buy me a Roamzy eSIM for the Tokyo trip with a $20 top-up.

Claude will call roamzy_create_order, which spends from the token's daily budget (default $50). The API returns a USDT payment URL — Claude shares it with you, you pay from your wallet, the webhook confirms, and Claude can then fetch the QR image URL to render in chat. Scan with your phone camera and the eSIM installs.

The security model in one paragraph

Five layers protect you from a runaway agent. Daily and monthly spending caps per token (default $50/day, $500/month, configurable up to $1000/$10000). A 7-day cool-off of $50 total spend on every new token, not raisable. Big-transaction confirmation: anything above $200 USDT is blocked at the API level and requires you to confirm in the dashboard. Purchase scope is opt-in per token. And there are three independent kill switches: per-token revoke, per-user agent-block, and global agent pause, with status visible at /api/v1/status.

For deeper detail, see /llms-full.txt — the long-form guidance we publish specifically for AI agents and engines.

What about other AI clients?

Cursor, Continue, Cline, Windsurf, and any other MCP-compatible client use the same config block — just put it in their respective config file. For non-MCP clients (LangChain, OpenAI function calling, n8n, custom Python scripts), call the REST API directly at /api/v1/docs. Same token, same security model.

That is the whole tutorial. If you get stuck, the Roamzy Telegram support bot is at @roamzy_support_bot.