10 Perguntas essenciais ao implementar MCP usando .NET | ecode10.com

10 Perguntas essenciais ao implementar MCP usando .NET

Implementação na prática

.NET

Monday, June 30, 2025

Views: 29 SHARE

A inteligência artificial já faz parte do dia a dia dos desenvolvedores .NET. Neste artigo, você vai descobrir como o Model Context Protocol (MCP) pode ser o motor que conecta, de forma simples e padronizada, suas aplicações e microsserviços a agentes de IA. Adote convenções leves, explore transportes flexíveis e elimine horas de retrabalho.

Eu tenho conversado bastante sobre estratrégia de IA durante palestras e consultoria nos clientes e o MCP é uma pergunta comum com muitas dúvidas comuns nos projetos de desenvolvimento de software.

Aprenda a configurar o protocolo em poucos passos, veja casos reais de ganhos de produtividade e domine práticas de testes e monitoramento para garantir segurança e resiliência. Ainda comparamos o Model Context Protocol (MCP) a soluções como OpenAPI, mostrando por que ele é a escolha ideal para arquiteturas modernas sem complicações.

Ao avançar no entendimento do protocolo Model Context Protocol (MCP), tenha em mente que você poderá implementar aplicações incríveis baseadas em arquiteturas modernas, como microsserviços, boas práticas de desenvolvimento, padronização, escalabilidade e reúso, da mesma forma que já faz nas aplicações tradicionais. o protocolo MCP padroniza a conectividade para um novo tipo de front-end, que consiste em agentes de inteligência artificial (IA), LLMs e ferramentas compatíveis.

Configuração do ambiente

1. Visão Geral do Model Context Protocol (MCP)

O que é MCP?

É um protocolo aberto, proposto inicialmente pela Anthropic em novembro de 2024 e amplamente adotado por provedores de IA, que padroniza como LLMs se conectam a serviços externos, oferecendo chamadas de ferramentas (tools), acesso a dados (resources) e uso de templates de prompt (prompts) de forma uniforme, conectando agentes de IA a plataformas como Claude e GitHub Copilot.

Por que usar MCP?

A padronização nas integrações simplifica a extensibilidade, ampliando as possibilidades de recursos ao combinar serviços distintos em torno de um mesmo padrão comparável à abordagem OpenAPI, conhecida pelos desenvolvedores, ou a um conector USB-C, além de reduzir retrabalho, facilitar a manutenção e acelerar o time-to-market de produtos de IA.

Motivação

O MCP possibilita que LLMs, assistentes de IA e agentes de IA acessem dados “vivos”, assim como ferramentas externas, de modo seguro e escalável, permitindo que serviços disponham de informações atualizadas para interações que façam sentido para o usuário e que, por exemplo, agentes de IA possam executar processos como realizar uma compra em um e-commerce, consultar o saldo de uma conta corrente e até planejar uma viagem, incluindo toda a logística envolvida, como reservas, passeios e seguros.

Analogia chave

O ecossistema de integração se popularizou nos últimos anos por meio de hubs de APIs, principalmente baseados em OpenAPI, e de portais de desenvolvedores com suas documentações por exemplo Swagger, Scalar muito usando em .NET, que na maioria das vezes dependem de procedimentos manuais e de soluções customizadas. Porém, nesta era de IA, o “cliente” deixa de ser um usuário humano para ser um LLM, um agente de IA ou outra ferramenta que precisa executar processos automaticamente, sem intervenção manual. Por isso o MCP, com seu funcionamento similar ao de um conector universal USB-C, habilita a autodescoberta e o uso por IA.

2. Arquitetura e Comunicação

Componentes

Host: a aplicação que roda o LLM e inicia conexões.
Server MCP: o serviço que expõe tools, resources e prompts.
Client MCP: a aplicação que implementa JSON-RPC para consumir os serviços.

Tipos de capacidades

Tools: funções executáveis (ex: enviar e-mail, consultar histórico de cliente, verificar preço de um produto).
Resources: dados fornecidos (ex: documentos).
Prompts: templates para guiar o LLM.

Transportes

STDIO: comunicação local via stdin/stdout, onde o Client MCP executa o Server MCP como processo filho.
Streamable HTTP: chamadas HTTP remotas com resposta em streaming (chunked transfer).
HTTP + SSE: chamadas HTTP remotas com Server-Sent Events, para receber atualizações em tempo real.

Handshake inicial

O Client MCP envia tools/list ? Server MCP retorna lista de ferramentas, descrições e schemas de parâmetros ? catálogo local pronto para orquestrações.

Formato das mensagens

Padrão JSON-RPC 2.0 com campos jsonrpc, method, params, id, result e error.

3. Fluxo de Execução

Ciclo de chamada

O usuário aciona o LLM, que detecta a necessidade de chamar uma ferramenta externa “MCP” via JSON-RPC, passa os parâmetros requeridos no método, executa a operação e obtém o resultado, devolvendo o contexto atualizado ao LLM para construir a resposta final.

Decisão do LLM

O LLM mantém um catálogo de ferramentas MCP cadastradas; ao detectar a intenção, aciona function calling ou prompt design, escolhendo a ferramenta apropriada para o contexto.

Incorporação de resultados

O retorno da ferramenta externa, recebido em JSON, é adicionado ao histórico antes de continuar a geração.

Interações multi-step

A conexão stateful preserva recursos e prompts ao longo de várias trocas.

Experiência integrada

As ferramentas MCP funcionam como um complemento ao LLM, trazendo recursos adicionais como dados atualizados, pesquisa na Web e interação com arquivos locais de acordo com o contexto.

4. Desenvolvimento de Servidores MCP

SDKs e linguagens
A documentação oficial do Model Context Protocol (MCP) reúne todas as orientações para implementar o protocolo em diversas linguagens como Python, TypeScript, C#, Java e você pode utilizar qualquer stack que leia ou escreva JSON. Para aprofundar, consulte o artigo "Explorando MCP Server para .NET Developers", que trata do servidor, e "Explorando o MCP Client para Desenvolvedores .NET Developers", que aborda o cliente.

Passos iniciais

Definir escopo com o objetivo da ferramenta Tool.
Escolher SDK e linguagem de desenvolvimento.
Definir o protocolo de transporte
Implementar tipo de transporte e JSON-RPC e/ou utilizar componentes como o ModelContextProtocol para .NET .
Definir com clareza a nomenclatura do métodos, parâmetros e exemplos na documentação do MCP.
Definir mecanismo de segurança e/ou token conforme o contexto.
Testar com MCP Inspector ou Postman e similares.

Boas práticas

Princípio do mínimo privilégio, sandboxing, OAuth, tratamento claro de erros e logs estruturados.

Exemplo

O exemplo abaixo traz uma implementação simples do MCP utilizando .NET, que você pode conferir em mais detalhes no artigo Explorando MCP Server para .NET/C# Developers. Como estamos utilizando o componente ModelContextProtocol grande parte da implementação do protocolo MCP está isolada tornando a experiência muito acessivel. Nós utilizamos a classe PingTool e você pode incluir chamadas a seu critério para serviços internos ou internos e/ou leitura e gravação em disco, comunicação interna dentro com outras aplicações e microsserviços.

using ModelContextProtocol.Server;
using System.ComponentModel;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddMcpServer()
    .WithHttpTransport() // Use HTTP transport for MCP server
    .WithStdioServerTransport() // Use standard input/output for MCP server
    .WithToolsFromAssembly(); // Automatically discover tools
builder.WebHost.UseUrls("http://localhost:5000"); // TCP
var app = builder.Build();
app.MapMcp("/mcp"); // Map the MCP server to the /mcp endpoint
app.Run();

namespace Tools
{
    [McpServerToolType]
    public class PingTool
    {
        [McpServerTool(Name = "ping"), Description("Return a greeting for the given name. Required: name (string).")]
        public string ping([Description("Person's name")] string name)
        {
            var greeting = $"Hello, {name}!";
            return greeting;
        }
    }
}

5. Ecossistema e Integrações

MCP Client Implemente um cliente MCP, conforme demonstrado no artigo Explorando o MCP Client para Desenvolvedores .NET para consumir qualquer recurso exposto por outro MCP adicionando uma integração com um sistema comporativo por exemplo da mesma forma que estaria criando um acesso a uma API externa usando Rest com documentação OpenAPI.

using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol; 

// Initialize MCP client
var mcpClient = await McpClientFactory.CreateAsync(
    new SseClientTransport(
        new SseClientTransportOptions
        {
            Name = "MCP",
            Endpoint = new Uri("http://localhost:5000/mcp")
        }
    )
);

// Call the "ping" tool
var pingResponse = await mcpClient.CallToolAsync(
    "ping",
    new Dictionary<string, object?> { ["name"] = "Ramon" }
);

// Extract result
var responseText = pingResponse.Content
    .OfType<TextContentBlock>()
    .Select(tb => tb.Text)
    .FirstOrDefault() 
    ?? "no response";

// print result
Console.WriteLine(responseText);

Hosts compatíveis
Cusor, Claude Desktop, Cody, Visual Studio Code, JetBrains, Continue, Windsurf

Servidores populares
PostgreSQL, GitHub, Slack, Google Drive, Stripe, Weaviate

6. Segurança e Conformidade

Autenticação

OAuth 2.0, tokens seguros.

Consentimento

Confirmação explícita antes de ações sensíveis.

Privacidade

Compartilhar só o necessário; mascarar em logs; respeitar políticas.

Tool safety

Auditar servidores confiáveis; whitelist/blacklist no host.

7. Operação e Escalabilidade

Escala distribuída

Balanceamento, contêineres (Docker/K8s) e autoscaling.

Implantação

Local (STDIO) para testes; remoto (HTTP+SSE / Streamable HTTP).

Monitoramento

Logs JSON, métricas, MCP Inspector, tracing distribuído.

Recursos avançados

Cancelamento, progresso via SSE, notificações e metadados.

8. MCP vs OpenAPI – Comparativo e convivência

Introdução
O OpenAPI é o padrão consolidado para documentar APIs REST (CRUD sobre HTTP/JSON, Swagger UI, geração de SDKs), amplamente adotado em portais de desenvolvedor para uso interno ou parceiros. Com o surgimento de function calling em LLMs (GPT-4, Claude etc.), ele passou a atender também agentes de IA de forma pontual. Mas será que isso basta para orquestrações complexas ou consumo totalmente autônomo?

OpenAPI

Suporte a LLMs: muitos modelos consomem specs OpenAPI para function calling sem código manual.
Ecossistema maduro: geração de clientes em várias linguagens, validação de payload, documentação interativa e integração com gateways API.

Limitações para agentes

Descoberta passiva: o agente só “vê” funções explicitamente enviadas no prompt; não há catálogo dinâmico.
Sem streaming ou cancelamento: não há SSE/Streamable HTTP por padrão nem forma de abortar chamadas em curso.
Contexto reduzido: cada requisição é isolada, sem passagem automática de estado ou metadados de execução.

O que o MCP acrescenta

Autodiscovery: endpoint tools/list expõe catálogo completo de ferramentas para LLMs.
Workflows avançados: suporte a multi-step, streaming (SSE) e cancelamento inline de execuções.
Metadados e auditoria: consentimento inline, sandboxing de ferramentas e logs detalhados por agente.

Quando usar cada um

Só OpenAPI: consumo majoritariamente humano, UIs Swagger ou integrações simples com function calling pontual.
OpenAPI + MCP: plataformas IA-first, RAG e agentes autônomos que exigem autodiscovery, orquestração e streaming em tempo real.

Reflexão

A dica de 1 milhão de dólares é entender que, apesar de compararmos OpenAPI e MCP, ambos podem (e devem) ser implementados em sua aplicação. Se sua prioridade é documentar e validar APIs REST para desenvolvedores, o OpenAPI é a solução ideal. Porém, para agentes de IA que demandam descoberta automática de recursos, composição de fluxos de trabalho complexos e reação em tempo real, adotar o MCP faz toda a diferença.

9. Implementando conjunta MCP e OpenAPI
Inspirado em plataformas como a Devprime AI, que automatizam esse fluxo, compartilho um exemplo unificando uma implementação REST com a documentação OpenAPI e ferramentas MCP em um único projeto .NET, registrando AddOpenApi() e AddMcpServer() com transportes HTTP e STDIO.

Em seguida, mapeamos /ping/{name} via OpenAPI e /mcp para chamadas MCP, criando uma integração poderosa e coesa, onde internamente executamos a mesma classe PingService, demonstrando claramente o potencial de reuso oferecendo uma API tradicional e uma exposição para LLMs e agentes de IA usando o protocolo MCP.

using ModelContextProtocol.Server;
using System.ComponentModel;
using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddOpenApi();
builder.Services.AddSingleton<PingService>();

//MCP Tools
builder.Services.AddMcpServer()
    .WithHttpTransport()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();
builder.WebHost.UseUrls("http://localhost:5000");

var app = builder.Build();

//OpenAPI
app.MapOpenApi();
app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/openapi/v1.json", "MCP API V1");
    options.RoutePrefix = "swagger";
});

//Endpoints HTTP
app.MapGet("/ping/{name}", (string name, PingService svc) => svc.CreatePing(name))
   .WithName("Ping")
   .WithSummary("Get a personalized greeting")
   .WithDescription("Return a greeting for the given name. Required: name (string).")
   .WithTags("Greeting")
   .WithOpenApi();

//MCP Endpoints
app.MapMcp("/mcp")
   .WithOpenApi();

app.Run();


//MCP Tools
[McpServerToolType]
public class PingTool
{
    private readonly PingService _pingService;
    public PingTool(PingService pingService)
    {
        _pingService = pingService;
    }

    [McpServerTool(Name = "ping"), Description("Return a greeting for the given name. Required: name (string).")]
    public string ping([Description("Person's name")] string name)
    {
        return _pingService.CreatePing(name);
    }
}

//Services
public class PingService
{
    public string CreatePing(string name)
    {
        return $"Hello, {name}!";
    }
}

Executando a aplicação
Explore na prática o projeto de exemplo utilizando o MCP e OpenAPI que estará expondo um endpoint na url http://localhost:5000

# Clone o repositório
git clone https://github.com/ramonduraes/dotnet-ai-mcp-openapi.git

# Entre na pasta do servidor
cd dotnet-ai-mcp-openapi/Server
 
# Execute a aplicação
dotnet run

Acessando via MCP pelo Postman
O endpoint MCP estará exposto em: http://localhost:5000/mcp

Acessando via OpenAPI pelo Swagger
A documentação OpenAPI ficará disponível em: http://localhost:5000/swagger

10. Estratégias de Teste e Validação de Integrações MCP em .NET

Uma aplicação que utiliza o protocolo MCP é, no fim das contas, uma aplicação tradicional, e você precisa se preocupar internamente com padronização, reuso e testabilidade. Afinal, seu cliente final (“Agente de IA / LLM / Ferramentas”) precisa acessar uma solução robusta, escalável e, principalmente, com qualidade nas respostas.

Isolamento da lógica de negócio

Separe regras de comportamento em classes ou serviços independentes, consumidos via interfaces.
Atente-se à nomenclatura, documentação e a resultados claros de sucesso e de erro.
Use injeção de dependência para substituir facilmente implementações por mocks em testes unitários.

Testes de contrato (contract tests)

Utilize o PactNet para gerar um contrato (pact file) que descreva as chamadas JSON-RPC do client (tools/list, invoke) e as respostas esperadas.
No pipeline do servidor, valide esse contrato automaticamente, garantindo que o MCP Server continue a atender às expectativas do cliente.

Mock de MCP Server em testes unitários

Simule respostas JSON-RPC em memória (stdin/stdout falso ou HTTP local) para testar o Client MCP sem precisar levantar o servidor real.

Testes de integração end-to-end

Levante o MCP Server em Docker no CI e execute chamadas reais a tools/list, invoke e streaming, verificando o fluxo completo.

Validação de performance e carga

Realize benchmarks de chamadas concorrentes ao MCP para medir throughput, latência e uso de recursos.

Integração com CI/CD

Configure Azure DevOps ou GitHub Actions para rodar todos os testes em cada PR e incluir gates de qualidade antes do merge.

Considerações Finais

A inteligencia artificial é uma realidade nas empresas e os desenvolvedores tem um papel importante construindo novas ferramentas e promovendo novos recursos com GenAI essa tem sido uma pauta frenquente durante a consolutoria que realizo em clientes e no trabalho de conselheiro em projetos de software e por isso estive compartilhando experiencias direto da trincheira como a utilizaçao do Model Context Protocol com .NET para potencialiar os projetos de software.

Essa estrategia garante uma integração padronizada entre LLMs e seus serviços, simplificando o desenvolvimento e manutenção. A arquitetura descrita neste guia oferece flexibilidade para orquestrar chamadas de ferramentas, recursos e prompts de forma stateful e escalável, aproveitando transportes como HTTP, SSE e STDIO. Seguir as boas práticas de segurança, autenticação e monitoramento assegura conformidade e resiliência em produção.

A convivência com OpenAPI permite atender tanto clientes humanos quanto agentes de IA, ampliando o alcance das suas APIs. Por fim, explorar recursos avançados como cancelamento de chamadas, streaming de progresso e auditoria enriquecerá ainda mais a experiência dos usuários e agentes inteligentes.

A sua contribuição é valiosa

?? Este artigo é fruto de longas horas de pesquisa, desenvolvimento, validação de contexto e elaboração minuciosa. Se fez sentido para você, deixe seu comentário e compartilhe com a sua rede além de sugerir novos temas.