DEV Community: Juan Gómez

Minimal APIs bien hechos en .NET 10: validación, versionado y OpenAPI sin controladores

Juan Gómez — Fri, 21 Aug 2026 17:28:59 +0000

Minimal APIs bien hechos en .NET 10: validación, versionado y OpenAPI sin controladores

La vez pasada publicamos la API de pedidos de Aurora Coffee Co. con Native AOT y logramos que arrancara en un parpadeo. Lo que no hicimos fue convertirla en un servicio del que alguien debería depender. Acepta con gusto un pedido de menos cinco bolsas de café. No tiene versión en la URL, así que el primer cambio incompatible que publiques rompe a todos los clientes al mismo tiempo. Y no le dice absolutamente nada sobre su propia forma al equipo que quiera integrarse — "lee el código fuente, supongo".

Eso está bien para medir tiempo de arranque. En producción es un pasivo. Este post cierra la brecha: validación, versionado y OpenAPI sobre un Minimal API, sin un solo controlador. La buena noticia es que .NET 10 por fin trae una respuesta de primera mano para el más difícil de los tres.

Dónde quedamos

El post de AOT terminó con dos endpoints y un almacén singleton:

var orders = app.MapGroup("/orders");

orders.MapGet("/{id}", (string id, OrdersStore store) =>
    store.Find(id) is { } order ? Results.Ok(order) : Results.NotFound());

orders.MapPost("/", (PlaceOrderRequest request, OrdersStore store) =>
{
    var order = store.Place(request.Sku, request.Quantity);
    return Results.Created($"/orders/{order.Id}", order);
});

Tres huecos, en el orden en que te van a doler:

Nada valida la petición. {"sku": "", "quantity": -5} se convierte en un pedido real.
Nada versiona el contrato. Renombra un campo del JSON y todos los clientes se rompen a la vez.
Nada describe la API. Sin esquema, sin documentación, sin cliente generado.

Los arreglamos en ese mismo orden.

Paso 1: los grupos son la costura donde se engancha todo lo demás

MapGroup parece una comodidad para compartir un prefijo de URL. En realidad es el punto de extensión al que se enganchan la validación, los filtros, el versionado y los metadatos de OpenAPI — aplica una convención al grupo y todos los endpoints que contiene la heredan.

Saca los handlers de Program.cs. Los métodos con nombre dentro de una clase estática le ganan a las lambdas por tres razones: puedes probarlos unitariamente, el compilador infiere metadatos de OpenAPI más ricos a partir de sus firmas y — novedad en .NET 10 — sus comentarios XML llegan hasta el documento de OpenAPI.

internal static class OrderEndpoints
{
    /// <summary>Busca un pedido por su identificador.</summary>
    /// <param name="id">El identificador del pedido, por ejemplo <c>A-2001</c>.</param>
    public static Results<Ok<OrderV1Response>, NotFound> GetOrderV1(string id, OrdersStore store)
        => store.Find(id) is { } order
            ? TypedResults.Ok(new OrderV1Response(order.Id, order.Sku, order.Quantity, order.Status))
            : TypedResults.NotFound();
}

Vale la pena detenerse en dos detalles. Results<Ok<T>, NotFound> es una unión discriminada: el compilador rechaza cualquier retorno que no sea uno de los tipos declarados, y OpenAPI lee tanto el 200 como el 404 directamente de la firma — sin necesidad de .Produces<T>(). Y el handler devuelve OrderV1Response, no el Order del dominio. Esa separación parece ceremonia hasta el Paso 3, donde es la razón completa de que el versionado sea llevadero.

Los comentarios XML solo llegan al documento si habilitas el archivo de documentación:

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Paso 2: validación, por fin integrada

Antes de .NET 10 la respuesta era FluentValidation o un filtro escrito a mano. Ahora System.ComponentModel.DataAnnotations funciona directamente sobre los parámetros de un Minimal API, conectado por un generador de código fuente:

builder.Services.AddProblemDetails();
builder.Services.AddValidation();

Esa es toda la configuración. Microsoft.Extensions.Validation vive en el shared framework de ASP.NET Core, así que un proyecto Microsoft.NET.Sdk.Web no necesita ningún PackageReference — una biblioteca de clases común sí. Y no, no hace falta el conjuro de InterceptorsNamespaces en el csproj que aparece en los posts de la época de preview; el SDK lo agrega por ti en net10.0.

Ahora anota la petición:

public sealed record PlaceOrderRequest(
    [property: Required]
    [property: RegularExpression(
        @"^[A-Z]{3}-[A-Z0-9]{2,4}$",
        ErrorMessage = "El SKU debe verse como ETH-250 o COL-1KG.")]
    string Sku,

    [property: Range(1, 100, ErrorMessage = "Los pedidos están limitados a 100 unidades por línea.")]
    int Quantity);

No omitas el prefijo [property:]. En un record posicional, un atributo que es válido tanto en un parámetro como en una propiedad se aplica al parámetro por defecto, y el validador lee propiedades. Si lo dejas fuera, tu validación no hace nada en silencio — el peor modo de falla posible, porque el endpoint sigue devolviendo 201 y te enteras por un ticket de soporte.

Una petición inválida ahora recibe un 400 con application/problem+json, con la forma de RFC 9457:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Sku": ["El SKU debe verse como ETH-250 o COL-1KG."],
    "Quantity": ["Los pedidos están limitados a 100 unidades por línea."]
  }
}

Registrar AddProblemDetails() es lo que te permite dar forma a ese payload de manera global en vez de quedarte con el predeterminado.

Tres cosas que debes saber antes de confiar en esto:

Desactívalo con .DisableValidation(). Es genérico sobre IEndpointConventionBuilder, así que funciona en un endpoint o en un grupo heredado completo.
El generador solo ve el ensamblado donde se llama a AddValidation(). Si separas tus DTOs en otro proyecto, no encuentra nada — expón una pequeña extensión AddMyModuleValidation() por ensamblado.
Los parámetros de tipo valor anulable se omiten en .NET 10. Un [Range] sobre un parámetro int? se ignora en silencio (dotnet/aspnetcore#67033); está corregido en .NET 11. Mientras tanto, usa un parámetro no anulable o valídalo tú.

Paso 3: las reglas que DataAnnotations no alcanza

DataAnnotations valida la forma: si esta cadena está presente, si este número está en rango. No puede responder "¿realmente tenemos 40 bolsas de ETH-250 en la bodega?", porque eso necesita un servicio. Para eso existe IEndpointFilter.

public sealed class StockReservationFilter(InventoryStore inventory) : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context, EndpointFilterDelegate next)
    {
        var request = context.GetArgument<PlaceOrderRequest>(0);

        if (!inventory.TryReserve(request.Sku, request.Quantity))
        {
            return TypedResults.Problem(
                title: "Inventario insuficiente",
                detail: $"No hay suficiente {request.Sku} en existencia para cubrir {request.Quantity} unidades.",
                statusCode: StatusCodes.Status409Conflict);
        }

        return await next(context);
    }
}

El filtro reserva en vez de consultar. Una llamada a HasStock() seguida de un descuento en el handler es la carrera clásica de comprobar-y-luego-actuar: dos peticiones ven 12 bolsas, ambas reservan 10, y acabas de vender 20 bolsas que no tienes. La reserva tiene que ser atómica, y eso significa un ciclo de comparar-e-intercambiar:

using System.Collections.Concurrent;

public sealed class InventoryStore
{
    private readonly ConcurrentDictionary<string, int> _stock = new()
    {
        ["ETH-250"] = 40,
        ["COL-1KG"] = 12,
    };

    public bool TryReserve(string sku, int quantity)
    {
        // La invariante se protege aquí, no en quien llama. Un almacén que un llamador
        // defectuoso puede dejar en negativo es un bug aunque hoy el único llamador se porte bien.
        if (quantity <= 0) return false;

        while (_stock.TryGetValue(sku, out var available))
        {
            if (available < quantity) return false;

            // Solo tiene éxito si nadie cambió el conteo desde que lo leímos.
            if (_stock.TryUpdate(sku, available - quantity, available)) return true;
        }

        return false;
    }
}

Regístralo por endpoint, no por grupo — un GET no tiene ningún PlaceOrderRequest que sacar del argumento cero:

v1.MapPost("/", OrderEndpoints.PlaceOrder).AddEndpointFilter<StockReservationFilter>();

Vale la pena memorizar el orden de los filtros, porque es asimétrico: el código antes de await next(...) corre en orden de registro, el código después corre en orden inverso, y los filtros de grupo siempre envuelven a los de endpoint sin importar en qué orden configuraste los grupos.

Una trampa: AddEndpointFilter<T>() construye el filtro una sola vez, cuando se construye el endpoint — es efectivamente un singleton. Inyectar un almacén singleton por constructor está bien; inyectar un DbContext o cualquier cosa con ámbito scoped es una dependencia cautiva que te va a entregar la misma instancia obsoleta durante toda la vida del proceso. En su lugar, resuelve los servicios scoped dentro de InvokeAsync desde context.HttpContext.RequestServices.

Paso 4: versionar, y versionar solo lo que se rompió

Agrega los dos paquetes de la comunidad a los que apunta la propia guía de Microsoft:

dotnet add package Asp.Versioning.Http
dotnet add package Asp.Versioning.OpenApi

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new HeaderApiVersionReader("X-Api-Version"));
})
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";        // v1, v1.1, v2
    options.SubstituteApiVersionInUrl = true;  // necesario para versionar por segmento de URL
})
.AddOpenApi();

ReportApiVersions hace que cada respuesta lleve las cabeceras api-supported-versions y api-deprecated-versions, que es como un cliente descubre una deprecación sin leer tu changelog. ApiVersionReader.Combine acepta la versión desde el segmento de URL o desde una cabecera, así que un cliente que no puede cambiar la estructura de sus URLs todavía tiene salida.

Después declara las versiones:

var orders = app.NewVersionedApi("Orders");

var v1 = orders.MapGroup("/api/v{version:apiVersion}/orders")
               .HasApiVersion(1.0)
               .WithTags("Orders");

var v2 = orders.MapGroup("/api/v{version:apiVersion}/orders")
               .HasApiVersion(2.0)
               .WithTags("Orders");

Fíjate en HasApiVersion(1.0) — un double, no una cadena. No existe una sobrecarga que reciba string, por más que algunos ejemplos que circulan por ahí sugieran lo contrario.

Aquí está la parte que la mayoría de los tutoriales de versionado hace mal: versionas los endpoints que se rompieron, no la API completa. La v2 de Aurora renombra status a state, agrega placedAt e introduce un endpoint de listado. El POST no cambió en nada:

v1.MapGet("/{id}", OrderEndpoints.GetOrderV1);

v2.MapGet("/{id}", OrderEndpoints.GetOrderV2);
v2.MapGet("/", OrderEndpoints.ListOrders);

v1.MapPost("/", OrderEndpoints.PlaceOrder).AddEndpointFilter<StockReservationFilter>();
v2.MapPost("/", OrderEndpoints.PlaceOrder).AddEndpointFilter<StockReservationFilter>();

Ese único handler PlaceOrder compartido solo funciona porque devuelve 201 Created con una cabecera Location y sin cuerpo — no hay forma de respuesta versionada sobre la cual discrepar:

/// <summary>Registra un pedido nuevo y devuelve su ubicación.</summary>
public static Created PlaceOrder(PlaceOrderRequest request, OrdersStore store, HttpContext http)
{
    var order = store.Place(request.Sku, request.Quantity);
    return TypedResults.Created($"{http.Request.Path}/{order.Id}");
}

Como la ubicación se construye a partir de la ruta entrante, un cliente que hizo POST a /api/v2/orders recibe un apuntador a /api/v2/orders/A-2003. El cuerpo de la respuesta es donde las versiones divergen, y este endpoint no tiene uno.

Paso 5: OpenAPI sin Swashbuckle

Microsoft.AspNetCore.OpenApi reemplazó a Swashbuckle como opción predeterminada en .NET 9, y .NET 10 lo afinó: OpenAPI 3.1 ahora es la versión de documento por defecto, la salida en YAML funciona en tiempo de ejecución, y puedes transformar una sola operación sin tocar el documento completo.

Como estamos versionados, los documentos por versión vienen de Asp.Versioning.OpenApi:

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi().WithDocumentPerVersion();   // /openapi/v1.json y /openapi/v2.json
    app.MapScalarApiReference();                 // UI interactiva en /scalar
}

Sin versionado sería solo builder.Services.AddOpenApi() más app.MapOpenApi(), sirviendo /openapi/v1.json.

Cuatro cosas que te van a ahorrar una tarde:

No viene ninguna UI incluida. ASP.NET Core genera el documento y ahí se detiene. Agrega Scalar.AspNetCore (lo que usan hoy los ejemplos de Microsoft) o quédate con Swashbuckle.AspNetCore.SwaggerUi si tu memoria muscular insiste en /swagger. En cualquier caso, protégelo detrás de IsDevelopment() — un endpoint de esquema público es un mapa de reconocimiento gratis para cualquiera que ande sondeando tu servicio.
.WithOpenApi() está obsoleto en .NET 10 (ASPDEPR002) y será eliminado. Muchos ejemplos todavía lo muestran. Usa .WithSummary(), .WithDescription(), .WithTags() o .AddOpenApiOperationTransformer(...) en su lugar.
YAML es un argumento: app.MapOpenApi("/openapi/{documentName}.yaml"). Solo en tiempo de ejecución — la generación del documento en tiempo de compilación sigue siendo JSON.
La 3.1 cambia la salida del esquema. Ya no existe nullable: true; la nulabilidad aparece como un tipo unión. Si un generador de clientes se atraganta, regresa con options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0 dentro de AddOpenApi().

¿Quieres una descripción en una respuesta que el tipo de retorno no puede expresar? Los atributos ahora la llevan:

[ProducesResponseType<OrderV2Response>(StatusCodes.Status200OK,
    Description = "El pedido, incluida su marca de tiempo de registro.")]

Todo junto

Program.cs:

using Asp.Versioning;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<OrdersStore>();
builder.Services.AddSingleton<InventoryStore>();
builder.Services.AddProblemDetails();
builder.Services.AddValidation();

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new HeaderApiVersionReader("X-Api-Version"));
})
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
})
.AddOpenApi();

var app = builder.Build();

var orders = app.NewVersionedApi("Orders");

var v1 = orders.MapGroup("/api/v{version:apiVersion}/orders")
               .HasApiVersion(1.0)
               .WithTags("Orders");

var v2 = orders.MapGroup("/api/v{version:apiVersion}/orders")
               .HasApiVersion(2.0)
               .WithTags("Orders");

v1.MapGet("/{id}", OrderEndpoints.GetOrderV1);
v1.MapPost("/", OrderEndpoints.PlaceOrder).AddEndpointFilter<StockReservationFilter>();

v2.MapGet("/{id}", OrderEndpoints.GetOrderV2);
v2.MapGet("/", OrderEndpoints.ListOrders);
v2.MapPost("/", OrderEndpoints.PlaceOrder).AddEndpointFilter<StockReservationFilter>();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi().WithDocumentPerVersion();
    app.MapScalarApiReference();
}

app.Run();

Los contratos y los handlers:

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Http.HttpResults;

// Modelo de dominio — nunca sale del proceso.
public sealed record Order(string Id, string Sku, int Quantity, string Status, DateTimeOffset PlacedAt);

// Contratos expuestos al cliente — uno por versión, libres de divergir.
public sealed record OrderV1Response(string Id, string Sku, int Quantity, string Status);
public sealed record OrderV2Response(string Id, string Sku, int Quantity, string State, DateTimeOffset PlacedAt);

public sealed record PlaceOrderRequest(
    [property: Required]
    [property: RegularExpression(
        @"^[A-Z]{3}-[A-Z0-9]{2,4}$",
        ErrorMessage = "El SKU debe verse como ETH-250 o COL-1KG.")]
    string Sku,

    [property: Range(1, 100, ErrorMessage = "Los pedidos están limitados a 100 unidades por línea.")]
    int Quantity);

internal static class OrderEndpoints
{
    /// <summary>Busca un pedido por su identificador.</summary>
    /// <param name="id">El identificador del pedido, por ejemplo <c>A-2001</c>.</param>
    public static Results<Ok<OrderV1Response>, NotFound> GetOrderV1(string id, OrdersStore store)
        => store.Find(id) is { } order
            ? TypedResults.Ok(new OrderV1Response(order.Id, order.Sku, order.Quantity, order.Status))
            : TypedResults.NotFound();

    /// <summary>Busca un pedido, incluida su marca de tiempo de registro.</summary>
    /// <param name="id">El identificador del pedido, por ejemplo <c>A-2001</c>.</param>
    public static Results<Ok<OrderV2Response>, NotFound> GetOrderV2(string id, OrdersStore store)
        => store.Find(id) is { } order
            ? TypedResults.Ok(new OrderV2Response(
                order.Id, order.Sku, order.Quantity, order.Status, order.PlacedAt))
            : TypedResults.NotFound();

    /// <summary>Lista todos los pedidos registrados.</summary>
    public static Ok<IReadOnlyCollection<OrderV2Response>> ListOrders(OrdersStore store)
        => TypedResults.Ok<IReadOnlyCollection<OrderV2Response>>(
            store.All()
                 .Select(o => new OrderV2Response(o.Id, o.Sku, o.Quantity, o.Status, o.PlacedAt))
                 .ToArray());

    /// <summary>Registra un pedido nuevo y devuelve su ubicación.</summary>
    public static Created PlaceOrder(PlaceOrderRequest request, OrdersStore store, HttpContext http)
    {
        var order = store.Place(request.Sku, request.Quantity);
        return TypedResults.Created($"{http.Request.Path}/{order.Id}");
    }
}

Y el almacén, seguro para concurrencia porque un singleton que atiende peticiones simultáneas no tiene otra opción:

using System.Collections.Concurrent;

public sealed class OrdersStore
{
    private readonly ConcurrentDictionary<string, Order> _orders = new()
    {
        ["A-2001"] = new("A-2001", "ETH-250", 2, "processing", DateTimeOffset.UtcNow),
        ["A-2002"] = new("A-2002", "COL-1KG", 1, "shipped", DateTimeOffset.UtcNow),
    };

    // Arranca después de los IDs precargados para que el primer pedido generado sea A-2003.
    private int _nextOrderId = 2002;

    public Order? Find(string id) => _orders.TryGetValue(id, out var order) ? order : null;

    public IReadOnlyCollection<Order> All() => _orders.Values.ToArray();

    public Order Place(string sku, int quantity)
    {
        var id = Interlocked.Increment(ref _nextOrderId);
        var order = new Order($"A-{id}", sku, quantity, "processing", DateTimeOffset.UtcNow);
        _orders[order.Id] = order;
        return order;
    }
}

Usar ConcurrentDictionary en vez de Dictionary no es decoración. Un almacén singleton mutado desde peticiones concurrentes a través de un Dictionary común puede corromper sus buckets internos durante un redimensionamiento — el síntoma clásico es una petición que deja girando un núcleo de CPU para siempre en vez de lanzar algo que puedas depurar a las 3 de la mañana.

Cuándo Minimal APIs — y cuándo controladores

Recurre a Minimal APIs cuando la superficie sea un conjunto de endpoints y no una jerarquía de recursos, cuando el tiempo de arranque y la huella importen (son la única opción bajo Native AOT) y — cada vez más — cuando quieras las funciones nuevas del framework primero. Ese último punto no es menor: la validación integrada de este post no soporta MVC ni Razor Pages. Solo Minimal APIs y Blazor. La inversión está fluyendo visiblemente en una sola dirección.

Quédate con controladores cuando tengas una superficie CRUD convencional y grande donde las convenciones de [ApiController] realmente te ahorren código, cuando dependas del ecosistema de filtros de MVC o de model binders que tendrías que reconstruir a mano, o cuando estés extendiendo una app MVC existente y la consistencia le gane a la novedad. "Ya tenemos cuarenta controladores" es una razón de ingeniería legítima, no una confesión.

Regla general: los servicios nuevos arrancan con Minimal; las apps MVC existentes se quedan en MVC hasta que algo concreto obligue a moverse. Y si alguien te dice que los Minimal APIs "no escalan a proyectos reales", eso normalmente significa que escribió los cuarenta endpoints como lambdas dentro de un solo Program.cs. Eso no es culpa del framework — es la misma persona que habría escrito un controlador de dos mil líneas.

Puntos Clave

AddValidation() hace que DataAnnotations funcione en Minimal APIs — sin FluentValidation, sin filtro escrito a mano, sin referencia de paquete en un proyecto web. En records posicionales, [property:] es obligatorio o la validación no hace nada en silencio.
Los filtros se encargan de las reglas que necesitan servicios — DataAnnotations valida la forma, IEndpointFilter valida la realidad. Mantén fuera la carrera de comprobar-y-actuar haciendo que la operación misma sea atómica.
Versiona los endpoints que se rompieron, no la API — un cambio en la forma de la respuesta se versiona; un 201 Created con solo una cabecera Location muchas veces no necesita versionarse.
TypedResults y Results<T1, T2> reemplazan a .Produces<T>() — la firma se convierte en el contrato de OpenAPI, y el compilador lo hace cumplir.
Los valores por defecto de OpenAPI cambiaron en .NET 10 — documentos 3.1, YAML en tiempo de ejecución, ninguna UI incluida y .WithOpenApi() obsoleto. La mitad de los ejemplos en línea siguen con la forma de .NET 8.

Minimal APIs Done Right in .NET 10: Validation, Versioning, and OpenAPI Without Controllers

Juan Gómez — Fri, 21 Aug 2026 17:28:57 +0000

Minimal APIs Done Right in .NET 10: Validation, Versioning, and OpenAPI Without Controllers

Last time we published Aurora Coffee Co.'s Orders API with Native AOT and made it start in a blink. What we did not do is make it a service anyone should depend on. It will cheerfully accept an order for negative five bags of coffee. It has no version in its URL, so the first breaking change you ship breaks every client at once. And it tells an integrating team exactly nothing about its own shape — "read the source, I guess."

That's fine for a startup-time benchmark. It's a liability in production. This post closes the gap: validation, versioning, and OpenAPI on a Minimal API, no controllers involved. The good news is that .NET 10 finally ships a first-party answer for the hardest of the three.

Where we left off

The AOT post ended with two endpoints and a singleton store:

var orders = app.MapGroup("/orders");

orders.MapGet("/{id}", (string id, OrdersStore store) =>
    store.Find(id) is { } order ? Results.Ok(order) : Results.NotFound());

orders.MapPost("/", (PlaceOrderRequest request, OrdersStore store) =>
{
    var order = store.Place(request.Sku, request.Quantity);
    return Results.Created($"/orders/{order.Id}", order);
});

Three gaps, in the order they'll hurt you:

Nothing validates the request. {"sku": "", "quantity": -5} becomes a real order.
Nothing versions the contract. Rename one JSON field and every client breaks simultaneously.
Nothing describes the API. No schema, no docs, no generated client.

We'll fix them in that order.

Step 1: Groups are the seam everything else hooks into

MapGroup looks like a convenience for sharing a URL prefix. It's actually the extension point that validation, filters, versioning, and OpenAPI metadata all attach to — apply a convention to the group and every endpoint inside inherits it.

Keep the handlers out of Program.cs. Named methods in a static class beat lambdas for three reasons: you can unit-test them, the compiler can infer richer OpenAPI metadata from their signatures, and — new in .NET 10 — their XML doc comments flow into the OpenAPI document.

internal static class OrderEndpoints
{
    /// <summary>Looks up a single order by its identifier.</summary>
    /// <param name="id">The order identifier, for example <c>A-2001</c>.</param>
    public static Results<Ok<OrderV1Response>, NotFound> GetOrderV1(string id, OrdersStore store)
        => store.Find(id) is { } order
            ? TypedResults.Ok(new OrderV1Response(order.Id, order.Sku, order.Quantity, order.Status))
            : TypedResults.NotFound();
}

Two things worth pausing on. Results<Ok<T>, NotFound> is a discriminated union: the compiler rejects any return that isn't one of the listed types, and OpenAPI reads both the 200 and the 404 straight off the signature — no .Produces<T>() needed. And the handler returns OrderV1Response, not the domain Order. That separation looks like ceremony until Step 3, where it's the entire reason versioning is survivable.

XML comments only reach the document if you enable the docs file:

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Step 2: Validation, finally built in

Before .NET 10 the answer was FluentValidation or a hand-rolled filter. Now System.ComponentModel.DataAnnotations works on Minimal API parameters directly, wired up by a source generator:

builder.Services.AddProblemDetails();
builder.Services.AddValidation();

That's the whole setup. Microsoft.Extensions.Validation lives in the ASP.NET Core shared framework, so a Microsoft.NET.Sdk.Web project needs no PackageReference — a plain class library does. And no, you don't need the InterceptorsNamespaces csproj incantation you'll find in preview-era blog posts; the SDK adds it for you on net10.0.

Now annotate the request:

public sealed record PlaceOrderRequest(
    [property: Required]
    [property: RegularExpression(
        @"^[A-Z]{3}-[A-Z0-9]{2,4}$",
        ErrorMessage = "SKU must look like ETH-250 or COL-1KG.")]
    string Sku,

    [property: Range(1, 100, ErrorMessage = "Orders are capped at 100 units per line.")]
    int Quantity);

Do not skip the [property:] prefix. On a positional record, an attribute that's legal on both a parameter and a property binds to the parameter by default, and the validator reads properties. Leave it off and your validation silently does nothing — the worst possible failure mode, since the endpoint keeps returning 201 and you only find out from a support ticket.

A failed request now gets a 400 with application/problem+json, RFC 9457 shaped:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Sku": ["SKU must look like ETH-250 or COL-1KG."],
    "Quantity": ["Orders are capped at 100 units per line."]
  }
}

Registering AddProblemDetails() is what lets you shape that payload globally instead of accepting the default.

Three things to know before you rely on it:

Opt out with .DisableValidation(). It's generic over IEndpointConventionBuilder, so it works on one endpoint or an entire legacy group.
The generator only sees the assembly where AddValidation() is called. Split your DTOs into another project and it finds nothing — expose a small AddMyModuleValidation() extension per assembly.
Nullable value-type parameters are skipped in .NET 10. A [Range] on an int? parameter is silently ignored (dotnet/aspnetcore#67033); it's fixed in .NET 11. Until then, take a non-nullable parameter or validate it yourself.

Step 3: The rules DataAnnotations can't reach

DataAnnotations validate shape: is this string present, is this number in range. They can't answer "do we actually have 40 bags of ETH-250 in the warehouse," because that needs a service. That's what IEndpointFilter is for.

public sealed class StockReservationFilter(InventoryStore inventory) : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context, EndpointFilterDelegate next)
    {
        var request = context.GetArgument<PlaceOrderRequest>(0);

        if (!inventory.TryReserve(request.Sku, request.Quantity))
        {
            return TypedResults.Problem(
                title: "Insufficient stock",
                detail: $"Not enough {request.Sku} on hand to fill {request.Quantity} units.",
                statusCode: StatusCodes.Status409Conflict);
        }

        return await next(context);
    }
}

The filter reserves rather than checks. A HasStock() call followed by a decrement in the handler is a textbook check-then-act race: two requests both see 12 bags, both reserve 10, and you've sold 20 bags you don't have. The reservation has to be atomic, which means a compare-and-swap loop:

using System.Collections.Concurrent;

public sealed class InventoryStore
{
    private readonly ConcurrentDictionary<string, int> _stock = new()
    {
        ["ETH-250"] = 40,
        ["COL-1KG"] = 12,
    };

    public bool TryReserve(string sku, int quantity)
    {
        // Guard the invariant here, not in the caller. A store that a bad caller can
        // drive negative is a bug even when today's only caller is well-behaved.
        if (quantity <= 0) return false;

        while (_stock.TryGetValue(sku, out var available))
        {
            if (available < quantity) return false;

            // Only succeeds if nobody changed the count since we read it.
            if (_stock.TryUpdate(sku, available - quantity, available)) return true;
        }

        return false;
    }
}

v1.MapPost("/", OrderEndpoints.PlaceOrder).AddEndpointFilter<StockReservationFilter>();

Filter ordering is worth memorizing, because it's asymmetric: code before await next(...) runs first-added-first, code after it runs first-added-last, and group filters always wrap endpoint filters regardless of the order you configured the groups in.

One trap: AddEndpointFilter<T>() builds the filter once, when the endpoint is built — it's effectively a singleton. Constructor-injecting a singleton store is fine; constructor-injecting a DbContext or anything else scoped is a captive dependency that will hand you the same stale instance for the life of the process. Resolve scoped services inside InvokeAsync from context.HttpContext.RequestServices instead.

Step 4: Versioning, and versioning only what broke

Add the two community packages that Microsoft's own guidance points at:

dotnet add package Asp.Versioning.Http
dotnet add package Asp.Versioning.OpenApi

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new HeaderApiVersionReader("X-Api-Version"));
})
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";        // v1, v1.1, v2
    options.SubstituteApiVersionInUrl = true;  // required for URL-segment versioning
})
.AddOpenApi();

ReportApiVersions makes every response carry api-supported-versions and api-deprecated-versions headers, which is how a client discovers a deprecation without reading your changelog. ApiVersionReader.Combine accepts the version from the URL segment or a header, so a client that can't change its URL structure still has a path forward.

Then declare the versions:

var orders = app.NewVersionedApi("Orders");

var v1 = orders.MapGroup("/api/v{version:apiVersion}/orders")
               .HasApiVersion(1.0)
               .WithTags("Orders");

var v2 = orders.MapGroup("/api/v{version:apiVersion}/orders")
               .HasApiVersion(2.0)
               .WithTags("Orders");

Note HasApiVersion(1.0) — a double, not a string. There is no string overload, despite what a few samples floating around suggest.

Here's the part most versioning tutorials get wrong: you version the endpoints that broke, not the whole API. Aurora's v2 renames status to state, adds placedAt, and introduces a list endpoint. The POST didn't change at all:

v1.MapGet("/{id}", OrderEndpoints.GetOrderV1);

v2.MapGet("/{id}", OrderEndpoints.GetOrderV2);
v2.MapGet("/", OrderEndpoints.ListOrders);

v1.MapPost("/", OrderEndpoints.PlaceOrder).AddEndpointFilter<StockReservationFilter>();
v2.MapPost("/", OrderEndpoints.PlaceOrder).AddEndpointFilter<StockReservationFilter>();

That single shared PlaceOrder handler only works because it returns 201 Created with a Location header and no body — there's no versioned response shape to disagree about:

/// <summary>Places a new order and returns its location.</summary>
public static Created PlaceOrder(PlaceOrderRequest request, OrdersStore store, HttpContext http)
{
    var order = store.Place(request.Sku, request.Quantity);
    return TypedResults.Created($"{http.Request.Path}/{order.Id}");
}

Because the location is built from the incoming path, a client that posted to /api/v2/orders gets pointed back at /api/v2/orders/A-2003. The response body is where versions diverge, and this endpoint doesn't have one.

Step 5: OpenAPI without Swashbuckle

Microsoft.AspNetCore.OpenApi replaced Swashbuckle as the default in .NET 9, and .NET 10 sharpened it: OpenAPI 3.1 is now the default document version, YAML output works at runtime, and you can transform a single operation without touching the whole document.

Because we're versioned, the per-version documents come from Asp.Versioning.OpenApi:

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi().WithDocumentPerVersion();   // /openapi/v1.json and /openapi/v2.json
    app.MapScalarApiReference();                 // interactive UI at /scalar
}

Without versioning it's just builder.Services.AddOpenApi() plus app.MapOpenApi(), serving /openapi/v1.json.

Four things that will save you an afternoon:

No UI ships in the box. ASP.NET Core generates the document and stops there. Add Scalar.AspNetCore (what Microsoft's samples use now) or keep Swashbuckle.AspNetCore.SwaggerUi if your muscle memory insists on /swagger. Either way, gate it behind IsDevelopment() — a public schema endpoint is a free reconnaissance map for anyone probing your service.
.WithOpenApi() is deprecated in .NET 10 (ASPDEPR002) and will be removed. Plenty of samples still show it. Use .WithSummary(), .WithDescription(), .WithTags(), or .AddOpenApiOperationTransformer(...) instead.
YAML is one argument: app.MapOpenApi("/openapi/{documentName}.yaml"). Runtime only — build-time document generation is still JSON.
3.1 changes the schema output. There's no nullable: true anymore; nullability shows up as a union type. If a downstream code generator chokes, drop back with options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0 inside AddOpenApi().

Want a description on a response the return type can't express? Attributes carry one now:

[ProducesResponseType<OrderV2Response>(StatusCodes.Status200OK,
    Description = "The order, including its placement timestamp.")]

The whole thing

Program.cs:

using Asp.Versioning;
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<OrdersStore>();
builder.Services.AddSingleton<InventoryStore>();
builder.Services.AddProblemDetails();
builder.Services.AddValidation();

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new HeaderApiVersionReader("X-Api-Version"));
})
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
})
.AddOpenApi();

var app = builder.Build();

var orders = app.NewVersionedApi("Orders");

var v1 = orders.MapGroup("/api/v{version:apiVersion}/orders")
               .HasApiVersion(1.0)
               .WithTags("Orders");

var v2 = orders.MapGroup("/api/v{version:apiVersion}/orders")
               .HasApiVersion(2.0)
               .WithTags("Orders");

v1.MapGet("/{id}", OrderEndpoints.GetOrderV1);
v1.MapPost("/", OrderEndpoints.PlaceOrder).AddEndpointFilter<StockReservationFilter>();

v2.MapGet("/{id}", OrderEndpoints.GetOrderV2);
v2.MapGet("/", OrderEndpoints.ListOrders);
v2.MapPost("/", OrderEndpoints.PlaceOrder).AddEndpointFilter<StockReservationFilter>();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi().WithDocumentPerVersion();
    app.MapScalarApiReference();
}

app.Run();

The contracts and handlers:

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Http.HttpResults;

// Domain model — never leaves the process.
public sealed record Order(string Id, string Sku, int Quantity, string Status, DateTimeOffset PlacedAt);

// Wire contracts — one per version, free to diverge.
public sealed record OrderV1Response(string Id, string Sku, int Quantity, string Status);
public sealed record OrderV2Response(string Id, string Sku, int Quantity, string State, DateTimeOffset PlacedAt);

public sealed record PlaceOrderRequest(
    [property: Required]
    [property: RegularExpression(
        @"^[A-Z]{3}-[A-Z0-9]{2,4}$",
        ErrorMessage = "SKU must look like ETH-250 or COL-1KG.")]
    string Sku,

    [property: Range(1, 100, ErrorMessage = "Orders are capped at 100 units per line.")]
    int Quantity);

internal static class OrderEndpoints
{
    /// <summary>Looks up a single order by its identifier.</summary>
    /// <param name="id">The order identifier, for example <c>A-2001</c>.</param>
    public static Results<Ok<OrderV1Response>, NotFound> GetOrderV1(string id, OrdersStore store)
        => store.Find(id) is { } order
            ? TypedResults.Ok(new OrderV1Response(order.Id, order.Sku, order.Quantity, order.Status))
            : TypedResults.NotFound();

    /// <summary>Looks up a single order, including its placement timestamp.</summary>
    /// <param name="id">The order identifier, for example <c>A-2001</c>.</param>
    public static Results<Ok<OrderV2Response>, NotFound> GetOrderV2(string id, OrdersStore store)
        => store.Find(id) is { } order
            ? TypedResults.Ok(new OrderV2Response(
                order.Id, order.Sku, order.Quantity, order.Status, order.PlacedAt))
            : TypedResults.NotFound();

    /// <summary>Lists every order currently on file.</summary>
    public static Ok<IReadOnlyCollection<OrderV2Response>> ListOrders(OrdersStore store)
        => TypedResults.Ok<IReadOnlyCollection<OrderV2Response>>(
            store.All()
                 .Select(o => new OrderV2Response(o.Id, o.Sku, o.Quantity, o.Status, o.PlacedAt))
                 .ToArray());

    /// <summary>Places a new order and returns its location.</summary>
    public static Created PlaceOrder(PlaceOrderRequest request, OrdersStore store, HttpContext http)
    {
        var order = store.Place(request.Sku, request.Quantity);
        return TypedResults.Created($"{http.Request.Path}/{order.Id}");
    }
}

And the store, thread-safe because a singleton serving concurrent requests has no other option:

using System.Collections.Concurrent;

public sealed class OrdersStore
{
    private readonly ConcurrentDictionary<string, Order> _orders = new()
    {
        ["A-2001"] = new("A-2001", "ETH-250", 2, "processing", DateTimeOffset.UtcNow),
        ["A-2002"] = new("A-2002", "COL-1KG", 1, "shipped", DateTimeOffset.UtcNow),
    };

    // Starts past the seeded IDs so the first generated order is A-2003.
    private int _nextOrderId = 2002;

    public Order? Find(string id) => _orders.TryGetValue(id, out var order) ? order : null;

    public IReadOnlyCollection<Order> All() => _orders.Values.ToArray();

    public Order Place(string sku, int quantity)
    {
        var id = Interlocked.Increment(ref _nextOrderId);
        var order = new Order($"A-{id}", sku, quantity, "processing", DateTimeOffset.UtcNow);
        _orders[order.Id] = order;
        return order;
    }
}

ConcurrentDictionary rather than Dictionary isn't decoration. A singleton store mutated from concurrent requests through a plain Dictionary can corrupt its internal buckets during a resize — the classic symptom is a request that spins a CPU core forever instead of throwing something you could debug at 3 a.m.

When Minimal APIs — and when controllers

Reach for Minimal APIs when the surface is a set of endpoints rather than a resource hierarchy, when startup time and footprint matter (they're the only option under Native AOT), and — increasingly — when you want the newest framework features first. That last one is not a small point: the built-in validation in this post does not support MVC or Razor Pages. Minimal APIs and Blazor only. The investment is visibly flowing one way.

Stay with controllers when you have a large conventional CRUD surface where [ApiController]'s conventions genuinely save code, when you depend on the MVC filter ecosystem or model binders you'd have to rebuild by hand, or when you're extending an existing MVC app and consistency beats novelty. "We already have forty controllers" is a legitimate engineering reason, not a confession.

Rule of thumb: new services start Minimal; existing MVC apps stay MVC until something concrete forces the move. And if someone tells you Minimal APIs "don't scale to real projects," that usually means they wrote all forty endpoints as lambdas in one Program.cs. That's not the framework's fault — that's the same person who'd have written a two-thousand-line controller.

Key Takeaways

AddValidation() makes DataAnnotations work on Minimal APIs — no FluentValidation, no hand-rolled filter, no package reference in a web project. On positional records, [property:] is mandatory or validation silently does nothing.
Filters own the rules that need services — DataAnnotations validate shape, IEndpointFilter validates reality. Keep the check-then-act race out of it by making the operation itself atomic.
Version the endpoints that broke, not the API — a response-shape change is versioned; a 201 Created with just a Location header often doesn't need to be.
TypedResults and Results<T1, T2> replace .Produces<T>() — the signature becomes the OpenAPI contract, and the compiler enforces it.
.NET 10's OpenAPI defaults changed — 3.1 documents, YAML at runtime, no bundled UI, and .WithOpenApi() deprecated. Half the samples online are still on the .NET 8 shape.

Consumir servidores MCP desde .NET: cuando tu app es el cliente

Juan Gómez — Fri, 14 Aug 2026 14:59:43 +0000

Consumir servidores MCP desde .NET: cuando tu app es el cliente

La última vez construimos un servidor MCP en C# y lo conectamos a Claude Desktop y a Claude Code. Ambas son aplicaciones de otra persona. Tú escribiste las herramientas, las entregaste, y un cliente que no escribiste se llevó todo el beneficio.

Así que aquí va la otra mitad de la historia: ¿qué pasa cuando tu app en .NET es la que necesita esas herramientas? No Claude Desktop — tu consola interna de soporte, tu worker service, tu CLI. Este post escribe el lado cliente, lo conecta al mismo servidor de Aurora Coffee Co. de la última vez, y termina en un punto satisfactorio: el bucle de agente que escribimos a mano en el post de tool use — ese de unas sesenta líneas — se reduce a tres.

El lado cliente del protocolo

Un post sobre servidores habla de exponer capacidades. Un post sobre clientes es la imagen espejo, y son solo tres verbos:

Conectar — a través de un transporte. O lanzas el servidor como proceso hijo (stdio) o apuntas a una URL (HTTP).
Descubrir — preguntarle al servidor qué tiene. Las herramientas, y sus esquemas de entrada, llegan como datos. Nada está compilado dentro.
Llamar — invocar una herramienta por nombre con un conjunto de argumentos, y recibir contenido de vuelta.

Vale la pena detenerse en ese tercer paso, porque es la misma frontera de seguridad del post de tool use vista desde el lado opuesto. Antes, tu código era dueño de la ejecución y Claude solo podía pedir. Ahora el que pide eres tú, y el servidor es dueño de la ejecución. Envías un nombre y unos argumentos; lo que realmente se ejecuta es asunto exclusivo del servidor.

El paso de descubrimiento es lo que diferencia esto de simplemente llamar a un cliente de API. No tienes una clase proxy generada con un GetOrderStatus(string) encima. Tienes una lista de herramientas que llegó en tiempo de ejecución, y código que tiene que estar cómodo con eso.

Conectando con el servidor de Aurora

Arranca una app de consola y agrega el SDK. El cliente vive en ModelContextProtocol.Core si quieres dependencias mínimas, o en el paquete completo ModelContextProtocol si esa misma app también hospeda un servidor:

dotnet new console -o AuroraCoffee.Support
cd AuroraCoffee.Support
dotnet add package ModelContextProtocol.Core

Para un servidor local, el transporte stdio lo lanza como proceso hijo — exactamente lo que Claude Desktop hacía por ti con aquel archivo JSON de configuración la última vez, solo que ahora el que lo lanza eres tú:

using ModelContextProtocol.Client;

var transport = new StdioClientTransport(new StdioClientTransportOptions
{
    Name = "aurora-coffee",
    Command = "dotnet",
    Arguments = ["run", "--project", "../AuroraCoffee.Mcp"],
});

await using var client = await McpClient.CreateAsync(transport);

Esa es toda la conexión. McpClient.CreateAsync arranca el proceso, hace el handshake del protocolo y te entrega un cliente vivo. Fíjate en el await using — el cliente es dueño de un proceso hijo, y dejarlo sin liberar te deja un dotnet huérfano corriendo. No preguntes cuántos procesos sueltos hicieron falta para que se me grabara.

Descubre antes de llamar

Ahora la parte que la gente se salta y luego depura durante una hora. Imprime la lista de herramientas antes de escribir un solo CallToolAsync:

foreach (var tool in await client.ListToolsAsync())
{
    Console.WriteLine($"{tool.Name} — {tool.Description}");
}

La razón no es ceremonia. El SDK deriva los nombres de las herramientas a partir de los nombres de los métodos de tu servidor, así que la cadena exacta que expone el protocolo puede no ser el identificador de C# que escribiste. El descubrimiento es el contrato; el código fuente en C# del lado servidor es un detalle de implementación. Imprime la lista, copia los nombres reales, y escribe tus llamadas contra esos. Adivinar el nombre te da un error en tiempo de ejecución sin ningún compilador que te salve.

Llamando a una herramienta

Con un nombre real en mano, invocarla es un nombre más un diccionario de argumentos:

using ModelContextProtocol.Protocol;

var result = await client.CallToolAsync(
    "get_order_status",
    new Dictionary<string, object?> { ["orderId"] = "A-1001" },
    cancellationToken: CancellationToken.None);

Console.WriteLine(result.Content.OfType<TextContentBlock>().First().Text);

Pedido A-1001: shipped, ETA 2026-08-03.

Content es una lista de bloques, no una cadena, porque una herramienta puede devolver texto, imágenes o varios bloques a la vez. Filtrar con OfType<TextContentBlock>() es la forma honesta de leerlo — y si haces .First() sobre una herramienta que no devolvió texto, eso es una excepción, así que usa FirstOrDefault() cuando no controles el servidor.

Fíjate en lo que no escribiste: ni JSON Schema, ni fontanería HTTP, ni encuadre de mensajes. Tampoco referenciaste el proyecto del servidor. Order y OrdersStore no existen en esta app — el único contrato es el cable.

La recompensa: entrégale las herramientas a Claude

Todo lo anterior es un cliente manejando herramientas a mano. La versión interesante es dejar que un modelo decida cuál llamar — que es exactamente para lo que escribimos un bucle a mano en el post de tool use.

McpClientTool hereda de AIFunction en Microsoft.Extensions.AI. Esa única herencia es todo el truco: las herramientas descubiertas de un servidor MCP entran directo en cualquier IChatClient como funciones invocables, sin código adaptador.

dotnet add package Anthropic
dotnet add package Microsoft.Extensions.AI

using Anthropic;
using Microsoft.Extensions.AI;

IChatClient chatClient = new AnthropicClient()   // lee ANTHROPIC_API_KEY
    .AsIChatClient("claude-opus-4-8")
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

var tools = await client.ListToolsAsync();

var response = await chatClient.GetResponseAsync(
    "¿El pedido A-1001 está enviado, y todavía te quedan ETH-250 en stock?",
    new ChatOptions { Tools = [.. tools] });

Console.WriteLine(response.Text);

El pedido A-1001 ya fue enviado y está en camino para llegar el 2026-08-03. Y sí —
los granos de Etiopía (ETH-250) están en stock, con 42 unidades disponibles.

Lee esa salida, y luego vuelve a mirar el bucle que escribimos a mano. La misma pregunta, las mismas dos llamadas a herramientas, la misma respuesta — solo que el while (true), la contabilidad de la lista de mensajes, la reconstrucción de bloques y la trampa de "devuelve el turno del asistente tal cual" desaparecieron. UseFunctionInvocation() es el middleware que corre ese bucle por ti: Claude pide una herramienta, él invoca la AIFunction correspondiente, devuelve el resultado y repite hasta que haya una respuesta.

Las herramientas en sí viven en un proceso completamente separado, escrito por alguien que nunca oyó hablar de esta app. Esa es la parte que vale la pena dejar reposar.

Conectando con un servidor remoto

stdio funciona cuando el servidor es un proceso hijo local. Para un servidor compartido — la versión HTTP con ASP.NET Core del final del post anterior — cambia el transporte y no toques nada más:

var transport = new HttpClientTransport(new HttpClientTransportOptions
{
    Endpoint = new Uri("https://tools.auroracoffee.example/mcp"),
    TransportMode = HttpTransportMode.StreamableHttp,
});

await using var client = await McpClient.CreateAsync(transport);

ListToolsAsync, CallToolAsync y el cableado del IChatClient son idénticos de aquí en adelante — el transporte es lo único que nota la diferencia. TransportMode usa AutoDetect por defecto, que intenta Streamable HTTP y cae a SSE heredado, así que puedes omitirlo si no sabes qué soporta el otro extremo. Ponlo explícito cuando sí lo sepas; la autodetección cuesta un viaje de ida y vuelta.

Algo que cambió desde el post anterior

Vale la pena señalarlo si estás construyendo sobre el post del servidor: el SDK de C# publicó la v2.0 el 28 de julio de 2026, implementando la revisión de especificación 2026-07-28 — el cambio de protocolo más grande desde que MCP salió. Los atributos del lado servidor ([McpServerToolType], [McpServerTool]) y las APIs de cliente de arriba siguen igual, pero dos cosas se movieron:

El transporte HTTP es sin estado (stateless) por defecto. HttpServerTransportOptions.Stateless ahora vale true por defecto, el handshake de initialize desapareció, y la cabecera Mcp-Session-Id se fue. Excelente para escalar un servidor compartido detrás de un balanceador; un cambio de comportamiento si asumías sesiones.
Las peticiones iniciadas por el servidor (sampling, roots) quedaron obsoletas bajo el diagnóstico MCP9005 y lanzan excepción en modo sin estado. Los flujos interactivos pasan a Multi Round-Trip Requests.

Si tu servidor hace herramientas de petición/respuesta simples — que es la mayoría, incluido Aurora — no vas a notar nada. Si dependía de sesiones, lee las notas de migración antes de actualizar.

Cuándo escribir un cliente — y cuándo no

Escribe un cliente MCP cuando tu app necesita capacidades que viven fuera de ella: un servidor que mantiene tu equipo de plataforma, un servidor de terceros que no controlas, o tu propio servidor que varias apps comparten. La ganancia es que la lista de herramientas puede cambiar en el servidor sin un redespliegue de tu lado — aparece una herramienta nueva, ListToolsAsync la devuelve, y si hay un modelo al volante, empieza a usarla sin que tú publiques una sola línea de código.

Sáltatelo cuando las herramientas son simplemente... tus propios métodos, en tu propia app, llamados por tu propio bucle de modelo. Pasar por un protocolo y una frontera de proceso para llamar a una función que podrías haber llamado directo es puro teatro arquitectónico. El enfoque de tool use es más simple y más rápido ahí, y siempre lo fue.

Regla general: cliente MCP cuando las herramientas cruzan una frontera que no controlas; tool use dentro del proceso cuando no la cruzan.

Puntos Clave

Un cliente son tres verbos — conectar por un transporte, descubrir qué hay, y llamar por nombre. Todo lo demás es problema del SDK.
El contrato es el descubrimiento, no el código C# de tu servidor — imprime ListToolsAsync() y usa los nombres que devuelve. El compilador no puede atrapar un nombre de herramienta adivinado.
McpClientTool es un AIFunction — esa única herencia hace que las herramientas MCP entren en cualquier IChatClient, y UseFunctionInvocation() reemplaza el bucle de agente escrito a mano completo.
El transporte es lo único que cambia para lo remoto — stdio para un proceso hijo local, HttpClientTransport para un servidor compartido; el código de descubrir y llamar es idéntico.
La v2.0 pasó a ser sin estado por defecto — los servidores HTTP ya no hacen el handshake de initialize y sampling/roots quedaron obsoletos. Los servidores de herramientas simples no se ven afectados; los que dependen de sesiones necesitan una revisión.

Consuming MCP Servers from .NET: When Your App Becomes the Client

Juan Gómez — Fri, 14 Aug 2026 14:59:40 +0000

Consuming MCP Servers from .NET: When Your App Becomes the Client

Last time we built an MCP server in C# and plugged it into Claude Desktop and Claude Code. Both of those are somebody else's app. You wrote the tools, handed them over, and a client you didn't write got all the benefit.

So here's the other half of the story: what happens when your .NET app is the thing that needs those tools? Not Claude Desktop — your internal support console, your worker service, your CLI. This post writes the client side, connects it to the same Aurora Coffee Co. server from last time, and ends somewhere satisfying: the hand-rolled agent loop from the tool-use post — the one we wrote by hand in about sixty lines — collapses into three.

The client side of the protocol

A server post talks about exposing capabilities. A client post is the mirror image, and it's just three verbs:

Connect — over a transport. Either you launch the server as a child process (stdio) or you point at a URL (HTTP).
Discover — ask the server what it has. Tools, and their input schemas, come back as data. Nothing is compiled in.
Call — invoke a tool by name with a bag of arguments, get content back.

That third step is worth pausing on, because it's the same security boundary from the tool-use post viewed from the opposite side. Back then, your code owned execution and Claude only got to ask. Now you're the one asking, and the server owns execution. You send a name and arguments; what actually runs is entirely the server's business.

The discovery step is what makes this different from just calling an API client. You don't have a generated proxy class with GetOrderStatus(string) on it. You have a list of tools that arrived at runtime, and code that has to be okay with that.

Connecting to the Aurora server

Start a console app and add the SDK. The client lives in ModelContextProtocol.Core if you want minimal dependencies, or the full ModelContextProtocol package if this same app also hosts a server:

dotnet new console -o AuroraCoffee.Support
cd AuroraCoffee.Support
dotnet add package ModelContextProtocol.Core

For a local server, the stdio transport launches it as a child process — exactly what Claude Desktop was doing for you via that JSON config last time, except now you're the one spawning it:

using ModelContextProtocol.Client;

var transport = new StdioClientTransport(new StdioClientTransportOptions
{
    Name = "aurora-coffee",
    Command = "dotnet",
    Arguments = ["run", "--project", "../AuroraCoffee.Mcp"],
});

await using var client = await McpClient.CreateAsync(transport);

That's the whole connection. McpClient.CreateAsync starts the process, performs the protocol handshake, and hands you a live client. Note the await using — the client owns a child process, and letting it go undisposed leaves an orphaned dotnet running. Ask me how many stray processes it took to internalize that.

Discover before you call

Now the part people skip and then debug for an hour. Print the tool list before you write a single CallToolAsync:

foreach (var tool in await client.ListToolsAsync())
{
    Console.WriteLine($"{tool.Name} — {tool.Description}");
}

The reason isn't ceremony. Tool names are derived from your server's method names by the SDK, so the exact string the protocol exposes may not be the C# identifier you typed. Discovery is the contract; the C# source on the server side is an implementation detail. Print the list, copy the real names, then write your calls against those. Guessing the name gets you a runtime error with no compiler to save you.

Calling a tool

With a real name in hand, invoking it is a name plus a dictionary of arguments:

using ModelContextProtocol.Protocol;

var result = await client.CallToolAsync(
    "get_order_status",
    new Dictionary<string, object?> { ["orderId"] = "A-1001" },
    cancellationToken: CancellationToken.None);

Console.WriteLine(result.Content.OfType<TextContentBlock>().First().Text);

Order A-1001: shipped, ETA 2026-08-03.

Content is a list of blocks, not a string, because a tool can return text, images, or several blocks at once. Filtering with OfType<TextContentBlock>() is the honest way to read it — and if you .First() on a tool that returned no text, that's an exception, so use FirstOrDefault() when you don't control the server.

Notice what you didn't write: no JSON Schema, no HTTP plumbing, no message framing. You also didn't reference the server's project. Order and OrdersStore don't exist in this app — the only contract is the wire.

The payoff: hand the tools to Claude

Everything above is a client driving tools by hand. The interesting version is letting a model decide which to call — which is exactly what we hand-wrote a loop for in the tool-use post.

McpClientTool derives from AIFunction in Microsoft.Extensions.AI. That single inheritance is the whole trick: tools discovered from an MCP server drop straight into any IChatClient as callable functions, no adapter code.

dotnet add package Anthropic
dotnet add package Microsoft.Extensions.AI

using Anthropic;
using Microsoft.Extensions.AI;

IChatClient chatClient = new AnthropicClient()   // reads ANTHROPIC_API_KEY
    .AsIChatClient("claude-opus-4-8")
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

var tools = await client.ListToolsAsync();

var response = await chatClient.GetResponseAsync(
    "Is order A-1001 shipped, and do you still have ETH-250 in stock?",
    new ChatOptions { Tools = [.. tools] });

Console.WriteLine(response.Text);

Order A-1001 has shipped and is on track to arrive 2026-08-03. And yes — the
Ethiopia beans (ETH-250) are in stock, with 42 units available.

Read that output, then go back and look at the loop we wrote by hand. Same question, same two tool calls, same answer — except the while (true), the message-list bookkeeping, the block reconstruction, and the "echo the assistant turn back verbatim" gotcha are all gone. UseFunctionInvocation() is the middleware that runs that loop for you: Claude asks for a tool, it invokes the matching AIFunction, feeds the result back, and repeats until there's an answer.

The tools themselves live in a completely separate process, written by someone who never heard of this app. That's the part worth sitting with.

Connecting to a remote server

stdio works when the server is a local child process. For a shared server — the ASP.NET Core HTTP version from the end of the last post — swap the transport and change nothing else:

var transport = new HttpClientTransport(new HttpClientTransportOptions
{
    Endpoint = new Uri("https://tools.auroracoffee.example/mcp"),
    TransportMode = HttpTransportMode.StreamableHttp,
});

await using var client = await McpClient.CreateAsync(transport);

ListToolsAsync, CallToolAsync, and the IChatClient wiring are all identical from here — the transport is the only thing that knows the difference. TransportMode defaults to AutoDetect, which tries Streamable HTTP and falls back to legacy SSE, so you can leave it off if you don't know what the far end supports. Set it explicitly when you do; auto-detection costs a round trip.

One thing that changed since the last post

Worth flagging if you're building on the server post: the C# SDK shipped v2.0 on July 28, 2026, implementing the 2026-07-28 spec revision — the largest protocol change since MCP launched. The server-side attributes ([McpServerToolType], [McpServerTool]) and the client APIs above are unchanged, but two things moved:

HTTP transport is stateless by default. HttpServerTransportOptions.Stateless now defaults to true, the initialize handshake is gone, and the Mcp-Session-Id header went away. Great for scaling a shared server behind a load balancer; a behavior change if you assumed sessions.
Server-initiated requests (sampling, roots) are deprecated under diagnostic MCP9005 and throw in stateless mode. Interactive flows move to Multi Round-Trip Requests instead.

If your server is doing plain request/response tools — which is most servers, including Aurora — you won't notice. If it was leaning on sessions, read the migration notes before you upgrade.

When to write a client — and when not to

Write an MCP client when your app needs capabilities that live outside it: a server your platform team maintains, a third-party server you don't control, or your own server that several apps share. The payoff is that the tool list can change on the server without a redeploy on your side — new tool appears, ListToolsAsync returns it, and if a model is driving, it starts using it without you shipping a line of code.

Skip it when the tools are just... your own methods, in your own app, called by your own model loop. Going through a protocol and a process boundary to call a function you could have called directly is architecture cosplay. The tool-use approach is simpler and faster there, and it always was.

Rule of thumb: MCP client when the tools cross a boundary you don't own; plain in-process tool use when they don't.

Key Takeaways

A client is three verbs — connect over a transport, discover what's there, call by name. Everything else is the SDK's problem.
Discovery is the contract, not your server's C# source — print ListToolsAsync() and use the names it returns. The compiler can't catch a guessed tool name.
McpClientTool is an AIFunction — that one inheritance means MCP tools drop into any IChatClient, and UseFunctionInvocation() replaces the entire hand-written agent loop.
Transport is the only thing that changes for remote — stdio for a local child process, HttpClientTransport for a shared server; the discover-and-call code is identical.
v2.0 went stateless by default — HTTP servers no longer do the initialize handshake and sampling/roots are deprecated. Plain tool servers are unaffected; session-dependent ones need a look.

Native AOT en .NET 10: publica un Minimal API que se salta el peaje del JIT

Juan Gómez — Fri, 07 Aug 2026 20:52:24 +0000

Native AOT en .NET 10: publica un Minimal API que se salta el peaje del JIT

Cada vez que un servicio .NET orquestado en contenedores escala, paga el mismo peaje: el runtime arranca, el compilador JIT se calienta, y solo entonces la app empieza a atender tráfico. Multiplica eso por la cantidad de réplicas que tu autoscaler lance durante un pico de tráfico, y "unos cientos de milisegundos de arranque" se convierte en dinero real y en latencia real sobre tu P99. Native AOT existe para saltarse ese peaje del todo — sin JIT, sin calentamiento, solo código máquina nativo que empieza a correr de inmediato.

Este post es un cambio de ritmo deliberado. Los últimos cuatro artículos integraron Claude en .NET de una forma u otra; este es .NET puro — sin ningún LLM a la vista, solo un Minimal API que arranca rápido porque nunca le pidió permiso a un compilador JIT.

Qué es Native AOT en realidad

"AOT" significa compilación ahead-of-time (por adelantado) — lo opuesto a la compilación JIT ("just-in-time") que .NET hace normalmente. Con Native AOT, dotnet publish ejecuta un compilador nativo de IL que convierte toda tu app, más las piezas del runtime que realmente usa, en un único ejecutable nativo en el momento de publicar. No queda IL esperando a ser compilado por el JIT al arrancar, porque la app desplegada no tiene compilador JIT en absoluto.

De ahí se derivan tres consecuencias:

El arranque es tan rápido como el código nativo, porque la CPU ejecuta código máquina desde la primera instrucción — no hay nada que compilar antes.
El binario es autocontenido y recortado (trimmed) — solo incluye el código que el grafo de dependencias de tu app realmente alcanza, no el framework completo.
Algunos comportamientos dinámicos dejan de funcionar — cualquier cosa que dependa de generar o cargar código en tiempo de ejecución (serialización basada en reflexión, Assembly.LoadFile, generación de código en runtime) ya no tiene nada contra qué generarse. Volvemos a esto más adelante; es lo que decide si AOT le queda bien a tu servicio.

Microsoft corre su propio benchmark comparando una app con Native AOT, una app recortada pero con JIT, y una app sin recortar, en tamaño en disco, memoria y tiempo de arranque — Native AOT gana en las tres en esa comparación. En vez de repetir números que no puedo verificar contra tu hardware y tu carga de trabajo, la sección "Números reales" más abajo te muestra exactamente cómo producir los tuyos.

Construyendo un servicio real: la API de pedidos de Aurora Coffee Co.

La misma tienda ficticia de los posts de Claude, esta vez sin Claude. Aurora Coffee Co. necesita una API de pedidos — pequeña, enfocada, y exactamente la forma de servicio que se despliega cien veces a lo largo de una flota. Genérala con la plantilla oficial lista para AOT:

dotnet new webapiaot -o AuroraCoffee.Orders
cd AuroraCoffee.Orders

webapiaot (Web API Native AOT) no es la plantilla de Web API normal con un flag activado — está diseñada distinta a propósito:

Llama a WebApplication.CreateSlimBuilder() en vez de CreateBuilder(), que registra solo las funciones esenciales de ASP.NET Core (sin HTTPS/HTTP3 en Kestrel, sin integración con IIS) para mantener pequeño el resultado recortado.
Solo Minimal APIs — MVC no es compatible con AOT, así que no hay controladores a los que recurrir.
La serialización JSON está conectada a un JsonSerializerContext generado por código fuente en vez de por reflexión, porque el System.Text.Json basado en reflexión no funciona una vez que se recortaron los metadatos de tipo que necesita.

El dominio y los datos

Una decisión deliberada desde el inicio: sin Entity Framework Core. EF Core hoy no es compatible con AOT — su pipeline de consultas depende de generación de código en tiempo de ejecución que Native AOT no puede producir. Para un servicio real recurrirías a Dapper o ADO.NET puro; para este ejemplo, un almacén en memoria inyectable ilustra lo mismo sin necesitar una base de datos:

using System.Collections.Concurrent;

public sealed record Order(string Id, string Sku, int Quantity, string Status);

public sealed class OrdersStore
{
    // Se registra como singleton y se escribe desde peticiones concurrentes, así que un
    // Dictionary común sería una condición de carrera — puede corromper sus buckets
    // internos durante un redimensionamiento.
    private readonly ConcurrentDictionary<string, Order> _orders = new()
    {
        ["A-2001"] = new("A-2001", "ETH-250", 2, "processing"),
        ["A-2002"] = new("A-2002", "COL-1KG", 1, "shipped"),
    };

    // Arranca después de los IDs precargados para que el primer pedido generado sea A-2003.
    private int _nextOrderId = 2002;

    public Order? Find(string id) => _orders.TryGetValue(id, out var order) ? order : null;

    public Order Place(string sku, int quantity)
    {
        var id = Interlocked.Increment(ref _nextOrderId);
        var order = new Order($"A-{id}", sku, quantity, "processing");
        _orders[order.Id] = order;
        return order;
    }
}

Program.cs — las partes con forma de AOT

using System.Text.Json.Serialization;

var builder = WebApplication.CreateSlimBuilder(args);

builder.Services.AddSingleton<OrdersStore>();
builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonContext.Default);
});

var app = builder.Build();

var orders = app.MapGroup("/orders");

orders.MapGet("/{id}", (string id, OrdersStore store) =>
    store.Find(id) is { } order ? Results.Ok(order) : Results.NotFound());

orders.MapPost("/", (PlaceOrderRequest request, OrdersStore store) =>
{
    var order = store.Place(request.Sku, request.Quantity);
    return Results.Created($"/orders/{order.Id}", order);
});

app.Run();

public sealed record PlaceOrderRequest(string Sku, int Quantity);

[JsonSerializable(typeof(Order))]
[JsonSerializable(typeof(PlaceOrderRequest))]
internal partial class AppJsonContext : JsonSerializerContext;

Ese AppJsonContext es la parte que todo Minimal API con Native AOT necesita, y la que todo tutorial que se la salta te va a dejar depurando una excepción en tiempo de ejecución. Cada tipo que cruza el cuerpo HTTP — request o response — necesita una entrada [JsonSerializable] aquí. Si te olvidas de uno, en vez de un error de compilación obtienes un fallo en runtime la primera vez que ese tipo necesite serializarse, porque el respaldo basado en reflexión sencillamente ya no está.

Publicarlo es el mismo comando que cualquier app autocontenida, ya que la plantilla webapiaot ya puso <PublishAot>true</PublishAot> en el .csproj:

dotnet publish -r linux-x64 -c Release

Presta atención a la salida del build en este paso — cada advertencia de AOT o de recorte que imprime es un reporte de bug real, no ruido. Una app que se publica sin advertencias se comporta igual que la versión compilada con JIT; una que se publica con advertencias puede fallar en runtime en una ruta de código que tus pruebas no cubrieron. Corrígelas antes de desplegar, no después de una alerta de guardia.

Números reales: mídelo tú mismo

En vez de citar un benchmark corrido en un hardware que no es el tuyo, publica las tres variantes de la misma app y compáralas en el tuyo:

# 1. Dependiente del framework (necesita el runtime de .NET instalado en la máquina destino)
dotnet publish -c Release -o out/framework-dependent

# 2. Autocontenida + recortada, todavía compilada con JIT
dotnet publish -r linux-x64 -c Release --self-contained -p:PublishTrimmed=true -o out/trimmed

# 3. Native AOT
dotnet publish -r linux-x64 -c Release -o out/aot

Luego compara lo que realmente importa para un servicio desplegado:

Tamaño en disco: du -sh out/*/AuroraCoffee.Orders* (o el tamaño de la imagen de contenedor, si empaquetas una) — esto es lo que descargas por red en cada despliegue.
Tiempo de arranque: mide el hueco entre el inicio del proceso y la primera petición exitosa, por ejemplo time curl --retry 20 --retry-connrefused http://localhost:5000/orders/A-2001 justo después de lanzar cada variante.
Memoria en reposo: ps -o rss -p <pid> (Linux) o el working set del Administrador de Tareas (Windows), unos segundos después de arrancar y sin tráfico todavía.

El propio benchmark de plantilla de Microsoft (tamaño, memoria y tiempo de arranque comparados entre AOT, recortada y sin recortar) muestra a Native AOT por delante en las tres — mira la gráfica en la documentación de Native AOT en ASP.NET Core. Tus números van a variar según la carga de trabajo y el hardware, pero la dirección — AOT más pequeña y más rápida, sin recortar la más grande y lenta — debería mantenerse.

Qué es realmente nuevo en .NET 10 (no heredado de .NET 7/8)

Native AOT en sí llegó en .NET 7 y maduró a lo largo de .NET 8 y 9. .NET 10 agrega tres cosas que vale la pena conocer en concreto:

Metadatos de ensamblado IsAotCompatible. Los autores de librerías ahora pueden declarar compatibilidad con AOT de forma explícita:

<PropertyGroup>
    <IsAotCompatible>true</IsAotCompatible>
</PropertyGroup>

Activarlo enciende automáticamente los analizadores de recorte, single-file y AOT para esa librería. Combínalo con VerifyReferenceAotCompatibility en tu propia app para que te avise cuando una dependencia no haya hecho esa promesa:

<PropertyGroup>
    <IsAotCompatible>true</IsAotCompatible>
    <VerifyReferenceAotCompatibility>true</VerifyReferenceAotCompatibility>
</PropertyGroup>

Las apps de un solo archivo apuntan a AOT por defecto. Un único archivo .cs ejecutado con dotnet run app.cs ahora se puede publicar directo a un ejecutable nativo con dotnet publish app.cs — sin necesitar archivo de proyecto. .NET 10 hace que AOT sea el valor por defecto para estas apps; puedes desactivarlo por archivo si un script necesita un paquete incompatible con AOT:

#:property PublishAot=false

Las apps de consola obtienen imágenes de contenedor nativas gratis. dotnet publish /t:PublishContainer ahora funciona en cualquier app de consola, no solo en proyectos de ASP.NET Core y Worker Service — ya no hace falta activar <EnableSdkContainerSupport>. Combínalo con Native AOT y un worker o una herramienta de CLI pasa directo de código fuente a una imagen de contenedor mínima en un solo comando.

Cuándo usarlo — y cuándo dejarlo en paz

Recurre a Native AOT cuando corres muchas instancias del mismo servicio — el tipo de carga de trabajo donde recortar el tiempo de arranque y la memoria de una réplica se paga solo cien veces a lo largo de una flota: microservicios en contenedores, funciones serverless, cualquier cosa que un autoscaler encienda y apague bajo carga.

Déjalo en paz cuando tu stack depende de las funciones dinámicas que no puede hacer: EF Core (hoy no compatible con AOT), librerías intensivas en reflexión que aún no agregaron generadores de código fuente, MVC, Blazor Server, SignalR completo, o Session — todas sin soporte o solo parcialmente soportadas bajo Native AOT a partir de .NET 10. Y recuerda que los binarios de AOT son específicos de plataforma: un publish para linux-x64 solo corre en linux-x64, así que el despliegue dependiente del framework y multiplataforma sigue siendo más simple si soportas muchas combinaciones de sistema operativo y arquitectura desde un mismo build.

Regla general: Native AOT cuando la cantidad de instancias es alta y tus dependencias son compatibles con AOT; quédate con JIT (opcionalmente recortado) cuando EF Core o librerías intensivas en reflexión sean pieza central. Y si el proveedor de una librería te dice que su paquete "funciona bien con reflexión", ese es el momento de recordar que Native AOT no hace favores — simplemente no ejecuta código que nunca estuvo ahí para empezar.

Puntos Clave

AOT cambia dinamismo por velocidad — sin JIT significa sin paso de compilación en runtime, pero también sin reflexión sin límites, sin generación de código en runtime, sin carga dinámica de ensamblados. Sabe cuáles de esas cosas realmente necesita tu app antes de comprometerte.
CreateSlimBuilder + JSON generado por código fuente es la forma de un Minimal API con AOT — dotnet new webapiaot genera ambos correctamente; saltarse el JsonSerializerContext es la forma número uno de romper uno.
EF Core es el mayor bloqueador real — si tu servicio depende fuerte de EF, Native AOT todavía no es una ganancia directa; Dapper o ADO.NET son las alternativas compatibles con AOT hoy.
Confía en las advertencias de publish, no en tu instinto — cero advertencias de AOT/recorte al publicar significa que el build de AOT se comporta como el build con JIT; cualquier advertencia es un posible fallo en runtime esperando la entrada correcta.
.NET 10 extiende AOT más allá de los servicios web — metadatos IsAotCompatible para autores de librerías, apps de un solo archivo con AOT por defecto, e imágenes de contenedor nativas para cualquier app de consola son nuevos en esta versión, no el mismo "AOT 101" repetido por cuarto año consecutivo.

Native AOT in .NET 10: Ship a Minimal API That Skips the JIT Tax

Juan Gómez — Fri, 07 Aug 2026 20:52:21 +0000

Native AOT in .NET 10: Ship a Minimal API That Skips the JIT Tax

Every time a container-orchestrated .NET service scales out, it pays the same toll: the runtime starts, the JIT compiler warms up, and only then does the app start serving traffic. Multiply that by however many replicas your autoscaler spins up during a traffic spike, and "a few hundred milliseconds of startup" turns into real money and real latency on your P99. Native AOT exists to skip that toll entirely — no JIT, no warm-up, just native machine code that starts running immediately.

This one's a deliberate change of pace. The last four posts here built Claude into .NET one way or another; this one is plain .NET — no LLM in sight, just a Minimal API that starts fast because it never asked a JIT compiler for permission.

What Native AOT actually is

"AOT" stands for ahead-of-time compilation — the opposite of the JIT ("just-in-time") compilation .NET normally does. With Native AOT, dotnet publish runs a native IL compiler that turns your entire app, plus the runtime bits it actually uses, into one native executable at publish time. There's no IL sitting around waiting to be JIT-compiled at startup, because there's no JIT compiler in the deployed app at all.

Three consequences fall out of that:

Startup is native-code-fast, because the CPU is running machine code from the first instruction — nothing needs to be compiled first.
The binary is self-contained and trimmed — it ships only the code your app's dependency graph actually reaches, not the whole framework.
Some dynamic behaviors stop working — anything that depends on generating or loading code at runtime (reflection-heavy serialization, Assembly.LoadFile, runtime code-gen) has nothing left to generate against. We'll come back to this; it's the main thing that decides whether AOT fits your service.

Microsoft runs its own benchmark comparing a Native AOT app, a trimmed-but-JIT app, and a plain untrimmed app across disk size, memory, and startup time — Native AOT wins on all three in that comparison. Rather than repeat numbers I can't verify against your hardware and workload, the "Real-world numbers" section below shows you exactly how to produce your own.

Building a real service: Aurora Coffee Co.'s Orders API

Same fictional shop from the Claude posts, minus Claude this time. Aurora Coffee Co. needs an Orders API — small, focused, and exactly the shape of service that gets deployed a hundred times across a fleet. Scaffold it with the official AOT-ready template:

dotnet new webapiaot -o AuroraCoffee.Orders
cd AuroraCoffee.Orders

webapiaot (Web API Native AOT) isn't the regular Web API template with a flag flipped — it's shaped differently on purpose:

It calls WebApplication.CreateSlimBuilder() instead of CreateBuilder(), which registers only the essential ASP.NET Core features (no HTTPS/HTTP3 in Kestrel, no IIS integration) to keep the trimmed output small.
Minimal APIs only — MVC isn't AOT-compatible, so there are no controllers to reach for.
JSON serialization is wired to a source-generated JsonSerializerContext instead of reflection, because reflection-based System.Text.Json doesn't work once the type metadata it needs has been trimmed away.

The domain and the data

One deliberate choice up front: no Entity Framework Core. EF Core isn't AOT-compatible today — its query pipeline leans on runtime code generation that Native AOT can't produce. For a real service you'd reach for Dapper or raw ADO.NET instead; for this example, an injectable in-memory store makes the same point without a database dependency:

using System.Collections.Concurrent;

public sealed record Order(string Id, string Sku, int Quantity, string Status);

public sealed class OrdersStore
{
    // Registered as a singleton and written from concurrent requests, so a plain
    // Dictionary would be a data race — it can corrupt its buckets during a resize.
    private readonly ConcurrentDictionary<string, Order> _orders = new()
    {
        ["A-2001"] = new("A-2001", "ETH-250", 2, "processing"),
        ["A-2002"] = new("A-2002", "COL-1KG", 1, "shipped"),
    };

    // Starts past the seeded IDs so the first generated order is A-2003.
    private int _nextOrderId = 2002;

    public Order? Find(string id) => _orders.TryGetValue(id, out var order) ? order : null;

    public Order Place(string sku, int quantity)
    {
        var id = Interlocked.Increment(ref _nextOrderId);
        var order = new Order($"A-{id}", sku, quantity, "processing");
        _orders[order.Id] = order;
        return order;
    }
}

Program.cs — the AOT-shaped parts

using System.Text.Json.Serialization;

var builder = WebApplication.CreateSlimBuilder(args);

builder.Services.AddSingleton<OrdersStore>();
builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonContext.Default);
});

var app = builder.Build();

var orders = app.MapGroup("/orders");

orders.MapGet("/{id}", (string id, OrdersStore store) =>
    store.Find(id) is { } order ? Results.Ok(order) : Results.NotFound());

orders.MapPost("/", (PlaceOrderRequest request, OrdersStore store) =>
{
    var order = store.Place(request.Sku, request.Quantity);
    return Results.Created($"/orders/{order.Id}", order);
});

app.Run();

public sealed record PlaceOrderRequest(string Sku, int Quantity);

[JsonSerializable(typeof(Order))]
[JsonSerializable(typeof(PlaceOrderRequest))]
internal partial class AppJsonContext : JsonSerializerContext;

That AppJsonContext is the part every Native AOT Minimal API needs and every tutorial that skips it will leave you debugging a runtime exception. Every type that crosses the HTTP body — request or response — needs a [JsonSerializable] entry here. Miss one, and instead of a compile error you get a runtime failure the first time that type needs serializing, because the reflection-based fallback simply isn't there anymore.

Publishing it is the same command as any self-contained app, since the webapiaot template already set <PublishAot>true</PublishAot> in the .csproj:

dotnet publish -r linux-x64 -c Release

Watch the build output on this step — every AOT or trimming warning it prints is a real bug report, not noise. An app that publishes with zero warnings behaves identically to the JIT-compiled version; one that publishes with warnings might throw at runtime on a code path your tests didn't exercise. Fix them before you ship, not after a page.

Real-world numbers: measure it yourself

Rather than quote a benchmark that was run on hardware you don't have, publish all three variants of the same app and compare them on yours:

# 1. Framework-dependent (needs the .NET runtime installed on the target machine)
dotnet publish -c Release -o out/framework-dependent

# 2. Self-contained + trimmed, still JIT-compiled
dotnet publish -r linux-x64 -c Release --self-contained -p:PublishTrimmed=true -o out/trimmed

# 3. Native AOT
dotnet publish -r linux-x64 -c Release -o out/aot

Then compare what actually matters for a deployed service:

Disk size: du -sh out/*/AuroraCoffee.Orders* (or the container image size, if you're shipping one) — this is what you pull across the network on every deploy.
Startup time: time the gap between process start and the first successful request, e.g. time curl --retry 20 --retry-connrefused http://localhost:5000/orders/A-2001 right after launching each variant.
Idle memory: ps -o rss -p <pid> (Linux) or Task Manager's working set (Windows), a few seconds after startup with no traffic yet.

Microsoft's own template benchmark (size, memory, and startup time compared across AOT, trimmed, and untrimmed) shows Native AOT ahead on all three — see the chart in the ASP.NET Core Native AOT docs. Your numbers will differ by workload and hardware, but the direction — AOT smallest and fastest, untrimmed largest and slowest — should hold.

What's actually new in .NET 10 (not carried over from .NET 7/8)

Native AOT itself shipped in .NET 7 and matured through .NET 8 and 9. .NET 10 adds three things worth knowing about specifically:

IsAotCompatible assembly metadata. Library authors can now declare AOT compatibility explicitly:

<PropertyGroup>
    <IsAotCompatible>true</IsAotCompatible>
</PropertyGroup>

Setting it turns on trim, single-file, and AOT analyzers for that library automatically. Pair it with VerifyReferenceAotCompatibility in your own app to get warned when a dependency hasn't made that promise:

<PropertyGroup>
    <IsAotCompatible>true</IsAotCompatible>
    <VerifyReferenceAotCompatibility>true</VerifyReferenceAotCompatibility>
</PropertyGroup>

File-based apps target AOT by default. A single .cs file run with dotnet run app.cs can now be published straight to a native executable with dotnet publish app.cs — no project file needed. .NET 10 makes AOT the default for these; opt out per-file if a script needs an AOT-incompatible package:

#:property PublishAot=false

Console apps get native container images for free. dotnet publish /t:PublishContainer now works on any console app, not just ASP.NET Core and Worker Service projects — no <EnableSdkContainerSupport> opt-in required anymore. Combine it with Native AOT and a worker or CLI tool goes straight from source to a minimal container image in one command.

When to use it — and when to leave it alone

Reach for Native AOT when you're running many instances of the same service — the kind of workload where shaving startup time and memory off one replica pays for itself a hundredfold across a fleet: containerized microservices, serverless functions, anything an autoscaler spins up and down under load.

Leave it alone when your stack leans on the dynamic features it can't do: EF Core (not AOT-compatible today), reflection-heavy libraries that haven't added source generators, MVC, Blazor Server, full SignalR, or Session — all either unsupported or only partially supported under Native AOT as of .NET 10. And remember AOT binaries are platform-specific: a linux-x64 publish only runs on linux-x64, so cross-platform framework-dependent deployment stays simpler if you support many OS/architecture combinations from one build.

Rule of thumb: Native AOT when instance count is high and your dependencies are AOT-clean; stick with JIT (optionally trimmed) when EF Core or reflection-heavy libraries are load-bearing. And if a library vendor tells you their package "works fine with reflection," that's the moment to remember Native AOT doesn't do favors — it just doesn't run code that was never there to begin with.

Key Takeaways

AOT trades dynamism for speed — no JIT means no runtime compilation step, but also no unbounded reflection, no runtime code-gen, no dynamic assembly loading. Know which of those your app actually needs before committing.
CreateSlimBuilder + source-generated JSON is the shape of an AOT Minimal API — dotnet new webapiaot scaffolds both correctly; skipping the JsonSerializerContext is the single most common way to break one.
EF Core is the biggest real-world blocker — if your service is EF-heavy, Native AOT isn't a drop-in win yet; Dapper or ADO.NET are the AOT-compatible alternatives today.
Trust the publish warnings, not your gut — zero AOT/trim warnings at publish time means the AOT build behaves like the JIT build; any warning is a potential runtime failure waiting for the right input.
.NET 10 extends AOT past web services — IsAotCompatible metadata for library authors, AOT-by-default file-based apps, and native container images for any console app are new this release, not just Native AOT 101 repeated for the fourth year running.

Crea un servidor MCP en C#: escribe tus herramientas una vez y úsalas en cualquier Claude

Juan Gómez — Fri, 31 Jul 2026 19:58:43 +0000

Crea un servidor MCP en C#: escribe tus herramientas una vez y úsalas en cualquier Claude

La última vez construimos un agente de tool use con Claude en C#. Funcionaba — pero cada herramienta vivía dentro de esa única app de consola. Si querías la misma capacidad de "consultar un pedido" dentro de Claude Desktop, o de Claude Code, o del agente de un compañero, tocaba copiar y pegar la herramienta y toda su fontanería en cada sitio. Herramientas atrapadas en un solo proceso, reimplementadas por todas partes. Ese es justo el acoplamiento que MCP viene a romper.

El Model Context Protocol le da la vuelta a quién es dueño de la herramienta. La escribes una vez, como un servidor independiente, y la expones sobre un protocolo estándar. Entonces cualquier cliente MCP — Claude Desktop, Claude Code, tu propio agente, lo que salga el próximo trimestre — se conecta y obtiene tus herramientas gratis. En este post cogemos las mismas herramientas de Aurora Coffee Co. de la última vez y las liberamos como un servidor MCP real en .NET, para luego enchufarlo a Claude.

Qué es MCP en realidad

MCP es un pequeño protocolo cliente/servidor (JSON-RPC por debajo) para conectar clientes de IA con tus capacidades. Con tres ideas ya puedes arrancar:

Cliente y servidor son procesos separados. El cliente es la app de IA (Claude Desktop, Claude Code). El servidor es tu código. Se hablan por un transporte, no por una tabla de funciones compartida.
Los servidores exponen tres cosas: tools (acciones que el modelo puede invocar — nuestro foco), resources (datos legibles, como ficheros o filas) y prompts (plantillas de prompt reutilizables). Hoy todo son tools.
Dos transportes. stdio — el cliente lanza tu servidor como proceso hijo y hablan por la entrada/salida estándar; ideal para herramientas locales. HTTP — tu servidor corre en algún sitio y los clientes se conectan por red; para herramientas compartidas o remotas.

Si leíste el artículo anterior, este es el mismo bucle de tool use — declaras una herramienta, el modelo la invoca, tu código la ejecuta, devuelves un resultado — pero ahora la herramienta vive al otro lado de una frontera de proceso, reutilizable por cualquier cliente en lugar de cableada dentro de una sola app.

El servidor que vamos a construir

¿Te acuerdas de Aurora Coffee Co.? Sus dos herramientas respondían preguntas de soporte sobre unos datos en memoria:

get_order_status(order_id) — consulta un pedido.
check_stock(sku) — comprueba el inventario de un producto.

La última vez esas herramientas eran métodos enterrados en un bucle de agente. Ahora se convierten en un servidor MCP que cualquier Claude puede invocar. Arranca una app de consola y añade dos paquetes:

dotnet new console -o AuroraCoffee.Mcp
cd AuroraCoffee.Mcp
dotnet add package ModelContextProtocol
dotnet add package Microsoft.Extensions.Hosting

ModelContextProtocol es el SDK oficial de C# (2.0, mantenido en colaboración con Microsoft). Microsoft.Extensions.Hosting nos da el host genérico — la misma historia de DI y configuración que usarías en cualquier servicio .NET.

Los datos, como servicio inyectable

Guardamos la "base de datos" de Aurora en un singleton para que las herramientas la reciban por inyección en el constructor — igual que un repositorio de verdad:

public sealed class CoffeeShopData
{
    public Dictionary<string, Order> Orders { get; } = new()
    {
        ["A-1001"] = new("A-1001", "shipped", "2026-08-03"),
        ["A-1002"] = new("A-1002", "processing", "2026-08-06"),
    };

    public Dictionary<string, int> Stock { get; } = new()
    {
        ["ETH-250"] = 42,
        ["COL-1KG"] = 0,
    };
}

public sealed record Order(string Id, string Status, string Eta);

Las herramientas

Esta es la parte que sustituye al JSON Schema escrito a mano y al switch de la última vez. Una clase marcada con [McpServerToolType], métodos marcados con [McpServerTool], y [Description] tanto en el método como en sus parámetros. El SDK lee la firma de tu método y te genera el JSON Schema:

using System.ComponentModel;
using ModelContextProtocol.Server;

[McpServerToolType]
public sealed class CoffeeTools(CoffeeShopData data)
{
    [McpServerTool, Description("Consulta el estado y la fecha estimada de entrega de un pedido por su id.")]
    public string GetOrderStatus(
        [Description("Id del pedido, p. ej. A-1001")] string orderId) =>
        data.Orders.TryGetValue(orderId, out var order)
            ? $"Pedido {order.Id}: {order.Status}, ETA {order.Eta}."
            : "No hay ningún pedido con ese id.";

    [McpServerTool, Description("Comprueba cuántas unidades de un SKU de producto hay en stock ahora mismo.")]
    public string CheckStock(
        [Description("SKU del producto, p. ej. ETH-250")] string sku) =>
        data.Stock.TryGetValue(sku, out var quantity)
            ? $"SKU {sku}: {quantity} unidades en stock."
            : "SKU desconocido.";
}

Esos atributos [Description] no son adorno — son los mismos docstrings con peso del artículo anterior, solo que escritos en un sitio más bonito. El del método le dice a Claude cuándo llamar a la herramienta; los de los parámetros, qué pasarle. Descripciones vagas aquí son la razón número uno de que un modelo ignore una herramienta perfectamente buena.

Fíjate en lo que desapareció: ni objeto input_schema, ni array required, ni parseo manual de argumentos. orderId es un parámetro string tipado, así que el SDK sabe que es un string obligatorio y te entrega el valor ya parseado. La fontanería del Enfoque 1 de la última vez ahora es trabajo del framework.

Uniéndolo todo

El host builder registra los datos, el servidor MCP, el transporte stdio y descubre automáticamente todos los [McpServerToolType] del ensamblado:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = Host.CreateApplicationBuilder(args);

// stdout es el canal del protocolo — los logs DEBEN ir a stderr o corromperás el stream.
builder.Logging.AddConsole(options =>
    options.LogToStandardErrorThreshold = LogLevel.Trace);

builder.Services.AddSingleton<CoffeeShopData>();
builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();

await builder.Build().RunAsync();

Ese es el servidor entero. Lee otra vez la línea del logging, porque ahí está la trampa más común del MCP por stdio: stdout transporta los mensajes JSON-RPC. Un solo Console.WriteLine despistado a stdout y Claude ve ruido donde esperaba JSON — el equivalente en protocolo a hablar con la boca llena. Manda todos los logs a stderr y no habrá problema.

Enchufándolo a Claude

Un servidor al que nadie se conecta no es más que una app de consola muy solitaria. Vamos a conectarlo a dos clientes.

Claude Desktop lee un fichero de configuración JSON (claude_desktop_config.json, en %APPDATA%\Claude\ en Windows o ~/Library/Application Support/Claude/ en macOS). Añade tu servidor bajo mcpServers:

{
  "mcpServers": {
    "aurora-coffee": {
      "command": "dotnet",
      "args": ["run", "--project", "C:/src/AuroraCoffee.Mcp"]
    }
  }
}

El cliente ejecuta ese comando, habla stdio con el proceso hijo y tus herramientas aparecen. Reinicia Claude Desktop y pregunta "¿El pedido A-1001 está enviado, y todavía te quedan ETH-250 en stock?" — llamará a ambas herramientas y responderá de verdad.

Claude Code es aún más corto — un comando de CLI, sin editar ficheros:

claude mcp add aurora-coffee -- dotnet run --project ./AuroraCoffee.Mcp

Mismo servidor, segundo cliente, cero cambios de código. Ese es justo el sentido de MCP: las herramientas no se movieron, pero ahora dos Claude distintos pueden alcanzarlas — y también el tercero que aún no has instalado.

Pruébalo sin cliente

Antes de tocar la config de ningún cliente, verifica el servidor con el MCP Inspector, una UI de navegador que habla el protocolo para que listes e invoques herramientas a mano:

npx @modelcontextprotocol/inspector dotnet run --project ./AuroraCoffee.Mcp

Lanza tu servidor, lista get_order_status y check_stock, y te deja disparar llamadas de prueba. Si una herramienta se porta mal, te enteras aquí — no tres capas dentro de un transcript de chat.

Llegando al mundo exterior: DI y HttpClient

Los diccionarios en memoria valen para una demo, pero las herramientas de verdad llaman a sistemas de verdad. Como el servidor es un host .NET normal, la inyección de dependencias funciona tal cual esperas — incluidos los HttpClient tipados. Considera que Aurora tiene una API de tostadero para notas de cata:

using System.ComponentModel;
using ModelContextProtocol.Server;

[McpServerToolType]
public sealed class RoastTools(HttpClient http)
{
    [McpServerTool, Description("Obtiene las notas de tueste de hoy para un origen de café.")]
    public async Task<string> GetRoastNotes(
        [Description("Nombre del origen, p. ej. Ethiopia")] string origin) =>
        await http.GetStringAsync(
            $"https://api.auroracoffee.example/roast-notes/{Uri.EscapeDataString(origin)}");
}

Regístralo como cliente tipado y listo — el SDK inyecta el HttpClient en el constructor de la herramienta:

builder.Services.AddHttpClient<RoastTools>();

Dos cosas a subrayar. Primera, las herramientas pueden ser async y devolver Task<string> — sin ceremonia, solo await. Segunda, usa AddHttpClient<T> (o IHttpClientFactory) en vez de instanciar un HttpClient por llamada; la factory reutiliza conexiones para que no agotes sockets bajo carga. Aplica la higiene de siempre en .NET — MCP no cambia nada de eso.

Pasando al modo remoto: el transporte HTTP

stdio es genial cuando el cliente puede lanzar tu servidor en local. Pero si quieres un servidor compartido por un equipo, o corriendo en un contenedor, quieres HTTP. Cambia el paquete de transporte y dos líneas:

dotnet add package ModelContextProtocol.AspNetCore

using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<CoffeeShopData>();
builder.Services
    .AddMcpServer()
    .WithHttpTransport()
    .WithToolsFromAssembly();

var app = builder.Build();
app.MapMcp();
app.Run();

Los mismos CoffeeTools, los mismos atributos, el mismo descubrimiento — solo cambiaron el transporte y el host. Ahora los clientes se conectan por URL en vez de lanzar un proceso, y obtienes todo lo que ASP.NET Core ya te da: middleware de auth, HTTPS, hosting, escalado. Tus herramientas ni se enteraron.

Una nota si estás en el SDK 2.0 (publicado el 28 de julio de 2026, implementando la revisión de especificación 2026-07-28): el transporte HTTP es sin estado (stateless) por defecto — HttpServerTransportOptions.Stateless vale true por defecto, el handshake de initialize desapareció, y la cabecera Mcp-Session-Id se fue. Para herramientas de petición/respuesta simples como las de Aurora, no cambia nada y ganas un escalado más fácil detrás de un balanceador. Si tu servidor depende de sesiones o de peticiones iniciadas por el servidor (sampling, roots — ahora obsoletos), lee las notas de migración antes de actualizar.

Cuándo construir un servidor MCP — y cuándo no

Tira de MCP cuando las herramientas necesiten ser compartidas o reutilizadas: la misma capacidad en Claude Desktop y en Claude Code, un servidor al que apunte todo tu equipo, o herramientas que quieras desacopladas de cualquier app y libres de evolucionar a su propio ritmo de releases. La frontera de proceso es una ventaja — es lo que permite que un servidor sirva a muchos clientes, en cualquier lenguaje.

Sáltatelo cuando exactamente una app vaya a usar las herramientas y sea esa app la que hace las llamadas al modelo. Entonces el bucle de tool use dentro de la app del artículo anterior es más simple y rápido — sin transporte, sin segundo proceso. Un servidor cuyo único cliente es él mismo no es más que una llamada a función disfrazada de protocolo.

Regla general: tool use dentro de la app cuando una app es dueña del modelo y de las herramientas; un servidor MCP en el momento en que más de un cliente necesita las mismas herramientas.

Puntos Clave

MCP desacopla las herramientas de los clientes — escribe una herramienta una vez como servidor y cualquier cliente MCP (Claude Desktop, Claude Code, tu propio agente) puede usarla, en vez de reimplementarla en cada app.
El SDK va por atributos — [McpServerToolType] en la clase, [McpServerTool] en el método, y el JSON Schema se genera a partir de tu firma. Sin schema a mano, sin parseo manual de argumentos.
Las descripciones siguen teniendo peso — [Description] en el método y en cada parámetro es como Claude decide cuándo llamar a una herramienta y qué pasarle. Escríbelas como docstrings.
Cuida stdout — en modo stdio el protocolo es stdout. Manda los logs a stderr o corromperás el stream con tu propia salida de debug.
Mismas herramientas, cambia el transporte — stdio para herramientas locales por proceso hijo, HTTP (ModelContextProtocol.AspNetCore) para compartidas o remotas. El código de la herramienta no cambia.

Build an MCP Server in C#: Write Your Tools Once, Use Them in Every Claude

Juan Gómez — Fri, 31 Jul 2026 19:58:32 +0000

Build an MCP Server in C#: Write Your Tools Once, Use Them in Every Claude

Last time we built a Claude tool-use agent in C#. It worked — but every tool lived inside that one console app. If you wanted the same "look up an order" ability inside Claude Desktop, or Claude Code, or a teammate's agent, you'd copy-paste the tool and its plumbing into each one. Tools trapped in a single process, re-implemented everywhere. That's the coupling MCP exists to break.

The Model Context Protocol flips the ownership around. You write a tool once, as a standalone server, and expose it over a standard protocol. Then any MCP client — Claude Desktop, Claude Code, your own agent, whatever ships next quarter — connects and gets your tools for free. In this post we'll take the exact same Aurora Coffee Co. tools from last time and set them loose as a real MCP server in .NET, then plug it into Claude.

What MCP actually is

MCP is a small client/server protocol (JSON-RPC under the hood) for connecting AI clients to your capabilities. Three ideas are all you need to start:

Client and server are separate processes. The client is the AI app (Claude Desktop, Claude Code). The server is your code. They talk over a transport, not a shared function table.
Servers expose three things: tools (actions the model can call — our focus), resources (readable data, like files or rows), and prompts (reusable prompt templates). Today it's all tools.
Two transports. stdio — the client launches your server as a child process and talks over standard in/out; perfect for local tools. HTTP — your server runs somewhere and clients connect over the network; for shared or remote tools.

If you read the previous article, this is the same tool-use loop — declare a tool, the model calls it, your code runs it, you return a result — but the tool now lives on the other side of a process boundary, reusable by any client instead of hardwired into one app.

The server we're building

Remember Aurora Coffee Co.? Its two tools answered support questions over some in-memory data:

get_order_status(order_id) — looks up an order.
check_stock(sku) — checks inventory for a product.

Last time those tools were methods buried in an agent loop. Now they become an MCP server that any Claude can call. Start a console app and add two packages:

dotnet new console -o AuroraCoffee.Mcp
cd AuroraCoffee.Mcp
dotnet add package ModelContextProtocol
dotnet add package Microsoft.Extensions.Hosting

ModelContextProtocol is the official C# SDK (2.0, maintained with Microsoft). Microsoft.Extensions.Hosting gives us the generic host — the same DI and configuration story you'd use in any .NET service.

The data, as an injectable service

We'll hold Aurora's "database" in a singleton so tools can take it via constructor injection — exactly like a real repository:

public sealed class CoffeeShopData
{
    public Dictionary<string, Order> Orders { get; } = new()
    {
        ["A-1001"] = new("A-1001", "shipped", "2026-08-03"),
        ["A-1002"] = new("A-1002", "processing", "2026-08-06"),
    };

    public Dictionary<string, int> Stock { get; } = new()
    {
        ["ETH-250"] = 42,
        ["COL-1KG"] = 0,
    };
}

public sealed record Order(string Id, string Status, string Eta);

The tools

Here's the part that replaces last time's hand-written JSON Schema and switch statement. A class marked [McpServerToolType], methods marked [McpServerTool], and [Description] on both the method and its parameters. The SDK reads your method signature and generates the JSON Schema for you:

using System.ComponentModel;
using ModelContextProtocol.Server;

[McpServerToolType]
public sealed class CoffeeTools(CoffeeShopData data)
{
    [McpServerTool, Description("Look up the status and ETA of a customer order by its id.")]
    public string GetOrderStatus(
        [Description("Order id, e.g. A-1001")] string orderId) =>
        data.Orders.TryGetValue(orderId, out var order)
            ? $"Order {order.Id}: {order.Status}, ETA {order.Eta}."
            : "No order found with that id.";

    [McpServerTool, Description("Check how many units of a product SKU are currently in stock.")]
    public string CheckStock(
        [Description("Product SKU, e.g. ETH-250")] string sku) =>
        data.Stock.TryGetValue(sku, out var quantity)
            ? $"SKU {sku}: {quantity} units in stock."
            : "Unknown SKU.";
}

Those [Description] attributes are not decoration — they're the same load-bearing docstrings from the last article, just written in a nicer place. The method one tells Claude when to call the tool; the parameter ones tell it what to pass. Vague descriptions here are the number-one reason a model ignores a perfectly good tool.

Notice what's gone: no input_schema object, no required array, no manual argument parsing. orderId is a typed string parameter, so the SDK knows it's a required string and hands you the parsed value. The plumbing from Approach 1 last time is now the framework's job.

Wiring it together

The host builder registers the data, the MCP server, the stdio transport, and auto-discovers every [McpServerToolType] in the assembly:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = Host.CreateApplicationBuilder(args);

// stdout is the protocol channel — logs MUST go to stderr or you corrupt the stream.
builder.Logging.AddConsole(options =>
    options.LogToStandardErrorThreshold = LogLevel.Trace);

builder.Services.AddSingleton<CoffeeShopData>();
builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();

await builder.Build().RunAsync();

That's the whole server. Read that logging line again, because it's the single biggest footgun in stdio MCP: stdout carries the JSON-RPC messages. One stray Console.WriteLine to stdout and Claude sees line noise where it expected JSON — the protocol equivalent of talking with your mouth full. Route every log to stderr and you're fine.

Plugging it into Claude

A server nobody connects to is just a very lonely console app. Let's wire it into two clients.

Claude Desktop reads a JSON config file (claude_desktop_config.json, in %APPDATA%\Claude\ on Windows or ~/Library/Application Support/Claude/ on macOS). Add your server under mcpServers:

{
  "mcpServers": {
    "aurora-coffee": {
      "command": "dotnet",
      "args": ["run", "--project", "C:/src/AuroraCoffee.Mcp"]
    }
  }
}

The client runs that command, speaks stdio to the child process, and your tools show up. Restart Claude Desktop and ask "Is order A-1001 shipped, and do you still have ETH-250 in stock?" — it'll call both tools and answer for real.

Claude Code is even shorter — one CLI command, no file editing:

claude mcp add aurora-coffee -- dotnet run --project ./AuroraCoffee.Mcp

Same server, second client, zero code changes. That's the entire point of MCP: the tools didn't move, but now two different Claudes can reach them — and so can the third one you haven't installed yet.

Test it without a client

Before you touch any client config, sanity-check the server with the MCP Inspector, a browser UI that speaks the protocol so you can list and invoke tools by hand:

npx @modelcontextprotocol/inspector dotnet run --project ./AuroraCoffee.Mcp

It launches your server, lists get_order_status and check_stock, and lets you fire test calls. If a tool misbehaves, you find out here — not three layers deep inside a chat transcript.

Reaching the outside world: DI and HttpClient

In-memory dictionaries are fine for a demo, but real tools call real systems. Because the server is a normal .NET host, dependency injection works exactly as you'd expect — including typed HttpClients. Suppose Aurora has a roastery API for tasting notes:

using System.ComponentModel;
using ModelContextProtocol.Server;

[McpServerToolType]
public sealed class RoastTools(HttpClient http)
{
    [McpServerTool, Description("Fetch today's roast notes for a coffee origin.")]
    public async Task<string> GetRoastNotes(
        [Description("Origin name, e.g. Ethiopia")] string origin) =>
        await http.GetStringAsync(
            $"https://api.auroracoffee.example/roast-notes/{Uri.EscapeDataString(origin)}");
}

builder.Services.AddHttpClient<RoastTools>();

Two things worth calling out. First, tools can be async and return Task<string> — no ceremony, just await. Second, use AddHttpClient<T> (or IHttpClientFactory) rather than newing up an HttpClient per call; the factory pools connections so you don't exhaust sockets under load. Standard .NET hygiene applies — MCP doesn't change any of it.

Going remote: the HTTP transport

stdio is great when the client can launch your server locally. But if you want one server shared across a team, or running in a container, you want HTTP. Swap the transport package and two lines:

dotnet add package ModelContextProtocol.AspNetCore

using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<CoffeeShopData>();
builder.Services
    .AddMcpServer()
    .WithHttpTransport()
    .WithToolsFromAssembly();

var app = builder.Build();
app.MapMcp();
app.Run();

Same CoffeeTools, same attributes, same discovery — only the transport and host changed. Now clients connect by URL instead of launching a process, and you get everything ASP.NET Core already gives you: auth middleware, HTTPS, hosting, scaling. Your tools didn't even notice.

One note if you're on SDK 2.0 (shipped July 28, 2026, implementing the 2026-07-28 spec revision): the HTTP transport is stateless by default — HttpServerTransportOptions.Stateless defaults to true, the initialize handshake is gone, and the Mcp-Session-Id header went away. For plain request/response tools like Aurora's, nothing changes and you get easier scaling behind a load balancer. If your server leans on sessions or server-initiated requests (sampling, roots — now deprecated), read the migration notes before upgrading.

When to build an MCP server — and when not to

Reach for MCP when tools need to be shared or reused: the same capability across Claude Desktop and Claude Code, a server your whole team points at, or tools you want decoupled from any single app and free to evolve on their own release cadence. The process boundary is a feature — it's what lets one server serve many clients, in any language.

Skip it when exactly one app will ever use the tools and it's the app doing the model calls. Then the in-app tool-use loop from the previous article is simpler and faster — no transport, no second process. A server whose only client is itself is just a function call wearing a lanyard.

Rule of thumb: in-app tool use when one app owns the model and the tools; an MCP server the moment more than one client needs the same tools.

Key Takeaways

MCP decouples tools from clients — write a tool once as a server and every MCP client (Claude Desktop, Claude Code, your own agent) can use it, instead of re-implementing it in each app.
The SDK is attribute-driven — [McpServerToolType] on the class, [McpServerTool] on the method, and the JSON Schema is generated from your signature. No hand-written schema, no manual argument parsing.
Descriptions are still load-bearing — [Description] on the method and each parameter is how Claude decides when to call a tool and what to pass. Write them like docstrings.
Guard stdout — in stdio mode the protocol is stdout. Send logs to stderr or you'll corrupt the stream with your own debug output.
Same tools, swap the transport — stdio for local child-process tools, HTTP (ModelContextProtocol.AspNetCore) for shared or remote ones. The tool code doesn't change.

Build a Claude Tool-Use Agent in C#: Not a Chatbot on Steroids

Juan Gómez — Fri, 24 Jul 2026 20:09:23 +0000

Build a Claude Tool-Use Agent in C#: Not a Chatbot on Steroids

Everyone ships "AI agents" now. Peek under the hood of most of them and you'll find a chatbot with a personality prompt and a hopeful // TODO: make it do things. It can talk about your orders. It cannot actually look one up.

A real agent closes that gap. You hand the model a set of tools — plain methods in your codebase — and it decides, mid-conversation, to call one. Your code runs the real work, hands back the result, and the model keeps going until it can answer for real. That loop is the whole trick, and you can build it in C# in about sixty lines. We'll do it twice: once by hand with HttpClient so you can see the wire protocol, and once with the official Anthropic .NET SDK for the short version you'd actually ship.

What "tool use" actually is

Tool use (a.k.a. function calling) is a small, strict loop:

You declare tools. Each is a name, a description, and a JSON Schema for its inputs. That's it — no code is sent to Claude, just the shape.
Claude replies with a tool_use block instead of text. It's saying "please run check_stock with { "sku": "ETH-250" } and tell me what you get."
Your code runs it. This is the part people miss: Claude never executes anything. It requests; your harness executes. The security boundary stays on your side of the fence.
You send the answer back as a tool_result block, tied to the request by id.
Claude continues — maybe calling more tools, maybe answering. You loop until it stops asking.

Think of Claude as a very fast senior colleague who can read your API but isn't allowed to touch production: it tells you exactly which button to press, you press it, you report back. The judgment is the model's; the hands are yours.

The agent we're building

Meet Aurora Coffee Co., a fictional shop with a support agent that answers questions like "Is my order shipped, and do you still have the Ethiopia beans?" It has two tools over some in-memory data, so the whole thing runs with zero external setup:

get_order_status(order_id) — looks up an order.
check_stock(sku) — checks inventory for a product.

Here's the shared part — the data and the tool executor. Both approaches below reuse this exact method; only the Claude plumbing changes.

using System.Text.Json;

// Aurora Coffee Co.'s "database" — in memory, so this runs with zero setup.
var orders = new Dictionary<string, Order>
{
    ["A-1001"] = new("A-1001", "shipped", "2026-07-26"),
    ["A-1002"] = new("A-1002", "processing", "2026-07-29"),
};
var stock = new Dictionary<string, int> { ["ETH-250"] = 42, ["COL-1KG"] = 0 };

// Your tools are ordinary C#. Claude never runs this — it only asks you to.
string RunTool(string name, IReadOnlyDictionary<string, JsonElement> args) => name switch
{
    "get_order_status" =>
        orders.TryGetValue(args["order_id"].GetString()!, out var o)
            ? $"Order {o.Id}: {o.Status}, ETA {o.Eta}."
            : "No order found with that id.",
    "check_stock" =>
        stock.TryGetValue(args["sku"].GetString()!, out var qty)
            ? $"SKU {args["sku"].GetString()}: {qty} units in stock."
            : "Unknown SKU.",
    _ => $"Unknown tool: {name}",
};

sealed record Order(string Id, string Status, string Eta);

Notice RunTool takes the tool inputs as a dictionary of JsonElement. We parse them — we never string-match the raw JSON Claude sends. That matters, and we'll come back to it.

Approach 1 — Raw HttpClient (see the protocol)

No SDK, no dependencies — just HttpClient and System.Net.Http.Json. This is the version that teaches you what's really going on the wire.

First, describe the tools as JSON Schema. This is the exact array that ships in the request:

var tools = new object[]
{
    new
    {
        name = "get_order_status",
        description = "Look up the status and ETA of a customer order by its id.",
        input_schema = new
        {
            type = "object",
            properties = new
            {
                order_id = new { type = "string", description = "Order id, e.g. A-1001" },
            },
            required = new[] { "order_id" },
        },
    },
    new
    {
        name = "check_stock",
        description = "Check how many units of a product SKU are currently in stock.",
        input_schema = new
        {
            type = "object",
            properties = new
            {
                sku = new { type = "string", description = "Product SKU, e.g. ETH-250" },
            },
            required = new[] { "sku" },
        },
    },
};

The description fields are load-bearing — they're how Claude decides when to reach for each tool. Write them like you'd write a docstring for a junior dev, not like a variable name.

Now the client and the agent loop. We keep a growing list of messages and keep calling until Claude stops asking for tools:

using System.Net.Http.Json;

var http = new HttpClient { BaseAddress = new Uri("https://api.anthropic.com") };
http.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY"));
http.DefaultRequestHeaders.Add("anthropic-version", "2023-06-01");

var json = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// The conversation grows as we go. Start with the user's question.
var messages = new List<object>
{
    new { role = "user", content = "Is order A-1001 shipped, and do you still have ETH-250 in stock?" },
};

while (true)
{
    var request = new { model = "claude-opus-4-8", max_tokens = 1024, tools, messages };

    var response = await http.PostAsJsonAsync("/v1/messages", request, json);
    response.EnsureSuccessStatusCode();
    var reply = await response.Content.ReadFromJsonAsync<JsonElement>();

    var stopReason = reply.GetProperty("stop_reason").GetString();
    var content = reply.GetProperty("content");

    // Echo Claude's whole turn back — tool_use blocks included — or the next
    // request won't line up with the tool_result we're about to send.
    messages.Add(new { role = "assistant", content });

    if (stopReason != "tool_use")
    {
        foreach (var block in content.EnumerateArray())
            if (block.GetProperty("type").GetString() == "text")
                Console.WriteLine(block.GetProperty("text").GetString());
        break;
    }

    // Claude asked for one or more tools. Run them all; collect every result.
    var results = new List<object>();
    foreach (var block in content.EnumerateArray())
    {
        if (block.GetProperty("type").GetString() != "tool_use") continue;

        var name = block.GetProperty("name").GetString()!;
        var toolInput = block.GetProperty("input").Deserialize<Dictionary<string, JsonElement>>(json)!;

        results.Add(new
        {
            type = "tool_result",
            tool_use_id = block.GetProperty("id").GetString(),
            content = RunTool(name, toolInput),
        });
    }

    // All the tool_results go back in ONE user message.
    messages.Add(new { role = "user", content = results });
}

Three details that will bite you if you skip them:

Echo the assistant turn back verbatim, tool_use blocks and all. The follow-up request must contain the original tool_use for every tool_result, matched by tool_use_id.
Return every result in a single user message. If Claude asks for two tools and you split the answers across two messages, it quietly learns to stop asking for tools in parallel.
Name your loop variable something other than args. Top-level statements already define an implicit args, and the compiler will not be shy about it. Ask me how I know.

That's a complete agent in one file — and you can see every byte that crosses the wire. Hand-rolling the JSON gets old fast, though, which is exactly why the SDK exists.

Approach 2 — The Anthropic .NET SDK (the short version)

Same agent, far less plumbing. Add the package:

dotnet add package Anthropic

Tool definitions become typed objects. InputSchema.Type is set to "object" for you — don't set it yourself:

using Anthropic;
using Anthropic.Models.Messages;
using System.Text.Json;

AnthropicClient client = new(); // reads ANTHROPIC_API_KEY

List<ToolUnion> tools =
[
    new Tool
    {
        Name = "get_order_status",
        Description = "Look up the status and ETA of a customer order by its id.",
        InputSchema = new()
        {
            Properties = new Dictionary<string, JsonElement>
            {
                ["order_id"] = JsonSerializer.SerializeToElement(
                    new { type = "string", description = "Order id, e.g. A-1001" }),
            },
            Required = ["order_id"],
        },
    },
    new Tool
    {
        Name = "check_stock",
        Description = "Check how many units of a product SKU are currently in stock.",
        InputSchema = new()
        {
            Properties = new Dictionary<string, JsonElement>
            {
                ["sku"] = JsonSerializer.SerializeToElement(
                    new { type = "string", description = "Product SKU, e.g. ETH-250" }),
            },
            Required = ["sku"],
        },
    },
];

The loop is the same idea, now with typed blocks. One quirk worth knowing: the SDK gives you response blocks (TextBlock, ToolUseBlock) but the request wants param blocks (TextBlockParam, ToolUseBlockParam), and there's no .ToParam() shortcut — you rebuild them. It's a few lines, and it keeps the type system honest:

List<MessageParam> messages =
[
    new() { Role = Role.User, Content = "Is order A-1001 shipped, and do you still have ETH-250 in stock?" },
];

while (true)
{
    var response = await client.Messages.Create(new MessageCreateParams
    {
        Model = Model.ClaudeOpus4_8,
        MaxTokens = 1024,
        Tools = tools,
        Messages = messages,
    });

    List<ContentBlockParam> assistant = [];
    List<ContentBlockParam> results = [];

    foreach (var block in response.Content)
    {
        if (block.TryPickText(out TextBlock? text))
        {
            assistant.Add(new TextBlockParam { Text = text.Text });
        }
        else if (block.TryPickToolUse(out ToolUseBlock? call))
        {
            assistant.Add(new ToolUseBlockParam { ID = call.ID, Name = call.Name, Input = call.Input });
            results.Add(new ToolResultBlockParam { ToolUseID = call.ID, Content = RunTool(call.Name, call.Input) });
        }
    }

    messages.Add(new() { Role = Role.Assistant, Content = assistant });

    if (response.StopReason != "tool_use")
    {
        foreach (var t in response.Content.Select(b => b.Value).OfType<TextBlock>())
            Console.WriteLine(t.Text);
        break;
    }

    messages.Add(new() { Role = Role.User, Content = results });
}

Notice RunTool didn't change at all — ToolUseBlock.Input is already an IReadOnlyDictionary<string, JsonElement>, so our executor drops right in.

Let the SDK drive the loop

If you don't want to write the loop yourself, the SDK ships a beta tool runner. You give each tool its schema and the code that runs it (a Run callback), and the runner handles the whole call-execute-continue cycle for you:

using Anthropic;
using Anthropic.Helpers.Beta;
using Anthropic.Models.Beta.Messages;
using System.Text.Json;

// Bundle each tool's schema with the code that answers it.
BetaRunnableTool MakeTool(string name, string description, string prop, string hint) => new()
{
    Name = name,
    Definition = new BetaTool
    {
        Name = name,
        Description = description,
        InputSchema = new()
        {
            Properties = new Dictionary<string, JsonElement>
            {
                [prop] = JsonSerializer.SerializeToElement(new { type = "string", description = hint }),
            },
            Required = [prop],
        },
    },
    Run = (call, ct) => Task.FromResult<BetaToolResultBlockParamContent>(RunTool(call.Name, call.Input)),
};

List<IBetaRunnableTool> runnable =
[
    MakeTool("get_order_status", "Look up the status and ETA of an order by id.", "order_id", "e.g. A-1001"),
    MakeTool("check_stock", "Check units in stock for a product SKU.", "sku", "e.g. ETH-250"),
];

var runner = client.Beta.Messages.ToolRunner(
    new MessageCreateParams
    {
        Model = "claude-opus-4-8",
        MaxTokens = 1024,
        Messages = [new() { Role = Role.User, Content = "Is A-1001 shipped, and is ETH-250 in stock?" }],
    },
    runnable);

await foreach (BetaMessage message in runner)
    foreach (var block in message.Content)
        if (block.TryPickText(out var text))
            Console.WriteLine(text.Text);

No manual loop, no block reconstruction — the runner calls your Run callbacks and keeps the conversation going until Claude is done. Whichever version you run, the output is the same:

> Is order A-1001 shipped, and do you still have ETH-250 in stock?
Order A-1001 has shipped and is on track to arrive 2026-07-26. And yes — the
Ethiopia beans (ETH-250) are in stock, with 42 units available.

Two tools, one question, and Claude figured out on its own that it needed to call both.

When to use tool use — and when not to

Tool use is the right call when the model needs something it can't have from text alone: live or private data (your database, an internal API, the filesystem) or the ability to take an action (send an email, create a ticket, refund an order). If the answer is genuinely locked inside your systems, tool use is how the model gets to it.

It's the wrong call when a single prompt would do. If you just need JSON out of a blob of text, reach for structured outputs, not a tool loop — you'll skip the extra round trips. Not every problem is an agent; some are just a well-shaped prompt.

Between the two implementations: go raw HttpClient when you're learning the protocol, want zero dependencies, or need total control over the loop — approval gates before a tool fires, custom logging, human-in-the-loop review. Go SDK for everything you'd actually ship: typed models, less boilerplate, and the tool runner when you just want the loop handled. And if cost matters more than raw capability, swap claude-opus-4-8 for claude-sonnet-5 — same code, cheaper runs.

Rule of thumb: prompt first, tool use when the model needs to reach into your world, an agent loop only when it needs to reach in more than once.

Key Takeaways

The loop is the whole trick, not magic — declare tools, Claude requests one, you run it, you return the result, repeat until it answers. Everything else is plumbing.
You own execution, and that's the point — Claude only asks to run a tool; your code decides whether and how. The security boundary never leaves your side.
Parse tool inputs, never string-match them — read the JSON into typed values (JsonElement / a dictionary). Matching against the raw serialized string is a bug waiting for a Unicode escape.
Native teaches the protocol, the SDK ships it — HttpClient shows every byte and gives you full control; the Anthropic SDK gives you typed blocks and a tool runner that drives the loop.
Start simple — a plain prompt beats an agent for most tasks. Add tool use when the model needs live data or has to do something, and an agent loop only when one tool call isn't enough.

Crea un agente con Tool Use de Claude en C#: no es un chatbot con esteroides

Juan Gómez — Fri, 24 Jul 2026 20:09:21 +0000

Crea un agente con Tool Use de Claude en C#: no es un chatbot con esteroides

Hoy todo el mundo lanza "agentes de IA". Levanta el capó de la mayoría y encontrarás un chatbot con un prompt de personalidad y un esperanzado // TODO: que haga algo. Puede hablar de tus pedidos. Lo que no puede es consultar uno de verdad.

Un agente real cierra esa brecha. Le das al modelo un conjunto de herramientas —métodos normales de tu código— y él decide, a mitad de la conversación, llamar a una. Tu código ejecuta el trabajo real, le devuelve el resultado, y el modelo sigue hasta que puede responder de verdad. Ese bucle es todo el truco, y lo puedes montar en C# en unas sesenta líneas. Lo haremos dos veces: primero a mano con HttpClient para que veas el protocolo tal cual viaja, y luego con el SDK oficial de Anthropic para .NET, que es la versión corta que de verdad pondrías en producción.

Qué es realmente "tool use"

Tool use (o function calling) es un bucle pequeño y estricto:

Declaras herramientas. Cada una es un name, una description y un JSON Schema para sus parámetros. Nada más — no le envías código a Claude, solo la forma.
Claude responde con un bloque tool_use en lugar de texto. Te está diciendo: "por favor ejecuta check_stock con { "sku": "ETH-250" } y dime qué obtienes".
Tu código lo ejecuta. Aquí está la parte que se le escapa a mucha gente: Claude nunca ejecuta nada. Él pide; tu harness ejecuta. La frontera de seguridad se queda de tu lado de la valla.
Le devuelves la respuesta como un bloque tool_result, atado a la petición por su id.
Claude continúa — quizá llamando a más herramientas, quizá respondiendo. Repites el bucle hasta que deja de pedir.

Piensa en Claude como un colega senior muy rápido que puede leer tu API pero no tiene permiso para tocar producción: te dice exactamente qué botón pulsar, tú lo pulsas y le reportas. El criterio es del modelo; las manos son tuyas.

El agente que vamos a construir

Te presento a Aurora Coffee Co., una tienda ficticia con un agente de soporte que responde preguntas como "¿Ya salió mi pedido y todavía tienen los granos de Etiopía?". Tiene dos herramientas sobre datos en memoria, así que todo corre sin ninguna configuración externa:

get_order_status(order_id) — consulta un pedido.
check_stock(sku) — revisa el inventario de un producto.

Esta es la parte compartida: los datos y el ejecutor de herramientas. Los dos enfoques de abajo reutilizan este mismo método; lo único que cambia es la fontanería de Claude.

using System.Text.Json;

// La "base de datos" de Aurora Coffee Co. — en memoria, para que corra sin setup.
var orders = new Dictionary<string, Order>
{
    ["A-1001"] = new("A-1001", "shipped", "2026-07-26"),
    ["A-1002"] = new("A-1002", "processing", "2026-07-29"),
};
var stock = new Dictionary<string, int> { ["ETH-250"] = 42, ["COL-1KG"] = 0 };

// Tus herramientas son C# normal. Claude nunca ejecuta esto — solo te pide que lo hagas.
string RunTool(string name, IReadOnlyDictionary<string, JsonElement> args) => name switch
{
    "get_order_status" =>
        orders.TryGetValue(args["order_id"].GetString()!, out var o)
            ? $"Pedido {o.Id}: {o.Status}, ETA {o.Eta}."
            : "No hay ningún pedido con ese id.",
    "check_stock" =>
        stock.TryGetValue(args["sku"].GetString()!, out var qty)
            ? $"SKU {args["sku"].GetString()}: {qty} unidades en stock."
            : "SKU desconocido.",
    _ => $"Herramienta desconocida: {name}",
};

sealed record Order(string Id, string Status, string Eta);

Fíjate en que RunTool recibe los parámetros como un diccionario de JsonElement. Los parseamos — nunca comparamos como texto el JSON crudo que manda Claude. Eso importa, y volveremos a ello.

Enfoque 1 — HttpClient a pelo (ver el protocolo)

Sin SDK, sin dependencias — solo HttpClient y System.Net.Http.Json. Esta es la versión que te enseña qué está pasando de verdad en el cable.

Primero, describe las herramientas como JSON Schema. Este es el array exacto que viaja en la petición:

var tools = new object[]
{
    new
    {
        name = "get_order_status",
        description = "Consulta el estado y la ETA de un pedido por su id.",
        input_schema = new
        {
            type = "object",
            properties = new
            {
                order_id = new { type = "string", description = "Id del pedido, p. ej. A-1001" },
            },
            required = new[] { "order_id" },
        },
    },
    new
    {
        name = "check_stock",
        description = "Consulta cuántas unidades de un SKU hay en stock ahora mismo.",
        input_schema = new
        {
            type = "object",
            properties = new
            {
                sku = new { type = "string", description = "SKU del producto, p. ej. ETH-250" },
            },
            required = new[] { "sku" },
        },
    },
};

Los campos description cargan con todo el peso — son la forma en que Claude decide cuándo echar mano de cada herramienta. Escríbelos como escribirías un docstring para alguien junior, no como el nombre de una variable.

Ahora el cliente y el bucle del agente. Mantenemos una lista de mensajes que va creciendo y seguimos llamando hasta que Claude deja de pedir herramientas:

using System.Net.Http.Json;

var http = new HttpClient { BaseAddress = new Uri("https://api.anthropic.com") };
http.DefaultRequestHeaders.Add("x-api-key", Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY"));
http.DefaultRequestHeaders.Add("anthropic-version", "2023-06-01");

var json = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// La conversación crece a medida que avanzamos. Empezamos con la pregunta del usuario.
var messages = new List<object>
{
    new { role = "user", content = "¿El pedido A-1001 ya salió, y todavía tienen ETH-250 en stock?" },
};

while (true)
{
    var request = new { model = "claude-opus-4-8", max_tokens = 1024, tools, messages };

    var response = await http.PostAsJsonAsync("/v1/messages", request, json);
    response.EnsureSuccessStatusCode();
    var reply = await response.Content.ReadFromJsonAsync<JsonElement>();

    var stopReason = reply.GetProperty("stop_reason").GetString();
    var content = reply.GetProperty("content");

    // Devuelve el turno completo de Claude — con sus bloques tool_use incluidos — o la
    // siguiente petición no cuadrará con el tool_result que estamos a punto de enviar.
    messages.Add(new { role = "assistant", content });

    if (stopReason != "tool_use")
    {
        foreach (var block in content.EnumerateArray())
            if (block.GetProperty("type").GetString() == "text")
                Console.WriteLine(block.GetProperty("text").GetString());
        break;
    }

    // Claude pidió una o más herramientas. Ejecútalas todas; recoge cada resultado.
    var results = new List<object>();
    foreach (var block in content.EnumerateArray())
    {
        if (block.GetProperty("type").GetString() != "tool_use") continue;

        var name = block.GetProperty("name").GetString()!;
        var toolInput = block.GetProperty("input").Deserialize<Dictionary<string, JsonElement>>(json)!;

        results.Add(new
        {
            type = "tool_result",
            tool_use_id = block.GetProperty("id").GetString(),
            content = RunTool(name, toolInput),
        });
    }

    // Todos los tool_results vuelven en UN SOLO mensaje de usuario.
    messages.Add(new { role = "user", content = results });
}

Tres detalles que te van a morder si los saltas:

Devuelve el turno del asistente tal cual, con bloques tool_use y todo. La petición de continuación debe contener el tool_use original para cada tool_result, emparejados por tool_use_id.
Devuelve todos los resultados en un único mensaje de usuario. Si Claude pide dos herramientas y repartes las respuestas en dos mensajes, aprende calladito a dejar de pedir herramientas en paralelo.
No llames args a tu variable del bucle. Los top-level statements ya definen un args implícito, y el compilador no se va a andar con timideces. No preguntes cómo lo sé.

Eso es un agente completo en un solo archivo — y puedes ver cada byte que cruza el cable. Escribir el JSON a mano cansa rápido, claro, que es justo para lo que existe el SDK.

Enfoque 2 — El SDK de Anthropic para .NET (la versión corta)

El mismo agente, con muchísima menos fontanería. Añade el paquete:

dotnet add package Anthropic

Las definiciones de herramientas pasan a ser objetos tipados. InputSchema.Type se pone en "object" por ti — no lo asignes a mano:

using Anthropic;
using Anthropic.Models.Messages;
using System.Text.Json;

AnthropicClient client = new(); // lee ANTHROPIC_API_KEY

List<ToolUnion> tools =
[
    new Tool
    {
        Name = "get_order_status",
        Description = "Consulta el estado y la ETA de un pedido por su id.",
        InputSchema = new()
        {
            Properties = new Dictionary<string, JsonElement>
            {
                ["order_id"] = JsonSerializer.SerializeToElement(
                    new { type = "string", description = "Id del pedido, p. ej. A-1001" }),
            },
            Required = ["order_id"],
        },
    },
    new Tool
    {
        Name = "check_stock",
        Description = "Consulta cuántas unidades de un SKU hay en stock ahora mismo.",
        InputSchema = new()
        {
            Properties = new Dictionary<string, JsonElement>
            {
                ["sku"] = JsonSerializer.SerializeToElement(
                    new { type = "string", description = "SKU del producto, p. ej. ETH-250" }),
            },
            Required = ["sku"],
        },
    },
];

El bucle es la misma idea, ahora con bloques tipados. Un detalle que conviene saber: el SDK te da bloques de respuesta (TextBlock, ToolUseBlock) pero la petición quiere bloques de parámetro (TextBlockParam, ToolUseBlockParam), y no hay atajo .ToParam() — los reconstruyes. Son unas pocas líneas, y mantienen honesto al sistema de tipos:

List<MessageParam> messages =
[
    new() { Role = Role.User, Content = "¿El pedido A-1001 ya salió, y todavía tienen ETH-250 en stock?" },
];

while (true)
{
    var response = await client.Messages.Create(new MessageCreateParams
    {
        Model = Model.ClaudeOpus4_8,
        MaxTokens = 1024,
        Tools = tools,
        Messages = messages,
    });

    List<ContentBlockParam> assistant = [];
    List<ContentBlockParam> results = [];

    foreach (var block in response.Content)
    {
        if (block.TryPickText(out TextBlock? text))
        {
            assistant.Add(new TextBlockParam { Text = text.Text });
        }
        else if (block.TryPickToolUse(out ToolUseBlock? call))
        {
            assistant.Add(new ToolUseBlockParam { ID = call.ID, Name = call.Name, Input = call.Input });
            results.Add(new ToolResultBlockParam { ToolUseID = call.ID, Content = RunTool(call.Name, call.Input) });
        }
    }

    messages.Add(new() { Role = Role.Assistant, Content = assistant });

    if (response.StopReason != "tool_use")
    {
        foreach (var t in response.Content.Select(b => b.Value).OfType<TextBlock>())
            Console.WriteLine(t.Text);
        break;
    }

    messages.Add(new() { Role = Role.User, Content = results });
}

Fíjate en que RunTool no cambió en absoluto — ToolUseBlock.Input ya es un IReadOnlyDictionary<string, JsonElement>, así que nuestro ejecutor encaja tal cual.

Deja que el SDK maneje el bucle

Si no quieres escribir el bucle tú, el SDK trae un tool runner (en beta). A cada herramienta le das su esquema y el código que la ejecuta (un callback Run), y el runner se encarga de todo el ciclo llamar-ejecutar-continuar:

using Anthropic;
using Anthropic.Helpers.Beta;
using Anthropic.Models.Beta.Messages;
using System.Text.Json;

// Empaqueta el esquema de cada herramienta junto con el código que la responde.
BetaRunnableTool MakeTool(string name, string description, string prop, string hint) => new()
{
    Name = name,
    Definition = new BetaTool
    {
        Name = name,
        Description = description,
        InputSchema = new()
        {
            Properties = new Dictionary<string, JsonElement>
            {
                [prop] = JsonSerializer.SerializeToElement(new { type = "string", description = hint }),
            },
            Required = [prop],
        },
    },
    Run = (call, ct) => Task.FromResult<BetaToolResultBlockParamContent>(RunTool(call.Name, call.Input)),
};

List<IBetaRunnableTool> runnable =
[
    MakeTool("get_order_status", "Consulta el estado y la ETA de un pedido por id.", "order_id", "p. ej. A-1001"),
    MakeTool("check_stock", "Consulta las unidades en stock de un SKU.", "sku", "p. ej. ETH-250"),
];

var runner = client.Beta.Messages.ToolRunner(
    new MessageCreateParams
    {
        Model = "claude-opus-4-8",
        MaxTokens = 1024,
        Messages = [new() { Role = Role.User, Content = "¿A-1001 ya salió, y ETH-250 está en stock?" }],
    },
    runnable);

await foreach (BetaMessage message in runner)
    foreach (var block in message.Content)
        if (block.TryPickText(out var text))
            Console.WriteLine(text.Text);

Sin bucle manual, sin reconstruir bloques — el runner llama a tus callbacks Run y mantiene la conversación viva hasta que Claude termina. Corras la versión que corras, la salida es la misma:

> ¿El pedido A-1001 ya salió, y todavía tienen ETH-250 en stock?
El pedido A-1001 ya salió y está previsto que llegue el 2026-07-26. Y sí — los
granos de Etiopía (ETH-250) están en stock, con 42 unidades disponibles.

Dos herramientas, una pregunta, y Claude dedujo por su cuenta que necesitaba llamar a ambas.

Cuándo usar tool use — y cuándo no

Tool use es la opción correcta cuando el modelo necesita algo que no puede sacar solo del texto: datos en vivo o privados (tu base de datos, una API interna, el sistema de archivos) o la capacidad de realizar una acción (mandar un correo, crear un ticket, reembolsar un pedido). Si la respuesta está de verdad encerrada dentro de tus sistemas, tool use es cómo el modelo llega a ella.

Es la opción equivocada cuando bastaría con un solo prompt. Si solo necesitas JSON a partir de un texto, tira de structured outputs, no de un bucle de herramientas — te ahorras los viajes de ida y vuelta. No todo problema es un agente; algunos son solo un prompt bien formado.

Entre las dos implementaciones: ve con HttpClient a pelo cuando estés aprendiendo el protocolo, quieras cero dependencias o necesites control total del bucle — puertas de aprobación antes de que dispare una herramienta, logging a medida, revisión con humano en el circuito. Ve con el SDK para todo lo que de verdad pondrías en producción: modelos tipados, menos boilerplate y el tool runner cuando solo quieres que se ocupe del bucle. Y si te pesa más el coste que la capacidad bruta, cambia claude-opus-4-8 por claude-sonnet-5 — mismo código, ejecuciones más baratas.

Regla de oro: primero el prompt, tool use cuando el modelo necesite meter la mano en tu mundo, y un bucle de agente solo cuando necesite meterla más de una vez.

Ideas clave

El bucle es todo el truco, no hay magia — declaras herramientas, Claude pide una, tú la ejecutas, devuelves el resultado, repites hasta que responde. Todo lo demás es fontanería.
La ejecución es tuya, y ese es el punto — Claude solo pide ejecutar una herramienta; tu código decide si lo hace y cómo. La frontera de seguridad nunca sale de tu lado.
Parsea los parámetros, no los compares como texto — lee el JSON a valores tipados (JsonElement / un diccionario). Comparar contra la cadena serializada cruda es un bug esperando a un escape Unicode.
El nativo enseña el protocolo, el SDK lo pone en producción — HttpClient muestra cada byte y te da control total; el SDK de Anthropic te da bloques tipados y un tool runner que maneja el bucle.
Empieza simple — un prompt normal le gana a un agente en la mayoría de tareas. Añade tool use cuando el modelo necesite datos en vivo o tenga que hacer algo, y un bucle de agente solo cuando una llamada no baste.

Stop Squinting at .NET Stack Traces: Debug Them With Claude Inside Visual Studio

Juan Gómez — Fri, 17 Jul 2026 13:35:22 +0000

Stop Squinting at .NET Stack Traces: Debug Them With Claude Inside Visual Studio

An unhandled exception fires, and Visual Studio drops forty lines of stack trace into your lap. Thirty-eight of them live in Microsoft.EntityFrameworkCore.* or System.Private.CoreLib, one is an async state-machine frame with a name like <<Main>$>b__0_0, and exactly one points at code you wrote. Your job is to find that one line, understand why it blew up, and fix the actual cause — not the symptom.

We've all pasted a trace into a search engine and gotten back a single Stack Overflow question from 2015, zero answers, one comment that just says "did you ever solve this?". There's a better way, and it now lives right inside Visual Studio: hand the trace to Claude, get back a ranked diagnosis tied to your line, and a fix you can actually reason about.

Why .NET Stack Traces Are Hard to Read

Stack traces aren't hard because they're long. They're hard because modern .NET code rarely runs in a straight line, and the trace reflects the machinery, not your intent.

Async unwinding. await compiles into a state machine. When an exception crosses an await, the frames you see are MoveNext() calls and ExecutionContext.Run, not the tidy call chain you wrote. The method name shows up as <SomethingAsync>d__4, and the line that logically threw might be three awaits up.
Inner exceptions. The message on top is often the least useful one. The real cause is nested — a DbUpdateException wrapping a SqliteException, or a TargetInvocationException wrapping the thing you actually care about. If you only read the first line, you're debugging the wrapper.
AggregateException. Anything involving Task.WhenAll or parallelism can bundle several failures into one. The outer message says "One or more errors occurred" — thanks, very helpful.
Inlined and framework frames. The JIT inlines small methods, so frames disappear. And the frames that remain are mostly library internals you can't change and don't need to read.

An LLM is genuinely good at this specific chore. It has seen these exception shapes thousands of times, it can tell the framework noise from the signal, and — this is the part that matters — when it runs inside your IDE, it can correlate the trace with the actual source file and line.

Two Ways to Put Claude Inside Visual Studio

You don't need to leave the IDE or paste anything into a browser. There are two solid paths, and they suit different moments.

1. Copilot Chat with a Claude model (in-IDE, conversational)

Visual Studio 2022 (17.14+) ships GitHub Copilot with a model picker. Click the Copilot badge, open the model dropdown in the chat prompt box, and pick a Claude model — Sonnet for fast everyday diagnosis, Opus when the bug is genuinely nasty. From then on, every Copilot Chat reply is generated by Claude.

Two things make this path shine for debugging:

When an unhandled exception pops the Exception Helper while debugging, there's an inline Ask Copilot link right on that dialog. With Claude selected as your model, that one-click analysis runs on Claude.
In the chat box you can pull real context in with # references — #Program.cs, #solution, or a highlighted selection — so Claude reads your actual code, not a paraphrase.

If you'd rather bring your own Anthropic key instead of using Copilot's models, the same picker has Manage Models → add Anthropic → paste your API key. Handy if you're already paying for API access.

2. Claude Code in the integrated terminal (agentic)

There's no official Claude Code extension for the full Visual Studio yet, but you don't need one — Claude Code runs in any terminal, including View → Terminal (Ctrl + backtick) inside VS. Run claude, paste the trace, and because Claude Code can read the whole repository, it will open the offending file itself, trace the call path, and propose the fix as a diff you approve or reject.

The trade-off is simple: Copilot Chat is faster for a quick "what does this mean?", while Claude Code is better when the fix touches several files or you want it to reproduce and verify. Use whichever the bug deserves.

A Real Example: The EF Core Trace That Blames the Wrong Thing

Let's debug something concrete. Here's a .NET 10 minimal API endpoint that returns an order summary. It looks reasonable, and it compiles cleanly:

// Program.cs — .NET 10 minimal API
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<ShopContext>(o => o.UseSqlite("Data Source=shop.db"));

var app = builder.Build();

app.MapGet("/orders/{customerId:int}/summary", async (int customerId, ShopContext db) =>
{
    // Fire both queries "in parallel" to be fast — right?
    var ordersTask = db.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
    var totalTask  = db.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);

    await Task.WhenAll(ordersTask, totalTask);

    return Results.Ok(new { Orders = ordersTask.Result, Total = totalTask.Result });
});

app.Run();

Hit the endpoint and it throws. Here's the trace Visual Studio shows (trimmed to the frames that appear):

System.InvalidOperationException: A second operation was started on this context
instance before a previous operation completed. This is usually caused by different
threads concurrently using the same instance of DbContext. For more information on
how to avoid threading issues with DbContext, see https://go.microsoft.com/fwlink/?linkid=2097913.
   at Microsoft.EntityFrameworkCore.Internal.ConcurrencyDetector.EnterCriticalSection()
   at Microsoft.EntityFrameworkCore.Query.Internal.QueryCompiler.ExecuteAsync[TResult](Expression query, CancellationToken ct)
   at Microsoft.EntityFrameworkCore.Query.Internal.EntityQueryProvider.ExecuteAsync[TResult](Expression expression, CancellationToken ct)
   at Microsoft.EntityFrameworkCore.EntityFrameworkQueryableExtensions.ToListAsync[TSource](IQueryable`1 source, CancellationToken ct)
   at Program.<>c.<<Main>$>b__0_0(Int32 customerId, ShopContext db) in C:\src\Shop.Api\Program.cs:line 12

Four of those five frames are EF Core internals. The one that's yours — Program.cs:line 12 — is the ToListAsync() call, which makes it look like ToListAsync is the villain. It isn't.

Feeding it to Claude the right way

The quality of the answer depends entirely on what you paste. A one-line message gets you a one-line guess. Give Claude the whole picture:

.NET 10, EF Core 10, SQLite. This endpoint throws on every request under normal load
(not just concurrency). Full exception and the endpoint code below — what's the root
cause, and what's the idiomatic fix?

[paste the FULL exception via ex.ToString() — message + all inner exceptions + trace]

[paste the MapGet handler]

Three things make that prompt good:

The full exception, not the headline. ex.ToString() includes every inner exception and the complete trace. In Copilot Chat, #Program.cs pulls the source in for you.
The first frame that's yours. Point Claude at Program.cs:line 12 and the code around it. The framework frames are context; your frame is the crime scene.
The conditions. "Every request" vs "only under load" vs "intermittent" changes the diagnosis completely. Say what you observed.

What Claude tells you

Instead of "line 12 failed", you get the actual mechanism: EF Core's DbContext is not thread-safe and does not allow two operations on the same instance at once. Task.WhenAll starts the second query before the first finishes, both on the same injected db, and EF's ConcurrencyDetector throws. The line number was a red herring — the bug is the pattern, not the call.

And it gives you both fixes, with the trade-off:

// Fix A — simplest: run them sequentially. One context, one operation at a time.
var orders = await db.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
var total  = await db.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);
return Results.Ok(new { Orders = orders, Total = total });

// Fix B — real parallelism: give each query its OWN context via a factory.
builder.Services.AddDbContextFactory<ShopContext>(o => o.UseSqlite("Data Source=shop.db"));

app.MapGet("/orders/{customerId:int}/summary",
    async (int customerId, IDbContextFactory<ShopContext> factory) =>
{
    await using var ordersDb = await factory.CreateDbContextAsync();
    await using var totalDb  = await factory.CreateDbContextAsync();

    var ordersTask = ordersDb.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
    var totalTask  = totalDb.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);

    await Task.WhenAll(ordersTask, totalTask);
    return Results.Ok(new { Orders = await ordersTask, Total = await totalTask });
});

Fix A is what you want 90% of the time — two SQLite queries are fast, and the parallelism was never worth the bug. Fix B is the answer when the queries are genuinely slow and independent, because IDbContextFactory<T> hands you a fresh, short-lived context per operation. That distinction — not the line number — is the thing you were actually missing, and it's the kind of judgment a good explanation gives you and a search result doesn't.

A .NET async stack trace has two kinds of frames: the forty that belong to the runtime, and the one that's your fault. Claude's job is to skip the forty and explain the one.

Verify — Don't Trust Blindly

Claude is a very fast senior colleague who is occasionally, confidently wrong. Treat its diagnosis as a strong hypothesis, not a verdict:

Reproduce and confirm. Apply the fix, re-run, and check the exception is actually gone — ideally under the same conditions that triggered it. In Visual Studio, set a breakpoint on the fixed line and watch the state.
Ask why, not just what. "Explain why this fixes it" surfaces a wrong root cause fast. If the reasoning doesn't hold, the fix probably doesn't either.
Watch for plausible-but-wrong causes. For intermittent bugs especially, Claude may propose a cause that fits the trace but isn't yours. Make it rank candidates and tell you how to distinguish them.

The debugger still owns state. Claude owns meaning. When you need to know the actual value of a variable at the moment of the crash, that's a watch window and a breakpoint, not a chat prompt.

When to Reach for Claude — and When Not To

Reach for it when:

The exception type or message is unfamiliar, or the trace is mostly framework internals.
The real cause is buried in inner exceptions or an AggregateException.
You're staring at async frames and can't tell which of your lines is the origin.
You want the idiomatic fix and the trade-offs, not just a patch that makes the red go away.

Don't bother when:

You already know the cause — a NullReferenceException on a line you just wrote doesn't need an LLM.
You need the runtime value of something — use the debugger.
The trace contains secrets or customer data. Connection strings, tokens, and PII live in exception messages and payloads more often than you'd like. Scrub before you paste, especially with a cloud model.

The rule of thumb: if you'd otherwise open a browser to search the exception, ask Claude instead — it's in the IDE, it can read your code, and it won't send you to a dead 2015 forum thread.

Key Takeaways

The trace shows machinery, not intent — async state machines, inner exceptions, and framework frames bury the one line that's yours. Reading traces is pattern recognition, which is exactly where an LLM helps.
Claude lives in Visual Studio two ways — pick it in Copilot Chat's model picker for quick, conversational diagnosis; run Claude Code in the integrated terminal when the fix is agentic and spans files.
Context is the whole game — paste the full ex.ToString(), point at the first frame that's yours, and describe when it happens. A headline message gets a headline guess.
The line number is often a red herring — the EF Core example throws at ToListAsync, but the bug is sharing one DbContext across parallel queries. The value is the explanation, not the location.
Verify, then trust — reproduce the fix, ask why it works, and never paste secrets. The debugger owns state; Claude owns meaning.

Deja de Entrecerrar los Ojos con los Stack Traces de .NET: Depúralos con Claude en Visual Studio

Juan Gómez — Fri, 17 Jul 2026 13:23:04 +0000

Deja de Entrecerrar los Ojos con los Stack Traces de .NET: Depúralos con Claude en Visual Studio

Salta una excepción no controlada y Visual Studio te suelta cuarenta líneas de stack trace en el regazo. Treinta y ocho viven en Microsoft.EntityFrameworkCore.* o en System.Private.CoreLib, una es un frame de máquina de estados asíncrona con un nombre tipo <<Main>$>b__0_0, y exactamente una apunta a código que escribiste tú. Tu trabajo es encontrar esa línea, entender por qué explotó y arreglar la causa real — no el síntoma.

Todos hemos pegado un trace en el buscador y recibido a cambio una sola pregunta de Stack Overflow de 2015, cero respuestas, y un único comentario que dice "¿al final lo resolviste?". Hay una forma mejor, y ahora vive dentro de Visual Studio: le pasas el trace a Claude y recibes un diagnóstico ordenado por probabilidad, atado a tu línea, con un arreglo que de verdad puedes razonar.

Por Qué Cuesta Tanto Leer un Stack Trace de .NET

Los stack traces no son difíciles por ser largos. Son difíciles porque el código moderno de .NET casi nunca corre en línea recta, y el trace refleja la maquinaria, no tu intención.

Desenrollado asíncrono. Un await compila a una máquina de estados. Cuando una excepción cruza un await, los frames que ves son llamadas a MoveNext() y ExecutionContext.Run, no la cadena de llamadas ordenada que escribiste. El método aparece como <AlgoAsync>d__4, y la línea que lógicamente lanzó puede estar tres await más arriba.
Excepciones internas (inner exceptions). El mensaje de arriba suele ser el menos útil. La causa real está anidada — un DbUpdateException envolviendo un SqliteException, o un TargetInvocationException envolviendo lo que de verdad importa. Si solo lees la primera línea, estás depurando el envoltorio.
AggregateException. Cualquier cosa con Task.WhenAll o paralelismo puede empaquetar varios fallos en uno. El mensaje externo dice "Se produjeron uno o más errores" — gracias, utilísimo.
Frames inlineados y de framework. El JIT hace inline de métodos pequeños, así que hay frames que desaparecen. Y los que quedan son en su mayoría internos de librerías que no puedes cambiar ni necesitas leer.

Un LLM es genuinamente bueno para esta tarea concreta. Ha visto estas formas de excepción miles de veces, sabe separar el ruido del framework de la señal y — esto es lo clave — cuando corre dentro de tu IDE, puede correlacionar el trace con el archivo y la línea reales.

Dos Formas de Meter a Claude Dentro de Visual Studio

No necesitas salir del IDE ni pegar nada en un navegador. Hay dos caminos sólidos, y cada uno sirve para un momento distinto.

1. Copilot Chat con un modelo Claude (dentro del IDE, conversacional)

Visual Studio 2022 (17.14+) trae GitHub Copilot con un selector de modelo. Haz clic en el badge de Copilot, abre el desplegable de modelos en la caja del chat y elige un modelo Claude — Sonnet para el diagnóstico rápido del día a día, Opus cuando el bug es realmente feo. A partir de ahí, cada respuesta de Copilot Chat la genera Claude.

Dos cosas hacen que este camino brille para depurar:

Cuando una excepción no controlada abre el Asistente de excepciones durante el debug, hay un enlace Preguntar a Copilot justo en ese diálogo. Con Claude seleccionado como modelo, ese análisis de un clic corre sobre Claude.
En la caja del chat puedes traer contexto real con referencias # — #Program.cs, #solution, o una selección resaltada — para que Claude lea tu código de verdad, no una paráfrasis.

Si prefieres usar tu propia clave de Anthropic en vez de los modelos de Copilot, el mismo selector tiene Manage Models → agregar Anthropic → pegar tu API key. Cómodo si ya pagas por acceso a la API.

2. Claude Code en la terminal integrada (agéntico)

Todavía no hay una extensión oficial de Claude Code para el Visual Studio completo, pero no la necesitas — Claude Code corre en cualquier terminal, incluida Ver → Terminal (Ctrl + backtick) dentro de VS. Ejecuta claude, pega el trace y, como Claude Code puede leer todo el repositorio, abrirá él mismo el archivo culpable, seguirá la ruta de llamadas y propondrá el arreglo como un diff que apruebas o rechazas.

El intercambio es simple: Copilot Chat es más rápido para un "¿qué significa esto?", mientras que Claude Code es mejor cuando el arreglo toca varios archivos o quieres que reproduzca y verifique. Usa el que el bug se merezca.

Un Ejemplo Real: El Trace de EF Core Que Culpa a Quien No Es

Depuremos algo concreto. Este es un endpoint de minimal API en .NET 10 que devuelve el resumen de pedidos de un cliente. Se ve razonable, y compila sin quejas:

// Program.cs — minimal API en .NET 10
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<ShopContext>(o => o.UseSqlite("Data Source=shop.db"));

var app = builder.Build();

app.MapGet("/orders/{customerId:int}/summary", async (int customerId, ShopContext db) =>
{
    // Disparamos ambas consultas "en paralelo" para ir rápido — ¿verdad?
    var ordersTask = db.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
    var totalTask  = db.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);

    await Task.WhenAll(ordersTask, totalTask);

    return Results.Ok(new { Orders = ordersTask.Result, Total = totalTask.Result });
});

app.Run();

Llamas al endpoint y lanza. Este es el trace que muestra Visual Studio (recortado a los frames que aparecen):

System.InvalidOperationException: A second operation was started on this context
instance before a previous operation completed. This is usually caused by different
threads concurrently using the same instance of DbContext. For more information on
how to avoid threading issues with DbContext, see https://go.microsoft.com/fwlink/?linkid=2097913.
   at Microsoft.EntityFrameworkCore.Internal.ConcurrencyDetector.EnterCriticalSection()
   at Microsoft.EntityFrameworkCore.Query.Internal.QueryCompiler.ExecuteAsync[TResult](Expression query, CancellationToken ct)
   at Microsoft.EntityFrameworkCore.Query.Internal.EntityQueryProvider.ExecuteAsync[TResult](Expression expression, CancellationToken ct)
   at Microsoft.EntityFrameworkCore.EntityFrameworkQueryableExtensions.ToListAsync[TSource](IQueryable`1 source, CancellationToken ct)
   at Program.<>c.<<Main>$>b__0_0(Int32 customerId, ShopContext db) in C:\src\Shop.Api\Program.cs:line 12

Cuatro de esos cinco frames son internos de EF Core. El único que es tuyo — Program.cs:line 12 — es la llamada a ToListAsync(), lo que hace parecer que ToListAsync es el villano. No lo es.

Cómo pasárselo a Claude bien

La calidad de la respuesta depende por completo de lo que pegues. Un mensaje de una línea te da una conjetura de una línea. Dale a Claude el panorama completo:

.NET 10, EF Core 10, SQLite. Este endpoint lanza en cada request con carga normal
(no solo con concurrencia). Abajo van la excepción completa y el código del endpoint —
¿cuál es la causa raíz y cuál es el arreglo idiomático?

[pega la excepción COMPLETA con ex.ToString() — mensaje + todas las inner exceptions + trace]

[pega el handler del MapGet]

Tres cosas hacen que ese prompt sea bueno:

La excepción completa, no el titular. ex.ToString() incluye cada inner exception y el trace entero. En Copilot Chat, #Program.cs te trae el código solo.
El primer frame que es tuyo. Apunta a Claude a Program.cs:line 12 y al código a su alrededor. Los frames de framework son contexto; tu frame es la escena del crimen.
Las condiciones. "En cada request" vs "solo bajo carga" vs "intermitente" cambia el diagnóstico por completo. Di lo que observaste.

Lo que Claude te responde

En vez de "la línea 12 falló", obtienes el mecanismo real: el DbContext de EF Core no es thread-safe y no permite dos operaciones sobre la misma instancia a la vez. Task.WhenAll arranca la segunda consulta antes de que termine la primera, ambas sobre el mismo db inyectado, y el ConcurrencyDetector de EF lanza. El número de línea era una pista falsa — el bug es el patrón, no la llamada.

Y te da los dos arreglos, con el intercambio incluido:

// Arreglo A — el más simple: ejecútalas en secuencia. Un contexto, una operación a la vez.
var orders = await db.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
var total  = await db.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);
return Results.Ok(new { Orders = orders, Total = total });

// Arreglo B — paralelismo real: dale a cada consulta su PROPIO contexto vía factory.
builder.Services.AddDbContextFactory<ShopContext>(o => o.UseSqlite("Data Source=shop.db"));

app.MapGet("/orders/{customerId:int}/summary",
    async (int customerId, IDbContextFactory<ShopContext> factory) =>
{
    await using var ordersDb = await factory.CreateDbContextAsync();
    await using var totalDb  = await factory.CreateDbContextAsync();

    var ordersTask = ordersDb.Orders.Where(o => o.CustomerId == customerId).ToListAsync();
    var totalTask  = totalDb.Orders.Where(o => o.CustomerId == customerId).SumAsync(o => o.Total);

    await Task.WhenAll(ordersTask, totalTask);
    return Results.Ok(new { Orders = await ordersTask, Total = await totalTask });
});

El Arreglo A es lo que quieres el 90% de las veces — dos consultas a SQLite son rápidas, y el paralelismo nunca valió el bug. El Arreglo B es la respuesta cuando las consultas son genuinamente lentas e independientes, porque IDbContextFactory<T> te entrega un contexto fresco y de vida corta por operación. Esa distinción — no el número de línea — es lo que de verdad te faltaba, y es el tipo de criterio que te da una buena explicación y no un resultado de búsqueda.

Un stack trace asíncrono de .NET tiene dos tipos de frames: los cuarenta que le pertenecen al runtime, y el que es culpa tuya. El trabajo de Claude es saltarse los cuarenta y explicarte el uno.

Verifica — No Confíes a Ciegas

Claude es un colega senior muy rápido que de vez en cuando se equivoca con toda seguridad. Trata su diagnóstico como una hipótesis fuerte, no como un veredicto:

Reproduce y confirma. Aplica el arreglo, vuelve a correr y comprueba que la excepción de verdad desapareció — idealmente bajo las mismas condiciones que la dispararon. En Visual Studio, pon un breakpoint en la línea corregida y observa el estado.
Pregunta el por qué, no solo el qué. "Explica por qué esto lo arregla" saca a la luz una causa raíz equivocada rapidísimo. Si el razonamiento no se sostiene, el arreglo probablemente tampoco.
Ojo con las causas plausibles pero falsas. Sobre todo con bugs intermitentes, Claude puede proponer una causa que encaja con el trace pero que no es la tuya. Haz que ordene los candidatos y te diga cómo distinguirlos.

El debugger sigue siendo el dueño del estado. Claude es dueño del significado. Cuando necesitas saber el valor real de una variable en el momento del crash, eso es una ventana de inspección y un breakpoint, no un prompt de chat.

Cuándo Recurrir a Claude — y Cuándo No

Recurre a él cuando:

El tipo o el mensaje de la excepción te resulta desconocido, o el trace es casi todo internos de framework.
La causa real está enterrada en inner exceptions o en un AggregateException.
Estás mirando frames asíncronos y no logras saber cuál de tus líneas es el origen.
Quieres el arreglo idiomático y sus intercambios, no solo un parche que quite el rojo.

No te molestes cuando:

Ya sabes la causa — un NullReferenceException en una línea que acabas de escribir no necesita un LLM.
Necesitas el valor en runtime de algo — usa el debugger.
El trace contiene secretos o datos de clientes. Las cadenas de conexión, los tokens y los datos personales aparecen en mensajes de excepción y payloads más seguido de lo que te gustaría. Límpialos antes de pegar, especialmente con un modelo en la nube.

La regla de oro: si de otro modo abrirías el navegador para buscar la excepción, mejor pregúntale a Claude — está en el IDE, puede leer tu código, y no te mandará a un hilo de foro muerto de 2015.

Puntos Clave

El trace muestra maquinaria, no intención — máquinas de estados asíncronas, inner exceptions y frames de framework entierran la única línea que es tuya. Leer traces es reconocimiento de patrones, que es justo donde ayuda un LLM.
Claude vive en Visual Studio de dos formas — elígelo en el selector de modelo de Copilot Chat para diagnóstico rápido y conversacional; corre Claude Code en la terminal integrada cuando el arreglo es agéntico y abarca varios archivos.
El contexto lo es todo — pega el ex.ToString() completo, apunta al primer frame que es tuyo y describe cuándo pasa. Un mensaje titular recibe una conjetura titular.
El número de línea suele ser una pista falsa — el ejemplo de EF Core lanza en ToListAsync, pero el bug es compartir un DbContext entre consultas paralelas. El valor está en la explicación, no en la ubicación.
Verifica, luego confía — reproduce el arreglo, pregunta por qué funciona y nunca pegues secretos. El debugger es dueño del estado; Claude, del significado.