Inicio rápido: Uso de SQL MCP Server con .NET Aspire

Importante

SQL MCP Server está en versión preliminar y esta documentación y la implementación del motor está sujeta a cambios durante este período de evaluación.

En este inicio rápido se usa Aspire para compilar una solución basada en contenedores. La solución incluye:

Una base de datos SQL con datos de ejemplo
Servidor MCP (Protocolo de Contexto de Modelo SQL) impulsado por Data API builder
MCP Inspector para pruebas

Aspire ejecuta todo para usted, inicia servicios y conecta contenedores, y detiene los servicios cuando se cierra.

Prerrequisitos

Instale estas herramientas antes de empezar.

1. .NET 10

En este paso, preparará la máquina con los requisitos previos necesarios para este inicio rápido.

Importante

Es posible que ya tenga instalada esta herramienta. Para probarlo, ejecute dotnet --version y confirme que informa de la versión 10 o posterior. Si ejecuta esta instalación y .NET ya está presente, actualiza el sistema sin causar ningún problema.

Windows

winget install Microsoft.DotNet.SDK.10

O descargar

https://get.dot.net

2. Tiempo de ejecución del contenedor

Durante este paso, instalará Docker Desktop para admitir el proyecto Aspire.

Importante

Es posible que ya tenga instalada esta herramienta. Para probarlo, ejecute docker --version para confirmar que Docker está disponible. Si ejecuta esta instalación y Docker ya está presente, actualiza el sistema sin causar ningún problema.

Windows

winget install Docker.DockerDesktop

macOS

brew install --cask docker

Nota:

Podman también funciona, pero la configuración varía. Los desarrolladores que prefieren Podman pueden adaptar estos pasos.

3. Herramientas Aspire y de creación de API de datos

En este paso, creará los archivos de proyecto Aspire predeterminados que se usaron más adelante.

Ejecute los comandos siguientes.

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

Nota:

SQL MCP Server se encuentra actualmente en versión preliminar. El uso de la --prerelease marca garantiza que obtiene la versión más reciente de Data API Builder con todas las características que se usan en este inicio rápido.

Cuando se le solicite, seleccione todos los valores predeterminados.

Este comando instala las herramientas y crea los archivos siguientes.

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

4. Complete el archivo AppHost.cs

En este paso, actualizará AppHost.cs con el código correcto para ejecutar este inicio rápido.

Reemplace el contenido de AppHost.cs por lo siguiente

#: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);
    """;

Este código configura los siguientes recursos

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

5. Crear el archivo de dab-config.json

Ejecute estos comandos en la carpeta del proyecto (la misma carpeta donde AppHost.cs se encuentra).

La @env('MSSQL_CONNECTION_STRING') sintaxis indica al generador de Data API que lea la cadena de conexión de una variable de entorno en tiempo de ejecución. Aspire establece esta variable automáticamente cuando se inicia el contenedor, por lo que no es necesario establecerla 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."

Nota:

La @env(...) expresión es una característica de configuración de DAB que resuelve las variables de entorno en tiempo de ejecución, no durante dab init. El dab-config.json generado contiene la cadena literal @env('MSSQL_CONNECTION_STRING'), que DAB resuelve cuando el contenedor comienza.

El dab-config.json archivo configura SQL MCP Server para conectarse a la base de datos e identifica los objetos que se van a exponer. En este caso, Products queda expuesto.

Este comando agrega un nuevo archivo al proyecto

dab-config.json

Importante

El archivo dab-config.json debe estar en el mismo directorio donde se ejecuta aspire run, porque el montaje enlazado usa una ruta relativa (./dab-config.json).

Opcionalmente, agregue descripciones de campo.

Estos metadatos pueden ayudar a los modelos de lenguaje a comprender el 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"

Prueba de la solución

En este paso, ejecutará el entorno de Aspire y confirmará que SQL Server, SQL MCP Server y MCP Inspector están trabajando juntos.

1. Iniciar Aspire

aspire run

Importante

Asegúrese de que Docker se está ejecutando. Aspire requiere que el host de contenedor funcione correctamente.

Cuando se abra el panel, verá vínculos para Swagger, MCP e Inspector.

Direcciones URL esperadas

El panel Aspire muestra estos vínculos (los puertos se asignan dinámicamente):

Resource	Link	Description
sql-mcp-server	Swagger	Documentación de la API de REST
sql-mcp-server	MCP	Punto de conexión de MCP (`/mcp`)
inspector	Inspector	Interfaz de usuario del Inspector de MCP

2. Prueba de la API REST con Swagger

Seleccione Swagger en el panel.

Pruebe la GET operación para Productos. Esta prueba confirma que SQL MCP Server se está ejecutando y puede conectarse a la base de datos.

3. Exploración de las herramientas de MCP

Seleccione Inspector en el panel.

Try:

list_tools para ver las herramientas de MCP disponibles
read_records para la Products entidad

Pruebe un filtro (sintaxis de ejemplo):

{ "filter": "Price gt 20" }

Esta prueba confirma que MCP funciona.

4. Detener Aspire

Para detener Aspire, presione Ctrl+C.

Aspire detiene todos los servicios. Los datos de SQL Server se conservan entre ejecuciones porque el código usa .WithDataVolume() y .WithLifetime(ContainerLifetime.Persistent).

Solución de problemas

No se puede iniciar el contenedor de SQL MCP Server

Compruebe los registros de contenedor en el panel Aspire para obtener más información sobre el error.
Compruebe que el --config argumento coincide con la sintaxis esperada del contenedor DAB (algunas versiones pueden usarse --ConfigFileName en su lugar).
Asegúrese de que dab-config.json existe en el mismo directorio donde se ejecuta aspire run

No se encontró el script de inicialización de la base de datos

Compruebe init-db.sql que está en el directorio del proyecto AppHost.
Asegúrese de que el archivo esté incluido en el proyecto y se copie al resultado si es necesario.

McP Inspector no se puede conectar

Confirme que el contenedor de SQL MCP Server se está ejecutando y en buen estado
Compruebe que la ruta de acceso del punto de conexión de MCP (/mcp) coincide con la configuración de DAB.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-01-07

Compartir a través de

Inicio rápido: Uso de SQL MCP Server con .NET Aspire

Prerrequisitos

1. .NET 10

Windows

O descargar

2. Tiempo de ejecución del contenedor

Windows

macOS

3. Herramientas Aspire y de creación de API de datos

Ejecute los comandos siguientes.

Este comando instala las herramientas y crea los archivos siguientes.

4. Complete el archivo AppHost.cs

Reemplace el contenido de AppHost.cs por lo siguiente

Este código configura los siguientes recursos

5. Crear el archivo de dab-config.json

Este comando agrega un nuevo archivo al proyecto

Opcionalmente, agregue descripciones de campo.

Prueba de la solución

1. Iniciar Aspire

Direcciones URL esperadas

2. Prueba de la API REST con Swagger

3. Exploración de las herramientas de MCP

4. Detener Aspire

Solución de problemas

No se puede iniciar el contenedor de SQL MCP Server

No se encontró el script de inicialización de la base de datos

McP Inspector no se puede conectar

Contenido relacionado

Comentarios

Recursos adicionales