Guida introduttiva: Usare SQL MCP Server con App Azure Container

• Azure IA Foundry
• .NET Aspire
• Visual Studio Code
• App per container di Azure

Importante

SQL MCP Server è disponibile in anteprima e questa documentazione e l'implementazione del motore è soggetta a modifiche durante questo periodo di valutazione.

Questa guida introduttiva illustra come distribuire SQL MCP Server in App Contenitore di Azure. Dopo la distribuzione, è possibile connettersi a esso da Visual Studio Code (VS Code), Microsoft Foundry o qualsiasi altro client MCP (Model Context Protocol) come endpoint server remoto.

Questo diagramma dell'architettura illustra una distribuzione cloud di produzione in Azure. In Azure, un ambiente di App Azure Container (rettangolo con bordo blu) contiene un server MCP (Model Context Protocol) (casella verde 3D). All'esterno del limite delle app contenitore ma ancora all'interno di Azure, un database SQL (cilindro blu) viene posizionato a destra. Una freccia curva si connette dal server MCP al database SQL. Questa architettura rappresenta una distribuzione di produzione scalabile in cui il server MCP viene eseguito come applicazione in contenitori che può essere ridimensionata automaticamente in base alla richiesta mantenendo al tempo stesso connessioni sicure al database gestito separatamente, rendendolo adatto per i carichi di lavoro di produzione in cui gli agenti di intelligenza artificiale necessitano di un accesso affidabile ai dati SQL.

Prerequisiti

Sottoscrizione di Azure

È necessaria una sottoscrizione di Azure attiva. Se non ne hai uno:

https://azure.microsoft.com/free

Azure CLI

Installare l'interfaccia della riga di comando di Azure per distribuire le risorse:

Windows

winget install Microsoft.AzureCLI

macOS

brew install azure-cli

.NET 9+

Questo strumento potrebbe essere già installato. Eseguire dotnet --version e confermare che segnala la versione 9 o successiva.

Windows

winget install Microsoft.DotNet.Runtime.9

Interfaccia della riga di comando di Generatore API dati

dotnet new tool-manifest
dotnet tool install microsoft.dataapibuilder --prerelease

Annotazioni

SQL MCP Server è attualmente in versione preliminare. L'uso del --prerelease flag garantisce di ottenere la versione più recente di Data API Builder con tutte le funzionalità usate in questa guida introduttiva.

PowerShell

Installare PowerShell se non è già installato.

dotnet tool install --global PowerShell

Passaggio 1: Creare e distribuire il database SQL di Azure

1. Accedere ad Azure

az login
az account set --subscription "<your-subscription-id>"

2. Impostare le variabili per la distribuzione

$RESOURCE_GROUP = "rg-sql-mcp"
$LOCATION = "eastus"
$SQL_SERVER = "sql-mcp-$(Get-Random -Minimum 1000 -Maximum 9999)"
$SQL_DATABASE = "ProductsDB"
$SQL_ADMIN = "sqladmin"
$SQL_PASSWORD = "<YourStrongPassword123!>"

3. Creare un gruppo di risorse

az group create \
  --name $RESOURCE_GROUP \
  --location $LOCATION

4. Creare SQL Server di Azure

az sql server create \
  --name $SQL_SERVER \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --admin-user $SQL_ADMIN \
  --admin-password $SQL_PASSWORD

5. Configurare il firewall per consentire i servizi di Azure

az sql server firewall-rule create \
  --resource-group $RESOURCE_GROUP \
  --server $SQL_SERVER \
  --name AllowAzureServices \
  --start-ip-address 0.0.0.0 \
  --end-ip-address 0.0.0.0

6. Creare il database

az sql db create \
  --resource-group $RESOURCE_GROUP \
  --server $SQL_SERVER \
  --name $SQL_DATABASE \
  --service-objective S0

7. Creare una tabella Products con dati di esempio

Ottieni prima la stringa di connessione:

$CONNECTION_STRING = "Server=tcp:$SQL_SERVER.database.windows.net,1433;Database=$SQL_DATABASE;User ID=$SQL_ADMIN;Password=$SQL_PASSWORD;Encrypt=true;TrustServerCertificate=false;Connection Timeout=30;"

Creare un file create-products.sqldi script SQL:

CREATE TABLE dbo.Products
(
    ProductID INT NOT NULL PRIMARY KEY IDENTITY(1,1),
    ProductName NVARCHAR(100) NOT NULL,
    Category NVARCHAR(50) NOT NULL,
    UnitPrice DECIMAL(10,2) NOT NULL,
    UnitsInStock INT NOT NULL,
    Discontinued BIT NOT NULL DEFAULT 0
);

INSERT INTO dbo.Products (ProductName, Category, UnitPrice, UnitsInStock, Discontinued) VALUES
('Laptop Pro 15', 'Electronics', 1299.99, 45, 0),
('Wireless Mouse', 'Electronics', 29.99, 150, 0),
('Office Chair', 'Furniture', 249.99, 30, 0),
('Standing Desk', 'Furniture', 599.99, 15, 0),
('Coffee Maker', 'Appliances', 89.99, 60, 0),
('Notebook Set', 'Office Supplies', 12.99, 200, 0),
('USB-C Hub', 'Electronics', 49.99, 80, 0),
('Desk Lamp', 'Furniture', 39.99, 100, 0),
('Bluetooth Headphones', 'Electronics', 149.99, 50, 0),
('Water Bottle', 'Office Supplies', 19.99, 120, 0);

Eseguirlo usando VS Code, SQL Server Management Studio o sqlcmd.

Passaggio 2: Configurare SQL MCP Server

1. Creare il dab-config.json

Inizializzare la configurazione:

dab init `
  --database-type mssql `
  --connection-string "@env('MSSQL_CONNECTION_STRING')" `
  --host-mode Production `
  --config dab-config.json

2. Aggiungere l'entità Products con descrizioni

dab add Products `
  --source dbo.Products `
  --permissions "anonymous:read" `
  --description "Product catalog with pricing, category, and inventory information"

3. Fornire al contesto dell'agente di intelligenza artificiale le descrizioni dei campi

Aggiungere descrizioni dei campi per aiutare gli agenti di intelligenza artificiale a comprendere lo schema del database:

dab update Products `
  --fields.name ProductID `
  --fields.description "Unique product identifier" `
  --fields.primary-key true

dab update Products `
  --fields.name ProductName `
  --fields.description "Name of the product"

dab update Products `
  --fields.name Category `
  --fields.description "Product category (Electronics, Furniture, Office Supplies, Appliances)"

dab update Products `
  --fields.name UnitPrice `
  --fields.description "Retail price per unit in USD"

dab update Products `
  --fields.name UnitsInStock `
  --fields.description "Current inventory count available for purchase"

dab update Products `
  --fields.name Discontinued `
  --fields.description "True if product is no longer available for sale"

Passaggio 3: Distribuire SQL MCP Server in App Contenitore di Azure

1. Creare un ambiente di app contenitore

$CONTAINERAPP_ENV = "sql-mcp-env"
$CONTAINERAPP_NAME = "sql-mcp-server"

az containerapp env create `
  --name $CONTAINERAPP_ENV `
  --resource-group $RESOURCE_GROUP `
  --location $LOCATION

2. Creare la configurazione con codifica Base64

$CONFIG_JSON = Get-Content dab-config.json -Raw
$CONFIG_BYTES = [System.Text.Encoding]::UTF8.GetBytes($CONFIG_JSON)
$CONFIG_BASE64 = [Convert]::ToBase64String($CONFIG_BYTES)

3. Distribuire il contenitore SQL MCP Server

az containerapp create `
  --name $CONTAINERAPP_NAME `
  --resource-group $RESOURCE_GROUP `
  --environment $CONTAINERAPP_ENV `
  --image mcr.microsoft.com/azure-databases/data-api-builder:latest `
  --target-port 5000 `
  --ingress external `
  --min-replicas 1 `
  --max-replicas 3 `
  --secrets "mssql-connection-string=$CONNECTION_STRING" "dab-config-base64=$CONFIG_BASE64" `
  --env-vars "MSSQL_CONNECTION_STRING=secretref:mssql-connection-string" "DAB_CONFIG_BASE64=secretref:dab-config-base64" `
  --cpu 0.5 `
  --memory 1.0Gi

Il gruppo di risorse dovrebbe essere simile all'esempio seguente:

4. Ottenere l'URL dell'endpoint MCP

$MCP_URL = az containerapp show `
  --name $CONTAINERAPP_NAME `
  --resource-group $RESOURCE_GROUP `
  --query "properties.configuration.ingress.fqdn" `
  --output tsv

Write-Host "Your MCP Server URL: https://$MCP_URL/mcp"

Salvare questo URL: viene usato per connettersi dai client MCP.

5. Testare la distribuzione

curl "https://$MCP_URL/health"

Dovrebbe essere visualizzata una risposta corretta.

Connettersi dai client MCP

SQL MCP Server è ora distribuito e pronto per l'uso. Ecco come connettersi da vari client:

Visual Studio Code (VS Code)

Seguire la Guida rapida con VS Code e utilizzare l'URL del server MCP distribuito invece di eseguire localmente.

Da Microsoft Foundry

Per aggiungere il server MCP come MCP Tool personalizzato, seguire la Guida rapida con Microsoft Foundry.

Altri clienti MCP

Usare l'URL del server MCP del passaggio 3.4 per connettersi da qualsiasi client compatibile con MCP.

Monitoraggio e risoluzione dei problemi

Visualizzare i log delle app contenitore

az containerapp logs show \
  --name $CONTAINERAPP_NAME \
  --resource-group $RESOURCE_GROUP \
  --follow

Controllare l'integrità dell'endpoint MCP

curl "https://$MCP_URL/health"

Problemi comuni

Errore di connessione non riuscita

• Verificare che l'ingresso di Container Apps sia impostato su external
• Verificare che la stringa di connessione SQL sia corretta
• Controllare le regole del firewall in AZURE SQL

Nessun dato restituito

• Verificare che la tabella Products sia stata creata e popolata
• Controllare le autorizzazioni per le entità in dab-config.json
• Controllare i log dei container apps per errori

Le prestazioni sono lente

• Prendere in considerazione l'aumento dell'allocazione di CPU/memoria
• Controllare se è necessario aumentare le repliche
• Esaminare le metriche di Application Insights

Procedure consigliate per la sicurezza per la produzione

• Abilitare l'autenticazione - Configurare l'autenticazione con ID Entra di Microsoft anziché l'accesso anonimo
• Usare le identità gestite - Consentire alle app contenitore di eseguire l'autenticazione a SQL usando l'identità gestita
• Implementare CORS : limitare i domini che possono accedere al server MCP
• Abilitare la limitazione della frequenza - Proteggere da abusi
• Usare Azure Key Vault - Archiviare le stringhe di connessione in modo sicuro
• Monitorare con Application Insights - Tenere traccia dell'utilizzo e delle prestazioni
• Limitare le autorizzazioni : concedere solo i livelli di accesso necessari

Pulire le risorse

Al termine, eliminare il gruppo di risorse per rimuovere tutte le risorse:

az group delete --name $RESOURCE_GROUP --yes --no-wait

Contenuto esterno

• Script di PowerShell di esempio
• Panoramica di SQL MCP Server
• Strumenti di manipolazione dei dati in SQL MCP Server
• Aggiunta di descrizioni semantiche al server SQL MCP