连接方式：本地模式与托管模式

CloudBase MCP 支持两种连接方式：本地模式（MCP 服务在本机通过 npx 运行）和托管模式（MCP 服务运行在腾讯云上，IDE 通过 HTTP 连接）。按需选择其一即可。

---

本地模式（推荐）

含义与适用场景

• 含义：MCP 服务在你本机通过 npx 启动，与 IDE 同机运行。
• 优点：功能最全，包含上传/下载、模板安装等依赖本地文件系统的能力。
• 要求：本机已安装 Node.js，且能执行 npx。

配置示例

在 IDE 的 MCP 配置中添加（以 Cursor / WindSurf 等为例）：

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": {}
    }
  }
}

本地模式可选环境变量

本地模式下，可通过修改 env 环境变量来控制。以下均为可选，不配置时使用默认行为。

环境变量	说明	默认 / 说明
CLOUDBASE_ENV_ID	云开发环境 ID（可选）	未设置时首次调用会引导登录并选择环境
TENCENTCLOUD_SECRETID	腾讯云 SecretId（可选）	不设则通过登录引导获取；获取腾讯云 API 密钥
TENCENTCLOUD_SECRETKEY	腾讯云 SecretKey（可选）	同上
TENCENTCLOUD_SESSIONTOKEN	腾讯云临时密钥 Token（可选）	仅在使用临时密钥时需要，可通过 STS 服务 获取
TCB_REGION	腾讯云地域，如 ap-shanghai（可选）	不设则使用 SDK 默认
TCB_AUTH_OAUTH_ENDPOINT	自定义 device-code 登录 endpoint（可选，推荐作为主要覆盖项）	不设则使用默认登录 endpoint
TCB_AUTH_CLIENT_ID	自定义 device-code 登录 client_id（高级可选）	不设则使用默认 client_id
TCB_AUTH_OAUTH_CUSTOM	自定义 endpoint 返回格式开关（高级可选）	未配置 endpoint 时默认 false；配置 endpoint 后默认 true
INTEGRATION_IDE	当前 IDE 标识（如 Cursor、CodeBuddy）（可选）	用于日志与能力适配
CLOUDBASE_MCP_PLUGINS_ENABLED	启用的插件列表，逗号分隔（可选）	不设则使用默认插件集
CLOUDBASE_MCP_PLUGINS_DISABLED	禁用的插件列表，逗号分隔（可选）	与 URL 参数 disable_plugins 效果类似
WORKSPACE_FOLDER_PATHS / PROJECT_ROOT	项目根目录（下载模板、远程文件等）（可选）	不设则使用当前工作目录；CI 下可用 GITHUB_WORKSPACE 等
CLOUDBASE_MCP_TELEMETRY_DISABLED	设为 true 关闭遥测上报（可选）	默认上报
CLOUDBASE_LOG_DIR	日志目录（可选）	默认 ~/.cloudbase-mcp/logs

登录相关环境变量怎么选

大多数情况下，这 3 个变量都不用配：TCB_AUTH_OAUTH_ENDPOINT、TCB_AUTH_CLIENT_ID、TCB_AUTH_OAUTH_CUSTOM。

只有在你们要接入企业/平台自己的登录中间层时，才需要配置。可参考官方文档 无 CAM 子账号的隔离方案。

• 个人开发、普通团队：不用配，直接走默认 device-code 登录
• 服务器、CI、远程环境：优先配 TENCENTCLOUD_SECRETID、TENCENTCLOUD_SECRETKEY、TENCENTCLOUD_SESSIONTOKEN、CLOUDBASE_ENV_ID
• 企业自建登录中间层：通常只先配 TCB_AUTH_OAUTH_ENDPOINT

最小示例：

TCB_AUTH_OAUTH_ENDPOINT=https://auth.your-domain.com/oauth

补充说明：

• TCB_AUTH_CLIENT_ID：只有自定义登录服务要求固定 client_id 时才配
• TCB_AUTH_OAUTH_CUSTOM：配置自定义 TCB_AUTH_OAUTH_ENDPOINT 时应按 true 使用；现在默认也会自动按 true 处理

---

托管模式

含义与适用场景

• 含义：MCP 服务运行在腾讯云上，IDE 通过 HTTP 连接云端服务，无需在本地安装或运行 Node。
• 优点：不依赖本机环境，配置好密钥即可使用。
• 限制：部分依赖本地文件系统的能力不可用（如本地文件上传、模板下载到本机等）。

配置示例

将下面配置中的 <env_id>、<腾讯云 Secret ID>、<腾讯云 Secret Key> 替换为你的环境 ID 和腾讯云 API 密钥：

{
  "mcpServers": {
    "cloudbase": {
      "type": "http",
      "url": "https://tcb-api.cloud.tencent.com/mcp/v1?env_id=<env_id>",
      "headers": {
        "X-TencentCloud-SecretId": "<腾讯云 Secret ID>",
        "X-TencentCloud-SecretKey": "<腾讯云 Secret Key>"
      }
    }
  }
}

• 环境 ID：在 云开发控制台 查看。
• SecretId / SecretKey：在 腾讯云 API 密钥 创建或查看。

通过 URL 控制插件启用范围（仅托管模式）

在 url 中可通过 query 参数控制插件启用范围：

• enable_plugins：仅启用指定插件，多个插件使用逗号分隔，例如只启用 env 和 database
• disable_plugins：从默认插件集合中禁用指定插件，多个插件使用逗号分隔，例如禁用 rag 和 env

# 只启用指定插件
https://tcb-api.cloud.tencent.com/mcp/v1?env_id=YOUR_ENV_ID&enable_plugins=env,database

# 禁用指定插件
https://tcb-api.cloud.tencent.com/mcp/v1?env_id=YOUR_ENV_ID&disable_plugins=rag,env

当前可配置的插件名以 mcp/src/server.ts 为准，建议优先使用 canonical 名称：env, database, functions, hosting, storage, setup, rag, download, gateway, cloudrun, app-auth, permissions, logs, agents, invite-code, capi, apps。

托管模式环境变量说明

托管模式下，MCP 服务运行在云端，环境变量在服务端配置。若你自建托管服务，可参考 MCP 工具 - 云端 MCP 配置说明 中的可选环境变量表（如 TENCENTCLOUD_SECRETID、TENCENTCLOUD_SECRETKEY、CLOUDBASE_ENV_ID 等）。

使用腾讯云提供的托管 MCP 时，通过上述 URL 与 headers 传入 env_id 和密钥即可，无需再配置服务端环境变量。

---

支持的插件

当前插件名称、默认启用集合与兼容别名以 mcp/src/server.ts 为准。下表列出当前支持的 canonical 名称：

插件名	默认启用	说明
env	是	环境登录、环境查询、安全域名管理
database	是	NoSQL / SQL / 数据模型
functions	是	云函数查询、创建、更新、调用
hosting	是	静态托管与域名管理
storage	是	云存储文件管理
setup	是	模板、IDE 规则与配置下载
rag	是	知识库检索与网页搜索
download	是	下载远程文件到本地
gateway	是	云函数访问入口与路由管理
cloudrun	是	云托管服务初始化、部署与管理
app-auth	是	应用侧认证配置
permissions	是	权限、角色与安全规则
logs	是	日志服务状态与日志检索
agents	是	Agent 查询与管理
invite-code	是	AI 编程激励激活
capi	是	通用云 API 调用
apps	否	CloudApp 应用与版本管理

其中 permissions 兼容旧别名 security-rule、security-rules、access-control、secret-rule、secret-rules、users；app-auth 兼容旧别名 auth-config。新文档与新示例请优先使用 canonical 名称。

未配置时默认启用上表中“默认启用”为“是”的插件；可通过环境变量或 URL 参数控制插件范围。enable_plugins / disable_plugins 以及 CLOUDBASE_MCP_PLUGINS_ENABLED / CLOUDBASE_MCP_PLUGINS_DISABLED 的多值格式均为逗号分隔。

支持的工具

工具数量与名称会随版本演进而变化。完整参数与说明请见 MCP 工具；如需确认某个工具或插件是否真实存在，请优先以 mcp/src/server.ts 与 mcp/src/tools/*.ts 中的注册结果为准。