Verbinden von AI-Agents mit der Fabric-API für GraphQL mit einem lokalen MCP-Server (Model Context Protocol)

Stellen Sie sich vor, GitHub Copilot "Alle Verkäufe aus dem letzten Quartal anzeigen" zu fragen und ihr Fabric-Data Warehouse automatisch abfragen zu lassen, das Schema zu verstehen und Ergebnisse zurückzugeben – alles, ohne eine einzelne Zeile von GraphQL zu schreiben. In diesem Lernprogramm erfahren Sie, wie Sie dies ermöglichen.

In diesem Lernprogramm erstellen Sie einen lokalen GraphQL MCP-Server, der als Brücke zwischen KI-Agents und Ihren Microsoft Fabric-Daten fungiert. Am Ende verfügen Sie über einen funktionierenden Entwicklungsserver, der KI-Assistenten wie GitHub Copilot, Claude und andere KI-Agents ermöglicht, Ihre Fabric-Daten natürlich mithilfe von Unterhaltungssprache abzufragen.

Umfang:

Einrichten der Authentifizierung, damit Ihr GraphQL MCP-Server sicher auf Fabric zugreifen kann
Aktivieren der Schemaintrospektion, damit KI-Agents Ihre Datenstruktur automatisch ermitteln können
Bereitstellen eines lokalen GraphQL MCP-Servers, der natürliche Sprache in GraphQL-Abfragen übersetzt
Verbinden Sie GitHub Copilot oder andere KI-Tools, um Ihre Daten interaktiv abzufragen.

Was ist das Model Context Protocol (MCP)?

Das Model Context Protocol (MCP) ist ein Standard zum Verbinden von KI-Assistenten mit den Systemen, in denen Daten leben, einschließlich Inhaltsrepositorys, Geschäftstools und Entwicklungsumgebungen. Ziel ist es, Grenzmodelle dabei zu unterstützen, bessere, relevantere Antworten zu liefern. Stellen Sie sich MCP wie einen USB-C Port für KI-Anwendungen vor. Wie USB-C eine standardisierte Möglichkeit zum Verbinden Ihrer Geräte mit verschiedenen Peripheriegeräten und Zubehör bietet, bietet MCP eine standardisierte Möglichkeit, KI-Modelle mit externen Datenquellen und Tools zu verbinden.

Wichtige KI-Plattformen wie OpenAI, Microsoft Copilot Studio und Microsoft Foundry haben MCP als Standardmethode zur Integration von KI-Agents in externe Systeme eingeführt. Dies macht MCP zu einer idealen Wahl, um KI-Agents mit Ihren Microsoft Fabric-Daten zu verbinden.

Warum GraphQL ideal für MCP ist

GraphQL eignet sich gut für MCP-Integrationen, da:

Schemaintrospektion: KI-Agents können automatisch verfügbare Datenstrukturen und Beziehungen direkt aus dem GraphQL-Schema ermitteln.
Flexible Abfragen: Agents können genau die Daten anfordern, die sie in einer einzigen Anforderung benötigen.
Typsicherheit: Eine starke Typisierung hilft KI-Agents, Datenformate und Einschränkungen zu verstehen
Effizientes Abrufen von Daten: Reduziert Überabfrage und Unterabfrage von Daten.

Die API von Microsoft Fabric für GraphQL erleichtert das Verfügbarmachen Ihrer Fabric Lakehouses, Data Warehouses und Datenbanken für KI-Agents über eine standardisierte GraphQL-Schnittstelle. Die API für GraphQL bietet zwar bereits leistungsstarke Abfragefunktionen, aber das Einrichten einer Verbindung für KI-Agents ist möglicherweise nicht so einfach wie möglich.

Mit einem einfachen lokalen GraphQL MCP-Server können Entwickler KI-Agents verwenden, um ihre Fabric-Datenstruktur zu ermitteln, zu verstehen, was verfügbar ist, und sie mithilfe natürlicher Sprache abzufragen – alles über die standardisierte MCP-Schnittstelle. Praktischerweise müssen Sie kein separates MCP-Tool auf dem Server für jeden GraphQL-Typ, jede Abfrage oder jede Mutation definieren. Der GraphQL-MCP-Server untersucht das GraphQL-Schema und ermöglicht es KI-Agenten, von Anfang an alle verfügbaren Typen und Operationen zu verstehen.

Voraussetzungen

Bevor Sie mit diesem Lernprogramm beginnen, stellen Sie sicher, dass Sie folgendes haben:

Ein Microsoft Fabric-Arbeitsbereich mit entsprechenden Berechtigungen. Eine Arbeitsbereichsadministratorrolle ist erforderlich, um Dienstprinzipale zu konfigurieren und die Introspektion zu aktivieren.
Eine API für graphQL-Element erstellt und konfiguriert. Siehe Erstellen und Hinzufügen von Daten zu einer API für GraphQL oder Zum Erstellen von GraphQL-API aus Ihrer SQL-Datenbank im Fabric-Portal.
Node.js auf Ihrem Entwicklungscomputer installiert (einschließlich npm)
Visual Studio Code auf Dem Entwicklungscomputer installiert

Hinweis

Kein Administrator? Einige Schritte in diesem Lernprogramm erfordern Administratorberechtigungen. Wenn Sie kein Administrator sind, können Sie den Großteil des Lernprogramms weiterhin ausführen, indem Sie Ihren Administrator bitten, bestimmte Aufgaben zu unterstützen. Jeder Schritt, der Administratorberechtigungen erfordert, ist eindeutig gekennzeichnet.

Schritt 1: Konfigurieren des Dienstprinzipalzugriffs

Was Sie tun: Einrichten nicht interaktiver Authentifizierungsanmeldeinformationen, damit Ihr GraphQL MCP-Server auf Fabric zugreifen kann, ohne dass sich ein Benutzer jedes Mal anmelden muss.

Warum dies wichtig ist: Der GraphQL MCP-Server wird als Hintergrunddienst ausgeführt, den KI-Agents automatisch aufrufen. Sie benötigt eine eigene Identität (einen Dienstprinzipal) mit Anmeldeinformationen, um sich im Auftrag Ihrer Anwendung bei Fabric zu authentifizieren, nicht im Auftrag eines bestimmten Benutzers.

Befolgen Sie den vollständigen Leitfaden für die Nutzung von Service Principals mit der Fabric-API für GraphQL, um:

Erstellen einer Azure-App-Registrierung (jeder Benutzer mit Berechtigungen zum Erstellen von App-Registrierungen in Microsoft Entra ID)
Hinzufügen eines geheimen Clientschlüssels unter Zertifikaten und geheimen Schlüsseln (beliebiger Benutzer)
Aktivieren von Dienstprinzipalen in Ihren Mandanteneinstellungen (erfordert Fabric-Mandantenadministrator)
Erteilen von Berechtigungen für Ihre GraphQL-API und Ihren Arbeitsbereich (erfordert Arbeitsbereichsadministrator oder Mitwirkenderolle)

Tipp

Kein Administrator? Sie können die ersten beiden Elemente selbst abschließen. Bitten Sie Ihren Fabric-Mandantenadministrator, für die Mandanteneinstellung "Dienstprinzipale können Fabric-APIs verwenden" unter denEntwicklereinstellungen> des Verwaltungsportals> zu aktivieren. Um Berechtigungen für den Arbeitsbereich zu erhalten, bitten Sie den Administrator des Arbeitsbereichs, Ihrem Dienstprinzipal Zugriff auf den Arbeitsbereich oder die spezifische GraphQL-API zu gewähren.

Erfassen Sie beim Abschließen des Setups diese drei Werte für die GraphQL MCP-Serverkonfiguration:

Mandanten-ID: In Microsoft Entra ID unter Übersicht>Mandanten-ID gefunden
Client-ID: In Ihrer App-Registrierung unter Übersicht>Anwendungs-ID (Client-ID) gefunden
Geheimer Clientschlüssel: Der geheime Wert, der angezeigt wird, wenn Sie einen neuen geheimen Clientschlüssel erstellen (sofort kopieren – es wird nur einmal angezeigt)

Schritt 2: Aktivieren der GraphQL-Introspection (erfordert Arbeitsbereichsadministrator)

Was Sie tun: Durch aktivieren der Introspektion kann der GraphQL-MCP-Server Ihre GraphQL-API "Welche Daten haben Sie?" fragen und eine vollständige Beschreibung aller verfügbaren Typen, Felder und Beziehungen erhalten.

Warum dies wichtig ist: Dies ist die "Magie", die natürliche Sprachabfragen möglich macht. Wenn Sie Copilot fragen: "Kunden anzeigen", verwendet der KI-Agent zunächst die Introspektion, um zu ermitteln, dass ein customers-Typ existiert, welche Felder es hat und wie es abgefragt werden kann. Ohne Introspektion müssen Sie Ihr gesamtes Schema für die KI manuell dokumentieren.

Von Bedeutung

Die Introspektion muss aktiviert sein, damit der GraphQL-MCP-Server funktioniert. Dies ist aus Sicherheitsgründen standardmäßig in Fabric deaktiviert. Nur Arbeitsbereichsadministratoren können die Introspection aktivieren. Wenn Sie kein Administrator sind, bitten Sie Ihren Arbeitsbereichsadministrator, diesen Schritt abzuschließen.

Folgen Sie dem vollständigen Leitfaden unter Microsoft Fabric API für GraphQL-Introspektion und Schemaexport, um zu:

Aktivieren Sie die Selbstprüfung in Ihren API-Einstellungen
Verstehen, wie Introspection-Abfragen funktionieren
Informationen zu Schemaexportoptionen

Sobald die Introspection aktiviert ist, kann der GraphQL MCP-Server Ihre Schemastruktur abfragen und für KI-Agents verfügbar machen.

Schritt 3: Einrichten des GraphQL MCP-Servers

Was Sie tun: Installieren und Konfigurieren eines lokalen Node.js-Servers, der das Modellkontextprotokoll implementiert. Dieser Server fungiert als Übersetzer zwischen KI-Agents und Ihrer Fabric GraphQL-API.

Warum dies wichtig ist: Der MCP-Server bietet eine standardisierte Schnittstelle, die KI-Agents verstehen. Wenn ein KI-Agent eine Verbindung herstellt, kann er ermitteln, welche Tools verfügbar sind (Introspection und Abfrage), diese Tools aufrufen und Antworten empfangen – alles, ohne dass Sie benutzerdefinierten Integrationscode für jede KI-Plattform schreiben.

Nachdem Sie nun Authentifizierungsanmeldeinformationen (Schritt 1) und Introspektion (Schritt 2) aktiviert haben, können Sie den Server konfigurieren, um diese zu verwenden.

Klonen des Beispiel-Repositorys

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

Installieren von Abhängigkeiten

npm install

Konfigurieren von Umgebungsvariablen

Erstellen Sie eine .env Datei im Projektstamm mit Ihrer Konfiguration:

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

Ersetzen Sie die Platzhalterwerte durch:

MICROSOFT_FABRIC_API_URL: Ihr GraphQL-Endpunkt aus dem Fabric-Portal
MICROSOFT_FABRIC_TENANT_ID: Ihre Azure-Mandanten-ID
MICROSOFT_FABRIC_CLIENT_ID: Ihre Client-ID für die App-Registrierung
MICROSOFT_FABRIC_CLIENT_SECRET: Geheimer Clientschlüssel für die App-Registrierung

Starten des GraphQL MCP-Servers

node FabricGraphQL_MCP.js

Der Server startet auf http://localhost:3000 und zeigt an:

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

Verfügbare MCP-Tools

Der GraphQL MCP-Server bietet zwei Haupttools:

`introspect-schema`

Zweck: Ruft das vollständige GraphQL-Schema ab
Parameter: Keiner
Verwendung: Muss zuerst aufgerufen werden, bevor Abfragen ausgeführt werden

`query-graphql`

Zweck: Führt GraphQL-Abfragen für Ihre Fabric-Daten aus
Parameter:
- query (erforderlich): Die GraphQL-Abfragezeichenfolge
- variables (optional): GraphQL-Variablenobjekt
Verwendung: Für alle Datenabruf- und Manipulationsvorgänge

Grundlegendes zum Workflow

Der typische GraphQL MCP-Workflow folgt diesem Muster:

Schemaermittlung: DER KI-Agent muss zuerst das introspect-schema Tool aufrufen, um das Schema und die verfügbaren Daten zu verstehen.
Abfrageplanung: Agent analysiert Ihre Anforderung in natürlicher Sprache und das GraphQL-Schema
Abfragegenerierung: Der Agent erstellt geeignete GraphQL-Abfragen
Ausführung: Agent ruft das query-graphql Tool mit den generierten Abfragen auf.
Antwortverarbeitung: Agent formatiert und präsentiert die Ergebnisse

Schritt 4: Testen des GraphQL MCP-Servers

Was Sie tun: Stellen Sie sicher, dass sich Ihr MCP-Server bei Fabric authentifizieren, Ihr Schema abrufen und Abfragen ausführen kann, bevor KI-Agents verbunden werden.

Warum dies wichtig ist: Durch manuelles Testen wird sichergestellt, dass alles ordnungsgemäß konfiguriert ist. Wenn diese Tests bestehen, wissen Sie, dass die KI-Agents in Schritt 5 erfolgreich eine Verbindung herstellen können.

Überprüfen der Serverintegrität

Vergewissern Sie sich zunächst, dass der Server ausgeführt wird und sich bei Fabric authentifizieren kann.

Verwenden von PowerShell:

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

Verwenden von cURL:

curl http://localhost:3000/health

Sie sollten eine Antwort erhalten, die angibt, dass der Server läuft, ähnlich wie:

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

Testen der Schemaintrospektion

Überprüfen Sie als Nächstes, ob der Server Ihr GraphQL-Schema über Introspektion abrufen kann. Dadurch wird das introspect-schema MCP-Tool aufgerufen.

Verwenden von 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

Verwenden von 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": {}
    }
  }'

Dadurch sollte Ihre GraphQL-Schemadefinition zurückgegeben werden.

Testen einer GraphQL-Abfrage

Testen Sie schließlich die Ausführung einer tatsächlichen GraphQL-Abfrage über den MCP-Server. In diesem Beispiel wird mithilfe des query-graphql MCP-Tools nach allen Typnamen in Ihrem Schema gesucht.

Verwenden von 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

Verwenden von 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 } } }"
      }
    }
  }'

Dadurch wird eine Liste aller Typen im GraphQL-Schema zurückgegeben.

Schritt 5: Verbinden von KI-Agents

Was Sie tun: Konfigurieren von KI-Tools für die Verwendung Ihres lokalen MCP-Servers als Datenquelle.

Warum dies wichtig ist: Hier kommt alles zusammen. Nach der Verbindung können Ihre KI-Agents Ihr Fabric-Schema über die Introspection ermitteln und GraphQL-Abfragen basierend auf Anforderungen in natürlicher Sprache generieren. Die KI behandelt die Abfragesyntax – Sie stellen nur Fragen in einfachem Englisch.

GitHub Copilot in Visual Studio Code

Installieren der GitHub Copilot-Erweiterung in VS Code

Konfigurieren Sie den GraphQL MCP-Server in Ihren Copilot-Einstellungen:

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

Bitten Sie im Copilot-Chat zunächst um die Überprüfung des Schemas und versuchen Sie dann, eine relevante Frage im Zusammenhang mit den überprüften Daten in natürlicher Sprache zu stellen, z. B.:

Cursor-IDE

Cursoreinstellungen öffnen

Fügen Sie die MCP-Serverkonfiguration hinzu:

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

Bitten Sie im Chat zuerst darum, das Schema zu untersuchen, und versuchen Sie dann, eine relevante Frage zu den untersuchten Daten in natürlicher Sprache zu stellen.

Was Sie erstellt haben

Glückwunsch! Sie verfügen jetzt über einen funktionierenden GraphQL MCP-Server, der:

Authentifiziert sich bei Fabric mithilfe von Dienstprinzipal- und Anmeldeinformationen.
Macht Ihr Fabric-Datenschema über die Introspection verfügbar
Übersetzt KI-Agent-Anforderungen in GraphQL-Abfragen
Gibt Daten in einem Format zurück, das KI-Agents verstehen und präsentieren können

Ihre KI-Agents (wie GitHub Copilot) können jetzt:

Automatisches Ermitteln, welche Daten in Ihrem Fabric-Arbeitsbereich verfügbar sind
Generieren von korrekten GraphQL-Abfragen basierend auf Fragen in natürlicher Sprache
Abrufen und Formatieren von Ergebnissen ohne Schreiben von Abfragecode

Dieser lokale Server ist für die Entwicklung und das Lernen vorgesehen. In den folgenden Abschnitten werden wichtige Überlegungen für Produktionsbereitstellungen und häufige Problembehandlungsszenarien behandelt.

Sicherheitsüberlegungen

Während der lokale GraphQL MCP-Server nur für Entwicklungszwecke implementiert werden sollte, wie in diesem Lernprogramm beschrieben, wird er mit HTTP-Transport implementiert und erleichtert die Verwendung als Ausgangspunkt für komplexere Clientserver- oder webbasierte Integrationen. Wenn Sie GraphQL MCP-Server in der Produktion bereitstellen:

Verwenden von Azure Key Vault zum Speichern von geheimen Schlüsseln anstelle von .env Dateien
Implementieren von ordnungsgemäßen Autorisierungs-, Netzwerksicherheits- und Firewallregeln
Aktivieren der Überwachungsprotokollierung für alle GraphQL-Abfragen
Verwenden von Azure App Service- oder Containerinstanzen für das Hosting
Implementieren von Ratenbeschränkungen und Authentifizierung für die MCP-Endpunkte
Regelmäßiges Erneuern von Client-Geheimnissen und Zertifikaten

Problembehandlung

Häufige Probleme und Lösungen

Authentifizierungsfehler

Überprüfen, ob Ihre Azure-App-Registrierung über die richtigen Berechtigungen verfügt
Überprüfen Sie, ob Dienstprinzipale in Ihrem Fabric-Mandanten aktiviert sind.
Sicherstellen, dass Ihr geheimer Clientschlüssel nicht abgelaufen ist

Fehler bei der Schema-Introspektion

Bestätigen, dass die Introspection in ihren GraphQL-API-Einstellungen aktiviert ist
Überprüfen Sie, ob Ihre GraphQL-Endpunkt-URL korrekt ist.
Überprüfen Sie die Netzwerkkonnektivität zu Ihrem Fabric-Arbeitsbereich

KI-Agent erkennt keine Tools

Starten Sie Ihren KI-Client nach Konfigurationsänderungen neu.
Überprüfen, ob auf die MCP-Server-URL zugegriffen werden kann
Überprüfen von Serverprotokollen auf Fehlermeldungen

Abfrageausführungsfehler

Überprüfen der Serverkonsole auf protokollierte Abfragen und Fehler
Stellen Sie sicher, dass Ihre Abfragen mit dem verfügbaren Schema übereinstimmen
Überprüfen Sie, ob Sie über entsprechende Berechtigungen für die angeforderten Daten verfügen.

Feedback

War diese Seite hilfreich?

Last updated on 2026-01-21

Teilen über

Verbinden von AI-Agents mit der Fabric-API für GraphQL mit einem lokalen MCP-Server (Model Context Protocol)

Was ist das Model Context Protocol (MCP)?

Warum GraphQL ideal für MCP ist

Voraussetzungen

Schritt 1: Konfigurieren des Dienstprinzipalzugriffs

Schritt 2: Aktivieren der GraphQL-Introspection (erfordert Arbeitsbereichsadministrator)

Schritt 3: Einrichten des GraphQL MCP-Servers

Klonen des Beispiel-Repositorys

Installieren von Abhängigkeiten

Konfigurieren von Umgebungsvariablen

Starten des GraphQL MCP-Servers

Verfügbare MCP-Tools

introspect-schema

query-graphql

Grundlegendes zum Workflow

Schritt 4: Testen des GraphQL MCP-Servers

Überprüfen der Serverintegrität

Testen der Schemaintrospektion

Testen einer GraphQL-Abfrage

Schritt 5: Verbinden von KI-Agents

GitHub Copilot in Visual Studio Code

Cursor-IDE

Was Sie erstellt haben

Sicherheitsüberlegungen

Problembehandlung

Häufige Probleme und Lösungen

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen

`introspect-schema`

`query-graphql`