Создание агента OpenAI .NET с помощью сервера MCP на Azure Container Apps

В этой статье показано, как создать агент протокола контекста модели (MCP) с помощью .NET. В этом примере клиент MCP (написанный на C#/.NET) подключается к серверу MCP (написанному в TypeScript) для управления списком дел. Клиент находит доступные средства с сервера и отправляет их в модель OpenAI Azure. Затем пользователи могут взаимодействовать с системой todo с помощью повседневного языка.

Перейдите к коду

Ознакомьтесь с шаблоном AI для создания агентов OpenAI MCP. В этом примере показано, как создать агент OpenAI, использующий клиент MCP для использования существующего сервера MCP.

Перейдите к разделу пошагового руководства по коду , чтобы понять, как работает этот пример.

Обзор архитектуры

На следующей схеме показана простая архитектура примерного приложения:

• Клиент MCP: подключается к серверу MCP и находит доступные инструменты
• Chat Client: работает с Azure OpenAI для понимания естественного языка
• Пользовательский интерфейс Blazor: предоставляет веб-интерфейс, в котором пользователи могут общаться
• Транспортный слой: использует события Server-Sent (SSE) для отправки сообщений в режиме реального времени
• Проверка подлинности. Использование маркеров JWT для обеспечения безопасности подключения

Сервер MCP выполняется в качестве контейнерного приложения в Azure Container Apps (ACA). Бэкенд TypeScript используется для предоставления инструментов клиенту MCP через протокол контекста модели. Все средства работают с серверной базой данных SQLite.

Себестоимость

Чтобы снизить затраты, в этом примере используются базовые или ценовые категории потребления для большинства ресурсов. Настройте уровень по мере необходимости и удалите ресурсы, чтобы избежать расходов.

Предпосылки

• Visual Studio Code — последняя версия для поддержки разработки СЕРВЕРА MCP.
• пакет SDK .NET 9
• C# Dev Kit for Visual Studio Code расширение для Visual Studio Code
• Расширение Visual Studio Code GitHub Copilot
• расширение GitHub Copilot Chat для Visual Studio Code
• CLI разработчика Azure (azd)
• Расширение Microsoft Foundry для Visual Studio Code
• Развернутая модель Foundry GPT-5-mini

Контейнер разработки включает все зависимости, необходимые для этой статьи. Его можно запустить в GitHub Codespaces (в браузере) или локально с помощью Visual Studio Code.

Чтобы следовать этой статье, убедитесь, что выполнены следующие предварительные требования:

Развертывание модели Foundry gpt-5-mini с помощью расширения Foundry VS Code

Разверните модель gpt-5-mini с помощью расширения Foundry в Visual Studio Code, выполнив следующие действия:

Создание проекта Foundry и развертывание модели

• Чтобы создать проект Foundry и развернуть модель gpt-5-mini, выполните указания в разделе Начало работы статьи о работе с расширением Microsoft Foundry для Visual Studio Code (Предварительная версия).

Создать connection string модели OpenAI

1. gpt-5-mini После развертывания модели щелкните правой кнопкой мыши модель в расширении Foundry и выберите "Копировать ключ API", чтобы скопировать ключ API модели в буфер обмена.

2. Затем щелкните правой кнопкой мыши развернутую gpt-5-mini модель в расширении Foundry и выберите Копировать конечную точку, чтобы скопировать конечную точку модели в буфер обмена, как показано на следующем снимке экрана.

   

3. Наконец, создайте строку подключения для развернутой модели gpt-5-mini с помощью скопированного адреса конечной точки и ключа API в следующем формате: Endpoint=<AZURE_OPENAI_ENDPOINT>;Key=<AZURE_OPENAI_API_KEY>. Вам потребуется эта строка подключения позже в статье.

Открытие среды разработки

Выполните следующие действия, чтобы настроить предварительно настроенную среду разработки со всеми необходимыми зависимостями.

Развертывание и запуск

Образец репозитория содержит все файлы кода и конфигурации для агента MCP, развертывания в Azure. Приведенные ниже шаги проведут вас через процесс развертывания образца агента Azure MCP.

Развертывание в Azure

Установка токена JWT

• Задайте токен JWT для сервера MCP, выполнив следующую команду в терминале в нижней части экрана:

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

  # PowerShell
  ./scripts/Set-JwtToken.ps1
  

Добавление токена JWT в конфигурацию среды azd

1. Добавьте токен JWT в конфигурацию среды azd, выполнив следующую команду в терминале в нижней части экрана:

   # 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
   

   Замечание

   По умолчанию клиентское приложение MCP защищено встроенной функцией проверки подлинности ACA. Вы можете отключить эту функцию перед запуском azd up , установив следующие параметры:

   azd env set USE_LOGIN false
   

2. Выполните следующую команду командной строки разработчика Azure Azure для подготовки ресурсов и развертывания исходного кода:

   azd up
   

3. Используйте следующую таблицу, чтобы ответить на запросы:

   Подсказка	Ответ
   Имя среды	Используйте короткое имя строчными буквами. Добавьте имя или псевдоним. Например: my-mcp-agent. Имя среды становится частью имени группы ресурсов.
   Subscription	Выберите подписку, в которой требуется создать ресурсы.
   Расположение (для размещения)	Выберите расположение развертывания модели из списка.
   Строка подключения OpenAI	Вставьте строку подключения для модели OpenAI, которую вы создали ранее, в раздел Создание строки подключения модели OpenAI.

4. Развертывание приложений занимает от 5 до 10 минут.

5. После завершения развертывания можно получить доступ к агенту MCP с помощью URL-адреса в выходных данных. URL-адрес выглядит следующим образом:

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

6. Откройте URL-адрес в веб-браузере, чтобы использовать агент MCP.

Использование агента TODO MCP

После запуска агента MCP можно использовать средства, которые он предоставляет в режиме агента. Чтобы использовать средства MCP в режиме агента:

1. Перейдите по URL-адресу клиентского приложения и войдите в приложение.

   Замечание

   Если вы установите значение USE_LOGIN на false, возможно, вам не потребуется вход в систему.

2. Введите запрос, например "Мне нужно отправить сообщение электронной почты моему менеджеру в среду" в поле ввода чата и обратите внимание, как средства автоматически вызываются по мере необходимости.

3. Агент MCP использует средства, предоставляемые сервером MCP, для выполнения запроса и возврата ответа в интерфейсе чата.

4. Поэкспериментируйте с другими запросами, например:

   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.
   

Обзор кода

Образец репозитория содержит весь код и файлы конфигурации для развертывания агента MCP в Azure. В следующих разделах описаны ключевые компоненты кода агента MCP.

Конфигурация и настройка клиента MCP

Приложение устанавливает клиент MCP в Program.cs. Эта конфигурация определяет, как подключиться и какие параметры следует использовать. В коде используется несколько расширенных шаблонов, включая интеграцию .NET Aspire и службы по умолчанию.

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();
});

Основные сведения о реализации:

• Конфигурация транспорта: SseClientTransportOptions поддерживает как события Server-Sent (SSE), так и потоковую передачу HTTP-транспорта. Метод транспорта зависит от URL-адреса конечной точки: конечные точки, заканчивающиеся на /sse, используют Server-Sent события, а те, что заканчиваются на /mcp, используют потоковый HTTP. Такой подход обеспечивает взаимодействие между клиентом и сервером в режиме реального времени
• Заголовки проверки подлинности: токены JWT помещаются в AdditionalHeaders для обеспечения безопасности серверного общения.
• Сведения о клиенте: McpClientOptions сообщает серверу имя и версию клиента.
• Шаблон фабрики: McpClientFactory.CreateAsync() устанавливает соединение и завершает выполнение процедуры рукопожатия протокола

интеграция служб .NET Aspire по умолчанию

Приложение использует по умолчанию шаблон сквозных задач службы .NET Aspire.

// 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;
}

Преимущества службы по умолчанию:

• Композиционные методы расширения: система использует шаблон чистого построителя для добавления функций общего назначения
• Стандартные обработчики устойчивости: система добавляет встроенные правила повторных попыток, останова цепи и времени ожидания.
• Интеграция обнаружения служб. Система автоматически находит службы в средах контейнеров
• OpenTelemetry по умолчанию: система получает полный мониторинг без каких-либо настроек.

На следующей схеме показана связь между перекрестными проблемами и службами приложений:

Разрешение URL-адреса конфигурации

Пример включает сложное разрешение URL-адресов для разных сред:

// 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...
}

Функции управления конфигурацией:

• Абстракция обнаружения служб: система обрабатывает URL-адреса разработки и рабочей среды корректно
• Согласование протоколов: система сначала выбирает HTTPS, а затем возвращается к HTTP
• Configuration Convention: система использует стандартные шаблоны настройки службы .NET Aspire

Реализация проверки подлинности

В этом примере для защиты подключения между клиентом и сервером MCP используется проверка подлинности JWT (JSON Web Token).

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

Клиент MCP получает маркер JWT из конфигурации и включает его в заголовки HTTP для проверки подлинности при подключении к серверу MCP:

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

Этот подход обеспечивает следующее:

• Безопасный обмен данными: система позволяет клиентам с допустимыми маркерами подключаться к серверу MCP.
• Token-Based Авторизация: токены JWT позволяют системе проверять пользователей без хранения данных сеанса
• Управление конфигурацией: система безопасно хранит чувствительные токены в пользовательских секретах в ходе разработки

Интеграция аутентификации в Azure Container Apps

В инфраструктуре показаны расширенные шаблоны проверки подлинности с помощью встроенных функций проверки подлинности и авторизации Azure Container Apps ("Простая проверка подлинности") :

// 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
        }
      }
    }
  }
}

Расширенные функции проверки подлинности:

• Аутентификация без кода Zero-Code: Azure Container Apps обеспечивает встроенную аутентификацию.
• Управляемое удостоверение для хранилища: система безопасно сохраняет токены без использования строк подключения
• Федеративные учетные данные удостоверения: система обеспечивает идентификацию рабочей нагрузки для аутентификации в стиле Kubernetes.

Схема ниже показывает рукопожатие безопасности между компонентами.

Обнаружение и регистрация инструментов

Клиент MCP обнаруживает доступные средства с сервера во время инициализации компонента в Chat.razor:

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

Как работает обнаружение инструментов:

1. Серверный запрос: McpClient.ListToolsAsync() отправляет запрос серверу MCP в список доступных средств
2. Извлечение схемы. Сервер отправляет определения инструментов обратно с именами, описаниями и входными схемами
3. Регистрация инструментов: система регистрирует средства с ChatOptions объектом, что делает их доступными для клиента OpenAI.
4. Безопасность типов: McpClientTool класс наследует от AIFunction, обеспечивая плавную интеграцию с Microsoft.Extensions.AI

На следующей схеме показано, как схемы инструментов анализируются и регистрируются:

Интеграция OpenAI и вызов функций

Конфигурация клиента чата демонстрирует интеграцию средств MCP с Azure OpenAI:

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

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

Преимущества интеграции:

• Автоматический вызов функции: расширение активирует автоматическое выполнение инструмента на основе решений LLM
• Easy Tool Access: средства MCP работают как встроенные функции для модели OpenAI
• Обработка ответов: система автоматически добавляет результаты средства в поток беседы

реализация чата в реальном времени

Интерфейс чата в Chat.razor демонстрирует потоковые ответы и выполнение инструментов с использованием продвинутых шаблонов Blazor.

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);
}

Функции реализации потоковой передачи:

• Обновления в реальном времени: GetStreamingResponseAsync() отправляет обновления ответа побитово
• Выполнение инструмента: система автоматически обрабатывает вызовы функций во время потоковой передачи.
• Адаптивность пользовательского интерфейса: ChatMessageItem.NotifyChanged() обновляет пользовательский интерфейс в режиме реального времени
• Поддержка отмены: пользователи могут отменять длительные операции

Расширенные шаблоны пользовательского интерфейса Blazor

Реализация использует расширенные шаблоны пользовательского интерфейса для обновлений в режиме реального времени:

обработка событийMemory-Safe:

// 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();
    }
}

Интеграция пользовательских веб-компонентов:

// 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...
        });
    }
});

Расширенное управление состояниями:

// 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;
}

Преимущества пользовательского интерфейса Blazor:

• Гибридные веб-компоненты: система объединяет Blazor Server с пользовательскими элементами для повышения производительности.
• Обработка событий с безопасностью памяти: система использует ConditionalWeakTable для предотвращения утечек памяти.
• Смарт-автопрокрутка: система обеспечивает понятное поведение чата с дебаунсингом
• Элегантная отмена: система сохраняет частичную работу при отмене операций пользователями.

Поток запросов и ответов

Ниже показано, как обычное взаимодействие с пользователем проходит через систему:

1. Входные данные пользователя: пользователь вводит сообщение, например "Добавить "Купить продуктовые продукты" в список моих дел".
2. Обработка сообщений: система добавляет сообщение в журнал беседы
3. LLM Analysis: Azure OpenAI анализирует запрос и решает, какие средства следует использовать
4. Обнаружение инструментов: модель находит подходящее средство MCP (например, addTodo)
5. Выполнение инструмента: клиент MCP вызывает сервер с необходимыми параметрами
6. Обработка ответов: система добавляет ответ сервера в беседу
7. Обновление пользовательского интерфейса: система показывает результат пользователю в режиме реального времени

На следующей схеме показано, как сообщения передаются из пользовательского ввода через OpenAI для выполнения инструментов и обратно в пользовательский интерфейс:

Асинхронное управление шаблонами

Приложение демонстрирует сложные асинхронные шаблоны для фоновых операций:

// 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);
    }
}

Преимущества фоновой задачи:

• Fire-and-Forget with Safety: система использует _ = шаблон с надлежащей обработкой исключений
• Сокращение умного контекста: система ограничивает историю чата, чтобы предотвратить переполнение токенов
• Интеллектуальная отмена: система правильно очищает конкурирующие операции

Обработка ошибок и устойчивость

Реализация включает несколько шаблонов устойчивости:

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;
}

Функции устойчивости:

• Грациозная отмена: система сохраняет ответы на ход выполнения при отмене пользователей.
• Восстановление подключения: транспорт SSE автоматически восстанавливает подключение при его потере
• Управление состояниями: состояние пользовательского интерфейса остается согласованным во время ошибок
• Интеграция с ведением журнала: система обеспечивает полное ведение журнала для отладки и мониторинга

Наблюдаемость и проверка работоспособности

Приложение включает сложные шаблоны наблюдаемости:

Конфигурация проверки работоспособности Smart:

// 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 с интеллектуальной фильтрацией:

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

Преимущества наблюдаемости:

• Учитывающие окружающую среду конечные точки: экспонирование проверки работоспособности с точки зрения безопасности
• Liveness vs Readiness: шаблоны проверки работоспособности в стиле Kubernetes
• Уменьшение шума телеметрии: отфильтровывание стандартных проверок работоспособности из трассировок

Настройка конфигурации и среды

Приложение поддерживает несколько сред с помощью конфигурации:

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

Параметры конфигурации:

• Azure OpenAI: рабочие развертывания обычно используют Azure OpenAI Service
• GitHub Модели. Сценарии разработки могут использовать модели GitHub
• Локальная разработка: поддержка локальных экземпляров сервера MCP
• Развертывание контейнеров: Azure Container Apps для размещения в производственной среде

Очистите ресурсы

После завершения использования агента MCP очистите созданные ресурсы, чтобы избежать ненужных затрат.

Чтобы очистить ресурсы, выполните следующие действия.

• Удалите ресурсы Azure, созданные интерфейсом командной строки разработчика Azure, выполнив следующую команду в терминале в нижней части экрана:

  azd down --purge --force
  

Очистка GitHub пространства кода

Получите помощь

Зарегистрируйте вашу проблему в Issues репозитория.

Связанные ресурсы

• Создайте MCP-сервер на TypeScript с использованием Azure Container Apps