MCP Server

What roamzy-io/mcp-server MCP server does

The roamzy-io/mcp-server MCP server exposes Roamzy’s eSIM API as structured MCP tools. It lets an agent create and manage one universal eSIM that works across 193 countries, with usage charged per actual megabyte at the applicable local rate. Users fund the eSIM with a stablecoin rather than choosing a country-specific package or data allowance.

The server supports both anonymous and authenticated account flows. Without ROAMZY_API_TOKEN, the first account-scoped call creates an anonymous Roamzy account and keeps its session token in memory. An authenticated token can be supplied when an existing account should be used instead.

How it works

The package is a thin HTTP client rather than an independent backend. It maps MCP tool calls to endpoints under https://roamzy.io/api/v1, returning structured JSON. It does not use filesystem access, child processes, telemetry, or environment scanning beyond the documented ROAMZY_* variables. The API destination can be changed with ROAMZY_API_BASE for a staging or self-hosted backend.

A purchase flow begins with roamzy_status, then checks currently enabled stablecoin and network combinations through roamzy_payment_options. The user must choose the payment currency and network before roamzy_create_order is called. The minimum top-up is $20 USDT. After payment, roamzy_order_status can be polled until completion, followed by roamzy_get_esim to obtain activation data.

Setup and configuration

Add the package as a standard stdio MCP server in the client configuration:

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

The package requires Node.js 20 or newer. An alternative hosted tarball can be supplied as the npx argument. ROAMZY_API_TOKEN selects a pre-existing account; leaving it unset enables anonymous mode. For non-anonymous tokens, ROAMZY_ENABLE_PURCHASE=true is required to expose purchase tools. ROAMZY_API_BASE overrides the default API base URL.

Tools and capabilities

The roamzy-io/mcp-server MCP server includes tools for:

• Checking service status and purchase pause flags.
• Listing supported countries and per-megabyte rates.
• Looking up a destination’s rate or estimating a usage cost.
• Retrieving official support, refund, and anonymous-account recovery guidance.
• Listing available stablecoin and network choices.
• Reading account details, eSIMs, balances, statuses, and MSISDNs.
• Creating orders, checking pending payments, and retrieving activation payloads.
• Reading referral links, earnings, and payout state.

roamzy_get_esim returns an LPA URI and QR payload, not a ready-made QR image. A client that wants to display a QR code must generate the image locally. In anonymous mode, users must retain the claim URL because the in-process session is not persisted between client sessions.

Limitations and notes

Country and estimate tools are informational; users do not select a country or data volume when purchasing. The eSIM works throughout the supported coverage area and charges for actual usage. Only one pending order can be active at a time, and an unpaid reservation can remain for 30 minutes. Purchase tools are gated by configuration and spending limits, and agents must stop purchase attempts when the status response reports purchases_paused=true.