豆包工作伙伴（原飞书 Aily）MCP 接入指南
概述
豆包工作伙伴（原飞书 Aily）采用管理员统一接入方式。管理员只需注册一次 GuanMCP 服务，成员即可使用各自在观远 BI 中的身份和权限查询数据。
豆包工作伙伴（原飞书 Aily）MCP 接入步骤
接入前确认
开始前请确认：
- GuanMCP 服务已按 管理员统一接入 配置
MCP_ENTRYPOINT_TOKEN、BI_APP_TOKEN、BI_USER_PROPERTY_HEADER和BI_USER_PROPERTY_KEY。 - GuanMCP 服务管理员已提供完整 MCP 地址和 MCP 服务凭证。
- 飞书用户邮箱已同步到观远 BI 用户的
email属性，并且能唯一匹配一个已启用的 BI 用户。
- MCP 服务凭证只提供给负责配置豆包工作伙伴的管理员，不要将凭证放入聊天、截图、工单或公开文档。
- 每个 GuanMCP 服务实例只能配置一组用户属性映射。若同一实例改为企业微信或钉钉映射，豆包工作伙伴的
x-aily-email将无法继续按邮箱完成映射。如需多个平台同时接入，请分别使用独立的 GuanMCP 服务实例和访问地址。
第一步：确认邮箱映射
- 选择两个观远 BI 权限不同的测试成员。
- 确认两名成员在飞书中均已配置邮箱。
- 确认相同邮箱已同步到观远 BI 用户的
email属性。 - 确认每个邮箱只对应一个已启用的观远 BI 用户。
可按以下位置核对两端邮箱：
-
在飞书管理后台打开「组织架构 > 成员与部门」，查看成员的「工作邮箱」。
-
在观远 BI 打开「管理中心 > 用户管理 > 用户」，查看同一成员基本信息中的「邮箱」。
邮箱映射关系如下：
飞书当前用户邮箱
↓ x-aily-email
观远用户属性 email
↓
按匹配到的观远用户权限查询
第二步：在豆包工作伙伴 MCP 市场注册 GuanMCP
-
打开 豆包工作伙伴 MCP 市场，点击「注册企业内部 MCP 服务」。
-
填写服务名称和描述，并配置以下内容：
配置项 填写内容 请求地址 URL GuanMCP 完整地址，例如 https://mcp.example.com/mcp。Endpoint 类型 Streamable HTTP。请求头名称 Authorization。请求头输入方式 固定值。 请求头值 Bearer <MCP 服务凭证>。下图展示请求地址、Endpoint 类型和
Authorization请求头的填写位置，示例中的域名和凭证已脱敏：
-
点击「保存」。保存成功后，豆包工作伙伴应能读取 GuanMCP 工具列表。
豆包工作伙伴调用 GuanMCP 时，请求需要同时携带入口凭证和当前用户邮箱：
POST https://mcp.example.com/mcp
Authorization: Bearer <MCP 服务凭证>
x-aily-email: user@example.com
Authorization 是管理员配置的固定请求头，x-aily-email 是豆包工作伙伴根据当前已登录成员动态传递的身份信息。x-aily-email 是沿用的协议字段名，不随产品名称变化，不要把它配置成固定值或用户输入项。
豆包工作伙伴端不要配置个人 PAT、BI 登录密码或 BI_APP_TOKEN。
第三步：在豆包工作伙伴智能体中添加 GuanMCP
- 打开目标豆包工作伙伴智能体的编辑页，点击「添加 MCP」。
- 选择「从 MCP 库添加」，再选择上一步注册的 GuanMCP 服务。
- 启用需要的 GuanMCP 工具，并点击「保存」。
GuanMCP 服务升级或工具发生变化后，请在豆包工作伙伴 MCP 市场中重新打开该服务并保存一次，再检查智能体中的工具列表。
第四步：验证接入
-
使用普通权限测试成员提问：
帮我查看下有哪些数据集 -
使用高权限测试成员提问相同问题，对比资源范围是否符合两人在观远 BI 中的权限。
-
让普通权限成员询问一个明确无权查看的页面或指标，确认豆包工作伙伴不会返回对应数据。
两名成员获得的结果均符合各自在观远 BI 中的权限，表示用户映射和权限控制生效。
使用 GuanMCP
在豆包工作伙伴中可以直接使用自然语言提问，例如：
- “销售额”指标的定义是什么？有哪些可用维度？
- 查询本周华东区销售额，并与上周对比。
- 按城市拆解销售额变化，列出变化最大的三项并说明数据来源。
提问时建议说明时间范围、业务范围、目标指标或资源名称，并要求豆包工作伙伴说明使用的数据来源。大范围分析可以拆成多轮，避免一次返回大量明细。
常见问题排查
在运行日志中确认工具调用
进入对应智能体的「运行日志」，展开「工具调用」并选中具体 GuanMCP 工具。 右侧可以直接查看 Input 调用参数和 Output 返回结果。
- 没有 GuanMCP 工具调用：返回智能体编辑页，确认已添加 GuanMCP、启用所需工具并保存。
- Input 与预期不一致：在问题中明确资源名称、时间范围和筛选条件后重新提问。
- Output 返回 401 或用户匹配错误：按下面对应章节修改配置。
返回 401
将请求头配置为 Authorization: Bearer <MCP 服务凭证>，并确认凭证与服务端
MCP_ENTRYPOINT_TOKEN 完全一致。不要使用 BI_APP_TOKEN。
提示缺少用户身份或无法匹配用户
确认服务端配置为 BI_USER_PROPERTY_HEADER=x-aily-email、BI_USER_PROPERTY_KEY=email，
并满足以下条件：
- 当前豆包工作伙伴对应的飞书用户已配置工作邮箱。
- 相同邮箱已同步到观远 BI 用户的
email属性。 - 该邮箱只匹配一个已启用的观远 BI 用户。
工具列表没有更新
在豆包工作伙伴 MCP 市场中打开 GuanMCP 服务并重新保存。 再返回智能体重新选择并启用工具。
能看到工具，但查不到资源
让当前成员直接登录观远 BI。 若该成员在 BI 中也看不到目标资源，请为邮箱匹配到的 BI 用户授予相应资源权限。
无法连接私有化 GuanMCP
客户的观远 BI 和 GuanMCP 均为私有化部署。
若豆包工作伙伴无法连接 GuanMCP，请联系豆包工作伙伴（原飞书 Aily）技术支持，
检查 MCP 客户端 → 客户观远域名 的网络连通性。
HTTP、会话及数据查询问题请参考 GuanMCP 常见问题排查。 也可以继续查看 企业微信插件 MCP 接入指南、 钉钉企业智能体 MCP 接入指南 或 自定义企业级 MCP 接入指南。