---
id: "zh/mcp-integration"
title: "巴别鸟 MCP"
language: "zh"
description: "了解巴别鸟 MCP 的能力、API Key 配置、权限与文件操作，完成智能体接入、连接验证、文件检索与上传。"
canonical_url: "https://www.babel.cc/public/babelwiki/zh/mcp-integration.html"
markdown_url: "https://www.babel.cc/public/babelwiki/ai/zh/mcp-integration.md"
alternates: {"en": "https://www.babel.cc/public/babelwiki/ai/en/mcp-integration.md", "zh": "https://www.babel.cc/public/babelwiki/ai/zh/mcp-integration.md"}
reading_note: "文档记录不等于当前部署能力；以实际版本、授权模块与配置为准。保留原文的可选、限制及待确认说明，勿补猜接口。 / Documentation is not a guarantee for every deployment. Preserve optional-module requirements, limitations and unresolved API contracts."
---

# 巴别鸟 MCP

巴别鸟 MCP 是连接企业文件与 AI 智能体的标准接口。接入后，Codex、WorkBuddy、OpenClaw 及其他支持 MCP 的智能体，可以在用户授权范围内查找文件、读取内容、查询企业知识库、检索相似图片，并把项目文件保存到指定的巴别鸟目录。

MCP 不会绕过巴别鸟权限。智能体最终可访问的内容，由用户原有权限、API Key 权限、可访问目录和企业安全策略共同决定。

> **巴别鸟公有云 MCP 使用固定地址：`https://www.babel.cc/mcp`。** 所有公有云用户使用同一个服务地址，通过各自创建的 API Key 完成身份识别和权限控制。创建新 API Key 不会产生新的 MCP 地址。

## 可以做什么

| 能力 | 智能体可以完成的工作 | 主要工具 |
| --- | --- | --- |
| 项目工作目录 | 选择一个有权限的文件夹作为当前项目目录 | `babel_get_workspace`、`babel_set_workspace` |
| 最近上传 | 获取最近上传或更新的文件 | `babel_get_recent_files` |
| 知识库查询 | 在巴别鸟向量库中进行语义查询，并返回来源文件 | `babel_query_knowledge` |
| 相似图片 | 用文字或已有图片查找相似图片 | `babel_find_similar_images` |
| 文件名搜索 | 按关键词搜索文件名 | `searchFileNameByKey` |
| 目录与文件信息 | 查看文件夹列表，或根据路径取得文件信息 | `listFolder`、`getFileInfoByPath` |
| 文件读取与下载 | 读取文件内容，或取得下载地址 | `getFileContent`、`getDownloadUrl` |
| 创建与上传 | 在授权目录创建文件夹并取得文件上传地址 | `createFolder`、`getUploadUrl` |
| 容量查询 | 查看当前账号的已用空间和可用配额 | `getUsageAndQuota` |

## 五分钟快速入门

### 1. 创建独立的 API Key

打开巴别鸟，进入“设置 > API秘钥”，点击右上方的“创建API密钥”。一个用户可以创建多个 API Key，建议按智能体和用途分别命名，例如 `Codex-研发项目`、`WorkBuddy-市场资料`、`OpenClaw-知识查询`，便于识别和分别管理。

![设置中的 API 密钥入口与创建按钮](https://www.babel.cc/public/babelwiki/assets/images/mcp-api-keys-list.png?v=20261009)
*尚未创建应用时显示空列表；右上方提供“API快速入门”和“创建API密钥”入口。创建后，列表按 APP 名称和创建日期展示应用。*

进入“创建新APP”后，填写 APP 名称并选择需要访问的权限类型：

- **应用程序文件夹**：系统为当前应用创建一个专用文件夹，智能体只访问该文件夹，适合仅操作该目录的通用 MCP 场景。
- **完整**：允许应用访问当前用户在巴别鸟中原本有权访问的文件及文件夹，适用于跨目录检索，也是在使用项目云端同步插件与 Skill 时必须选择的访问范围。

> **使用[项目云端同步插件与 Skill](https://www.babel.cc/public/babelwiki/zh/project-cloud-sync.html)，必须在巴别鸟的 MCP / API Key 设置中授予“完整”访问权限，并开启下文所列的文件元数据与内容读写权限。** “应用程序文件夹”授权不满足该插件与 Skill 的使用要求。这里的设置入口是巴别鸟“设置 > API秘钥”中对应的 APP，而不只是智能体客户端中的“启用 MCP”开关。

![为 APP 命名并选择应用程序文件夹或完整访问范围](https://www.babel.cc/public/babelwiki/assets/images/mcp-create-api-key.png?v=20261009)
*确认名称与访问范围后，点击“创建密钥”。“完整”仍受当前用户原有权限约束，不代表可访问全企业的所有文件。*

### 2. 复制 API Key 或接入提示词

创建完成后，打开对应 APP 的详情页。接入 MCP 时使用页面上方的 **APIKey**，不要把下方高级选项中的 APP Key 或 APP Secret 当作 API Key。

![API 访问 URL、APIKey、重置 Key 和 AI 接入提示词](https://www.babel.cc/public/babelwiki/assets/images/mcp-api-key-details.png?v=20261009)
*详情页上方可复制 MCP 地址和 API Key，也可直接复制“AI接入提示词”。配图中的凭据已遮盖，请使用自己账户创建的密钥。*

| 页面项目 | 接入时如何使用 |
| --- | --- |
| API访问URL | 公有云固定为 `https://www.babel.cc/mcp`，可点击右侧复制图标 |
| APIKey | 点击“复制”取得当前 APP 的 API Key，用于 AI 智能体接入 |
| 可访问范围 | 核对当前 APP 的目录范围；“全部文件”仅指当前用户原本有权访问的文件 |
| AI接入提示词 | 点击该区域右侧的复制图标，将接入提示词交给可信的智能体 |
| 重置 Key | 需要更换密钥时使用；重置后及时更新使用该密钥的智能体配置 |

接入 MCP 时，优先在智能体 MCP 设置的安全密钥输入框中填写 APIKey。如果当前智能体没有安全填写入口，可使用巴别鸟页面生成的“AI接入提示词”；它包含 MCP 地址、API Key 和只读检查要求。下面是这种接入方式的模板：

```text
我需要接入巴别鸟 MCP，该 MCP 的访问 URL 是 https://www.babel.cc/mcp，API Key 为 <你的 API Key>。配置完成后列出可用工具，并执行一次只读连接测试。
```

仅将含有真实密钥的提示词提供给可信的智能体和私密会话，不要发送到群聊、公开工单或代码仓库。如果智能体不能自动完成设置，请在其 MCP 设置中新增远程 MCP 服务，地址填写 `https://www.babel.cc/mcp`，认证信息使用当前 APP 的 API Key。

以 Codex 为例，可采用下面的远程 MCP 配置。API Key 通过环境变量读取，不直接写入配置文件：

```toml
[mcp_servers.babelbird]
url = "https://www.babel.cc/mcp"
bearer_token_env_var = "BABELBIRD_API_KEY"
```

### 3. 检查文件与文件夹权限

向下滚动 APP 详情页，可以看到“高级选项”和“文件和文件夹权限”。目录范围决定应用能接触哪些文件，下面的权限决定应用可以执行哪些操作，两者都受当前用户原有权限约束。

![高级选项与文件和文件夹权限](https://www.babel.cc/public/babelwiki/assets/images/mcp-api-permissions.png?v=20261009)
*文件权限区提供元数据与文件内容的读写选项。图中勾选状态仅为示例，应按实际用途授予最小必要权限。*

| 权限 | 用途 |
| --- | --- |
| `files.metadata.read` | 查看有权限的文件和文件夹信息 |
| `files.metadata.write` | 查看和编辑有权限的文件和文件夹信息 |
| `files.content.read` | 查看文件和文件夹的内容 |
| `files.content.write` | 编辑文件和文件夹的内容 |

只需查询和读取时，优先使用读取权限；需要创建、上传或更新文件时，再按操作需要配置写入权限。搜索、知识库和图片检索的可用性还取决于产品版本、企业策略和相关索引状态。

**项目云端同步插件与 Skill 需要上表四项读写权限均开启**，用于读取目录、拉取文件、创建工程目录和上传更新。访问范围选择“完整”与操作权限开启读写是两项检查，缺一不可；“完整”不会扩大当前账号本身的文件权限。

**高级选项与 MCP 接入凭据不同：** APP Key、APP Secret 和“重定向 URI（OAuth 2）”用于需要 OAuth 2 授权流程的开发集成。仅使用 API Key 接入 MCP 时，不需要填写重定向 URI，也不要用 APP Key 或 APP Secret 替代 APIKey。

### 4. 验证连接

先在 APP 详情中核对 API Key 的可访问范围：使用“应用程序文件夹”时，以该应用的专用目录测试；使用“完整”时，可选当前账号有权访问的“个人文件”目录。项目云端同步插件与 Skill 按“完整”访问权限配置后，使用“个人文件”检查。连接完成后，可以依次发送：

```text
列出巴别鸟 MCP 的可用工具，不要执行写入操作。
```

```text
读取这个 API Key 授权范围内的目录并列出一页文件，检查巴别鸟连接。若限定为应用程序文件夹，只读取该应用目录；若是完整访问，可读取我有权限的“个人文件”。不清楚授权目录时先向我确认。暂时不要上传文件，也不要查询配额。
```

应由 `getFileInfoByPath` 定位授权目录，再用返回的真实目录 ID 调用 `listFolder`，确认返回成功的业务结果；空目录也可以验证成功。工具可见、HTTP 200 或页面显示“已连接”都不能替代实际目录读取。配额查询不作为默认连接检查，配额超时不代表密钥失效。

### 5. 选择项目工作目录

在执行写入前，让智能体先用 `listFolder` 查看已授权的目标目录，再明确选择一个有权限的文件夹作为工作目录。下面是具有“完整”访问范围且能访问“个人文件”时的示例；应用程序文件夹授权应改用其专用目录：

```text
列出“个人文件/AI 项目”下的文件夹，把“官网改版”设为本次会话的工作目录。所有新文件只能上传到这个目录；更新已有文件前先征得我的确认。
```

未选择工作目录、目录不在 API Key 可访问范围内或没有内容写入权限时，智能体不应继续上传。

## 常用操作流程

### 查找并读取文件

1. 使用 `searchFileNameByKey` 按文件名关键词查找候选文件，或用 `listFolder` 浏览目标目录。
2. 使用 `getFileInfoByPath` 核对文件路径、类型、大小和更新时间。
3. 需要直接读取内容时调用 `getFileContent`；需要下载原文件时调用 `getDownloadUrl`。

### 创建目录并上传文件

1. 使用 `createFolder` 在个人文件或已授权目录中创建目标文件夹。
2. 使用 `getUploadUrl` 为目标目录和文件名申请上传地址。
3. 智能体将文件上传到返回的地址，再使用 `listFolder` 或 `getFileInfoByPath` 验证结果。

### 查询知识库与图片

- 使用 `babel_query_knowledge` 在巴别鸟向量库中查询，例如“在知识库中查询合同归档流程，并附来源文件”。
- 使用 `babel_find_similar_images` 按文字或图片文件查找相似图片，并返回用户有权访问的结果。

## 常用指令示例

- “查询当前空间用量和剩余配额。”
- “获取最近 7 天上传的文件，按更新时间倒序排列。”
- “在巴别鸟知识库中查询‘合同归档流程’，回答时附上来源文件。”
- “按文件名搜索‘华东渠道政策’，只显示我有权访问的结果。”
- “列出个人文件下的 PDF，并读取其中的会议纪要。”
- “用文件 ID `xxxx` 查找相似图片，返回前 20 条并标出所在目录。”
- “在个人文件中创建‘AI 项目/季度复盘’，取得上传地址并保存本次输出。”

## MCP 工具清单

工具名区分大小写，应以当前连接实际列出的工具为准；当前目录列表工具为 `listFolder`，部分旧说明写作 `ListFolder`。不要仅按文档名称猜测调用。

| 工具 | 作用 | 操作类型 |
| --- | --- | --- |
| `listFolder` | 列出指定文件夹或当前工作目录中的文件和子文件夹 | 只读 |
| `getFileContent` | 读取有权限文件的内容 | 只读 |
| `getUsageAndQuota` | 查询账号已使用空间和可用配额 | 只读 |
| `getDownloadUrl` | 获取有权限文件的下载地址 | 只读 |
| `searchFileNameByKey` | 按关键词搜索文件名 | 只读 |
| `getUploadUrl` | 为指定目录和文件申请上传地址 | 写入准备 |
| `createFolder` | 在个人文件或已授权目录中创建文件夹 | 写入 |
| `getFileInfoByPath` | 根据完整路径查询文件或文件夹信息 | 只读 |
| `babel_get_workspace` | 查看当前项目工作目录及读写状态 | 只读 |
| `babel_set_workspace` | 选择一个已授权文件夹作为当前工作目录 | 设置上下文 |
| `babel_get_recent_files` | 获取最近上传或更新的文件 | 只读 |
| `babel_query_knowledge` | 在企业知识库或向量库中查询，并返回来源 | 只读 |
| `babel_find_similar_images` | 通过文字或图片文件 ID 检索相似图片 | 只读 |

当前工具清单不包含删除文件、移动文件、对外分享或修改成员权限等高风险操作。调用 `getUploadUrl` 或 `createFolder` 前，智能体应明确目标目录和操作内容；重复上传前应先检查已有文件。

## 权限与安全

- 继承用户权限：MCP 只能访问当前用户原本有权查看或编辑的内容。
- 限制目录范围：仅操作专用目录的通用 MCP 场景可选择“应用程序文件夹”；项目云端同步插件与 Skill 必须选择“完整”。两种授权都不能绕过当前账号权限。
- 区分读写权限：查询、搜索和读取不等同于写入；不需要上传时不要开启写权限。
- 一工具一密钥：建议 Codex、WorkBuddy、OpenClaw 分别创建 API Key，便于单独停用和审计。
- 全程留痕：记录密钥标识、用户、智能体、工具、目标文件、结果、时间和来源地址，但不记录 API Key 明文。
- 最小化返回：搜索和知识库查询只返回完成任务所需的字段与片段，大文件通过下载地址读取。
- 安全上传：申请上传地址前明确目标文件夹和文件名，更新已有文件前应由用户确认。
- 安全保管密钥：API Key 和 APP Secret 都属于敏感凭据。复制的 AI 接入提示词也含有 API Key，不应公开。API Key 疑似泄露时，在对应 APP 详情页点击“重置 Key”，并更新使用该密钥的智能体配置。

## 常见问题

### 在哪里复制 API Key？

进入“设置 > API秘钥”，打开对应 APP，在上方“APIKey”区域点击“复制”，或复制“AI接入提示词”。不要到高级选项中复制 APP Key 或 APP Secret 作为 MCP 接入密钥。

### API Key、APP Key 和 APP Secret 是同一个东西吗？

不是。API Key 用于本文的 MCP 智能体接入；APP Key 和 APP Secret 是高级选项中的应用凭据，用于相应的开发授权流程。接入 MCP 时，应复制明确标为“APIKey”的值。

### 重置 Key 后需要重新配置智能体吗？

需要。在 APP 详情页点击“重置 Key”后，将新的 API Key 更新到所有使用该 APP 密钥的智能体，再执行一次只读连接测试。MCP 地址不变，无需因为重置密钥而更换公有云 URL。

### 公有云 MCP 地址会随用户或 API Key 改变吗？

不会。巴别鸟公有云 MCP 地址固定为 `https://www.babel.cc/mcp`。不同用户和不同智能体通过各自的 API Key 鉴权并获得相应权限，不需要为每个 API Key 配置不同地址。

### 一个用户可以创建多个 API Key 吗？

可以。建议为不同智能体、项目或权限范围分别创建，避免共用凭证。停用某一个 API Key 不会影响其他密钥。

### 为什么智能体找不到某个文件？

依次检查用户本身是否有权限、API Key 是否包含该目录、读取权限是否开启，以及文件是否已完成搜索或向量索引。MCP 不会扩大用户原有权限。

### 上传文件为什么要先调用 `getUploadUrl`？

`getUploadUrl` 用于在权限校验后取得上传地址。智能体应先确定目标目录和文件名，再通过返回地址上传文件，最后用 `listFolder` 或 `getFileInfoByPath` 验证上传结果。

### 私有化部署使用哪个地址？

固定地址 `https://www.babel.cc/mcp` 仅用于巴别鸟公有云。私有化部署使用企业自己的 MCP 地址，具体 URL、网络连通方式和证书配置由企业管理员或实施人员提供。

### 显示“已连接”或能列出工具，就代表文件操作可用吗？

还不能。握手成功或列出工具只说明 MCP 通道可用。请继续在 API Key 的授权范围内执行只读业务检查：限定应用程序文件夹时读取该应用目录；完整访问时可读取有权限的“个人文件”。得到实际目录结果，才确认该目录的读取可用。项目云端同步插件与 Skill 还要求“完整”访问范围及文件读写权限。上传后还需检查云端文件信息，不能只凭取得上传地址判断上传成功。

### 配额查询超时，或响应流结束却没有结果，怎么办？

这次调用没有返回有效业务结果，不能当成成功，也不能仅凭它判断 API Key 错误。项目同步插件默认跳过配额查询，改用实际目录读取检查连接。如果目录查询也失败，检查 MCP 地址、网络、API Key 和目录读取权限，再重试并记录具体报错。配额超时可以不作为连接的唯一阻断项，但实际读写结果仍需确认。

## 工作方式

```text
Codex / WorkBuddy / OpenClaw / 其他智能体
                    │
        固定地址 https://www.babel.cc/mcp
                 + API Key
                    │
                    ▼
              巴别鸟 MCP 网关
      身份校验 · 权限交集 · 目录限制 · 审计
          ┌─────────┼─────────┐
          ▼         ▼         ▼
       文件服务   搜索/OCR   智巢 AI
                            向量库/搜图
```

## 相关资料

- [MCP 应用：项目云端同步插件与 Skill](https://www.babel.cc/public/babelwiki/zh/project-cloud-sync.html)
- [智巢 AI 概览](https://www.babel.cc/public/babelwiki/zh/ai-overview.html)
- [标准版模块](https://www.babel.cc/public/babelwiki/zh/ai-standard-modules.html)
- [权限体系](https://www.babel.cc/public/babelwiki/zh/permissions.html)
- [安全与审计](https://www.babel.cc/public/babelwiki/zh/security.html)
- [Codex MCP 配置说明](https://developers.openai.com/codex/mcp)
- [Model Context Protocol](https://modelcontextprotocol.io/specification/latest)