Поделиться через


Руководство: Использование MCP с динамическими сеансами (оболочка)

Это важно

Сервер MCP под управлением платформы для динамических сеансов находится в предварительной версии. Версия API 2025-02-02-preview и свойства mcpServerSettings могут быть изменены.

В этом руководстве показано, как создать пул сеансов оболочки с включенным сервером MCP с поддержкой платформы, подключиться к нему и выполнять команды оболочки удаленно как из интерфейса командной строки, так и из чата GitHub Copilot в VS Code.

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

Инструмент Description
launchShell Создает новую среду оболочки и возвращает environmentId
runShellCommandInRemoteEnvironment Выполняет команду оболочки в существующей среде

Изучив это руководство, вы:

  • Создание пула сеансов оболочки с включенным сервером MCP
  • Получение конечной точки и ключа API MCP
  • Инициализация подключения MCP и выполнение команд оболочки с помощью JSON-RPC
  • Подключение сервера MCP к GitHub Copilot в VS Code

Предпосылки

Требование Description
Учетная запись Azure Учетная запись Azure с активной подпиской. Создайте его бесплатно.
Azure CLI (Интерфейс командной строки для Azure) Установите Azure CLI.
завиток curl (предустановлено в большинстве систем Linux и macOS).
jq Jq Обработчик JSON, используемый для анализа ответов API.
VS Code Visual Studio Code с расширением GitHub Copilot (для раздела интеграции Copilot).

Настройка

  1. Обновите Azure CLI и установите расширение "Приложения контейнеров":

    az upgrade
    az provider register --namespace Microsoft.App
    az extension add --name containerapp --allow-preview true --upgrade
    
  2. Войдите и задайте подписку:

    az login
    SUBSCRIPTION_ID=$(az account show --query id --output tsv)
    az account set -s $SUBSCRIPTION_ID
    
  3. Задайте переменные для этого руководства. Замените заполнители вашими данными.

    RESOURCE_GROUP=<RESOURCE_GROUP_NAME>
    SESSION_POOL_NAME=<SESSION_POOL_NAME>
    LOCATION=<LOCATION>
    
    Заполнитель Description
    <RESOURCE_GROUP_NAME> Имя группы ресурсов Azure.
    <SESSION_POOL_NAME> Имя пула сеансов (например, my-shell-sessions).
    <LOCATION> Регион Azure, поддерживающий динамические сеансы (например, westus2).
  4. Создайте группу ресурсов:

    az group create --name $RESOURCE_GROUP --location $LOCATION
    

Создайте пул сеансов командной оболочки с сервером MCP

Разверните пул сеансов с помощью шаблона ARM с включенным сервером MCP.

  1. Создайте файл с именем deploy.json:

    {
        "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
        "contentVersion": "1.0.0.0",
        "parameters": {
            "name": { "type": "String" },
            "location": { "type": "String" }
        },
        "resources": [
            {
                "type": "Microsoft.App/sessionPools",
                "apiVersion": "2025-02-02-preview",
                "name": "[parameters('name')]",
                "location": "[parameters('location')]",
                "properties": {
                    "poolManagementType": "Dynamic",
                    "containerType": "Shell",
                    "scaleConfiguration": {
                        "maxConcurrentSessions": 5
                    },
                    "sessionNetworkConfiguration": {
                        "status": "EgressEnabled"
                    },
                    "dynamicPoolConfiguration": {
                        "lifecycleConfiguration": {
                            "lifecycleType": "Timed",
                            "coolDownPeriodInSeconds": 300
                        }
                    },
                    "mcpServerSettings": {
                        "isMCPServerEnabled": true
                    }
                }
            }
        ]
    }
    

    Замечание

    Ключевые свойства в этом шаблоне:

    • containerType: "Shell" — создает сеансы с средой оболочки Linux.
    • mcpServerSettings.isMCPServerEnabled: true — включает конечную точку MCP, управляемую платформой.
    • coolDownPeriodInSeconds: 300 — сеансы уничтожаются через 5 минут бездействия.
  2. Разверните шаблон:

    az deployment group create \
        --resource-group $RESOURCE_GROUP \
        --template-file deploy.json \
        --parameters name=$SESSION_POOL_NAME location=$LOCATION
    

Получение конечной точки сервера MCP

После развертывания получите URL-адрес конечной точки MCP для пула сеансов.

MCP_ENDPOINT=$(az rest --method GET \
    --uri "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionPools/$SESSION_POOL_NAME" \
    --uri-parameters api-version=2025-02-02-preview \
    --query "properties.mcpServerSettings.mcpServerEndpoint" -o tsv)

Получение учетных данных сервера MCP

Сервер MCP, управляемый платформой, использует проверку подлинности ключа API через x-ms-apikey заголовок. Этот подход отличается от аутентификации с использованием токена типа носителя, которая применяется в стандартных API-интерфейсах управления пулом сеансов.

API_KEY=$(az rest --method POST \
    --uri "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionPools/$SESSION_POOL_NAME/fetchMCPServerCredentials" \
    --uri-parameters api-version=2025-02-02-preview \
    --query "apiKey" -o tsv)

Предупреждение

Рассматривайте ключ API как секрет. Не добавляйте его в систему управления версиями или делайте общедоступным. Ключ аутентифицирует все вызовы инструментов MCP в контексте вашего пула сеансов.

Инициализация сервера MCP

initialize Отправьте запрос JSON-RPC, чтобы установить подключение MCP:

curl -sS -X POST "$MCP_ENDPOINT" \
    -H "Content-Type: application/json" \
    -H "x-ms-apikey: $API_KEY" \
    -d '{ "jsonrpc": "2.0", "id": "1", "method": "initialize" }'

Вы увидите ответ, который включает в себя следующее:

  • protocolVersion: 2025-03-26
  • serverInfo.name: Microsoft Container Apps MCP Server
  • capabilities.tools: { "call": true, "list": true }

Запуск среды оболочки

Создайте новую среду оболочки для выполнения команд.

ENVIRONMENT_RESPONSE=$(curl -sS -X POST "$MCP_ENDPOINT" \
    -H "Content-Type: application/json" \
    -H "x-ms-apikey: $API_KEY" \
    -d '{ "jsonrpc": "2.0", "id": "2", "method": "tools/call", "params": { "name": "launchShell", "arguments": {} } }')

echo $ENVIRONMENT_RESPONSE

Извлеките environmentId из ответа для использования в последующих командах.

ENVIRONMENT_ID=$(echo $ENVIRONMENT_RESPONSE | jq -r '.result.structuredContent.environmentId')
echo $ENVIRONMENT_ID

Выполнение команд оболочки

Используйте $ENVIRONMENT_ID из предыдущего шага для выполнения команд в удаленной среде оболочки.

curl -sS -X POST "$MCP_ENDPOINT" \
    -H "Content-Type: application/json" \
    -H "x-ms-apikey: $API_KEY" \
    -d '{
        "jsonrpc": "2.0",
        "id": "3",
        "method": "tools/call",
        "params": {
            "name": "runShellCommandInRemoteEnvironment",
            "arguments": {
                "environmentId": "'"$ENVIRONMENT_ID"'",
                "shellCommand": "echo Hello from Azure Container Apps Shell Session!"
            }
        }
    }'

Ответ содержит результаты команды в stdout поле.

Попробуйте выполнить дополнительные команды:

# Check the operating system
curl -sS -X POST "$MCP_ENDPOINT" \
    -H "Content-Type: application/json" \
    -H "x-ms-apikey: $API_KEY" \
    -d '{
        "jsonrpc": "2.0",
        "id": "4",
        "method": "tools/call",
        "params": {
            "name": "runShellCommandInRemoteEnvironment",
            "arguments": {
                "environmentId": "'"$ENVIRONMENT_ID"'",
                "shellCommand": "cat /etc/os-release && uname -a"
            }
        }
    }'

Замечание

Средство runShellCommandInRemoteEnvironment принимает shellCommand строку или execCommandAndArgs массив для команд с аргументами. Используйте shellCommand для простых команд и execCommandAndArgs, когда требуется строгий контроль над экранированием аргументов.

Подключение к GitHub Copilot в VS Code

Сервер пула сеансов MCP можно подключить к GitHub Copilot для интерфейса естественного языка к среде выполнения команд оболочки.

  1. Создайте .vscode/mcp.json в проекте:

    {
        "servers": {
            "aca-shell-sessions": {
                "type": "http",
                "url": "<MCP_ENDPOINT>",
                "headers": {
                    "x-ms-apikey": "<API_KEY>"
                }
            }
        }
    }
    

    Замените <MCP_ENDPOINT> и <API_KEY> на значения из предыдущих шагов.

    Предупреждение

    Не добавляйте ключи API MCP в систему управления исходным кодом. Используйте переменные среды или диспетчер секретов в рабочей среде. Добавьте .vscode/mcp.json в свой .gitignore.

  2. Откройте VS Code, а затем откройте чат Copilot в режиме агента .

  3. Убедитесь, что aca-shell-sessions отображается в списке инструментов.

  4. Тестирование с помощью запросов, таких как:

    • "Запустите оболочку и покажите мне использование диска"
    • Выполните команду оболочки для перечисления всех переменных среды.
    • "Проверьте, какие пакеты установлены в среде оболочки"

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

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

az group delete --resource-group $RESOURCE_GROUP