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

# API and MCP

> Deploy and manage Ubuntu VPS instances with the RepoCloud REST API or from MCP clients that can send a custom Authorization header

## Overview

The RepoCloud API lets you deploy, manage, and destroy Ubuntu VPS instances programmatically. It works on servers that were created through the API with a key: an Ubuntu VPS made in the dashboard answers 404 to every API call. It is ideal for:

- **AI coding agents** (Cursor, Claude Code, Codex) that need to provision servers on demand
- **Automation scripts** that deploy infrastructure as part of CI/CD pipelines
- **Custom dashboards** that manage RepoCloud instances alongside other services

The API is available at `https://repocloud.io/api/v1/` and follows REST conventions with JSON request and response bodies, with the exceptions listed under [Response Format](https://repocloud.io/docs/api/introduction.md#response-format).

## MCP Integration

The same API powers the **Model Context Protocol (MCP)** integration. An MCP client that can send a custom `Authorization` header connects to RepoCloud as a tool server at `https://mcp.repocloud.io/mcp`, and its AI agent can deploy servers, check instance status, and manage Ubuntu VPS servers created through the API, in natural language. The server offers five tools, and each one calls one REST endpoint with your own key.

> **[Authentication](https://repocloud.io/docs/api/authentication.md)**
>
> Create API keys and authenticate requests

> **[Deploy Instances](https://repocloud.io/docs/api/deploy.md)**
>
> Deploy new Ubuntu VPS instances

> **[List and Get Instances](https://repocloud.io/docs/api/instances.md)**
>
> List, inspect, and delete instances

> **[Instance Actions](https://repocloud.io/docs/api/actions.md)**
>
> Power on/off, reboot, and resize instances

> **[API Key Management](https://repocloud.io/docs/api/keys.md)**
>
> Create, list, and revoke keys (needs your dashboard session)

> **[MCP Setup](https://repocloud.io/docs/api/mcp-setup.md)**
>
> Configure AI agents to use RepoCloud as an MCP server

## Quick Start

**1. Get an API Key**

Make a payment of $1 or more on your account, then go to the [API / MCP tab](https://repocloud.io/mcp) in your dashboard. The first visit creates a key called `Default` and shows it once ("Copy it now — it won't be shown again."). Later keys come from **Generate New Key**. Without the payment, the page shows no key.

**2. Deploy a VPS**

```bash
curl -X POST https://repocloud.io/api/v1/instances \
  -H "Authorization: Bearer rcmcp_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"project_name": "my-server", "flavor": "s-1vcpu-2gb"}'
```

The call needs a balance above $3 and answers HTTP 202 with the details of the new server, including the `instance_id` that the next call uses. See [Deploy Instances](https://repocloud.io/docs/api/deploy.md) for the whole reply.

**3. Check Status**

```bash
curl https://repocloud.io/api/v1/instances/123 \
  -H "Authorization: Bearer rcmcp_your_key_here"
```

The number is the `instance_id` of the deploy reply, an integer.

## Scope

The API currently supports **Ubuntu VPS instances only**, and it sees only the servers created through it with a key. It has no endpoints for snapshots, SSH keys, custom domains, billing, Container Apps, or AI Deploy. Container App deployment and management are available through the web dashboard. Applications that RepoCloud installs on a VPS (Coolify, Dokploy, and others) go through [AI Deploy](https://repocloud.io/docs/deployment/ai-deploy.md), which puts a GitHub project on an Ubuntu VPS and is not part of the API.

## Base URL

All API endpoints use the base URL:

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

Paths are appended directly, for example `https://repocloud.io/api/v1/instances`.

## Response Format

Responses are JSON. Successful responses return the requested data directly. Errors return a JSON object with an `error` field and an optional `detail` field; some also carry `hint`, `retry_after`, or `balance`:

```json
{
  "error": "Insufficient balance",
  "detail": "Balance must be greater than $3 to deploy. Deposit at /billing.",
  "balance": 2.5
}
```

Not every failure is JSON. An unknown path answers an HTML 404 page and a wrong method an HTML 405 page. A request body that is not a JSON object (or that has a number where text is expected) answers the default HTML 500 page, as does an unexpected fault while deleting a server.

## Rate Limits

| Scope | Limit |
|-------|-------|
| General (every call that carries a key) | 60 requests per 60 seconds per API key |
| Deploy (`POST /instances`) | 5 requests per hour per API key; every attempt counts, including one that fails validation |

When rate-limited, the API returns HTTP 429 with a `Retry-After` header indicating how many seconds to wait (at most 60 for the general limit and at most 3600 for deploys), and the same number in the JSON field `retry_after`:

```json
{
  "error": "Rate limit exceeded",
  "retry_after": 42
}
```

The key management routes (which use your dashboard session) and the OpenAPI file are not counted. The counters live in the memory of each web server process.