AKS-MCP

The AKS-MCP is a Model Context Protocol (MCP) server that enables AI assistants to interact with Azure Kubernetes Service (AKS) clusters. It serves as a bridge between AI tools (like GitHub Copilot, Claude, and other MCP-compatible AI assistants) and AKS, translating natural language requests into AKS operations and returning the results in a format the AI tools can understand.

It allows AI tools to:

• Operate (CRUD) AKS resources
• Retrieve details related to AKS clusters (VNets, Subnets, NSGs, Route Tables, etc.)
• Manage Azure Fleet operations for multi-cluster scenarios

Supported Deployment Model and Security Considerations

AKS-MCP is designed to be run locally, by a single trusted user, as a bridge between that user's own AI assistant and their own Azure/AKS resources. This is the only deployment model the project supports and hardens for.

The trust boundary

AKS-MCP executes command-line tools — including az, kubectl, helm, cilium, and hubble — using the identity of the process it runs as. It does not perform per-caller authorization, and it does not attempt to sandbox the commands it runs. Therefore:

Anyone who can invoke AKS-MCP tools effectively has the full Azure and Kubernetes privileges of the identity AKS-MCP is running under.

This includes the ability to obtain reusable credentials. For example, in readwrite or admin mode a caller can reach Azure Resource Manager and AKS with the server identity's full authority, and kubectl or helm can be used to read Secrets, mint service account tokens, or deploy arbitrary workloads into the cluster. This is an inherent consequence of exposing a CLI execution surface — it is not prevented by --access-level.

Specific credential-returning Azure CLI commands (such as az account get-access-token and az aks get-credentials) are rejected by an explicit denylist. That denylist reduces accidental exposure — it is not a security boundary, it does not cover the kubectl, helm, cilium, or hubble surfaces, and it must not be relied upon to contain an untrusted caller.

Treat the ability to call AKS-MCP as equivalent to handing over a shell that is already logged in as the server identity.

Network exposure and local authority

Removing HTTP/SSE transports and the official remote deployment artifacts removes the supported network-reachable service and its remote-caller threat model. In the supported configuration, AKS-MCP has no listener that accepts requests from the network.

This does not make the local MCP client, its prompts, or --access-level an authorization boundary. A person or process that controls the local client, its server configuration, or AKS-MCP can normally run the same CLI commands under the same identity without AKS-MCP. Protecting the workstation, client configuration, and local credentials remains the operator's responsibility.

What --access-level is and is not

--access-level (readonly / readwrite / admin) is a guardrail to reduce accidental damage from an AI assistant that misinterprets a request. It is not a security boundary against a deliberately malicious caller, and it must not be relied upon to contain an untrusted party. Do not expose AKS-MCP to callers you would not grant the underlying Azure/Kubernetes credentials to directly.

Recommended (supported) setup

• Run as a local subprocess, launched on demand by your local MCP client.
• Authenticate with your own developer identity via az login.
• Grant the identity only the Azure/Kubernetes permissions you actually need.

Unsupported deployment models

AKS-MCP supports only stdio and must be launched as a local subprocess by an MCP client. Do not expose it through HTTP, SSE, a container service, Helm, Kubernetes, a proxy, or a gateway. Any third-party bridge is outside the project's security and support boundary.

How it works

AKS-MCP connects to Azure using the Azure SDK and provides a set of tools that AI assistants can use to interact with AKS resources. It leverages the Model Context Protocol (MCP) to facilitate this communication, enabling AI tools to make API calls to Azure and interpret the responses.

Azure CLI Authentication

AKS-MCP uses Azure CLI (az) for AKS operations. Azure CLI authentication is attempted in this order:

1. Service Principal (client secret): When AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID environment variables are present, a service principal login is performed using the following command: az login --service-principal -u CLIENT_ID -p CLIENT_SECRET --tenant TENANT_ID

2. Workload Identity (federated token): When AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_FEDERATED_TOKEN_FILE environment variables are present, a federated token login is performed using the following command: az login --service-principal -u CLIENT_ID --tenant TENANT_ID --federated-token TOKEN

3. User-assigned Managed Identity (managed identity client ID): When only AZURE_CLIENT_ID environment variable is present, a user-assigned managed identity login is performed using the following command: az login --identity -u CLIENT_ID

4. System-assigned Managed Identity: When AZURE_MANAGED_IDENTITY is set to system, a system-assigned managed identity login is performed using the following command: az login --identity

5. Existing Login: When none of the above environment variables are set, AKS-MCP assumes you have already authenticated (for example, via az login) and uses the existing session.

Optional subscription selection:

• If AZURE_SUBSCRIPTION_ID is set, AKS-MCP will run az account set --subscription SUBSCRIPTION_ID after login.

Notes and security:

• The federated token file must be exactly /var/run/secrets/azure/tokens/azure-identity-token and is strictly validated; other paths are rejected.
• After each login, AKS-MCP verifies authentication with az account show --query id -o tsv.
• Ensure the Azure CLI is installed and on PATH.

Environment variables used:

• AZURE_TENANT_ID
• AZURE_CLIENT_ID
• AZURE_CLIENT_SECRET
• AZURE_FEDERATED_TOKEN_FILE
• AZURE_SUBSCRIPTION_ID
• AZURE_MANAGED_IDENTITY (set to system to opt into system-assigned managed identity)

Available Tools

The AKS-MCP server provides consolidated tools for interacting with AKS clusters. By default, the server uses unified tools (call_az for Azure operations and call_kubectl for Kubernetes operations) which provide a more flexible interface. For backward compatibility, you can enable legacy specialized tools by setting the environment variable USE_LEGACY_TOOLS=true.

Some tools will require read-write or admin permissions to run debugging pods on your cluster. To enable read-write or admin permissions for the AKS-MCP server, add the access level parameter to your MCP configuration file:

1. Navigate to your mcp.json file, or go to MCP: List Servers -> AKS-MCP -> Show Configuration Details in the Command Palette (For VSCode; Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS).
2. In the "args" section of AKS-MCP, add the following parameters: "--access-level", "readwrite" / "admin"

For example:

"args": [
  "--access-level",
  "readwrite"
]

These tools have been designed to provide comprehensive functionality through unified interfaces:

Tool: call_az (default, available when USE_LEGACY_TOOLS is not set or set to false)

Unified tool for executing Azure CLI commands directly. This tool provides a flexible interface to run any Azure CLI command.

Parameters:

• cli_command: The complete Azure CLI command to execute (e.g., az aks list --resource-group myRG, az vm list --subscription <sub-id>)
• timeout: Optional timeout in seconds (default: 120)

Example Usage:

{
  "cli_command": "az aks list --resource-group myResourceGroup --output json"
}

Access Control:

• readonly: Only read operations are allowed
• readwrite/admin: Both read and write operations are allowed

Important: Commands must be simple Azure CLI invocations without shell features like pipes (|), redirects (>, <), command substitution, or semicolons (;).

Tool: az_aks_operations (available when USE_LEGACY_TOOLS=true)

Unified tool for managing Azure Kubernetes Service (AKS) clusters and related operations.

Available Operations:

• Read-Only (all access levels):

  • show: Show cluster details
  • list: List clusters in subscription/resource group
  • get-versions: Get available Kubernetes versions
  • check-network: Perform outbound network connectivity check
  • nodepool-list: List node pools in cluster
  • nodepool-show: Show node pool details
  • account-list: List Azure subscriptions

• Read-Write (readwrite/admin access levels):

  • create: Create new cluster
  • delete: Delete cluster
  • scale: Scale cluster node count
  • start: Start a stopped cluster
  • stop: Stop a running cluster
  • update: Update cluster configuration
  • upgrade: Upgrade Kubernetes version
  • nodepool-add: Add node pool to cluster
  • nodepool-delete: Delete node pool
  • nodepool-scale: Scale node pool
  • nodepool-upgrade: Upgrade node pool
  • account-set: Set active subscription
  • login: Azure authentication

• Admin-Only (admin access level):

  • get-credentials: Get cluster credentials for kubectl access

Tool: aks_network_resources

Unified tool for getting Azure network resource information used by AKS clusters.

Available Resource Types:

• all: Get information a