跳到主要内容
版本：8.3.0

钉钉企业智能体 MCP 接入指南

概述

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

钉钉企业智能体 MCP 接入步骤

接入前确认

开始前请确认：

  • GuanMCP 服务已按 管理员统一接入 配置 MCP_ENTRYPOINT_TOKEN 和 BI_APP_TOKEN。
  • GuanMCP 服务管理员已提供完整 MCP 地址和 MCP 服务凭证。
  • 钉钉企业智能体或企业可信网关能够根据当前已登录成员动态注入其 UserId。
  • 钉钉成员 UserId 已同步到观远 BI 用户的「钉钉账号」属性，并且能唯一匹配一个已启用的 BI 用户。
风险提示

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

第一步：确认钉钉身份传递约定

本文按当前接入约定使用 X-DingTalk-User-Id 传递钉钉成员 UserId。该名称不是 GuanMCP 硬编码的固定 Header；配置前需要确认钉钉企业智能体或企业可信网关会在每次请求中动态携带：

X-DingTalk-User-Id: <当前成员 UserId>

钉钉官方的 自定义 MCP 说明 可用于了解平台侧 MCP 配置入口。公开说明未定义 X-DingTalk-User-Id，请以企业当前接入方案的实际请求为准。

第二步：更新 GuanMCP 用户映射

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

BI_USER_PROPERTY_HEADER=X-DingTalk-User-Id
BI_USER_PROPERTY_KEY=dingtalk

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

data:
  BI_USER_PROPERTY_HEADER: "X-DingTalk-User-Id"
  BI_USER_PROPERTY_KEY: "dingtalk"

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

注意

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

第三步：添加 GuanMCP 服务

  1. 按企业当前的钉钉企业智能体 MCP 接入方式，填写 GuanMCP 完整地址，例如 https://mcp.company.com/mcp。

  2. 使用固定请求头 Authorization: Bearer <MCP 服务凭证> 完成 MCP 入口鉴权。

  3. 确认每次请求都按第一步的约定动态携带当前成员 UserId。

  4. 点击「MCP 检测」。检测通过后，右侧应展示 GuanMCP 工具列表。

    钉钉企业智能体 MCP 配置与检测结果

请求示例：

POST https://mcp.company.com/mcp
Authorization: Bearer <MCP 服务凭证>
X-DingTalk-User-Id: <当前成员 UserId>

钉钉端不要配置个人 PAT、BI 登录密码或 BI_APP_TOKEN。

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

确认钉钉成员 UserId 与观远 BI 用户基本信息中的「钉钉账号」完全一致，包括大小写，并且该值在观远 BI 中只对应一个已启用用户。

  1. 在钉钉管理后台打开「通讯录 > 成员管理」，查看成员的「员工 UserID」。

    钉钉管理后台成员 UserID

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

    观远 BI 用户的钉钉账号

不要使用钉钉 CorpId、UnionId、手机号或昵称代替成员 UserId。

第五步：验证接入

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

    帮我查看下有哪些数据集

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

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

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

使用 GuanMCP

在钉钉企业智能体中可以直接使用自然语言提问，例如：

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

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

常见问题排查

提示缺少用户身份

确认钉钉企业智能体或企业可信网关是否按约定注入 X-DingTalk-User-Id。仅在 GuanMCP 中配置 Header 名称，不会让上游平台自动产生当前成员 UserId。

提示无法匹配用户

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

修改配置后仍使用旧映射

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

不同成员看到相同数据

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

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