--- title: 巴别鸟 MCP description: 在设置中创建 API 密钥，复制 API Key 或 AI 接入提示词，配置文件权限，将智能体接入巴别鸟 MCP。 slug: mcp-integration lang: zh category: 智巢 AI category_order: 5 order: 9 keywords: - 巴别鸟MCP - MCP - API Key - API 密钥 - APIKey - AI接入提示词 - 重置 Key - Codex - WorkBuddy - OpenClaw - 向量库 - 文件读写 --- # 巴别鸟 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 密钥入口与创建按钮](../../assets/images/mcp-api-keys-list.png?v=20261009) *尚未创建应用时显示空列表；右上方提供“API快速入门”和“创建API密钥”入口。创建后，列表按 APP 名称和创建日期展示应用。* 进入“创建新APP”后，填写 APP 名称并选择需要访问的权限类型： - **应用程序文件夹**：系统为当前应用创建一个专用文件夹，智能体只访问该文件夹，适合限定项目文件的读写范围。 - **完整**：允许应用访问当前用户在巴别鸟中原本有权访问的文件及文件夹，适合需要跨目录检索的场景。该选项范围较大，应谨慎使用。 ![为 APP 命名并选择应用程序文件夹或完整访问范围](../../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 接入提示词](../../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 | 需要更换密钥时使用；重置后及时更新使用该密钥的智能体配置 | 推荐直接复制页面生成的“AI接入提示词”。它包含 MCP 地址、API Key，以及配置后列出工具并执行只读连接测试的要求。也可以使用下面的模板，替换 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 详情页，可以看到“高级选项”和“文件和文件夹权限”。目录范围决定应用能接触哪些文件，下面的权限决定应用可以执行哪些操作，两者都受当前用户原有权限约束。 ![高级选项与文件和文件夹权限](../../assets/images/mcp-api-permissions.png?v=20261009) *文件权限区提供元数据与文件内容的读写选项。图中勾选状态仅为示例，应按实际用途授予最小必要权限。* | 权限 | 用途 | | --- | --- | | `files.metadata.read` | 查看有权限的文件和文件夹信息 | | `files.metadata.write` | 查看和编辑有权限的文件和文件夹信息 | | `files.content.read` | 查看文件和文件夹的内容 | | `files.content.write` | 编辑文件和文件夹的内容 | 只需查询和读取时，优先使用读取权限；需要创建、上传或更新文件时，再按操作需要配置写入权限。搜索、知识库和图片检索的可用性还取决于产品版本、企业策略和相关索引状态。 **高级选项与 MCP 接入凭据不同：** APP Key、APP Secret 和“重定向 URI（OAuth 2）”用于需要 OAuth 2 授权流程的开发集成。仅使用 API Key 接入 MCP 时，不需要填写重定向 URI，也不要用 APP Key 或 APP Secret 替代 APIKey。 ### 4. 验证连接 连接完成后，可以依次发送： ```text 列出巴别鸟 MCP 的可用工具，不要执行写入操作。 ``` ```text 查询我的巴别鸟空间用量和配额，再列出最近上传的 10 个文件。 ``` 能返回 `getUsageAndQuota` 的配额信息和最近文件，说明固定地址、API Key 及读取权限均已生效。 ### 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` | 列出指定文件夹或当前工作目录中的文件和子文件夹 | 只读 | | `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 只能访问当前用户原本有权查看或编辑的内容。 - 限制目录范围：按用途选择“应用程序文件夹”或“完整”；优先使用应用程序文件夹，不能用路径跳转到授权范围之外。 - 区分读写权限：查询、搜索和读取不等同于写入；不需要上传时不要开启写权限。 - 一工具一密钥：建议 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、网络连通方式和证书配置由企业管理员或实施人员提供。 ## 工作方式 ```text Codex / WorkBuddy / OpenClaw / 其他智能体 │ 固定地址 https://www.babel.cc/mcp + API Key │ ▼ 巴别鸟 MCP 网关 身份校验 · 权限交集 · 目录限制 · 审计 ┌─────────┼─────────┐ ▼ ▼ ▼ 文件服务 搜索/OCR 智巢 AI 向量库/搜图 ``` ## 相关资料 - [智巢 AI 概览](ai-overview.md) - [标准版模块](ai-standard-modules.md) - [权限体系](permissions.md) - [安全与审计](security.md) - [Codex MCP 配置说明](https://developers.openai.com/codex/mcp) - [Model Context Protocol](https://modelcontextprotocol.io/specification/latest)