ローカルモデルコンテキストプロトコル (MCP) サーバーを使用して GraphQL 用ファブリック API に AI エージェントを接続する

GitHub Copilot に「前四半期のすべての売上を表示する」と尋ね、自動的に Fabric データウェアハウスにクエリを実行し、スキーマを理解し、結果を返すようにするとします。すべて GraphQL の 1 行を記述せずに行います。このチュートリアルでは、これを可能にする方法について説明します。

このチュートリアルでは、AI エージェントと Microsoft Fabric データの間のブリッジとして機能するローカル GraphQL MCP サーバーを構築します。最終的には、GitHub Copilot、Claude、その他の AI エージェントなどの AI アシスタントが会話言語を使用して Fabric データに自然にクエリを実行できるようにする、実際の開発サーバーが用意されています。

作業内容:

GraphQL MCP サーバーが Fabric に安全にアクセスできるように認証を設定する
AI エージェントがデータ構造を自動的に検出できるように、スキーマのイントロスペクションを有効にする
自然言語を GraphQL クエリに変換するローカル GraphQL MCP サーバーをデプロイする
GitHub Copilot またはその他の AI ツールを接続して、会話的にデータにクエリを実行する

モデルコンテキストプロトコル (MCP) とは

モデルコンテキストプロトコル (MCP) は、コンテンツリポジトリ、ビジネスツール、開発環境など、データが存在するシステムに AI アシスタントを接続するための標準です。その目的は、フロンティアモデルがより適切で関連性の高い応答を生み出すのを支援することです。 MCP は、AI アプリケーションの USB-C ポートと考えてください。 USB-C がデバイスをさまざまな周辺機器やアクセサリに接続する標準化された方法を提供するのと同様に、MCP は AI モデルを外部のデータソースやツールに接続するための標準化された方法を提供します。

OpenAI、Microsoft Copilot Studio、Microsoft Foundry などの主要な AI プラットフォームでは、AI エージェントを外部システムと統合するための標準的な方法として MCP が採用されました。これにより、MCP は、AI エージェントを Microsoft Fabric データに接続するための理想的な選択肢になります。

GraphQL が MCP に最適な理由

GraphQL は、次の理由から MCP 統合に適しています。

スキーマのイントロスペクション: AI エージェントは、GraphQL スキーマから直接、使用可能なデータ構造とリレーションシップを自動的に検出できます
柔軟なクエリ: エージェントは、1 つの要求で必要なデータを正確に要求できます
型の安全性: 強力な型指定は、AI エージェントがデータ形式と制約を理解するのに役立ちます
効率的なデータフェッチ:データの過剰フェッチとアンダーフェッチを削減

Microsoft Fabric の GraphQL 用 API を使用すると、標準化された GraphQL インターフェイスを使用して、Fabric Lakehouse、Data Warehouse、およびデータベースを AI エージェントに簡単に公開できます。 GraphQL 用 API には強力なクエリ機能が既に用意されていますが、AI エージェントの接続の設定は、可能な限り簡単ではない可能性があります。

シンプルなローカル GraphQL MCP サーバーを使用すると、開発者は AI エージェントを使用して、Fabric データ構造を検出し、利用できる内容を理解し、自然言語を使用してクエリを実行できます。すべて標準化された MCP インターフェイスを介して実行できます。便利なことに、GraphQL の種類、クエリ、または変更ごとに、サーバーに個別の MCP ツールを定義する必要はありません。 GraphQL MCP サーバーは GraphQL スキーマをイントロスペクトし、AI エージェントが get-go から使用可能なすべての型と操作を理解できるようにします。

[前提条件]

このチュートリアルを開始する前に、次の内容を確認してください。

適切なアクセス許可を持つ Microsoft Fabric ワークスペース。サービスプリンシパルを構成し、イントロスペクションを有効にするには、ワークスペース管理者ロールが必要です。
作成および構成された GraphQL 項目の API。 Fabric ポータルの「SQL データベースから GraphQL 用 API を作成して API にデータを追加する」または「GraphQL API を作成する」を参照してください。
開発用コンピューターにインストールされている Node.js (npm を含む)
開発用コンピューターにインストールされている Visual Studio Code

注

管理者ではないですか。 このチュートリアルの一部の手順では、管理者のアクセス許可が必要です。管理者でない場合でも、特定のタスクのサポートを管理者に依頼することで、ほとんどのチュートリアルを完了できます。管理者のアクセス許可を必要とする各手順は、明確にマークされます。

手順 1: サービスプリンシパルアクセスを構成する

作業内容: GraphQL MCP サーバーが毎回サインインしなくても Fabric にアクセスできるように、非対話型認証資格情報を設定します。

これが重要な理由: GraphQL MCP サーバーは、AI エージェントが自動的に呼び出すバックグラウンドサービスとして実行されます。特定のユーザーに代わってではなく、アプリケーションに代わって Fabric に対して認証するための資格情報を持つ独自の ID (サービスプリンシパル) が必要です。

「Fabric API for GraphQL でサービスプリンシパルを使用する」の完全なガイドに従って、次の操作を行います。

Azure アプリ登録を作成する (Microsoft Entra ID でアプリ登録を作成するアクセス許可を持つすべてのユーザー)
証明書とシークレット (任意のユーザー) の下にクライアントシークレットを追加する
テナント設定でサービスプリンシパルを有効にする (Fabric テナント管理者が必要)
GraphQL API とワークスペースにアクセス許可を付与する (ワークスペース管理者または共同作成者ロールが必要)

ヒント

管理者ではありませんか? 最初の 2 つの項目は自分で完了できます。テナント設定については、Fabric テナント管理者に対して、管理ポータルの [サービスプリンシパルで Fabric API を使用できます]<テナント設定Developer 設定を有効にするように依頼します。ワークスペースのアクセス許可については、ワークスペース管理者に、ワークスペースまたは特定の GraphQL API へのアクセス権をサービスプリンシパルに付与するように依頼します。

セットアップを完了したら、 GraphQL MCP サーバー構成の次の 3 つの値をキャプチャします。

テナント ID: Microsoft Entra ID の概要>テナント ID にあります
クライアント ID: [概要] の [アプリの登録] の [アプリケーション (クライアント) ID] で見つかります
クライアントシークレット: 新しいクライアントシークレットを作成するときに表示されるシークレット値 (すぐにコピーします。1 回だけ表示されます)

手順 2: GraphQL のイントロスペクションを有効にする (ワークスペース管理者が必要)

作業内容: イントロスペクションを有効にすると、GraphQL MCP サーバーは GraphQL API に "どのようなデータがありますか" と尋ね、使用可能なすべての型、フィールド、リレーションシップの完全な説明を受け取ることができます。

これが重要な理由: これは、自然言語クエリを可能にする "マジック" です。 Copilot に「顧客を表示する」と尋ねると、AI エージェントは最初にイントロスペクションを使用して、 customers の種類が存在し、どのようなフィールドがあり、クエリを実行するかを検出します。イントロスペクションを使用しない場合は、AI のスキーマ全体を手動で文書化する必要があります。

Von Bedeutung

GraphQL MCP サーバーを機能させるには、イントロスペクションを有効にする必要があります。これは、セキュリティ上の理由から、Fabric では既定で無効になっています。 ワークスペース管理者のみがイントロスペクションを有効にすることができます。 管理者でない場合は、ワークスペース管理者にこの手順を完了するよう依頼してください。

Microsoft Fabric API for GraphQL Introspection と Schema Export の完全なガイドに従って、次の操作を行います。

API 設定でイントロスペクションを有効にする
イントロスペクションクエリのしくみを理解する
スキーマのエクスポートオプションについて説明します

イントロスペクションが有効になると、GraphQL MCP サーバーはスキーマ構造に対してクエリを実行し、AI エージェントで使用できるようになります。

手順 3: GraphQL MCP サーバーを設定する

作業内容: モデルコンテキストプロトコルを実装するローカル Node.js サーバーのインストールと構成。このサーバーは、AI エージェントと Fabric GraphQL API の間のトランスレーターとして機能します。

これが重要な理由: MCP サーバーは、AI エージェントが理解する標準化されたインターフェイスを提供します。 AI エージェントは、接続すると、使用可能なツール (イントロスペクションとクエリ) を検出し、それらのツールを呼び出し、応答を受け取ることができます。AI プラットフォームごとにカスタム統合コードを記述する必要はありません。

認証資格情報 (手順 1) とイントロスペクションを有効にしました (手順 2) の準備ができたので、それらを使用するようにサーバーを構成する準備ができました。

サンプルリポジトリを複製する

git clone https://github.com/microsoft/fabric-samples.git
cd fabric-samples/docs-samples/data-engineering/GraphQL/MCP

依存関係のインストール

npm install

環境変数を構成する

構成を使用して、プロジェクトルートに .env ファイルを作成します。

MICROSOFT_FABRIC_API_URL=https://your-fabric-endpoint/graphql
MICROSOFT_FABRIC_TENANT_ID=your_tenant_id_here
MICROSOFT_FABRIC_CLIENT_ID=your_client_id_here
MICROSOFT_FABRIC_CLIENT_SECRET=your_client_secret_here
SCOPE=https://api.fabric.microsoft.com/.default

プレースホルダーの値を次のように置き換えます。

MICROSOFT_FABRIC_API_URL: Fabric ポータルからの GraphQL エンドポイント
MICROSOFT_FABRIC_TENANT_ID: Azure テナント ID
MICROSOFT_FABRIC_CLIENT_ID: アプリ登録クライアント ID
MICROSOFT_FABRIC_CLIENT_SECRET: アプリ登録クライアントシークレット

GraphQL MCP サーバーを起動する

node FabricGraphQL_MCP.js

サーバーは http://localhost:3000 で起動し、次の情報を表示します。

Microsoft Fabric GraphQL MCP server listening on port 3000
API URL: https://your-fabric-endpoint/graphql
Scope: https://api.fabric.microsoft.com/.default

使用可能な MCP ツール

GraphQL MCP サーバーには、次の 2 つの主要なツールが用意されています。

`introspect-schema`

目的: GraphQL スキーマ全体を取得します。
パラメーター: なし
使用法: クエリを実行する前に最初に呼び出す必要があります

`query-graphql`

目的: Fabric データに対して GraphQL クエリを実行する
パラメーター:
- query (必須): GraphQL クエリ文字列
- variables (省略可能): GraphQL 変数オブジェクト
使用法: すべてのデータ取得および操作操作用

ワークフローについて

一般的な GraphQL MCP ワークフローは、次のパターンに従います。

スキーマ検出: AI エージェントは、最初に introspect-schema ツールを呼び出してスキーマと使用可能なデータを理解する必要があります
クエリ計画: エージェントが自然言語要求と GraphQL スキーマを分析する
クエリの生成: エージェントが適切な GraphQL クエリを作成する
実行: エージェントは、生成されたクエリを使用して query-graphql ツールを呼び出します
応答処理: エージェントの形式と結果の表示

手順 4: GraphQL MCP サーバーをテストする

作業内容: AI エージェントを接続する前に、MCP サーバーが Fabric に対する認証、スキーマの取得、クエリの実行を行うことができることを確認します。

これが重要な理由: 手動でテストすると、すべてが正しく構成されていることを確認します。これらのテストに合格した場合、AI エージェントは手順 5 で正常に接続できることがわかります。

サーバーの正常性を確認する

まず、サーバーが実行されていて、Fabric に対して認証できることを確認します。

PowerShell の使用:

Invoke-RestMethod -Uri "http://localhost:3000/health" -Method Get

cURL の使用:

curl http://localhost:3000/health

サーバーが稼働中であることを示す応答を受け取るはずです。この応答は、次のようになります。

{"status":"healthy","server":"Microsoft Fabric GraphQL MCP Server","hasToken":true,"tokenExpiry":"2025-06-30T23:11:36.339Z"}

テストスキーマのイントロスペクション

次に、サーバーがイントロスペクションを使用して GraphQL スキーマを取得できることを確認します。これにより、 introspect-schema MCP ツールが呼び出されます。

PowerShell の使用:

$headers = @{
    "Content-Type" = "application/json"
    "Accept" = "application/json, text/event-stream"
}

$body = @{
    jsonrpc = "2.0"
    id = 1
    method = "tools/call"
    params = @{
        name = "introspect-schema"
        arguments = @{}
    }
} | ConvertTo-Json -Depth 3

Invoke-RestMethod -Uri "http://localhost:3000/mcp" -Method Post -Body $body -Headers $headers

cURL の使用:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "introspect-schema",
      "arguments": {}
    }
  }'

これにより、GraphQL スキーマ定義が返されます。

GraphQL クエリをテストする

最後に、MCP サーバーを介して実際の GraphQL クエリを実行するテストを行います。この例では、 query-graphql MCP ツールを使用して、スキーマ内のすべての型名を照会します。

PowerShell の使用:

$headers = @{
    "Content-Type" = "application/json"
    "Accept" = "application/json, text/event-stream"
}

$body = @{
    jsonrpc = "2.0"
    id = 2
    method = "tools/call"
    params = @{
        name = "query-graphql"
        arguments = @{
            query = "query { __schema { types { name } } }"
        }
    }
} | ConvertTo-Json -Depth 4

Invoke-RestMethod -Uri "http://localhost:3000/mcp" -Method Post -Body $body -Headers $headers

cURL の使用:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "query-graphql",
      "arguments": {
        "query": "query { __schema { types { name } } }"
      }
    }
  }'

これにより、GraphQL スキーマ内のすべての型の一覧が返されます。

手順 5: AI エージェントを接続する

作業内容: ローカル MCP サーバーをデータソースとして使用するように AI ツールを構成する。

これが重要な理由: これがすべてが一緒に来る場所です。接続されると、AI エージェントはイントロスペクションを使用して Fabric スキーマを検出し、自然言語要求に基づいて GraphQL クエリを生成できます。 AI はクエリ構文を処理します。単に英語で質問するだけです。

Visual Studio Code の GitHub Copilot

VS Code に GitHub Copilot 拡張機能をインストールする

Copilot 設定で GraphQL MCP サーバーを構成します。

{
  "fabric-graphql": {
    "type": "http",
    "url": "http://localhost:3000/mcp"
  }
}

Copilot チャットで、最初にスキーマをイントロスペクトするように依頼してから、次に、イントロスペクトされたデータに関連する関連する質問を自然言語で尋ねてみてください。次に例を示します。

カーソル IDE

カーソルを開く設定

MCP サーバー構成を追加します。

{
  "fabric-graphql": {
    "type": "http",
    "url": "http://localhost:3000/mcp"
  }
}

チャットで、最初にスキーマをイントロスペクトするように依頼してから、自然言語でイントロスペクトされたデータに関連する関連する質問をしてみてください。

作成した内容

おめでとうございます! これで、次のような GraphQL MCP サーバーが動作するようになりました。

サービスプリンシパルの資格情報を使用して Fabric に対する認証を行う
イントロスペクションを使用して Fabric データスキーマを公開する
AI エージェント要求を GraphQL クエリに変換します
AI エージェントが理解して提示できる形式でデータを返します

AI エージェント (GitHub Copilot など) は、次のことができます。

Fabric ワークスペースで使用可能なデータを自動的に検出する
自然言語の質問に基づいて正しい GraphQL クエリを生成する
クエリコードを記述せずに結果を取得して書式設定する

このローカルサーバーは、開発と学習を目的としています。次のセクションでは、運用環境のデプロイと一般的なトラブルシューティングシナリオに関する重要な考慮事項について説明します。

セキュリティに関する考慮事項

ローカル GraphQL MCP サーバーは、このチュートリアルで説明されている開発目的でのみ実装する必要があります。HTTP トランスポートを使用して実装されるため、より複雑なクライアントサーバーまたは Web ベースの統合の開始点として使用しやすくなります。 GraphQL MCP サーバーを運用環境にデプロイする場合:

Azure Key Vault を使用して、 .env ファイルの代わりにシークレットを格納する
適切な承認、ネットワークセキュリティ、ファイアウォール規則を実装する
すべての GraphQL クエリの監査ログを有効にする
ホスティングに Azure App Service またはコンテナーインスタンスを使用する
MCP エンドポイントのレート制限と認証を実装する
クライアントシークレットと証明書を定期的にローテーションする

トラブルシューティング

一般的な問題と解決策

認証エラー

Azure アプリ登録に正しいアクセス許可があることを確認する
Fabric テナントでサービスプリンシパルが有効になっていることを確認する
クライアントシークレットの有効期限が切れていないことを確認する

スキーマのイントロスペクションが失敗する

GraphQL API 設定でイントロスペクションが有効になっていることを確認する
GraphQL エンドポイント URL が正しいことを確認する
Fabric ワークスペースへのネットワーク接続を確認する

AI エージェントがツールを認識しない

構成の変更後に AI クライアントを再起動する
MCP サーバー URL にアクセス可能であることを確認する
エラーメッセージがないかサーバーログを確認する

クエリ実行エラー

サーバーコンソールでログに記録されたクエリとエラーを確認する
クエリが使用可能なスキーマと一致していることを確認する
要求されたデータに対する適切なアクセス許可があることを確認します

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-01-21

次の方法で共有

ローカル モデル コンテキスト プロトコル (MCP) サーバーを使用して GraphQL 用ファブリック API に AI エージェントを接続する

モデル コンテキスト プロトコル (MCP) とは

GraphQL が MCP に最適な理由

[前提条件]

手順 1: サービス プリンシパル アクセスを構成する

手順 2: GraphQL のイントロスペクションを有効にする (ワークスペース管理者が必要)

手順 3: GraphQL MCP サーバーを設定する

サンプル リポジトリを複製する

依存関係のインストール

環境変数を構成する

GraphQL MCP サーバーを起動する

使用可能な MCP ツール

introspect-schema

query-graphql

ワークフローについて

手順 4: GraphQL MCP サーバーをテストする

サーバーの正常性を確認する

テスト スキーマのイントロスペクション

GraphQL クエリをテストする

手順 5: AI エージェントを接続する

Visual Studio Code の GitHub Copilot

カーソル IDE

作成した内容

セキュリティに関する考慮事項

トラブルシューティング

一般的な問題と解決策

関連コンテンツ

フィードバック

その他のリソース

ローカルモデルコンテキストプロトコル (MCP) サーバーを使用して GraphQL 用ファブリック API に AI エージェントを接続する

モデルコンテキストプロトコル (MCP) とは

手順 1: サービスプリンシパルアクセスを構成する

サンプルリポジトリを複製する

`introspect-schema`

`query-graphql`

テストスキーマのイントロスペクション