Conectar seu cluster do AKS (Serviço de Kubernetes do Azure) a agentes de IA usando o servidor MCP (Model Context Protocol)

A maneira mais fácil de começar a usar AKS-MCP é por meio da Extensão de Serviço de Kubernetes do Azure para VS Code. A extensão do AKS lida automaticamente com downloads binários, atualizações e configuração, garantindo que você sempre tenha a versão mais recente com configurações ideais.

Etapa 1: instalar a extensão do AKS

1. Abra o VS Code e vá para Extensões (Ctrl+Shift+X no Windows/Linux ou Cmd+Shift+X no macOS).
2. Pesquise pelo Serviço de Kubernetes do Azure.
3. Instale a extensão oficial do Microsoft AKS.

Etapa 2: iniciar o servidor AKS-MCP

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 MCP do AKS.

Após a instalação bem-sucedida, o servidor aparece no MCP: Listar servidores (por meio da Paleta de Comandos). A partir daí, você pode iniciar o servidor MCP ou exibir seu status.

Etapa 3: Começar a usar o AKS-MCP

Uma vez iniciado, o servidor MCP aparece na lista suspensa Copilot Chat: Configurar Ferramentas em MCP Server: AKS MCP, pronto para aprimorar prompts contextuais com base no seu ambiente AKS. Por padrão, todas as ferramentas de servidor AKS-MCP estão habilitadas. Você pode examinar a lista de ferramentas disponíveis e desabilitar todas as que não são necessárias para seu cenário.

Tente um prompt como "Listar todos os meus clusters do AKS" para começar a usar ferramentas do servidor AKS-MCP.

Para uso binário direto sem a extensão vs code:

Etapa 1: Baixar o binário

Escolha sua plataforma e baixe o binário de AKS-MCP mais recente:

Etapa 2: Configurar o VS Code

Crie um .vscode/mcp.json arquivo na raiz da área de trabalho com o caminho do binário que você baixou:

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

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

Configuração no nível do usuário (persistente em todos os workspaces):

Adicione às configurações de usuário do VS Code no JSON (Ctrl+, ou Cmd+, e, em seguida, pesquise por "mcp"):

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

Etapa 3: Carregar as ferramentas do servidor AKS-MCP

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

Você pode executar o servidor AKS-MCP usando a imagem oficial do Docker do Kit de Ferramentas do Docker MCP ou como uma configuração MCP em contêineres.

Opção 1: Kit de Ferramentas do Docker MCP

1. Abra o Docker Desktop.
2. Selecione MCP Toolkit na barra lateral esquerda.
3. Pesquise "aks" na guia Catálogo.
4. Selecione o cartão do servidor AKS-MCP.
5. Habilite o servidor selecionando + no canto superior direito.
6. Configure o servidor usando a guia Configuração :
   • [REQUIRED]azure_dir: caminho absoluto para o diretório de credenciais do Azure (por exemplo, /home/user/.azure)
   • kubeconfig[REQUIRED]: caminho absoluto para o arquivo kubeconfig (por exemplo, /home/user/.kube/config)
   • access_level[REQUIRED]: Definir como readonly, readwrite ou admin conforme necessário
   • [OPTIONAL]container_user: nome de usuário ou UID para executar o contêiner como (o padrão émcp). Utilize o ID de usuário do host (por exemplo, 1000) se estiver executando o Docker Engine no Linux.

Opção 2: Configuração de MCP em contêineres

Montar credenciais do host (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 buscar credenciais dentro do contêiner, omita as montagens de volume e execute os seguintes comandos após iniciar o contêiner:

# 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 configuração do MCP:

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

Você também pode executar o servidor diretamente na linha de comando:

./aks-mcp --transport stdio

Opções de linha de comando:

Variáveis de ambiente:

• USE_LEGACY_TOOLS: definido para true usar ferramentas especializadas herdadas em vez de ferramentas unificadas (padrão: false)
• Há suporte para variáveis de ambiente de autenticação padrão do Azure (AZURE_TENANT_ID, , AZURE_CLIENT_ID, AZURE_CLIENT_SECRET) AZURE_SUBSCRIPTION_ID

A Identidade da Carga de Trabalho fornece autenticação sem senha vinculando um ServiceAccount do Kubernetes a uma Identidade Gerenciada do Azure.

1. Habilitar o OIDC no cluster do AKS

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

2. Criar uma Identidade Gerenciada 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 a Identidade da carga de trabalho habilitada

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>

Habilite a autenticação OAuth para exigir o login do usuário para operações de leitura/gravação ou administrativas.

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>

Use um segredo do Kubernetes que contém as credenciais do 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 por meio 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>

VS Code com extensão do AKS

1. Abra a Paleta de Comandos (Ctrl+Shift+P no Windows/Linux ou Cmd+Shift+P no macOS).
2. Executar MCP: Listar servidores.
3. Selecione o AKS MCP na lista.
4. Selecione Parar Servidor para interromper o servidor em execução.
5. Para remover a configuração, selecione Excluir Configuração do Servidor.

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

1. Abra o .vscode/mcp.json arquivo ou as configurações do usuário do VS Code.
2. Exclua a entrada aks-mcp-server do objeto servers ou github.copilot.chat.mcp.servers.
3. Exclua o binário AKS-MCP do sistema (o local varia de acordo com o método de instalação).

Docker

Se estiver usando o Kit de Ferramentas do Docker MCP:

1. Abra o Docker Desktop.
2. Selecione MCP Toolkit na barra lateral esquerda.
3. Localize o servidor AKS-MCP e desabilite-o.

Se estiver usando uma configuração em contêineres, pare e remova o contêiner:

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

Outros clientes MCP

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

Remover a versão do Helm

helm uninstall aks-mcp --namespace aks-mcp

Limpar o namespace (opcional)

kubectl delete namespace aks-mcp

Limpe recursos do Azure (somente identidade de carga de trabalho)

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

# 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

Exclua o segredo do Kubernetes (somente Entidade de Serviço)

Se você criou um segredo para as credenciais do Service Principal:

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