Создание и регистрация сервера протокола контекста модели (MCP)

Протокол контекста модели (MCP) предоставляет стандартный интерфейс для агентов ИИ для взаимодействия с API и внешними службами. Если необходимо интегрировать частные или внутренние корпоративные системы, у которых нет существующих реализаций сервера MCP, можно создать собственный пользовательский сервер. В этой статье показано, как создать удаленный сервер MCP с помощью Функции Azure, зарегистрировать его в каталоге средств частной организации с помощью центра API Azure и подключить его к службе агента Foundry.

Этот подход позволяет безопасно интегрировать внутренние API и службы в экосистему Microsoft Foundry, позволяя агентам вызывать средства для конкретного предприятия через стандартный интерфейс MCP.

Необходимые условия

• Проект Foundry с включенной агентской службой. Инструкции по настройке см. в кратком руководстве по созданию агента запроса.
• Подписка Azure и разрешения для создания ресурсов. Как минимум, для целевой группы ресурсов требуется роль участника.
• Python версии 3.11 или более поздней версии, установленной на локальном компьютере разработки.
• Функции Azure Core Tools версии 4.0.7030 или более поздней.
• Azure Developer CLI установлен для автоматизации процессов развертывания.
• Для локальной разработки и отладки:
  • Visual Studio Code
  • расширение Функции Azure для Visual Studio Code
• Ресурс центра API Azure (необязательно, требуется только для регистрации каталога инструментов организации).

Общие сведения о потоке запросов

Удаленные серверы MCP могут быть разработаны на заказ (как описано в этой статье) или предоставлены Microsoft в виде предложений, доступных в каталоге Foundry Add Tools, например, Azure DevOps MCP Server (превью-версия). Интерфейс подключения и управления в Foundry аналогичен в обоих случаях, с различиями в проверке подлинности и области для конкретного поставщика.

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

1. Вы развертываете сервер MCP (в этой статье используется Функции Azure), который предоставляет один или несколько средств MCP.
2. При необходимости вы регистрируете сервер в Центре API Azure, чтобы он отображался в каталоге инструментов организации.
3. На портале Foundry вы подключаете сервер MCP к Службе агента.
4. Когда агенту требуется средство, служба агента вызывает конечную точку сервера MCP.
5. Сервер MCP проверяет запрос, вызывает внутренний API и возвращает результат инструмента.

Создание сервера MCP с помощью Функции Azure

Функции Azure — это бессерверная служба вычислений, которая обеспечивает возможность масштабирования до нулевой нагрузки, всплескового масштабирования и корпоративные функции, включая доступ на основе удостоверений и виртуальное сетевое взаимодействие. Упрощенная модель программирования упрощает создание серверов MCP, чтобы сосредоточиться на реализации бизнес-логики, а не на управлении инфраструктурой.

1. Откройте терминал или командную строку и перейдите в папку, в которой вы хотите создать проект.

2. Выполните команду azd init, чтобы инициализировать проект из шаблона сервера MCP :

   azd init --template remote-mcp-functions-python -e mcpserver-python
   

3. Просмотрите пример структуры кода. Шаблон включает:

   • Определения функций для конечных точек MCP.
   • Настройка проверки подлинности и авторизации.
   • Скрипты развертывания для Azure.

4. Настройте функции сервера MCP для предоставления определенных API и служб. Измените код функции, чтобы реализовать необходимые средства и возможности агентов.

5. Протестируйте сервер MCP локально с помощью основных средств Функции Azure:

   func start
   

6. Разверните сервер MCP в Azure с помощью интерфейса командной строки разработчика Azure:

   azd up
   

   Следуйте инструкциям, чтобы выбрать Azure подписку и группу ресурсов.

7. После завершения развертывания сохраните следующие сведения для последующих действий:

   • Удаленная конечная точка сервера MCP: https://{function_app_name}.azurewebsites.net/runtime/webhooks/mcp
   • Сведения о проверке подлинности. Для проверки подлинности ключа доступа обратите внимание на системный ключ mcp_extension на портале Azure.

   Если вы предпочитаете рабочий процесс CLI для извлечения ключей доступа к функциям, см. статью Работа с ключами доступа в Функции Azure.

8. (Необязательно) Чтобы использовать проверку подлинности Microsoft Entra вместо доступа на основе ключей, включите проверку подлинности Функции Azure в приложении-функции, задайте для аудитории URI идентификатора приложения, ожидаемый конечной точкой MCP, и проверьте путь веб-перехватчика MCP (/runtime/webhooks/mcp). Подробные инструкции по настройке см. в руководстве Развертывание MCP-сервера на Функции Azure.

Дополнительные подробности реализации, включая расширенные паттерны аутентификации и устранение неисправностей, см. в руководстве Хостинг MCP-сервера на Функции Azure.

Защита конечной точки сервера MCP

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

• Требовать проверку подлинности. Избегайте анонимного доступа, если сценарий явно не нуждается в нем.
• Считайте учетные данные секретами. Не хардкодируйте ключи в программе и не загружайте их в систему управления версиями. Храните секреты в безопасном хранилище, например Azure Key Vault.
• Реализуйте минимизацию прав доступа для последующих вызовов. Если сервер MCP вызывает внутренние API, ограничьте разрешения только теми, которые необходимы предоставляемым инструментам.
• Регистрация и мониторинг вызовов инструментов. Используйте логгирование Функции Azure для трассировки запросов и поиска и устранения неисправностей.

При использовании Функции Azure для размещения сервера MCP параметры проверки подлинности сопоставляют с Foundry следующим образом:

• Ключи функций (x-functions-key): соответствует проверке подлинности на основе ключей в Foundry.
• Microsoft Entra: связано с аутентификацией Microsoft Entra в Foundry (удостоверение агента или управляемое удостоверение проекта).
• Сквозная передача удостоверений OAuth: соответствует сквозной передаче удостоверений OAuth (OBO) в Foundry.
• Не прошедший проверку подлинности: поддерживается для ограниченных сценариев, но не рекомендуется для рабочих нагрузок.

Шаблоны проверки подлинности службы агента (например, проверка подлинности на основе ключей, удостоверения Microsoft Entra и сквозная идентификация OAuth) см. в разделе MCP server authentication.

Рекомендации по управлению и эксплуатации при запуске средств MCP см. в руководстве по обеспечению безопасности и рекомендации по управлению сервером Foundry MCP.

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

При регистрации сервера MCP в Центре API Azure создается частный каталог средств организации. Этот шаг является необязательным, но рекомендуется предоставлять общий доступ к серверам MCP в организации с согласованным управлением и возможностью обнаружения.

Чтобы зарегистрировать сервер MCP, выполните приведенные действия.

1. Войдите на портал Azure и перейдите к ресурсу Центра API Azure.

   Совет

   Имя Центра API становится именем каталога частных инструментов в фильтре реестра. Выберите информативное имя, которое помогает пользователям определить каталог инструментов вашей организации.

2. В панели навигации слева разверните Инвентаризация и выберите Активы.

3. Выберите "Зарегистрировать ресурс " и выберите сервер MCP.

4. Укажите необходимые сведения о сервере MCP.

5. Настройте среды и развертывания согласно руководству: Добавление сред и развертываний для API в Центре API Azure.

6. Настройте проверку подлинности для сервера MCP (необязательно):

   В левой области навигации ресурса Центра API выберите Управление>Авторизация.

   

7. Выберите "Добавить конфигурацию".

8. Выберите схему безопасности, соответствующую требованиям сервера MCP:

   • Ключ API. Разработчики предоставляют ключ API во время настройки средства в Foundry
   • OAuth: настройка параметров проверки подлинности OAuth 2.0
   • HTTP: конфигурация авторизации с использованием токена

9. Укажите необходимые сведения о проверке подлинности для выбранной схемы.

   Примечание

   Если выбрать проверку подлинности ключа API, ключ, который вы храните в Azure Key Vault, не используется автоматически в Foundry. Разработчики должны предоставить ключ API при настройке подключения сервера MCP.

10. Настройка управления доступом (необязательно):

    a. Перейдите на зарегистрированный сервер MCP в Центре API.

    B. Выберите Детали>Версии>Управление доступом (предварительная версия).

    C. Настройте, какие пользователи или группы могут получить доступ к этому серверу MCP через каталог организации.

После регистрации сервер MCP появится в каталоге инструментов Foundry с настроенными параметрами управления и проверки подлинности.

Предоставление общего доступа к серверам MCP за пределами организации

Каталог инструментов организации (Azure API Центр) распространяется на вашу организацию. Чтобы совместно использовать серверы MCP с внешними командами или более широким сообществом, рассмотрите возможность распространения их через общедоступный или частный репозиторий GitHub с инструкциями по настройке. В настоящее время нет межорганизационной платформы серверов MCP, но экосистема MCP развивается. Проверьте сайт спецификации MCP для обновлений по обнаружению и распределению серверов.

Подключение сервера MCP к службе агента

Сервер MCP можно подключить к службе агента через каталог средств организации (если вы зарегистрировали его) или в качестве пользовательского средства MCP.

Подключение с помощью каталога средств организации

Если вы зарегистрировали сервер MCP в Центре API Azure, пользователи с соответствующим доступом могут обнаружить и настроить его:

1. На портале Foundry перейдите к проекту.

2. Перейдите ксредствам> или откройте построитель агентов.

3. Перейдите в каталог средств организации, чтобы найти зарегистрированный сервер MCP.

4. Следуйте инструкциям по настройке, отображаемым в каталоге инструментов, чтобы добавить сервер в агент.

Один и тот же сервер MCP можно повторно использовать несколькими клиентами (например, службой агента Foundry и средствами разработчика, такими как Visual Studio Code), если проверка подлинности настроена соответствующим образом.

Подключение с помощью пользовательского средства MCP

Если вы не регистрируете сервер MCP в каталоге организации, добавьте его непосредственно в качестве настраиваемого средства:

1. На портале Foundry перейдите к проекту.

2. Перейдите ксредствам> или откройте построитель агентов.

3. Выберите Добавить средство>Пользовательская>Модель контекстного протокола.

4. Введите сведения о сервере MCP:

   • Имя: уникальное имя удаленного сервера MCP
   • Удаленная конечная точка сервера MCP: введите URL-адрес удаленной конечной точки сервера MCP (например, https://{function_app_name}.azurewebsites.net/runtime/webhooks/mcp)
   • Проверка подлинности: выберите метод проверки подлинности:
     • На основе ключа: укажите учетные данные в качестве "x-functions-key": "{mcp_extension_system_key}".
     • Microsoft Entra ID: выберите удостоверение агента Agent identity или удостоверение, управляемое проектом Project. Укажите URI аудитории (URI идентификатора приложения), настроенную на сервере MCP. Убедитесь, что выбранное удостоверение имеет необходимые разрешения в функциональном приложении.
     • Проброс идентификационных данных OAuth (OBO): укажите идентификатор клиента, секрет клиента, URL-адрес авторизации, URL-адрес токена, URL-адрес обновления (если применимо), а также области доступа для вашего поставщика OAuth. Используйте этот параметр, когда необходимо действовать от имени пользователя, вошедшего в систему.

5. Выберите "Подключиться" , чтобы зарегистрировать настраиваемое средство MCP.

Подробные инструкции по настройке (включая подключения к проектам и рабочие процессы утверждения), см. в разделе "Подключение к серверам контекста модели" (предварительная версия).

После подключения сервера MCP агенты в проекте Foundry могут вызывать средства и функции, предоставляемые пользовательским сервером. Один и тот же сервер MCP можно повторно использовать несколькими клиентами (например, службой агента Foundry и средствами разработчика, такими как Visual Studio Code), если проверка подлинности настроена соответствующим образом.

Проверьте, что сервер MCP работает от начала до конца

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

1. На портале Foundry убедитесь, что сервер MCP отображается в списке инструментов проекта.

2. Создайте агент (или откройте существующий агент) и добавьте средство сервера MCP.

3. Запустите запрос, который должен требовать одно из средств MCP.

4. Если включено одобрение, просмотрите имя и аргументы инструмента, а затем одобрите вызов.

5. Подтвердите успешность вызова инструмента.

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

Устранение неполадок

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

• Подключение к серверу MCP не удается: убедитесь, что URL-адрес сервера доступен из Agent Service и использует путь веб-перехватчика MCP (/runtime/webhooks/mcp). Для общедоступных конечных точек убедитесь, что URL-адрес является общедоступным. Для частных конечных точек убедитесь, что настройка стандартного агента с помощью частной сети настроена правильно. Проверьте журналы приложения-функции на портале Azure на наличие ошибок.
• Ошибки проверки подлинности (401/403): убедитесь, что вы используете правильный ключ или маркер для выбранного метода проверки подлинности. Поменяйте ключи, которые могли быть скомпрометированы, и обновите все ваши сохраненные учетные данные.
• Microsoft Entra сбои проверки подлинности (401/403). Убедитесь, что аудитория (URI идентификатора приложения) в конфигурации инструмента Foundry соответствует разрешенной аудитории, настроенной в параметрах проверки подлинности вашего функционального приложения. Убедитесь, что выбранное удостоверение (удостоверение агента или управляемое удостоверение проекта) имеет необходимые назначения ролей в функциональном приложении. Убедитесь, что URL-адрес издателя правильный для клиента Microsoft Entra.
• Неудачи передачи идентификаторов OAuth: Проверьте URL-адрес авторизации, URL-адрес токена и области в конфигурации средства Foundry соответствуют параметрам поставщика OAuth. Убедитесь, что идентификатор клиента и секрет клиента являются правильными и не истекают. Несоответствия области или неправильные URL-адреса конечных точек являются распространенными причинами сбоев обмена маркерами OBO.
• проблемы обнаружения Tool. Если вы зарегистрировали сервер в центре API Azure, убедитесь, что API опубликован и к нему есть доступ. Если вы добавили пользовательское средство, убедитесь, что URL-адрес конечной точки правильный.
• Вызов средства завершается успешно, но внутренний API завершается ошибкой: просмотрите журналы сервера MCP, чтобы убедиться, что запрос был отправлен в нижестоящий API. Убедитесь, что удостоверение сервера MCP или учетные данные API имеют необходимые разрешения.

Очистка ресурсов

По завершении удалите ресурсы Azure, созданные шаблоном, чтобы избежать текущих расходов.

1. В папке проекта сервера MCP выполните следующую команду:

   azd down --purge
   

2. Если вы зарегистрировали сервер в Центре API Azure, удалите запись API, если она больше не нужна.

Связанное содержимое

• Проверка подлинности сервера MCP
• Начните работу с сервером Foundry MCP (предварительная версия) с помощью Visual Studio Code
• Лучшие практики и рекомендации по обеспечению безопасности для сервера Foundry MCP
• Изучите доступные средства и примеры запросов на сервер Foundry MCP (предварительная версия)
• Добавить среды и развертывания в Azure API Центр
• руководство разработчика Функции Azure Python