使用本地模型上下文协议（MCP）服务器将 AI 代理连接到 GraphQL 的 Fabric API

试想一下问 GitHub Copilot “显示上季度的所有销售额”，并让它自动查询 Fabric 数据仓库、理解架构并返回结果——所有这些操作都无需编写一行 GraphQL。本教程介绍如何使这一点成为可能。

在本教程中，你将生成一个本地 GraphQL MCP 服务器，该服务器充当 AI 代理与 Microsoft Fabric 数据之间的桥梁。最后，你有一个工作开发服务器，使 AI 助手（如 GitHub Copilot、Claude 和其他 AI 代理）能够自然地使用对话语言查询 Fabric 数据。

你将完成的工作：

设置身份验证，使 GraphQL MCP 服务器能够安全地访问 Fabric
启用模式内省，以便 AI 代理可以自动发现数据结构
部署将自然语言翻译成 GraphQL 查询的本地 GraphQL MCP 服务器
连接 GitHub Copilot 或其他 AI 工具以对话方式查询数据

什么是模型上下文协议（MCP）？

模型上下文协议（MCP）是将 AI 助手连接到数据所在的系统（包括内容存储库、业务工具和开发环境）的标准。其目标是帮助前沿模型产生更好的、更相关的反应。将 MCP 视为 AI 应用程序的 USB-C 端口。正如 USB-C 提供了将设备连接到各种外围设备和配件的标准化方法一样，MCP 提供了一种标准化的方法，用于将 AI 模型连接到外部数据源和工具。

包括 OpenAI、Microsoft Copilot Studio 和 Microsoft Foundry 的主要 AI 平台采用 MCP 作为将 AI 代理与外部系统集成的标准方法。这使得 MCP 成为将 AI 代理连接到 Microsoft Fabric 数据的理想选择。

为什么 GraphQL 非常适合 MCP

GraphQL 非常适合 MCP 集成，因为：

架构反省：AI 代理可以直接从 GraphQL 架构自动发现可用的数据结构和关系
灵活的查询：代理可以准确请求单个请求中所需的数据
类型安全性：强键入可帮助 AI 代理了解数据格式和约束
高效的数据提取：减少过度提取和提取数据不足

Microsoft Fabric 的 GraphQL API 能轻松通过标准化 GraphQL 接口向 AI 代理公开 Fabric 湖区、数据仓库和数据库。虽然适用于 GraphQL 的 API 已经提供强大的查询功能，但为 AI 代理设置连接可能不像它那么简单。

使用简单的本地 GraphQL MCP 服务器，开发人员可以使用 AI 代理来发现其 Fabric 数据结构、了解可用内容，以及使用自然语言对其进行查询- 全部通过标准化 MCP 接口进行查询。方便地，无需在服务器中为每个 GraphQL 类型、查询或突变定义单独的 MCP 工具。 GraphQL MCP 服务器对 GraphQL 架构进行自省，使 AI 代理能够从一开始了解所有可用的类型和操作。

先决条件

在开始本教程之前，请确保具备：

具有适当权限的 Microsoft Fabric 工作区。需要工作区管理员角色来配置服务主体并启用反省。
创建和配置用于 GraphQL 项目的 API。请参阅在 Fabric 门户中从 SQL 数据库创建数据并将其添加到 GraphQL API 或创建 GraphQL API。
Node.js 安装在开发计算机上（包括 npm）
在您的开发计算机上安装了Visual Studio Code

注释

不是管理员？ 本教程中的一些步骤需要管理员权限。如果你不是管理员，你仍可以通过要求管理员帮助完成特定任务来完成大部分教程。需要管理员权限的每个步骤都会明确标记。

步骤 1：配置服务主体访问

正在执行的作业： 设置非交互式身份验证凭据，以便 GraphQL MCP 服务器可以访问 Fabric，而不需要用户每次登录。

为什么这很重要： GraphQL MCP 服务器作为 AI 代理自动调用的后台服务运行。它需要自己的标识（服务主体）和凭据才能代表应用程序向 Fabric 进行身份验证，而不是代表特定用户进行身份验证。

请按照使用服务主体与 Fabric API 和 GraphQL 的完整指南：

创建 Azure 应用注册（有权在 Microsoft Entra ID 中创建应用注册的任何用户）
在 “证书和机密 ”下添加客户端密码（任何用户）
在租户设置中启用服务主体（需要 Fabric 租户管理员）
向 GraphQL API 和工作区授予权限（需要工作区管理员或参与者角色）

小窍门

不是管理员？ 可以自行完成前两个项目。对于租户设置，请让 Fabric 租户管理员在管理门户>租户设置>下启用“服务主体可以使用 Fabric API”。对于工作区权限，请让工作区管理员向服务主体授予对工作区或特定 GraphQL API 的访问权限。

完成设置后，捕获 GraphQL MCP 服务器配置的这三个值：

租户 ID：在概述>租户 ID 下的 Microsoft Entra ID 中找到
客户端 ID：在“概述>应用程序”（客户端）ID 下的应用注册中找到
客户端密码：创建新客户端密码时显示的机密值（立即复制 —仅显示一次）

步骤 2：启用 GraphQL 内省（这需要工作区管理员权限）

您正在执行的操作： 启用内省允许 GraphQL MCP 服务器询问 GraphQL API“有哪些数据可用？”，并接收有关所有可用类型、字段和关系的完整描述。

为什么这很重要： 这是使自然语言查询成为可能的“神奇”。当你问 Copilot “向我显示客户”时，AI 代理首先使用自省来发现是否存在类型 customers 、它具有哪些字段以及如何对其进行查询。如果不进行反省，则需要手动记录 AI 的整个架构。

重要

必须启用内省，才能使 GraphQL MCP 服务器正常工作。默认情况下，出于安全原因，在 Fabric 中禁用此功能。 只有工作区管理员可以启用内省。 如果你不是管理员，请让工作区管理员完成此步骤。

请参阅 Microsoft Fabric API for GraphQL 内省和模式导出的完整指南以进行操作：

在 API 设置中启用内省
了解自省查询的工作原理
了解架构导出选项

启用反省后，GraphQL MCP 服务器可以查询架构结构，并将其提供给 AI 代理。

步骤 3：设置 GraphQL MCP 服务器

正在执行的作： 安装和配置实现模型上下文协议的本地 Node.js 服务器。此服务器充当 AI 代理和 Fabric GraphQL API 之间的翻译器。

为什么这很重要： MCP 服务器提供 AI 代理理解的标准化接口。当 AI 代理连接时，它可以发现可用的工具（内省和查询）、调用这些工具和接收响应，所有这些工具都无需为每个 AI 平台编写自定义集成代码。

现在你已经获得了身份验证凭据（步骤 1）并启用了自省（步骤 2），现在可以配置服务器以使用它们。

克隆示例存储库

git clone https://github.com/microsoft/fabric-samples.git
cd fabric-samples/docs-samples/data-engineering/GraphQL/MCP

安装依赖项

npm install

配置环境变量

在项目根目录中创建一个.env文件，并加入你的配置：

MICROSOFT_FABRIC_API_URL=https://your-fabric-endpoint/graphql
MICROSOFT_FABRIC_TENANT_ID=your_tenant_id_here
MICROSOFT_FABRIC_CLIENT_ID=your_client_id_here
MICROSOFT_FABRIC_CLIENT_SECRET=your_client_secret_here
SCOPE=https://api.fabric.microsoft.com/.default

将占位符值替换为：

MICROSOFT_FABRIC_API_URL：Fabric 门户中的 GraphQL接口终结点
MICROSOFT_FABRIC_TENANT_ID：您的 Azure 租户 ID
MICROSOFT_FABRIC_CLIENT_ID：应用注册客户端 ID
MICROSOFT_FABRIC_CLIENT_SECRET：应用注册客户端密码

启动 GraphQL MCP 服务器

node FabricGraphQL_MCP.js

服务器在http://localhost:3000启动并显示：

Microsoft Fabric GraphQL MCP server listening on port 3000
API URL: https://your-fabric-endpoint/graphql
Scope: https://api.fabric.microsoft.com/.default

可用的 MCP 工具

GraphQL MCP 服务器提供两个主要工具：

`introspect-schema`

目的：检索完整的 GraphQL 架构
参数：无
用法：在进行查询之前必须先调用

`query-graphql`

目的：针对 Fabric 数据执行 GraphQL 查询
参数：
- query （必需）：GraphQL 查询字符串
- variables （可选）：GraphQL 变量对象
用法：对于所有数据检索和操作操作

了解工作流

典型的 GraphQL MCP 工作流遵循以下模式：

架构发现：AI 代理必须首先调用 introspect-schema 该工具来了解架构和可用数据
查询规划：代理分析自然语言请求和 GraphQL 架构
查询生成：代理创建适当的 GraphQL 查询
执行：代理使用生成的查询调用 query-graphql 工具
响应处理：代理格式并显示结果

步骤 4：测试 GraphQL MCP 服务器

正在执行的作： 在连接 AI 代理之前，验证 MCP 服务器是否可以向 Fabric 进行身份验证、检索架构和执行查询。

为什么这很重要： 手动测试可确保正确配置所有内容。如果这些测试通过，你知道 AI 代理能够在步骤 5 中成功连接。

验证服务器运行状况

首先，确认服务器正在运行，并且可以向 Fabric 进行身份验证。

使用 PowerShell：

Invoke-RestMethod -Uri "http://localhost:3000/health" -Method Get

使用 cURL：

curl http://localhost:3000/health

应收到指示服务器正在运行的响应，如下所示：

{"status":"healthy","server":"Microsoft Fabric GraphQL MCP Server","hasToken":true,"tokenExpiry":"2025-06-30T23:11:36.339Z"}

测试架构反省

接下来，验证服务器是否可以通过内省检索 GraphQL 架构。这会调用 introspect-schema MCP 工具。

使用 PowerShell：

$headers = @{
    "Content-Type" = "application/json"
    "Accept" = "application/json, text/event-stream"
}

$body = @{
    jsonrpc = "2.0"
    id = 1
    method = "tools/call"
    params = @{
        name = "introspect-schema"
        arguments = @{}
    }
} | ConvertTo-Json -Depth 3

Invoke-RestMethod -Uri "http://localhost:3000/mcp" -Method Post -Body $body -Headers $headers

使用 cURL：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "introspect-schema",
      "arguments": {}
    }
  }'

这应返回 GraphQL 架构定义。

测试 GraphQL 查询

最后，测试通过 MCP 服务器执行实际的 GraphQL 查询。此示例使用 query-graphql MCP 工具查询架构中的所有类型名称。

使用 PowerShell：

$headers = @{
    "Content-Type" = "application/json"
    "Accept" = "application/json, text/event-stream"
}

$body = @{
    jsonrpc = "2.0"
    id = 2
    method = "tools/call"
    params = @{
        name = "query-graphql"
        arguments = @{
            query = "query { __schema { types { name } } }"
        }
    }
} | ConvertTo-Json -Depth 4

Invoke-RestMethod -Uri "http://localhost:3000/mcp" -Method Post -Body $body -Headers $headers

使用 cURL：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "query-graphql",
      "arguments": {
        "query": "query { __schema { types { name } } }"
      }
    }
  }'

这会返回 GraphQL 架构中所有类型的列表。

步骤 5：连接 AI 代理

正在执行的作： 将 AI 工具配置为使用本地 MCP 服务器作为数据源。

为什么这很重要： 这就是一切聚集在一起的地方。连接后，AI 代理可以通过反省发现 Fabric 架构，并根据自然语言请求生成 GraphQL 查询。 AI 处理查询语法 - 只需用纯英语提问。

Visual Studio Code 中的 GitHub Copilot

在 VS Code 中安装 GitHub Copilot 扩展

在 Copilot 设置中配置 GraphQL MCP 服务器：

{
  "fabric-graphql": {
    "type": "http",
    "url": "http://localhost:3000/mcp"
  }
}

在 Copilot 聊天中，首先要求反省架构，然后尝试询问与自然语言中反省数据相关的相关问题，例如：

游标 IDE

打开光标设置

添加 MCP 服务器配置：

{
  "fabric-graphql": {
    "type": "http",
    "url": "http://localhost:3000/mcp"
  }
}

在聊天中，首先要求对架构进行反省，然后尝试使用自然语言询问与反省数据相关的相关问题。

你构建的内容

祝贺！你现在有一个运行良好的 GraphQL MCP 服务器，该服务器：

使用服务主体凭据向 Fabric 进行身份验证
通过自省展示 Fabric 数据架构
将 AI 代理请求转换为 GraphQL 查询
以 AI 代理可以理解和呈现的格式返回数据

AI助手（如 GitHub Copilot）现在可以：

自动发现您 Fabric 工作区中的可用数据
根据自然语言问题生成正确的 GraphQL 查询
检索和格式化结果，而无需编写任何查询代码

此本地服务器适用于开发和学习。以下部分介绍生产部署和常见故障排除方案的重要注意事项。

安全注意事项

虽然应仅按照本教程中所述实现本地 GraphQL MCP 服务器以实现开发目的，但它通过 HTTP 传输实现，因此更容易将其用作更复杂的客户端服务器或基于 Web 的集成的起点。如果要在生产环境中部署 GraphQL MCP 服务器：

使用 Azure Key Vault 存储机密而不是 .env 文件
实现适当的授权、网络安全和防火墙规则
为所有 GraphQL 查询启用审核日志记录
使用 Azure 应用服务或容器实例进行托管
为 MCP 终结点实现速率限制和身份验证
定期轮换客户端机密和证书

故障排除

常见问题和解决方案

身份验证错误

验证 Azure 应用注册是否具有正确的权限
检查是否已在 Fabric 租户中启用服务主体
确保客户端机密未过期

架构反省失败

确认在 GraphQL API 设置中启用了自省
检查 GraphQL 终结点 URL 是否正确
验证与 Fabric 工作区的网络连接

AI 代理无法识别工具

配置更改后重启 AI 客户端
验证 MCP 服务器 URL 是否可访问
检查服务器日志中是否有任何错误消息

查询执行错误

查看服务器控制台中记录的查询和错误
确保查询与可用架构匹配
检查你是否对请求的数据具有适当的权限

反馈

此页面是否有帮助？

Last updated on 2026-01-21

通过

使用本地模型上下文协议（MCP）服务器将 AI 代理连接到 GraphQL 的 Fabric API

什么是模型上下文协议（MCP）？

为什么 GraphQL 非常适合 MCP

先决条件

步骤 1：配置服务主体访问

步骤 2：启用 GraphQL 内省（这需要工作区管理员权限）

步骤 3：设置 GraphQL MCP 服务器

克隆示例存储库

安装依赖项

配置环境变量

启动 GraphQL MCP 服务器

可用的 MCP 工具

introspect-schema

query-graphql

了解工作流

步骤 4：测试 GraphQL MCP 服务器

验证服务器运行状况

测试架构反省

测试 GraphQL 查询

步骤 5：连接 AI 代理

Visual Studio Code 中的 GitHub Copilot

游标 IDE

你构建的内容

安全注意事项

故障排除

常见问题和解决方案

相关内容

反馈

其他资源

`introspect-schema`

`query-graphql`