Connetti gli agenti AI al server MCP ospitato da OneLake (anteprima)

Il server OneLake Model Context Protocol (MCP) ospitato consente agli agenti IA di sfogliare i file, ispezionare i metadati delle tabelle e gestire le directory in un elemento Fabric senza installare un server MCP locale. Collega un client compatibile MCP all'endpoint HTTPS dell'item, poi usa richieste in linguaggio naturale o chiama direttamente gli strumenti.

Il server ospitato fornisce una connessione item-data-plane ed è un'alternativa al server Fabric MCP locale. Per la gestione di workspace e elementi, scorciatoie OneLake e ruoli di accesso dati OneLake, usa il server MCP Fabric Core. Connettiti a ogni server per le operazioni di cui hai bisogno.

Importante

Il server OneLake MCP ospitato è attualmente in anteprima pubblica. Le funzionalità e il comportamento potrebbero cambiare prima della disponibilità generale.

Prerequisites

  • Un elemento Fabric che memorizza i dati in OneLake, con un endpoint OneLake MCP ospitato disponibile nel tuo ambiente.
  • Un'identità Microsoft Entra con permesso di eseguire le operazioni previste sui dati dell'elemento.
  • Un client MCP che supporta HTTP streamable e può collegare un token bearer di Microsoft Entra alle richieste.
  • Accesso di rete all'endpoint MCP e, per trasferimenti file diretti, all'endpoint di archiviazione restituito.

Per il modello dei permessi, vedi Data Security in OneLake. L'accesso allo spazio di lavoro da solo non significa che ogni identità possa leggere o scrivere ogni percorso dati. Per le esigenze di rete, vedi Connect to OneLake.

Connettiti a un elemento

Usa l'URL dell'endpoint MCP ospitato di OneLake per il tuo spazio di lavoro e il tuo artefatto.

  1. Aggiungi l'URL alla configurazione HTTP MCP del tuo client. Configura l'autenticazione come descritto nella sezione successiva, poi inizializza la connessione.
  2. Chiedi all'agente di chiamare onelake_list_items_data per scoprire le aree dati di primo livello dell'articolo senza modificare i dati. Scegli una directory restituita da esplorare con onelake_list_files, usando un item-relativo path. Non dare per scontato che ogni elemento abbia una Files directory.

Per i percorsi di installazione e configurazione di Visual Studio Code, vedi Aggiungi server MCP in VS Code. La configurazione dell'autenticazione dipende dall'ambiente client e agente; aggiungere un URL non ti fa accedere.

L'endpoint dell'item segue questo percorso:

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

Qui {oneLakeHost} è l'origine HTTPS dal tuo URL endpoint, e i due ID identificano lo spazio di lavoro e l'elemento. Mantieni insieme il nome host e il percorso dell'endpoint. Non sostituire un nome host regionale o specifico per l'ambiente con un altro nome host OneLake.

Usa un endpoint indirizzato tramite GUID. I nomi descrittivi sono disponibili come argomenti dello strumento, come descritto in Parametri comuni. Un URL indirizzato per nome può inizializzare con successo ma fallire quando uno strumento utilizza il suo contesto URL.

Note

Se l'inizializzazione restituisce 404, confermare la disponibilità di oggetto, ambiente e endpoint prima di configurare l'agente.

Autenticazione e autorizzazioni

Usa un token di accesso Microsoft Entra per l'audience di Archiviazione di Azure, https://storage.azure.com/. Per le librerie di autenticazione che accettano scope, usa https://storage.azure.com/.default. Non sostituire un token con https://api.fabric.microsoft.com/.

Invia il token nell'intestazione Authorization: Bearer <access-token> di ogni richiesta. Per la configurazione dell'autenticazione, vedi Prepararsi all'autenticazione.

Il cliente è responsabile dell'ottenimento e del refresh del proprio token. L'accesso ad interfaccia della riga di comando di Azure non autentica automaticamente un client HTTP MCP arbitrario. Usa il meccanismo di credenziali supportato dal tuo cliente e non mettere token in chat, file di configurazione condivise o controllo del codice sorgente.

OneLake valuta i permessi del chiamante per ogni operazione. Collegare un agente non gli concede accesso aggiuntivo ai dati. Mantieni attivata l'approvazione dell'utente per le operazioni di scrittura e cancellazione, e rivedi l'elemento di destinazione e il percorso prima di approvarli.

Connessione e scoperta MCP

L'endpoint utilizza JSON-RPC 2.0 tramite HTTP streamabile. Ogni messaggio MCP è un HTTP POST separato allo stesso endpoint.

Intestazione Value
Authorization Bearer <access-token>.
Content-Type application/json.
Accept application/json, text/event-stream.
MCP-Protocol-Version La versione negoziata durante l'inizializzazione, nelle richieste successive.
Mcp-Session-Id L'ID della sessione del server, se l'inizializzazione ne restituisce uno. Invialo nelle richieste successive.

Inizializza la connessione con la versione del protocollo supportata dal tuo client, poi invia notifications/initialized. Il server negozia la versione 2025-06-18 del protocollo e si identifica come microsoft.onelake, versione 1.0.0. Le sue capacità includono logging e tools, con tools.listChanged: true. Usa i valori negoziati invece di codificare direttamente la versione server.

Scopri gli strumenti con questa richiesta:

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

Leggi name, description, inputSchema e annotations di ogni voce. Se una risposta include result.nextCursor, passala come params.cursor per ottenere la pagina successiva. Aggiorna il discovery quando il server invia notifications/tools/list_changed.

Il catalogo descritto qui contiene 15 strumenti: 11 contrassegnati come solo lettura e idempotenti, e quattro contrassegnati come distruttivi. Le annotazioni degli strumenti descrivono il comportamento; non sono concessioni di permesso. Il server non annuncia un outputSchema per questi strumenti.

Informazioni di riferimento per gli strumenti

Usa i nomi esatti degli strumenti e il casing dei parametri restituiti da tools/list. Le seguenti tabelle coprono tutti i parametri di questo catalogo. Scopri gli schema correnti durante la connessione, perché gli strumenti disponibili possono cambiare. Gli strumenti file utilizzano l'API del sistema file distribuito (DFS) o API Blob di OneLake.

Parametri comuni

Ogni strumento accetta questi parametri opzionali oltre ai parametri specifici dello strumento:

Parametro Tipo JSON Description
workspaceId Stringa GUID o nome dello spazio di lavoro. Se ometti questo parametro, l'endpoint utilizza il suo contesto di workspace.
itemId Stringa GUID o nome dell'elemento. Per i nomi, usare itemName.itemType, come Sales.Lakehouse. Se ometti questo parametro, l'endpoint usa il contesto del suo item.

Normalmente, omettere entrambi i parametri per lavorare con l'elemento nell'URL. Quando specifichi esplicitamente una destinazione, usa entrambi i GUID o entrambi i nomi. L'ambito degli URL fornisce valori predefiniti; non rimuove questi parametri di targeting né sostituisce l'autorizzazione.

Gli schemi dichiarano questi parametri come stringhe con un default di null. Ometti una stringa opzionale per usare il valore predefinito invece di inviare JSON null: null non è compreso nel tipo dichiarato. Questa regola si applica anche a path, prefix, schemaName, e contentType dove quelle stringhe sono opzionali.

I percorsi di file e directory sono relativi all'elemento, come Files/incoming/orders.csv o Tables/dbo/orders. Non includere lo spazio di lavoro o l'identificatore dell'oggetto in un argomento path.

Sfoglia e leggi i dati

Il server segna questi strumenti come in sola lettura e idempotenti.

Tool Parametri obbligatori Parametri opzionali, escludendo i parametri comuni Purpose
onelake_list_files None. path: stringa, radice dell'item se omesso. recursive: booleano, valore predefinito false. Elenco file e directory tramite l'API DFS, inclusi metadati come proprietario, permessi ed ETag.
onelake_blob_list None. prefix: stringa, nessun filtro se omesso. maxResults: intero, predefinito 100. Elenca i blob tramite l'API Blob, con nomi, lunghezze, tipi di contenuto e tempi di modifica.
onelake_list_items_data None. None. Elenca le aree dati di primo livello dell'elemento. Questo strumento non elenca gli elementi Fabric in uno spazio di lavoro.
onelake_read_file path: string. None. Leggi un piccolo file di testo tramite l'API DFS.
onelake_download_file path: string. None. Scarica tramite l'API Blob. Il server pubblicizza risorse embedded inline per file fino a 4 MB e istruzioni di trasferimento diretto per file più grandi.
onelake_get_principal_access None. None. Ottieni i flag di accesso segnalati e i metadati del controllo di accesso. Consulta la limitazione del flag di accesso in questa sezione prima di utilizzare questo risultato.

Inizia con uno stretto path o prefix. Gli elenchi ricorsivi e gli elenchi Blob estesi possono produrre più dati di quanti ne servano a un agente.

Importante

onelake_get_principal_access può segnalare canRead: false anche quando lo stesso chiamante riesce a leggere l'oggetto. Non usare questo strumento come meccanismo di autorizzazione. OneLake fa rispettare i permessi sull'operazione richiesta. Usa il risultato di quell'operazione e il modello di sicurezza OneLake per diagnosticare l'accesso.

Ispeziona i metadati della tabella

Il server segna questi strumenti come in sola lettura e idempotenti. Ispezionano i metadati, non le righe delle tabelle.

Tool Parametri obbligatori Parametri opzionali, escludendo i parametri comuni Purpose
onelake_list_namespaces None. None. Elenca gli identificatori degli spazi di nomi Iceberg tramite l'API della tabella.
onelake_get_namespace namespace: string. None. Ottieni i dettagli del namespace, incluso il payload restituito della lista delle tabelle.
onelake_get_table_config tableName: string. schemaName: string. La descrizione specifica dbo quando viene omesso; il default dello schema è null. Ottieni i metadati della tabella, descritti dal server come formato, colonne dello schema, informazioni sulla partizione e metadati delle versioni.

Usa uno spazio dei nomi restituito da onelake_list_namespaces invece di assumere che ogni elemento abbia gli stessi schemi. Per le API sottostanti, vedi OneLake Table APIs.

Ottieni istruzioni per il trasferimento di file

Il server segna questi strumenti come in sola lettura e idempotenti. Restituiscono le istruzioni ma non trasferiscono byte del file. L'esecuzione di un'istruzione di upload è un'operazione di scrittura separata.

Tool Parametri obbligatori Parametri opzionali, escludendo i parametri comuni Purpose
onelake_get_download_instructions path: string. None. Ottieni un link a una risorsa e istruzioni per scaricare un file direttamente da OneLake.
onelake_get_upload_instructions path: string. sizeBytes: intero, predefinito 0, per la visualizzazione. contentType: stringa, omessa di default. overwrite: booleano, valore predefinito false. Ottieni un link a una risorsa e istruzioni per caricare in un percorso di destinazione.

Usare onelake_get_upload_instructions per un caricamento. Il catalogo non include uno strumento di upload inline, anche se la descrizione dello strumento di istruzioni di caricamento si riferisce a uploadFile. Allo stesso modo, usa il nome onelake_download_fileusato nel materiale promozionale, non l'abbreviazione downloadFile nella descrizione dello strumento di istruzioni per il download.

Il risultato delle istruzioni di caricamento include un blocco di contenuto resource_link. La sua uri è la destinazione e _meta include method, tokenAudience, path e overwrite. Il risultato include anche indicazioni testuali. Il link non contiene i byte del file né concede l'accesso alla destinazione.

Autentica il trasferimento separatamente per i destinatari restituiti. Prima di eseguire un comando, controlla la destinazione e il comportamento di sovrascrittura. Il testo generato può contenere un nome host che differisce dal link delle risorse, oppure dire che un piccolo file supera il limite inline. Non eseguire istruzioni contrastanti senza modifiche; verifica la destinazione rispetto alle informazioni di connessione di archiviazione dell'oggetto.

Crea ed elimina directory o file

Il server contrassegna questi quattro strumenti come distruttivi. Richiedi una conferma prima di invocarli.

Tool Parametri obbligatori Parametri opzionali, escludendo i parametri comuni Purpose
onelake_create_directory path: string. None. Crea una directory e tutte le directory genitori necessarie.
onelake_delete_directory path: string. recursive: booleano, valore predefinito false. Elimina una directory; la cancellazione ricorsiva include i suoi contenuti.
onelake_delete_file path: string. None. Elimina un file tramite l'API DFS.
onelake_blob_delete path: string. None. Elimina un blob tramite l'API Blob.

Le descrizioni degli strumenti avvertono che la cancellazione di file e blob è irreversibile. Non usare questi strumenti per rimuovere file da una tabella in sostituzione di un'operazione di manutenzione specifica per tabelle.

Visualizza i risultati dello strumento

Una chiamata a uno strumento MCP restituisce un JSON-RPC result con un content array. Ispeziona il type di ogni blocco; non presumere che ogni strumento restituisca direttamente un oggetto JSON.

Tipo di contenuto Come usarlo
text Leggi text come una stringa. Gli strumenti di metadati possono serializzare JSON in questa stringa. Analizza quel JSON solo dopo aver verificato la presenza di un errore. Il testo del file e il testo delle istruzioni non sono necessariamente JSON.
resource Una risorsa incorporata, utilizzata per download inline. Leggi il suo oggetto annidato resource secondo il formato di risorsa MCP.
resource_link Un riferimento a una risorsa, usata per trasferimenti diretti. Ispeziona il relativo uri e i metadati; i byte non sono incorporati nella risposta.

Gestire sia le risposte HTTP JSON sia risposte text/event-stream. Per questo secondo caso, elaborare i messaggi JSON-RPC trasportati dagli eventi inviati dal server. Consulta i risultati degli strumenti MCP.

I payload di metadati hanno forme diverse:

  • Le liste DFS restituiscono Paths, un array di oggetti, e possono includere ContinuationToken, che possono essere null. Ogni percorso include Name (stringa), IsDirectory (booleana), ContentLength (intera), LastModified (stringa), ETag (stringa), Owner (stringa) e Permissions (stringa).
  • Gli elenchi di blob restituiscono un Blobs array. Le voci includono Name, ContentLength, ContentType, LastModified, ETag, e il booleano IsPrefix. Una stringa vuota è una stringa, non null.
  • Le liste dei namespace restituiscono namespaces come un array di array di stringhe, come [["dbo"]], e possono includere next-page-token.
  • I dettagli dello spazio dei nomi tornano namespace come stringa, exists come booleana e tables come stringa codificata in JSON. Analizza tables separatamente per ispezionare la lista delle tabelle annidate.
  • I risultati di accesso includono workspaceId, canRead, i flag booleani canWrite, canExecute e owner, più i campi stringa permissions e itemId. Queste stringhe possono essere vuote.

Preservare le maiuscole/minuscole del campo e distinguere le proprietà omesse, null, stringhe vuote e array vuoti. Elabora i campi che il tuo client comprende senza rifiutare un'intera risposta quando compaiono campi aggiuntivi.

Esempio: esplora i file di un oggetto

Dopo esserti collegato a un lakehouse e aver confermato che onelake_list_items_data restituisce una directory Files, chiedi al tuo agente:

Elenca le directory sotto File in questo elemento. Non cambiare nessun dato."

La corrispondente chiamata dello strumento è:

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

Di seguito è riportato il JSON completo decodificato dal primo blocco result.content[].text della risposta, non l'involucro JSON-RPC. Gli ID di oggetti e proprietari, i nomi delle directory, i timestamp e gli ETag sono esemplari.

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

Entrambe le voci sono directory. I loro ContentLength valori non rappresentano le dimensioni totali dei file sottostanti. Per esplorare la prima directory, chiamare onelake_list_files con path: "Files/incoming". Il valore restituito Name include l'ID dell'articolo, ma quello path dello strumento successivo è relativo all'elemento.

Altri compiti che puoi chiedere al tuo agente di completare includono:

  • Elenca i namespace in questo lakehouse, poi mostra i metadati per una tabella che selezionerò.
  • Leggi il file di configurazione JSON in Files/config/settings.json.
  • Ricevi istruzioni per il download di Files/exports/orders.parquet. Non trasferirlo ancora."

Errori e limitazioni

Controlla lo stato HTTP, un JSON-RPC errordi livello superiore, e result.isError. HTTP 200 da solo non significa che uno strumento sia riuscito.

Risposta Significato e azione
HTTP 401 L'autenticazione manca o non è valida. Ottieni un token valido per il destinatario corretto e allegalo alla richiesta.
HTTP 404 durante l'inizializzazione Controlla l'endpoint, l'ambiente e la coppia spazio di lavoro/elemento. Un oggetto mancante può essere restituito TargetItemNotInWorkspace.
HTTP 400 con codice JSON-RPC -32700 Il corpo della richiesta non è valido in JSON-RPC. Correggi il corpo del messaggio prima di riprovare.
HTTP 200 con result.isError: true Lo strumento non è riuscito. Esamina il messaggio di testo. Percorsi mancanti, argomenti necessari mancanti, tipi di argomenti non validi e accesso negato possono essere segnalati tramite questo modulo.

Ad esempio, un file mancante può restituire questa risposta completa JSON-RPC:

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

Ulteriori limitazioni:

  • Le elencazioni di archiviazione e tabelle non espongono i parametri di input del token di continuazione in questo catalogo. Non dare per scontato che un elenco sia esaustivo quando raggiunge un limite o restituisce un token di continuazione. Usa le API file OneLake di base o le API di tabella quando hai bisogno di paginazione.
  • maxResults limita un elenco di Blob; non è un cursore di paginazione.

Contenuti correlati

  • Ultimo aggiornamento: