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

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

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

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

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

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

Ограничения

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

Предпосылки

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

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

  Замечание

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

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

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

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

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

1. На портале Azure откройте экземпляр API Management.
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 Management.

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, семантический ядро или 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 см. в разделе "Использование серверов MCP в 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 выберите режим агента и нажмите кнопку "Сервис ", чтобы просмотреть доступные инструменты.

   

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

   

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

   Get information for order 2
   

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

   

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

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

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

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

• Пример. Защита удаленных серверов MCP с помощью службы "Управление API Azure" (экспериментальная версия)

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

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

• Регистрация и обнаружение удаленных серверов MCP в Центре API Azure

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

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