將 AI 代理連接到託管的 OneLake MCP 伺服器（預覽）

託管的 OneLake 模型上下文協定（MCP）伺服器讓 AI 代理能瀏覽檔案、檢查資料表中繼資料，並管理 Fabric 項目中的目錄，而無需安裝本地 MCP 伺服器。 將一個 MCP 相容的用戶端連接到該物件的 HTTPS 端點，然後使用自然語言請求或直接呼叫工具。

託管伺服器提供項目資料平面連線，是本地 Fabric MCP 伺服器的替代方案。 對於工作區與項目管理、OneLake 捷徑及 OneLake 資料存取角色，請使用 Fabric Core MCP 伺服器。 連接到每台伺服器進行你需要的操作。

Prerequisites

• 一個在 OneLake 中儲存資料的 Fabric 項目，並在你的環境中提供一個託管的 OneLake MCP 端點。
• 一個 Microsoft Entra 身份，並擁有對該項目資料執行預定操作的權限。
• 一個支援可串流 HTTP 並能將 Microsoft Entra 持有人權杖附加於請求的 MCP 用戶端。
• 存取 MCP 端點的網路存取，以及直接檔案傳輸時回傳的儲存端點。

關於權限模型，請參見 OneLake 中的資料安全。 僅有工作區存取並不代表每個身份都能讀寫所有資料路徑。 關於網路需求，請參見 Connect to OneLake。

連接到一個項目

使用託管的 OneLake MCP 端點網址用於你的工作區和項目。

1. 將該網址加入你客戶端的 HTTP MCP 設定。 依下一節所述設定認證，然後初始化連線。
2. 請代理程式呼叫 onelake_list_items_data，在不更改資料的情況下，查詢該項目的頂層資料區域。 選擇一個回傳的目錄以使用 path 進行探索，並使用項目相對的 onelake_list_files。 不要假設每個項目都有 Files 目錄。

關於 Visual Studio Code 的安裝和設定位置，請參見 VS Code 中新增 MCP 伺服器。 認證設定取決於客戶端和代理的環境;新增網址並不會讓你登入。

項目端點的路徑如下：

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

這裡， {oneLakeHost} 是你端點 URL 的 HTTPS 來源，兩個 ID 分別識別工作區和項目。 保持端點的主機名稱和路徑一起。 不要用不同的 OneLake 主機名稱替換區域或環境特定的主機名稱。

使用以 GUID 定址的端點。 友善名稱可作為工具參數使用，詳見 Common parameters。 以名稱定址的 URL 可以成功初始化，但當工具使用其 URL 上下文時會失敗。

認證與權限

針對 Azure 儲存體 對象使用 Microsoft Entra 存取權杖，https://storage.azure.com/。 對於接受 scope 的認證函式庫，請使用 https://storage.azure.com/.default。 不要用權杖取代 https://api.fabric.microsoft.com/。

在每個請求的 Authorization: Bearer <access-token> 標頭中傳送權杖。 如需設定驗證，請參見準備驗證。

客戶端負責取得並刷新其代幣。 登入 Azure CLI 並不會自動讓任意的 HTTP MCP 用戶端通過驗證。 使用客戶端支援的憑證機制，不要在聊天、共用設定檔或原始碼控制中放置令牌。

OneLake 會評估呼叫者對每個操作的權限。 連接專員並不會賦予該專員額外的資料存取權限。 寫入與刪除時保持使用者批准開啟，並在核准前檢視目標項目與路徑。

MCP 連接與發現

端點使用 JSON-RPC 2.0 透過 Streamable HTTP 傳輸。 每個 MCP 訊息都是發送給同一端點的獨立 HTTP POST。

先用你客戶端支援的協定版本初始化連線，然後傳送 notifications/initialized。 伺服器協商協定版本 2025-06-18 ，並將自己識別為 microsoft.onelake，版本 1.0.0。 其能力包括 logging 和 tools，且 tools.listChanged: true。 使用協商好的數值，而不是硬編碼伺服器版本。

透過此請求探索這些工具：

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

閱讀每個項目的name、description、inputSchema和annotations。 如果回覆包含 result.nextCursor，則將其作為 params.cursor 傳遞以取得下一頁。 當伺服器傳送 notifications/tools/list_changed 時，重新整理探索。

此目錄包含 15 種工具：11 種標記為唯讀且冪等，4 種標記為具破壞性。 工具註解描述行為；它們不是權限授予。 伺服器並未針對這些工具宣告 outputSchema。

工具參考

使用 tools/list 傳回的精確工具名稱與參數大小寫。 以下表格涵蓋本目錄中的所有參數。 連線時要發現目前的結構描述，因為可用的工具可能會改變。 檔案工具使用 OneLake 的分散式檔案系統（DFS）API 或 Blob API。

常見參數

每個工具除了工具專用參數外，也接受以下可選參數：

通常，為了配合網址中的項目，可以省略兩個參數。 當你明確指定目標時，請同時使用兩個 GUID，或同時使用兩個名稱。 URL 範圍設定提供預設值;它不會移除這些目標參數或取代授權。

這些結構描述將這些參數宣告為字串，且其值為 default 的 null。 省略一個可選字串，使用其預設值，而不是傳送 JSON null：null 未包含在其宣告的型別內。 此規則同樣適用於 path、prefix、schemaName 和 contentType，在這些字串為選用時。

檔案與目錄路徑相對於項目而言，例如 Files/incoming/orders.csv 或 Tables/dbo/orders。 不要在 path 引數中包含工作區或項目識別碼。

瀏覽與讀取資料

伺服器會將這些工具標記為唯讀且冪等。

從較窄的 path 或 prefix 開始。 遞迴列出和廣泛的 Blob 列出可能產生的資料量超過代理所需的。

檢查表格元資料

伺服器會將這些工具標記為唯讀且冪等。 檢查的是元資料，不是資料表列。

使用 onelake_list_namespaces 傳回的命名空間，而不是假設每個項目都有相同的結構描述。 關於底層 API，請參見 OneLake 資料表 API。

取得檔案傳輸說明

伺服器會將這些工具標記為唯讀且冪等。 它們會回傳指令，但不會傳輸檔案位元組。 執行上傳指令是一個獨立的寫入操作。

用 onelake_get_upload_instructions 進行上傳。 目錄中並未包含內嵌上傳工具，儘管上傳說明工具的描述中提到了 uploadFile。 同樣地，在下載說明工具的描述中，請使用宣傳名稱 onelake_download_file，而非簡稱 downloadFile。

上傳指令結果包含一個 resource_link 內容區塊。 它的uri是目的地，而_meta包含method、tokenAudience、path和overwrite。 結果也包含文字指引。 連結不包含檔案位元組，也不授予對目的地的存取權限。

請為返回的受眾單獨驗證轉移。 執行指令前，先檢查其目的地及是否會覆寫。 產生的文字可能包含與資源連結不同的主機名稱，或例如一個小檔案超過內嵌限制。 不要原樣執行相互衝突的指令；請根據物品的儲存連線資訊核對目的地。

建立與刪除目錄或檔案

伺服器會將這四種工具標記為破壞性工具。 在叫用它們之前要求確認。

工具說明警告檔案和 blob 的刪除是不可逆的。 不要用這些工具來移除資料表中的檔案，作為資料表感知維護作業的替代方式。

讀取工具結果

MCP 工具呼叫會回傳一個 JSON-RPCcontent，內含 result 陣列。 檢查每個區塊的 type;不要假設每個工具都會直接回傳 JSON 物件。

同時處理 JSON HTTP 回應和 text/event-stream 回應。 對於前者，處理伺服器發送事件所攜帶的 JSON-RPC 訊息。 請參閱 MCP 工具結果。

元資料承載資料有不同的形式：

• DFS 列表回傳 Paths，一個物件陣列，且可包含 ContinuationToken，且可為 null。 每條路徑包含 Name （string）、 IsDirectory （boolean）、 ContentLength （ingeger）、 LastModified （string）、 ETag （string）、 Owner （string）和 Permissions （string）。
• blob 列表會回傳一個 Blobs 陣列。 項目包括 Name、 ContentLength、 ContentType、 LastModified、 ETag、 以及布林值 IsPrefix。 空 ContentType 是字串，不是 null。
• 命名空間列表會以字串陣列的陣列回傳 namespaces ，例如 [["dbo"]]，且可包含 next-page-token。
• 命名空間細節以 exists 作為字串、tables 作為布林值，以及 namespace 作為 JSON 編碼字串傳回。 另外解析 tables 以檢查巢狀資料表清單。
• 存取結果包括 workspaceId、itemId、布林標誌canRead、canExecutecanWrite以及字串欄位owner和permissions。 這些字串可以是空的。

保留欄位大小寫，並區分遺漏屬性、null、空字串與空陣列。 處理用戶端理解的欄位，且不會在出現額外欄位時拒絕整個回應。

範例：瀏覽項目的檔案

連接到 Lakehouse 並確認 onelake_list_items_data 會傳回 Files 目錄後，請詢問你的代理程式：

請在本項目中的「檔案」下列出目錄。 不要更改任何資料。

對應的工具呼叫為：

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

以下是回應第一個 result.content[].text 區塊的完整解碼 JSON，而非 JSON-RPC 信封。 項目與擁有者ID、目錄名稱、時間戳及ETag是說明性資料。

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

這兩個條目都是資料夾。 它們 ContentLength 的數值並不代表下面檔案的總大小。 要探索第一個目錄，請使用 path: "Files/incoming" 呼叫 onelake_list_files。 回傳的 Name 包含物品 ID，但下一個工具的 path 是相對於該項目的。

你還可以請代理人完成的其他任務包括：

• 「列出這個 Lakehouse 裡的命名空間，然後顯示我選擇的表格的中繼資料。」
• 「請閱讀 Files/config/settings.json的 JSON 設定檔。」
• 取得 Files/exports/orders.parquet 的下載指示。 別急著轉送。

錯誤與限制

檢查 HTTP 狀態、頂層 JSON-RPC error，以及 result.isError。 僅靠 HTTP 200 並不代表工具已成功執行。

例如，遺失的檔案可以回傳以下完整 JSON-RPC 回應：

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

其他限制：

• 儲存與表格列表不會在此目錄中顯示接續權杖輸入參數。 不要以為一個清單在達到上限或傳回接續權杖時就已經是全部。 需要分頁時，可以使用底層的 OneLake 檔案 API 或 表格 API 。
• maxResults 限制 Blob 列表;它不是分頁游標。

相關內容

• Fabric Core MCP 伺服器工具參考
• 使用本地的 Fabric MCP 伺服器搭配 OneLake。
• 連線到 OneLake。
• OneLake 表格 API 概述。
• OneLake 的資料安全。