Forbind AI-agenter til Fabric API til GraphQL med en lokal MCP-server (Model Context Protocol)

Forestil dig at spørge GitHub Copilot "Vis mig alle salg fra sidste kvartal" og få det til automatisk at forespørge dit Fabric-datalager, forstå skemaet og returnere resultater – alt sammen uden at skrive en eneste linje GraphQL. Denne vejledning viser dig, hvordan du gør det muligt.

I denne tutorial bygger du en lokal GraphQL MCP-server, der fungerer som en bro mellem AI-agenter og dine Microsoft Fabric-data. Til sidst har du en fungerende udviklingsserver, der gør det muligt for AI-assistenter som GitHub, Copilot, Claude og andre AI-agenter naturligt at forespørge dine Fabric-data ved hjælp af samtalesprog.

Hvad du opnår:

Opsæt autentificering, så din GraphQL MCP-server sikkert kan få adgang til Fabric
Aktiver skema-introspektion, så AI-agenter automatisk kan opdage din datastruktur
Udrul en lokal GraphQL MCP-server, der oversætter naturligt sprog til GraphQL-forespørgsler
Forbind GitHub, Copilot eller andre AI-værktøjer til at forespørge dine data samtalemæssigt

Hvad er MCP (Model Context Protocol)?

Model Context Protocol (MCP) er en standard til at forbinde AI-assistenter til de systemer, hvor data befinder sig, herunder indholdsarkiver, forretningsværktøjer og udviklingsmiljøer. Målet er at hjælpe grænsemodellerne med at skabe bedre og mere relevante svar. Tænk på MCP som en USB-C port til AI-programmer. Ligesom USB-C giver en standardiseret måde at forbinde dine enheder til forskellige eksterne enheder og tilbehør på, er MCP en standardiseret måde at forbinde AI-modeller til eksterne datakilder og værktøjer på.

Store AI-platforme som OpenAI, Microsoft Copilot Studio og Microsoft Foundry har taget MCP i brug som en standard måde at integrere AI-agenter med eksterne systemer på. Det gør MCP til et ideelt valg til at forbinde AI-agenter med dine Microsoft Fabric-data.

Hvorfor GraphQL er ideelt til MCP

GraphQL egner sig godt til MCP-integrationer, fordi:

Skemaintrospektion: AI-agenter kan automatisk finde tilgængelige datastrukturer og relationer direkte fra GraphQL-skemaet
Fleksible forespørgsler: Agenter kan anmode om præcis de data, de har brug for, i en enkelt anmodning
Typesikkerhed: Stærk indtastning hjælper AI-agenter med at forstå dataformater og begrænsninger
Effektiv datahentning: Reducerer over-hentning og under-hentning af data

Microsoft Fabrics API for GraphQL gør det nemt at eksponere dine Fabric-lakehouses, Data Warehouses og databaser for AI-agenter via en standardiseret GraphQL-grænseflade. Selvom API til GraphQL allerede indeholder effektive forespørgselsfunktioner, er det muligvis ikke så ligetil at konfigurere en forbindelse til AI-agenter, som det kunne være.

Med en simpel lokal GraphQL MCP-server kan udviklere bruge AI-agenter til at opdage deres Fabric-datastruktur, forstå hvad der er tilgængeligt, og forespørge den ved hjælp af naturligt sprog – alt sammen via det standardiserede MCP-interface. Bekvemt nok behøver du ikke at definere et separat MCP-værktøj i serveren for hver GraphQL-type, forespørgsel eller mutation. GraphQL MCP-serveren gennemgår GraphQL-skemaet og giver AI-agenter mulighed for at forstå alle tilgængelige typer og operationer fra starten.

Forudsætninger

Før du begynder dette selvstudium, skal du sørge for, at du har:

Et Microsoft Fabric-arbejdsområde med passende tilladelser. En arbejdsområdeadministratorrolle er nødvendig for at konfigurere serviceprincipaler og muliggøre introspektion.
Et API til GraphQL-elementer oprettet og konfigureret. Se Opret og tilføj data til et API for GraphQL eller Opret GraphQL API fra din SQL-database i Fabric-portalen.
Node.js installeret på din udviklingsmaskine (inkluderer NPM)
Visual Studio Code installeret på din udviklingsmaskine

Notat

Ikke administrator? Nogle trin i denne vejledning kræver administratorrettigheder. Hvis du ikke er administrator, kan du stadig gennemføre det meste af tutorialen ved at bede din admin om hjælp til specifikke opgaver. Hvert trin, der kræver administratorrettigheder, er tydeligt markeret.

Trin 1: Konfigurer adgang til tjenesteprincipal

Hvad du gør: Opsætning af ikke-interaktive autentificeringsoplysninger, så din GraphQL MCP-server kan få adgang til Fabric uden at kræve, at brugeren logger ind hver gang.

Hvorfor dette er vigtigt: GraphQL MCP-serveren kører som en baggrundstjeneste, som AI-agenter automatisk kalder. Den har brug for sin egen identitet (en service principal) med legitimationsoplysninger til at autentificere til Fabric på vegne af din applikation, ikke på vegne af en specifik bruger.

Følg den komplette vejledning under Brug tjenesteprincipaler med Fabric API til GraphQL for at:

Opret en Azure App Registration (enhver bruger med tilladelser til at oprette app-registreringer i Microsoft Entra ID)
Tilføj en klienthemmelighed under Certifikater & hemmeligheder (enhver bruger)
Aktivér service principals i dine lejerindstillinger (kræver Fabric tenant admin)
Giv tilladelser til dit GraphQL API og arbejdsområde (kræver arbejdsområde-administrator eller bidragyderrolle)

Tips

Ikke administrator? Du kan selv gennemføre de to første ting. For lejerindstillingen, bed din Fabric-lejeradministrator om at aktivere "Service Principals can use Fabric APIs" under Admin-portalen>Lejerindstillinger>Udviklerindstillinger. For arbejdsområde-tilladelser, bed din arbejdsområdeadministrator om at give din serviceprincipal adgang til arbejdsområdet eller det specifikke GraphQL API.

Når du færdiggør opsætningen, skal du fange disse tre værdier for GraphQL MCP-serverkonfigurationen:

Lejer-ID: Findes i Microsoft Entra ID under Oversigt>Lejer-ID
Klient-ID: Findes i din app-registrering under Oversigt>Applikation (klient) ID
Client Secret: Den hemmelige værdi, der vises, når du opretter en ny klienthemmelighed (kopier med det samme—den vises kun én gang)

Trin 2: Aktiver GraphQL introspektion (kræver arbejdsområde-administration)

Hvad du gør: Ved at aktivere introspektion kan GraphQL MCP-serveren spørge dit GraphQL API "Hvilke data har du?" og modtage en komplet beskrivelse af alle tilgængelige typer, felter og relationer.

Hvorfor dette er vigtigt: Dette er den "magi", der gør naturlige sprogforespørgsler mulige. Når du spørger Copilot "Vis mig kunder", bruger AI-agenten først introspektion til at opdage, at en customers type eksisterer, hvilke felter den har, og hvordan man forespørger den. Uden introspektion skal du manuelt dokumentere hele dit skema for AI'en.

Vigtigt!

Introspektion skal være aktiveret for at GraphQL MCP-serveren kan fungere. Dette er deaktiveret som standard i Fabric af sikkerhedsmæssige årsager. Kun arbejdsområdeadministratorer kan aktivere introspektion. Hvis du ikke er administrator, så bed din workspace-admin om at udføre dette trin.

Følg den komplette guide på Microsoft Fabric API for GraphQL Introspection og Schema Export til:

Aktiver introspektion i dine API-indstillinger
Forstå, hvordan introspektionsforespørgsler fungerer
Lær om skema-eksportmuligheder

Når introspektion er aktiveret, kan GraphQL MCP-serveren forespørge din skemastruktur og gøre den tilgængelig for AI-agenter.

Trin 3: Opsæt GraphQL MCP-serveren

Hvad du gør: Installation og konfiguration af en lokal Node.js-server, der implementerer Model Context Protocol. Denne server fungerer som en oversætter mellem AI-agenter og din Fabric GraphQL API.

Hvorfor dette er vigtigt: MCP-serveren tilbyder en standardiseret grænseflade, som AI-agenter forstår. Når en AI-agent forbinder, kan den finde ud af, hvilke værktøjer der er tilgængelige (introspektion og forespørgsler), kalde disse værktøjer og modtage svar – alt sammen uden at du skal skrive brugerdefineret integrationskode til hver AI-platform.

Nu hvor du har autentificeringsoplysninger (trin 1) og introspektion aktiveret (trin 2), er du klar til at konfigurere serveren til at bruge dem.

Klon eksempellageret

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

Installér afhængigheder

npm install

Konfigurer miljøvariabler

Opret en .env fil i projektroden med din 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

Erstat pladsholderværdierne med:

MICROSOFT_FABRIC_API_URL: Dit GraphQL-slutpunkt fra Fabric-portalen
MICROSOFT_FABRIC_TENANT_ID: Dit Azure-lejer-id
MICROSOFT_FABRIC_CLIENT_ID: Klient-id'et til appregistrering
MICROSOFT_FABRIC_CLIENT_SECRET: Klienthemmeligheden for appregistrering

Start GraphQL MCP-serveren

node FabricGraphQL_MCP.js

Serveren starter på http://localhost:3000 og viser:

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

Tilgængelige MCP-værktøjer

GraphQL MCP-serveren tilbyder to hovedværktøjer:

`introspect-schema`

Formål: Henter det komplette GraphQL-skema
Parametre: Ingen
Forbrug: Skal kaldes først, før du foretager forespørgsler

`query-graphql`

Formål: Udfører GraphQL-forespørgsler mod dine Fabric-data
Parametre:
- query (påkrævet): GraphQL-forespørgselsstrengen
- variables (valgfrit): Objektet GraphQL-variabler
Anvendelse: For alle datahentnings- og manipulationshandlinger

Om arbejdsprocessen

Den typiske GraphQL MCP-arbejdsgang følger dette mønster:

Skemaopdagelse: AI-agenten skal først kalde værktøjet introspect-schema for at forstå skemaet og de tilgængelige data
Forespørgselsplanlægning: Agenten analyserer din anmodning om naturligt sprog og GraphQL-skemaet
Oprettelse af forespørgsel: Agent opretter relevante GraphQL-forespørgsler
Eksekvering: Agenten kalder værktøjet query-graphql med de genererede forespørgsler
Svarbehandling: Agent formaterer og præsenterer resultaterne

Trin 4: Test GraphQL MCP-serveren

Hvad du gør: At verificere at din MCP-server kan autentificere sig til Fabric, hente dit skema og udføre forespørgsler – før du forbinder AI-agenter.

Hvorfor dette er vigtigt: Manuel test sikrer, at alt er konfigureret korrekt. Hvis disse tests består, ved du, at AI-agenterne kan forbinde sig succesfuldt i trin 5.

Kontrollér servertilstand

Først, bekræft at serveren kører og kan autentificere til Fabric.

Brug af PowerShell:

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

Brug af cURL:

curl http://localhost:3000/health

Du bør modtage et svar, der angiver, at serveren kører på samme måde som:

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

Test skemaintrospektion

Dernæst skal du sikre dig, at serveren kan hente dit GraphQL-skema gennem introspektion. Dette kaldes introspect-schema MCP-værktøjet.

Brug af 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

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

Dette bør returnere din GraphQL-skemadefinition.

Test en GraphQL-forespørgsel

Til sidst test udførelsen af en faktisk GraphQL-forespørgsel gennem MCP-serveren. Dette eksempel forespørger alle typenavne i dit skema ved hjælp af MCP-værktøjet query-graphql .

Brug af 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

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

Dette returnerer en liste over alle typer i dit GraphQL-skema.

Trin 5: Opret forbindelse til AI-agenter

Hvad du gør: Konfigurerer AI-værktøjer til at bruge din lokale MCP-server som datakilde.

Hvorfor dette er vigtigt: Det er her, alt falder på plads. Når de er forbundet, kan dine AI-agenter opdage dit Fabric-skema gennem introspektion og generere GraphQL-forespørgsler baseret på naturlige sprogforespørgsler. AI'en håndterer forespørgselssyntaksen – du stiller bare spørgsmål på almindeligt engelsk.

GitHub Copilot i Visual Studio Code

Installér GitHub Copilot-udvidelsen i VS Code

Konfigurér GraphQL MCP-serveren i dine Copilot-indstillinger:

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

I Copilot-chat skal du først bede om at introspektere skemaet og derefter prøve at stille et relevant spørgsmål, der er relateret til de indadvendte data på et naturligt sprog, f.eks.:

Markør-IDE

Åbn markørindstillinger

Tilføj MCP-serverkonfigurationen:

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

I chatten skal du først bede om at introspect skemaet og derefter prøve at stille et relevant spørgsmål, der er relateret til de inspicerede data på et naturligt sprog.

Hvad du byggede

Tillykke! Du har nu en fungerende GraphQL MCP-server, der:

Autentificerer til Fabric ved hjælp af service principal credentials
Eksponerer dit Fabric-dataskema gennem introspektion
Oversætter AI-agentanmodninger til GraphQL-forespørgsler
Returndata i et format, AI-agenter kan forstå og præsentere

Dine AI-agenter (som GitHub Copilot) kan nu:

Find automatisk ud af, hvilke data der er tilgængelige i dit Fabric-arbejdsområde
Generer korrekte GraphQL-forespørgsler baseret på naturlige sprogspørgsmål
Hent og formater resultater uden at du skriver nogen forespørgselskode

Denne lokale server er beregnet til udvikling og læring. De følgende afsnit dækker vigtige overvejelser for produktionsudrulninger og almindelige fejlfindingsscenarier.

Overvejelser om sikkerhed

Selvom den lokale GraphQL MCP-server kun bør implementeres til udviklingsformål som beskrevet i denne vejledning, er den implementeret med HTTP-transport, hvilket gør det lettere at bruge den som udgangspunkt for mere komplekse klient-server eller webbaserede integrationer. Hvis du deployerer GraphQL MCP-servere i produktion:

Brug Azure Key Vault til at gemme hemmeligheder i stedet for .env filer
Implementer korrekt autorisation, netværkssikkerhed og firewallregler
Aktivér overvågningslogføring for alle GraphQL-forespørgsler
Brug Azure App Service eller Container Instances til hosting
Implementer hastighedsbegrænsning og godkendelse for MCP-slutpunkterne
Roter jævnligt klienthemmeligheder og certifikater

Fejlfinding

Almindelige problemer og løsninger

Godkendelsesfejl

Kontrollér, at din Azure App Registration har de korrekte tilladelser
Kontrollér, at tjenesteprincipaler er aktiveret i din Fabric-lejer
Sørg for, at din klienthemmelighed ikke er udløbet

Skemaintrospektion mislykkes

Bekræft, at introspektion er aktiveret i indstillingerne for GraphQL-API'en
Kontrollér, at URL-adressen til dit GraphQL-slutpunkt er korrekt
Kontrollér netværksforbindelsen til dit Fabric-arbejdsområde

AI-agent genkender ikke værktøjer

Genstart din AI-klient efter konfigurationsændringer
Kontrollér, at URL-adressen til MCP-serveren er tilgængelig
Kontrollér serverlogge for eventuelle fejlmeddelelser

Fejl i udførelse af forespørgsel

Gennemse serverkonsollen for logførte forespørgsler og fejl
Sørg for, at dine forespørgsler stemmer overens med det tilgængelige skema
Kontrollér, at du har de nødvendige tilladelser til de ønskede data

Feedback

Var denne side nyttig?

Last updated on 2026-01-20

Del via

Forbind AI-agenter til Fabric API til GraphQL med en lokal MCP-server (Model Context Protocol)

Hvad er MCP (Model Context Protocol)?

Hvorfor GraphQL er ideelt til MCP

Forudsætninger

Trin 1: Konfigurer adgang til tjenesteprincipal

Trin 2: Aktiver GraphQL introspektion (kræver arbejdsområde-administration)

Trin 3: Opsæt GraphQL MCP-serveren

Klon eksempellageret

Installér afhængigheder

Konfigurer miljøvariabler

Start GraphQL MCP-serveren

Tilgængelige MCP-værktøjer

introspect-schema

query-graphql

Om arbejdsprocessen

Trin 4: Test GraphQL MCP-serveren

Kontrollér servertilstand

Test skemaintrospektion

Test en GraphQL-forespørgsel

Trin 5: Opret forbindelse til AI-agenter

GitHub Copilot i Visual Studio Code

Markør-IDE

Hvad du byggede

Overvejelser om sikkerhed

Fejlfinding

Almindelige problemer og løsninger

Relateret indhold

Feedback

Yderligere ressourcer

`introspect-schema`

`query-graphql`