Menyambungkan Azure Database for PostgreSQL ke Microsoft Foundry dengan MCP

Server MCP (Model Context Protocol) Azure Database for PostgreSQL memungkinkan agen AI di Microsoft Foundry berinteraksi dengan database PostgreSQL melalui kueri bahasa alami. Integrasi ini mendukung operasi SQL, pencarian vektor, penemuan skema, dan analisis data dengan keamanan tingkat perusahaan.

Artikel ini memperlihatkan kepada Anda cara menyiapkan dan mengonfigurasi MCP Server Azure PostgreSQL dengan agen Foundry untuk interaksi database bahasa alami.

Apa itu MCP dan bagaimana cara kerjanya?

Model Context Protocol (MCP) adalah standar terbuka yang memungkinkan aplikasi AI terhubung dengan aman ke sumber dan alat data eksternal. Server MCP Azure PostgreSQL bertindak sebagai jembatan antara agen Foundry dan database PostgreSQL Anda.

Sistem ini menggunakan tiga komponen utama:

Microsoft Foundry Agent (Klien): Mengautentikasi ke Server MCP Azure PostgreSQL dengan menggunakan identitas terkelolanya
Azure PostgreSQL MCP Server (Server): Berjalan di Azure Container Apps, menggunakan identitas terkelola untuk akses PostgreSQL
Database PostgreSQL (Target): Azure Database for PostgreSQL dengan autentikasi Microsoft Entra ID

Arsitektur ini memastikan isolasi keamanan yang tepat dengan identitas terkelola terpisah untuk autentikasi klien dan akses database.

Fitur dan kemampuan

Azure PostgreSQL MCP Server menyediakan kemampuan integrasi database yang komprehensif:

Operasi SQL - Menjalankan kueri dan mengelola data. Melakukan analitik melalui bahasa alami
Pencarian Vektor - Gunakan penyematan bertenaga AI untuk pencarian kesamaan
Penemuan Skema - Analisis tabel dan kolom otomatis dengan pemetaan hubungan
Keamanan Perusahaan - Identitas terkelola Azure dan autentikasi ID Microsoft Entra
Bahasa Alami - Database kueri dengan menggunakan AI percakapan tanpa pengetahuan SQL
Penyebaran Mudah - Penyebaran Azure yang mudah dengan penyiapan infrastruktur lengkap

Contoh kasus penggunaan

Dengan integrasi MCP, agen AI Anda dapat menangani kueri seperti:

"Daftar semua pelanggan yang melakukan pesanan dalam 30 hari terakhir"
"Tunjukkan kepada saya lima produk terlaris berdasarkan kuantitas"
"Apa skema tabel pesanan?"
"Hitung nilai pesanan rata-rata menurut segmen pelanggan"
"Temukan tabel yang berisi informasi pelanggan"

Prasyarat

Sebelum memulai, pastikan Anda memiliki alat, akun, dan izin yang diperlukan untuk menyebarkan dan mengonfigurasi Server MCP PostgreSQL. Memastikan prasyarat ini siap dapat mengurangi gangguan dan membantu menjamin integrasi yang lancar dengan Foundry.

Azure CLI (versi terbaru)
Azure Database for PostgreSQL Flexible Server dengan autentikasi ID Microsoft Entra diaktifkan
Proyek Pengecoran
Microsoft .NET
Langganan Azure dengan izin yang sesuai untuk membuat sumber daya

Penyebaran mulai cepat

Sebarkan infrastruktur Azure MCP PostgreSQL Server lengkap dengan menggunakan Azure Developer CLI (azd):

Langkah 1: Terapkan dengan azd up

Cara tercepat untuk memulai adalah dengan menggunakan skrip penyebaran otomatis.

Pertama, mengkloning repositori:

# Clone the repository
git clone https://github.com/Azure-Samples/azure-postgres-mcp-demo
cd azure-postgres-mcp-demo

Buka infra/main.parameters.json dan perbarui 2 nilai ini

Pengaturan	Description
`postgresResourceId`	ID Sumber Daya Server Fleksibel Azure Database for PostgreSQL yang ingin Anda sambungkan
`aifProjectResourceId`	ID sumber daya proyek Azure Foundry yang ingin Anda gunakan

a. postgresResourceId Perbarui variabel agar sesuai dengan Postgres DB yang ingin Anda akses.

"postgresResourceId": {
  "value": "/subscriptions/<subscription-id>/resourceGroups/<postgres-resource-group>/providers/Microsoft.DBforPostgreSQL/flexibleServers/<postgres-server-name>"
}

Nota

Temukan ID Sumber Daya Azure Database for PostgreSQL Anda di portal Microsoft Azure Anda. JSON View → Resource ID: Cuplikan layar halaman detail Azure.

b. aifProjectResourceId Perbarui variabel agar sesuai dengan sumber daya proyek Foundry yang ingin Anda gunakan

"aifProjectResourceId": {
  "value": "/subscriptions/<subscription-id>/resourceGroups/<aifoundry-resource-group>/providers/Microsoft.CognitiveServices/accounts/<aifoundry-resource-name>/projects/<aifoundry-project-name>"
}

Nota

Temukan ID Sumber Daya proyek Foundry Anda di portal Microsoft Azure Anda. JSON View → Resource ID: Tangkapan layar detail Foundry.

Buat lingkungan azd baru dan sebarkan. Pastikan Anda berada di direktori utama (azure-postgres-mcp-demo):
```
azd env new
```
```
azd up
```
Penyebaran biasanya memakan waktu 5-8 menit. Setelah penyebaran selesai, azd akan menghasilkan URL server MCP + info Identitas Terkelola yang akan Anda gunakan di langkah berikutnya.

Penyebaran ini menghasilkan:

Aplikasi Kontainer Azure yang menjalankan server MCP dengan Identitas Terkelola (Akses pembaca ke server PostgreSQL Anda)
Pendaftaran Aplikasi Id Entra untuk autentikasi server MCP
Penugasan Peran Entra ID untuk Foundry agar dapat mengautentikasi dengan server MCP

Langkah 2: Mengonfigurasi akses database

Setelah penyebaran selesai, berikan akses server MCP ke database PostgreSQL Anda:

Sambungkan ke server PostgreSQL Anda menggunakan psql atau klien PostgreSQL pilihan Anda:

Atur variabel lingkungan berikut dengan menyalin dan menempelkan baris di bawah ini ke terminal bash Anda (WSL, Azure Cloud Shell, dll.). Temukan detail untuk koneksi Anda di Tab Sambungkan di Sumber Daya Postgres Anda di portal Microsoft Azure:
```
export PGHOST=<your-database-host-name>
export PGUSER=<your-admin-username>
export PGPORT=5432
export PGDATABASE=<your-database-name>
export PGPASSWORD="$(az account get-access-token --resource https://ossrdbms-aad.database.windows.net --query accessToken --output tsv)" 
```
Kemudian jalankan:
```
psql
```
Atau, Anda dapat terhubung melalui Sambungkan dan kueri database dengan ekstensi PostgreSQL untuk Visual Studio Code.
Buat prinsipal database untuk identitas terkelola server MCP:
```
SELECT * FROM pgaadauth_create_principal('<CONTAINER_APP_IDENTITY_NAME>', false, false);
```
Ganti <CONTAINER_APP_IDENTITY_NAME> dengan nama identitas terkelola dari output penyebaran Anda (misalnya, azmcp-postgres-server-nc3im7asyw).

Petunjuk / Saran

Gunakan azd env get-values perintah untuk menemukan CONTAINER_APP_IDENTITY_NAME nilai

Berikan izin yang sesuai ke identitas terkelola:

-- Grant SELECT on a specific table
GRANT SELECT ON TABLE_NAME TO "<CONTAINER_APP_IDENTITY_NAME>";

Untuk memberikan perizinan ke semua tabel di masa mendatang dan yang sudah ada

-- Grant SELECT on all existing tables
GRANT SELECT ON ALL TABLES IN SCHEMA public TO "<CONTAINER_APP_IDENTITY_NAME>";

-- Grant SELECT on all future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO "<CONTAINER_APP_IDENTITY_NAME>";

Mengonfigurasi integrasi Foundry

Setelah Anda menyebarkan server MCP, sambungkan ke Foundry:

Menyambungkan melalui portal Foundry

Buka proyek Foundry Anda di portal Microsoft Azure.
Buka Build → Buat agen.
Di bagian alat, pilih + Tambahkan.
Pilih tab Kustom dan pilih Protokol Konteks Model.
Pilih Microsoft Entra → Project Managed Identity sebagai metode autentikasi.
Masukkan ENTRA_APP_CLIENT_ID Anda sebagai penonton (dari output penyebaran Anda).

Petunjuk / Saran

Gunakan azd env get-values untuk menemukan nilainya ENTRA_APP_CLIENT_ID .

Tambahkan instruksi ke agen Anda:

You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.

Use these parameters when calling PostgreSQL MCP tools:
- database: <YOUR_DATABASE_NAME>
- resource-group: <YOUR_RESOURCE_GROUP>
- server: <YOUR_SERVER_NAME>
- subscription: <YOUR_SUBSCRIPTION_ID>
- user: <CONTAINER_APP_IDENTITY_NAME>

Menguji integrasi

Setelah terhubung, uji integrasi MCP Anda dengan kueri bahasa alami.

Anda dapat menemukan tabel.

List all tables in my PostgreSQL database

Anda dapat mengambil data menggunakan bahasa alami.

Show me the latest 10 records from the orders table

Find customers who placed orders in the last 30 days

Anda dapat melakukan pencarian vektor dan menentukan contoh kueri untuk meningkatkan akurasi.

Do a vector search for "product for customer that love to hike"

Ini adalah contoh pencarian vektor.

- `SELECT id, name, price, embedding <=> azure_openai.create_embeddings(
'text-embedding-3-small',
'query example'
)::vector AS similarity
FROM public.products
ORDER BY similarity
LIMIT 10;

Agen AI secara otomatis menerjemahkan permintaan ini ke dalam operasi database yang sesuai melalui server MCP.

Menyambungkan melalui Foundry SDK

Untuk akses terprogram, gunakan konfigurasi MCP berikut dalam kode Python Anda:

Buat .env file dari .env.example:
```
cd client
cp .env.example .env
```

Perbarui semua nilai untuk menjalankan agen Anda. Semua nilai dapat ditemukan di Proyek Foundry Anda.

Nama Variabel	Contoh Nilai	Description
`PROJECT_ENDPOINT`	`https://example-endpoint.services.ai.azure.com/api/projects/example-project`	Titik akhir proyek Foundry
`MODEL_DEPLOYMENT_NAME`	`example-model`	Nama model AI yang dijalankan
`MCP_SERVER_URL`	`https://example-mcp-server.azurecontainerapps.io`	URL titik akhir server MCP
`MCP_SERVER_LABEL`	`example-label`	Label untuk server MCP
`AZURE_OPENAI_API_KEY`	`your-azure-openai-api-key`	Kunci API layanan Azure OpenAI
`AZURE_OPENAI_ENDPOINT`	`https://example-openai-endpoint.openai.azure.com/`	Titik akhir layanan Azure OpenAI
`AZURE_OPENAI_API_VERSION`	`your-api-version`	Versi API untuk Azure OpenAI
`AZURE_SUBSCRIPTION_ID`	`your-azure-subscription-id`	Pengidentifikasi langganan Azure
`CONNECTION_NAME`	`your-connection-name`	Nama untuk koneksi database
`POSTGRES_SERVER`	`your-postgres-server`	Nama server PostgreSQL
`POSTGRES_DATABASE`	`your-postgres-database`	Nama database PostgreSQL
`POSTGRES_TABLE`	`your-postgres-table`	Tabel Target PostgreSQL
`POSTGRES_USER`	`your-postgres-user`	Pengguna PostgreSQL untuk autentikasi, gunakan CONTAINER_APP_IDENTITY_NAME di sini
`AZURE_RESOURCE_GROUP`	`your-azure-resource-group`	Nama grup sumber daya Azure

Jalankan sampel SDK Lengkap di client folder di GitHub Repo.

Contoh penggunaan Alat dan Konfigurasi MCP dalam kode sampel.

mcp_tool_config = {
   "type": "mcp",
   "server_url": "<MCP_SERVER_URL>",
   "server_label": "<MCP_SERVER_LABEL>",
   "server_authentication": {
      "type": "connection",
      "connection_name": "<CONNECTION_NAME>",
   }
}

mcp_tool_resources = {
   "mcp": [
      {
            "server_label": "<MCP_SERVER_LABEL>",
            "require_approval": "never"
      }
   ]
}

Keamanan

Saat menggunakan Azure MCP PostgreSQL Server, ketahui pertimbangan keamanan berikut:

Akses dan paparan data

Agen AI yang terhubung berpotensi mengakses data apa pun yang dapat diakses oleh server MCP
Server dapat menjalankan kueri SQL pada database dan tabel yang dapat diakses, namun server MCP dibatasi untuk hanya membaca operasi.
Agen yang terhubung dapat meminta dan menerima data melalui kueri bahasa alami

Fitur keamanan

Anda bisa menggunakan fitur keamanan berikut untuk melindungi data Anda:

Identitas Terkelola: Tidak ada kredensial yang disimpan dalam gambar kontainer.
Microsoft Entra ID Authentication: Autentikasi database yang aman.
RBAC: Kontrol akses berbasis peran untuk operasi database.
Keamanan Tingkat Baris: Kontrol akses halus di tingkat baris.

Praktik terbaik

Berikan izin database HANYA untuk skema dan tabel tertentu yang diperlukan untuk agen AI.
Gunakan prinsip hak istimewa paling sedikit - jangan berikan akses database yang luas.
Meninjau dan mengaudit izin yang diberikan secara teratur ke identitas terkelola server MCP.
Pertimbangkan untuk menggunakan database atau skema khusus untuk akses agen AI.
Mulailah dengan database pengujian yang hanya berisi data sampel yang tidak sensitif.

Troubleshoot

Jika Anda mengalami masalah dengan integrasi MCP PostgreSQL Server, bagian pemecahan masalah ini membantu Anda dengan cepat mengidentifikasi akar penyebab dan memulihkan masalah umum. Mulailah dengan pemeriksaan kesehatan dan log, lalu verifikasi autentikasi identitas terkelola, konektivitas jaringan, dan izin database.

Pemeriksaan kesehatan

# Check MCP server status
ping https://your-mcp-server.azurecontainerapps.io

Jika MCP aktif dan berjalan:

64 bytes from X.XXX.XXX.X: icmp_seq=0 ttl=108 time=92.748 ms

Jika MCP tidak berjalan:

ping: cannot resolve https://your-mcp-server.azurecontainerapps.io: Unknown host

Anda harus menjalankan kembali azd up.

Batasan dan pertimbangan

Tidak dapat memvalidasi Microsoft Entra ID ... nama tidak unik di tenant

Kesalahan: Seseorang di penyewa Anda sudah menyebarkan server Postgres MCP dengan nama azure-mcp-postgres-server

postgres=> SELECT * FROM pgaadauth_create_principal('azure-mcp-postgres-server', false, false);
ERROR:  Cannot validate Microsoft Entra ID user "azure-mcp-postgres-server" because its name isn't unique in the tenant.
Make sure it's correct and retry.
CONTEXT:  SQL statement "SECURITY LABEL for "pgaadauth" on role "azure-mcp-postgres-server" is 'aadauth'"
PL/pgSQL function pgaadauth_create_principal(text,boolean,boolean) line 23 at EXECUTE

Solusi: Perbarui acaName di infra/main.parameter.json ke nama yang berbeda, dan jalankan ulang penyebaran dengan azd up

Kesalahan autentikasi

Kesalahan: Unauthorized atau Forbidden
Solusi: Memverifikasi konfigurasi identitas terkelola dan izin akses PostgreSQL

Masalah koneksi

Kesalahan: Connection timeout atau Cannot connect to server
Solusi: Periksa aturan firewall PostgreSQL dan konfigurasi jaringan

Kesalahan izin

Kesalahan: Permission denied for relation
Solusi: Berikan izin yang sesuai ke identitas terkelola server MCP:
```
GRANT SELECT ON my_table TO "<CONTAINER_APP_IDENTITY_NAME>";
```

Debug dengan log

Lihat log Container Apps untuk pemecahan masalah:

# Stream Container Apps logs
az containerapp logs show -n your-mcp-container-name -g your-resource-group

# Check deployment status
az containerapp show -n your-mcp-container-name -g your-resource-group

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-11-25