通过


你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

教程:将 MCP 与动态会话配合使用(shell)

重要

动态会话的平台托管 MCP 服务器处于 预览状态。 API 版本 2025-02-02-previewmcpServerSettings 属性可能会更改。

本教程演示如何创建启用了平台管理的 MCP 服务器的 shell 会话池、连接到它并远程执行 shell 命令-无论是从 CLI 还是从 VS Code 中的 GitHub Copilot Chat。

独立的 MCP 服务器教程不同,不编写或部署 MCP 服务器代码。 该平台为 shell 会话池提供内置工具:

工具 Description
launchShell 创建新的 shell 环境并返回 environmentId
runShellCommandInRemoteEnvironment 在现有环境中执行 shell 命令

在本教程中,你将了解:

  • 创建启用了 MCP 服务器的 shell 会话池
  • 检索 MCP 终结点和 API 密钥
  • 通过 JSON-RPC 初始化 MCP 连接并运行 shell 命令
  • 在 VS Code 中将 MCP 服务器连接到 GitHub Copilot

先决条件

Requirement Description
Azure 帐户 拥有有效订阅的 Azure 帐户。 免费创建一个
Azure CLI 安装 Azure CLI
curl curl (预安装在大多数 Linux 和 macOS 系统上)。
jq jq JSON 处理器,用于分析 API 响应。
VS Code 安装了 GitHub Copilot 扩展的 Visual Studio Code(用于 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 服务器创建 shell 会话池

使用启用了 MCP 服务器的 ARM 模板部署会话池。

  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 shell 环境创建会话。
    • 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 服务器终结点

部署后,检索会话池的 MCP 终结点 URL。

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 服务器通过 x-ms-apikey 标头使用 API 密钥身份验证。 此方法不同于标准会话池管理 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 }

启动 shell 环境

创建新的 shell 环境以运行命令。

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

执行 shell 命令

使用上一步中的$ENVIRONMENT_ID在远程 shell 环境中运行命令。

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

在 VS Code 中连接到 GitHub Copilot

可以将会话池 MCP 服务器连接到 GitHub Copilot,以便将自然语言接口连接到 shell 执行环境。

  1. 在项目中创建 .vscode/mcp.json

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

    <MCP_ENDPOINT><API_KEY> 替换为前面步骤中的值。

    警告

    不要将 MCP API 密钥提交到源代码管理。 在生产环境中使用环境变量或机密管理器。 将 .vscode/mcp.json 添加到您的 .gitignore.

  2. 打开 VS Code,然后在代理模式下打开 Copilot Chat

  3. 验证 aca-shell-sessions 是否显示在“工具”列表中。

  4. 使用提示进行测试,例如:

    • “启动 shell 并显示磁盘使用情况”
    • “运行 shell 命令列出所有环境变量”
    • “检查 shell 环境中安装了哪些包”

清理资源

完成本教程后,请删除创建的资源以避免产生费用。

az group delete --resource-group $RESOURCE_GROUP