Connecter des agents IA à l’API Fabric pour GraphQL avec un serveur MCP (Model Context Protocol) local

Imaginez demander à GitHub Copilot « Afficher toutes les ventes du dernier trimestre » et de l’avoir automatiquement interroger votre entrepôt de données Fabric, comprendre le schéma et retourner les résultats, sans écrire une seule ligne de GraphQL. Ce tutoriel vous montre comment rendre cela possible.

Dans ce tutoriel, vous créez un serveur GraphQL MCP local qui agit comme un pont entre les agents IA et vos données Microsoft Fabric. À la fin, vous disposez d’un serveur de développement opérationnel qui permet aux assistants IA tels que GitHub Copilot, Claude et d’autres agents IA d’interroger naturellement vos données Fabric à l’aide du langage conversationnel.

Ce que vous allez faire :

Configurer l’authentification afin que votre serveur GraphQL MCP puisse accéder en toute sécurité à Fabric
Activer l’introspection de schéma afin que les agents IA puissent découvrir automatiquement votre structure de données
Déployer un serveur GraphQL MCP local qui traduit le langage naturel en requêtes GraphQL
Connecter GitHub Copilot ou d’autres outils IA pour interroger vos données de manière conversationnelle

Qu’est-ce que le protocole MCP (Model Context Protocol) ?

Le protocole MCP (Model Context Protocol) est un standard pour connecter des assistants IA aux systèmes où les données se trouvent, notamment les référentiels de contenu, les outils métier et les environnements de développement. Son objectif est d’aider les modèles de frontière à produire de meilleures réponses plus pertinentes. Considérez MCP comme un port USB-C pour les applications IA. Tout comme USB-C fournit un moyen standardisé de connecter vos appareils à différents périphériques et accessoires, MCP offre un moyen standardisé de connecter des modèles IA à des sources de données et outils externes.

Les principales plateformes IA, notamment OpenAI, Microsoft Copilot Studio et Microsoft Foundry, ont adopté MCP comme moyen standard d’intégrer des agents IA à des systèmes externes. Cela rend MCP idéal pour connecter des agents IA à vos données Microsoft Fabric.

Pourquoi GraphQL est idéal pour MCP

GraphQL convient parfaitement aux intégrations MCP, car :

Introspection de schéma : les agents IA peuvent détecter automatiquement les structures et relations de données disponibles directement à partir du schéma GraphQL
Requêtes flexibles : les agents peuvent demander exactement les données dont ils ont besoin dans une seule requête
Sécurité des types : Le typage fort aide les agents IA à comprendre les formats et les contraintes des données.
Extraction efficace des données : réduit la sur-extraction et la sous-extraction des données

L’API de Microsoft Fabric pour GraphQL facilite l’exposition de vos bases de données, entrepôts de données et lakehouses Fabric à des agents IA via une interface GraphQL standardisée. Bien que l’API pour GraphQL offre déjà de puissantes fonctionnalités d’interrogation, la configuration d’une connexion pour les agents IA peut ne pas être aussi simple que possible.

Avec un serveur GRAPHQL MCP local simple, les développeurs peuvent utiliser des agents IA pour découvrir leur structure de données Fabric, comprendre ce qui est disponible et l’interroger à l’aide du langage naturel, tout au long de l’interface MCP standardisée. De façon pratique, vous n’avez pas besoin de définir un outil MCP distinct dans le serveur pour chaque type, requête ou mutation GraphQL. Le serveur GraphQL MCP introspecte le schéma GraphQL, ce qui permet aux agents IA de comprendre tous les types et opérations disponibles dès le début.

Conditions préalables

Avant de commencer ce tutoriel, vérifiez que vous disposez des points suivants :

Un espace de travail Microsoft Fabric avec les autorisations appropriées. Un rôle d’administrateur d’espace de travail est nécessaire pour configurer les principaux de service et activer l’introspection.
Une API pour un élément GraphQL a été créée et configurée. Consultez Créer et ajouter des données à une API pour GraphQL ou Créer une API GraphQL à partir de votre base de données SQL dans le portail Fabric.
Node.js installé sur votre ordinateur de développement (inclut npm)
Visual Studio Code installé sur votre ordinateur de développement

Note

Pas un administrateur ? Certaines étapes de ce didacticiel nécessitent des autorisations d’administrateur. Si vous n’êtes pas administrateur, vous pouvez toujours suivre la plupart du didacticiel en demandant à votre administrateur d’aider à effectuer des tâches spécifiques. Chaque étape qui nécessite des autorisations d’administrateur est clairement marquée.

Étape 1 : Configurer l'accès au principal du service

Ce que vous faites : Configuration des informations d’identification d’authentification non interactives afin que votre serveur GraphQL MCP puisse accéder à Fabric sans demander à un utilisateur de se connecter à chaque fois.

Pourquoi cela est important : Le serveur GRAPHQL MCP s’exécute en tant que service en arrière-plan que les agents IA appellent automatiquement. Il a besoin de son propre identité (un principal de service) avec des informations d’identification pour s’authentifier auprès de Fabric au nom de votre application, et non pour le compte d’un utilisateur spécifique.

Suivez ce guide complet sur Utilisation des principaux services avec l'API Fabric pour GraphQL pour :

Créer une inscription d’application Azure (tout utilisateur disposant des autorisations nécessaires pour créer des inscriptions d’applications dans Microsoft Entra ID)
Ajouter un secret client sous Certificats &secrets (n’importe quel utilisateur)
Activer les principaux de service dans les paramètres de votre locataire (nécessite l’administrateur du locataire Fabric)
Accorder des autorisations à votre API GraphQL et à votre espace de travail (nécessite un rôle d’administrateur ou de contributeur d’espace de travail)

Conseil / Astuce

Pas un administrateur ? Vous pouvez compléter les deux premiers éléments vous-même. Pour le paramètre de locataire, demandez à votre administrateur de locataire Fabric d’activer « Les principaux de service peuvent utiliser les API Fabric » sous Portail d'administration>Paramètres du locataire>Paramètres du développeur. Pour les autorisations d’espace de travail, demandez à votre administrateur d’espace de travail d’accorder à votre principal de service l’accès à l’espace de travail ou à l’API GraphQL spécifique.

Une fois l’installation terminée, capturez ces trois valeurs pour la configuration du serveur MCP GraphQL :

ID de locataire : trouvé dans l'ID Microsoft Entra sous vue d’ensemble>ID de locataire
ID client : trouvé dans votre inscription d'application dans la section Vue d'ensemble>ID d'application (client)
Clé secrète client : valeur secrète affichée lorsque vous créez un secret client (copie immédiatement, il n’est affiché qu’une seule fois)

Étape 2 : Activer l’introspection GraphQL (nécessite l’administrateur de l’espace de travail)

Ce que vous faites : L’activation de l’introspection permet au serveur GraphQL MCP de demander à votre API GraphQL « Quelles données avez-vous ? » et de recevoir une description complète de tous les types, champs et relations disponibles.

Pourquoi cela est important : Il s’agit de la « magie » qui rend possible des requêtes en langage naturel. Lorsque vous demandez à Copilot « Afficher les clients », l’agent IA utilise d’abord l’introspection pour découvrir qu’un customers type existe, quels champs il a et comment l’interroger. Sans introspection, vous devrez documenter manuellement l’intégralité de votre schéma pour l’IA.

Important

L’introspection doit être activée pour que le serveur MCP GraphQL fonctionne. Cette option est désactivée par défaut dans Fabric pour des raisons de sécurité. Seuls les administrateurs d’espace de travail peuvent activer l’introspection. Si vous n’êtes pas administrateur, demandez à votre administrateur d’espace de travail d’effectuer cette étape.

Suivez le guide complet de l’API Microsoft Fabric pour GraphQL Introspection et l’exportation des schémas :

Activer l’introspection dans vos paramètres d’API
Comprendre le fonctionnement des requêtes d’introspection
En savoir plus sur les options d’exportation de schéma

Une fois l’introspection activée, le serveur GraphQL MCP peut interroger votre structure de schéma et le rendre disponible pour les agents IA.

Étape 3 : Configurer le serveur GraphQL MCP

Ce que vous faites : Installation et configuration d’un serveur de Node.js local qui implémente le protocole de contexte de modèle. Ce serveur agit en tant que traducteur entre les agents IA et votre API Fabric GraphQL.

Pourquoi cela est important : Le serveur MCP fournit une interface standardisée que les agents IA comprennent. Lorsqu’un agent IA se connecte, il peut découvrir quels outils sont disponibles (introspection et interrogation), appeler ces outils et recevoir des réponses, sans écrire de code d’intégration personnalisé pour chaque plateforme IA.

Maintenant que vous disposez d’informations d’identification d’authentification (étape 1) et d’introspection activées (étape 2), vous êtes prêt à configurer le serveur pour les utiliser.

Clonez l’exemple de dépôt

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

Installer des dépendances

npm install

Configurer les variables d’environnement

Créez un .env fichier à la racine du projet avec votre configuration :

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

Remplacez les valeurs d’espace réservé par :

MICROSOFT_FABRIC_API_URL : votre point de terminaison GraphQL à partir du portail Fabric
MICROSOFT_FABRIC_TENANT_ID : VOTRE ID de locataire Azure
MICROSOFT_FABRIC_CLIENT_ID : ID client d’inscription d’application
MICROSOFT_FABRIC_CLIENT_SECRET : secret client de l'enregistrement de votre application

Démarrer le serveur GraphQL MCP

node FabricGraphQL_MCP.js

Le serveur démarre sur http://localhost:3000 et s’affiche :

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

Outils MCP disponibles

Le serveur GRAPHQL MCP fournit deux outils principaux :

`introspect-schema`

Objectif : récupère le schéma GraphQL complet
Paramètres : Aucun
Utilisation : doit être appelée en premier avant d’effectuer des requêtes

`query-graphql`

Objectif : exécute des requêtes GraphQL sur vos données Fabric
Paramètres :
- query (obligatoire) : chaîne de requête GraphQL
- variables (facultatif) : Objet de variables GraphQL
Utilisation : pour toutes les opérations de récupération et de manipulation des données

Présentation du flux de travail

Le flux de travail GraphQL MCP classique suit ce modèle :

Découverte de schéma : l’agent IA doit d’abord appeler l’outil introspect-schema pour comprendre le schéma et les données disponibles
Planification des requêtes : Agent analyse votre demande de langage naturel et le schéma GraphQL
Génération de requêtes : Agent crée des requêtes GraphQL appropriées
Exécution : Agent appelle l’outil query-graphql avec les requêtes générées
Traitement des réponses : l’agent met en forme et présente les résultats

Étape 4 : Tester le serveur GRAPHQL MCP

Ce que vous faites : Vérifiez que votre serveur MCP peut s’authentifier auprès de Fabric, récupérer votre schéma et exécuter des requêtes avant de connecter des agents IA.

Pourquoi cela est important : Le test permet de vérifier manuellement que tout est configuré correctement. Si ces tests réussissent, vous savez que les agents IA sont en mesure de se connecter correctement à l’étape 5.

Vérifier l’intégrité du serveur

Tout d’abord, vérifiez que le serveur est en cours d’exécution et qu’il peut s’authentifier auprès de Fabric.

Utilisation de PowerShell :

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

Utilisation de cURL :

curl http://localhost:3000/health

Vous devez recevoir une réponse indiquant que le serveur est en cours d’exécution, comme suit :

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

Tester l'introspection des schémas

Ensuite, vérifiez que le serveur peut récupérer votre schéma GraphQL via l’introspection. Cela appelle l’outil introspect-schema MCP.

Utilisation de 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

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

Cela doit retourner votre définition de schéma GraphQL.

Tester une requête GraphQL

Enfin, testez l’exécution d’une requête GraphQL réelle via le serveur MCP. Cet exemple interroge tous les noms de types dans votre schéma à l’aide de l’outil query-graphql MCP.

Utilisation de 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

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

Cette opération renvoie une liste de tous les types dans votre schéma GraphQL.

Étape 5 : Connecter des agents IA

Ce que vous faites : Configuration d’outils IA pour utiliser votre serveur MCP local en tant que source de données.

Pourquoi cela est important : C’est là que tout se réunit. Une fois connectés, vos agents IA peuvent découvrir votre schéma Fabric via l’introspection et générer des requêtes GraphQL basées sur des requêtes en langage naturel. L’IA gère la syntaxe de requête : vous posez simplement des questions en anglais brut.

GitHub Copilot dans Visual Studio Code

Installer l’extension GitHub Copilot dans VS Code

Configurez le serveur MCP GraphQL dans vos paramètres Copilot :

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

Dans la conversation Copilot, commencez par demander à introspecter le schéma, puis essayez de poser une question pertinente liée aux données introspectées en langage naturel, par exemple :

Cursor IDE

Ouvrir les paramètres du curseur

Ajoutez la configuration du serveur MCP :

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

Dans la conversation, commencez par demander à introspecter le schéma, puis essayez de poser une question pertinente liée aux données introspectées dans le langage naturel.

Ce que vous avez créé

Félicitations! Vous disposez maintenant d’un serveur GraphQL MCP fonctionnel qui :

S’authentifie auprès de Fabric à l’aide des informations d’identification du principal de service
Exposez votre schéma de données Fabric grâce à l’introspection
Traduit les requêtes de l’agent IA en requêtes GraphQL
Retourne des données dans un format que les agents IA peuvent comprendre et présenter

Vos agents IA (comme GitHub Copilot) peuvent désormais :

Découvrir automatiquement les données disponibles dans votre espace de travail Fabric
Générer des requêtes GraphQL correctes basées sur des questions en langage naturel
Récupérer et mettre en forme les résultats sans écrire de code de requête

Ce serveur local est destiné au développement et à l’apprentissage. Les sections suivantes traitent des considérations importantes relatives aux déploiements de production et aux scénarios de résolution des problèmes courants.

Considérations relatives à la sécurité

Bien que le serveur GRAPHQL MCP local soit implémenté à des fins de développement uniquement comme décrit dans ce didacticiel, il est implémenté avec le transport HTTP, ce qui facilite son utilisation comme point de départ pour des intégrations client-serveur ou web plus complexes. Si vous déployez des serveurs MCP GraphQL en production :

Utiliser Azure Key Vault pour stocker des secrets au lieu de .env fichiers
Implémenter des règles d’autorisation, de sécurité réseau et de pare-feu appropriées
Activer la journalisation d’audit pour toutes les requêtes GraphQL
Utiliser Azure App Service ou Container Instances pour l’hébergement
Implémenter la limitation de débit et l’authentification pour les points de terminaison MCP
Renouveler régulièrement les secrets client et les certificats

Résolution des problèmes

Problèmes courants et solutions

Erreurs d'authentification

Vérifier que votre inscription d’application Azure dispose des autorisations appropriées
Vérifiez que les principaux de service sont activés dans votre locataire Fabric
Vérifiez que votre clé secrète client n’a pas expiré

Échec de l’introspection de schéma

Vérifiez que l’introspection est activée dans vos paramètres d’API GraphQL
Vérifiez que l’URL de votre point de terminaison GraphQL est correcte
Vérifier la connectivité réseau à votre espace de travail Fabric

L’agent IA ne reconnaît pas les outils

Redémarrez votre client IA après les modifications de configuration
Vérifier que l’URL du serveur MCP est accessible
Vérifier les journaux d’activité du serveur pour les messages d’erreur

Erreurs d’exécution de requête

Passez en revue la console du serveur pour les requêtes et erreurs journalisées
Vérifiez que vos requêtes correspondent au schéma disponible
Vérifiez que vous disposez des autorisations appropriées pour les données demandées

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-01-21

Partager via

Connecter des agents IA à l’API Fabric pour GraphQL avec un serveur MCP (Model Context Protocol) local

Qu’est-ce que le protocole MCP (Model Context Protocol) ?

Pourquoi GraphQL est idéal pour MCP

Conditions préalables

Étape 1 : Configurer l'accès au principal du service

Étape 2 : Activer l’introspection GraphQL (nécessite l’administrateur de l’espace de travail)

Étape 3 : Configurer le serveur GraphQL MCP

Clonez l’exemple de dépôt

Installer des dépendances

Configurer les variables d’environnement

Démarrer le serveur GraphQL MCP

Outils MCP disponibles

introspect-schema

query-graphql

Présentation du flux de travail

Étape 4 : Tester le serveur GRAPHQL MCP

Vérifier l’intégrité du serveur

Tester l'introspection des schémas

Tester une requête GraphQL

Étape 5 : Connecter des agents IA

GitHub Copilot dans Visual Studio Code

Cursor IDE

Ce que vous avez créé

Considérations relatives à la sécurité

Résolution des problèmes

Problèmes courants et solutions

Contenu connexe

Commentaires

Ressources supplémentaires

`introspect-schema`

`query-graphql`