--- title: 巴别鸟 MCP description: 使用固定的公有云 MCP 地址和 API Key，将 Codex、WorkBuddy、OpenClaw 等智能体接入巴别鸟文件、搜索、知识库和图片检索能力。 slug: mcp-integration lang: zh category: 智巢 AI category_order: 5 order: 9 keywords: - 巴别鸟MCP - MCP - API 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) *API 秘钥列表显示已创建的应用及创建日期，可从这里创建新密钥或进入已有密钥的详情。* 点击“创建 API 密钥”后，先填写 APP 名称并选择访问权限类型： - **应用程序文件夹**：系统为当前应用创建一个专用文件夹，智能体只访问该文件夹，适合限定项目文件的读写范围。 - **完整**：允许应用访问当前用户在巴别鸟中原本有权访问的文件及文件夹，适合需要跨目录检索的场景。该选项范围较大，应谨慎使用。 ![创建 API 密钥并选择访问范围](../../assets/images/mcp-create-api-key.png) *创建密钥时选择应用程序文件夹或完整访问范围。* 创建完成后，打开对应 APP 进入密钥详情。详情页集中显示 APP Key、APP Secret、可访问范围、OAuth 2 重定向 URI、访问凭证和文件权限。 ![API 密钥详情与权限](../../assets/images/mcp-api-key-details.png) *密钥详情页用于查看应用凭据、确认目录范围并配置文件和文件夹权限。* 需要重点确认： - 可访问范围：优先使用应用程序文件夹；确需跨目录工作时才选择完整范围。无论选择哪一种，都不会突破当前用户原有权限。 - 元数据读取 `files.metadata.read`：列出目录、搜索文件和读取文件信息。 - 文件内容读取 `files.content.read`：读取文件内容或取得下载地址。 - 元数据写入 `files.metadata.write`：创建文件夹或更新文件信息。 - 文件内容写入 `files.content.write`：取得上传地址并向授权目录上传文件。 - 搜索、知识库和图片检索权限：由管理员按产品版本和企业策略启用。 重定向 URI 和访问凭证用于 OAuth 2 接入流程；采用本文的一行命令和 API Key 方式接入 MCP 时，不需要为了取得固定 MCP 地址而填写重定向 URI。 API Key 只在可信环境中使用，不要粘贴到群聊、工单、公开截图或代码仓库。凭证疑似泄露时，应立即停用并重新创建。 ### 2. 用一句话接入智能体 在可信的个人会话中，将下面一行发给支持自动配置 MCP 的智能体，只需替换 API Key： ```text 请帮我接入巴别鸟 MCP，名称为 BabelBird，地址为 https://www.babel.cc/mcp，API Key 为 <你的 API Key>。配置完成后列出可用工具，并执行一次只读连接测试。 ``` 公有云地址是固定值，不需要从 API Key 详情中复制其他服务器地址。如果智能体不能自动完成设置，请在其 MCP 设置中新增远程 MCP 服务，地址填写 `https://www.babel.cc/mcp`，认证信息填写当前用户创建的 API Key。 以 Codex 为例，可采用下面的远程 MCP 配置。API Key 通过环境变量读取，不直接写入配置文件： ```toml [mcp_servers.babelbird] url = "https://www.babel.cc/mcp" bearer_token_env_var = "BABELBIRD_API_KEY" ``` ### 3. 验证连接 连接完成后，可以依次发送： ```text 列出巴别鸟 MCP 的可用工具，不要执行写入操作。 ``` ```text 查询我的巴别鸟空间用量和配额，再列出最近上传的 10 个文件。 ``` 能返回 `getUsageAndQuota` 的配额信息和最近文件，说明固定地址、API Key 及读取权限均已生效。 ### 4. 选择项目工作目录 在执行写入前，让智能体先用 `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 只能访问当前用户原本有权查看或编辑的内容。 - 限制目录范围：每个 API Key 可以限定一个或多个可访问目录，不能用路径跳转到范围之外。 - 区分读写权限：查询、搜索和读取不等同于写入；不需要上传时不要开启写权限。 - 一工具一密钥：建议 Codex、WorkBuddy、OpenClaw 分别创建 API Key，便于单独停用和审计。 - 全程留痕：记录密钥标识、用户、智能体、工具、目标文件、结果、时间和来源地址，但不记录 API Key 明文。 - 最小化返回：搜索和知识库查询只返回完成任务所需的字段与片段，大文件通过下载地址读取。 - 安全上传：申请上传地址前明确目标文件夹和文件名，更新已有文件前应由用户确认。 ## 常见问题 ### 公有云 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)