Menyambungkan Agen AI ke Fabric API untuk GraphQL dengan server Protokol Konteks Model (MCP) lokal

Bayangkan meminta GitHub Copilot "Tunjukkan semua penjualan dari kuartal terakhir" dan mengakses gudang data Fabric Anda secara otomatis, memahami skema, dan mengembalikan hasil—semua tanpa menulis satu baris GraphQL. Tutorial ini menunjukkan kepada Anda cara memungkinkan itu.

Dalam tutorial ini, Anda membangun server MCP GraphQL lokal yang bertindak sebagai jembatan antara agen AI dan data Microsoft Fabric Anda. Pada akhirnya, Anda memiliki server pengembangan kerja yang memungkinkan asisten AI seperti GitHub Copilot, Claude, dan agen AI lainnya untuk secara alami mengkueri data Fabric Anda menggunakan bahasa percakapan.

Apa yang akan Anda capai:

Menyiapkan autentikasi sehingga server MCP GraphQL Anda dapat mengakses Fabric dengan aman
Aktifkan introspeksi skema sehingga agen AI dapat menemukan struktur data Anda secara otomatis
Menyebarkan server MCP GraphQL lokal yang menerjemahkan bahasa alami ke dalam kueri GraphQL
Sambungkan GitHub Copilot atau alat AI lainnya untuk mengkueri data Anda secara percakapan

Apa itu Protokol Konteks Model (MCP)?

Protokol Konteks Model (MCP) adalah standar untuk menghubungkan asisten AI ke sistem tempat data berada, termasuk repositori konten, alat bisnis, dan lingkungan pengembangan. Tujuannya adalah untuk membantu model frontier menghasilkan respons yang lebih baik dan lebih relevan. Pikirkan MCP seperti port USB-C untuk aplikasi AI. Sama seperti USB-C menyediakan cara standar untuk menghubungkan perangkat Anda ke berbagai periferal dan aksesori, MCP menyediakan cara standar untuk menghubungkan model AI ke sumber dan alat data eksternal.

Platform AI utama termasuk OpenAI, Microsoft Copilot Studio, dan Microsoft Foundry mengadopsi MCP sebagai cara standar untuk mengintegrasikan agen AI dengan sistem eksternal. Ini menjadikan MCP pilihan ideal untuk menghubungkan agen AI ke data Microsoft Fabric Anda.

Mengapa GraphQL sangat ideal untuk MCP

GraphQL sangat cocok untuk integrasi MCP karena:

Introspeksi skema: Agen AI dapat secara otomatis menemukan struktur dan hubungan data yang tersedia langsung dari skema GraphQL
Kueri fleksibel: Agen dapat meminta data yang mereka butuhkan dalam satu permintaan
Keamanan jenis: Pengetikan yang kuat membantu agen AI memahami format dan batasan data
Pengambilan data yang efisien: Mengurangi pengambilan berlebihan dan pengambilan data yang kurang

API GraphQL dari Microsoft Fabric memudahkan untuk mengekspos lakehouse Fabric Anda, Gudang Data Anda, dan database Anda ke agen AI melalui antarmuka GraphQL standar. Meskipun API untuk GraphQL sudah menyediakan kemampuan kueri yang kuat, pengaturan koneksi untuk agen AI mungkin tidak semudah yang diharapkan.

Dengan server MCP GraphQL lokal sederhana, pengembang dapat menggunakan agen AI untuk menemukan struktur data Fabric mereka, memahami apa yang tersedia, dan mengkuerinya dengan menggunakan bahasa alami - semua melalui antarmuka MCP standar. Dengan nyaman, Anda tidak perlu menentukan alat MCP terpisah di server untuk setiap jenis, kueri, atau mutasi GraphQL. Server GraphQL MCP melakukan introspeksi terhadap skema GraphQL, yang memberdayakan agen AI agar mampu memahami segala jenis dan operasi yang ada sejak awal.

Prasyarat

Sebelum memulai tutorial ini, pastikan Anda memiliki:

Ruang kerja Microsoft Fabric dengan izin yang sesuai. Peran admin ruang kerja diperlukan untuk mengonfigurasi perwakilan layanan dan mengaktifkan introspeksi.
API untuk item GraphQL dibuat dan dikonfigurasi. Lihat Membuat dan menambahkan data ke API untuk GraphQL atau Membuat API GraphQL dari database SQL Anda di portal Fabric.
Node.js diinstal pada komputer pengembangan Anda (termasuk npm)
Visual Studio Code terinstal pada komputer pengembangan Anda

Nota

Bukan admin? Beberapa langkah dalam tutorial ini memerlukan izin admin. Jika Anda bukan admin, Anda masih dapat menyelesaikan sebagian besar tutorial dengan meminta admin Anda untuk membantu tugas tertentu. Setiap langkah yang memerlukan izin admin ditandai dengan jelas.

Langkah 1: Mengonfigurasi akses prinsipal layanan

Apa yang Anda lakukan: Menyiapkan kredensial autentikasi non-interaktif sehingga server GraphQL MCP Anda dapat mengakses Fabric tanpa mengharuskan pengguna untuk masuk setiap kali.

Mengapa hal ini penting: Server GraphQL MCP berjalan sebagai layanan latar belakang yang dipanggil agen AI secara otomatis. Ini membutuhkan identitasnya sendiri (perwakilan layanan) dengan kredensial untuk mengautentikasi ke Fabric atas nama aplikasi Anda, bukan atas nama pengguna tertentu.

Ikuti panduan lengkap di Menggunakan Prinsipal Layanan dengan Fabric API untuk GraphQL untuk:

Membuat Pendaftaran Aplikasi Azure (setiap pengguna dengan izin untuk membuat pendaftaran aplikasi di ID Microsoft Entra)
Menambahkan rahasia klien di bawah Sertifikat & rahasia (pengguna mana pun)
Aktifkan prinsipal layanan di pengaturan penyewa Anda (memerlukan admin penyewa Fabric)
Memberikan izin ke GraphQL API dan ruang kerja Anda (memerlukan peran admin atau kontributor ruang kerja)

Tip

Bukan admin? Anda dapat menyelesaikan dua item pertama sendiri. Untuk pengaturan penyewa, minta admin penyewa Fabric Anda untuk mengaktifkan "Perwakilan layanan dapat menggunakan Fabric API" di bawah Portal admin>Pengaturan penyewa>Pengaturan pengembang. Untuk izin ruang kerja, minta admin ruang kerja Anda untuk memberikan akses perwakilan layanan Anda ke ruang kerja atau API GraphQL tertentu.

Saat Anda menyelesaikan penyiapan, ambil tiga nilai ini untuk konfigurasi server MCP GraphQL:

ID Penyewa: Ditemukan di Microsoft Entra ID di bawah Gambaran>ID Penyewa
ID Klien: Ditemukan di Pendaftaran Aplikasi Anda di bawah ID Aplikasi Gambaran Umum>(klien)
Rahasia Klien: Nilai rahasia ditampilkan saat Anda membuat rahasia klien baru (segera disalin—hanya ditampilkan sekali)

Langkah 2: Mengaktifkan introspeksi GraphQL (memerlukan admin ruang kerja)

Apa yang Anda lakukan: Mengaktifkan introspeksi memungkinkan server MCP GraphQL untuk meminta API GraphQL Anda "Data apa yang Anda miliki?" dan menerima deskripsi lengkap tentang semua jenis, bidang, dan hubungan yang tersedia.

Mengapa hal ini penting: Ini adalah "sihir" yang memungkinkan kueri bahasa alami. Ketika Anda bertanya kepada Copilot "Tampilkan pelanggan," agen AI terlebih dahulu menggunakan introspeksi untuk menemukan bahwa jenis customers ada, bidang apa yang dimilikinya, dan cara mengkuerinya. Tanpa introspeksi, Anda harus mendokumenkan seluruh skema Anda secara manual untuk AI.

Penting

Introspeksi harus diaktifkan agar server MCP GraphQL berfungsi. Ini dinonaktifkan secara default di Fabric karena alasan keamanan. Hanya admin ruang kerja yang dapat mengaktifkan introspeksi. Jika Anda bukan admin, minta admin ruang kerja Anda untuk menyelesaikan langkah ini.

Ikuti panduan lengkap di Microsoft Fabric API untuk Introspeksi GraphQL dan Ekspor Skema ke:

Mengaktifkan introspeksi di pengaturan API Anda
Memahami cara kerja kueri introspeksi
Pelajari tentang opsi ekspor skema

Setelah introspeksi diaktifkan, server MCP GraphQL dapat mengkueri struktur skema Anda dan membuatnya tersedia untuk agen AI.

Langkah 3: Siapkan server MCP GraphQL

Apa yang Anda lakukan: Menginstal dan mengonfigurasi server Node.js lokal yang mengimplementasikan Protokol Konteks Model. Server ini bertindak sebagai penerjemah antara agen AI dan Fabric GraphQL API Anda.

Mengapa hal ini penting: Server MCP menyediakan antarmuka standar yang dipahami agen AI. Saat agen AI terhubung, agen AI dapat menemukan alat apa yang tersedia (introspeksi dan kueri), memanggil alat tersebut, dan menerima respons—semua tanpa Anda menulis kode integrasi kustom untuk setiap platform AI.

Sekarang setelah Anda memiliki kredensial autentikasi (Langkah 1) dan introspeksi diaktifkan (Langkah 2), Anda siap untuk mengonfigurasi server untuk menggunakannya.

Salin repositori contoh

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

Pasang dependensi

npm install

Mengonfigurasi variabel lingkungan

Buat .env file di akar proyek dengan konfigurasi Anda:

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

Ganti nilai tempat penampung dengan:

MICROSOFT_FABRIC_API_URL: Titik akhir GraphQL Anda dari portal Fabric
MICROSOFT_FABRIC_TENANT_ID: ID penyewa Azure Anda
MICROSOFT_FABRIC_CLIENT_ID: ID klien pendaftaran aplikasi Anda
MICROSOFT_FABRIC_CLIENT_SECRET: Rahasia klien pendaftaran aplikasi Anda

Mulai server MCP GraphQL

node FabricGraphQL_MCP.js

Server dimulai pada http://localhost:3000 dan ditampilkan:

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

Alat MCP yang tersedia

Server GraphQL MCP menyediakan dua alat utama:

`introspect-schema`

Tujuan: Mengambil skema GraphQL lengkap
Parameter: Tidak ada
Penggunaan: Harus dipanggil terlebih dahulu sebelum membuat kueri

`query-graphql`

Tujuan: Menjalankan kueri GraphQL terhadap data Fabric Anda
Parameter:
- query (wajib): String kueri GraphQL
- variables (opsional): Objek variabel GraphQL
Penggunaan: Untuk semua operasi pengambilan dan manipulasi data

Memahami alur kerja

Alur kerja MCP GraphQL yang khas mengikuti pola ini:

Penemuan Skema: Agen AI harus terlebih dahulu memanggil introspect-schema alat untuk memahami skema dan data yang tersedia
Perencanaan Kueri: Agen menganalisis permintaan bahasa alami Anda dan skema GraphQL
Pembuatan Kueri: Agen membuat kueri GraphQL yang sesuai
Eksekusi: Agen memanggil query-graphql alat dengan kueri yang dihasilkan
Pemrosesan Respons: Agen memformat dan menyajikan hasilnya

Langkah 4: Uji server MCP GraphQL

Apa yang Anda lakukan: Memverifikasi bahwa server MCP Anda dapat mengautentikasi ke Fabric, mengambil skema Anda, dan menjalankan kueri—sebelum menyambungkan agen AI.

Mengapa hal ini penting: Pengujian secara manual memastikan semuanya dikonfigurasi dengan benar. Jika pengujian ini lulus, Anda tahu agen AI dapat berhasil terhubung di Langkah 5.

Memverifikasi kesehatan server

Pertama, konfirmasikan server berjalan dan dapat mengautentikasi ke Fabric.

Jika menggunakan PowerShell:

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

Menggunakan cURL:

curl http://localhost:3000/health

Anda harus menerima respons yang menunjukkan server sedang berjalan, mirip dengan:

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

Menguji introspeksi skema

Selanjutnya, verifikasi bahwa server dapat mengambil skema GraphQL Anda melalui introspeksi. Ini memanggil introspect-schema alat MCP.

Jika menggunakan 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

Menggunakan 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": {}
    }
  }'

Ini harus mengembalikan definisi skema GraphQL Anda.

Menguji kueri GraphQL

Terakhir, uji menjalankan kueri GraphQL aktual melalui server MCP. Contoh ini mengkueri semua nama jenis dalam skema Anda menggunakan query-graphql alat MCP.

Jika menggunakan 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

Menggunakan 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 } } }"
      }
    }
  }'

Ini mengembalikan daftar semua jenis dalam skema GraphQL Anda.

Langkah 5: Menyambungkan agen AI

Apa yang Anda lakukan: Mengonfigurasi alat AI untuk menggunakan server MCP lokal Anda sebagai sumber data.

Mengapa hal ini penting: Di sinilah semuanya datang bersama-sama. Setelah terhubung, agen AI Anda dapat menemukan skema Fabric Anda melalui introspeksi dan menghasilkan kueri GraphQL berdasarkan permintaan bahasa alami. AI menangani sintaks kueri—Anda hanya mengajukan pertanyaan dalam bahasa Inggris biasa.

GitHub Copilot di Visual Studio Code

Menginstal ekstensi GitHub Copilot di Visual Studio Code

Konfigurasikan server GraphQL MCP di pengaturan Copilot Anda:

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

Dalam obrolan Copilot, pertama-tama minta untuk introspiksi skema lalu coba ajukan pertanyaan yang berkaitan dengan data yang diintrosekksi dalam bahasa alami, misalnya:

IDE Kursor

Buka pengaturan Kursor

Tambahkan konfigurasi server MCP:

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

Dalam obrolan, pertama-tama minta untuk menganalisis skema, kemudian mencoba mengajukan pertanyaan yang berkaitan dengan data yang telah dianalisis dalam bahasa sehari-hari.

Apa yang Anda buat

Selamat! Anda sekarang memiliki server MCP GraphQL yang berfungsi yang:

Mengautentikasi ke Fabric menggunakan kredensial prinsipal layanan
Mengekspos skema data Fabric Anda melalui introspeksi
Menerjemahkan permintaan agen AI ke dalam kueri GraphQL
Mengembalikan data dalam format agen AI dapat memahami dan menyajikan

Agen AI Anda (seperti GitHub Copilot) sekarang dapat:

Secara otomatis menemukan data apa yang tersedia di ruang kerja Fabric Anda
Hasilkan kueri GraphQL yang benar berdasarkan pertanyaan bahasa alami
Mengambil dan memformat hasil tanpa Anda menulis kode kueri apa pun

Server lokal ini ditujukan untuk pengembangan dan pembelajaran. Bagian berikut mencakup pertimbangan penting untuk penyebaran produksi dan skenario pemecahan masalah umum.

Pertimbangan keamanan

Meskipun server GraphQL MCP lokal harus diimplementasikan untuk tujuan pengembangan hanya seperti yang dijelaskan dalam tutorial ini, server ini diimplementasikan dengan transportasi HTTP, sehingga lebih mudah untuk menggunakannya sebagai titik awal untuk integrasi berbasis server klien atau web yang lebih kompleks. Jika Anda menerapkan server MCP GraphQL dalam lingkungan produksi:

Menggunakan Azure Key Vault untuk menyimpan rahasia alih-alih .env file
Menerapkan aturan otorisasi, keamanan jaringan, dan firewall yang tepat
Mengaktifkan pencatatan audit untuk semua kueri GraphQL
Menggunakan Azure App Service atau Container Instances untuk hosting
Menerapkan pembatasan laju dan autentikasi untuk titik akhir MCP
Mengganti rahasia klien dan sertifikat secara teratur

Penyelesaian Masalah

Masalah dan solusi umum

Kesalahan autentikasi

Memverifikasi Pendaftaran Aplikasi Azure Anda memiliki izin yang benar
Periksa apakah entitas layanan diaktifkan di penyewa Fabric Anda
Pastikan rahasia klien Anda tidak kedaluwarsa

Introspeksi skema gagal

Konfirmasikan introspeksi diaktifkan di pengaturan API GraphQL Anda
Periksa apakah URL titik akhir GraphQL Anda sudah benar
Memverifikasi konektivitas jaringan ke ruang kerja Fabric Anda

Agen AI tidak mengenali alat

Mulai ulang klien AI Anda setelah perubahan konfigurasi
Pastikan URL server MCP dapat diakses
Periksa log server untuk pesan kesalahan apa pun

Kesalahan eksekusi kueri

Tinjau konsol server untuk kueri dan kesalahan yang tercatat
Pastikan kueri Anda cocok dengan skema yang tersedia
Periksa apakah Anda memiliki izin yang sesuai untuk data yang diminta

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-01-21

Bagikan melalui

Menyambungkan Agen AI ke Fabric API untuk GraphQL dengan server Protokol Konteks Model (MCP) lokal

Apa itu Protokol Konteks Model (MCP)?

Mengapa GraphQL sangat ideal untuk MCP

Prasyarat

Langkah 1: Mengonfigurasi akses prinsipal layanan

Langkah 2: Mengaktifkan introspeksi GraphQL (memerlukan admin ruang kerja)

Langkah 3: Siapkan server MCP GraphQL

Salin repositori contoh

Pasang dependensi

Mengonfigurasi variabel lingkungan

Mulai server MCP GraphQL

Alat MCP yang tersedia

introspect-schema

query-graphql

Memahami alur kerja

Langkah 4: Uji server MCP GraphQL

Memverifikasi kesehatan server

Menguji introspeksi skema

Menguji kueri GraphQL

Langkah 5: Menyambungkan agen AI

GitHub Copilot di Visual Studio Code

IDE Kursor

Apa yang Anda buat

Pertimbangan keamanan

Penyelesaian Masalah

Masalah dan solusi umum

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan:

`introspect-schema`

`query-graphql`