巴别鸟 MCP

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

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

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

可以做什么

五分钟快速入门

1. 创建独立的 API Key

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

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

• 应用程序文件夹：系统为当前应用创建一个专用文件夹，智能体只访问该文件夹，适合限定项目文件的读写范围。
• 完整：允许应用访问当前用户在巴别鸟中原本有权访问的文件及文件夹，适合需要跨目录检索的场景。该选项范围较大，应谨慎使用。

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

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

推荐直接复制页面生成的“AI接入提示词”。它包含 MCP 地址、API Key，以及配置后列出工具并执行只读连接测试的要求。也可以使用下面的模板，替换 API Key 占位符：

我需要接入巴别鸟 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 通过环境变量读取，不直接写入配置文件：

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

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

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

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

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

4. 验证连接

连接完成后，可以依次发送：

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

查询我的巴别鸟空间用量和配额，再列出最近上传的 10 个文件。

能返回 getUsageAndQuota 的配额信息和最近文件，说明固定地址、API Key 及读取权限均已生效。

5. 选择项目工作目录

在执行写入前，让智能体先用 ListFolder 查看个人文件或目标项目目录，再明确选择一个有权限的文件夹作为工作目录：

列出“个人文件/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 工具清单

工具名区分大小写。配置智能体或编写提示词时，应使用下表中的准确名称。

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

权限与安全

• 继承用户权限：MCP 只能访问当前用户原本有权查看或编辑的内容。
• 限制目录范围：按用途选择“应用程序文件夹”或“完整”；优先使用应用程序文件夹，不能用路径跳转到授权范围之外。
• 区分读写权限：查询、搜索和读取不等同于写入；不需要上传时不要开启写权限。
• 一工具一密钥：建议 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、网络连通方式和证书配置由企业管理员或实施人员提供。

工作方式

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

相关资料

• 智巢 AI 概览
• 标准版模块
• 权限体系
• 安全与审计
• Codex MCP 配置说明
• Model Context Protocol