跳到主要内容
版本：8.3.0

自定义企业级 MCP 接入指南

概述

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

自定义企业级 MCP 接入步骤

接入前确认

开始前请确认：

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

第一步：确定用户映射

选择平台能够传递的身份 Header，并将它与观远 BI 中保存同一标识的用户属性 Key 对应。以下以 Coze 用户 ID 映射到观远 BI 自定义属性 CozeID 为例，约定使用 x-aiplugin-connector-identifier 作为身份 Header：

项目示例值说明
身份 Headerx-aiplugin-connector-identifier企业 AI 平台随当前成员动态传递的 Header。
观远用户属性 Key74970c76-114d-cf73-8403-c5dc1a954952观远 BI 自定义属性 CozeID 的内部 key。
属性值123两端保存的成员标识，必须完全一致并保持唯一。

示例 UUID 需替换为当前 BI 环境中 CozeID 属性的实际内部 key，不能直接填写显示名称 CozeID。

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

第二步：配置 GuanMCP

在服务端填写 MCP_ENTRYPOINT_TOKEN 和 BI_APP_TOKEN：

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

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

  1. 添加 Streamable HTTP MCP 服务，填写 GuanMCP 完整地址，例如 https://mcp.company.com/mcp。
  2. 配置固定请求头 Authorization: Bearer <MCP 服务凭证>。
  3. 在平台自定义请求头或可信网关中配置 bi-user-property-header: x-aiplugin-connector-identifier 和 bi-user-property-key: 74970c76-114d-cf73-8403-c5dc1a954952。
  4. 由平台根据当前已登录成员动态填写身份 Header x-aiplugin-connector-identifier，每次请求同时传入两个映射 Header 和身份值。

最简请求示例：

POST https://mcp.company.com/mcp
Authorization: Bearer <MCP 服务凭证>
bi-user-property-header: x-aiplugin-connector-identifier
bi-user-property-key: 74970c76-114d-cf73-8403-c5dc1a954952
x-aiplugin-connector-identifier: 123

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

第四步：验证接入

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

    帮我查看下有哪些数据集

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

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

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

常见问题排查

提示缺少用户身份

确认企业 AI 平台是否按当前成员动态传递 bi-user-property-header 指定的 Header。仅指定 Header 名称，不会让上游平台自动产生成员标识。

提示无法匹配用户

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

不同成员看到相同数据

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

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