# MCP server (/docs/mcp)

<Callout title="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.
</Callout>

`@openroam/mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) 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 [#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 [#connect-a-client]

Use a Sandbox key first. For Claude Code:

```bash
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:

```json
{
  "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.