对接飞书 Aily 使用指南
概述
本文介绍如何在飞书 Aily 中接入已部署好的 GuanMCP 服务。配置完成后，Aily 可以通过 MCP 调用观远 BI 查询能力。
接入完成后，员工仍然在 Aily 中提问，Aily 通过 GuanMCP 调用观远 BI 的数据查询、指标查询、页面和卡片信息读取以及 ChatBI 问数类能力，并按员工在 BI 中的权限返回结果。
关键认证
正式接入前需要准备两类认证信息：
| 认证信息 | 提供方 | 用途 |
|---|---|---|
| 账号同步令牌 (Token) | BI 管理员 | 用于 MCP Server 部署，对应启动配置 BI_APP_TOKEN，是 MCP Server 识别并映射 GuanBI 用户身份的关键信息。 |
MCP_ENTRYPOINT_TOKEN | 运维人员 | 按 GuanMCP 部署指南生成，用于 Aily 中的请求头配置，对应 Authorization: Bearer {MCP_ENTRYPOINT_TOKEN}，用于保护 MCP 服务入口。 |
正式多用户接入应使用企业身份映射，Aily 客户端不应保存或要求用户输入 BI Token。GuanMCP 服务部署、BI_APP_TOKEN、MCP_ENTRYPOINT_TOKEN 配置以及企业级身份映射的详细内容，请参考 GuanMCP 部署指南。
推荐接入方式
生产环境建议使用“企业身份映射”方式：Aily 传递当前用户标识，GuanMCP 服务端将外部账号映射到唯一的 GuanBI 用户，再按该用户在 BI 中的权限查询数据。
Aily 调用 MCP 时，会在 Header 中传递用户身份信息：
| Header | 含义 | 使用建议 |
|---|---|---|
x-aily-user | 用户在当前企业内的 Feishu_user_id，是一串数字。 | 注意不是员工工号。由于该 ID 对业务和管理员不直观，也不易人工获取，不建议优先用它做映射。 |
x-aily-email | 当前用户邮箱。 | 推荐使用邮箱识别用户，便于与 GuanBI 用户邮箱字段匹配和排查。 |
使用邮箱识别用户时，GuanMCP 服务端需要配置：
BI_USER_PROPERTY_HEADER=x-aily-email
BI_USER_PROPERTY_KEY=email
不建议在生产环境中让所有 Aily 用户共用一个固定 uIdToken。固定 Token 适合演示和临时验证，但会让所有人共享同一个 BI 账号权限，无法体现真实的用户权限隔离。
Aily 接入流程
第一步：准备账号同步令牌
请先准备账号同步令牌 (Token)。如果缺失，需要由 BI 管理员提供。
该令牌对应 MCP Server 启动配置参数：
BI_APP_TOKEN=<账号同步令牌>
第二步：部署 MCP Server
由运维人员部署 MCP Server。MCP_ENTRYPOINT_TOKEN 需要参考 GuanMCP 部署指南生成。部署完成后，运维需要提供：
- MCP Server 完整地址，例如
https://<mcp-domain>/mcp MCP_ENTRYPOINT_TOKEN
启动参数建议配置如下：
BI_APP_TOKEN=<账号同步令牌>
MCP_ENTRYPOINT_TOKEN=<运维生成的入口 Token>
BI_USER_PROPERTY_HEADER=x-aily-email
BI_USER_PROPERTY_KEY=email
MCP Server 的相对路径建议使用 /mcp。部署完成后，运维需要提供完整 URL，例如 https://<mcp-domain>/mcp，供 Aily 配置请求地址。
Aily 会自动传递当前用户标识，常见 Header 为 x-aily-user 和 x-aily-email。推荐服务端使用 x-aily-email 匹配 GuanBI 用户邮箱。GuanMCP 根据服务端身份映射识别唯一的 GuanBI 用户，并按该用户的 BI 权限返回数据。客户端侧不要配置 uIdToken、loginId 或 BI_APP_TOKEN。
x-aily-user 是用户在当前企业的 Feishu_user_id，通常是一串数字，不是员工工号。如果使用它做映射，需要确保 GuanBI 用户属性中也维护了对应的 Feishu_user_id。多数场景建议使用 x-aily-email。
第三步：在 Aily MCP 市场注册企业内部 MCP 服务
进入 Aily MCP 市场，创建一个“注册企业内部 MCP 服务”。Aily MCP 配置可参考 飞书 Aily MCP 配置文档。
按需填写名称和描述后，配置以下内容：
| 配置项 | 填写方式 |
|---|---|
| 请求地址 URL | 填写第二步运维提供的 MCP Server 完整地址，例如 https://<mcp-domain>/mcp。 |
| Endpoint 类型 | 选择 Streamable HTTP。 |
| 请求头 | 添加一个输入方式为“固定值”的请求头。参数名称为 Authorization，参数值为 Bearer {MCP_ENTRYPOINT_TOKEN}。 |
第四步：在 Aily 智能体中添加 MCP
进入 Aily 智能体编辑页，找到 MCP 配置并点击添加 MCP。添加方式选择“从 MCP 库添加”，然后选择第三步创建的 MCP。
完成上述步骤后，就可以在智能体中使用 BI MCP 了。
每次 MCP Server 升级或修改配置后，都需要在 Aily 的“MCP 市场”中打开目标 MCP 的编辑页，然后保存一次，才能刷新 MCP 配置。
临时测试方式
固定值模式
固定值模式适合测试环境，或希望 Aily 中所有用户都以同一个 BI 账号身份访问数据的场景。
这种模式下，所有用户共享同一个 uIdToken，因此也共享该 Token 对应账号的数据权限。如何获取 uIdToken 可参考下文 如何获取测试用 uIdToken。
| 参数类型 | 参数名称 Key | 参数值类型 | 参数值 Value | 说明 |
|---|---|---|---|---|
| 请求头 | Authorization | 固定值 | Bearer <你的mcp_service_token> | 对应 MCP 服务端配置的 MCP_ENTRYPOINT_TOKEN |
| 请求头 | X-GuanBI-Uid-Token | 固定值 | <从浏览器中获取的 uIdToken 字符串> | 所有用户共享此 Token 的数据权限 |
固定值模式会让所有 Aily 用户共用同一个 BI 账号权限。该模式更适合测试、演示或受控验证，不建议作为正式多用户权限隔离方案。
用户输入模式
相比固定值模式，用户输入模式更适合需要区分用户数据权限的临时验证场景。Aily 统一配置 uIdToken 请求头格式，但由每个用户输入自己的 GuanBI uIdToken。
这样可以继承 BI 系统原有的数据权限隔离，防止不同用户之间越权查看数据。
| 参数类型 | 参数名称 Key | 参数值类型 | 展示名称 | 描述建议 |
|---|---|---|---|---|
| 请求头 | Authorization | 固定值 | 固定值无需展示名称 | 参数值填写：Bearer <你的mcp_service_token> |
| 请求头 | X-GuanBI-Uid-Token | 用户输入 | GuanBI 用户凭证 (uIdToken) | 请输入您在 GuanBI 系统中获取的个人 uIdToken。该凭证用于保障您的个人数据权限安全，防止数据越权。 |
配置为「用户输入」后，当用户在 Aily 智能体中添加或激活这个 MCP 工具时，Aily 会提示其输入自己的 uIdToken。如何获取 uIdToken 可参考下文 如何获取测试用 uIdToken。该模式只用于临时验证，不作为正式多用户接入方案。
如何获取测试用 uIdToken
两种临时测试模式获取 uIdToken 的方式相同。管理员可以按以下步骤获取统一账号 Token；普通用户也可以按相同步骤获取自己的个人 Token。
该方式适合测试、演示或临时验证。正式生产接入不建议要求每个业务用户手动复制 Cookie Token，应优先采用企业身份映射、网关注入身份等方式。相关部署和身份映射配置请参考 GuanMCP 部署指南。
通过 Cookie 方式获取的 uIdToken 通常带有一定的有效期（取决于 BI 系统的安全策略）。如果后续 Aily 报错提示鉴权失败（401），通常是因为该 Token 已过期，需要按照步骤重新获取并在 Aily 中更新。
-
登录观远 BI。
-
在 BI 页面任意空白处右键，选择「检查」或「检查元素」，打开浏览器开发者工具。
也可以使用快捷键：
| 操作系统 | 快捷键 |
| --------------- | -------------------------- |
| Windows / Linux |
F12或Ctrl + Shift + I|| macOS |
Cmd + Option + I| -
在开发者工具顶部导航栏中，找到「Application」标签页，在左侧边栏中展开「Storage > Cookies」，点击当前 BI 系统的域名后，点击「uIdToken」。Cookie Value 即为所需的
uIdToken，双击或选中后复制。
配置后验证
配置完成后，建议按以下顺序验证：
- 在 Aily 中确认 GuanMCP 工具已启用，且不会提示入口鉴权失败。
- 使用一个普通权限用户提问一个简单问题，例如“我能看到哪些销售相关看板？”。
- 使用一个高权限用户提问相同问题，对比返回资源范围是否符合 BI 权限。
- 提问一个指标口径问题，例如“销售额这个指标是什么意思？”。
- 提问一个数据问题，例如“昨天华东区销售额是多少？”。
- 提问一个用户无权查看的资源，确认不会返回越权数据。
如果验证不通过，请先判断问题属于 Aily 配置、MCP 服务入口鉴权、用户身份映射，还是 BI 资源权限。
上下文与返回数据限制
Aily MCP 对模型上下文和工具返回内容有长度限制。由于模型上下文有限，建议让 MCP 工具返回的数据保持在 2 万字左右，避免单次返回数据过长，导致 Agent 无法完整消费、总结或继续调用后续工具。
在设计 BI MCP 查询场景时，建议：
- 优先返回汇总结果、关键指标、Top N 明细和必要的追溯信息。
- 对明细数据设置合理行数上限，避免一次返回大量原始记录。
- 对需要深入分析的问题，拆成多轮查询，例如先查整体趋势，再按门店、区域、商品或时间继续下钻。
- 如果确实需要导出大量明细，建议改用 BI 页面、数据集导出或其他专门的数据导出方式，不建议直接通过 Aily 对话承载。
更多 Aily MCP 限制可参考 飞书 Aily MCP 配置文档。
常见问题
正式接入和临时测试有什么区别
正式接入由 Aily 自动传递用户标识，服务端将其映射为唯一的 GuanBI 用户；客户端只保存 MCP 入口凭证，因此可以继承 BI 的用户权限。
固定值模式让所有用户共用一个 BI 账号权限；用户输入模式要求每位用户手动提供自己的 uIdToken。两者都只适合测试、演示或临时验证。
提示鉴权失败或 401
通过 Cookie 获取的 uIdToken 通常有有效期。若 Aily 后续提示鉴权失败或返回 401，请重新登录 GuanBI，按本文步骤重新复制测试用 uIdToken，并在 Aily 中更新。