跳到主要内容
版本：8.3.0

自定义企业级 MCP 接入指南

概述

自定义企业级接入适用于企业自研 AI 助手或其他支持 Streamable HTTP MCP 的平台。平台在请求中传递当前成员的唯一标识，GuanMCP 通过对应的观远 BI 用户属性匹配用户，查询权限仍按匹配到的 BI 用户控制。

自定义企业级 MCP 接入步骤

接入前确认

开始前请确认：

  • GuanMCP 服务已按 管理员统一接入 配置 MCP_ENTRYPOINT_TOKEN 和 BI_APP_TOKEN。
  • 企业 AI 平台可以根据当前已登录成员动态传递一个稳定且唯一的标识，例如员工编号。
  • 相同标识已写入观远 BI 用户属性，并且能唯一匹配一个已启用的 BI 用户。

第一步：确定用户映射

选择平台能够传递的身份 Header，并将它与观远 BI 中保存同一标识的用户属性 Key 对应。以下以员工编号为例：

项目示例值说明
身份 HeaderX-Company-User-Id企业 AI 平台随当前成员动态传递的 Header。
观远用户属性 Keyemployee_no观远 BI 中保存员工编号的用户属性 Key。
属性值E001827两端保存的成员标识，必须完全一致并保持唯一。

employee_no 仅为示例，接入时需要替换为当前观远 BI 环境中的实际用户属性 Key。

用户较多时，建议通过 账户数据集 和 账户同步 批量维护身份映射属性；用户较少时，可直接 修改用户信息。

第二步：配置 GuanMCP

填写 MCP_ENTRYPOINT_TOKEN 和 BI_APP_TOKEN，并配置第一步确定的 Header 和用户属性 Key：

MCP_ENTRYPOINT_TOKEN=<MCP 服务凭证>
BI_APP_TOKEN=<观远 Public API 应用 Token（账号同步令牌）>
BI_USER_PROPERTY_HEADER=X-Company-User-Id
BI_USER_PROPERTY_KEY=employee_no

每个 GuanMCP 服务实例只能配置一组用户属性映射；多个平台使用不同映射时，需要使用独立的 GuanMCP 服务实例和访问地址。

第三步：在企业 AI 平台添加 GuanMCP

  1. 添加 Streamable HTTP MCP 服务，填写 GuanMCP 完整地址，例如 https://mcp.company.com/mcp。
  2. 配置固定请求头 Authorization: Bearer <MCP 服务凭证>。
  3. 配置身份 Header X-Company-User-Id，由平台根据当前已登录成员动态填写。

最简请求示例：

POST https://mcp.company.com/mcp
Authorization: Bearer <MCP 服务凭证>
X-Company-User-Id: E001827

身份 Header 不能使用固定值或由终端用户自行填写。企业 AI 平台端不要配置个人 PAT、BI 登录密码或 BI_APP_TOKEN。

第四步：验证接入

  1. 使用普通权限测试成员提问：

    帮我查看下有哪些数据集

  2. 使用高权限测试成员提问相同问题，对比资源范围是否符合两人在观远 BI 中的权限。

  3. 检查两次请求中的身份 Header 是否分别为两名成员的标识。

两名成员获得的结果均符合各自在观远 BI 中的权限，表示用户映射和权限控制生效。

常见问题排查

提示缺少用户身份

确认企业 AI 平台是否按当前成员动态传递 BI_USER_PROPERTY_HEADER 指定的 Header。仅在 GuanMCP 中配置 Header 名称，不会让上游平台自动产生成员标识。

提示无法匹配用户

对比请求中的 Header 值和 BI_USER_PROPERTY_KEY 对应的观远用户属性。两端属性值必须完全一致，并且只能匹配一个已启用的 BI 用户。

不同成员看到相同数据

确认身份 Header 是否随当前成员变化，并检查两名成员在观远 BI 中的权限是否确实不同。不要使用固定 BI 账号代替所有成员查询。

更多问题请参考 GuanMCP 快速入门-常见问题排查。也可以查看 豆包工作伙伴（原飞书 Aily）MCP 接入指南、企业微信插件 MCP 接入指南 或 钉钉企业智能体 MCP 接入指南。