AIエージェントをホストされたOneLake MCPサーバーに接続(プレビュー)

ホストされているOneLakeモデルコンテキストプロトコル(MCP)サーバーは、AIエージェントがローカルMCPサーバーを設置せずにファイルの閲覧、テーブルメタデータの検査、Fabricアイテム内のディレクトリ管理を可能にします。 MCP互換クライアントをアイテムのHTTPSエンドポイントに接続し、自然言語リクエストを使うか、ツールを直接呼び出します。

ホストサーバーはアイテムデータプレーン接続を提供し、ローカルのFabric MCPサーバーの代替手段となります。 ワークスペースやアイテム管理、OneLakeのショートカット、OneLakeのデータアクセスロールについては、Fabric Core MCPサーバーを使用してください。 必要な操作のために各サーバーに接続してください。

Important

ホストされているOneLake MCPサーバーは現在 パブリックプレビュー中です。 機能と動作は、一般公開前に変更される可能性があります。

Prerequisites

  • OneLakeにデータを保存するFabricアイテムで、環境内でホストされたOneLake MCPエンドポイントが用意されています。
  • アイテムのデータに対して意図した操作を実行する権限を持つ Microsoft Entra ID
  • Streamable HTTPをサポートし、リクエストにMicrosoft Entraベアラートークンを付与できるMCPクライアントです。
  • MCPエンドポイントへのネットワークアクセス、そして直接ファイル転送の場合は返されたストレージエンドポイントへのアクセス。

権限モデルについては、 OneLakeのデータセキュリティを参照してください。 ワークスペースへのアクセス権があるだけでは、すべてのアイデンティティがすべてのデータパスを読み取ったり書き込んだりできることを意味しません。 ネットワーク要件については、 Connect to OneLakeをご覧ください。

アイテムに接続

ワークスペースとアイテム用のホストされたOneLake MCPエンドポイントのURLを使ってください。

  1. クライアントのHTTP MCP設定にURLを追加してください。 次のセクションで説明するように認証を設定し、その後接続を初期化します。
  2. エージェントに onelake_list_items_data を呼び出してもらい、データを変更せずにアイテムのトップレベルデータエリアを検出するよう依頼してください。 onelake_list_files というアイテム相対パスを使用して、path で探索する返されたディレクトリを選択します。 すべての項目に Files ディレクトリがあると決めつけないでください。

Visual Studio Codeのセットアップおよび構成の場所については、「VS CodeでMCPサーバーを追加」をご覧ください。 認証の設定はクライアントとエージェントの環境に依存します。URLを追加してもサインインされません。

アイテムエンドポイントの経路は以下の通りです:

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

ここで、{oneLakeHost} はエンドポイントURLのHTTPSオリジンであり、2つのIDはワークスペースとアイテムを識別します。 エンドポイントのホスト名とパスは分けずに保持します。 地域や環境固有のホスト名を別のOneLakeホスト名に置き換えないでください。

GUIDで指定されたエンドポイントを使いましょう。 表示名はツールの引数として利用可能で、共通パラメーターで説明されています。 名前指定URLは初期化には成功しますが、ツールがそのURLコンテキストを利用すると失敗します。

Note

初期化で 404 が返された場合は、エージェントを設定する前にアイテム、環境、エンドポイントの可用性を確認してください。

認証とアクセス許可

Azure StorageのオーディエンスにはMicrosoft Entraアクセストークンを使いましょう、https://storage.azure.com/。 スコープを受け入れる認証ライブラリの場合は https://storage.azure.com/.defaultを使いましょう。 https://api.fabric.microsoft.com/ の代わりにトークンを使わないでください。

各リクエストで Authorization: Bearer <access-token> ヘッダー内にトークンを送信します。 認証の設定については 「認証の準備」を参照してください。

クライアントはトークンの取得と更新の責任を負います。 Azure CLIにサインインしても、任意のHTTP MCPクライアントが自動的に認証されるわけではありません。 クライアントがサポートする認証情報の仕組みを使い、チャットや共有設定ファイル、ソース管理にはトークンを入れないでください。

OneLakeは各操作の呼び出し元の権限を評価します。 エージェントを接続しても追加のデータアクセス権は与えられません。 書き込みと削除の際にユーザー承認を有効にし、承認する前にターゲットアイテムとパスを確認しましょう。

MCP接続と検出

エンドポイントは Streamable HTTP上で JSON-RPC 2.0を使用しています。 各MCPメッセージは同じエンドポイントへの別々のHTTP POSTです。

Header Value
Authorization Bearer <access-token>。
Content-Type application/json。
Accept application/json, text/event-stream。
MCP-Protocol-Version 初期化時にネゴシエートされたバージョン(後続のリクエスト時)
Mcp-Session-Id 初期化でセッションIDが返される場合のサーバーのセッションID その後のリクエストで送ってください。

クライアントがサポートするプロトコル バージョンで接続を初期化し、その後 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を使用します。

共通パラメーター

すべてのツールは、ツール固有のパラメータに加えて、以下のオプションパラメータを受け入れています:

Parameter JSON 型 Description
workspaceId String ワークスペースのGUIDか名前。 このパラメータを省略すると、エンドポイントはワークスペースコンテキストを使用します。
itemId String アイテムGUIDか名前。 名前にはitemName.itemTypeのようなSales.Lakehouseを使います。 このパラメータを省略すると、エンドポイントはアイテムコンテキストを使用します。

通常は、URL内のアイテムを対象に動作するために両方のパラメータを省略します。 ターゲットを明示的に指定する場合は、両方のGUIDまたは両方の名前を使ってください。 URL のスコープ設定はデフォルトを提供します。これらのターゲティングパラメータを削除したり、認可を置き換えたりするものではありません。

スキーマはこれらのパラメータを、default が nullの文字列として宣言します。 JSON null を送信する代わりにデフォルトを使用するには、オプションの文字列を省略してください: は宣言された型に含まれていません。 このルールは、これらの文字列が任意である path、 prefix、 schemaName、 contentType にも適用されます。

ファイルパスやディレクトリパスは、 Files/incoming/orders.csv や Tables/dbo/ordersなど、アイテムに対して相対的です。 pathの引数にワークスペースやアイテム識別子を含めないでください。

データの閲覧と読み取り

サーバーはこれらのツールを読み取り専用かつ冪等としてマークします。

ツール 必須のパラメーター 共通パラメーターを除くオプション パラメーター Purpose
onelake_list_files None. path: 文字列、省略した場合のアイテムルート。 recursive: ブール値、既定値は false。 DFS APIを通じてファイルやディレクトリを一覧表示し、所有者、権限、ETagなどのメタデータも含みます。
onelake_blob_list None. prefix: 文字列、省略した場合はフィルターなし。 maxResults:整数、デフォルト 100。 Blob APIを通じて、名前、長さ、コンテンツタイプ、修正時間とともにブロブを一覧化します。
onelake_list_items_data None. None. アイテムの最上位のデータ領域を一覧表示します。 このツールはワークスペース内のFabricアイテムをリストアップしません。
onelake_read_file path:文字列。 None. DFS APIを通じて小さなテキストファイルを読みます。
onelake_download_file path:文字列。 None. Blob APIを通じてダウンロードしてください。 サーバーは最大4MBまでのファイル用にインライン組み込みリソースを提示し、より大きなファイルには直接転送の手順を提供します。
onelake_get_principal_access None. None. 報告されたアクセスフラグやアクセス制御メタデータを取得します。 この結果を使用する前に、このセクションのアクセスフラグ制限を参照してください。

まずは狭い path や prefixから始めましょう。 再帰的リストアップや広範なBlobリストは、エージェントが必要とする以上のデータを生成することがあります。

Important

onelake_get_principal_access は、同じ発信者がその項目を読める場合でも、canRead: false を報告できます。 このツールを認可ゲートとして使わないでください。 OneLakeは、要求された操作に対してアクセス許可を適用します。 その操作結果と OneLakeのセキュリティモデル を使ってアクセスを診断します。

テーブルのメタデータを確認

サーバーはこれらのツールを読み取り専用かつ冪等としてマークします。 彼らはメタデータを検査しており、テーブルの行を検査しません。

ツール 必須のパラメーター 共通パラメーターを除くオプション パラメーター Purpose
onelake_list_namespaces None. None. テーブルAPIを通じてIcebergの名前空間識別子を一覧表示してください。
onelake_get_namespace namespace:文字列。 None. 名前空間の詳細を取得します(返却されたテーブルリストのペイロードを含む)。
onelake_get_table_config tableName:文字列。 schemaName:文字列。 説明には省略した場合は dbo と明記されており、スキーマの default は nullです。 サーバーによりフォーマット、スキーマ列、パーティション情報、バージョンメタデータとして記述されるテーブルメタデータを取得します。

すべてのアイテムが同じスキーマを持つと仮定するのではなく、 onelake_list_namespaces が返す名前空間を使いましょう。 基盤となるAPIについては、 OneLakeテーブルAPIを参照してください。

ファイル転送手順を取得

サーバーはこれらのツールを読み取り専用かつ冪等としてマークします。 命令は返しますが、ファイルバイトの転送はしません。 アップロード命令の実行は別の書き込み操作です。

ツール 必須のパラメーター 共通パラメーターを除くオプション パラメーター Purpose
onelake_get_download_instructions path:文字列。 None. OneLakeから直接ファイルをダウンロードするためのリソースリンクと手順を入手できます。
onelake_get_upload_instructions path:文字列。 sizeBytes: 整数、デフォルト 0、表示用の。 contentType: 文字列。既定では省略。 overwrite: ブール値、既定値は false。 リソースリンクと、宛先パスへのアップロード手順を入手してください。

アップロードには onelake_get_upload_instructions を使いましょう。 カタログにはインラインアップロードツールが含まれていませんが、アップロード指示ツールの説明では uploadFile に言及しています。 同様に、ダウンロード指示ツールの説明にあるonelake_download_fileの略語ではなく、広告されている名前downloadFileを使用してください。

アップロード指示の結果には、 resource_link コンテンツブロックが含まれます。 その uri が目的地であり、 _meta には method、 tokenAudience、 path、 overwriteが含まれます。 その結果、テキストガイダンスも含まれています。 リンクにはファイルバイトが含まれておらず、宛先へのアクセスも許可しません。

returned audience 向けに転送を別途認証してください。 コマンドを実行する前に、その宛先と上書き時の動作を確認してください。 生成されたテキストには、リソースリンクと異なるホスト名が含まれたり、または小さなファイルがインライン制限を超えていると記載されることがあります。 矛盾する命令をそのまま実行しないでください。目的地をアイテムのストレージ接続情報と照らし合わせてください。

ディレクトリやファイルの作成と削除

サーバーはこれら4つのツールを破壊的としてマークします。 それらを呼び出す前に確認を得てください。

ツール 必須のパラメーター 共通パラメーターを除くオプション パラメーター Purpose
onelake_create_directory path:文字列。 None. ディレクトリと必要な親ディレクトリを作成します。
onelake_delete_directory path:文字列。 recursive: ブール値、既定値は false。 ディレクトリを削除します。再帰的削除ではその内容も削除されます。
onelake_delete_file path:文字列。 None. DFS APIを通じてファイルを削除してください。
onelake_blob_delete path:文字列。 None. Blob APIを通じてブロブを削除してください。

ツールの説明には、ファイルやブロブの削除は不可逆的であると警告されています。 これらのツールを使ってテーブルからファイルを削除することを、テーブル対応の保守操作の代替にしないでください。

ツールの結果を確認

MCPツール呼び出しは JSON-RPC content と result 配列を返します。 各ブロックの typeを確認し、すべてのツールがJSONオブジェクトを直接返すとは限りません。

コンテンツ タイプ 使用方法
text textを文字列として読み取ります。 メタデータツールはJSONをこの文字列にシリアライズできます。 エラーがないことを確認してからJSONを解析してください。 ファイルテキストや指示テキストは必ずしもJSONではありません。
resource インラインダウンロードに使われる組み込みリソース。 MCPリソース形式に従ってネストされた resource オブジェクトを読み込みます。
resource_link 直接転送に使用されるリソースへの参照です。 そのuriとメタデータを調べてください。バイトは応答に埋め込まれていません。

JSONのHTTP応答と text/event-stream 応答の両方を処理してください。 後者については、サーバー送信イベントによって運ばれた JSON-RPC メッセージを処理します。 MCPツールの結果をご覧ください。

メタデータペイロードはさまざまな形状を持っています:

  • DFSリストはPaths(オブジェクトの配列)を返し、nullを含めることができ、これはContinuationTokenになる場合があります。 各パスは Name (文字列)、 IsDirectory (ブール値)、 ContentLength (整数)、 LastModified (文字列)、 ETag (文字列)、 Owner (文字列)、 Permissions (文字列)で構成されています。
  • ブロブの一覧は Blobs 配列を返します。 エントリには Name、 ContentLength、 ContentType、 LastModified、 ETag、そしてブール値 IsPrefixが含まれます。 空の ContentType は文字列であり、 nullではありません。
  • 名前空間のリストは、[["dbo"]] などの文字列の配列の配列として namespaces を返し、next-page-tokenを含めることができます。
  • 名前空間の詳細は、 namespace を文字列として返し、 exists をブールで返し、 tables をJSONでエンコードした文字列として返します。 ネストされたテーブルリストを確認するため、tables を個別にパースします。
  • アクセス結果には workspaceId、 itemId、ブールフラグ canRead、 canWrite、 canExecute、さらに文字列フィールド owner と permissionsが含まれます。 これらの文字列は空の場合があります。

フィールドケーシングを保持し、省略されたプロパティ、 null、空文字列、空配列を区別します。 クライアントが理解するフィールドを処理し、追加のフィールドが出てもレスポンス全体を拒否しないでください。

例: アイテムのファイルを参照する

レイクハウスに接続し、Files が 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や所有者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値は、その配下のファイルの総サイズを表していません。 最初のディレクトリを調べるには、onelake_list_files を付けて path: "Files/incoming" を呼び出します。 返される Name にはアイテム ID が含まれていますが、次のツールの path はアイテム相対です。

エージェントに依頼できるその他の業務には以下があります:

  • 「このレイクハウスのネームスペースをリストアップし、私が選択するテーブルのメタデータを見せて。」
  • 「Files/config/settings.jsonのJSON設定ファイルを読んでみてください。」
  • ファイル/exports/orders.parquet のダウンロード手順を確認してください。 まだ転送しないで。」

エラーと制限

HTTPステータス、トップレベルの JSON-RPC error、および result.isErrorを確認してください。 HTTP 200 だけではツールが成功したわけではありません。

応答 意味とアクション
HTTP 401 認証が欠落しているか無効です。 正しいオーディエンス用の有効なトークンを取得し、リクエストに添付してください。
初期化時のHTTP 404 エンドポイント、環境、ワークスペース/アイテムのペアを確認してください。 不足しているアイテムは TargetItemNotInWorkspace返金できます。
JSON-RPC コード -32700 を使用する HTTP 400 リクエストボディは有効なJSON-RPCではありません。 再挑戦する前に本文を修正してください。
HTTP 200 と result.isError: true ツールでエラーが発生しました。 そのテキストメッセージを調べてください。 パスの欠如、必要な引数の欠如、無効な引数型、アクセス拒否などの場合は、このフォームを使用できます。

例えば、ファイルが見つからない場合、以下の完全な 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のリストを制限します。ページ付きカーソルではありません。