Criar um agente do .NET OpenAI usando um servidor MCP em Aplicativos de Contêiner do Azure

Este artigo mostra como criar um agente do PROTOCOLO MCP usando o .NET. Neste exemplo, o cliente MCP (escrito em C#/.NET) conecta-se a um servidor MCP (escrito em TypeScript) para gerenciar uma lista de tarefas pendentes. O cliente encontra as ferramentas disponíveis do servidor e as envia para um modelo do Azure OpenAI. Os usuários podem então conversar com o sistema todo usando o idioma cotidiano.

Acessar o código

Confira o modelo de IA do Bloco de Construção do Agente DO MCP openai. Este exemplo mostra como criar um agente OpenAI que usa um cliente MCP para consumir um servidor MCP existente.

Vá para a seção passo a passo do código para entender como esse exemplo funciona.

Visão geral da arquitetura

O diagrama a seguir mostra a arquitetura simples do aplicativo de exemplo:

• Cliente MCP: conecta-se ao servidor MCP e localiza as ferramentas disponíveis
• Cliente de chat: funciona com o Azure OpenAI para entender a linguagem natural
• Interface do usuário do Blazor: fornece uma interface da Web em que os usuários podem conversar
• Camada de transporte: usa eventos de Server-Sent (SSE) para enviar mensagens em tempo real
• Autenticação: usa tokens JWT para manter a conexão segura

O servidor MCP é executado como um aplicativo em contêineres nos Aplicativos de Contêiner do Azure (ACA). Ele usa um back-end TypeScript para fornecer ferramentas ao cliente MCP por meio do Protocolo de Contexto de Modelo. Todas as ferramentas funcionam com um banco de dados SQLite de back-end.

Custo

Para manter os custos baixos, este exemplo usa tipos de preço básicos ou de consumo para a maioria dos recursos. Ajuste a camada conforme necessário e exclua os recursos quando terminar para evitar encargos.

Pré-requisitos

• Visual Studio Code – versão mais recente para dar suporte ao desenvolvimento do MCP Server.
• SDK do .NET 9
• Kit de Desenvolvimento em C# para Visual Studio Code Extensão do Visual Studio Code
• GitHub Copilot Extensão do Visual Studio Code
• Chat do GitHub Copilot Extensão do Visual Studio Code
• CLI do Azure Developer CLI
• A extensão de AI Foundry Extensão do Visual Studio Code
• Um modelo AI Foundry gpt-5-mini implantado

Um contêiner de desenvolvimento inclui todas as dependências necessárias para este artigo. Você pode executá-lo em Codespaces do GitHub (em um navegador) ou localmente usando o Visual Studio Code.

Para seguir este artigo, verifique se você atende a estes pré-requisitos:

Implantar um modelo gpt-5-mini do AI Foundry usando a extensão do VS Code da AI Foundry

Implante um gpt-5-mini modelo usando a Extensão de AI Foundry no Visual Studio Code usando as seguintes etapas:

Criar um projeto do AI Foundry e implantar o modelo

• Para criar um projeto do AI Foundry e implantar um gpt-5-mini modelo, siga as instruções de Introdução no artigo Trabalhar com a extensão do Azure AI Foundry para Visual Studio Code (versão prévia ).

Criar a cadeia de conexão do Modelo OpenAI

1. Depois que o gpt-5-mini modelo for implantado, clique com o botão direito do mouse no modelo na extensão AI Foundry e selecione Copiar chave de API para copiar a chave de API do modelo para sua área de transferência.

2. Em seguida, clique com o botão direito do mouse no modelo implantado gpt-5-mini na extensão do AI Foundry e selecione Copiar ponto de extremidade para copiar o ponto de extremidade do modelo para sua área de transferência, conforme mostrado na seguinte captura de tela:

   

3. Por fim, crie uma cadeia de conexão para o modelo implantado gpt-5-mini usando o ponto de extremidade copiado e a chave de API no seguinte formato: Endpoint=<AZURE_OPENAI_ENDPOINT>;Key=<AZURE_OPENAI_API_KEY>. Você precisa dessa cadeia de conexão mais adiante no artigo.

Abrir o ambiente de desenvolvimento

Siga estas etapas para configurar um ambiente de desenvolvimento pré-configurado com todas as dependências necessárias.

Implantar e executar

O repositório de exemplo contém todos os arquivos de código e configuração para a implantação do Azure do agente MCP. As etapas a seguir explicam o processo de implantação do Azure do agente MCP de exemplo.

Desplegar no Azure

Definir o token JWT

• Defina o token JWT para o servidor MCP executando o seguinte comando no terminal na parte inferior da tela:

  # zsh/bash
  ./scripts/set-jwttoken.sh
  

  # PowerShell
  ./scripts/Set-JwtToken.ps1
  

Adicionar token JWT à configuração do ambiente azd

1. Adicione o token JWT à configuração do ambiente azd executando o seguinte comando no terminal na parte inferior da tela:

   # zsh/bash
   env_dir=".azure/$(azd env get-value AZURE_ENV_NAME)"
   mkdir -p "$env_dir"
   cat ./src/McpTodo.ServerApp/.env >> "$env_dir/.env"
   

   # PowerShell
   $dotenv = Get-Content ./src/McpTodo.ServerApp/.env
   $dotenv | Add-Content -Path ./.azure/$(azd env get-value AZURE_ENV_NAME)/.env -Encoding utf8 -Force
   

   Observação

   Por padrão, o aplicativo cliente MCP é protegido pelo recurso de autenticação interna da ACA. Você pode desativar esse recurso antes de executar azd up definindo:

   azd env set USE_LOGIN false
   

2. Execute o seguinte comando da CLI do Desenvolvedor do Azure para provisionamento de recursos do Azure e implantação de código-fonte:

   azd up
   

3. Use a tabela a seguir para responder aos prompts:

   Rápido	Resposta
   Nome do ambiente	Use um nome curto e minúsculo. Adicione seu nome ou alias. Por exemplo, my-mcp-agent. O nome do ambiente torna-se parte do nome do grupo de recursos.
   Subscription	Escolha a assinatura na qual você deseja criar recursos.
   Local (para hospedagem)	Escolha o local de implantação do modelo na lista.
   Cadeia de conexão OpenAI	Cole a cadeia de conexão para o modelo OpenAI criado anteriormente na seção Criar a cadeia de conexão do Modelo OpenAI .

4. A implantação do aplicativo leva de 5 a 10 minutos.

5. Após a conclusão da implantação, você pode acessar o agente MCP usando a URL na saída. A URL tem esta aparência:

   https://<env-name>.<container-id>.<region>.azurecontainerapps.io
   

6. Abra a URL em um navegador da Web para usar o agente MCP.

Usar o agente TODO MCP

Depois que o agente MCP estiver em execução, você poderá usar as ferramentas que ele fornece no modo de agente. Para usar ferramentas MCP no modo de agente:

1. Navegue até a URL do aplicativo cliente e entre no aplicativo.

   Observação

   se você definir o USE_LOGIN valor como false, talvez você não seja solicitado a entrar.

2. Insira um prompt como "Preciso enviar um email ao meu gerente na quarta-feira" na caixa de entrada do chat e observe como as ferramentas são automaticamente invocadas conforme necessário.

3. O agente MCP usa as ferramentas fornecidas pelo servidor MCP para atender à solicitação e retornar uma resposta na interface de chat.

4. Experimente outros prompts como:

   Give me a list of to dos.
   Set "meeting at 1pm".
   Give me a list of to dos.
   Mark #1 as completed.
   Delete #1 from the to-do list.
   

Explore o código

O repositório de exemplo contém todos os arquivos de código e configuração para a implantação do Azure do agente MCP. As seções a seguir orientam você pelos principais componentes do código do agente MCP.

Configuração e configuração do cliente MCP

O aplicativo configura o cliente MCP em Program.cs. Essa configuração define como se conectar e quais opções usar. O código usa vários padrões avançados, incluindo a integração do .NET Aspire e os padrões de serviço:

builder.Services.AddSingleton<IMcpClient>(sp =>
{
    var config = sp.GetRequiredService<IConfiguration>();
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();

    var uri = new Uri(config["McpServers:TodoList"]!);

    var clientTransportOptions = new SseClientTransportOptions()
    {
        Endpoint = new Uri($"{uri.AbsoluteUri.TrimEnd('/')}/mcp"),
        AdditionalHeaders = new Dictionary<string, string>
        {
            { "Authorization", $"Bearer {config["McpServers:JWT:Token"]!}" }
        }
    };
    var clientTransport = new SseClientTransport(clientTransportOptions, loggerFactory);

    var clientOptions = new McpClientOptions()
    {
        ClientInfo = new Implementation()
        {
            Name = "MCP Todo Client",
            Version = "1.0.0",
        }
    };

    return McpClientFactory.CreateAsync(clientTransport, clientOptions, loggerFactory).GetAwaiter().GetResult();
});

Principais detalhes de implementação:

• Configuração de Transporte: SseClientTransportOptions dá suporte ao SSE (Eventos Server-Sent) e ao transporte HTTP que pode ser transmitido. O método de transporte depende da URL do ponto de extremidade – pontos de extremidade que terminam com /sse o uso Server-Sent Eventos, enquanto os pontos de extremidade que terminam com /mcp o uso de HTTP transmitivel. Essa abordagem permite a comunicação em tempo real entre o cliente e o servidor
• Cabeçalhos de autenticação: os tokens JWT entram para manter a comunicação do AdditionalHeaders servidor segura
• Informações do cliente: McpClientOptions informa ao servidor o nome e a versão do cliente
• Padrão de Fábrica: McpClientFactory.CreateAsync() conecta e conclui o handshake de protocolo

Integração padrão do serviço .NET Aspire

O aplicativo usa o padrão de padrões de serviço do .NET Aspire para preocupações de corte cruzado:

// McpTodo.ServiceDefaults/Extensions.cs
public static TBuilder AddServiceDefaults<TBuilder>(this TBuilder builder) where TBuilder : IHostApplicationBuilder
{
    builder.ConfigureOpenTelemetry();
    builder.AddDefaultHealthChecks();
    builder.Services.AddServiceDiscovery();
    
    builder.Services.ConfigureHttpClientDefaults(http =>
    {
        // Turn on resilience by default
        http.AddStandardResilienceHandler();
        // Turn on service discovery by default
        http.AddServiceDiscovery();
    });
    
    return builder;
}

Os benefícios padrão do serviço:

• Métodos de extensão composable: o sistema usa um padrão de construtor limpo para adicionar recursos compartilhados
• Manipuladores de resiliência padrão: o sistema adiciona regras internas de repetição, disjuntor e tempo limite para você
• Integração de descoberta de serviço: o sistema localiza serviços automaticamente em ambientes de contêiner
• OpenTelemetry por padrão: o sistema obtém o monitoramento completo sem nenhum trabalho de instalação

O diagrama a seguir mostra a relação entre preocupações de corte cruzado e serviços de aplicativo:

Resolução de URL de configuração

O exemplo inclui uma resolução de URL sofisticada para ambientes diferentes:

// AspireUrlParserExtensions.cs
public static Uri Resolve(this Uri uri, IConfiguration config)
{
    var absoluteUrl = uri.ToString();
    if (absoluteUrl.StartsWith("https+http://"))
    {
        var appname = absoluteUrl.Substring("https+http://".Length).Split('/')[0];
        var https = config[$"services:{appname}:https:0"]!;
        var http = config[$"services:{appname}:http:0"]!;
        
        return string.IsNullOrWhiteSpace(https) ? new Uri(http) : new Uri(https);
    }
    // Handle other URL formats...
}

Recursos de Gerenciamento de Configuração:

• Abstração da Descoberta de Serviços: o sistema lida com as URLs de desenvolvimento e produção de forma limpa
• Negociação de protocolo: o sistema escolhe HTTPS primeiro e, em seguida, volta para HTTP
• Convenção de Configuração: o sistema usa padrões padrão de configuração do serviço .NET Aspire

Implementação de autenticação

Este exemplo usa a autenticação JWT (Token Web JSON) para proteger a conexão entre o cliente MCP e o servidor.

dotnet user-secrets --project ./src/McpTodo.ClientApp set McpServers:JWT:Token "$TOKEN"

O cliente MCP recupera o token JWT da configuração e o inclui nos cabeçalhos HTTP para autenticação ao se conectar ao servidor MCP:

AdditionalHeaders = new Dictionary<string, string>
{
    { "Authorization", $"Bearer {config["McpServers:JWT:Token"]!}" }
}

Essa abordagem garante:

• Comunicação Segura: o sistema só permite que clientes com tokens válidos se conectem ao servidor MCP
• Token-Based Autorização: os tokens JWT permitem que o sistema verifique os usuários sem armazenar dados de sessão
• Gerenciamento de Configuração: o sistema armazena tokens confidenciais com segurança em segredos do usuário durante o desenvolvimento

Integração de Autenticação de Aplicativos de Contêiner do Azure

A infraestrutura mostra padrões avançados de autenticação usando os recursos internos de autenticação e autorização dos Aplicativos de Contêiner do Azure ("Autenticação Fácil"):

// containerapps-authconfigs.bicep
resource containerappAuthConfig 'Microsoft.App/containerApps/authConfigs@2024-10-02-preview' = {
  properties: {
    identityProviders: {
      azureActiveDirectory: {
        enabled: true
        registration: {
          clientId: clientId
          openIdIssuer: openIdIssuer
        }
      }
    }
    login: {
      tokenStore: {
        enabled: true
        azureBlobStorage: {
          blobContainerUri: '${storageAccount.properties.primaryEndpoints.blob}/token-store'
          managedIdentityResourceId: userAssignedIdentity.id
        }
      }
    }
  }
}

Recursos avançados de autenticação:

• AutenticaçãoZero-Code: Os Aplicativos de Contêiner do Azure fornecem autenticação interna
• Identidade Gerenciada para Armazenamento: o sistema armazena tokens com segurança sem cadeias de conexão
• Credenciais de identidade federadas: o sistema habilita a identidade da carga de trabalho para autenticação no estilo Kubernetes

O diagrama a seguir mostra o handshake de segurança entre componentes:

Descoberta e registro de ferramentas

O cliente MCP descobre as ferramentas disponíveis do servidor durante a inicialização do componente em Chat.razor:

protected override async Task OnInitializedAsync()
{
    messages.Add(new(ChatRole.System, SystemPrompt));
    tools = await McpClient.ListToolsAsync();
    chatOptions.Tools = [.. tools];
}

Como funciona a descoberta de ferramentas:

1. Consulta de servidor: McpClient.ListToolsAsync() envia uma solicitação ao servidor MCP para listar as ferramentas disponíveis
2. Recuperação de esquema: o servidor envia definições de ferramenta de volta com nomes, descrições e esquemas de entrada
3. Registro da ferramenta: o sistema registra ferramentas com o ChatOptions objeto, disponibilizando-as para o cliente OpenAI
4. Segurança de Tipo: a McpClientTool classe herda, AIFunctiondando uma integração suave com Microsoft.Extensions.AI

O diagrama a seguir mostra como os esquemas de ferramentas são analisados e registrados:

Invocação de função e integração do OpenAI

A configuração do cliente de chat demonstra como as ferramentas MCP se integram ao Azure OpenAI:

var chatClient = openAIClient.GetChatClient(config["OpenAI:DeploymentName"]).AsIChatClient();

builder.Services.AddChatClient(chatClient)
                .UseFunctionInvocation()
                .UseLogging();

Benefícios de integração:

• Chamada automática de função: a .UseFunctionInvocation() extensão ativa a execução automática da ferramenta com base nas decisões de LLM
• Acesso fácil à ferramenta: as ferramentas MCP funcionam como funções internas para o modelo OpenAI
• Processamento de resposta: o sistema adiciona automaticamente os resultados da ferramenta ao fluxo de conversa

Real-Time implementação de chat

A interface de chat demonstra Chat.razor respostas de streaming e execução de ferramentas com padrões blazor avançados:

private async Task AddUserMessageAsync(ChatMessage userMessage)
{
    CancelAnyCurrentResponse();

    // Add the user message to the conversation
    messages.Add(userMessage);
    chatSuggestions?.Clear();
    await chatInput!.FocusAsync();

    // Stream and display a new response from the IChatClient
    var responseText = new TextContent("");
    currentResponseMessage = new ChatMessage(ChatRole.Assistant, [responseText]);
    currentResponseCancellation = new();
    await foreach (var update in ChatClient.GetStreamingResponseAsync([.. messages], chatOptions, currentResponseCancellation.Token))
    {
        messages.AddMessages(update, filter: c => c is not TextContent);
        responseText.Text += update.Text;
        ChatMessageItem.NotifyChanged(currentResponseMessage);
    }

    // Store the final response in the conversation, and begin getting suggestions
    messages.Add(currentResponseMessage!);
    currentResponseMessage = null;
    chatSuggestions?.Update(messages);
}

Recursos de implementação de streaming:

• Real-Time Atualizações: GetStreamingResponseAsync() envia atualizações de resposta bit a bit
• Execução da ferramenta: o sistema processa chamadas de função automaticamente durante o streaming
• Capacidade de resposta da interface do usuário: ChatMessageItem.NotifyChanged() atualiza a interface do usuário em tempo real
• Suporte ao cancelamento: os usuários podem cancelar operações de execução prolongada

Padrões avançados de interface do usuário do Blazor

A implementação usa padrões avançados de interface do usuário para atualizações em tempo real:

Memory-Safe tratamento de eventos:

// ChatMessageItem.razor
private static readonly ConditionalWeakTable<ChatMessage, ChatMessageItem> SubscribersLookup = new();

public static void NotifyChanged(ChatMessage source)
{
    if (SubscribersLookup.TryGetValue(source, out var subscriber))
    {
        subscriber.StateHasChanged();
    }
}

Integração personalizada de componentes da Web:

// ChatMessageList.razor.js
window.customElements.define('chat-messages', class ChatMessages extends HTMLElement {
    connectedCallback() {
        this._observer = new MutationObserver(mutations => this._scheduleAutoScroll(mutations));
        this._observer.observe(this, { childList: true, attributes: true });
    }
    
    _scheduleAutoScroll(mutations) {
        // Debounce the calls and handle smart auto-scrolling
        cancelAnimationFrame(this._nextAutoScroll);
        this._nextAutoScroll = requestAnimationFrame(() => {
            const addedUserMessage = mutations.some(m => 
                Array.from(m.addedNodes).some(n => 
                    n.parentElement === this && n.classList?.contains('user-message')));
            // Smart scrolling logic...
        });
    }
});

Gerenciamento de estado avançado:

// Chat.razor
private void CancelAnyCurrentResponse()
{
    // If a response was cancelled while streaming, include it in the conversation so it's not lost
    if (currentResponseMessage is not null)
    {
        messages.Add(currentResponseMessage);
    }
    
    currentResponseCancellation?.Cancel();
    currentResponseMessage = null;
}

Benefícios da interface do usuário do Blazor:

• Componentes web híbridos: o sistema combina o Blazor Server com elementos personalizados para melhorar o desempenho
• Memory-Safe tratamento de eventos: o sistema usa ConditionalWeakTable para evitar vazamentos de memória
• Rolagem Automática Inteligente: o sistema fornece um comportamento de chat amigável com o debouncing
• Cancelamento normal: o sistema salva o trabalho parcial quando os usuários cancelam operações

Fluxo de solicitação/resposta

Veja como uma interação típica do usuário flui pelo sistema:

1. Entrada do usuário: o usuário digita uma mensagem como "Adicionar 'Comprar mantimentos' à minha lista todo"
2. Processamento de Mensagens: O sistema adiciona a mensagem ao histórico de conversas
3. Análise de LLM: O Azure OpenAI analisa a solicitação e decide quais ferramentas usar
4. Descoberta de Ferramentas: o modelo localiza a ferramenta MCP certa (por exemplo, addTodo)
5. Execução da ferramenta: o cliente MCP chama o servidor com os parâmetros necessários
6. Processamento de resposta: o sistema adiciona a resposta do servidor à conversa
7. Atualização da interface do usuário: o sistema mostra o resultado para o usuário em tempo real

O diagrama a seguir mostra como as mensagens fluem da entrada do usuário por meio do OpenAI para a execução da ferramenta e de volta para a interface do usuário:

Gerenciamento de padrões assíncronos

O aplicativo demonstra padrões assíncronos sofisticados para operações em segundo plano:

// ChatSuggestions.razor
public void Update(IReadOnlyList<ChatMessage> messages)
{
    // Runs in the background and handles its own cancellation/errors
    _ = UpdateSuggestionsAsync(messages);
}

private async Task UpdateSuggestionsAsync(IReadOnlyList<ChatMessage> messages)
{
    cancellation?.Cancel();
    cancellation = new CancellationTokenSource();
    
    try
    {
        var response = await ChatClient.GetResponseAsync<string[]>(
            [.. ReduceMessages(messages), new(ChatRole.User, Prompt)],
            cancellationToken: cancellation.Token);
        // Handle response...
    }
    catch (Exception ex) when (ex is not OperationCanceledException)
    {
        await DispatchExceptionAsync(ex);
    }
}

Benefícios da tarefa em segundo plano:

• Fire-and-Forget with Safety: o sistema usa _ = padrão com tratamento de exceção adequado
• Redução de Contexto Inteligente: o sistema limita o histórico de conversas para evitar o estouro do token
• Cancelamento inteligente: o sistema limpa corretamente as operações concorrentes

Tratamento de erros e resiliência

A implementação inclui vários padrões de resiliência:

private void CancelAnyCurrentResponse()
{
    // If a response was cancelled while streaming, include it in the conversation so it's not lost
    if (currentResponseMessage is not null)
    {
        messages.Add(currentResponseMessage);
    }

    currentResponseCancellation?.Cancel();
    currentResponseMessage = null;
}

Recursos de resiliência:

• Cancelamento normal: o sistema salva respostas em andamento quando os usuários as cancelam
• Recuperação de conexão: a conexão de identificadores de transporte SSE é descartada automaticamente
• Gerenciamento de Estado: o estado da interface do usuário permanece consistente durante erros
• Integração de log: o sistema fornece log completo para depuração e monitoramento

Verificações de observabilidade e integridade

O aplicativo inclui padrões de observabilidade sofisticados:

Configuração de verificação de integridade inteligente:

// Extensions.cs
public static WebApplication MapDefaultEndpoints(this WebApplication app)
{
    if (app.Environment.IsDevelopment())
    {
        // All health checks must pass for app to be considered ready
        app.MapHealthChecks(HealthEndpointPath);
        
        // Only health checks tagged with "live" must pass for app to be considered alive
        app.MapHealthChecks(AlivenessEndpointPath, new HealthCheckOptions
        {
            Predicate = r => r.Tags.Contains("live")
        });
    }
    return app;
}

OpenTelemetry com filtragem inteligente:

// Extensions.cs
.AddAspNetCoreInstrumentation(tracing =>
    // Exclude health check requests from tracing
    tracing.Filter = context =>
        !context.Request.Path.StartsWithSegments(HealthEndpointPath)
        && !context.Request.Path.StartsWithSegments(AlivenessEndpointPath)
)

Benefícios de observabilidade:

• pontos de extremidadeEnvironment-Aware: exposição de verificação de integridade consciente da segurança
• Liveness vs Readiness: padrões de verificação de integridade no estilo Kubernetes
• Redução de ruído de telemetria: filtrando verificações de integridade de rotina de rastreamentos

Configuração e configuração do ambiente

O aplicativo dá suporte a vários ambientes por meio da configuração:

var openAIClient = Constants.GitHubModelEndpoints.Contains(endpoint.TrimEnd('/'))
                   ? new OpenAIClient(credential, openAIOptions)
                   : new AzureOpenAIClient(new Uri(endpoint), credential);

Opções de configuração:

• Azure OpenAI: as implantações de produção normalmente usam o Serviço OpenAI do Azure
• Modelos do GitHub: cenários de desenvolvimento podem usar modelos do GitHub
• Desenvolvimento Local: suporte para instâncias de servidor MCP locais
• Implantação de contêiner: Aplicativos de Contêiner do Azure para hospedagem de produção

Limpar os recursos

Depois de terminar de usar o agente MCP, limpe os recursos criados para evitar incorrer em custos desnecessários.

Para limpar recursos, siga estas etapas:

• Exclua os recursos do Azure criados pela CLI do Desenvolvedor do Azure executando o seguinte comando no terminal na parte inferior da tela:

  azd down --purge --force
  

Limpar os codespaces do GitHub

Obter ajuda

Registre seu problema nos problemas do repositório.

Recursos relacionados

• Criar um servidor MCP typeScript usando aplicativos de contêiner do Azure