MCP server
Connect AI assistants and agents to the Partner API with the OpenRoam MCP server.
Private beta
The MCP server is in private beta and not on a public package registry yet. OpenRoam sends you the release file to install.
@openroam/mcp is a Model Context Protocol server. It connects AI assistants and agents (Claude, Cursor, VS Code and any other MCP client) to the Partner API. With one API key, an agent can search, price, buy and manage airtime, utility bill payments, gift cards, eSIMs, hotels and flights, and follow delivery to the end.
Every tool call is a normal Partner API request made with your key, so your permissions, enabled products, validation, idempotency and errors apply exactly as they do to your own integration.
A second group of read-only tools helps developers integrate the API: they search the documentation, explain an error, check a request before it is sent and build a signed test webhook event. Most of them work without a key.
Why it is safe to let an agent buy
| Guard | What it does |
|---|---|
| Quote, then confirm | Ordering takes only a sealed token from a quote, so the agent cannot change items, inputs or prices |
| Price lock | The order is sent with each quoted unit price as maxPrice and the quoted total as maxTotal. If a price rose, nothing is charged |
| One purchase per quote | The Idempotency-Key comes from the quote token, so a repeated call returns the same order and never buys twice |
| Bound to your account | A token works only with the key and environment that created it, and expires within 15 minutes |
| Spend cap | OPENROAM_MAX_ORDER_TOTAL refuses any order above your cap before a request is sent |
| Read-only mode | OPENROAM_READ_ONLY=true registers no tool that changes anything or moves money |
| Product allow-list | OPENROAM_PRODUCTS limits the agent to the products you choose |
| Secrets stay out of chats | Gift card codes, PINs, utility tokens and eSIM activation data are hidden unless you allow them |
| Sandbox by default | Production must be chosen explicitly, and every result says which environment it came from |
Moving money between wallets, wallet settings and webhook settings are not available to agents.
Connect a client
Use a Sandbox key first. For Claude Code:
claude mcp add openroam -e OPENROAM_API_KEY=your_sandbox_key -- npx -y @openroam/mcpFor Claude Desktop, Cursor and other clients, add the server to the client's MCP configuration:
{
"mcpServers": {
"openroam": {
"command": "npx",
"args": ["-y", "@openroam/mcp"],
"env": { "OPENROAM_API_KEY": "your_sandbox_key" }
}
}
}During the private beta, replace npx -y @openroam/mcp with the path of the release file you received.