Ligue o seu cluster Azure Kubernetes Service (AKS) a agentes de IA usando o servidor Model Context Protocol (MCP)

A forma mais fácil de começar com AKS-MCP é através da Extensão de Serviço Azure Kubernetes para VS Code. A extensão AKS gere automaticamente downloads binários, atualizações e configurações, garantindo que tem sempre a versão mais recente com as definições ótimas.

Passo 1: Instalar a extensão AKS

1. Abre o VS Code e vai a Extensões (Ctrl+Shift+X no Windows/Linux ou Cmd+Shift+X no macOS).
2. Pesquisar por Azure Kubernetes Service.
3. Instala a extensão oficial Microsoft AKS.

Passo 2: Iniciar o AKS-MCP Server

1. Abra a paleta de comandos (Ctrl+Shift+P no Windows/Linux ou Cmd+Shift+P no macOS).
2. Pesquisar e executar: AKS: Configurar o servidor AKS MCP.

Após a instalação bem-sucedida, o servidor aparece em MCP: List Servers (via Command Palette). A partir daí, podes iniciar o servidor MCP ou ver o seu estado.

Passo 3: Começar a usar AKS-MCP

Uma vez iniciado, o servidor MCP aparece no menu suspenso Copilot Chat: Configure Tools em MCP Server: AKS MCP, pronto para melhorar prompts contextuais com base no seu ambiente AKS. Por defeito, todas as ferramentas de servidor AKS-MCP estão ativadas. Podes rever a lista de ferramentas disponíveis e desativar as que não são necessárias para o teu cenário.

Experimenta um prompt como "Lista todos os meus clusters AKS" para começares a usar ferramentas do servidor AKS-MCP.

Para uso binário direto sem a extensão VS Code:

Passo 1: Descarregar o Binário

Escolha a sua plataforma e descarregue o AKS-MCP binário mais recente:

Passo 2: Configurar VS Code

Crie um .vscode/mcp.json ficheiro na raiz do seu espaço de trabalho com o caminho para o seu binário descarregado:

Configuração específica do espaço de trabalho (recomendada para uso específico do projeto):

{
  "servers": {
    "aks-mcp-server": {
      "type": "stdio",
      "command": "<path-to-binary>",
      "args": [
        "--transport", "stdio"
      ]
    }
  }
}

Configuração ao nível do utilizador (persistente em todos os espaços de trabalho):

Adicione às suas Definições de Utilizador JSON do VS Code (Ctrl+, ou Cmd+,, depois procure por "mcp"):

{
  "github.copilot.chat.mcp.servers": {
    "aks-mcp-server": {
      "type": "stdio",
      "command": "<path-to-binary>",
      "args": [
        "--transport", "stdio"
      ]
    }
  }
}

Passo 3: Carregar as ferramentas do servidor AKS-MCP

1. Reiniciar o VS Code para carregar a nova configuração do servidor MCP.
2. Abre o GitHub Copilot no VS Code e muda para o modo Agente.
3. Selecione o botão Ferramentas para ver a lista de ferramentas disponíveis.
4. Verifique se as ferramentas AKS-MCP aparecem na lista.
5. Experimenta um prompt como: "Lista todos os meus clusters AKS na subscrição xxx."

Pode correr o servidor AKS-MCP usando a imagem oficial Docker do Docker MCP Toolkit ou como uma configuração MCP containerizada.

Opção 1: Docker MCP Toolkit

1. Abre o Docker Desktop.
2. Selecione MCP Toolkit na barra lateral esquerda.
3. Pesquise por "aks" na aba Catálogo.
4. Selecione o cartão de servidor AKS-MCP.
5. Ativa o servidor selecionando + no canto superior direito.
6. Configure o servidor usando o separador Configuração :
   • azure_dir[REQUIRED]: Caminho absoluto para o seu diretório de credenciais Azure (por exemplo, /home/user/.azure)
   • kubeconfig[REQUIRED]: Caminho absoluto para o teu ficheiro kubeconfig (por exemplo, /home/user/.kube/config)
   • access_level[REQUIRED]: Definir para readonly, readwrite, ou admin conforme necessário
   • container_user[OPTIONAL]: Nome de utilizador ou UID para executar o contentor como (o padrão é mcp). Use o ID de utilizador do seu host (por exemplo, 1000) se estiver a correr o Docker Engine no Linux.

Opção 2: Configuração MCP contentorizada

Montar credenciais a partir do anfitrião (recomendado):

{
  "mcpServers": {
    "aks": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--user", "<your-user-id>",
        "-v", "~/.azure:/home/mcp/.azure",
        "-v", "~/.kube:/home/mcp/.kube",
        "ghcr.io/azure/aks-mcp:latest",
        "--transport", "stdio"
      ]
    }
  }
}

Para obter credenciais dentro do contentor, omita as montagens de volume e execute os seguintes comandos após iniciar o contentor.

# Login to Azure CLI
docker exec -it <container-id> az login --use-device-code

# Get kubeconfig
docker exec -it <container-id> az aks get-credentials -g <resource-group> -n <cluster-name>

Para outros clientes de IA compatíveis com MCP, como o Claude Desktop, configure o servidor na sua configuração MCP:

{
  "mcpServers": {
    "aks": {
      "command": "<path-to-binary>",
      "args": [
        "--transport", "stdio"
      ]
    }
  }
}

Também podes executar o servidor diretamente a partir da linha de comandos:

./aks-mcp --transport stdio

Opções de linha de comandos:

Variáveis de ambiente:

• USE_LEGACY_TOOLS: Definir para true usar ferramentas especializadas legadas em vez de ferramentas unificadas (por defeito: false)
• São suportadas variáveis padrão do ambiente de autenticação Azure (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID)

A Identidade de Carga de Trabalho fornece autenticação sem palavra-passe ao ligar uma Conta de Serviço Kubernetes a uma Identidade Gerida Azure.

1. Ativar o OIDC no seu cluster AKS

az aks update \
  --resource-group <your-resource-group> \
  --name <your-aks-cluster> \
  --enable-oidc-issuer \
  --enable-workload-identity

2. Criar uma Identidade Gerida e atribuir permissões RBAC

# Create identity
az identity create --resource-group <your-resource-group> --name aks-mcp-identity --location <your-location>

# Get IDs
IDENTITY_CLIENT_ID=$(az identity show --resource-group <your-resource-group> --name aks-mcp-identity --query "clientId" -o tsv)
IDENTITY_PRINCIPAL_ID=$(az identity show --resource-group <your-resource-group> --name aks-mcp-identity --query "principalId" -o tsv)

# Assign Reader role (use Contributor for readwrite access)
az role assignment create --role "Reader" --assignee-object-id $IDENTITY_PRINCIPAL_ID --assignee-principal-type ServicePrincipal --scope "/subscriptions/<subscription-id>"

3. Criar uma credencial de identidade federada

AKS_OIDC_ISSUER=$(az aks show --resource-group <your-resource-group> --name <your-aks-cluster> --query "oidcIssuerProfile.issuerUrl" -o tsv)

az identity federated-credential create \
  --name "aks-mcp-federated-credential" \
  --identity-name aks-mcp-identity \
  --resource-group <your-resource-group> \
  --issuer $AKS_OIDC_ISSUER \
  --subject "system:serviceaccount:aks-mcp:aks-mcp" \
  --audience api://AzureADTokenExchange

4. Instalar com Identidade de Carga de Trabalho ativada

helm install aks-mcp . \
  --namespace aks-mcp \
  --create-namespace \
  --set workloadIdentity.enabled=true \
  --set azure.clientId=$IDENTITY_CLIENT_ID \
  --set azure.subscriptionId=<your-subscription-id>

Ative a autenticação OAuth para exigir login do utilizador para operações de leitura, escrita ou administração:

helm install aks-mcp . \
  --namespace aks-mcp \
  --create-namespace \
  --set app.accessLevel=readwrite \
  --set oauth.enabled=true \
  --set oauth.tenantId=<your-tenant-id> \
  --set oauth.clientId=<your-oauth-client-id> \
  --set azure.subscriptionId=<your-subscription-id>

Utilize um segredo do Kubernetes contendo credenciais de Service Principal:

# Create secret first
kubectl create secret generic azure-credentials \
  --namespace aks-mcp \
  --from-literal=tenant-id=<your-tenant-id> \
  --from-literal=client-id=<your-client-id> \
  --from-literal=client-secret=<your-client-secret> \
  --from-literal=subscription-id=<your-subscription-id>

# Install with existing secret
helm install aks-mcp . \
  --namespace aks-mcp \
  --set app.accessLevel=readonly \
  --set azure.existingSecret=azure-credentials

Passe as credenciais diretamente através dos valores do Helm (não recomendado para produção):

helm install aks-mcp . \
  --namespace aks-mcp \
  --create-namespace \
  --set azure.tenantId=<your-tenant-id> \
  --set azure.clientId=<your-client-id> \
  --set azure.clientSecret=<your-client-secret>

Código VS com extensão AKS

1. Abra a paleta de comandos (Ctrl+Shift+P no Windows/Linux ou Cmd+Shift+P no macOS).
2. Executa MCP: Servidores de Listas.
3. Selecione o AKS MCP da lista.
4. Seleciona Parar Servidor para parar o servidor em execução.
5. Para remover a configuração, selecione Eliminar Configuração do Servidor.

Em alternativa, remova manualmente a configuração do servidor:

1. Abra o seu .vscode/mcp.json ficheiro ou as Definições de Utilizador do VS Code.
2. Apaga a entrada do aks-mcp-server do objeto servers ou github.copilot.chat.mcp.servers.
3. Apaga o AKS-MCP binário do teu sistema (a localização varia consoante o método de instalação).

Docker

Se estiver a usar o Docker MCP Toolkit:

1. Abre o Docker Desktop.
2. Selecione MCP Toolkit na barra lateral esquerda.
3. Encontra o servidor AKS-MCP e desativa-o.

Se usar uma configuração containerizada, pare e remova o contentor:

docker stop <container-id>
docker rm <container-id>

Outros Clientes MCP

Remova a entrada aks ou aks-mcp do ficheiro de configuração do cliente MCP (por exemplo, Claude Desktop claude_desktop_config.json).

Remover a libertação do Helm

helm uninstall aks-mcp --namespace aks-mcp

Limpar o espaço de nomes (opcional)

kubectl delete namespace aks-mcp

Limpar recursos de Azure (somente Identidade de Trabalho)

Se configurou a Identidade da Carga de Trabalho, remova os recursos Azure associados:

# Delete the federated credential
az identity federated-credential delete \
  --name "aks-mcp-federated-credential" \
  --identity-name aks-mcp-identity \
  --resource-group <your-resource-group>

# Remove role assignments
IDENTITY_PRINCIPAL_ID=$(az identity show --resource-group <your-resource-group> --name aks-mcp-identity --query "principalId" -o tsv)
az role assignment delete --assignee $IDENTITY_PRINCIPAL_ID --scope "/subscriptions/<subscription-id>"

# Delete the managed identity
az identity delete --resource-group <your-resource-group> --name aks-mcp-identity

Eliminar o segredo do Kubernetes (apenas Service Principal)

Caso tenha criado um segredo para credenciais de Service Principal:

kubectl delete secret azure-credentials --namespace aks-mcp