RareCloud MCP server: install, scopes and every tool

In one paragraph: @rarecloudio/mcp-server is the official Model Context Protocol server for RareCloud. It runs on your machine over stdio, talks to the public API at https://api.rarecloud.io/v1 with an API token you create, and gives your agent 173 tools: 86 that read and 87 that act. Tools that spend money, delete something, interrupt something running or touch access do nothing unless the call carries confirm: true. This page covers version 0.3.0. The source is on GitHub under the MIT licence.

Before you start

• Node.js 21 or newer. The package declares node >= 21 and the clients below start it with npx.
• A RareCloud account and an API token (next section).
• An MCP client: Claude Code, Claude Desktop, Cursor, Windsurf or any other client that can launch a stdio server.

Create an API token

In the console open Account, then API tokens, then New token. Give it a name, pick its scopes, and optionally an expiry date and a rate limit (1 to 600 requests a minute). The token starts with rc_pat_ and is shown once, so copy it before you close the dialog.

The MCP server reads the token from the environment variable RARECLOUD_API_TOKEN. (The CLI and the Terraform provider use RARECLOUD_TOKEN instead.)

Scopes

Scope matching is exact. services:write does not include services:read, so give an agent that reads and acts both scopes. Patterns like *:read are not supported. The tool list is the same whatever the token holds: an under-scoped call comes back from the API as a permission error.

A sensible start: a read-only token (account:read, services:read, billing:read, domains:read, tickets:read). Add a :write scope when you want the agent to act in that area.

Install

Claude Code

claude mcp add rarecloud -e RARECLOUD_API_TOKEN=rc_pat_... -- npx -y @rarecloudio/mcp-server

Options such as -e go before the server name; the command that starts the server goes after --. Add -s user to make it available in every project instead of only the current one. Check it with claude mcp list.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows, then restart Claude Desktop:

{
  "mcpServers": {
    "rarecloud": {
      "command": "npx",
      "args": ["-y", "@rarecloudio/mcp-server"],
      "env": { "RARECLOUD_API_TOKEN": "rc_pat_..." }
    }
  }
}

Cursor

Put the same block in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "rarecloud": {
      "command": "npx",
      "args": ["-y", "@rarecloudio/mcp-server"],
      "env": { "RARECLOUD_API_TOKEN": "rc_pat_..." }
    }
  }
}

Windsurf

Windsurf reads ~/.codeium/windsurf/mcp_config.json. Add the same mcpServers block and refresh the MCP servers in Windsurf's settings.

Any other MCP client

Run npx -y @rarecloudio/mcp-server as a stdio server with RARECLOUD_API_TOKEN in its environment. You can also install it globally with npm install -g @rarecloudio/mcp-server and run the rarecloud-mcp binary.

Optional: another API endpoint

RARECLOUD_API_ENDPOINT changes the API base URL. It defaults to https://api.rarecloud.io and you only need it for a staging instance.

How write gating works

Three layers decide what an agent can do, from the outside in:

1. Token scopes. The API checks them on every request. A token without services:write cannot deploy anything, whatever the agent tries.

2. The confirm gate. Every write tool has one safety kind. 63 of the 87 are gated and refuse to run unless the call passes confirm: true:

   • spends: places an order or charges the account (deploy, resize, renew, register, reserve an IP, add a node pool, create a bucket);
   • destructive: cannot be undone (destroy, delete, cancel, revoke, release, reinstall);
   • disruptive: can be undone but interrupts something running or locks someone out (stop, reboot, detach, move a VM to another network, roll a node pool, replace DNS or credentials);
   • sensitive: grants access or speaks for you (install an SSH key, mint a long-lived kubeconfig, change a bucket's settings, create an S3 key, edit domain contacts or the account profile, open or reply to a ticket).

   Without confirm: true a gated tool makes no API call at all and says what it would have done, so the agent has to come back to you first. There is no "confirm once, run many". The other 24 write tools are plain: they cost nothing, tear nothing down and run as soon as the scope allows.

3. No tool at all. Some things are left out on purpose: password and 2FA changes, sub-user invites, payment methods, API token management, credit top-ups, invoice payment, affiliate activation or withdrawal, and the per-resource API access switch. A token with * still cannot reach them through MCP.

Destructive and disruptive tools also carry the MCP destructiveHint annotation, and every read tool carries readOnlyHint, so clients that show their own approval prompts can treat them accordingly. A few tools return a live secret (kubeconfigs, proxy credentials, S3 secret keys, one-time console passwords); their descriptions tell the agent not to repeat the value back unless you ask.

Resources you made read-only

In the console you can switch API access off for any single service or domain: a VM, cluster, volume, load balancer, network, proxy or hosting plan. The agent can still list it and read its details (it shows apiAccess: "read_only", and list_api_access lists every such resource in one call), but every change to it, and every read of its credentials, is refused with RESOURCE_PROTECTED and a link to the console. Only you can turn it back on, signed in to the console: there is no tool for the switch.

Safe retries

The 40 write tools that create or change something through a route the API protects with an Idempotency-Key take an optional idempotency_key (1 to 255 printable characters). Reuse the same value when retrying the same request and the API runs it at most once, returning the first answer again. Without one, the server makes a fresh key per call and, if the connection drops before the answer arrives, retries once with that key. A replayed answer says it is a replay, and a secret from the first answer (a console password, an S3 secret key) is not repeated. The confirm gate still comes first: without confirm: true no key is made and no request is sent.

Every tool, by area

Generated from the 0.3.0 release. "Write" tools without a gate are plain changes that cost nothing and tear nothing down, and they run as soon as the token's scope allows.

Catalog (8 read, 0 write)

Services (11 read, 21 write)

Orders (2 read, 0 write)

Billing (11 read, 3 write)

Account (11 read, 6 write)

Cloud infrastructure (10 read, 21 write)

Object Storage (7 read, 7 write)

Managed Kubernetes (5 read, 8 write)

Domains (8 read, 7 write)

Proxies (10 read, 11 write)

Support (3 read, 3 write)

Recipes

Type these to your agent. Each one names the tools it should use, so you can check what it did in the tool log.

Deploy a VM. "Deploy a Cloud VM named web-01 in Bucharest on plan g-2vcpu-8gb with Ubuntu 24.04 and my SSH key. Show me the price first." The agent reads the plan with get_product_details, list_regions and list_images, checks with check_order that the order would be accepted, shows you the cost, and after your yes calls deploy_service with category: "cloud-vm", productId: "g-2vcpu-8gb", region: "bucharest-ro", imageId: "ubuntu-24.04" and confirm: true. Then get_provisioning_state until it is running.

Add a volume. "Create a 50 GB volume called web-01-data and attach it to web-01." Uses create_volume (spends, needs your confirm), then attach_volume. Format and mount it inside the VM yourself.

Put a load balancer in front. "Create a load balancer on port 443 for web-01 and web-02." Uses create_load_balancer (spends, needs confirm). It answers at once with status pending and finishes building in the background in a few minutes; the agent polls get_load_balancer until it is active instead of creating it again. It costs €9 a month with its public IP included, billed hourly.

Create a bucket and a key. "Create a bucket called backups in Frankfurt and an access key that can only read it." Uses list_object_storage_regions, create_bucket (spends: the first bucket starts the monthly base fee and needs a handle, your permanent namespace) and create_object_storage_key (sensitive, returns the secret once).

Create a cluster and get a kubeconfig. "Which Kubernetes versions can I pick? Create a cluster with 2 to 4 workers on g-2vcpu-8gb, then give me a 90-day view-only kubeconfig for CI." Uses list_kubernetes_versions (the versions on offer, newest first; a cluster created without a version gets the newest), deploy_service with category: "cloud-k8s" (spends, needs confirm), then create_cluster_kubeconfig (sensitive, needs confirm). For a quick admin session, get_cluster_kubeconfig returns a short-lived one.

Check balance and invoices. "What is my balance, is anything unpaid, and what did I spend this month?" Uses get_credit_balance, get_bonus_balance, list_invoices, get_billing_state and get_billing_alert. Add "alert me if the month passes 50 euro" and it calls set_billing_alert, which flags the alert in the console when spend crosses that figure.

Destroy what you no longer need. "Delete the volume web-01-data, then destroy web-01." Uses detach_volume, delete_volume and destroy_service. The detach is disruptive and both deletions are destructive, so the agent has to ask you, and only a call with confirm: true goes through.

Troubleshooting

Links

• Source and issues: github.com/RareCloudio/rarecloud-mcp-server
• Package: @rarecloudio/mcp-server on npm
• API reference: console.rarecloud.io/docs/api and the OpenAPI spec
• For agents: console.rarecloud.io/llms.txt
• The same API from a terminal or as code: CLI docs and Terraform docs