MCP Server

Cloady ships a remote MCP server that exposes its core operations as tools an AI agent can call. It’s an in-process server backed by the same API logic the dashboard and REST endpoints use — so an agent can list workspaces, browse the catalog, install apps, and manage their lifecycle without leaving the chat.

What it is

The Model Context Protocol (MCP) lets an AI client discover and call tools on a server. Cloady’s server runs inside the control plane and re-uses the exact functions behind the dashboard, so every tool call goes through the same authorization, validation, and reconciliation paths. There’s no separate codebase to drift — the tools wrap listWorkspacesForUser, createApp, updateApp, and friends directly.

Connect

One endpoint, bearer-authenticated:

Endpoint: https://cloady.com/api/mcp
Transport: streamable HTTP (stateless — no session is persisted between requests; each request carries its own auth and builds a fresh server)
Auth: Authorization: Bearer cldy_... — a Cloady personal API token

Create a token under Account → Tokens and copy the cldy_... secret (shown once). The token’s scope (read / deploy / full) and optional workspace pin govern what the agent can do — see Scopes below.

From a remote-MCP client

Clients that speak streamable HTTP connect with the URL plus a bearer header:


{
  "mcpServers": {
    "cloady": {
      "url": "https://cloady.com/api/mcp",
      "headers": {
        "Authorization": "Bearer cldy_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

From a stdio-only client

For clients that can only spawn a local stdio server, use the wrapper. It runs locally and forwards your CLOADY_TOKEN to the remote endpoint:


{
  "mcpServers": {
    "cloady": {
      "command": "npx",
      "args": ["-y", "@cloady/mcp"],
      "env": { "CLOADY_TOKEN": "cldy_xxxxxxxxxxxxxxxx" }
    }
  }
}

Tools

Every tool maps to a single Cloady operation. Each call checks the token’s scope first, then — for workspace-scoped tools — the caller’s role in that workspace. The env parameter is one of prod (default), staging, or dev. region is optional on app-lifecycle tools and only required when the same app slug exists in more than one region.

Tool	Scope	Role	Params	Does
`list_workspaces`	`read`	—	(none)	Lists every workspace you belong to, hydrated with apps, regions, and pools.
`get_workspace`	`read`	viewer	`slug`	Gets one workspace by slug — apps, regions, pools, and billing.
`list_templates`	`read`	—	(none)	Lists the app catalog (installable templates) with versions and resource footprint.
`list_regions`	`read`	—	(none)	Lists available regions and their status.
`list_deploys`	`read`	viewer	`slug`, `svcId`, `env`, `region?`	Lists recent deploys for an app (instance) in a workspace region.
`install_app`	`deploy`	developer	`slug`, `applicationId`, `region`, `name?`, `env`, `version?`, `vars?`	Installs a catalog app into a workspace region — creates an instance and deploys it.
`start_app`	`deploy`	developer	`slug`, `svcId`, `env`, `region?`	Starts a stopped app.
`stop_app`	`deploy`	developer	`slug`, `svcId`, `env`, `region?`	Stops a running app (data is preserved).
`restart_app`	`deploy`	developer	`slug`, `svcId`, `env`, `region?`	Redeploys an app — refreshes code from its repo and restarts it.
`delete_app`	`full`	admin	`slug`, `svcId`, `env`, `region?`	Permanently deletes an app and purges all of its data.

Notes on the parameters:

slug is the workspace slug; svcId is the app (instance) slug — the URL slug derived from the app’s name at install time.
applicationId is the catalog id, e.g. "wordpress" or "postgres".
version is a catalog version tag; omit it to install the current default.
vars is an array of { key, value, isSecret? } — environment variables or prompt answers. Entries with isSecret: true are encrypted at rest.

Scopes

Tokens carry one scope; the server enforces it before any workspace check. Scopes are ranked, so a higher scope satisfies a lower requirement:

read — read-only. Lists and gets only.
deploy — read plus install / start / stop / restart.
full — everything, including destructive delete_app.

On top of scope, workspace-scoped tools require a workspace role (viewer < developer < admin). Both must pass — a full-scope token still can’t delete in a workspace where you’re only a viewer.

A token may also be pinned to one workspace. A pinned token used against a different workspace’s slug is rejected with a forbidden error.

Errors

Failures come back as tool errors, not transport errors — the result is flagged isError with a JSON body:


{ "error": { "code": "forbidden", "message": "Token scope 'read' cannot perform a 'deploy' action" } }

Common codes: unauthorized (missing or invalid token — returned at the HTTP layer, 401), forbidden (scope, role, or workspace-pin mismatch), and operation-specific codes such as activation_required (the target region isn’t activated for the workspace).

Example interaction


You: Install WordPress in the neptolab workspace, region hil1.

Agent → list_templates
  ← [ … { "id": "wordpress", "currentVersion": "6.5", … } … ]

Agent → install_app { slug: "neptolab", applicationId: "wordpress",
                      region: "hil1", name: "DailyFrog", env: "prod" }
  ← { "svcId": "dailyfrog", "status": "deploying",
      "env": "prod", "region": "hil1", "version": "6.5" }

Agent: Installed DailyFrog (WordPress 6.5) in hil1. It's deploying now —
       check back with list_deploys for build status.

Not yet exposed

The MCP surface is intentionally focused. Not yet available as tools:

Richer install — interactive prompts, profile selection, and managed secret generation. install_app accepts plain vars only; apps needing install-time secret minting or profile checkboxes are better done in the dashboard for now.
Plan and region changes — activating / deactivating regions and changing tiers aren’t exposed; manage billing in the dashboard.