LetsCloud MCP Server

> 🇧🇷 Versão em português

> **Remote MCP server + REST API to manage LetsCloud infrastructure with AI assistants.**

This project exposes LetsCloud's cloud platform through the Model Context Protocol (MCP) so AI assistants like Claude, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client can create and manage servers, snapshots and SSH keys on behalf of the user.

Unlike "local" MCP servers, this is a hosted service: any LetsCloud customer can connect by providing their API key — no installation required on the client side.

The same backend also exposes a clean REST API under `/api/v1` for plain HTTP integrations (curl, scripts, automations).

✨ Features

• 🔌 Native MCP transport (Streamable HTTP) at `/mcp`
• 🌐 REST API at `/api/v1` mirroring every MCP tool
• 🔑 Per-request authentication via `Authorization: Bearer `
• 📦 Full coverage of the LetsCloud API — instances, SSH keys, snapshots, plans, images, locations, account
• ⚡ Async, fast and lightweight (FastAPI + httpx + official MCP SDK)
• 🐳 Docker-ready
• 📝 Auto-generated OpenAPI docs at `/docs`

🧠 How it works

┌──────────────────┐      Authorization: Bearer      ┌──────────────────────┐
│ AI client (MCP)  │ ───────────────────────────────────────► │ mcp.letscloud.io/mcp │
│ Claude, Cursor…  │                                          │  (this server)       │
└──────────────────┘                                          └──────────┬───────────┘
                                                                         │  api-token: 
                                                                         ▼
                                                            ┌──────────────────────────┐
                                                            │ core.letscloud.io/api    │
                                                            └──────────────────────────┘

The user's API key never leaves the request: the server just relays it to the LetsCloud upstream and returns the response. The server itself stores no credentials.

🚀 Quick start (using the hosted server)

Get your API key

Generate an API key in the LetsCloud dashboard.

Configure your MCP client

Claude Desktop / Cursor / Windsurf (remote MCP)

{
  "mcpServers": {
    "letscloud": {
      "url": "https://mcp.letscloud.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_LETSCLOUD_API_KEY"
      }
    }
  }
}

> Note: the exact field names may differ slightly between clients (some use `transport: "streamable-http"`, others auto-detect). Check your client's docs for "remote MCP server".

Test from curl (REST API)

curl -H "Authorization: Bearer YOUR_LETSCLOUD_API_KEY" \
     https://mcp.letscloud.io/api/v1/account

curl -H "Authorization: Bearer YOUR_LETSCLOUD_API_KEY" \
     https://mcp.letscloud.io/api/v1/instances

🛠️ Available tools

Full interactive docs (with request/response schemas) are available at `/docs`.

📡 Hosted vs self-hosted

This project ships as a hosted service at ,

operated by the LetsCloud team. As an end user you only need your

LetsCloud API key — there is nothing to install locally.

If you want to run your own private instance (corporate VPC, offline

tests, contributions), see DEPLOY.md for a one-command Docker

or Python setup.

🔐 Authentication

Every request to `/mcp` and `/api/v1/*` must carry the user's LetsCloud API key in one of:

• `Authorization: Bearer ` (recommended, MCP-friendly)
• `X-LetsCloud-Token: ` (fallback)

The server forwards the key to LetsCloud's API as `api-token: ` (matching the official Go SDK behavior). The server stores nothing.

🏗️ Architecture

src/letscloud_mcp/
├── main.py             # FastAPI app, mounts /mcp and /api/v1
├── __main__.py         # uvicorn entrypoint  (python -m letscloud_mcp)
├── config.py           # Settings via pydantic-settings
├── auth.py             # Per-request token extraction (ContextVar)
├── logging_setup.py    # structlog
├── letscloud/
│   ├── client.py       # Async httpx client for core.letscloud.io
│   ├── models.py       # Pydantic models (Profile, Instance, Snapshot…)
│   └── exceptions.py
├── mcp_app/
│   ├── server.py       # FastMCP server (Streamable HTTP)
│   └── tools.py        # @mcp.tool functions
└── rest/
    └── routes.py       # FastAPI router for /api/v1

📄 License

MIT — see LICENSE.

🔗 Links

• LetsCloud – cloud provider
• Official Go SDK – the basis for this client
• Model Context Protocol
• Self-hosting guide
• Security policy · Contributing