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 <api-key>
• 📦 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 <api-key>     ┌──────────────────────┐
│ AI client (MCP)  │ ───────────────────────────────────────► │ mcp.letscloud.io/mcp │
│ Claude, Cursor…  │                                          │  (this server)       │
└──────────────────┘                                          └──────────┬───────────┘
                                                                         │  api-token: <key>
                                                                         ▼
                                                            ┌──────────────────────────┐
                                                            │ 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

MCP tool	REST endpoint	Description
get_account_info	GET /api/v1/account	Account profile (name, balance, email…)
list_locations	GET /api/v1/locations	All datacenter locations
list_plans	GET /api/v1/locations/{slug}/plans	Plans available at a location
list_images	GET /api/v1/locations/{slug}/images	OS images at a location
list_ssh_keys	GET /api/v1/ssh-keys	List SSH keys
get_ssh_key	GET /api/v1/ssh-keys/{title}	Get one SSH key
create_ssh_key	POST /api/v1/ssh-keys	Create SSH key
delete_ssh_key	DELETE /api/v1/ssh-keys/{slug}	Delete SSH key
list_servers	GET /api/v1/instances	List instances
get_server	GET /api/v1/instances/{id}	Instance details
create_server	POST /api/v1/instances	Create instance
delete_server	DELETE /api/v1/instances/{id}	Delete instance
start_server	PUT /api/v1/instances/{id}/power-on	Power on
shutdown_server	PUT /api/v1/instances/{id}/power-off	Power off
reboot_server	PUT /api/v1/instances/{id}/reboot	Reboot
reset_server_password	PUT /api/v1/instances/{id}/reset-password	Reset root password
list_snapshots	GET /api/v1/snapshots	List snapshots
get_snapshot	GET /api/v1/snapshots/{slug}	Snapshot details
create_snapshot	POST /api/v1/instances/{id}/snapshots	Create snapshot
update_snapshot	PUT /api/v1/snapshots/{slug}	Rename snapshot
delete_snapshot	DELETE /api/v1/snapshots/{slug}	Delete snapshot

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

---

📡 Hosted vs self-hosted

This project ships as a hosted service at https://mcp.letscloud.io, 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 <api-key> (recommended, MCP-friendly)
• X-LetsCloud-Token: <api-key> (fallback)

The server forwards the key to LetsCloud's API as api-token: <key> (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