Connectez les agents IA au serveur MCP hébergé OneLake (aperçu)

Le serveur OneLake Model Context Protocol (MCP) hébergé permet aux agents IA de parcourir les fichiers, d’inspecter les métadonnées des tables et de gérer des répertoires dans un élément Fabric sans installer de serveur MCP local. Connectez un client compatible MCP au point de terminaison HTTPS de l’item, puis utilisez des requêtes en langage naturel ou appelez directement les outils.

Le serveur hébergé fournit une connexion au plan de données des éléments et constitue une alternative au serveur Fabric MCP local. Pour la gestion des espaces de travail et des éléments, les raccourcis OneLake et les rôles d’accès aux données OneLake, utilisez le serveur MCP Fabric Core. Connectez-vous à chaque serveur pour effectuer les opérations dont vous avez besoin.

Prerequisites

• Un élément Fabric qui stocke les données dans OneLake, avec un point de terminaison OneLake MCP hébergé disponible dans votre environnement.
• Une identité Microsoft Entra avec la permission d'effectuer les opérations prévues sur les données de l’élément.
• Un client MCP qui prend en charge Streamable HTTP et peut attacher un bearer token Microsoft Entra aux requêtes.
• l’accès réseau au point de terminaison MCP et, pour les transferts directs de fichiers, au point de terminaison de stockage retourné.

Pour le modèle des permissions, voir Sécurité des données dans OneLake. L’accès à l’espace de travail seul ne signifie pas que chaque identité peut lire ou écrire chaque chemin de données. Pour les besoins en réseau, voir Se connecter à OneLake.

Se connecter à un élément

Utilisez l’URL hébergée du point de terminaison OneLake MCP pour votre espace de travail et votre élément.

1. Ajoutez l’URL à la configuration HTTP MCP de votre client. Configurez l’authentification comme décrit dans la section suivante, puis initialisez la connexion.
2. Demandez à l’agent d’appeler onelake_list_items_data pour découvrir les zones de données de premier niveau de l’article sans modifier les données. Choisissez un répertoire renvoyé à explorer avec onelake_list_files, en utilisant un élément relatif path. Ne supposez pas que chaque élément ait un Files répertoire.

Pour les emplacements d’installation et de configuration de Visual Studio Code, voir Ajouter des serveurs MCP dans VS Code. La configuration de l’authentification dépend du client et de l’environnement de l’agent ; ajouter une URL ne vous permet pas de vous connecter.

L’endpoint de l’élément a le chemin suivant :

POST {oneLakeHost}/v1.0/workspaces/{workspaceId}/items/{itemId}/mcp

Ici, {oneLakeHost} c’est l’origine HTTPS de l’URL du point de terminaison, et les deux identifiants identifient l’espace de travail et l’élément. Gardez le nom d’hôte et le chemin du point de terminaison ensemble. Ne remplacez pas un nom d’hôte régional ou spécifique à l’environnement par un autre nom d’hôte OneLake.

Utilisez un point de terminaison adressé par GUID. Les noms conviviaux sont disponibles comme arguments d’outil, comme décrit dans les paramètres Communs. Une URL adressée par nom peut être initialisée avec succès mais échouer lorsqu’un outil utilise son contexte URL.

Authentification et autorisations

Utilisez un token d’accès Microsoft Entra pour l’audience stockage Azure, https://storage.azure.com/. Pour les bibliothèques d’authentification acceptant des scopes, utilisez https://storage.azure.com/.default. Ne remplacez pas un jeton par https://api.fabric.microsoft.com/.

Envoyez le jeton dans l’en-tête Authorization: Bearer <access-token> pour chaque demande. Pour la configuration de l’authentification, voir Préparer l’authentification.

Le client est responsable de l’obtention et de la mise à jour de son jeton. Se connecter à Azure CLI n'authentifie pas automatiquement un client HTTP MCP arbitraire. Utilisez le mécanisme d’identifiants supporté par votre client, et ne mettez pas de jetons dans le chat, les fichiers de configuration partagés ou le contrôle de version.

OneLake évalue les autorisations de l’appelant pour chaque opération. Connecter un agent ne lui accorde pas un accès supplémentaire aux données. Gardez l’approbation utilisateur activée pour les écritures et suppressions, et examinez l’élément cible et le chemin avant de les approuver.

Connexion et découverte MCP

Le point de terminaison utilise JSON-RPC 2.0 via HTTP streamable. Chaque message MCP est un HTTP POST distinct vers le même point de terminaison.

Initialisez la connexion avec la version du protocole prise en charge par votre client, puis envoyez notifications/initialized. Le serveur négocie la version 2025-06-18 du protocole et s’identifie comme microsoft.onelake, version 1.0.0. Ses capacités incluent logging et tools, avec tools.listChanged: true. Utilisez les valeurs négociées plutôt que de coder en dur la version serveur.

Découvrez les outils dans cette requête :

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Lisez chaque name, description, inputSchema et annotations. Si une réponse inclut result.nextCursor, transmettez-la comme params.cursor pour obtenir la page suivante. Rafraîchir la découverte lorsque le serveur envoie notifications/tools/list_changed.

Le catalogue décrit ici contient 15 outils : 11 marqués en lecture seule et idempotents, et quatre marqués destructeurs. Les annotations d’outils décrivent le comportement ; ce ne sont pas des autorisations. Le serveur n’annonce pas outputSchema pour ces outils.

Informations de référence sur l’outil

Utilisez les noms exacts des outils et la casse des paramètres retournés par tools/list. Les tableaux suivants couvrent tous les paramètres de ce catalogue. Découvrez les schémas de base de données actuels lors de la connexion, car les outils disponibles peuvent changer. Les outils de fichiers utilisent l’API du système de fichiers distribué (DFS) ou API Blob de OneLake.

Paramètres courants

Chaque outil accepte ces paramètres optionnels en plus de ses paramètres spécifiques à l’outil :

Normalement, omettez les deux paramètres pour travailler avec l’élément dans l’URL. Lorsque vous spécifiez explicitement une cible, utilisez les deux GUID ou les deux noms. La portée de l’URL fournit les paramètres par défaut ; elle ne supprime pas ces paramètres de ciblage ni ne remplace l’autorisation.

Les schémas déclarent ces paramètres comme des chaînes ayant une valeur default de null. Omettre une chaîne optionnelle pour utiliser sa chaîne par défaut plutôt que d’envoyer du JSON null: null n’est pas inclus dans son type déclaré. Cette règle s’applique également à path, prefix, schemaName, et contentType lorsque ces chaînes sont optionnelles.

Les chemins de fichiers et de répertoires sont relatifs à l’élément, tels que Files/incoming/orders.csv ou Tables/dbo/orders. N’incluez pas l’espace de travail ou l’identifiant d’élément dans un argument path.

Parcourez et lisez les données

Le serveur marque ces outils comme en lecture seule et idempotents.

Commencez par un étroit path ou prefix. Les listes récursives et les listages Blob étendus peuvent produire plus de données qu’un agent n’en a besoin.

Inspectez les métadonnées de la table

Le serveur marque ces outils comme en lecture seule et idempotents. Ils inspectent les métadonnées, pas les lignes de tableaux.

Utilisez un espace de noms retourné par onelake_list_namespaces plutôt que de supposer que chaque élément possède les mêmes schémas. Pour les API sous-jacentes, voir OneLake table APIs.

Obtenir les instructions de transfert de fichiers

Le serveur marque ces outils comme en lecture seule et idempotents. Ils renvoient les instructions mais ne transfèrent pas les octets du fichier. L’exécution d’une instruction de téléversement est une opération d’écriture distincte.

Utilisez onelake_get_upload_instructions pour un téléchargement. Le catalogue n’inclut pas d’outil de téléversement en ligne, même si la description de l’outil d’instructions de téléversement fait référence à uploadFile. De même, utilisez le nom onelake_download_fileannoncé, et non l’abrégé downloadFile dans la description de l’outil d’instructions de téléchargement.

Un résultat d’instruction de téléchargement inclut un bloc de contenu resource_link. Sa uri est la destination, et _meta inclut method, tokenAudience, path et overwrite. Le résultat inclut également des indications textuelles. Le lien ne contient pas les octets du fichier ni n’accorde l’accès à la destination.

Authentifiez le transfert séparément pour l'audience renvoyée. Avant d’exécuter une commande, vérifiez sa destination et le comportement d’écrasement. Le texte généré peut contenir un nom d’hôte différent du lien de ressources, ou indiquer qu’un petit fichier dépasse la limite d’incorporation. N’exécutez pas les instructions contradictoires telles quelles ; vérifiez la destination par rapport aux informations de connexion de stockage de l’objet.

Créer et supprimer des répertoires ou des fichiers

Le serveur considère ces quatre outils comme destructeurs. Exigez une confirmation avant de les invoquer.

Les descriptions des outils avertissent que la suppression de fichiers et de blobs est irréversible. N’utilisez pas ces outils pour retirer des fichiers d’une table en remplacement d’une opération de maintenance adaptée à la table.

Lire les résultats de l’outil

Un appel d’outil MCP renvoie un JSON-RPC result avec un tableau content. Inspectez le type de chaque bloc ; ne supposez pas que chaque outil renvoie directement un objet JSON.

Gérer à la fois les réponses HTTP JSON et les réponses text/event-stream. Dans ce cas, traitez les messages JSON-RPC transportés par les événements envoyés par le serveur. Voir les résultats de l’outil MCP.

Les charges de métadonnées se présentent sous différentes formes :

• Les listings DFS retournent Paths, un tableau d’objets, et peuvent inclure ContinuationToken, qui peuvent être null. Chaque chemin comprend Name (chaîne), IsDirectory (booléen), ContentLength (entier), LastModified (chaîne), ETag (chaîne), Owner (chaîne) et Permissions (chaîne).
• Les listes de blobs renvoient un Blobs tableau. Les entrées incluent Name, ContentLength, ContentType, LastModified, ETag, et le booléen IsPrefix. Une chaîne vide ContentType est une chaîne, et non null.
• Les listes d’espaces de noms sont retournées namespaces sous forme d’un tableau de tableaux de chaînes, comme [["dbo"]], et peuvent inclure next-page-token.
• Les détails de l’espace de noms renvoient namespace sous forme de chaîne, exists sous forme de booléen, et tables sous forme de chaîne encodée en JSON. Analysez tables séparément pour inspecter la liste de tableaux imbriqués.
• Les résultats d’accès incluent canRead, canWrite, les indicateurs booléens canExecute, owner et permissions, ainsi que les champs de chaîne itemId et workspaceId. Ces chaînes peuvent être vides.

Préserver la casse du champ et distinguer les propriétés omises, null, les chaînes vides et les tableaux vides. Traitez les champs que votre client comprend sans rejeter une réponse complète lorsque des champs supplémentaires apparaissent.

Exemple : explorer les fichiers d’un objet

Après s’être connecté à un lakehouse et avoir confirmé que onelake_list_items_data renvoie un répertoire Files, demandez à votre agent :

Listez les répertoires sous Fichiers dans cet élément. Ne modifie aucune donnée.

L’appel correspondant à l’outil est :

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "onelake_list_files",
    "arguments": {
      "path": "Files",
      "recursive": false
    }
  }
}

Voici le JSON complet décodé à partir du premier bloc result.content[].text de la réponse, et non l’enveloppe JSON-RPC. Les identifiants d’éléments et de propriétaires, les noms d’annuaire, les horodatages et les ETags sont illustratifs.

{
  "Paths": [
    {
      "Name": "87654321-4321-4321-8321-cba987654321/Files/incoming",
      "IsDirectory": true,
      "ContentLength": 0,
      "LastModified": "Wed, 21 Oct 2026 10:00:00 GMT",
      "ETag": "0x8DE000000000001",
      "Owner": "11111111-2222-4333-8444-555555555555",
      "Permissions": "rwxr-x---"
    },
    {
      "Name": "87654321-4321-4321-8321-cba987654321/Files/archive",
      "IsDirectory": true,
      "ContentLength": 0,
      "LastModified": "Tue, 20 Oct 2026 10:00:00 GMT",
      "ETag": "0x8DE000000000002",
      "Owner": "11111111-2222-4333-8444-555555555555",
      "Permissions": "rwxr-x---"
    }
  ],
  "ContinuationToken": null
}

Les deux entrées sont des répertoires. Leurs valeurs ContentLength ne représentent pas la taille totale des fichiers qu’ils contiennent. Pour explorer le premier répertoire, appelez onelake_list_files avec path: "Files/incoming". L’élément renvoyé Name inclut l’identifiant de l’article, mais le path de l’outil suivant est relatif à l’article.

D’autres tâches que vous pouvez demander à votre agent d’accomplir incluent :

• Répertoriez les espaces de noms dans ce lakehouse, puis affichez les métadonnées d’une table que je sélectionne.
• Lisez le fichier de configuration JSON dans Files/config/settings.json.
• « Obtenez les instructions de téléchargement pour Files/exports/orders.parquet. Ne le transférez pas encore. »

Erreurs et limites

Vérifiez le statut HTTP, un JSON-RPC error de premier niveau, et result.isError. HTTP 200 seul ne signifie pas qu’un outil a réussi.

Par exemple, un fichier manquant peut renvoyer cette réponse complète JSON-RPC :

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "The requested path or resource was not found."
      }
    ],
    "isError": true
  },
  "id": 27,
  "jsonrpc": "2.0"
}

Limitations supplémentaires :

• Les listings du stockage et des tableaux n’exposent pas les paramètres d’entrée des jetons de continuation dans ce catalogue. Ne supposez pas qu’une liste est exhaustive lorsqu’elle atteint une limite ou renvoie un jeton de continuation. Utilisez les API de fichiers OneLake sous-jacentes ou les API de table lorsque vous avez besoin de pagination.
• maxResults limite une liste de Blob ; ce n’est pas un curseur de pagination.

Contenu connexe

• Référence des outils du serveur MCP Fabric Core.
• Utilisez le serveur Fabric MCP local avec OneLake.
• Connectez-vous à OneLake.
• Aperçu des API de tableaux OneLake.
• Sécurité des données dans OneLake.