Construindo servidores MCP em .NET

Esta habilidade ajuda você a escrever servidores MCP de qualidade de produção e clientes básicos em C#/.NET usando os pacotes NuGet oficiais ModelContextProtocol, mantidos pela Microsoft e pelo projeto MCP. Ele tem como alvo a linha estável 2.x e a especificação atual (28/07/2026).

Quando esta habilidade se justifica

O SDK MCP .NET teve anos de pacotes de pré-visualização (0.x-preview) antes de atingir 1.0, e a v2 inverteu várias configurações padrão. Sem ajuda, o modelo tende a:

• Fixar uma versão de pré-visualização desatualizada que não compilará com exemplos atuais.
• Aplicar configurações padrão da era 1.x que a v2 reverteu (HTTP era stateful por padrão; em 2.x Stateless tem como padrão true).
• Recomendar recursos que a especificação de 28/07/2026 deprecia (roots, sampling, logging de canal MCP — agora [Obsolete], aviso MCP9005).
• Perder recursos recentes da especificação (multi-round-trip input_required, negociação discovery-first, pacotes de extensão MCP Apps/Tasks, modo de URL de elicitação, blocos de conteúdo estruturados).
• Errar detalhes do transporte HTTP (stateful/stateless, buffering de proxy, fiação OAuth).
• Esquecer a armadilha STDIO stdout/stderr.

Se a tarefa for uma dessas, carregue a referência correspondente e siga-a. Se for realmente trivial (por exemplo, "renomear este método de ferramenta"), você não precisa ler tudo — as regras cardinais abaixo são o mínimo.

Modelo mental em 30 segundos

Um servidor MCP .NET é um aplicativo Microsoft.Extensions.Hosting (ou WebApplication) comum que conecta um servidor MCP através de DI:

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()      // OR .WithHttpTransport(...)
    .WithToolsFromAssembly()         // discover [McpServerToolType] classes
    .WithPrompts<MyPrompts>()        // optional
    .WithResources<MyResources>();   // optional

Primitivas são métodos C# simples em classes marcadas com atributos ([McpServerToolType] + [McpServerTool], [McpServerPromptType] + [McpServerPrompt], [McpServerResourceType] + [McpServerResource]). Os parâmetros são vinculados a partir de JSON-RPC; o SDK constrói o JSON Schema a partir da assinatura mais os atributos [Description].

Recursos de servidor para cliente (elicitação, notificações de progresso e as agora depreciadas notificações de amostragem/roots/log) são métodos na IMcpServer injetada.

Árvore de decisão → quais referências carregar

Sempre carregue references/packages.md se você estiver criando um novo projeto ou não tiver certeza da versão atual do pacote.

Para tarefas com múltiplas primitivas, carregue várias de uma vez. Para edições triviais em um arquivo existente, você geralmente não precisa de nenhuma.

Regras cardinais (aplicam-se sempre; estas evitam as falhas mais frequentes)

1. Fixe o pacote estável atual, não uma pré-visualização. Use ModelContextProtocol / ModelContextProtocol.AspNetCore / ModelContextProtocol.Core na versão 2.x mais recente. Se você se encontrar escrevendo 0.3-preview ou 0.4-preview, pare e verifique o NuGet — APIs de pré-visualização têm diferenças que quebram a compatibilidade. A 1.x ainda funciona, mas é anterior à especificação de 28/07/2026.
2. Servidores STDIO não devem escrever em stdout. Stdout é o canal JSON-RPC. Configure LogToStandardErrorThreshold = LogLevel.Trace antes de qualquer outra coisa e nunca Console.WriteLine de uma ferramenta.

…