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

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_API_KEY`	CloudBase 环境级 API Key（推荐用于 CI/CD、MCP Server）	与 `CLOUDBASE_ENV_ID` 配合使用，优先级高于 `TENCENTCLOUD_*` 密钥；在控制台创建
`CLOUDBASE_ENV_ID`	云开发环境 ID（可选）	未设置时首次调用会引导登录并选择环境
`CLOUDBASE_API_ENDPOINT`	自定义 API Key 换取凭证的 Endpoint（高级可选）	不设则使用默认 `https://<envId>.<region>.tcb-api.tencentcloudapi.com`
`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/CD、MCP Server、AI Agent：推荐配 CLOUDBASE_API_KEY + CLOUDBASE_ENV_ID（环境级长期凭证，自动换取临时密钥）
传统密钥方式：配 TENCENTCLOUD_SECRETID、TENCENTCLOUD_SECRETKEY、TENCENTCLOUD_SESSIONTOKEN、CLOUDBASE_ENV_ID
企业自建登录中间层：通常只先配 TCB_AUTH_OAUTH_ENDPOINT

凭证优先级

当多种凭证同时存在时，MCP 按以下优先级选择：

CLOUDBASE_API_KEY + CLOUDBASE_ENV_ID — CloudBase 环境级 API Key
TENCENTCLOUD_SECRETID + TENCENTCLOUD_SECRETKEY — 腾讯云永久/临时密钥
本地存储的 Device Flow 登录凭证（~/.config/.cloudbase/auth.json）

API Key 模式示例

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": {
        "CLOUDBASE_API_KEY": "<your-api-key>",
        "CLOUDBASE_ENV_ID": "<your-env-id>"
      }
    }
  }
}

💡 API Key 可在云开发控制台的环境设置中创建和管理。

⚠️ API Key 具有环境级别的操作权限，请妥善保管，建议通过环境变量注入，不要硬编码在配置文件中。

最小示例：

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 和密钥即可，无需再配置服务端环境变量。

自建服务器部署（Cloud Mode）

含义与适用场景

含义：在自有服务器上运行 MCP 服务，通过环境变量启用 Cloud Mode，对外提供 Streamable HTTP 接口。
优点：完全自主可控的部署方式，可集成到已有基础设施中。
安全机制：启用 Cloud Mode 后，涉及本地文件系统读写和本地进程启动的工具将被逐一禁用（见下方完整列表），确保远程调用方无法通过这些工具操作服务器本地资源。

启用方式

通过以下任一方式启用 Cloud Mode（三选一）：

# 方式 1：环境变量
export CLOUDBASE_MCP_CLOUD_MODE=true

# 方式 2：备选环境变量
export MCP_CLOUD_MODE=true

# 方式 3：CLI 参数
npx @cloudbase/cloudbase-mcp@latest --cloud-mode

Cloud Mode 禁用的工具

启用 Cloud Mode 后，以下涉及本地文件系统或本地进程的工具将被自动跳过注册：

工具名	禁用原因
`downloadRemoteFile`	下载远程文件到本地文件系统
`downloadTemplate`	下载项目模板到本地
`manageCloudRun`	涉及本地服务启动（`action="run"`）
`manageStorage`	涉及本地文件上传/下载
`manageApps`	`deployApp` 读取本地 filePath 上传代码
`createFunction`	涉及本地代码上传
`updateFunctionCode`	涉及本地代码上传
`setupEnvironmentId`	涉及本地配置文件操作

安全架构说明

CloudBase MCP 针对不同部署场景提供分层安全保护：

┌─────────────────────────────────────────────────────┐
│                  本地模式 (Local)                      │
│  - 全部工具可用                                       │
│  - 调用方 = 开发者本人（已拥有机器完整控制权）           │
│  - 通信方式：stdio / localhost                        │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│           云端模式 (Cloud Mode)                       │
│  - 本地文件/进程工具自动禁用                           │
│  - 三层过滤：服务端注册过滤 + 客户端白名单（双重冗余）  │
│  - 远程调用方无法操作服务器本地资源                     │
│  - 通信方式：HTTPS (Streamable HTTP)                  │
└─────────────────────────────────────────────────────┘

重要提示：本地模式下 downloadRemoteFile、manageCloudRun(action="run") 等工具是产品的正常功能，等同于开发者在终端执行 curl 或 node app.js。这些工具仅在开发者本机运行，不存在权限提升风险。如果你需要在远程服务器上部署 MCP 服务并对外提供接口，务必启用 Cloud Mode。

部署模式选择建议

场景	推荐模式	说明
个人开发	本地模式（`npx`）	功能最全，无需额外配置
团队协作 / 远程服务	腾讯云托管模式	免运维，自动启用安全保护
自建服务器	Cloud Mode	务必设置 `CLOUDBASE_MCP_CLOUD_MODE=true`

支持的插件

当前插件名称、默认启用集合与兼容别名以 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 中的注册结果为准。

本地模式（推荐）​

含义与适用场景​

配置示例​

本地模式可选环境变量​

登录相关环境变量怎么选​

凭证优先级​

API Key 模式示例​

托管模式​

含义与适用场景​

配置示例​

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

托管模式环境变量说明​

自建服务器部署（Cloud Mode）​

含义与适用场景​

启用方式​

Cloud Mode 禁用的工具​

安全架构说明​

部署模式选择建议​

支持的插件​

支持的工具​

本地模式（推荐）

含义与适用场景

配置示例

本地模式可选环境变量

登录相关环境变量怎么选

凭证优先级

API Key 模式示例

托管模式

含义与适用场景

配置示例

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

托管模式环境变量说明

自建服务器部署（Cloud Mode）

含义与适用场景

启用方式

Cloud Mode 禁用的工具

安全架构说明

部署模式选择建议

支持的插件

支持的工具