Настройка встроенной MCP службы приложений (предварительная версия)

Встроенная служба приложений MCP преобразует существующий REST API, размещенный на Служба приложений Azure, в >Медельный контекстный протокол (MCP) сервер без написания или развертывания кода MCP. Платформа считывает спецификацию OpenAPI, предоставляемую и генерирует средство MCP для каждой операции. Затем он предоставляет доступ к конечной точке MCP по потоковому HTTP по выбранному вами пути.

Когда следует использовать встроенный MCP

Используйте встроенный MCP, если:

• У вас уже есть REST API, работающий в службе приложений, и вы хотите предоставить его клиенту ИИ, совместимого с MCP (GitHub Copilot Chat, Cursor, Windsurf, Claude Desktop), без изменений кода.
• У вас есть спецификация OpenAPI 3.x (JSON или YAML), описывающая операции, которые необходимо предоставить.
• Вы хотите, чтобы платформа обрабатывала согласование протокола MCP, обнаружение инструментов, горячую перезагрузку спецификации и отмену клиента.
• Вы хотите, чтобы аутентификация App Service обеспечивала проверку удостоверения личности для запросов MCP точно так же, как для любых других маршрутов вашего приложения.

Используйте вместо этого пользовательский сервер MCP (созданный с помощью SDK MCP и развернутый как код вашего приложения) в следующих случаях:

• Вам нужно поведение инструмента MCP, которое нельзя однозначно сопоставить с одной REST-операцией — например, многошаговые рабочие процессы, агрегация в памяти или инструменты, за которыми не стоит HTTP-эндпоинт.
• Вы должны предоставлять ресурсы MCP или промпты в дополнение к инструментам.
• На одном приложении необходимо разместить несколько серверов MCP.

Сравнение всех вариантов размещения MCP на Azure см. в разделе Выбор службы Azure для сервера MCP.

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

• Приложение службы приложений на выделенной ценовой категории (базовый или более высокий). Встроенная поддержка MCP не поддерживается в планах Free, Shared, Consumption и Flex Consumption.
• Спецификация OpenAPI 3.x (JSON или YAML), описывающая операции, которые необходимо предоставить в виде средств MCP. См. шаг 1. Укажите спецификацию OpenAPI для параметров создания.

Шаг 1. Предоставление спецификации OpenAPI

Для встроенного MCP требуется документ OpenAPI 3.x (JSON или YAML). Большинство веб-фреймворков могут создать его для вас:

• ASP.NET Core минимальные API — используйте встроенный пакет Microsoft.AspNetCore.OpenApi (по умолчанию в .NET 9 и более поздних версий).
• контроллеры ASP.NET Core— используйте Swashbuckle.
• FastAPI — автогенерировано по /openapi.jsonадресу.
• Express/NestJS — использование @nestjs/swagger или express-openapi.
• Spring Boot — используйте springdoc-openapi.
• Java/Quarkus — используйте SmallRye OpenAPI.

Если ваш API уже запущен и предоставляет конечную точку OpenAPI, вам не нужно добавлять новую библиотеку — скачайте спецификацию из этой конечной точки (например, с помощью curl) и сохраните её локально, чтобы затем загрузить её при включении встроенной поддержки MCP.

Минимальная спецификация, которая предоставляет одну операцию, выглядит следующим образом:

{
  "openapi": "3.0.3",
  "info": { "title": "Zava Orders", "version": "1.0.0" },
  "paths": {
    "/orders/{id}": {
      "get": {
        "operationId": "get_order",
        "summary": "Get an order by ID",
        "parameters": [
          { "name": "id", "in": "path", "required": true,
            "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "OK" }
        }
      }
    }
  }
}

Используйте понятные, ориентированные на действие operationId значения (list_orders, create_order, cancel_order). Клиент ИИ использует их в качестве имен инструментов при выборе вызываемого средства. Дополнительные сведения о сопоставлении операций с инструментами MCP см. в статье "Как встроенные операции MCP сопоставляют операции REST с инструментами MCP?".

Сделать спецификацию доступной для платформы

Платформа считывает спецификацию из файла в файловой системе приложения. Путь по умолчанию — /home/data/.ai/apispec.json, его можно настроить с помощью ApiSpecPath. Способ получения файла зависит от пути конфигурации, используемого на шаге 2.

• Портал— отправка JSON-файла или YAML при создании сервера MCP. Портал записывает содержимое в ApiSpecPath за вас.
• Azure CLI — разверните спецификацию вместе с приложением (например, включите ее в артефакт развертывания) или загрузите ее позже с помощью az webapp deploy или az webapp ssh.
• Bicep — указывает путь, в который при развертывании помещается приложение.

Шаг 2. Включение встроенного MCP

Встроенный MCP настраивается с помощью свойства aiIntegration в ресурсе Microsoft.Web/sites. Предварительная версия поддерживает портал, Azure CLI (с помощью az rest) и Bicep в качестве поддерживаемых способов настройки.

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

RESOURCE_GROUP=<resource-group>
APP_NAME=<app-name>
SUBSCRIPTION=$(az account show --query id -o tsv)
API_VERSION=2025-05-01

az rest \
  --method PATCH \
  --uri "https://management.azure.com/subscriptions/$SUBSCRIPTION/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.Web/sites/$APP_NAME?api-version=$API_VERSION" \
  --body '{
    "properties": {
      "aiIntegration": {
        "Mcp": {
          "Servers": [
            { "Name": "orders", "Endpoint": "/mcp/orders" }
          ]
        }
      }
    }
  }'

az rest \
  --method PATCH \
  --uri "https://management.azure.com/subscriptions/$SUBSCRIPTION/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.Web/sites/$APP_NAME?api-version=$API_VERSION" \
  --body '{ "properties": { "aiIntegration": null } }'

resource site 'Microsoft.Web/sites@2025-05-01' = {
  name: appName
  location: location
  properties: {
    serverFarmId: appServicePlanId
    aiIntegration: {
      Mcp: {
        Servers: [
          {
            Name: 'orders'
            Endpoint: '/mcp/orders'
          }
        ]
      }
    }
  }
}

Шаг 3. Подключение клиента MCP

После сохранения конфигурации конечная точка MCP доступна по адресу:

https://<app-name>.azurewebsites.net/<endpoint path you provided>

Настройте клиент MCP с помощью этого URL-адреса. Например, в GitHub Copilot Chat в Visual Studio Code добавьте его в .vscode/mcp.json:

{
  "servers": {
    "my-mcp-server": {
      "type": "http",
      "url": "https://<app-name>.azurewebsites.net/<endpoint path you provided>"
    }
  }
}

Когда клиент подключается, он вызывает initialize, затем tools/list, чтобы определить, какие операции предоставляет ваша спецификация OpenAPI, а затем tools/call для каждого вызова.

Authentication

Встроенный MCP не выдает токены и не реализует сервер авторизации. App Service Authentication обеспечивает проверку удостоверения в рамках того же приложения и работает с любым поставщиком удостоверений, который поддерживается App Service Authentication (Microsoft Entra и любым другим настроенным поставщиком OpenID Connect (OIDC)). Поддерживаются две конфигурации:

• Проверка подлинности службы приложений включена (рекомендуется). Запросы MCP проходят те же проверки удостоверений, что и любой другой маршрут, и платформа публикует защищенные метаданные ресурсов , /.well-known/oauth-protected-resource чтобы клиенты MCP могли автоматически завершить OAuth. Требуемые дальнейшие действия: выполните действия, описанные в разделе Настройка встроенной авторизации сервера MCP, чтобы зарегистрировать аудиторию и области MCP у поставщика удостоверений.
• Проверка подлинности службы приложений не включена. Укажите метаданные поставщика удостоверений в блоке SiteAuthaiIntegration. Этот параметр подходит для случаев, когда вы уже проверяете маркеры в коде приложения и не хотите, чтобы проверка подлинности службы приложений обрабатывала поток OAuth от имени приложения. См . статью "Настройка проверки подлинности без проверки подлинности службы приложений".

В обоих случаях код вашего приложения по-прежнему отвечает за проверку токена Bearer при каждом запросе. Встроенный MCP не обеспечивает авторизацию для базовых HTTP-маршрутов.

Настройка встроенного MCP

Минимальный набор данных в Шаге 2 использует все значения по умолчанию. Добавьте только нужные поля. Каждый фрагмент показывает поле, добавленное к минимальной полезной нагрузке.

Изменение расположения спецификации

По умолчанию платформа считывает спецификацию из /home/data/.ai/apispec.json. Установите ApiSpecPath для чтения его из другого места:

"aiIntegration": {
  "ApiSpecPath": "/home/site/wwwroot/openapi/orders.yaml",
  "Mcp": { "Servers": [ { "Name": "orders", "Endpoint": "/mcp/orders" } ] }
}

Отфильтруйте, какие операции доступны

ToolList на каждом сервере определяет, какие операции OpenAPI предоставляет сервер MCP. Значение по умолчанию — ["*"] (каждая операция в спецификации).

• ["*"]— предоставляет доступ ко всем операциям в спецификации.
• []— не предоставляет никаких операций. Полезно для временного отключения обнаружения инструментов без удаления сервера.
• ["get_order", "list_orders"]— предоставляют только перечисленные operationId значения.

"Mcp": {
  "Servers": [
    {
      "Name": "orders",
      "Endpoint": "/mcp/orders",
      "ToolList": ["get_order", "list_orders"]
    }
  ]
}

Используйте этот фильтр, чтобы скрыть потенциально опасные или доступные только администраторам операции из интерфейса MCP, сохранив к ним доступ для ваших существующих HTTP-клиентов.

ToolList взаимодействует с обновлениями спецификаций следующим образом:

• ToolList = ["*"]— при обновлении спецификации новые операции автоматически становятся доступными.
• ToolList = ["op1", "op2"]— при обновлении спецификации доступны только op1 и op2. Новые операции в спецификации игнорируются, пока не добавите их в ToolList.
• Идентификаторы операций, которые не существуют в ToolList спецификации, автоматически удаляются.

Если требуется только фильтрация на основе спецификаций (без списка разрешений на стороне ARM), сохраните ToolList = ["*"] и удалите операции из самой спецификации.

Отключение сервера без его удаления

Установите Enabled в значение false, чтобы перевести конечную точку MCP в автономный режим, не удаляя конфигурацию:

"Mcp": {
  "Servers": [
    { "Name": "orders", "Endpoint": "/mcp/orders", "Enabled": false }
  ]
}

Настройка аутентификации без аутентификации в службе приложений

Если аутентификация App Service не включена для приложения, добавьте блок SiteAuth, чтобы платформа могла публиковать метаданные защищённого ресурса по адресу /.well-known/oauth-protected-resource. Клиенты MCP (например, VS Code) используют заголовок WWW-Authenticate, возвращённый при первом запросе, чтобы обнаружить сервер авторизации и завершить поток OAuth.

"aiIntegration": {
  "Mcp": { "Servers": [ { "Name": "orders", "Endpoint": "/mcp/orders" } ] },
  "SiteAuth": {
    "Scopes": ["api://my-app/user_impersonation"],
    "WellKnownOpenIdConfiguration": "https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration",
    "Audience": "api://my-app-client-id"
  }
}

Обязательные поля: Scopesплюс WellKnownOpenIdConfiguration или Issuer. JwksUri и Audience являются необязательными. См. Справочник: схема aiIntegration для полного списка полей.

Код вашего приложения по-прежнему отвечает за проверку токена Bearer при каждом запросе.

Регистрация сервера MCP в Центре API Azure

Вы можете зарегистрировать свой встроенный сервер MCP как ресурс в Azure API Center, чтобы отслеживать все свои API в одном централизованном месте для их обнаружения, повторного использования и управления ими. Регистрация необязательна— встроенная MCP работает без нее, но рекомендуется сохранить серверы MCP видимыми вместе с остальной частью вашего пространства API.

Портал создает процесс регистрации одного выбора:

1. На вкладке Серверы MCP раскройте свой сервер.

2. Рядом с Azure API Center выберите + Подключить.

   

3. На панели Connect API Center выберите Подписка и существующий API Center или выберите Создать новый, чтобы создать новый. Служба приложений заполняет значения по умолчанию (тип, этап жизненного цикла, среда, развертывание) от вашего имени, чтобы их не нужно настраивать вручную.

4. Нажмите Подключиться. Теперь сведения о сервере содержат ссылку на ресурс в Центре API.

Чтобы изменить метаданные ресурса (тип, этап жизненного цикла, версия, настраиваемые свойства, определения, развертывания), измените ресурс непосредственно в Центре API. Чтобы зарегистрировать сервер MCP в Центре API, не используя App Service, или зарегистрировать сервер, который не был создан встроенным MCP в App Service, см. статью Регистрация и обнаружение удалённых серверов MCP в инвентаре API.

Чтобы отключить сервер MCP из Центра API, удалите соответствующий ресурс сервера MCP в Центре API. Ссылка на вкладке службы App Service MCP servers исчезает после удаления ресурса.

Troubleshooting

Клиент MCP получает 404 в настроенной конечной точке.

• Убедитесь, что значение Endpoint начинается с / и не конфликтует с существующим маршрутом в вашем приложении.
• Убедитесь, что поле сервера Enabled имеет значение true.

Клиент MCP подключается, но tools/list возвращает пустой массив.

• Убедитесь, что спецификация настроена: либо загружена через портал, либо доступна по пути, указанному в ApiSpecPath.
• Убедитесь, что для ToolList не задано значение [].
• Проверьте спецификацию с помощью линтера OpenAPI 3.x — операции, в которых отсутствуют обязательные поля (например, схема ответа), пропускаются.

Клиент MCP получает 401 с WWW-Authenticate проблемой.

• Эта ошибка является ожидаемой, если включена аутентификация App Service и у клиента нет допустимого токена. Запрос проверки подлинности направляет клиента к конечной точке метаданных защищённого ресурса, которая, в свою очередь, указывает на вашего поставщика удостоверяющих данных. См . раздел "Настройка встроенной авторизации сервера MCP".

Клиент MCP получает ошибку 403 при вызове инструмента, но tools/list выполняется успешно.

• Токен OAuth действителен для обнаружения MCP, но у него нет области действия или роли, которые требуются вашему приложению для соответствующего HTTP-маршрута. Проверьте HTTP-статус вышестоящего сервера, отображаемый в CallToolResult.

Часто задаваемые вопросы

Как встроенные операции MCP сопоставляют операции REST с инструментами MCP?

Каждая операция OpenAPI становится одним средством MCP:

• Имя средства— производное от операции operationId. Если operationId отсутствует, платформа возвращается обратно {method}_{path} (например, get__orders__id_). Используйте явные, ориентированные operationId на действия значения, чтобы дать клиенту ИИ более четкие имена инструментов.

• Описание инструмента — сначала операции summary, затем description, если summary отсутствует.

• Аннотации инструментов — встроенный MCP сопоставляет HTTP-метод с аннотациями инструментов:

  Метод HTTP	readOnlyHint	idempotentHint	destructiveHint
  GET, HEAD	true	true	false
  PUT, PATCH	false	true	false
  DELETE	false	true	true
  POST	false	false	false

Как платформа обрабатывает обновления спецификаций?

Когда спецификация в ApiSpecPath изменяется — либо потому, что вы повторно развернули файл, либо потому, что вы загрузили новую версию через портал, — платформа:

1. Обнаруживает изменение.
2. Повторно разбирает спецификацию и пересчитывает список инструментов.
3. Хэширует новый список инструментов (SHA-256) и сравнивает его с предыдущим хэшом.
4. Если хэш изменился, отправляет notifications/tools/list_changed событие каждому подключенного клиента MCP.

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

Для чего служит платформа /.well-known/oauth-protected-resource?

Платформа публикует защищенные метаданные ресурсов (PRM), чтобы клиенты MCP могли узнать, где получить маркер доступа. Содержимое исходит от:

• Проверка подлинности службы приложений, если она включена в приложении. Платформа публикует метаданные настроенного поставщика удостоверений.
• SiteAuthБлокировка aiIntegrationпри отключении проверки подлинности службы приложений. См . статью "Настройка проверки подлинности без проверки подлинности службы приложений".

Если ни один из них не настроен, платформа не публикует конечную точку, и клиентам не предлагается пройти аутентификацию OAuth.

Каковы ограничения?

Справочник: схема aiIntegration

Дальнейшие действия

• Настройка встроенной авторизации сервера MCP
• Защитите вызовы MCP в Visual Studio Code с помощью аутентификации Microsoft Entra
• Серверы Службы приложений в качестве протокола контекста модели (MCP)
• Выберите службу Azure для вашего сервера MCP