使用本機模型內容通訊協定（MCP）伺服器將 AI 代理程式連線至 GraphQL 的網狀架構 API

想像一下，請 GitHub Copilot 「顯示上一季的所有銷售」，它會自動查詢你的 Fabric 資料倉儲、理解結構並回傳結果——這一切都不需要寫一行 GraphQL。這個教學會教你如何實現這個目標。

在這個教學中，你要建置一台本地的 GraphQL MCP 伺服器，作為 AI 代理與 Microsoft Fabric 資料之間的橋樑。最後，你擁有一台可用的開發伺服器，讓像 GitHub Copilot、Claude 等 AI 助理能自然地用對話式語言查詢你的 Fabric 資料。

您將完成什麼：

設定認證，讓你的 GraphQL MCP 伺服器能安全存取 Fabric
啟用結構內省，讓 AI 代理能自動發現你的資料結構
部署本地 GraphQL MCP 伺服器，將自然語言轉換成 GraphQL 查詢
連接 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網狀架構數據的理想選擇。

為什麼 GraphQL 非常適合 MCP

GraphQL 非常適合 MCP 整合，因為：

架構反省：AI 代理程式可以直接從 GraphQL 架構自動探索可用的數據結構和關聯性
彈性查詢：代理程式可以在單一要求中確切要求所需的數據
類型安全：強型別有助於 AI 智能體理解資料格式和限制條件
有效率的數據擷取：減少數據的過度擷取和擷取不足

Microsoft Fabric 的 GraphQL API 讓您能透過標準化的 GraphQL 介面，輕鬆將您的 Fabric 湖屋、資料倉儲和資料庫暴露給 AI 代理。雖然適用於 GraphQL 的 API 已經提供強大的查詢功能，但為 AI 代理程式設定連線可能不像它那麼簡單。

透過簡單的本地 GraphQL MCP 伺服器，開發者可利用 AI 代理發現他們的 Fabric 資料結構，了解可用資料，並透過標準化的 MCP 介面以自然語言查詢。方便的是，你不需要在伺服器中為每個 GraphQL 類型、查詢或變異定義獨立的 MCP 工具。 GraphQL MCP 伺服器內省 GraphQL 架構，讓 AI 代理從一開始就能理解所有可用的類型與操作。

先決條件

開始本教學課程之前，請確定您有：

一個擁有適當權限的 Microsoft Fabric 工作空間。需要一個工作區管理員角色來設定服務主體並啟用內省功能。
一個用於建立與設定的 GraphQL 項目的 API。請參閱建立並新增資料到 GraphQL 的 API 或在 Fabric 入口網站中從 SQL 資料庫建立 GraphQL API。
Node.js 安裝在你的開發機器上（包含 NPM）
安裝在你的開發機器上的 Visual Studio Code

備註

不是管理員？ 本教學中的某些步驟需要管理員權限。如果你不是管理員，也可以請管理員幫忙完成大部分教學。每個需要管理員權限的步驟都會清楚標示。

步驟 1：設定服務主體存取

你正在做的事情： 設定非互動式的認證憑證，讓你的 GraphQL MCP 伺服器能存取 Fabric，而不需要每次都讓使用者登入。

為什麼這很重要： GraphQL MCP 伺服器作為背景服務執行，AI 代理會自動呼叫。它需要自己的身份（服務主體）和憑證，才能代表你的應用程式向 Fabric 認證，而不是代表特定使用者。

請遵循使用 Service Principals with Fabric API for GraphQL 的完整指南來：

建立 Azure 應用程式註冊（任何有權限在 Microsoft Entra ID 中建立應用程式註冊的使用者）
在 憑證與秘密 （任何使用者）下新增客戶端秘密
在租戶設定中啟用服務主體（需要 Fabric 租戶管理員）
授予你的 GraphQL API 和工作區權限（需要工作區管理員或貢獻者角色）

小提示

不是管理員？ 你可以自己完成前兩項。在租戶設定中，請你的 Fabric 租戶管理員在管理入口>租戶設定>開發者設定中啟用「服務主體可以使用 Fabric API」。關於工作區權限，請你的工作區管理員授權你的服務主體存取工作區或特定的 GraphQL API。

完成設定後，擷取 GraphQL MCP 伺服器配置的這三個數值：

租戶 ID：在 Microsoft Entra ID 的「概覽>租戶 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 租使用者識別碼
MICROSOFT_FABRIC_CLIENT_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`

目的：針對您的網狀架構數據執行 GraphQL 查詢
參數：
- query （必要）：GraphQL 查詢字串
- variables （選擇性）：GraphQL 變數物件
使用方式：針對所有數據擷取和操作

瞭解工作流程

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

架構發現：AI 代理必須先呼叫工具 introspect-schema 以了解架構及可用資料
查詢規劃：代理會分析你的自然語言請求與 GraphQL 架構
查詢產生：代理程式會建立適當的 GraphQL 查詢
執行：代理程式呼叫 query-graphql 工具並產生查詢
回應處理：代理程式會格式化並呈現結果

步驟 4：測試 GraphQL MCP 伺服器

你正在做的事情： 驗證你的 MCP 伺服器能向 Fabric 認證、取得你的結構並執行查詢——在連接 AI 代理之前。

為什麼這很重要： 手動測試確保一切配置正確。如果這些測試通過，你就知道 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 代理（像是 GitHub Copilot）現在可以：

自動發現 Fabric 工作區中可用的資料
根據自然語言問題產生正確的 GraphQL 查詢
在不寫查詢程式碼的情況下，擷取並格式化結果

此本地伺服器旨在開發與學習。以下章節將涵蓋生產部署的重要考量及常見的故障排除情境。

安全性考慮

根據本教學的說明，本地的 GraphQL MCP 伺服器應僅用於開發目的。該伺服器以 HTTP 傳輸實作，使得作為更複雜的客戶端-伺服器或網頁整合的起始點變得更加容易。如果你在生產環境中部署 GraphQL MCP 伺服器：

使用 Azure Key Vault 來儲存秘密，而不是使用 .env 檔案。
實施適當的授權、網路安全與防火牆規則
啟用所有 GraphQL 查詢的稽核記錄
使用 Azure App Service 或容器實例進行裝載
實作 MCP 端點的速率限制和驗證
定期輪替用戶端秘密和憑證

故障排除

常見問題和解決方案

驗證錯誤

確認您的 Azure 應用程式註冊具有正確的許可權
檢查您的 Fabric 租戶中是否已啟用服務主體
確保你的客戶秘密沒有過期

架構反省失敗

確認您在 GraphQL API 設定中已啟用內省
檢查 GraphQL 端點 URL 是否正確
驗證網路連線至您的 Fabric 工作區

AI 代理程式無法辨識工具

在設定變更之後重新啟動您的 AI 用戶端
確認 MCP 伺服器 URL 可存取
檢查伺服器記錄是否有任何錯誤訊息

查詢執行錯誤

檢閱伺服器控制台中記錄的查詢和錯誤
確定您的查詢符合可用的架構
檢查您是否具有要求數據的適當許可權

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-21

共用方式為

使用本機模型內容通訊協定 （MCP） 伺服器將 AI 代理程式連線至 GraphQL 的網狀架構 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

你所建造的

安全性考慮

故障排除

常見問題和解決方案

相關內容

意見反應

其他資源

使用本機模型內容通訊協定（MCP）伺服器將 AI 代理程式連線至 GraphQL 的網狀架構 API

什麼是模型內容通訊協定（MCP）？

`introspect-schema`

`query-graphql`