@roamzy/mcp-server

MCP server for Roamzy — buy and manage a global eSIM through Claude Desktop, Cursor, Continue, Cline, Windsurf, Zed, or any other Model Context Protocol client. Anonymous flow by default: no account required to use it.

One eSIM for 192 countries. Pay per actual MB used. USDT or USDC on your preferred network. No packages. No expiry. No subscription.

---

What it does

This MCP server lets an agent (running in any MCP-compatible client) call the Roamzy HTTP API on the user's behalf. Sample conversation in Claude Desktop:

User: I'm going to Thailand for a week, buy me an eSIM.

Claude: Roamzy — one universal eSIM, works in 192 countries. Billed per MB at the local rate, no packages, no expiry. For Thailand the rate is ~$2.15/GB. Which stablecoin / network do you want to pay with? (USDT on TRON, BSC, Polygon, Optimism, Arbitrum, TON — or USDC on Solana, BSC, Polygon, Optimism, Arbitrum.) Minimum top-up is $20 USDT.

User: USDC on Solana, $20.

Claude: Order created. eSIM number 2040XXXXXX. Pay here: [pay-link]. After ~1 minute on Solana, I'll fetch your QR. ❗ Save this recovery URL so you can return to this eSIM from another Claude chat: [claim-link].

User pays $20 USDC.

Claude: Paid. Here's your activation QR — open Settings → Cellular → Add eSIM and scan it with your phone camera. [QR PNG attached]

The server doesn't run a backend itself — it's a thin client to https://roamzy.io/api/v1/*, mapped 1:1 to MCP tools.

---

Install

Add this to your MCP client's configuration (e.g. ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop on macOS):

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

Restart your MCP client. The first authed tool call will mint an anonymous Roamzy account automatically — no signup required.

Alternative: install from a hosted tarball

If you can't reach the npm registry, want to pin a pre-release, or prefer to fetch a specific version directly from Roamzy's CDN, swap the args to a URL:

"args": ["-y", "https://roamzy.io/mcp/roamzy-mcp-latest.tgz"]

Both forms run the same code — the npm registry path is the recommended default because it integrates with npm view, version pinning, and MCP registries (Smithery, modelcontextprotocol/servers, etc.).

Optional environment variables

Variable	Default	Purpose
ROAMZY_API_TOKEN	(unset → anonymous mode)	Use a pre-existing API token from /dashboard/settings instead of an anonymous account.
ROAMZY_ENABLE_PURCHASE	false (but true in anon mode)	When using a non-anonymous token, opt-in flag required to expose purchase tools.
ROAMZY_API_BASE	https://roamzy.io/api/v1	Override for staging / self-hosted backends.

---

Tools

Public (no auth required)

Tool	Purpose
roamzy_status	Service status + agent-pause flags. Call before any purchase attempt.
roamzy_list_countries	Reference list of all 192 supported countries with per-MB rates.
roamzy_country_detail	Per-MB rate for one country.
roamzy_estimate	Reference calc: «how many USDT would N MB cost in country X».
roamzy_support	Official support channels + recovery procedure. Call instead of web-searching.
roamzy_payment_options	Currently-enabled stablecoins + networks (live from NowPayments). Call before order.

Account-scoped (anonymous or token)

Tool	Purpose
roamzy_me	Current Roamzy account info (auto-mints anonymous account on first call).
roamzy_list_esims	The account's eSIMs with MSISDN, status, balance.
roamzy_get_esim	One eSIM's activation details (QR payload, LPA URI). Generate the QR PNG locally.
roamzy_order_status	Poll a pending order: waiting → confirming → finished.

Purchase (anonymous or token + ROAMZY_ENABLE_PURCHASE=true)

Tool	Purpose
roamzy_create_order	Mint a new eSIM and fund it. Min top-up $20 USDT. Requires pay_currency from options.

Each tool returns structured JSON. Tool descriptions (visible via tools/list) encode the agent contract — when to call each tool, what to surface to the user, what to keep internal.

---

Anonymous flow

When the MCP server starts without ROAMZY_API_TOKEN, the first authed call sends POST /api/v1/anon-session (no auth) to mint a fresh anonymous Roamzy account. The server caches the returned token in-process (never written to disk) and uses it for subsequent calls.

The response also includes a claim_url — a magic-link that lets the user later attach this anonymous account to a permanent Google or Telegram identity. Once attached, the eSIM, balance, and history become visible from /dashboard/esims on the web.

Important: the anonymous token lives only in this MCP server process. If the user closes their MCP client (e.g. quits Claude Desktop) without saving claim_url, the access path is lost — the eSIM itself keeps working, but the user can't see or manage it from a new session. The recovery procedure (operator-mediated via support) is described in the roamzy_support tool response.

Anonymous accounts have conservative daily / monthly spending caps and a cool-off period that gates large transactions; exact thresholds are shown to the user in the dashboard once they claim.

---

Security model

• No filesystem access. The server only makes HTTP calls.
• No child processes.
• No environment scan beyond explicit ROAMZY_* variables.
• Outbound traffic only to https://roamzy.io (override via ROAMZY_API_BASE if you self-host).
• Purchase tools are registered only in anonymous mode or with ROAMZY_ENABLE_PURCHASE=true.
• Per-token spending caps with cool-off period + big-transaction threshold; configurable per token in /dashboard/settings.
• Service status honoured. When roamzy_status reports purchases_paused=true, the agent must back off.
• No telemetry. The server doesn't phone home except to call the configured API base.

See SECURITY.md for the disclosure policy.

---

Build from source

git clone https://github.com/roamzy-io/mcp-server.git
cd mcp-server
pnpm install
pnpm build

Output: a single-file ESM bundle at dist/index.js (~520 KB, self-contained, executable via Node 20+).

To produce a tarball for distribution:

pnpm build:tgz
# → dist/roamzy-mcp-server-<version>.tgz

---

Links

• Website: https://roamzy.io
• API docs: https://roamzy.io/api/v1/docs
• For agents: https://roamzy.io/agents.html
• Long-form for AI engines: https://roamzy.io/llms-full.txt
• Support: @roamzy_support_bot or support@roamzy.io
• Security: roamzy.agent@gmail.com (SECURITY.md)

---

License

MIT — © 2026 Artur. The Roamzy name and brand are trademarks of the Roamzy service operator and are not licensed under MIT.