# 连接方式：本地模式与托管模式
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"]
}
}
}
```
### 本地模式可选环境变量
本地模式下，可通过环境变量调整行为，无需改代码。以下均为**可选**，不配置时使用默认行为。
| 环境变量 | 说明 | 默认 / 说明 |
|----------|------|-------------|
| `CLOUDBASE_ENV_ID` | 云开发环境 ID（可选） | 未设置时首次调用会引导登录并选择环境 |
| `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 默认 |
| `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` |
| `CLOUDBASE_GUIDE_PROMPT` | 设为 `false` 关闭部分引导提示（可选） | 部分 IDE 下会减少提示 |
---
## 托管模式
### 含义与适用场景
- **含义**：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 参数 `disable_plugins` 可禁用指定插件，例如禁用 `rag` 和 `env`：
```
https://tcb-api.cloud.tencent.com/mcp/v1?env_id=YOUR_ENV_ID&disable_plugins=rag&disable_plugins=env
```
当前可配置的插件名：`env`, `database`, `functions`, `hosting`, `storage`, `setup`, `interactive`, `rag`, `cloudrun`, `gateway`, `download`, `security-rule`, `invite-code`, `capi`。
### 托管模式环境变量说明
托管模式下，MCP 服务运行在云端，环境变量在**服务端**配置。若你自建托管服务，可参考 [MCP 工具 - 云端 MCP 配置说明](/ai/cloudbase-ai-toolkit/mcp-tools#云端-mcp-配置说明) 中的可选环境变量表（如 `TENCENTCLOUD_SECRETID`、`TENCENTCLOUD_SECRETKEY`、`CLOUDBASE_ENV_ID` 等）。
使用腾讯云提供的托管 MCP 时，通过上述 URL 与 headers 传入 `env_id` 和密钥即可，无需再配置服务端环境变量。
---
## 支持的插件
| 插件名 | 说明 |
|--------|------|
| `env` | 环境：登录/登出、环境查询、安全域名管理 |
| `database` | 数据库：NoSQL / SQL 结构及数据读写、数据模型 |
| `functions` | 云函数：列表、创建、更新、调用、日志、触发器、HTTP 访问 |
| `hosting` | 静态托管：上传/删除/搜索文件、域名管理 |
| `storage` | 云存储：查询、上传/下载/删除文件 |
| `setup` | 配置与规则：下载模板、IDE 规则与配置文件 |
| `interactive` | 交互：需求澄清、操作确认对话框 |
| `rag` | 知识库与联网：知识库检索、网页搜索 |
| `download` | 下载：项目模板、远程文件到本地 |
| `gateway` | 网关：云函数 HTTP 访问 |
| `security-rule` | 安全规则：NoSQL/SQL/云函数/存储桶的读写规则 |
| `invite-code` | 邀请码：AI 编程激励激活 |
| `cloudrun` | 云托管：服务查询、初始化/部署/删除等 |
| `capi` | 云 API：通用腾讯云 API 调用 |
未配置时默认启用以上全部插件；可通过环境变量或 URL 参数禁用部分插件，见上文本地模式与托管模式说明。
## 支持的工具
当前提供约 38 个 MCP 工具，按插件分布如下。完整参数与说明见 [MCP 工具](/ai/cloudbase-ai-toolkit/mcp-tools)。
| 插件 | 工具名 |
|------|--------|
| env | `login`, `logout`, `envQuery`, `envDomainManagement` |
| database | `readNoSqlDatabaseStructure`, `writeNoSqlDatabaseStructure`, `readNoSqlDatabaseContent`, `writeNoSqlDatabaseContent`, `executeReadOnlySQL`, `executeWriteSQL`, `manageDataModel`, `modifyDataModel` |
| functions | `getFunctionList`, `createFunction`, `updateFunctionCode`, `updateFunctionConfig`, `invokeFunction`, `getFunctionLogs`, `getFunctionLogDetail`, `manageFunctionTriggers` |
| hosting | `uploadFiles`, `deleteFiles`, `findFiles`, `domainManagement` |
| storage | `queryStorage`, `manageStorage` |
| setup | `downloadTemplate`, `downloadRemoteFile` |
| interactive | `interactiveDialog` |
| rag | `searchWeb`, `searchKnowledgeBase` |
| gateway | `createFunctionHTTPAccess` |
| cloudrun | `queryCloudRun`, `manageCloudRun` |
| security-rule | `readSecurityRule`, `writeSecurityRule` |
| invite-code | `activateInviteCode` |
| capi | `callCloudApi` |
