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

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_APIKEY`（与 `@cloudbase/js-sdk` / `@cloudbase/node-sdk` 对齐，优先使用带下划线的 `CLOUDBASE_API_KEY`）；在控制台创建
`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_SITE`	站点：`domestic`（国内站）或 `intl`（国际站）（可选）	不设则按 `region` 反查映射表；`ap-singapore` 歧义时默认 `intl`。国内站新加坡用户必须显式设 `domestic`，避免被误判为国际站
`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`
`TCB_TCR_USERNAME`	个人版 TCR 推送用户名，即腾讯云账号 UIN（可选）	仅 HTTP 云函数个人版镜像构建（`imageType=personal` 的 `local` / `cloud`）需要；与 cloudbaserc 的 `{{env.TCB_TCR_USERNAME}}` 同名，CLI 与 MCP 共用一套变量
`TCB_TCR_PASSWORD`	个人版 TCR 固定密码（可选）	同上；配置后无需在工具参数中传递凭证，避免密码进入 AI 上下文。获取个人版镜像仓库密码
`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（若未设置 CLOUDBASE_API_KEY，兼容读取 CLOUDBASE_APIKEY）
TENCENTCLOUD_SECRETID + TENCENTCLOUD_SECRETKEY — 腾讯云永久/临时密钥
本地存储的 Device Flow 登录凭证（~/.config/.cloudbase/auth.json）

登录模式与查询范围

两种登录的可见环境范围不同，这是凭据权限边界，不是环境丢失：

登录方式	`auth(status)` 字段	能看到什么
账号级（device / web / 腾讯云 SecretId）	`credential_scope=account`	当前地域下账号有权的环境；其他地域需显式查询
环境级 API Key（`CLOUDBASE_API_KEY` + `CLOUDBASE_ENV_ID`）	`credential_scope=single_env`	仅绑定的那一个 envId，无法列出其他环境或其他地域

跨地域查询（仅账号级凭据）：

MCP：queryEnv(action="list", region="ap-singapore")（envQuery 同义）
MCP 管控面：callCloudApi(service="tcb", action="DescribeEnvs", region="ap-singapore")。不要把 Region 放进 params（会报 The parameter Region is not recognized）
CLI：tcb env list -r ap-singapore --json

绑定非当前地域环境：账号级登录下 auth(action="set_env", envId="<EnvId>") 不要求 envId 出现在当前地域候选列表中；环境级 API Key 不能改绑到其他 envId。

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 处理

站点与地域（site / region）

CloudBase 有国内站（domestic，cloud.tencent.com）与国际站（intl，tencentcloud.com）两套独立的账号体系与登录域名。MCP 用 site 决定登录域名/凭证槽位，用 region 决定 API 路由目标，两者解耦。

解析优先级

显式 cloudBaseOptions.site/region
  > 环境变量 TCB_SITE / TCB_REGION
  > 项目级配置 .cloudbase/project.json
  > cloudbaserc.json（按字段回退，site 为 MCP 扩展字段）
  > 全局默认：domestic + ap-shanghai

地域与站点的默认关系

region	未配 site 时的解析结果
`ap-shanghai` / `ap-guangzhou`	`domestic`（国内站）
`ap-singapore`	歧义：国内站与国际站都有该地域，未配 site 时默认 `intl`（兼容既有行为）

国际站用户

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": {
        "TCB_SITE": "intl",
        "TCB_REGION": "ap-singapore"
      }
    }
  }
}

国内站新加坡用户（重要迁移指引）

国内站现已支持新加坡地域。只配置 TCB_REGION=ap-singapore 会被默认按国际站处理（登录跳国际站、NoSQL 工具被跳过）。国内站新加坡用户必须显式配置站点：

{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": ["@cloudbase/cloudbase-mcp@latest"],
      "env": {
        "TCB_SITE": "domestic",
        "TCB_REGION": "ap-singapore"
      }
    }
  }
}

也可以使用项目级配置 .cloudbase/project.json（独立文件，不并入 cloudbaserc.json），让同一目录下的所有会话自动带入正确的站点：

{
  "site": "domestic",
  "region": "ap-singapore",
  "envId": "your-env-id"
}

其中 envId 会作为该项目的默认环境，解析优先级：

显式 cloudBaseOptions.envId
  > 环境变量 CLOUDBASE_ENV_ID
  > 当前进程内已绑定的环境（auth(action="set_env") 结果）
  > 项目级配置 .cloudbase/project.json 的 envId
  > cloudbaserc.json 的 envId（按字段回退）
  > 账号登录态里的环境
  > 返回 ENV_REQUIRED，引导调用 auth(action="set_env")

cloudbaserc.json 回退源说明（面向已有 CLI 项目，无需重复维护绑定配置）：

按字段回退：project.json 与 cloudbaserc.json 各字段独立互补（如 project.json 只写 site、cloudbaserc.json 只写 envId 时两边同时生效），同一字段以 project.json 优先
envId / region 支持字面量与 {{env.KEY}} 模板：模板从项目根 .env / .env.local 解析（与 CLI 同源）；{{private.X}} 及解析失败的模板会被跳过，继续走下一级，不会报错
MCP 不写 cloudbaserc.json：它是 CLI 维护的人工部署配置（CLI 部署后还会自动回写）；机器管理的绑定持久化走 .cloudbase/project.json

因为该文件在仓库内且随仓库提交，所以新起的 MCP 进程、以及同一仓库的每个 Git worktree 都会自动命中同一环境，无需为每个 worktree 重新 set_env；不同仓库各读自己的文件，绑定不会互相串。

多站点凭证并存

登录凭证按站点分槽存储（~/.config/.cloudbase/auth.json 的 credential 升级为 credential.domestic / credential.intl），国内站与国际站可分别登录并存，切换环境无需重新登录。旧版单槽数据读取时自动视为 domestic，首次写回时自动升级为分槽格式。

托管模式

含义与适用场景

含义：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, pg_database, pg_storage, mysql_database, functions, hosting, storage, setup, rag, download, gateway, cloudrun, app-auth, permissions, logs, agents, apps, capi, database-nosql, database-sql, data-model。

通过 URL 指定站点（site）（仅托管模式）

托管模式与本地模式一样区分国内站（domestic）与国际站（intl）。可通过 site query 参数显式指定站点，用于国内站新加坡地域等 ap-singapore 场景的正确路由：

site=domestic：国内站（cloud.tencent.com）
site=intl：国际站（tencentcloud.com）
不传 site 时由服务端按环境归属解析；ap-singapore 地域国内站与国际站都存在，无法归属时默认按 intl 处理

# 国内站新加坡地域：必须显式传 site=domestic，避免被按国际站处理
https://tcb-api.cloud.tencent.com/mcp/v1?env_id=YOUR_ENV_ID&site=domestic

国内站新加坡用户（TCB_REGION 对应 ap-singapore）请务必在托管 URL 中带上 site=domestic，否则登录与 NoSQL 工具等能力可能被按国际站处理。

托管模式环境变量说明

托管模式下，MCP 服务运行在云端，环境变量在服务端配置。若你自建托管服务，可参考 MCP 工具 - 云端 MCP 配置说明中的可选环境变量表（如 TENCENTCLOUD_SECRETID、TENCENTCLOUD_SECRETKEY、CLOUDBASE_ENV_ID 等）；站点同样支持用 TCB_SITE 环境变量指定（domestic / intl），与本地模式行为一致。

使用腾讯云提供的托管 MCP 时，通过上述 URL 与 headers 传入 env_id 和密钥即可，无需再配置服务端环境变量；如需指定站点，直接在 URL 上加 site=domestic 或 site=intl 参数（见上文）。

自建服务器部署（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 后，以下涉及本地文件系统或本地进程的工具将被自动跳过注册：

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

安全架构说明

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

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

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

重要提示：本地模式下 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 数据库 + 数据模型（组合注册）
`pg_database`	是	PostgreSQL 数据库
`pg_storage`	是	PostgreSQL 存储
`mysql_database`	是	MySQL 数据库
`functions`	是	云函数查询、创建、更新、调用
`hosting`	是	静态托管与域名管理
`storage`	是	云存储文件管理
`setup`	是	模板、IDE 规则与配置下载
`rag`	是	知识库、技能、OpenAPI 与官方文档检索
`download`	是	下载远程文件到本地
`gateway`	是	云函数访问入口与路由管理
`cloudrun`	是	云托管服务初始化、部署与管理
`app-auth`	是	应用侧认证配置
`permissions`	是	权限、角色与安全规则
`logs`	是	日志服务状态与日志检索
`agents`	是	Agent 查询与管理
`apps`	是	CloudApp 应用与版本管理
`capi`	是	通用云 API 调用
`database-nosql`	否	仅 NoSQL 数据库（`database` 的子集）
`database-sql`	否	仅 SQL 数据库（`mysql_database` 的子集）
`data-model`	否	仅数据模型（`database` 的子集）

兼容别名（建议优先使用 canonical 名称）：

别名	→ canonical
`access-control`	`permissions`
`auth-config`	`app-auth`
`security-rule` / `security-rules`	`permissions`
`secret-rule` / `secret-rules`	`permissions`
`users`	`permissions`
`mysql` / `mysql-database`	`mysql_database`
`sql-database`	`mysql_database`

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

支持的工具

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

本地模式（推荐）​

含义与适用场景​

配置示例​

本地模式可选环境变量​

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

凭证优先级​

登录模式与查询范围​

API Key 模式示例​

站点与地域（site / region）​

解析优先级​

地域与站点的默认关系​

国际站用户​

国内站新加坡用户（重要迁移指引）​

多站点凭证并存​

托管模式​

含义与适用场景​

配置示例​

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

通过 URL 指定站点（site）（仅托管模式）​

托管模式环境变量说明​

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

含义与适用场景​

启用方式​

Cloud Mode 禁用的工具​

安全架构说明​

部署模式选择建议​

支持的插件​

支持的工具​

本地模式（推荐）

含义与适用场景

配置示例

本地模式可选环境变量

登录相关环境变量怎么选

凭证优先级

登录模式与查询范围

API Key 模式示例

站点与地域（site / region）

解析优先级

地域与站点的默认关系

国际站用户

国内站新加坡用户（重要迁移指引）

多站点凭证并存

托管模式

含义与适用场景

配置示例

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

通过 URL 指定站点（site）（仅托管模式）

托管模式环境变量说明

自建服务器部署（Cloud Mode）

含义与适用场景

启用方式

Cloud Mode 禁用的工具

安全架构说明

部署模式选择建议

支持的插件

支持的工具