Skip to Content
OpenRoam Docs

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

GuardWhat it does
Quote, then confirmOrdering takes only a sealed token from a quote, so the agent cannot change items, inputs or prices
Price lockThe 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 quoteThe Idempotency-Key comes from the quote token, so a repeated call returns the same order and never buys twice
Bound to your accountA token works only with the key and environment that created it, and expires within 15 minutes
Spend capOPENROAM_MAX_ORDER_TOTAL refuses any order above your cap before a request is sent
Read-only modeOPENROAM_READ_ONLY=true registers no tool that changes anything or moves money
Product allow-listOPENROAM_PRODUCTS limits the agent to the products you choose
Secrets stay out of chatsGift card codes, PINs, utility tokens and eSIM activation data are hidden unless you allow them
Sandbox by defaultProduction 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/mcp

For 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.

On this page