Cloud Manager 在 10 月 28 日的 v1.3.5 中加入了远程 MCP。以前查实例、看账单、找 DNS 记录需要打开管理页面,现在支持 MCP 的客户端也可以调用这些能力。

接一个接口本身不复杂。这个项目后面连着真实的云账户,查询实例和删除实例又共用一套服务,所以我把这篇的重点放在权限怎么落到代码上。

下面按截至 2026 年 11 月 17 日的仓库实现来写,不涉及具体 AI 客户端的安装教程。

入口用无会话的 Streamable HTTP

接口挂在现有 Express 服务的 /mcp,复用后端端口。路由里创建传输对象的代码是:

1
2
3
4
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined,
enableJsonResponse: true
})

每次 POST 请求创建对应的 MCP server 和 transport,请求处理完后关闭。这里不保存跨请求的 MCP 会话,也没有旧式 /sse 入口。

接入时需要支持 Streamable HTTP 和自定义 Bearer 请求头的客户端。仅支持 OAuth 的客户端不能直接套用这份配置,因为当前接口没有实现 OAuth 授权流程。

客户端配置大致如下,具体字段仍以客户端自身要求为准:

1
2
3
4
5
6
7
8
9
10
{
"mcpServers": {
"cloud-manager": {
"url": "https://cloud.example.com/mcp",
"headers": {
"Authorization": "Bearer <YOUR_MCP_TOKEN>"
}
}
}
}

反向代理需要转发 /mcp 和 Authorization 请求头。若浏览器客户端会携带 Origin,还要在后台登记它的精确来源;来源许可和令牌认证各管一件事,前者不能替代后者。

只读权限要在服务端生效

新安装默认关闭 MCP。开启后可以创建只读令牌,或者明确允许操作资源的令牌。

只读令牌可以查询账户、实例、账单、任务和 DNS。创建实例、重启、删除资源、修改 DNS 等工具,需要操作令牌。

注册工具时先做一层判断:

1
if (write && token.mode !== 'write') return

因此只读客户端的 tools/list 根本不会列出修改工具。工具还带有 readOnlyHint、destructiveHint 等注解,但这些只是供客户端理解用途,实际授权不能依赖它们。

真正执行 handler 前,代码还会再查一次令牌:

1
2
3
4
5
const current = findMcpToken(req.headers.authorization)
if (!current || current.id !== token.id ||
(write && current.mode !== 'write')) {
throw new Error('MCP 令牌已失效或权限不足')
}

入口校验和执行前校验之间,管理员可能撤销令牌、关闭 MCP,或者令牌已经过期。第二次检查可以覆盖这个时间窗口,但不会中断已经提交到云平台的操作。

当前授权粒度也有明确限制:一个令牌覆盖所有已启用的计算和 DNS 账户,还没有逐账户授权。若要只开放某个账户,不能以为选择“只读”就顺便完成了账户隔离。

令牌不直接存在配置文件里

生成令牌时,服务端使用 32 字节随机值,拼上固定前缀。明文只在创建时返回一次,持久化的是 SHA-256 摘要以及名称、模式、有效期等元数据。校验时计算请求令牌的摘要,再用 timingSafeEqual 比较。

这里使用普通摘要的前提是令牌来自足够长的随机值,不能把这个做法直接照搬到用户设置的短密码上。

后台默认有效期为 90 天,最多保留 20 个有效令牌。遗失明文之后只能重新生成,不能从管理页面把旧令牌查回来。

返回内容也要收口

云 SDK 的响应往往比页面需要的字段多,错误信息还可能带回请求参数。因此 MCP 没有简单地把所有内部数据原样返回。

账户列表只选取 ID、名称和平台类型;任务结果通过 visibleTask() 挑选状态、时间、结果、错误等字段。统一清理函数还会递归过滤密码、密钥、凭证等字段名,去掉 raw,并在字符串中替换收集到的敏感值。

错误信息也走这一步,而不是只清理成功响应。

这种过滤仍然依赖字段命名和已知敏感值,不能视为永远不会泄露的保证。扩展 provider 时,仍应明确挑选返回字段,尤其不要把新增 SDK 的原始响应直接塞进工具结果。

操作日志记录令牌名称、ID、工具名、目标和执行结果,不记录完整调用参数。这样排查问题时可以知道哪个客户端做了什么,又不必为了留日志保存一份密码。

创建实例返回的是任务,不是创建结果

云实例创建通常比一次 HTTP 请求慢。create_instance 继续走已有的参数校验和任务队列,返回 taskId,再通过 get_task 跟踪进度。

这里有一个容易混淆的失败场景:客户端超时,并不能说明任务没有创建。若收到任务 ID,应该先查任务;若响应完全丢失,需要结合任务列表确认,不能直接重复创建。

当前接口没有让创建请求自动具备完整的幂等语义。取消任务和撤销令牌也不会回滚已经送达云平台的请求。这些限制写在工具说明里,是为了让调用端知道什么时候该查状态,而不是继续重试。

并发额度不能随客户端断开就释放

入口按令牌限制每分钟 120 个 POST、最多 8 个同时处理的请求,请求体限制为 128 KiB。限流状态目前保存在进程内,多副本部署时并不是全局额度。

有个细节是:客户端断开连接,不代表后端云请求已经结束。当前实现等请求处理和清理结束才释放执行名额,避免客户端反复断开、重连,把仍在执行的操作排除在并发计数之外。

如果只是接入查询,先建一个只读令牌就够用了。可以依次检查账户列表、实例列表和账单;需要修改资源时,再单独创建操作令牌。这样从日志里也容易区分用途。

本文对应引入 MCP 的 提交 3c30ce8,源码核对版本为 53fe431。相关文件:HTTP 路由、工具注册与结果清理、令牌管理、接入文档。