AI-agents verbinden met Fabric-API voor GraphQL met een lokale MCP-server (Model Context Protocol)

Stel dat u GitHub Copilot vraagt :Toon me alle verkopen van het afgelopen kwartaal en laat deze automatisch query's uitvoeren op uw Fabric-datawarehouse, het schema begrijpen en resultaten retourneren, allemaal zonder één regel GraphQL te schrijven. In deze zelfstudie leert u hoe u dit mogelijk maakt.

In deze zelfstudie bouwt u een lokale GraphQL MCP-server die fungeert als een brug tussen AI-agents en uw Microsoft Fabric-gegevens. Aan het einde hebt u een werkende ontwikkelserver waarmee AI-assistenten zoals GitHub Copilot, Claude en andere AI-agents op natuurlijke wijze query's kunnen uitvoeren op uw Fabric-gegevens met behulp van gesprekstaal.

Wat u gaat bereiken:

Verificatie instellen zodat uw GraphQL MCP-server veilig toegang heeft tot Fabric
Introspectie van schema inschakelen, zodat AI-agents uw gegevensstructuur automatisch kunnen detecteren
Een lokale GraphQL MCP-server implementeren die natuurlijke taal vertaalt in GraphQL-query's
Verbind GitHub Copilot of andere AI-hulpprogramma's om op een converserende manier queries op uw gegevens uit te voeren.

Wat is het Model Context Protocol (MCP)?

Het McP (Model Context Protocol) is een standaard voor het verbinden van AI-assistenten met de systemen waarin gegevens zich bevinden, waaronder inhoudsopslagplaatsen, bedrijfshulpprogramma's en ontwikkelomgevingen. Het doel is om grensmodellen te helpen betere, relevantere reacties te produceren. Denk aan MCP als een USB-C poort voor AI-toepassingen. Net zoals USB-C een gestandaardiseerde manier biedt om uw apparaten te verbinden met verschillende randapparatuur en accessoires, biedt MCP een gestandaardiseerde manier om AI-modellen te verbinden met externe gegevensbronnen en hulpprogramma's.

Belangrijke AI-platformen, waaronder OpenAI, Microsoft Copilot Studio en Microsoft Foundry, hebben MCP als standaardmethode gebruikt om AI-agents te integreren met externe systemen. Dit maakt MCP een ideale keuze voor het verbinden van AI-agents met uw Microsoft Fabric-gegevens.

Waarom GraphQL ideaal is voor MCP

GraphQL is geschikt voor MCP-integraties omdat:

Schema-introspectie: AI-agents kunnen automatisch beschikbare gegevensstructuren en -relaties rechtstreeks vanuit het GraphQL-schema detecteren
Flexibele query's: agents kunnen precies de gegevens aanvragen die ze nodig hebben in één aanvraag
Typeveiligheid: Sterke typen helpen AI-agenten inzicht te geven in gegevensindelingen en beperkingen
Efficiënt ophalen van gegevens: vermindert het over-ophalen en onder-ophalen van gegevens

Met de API van Microsoft Fabric voor GraphQL kunt u uw Fabric Lakehouses, Data Warehouses en databases eenvoudig beschikbaar maken voor AI-agents via een gestandaardiseerde GraphQL-interface. Hoewel API voor GraphQL al krachtige querymogelijkheden biedt, is het instellen van een verbinding voor AI-agents mogelijk niet zo eenvoudig als mogelijk.

Met een eenvoudige lokale GraphQL MCP-server kunnen ontwikkelaars AI-agents gebruiken om hun Fabric-gegevensstructuur te detecteren, te begrijpen wat er beschikbaar is en er query's op uit te voeren met behulp van natuurlijke taal, allemaal via de gestandaardiseerde MCP-interface. Eenvoudig hoeft u geen afzonderlijk MCP-hulpprogramma op de server te definiëren voor elk GraphQL-type, query of mutatie. De GraphQL MCP server inspecteert het GraphQL schema waardoor AI-agenten inzicht krijgen in alle beschikbare typen en bewerkingen vanaf het begin.

Vereiste voorwaarden

Voordat u aan deze zelfstudie begint, moet u het volgende doen:

Een Microsoft Fabric-werkruimte met de juiste machtigingen. Er is een werkruimtebeheerderrol nodig om service-principals te configureren en introspectie in te schakelen.
Een API voor GraphQL-item dat is gemaakt en geconfigureerd. Zie Gegevens maken en toevoegen aan een API voor GraphQL of GraphQL-API maken vanuit uw SQL-database in de Fabric-portal.
Node.js geïnstalleerd op uw ontwikkelcomputer (inclusief npm)
Visual Studio Code geïnstalleerd op uw ontwikkelcomputer

Opmerking

Bent u geen beheerder? Voor sommige stappen in deze zelfstudie zijn beheerdersmachtigingen vereist. Als u geen beheerder bent, kunt u het grootste deel van de zelfstudie voltooien door uw beheerder om hulp te vragen bij specifieke taken. Elke stap waarvoor beheerdersmachtigingen zijn vereist, is duidelijk gemarkeerd.

Stap 1: Toegang tot de service-principal configureren

Wat u doet: Het instellen van niet-interactieve verificatiereferenties, zodat uw GraphQL MCP-server toegang heeft tot Fabric zonder dat een gebruiker zich telkens hoeft aan te melden.

Waarom dit belangrijk is: De GraphQL MCP-server wordt uitgevoerd als een achtergrondservice die AI-agents automatisch aanroepen. Het heeft een eigen identiteit (een service-principal) nodig met referenties voor verificatie bij Fabric namens uw toepassing, niet namens een specifieke gebruiker.

Volg de volledige handleiding bij Service Principals gebruiken met Fabric-API voor GraphQL om het volgende te doen:

Een Azure-app-registratie maken (elke gebruiker met machtigingen voor het maken van app-registraties in Microsoft Entra ID)
Een clientgeheim toevoegen onder Certificaten en geheimen (elke gebruiker)
Service-principals inschakelen in uw tenantinstellingen (hiervoor is een Fabric-tenantbeheerder vereist)
Machtigingen verlenen aan uw GraphQL-API en -werkruimte (hiervoor is de rol werkruimtebeheerder of inzender vereist)

Aanbeveling

Bent u geen beheerder? U kunt de eerste twee items zelf voltooien. Voor de tenantinstelling vraagt u uw Fabric-tenantbeheerder om 'Service-principals kunnen Fabric-API's gebruiken' in te schakelen onder instellingen voortenantinstellingen> van de beheerportal>voor ontwikkelaars. Voor werkruimtemachtigingen vraagt u uw werkruimtebeheerder om uw service-principal toegang te verlenen tot de werkruimte of specifieke GraphQL-API.

Wanneer u de installatie voltooit, legt u deze drie waarden vast voor de Configuratie van de GraphQL MCP-server:

Tenant-ID: gevonden in Microsoft Entra ID onder Overzicht>Tenant-ID
Client ID: gevonden in uw app-registratie onder Overzicht>Applicatie (client) ID
Clientgeheim: de waarde van het geheim die wordt weergegeven wanneer u een nieuw clientgeheim maakt (direct kopiëren, dit wordt slechts eenmaal weergegeven)

Stap 2: GraphQL-introspectie inschakelen (vereist werkruimtebeheerder)

Wat u doet: Als u introspectie inschakelt, kan de GraphQL MCP-server uw GraphQL-API 'Welke gegevens hebt u?' vragen en een volledige beschrijving ontvangen van alle beschikbare typen, velden en relaties.

Waarom dit belangrijk is: Dit is de 'magie' die query's in natuurlijke taal mogelijk maakt. Wanneer u Copilot 'Toon me klanten' vraagt, gebruikt de AI-agent eerst introspectie om te ontdekken dat er een customers type bestaat, welke velden het heeft en hoe u er query's op kunt uitvoeren. Zonder introspectie moet u het hele schema voor de AI handmatig documenteren.

Belangrijk

Introspectie moet zijn ingeschakeld om de GraphQL MCP-server te laten werken. Dit is standaard uitgeschakeld in Fabric om veiligheidsredenen. Alleen werkruimtebeheerders kunnen introspectie inschakelen. Als u geen beheerder bent, vraagt u de werkruimtebeheerder om deze stap te voltooien.

Volg de volledige handleiding bij Microsoft Fabric API voor GraphQL Introspection en Schema Export naar:

Introspectie inschakelen in uw API-instellingen
Begrijpen hoe introspectiequeries werken
Meer informatie over opties voor schema-export

Zodra introspectie is ingeschakeld, kan de GraphQL MCP-server een query uitvoeren op uw schemastructuur en deze beschikbaar maken voor AI-agents.

Stap 3: De GraphQL MCP-server instellen

Wat u doet: Een lokale Node.js-server installeren en configureren waarmee het Model Context Protocol wordt geïmplementeerd. Deze server fungeert als een vertaler tussen AI-agents en uw Fabric GraphQL-API.

Waarom dit belangrijk is: De MCP-server biedt een gestandaardiseerde interface die AI-agents begrijpen. Wanneer een AI-agent verbinding maakt, kan deze ontdekken welke hulpprogramma's beschikbaar zijn (introspectie en query's), deze hulpprogramma's aanroepen en antwoorden ontvangen, allemaal zonder dat u aangepaste integratiecode voor elk AI-platform hoeft te schrijven.

Nu u verificatiereferenties (stap 1) en introspectie hebt ingeschakeld (stap 2), kunt u de server configureren om deze te gebruiken.

De voorbeeldopslagplaats klonen

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

Afhankelijkheden installeren

npm install

Omgevingsvariabelen configureren

Maak een .env bestand in de hoofdmap van het project met uw configuratie:

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

Vervang de waarden van de tijdelijke aanduiding door:

MICROSOFT_FABRIC_API_URL: Uw GraphQL-eindpunt vanuit de Fabric-portal
MICROSOFT_FABRIC_TENANT_ID: uw Azure-tenant-id
MICROSOFT_FABRIC_CLIENT_ID: de client-id van uw app-registratie
MICROSOFT_FABRIC_CLIENT_SECRET: Het clientgeheim voor app-registratie

De GraphQL MCP-server starten

node FabricGraphQL_MCP.js

De server start op http://localhost:3000 en wordt weergegeven:

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

Beschikbare MCP-hulpprogramma's

De GraphQL MCP-server biedt twee belangrijke hulpprogramma's:

`introspect-schema`

Doel: haalt het volledige GraphQL-schema op
Parameters: Geen
Gebruik: moet eerst worden aangeroepen voordat u query's maakt

`query-graphql`

Doel: Voert GraphQL-query's uit op uw Fabric-gegevens
Parameters:
- query (vereist): De GraphQL-querystring
- variables (optioneel): object met GraphQL-variabelen
Gebruik: Voor alle bewerkingen voor het ophalen en bewerken van gegevens

Inzicht in het werkproces

De typische GraphQL MCP-werkstroom volgt dit patroon:

Schemadetectie: AI-agent moet eerst het hulpprogramma aanroepen om inzicht introspect-schema te hebben in het schema en de beschikbare gegevens
Queryplanning: Agent analyseert uw aanvraag in natuurlijke taal en het GraphQL-schema
Query genereren: Agent maakt de juiste GraphQL-query's
Uitvoering: Agent roept het hulpprogramma aan query-graphql met de gegenereerde query's
Antwoordverwerking: Agentindelingen en geeft de resultaten weer

Stap 4: De GraphQL MCP-server testen

Wat u doet: Controleer of uw MCP-server kan worden geverifieerd bij Fabric, haal uw schema op en voer query's uit, voordat u AI-agents verbindt.

Waarom dit belangrijk is: Testen zorgt ervoor dat alles correct is geconfigureerd. Als deze tests slagen, weet u dat de AI-agents verbinding kunnen maken in stap 5.

Serverstatus controleren

Controleer eerst of de server draait en kan authenticeren bij Fabric.

PowerShell gebruiken:

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

CURL gebruiken:

curl http://localhost:3000/health

U ontvangt een antwoord dat aangeeft dat de server draait, vergelijkbaar met:

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

Introspectie van schema testen

Controleer vervolgens of de server uw GraphQL-schema kan ophalen via introspectie. Dit roept het introspect-schema MCP-hulpprogramma aan.

PowerShell gebruiken:

$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 gebruiken:

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

Hiermee wordt de GraphQL-schemadefinitie geretourneerd.

Een GraphQL-query testen

Ten slotte test u het uitvoeren van een werkelijke GraphQL-query via de MCP-server. In dit voorbeeld worden query's uitgevoerd voor alle typenamen in uw schema met behulp van het query-graphql MCP-hulpprogramma.

PowerShell gebruiken:

$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 gebruiken:

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

Hiermee wordt een lijst met alle typen in uw GraphQL-schema geretourneerd.

Stap 5: AI-agents verbinden

Wat u doet: AI-hulpprogramma's configureren voor het gebruik van uw lokale MCP-server als gegevensbron.

Waarom dit belangrijk is: Hier komt alles samen. Zodra u verbinding hebt gemaakt, kunnen uw AI-agents uw Fabric-schema detecteren via introspectie en GraphQL-query's genereren op basis van aanvragen in natuurlijke taal. De AI verwerkt de querysyntaxis. U hoeft alleen maar vragen te stellen in het Engels.

GitHub Copilot in Visual Studio Code

De GitHub Copilot-extensie installeren in VS Code

Configureer de GraphQL MCP-server in uw Copilot-instellingen:

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

In Copilot-chat moet u eerst het schema introspecteren en vervolgens proberen een relevante vraag te stellen met betrekking tot de geïntrospeceerde gegevens in natuurlijke taal, bijvoorbeeld:

Cursor IDE

Cursorinstellingen openen

Voeg de CONFIGURATIE van de MCP-server toe:

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

Vraag in de chat eerst om het schema te onderzoeken en probeer vervolgens een relevante vraag te stellen met betrekking tot de onderzochte gegevens in natuurlijke taal.

Wat u hebt gebouwd

Gefeliciteerd! U hebt nu een werkende GraphQL MCP-server die:

Verifieert bij Fabric met behulp van service-principalreferenties
Uw Fabric-gegevensschema beschikbaar maken via introspectie
Vertaalt AI-agentaanvragen in GraphQL-query's
Retourneert gegevens in een indeling die AI-agents kunnen begrijpen en presenteren

Uw AI-agents (zoals GitHub Copilot) kunnen nu:

Automatisch ontdekken welke gegevens beschikbaar zijn in uw Fabric-werkruimte
Juiste GraphQL-query's genereren op basis van vragen over natuurlijke taal
Resultaten ophalen en opmaken zonder dat u querycode hoeft te schrijven

Deze lokale server is bedoeld voor ontwikkeling en leren. In de volgende secties worden belangrijke overwegingen behandeld voor productie-implementaties en veelvoorkomende scenario's voor probleemoplossing.

Beveiligingsoverwegingen

Hoewel de lokale GraphQL MCP-server alleen moet worden geïmplementeerd voor ontwikkelingsdoeleinden, zoals beschreven in deze zelfstudie, wordt deze geïmplementeerd met HTTP-transport, waardoor het eenvoudiger is om deze te gebruiken als uitgangspunt voor complexere client-server- of webintegraties. Als u GraphQL MCP-servers in productie implementeert:

Azure Key Vault gebruiken voor het opslaan van geheimen in plaats van .env bestanden
De juiste autorisatie, netwerkbeveiliging en firewallregels implementeren
Auditlogboekregistratie inschakelen voor alle GraphQL-query's
Azure App Service of Container Instances gebruiken voor hosting
Snelheidsbeperking en verificatie implementeren voor de MCP-eindpunten
Clientgeheimen en -certificaten regelmatig roteren

Probleemoplossingsproces

Veelvoorkomende problemen en oplossingen

Verificatiefouten

Controleer of uw Azure-app-registratie de juiste machtigingen heeft
Controleer of serviceprincipals zijn ingeschakeld in uw Fabric-tenant
Zorg ervoor dat uw clientgeheim niet is verlopen

Schema-introspectie mislukt

Controleer of introspectie is ingeschakeld in uw GraphQL API-instellingen
Controleer of de URL van uw GraphQL-eindpunt juist is
Netwerkconnectiviteit met uw Fabric-werkruimte controleren

AI-agent herkent geen hulpprogramma's

Start uw AI-client opnieuw op nadat de configuratie is gewijzigd
Controleer of de URL van de MCP-server toegankelijk is
Serverlogboeken controleren op eventuele foutberichten

Fouten bij het uitvoeren van query's

Controleer de serverconsole op geregistreerde query's en fouten
Zorg ervoor dat uw query's overeenkomen met het beschikbare schema
Controleer of u over de juiste machtigingen beschikt voor de aangevraagde gegevens

Feedback

Is deze pagina nuttig?

Last updated on 2026-01-21

Delen via

AI-agents verbinden met Fabric-API voor GraphQL met een lokale MCP-server (Model Context Protocol)

Wat is het Model Context Protocol (MCP)?

Waarom GraphQL ideaal is voor MCP

Vereiste voorwaarden

Stap 1: Toegang tot de service-principal configureren

Stap 2: GraphQL-introspectie inschakelen (vereist werkruimtebeheerder)

Stap 3: De GraphQL MCP-server instellen

De voorbeeldopslagplaats klonen

Afhankelijkheden installeren

Omgevingsvariabelen configureren

De GraphQL MCP-server starten

Beschikbare MCP-hulpprogramma's

introspect-schema

query-graphql

Inzicht in het werkproces

Stap 4: De GraphQL MCP-server testen

Serverstatus controleren

Introspectie van schema testen

Een GraphQL-query testen

Stap 5: AI-agents verbinden

GitHub Copilot in Visual Studio Code

Cursor IDE

Wat u hebt gebouwd

Beveiligingsoverwegingen

Probleemoplossingsproces

Veelvoorkomende problemen en oplossingen

Verwante inhoud

Feedback

Aanvullende resources

`introspect-schema`

`query-graphql`