GuanMCP 接入与使用指南

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

概述

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

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

接入 GuanMCP

第一步：选择接入方式

GuanMCP 支持两类接入方式：

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

如果企业已经提供 GuanMCP 地址，请选择管理员统一接入；如果需要在个人电脑上直接使用，请选择成员各自接入，推荐使用 PAT。

第二步：完成接入

管理员统一接入

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

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

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

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

   填写 MCP_ENTRYPOINT_TOKEN 和 BI_APP_TOKEN，并按下表为 BI_USER_PROPERTY_HEADER、BI_USER_PROPERTY_KEY 选择当前平台的用户映射：

   MCP_ENTRYPOINT_TOKEN=<MCP 服务凭证>
   BI_APP_TOKEN=<观远 Public API 应用 Token（账号同步令牌）>
   BI_USER_PROPERTY_HEADER=<平台身份 Header>
   BI_USER_PROPERTY_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 服务实例只能配置一组用户属性映射。如需多个平台同时接入，请为每个平台使用独立的 GuanMCP 服务实例和访问地址。

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

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

4. 确认每次请求都携带当前用户属性。身份 Header 必须由已完成用户认证的 AI 平台或可信网关覆盖注入，不能由终端用户或外部客户端自行填写。请求示例如下：

   POST https://mcp.example.com/mcp
   Authorization: Bearer <MCP 服务凭证>
   <用户身份 Header>: <当前用户属性值>

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

风险提示

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

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

成员各自接入

个人接入由 MCP 客户端在本机启动 GuanMCP，每位成员使用自己的观远 BI 凭证。

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 是否可用，取决于所在环境是否已开通相应模块。
• GuanMCP 适合搜索资源、读取配置和查询数据，不适合创建、修改、发布 BI 资源或导出大批量明细。

常见问题排查

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

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

相关文档

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