Tutorial: Usar o MCP com sessões dinâmicas (Python)

Importante

O servidor MCP gerenciado pela plataforma para sessões dinâmicas está em versão prévia. A versão da API 2025-02-02-preview e as propriedades mcpServerSettings estão sujeitas a alterações.

Este tutorial mostra como criar um pool de sessões com o servidor MCP gerenciado pela plataforma habilitado, conectar-se a ele e executar o código Python remotamente.

Ao contrário dos tutoriais autônomos do servidor MCP, você não escreve nem implanta o código do servidor MCP. A plataforma fornece ferramentas integradas para pools de sessão de Python.

Tool Description
launchShell Cria um novo ambiente e retorna um environmentId
runPythonCodeInRemoteEnvironment Executa código Python em um ambiente existente
runShellCommandInRemoteEnvironment Executa um comando shell em um ambiente existente

Neste tutorial, você:

  • Criar um pool de sessões do Python com o servidor MCP habilitado
  • Recuperar o ponto de extremidade MCP e a chave de API
  • Inicialize a conexão MCP e execute o código Python por meio de JSON-RPC
  • Conectar o servidor MCP ao GitHub Copilot no VS Code

Pré-requisitos

Requirement Description
Conta do Azure Uma conta do Azure com uma assinatura ativa. Crie um gratuitamente.
CLI do Azure Instale a CLI do Azure.
curl curl (pré-instalado na maioria dos sistemas Linux e macOS).
jq jq Processador JSON, usado para analisar respostas de API.
VS Code Visual Studio Code com a extensão GitHub Copilot (para a seção de integração do Copilot).

Configuração

  1. Atualize a CLI do Azure e instale a extensão Aplicativos de Contêiner:

    az upgrade
az provider register --namespace Microsoft.App
az extension add --name containerapp --allow-preview true --upgrade

  2. Entre e defina sua assinatura:

    az login
SUBSCRIPTION_ID=$(az account show --query id --output tsv)
az account set -s $SUBSCRIPTION_ID

  3. Defina variáveis para este tutorial. Substitua os espaços reservados pelos seus valores:

    RESOURCE_GROUP=<RESOURCE_GROUP_NAME>
SESSION_POOL_NAME=<SESSION_POOL_NAME>
LOCATION=<LOCATION>

  4. Crie um grupo de recursos:

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

Criar um pool de sessões do Python com o servidor MCP

Implante um pool de sessões usando um modelo do ARM com o MCP habilitado.

  1. Crie um arquivo chamado 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": "PythonLTS",
                "scaleConfiguration": {
                    "maxConcurrentSessions": 5
                },
                "sessionNetworkConfiguration": {
                    "status": "EgressEnabled"
                },
                "dynamicPoolConfiguration": {
                    "lifecycleConfiguration": {
                        "lifecycleType": "Timed",
                        "coolDownPeriodInSeconds": 300
                    }
                },
                "mcpServerSettings": {
                    "isMCPServerEnabled": true
                }
            }
        }
    ]
}

    Observação

    Principais propriedades neste modelo:

    • containerType: "PythonLTS": cria sessões com um runtime do Python.
    • mcpServerSettings.isMCPServerEnabled: true: habilita o endpoint MCP gerenciado pela plataforma.
    • coolDownPeriodInSeconds: 300: as sessões são destruídas após 5 minutos de inatividade.

  2. Implante o modelo:

Use um modelo do ARM para criar um pool de sessões do Python com o servidor MCP habilitado.

  1. Crie um arquivo de modelo de implantação chamado deploy.json:

    {
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "name": { "type": "String" },
        "location": { "type": "String" }
    },
    "resources": [
          {
            "type": "Microsoft.App/sessionPools",
            "apiVersion": "2025-10-02-preview",
            "name": "[parameters('name')]",
            "location": "[parameters('location')]",
            "properties": {
                "poolManagementType": "Dynamic",
                "containerType": "PythonLTS", # Set the "containerType" property to "PythonLTS"
                "scaleConfiguration": {
                    "maxConcurrentSessions": 5
                },
                "sessionNetworkConfiguration": {
                    "status": "EgressEnabled"
                },
                "dynamicPoolConfiguration": {
                    "lifecycleConfiguration": {
                        "lifecycleType": "Timed",
                        "coolDownPeriodInSeconds": 300
                    }
                },
                "mcpServerSettings": { 
                    "isMCPServerEnabled": true # Add the "mcpServerSettings" section to enable the MCP server
                }
            }
        }
    ]
}

  2. Implantar o modelo do ARM.

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

Obter o endpoint do servidor MCP

Após a implantação, recupere a URL do endpoint MCP para o pool de sessões.

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-10-02-preview --query "properties.mcpServerSettings.mcpServerEndpoint" -o tsv)

Obter credenciais do servidor MCP

O servidor MCP gerenciado pela plataforma usa a autenticação de chave de API por meio do x-ms-apikey cabeçalho. Esse método de autenticação difere da autenticação de token de portador que as APIs de gerenciamento do pool de sessão padrão usam.

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-10-02-preview --query "apiKey" -o tsv)

Aviso

Trate a chave de API como um segredo. Não faça commit no controle do código-fonte nem compartilhe-o publicamente. A chave autentica todas as invocações da ferramenta MCP no pool de sessões.

Inicializar o servidor MCP

Envie a solicitação initialize JSON-RPC para estabelecer a conexão 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" }'

Você deverá ver uma resposta que inclua:

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

Iniciar um ambiente do Python

Crie um novo ambiente do Python:

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

Extraia o environmentId do campo structuredContent na resposta. Você precisa dessa ID para todos os comandos subsequentes.

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

Observação

A launchShell ferramenta gera um identificador de ambiente exclusivo. A sessão real é alocada "lentamente". Quando você executa seu primeiro comando, o pool de sessão atribui um contêiner isolado do Hyper-V para lidar com ele.

Executar comandos do Python

Para executar o código Python no ambiente remoto, use o $ENVIRONMENT_ID do passo anterior.

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": "runPythonCodeInRemoteEnvironment",
            "arguments": {
                "environmentId": "'"$ENVIRONMENT_ID"'",
                "pythonCode": "import sys; print(f\"Python {sys.version}\")"
            }
        }
    }'

A resposta inclui resultados de comando no campo stdout dentro de structuredContent.

Experimente um exemplo mais complexo:

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": "runPythonCodeInRemoteEnvironment",
            "arguments": {
                "environmentId": "'"$ENVIRONMENT_ID"'",
                "pythonCode": "import math\nresults = {n: math.factorial(n) for n in range(1, 11)}\nfor k, v in results.items():\n    print(f\"{k}! = {v}\")"
            }
        }
    }'

Conectar-se ao GitHub Copilot no VS Code

Você pode conectar o servidor MCP do pool de sessões ao GitHub Copilot para ter uma interface de linguagem natural com o ambiente de execução de código.

  1. Crie .vscode/mcp.json em seu projeto:

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

    Substitua <MCP_ENDPOINT> e <API_KEY> pelos valores das etapas anteriores.

    Aviso

    Não faça commit das chaves de API do MCP no controle do código-fonte. Use variáveis de ambiente ou um gerenciador de segredos em produção. Adicione .vscode/mcp.json ao seu .gitignore.

  2. Abra o VS Code e, em seguida, abra o Copilot Chat no modo Agente .

  3. Verifique se aca-python-sessions está na lista de ferramentas.

  4. Teste com prompts como:

    • "Inicie um ambiente python e calcule os primeiros 20 números fibonacci"
    • "Executar um script python que busca https://api.github.com e imprime os cabeçalhos de resposta"

Limpar os recursos

Ao concluir este tutorial, remova os recursos criados para evitar incorrer em encargos.

az group delete --resource-group $RESOURCE_GROUP

Conteúdo relacionado

  • Last updated on