Collegare gli agenti di intelligenza artificiale alla Fabric API per GraphQL con un server MCP (Model Context Protocol) locale

Si supponga di chiedere a GitHub Copilot di visualizzare tutte le vendite dell'ultimo trimestre e di eseguirne automaticamente query sul data warehouse di Fabric, comprendere lo schema e restituire i risultati, senza scrivere una singola riga di GraphQL. Questa esercitazione illustra come rendere possibile questa operazione.

In questa esercitazione viene creato un server MCP GraphQL locale che funge da ponte tra gli agenti di intelligenza artificiale e i dati di Microsoft Fabric. Al termine, si dispone di un server di sviluppo funzionante che consente agli assistenti di intelligenza artificiale come GitHub Copilot, Claude e altri agenti di intelligenza artificiale di eseguire naturalmente query sui dati di Fabric usando il linguaggio di conversazione.

Cosa si otterrà:

Configurare l'autenticazione in modo che il server MCP GraphQL possa accedere in modo sicuro a Fabric
Abilitare l'introspezione dello schema in modo che gli agenti di intelligenza artificiale possano individuare automaticamente la struttura dei dati
Distribuire un server MCP GraphQL locale che converte il linguaggio naturale in query GraphQL
Connettere GitHub Copilot o altri strumenti di intelligenza artificiale per eseguire query sui dati in modo colloquiale

Che cos'è il protocollo MCP (Model Context Protocol)?

Il protocollo MCP (Model Context Protocol) è uno standard per connettere gli assistenti di intelligenza artificiale ai sistemi in cui si trovano i dati, inclusi repository di contenuti, strumenti aziendali e ambienti di sviluppo. Il suo obiettivo è aiutare i modelli di frontiera a produrre risposte migliori e più rilevanti. Si pensi a MCP come una porta USB-C per le applicazioni di intelligenza artificiale. Proprio come USB-C offre un modo standardizzato per connettere i dispositivi a varie periferiche e accessori, MCP offre un modo standardizzato per connettere i modelli di intelligenza artificiale a origini dati e strumenti esterni.

Le principali piattaforme di intelligenza artificiale, tra cui OpenAI, Microsoft Copilot Studio e Microsoft Foundry hanno adottato MCP come modo standard per integrare gli agenti di intelligenza artificiale con sistemi esterni. Questo rende MCP una scelta ideale per connettere gli agenti di intelligenza artificiale ai dati di Microsoft Fabric.

Perché GraphQL è ideale per MCP

GraphQL è particolarmente adatto per le integrazioni MCP perché:

Introspezione dello schema: gli agenti di intelligenza artificiale possono individuare automaticamente le strutture e le relazioni dei dati disponibili direttamente dallo schema GraphQL
Query flessibili: gli agenti possono richiedere esattamente i dati necessari in una singola richiesta
Sicurezza dei tipi: la tipizzazione avanzata aiuta gli agenti di intelligenza artificiale a comprendere i formati e i vincoli dei dati
Recupero efficiente dei dati: Riduce la sovra-estrazione e la sotto-estrazione dei dati

L'API di Microsoft Fabric per GraphQL semplifica l'esposizione dei lakehouse, dei data warehouse e dei database di Fabric agli agenti di intelligenza artificiale tramite un'interfaccia GraphQL standardizzata. Anche se l'API per GraphQL offre già potenti funzionalità di query, la configurazione di una connessione per gli agenti di intelligenza artificiale potrebbe non essere semplice come potrebbe essere.

Con un semplice server MCP GraphQL locale, gli sviluppatori possono usare gli agenti di intelligenza artificiale per individuare la struttura dei dati di Fabric, comprendere cosa è disponibile ed eseguire query usando il linguaggio naturale, tutto tramite l'interfaccia MCP standardizzata. In pratica, non è necessario definire uno strumento MCP separato nel server per ogni tipo, query o mutazione di GraphQL. Il server MCP GraphQL esegue un'analisi dello schema GraphQL che consente agli agenti di intelligenza artificiale di comprendere tutti i tipi e le operazioni disponibili sin dall'inizio.

Prerequisiti

Prima di iniziare questa esercitazione, assicurarsi di avere:

Area di lavoro di Microsoft Fabric con autorizzazioni appropriate. È necessario un ruolo di amministratore dell'area di lavoro per configurare le entità servizio e abilitare l'introspezione.
API per l'elemento GraphQL creato e configurato. Vedere Creare e aggiungere dati a un'API per GraphQL o Creare un'API GraphQL dal database SQL nel portale di Fabric.
Node.js installato nel computer di sviluppo (include npm)
Visual Studio Code installato nel computer di sviluppo

Annotazioni

Non è un amministratore? Alcuni passaggi di questa esercitazione richiedono autorizzazioni di amministratore. Se non si è un amministratore, è comunque possibile completare la maggior parte dell'esercitazione chiedendo all'amministratore di fornire assistenza per attività specifiche. Ogni passaggio che richiede autorizzazioni di amministratore è chiaramente contrassegnato.

Passaggio 1: Configurare l'accesso al principale del servizio

Cosa stai facendo: Configurazione delle credenziali di autenticazione non interattive in modo che il server MCP GraphQL possa accedere a Fabric senza richiedere a un utente di accedere ogni volta.

Perché questo aspetto è importante: Il server MCP GraphQL viene eseguito come servizio in background che gli agenti di intelligenza artificiale chiamano automaticamente. Ha bisogno di una propria identità (un principale del servizio) con le relative credenziali per autenticarsi a Fabric per conto della tua applicazione, non per conto di un utente specifico.

Seguire la guida completa in Usare i princìpi del servizio con l'API di Fabric per GraphQL per:

Creare una registrazione dell'app di Azure (qualsiasi utente con autorizzazioni per creare registrazioni di app in Microsoft Entra ID)
Aggiungere un segreto client in Certificati e segreti (qualsiasi utente)
Abilitare i principali del servizio nelle impostazioni del tenant (richiede un amministratore del tenant di Fabric)
Concedere le autorizzazioni all'API GraphQL e all'area di lavoro (richiede il ruolo di amministratore o collaboratore dell'area di lavoro)

Suggerimento

Non è un amministratore? È possibile completare i primi due elementi manualmente. Per l'impostazione del tenant, chiedere all'amministratore del tenant di Fabric di abilitare "Le entità servizio possono usare le API di Fabric" sotto Portale di amministrazione>, Impostazioni del tenant>, Impostazioni sviluppatore. Per le autorizzazioni dell'area di lavoro, chiedere all'amministratore dell'area di lavoro di concedere al principale del servizio l'accesso all'area di lavoro o all'API GraphQL specifica.

Al termine dell'installazione, acquisire questi tre valori per la configurazione del server MCP GraphQL:

ID tenant: trovato in MICROSOFT Entra ID in Panoramica>ID tenant
ID client: trovato nella registrazione dell'app in PANORAMICA>ID applicazione (client)
Segreto client: il valore del segreto visualizzato quando si crea un nuovo segreto client (copia immediatamente, viene visualizzato una sola volta)

Passaggio 2: Abilitare l'introspezione GraphQL (richiede l'amministratore dell'area di lavoro)

Cosa stai facendo: L'abilitazione dell'introspezione consente al server MCP GraphQL di chiedere all'API GraphQL "Quali dati sono disponibili?" e di ricevere una descrizione completa di tutti i tipi, i campi e le relazioni disponibili.

Perché questo aspetto è importante: Si tratta del "magic" che rende possibili le query in linguaggio naturale. Quando si chiede a Copilot "Show me customers", l'agente di intelligenza artificiale usa prima di tutto l'introspezione per scoprire che esiste un customers tipo, quali campi ha e come eseguire query su di esso. Senza introspezione, è necessario documentare manualmente l'intero schema per l'intelligenza artificiale.

Importante

Per il funzionamento del server MCP GraphQL, è necessario abilitare l'introspezione. Questa opzione è disabilitata per impostazione predefinita in Fabric per motivi di sicurezza. Solo gli amministratori dell'area di lavoro possono abilitare l'introspezione. Se non si è un amministratore, chiedere all'amministratore dell'area di lavoro di completare questo passaggio.

Segui la guida completa all'API di Microsoft Fabric per GraphQL Introspection ed Esportazione dello Schema per:

Abilitare l'introspezione nelle impostazioni dell'API
Informazioni sul funzionamento delle query di introspezione
Informazioni sulle opzioni di esportazione dello schema

Dopo aver abilitato l'introspezione, il server MCP GraphQL può eseguire query sulla struttura dello schema e renderlo disponibile agli agenti di intelligenza artificiale.

Passaggio 3: Configurare il server MCP GraphQL

Cosa stai facendo: Installazione e configurazione di un server Node.js locale che implementa il protocollo del contesto del modello. Questo server funge da traduttore tra gli agenti di intelligenza artificiale e l'API GraphQL di Fabric.

Perché questo aspetto è importante: Il server MCP fornisce un'interfaccia standardizzata che gli agenti di intelligenza artificiale comprendono. Quando un agente di intelligenza artificiale si connette, può scoprire quali strumenti sono disponibili (introspezione e query), chiamare questi strumenti e ricevere risposte, senza scrivere codice di integrazione personalizzato per ogni piattaforma di intelligenza artificiale.

Dopo aver ottenuto le credenziali di autenticazione (passaggio 1) e l'introspezione abilitata (passaggio 2), è possibile configurare il server per usarle.

Clonare il repository di esempio:

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

Installa le dipendenze

npm install

Configurare le variabili di ambiente

Creare un .env file nella radice del progetto con la configurazione:

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

Sostituire i valori segnaposto con:

MICROSOFT_FABRIC_API_URL: endpoint GraphQL dal portale di Fabric
MICROSOFT_FABRIC_TENANT_ID: ID tenant di Azure
MICROSOFT_FABRIC_CLIENT_ID: ID client di registrazione dell'app
MICROSOFT_FABRIC_CLIENT_SECRET: segreto client di registrazione dell'app

Avviare il server MCP GraphQL

node FabricGraphQL_MCP.js

Il server viene avviato su http://localhost:3000 e visualizza:

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

Strumenti MCP disponibili

Il server MCP GraphQL offre due strumenti principali:

`introspect-schema`

Scopo: recupera lo schema GraphQL completo
Parametri: nessuno
Utilizzo: deve essere chiamato prima di eseguire query

`query-graphql`

Scopo: esegue query GraphQL sui dati di Fabric
Parametri:
- query (obbligatorio): stringa di query GraphQL
- variables (facoltativo): oggetto delle variabili GraphQL
Utilizzo: per tutte le operazioni di recupero e manipolazione dei dati

Informazioni sul flusso di lavoro

Il tipico flusso di lavoro MCP GraphQL segue questo modello:

Individuazione dello schema: l'agente di intelligenza artificiale deve prima chiamare lo introspect-schema strumento per comprendere lo schema e i dati disponibili
Pianificazione query: L'agente analizza la richiesta in linguaggio naturale e lo schema GraphQL
Generazione di query: L'agente crea query GraphQL appropriate.
Esecuzione: Agent chiama lo query-graphql strumento con le query generate
Elaborazione delle risposte: l'agente formatta e presenta i risultati

Passaggio 4: Testare il server MCP GraphQL

Cosa stai facendo: Verifica che il server MCP possa eseguire l'autenticazione in Fabric, recuperare lo schema ed eseguire query prima di connettere gli agenti di intelligenza artificiale.

Perché questo aspetto è importante: Il test verifica manualmente che tutto sia configurato correttamente. Se questi test vengono superati, si sa che gli agenti di intelligenza artificiale sono in grado di connettersi correttamente nel passaggio 5.

Verificare l'integrità del server

Prima di tutto, verificare che il server sia in esecuzione e possa eseguire l'autenticazione in Fabric.

Tramite PowerShell:

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

Uso di cURL:

curl http://localhost:3000/health

Si dovrebbe ricevere una risposta che indica che il server è in esecuzione, simile al seguente:

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

Introspezione dello schema di test

Verificare quindi che il server possa recuperare lo schema GraphQL tramite introspezione. Viene chiamato lo introspect-schema strumento MCP.

Tramite 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

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

Verrà restituita la definizione dello schema GraphQL.

Testare una query GraphQL

Infine, testare l'esecuzione di una query GraphQL effettiva tramite il server MCP. In questo esempio vengono eseguite query per tutti i nomi di tipo nello schema usando lo query-graphql strumento MCP.

Tramite 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

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

Verrà restituito un elenco di tutti i tipi nello schema GraphQL.

Passaggio 5: Connettere gli agenti di intelligenza artificiale

Cosa stai facendo: Configurazione degli strumenti di intelligenza artificiale per l'uso del server MCP locale come origine dati.

Perché questo aspetto è importante: È qui che tutto si riunisce. Dopo la connessione, gli agenti di intelligenza artificiale possono individuare lo schema di Fabric tramite introspezione e generare query GraphQL in base alle richieste in linguaggio naturale. L'intelligenza artificiale gestisce la sintassi della query, ma è sufficiente porre domande in inglese normale.

GitHub Copilot in Visual Studio Code

Installare l'estensione GitHub Copilot in VS Code

Configurare il server MCP GraphQL nelle impostazioni di Copilot:

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

Nella chat di Copilot, chiedere prima di tutto di introspettire lo schema e quindi provare a porre una domanda pertinente correlata ai dati introspettati nel linguaggio naturale, ad esempio:

IDE cursore

Aprire le impostazioni del cursore

Aggiungere la configurazione del server MCP:

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

Nella chat, chiedere prima di tutto di introspettire lo schema e quindi provare a porre una domanda pertinente correlata ai dati introspettati nel linguaggio naturale.

Ciò che hai creato

Congratulazioni! È ora disponibile un server MCP GraphQL funzionante che:

Esegue l'autenticazione a Fabric usando le credenziali dell'entità servizio
Espone lo schema dei dati di Fabric tramite introspezione
Converte le richieste dell'agente di intelligenza artificiale in query GraphQL
Restituisce i dati in un formato che gli agenti di intelligenza artificiale possono comprendere e presentare

Gli agenti di intelligenza artificiale (ad esempio GitHub Copilot) possono ora:

Individua automaticamente quali dati sono disponibili nel tuo workspace Fabric
Generare query GraphQL corrette in base alle domande in linguaggio naturale
Recuperare e formattare i risultati senza scrivere codice di query

Questo server locale è destinato allo sviluppo e all'apprendimento. Le sezioni seguenti illustrano considerazioni importanti per le distribuzioni di produzione e gli scenari comuni di risoluzione dei problemi.

Considerazioni sulla sicurezza

Anche se il server MCP GraphQL locale deve essere implementato solo a scopo di sviluppo come descritto in questa esercitazione, viene implementato con il trasporto HTTP, rendendo più semplice usarlo come punto di partenza per integrazioni client-server o basate sul Web più complesse. Se si distribuiscono server MCP GraphQL nell'ambiente di produzione:

Usare Azure Key Vault per archiviare segreti anziché .env file
Implementare le regole appropriate per l'autorizzazione, la sicurezza di rete e il firewall
Abilitare la registrazione di controllo per tutte le query GraphQL
Usare servizio app di Azure o istanze di contenitore per l'hosting
Implementare la limitazione della frequenza e l'autenticazione per gli endpoint MCP
Ruotare regolarmente i segreti client e i certificati client

Risoluzione dei problemi

Problemi e soluzioni comuni

Errori di autenticazione

Verificare che la registrazione dell'app di Azure disponga delle autorizzazioni corrette
Verificare che le entità servizio siano abilitate nel tenant di Fabric
Verificare che il segreto client non sia scaduto

L'introspezione dello schema ha esito negativo

Verificare che l'introspezione sia abilitata nelle impostazioni dell'API GraphQL
Verificare che l'URL dell'endpoint GraphQL sia corretto
Verificare la connettività di rete alla workspace Fabric

L'agente di intelligenza artificiale non riconosce gli strumenti

Riavviare il client di intelligenza artificiale dopo le modifiche alla configurazione
Verificare che l'URL del server MCP sia accessibile
Controllare i log del server per eventuali messaggi di errore

Errori di esecuzione delle query

Esaminare la console del server per individuare le query registrate e gli errori
Verificare che le query corrispondano allo schema disponibile
Verificare di disporre delle autorizzazioni appropriate per i dati richiesti

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-01-21

Condividi tramite

Collegare gli agenti di intelligenza artificiale alla Fabric API per GraphQL con un server MCP (Model Context Protocol) locale

Che cos'è il protocollo MCP (Model Context Protocol)?

Perché GraphQL è ideale per MCP

Prerequisiti

Passaggio 1: Configurare l'accesso al principale del servizio

Passaggio 2: Abilitare l'introspezione GraphQL (richiede l'amministratore dell'area di lavoro)

Passaggio 3: Configurare il server MCP GraphQL

Clonare il repository di esempio:

Installa le dipendenze

Configurare le variabili di ambiente

Avviare il server MCP GraphQL

Strumenti MCP disponibili

introspect-schema

query-graphql

Informazioni sul flusso di lavoro

Passaggio 4: Testare il server MCP GraphQL

Verificare l'integrità del server

Introspezione dello schema di test

Testare una query GraphQL

Passaggio 5: Connettere gli agenti di intelligenza artificiale

GitHub Copilot in Visual Studio Code

IDE cursore

Ciò che hai creato

Considerazioni sulla sicurezza

Risoluzione dei problemi

Problemi e soluzioni comuni

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive

`introspect-schema`

`query-graphql`