Połącz agentów AI z hostowanym serwerem OneLake MCP (podgląd)

Hostowany serwer OneLake Model Context Protocol (MCP) pozwala agentom AI przeglądać pliki, przeglądać metadane tabel oraz zarządzać katalogami w elemencie Fabric bez instalowania lokalnego serwera MCP. Podłącz klienta kompatybilnego z MCP do punktu końcowego HTTPS tego elementu, a następnie użyj żądań w języku naturalnym lub wywołaj narzędzia bezpośrednio.

Serwer hostowany zapewnia połączenie item data-plane i stanowi alternatywę dla lokalnego serwera Fabric MCP. Do zarządzania przestrzenią roboczą i elementami, skrótami OneLake oraz rolami dostępu do danych OneLake korzystaj z serwera MCP Fabric Core. Łącz się z każdym serwerem dla operacji, których potrzebujesz.

Prerequisites

• Element Fabric, który przechowuje dane w OneLake, z dostępnym w Twoim środowisku hostowanym punktem końcowym OneLake MCP.
• Tożsamość Microsoft Entra z uprawnieniami do wykonywania zamierzonych operacji na danych elementu.
• Klient MCP wspierający Streamable HTTP i potrafiący dołączyć token bearer Microsoft Entra do żądań.
• Dostęp sieciowy do punktu końcowego MCP oraz, w przypadku bezpośrednich transferów plików, do zwracanego punktu końcowego magazynu.

Aby poznać model uprawnień, zobacz bezpieczeństwo danych w OneLake. Sam dostęp do przestrzeni roboczej nie oznacza, że każda tożsamość może odczytywać lub zapisywać każdą ścieżkę danych. Wymagania dotyczące sieci znajdziesz w artykule Connect to OneLake.

Połącz się z elementem

Użyj hostowanego adresu endpoint OneLake MCP dla swojej przestrzeni roboczej i elementu.

1. Dodaj adres URL do konfiguracji HTTP MCP swojego klienta. Skonfiguruj uwierzytelnianie zgodnie z opisem w następnej sekcji, a następnie zainicjuj połączenie.
2. Poproś agenta, aby wywołał onelake_list_items_data, aby odkryć obszary danych najwyższego poziomu produktu, bez zmiany danych. Wybierz zwrócony katalog do eksploracji z onelake_list_files, używając ścieżki względnej względem elementu path. Nie zakładaj, że każdy element jest katalogiem Files.

Aby uzyskać informacje o konfiguracji i lokalizacjach instalacji programu Visual Studio Code, zobacz Dodaj serwery MCP w VS Code. Konfiguracja uwierzytelniania zależy od środowiska klienta i agenta; dodanie adresu URL nie powoduje zalogowania.

Endpoint elementu ma taką ścieżkę:

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

Tutaj {oneLakeHost} to origin HTTPS z adresu URL Twojego punktu końcowego, a dwa identyfikatory identyfikują przestrzeń roboczą i element. Zachowaj razem nazwę hosta i ścieżkę punktu końcowego. Nie zastępuj regionalnej nazwy hosta ani nazwy hosta specyficznej dla środowiska inną nazwą hosta OneLake.

Użyj punktu końcowego identyfikowanego za pomocą identyfikatora GUID. Przyjazne nazwy są dostępne jako argumenty narzędzi, opisane w parametrach Wspólnych. URL adresowany nazwą hosta może się pomyślnie inicjalizować, ale kończy się niepowodzeniem, gdy narzędzie korzysta z jego kontekstu URL.

Uwierzytelnianie i uprawnienia

Użyj tokena dostępu Microsoft Entra dla grupy odbiorców usługi Azure Storage, https://storage.azure.com/. Dla bibliotek uwierzytelniających akceptujących zakresy używaj https://storage.azure.com/.default. Nie zastępuj elementu https://api.fabric.microsoft.com/ tokenem.

Wyślij token w nagłówku Authorization: Bearer <access-token> przy każdym żądaniu. Informacje o konfigurowaniu uwierzytelniania zawiera temat Przygotowanie do uwierzytelniania.

Klient odpowiada za uzyskanie i odświeżenie swojego tokena. Zalogowanie się do Azure CLI nie uwierzytelnia automatycznie dowolnego klienta HTTP MCP. Korzystaj z mechanizmu poświadczeń obsługiwanego przez klienta i nie umieszczaj tokenów w czacie, współdzielonych plikach konfiguracyjnych ani repozytoriach kontroli wersji.

OneLake ocenia uprawnienia wywołującego dla każdej operacji. Podłączenie agenta nie daje mu dodatkowego dostępu do danych. Pozostaw włączone zatwierdzenie użytkownika dla operacji zapisu i usuwania oraz sprawdź element docelowy i ścieżkę przed ich zatwierdzeniem.

Połączenie MCP i wykrywanie

Endpoint korzysta z JSON-RPC 2.0 przez Streamable HTTP. Każda wiadomość MCP to osobny HTTP POST do tego samego punktu końcowego.

Zainicjalizuj połączenie przy użyciu obsługiwanej przez klienta wersji protokołu, a następnie wyślij notifications/initialized. Serwer negocjuje wersję protokołu 2025-06-18 i identyfikuje się jako microsoft.onelake w wersji 1.0.0. Jego możliwości obejmują logging oraz tools, z tools.listChanged: true. Używaj wartości negocjowanych zamiast kodować na stałe wersję serwerową.

Odkryj narzędzia za pomocą tego żądania:

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

Przeczytaj name, description, inputSchema oraz annotations każdego wpisu. Jeśli odpowiedź zawiera result.nextCursor, przekaż ją jako params.cursor, aby uzyskać następną stronę. Odśwież wykrywanie, gdy serwer wyśle notifications/tools/list_changed.

Katalog opisany tutaj zawiera 15 narzędzi: 11 oznaczonych jako tylko do odczytu i idempotent, a cztery oznaczone jako destrukcyjne. Adnotacje narzędzi opisują zachowania; nie są to nadania uprawnień. Serwer nie ogłasza outputSchema dla tych narzędzi.

Dokumentacja narzędzia

Użyj dokładnych nazw narzędzi i wielkości liter w nazwach parametrów zwracanych przez tools/list. Poniższe tabele obejmują wszystkie parametry w tym katalogu. Wyświetl bieżące schematy podczas nawiązywania połączenia, ponieważ dostępne narzędzia mogą się zmieniać. Narzędzia do plików korzystają z API systemu plików (DFS) OneLake lub API Blob.

Wspólne parametry

Każde narzędzie akceptuje te opcjonalne parametry oprócz parametrów specyficznych dla danego narzędzia:

Zazwyczaj pomija się oba parametry, aby pracować z elementem w URL. Gdy wyraźnie określasz cel, używaj obu GUID lub obu nazw. Zakres URL określa wartości domyślne; nie usuwa tych parametrów kierowania ani nie zastępuje autoryzacji.

Schematy deklarują te parametry jako ciągi znaków o wartości defaultnull. Pomiń opcjonalny ciąg znaków, aby użyć wartości domyślnej zamiast wysyłania JSON null: null nie jest uwzględnione w jego zadeklarowanym typie. Ta zasada dotyczy pathtakże , prefix, schemaName, oraz contentType gdy te ciągi są opcjonalne.

Ścieżki plików i katalogów są względne względem elementu, takie jak Files/incoming/orders.csv lub Tables/dbo/orders. Nie umieszczaj workspace ani identyfikatora elementu w argumentze path .

Przeglądaj i odczytuj dane

Serwer oznacza te narzędzia jako tylko do odczytu i idempotentne.

Zacznij od wąskiego path lub prefix. Listowania rekurencyjne i szerokie listy Blob mogą generować więcej danych, niż agent potrzebuje.

Sprawdź metadane tabeli

Serwer oznacza te narzędzia jako tylko do odczytu i idempotentne. Sprawdzają metadane, a nie wiersze tabeli.

Użyj przestrzeni nazw zwracanej przez onelake_list_namespaces, zamiast zakładać, że każdy element ma te same schematy. Informacje o bazowych interfejsach API można znaleźć w OneLake table APIs.

Pobierz instrukcje dotyczące przesyłania plików

Serwer oznacza te narzędzia jako tylko do odczytu i idempotentne. Zwracają instrukcje, ale nie przesyłają bajtów plików. Wykonanie polecenia przesyłania jest osobną operacją zapisu.

Użyj onelake_get_upload_instructions, aby przesłać. Katalog nie zawiera narzędzia do przesyłania w tekście, mimo że opis narzędzia instrukcji przesyłania odnosi się do uploadFile. Podobnie używaj promowanej nazwy onelake_download_file, a nie skrótu downloadFile w opisie narzędzia do instrukcji pobierania.

Wynik instrukcji przesyłania pliku zawiera blok treści resource_link. Jego uri to miejsce docelowe, a _meta obejmuje method, tokenAudience, path oraz overwrite. Wynik obejmuje także wskazówki w formie tekstu. Link nie zawiera bajtów pliku ani nie daje dostępu do miejsca docelowego.

Uwierzytelnij przeniesienie osobno dla zwróconej grupy odbiorców. Przed uruchomieniem polecenia sprawdź jego miejsce docelowe i sposób nadpisywania. Wygenerowany tekst może zawierać nazwę hosta różniącą się od linku zasobu lub informować, że mały plik przekracza limit inline. Nie uruchamiaj sprzecznych instrukcji w niezmienionej postaci; weryfikuj miejsce docelowe na podstawie informacji o połączeniu magazynu przedmiotu.

Twórz i usuwaj katalogi lub pliki

Serwer określa te cztery narzędzia jako destrukcyjne. Wymagaj potwierdzenia przed ich wywołaniem.

Opisy narzędzi ostrzegają, że usuwanie plików i blobów jest nieodwracalne. Nie używaj tych narzędzi do usuwania plików z tabeli jako zamiennika operacji konserwacji uwzględniającej tabelę.

Wyniki narzędzia odczytu

Wywołanie narzędzia MCP zwraca JSON-RPC result z tablicą content. Sprawdź type każdego bloku; nie zakładaj, że każde narzędzie zwraca bezpośrednio obiekt JSON.

Obsługuje zarówno odpowiedzi HTTP w formacie JSON, jak i odpowiedzi text/event-stream. W tym drugim przypadku przetwórz wiadomości JSON-RPC przesyłane przez Server-Sent Events (SSE). Zobacz wyniki narzędzi MCP.

Ładunki danych metadanych mają różne kształty:

• Listy DFS zwracają Paths, tablicę obiektów i mogą zawierać ContinuationToken, które mogą być null. Każda ścieżka obejmuje Name (łańcuch), IsDirectory (boolean), ContentLength (liczba całkowita), LastModified (łańcuch), ETag (ciąg), Owner (ciąg) oraz Permissions (ciąg).
• Listingi obiektów blob zwracają tablicę Blobs. Elementy obejmują Name, ContentLength, ContentType, LastModified, ETag oraz typ logiczny IsPrefix. Pusty ContentType to ciąg znaków, a nie null.
• Wylistowania przestrzeni nazw zwracają namespaces jako tablicę tablic ciągów znaków, takich jak [["dbo"]], i mogą zawierać next-page-token.
• Szczegóły przestrzeni nazw zwracają namespace jako ciąg znaków, exists jako boolean oraz tables jako ciąg zakodowany w JSON. Parsuj tables osobno, aby sprawdzić listę zagnieżdżonych tabel.
• Wyniki dostępu obejmują workspaceId, itemId, flagi logiczne canRead, canWrite i canExecute, a także pola tekstowe owner i permissions. Te ciągi mogą być puste.

Zachowaj wielkość liter w nazwach pól i rozróżnij pominięte właściwości, null, puste ciągi i puste tablice. Przetwarzaj pola, które klient rozumie, nie odrzucając całej odpowiedzi, gdy pojawiają się kolejne pola.

Przykład: eksploruj pliki elementu

Po połączeniu z lakehouse i potwierdzeniu, że onelake_list_items_data zwraca katalog Files, zapytaj swojego agenta:

Wymień katalogi w sekcji Pliki w tej pozycji. Nie zmieniaj żadnych danych."

Odpowiadające wywołanie narzędzia to:

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

Poniżej znajduje się kompletny zdekodowany JSON z pierwszego result.content[].text bloku odpowiedzi, a nie z JSON-RPC obwiedni. Przykładowe są identyfikatory przedmiotów i właścicieli, nazwy katalogów, znaczniki czasu oraz ETags.

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

Oba wpisy są katalogami. Te ContentLength wartości nie odzwierciedlają całkowitych rozmiarów plików znajdujących się pod nimi. Aby zbadać pierwszy katalog, wywołaj onelake_list_files z path: "Files/incoming" Zwrócone Name zawiera ID przedmiotu, ale path następnego narzędzia jest względne do elementu.

Inne zadania, o których wykonanie możesz poprosić swojego agenta, obejmują:

• Wypisz przestrzenie nazw w tym lakehouse, a potem pokaż metadane dla wybranej przeze mnie tabeli.
• Przeczytaj plik konfiguracyjny JSON w Files/config/settings.json.
• Zobacz instrukcje pobierania pliku Files/exports/orders.parquet. Jeszcze go nie przenoś.

Błędy i ograniczenia

Sprawdź status HTTP, obiekt JSON-RPC najwyższego poziomu error oraz result.isError. Sam HTTP 200 nie oznacza, że narzędzie odniosło sukces.

Na przykład brakujący plik może zwrócić pełną JSON-RPC odpowiedź:

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

Dodatkowe ograniczenia:

• Listy magazynów i listy tabel nie ujawniają parametrów wejściowych tokenów kontynuacji w tym katalogu. Nie zakładaj, że wyliczenie jest wyczerpujące, gdy osiągnie limit lub zwróci token kontynuacyjny. Używaj bazowych interfejsów API plików OneLake lub interfejsów API tabel, gdy potrzebujesz paginacji.
• maxResults ogranicza listę Blobów; nie jest to kursor paginacji.

Treści powiązane

• Dokumentacja referencyjna narzędzi serwera MCP Fabric Core.
• Użyj lokalnego serwera Fabric MCP z OneLake.
• Połącz się z OneLake.
• Przegląd API tabel OneLake.
• Bezpieczeństwo danych w OneLake.