Verbind AI-agenten met de gehoste OneLake MCP-server (preview)

De gehoste OneLake Model Context Protocol (MCP)-server stelt AI-agenten in staat bestanden te doorzoeken, metadata van tabellen te inspecteren en mappen in een Fabric-item te beheren zonder een lokale MCP-server te installeren. Verbind een MCP-compatibele client met het HTTPS-eindpunt van het item, gebruik vervolgens natuurtaalverzoeken of roep de tools direct aan.

De gehoste server biedt een item dataplane-verbinding en is een alternatief voor de lokale Fabric MCP-server. Voor werkruimte- en itembeheer, OneLake-snelkoppelingen en OneLake-datatoegangsrollen gebruik je de Fabric Core MCP-server. Verbind met elke server voor de benodigde bewerkingen.

Prerequisites

• Een Fabric-item dat data opslaat in OneLake, met een gehoste OneLake MCP-endpoint beschikbaar in je omgeving.
• Een Microsoft Entra-identiteit met toestemming om de bedoelde bewerkingen uit te voeren op de gegevens van het item.
• Een MCP-client die Streamable HTTP ondersteunt en een Microsoft Entra bearer-token aan verzoeken kan koppelen.
• Netwerktoegang tot het MCP-eindpunt en, voor directe bestandsoverdrachten, tot het teruggestuurde opslag-eindpunt.

Voor het permissiemodel, zie Data security in OneLake. Alleen toegang tot de werkruimte betekent niet dat elk account elk datapad kan lezen of schrijven. Zie Connect to OneLake voor netwerkvereisten.

Verbind met een item

Gebruik de gehoste OneLake MCP-endpoint-URL voor je werkruimte en item.

1. Voeg de URL toe aan de HTTP MCP-configuratie van je client. Configureer de authenticatie zoals beschreven in de volgende sectie en initialiseer vervolgens de verbinding.
2. Vraag de medewerker om onelake_list_items_data aan te roepen om de top-level datagebieden van het item te ontdekken zonder de data te wijzigen. Kies een geretourneerde map om te verkennen met onelake_list_files, met behulp van een item-relatief path. Ga er niet van uit dat elk item een Files map heeft.

Voor Visual Studio Code-instellingen en configuratielocaties, zie MCP-servers toevoegen in VS Code. De authenticatieconfiguratie hangt af van de client- en agentomgeving; het toevoegen van een URL logt je niet in.

Het item-eindpunt heeft het volgende pad:

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

Hier is {oneLakeHost} de HTTPS-oorsprong van je endpoint-URL, en de twee ID's identificeren de werkruimte en het item. Houd de hostnaam en het pad van het eindpunt bij elkaar. Vervang geen regionale of omgevingsspecifieke hostnaam door een andere OneLake-hostnaam.

Gebruik een GUID-geadresseerd eindpunt. Vriendelijke namen zijn beschikbaar als toolargumenten, zoals beschreven in Common parameters. Een naamgeadresseerde URL kan succesvol initialiseren, maar faalt wanneer een tool zijn URL-context gebruikt.

Verificatie en machtigingen

Gebruik een Microsoft Entra toegangstoken voor de Azure Storage-doelgroep, https://storage.azure.com/. Voor authenticatiebibliotheken die scopes accepteren, gebruik https://storage.azure.com/.default. Vervang geen token door https://api.fabric.microsoft.com/.

Stuur het token in de Authorization: Bearer <access-token> header bij elk verzoek. Voor het instellen van verificatie, zie Authenticatie voorbereiden.

De client is verantwoordelijk voor het verkrijgen en verversen van zijn token. Aanmelden bij de Azure CLI authenticeert niet automatisch een willekeurige HTTP MCP-client. Gebruik het ondersteunde credentialmechanisme van je cliënt en plaats geen tokens in chat, gedeelde configuratiebestanden of versiebeheer.

OneLake evalueert de rechten van de beller voor elke bewerking. Het verbinden van een agent geeft hem geen extra data-toegang. Houd gebruikersgoedkeuring ingeschakeld voor schrijfbewerkingen en verwijderingen, en bekijk het doelitem en het pad voordat je ze goedkeurt.

MCP-verbinding en detectie

Het eindpunt gebruikt JSON-RPC 2.0 via Streamable HTTP. Elk MCP-bericht is een aparte HTTP POST naar hetzelfde eindpunt.

Initialiseer de verbinding met de door je client ondersteunde protocolversie en stuur notifications/initialized dan. De server onderhandelt protocolversie 2025-06-18 en identificeert zichzelf als microsoft.onelake, versie 1.0.0. De mogelijkheden omvatten logging en tools, met tools.listChanged: true. Gebruik de onderhandelde waarden in plaats van de serverversie hardcoded vast te leggen.

Ontdek de tools met dit verzoek:

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

Lees van elk item de description, inputSchema, annotations en name. Als een reactie result.nextCursor bevat, geef het door als params.cursor om de volgende pagina te krijgen. Ververs de detectie wanneer de server notifications/tools/list_changed verzendt.

De hier beschreven catalogus bevat 15 gereedschappen: 11 gemarkeerd als alleen-lezen en idempotent, en vier gemarkeerd als destructief. Tool-annotaties beschrijven gedrag; het zijn geen machtigingen. De server biedt voor deze tools geen outputSchema.

Toolreferentie

Gebruik de exacte toolnamen en het hoofdlettergebruik van parameters die door tools/list worden geretourneerd. De volgende tabellen behandelen alle parameters in deze catalogus. Ontdek de huidige schema's bij het verbinden, omdat de beschikbare tools kunnen veranderen. Bestandstools gebruiken de API voor het gedistribueerde bestandssysteem (DFS) of de Blob API van OneLake.

Algemene parameters

Elke tool accepteert deze optionele parameters naast zijn tool-specifieke parameters:

Normaal gesproken laat je beide parameters weg om met het item in de URL te werken. Wanneer je expliciet een doel specificeert, gebruik dan beide GUID's of beide namen. URL-scoping levert standaardinstellingen; het verwijdert deze targetingparameters niet en vervangt de machtiging niet.

De schema's declareren deze parameters als strings met als defaultnull. Laat een optionele tekenreeks weg om de standaardwaarde te gebruiken in plaats van JSON null te verzenden: JSON null is niet opgenomen in het gedeclareerde type. Deze regel geldt ook voor path, prefix, schemaName, en contentType waar die strings optioneel zijn.

Bestands- en directorypaden zijn relatief aan het item, zoals Files/incoming/orders.csv of Tables/dbo/orders. Neem de werkruimte- of item-id niet op in een path-argument.

Blader door en lees gegevens

De server markeert deze tools als alleen-lezen en idempotent.

Begin met een smalle path of prefix. Recursieve vermeldingen en brede Blob-vermeldingen kunnen meer data opleveren dan een agent nodig heeft.

Tabelmetadata inspecteren

De server markeert deze tools als alleen-lezen en idempotent. Ze inspecteren de metadata, niet de tabelrijen.

Gebruik een naamruimte die wordt teruggegeven door onelake_list_namespaces in plaats van aan te nemen dat elk item dezelfde schema's heeft. Voor de onderliggende API's, zie OneLake-tabel API's.

Ontvang instructies voor bestandsoverdracht

De server markeert deze tools als alleen-lezen en idempotent. Ze geven instructies terug, maar zetten geen bestandsbytes over. Het uitvoeren van een uploadinstructie is een aparte schrijfoperatie.

Gebruik onelake_get_upload_instructions voor een upload. De catalogus bevat geen inline uploadtool, hoewel de beschrijving van de upload-instructietool verwijst naar uploadFile. Gebruik evenzo de geadverteerde naam onelake_download_file, niet de downloadFile afkorting in de beschrijving van de download-instructietool.

Een upload-instructieresultaat bevat een resource_link inhoudsblok. Het uri is de bestemming, en _meta omvat method, tokenAudience, path, en overwrite. Het resultaat bevat ook tekstbegeleiding. De link bevat geen bestandsbytes en verleent geen toegang tot de doellocatie.

Verifieer de overdracht afzonderlijk voor de geretourneerde doelgroep. Controleer voordat je een commando uitvoert de bestemming en het overschrijfgedrag. Gegenereerde tekst kan een hostnaam bevatten die verschilt van de resourcelink, of aangeven dat een klein bestand de inline-limiet overschrijdt. Voer conflicterende instructies niet ongewijzigd uit; verifieer de bestemming aan de hand van de opslagverbindingsgegevens van het item.

Maak mappen of bestanden aan en verwijder ze

De server markeert deze vier tools als destructief. Vraag om bevestiging voordat je ze uitvoert.

De toolbeschrijvingen waarschuwen dat verwijdering van bestanden en blobs onomkeerbaar is. Gebruik deze tools niet om bestanden uit een tabel te verwijderen als vervanging voor een tabelbewuste onderhoudsoperatie.

Lees de resultaten van de tool

Een MCP-toolcall geeft een JSON-RPC result met een content array terug. Inspecteer de type van elk blok; ga er niet van uit dat elk gereedschap direct een JSON-object teruggeeft.

Behandel zowel JSON HTTP-antwoorden als text/event-stream antwoorden. Voor het laatste verwerk je de JSON-RPC-berichten die door server-sent events worden meegeleverd. Bekijk de resultaten van het MCP-instrument.

Metadata-payloads hebben verschillende vormen:

• DFS-lijsten geven Paths, een array van objecten, en kunnen ContinuationToken bevatten, wat null kan zijn. Elk pad omvat Name (string), IsDirectory (booleaan), ContentLength (geheel getal), LastModified (string), ETag (string), Owner (string) en Permissions (string).
• Blob-lijsten geven een Blobs array terug. Elementen omvatten ETag, IsPrefix, LastModified, ContentType, ContentLength en de booleaan Name. Een leeg ContentType is een string, niet null.
• Naamruimtevermeldingen geven namespaces terug als een array van arrays van strings, zoals [["dbo"]], en kunnen next-page-token bevatten.
• Details van de naamruimte worden teruggegeven als namespace een string, exists een boolean en tables een JSON-gecodeerde string. Parse tables afzonderlijk om de geneste tabellijst te inspecteren.
• Toegangsresultaten omvatten workspaceId, itemId, de booleaanse vlaggen canRead, canWrite, en canExecute, plus stringvelden owner en permissions. Deze strings kunnen leeg zijn.

Behoud veldcasing en onderscheid weggelaten eigenschappen, null, lege strings en lege arrays. Verwerk velden die je client begrijpt zonder een volledig antwoord af te wijzen wanneer er extra velden verschijnen.

Voorbeeld: bekijk de bestanden van een item

Nadat je verbinding hebt gemaakt met een lakehouse en hebt bevestigd dat het onelake_list_items_data een Files directory terugstuurt, vraag je aan je agent:

"Vermeld de mappen onder Bestanden in dit item. Verander geen data."

De bijbehorende toolroep is:

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

Het volgende is de volledige gedecodeerde JSON van het eerste result.content[].text blok van de respons, niet de JSON-RPC envelop. Item- en eigenaar-ID's, directorynamen, tijdstempels en ETags zijn illustratief.

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

Beide vermeldingen zijn directories. Hun ContentLength waarden geven niet de totale grootte van de bestanden eronder weer. Om de eerste map te bekijken, roep onelake_list_files aan met path: "Files/incoming". De teruggegeven Name bevat de item-ID, maar de path van de volgende tool is item-relatief.

Andere taken die u uw agent kunt laten uitvoeren zijn:

• Vermeld de naamruimtes in dit lakehouse en toon dan de metadata van een tabel die ik selecteer.
• Lees het JSON-configuratiebestand in Files/config/settings.json.
• "Downloadinstructies voor Files/exports/orders.parquet ophalen. Draag het nog niet over.

Fouten en beperkingen

Controleer de HTTP-status, een topniveau-JSON-RPC error, en result.isError. HTTP 200 alleen betekent niet dat een tool succesvol is.

Een ontbrekend bestand kan bijvoorbeeld deze volledige JSON-RPC teruggeven:

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

Aanvullende beperkingen:

• Opslag- en tabelvermeldingen maken in deze catalogus geen continuation-token invoerparameters zichtbaar. Ga er niet van uit dat een listing uitputtend is wanneer deze een limiet bereikt of een voortzettingstoken teruggeeft. Gebruik de onderliggende OneLake-bestands-API's of tabel-API's wanneer je paginering nodig hebt.
• maxResults beperkt een Blob-lijst; het is geen pagineringscursor.

Verwante onderwerpen

• Referentie voor Fabric Core MCP-servertools.
• Gebruik de lokale Fabric MCP-server met OneLake.
• Maak verbinding met OneLake.
• OneLake table APIs overview.
• Gegevensbeveiliging in OneLake.