Início Rápido: Usar o SQL MCP Server com aplicativos de contêiner do Azure

• Fundição de IA do Azure
• .NET Aspire
• Código do Visual Studio
• Aplicativos de Contêiner do Azure

Importante

O SQL MCP Server está em versão prévia e esta documentação e a implementação do mecanismo estão sujeitas a alterações durante esse período de avaliação.

Este início rápido mostra como implantar o SQL MCP Server nos Aplicativos de Contêiner do Azure. Depois de implantado, você pode se conectar a ele por meio do Visual Studio Code (VS Code), do Microsoft Foundry ou de qualquer outro cliente MCP (Protocolo de Contexto de Modelo) como endpoint de servidor remoto.

Este diagrama de arquitetura ilustra uma implantação de nuvem de produção no Azure. No Azure, um ambiente de Aplicativos de Contêiner do Azure (retângulo de borda azul) contém um servidor MCP (Protocolo de Contexto de Modelo) (caixa 3D verde). Fora do limite de aplicativos de contêiner, mas ainda dentro do Azure, um banco de dados SQL (cilindro azul) é posicionado à direita. Uma seta curvada se conecta do servidor MCP ao banco de dados SQL. Essa arquitetura representa uma implantação de produção escalonável em que o servidor MCP é executado como um aplicativo em contêineres que pode ser dimensionado automaticamente com base na demanda, mantendo conexões seguras com o banco de dados gerenciado separadamente, tornando-o adequado para cargas de trabalho de produção em que os agentes de IA precisam de acesso confiável aos dados SQL.

Pré-requisitos

Assinatura do Azure

Você precisa de uma assinatura ativa do Azure. Se você não tiver um:

https://azure.microsoft.com/free

CLI do Azure

Instale a CLI do Azure para implantar recursos:

Windows

winget install Microsoft.AzureCLI

macOS

brew install azure-cli

.NET 9+

Talvez você já tenha essa ferramenta instalada. Execute o dotnet --version e confirme que relata a versão 9 ou posterior.

Windows

winget install Microsoft.DotNet.Runtime.9

CLI do construtor de API de Dados

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

Observação

O SQL MCP Server está atualmente em pré-lançamento. O uso do --prerelease sinalizador garante que você obtenha a versão mais recente do construtor de API de Dados com todos os recursos usados neste início rápido.

PowerShell

Instale o PowerShell se ele ainda não estiver instalado.

dotnet tool install --global PowerShell

Etapa 1: Criar e implantar o Banco de Dados SQL do Azure

1. Entrar no Azure

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

2. Definir variáveis para sua implantação

$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. Criar um grupo de recursos

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

4. Criar o SQL Server do Azure

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

5. Configurar o firewall para permitir serviços do 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. Criar o banco de dados

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

7. Criar uma tabela Produtos com dados de exemplo

Obtenha sua string de conexão primeiro:

$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;"

Criar um arquivo create-products.sqlde 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);

Execute-o usando o VS Code, o SQL Server Management Studio ou o sqlcmd.

Etapa 2: Configurar o SQL MCP Server

1. Criar seu dab-config.json

Inicialize a configuração:

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

2. Adicionar a entidade Produtos com descrições

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

3. Fornecer contexto do agente de IA com descrições de campo

Adicione descrições de campo para ajudar os agentes de IA a entender seu esquema de banco de dados:

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"

Etapa 3: Implantar o SQL MCP Server nos Aplicativos de Contêiner do Azure

1. Criar ambiente de Aplicativos de Contêiner

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

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

2. Criar configuração codificada em 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. Implantar o contêiner do 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

Seu grupo de recursos deve ser semelhante ao seguinte exemplo:

4. Obter a URL do ponto de extremidade 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"

Salve essa URL – use-a para se conectar a partir de clientes MCP.

5. Testar sua implantação

curl "https://$MCP_URL/health"

Você deve ver uma resposta saudável.

Conectar-se a partir de clientes MCP

Seu SQL MCP Server agora está implantado e pronto para uso. Veja como se conectar de vários clientes:

Visual Studio Code (VS Code)

Siga o Guia de início rápido com o VS Code e use a URL do seu servidor MCP implantado em vez de executar localmente.

Microsoft Foundry

Para adicionar seu servidor MCP como uma Ferramenta MCP Personalizada, siga o guia de Início Rápido com o Microsoft Foundry .

Outros clientes MCP

Use a URL do servidor MCP da Etapa 3.4 para se conectar de qualquer cliente compatível com MCP.

Monitoramento e solução de problemas

Exibir logs de Aplicações de Contêiner

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

Verificar a integridade do ponto de extremidade do MCP

curl "https://$MCP_URL/health"

Problemas comuns

Erro de falha na conexão

• Verifique se a entrada de Aplicativos de Contêiner está definida como external
• Verificar se a cadeia de conexão SQL está correta
• Verificar regras de firewall no SQL do Azure

Nenhum dado retornado

• Verificar se a tabela Produtos foi criada e preenchida
• Verificar permissões de entidade em dab-config.json
• Examinar os logs de Aplicativos em Containers em busca de erros

O desempenho é lento

• Considere aumentar a alocação de CPU/memória
• Verificar se você precisa aumentar o número de réplicas
• Examinar as métricas do Application Insights

Práticas recomendadas de segurança para produção

• Habilitar autenticação – Configurar a autenticação do Microsoft Entra ID em vez de acesso anônimo
• Usar identidades gerenciadas – Permitir que os Aplicativos de Contêiner se autentiquem no SQL usando a identidade gerenciada
• Implementar CORS – Restringir quais domínios podem acessar seu servidor MCP
• Habilitar limitação de taxa – Proteger contra abuso
• Usar o Azure Key Vault – Armazenar cadeias de conexão com segurança
• Monitorar com o Application Insights – Acompanhar o uso e o desempenho
• Restringir permissões – conceder apenas os níveis de acesso necessários

Limpar os recursos

Quando terminar, exclua o grupo de recursos para remover todos os recursos:

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

Conteúdo externo

• Exemplo de script do PowerShell
• Visão geral do SQL MCP Server
• Ferramentas de manipulação de dados no SQL MCP Server
• Adicionando descrições semânticas ao SQL MCP Server