豆包工作伙伴（原飞书 Aily）MCP 接入指南

更新时间：2026-09-10 09:57:41

概述

豆包工作伙伴（原飞书 Aily）采用管理员统一接入方式。管理员只需注册一次 GuanMCP 服务，成员即可使用各自在观远 BI 中的身份和权限查询数据。

豆包工作伙伴（原飞书 Aily）MCP 接入步骤

接入前确认

开始前请确认：

• GuanMCP 服务已按 管理员统一接入 配置 MCP_ENTRYPOINT_TOKEN 和 BI_APP_TOKEN。
• GuanMCP 服务管理员已提供完整 MCP 地址和 MCP 服务凭证。
• 客户侧运维已按 MCP 出口 IP 白名单配置说明，在 BI 所在服务器的网络管理处添加白名单，放行豆包工作伙伴的访问请求。
• 飞书用户邮箱已同步到观远 BI 用户的 email 属性，并且能唯一匹配一个已启用的 BI 用户。

风险提示

• MCP 服务凭证只提供给负责配置豆包工作伙伴的管理员，不要将凭证放入聊天、截图、工单或公开文档。

第一步：确认邮箱映射

1. 选择两个观远 BI 权限不同的测试成员。
2. 确认两名成员在飞书中均已配置邮箱。
3. 确认相同邮箱已同步到观远 BI 用户的 email 属性。
4. 确认每个邮箱只对应一个已启用的观远 BI 用户。

可按以下位置核对两端邮箱：

1. 在飞书管理后台打开「组织架构 > 成员与部门」，查看成员的「工作邮箱」。

   

2. 在观远 BI 打开「管理中心 > 用户管理 > 用户」，查看同一成员基本信息中的「邮箱」。

   

邮箱映射关系如下：

飞书当前用户邮箱
    ↓ x-aily-email
观远用户属性 email
    ↓
按匹配到的观远用户权限查询

第二步：在豆包工作伙伴 MCP 市场注册 GuanMCP

1. 打开公司专属的豆包工作伙伴 MCP 市场：https://{公司前缀}.feishu.cn/ai/mcpservers，点击「注册企业内部 MCP 服务」。

   将 {公司前缀} 替换为公司的飞书域名前缀。

2. 填写服务名称和描述，并配置以下内容：

   配置项	填写内容
   请求地址 URL	GuanMCP 完整地址，例如 https://bi.example.com/mcp。
   Endpoint 类型	Streamable HTTP。
   请求头名称	Authorization。
   请求头输入方式	固定值。
   请求头值	Bearer <MCP 服务凭证>。

   下图展示请求地址、Endpoint 类型和 Authorization 请求头的填写位置，示例中的域名和凭证已脱敏：

   

3. 在自定义请求头中增加两个固定值：bi-user-property-header: x-aily-email、bi-user-property-key: email。

4. 点击「保存」。保存成功后，豆包工作伙伴应能读取 GuanMCP 工具列表。

豆包工作伙伴调用 GuanMCP 时，每次请求需要同时携带入口凭证、两个映射 Header 和当前用户邮箱：

POST https://bi.example.com/mcp
Authorization: Bearer <MCP 服务凭证>
bi-user-property-header: x-aily-email
bi-user-property-key: email
x-aily-email: user@example.com

Authorization 是管理员配置的固定请求头，x-aily-email 是豆包工作伙伴根据当前已登录成员动态传递的身份信息。x-aily-email 是沿用的协议字段名，不随产品名称变化，不要把它配置成固定值或用户输入项。

豆包工作伙伴端不要配置个人 PAT、BI 登录密码或 BI_APP_TOKEN。

第三步：在豆包工作伙伴智能体中添加 GuanMCP

1. 打开目标豆包工作伙伴智能体的编辑页，点击「添加 MCP」。
2. 选择「从 MCP 库添加」，再选择上一步注册的 GuanMCP 服务。
3. 启用需要的 GuanMCP 工具，并点击「保存」。

GuanMCP 服务升级或工具发生变化后，请在豆包工作伙伴 MCP 市场中重新打开该服务并保存一次，再检查智能体中的工具列表。

第四步：验证接入

1. 使用普通权限测试成员提问：

   帮我查看下有哪些数据集

2. 使用高权限测试成员提问相同问题，对比资源范围是否符合两人在观远 BI 中的权限。

3. 让普通权限成员询问一个明确无权查看的页面或指标，确认豆包工作伙伴不会返回对应数据。

两名成员获得的结果均符合各自在观远 BI 中的权限，表示用户映射和权限控制生效。

使用 GuanMCP

在豆包工作伙伴中可以直接使用自然语言提问，例如：

• “销售额”指标的定义是什么？有哪些可用维度？
• 查询本周华东区销售额，并与上周对比。
• 按城市拆解销售额变化，列出变化最大的三项并说明数据来源。

提问时建议说明时间范围、业务范围、目标指标或资源名称，并要求豆包工作伙伴说明使用的数据来源。大范围分析可以拆成多轮，避免一次返回大量明细。

常见问题排查

在运行日志中确认工具调用

进入对应智能体的「运行日志」，展开「工具调用」并选中具体 GuanMCP 工具。 右侧可以直接查看 Input 调用参数和 Output 返回结果。

• 没有 GuanMCP 工具调用：返回智能体编辑页，确认已添加 GuanMCP、启用所需工具并保存。
• Input 与预期不一致：在问题中明确资源名称、时间范围和筛选条件后重新提问。
• Output 返回 401 或用户匹配错误：按下面对应章节修改配置。
• 工具调用均失败、连接超时或提示连通性不通过：按 MCP 连通性排查 检查网络及出口 IP 白名单。

返回 401

将请求头配置为 Authorization: Bearer <MCP 服务凭证>，并确认凭证与服务端 MCP_ENTRYPOINT_TOKEN 完全一致。不要使用 BI_APP_TOKEN。

提示缺少用户身份或无法匹配用户

确认请求携带 bi-user-property-header: x-aily-email、bi-user-property-key: email 和当前成员的 x-aily-email， 并满足以下条件：

• 当前豆包工作伙伴对应的飞书用户已配置工作邮箱。
• 相同邮箱已同步到观远 BI 用户的 email 属性。
• 该邮箱只匹配一个已启用的观远 BI 用户。

工具列表没有更新

在豆包工作伙伴 MCP 市场中打开 GuanMCP 服务并重新保存。 再返回智能体重新选择并启用工具。

能看到工具，但查不到资源

让当前成员直接登录观远 BI。 若该成员在 BI 中也看不到目标资源，请为邮箱匹配到的 BI 用户授予相应资源权限。

豆包工作伙伴 MCP 连通性问题

豆包工作伙伴可能提示「GuanMCP 数据服务连接异常」「所有工具调用均失败」或「MCP 连通性不通过」， 例如 global_search 查询数据集失败、get_bi_capabilities 获取 BI 能力状态失败。 这些提示本身不能确认根因，请先查看 运行日志中的工具调用，再按以下步骤排查。

排查与处理

1. 确认地址为 https://bi.example.com/mcp 等完整入口，类型为 Streamable HTTP。 日志返回 401 或用户匹配错误时，按 返回 401 或 用户映射问题 处理。
2. 由客户侧运维在 BI 所在服务器（如阿里云服务器）的网络管理处配置白名单， 放行下方 MCP 出口 IP 及所用场景的 额外网段 对 MCP 服务端口的访问。
3. 在 MCP 市场重新保存服务，再从实际使用的智能体或工作流节点查询数据集，确认工具调用成功。

MCP 出口 IP 地址

在豆包工作伙伴官方 IP 白名单 页面查看「MCP 出口 IP 地址」， 按官方最新清单配置，位置如下图所示。

工作流、自定义智能体的智能体节点额外出口 IP

工作流、自定义智能体的智能体节点调用 MCP 时，除基础出口 IP 外，还需放行官方页面“需要额外配置如下 IP”中的 IPv4、IPv6 网段。 配置时请保留完整 CIDR 前缀。

HTTP、会话及数据查询问题请参考 GuanMCP 常见问题排查。 也可以继续查看 企业微信插件 MCP 接入指南、 钉钉企业智能体 MCP 接入指南 或 自定义企业级 MCP 接入指南。