跳到主要内容
版本：8.2.0

企业微信插件 MCP 接入指南

概述

企业微信插件采用管理员统一接入方式。插件在请求中传递当前成员的 UserId，GuanMCP 再匹配观远 BI 用户的企业微信账号，查询权限仍按匹配到的 BI 用户控制。

企业微信插件 MCP 接入步骤

接入前确认

开始前请确认：

  • GuanMCP 服务已按 管理员统一接入 配置 MCP_ENTRYPOINT_TOKEN 和 BI_APP_TOKEN。
  • GuanMCP 服务管理员已提供使用企业域名的完整 MCP 地址和 MCP 服务凭证。
  • 企业微信成员 UserId 已同步到观远 BI 用户的「企业微信账号」属性，并且能唯一匹配一个已启用的 BI 用户。
风险提示

MCP 服务凭证只提供给负责配置企业微信插件的管理员。网关必须丢弃外部请求自带的观远直连凭证或身份 Header，只保留入口鉴权所需的 Authorization，再按已认证的当前成员写入 X-WeCom-User-Id。该 Header 不能由终端用户自行填写。

第一步：更新 GuanMCP 用户映射

在 GuanMCP 的部署环境中将用户映射更新为：

BI_USER_PROPERTY_HEADER=X-WeCom-User-Id
BI_USER_PROPERTY_KEY=wechatwork

如果使用 K8s 部署，请在现有 MCP ConfigMap 中新增或更新以下内容：

data:
  BI_USER_PROPERTY_HEADER: "X-WeCom-User-Id"
  BI_USER_PROPERTY_KEY: "wechatwork"

MCP_ENTRYPOINT_TOKEN 和 BI_APP_TOKEN 沿用管理员统一接入配置。更新 ConfigMap 后，需要滚动重启对应的 MCP Pod，使新的环境变量生效。

注意

每个 GuanMCP 服务实例只能配置一组用户属性映射。若同一实例改为企业微信映射，原豆包工作伙伴或钉钉的身份 Header 将无法继续按原属性完成映射。如需多个平台同时接入，请分别使用独立的 GuanMCP 服务实例和访问地址。

第二步：配置企业微信插件

  1. 参考 企业微信官方插件说明 添加 GuanMCP。
  2. 将 GuanMCP 完整地址配置为企业自有域名，例如 https://mcp.company.com/mcp。
  3. 使用固定请求头 Authorization: Bearer <MCP 服务凭证> 完成 MCP 入口鉴权。

下图展示插件 URL、鉴权方式、请求头和传输协议的配置位置。图中的地址与凭证已脱敏；若页面出现「URL 不属于企业域名」提示，请先改用企业域名，确认提示不再出现后再点击「添加插件」。

企业微信插件 MCP 配置项位置

企业微信官方插件仅在插件 URL 使用企业域名时，自动传递发起请求成员的身份。身份请求头为 X-WeCom-User-Id，值对应企业微信管理后台通讯录成员的账号。

企业微信用户身份请求头规则

请求示例：

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

Authorization 是管理员配置的固定值，X-WeCom-User-Id 必须随当前成员动态变化。企业微信端不要配置个人 PAT、BI 登录密码或 BI_APP_TOKEN。

第三步：校验用户账号映射

确保观远 BI 用户的「企业微信账号」与企业微信管理后台对应成员的账号完全一致，包括大小写，并且该值在观远 BI 中只对应一个已启用用户。企业已完成企业微信集成时，该属性通常已经同步，仍建议在接入前核对一次。

  1. 在企业微信管理后台打开「通讯录 > 组织架构」，查看成员的账号，也就是插件传递的 UserId。

    企业微信管理后台成员账号

  2. 在观远 BI 打开「管理中心 > 用户管理 > 用户」，查看同一成员基本信息中的「企业微信账号」。

    观远 BI 用户的企业微信账号

不要使用企业微信 CorpId、手机号或 UnionId 代替成员账号。

第四步：验证接入

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

    帮我查看下有哪些数据集

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

  3. 让普通权限成员询问一个明确无权查看的页面或指标，确认企业微信不会返回对应数据。

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

使用 GuanMCP

在企业微信中可以直接使用自然语言提问，例如：

  • “销售额”指标的定义是什么？有哪些可用维度？
  • 查询本周华东区销售额，并与上周对比。
  • 按城市拆解销售额变化，列出变化最大的三项并说明数据来源。

提问时建议说明时间范围、业务范围、目标指标或资源名称，并要求说明使用的数据来源。大范围分析可以拆成多轮，避免一次返回大量明细。

常见问题排查

提示缺少用户身份

确认插件使用的是企业域名 MCP 地址，并检查请求是否携带 X-WeCom-User-Id。如果请求经过代理或网关，还需要确认该 Header 没有被删除，并由可信链路按当前成员覆盖注入。

提示无法匹配用户

对比企业微信成员账号、请求中的 X-WeCom-User-Id 和观远用户的「企业微信账号」。三者必须完全一致，包括大小写；该属性还需要唯一匹配一个已启用用户。

修改配置后仍使用旧映射

如果使用 K8s 部署，请确认已更新正确的 MCP ConfigMap，并滚动重启对应 Pod。仅修改 ConfigMap 不会更新已经运行的进程环境变量。

不同成员看到相同数据

先确认两名成员在观远 BI 中的权限确实不同，再检查请求中的 X-WeCom-User-Id 是否随当前成员变化。不要使用固定 BI 账号代替所有成员查询。

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