MCP 服务器 — Cloady Docs

Cloady 提供一个 MCP 服务器，让 AI 智能体可以操作你的账号，包括工作区、应用、部署、环境变量、域名、存储卷、成员、集成、计费和支持工单。

概述

模型上下文协议（Model Context Protocol，MCP）让 AI 客户端可以发现并调用服务器上的工具。REST 参考中的各项操作都会成为 Cloady 工具；每次调用都会带着你的 API 令牌发往对应的端点，并经过与你自己的请求相同的权限检查。

你可以把它作为 @cloady/mcp 在本地通过 stdio 运行，也可以连接托管端点 https://cloady.com/api/mcp：它通过 Streamable HTTP 提供同样的工具，无需安装任何东西。托管端点不提供会返回凭据的工具：revealVar、getDbCredentials、getVolumeKeys、createSshSession、getSshSession、createToken、startCardSetup、邀请类工具（邀请链接任何人打开即可加入）以及从其他云平台导入服务的工具；generateImage 也不在其中。大部分监控（Monitor）工具同样不在托管端点上：在那里，智能体通过 queryAppMetrics、queryAppMetricsRange、queryAppLogs 和 queryWorkspaceMetrics 读取指标和日志。所有未提供的工具，在本地包和 API 中依然可用。

OpenAI 应用目录中的公开连接使用 https://cloady.com/api/mcp?profile=openai。它提供应用诊断、数据库结构查看、仓库操作和域名管理，但不提供以下功能：获取凭据、验证码、设置付款方式、变更订阅，以及创建应用或调整应用规格。这些操作仍可通过 Cloady 控制台、REST API 和本地 @cloady/mcp 包使用。每个 Git 操作都是一个单独的工具。

支持 OAuth 的客户端无需复制 API 令牌即可连接。在授权同意页面选择权限范围；不再需要时，在 Account → API tokens 中吊销生成的令牌。账号级连接可以访问你的账号所属的所有工作区，但受其权限范围和你的角色限制。关于数据共享、保留和删除，请参阅隐私政策。

连接

在 Account → API tokens 中创建令牌，并复制 cldy_… 密钥（它只显示一次）。需要 Node 20 或更高版本。

Claude Code

Terminal

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

托管版，无需安装

Terminal

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

任何支持 Streamable HTTP 的客户端，都可以使用同样的 URL 和 Authorization: Bearer 请求头。每个请求都以令牌所有者的身份执行，与本地包完全相同。

Claude Desktop / Cursor / 任意 MCP 客户端

JSON

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

如果要连接 https://cloady.com 以外的地址，可以用 API_BASE_URL 覆盖目标主机。

工具

每个 API 操作对应一个工具，以操作 ID 命名，例如 listVars、createVar、deployApp、execCommand、listDeploys。路径参数和查询参数是顶层参数；原本属于 JSON 请求体的内容，都放在嵌套的 requestBody 对象中。因此，createVar 接收 workspaceSlug、appSlug、env 和 region，外加 requestBody: { key, value, isSecret }。

每个应用运行在一个区域和一个环境中，应用名称在同一工作区和环境内唯一。env 取值为 production（默认）、preview 或 development；只有当同名应用存在于多个区域时，才需要传入 region。

完整的工具列表及其全部参数见 API 参考：那里列出的每个操作都是一个工具。下面几个值得了解：

工具	作用
`listWorkspaces`、`getWorkspace`	工作区及其应用（位于 `services` 下），包括状态、区域、端点和资源上限。
`deployApp`	从模板目录、Git 仓库或上传的文件创建应用：`source` 为 `{type:"catalog", name}`、`{type:"git", repoUrl}` 或 `{type:"upload", uploadId}`，`region` 指定应用在哪里运行，`values` 设置安装时的配置项。
`updateApp`	重命名、切换分支、扩缩容，以及用 `status: "stopped"` / `"running"` 停止或启动应用。
`deleteApp`	删除应用及其数据。
`listVars`、`createVar`、`updateVar`、`deleteVar`、`importVars`、`revealVar`	环境变量和凭据。
`listDeploys`、`createAppDeploy`、`redeployApp`、`rollbackDeploy`	部署历史、发起新部署，以及回滚到之前的部署。
`execCommand`	在运行中的容器里执行 Shell 命令。
`readServiceLogs`	某个服务最近 200 行日志，其中 `serviceName` 是应用内的某个服务。
`listAppDomains`、`createDomain`、`listCertStatuses`	自定义域名，以及它们的 HTTPS 是否已就绪。

deleteApp 具有破坏性。它会永久删除应用及其数据，且无法撤销。

通过 updateApp 重命名，才是修改应用名称的安全方式：应用会保留数据，地址也会随新名称变化。例如，acme 工作区中名为 My Blog 的应用，地址是 my-blog-k7q2v9ze-acme.cloady.io；重命名后，它会改用新名称对应的地址。切勿为了重命名而删除再重建应用：删除会销毁它的数据。

五个 stream… 工具（streamAppStatus、streamAppMetrics、streamActiveDeploy、streamDeployLogs、streamTicketMessages）每次调用只返回当前的一帧，而不是实时推送；要跟踪进展，就再次调用它们。

权限范围

每个令牌带有一个权限范围，它限定了令牌在工作区中可以使用的最高角色：read 以 viewer 身份操作，deploy 以 developer 身份操作，full 最高可达 owner。每个操作所需的角色仍与在控制台中相同，所以在你只是 viewer 的工作区里，full 权限范围的令牌也无法删除任何东西。

令牌还可以绑定到某一个工作区；用于其他工作区时，请求会被拒绝，并返回 forbidden 错误。

错误

失败时，返回的是对应端点本身的错误响应体：

JSON

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

错误码	含义
`unauthorized`	缺少令牌，或令牌无效。
`phone_required`	令牌所有者的手机号尚未验证。在 cloady.com 上验证一次后，所有工具即可正常使用。
`forbidden`	权限范围或工作区角色不足，或者令牌绑定的是另一个工作区。
`not_found`	工作区、应用或记录不存在。
`region_required`	同名应用存在于多个区域，请传入 `region`。
`payment_required`	该应用会让工作区超出免费额度，而目前没有绑定银行卡，或银行卡扣款被拒。工作区所有者需要在 cloady.com 的 Account → Billing 中添加银行卡。

交互示例

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

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

Agent → deployApp { workspaceSlug: "acme",
                    requestBody: { name: "My Blog", region: "usw1",
                                   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 usw1; it's deploying now. Here are its settings — …

本页内容