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

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

---

## 本地模式（推荐）

### 含义与适用场景

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

### 配置示例

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

```json
{
  "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_*` 密钥；[在控制台创建](https://tcb.cloud.tencent.com/dev) |
| `CLOUDBASE_ENV_ID` | 云开发环境 ID（可选） | 未设置时首次调用会引导登录并选择环境 |
| `CLOUDBASE_API_ENDPOINT` | 自定义 API Key 换取凭证的 Endpoint（高级可选） | 不设则使用默认 `https://<envId>.<region>.tcb-api.tencentcloudapi.com` |
| `TENCENTCLOUD_SECRETID` | 腾讯云 SecretId（可选） | 不设则通过登录引导获取；[获取腾讯云 API 密钥](https://console.cloud.tencent.com/cam/capi) |
| `TENCENTCLOUD_SECRETKEY` | 腾讯云 SecretKey（可选） | 同上 |
| `TENCENTCLOUD_SESSIONTOKEN` | 腾讯云临时密钥 Token（可选） | 仅在使用临时密钥时需要，可通过 [STS 服务](https://console.cloud.tencent.com/cam/capi) 获取 |
| `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 子账号的隔离方案](https://docs.cloudbase.net/quick-start/enterprise-ai-platform-no-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 按以下优先级选择：

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

#### API Key 模式示例

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

> 💡 API Key 可在 [云开发控制台](https://tcb.cloud.tencent.com/dev) 的环境设置中创建和管理。
>
> ⚠️ API Key 具有环境级别的操作权限，请妥善保管，建议通过环境变量注入，不要硬编码在配置文件中。

最小示例：

```bash
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 密钥：

```json
{
  "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**：在 [云开发控制台](https://tcb.cloud.tencent.com/dev) 查看。
- **SecretId / SecretKey**：在 [腾讯云 API 密钥](https://console.cloud.tencent.com/cam/capi) 创建或查看。

### 通过 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 配置说明](/ai/cloudbase-ai-toolkit/mcp-tools#云端-mcp-配置说明) 中的可选环境变量表（如 `TENCENTCLOUD_SECRETID`、`TENCENTCLOUD_SECRETKEY`、`CLOUDBASE_ENV_ID` 等）。

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

---

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

### 含义与适用场景

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

### 启用方式

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

```bash
# 方式 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 工具](/ai/cloudbase-ai-toolkit/mcp-tools)；如需确认某个工具或插件是否真实存在，请优先以 `mcp/src/server.ts` 与 `mcp/src/tools/*.ts` 中的注册结果为准。
