Публикация REST API в системе "Управление API" в роли сервера MCP

ОБЛАСТЬ ПРИМЕНЕНИЯ: Разработчик | Базовый | Базовая версия 2 | Стандартный | Стандартная версия 2 | Премиум | Премиум версия 2

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

Azure API Management также поддерживает безопасную интеграцию с существующими серверами, совместимыми с MCP, — серверами инструментов, размещенными за пределами управления API. Дополнительные сведения см. в разделе "Предоставление существующего сервера MCP".

Дополнительные сведения:

• Поддержка сервера MCP в службе управления API
• Возможности шлюза искусственного интеллекта

Ограничения

• Для серверов MCP, обрабатываемых в службе управления API из управляемых REST API, в настоящее время служба управления API поддерживает серверные инструменты MCP, но не поддерживает ресурсы или запросы MCP.
• В настоящее время управление API не поддерживает возможности сервера MCP в рабочих областях.

Предпосылки

• Если у вас еще нет экземпляра управления API, выполните следующее краткое руководство: Создание экземпляра Azure API Management. Экземпляр должен находиться на одном из уровней сервисов, поддерживающих серверы MCP.

• Убедитесь, что экземпляр управляет API-интерфейсом, совместимым с HTTP (любым API, импортированным как REST API, включая API, импортированные из ресурсов Azure), которые необходимо предоставить в качестве сервера MCP. Чтобы импортировать пример API, см. статью "Импорт и публикация первого API".

  Замечание

  Другие типы API в службе управления API, несовместимые с HTTP, не могут предоставляться как серверы MCP.

• Если вы включите ведение журнала диагностики с помощью Application Insights или Azure Monitor в глобальной области (для всех API) для экземпляра службы управления API, установите параметр Число байтов полезной нагрузки для журналирования на 0 для Frontend Response. Этот параметр предотвращает непреднамеренное логирование содержимого тела ответа для всех API, что помогает обеспечить надлежащее функционирование серверов MCP. Чтобы регистрировать данные селективно для определенных API, настройте настройки отдельно в области API, позволяя эффективно управлять ведением журнала ответов.

• Чтобы протестировать сервер MCP, можно использовать Visual Studio Code с доступом к GitHub Copilot или таким инструментам, как инспектор MCP.

Публикация API как сервера MCP

Выполните следующие действия, чтобы предоставить управляемый REST API в службе управления API в качестве сервера MCP:

1. В портале Azure перейдите к экземпляру управления API.
2. В меню слева в разделе APIs выберите MCP Servers>+ Create MCP server.
3. Выберите "Предоставить API в качестве сервера MCP".
4. На бэкенд-сервере MCP:
   1. Выберите управляемый API для предоставления в качестве сервера MCP.
   2. Выберите одну или несколько операций API для предоставления в виде инструментов. Вы можете выбрать все операции или только определенные операции.

      Замечание

      Вы можете обновить операции, предоставляемые в виде инструментов, далее в колонке "Сервис " сервера MCP.

5. На новом сервере MCP:
   1. Введите имя сервера MCP в службе управления API.
   2. При необходимости введите описание сервера MCP.
6. Нажмите кнопку "Создать".

• Сервер MCP создается, а операции API предоставляются в виде инструментов.
• Сервер MCP указан в колонке "Серверы MCP ". В столбце URL-адрес сервера показан адрес сервера MCP для тестирования или в клиентском приложении.

Настройка политик для сервера MCP

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

Дополнительные сведения о настройке политик:

• Политики в управлении API
• Преобразование и защита API
• Установка и изменение политик
• Безопасный доступ к серверу MCP

Осторожность

Не обращаться к тексту ответа с помощью переменной context.Response.Body в политиках сервера MCP. Это приводит к возникновению буферизации ответов, что влияет на поведение потоковой передачи, необходимое для серверов MCP, и может привести к сбоям.

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

1. В портале Azure перейдите к экземпляру управления API.

2. В меню слева в разделе API выберите MCP-серверы.

3. Выберите сервер MCP из списка.

4. В меню слева в разделе MCP выберите "Политики".

5. В редакторе политик добавьте или измените политики, которые необходимо применить к средствам сервера MCP. Определите политики в формате XML.

   Например, можно добавить политику для ограничения вызовов средств сервера MCP (в этом примере один вызов в 60 секунд на сеанс MCP).

   <!-- Rate limit tool calls by Mcp-Session-Id header -->
   <set-variable name="body" value="@(context.Request.Body.As<string>(preserveContent: true))" />
   <choose>
       <when condition="@(
           Newtonsoft.Json.Linq.JObject.Parse((string)context.Variables["body"])["method"] != null 
           && Newtonsoft.Json.Linq.JObject.Parse((string)context.Variables["body"])["method"].ToString() == "tools/call"
       )">
       <rate-limit-by-key 
           calls="1" 
           renewal-period="60" 
           counter-key="@(
               context.Request.Headers.GetValueOrDefault("Mcp-Session-Id", "unknown")
           )" />
       </when>
   </choose>
   

   

Замечание

Управление API оценивает политики, настроенные в глобальной области (все API), прежде чем оценивать политики в области сервера MCP.

Проверка и использование сервера MCP

Используйте соответствующий агент LLM (например, GitHub Copilot, Semantic Kernel или Copilot Studio) или тестовый клиент (например, curl) для вызова конечной точки MCP, размещенной в службе управления API. Убедитесь, что запрос содержит соответствующие заголовки или маркеры, а также подтвердите успешную маршрутизацию и ответ с сервера MCP.

Подсказка

Если вы используете инспектор MCP для тестирования сервера MCP, управляемого управлением API Management, используйте версию 0.9.0.

Добавление сервера MCP в Visual Studio Code

В Visual Studio Code используйте GitHub Copilot чат в режиме агента для добавления сервера MCP и использования средств. Общие сведения о серверах MCP в Visual Studio Code см. в разделе Use MCP Servers in VS Code.

Чтобы добавить сервер MCP в Visual Studio Code, выполните следующие действия.

1. Используйте команду MCP: Add Server из палитры команд.

2. При появлении запроса выберите тип сервера : HTTP (HTTP или отправленные события сервера).

3. Введите URL-адрес сервера MCP в службе управления API. Например, https://<apim-service-name>.azure-api.net/<api-name>-mcp/mcp для конечной точки MCP.

4. Введите идентификатор сервера по своему усмотрению.

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

   • Параметры рабочей области . Конфигурация сервера сохраняется только в файле, доступном .vscode/mcp.json только в текущей рабочей области.

   • Параметры пользователя — конфигурация сервера добавляется в глобальный settings.json файл и доступна во всех рабочих областях. Конфигурация выглядит примерно так:

   

Добавьте поля в конфигурацию JSON для параметров, таких как заголовок проверки подлинности. В следующем примере показана конфигурация ключа подписки для управления API, передаваемого в заголовке в качестве входного значения. Дополнительные сведения о формате конфигурации

Использование средств в режиме агента

После добавления сервера MCP в Visual Studio Code можно использовать средства в режиме агента.

1. В чате GitHub Copilot выберите режим Agent и нажмите кнопку Tools, чтобы просмотреть доступные инструменты.

   

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

   Скриншот выбора инструментов в Visual Studio Code.

3. Введите запрос в чате, чтобы вызвать средство. Например, если вы выбрали средство для получения сведений о заказе, вы можете попросить агента о заказе.

   Get information for order 2
   

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

   

Устранение неполадок и известных проблем

Проблема.	Причина	Solution
401 Unauthorized ошибка в сервере	Заголовок авторизации не перенаправлен	Используйте правило set-header для ручного присоединения маркера, при необходимости.
Вызов API работает в службе управления API, но завершается сбоем в агенте	Неправильный базовый URL-адрес или отсутствующий маркер	Перепроверьте политики безопасности и конечные точки.
Поток сервера MCP прекращается, когда включены журналы диагностики.	Логирование тела ответа или доступ к телу ответа через политику мешает транспортировке MCP.	Отключение ведения журнала текста ответа в области "Все API" — см. предварительные требования

Связанный контент

• Пример: авторизация серверов MCP с защищенными метаданными ресурсов (PRM)

• Sample: защита удаленных серверов MCP с помощью Azure API Management (экспериментальная)

• лаборатория авторизации клиента MCP

• Используйте расширение Azure API Management для VS Code для импорта и управления API

• Зарегистрируйте и обнаружьте удаленные серверы MCP в Центре API Azure

• Экспонирование REST API в Управлении API в качестве сервера MCP

• Отображение и управление существующим сервером MCP