Roamzy MCP tools — full reference
What each of the twelve tools takes, what it returns, and which one spends money. Eleven are read-only and safe to call in any order; one mints an eSIM.
Read tools
Safe to call at any time, in any order. None of them charges anything or changes state, so an agent exploring the surface cannot do damage.
| Tool | Arguments | Returns |
|---|---|---|
roamzy_status | — | API health plus the agent pause flags. Call this before any purchase and back off if purchases are paused — it is how we stop agents during an incident. |
roamzy_list_countries | — | All 193 countries with their per-MB rate in USDT. One eSIM covers all of them; the rate is simply what the meter charges wherever the device is. |
roamzy_country_detail | country_slug (required) | The per-MB rate for one country. Use when the user asks about a specific place rather than pulling the whole table. |
roamzy_estimate | country_slug, mb_estimated (both required) | What a given volume would cost at that country's rate. Arithmetic, not a quote — nothing is reserved. |
roamzy_payment_options | — | The stablecoin and network combinations currently enabled: USDT and USDC across seven chains. |
roamzy_me | — | The current account. ⚠️ A connected MCP does not mean an account exists yet — anonymous accounts are minted on first use, not on connection. |
roamzy_referral | — | Referral link and earnings. An agent earns 20% of every real payment it refers, forever, and an anonymous agent accrues too. |
roamzy_list_esims | — | The account's eSIMs with status, balance and MSISDN. The MSISDN is the only identifier to show a human. |
roamzy_get_esim | esim_id | One eSIM, including the QR payload for activation. Render the QR locally — the payload is a one-shot credential and must never go to a third-party image service. |
roamzy_order_status | order_id (required) | Poll a pending order: waiting → confirming → finished. Crypto settlement typically takes 5–15 minutes. |
roamzy_support | — | The official support and recovery channel. Hand this to a user rather than improvising an address. |
The one tool that spends money
| Tool | Arguments | Effect |
|---|---|---|
roamzy_create_order | amount_usdt, pay_currency | Mints an eSIM and creates an invoice to fund it. Minimum $20. In anonymous mode the response carries a recovery link — surface it to the user and tell them to save it, because it is the only way back to the account. |
It is the only tool with a financial effect, and it is marked as such in the tool annotations, so a client that distinguishes read from write will treat it correctly without being told.
A working sequence
The shortest path from nothing to an installed eSIM:
roamzy_status— confirm purchases are not paused.roamzy_country_detail— get the rate for where the user is going.roamzy_payment_options— pick a chain the user can actually pay on.roamzy_create_order— mint and invoice. Show the user the MSISDN and the payment link.roamzy_order_status— poll untilfinished.roamzy_get_esim— render the QR locally for the user to scan.
No signup step appears anywhere in that list, which is the point: the endpoint never returns 401.
Errors worth handling
- Purchases paused —
roamzy_statussays so. Do not retry in a loop; tell the user and stop. - Spending limits — tokens carry daily and monthly caps. Exceeding one is a refusal, not a failure.
- Order still pending —
finishedcan take fifteen minutes on a slow chain. Poll, do not re-order.
FAQ
How many of the tools change anything?
One. roamzy_create_order mints an eSIM and creates an invoice; the other eleven are read-only and cannot charge or alter anything.
Which tool should an agent call first?
roamzy_status. It reports whether purchases are paused, which is how we stop agent traffic during an incident.
Do the tools need a token?
No. The remote endpoint is anonymous-first and never returns 401. A token only binds activity to an existing account.
What must never be sent to a third party?
The QR payload from roamzy_get_esim. It is a one-shot activation credential — render it locally.
Connect the server
Install snippets and client list:
{
"mcpServers": {
"roamzy": {
"type": "streamable-http",
"url": "https://roamzy.io/mcp"
}
}
}