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

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.

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.

winget install Microsoft.DotNet.SDK.10

2. Runtime do contêiner

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

winget install Docker.DockerDesktop

brew install --cask docker

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 comandos a seguir:

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

Quando solicitado, selecione todos os valores padrão.

Esse 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 código:

#: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", "2.0.1-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 seguintes recursos:

.
├── 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 para 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."

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.

Este comando adiciona um novo arquivo ao seu projeto:

dab-config.json

Adicione descrições de campo às suas entidades:

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 SQL Server, o SQL MCP Server e o MCP Inspector estão trabalhando juntos.

1. Iniciar o Aspire

aspire run

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):

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. SQL Server dados 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 copie para a saída, se necessário

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