Explorando MCP Server para .NET Developers

Para .NET Developers: Model Context Protocol

A nova era da inteligência artificial generativa (GenAI), com a popularização dos modelos de Large Language Model (LLM), tornou acessível o desenvolvimento de aplicações inteligentes. Com isso, surgiu a demanda por mecanismos de integração dos modelos de IA com os recursos tradicionais de forma muito semelhante ao que já realizamos nas empresas com APIs.

O Model Context Protocol (MCP) foi proposto pela Anthropic e rapidamente adotado pela OpenAI, Google e outros grandes players da indústria. Ele permite expor funcionalidades de negócio como “tools” integrados em LLM, agentes de IA e outras aplicações clientes usando o protocolo MCP. Com ele, desenvolvedores .NET podem criar APIs padronizadas, documentadas automaticamente e prontas para integração com fluxos de trabalho baseados em LLMs.

Durante este artigo, faremos uma rápida introdução ao MCP Server utilizando .NET e o componente NuGet ModelContextProtocol, que vem sendo implementado pela comunidade técnica e pela Microsoft. Apresentaremos os conceitos-chave, a configuração mínima e exemplos práticos de uso.

Eu costumo comentar durante as consultorias e palestras que realizo em conferências técnicas que o MCP nada mais é do que uma API tradicional com documentação embarcada, permitindo que mecanismos de IA (como um LLM) realizem discovery automático e utilizem os recursos de forma muito semelhante ao que já praticamos na indústria, seja com WSDL (Web Services Description Language) ou com a especificação OpenAPI, tão popular entre os desenvolvedores.

A melhor parte de atuar em consultoria é acompanhar de perto os mais variados desafios em empresas distintas. Nesta nova era de IA e desenvolvimento de software, as oportunidades se multiplicaram. Precisamos continuar evoluindo os projetos e, ao mesmo tempo, oferecer novos mecanismos de integração entre os recursos da empresa e as plataformas de inteligência artificial. É justamente nesse contexto que o padrão MCP se destaca como uma ponte entre o legado técnico e o futuro inteligente.

Um projeto MCP não difere de qualquer outro projeto .NET e você usará as mesmas práticas de arquitetura, padronização, segurança e separação de responsabilidades existentes. Neste contexto, focaremos apenas na exposição do recurso, para que você possa rapidamente executar tudo em um ambiente local.

Introdução ao MCP Server e ao MCP Client
Um conceito fundamental na arquitetura do MCP é bem parecido com o que já faz hoje no desenvolvimento de APIs tradicionais tendo a a aplicação Server como o serviço que expõe o recurso, nesse contexto seu projeto server e o cliente como a aplicação que vai consumir o mcp e pode ser em .NET ou qualquer outra linguagem de programação compativel com o protocolo assim como os LLM, Agentes de IA, ferramentas e clientes específicos como Postman e MCP Inspector.

Protocolo de comunicação
A comunicação do MCP utiliza o JSON-RPC 2.0 para integração entre cliente e servidor. Você pode utilizar:

• Stdio (Standard Input/Output): Quando o cliente “executa” o servidor em um cenário local, por exemplo, com um editor ou agente de IA rodando na sua máquina.
• HTTP Streaming: Usando Server-Sent Events (SSE) ou o formato mais recente de Streamable HTTP para respostas em streaming via HTTP seja com o seu servidor MCP rodando local ou remoto.

Arquitetura de implementações
A implementação do MCP Server inclui três tipos de componentes que o protocolo disponibiliza aos clientes:

• Tools: Ferramentas expostas que funcionam como endpoints de API.
• Prompts: Templates de instruções de texto que o servidor disponibiliza para orientar chamadas de IA.
• Resources: Arquivos ou dados auxiliares (esquemas, templates etc.) que o cliente pode consultar ou baixar.

Neste artigo, trataremos apenas de Tools, que é o escopo principal do MCP Server.

Checklist inicial

• .NET SDK 9.x+
• Visual Studio Code
• ModelContextProtocol/ModelContextProtocol.AspNetCore
• Postman 11.48.0+
• MCP Inspector v0.14.0+ (Node.js v22.7.5+) (MCP Client) (Opcional)
• Exemplo completo desse artigo (Opcional)

Criando o projeto web e adicionando componente MCP
Agora chegou o momento de iniciarmos a criação do MCP Server utilizando o CLI do .NET e depois na sequência adicionaremos o componente MCP.

1. Crie um projeto web e entre na pasta dotnet new web -o AppMcpServer --exclude-launch-settings --no-https
2. Adicione o nuget ModelContextProtocol.AspNetCore dotnet add package ModelContextProtocol.AspNetCore --prerelease

Implemente o código principal do MCP Server
Abra o projeto no Visual Studio Code e edite o arquivo Program.cs, substituindo seu conteúdo pelo código de exemplo que implementa o servidor MCP no endpoint http://localhost:5000/mcp. Após essa etapa, faça o build do projeto para que possamos adicionar os Tools no próximo passo.

Console.WriteLine("Initializing Streamable HTTP MCP Server...");
Console.WriteLine("http://localhost:5000/mcp");

var builder = WebApplication.CreateBuilder(args);

// 1. Register the MCP server in the service container
builder.Services.AddMcpServer()
    .WithStdioServerTransport() // Use Stdio transport for the MCP server
    .WithHttpTransport()       // Use HTTP transport for the MCP server
    .WithToolsFromAssembly(); // Automatically discoer and register MCP tools from this assembly

builder.WebHost.UseUrls("http://localhost:5000");

var app = builder.Build();

// 2. Map root route to a welcome message
app.MapGet("/", () => "Welcome to .NET MCP Server !!");
// 3. Map the "/mcp" endpoint to the MCP server
app.MapMcp("/mcp");
// 4. Start the server
app.Run();

Console.WriteLine("Finish MCP Server");

Após atualizar, execute o projeto usando o dotnet run na pasta do mesmo e já será possivel abrir os dois endpoins disponíveis por meio do navegador web visitando uma das urls.

• Acesso padrão - http://localhost:5000
• Acesso MCP - http://localhost:5000/mcp

Na url do mcp você terá um retorno parecido com "{"error":{"code":-32001,"message":"Session not found"},"id":"","jsonrpc":"2.0"}" sinalizando que já tem uma resposta do servidor e inicando que está ativo mesmo sem inserirmos o Tool.

Implemente o MCP Tool "HelloTool" no MCP Server
Agora chegou aquele momento tão esperado de expor um Tool pelo MCP Server para ser consumido por meio de uma aplicação MCP Client compatível com o protocolo.

O procedimento é muito fácil e totalmente padrão com o dia a dia de uma implementação .NET então para avançar inclua um novo arquivo no projeto chamado HelloTool.cs e depois adicione o código de exemplo abaixo que descreve o comportamento do método e retorna um valor ao ser executado.

Para esse cenário é importante observar os atributos do MCP incluidos na classe e no método, pois são fundamentais para que durante o inicio do projeto o inicializador possa recuperar quais as ferramentas serão expostas automaticamente.

• McpServerToolType
• McpServerTool

// HelloTool.cs
using ModelContextProtocol.Server;
using System.ComponentModel;

// This code defines a simple MCP tool that returns a greeting message based on the provided name.
// The tool is registered with the MCP server and can be accessed via HTTP requests.
[McpServerToolType]
public class HelloTool
{
    [McpServerTool(Name = "say"), Description("Return a greeting for the given name. Required: name (string).")]
    public string SayHello([Description("Person's name")] string name)
    {
        var greeting = $"Hello, {name}!";
        return greeting;
    }
}

Utilizando o Postman como cliente MCP
Na primeira vez que você iniciar o Postman, localize o menu File > New > MCP para criar uma aba de MCP Request.

Em seguida, informe a URL do seu servidor MCP local (no exemplo abaixo, http://localhost:5000/mcp), certifique-se de que o projeto .NET esteja em execução e clique em Connect para carregar a ferramenta. A partir desse momento, o MCP ficará disponível para preenchimento dos parâmetros e execução das chamadas, permitindo visualizar os resultados diretamente no Postman.

Esse fluxo é muito semelhante à experiência que já temos em .NET com o Swagger. A vantagem, porém, é que esse método possibilita que seu motor de inteligência artificial (LLM), agente de IA ou outras ferramentas clientes interajam com o MCP e, inclusive, acessem serviços corporativos.

Utilizando o MCP Inspector como cliente MCP
O MCP Inspector é uma interface interativa para testar e depurar servidores que implementam o Model Context Protocol (MCP). Ele permite inspecionar esquemas, métodos e respostas das chamadas a um endpoint MCP de forma rápida e visual. Para utilizá-lo, é necessário ter Node.js (v22.7.5 ou superior) e npm instalados. Ao executá-lo, o Inspector abre um portal com a ferramenta.

Executando o MCP Inspector. npx @modelcontextprotocol/inspector

Ao abrir o portal você seguir os passos similares do exemplo anterior com o Postman e realizar um teste no Tool "say" disponibilizado pelo MCP Server.

Implemente o MCP Tool “MathTool” no MCP Server
Agora, pare o projeto caso ele esteja em execução e, para complementar o nosso exemplo, adicione um segundo tool chamado MathTool. Crie um arquivo chamado MathTool.cs com o conteúdo abaixo para habilitar algumas operações de matemática e visualizá-las na ferramenta MCP Client.

// MathTool.cs
[McpServerToolType]
public class MathTools
{
    [McpServerTool(Name = "Multiply"), Description("Multiplies two integers and returns the result. Example: 3 * 4 = 12")]
    public int Multiply(int a, int b) => a * b;

    [McpServerTool(Name = "Divide"), Description("Divides two integers and returns the result as a decimal. Example: 10 / 4 = 2.5")]
    public double Divide(int a, int b) => (double)a / b;

    [McpServerTool(Name = "Add"), Description("Adds two integers and returns the result. Example: 5 + 2 = 7")]
    public int Add(int a, int b) => a + b;

    [McpServerTool(Name = "Subtract"), Description("Subtracts the second integer from the first and returns the result. Example: 9 - 3 = 6")]
    public int Subtract(int a, int b) => a - b;
}

Ao final, execute novamente o projeto e tente conectar pelo Postman e/ou pelo MCP Inspector. Você poderá visualizar os novos tools expostos pelo MCP Server.

Utilizando o MCP Inspector como cliente via protocolo STDIO Neste cenário, usaremos o MCP Inspector como cliente para executar e inspecionar o seu projeto .NET, da mesma forma que ocorre em editores integrados (por exemplo, Cursor ou GitHub Copilot), mas aproveitando a interface dedicada do Inspector. Durante essa abordagem a aplicação MCP Inspector executará o seu projeto .NET

Siga estes passos:

1. Navegue até a pasta raiz do seu projeto e certifique-se de que ele não esteja em execução.

2. Execute o Inspector passando o comando dotnet run (e quaisquer outros parâmetros necessários). Por exemplo:

   npx @modelcontextprotocol/inspector -- dotnet run
   

3. Ao abrir a interface do MCP Inspector no navegador, selecione Transport Type: STDIO, confirme que “Command” está definido como dotnet e “Arguments” como run, e clique em Connect.

4. O Inspector iniciará o processo dotnet run internamente, estabelecerá o canal STDIO e exibirá a lista de ferramentas (tools) registradas no seu MCP Server.

Dessa maneira, você poderá testar e verificar todas as operações disponíveis diretamente pelo MCP Inspector, sem depender de editores externos.

Considerações finais
O Model Context Protocol (MCP) tornou-se um padrão da indústria para integração de serviços com provedores de inteligência artificial. Nesta jornada, foi um prazer compartilhar uma experiência prática que acompanho nos projetos de consultoria que realizo. Você pôde observar a criação de um servidor básico (“MCP Server”) usando o SDK .NET e o pacote NuGet modelcontextprotocol, construindo um exemplo que opera tanto via Streamable HTTP quanto via STDIO. Além disso, mostramos como testar esse servidor com ferramentas amplamente utilizadas, como Postman e MCP Inspector, tornando o processo simples e acessível.