Cloud Manager 在 10 月 28 日的 v1.3.5 中加入了远程 MCP。以前查实例、看账单、找 DNS 记录需要打开管理页面,现在支持 MCP 的客户端也可以调用这些能力。
接一个接口本身不复杂。这个项目后面连着真实的云账户,查询实例和删除实例又共用一套服务,所以我把这篇的重点放在权限怎么落到代码上。
下面按截至 2026 年 11 月 17 日的仓库实现来写,不涉及具体 AI 客户端的安装教程。
入口用无会话的 Streamable HTTP
接口挂在现有 Express 服务的 /mcp,复用后端端口。路由里创建传输对象的代码是:
1 | const transport = new StreamableHTTPServerTransport({ |
每次 POST 请求创建对应的 MCP server 和 transport,请求处理完后关闭。这里不保存跨请求的 MCP 会话,也没有旧式 /sse 入口。
接入时需要支持 Streamable HTTP 和自定义 Bearer 请求头的客户端。仅支持 OAuth 的客户端不能直接套用这份配置,因为当前接口没有实现 OAuth 授权流程。
客户端配置大致如下,具体字段仍以客户端自身要求为准:
1 | { |
反向代理需要转发 /mcp 和 Authorization 请求头。若浏览器客户端会携带 Origin,还要在后台登记它的精确来源;来源许可和令牌认证各管一件事,前者不能替代后者。
只读权限要在服务端生效
新安装默认关闭 MCP。开启后可以创建只读令牌,或者明确允许操作资源的令牌。
只读令牌可以查询账户、实例、账单、任务和 DNS。创建实例、重启、删除资源、修改 DNS 等工具,需要操作令牌。
注册工具时先做一层判断:
1 | if (write && token.mode !== 'write') return |
因此只读客户端的 tools/list 根本不会列出修改工具。工具还带有 readOnlyHint、destructiveHint 等注解,但这些只是供客户端理解用途,实际授权不能依赖它们。
真正执行 handler 前,代码还会再查一次令牌:
1 | const current = findMcpToken(req.headers.authorization) |
入口校验和执行前校验之间,管理员可能撤销令牌、关闭 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 路由、工具注册与结果清理、令牌管理、接入文档。