Conexión del clúster de Azure Kubernetes Service (AKS) a agentes de IA mediante el servidor de Protocolo de contexto de modelo (MCP)

La manera más fácil de empezar a trabajar con AKS-MCP es a través de la extensión de Azure Kubernetes Service para VS Code. La extensión de AKS controla automáticamente las descargas binarias, las actualizaciones y la configuración, lo que garantiza que siempre tiene la versión más reciente con una configuración óptima.

Paso 1: Instalar la extensión de AKS

1. Abra VS Code y vaya a Extensiones (Ctrl+Shift+X en Windows/Linux o Cmd+Shift+X en macOS).
2. Busque Azure Kubernetes Service.
3. Instale la extensión oficial de Microsoft AKS.

Paso 2: Iniciar el servidor de AKS-MCP

1. Abra la paleta de comandos (Ctrl+Shift+P en Windows/Linux o Cmd+Shift+P en macOS).
2. Buscar y ejecutar: AKS: configuración del servidor MCP de AKS.

Tras la instalación correcta, el servidor aparece en MCP: List Servers (a través de la paleta de comandos). Desde allí, puede iniciar el servidor MCP o ver su estado.

Paso 3: Empezar a usar AKS-MCP

Una vez iniciado, el servidor MCP aparece en la lista desplegable Copilot Chat: Configurar herramientas en MCP Server: AKS MCP, listo para mejorar las solicitudes contextuales basadas en el entorno de AKS. De forma predeterminada, todas las herramientas de servidor de AKS-MCP están habilitadas. Puede revisar la lista de herramientas disponibles y deshabilitar cualquiera que no sea necesario para su escenario.

Pruebe un mensaje como "Enumerar todos los clústeres de AKS" para empezar a usar herramientas del servidor de AKS-MCP.

Para el uso binario directo sin la extensión de VS Code:

Paso 1: Descargar el archivo binario

Elija la plataforma y descargue el archivo binario de AKS-MCP más reciente:

Paso 2: Configurar VS Code

Cree un .vscode/mcp.json archivo en la raíz del área de trabajo con la ruta de acceso al archivo binario descargado:

Configuración específica del área de trabajo (recomendada para el uso específico del proyecto):

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

Configuración de nivel de usuario (persistente en todas las áreas de trabajo):

Agregue al JSON de configuración de usuario de VS Code (Ctrl+, o Cmd+, y luego busque "mcp").

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

Paso 3: Cargar las herramientas de servidor de AKS-MCP

1. Reinicie VS Code para cargar la nueva configuración del servidor MCP.
2. Abra GitHub Copilot en VS Code y cambie al modo agente.
3. Seleccione el botón Herramientas para ver la lista de herramientas disponibles.
4. Compruebe que las herramientas de AKS-MCP aparecen en la lista.
5. Pruebe un indicativo como: "Enumera todos mis clústeres de AKS en la suscripción xxx".

Puede ejecutar el servidor de AKS-MCP mediante la imagen oficial de Docker de Docker MCP Toolkit o como una configuración de MCP en contenedor.

Opción 1: Docker MCP Toolkit

1. Abra Docker Desktop.
2. Seleccione MCP Toolkit en la barra lateral izquierda.
3. Busque "aks" en la pestaña Catálogo.
4. Seleccione la tarjeta de servidor AKS-MCP.
5. Habilite el servidor seleccionando + en la esquina superior derecha.
6. Configure el servidor mediante la pestaña Configuración :
   • [REQUIRED]azure_dir: ruta de acceso absoluta al directorio de credenciales de Azure (por ejemplo, /home/user/.azure)
   • kubeconfig[REQUIRED]: ruta de acceso absoluta al archivo kubeconfig (por ejemplo, /home/user/.kube/config)
   • access_level[REQUIRED]: Establecer en readonly, readwrite, o admin según sea necesario.
   • [OPTIONAL]container_user: nombre de usuario o UID para ejecutar el contenedor como (el valor predeterminado es mcp). Use el identificador de usuario del host (por ejemplo, 1000) si ejecuta Docker Engine en Linux.

Opción 2: Configuración de MCP en contenedor

Montaje de credenciales desde el 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 recuperar las credenciales dentro del contenedor, omita los montajes de volúmenes y ejecute los siguientes comandos después de iniciar el contenedor.

# 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 otros clientes de IA compatibles con MCP, como Claude Desktop, configure el servidor en la configuración de MCP:

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

También puede ejecutar el servidor directamente desde la línea de comandos:

./aks-mcp --transport stdio

Opciones de línea de comandos:

Variables de entorno:

• USE_LEGACY_TOOLS: se establece en true para usar herramientas especializadas heredadas en lugar de herramientas unificadas (valor predeterminado: false)
• Se admiten variables de entorno de autenticación de Azure estándar (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID)

La identidad de carga de trabajo proporciona autenticación sin contraseña mediante la vinculación de una cuenta de Kubernetes ServiceAccount a una identidad administrada de Azure.

1. Habilitación de OIDC en el clúster de AKS

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

2. Creación de una identidad administrada y asignación de permisos de 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. Creación de una credencial de identidad 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. Instalación con la identidad de carga de trabajo 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 la autenticación de OAuth para requerir el inicio de sesión de usuario para las operaciones de lectura y escritura o administración:

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>

Usa un secreto de Kubernetes que contenga credenciales de Principal de servicio:

# 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

Transfiera las credenciales directamente a través de valores de Helm (no se recomienda para uso en producción):

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 con la extensión de AKS

1. Abra la paleta de comandos (Ctrl+Shift+P en Windows/Linux o Cmd+Shift+P en macOS).
2. Ejecute MCP: Enumerar servidores.
3. Seleccione AKS MCP en la lista.
4. Seleccione Detener servidor para detener el servidor en ejecución.
5. Para quitar la configuración, seleccione Eliminar configuración del servidor.

Como alternativa, quite manualmente la configuración del servidor:

1. Abra el .vscode/mcp.json archivo o la configuración de usuario de VS Code.
2. Elimine la aks-mcp-server entrada del servers objeto o github.copilot.chat.mcp.servers .
3. Elimine el AKS-MCP binario del sistema (la ubicación varía en función del método de instalación).

Docker

Si usa Docker MCP Toolkit:

1. Abra Docker Desktop.
2. Seleccione MCP Toolkit en la barra lateral izquierda.
3. Busque el servidor AKS-MCP y deshabilítelo.

Si usa una configuración en contenedor, detenga y quite el contenedor:

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

Otros clientes MCP

Quite la entrada aks o aks-mcp del archivo de configuración de su cliente MCP (por ejemplo, de Claude Desktop claude_desktop_config.json).

Eliminar el lanzamiento de Helm

helm uninstall aks-mcp --namespace aks-mcp

Limpieza del espacio de nombres (opcional)

kubectl delete namespace aks-mcp

Limpiar los recursos de Azure (solo identidad de carga de trabajo)

Si configuró Identidad de carga de trabajo, quite los recursos de Azure asociados.

# 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

Elimina el secreto de Kubernetes (solo Principal de Servicio)

Si creó un secreto para las credenciales de la entidad de servicio:

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