MCP Server

Cloady ships an MCP server that lets an AI agent work on your account — workspaces, apps, deploys, environment variables, domains, volumes, members, integrations, billing and support tickets.

What it is

The Model Context Protocol (MCP) lets an AI client discover and call tools on a server. Every operation in the REST reference is one Cloady tool — 87 of them — and each call goes to the matching endpoint with your API token, under the same permission checks your own requests get.

Run it locally over stdio as @cloady/mcp, or connect to the hosted endpoint, https://cloady.com/api/mcp, which serves the same tools over Streamable HTTP with nothing to install.

Connect

Create a token under Account → API tokens and copy the cldy_… secret — it is shown once. Node 20 or newer is required.

Claude Code

claude mcp add cloady -e BEARER_TOKEN_CLOADY=cldy_… -- npx -y @cloady/mcp

Hosted, no install

claude mcp add --transport http cloady https://cloady.com/api/mcp --header "Authorization: Bearer cldy_…"

Any client that speaks Streamable HTTP takes the same URL and Authorization: Bearer header. Each request acts as the token's owner, exactly like the package.

Claude Desktop / Cursor / any MCP client

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

API_BASE_URL overrides the target host if you point at something other than https://cloady.com.

Tools

One tool per API operation, named after its operation id — listVars, createVar, deployApp, execCommand, listDeploys. Path and query parameters are top-level arguments; anything that would be a JSON body goes in a nested requestBody object. So createVar takes workspaceSlug, appSlug, env and region, plus requestBody: { key, value, isSecret }.

Each app runs in one region and one environment, and an app's name is unique within a workspace and environment. env is one of production (the default), preview or development; region is only needed when an app of that name exists in more than one region.

The complete list, with every argument, is the API reference — whatever is there is a tool. A few worth knowing:

Tool	Does
`listWorkspaces`, `getWorkspace`	Workspaces with their apps under `services` — status, region, endpoints, limits.
`deployApp`	Create an app from the catalog, a git repo or an upload: `source` is `{type:"catalog", name}`, `{type:"git", repoUrl}` or `{type:"upload", uploadId}`, `region` says where it runs, and `values` sets install-time settings.
`updateApp`	Rename, switch branch, scale, and `status: "stopped"` / `"running"` to stop or start.
`deleteApp`	Destructive. Deletes the app and its data permanently. There is no undo.
`listVars`, `createVar`, `updateVar`, `deleteVar`, `importVars`, `revealVar`	Environment variables and credentials.
`listDeploys`, `createAppDeploy`, `redeployApp`, `rollbackDeploy`	Deploy history, new deploys, and rolling back to an earlier one.
`execCommand`	Run a shell command in a running container.
`readServiceLogs`	The last 200 lines from one service — `serviceName` is a service inside the app.
`listAppDomains`, `createDomain`, `listCertStatuses`	Custom domains, and whether HTTPS is ready on them.

Renaming through updateApp is the safe way to change an app's name: the app keeps its data, and its address follows the new name — an app called My Blog in the acme workspace answers at my-blog-k7q2v9ze-acme.cloady.io, and renaming it moves it to the new name's address. Never delete and recreate an app to rename it; deleting destroys its data.

The five stream… tools (streamAppStatus, streamAppMetrics, streamActiveDeploy, streamDeployLogs, streamTicketMessages) return one current frame per call rather than a live feed, so call them again to watch something progress.

Scopes

A token carries one scope, and it caps the workspace role the token can act with: read acts as a viewer, deploy as a developer, full up to owner. Each operation still needs the same role it needs in the dashboard, so a full-scope token can't delete anything in a workspace where you are only a viewer.

A token may also be pinned to one workspace; used against another it is rejected with a forbidden error.

Errors

Failures come back as the endpoint's own error body:

{ "error": { "code": "forbidden", "message": "API token scope 'read' cannot perform 'developer'-level actions" } }

Code	What it means
`unauthorized`	Missing or invalid token.
`phone_required`	The token owner's phone is not verified. Verify it once at cloady.com and every tool works.
`forbidden`	Scope, workspace role, or the token is pinned to a different workspace.
`not_found`	No such workspace, app or record.
`region_required`	An app of that name exists in more than one region — pass `region`.
`payment_required`	The app would take the workspace past its free allowance and there is no card on file, or it was declined. A person has to add a card at cloady.com (workspace Settings → Billing); `previewWorkspaceSubscription` prices a change before you make it.

Example interaction

You: Install WordPress in the acme workspace, region hil1, then show me its settings.

Agent → listTemplates
  ← the catalog, including { "slug": "wordpress", … }

Agent → deployApp { workspaceSlug: "acme",
                    requestBody: { name: "My Blog", region: "hil1",
                                   source: { type: "catalog", name: "wordpress" } } }
  ← the created app: slug "my-blog", status "deploying"

Agent → listVars { workspaceSlug: "acme", appSlug: "my-blog" }
  ← its variables and generated credentials

Agent: Installed My Blog in hil1; it's deploying now. Here are its settings — …

MCP Server

On this page