> ## Documentation Index
> Fetch the complete documentation index at: https://repocloud.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Setup

> Configure Cursor, Claude Code, Codex, Claude on the web and Desktop, and other MCP clients that send a custom header to deploy and manage VPS instances

## What is MCP?

The **Model Context Protocol (MCP)** is an open standard that lets AI agents use external tools. When you connect RepoCloud as an MCP server, your AI coding agent can:

- Deploy Ubuntu VPS instances on demand
- Check server status and get connection credentials (these answers carry the root password, so the agent's conversation holds it)
- Power on, power off, and reboot servers (a powered-off VPS is still billed at the full rate of its tier)
- Resize instances to different resource tiers (the new tier's disk must not be smaller than the current one)
- Delete instances when they are no longer needed (the `confirm` argument must be `true`, and deletion cannot be undone)

All actions use your API key and count against your RepoCloud balance — the AI agent acts on your behalf.

The MCP server is at `https://mcp.repocloud.io/mcp`. Every tool calls one endpoint of the [REST API](https://repocloud.io/docs/api/introduction.md) with your own key, so the rules of the REST pages apply to it.

For how MCP fits with the other AI agents on RepoCloud, see [Your Own Agent](https://repocloud.io/docs/ai-agents/your-own-agent.md).

## Prerequisites

1. A RepoCloud account with email verified
2. A payment of at least $1.00 on the account to create a key, and a balance above $3.00 to deploy (go to [Billing](https://repocloud.io/billing))
3. An API key from the [API / MCP tab](https://repocloud.io/mcp) in your dashboard

## Setup by Agent

The client must reach a remote streamable-HTTP server and let you send a request header. Pick yours:

**Cursor**

Add the following to your Cursor MCP configuration file: `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for every project:

```json
{
  "mcpServers": {
    "repocloud": {
      "url": "https://mcp.repocloud.io/mcp",
      "headers": {
        "Authorization": "Bearer rcmcp_your_key_here"
      }
    }
  }
}
```

To keep the key out of the file, put it in an environment variable and write `"Authorization": "Bearer ${env:REPOCLOUD_API_KEY}"` instead.

The RepoCloud tools are listed under Available Tools, and Cursor asks for your approval before it uses a tool by default.

**Claude Code**

Add RepoCloud with one command:

```bash
claude mcp add --transport http repocloud https://mcp.repocloud.io/mcp \
  --header "Authorization: Bearer rcmcp_your_key_here"
```

You can also write it into `.mcp.json` in your project, where the `type` must be `http`:

```json
{
  "mcpServers": {
    "repocloud": {
      "type": "http",
      "url": "https://mcp.repocloud.io/mcp",
      "headers": {
        "Authorization": "Bearer rcmcp_your_key_here"
      }
    }
  }
}
```

Run `claude mcp list` to see the configured servers, or type `/mcp` inside a session.

**Codex**

Add the server to `~/.codex/config.toml`, or to `.codex/config.toml` in a trusted project, and keep the key in an environment variable:

```toml
[mcp_servers.repocloud]
url = "https://mcp.repocloud.io/mcp"
bearer_token_env_var = "REPOCLOUD_API_KEY"
```

Set `REPOCLOUD_API_KEY` to your key before you start Codex. Run `codex mcp list` to see the configured servers, or type `/mcp` in the Codex terminal interface.

**Claude on the web and Desktop**

Claude connects to a remote server from Anthropic's cloud, not from your computer, so the address must be public, which RepoCloud's is. Open **Customize**, then **Connectors**, click **Add**, and choose **Add custom connector** (on Team and Enterprise plans an owner adds it under Organization settings). Then:

1. Enter `https://mcp.repocloud.io/mcp` as the server address.
2. Choose **No sign-in** as the authentication.
3. Under **Request headers**, add a header named `Authorization` with the value `Bearer rcmcp_your_key_here`. Claude sends the value exactly as you type it, so it must start with `Bearer` and a space.

Request headers are in beta and available to a limited set of organizations: if you do not see the **Request headers** section, your organization does not have access yet. You cannot change a connector's headers after you add it: to change the key, remove the connector and add it again. On Team and Enterprise plans, everyone who uses the connector reaches RepoCloud with that one key.

**Other MCP Clients**

A client can connect if it reaches a remote streamable-HTTP server and lets you set a request header. Use the following server configuration:

- **Server URL**: `https://mcp.repocloud.io/mcp`
- **Authentication**: Bearer token in the `Authorization` header
- **Token format**: `Bearer rcmcp_your_key_here`

RepoCloud has not verified that ChatGPT can attach a fixed `Authorization` key to a custom MCP server, so this page gives no steps for it.

## Available Tools

Once connected, the AI agent has access to these tools:

| Tool | Arguments | Description | Maps to API Endpoint |
|------|-----------|-------------|---------------------|
| `provision_ubuntu_vps` | `project_name`, `flavor` (optional, defaults to `s-2vcpu-2gb`), `ssh_public_key` (optional) | Deploy a new Ubuntu VPS | `POST /api/v1/instances` |
| `list_instances` | none | List all API-created instances | `GET /api/v1/instances` |
| `get_instance_status` | `instance_id` | Get instance details and live status | `GET /api/v1/instances/{id}` |
| `manage_instance` | `instance_id`, `action`, `flavor` (for a resize) | Power on/off, reboot, or resize. The `action` is one of `power_on`, `power_off`, `reboot` and `resize`: it is the `type` of the REST body | `POST /api/v1/instances/{id}/actions` |
| `destroy_instance` | `instance_id`, `confirm` | Destroy an instance; the tool refuses unless `confirm` is `true` | `DELETE /api/v1/instances/{id}` |

When RepoCloud refuses a call, the tool returns an `error` text and the HTTP `status_code`, with a plain hint added for 401, 402, 403, 404, 409, 422, 429, and 503.

## Example Conversations

Here are examples of what you can ask your AI agent after connecting RepoCloud:

### Deploy a server

> "Deploy a new 4 GB Ubuntu VPS called 'staging-api' and give me the SSH credentials when it's ready."

The agent will call `provision_ubuntu_vps` with the appropriate flavor, poll `get_instance_status` for readiness, and return the connection details.

### Check server status

> "What's the status of all my servers created through the API?"

The agent will call `list_instances` and summarize the results. Servers you deployed from the dashboard are not in that list.

### Resize a server

> "Resize my staging-api server to 8 GB RAM."

The agent will identify the instance and call `manage_instance` with `action: resize` and the `s-4vcpu-8gb` flavor. This works from Tier 2, 3, or 4 (30 or 40 GB disks) to Tier 5 (80 GB): a resize never goes to a tier with a smaller disk.

### Clean up

> "Delete all my servers created through the API that are currently powered off."

The agent will list instances, filter for paused ones, and call `destroy_instance` with `confirm: true` for each. Only servers created through the API are in reach, and deletion cannot be undone.

## Security

- Your API key controls the Ubuntu VPS servers created through the API and can read their root passwords, which your AI agent's conversation then holds — treat it like a password
- The AI agent can deploy instances (which costs money) and delete instances (which is irreversible)
- Rate limits apply per key: 60 requests per minute, 5 deploys per hour
- The MCP server does not store your key: it forwards the `Authorization` header of each call to the REST API
- Revoke the key at once from the [API / MCP tab](https://repocloud.io/mcp) if you suspect it has been compromised. Servers already created stay, and another key of your account manages them

## OpenAPI Specification

The full REST API schema is available as an OpenAPI 3.1.0 specification:

```
https://repocloud.io/api/v1/openapi.json
```

The file is written by hand and read at each request. It describes the REST API; the MCP server announces its own tools to the client.

## Troubleshooting

> **Agent says 'tool not found' or 'server unreachable'**
>
> Verify the server URL is exactly `https://mcp.repocloud.io/mcp`. Opening that address in a browser shows a "Not Acceptable" message, which is normal, because it is not a web page; `https://mcp.repocloud.io/health` answers 200 when the server is up.

> **Agent gets 401 Unauthorized**
>
> Check that your API key starts with `rcmcp_` and is active in the [API / MCP tab](https://repocloud.io/mcp). The REST answers are `Missing or malformed Authorization header` (the word `Bearer` is case-sensitive), `Invalid API key prefix`, and `Invalid or revoked API key`. The tool adds "Authentication failed — check your API key."

> **Agent gets 402 when deploying**
>
> Your balance is $3 or less. Add funds at [Billing](https://repocloud.io/billing).

> **Agent gets 429 Too Many Requests**
>
> Rate limit exceeded. The tool answers "Rate limit exceeded — wait and retry." with no wait time; a REST caller gets the `Retry-After` header and `retry_after`. The deploy limit is 5 per hour per key.