将 Data Agent 接入外部 Agent（MCP Server）

Data Agent 可以作为 MCP Server，把自然语言问数能力提供给 WorkBuddy 等支持 MCP 的 Agent 软件。接入后，用户可以直接在外部 Agent 中提问业务数据，由 Agent 调用 Data Agent 完成查询和分析。

Data Agent 提供的 MCP 服务具有以下特点：

使用 Streamable HTTP 传输协议。
默认服务地址为 https://<Data Agent 域名>/api/mcp。
支持 OAuth 浏览器授权，也支持通过 Bearer Token 鉴权。
复用 Data Agent 原有的用户、角色、空间和数据权限。
当前提供 ask_data 工具，用于调用 Nora 完成自然语言问数。

接入流程

前置条件

接入前请确认：

Data Agent 已完成业务建模，且 Nora 可以在系统内正常回答目标问题。
当前安装包中包含 YiAsk：MCP 服务器 插件。
用于授权的用户已获得目标空间、数据表和字段的访问权限。
外部 Agent 可以通过网络访问 Data Agent。生产环境应使用受信任的 HTTPS 证书。
如果使用 OAuth 自动授权，当前安装包中还需包含并启用 IdP: OAuth 插件。

如果插件列表中没有上述插件，请先升级到包含 MCP Server 能力的 Data Agent 版本。

在 Data Agent 中启用 MCP Server

使用管理员账号进入 系统设置 → 插件管理，确认并启用以下插件：

IdP: OAuth：让外部 Agent 可以通过浏览器登录 Data Agent 并完成授权。使用固定 Bearer Token 接入时可不启用。
YiAsk：MCP 服务器：提供 Data Agent 的 MCP 服务端点和 ask_data 工具。

Data Agent 的 YiAsk：MCP 服务器 与 NocoBase 的同名 MCP Server 插件都会占用 /api/mcp。不要同时启用两者。

插件启用后，MCP 地址为：

https://<Data Agent 域名>/api/mcp

如果部署时修改了 API_BASE_PATH，请把地址中的 /api 替换为实际 API 基础路径。

配置许可证域名

部分许可证会绑定访问域名。浏览器请求会自动携带来源信息，但 WorkBuddy 等 MCP 客户端可能不发送 Origin 或 Referer。此时应在 Data Agent 的部署环境中配置：

YIASK_MCP_ORIGIN=https://data-agent.example.com

该值必须是许可证登记的 Data Agent 对外访问地址，只填写协议和域名，不要包含 /admin、/api/mcp 等路径。修改环境变量后重启 Data Agent。

未配置 YIASK_MCP_ORIGIN 时，系统还会依次尝试读取 APP_PUBLIC_URL、APP_BASE_URL、WEB_BASE_URL 和 API_BASE_URL 中的有效绝对地址。

在 WorkBuddy 中接入

WorkBuddy 支持通过连接器界面添加自定义 MCP Server。不同版本的按钮名称可能略有差异，操作流程如下：

打开 WorkBuddy，在左侧进入 连接器。
点击页面右上角的 自定义连接器。
新建远程 MCP 连接器，名称可以填写 Data Agent。
传输方式选择 Streamable HTTP 或 HTTP。
服务地址填写 https://<Data Agent 域名>/api/mcp。
保存并连接。WorkBuddy 会打开浏览器进入 Data Agent 授权页面。
登录 Data Agent，确认当前账号和授权范围后同意授权。
返回 WorkBuddy，确认连接器状态为已连接，并且工具列表中出现 ask_data。

WorkBuddy 支持用户级和项目级 MCP 配置。希望所有项目都能问数时使用用户级；仅在特定项目中使用时选择项目级。可参考 WorkBuddy 官方的连接器说明和 MCP 配置指南。

如果当前 WorkBuddy 版本提供的是 JSON 编辑器，可按其远程 MCP 配置格式加入以下服务：

{
  "mcpServers": {
    "data-agent": {
      "url": "https://data-agent.example.com/api/mcp"
    }
  }
}

保存后，WorkBuddy 会发起 OAuth 授权。OAuth 模式不需要在配置文件中填写用户名、密码或 Token。

验证问数

新建一个 WorkBuddy 任务，输入一个当前用户有权查询的问题，例如：

请使用 Data Agent 查询本月各区域销售额，并总结表现最好的区域。

执行过程中应能看到 WorkBuddy 调用 ask_data。如果存在多个 MCP 工具，第一次验证时建议在指令中明确写出“使用 Data Agent”，以便确认工具路由是否正确。

接入其他 Agent 软件

任何支持远程 Streamable HTTP MCP 的客户端都可以接入。优先使用 OAuth，客户端只需要配置 MCP 地址：

https://data-agent.example.com/api/mcp

首次连接时，兼容 MCP OAuth 的客户端会自动发现 Data Agent 的授权服务，打开浏览器完成登录和授权。Data Agent 使用 mcp offline_access 权限范围，客户端可以在授权后刷新访问令牌。

使用 Bearer Token

如果客户端不支持 MCP OAuth，但允许为远程 MCP 请求配置 Header，可以使用 Data Agent 用户 Token：

{
  "mcpServers": {
    "data-agent": {
      "url": "https://data-agent.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <USER_JWT_TOKEN>",
        "X-SPACES": "default"
      }
    }
  }
}

不同客户端的远程 MCP 配置格式可能不同，请以客户端文档为准。Header 的含义如下：

Header	是否必需	说明
`Authorization`	是	Data Agent 用户 JWT Token。
`X-SPACES`	建议配置	指定默认业务空间，例如 `default`。也可以在调用工具时通过 `spaceName` 指定。
`X-ROLE`	否	多角色用户需要固定使用某个角色时配置。
`X-TIMEZONE`	否	指定时区，例如 `Asia/Shanghai`。

用户 Token 的签发方式请参考 JWT Token 生成。不要把管理员 API key 直接交给外部 Agent，也不要把 Token 提交到代码仓库。

`ask_data` 工具

MCP Server 当前提供一个工具：

工具	作用
`ask_data`	将自然语言业务问题交给 Nora，返回精简的数据查询和分析结果。

工具参数：

参数	类型	是否必需	说明
`question`	string	是	要查询的自然语言业务问题。
`spaceName`	string	否	Data Agent 空间名称。未填写时使用当前请求中的空间。

调用参数示例：

{
  "question": "本月各区域销售额是多少？",
  "spaceName": "default"
}

MCP 调用沿用授权用户在 Data Agent 中的权限。用户在 Data Agent 页面中看不到的数据，也不应通过 MCP 查询到。为不同人员接入时，应让每个人使用自己的 OAuth 授权，不要多人共享同一个高权限 Token。

验证服务端点

可以在部署机器或能够访问 Data Agent 的终端中发送一个未登录的初始化请求：

curl -i 'https://data-agent.example.com/api/mcp' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Referer: https://data-agent.example.com/' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {
        "name": "mcp-connectivity-check",
        "version": "1.0.0"
      }
    }
  }'

启用了 OAuth 时，未登录请求应返回 401 Unauthorized，并在 WWW-Authenticate 响应头中给出 OAuth 资源元数据地址。这说明网络、路由和 OAuth 发现入口已经生效。404 通常表示 MCP 插件未启用或反向代理没有转发该路径。

常见问题

WorkBuddy 一直停留在连接中

依次检查：

MCP 地址是否使用完整的公网 HTTPS 地址，并以 /api/mcp 结尾。
YiAsk：MCP 服务器 和 IdP: OAuth 是否已经启用。
反向代理是否转发了 /api/mcp、/api/.well-known/ 和 OAuth 授权相关路径。
Data Agent 的对外域名和协议是否识别正确。多层代理场景应正确传递 Host、X-Forwarded-Host 和 X-Forwarded-Proto。
浏览器是否拦截了授权窗口。

授权成功但看不到 `ask_data`

确认启用的是 YiAsk：MCP 服务器，而不是占用相同路径的其他 MCP 插件。断开连接器后重新连接，让客户端重新拉取工具列表。

调用工具后返回 401 或 403

401：登录状态或访问令牌无效，重新授权或更换有效的用户 Token。
403：当前用户、角色或空间没有相应权限。先用同一用户登录 Data Agent，在系统内验证该问题是否可以正常查询。

提示空间不存在或查询不到目标数据

检查 spaceName 或 X-SPACES 是否与 Data Agent 中的空间名称完全一致，并确认授权用户已加入该空间。OAuth 接入通常会沿用用户的默认空间；存在多个空间时，建议在问题对应的 Agent 配置中明确空间名称。

返回许可证域名错误

将 YIASK_MCP_ORIGIN 配置为许可证登记的公网地址并重启 Data Agent。该值只包含协议和域名，例如 https://data-agent.example.com。

如何查看 OAuth 接入日志

MCP OAuth 诊断日志默认开启，日志前缀为：

[yiask-mcp][oauth]

日志会记录发现、客户端注册、授权、Token 交换和 MCP 请求等阶段，但不会记录密码、Token、客户端密钥或工具参数。问题排查完成后如需关闭，可配置：

YIASK_MCP_OAUTH_DIAGNOSTICS=false

修改后重启 Data Agent。

#将 Data Agent 接入外部 Agent（MCP Server）

#接入流程

#前置条件

#在 Data Agent 中启用 MCP Server

#配置许可证域名

#在 WorkBuddy 中接入

#验证问数

#接入其他 Agent 软件

#使用 Bearer Token

#ask_data 工具

#验证服务端点

#常见问题

#WorkBuddy 一直停留在连接中

#授权成功但看不到 ask_data

#调用工具后返回 401 或 403

#提示空间不存在或查询不到目标数据

#返回许可证域名错误

#如何查看 OAuth 接入日志