对接飞书 Aily 使用指南
概述
本文介绍如何在飞书 Aily 中接入已部署好的 GuanMCP 服务。配置完成后，Aily 可以通过 MCP 调用观远 BI 能力。
开始前，请先确认已获得：
- GuanMCP 服务地址。请以运维提供的地址为准；生产环境通常为
https://<mcp-domain>/mcp。 - MCP 服务入口 Token，即服务端配置的
MCP_ENTRYPOINT_TOKEN - 已完成企业身份映射的部署；临时测试时，还需要测试用 GuanBI 账号以获取
uIdToken。
正式多用户接入应使用企业身份映射，Aily 客户端不应保存或要求用户输入 BI Token。本文同时保留两种临时测试方式，便于在身份映射尚未完成时验证连通性。GuanMCP 服务部署、MCP_ENTRYPOINT_TOKEN 配置以及企业级身份映射的详细内容，请参考 GuanMCP 部署指南。
配置 Aily 自定义 MCP
进入 Aily MCP 市场，点击创建或添加自定义 MCP，点击 此处 查看官方操作手册。
基础信息配置
| 配置项 | 填写方式 |
|---|---|
| 请求地址 URL | 填写已部署的 MCP 服务地址。若 Aily 要求完整入口，填写 http://<mcp-server-ip>:9090/mcp；若运维提供了网关地址，按网关地址填写。 |
| Endpoint 类型 | 选择 Streamable HTTP |
请求头配置
完成基础信息后，按实际部署方式配置请求头。
正式生产：企业身份映射（推荐）
服务端已按 部署指南 配置外部账号映射后，Aily 客户端只配置 MCP 入口凭证：
| 参数类型 | 参数名称 Key | 参数值类型 | 参数值 Value |
|---|---|---|---|
| 请求头 | Authorization | 固定值 | Bearer <你的mcp_service_token> |
Aily 会自动传递当前用户标识，GuanMCP 根据服务端的身份映射识别唯一的 GuanBI 用户，并按该用户的 BI 权限返回数据。客户端侧不要配置 uIdToken、loginId 或 BI_APP_TOKEN。
临时测试：固定值模式
固定值模式适合测试环境，或希望 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 自动传递用户标识，服务端将其映射为唯一的 GuanBI 用户；客户端只保存 MCP 入口凭证，因此可以继承 BI 的用户权限。
固定值模式让所有用户共用一个 BI 账号权限；用户输入模式要求每位用户手动提供自己的 uIdToken。两者都只适合测试、演示或临时验证。
提示鉴权失败或 401
通过 Cookie 获取的 uIdToken 通常有有效期。若 Aily 后续提示鉴权失败或返回 401，请重新登录 GuanBI，按本文步骤重新复制测试用 uIdToken，并在 Aily 中更新。