GuanMCP 接入与使用指南

更新时间：2026-08-31 17:54:02

概述

GuanMCP 用于将支持 MCP 的 AI 客户端连接到观远 BI。接入后，用户可以用自然语言搜索 BI 资源、了解指标口径和查询有权限的数据。

GuanMCP 只提供查询能力，不创建、修改或删除 BI 资源，也不会绕过观远 BI 的用户权限。

接入 GuanMCP

第一步：选择接入方式

GuanMCP 支持两类接入方式：

接入方式	适用场景	身份与权限
管理员统一接入，成员使用各自身份	豆包工作伙伴（原飞书 Aily）、企业微信插件、钉钉企业智能体、自定义企业级 AI 平台	管理员统一提供 Streamable HTTP 服务；每次请求携带当前用户身份，查询权限按该用户在观远 BI 中的权限控制。
成员各自接入，使用个人 PAT 或账号	个人远程连接、小团队、特定部门、个人本地使用	每位成员在自己的 MCP 客户端中配置个人凭证，查询权限按凭证所属用户控制。

如果 AI 平台能动态传递当前成员身份，可选择管理员统一接入；如果每位成员自行配置凭证，可选择成员各自接入， 使用个人 PAT 连接远程服务或在本机启动 GuanMCP。

第二步：完成接入

管理员统一接入

统一接入适合由管理员集中维护 GuanMCP 服务、成员从同一个 AI 入口使用的场景。

1. 确认 AI 平台可以在每次请求中传递当前用户的唯一属性，并确认该属性已同步到观远 BI 用户信息中。

2. 在标准 GuanMCP 服务中配置 MCP_ENTRYPOINT_TOKEN 和 BI_APP_TOKEN：

   配置项	说明
   MCP_ENTRYPOINT_TOKEN	由 GuanMCP 服务管理员生成的 MCP 服务凭证。AI 平台通过 Authorization: Bearer <MCP 服务凭证> 访问 GuanMCP。
   BI_APP_TOKEN	由观远 BI 管理员提供的 Public API 应用 Token（账号同步令牌），用于换取当前用户的观远身份凭证。只保存在 GuanMCP 服务端，不得配置到客户端请求中。

   MCP_ENTRYPOINT_TOKEN=<MCP 服务凭证>
   BI_APP_TOKEN=<观远 Public API 应用 Token（账号同步令牌）>

   在 AI 平台的自定义请求头中配置用户映射：bi-user-property-header 指定承载当前用户属性值的 Header 名称，bi-user-property-key 指定观远用户属性的内部 key。自定义属性需填写实际内部 key，不能填写显示名称。

   接入平台	bi-user-property-header	bi-user-property-key	映射关系
   豆包工作伙伴（原飞书 Aily）	x-aily-email	email	当前成员邮箱 → 观远用户邮箱
   企业微信插件	X-WeCom-User-Id	wechatwork	企业微信成员 UserId → 观远用户的企业微信账号
   钉钉企业智能体	X-DingTalk-User-Id	dingtalk	钉钉成员 UserId → 观远用户的钉钉账号
   自定义企业级 AI 平台	平台约定的身份 Header	对应的观远用户属性 Key	平台成员唯一标识 → 观远用户属性

   使用支持上述请求头的 GuanMCP 服务后，不同平台可按请求指定映射，共用同一服务。每次请求需同时携带两个映射 Header 和对应用户属性值；配置不完整或无效时直接报错。两个映射 Header 均未传入时，沿用原有 BI_USER_PROPERTY_HEADER、BI_USER_PROPERTY_KEY 环境变量。

   用户映射维护建议：用户较多时，通过 账户数据集 获取企业 OA 账户，再使用 账户同步 批量维护观远 BI 用户及身份映射属性；用户较少时，可直接 修改用户信息。属性值需与接入平台传递的成员标识完全一致并保持唯一。

3. 在 AI 平台中添加 Streamable HTTP MCP 服务，填写完整服务地址，并将 MCP_ENTRYPOINT_TOKEN 配置到 Authorization 请求头。

4. 确认每次请求都携带两个映射 Header 和当前用户属性值，由已完成用户认证的 AI 平台或可信网关注入。以豆包工作伙伴的邮箱映射为例：

   POST https://bi.example.com/mcp
   Authorization: Bearer <MCP 服务凭证>
   bi-user-property-header: x-aily-email
   bi-user-property-key: email
   x-aily-email: <当前用户邮箱>

5. 分别使用两个 BI 权限不同的成员提问同一个问题。两人的结果范围与各自在观远 BI 中的权限一致，表示身份映射和权限控制生效。

风险提示

凭证与身份安全：MCP_ENTRYPOINT_TOKEN 只用于保护 MCP 服务入口，BI_APP_TOKEN 只用于服务端身份交换，两者不能混用。该统一身份映射入口的网关必须丢弃外部请求自带的观远直连凭证、映射 Header 或身份 Header，包括 X-Personal-Token、X-GuanBI-Uid-Token、X-GuanBI-Login-Id 和平台身份 Header，再写入平台固定映射 Header 和已认证的当前用户身份 Header，防止绕过用户映射或冒用他人身份。不要在聊天、截图、工单或代码仓库中暴露真实 Token。

不同平台的具体操作请参考 豆包工作伙伴（原飞书 Aily）MCP 接入指南、企业微信插件 MCP 接入指南、钉钉企业智能体 MCP 接入指南 或 自定义企业级 MCP 接入指南。

成员各自接入

每位成员在自己的 MCP 连接中配置个人凭证，查询权限按凭证所属 BI 用户及其授权范围控制。可以选择以下两种方式。

方式一：连接远程服务，使用个人 PAT

适用于已有 GuanMCP 服务地址、客户端支持 Streamable HTTP 和自定义请求头的场景，无需在本机安装 Node.js 或启动 GuanMCP。

1. 向管理员获取支持个人 PAT 接入的完整 HTTPS MCP 地址。若企业统一身份映射入口会过滤个人凭证，请使用管理员提供的个人 PAT 接入地址。

2. 登录该服务对应的观远 BI 环境，创建并复制自己的 个人访问令牌（PAT）。

3. 在个人 MCP 连接中填写服务地址，并添加请求头 X-Personal-Token，值为本人 PAT。支持 JSON 配置的客户端可参考：

   {
     "mcpServers": {
       "guanbi": {
         "url": "https://bi.example.com/mcp",
         "headers": {
           "X-Personal-Token": "<成员个人 PAT>"
         }
       }
     }
   }

4. 保存配置并重新连接 MCP 服务，提问“帮我查看下有哪些数据集”，确认返回本人有权访问的资源，再继续执行 第三步：验证接入。

个人 PAT 接入不需要额外配置 Authorization、BI_APP_TOKEN 或用户身份 Header； 不能用 Authorization: Bearer <PAT> 代替 X-Personal-Token。 服务地址应使用管理员提供的完整路径，例如 https://bi.example.com/mcp。

每位成员必须使用自己的 PAT，不要将某个人的 PAT 配置为多人共用智能体的公共凭证； 共用 PAT 会按同一个 BI 用户身份查询，不会随当前对话成员自动切换。PAT 失效后，请在个人连接中更新凭证并重新连接。

PAT 模式当前仅支持普通 BI 工具，不提供 ChatBI 工具。 完整限制请参考 PAT 使用指南。

方式二：在本机启动 GuanMCP（stdio）

适用于 MCP 客户端支持在本机启动服务的场景。

1. 登录观远 BI，打开「个人访问令牌」页面，创建并复制个人 PAT。如果看不到该入口，请联系 BI 管理员确认当前环境和用户权限。PAT 操作详见 PAT。

2. 确认本机已安装 Node.js 20 或更高版本，并且可以执行 npx。

3. 在 MCP 客户端中添加以下配置，并将示例地址和 PAT 替换为个人实际信息：

   {
     "mcpServers": {
       "guanbi": {
         "command": "npx",
         "args": ["-y", "@guandata/guanbi-mcp-server@latest"],
         "env": {
           "BI_BASE_URL": "https://bi.example.com",
           "BI_PAT": "<成员个人 PAT>"
         }
       }
     }
   }

4. 保存配置并重新加载 MCP 服务。客户端中出现 GuanMCP 工具后，继续执行 第三步：验证接入。

PAT 是推荐方式，可以单独设置权限、到期时间和撤销。当前环境暂不支持 PAT 时，可以将 env 中的 PAT 配置替换为个人账号：

{
  "BI_BASE_URL": "https://bi.example.com",
  "BI_LOGIN_ID": "<登录账号>",
  "BI_LOGIN_PASSWORD": "<登录密码>"
}

BI_LOGIN_DOMAIN 默认值为 guanbi；登录域不同时，请向 BI 管理员确认后补充该配置。账号密码会保存在本地客户端配置中，请仅在符合企业安全要求时使用。

第三步：验证接入

接入完成后，在 AI 客户端中依次提问：

1. 查询当前能力：

   当前 GuanMCP 可以使用哪些 BI 能力？

2. 搜索当前用户有权访问的资源：

   帮我查看下有哪些数据集

3. 查询数据并要求说明来源：

   查询本周华东区销售额，并说明使用了哪个指标、卡片或数据集。

如果能看到 GuanMCP 工具、找到有权限的资源并返回可核对的数据来源，表示接入成功。

使用 GuanMCP

常用方式

使用目的	提问示例
查找资源	帮我查找名称中包含“门店经营”的页面、卡片和数据集。
了解口径	“销售额”指标的定义是什么？有哪些可用维度？
查询数据	查询本周华东区销售额，并与上周对比。
继续分析	按城市拆解销售额变化，列出变化最大的三项并说明数据来源。

提问时尽量说明时间范围、业务范围、目标指标或资源名称，以及希望返回汇总、趋势还是 Top N。资源名称不确定时，可以先让 AI 搜索并列出候选项，再继续查询。

权限与能力边界

• GuanMCP 按当前用户在观远 BI 中的资源权限、组织范围和行列权限返回结果。
• 指标平台、指标树和 ChatBI 是否可用，取决于所在环境是否已开通相应模块；PAT 模式当前不提供 ChatBI 工具。
• GuanMCP 适合搜索资源、读取配置和查询数据，不适合创建、修改、发布 BI 资源或导出大批量明细。

常见问题排查

本页不重复展开排查步骤。 遇到 HTTP、会话、stdio、分页、UTF-8 或 SQL 问题时，请直接查看 GuanMCP 常见问题排查 中对应的明确处理方法。

豆包工作伙伴接入问题请查看 豆包接入指南。

相关文档

• GuanMCP 常见问题排查
• 豆包工作伙伴（原飞书 Aily）MCP 接入指南
• 企业微信插件 MCP 接入指南
• 钉钉企业智能体 MCP 接入指南
• 自定义企业级 MCP 接入指南
• GuanCLI 与 GuanMCP 对比
• GuanCLI 使用指南