Notebook UCC / ADC / Remote MCP

UCC MCP 工具实现、注册与认证审计

本页追踪 GetSemanticModelSchema、GetReportMetadata、ValueSearch、ExecuteQuery 和 fabric-sqlendpoint-execute_query 的真实服务端实现、MCP 注册、调用路径和认证边界。每项事实均链接到固定 commit 的源码。

结论

0五个工具中在 ADC 容器内部实现的数量。ADC 负责把 bundle 中的 MCP 配置交给 Copilot session。 [E3] [E4]
4个 Power BI 工具由 FabricIQ M365 MCP server 注册，主要逻辑来自 workload-powerbi。 [E11] [E12]
1个 SQL Endpoint 工具由 XDW MCP server 实现，最终通过 TDS 执行 T-SQL。 [E21] [E26]
关键区分： fabric-sqlendpoint-execute_query 是模型侧常见显示名；服务端声明的原始 MCP tool name 是 execute_query。当前可见源码只能证明原始名称，不能证明 prefix 的具体拼接实现。 [E22] [E27]
Notebook UCC
MWC v2 token 调 Copilot workload
[E5]
→
workload-copilot
校验用户上下文，准备 sandbox 和下游 token
[E6] [E7]
→
fabric-adc-agent
把 MCP servers 注入 Copilot SDK session
[E4]
→
Fabric API MCP proxy
egress proxy 注入 Fabric API bearer
[E8] [E9]
→
FabricAIHub / XDW
执行 Power BI metadata/DAX 或 SQL Endpoint/TDS 路径
[E12] [E21]

五个工具：实现、输入和下游

模型可见名称实际实现输入 contract下游和输出源码
GetSemanticModelSchema FabricAIHub 注册 GetSemanticModelSchemaJmesPathTool；wrapper 委派 GetSemanticModelSchemaToolHandler，handler 解析 workspace/model 并读取 enriched schema。 artifactId: GUID
queries?: string[≤5]		 调用 Power BI Explore .../enrichedmetadata；返回模型 schema、custom instructions、verified answers、citation，并支持 JMESPath/大结果摘要。 [E13] [E14]
GetReportMetadata FabricAIHub 注册自己的 JMESPath wrapper；wrapper 委派 Power BI GetReportMetadataToolHandler，handler 通过 report schema cache 组装结果。 reportObjectId: GUID
queries?: string[≤5]		 调用 Power BI Explore .../reportmetadata；返回 workspace、semantic model、pages、visuals、filters 和 citation，并支持 JMESPath/摘要。 [E15] [E16]
ValueSearch ValueSearchTool 解析 report/model 到 semantic model、校验参数，然后调用 ValueSearchToolService；scope 当前在客户端过滤。 artifactId: GUID
searchTerms: string[1..20]
scope?		 调用 Explore .../instanceLookup；返回精确 table/column/value 位置、score 和 citation。 [E17] [E18]
ExecuteQuery ExecuteDaxQueryTool 执行 1–4 条含单个 EVALUATE 的 DAX；根据 flight 选择 Shared Explore API 或 direct AS provider。 artifactId: GUID
daxQueries: string[1..4]
maxRows?: number		 Shared 路径调用 .../executequery；默认 250 行、通常上限 1000 行（large-result flight 可提高上限）。 [E19] [E20]
fabric-sqlendpoint-execute_query
(raw: execute_query)		 XDW SqlEndpointMcpController 接收 MCP POST，ExecuteQueryToolWrapper 校验参数，ExecuteQueryTool 调 SqlEndpointQueryExecutor 通过 TDS 执行。 workspaceId: GUID
itemId: GUID
query: non-empty T-SQL		 默认最多 10,000 行、300 秒；返回 metadata text 和 embedded text/csv resource。 [E21] [E22] [E23] [E24]

如何注册到 UCC

  1. fabric-adc-agent 固定 GitHub Copilot SDK 1.0.0-beta.10 和 Microsoft.Fabric.Copilot.AdcSkills 0.3.12，并把 package 中完整 skills-for-fabric payload 复制到 publish output。 [E1] [E2]
  2. 该 bundle 的 .mcp.json 声明两个 HTTP MCP servers：FabricIQ 指向 FabricAIHub M365 endpoint 并带 X-VARIANTS: Fabric.Routing.PowerBIDataExploration；fabric-sqlendpoint 指向 SQL Endpoint endpoint，并只允许 raw tool execute_query。 [E27]
  3. SkillBundleLoader.LoadMcpServers() 解析 .mcp.json 为 SDK McpServerConfig；缺失、空或解析失败时返回 null，session 将没有 MCP servers。 [E3]
  4. ADC 创建正常 session 或恢复非 ephemeral session 时把结果写入 SessionConfig.McpServers/ResumeSessionConfig.McpServers。 [E4]
  5. FabricIQ 的 routing variant 映射到稳定的 powerbi-data-exploration toolset；该 toolset 明确包含四个 Power BI tools，DI 注册又把每个模型名绑定到对应 tool type。 [E11] [E12]
  6. SQL Endpoint 路径由 XDW 的 MCP controller 接收，并仅为该 controller 注册 MWC-token authenticator；tool wrapper 通过 [McpServerTool(Name="execute_query")] 暴露原始工具。 [E21] [E22] [E25]

认证与用户委托链

跳转入站认证转换/转发源码可证明内容证据
Browser → workload-copilotAuthorization: MwcToken <v2 token> + resource monikerPortal host 先取 user token，再 mint workspace-scoped MWC v2 token。客户端 header 构造和 workload 的 MWC v2 验证均可见。[E5] [E6]
workload-copilot → ADC独立 sandbox ingress bearerworkload 准备 sandbox、刷新 session token，并流式调用 ADC。这是 sandbox 入口凭据，不是下游 Fabric MCP bearer。[E7]
ADC runtime → Fabric API MCP.mcp.json 本身不含静态 Authorization。sandbox egress policy 为 Fabric API /v1/* 请求注入 SecretRef-backed Bearer。original-token 路径调用 Shared OBO；refresh-token 路径明确使用 Power BI resource。[E8] [E9] [E27]
Fabric API → FabricAIHub → Power BIFabricAIHub controller 默认 S2sObo，request context 读取原始用户 AAD context。Power BI client 调用 metadata/query API。controller auth mode、tool implementation 和 API 路径可见；gateway 内部 token exchange 不可见。[E10] [E14] [E16] [E20]
Fabric API → XDW → SQLXDW controller 只注册 MWC authenticator。executor 从 MWC/AAD context 取原始 AAD token，必要时先换到 PBI audience，再 mint SQL-audience MWC token。最终 token 写入 SqlConnection.AccessToken；代码注释明确 SQL audience 为 https://database.windows.net/。[E25] [E26]

证据边界：不能声称的内容

当前可见 GitHub Copilot SDK 源码没有包含 bundled runtime 的 HTTP MCP discovery、tools/list/tools/call transport 或 server-name prefix 拼接实现。因此本文只把 execute_query 视为源码确认的 raw name，把 fabric-sqlendpoint-execute_query 标为模型侧常见名称。 [E4] [E22]
GetOBOAadTokenForSharedAsync 的内部实现和精确 target audience 位于外部平台依赖；不能仅凭方法名推断。可确认的是调用发生，以及 refresh-token 路径使用默认 Power BI resource https://analysis.windows.net/powerbi/api。 [E9]
Fabric API gateway 从外部 Bearer 到 FabricAIHub/XDW 内部 S2S/OBO/MWC token 的具体交换实现不在已读源码中；本文只描述 gateway 两端可见的认证 contract。 [E8] [E10] [E21]
源码 commit 是 2026-08-26 审计时各目标分支的固定快照；没有 deployment manifest 证明这些 commit 与当前生产部署完全一致。若要将置信度提升到生产级，需要一次脱敏 live trace，关联 ADC MCP event、egress rule、Fabric API route 和 FabricAIHub/XDW correlation ID。

源码索引（全部固定到 commit）

  1. [E1] fabric-adc-agent @ a1a8b3847bc818b8aeeaf8a2874cddb3577d947a — Directory.Packages.props:6-10.
  2. [E2] fabric-adc-agent — Microsoft.Fabric.Copilot.AdcAgent.csproj:52-92.
  3. [E3] fabric-adc-agent — SkillBundleLoader.cs:11-103.
  4. [E4] fabric-adc-agent — CopilotAgentService.cs:559-572 and 709-740.
  5. [E5] PowerBIClients @ 18b59a632f08288efb403f430c6c423662c26068 — unified-copilot-pane.module.ts:53-95 and copilot-api.service.ts:213-230.
  6. [E6] workload-copilot @ 4036c75691e5834c3336e188411b42666d50c193 — MessagesController.cs:32-75 and CopilotMwcTokenV2AadAuthenticator.cs:20-58.
  7. [E7] workload-copilot — MessagesService.cs:143-192 and IngressProxyAuthHandler.cs:17-51.
  8. [E8] workload-copilot — EgressPolicyRulesProvider.cs:779-845.
  9. [E9] workload-copilot — AadTokenProvider.cs:145-215 and AdcSandboxOptions.cs:319-333.
  10. [E10] workload-fabricaihub @ 721c41560c6e7b7dae0b4dccb596b9cc2b5e30f6 — M365McpServerController.cs:22-115.
  11. [E11] workload-fabricaihub — M365McpServerConfig.cs:125-163 and 318-330.
  12. [E12] workload-fabricaihub — M365McpServerDependencies.cs:777-812.
  13. [E13] workload-powerbi @ 645d7f529326f5416cec97ebf1694bd0eca8650d — GetSemanticModelSchemaJmesPathTool.cs:14-65.
  14. [E14] workload-powerbi — GetSemanticModelSchemaToolHandler.cs:146-200 and EnrichedModelSchemaCache.cs:286-304.
  15. [E15] workload-fabricaihub — GetReportMetadataJmesPathTool.cs:14-65.
  16. [E16] workload-powerbi — GetReportMetadataToolHandler.cs:105-226 and ReportSchemaCache.cs:224-236.
  17. [E17] workload-powerbi — ValueSearchTool.cs:25-160.
  18. [E18] workload-powerbi — ValueSearchToolService.cs:177-207.
  19. [E19] workload-powerbi — ExecuteDaxQueryTool.cs:40-155.
  20. [E20] workload-powerbi — ExecuteDaxQueryToolService.cs:20-105.
  21. [E21] workload-xdw @ 16169febb6bd73fe9ea9b6be540e8e0d6f4dca92 — SqlEndpointMcpController.cs:31-170.
  22. [E22] workload-xdw — ExecuteQueryToolWrapper.cs:20-88.
  23. [E23] workload-xdw — ExecuteQueryOptions.cs:12-22 and ExecuteQueryTool.cs:42-187.
  24. [E24] workload-xdw — McpToolResponseHelper.cs:24-120.
  25. [E25] workload-xdw — ControllerAuthenticatorsMap.cs:31-54.
  26. [E26] workload-xdw — SqlEndpointQueryExecutor.cs:82-94 and 240-394.
  27. [E27] skills-for-fabric @ 3c8a1805061e97ca13ba5ddc773dcb9cbc83aa8e / AdcSkills 0.3.12 — .mcp.json and sqldw-cli/SKILL.md.