Início Rápido: Usar o SQL MCP Server com o .NET Aspire

• 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 usa o Aspire para criar uma solução baseada em contêiner. A solução inclui:

• Um banco de dados SQL com dados de exemplo
• Um servidor MCP (Protocolo de Contexto de Modelo SQL) alimentado pelo construtor de API de Dados
• Inspetor MCP para testes

O Aspire executa tudo para você, inicia serviços e conecta contêineres e interrompe os serviços quando você o fecha.

Este diagrama de arquitetura ilustra um ambiente de testes em contêiner em uma Máquina Local com um ambiente Docker (retângulo de borda tracejada). Dentro do contêiner do Docker, três componentes são organizados: uma ferramenta mcp inspector (caixa laranja), um servidor MCP (Protocolo de Contexto de Modelo) (caixa 3D verde) e um banco de dados SQL (cilindro azul). Uma seta curva se estende do Inspetor MCP para o servidor MCP, que tem uma conexão bidirecional com o banco de dados. Essa configuração permite que os desenvolvedores testem, depurem e inspecionem as interações do servidor MCP com um banco de dados SQL em um ambiente isolado em contêineres, com o Inspetor MCP servindo como uma ferramenta de diagnóstico para validar a comunicação entre agentes de IA e o banco de dados.

Pré-requisitos

Instale essas ferramentas antes de começar.

1. .NET 10

Nesta etapa, você prepara seu computador com os pré-requisitos necessários para este início rápido.

Importante

Talvez você já tenha essa ferramenta instalada. Teste-o executando dotnet --version e confirme que ele exibe a versão 10 ou posterior. Se você executar essa instalação e o .NET já estiver presente, ele atualizará seu sistema sem causar problemas.

Windows

winget install Microsoft.DotNet.SDK.10

Ou baixe

https://get.dot.net

2. Runtime do contêiner

Nesta etapa, você instalará o Docker Desktop para dar suporte ao projeto Aspire.

Importante

Talvez você já tenha essa ferramenta instalada. Teste-o executando docker --version para confirmar se o Docker está disponível. Se você executar essa instalação e o Docker já estiver presente, ele atualizará seu sistema sem causar problemas.

Windows

winget install Docker.DockerDesktop

macOS

brew install --cask docker

Observação

O Podman também funciona, mas a configuração varia. Os desenvolvedores que preferem o Podman podem adaptar essas etapas.

3. Aspire e ferramentas de construção de API de Dados

Nesta etapa, você criará os arquivos de projeto aspire padrão usados posteriormente.

Execute os seguintes comandos

dotnet new tool-manifest
dotnet tool install aspire.cli
dotnet tool install microsoft.dataapibuilder --prerelease
aspire init

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.

Quando solicitado, selecione todos os valores padrão.

Este comando instala as ferramentas e cria os seguintes arquivos

.
├── .config
│   └── dotnet-tools.json
├── AppHost.cs
└── apphost.run.json

4. Concluir o arquivo de AppHost.cs

Nesta etapa, você atualizará AppHost.cs com o código correto para executar este início rápido.

Substitua o conteúdo de AppHost.cs pelo seguinte

#:sdk Aspire.AppHost.Sdk@13.0.2
#:package Aspire.Hosting.SqlServer@13.0.2
#:package CommunityToolkit.Aspire.Hosting.McpInspector@9.8.0

using System.ComponentModel;
using Aspire.Hosting;
using Aspire.Hosting.ApplicationModel;

var builder = DistributedApplication.CreateBuilder(args);

var db = AddSqlServer(builder);
WithSqlCommander(db);

var mcp = AddMcpServer(db);
WithMcpInspector(mcp);

await builder.Build().RunAsync();

IResourceBuilder<SqlServerDatabaseResource> AddSqlServer(IDistributedApplicationBuilder builder) => builder
    .AddSqlServer("sql-server").WithDataVolume()
    .AddDatabase("sql-database", "productsdb")
    .WithCreationScript(SqlScript("productsdb"));

IResourceBuilder<ContainerResource> WithSqlCommander(IResourceBuilder<SqlServerDatabaseResource> db) => db
    .ApplicationBuilder.AddContainer("sql-cmdr", "jerrynixon/sql-commander", "latest")
    .WithImageRegistry("docker.io")
    .WithHttpEndpoint(targetPort: 8080, name: "http")
    .WithEnvironment("ConnectionStrings__db", db)
    .WithParentRelationship(db)
    .WaitFor(db)
    .WithUrls(x =>
    {
        x.Urls.Clear();
        x.Urls.Add(new() { Url = "/", DisplayText = "Commander", Endpoint = x.GetEndpoint("http") });
    });

IResourceBuilder<ContainerResource> AddMcpServer(IResourceBuilder<SqlServerDatabaseResource> db) => db
    .ApplicationBuilder.AddContainer("sql-mcp-server", "azure-databases/data-api-builder", "1.7.83-rc")
    .WithImageRegistry("mcr.microsoft.com")
    .WithHttpEndpoint(targetPort: 5000, name: "http")
    .WithEnvironment("MSSQL_CONNECTION_STRING", db)
    .WithBindMount("dab-config.json", "/App/dab-config.json", true)
    .WaitFor(db)
    .WithUrls(x =>
    {
        x.Urls.Clear();
        x.Urls.Add(new() { Url = "/swagger", DisplayText = "Swagger", Endpoint = x.GetEndpoint("http") });
    });

IResourceBuilder<McpInspectorResource> WithMcpInspector(IResourceBuilder<ContainerResource> mcp) => mcp
    .ApplicationBuilder.AddMcpInspector("mcp-inspector")
    .WithMcpServer(mcp)
    .WithParentRelationship(mcp)
    .WaitFor(mcp)
    .WithUrls(x =>
    {
        x.Urls[0].DisplayText = "Inspector";
    });

string SqlScript(string db) => $"""
    CREATE DATABASE {db};
    GO

    SELECT *
    INTO {db}.dbo.Products
    FROM (VALUES
        (1, 'Action Figure', 40, 14.99, 5.00),
        (2, 'Building Blocks', 25, 29.99, 10.00),
        (3, 'Puzzle 500 pcs', 30, 12.49, 4.00),
        (4, 'Toy Car', 50, 7.99, 2.50),
        (5, 'Board Game', 20, 34.99, 12.50),
        (6, 'Doll House', 10, 79.99, 30.00),
        (7, 'Stuffed Bear', 45, 15.99, 6.00),
        (8, 'Water Blaster', 35, 19.99, 7.00),
        (9, 'Art Kit', 28, 24.99, 8.00),
        (10,'RC Helicopter', 12, 59.99, 22.00)
    ) AS x (Id, Name, Inventory, Price, Cost);

    ALTER TABLE {db}.dbo.Products
    ADD CONSTRAINT PK_Products PRIMARY KEY (Id);
    """;

Esse código configura os recursos a seguir

.
├── SQL Server (sql)
│   └── SQL Database (productsdb)
└── SQL MCP Server (sql-mcp-server)
    └── MCP Inspector (inspector)

5. Criar seu arquivo de dab-config.json

Execute esses comandos na pasta do projeto (a mesma pasta onde AppHost.cs está localizada).

A sintaxe @env('MSSQL_CONNECTION_STRING') informa ao construtor de API de Dados a ler a cadeia de conexão de uma variável de ambiente em tempo de execução. O Aspire define essa variável automaticamente quando ela inicia o contêiner, portanto, você não precisa defini-la localmente.

dab init --database-type mssql --connection-string "@env('MSSQL_CONNECTION_STRING')" --host-mode Development --config dab-config.json
dab add Products --source dbo.Products --permissions "anonymous:read" --description "Toy store products with inventory, price, and cost."

Observação

A @env(...) expressão é um recurso de configuração do DAB que resolve variáveis de ambiente em runtime, não durante dab init. O gerado dab-config.json contém a cadeia de caracteres literal @env('MSSQL_CONNECTION_STRING'), que o DAB resolve quando o contêiner inicia.

O dab-config.json arquivo configura o SQL MCP Server para se conectar ao banco de dados e identifica quais objetos expor. Nesse caso, Products está exposto.

Esse comando adiciona um novo arquivo ao seu projeto

dab-config.json

Importante

O arquivo dab-config.json deve estar no mesmo diretório onde você executa aspire run, pois a montagem de ligação usa um caminho relativo (./dab-config.json).

Opcionalmente, adicione descrições de campo

Esses metadados podem ajudar os modelos de linguagem a entender seu esquema.

dab update Products --fields.name Id --fields.primary-key true --fields.description "Product Id"
dab update Products --fields.name Name --fields.description "Product name"
dab update Products --fields.name Inventory --fields.description "Units in stock"
dab update Products --fields.name Price --fields.description "Retail price"
dab update Products --fields.name Cost --fields.description "Store cost"

Testar sua solução

Nesta etapa, você executará seu ambiente Aspire e confirmará que o SQL Server, o SQL MCP Server e o MCP Inspector estão trabalhando juntos.

1. Iniciar o Aspire

aspire run

Importante

Verifique se o Docker está em execução. O Aspire exige que o host do contêiner funcione corretamente.

Quando o painel é aberto, você vê links para Swagger, MCP e Inspetor.

URLs esperadas

O painel do Aspire exibe esses links (as portas são atribuídas dinamicamente):

Resource	Link	Description
servidor-sql-mcp	Swagger	Documentação da API REST
servidor-sql-mcp	MCP	Ponto de extremidade MCP (/mcp)
inspetor	Inspector	Interface do usuário do INSPETOR MCP

2. Testar a API REST com o Swagger

Selecione Swagger no painel.

Experimente a operação GET para produtos. Este teste confirma que o SQL MCP Server está em execução e pode se conectar ao banco de dados.

3. Explorar as ferramentas do MCP

Selecione Inspetor no painel.

Try:

• list_tools para ver as ferramentas MCP disponíveis
• read_records para a Products entidade

Experimente um filtro (sintaxe de exemplo):

{ "filter": "Price gt 20" }

Este teste confirma que o MCP está funcionando.

4. Parar o Aspire

Para parar o Aspire, pressione Ctrl+C.

O Aspire interrompe todos os serviços. Os dados do SQL Server persistem entre execuções porque o código usa .WithDataVolume() e .WithLifetime(ContainerLifetime.Persistent).

Resolução de problemas

Falha ao iniciar o contêiner do SQL MCP Server

• Verifique os logs de contêiner no painel do Aspire para obter detalhes de erro
• Verifique se o --config argumento corresponde à sintaxe esperada do contêiner da DAB (algumas versões podem ser usadas --ConfigFileName em vez disso)
• Verifique se dab-config.json existe no mesmo diretório em que você executa aspire run

Script de inicialização de banco de dados não encontrado

• Verificar init-db.sql se está no diretório do projeto AppHost
• Verifique se o arquivo está incluído no projeto e, se necessário, faça uma cópia para a saída.

O Inspetor do MCP não pode se conectar

• Confirme se o contêiner do SQL MCP Server está em execução e íntegro
• Verifique se o caminho do endpoint MCP (/mcp) corresponde à configuração do DAB

Conteúdo relacionado

• 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