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 about all network resources
• vnet: Virtual Network information
• subnet: Subnet information
• nsg: Network Security Group information
• route_table: Route Table information
• load_balancer: Load Balancer information
• private_endpoint: Private endpoint information

Tool: aks_monitoring

Unified tool for Azure monitoring and diagnostics operations for AKS clusters.

Available Operations:

• metrics: List metric values for resources
• resource_health: Retrieve resource health events for AKS clusters
• app_insights: Execute KQL queries against Application Insights telemetry data
• diagnostics: Check if AKS cluster has diagnostic settings configured
• control_plane_logs: Query AKS control plane logs with safety constraints and time range validation

Tool: get_aks_vmss_info

• Get detailed VMSS configuration for node pools in the AKS cluster

Tool: collect_aks_node_logs

Collect system logs from AKS VMSS nodes for debugging and troubleshooting.

Parameters:

• aks_resource_id: AKS cluster resource ID
• vmss_name: VMSS name (obtain from get_aks_vmss_info or kubectl get nodes)
• instance_id: VMSS instance ID
• log_type: Type of logs to collect (kubelet, containerd, kernel, syslog)
• lines: Number of recent log lines to return (default: 500, max: 2000)
• since: Time range for logs (e.g., 1h, 30m, 2d) - takes precedence over lines
• level: Log level filter (ERROR, WARN, INFO)
• filter: Filter logs by keyword (case-insensitive text match)

Example Usage:

{
  "aks_resource_id": "/subscriptions/.../managedClusters/myAKS",
  "vmss_name": "aks-nodepool1-12345678-vmss",
  "instance_id": "0",
  "log_type": "kubelet",
  "since": "1h",
  "level": "ERROR",
  "filter": "ImagePullBackOff"
}

Limitations:

• Only supports Linux VMSS nodes (Windows nodes and standalone VMs are not supported yet)
• Only one run command can execute at a time per VMSS instance

Tool: az_compute_operations

Unified tool for managing Azure Virtual Machines (VMs) and Virtual Machine Scale Sets (VMSS) used by AKS.

Available Operations:

• show: Get details of a VM/VMSS
• list: List VMs/VMSS in subscription or resource group
• get-instance-view: Get runtime status
• start: Start VM
• stop: Stop VM
• restart: Restart VM/VMSS instances
• reimage: Reimage VMSS instances (VM not supported for reimage)

Resource Types: vm (single virtual machines), vmss (virtual machine scale sets)

Tool: az_fleet

Comprehensive Azure Fleet management for multi-cluster scenarios.

Available Operations:

• Fleet Operations: list, show, create, update, delete, get-credentials
• Member Operations: list, show, create, update, delete
• Update Run Operations: list, show, create, start, stop, delete
• Update Strategy Operations: list, show, create, delete
• ClusterResourcePlacement Operations: list, show, get, create, delete

Supports both Azure Fleet management and Kubernetes ClusterResourcePlacement CRD operations.

Tool: aks_detector

Unified tool for executing AKS diagnostic detector operations.

Available Operations:

• list: List all available AKS cluster detectors
• run: Run a specific AKS diagnostic detector
• run_by_category: Run all detectors in a specific category

Parameters:

• operation (required): Operation to perform (list, run, or run_by_category)
• aks_resource_id (required): AKS cluster resource ID
• detector_name (required for run operation): Name of the detector to run
• category (required for run_by_category operation): Detector category
• start_time (required for run and run_by_category operations): Start time in UTC ISO format (within last 30 days)
• end_time (required for run and run_by_category operations): End time in UTC ISO format (within last 30 days, max 24h from start)

Available Categories:

• Best Practices
• Cluster and Control Plane Availability and Performance
• Connectivity Issues
• Create, Upgrade, Delete and Scale
• Deprecations
• Identity and Security
• Node Health
• Storage

Example Usage:

{
  "operation": "list",
  "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx"
}

{
  "operation": "run",
  "aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx",
  "detector_name": "node-health-detector",
  "start_time": "2025-01-15T10:00:00Z",
  "end_time": "2025-01-15T12:00:00Z"
}

Tool: aks_advisor_recommendation

Retrieve and manage Azure Advisor recommendations for AKS clusters.

Available Operations:

• list: List recommendations with filtering options
• report: Generate recommendation reports
• Filter Options: resource_group, cluster_names, category (Cost, HighAvailability, Performance, Security), severity (High, Medium, Low)

Note: All Kubernetes tools (kubectl, helm, cilium, hubble) are enabled by default. Use --enabled-components to selectively enable specific components.

Unified kubectl Tool (Default)

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

Unified tool for executing kubectl commands directly. This tool provides a flexible interface to run any kubectl command with full argument support.

Parameters:

• args: The kubectl command arguments (e.g., get pods, describe node mynode, apply -f deployment.yaml)

Example Usage:

{
  "args": "get pods -n kube-system -o wide"
}

Access Control: Operations are restricted based on the configured access level:

• readonly: Only read operations (get, describe, logs, etc.) are allowed
• readwrite/admin: All operations including mutating commands (create, delete, apply, etc.)

Legacy kubectl Tools (Specialized)

Available when USE_LEGACY_TOOLS=true:

• Read-Only (all access levels):

  • kubectl_resources: View resources (get, describe) - filtered to read-only operations in readonly mode
  • kubectl_diagnostics: Debug and diagnose (logs, events, top, exec, cp)
  • kubectl_cluster: Cluster information (cluster-info, api-resources, api-versions, explain)
  • kubectl_config: Configuration management (diff, auth, config) - filtered to read-only operations in readonly mode

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

  • kubectl_resources: Full resource management (get, describe, create, delete, apply, patch, replace, cordon, uncordon, drain, taint)
  • kubectl_workloads: Workload lifecycle (run, expose, scale, autoscale, rollout)
  • kubectl_metadata: Metadata management (label, annotate, set)
  • kubectl_config: Full configuration management (diff, auth, certificate, config)

Helm

Tool: call_helm

Helm package manager for Kubernetes.

Cilium

Tool: call_cilium

Cilium CLI for eBPF-based networking and security.

Hubble

Tool: call_hubble

Hubble network observability for Cilium.

Tool: inspektor_gadget_observability

Real-time observability tool for Azure Kubernetes Service (AKS) clusters using eBPF.

Available Actions:

• deploy: Deploy Inspektor Gadget to cluster
• undeploy: Remove Inspektor Gadget from cluster
• is_deployed: Check deployment status
• run: Run one-shot gadgets
• start: Start continuous gadgets
• stop: Stop running gadgets
• get_results: Retrieve gadget results
• list_gadgets: List available gadgets

Available Gadgets:

• observe_dns: Monitor DNS requests and responses
• observe_tcp: Monitor TCP connections
• observe_file_open: Monitor file system operations
• observe_process_execution: Monitor process execution
• observe_signal: Monitor signal delivery
• observe_system_calls: Monitor system calls
• top_file: Top files by I/O operations
• top_tcp: Top TCP connections by traffic
• tcpdump: Capture network packets

The easiest way to get started with AKS-MCP is through the Azure Kubernetes Service Extension for VS Code.

Step 1: Install the AKS Extension

1. Open VS Code and go to Extensions (Ctrl+Shift+X on Windows/Linux or Cmd+Shift+X on macOS).
2. Search for Azure Kubernetes Service.
3. Install the official Microsoft AKS extension.

Step 2: Launch the AKS-MCP Server

1. Open the Command Palette (Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS).
2. Search and run: AKS: Setup AKS MCP Server.

Upon successful installation, the server will now be visible in MCP: List Servers (via Command Palette). From there, you can start the MCP server or view its status.

Step 3: Start Using AKS-MCP

Once started, the MCP server will appear in the Copilot Chat: Configure Tools dropdown under MCP Server: AKS MCP, ready to enhance contextual prompts based on your AKS environment. By default, all AKS-MCP server tools are enabled. You can review the list of available tools and disable any that are not required for your specific scenario.

Try a prompt like "List all my AKS clusters", which will start using tools from the AKS-MCP server.

WSL Configuration

The MCP configuration differs depending on whether VS Code is running on Windows or inside WSL:

🪟 Windows Host (VS Code on Windows): Use "command": "wsl" to invoke the WSL binary from Windows:

{
  "servers": {
    "aks-mcp": {
      "type": "stdio",
      "command": "wsl",
      "args": [
        "--",
        "/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp",
        "--transport",
        "stdio"
      ]
    }
  }
}

🐧 Remote-WSL (VS Code running inside WSL): Call the binary directly or use a shell wrapper:

{
  "servers": {
    "aks-mcp": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "/home/you/.vs-kubernetes/tools/aks-mcp/aks-mcp --transport stdio"
      ]
    }
  }
}

🔧 Troubleshooting ENOENT Errors

If you see "spawn ENOENT" errors, verify your VS Code environment:

• Windows host: Check if the WSL binary path is correct and accessible via wsl -- ls /path/to/aks-mcp
• Remote-WSL: Do NOT use "command": "wsl" - use direct paths or bash wrapper as shown above

1. Helm chart installation with OAuth-based access: Helm Chart

2. Helm chart installation with RBAC (Workload Identity): Blog Post - Deploy AKS MCP server with Workload Identity

Step 1: Download the Binary

Choose your platform and download the latest AKS-MCP binary:

Step 2: Configure VS Code

After downloading, create a .vscode/mcp.json file in your workspace root with the path to your downloaded binary.

Option A: Automated Setup Script

For quick setup, you can use these one-liner scripts that download the binary and create the configuration:

Windows (PowerShell):

# Download binary and create VS Code configuration
mkdir -p .vscode ; Invoke-WebRequest -Uri "https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-windows-amd64.exe" -OutFile "aks-mcp.exe" ; @{servers=@{"aks-mcp-server"=@{type="stdio";command="$PWD\aks-mcp.exe";args=@("--transport","stdio")}}} | ConvertTo-Json -Depth 3 | Out-File ".vscode/mcp.json" -Encoding UTF8

macOS/Linux (Bash):

# Download binary and create VS Code configuration
mkdir -p .vscode && curl -sL https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-linux-amd64 -o aks-mcp && chmod +x aks-mcp && echo '{"servers":{"aks-mcp-server":{"type":"stdio","command":"'$PWD'/aks-mcp","args":["--transport","stdio"]}}}' > .vscode/mcp.json

Option B: Manual Configuration

✨ Simple Setup: Download the binary for your platform, then use the manual configuration below to set up the MCP server in VS Code.

Manual VS Code Configuration

You can configure the AKS-MCP server in two ways:

1. Workspace-specific configuration (recommended for project-specific usage):

Create a .vscode/mcp.json file in your workspace with the path to your downloaded binary:

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

2. User-level configuration (persistent across all workspaces):

For a persistent configuration that works across all your VS Code workspaces, add the MCP server to your VS Code user settings:

1. Open VS Code Settings (Ctrl+, or Cmd+,)
2. Search for "mcp" in the settings
3. Add the following to your User Settings JSON:

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

Step 3: Load the AKS-MCP server tools to Github Copilot

1. If running on an older version of VS Code: restart VS Code i.e. close and reopen VS Code to load the new MCP server configuration.
2. Open GitHub Copilot in VS Code and switch to Agent mode
3. Click the Tools button or run /list in the Github Copilot window to see the list of available tools
4. You should see the AKS-MCP tools in the list
5. Try a prompt like: "List all my AKS clusters in subscription xxx"
6. The agent will automatically use AKS-MCP tools to complete your request

💡 Tip: If you don't see the AKS-MCP tools after restarting, check the VS Code output panel for any MCP server connection errors and verify your binary path in .vscode/mcp.json.

Note: Ensure you have authenticated with Azure CLI (az login) for the server to access your Azure resources.

For other MCP-compatible AI clients like Claude Desktop or GitHub Copilot CLI, configure the server in your MCP configuration:

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

🐳 Docker MCP Toolkit

You can enable the AKS-MCP server directly from MCP Toolkit:

1. Open Docker Desktop
2. Click "MCP Toolkit" in the left sidebar
3. Search for "aks" in Catalog tab
4. Click on the AKS-MCP server card
5. Enable the server by clicking "+" in the top right corner
6. Configure the server using "Configuration" tab:
   • azure_dir [REQUIRED]: Path to your Azure credentials directory e.g /home/user/.azure (must be absolute – without $HOME or ~)
   • kubeconfig [REQUIRED]: Path to your kubeconfig file e.g /home/user/.kube/config (must be absolute – without $HOME or ~)
   • access_level [REQUIRED]: Set to readonly, readwrite, or admin as needed
   • container_user [OPTIONAL]: Username or UID to run the container as (default is mcp), e.g. use 1000 to match your host user ID (see note below). Only needed if you are using docker engine on Linux.
7. You are now ready to use the AKS-MCP server with your preferred MCP client, see an example here. (requires >= v0.16.0 for MCP gateway)

Note: When running the MCP gateway using Docker Engine, you have to set the container_user to match your host user ID (e.g using id -u) to ensure proper file permissions for accessing mounted volumes. On Docker Desktop, this is handled automatically if you use desktop-* contexts, confirmed by running docker context ls.

On Windows, the Azure credentials won't work by default, but you have two options:

1. Long-lived servers: Configure the MCP gateway to use long-lived servers using --long-lived flag and then authenticate with Azure CLI in the container, see option B in Containerized MCP configuration below on how to fetch credentials inside the container.

2. Custom Azure Directory: Set up a custom Azure directory:

   hljs language-powershell

   Copy

   # Set custom Azure config directory
   $env:AZURE_CONFIG_DIR = "$env:USERPROFILE\.azure-for-docker"
   
   # Disable token cache encryption (to match behavior with Linux/macOS)
   $env:AZURE_CORE_ENCRYPT_TOKEN_CACHE = "false"
   
   # Login to Azure CLI
   az login
   

   This will store the credentials in $env:USERPROFILE\.azure-for-docker (e.g. C:\Users\<username>\.azure-for-docker), use this path in the AKS-MCP server configuration azure_dir.

You can also use the MCP Gateway to enable the AKS-MCP server directly using:

# Enable AKS-MCP server in Docker MCP Gateway
docker mcp server enable aks

Note: You still need to configure the server (e.g. using docker mcp config) with your Azure credentials, kubeconfig file, and access level.

🐋 Containerized MCP configuration

For containerized deployment, you can run AKS-MCP server using the official Docker image:

Option A: Mount credentials from host (recommended):

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

Option B: fetch the credentials inside the container:

{
  "mcpServers": {
    "aks": {
      "type": "stdio",
      "command": "docker",
      "args": [
          "run",
          "-i",
          "--rm",
          "ghcr.io/azure/aks-mcp:latest",
          "--transport",
          "stdio"
        ]
    }
  }
}

Start the MCP server container first per above command, and then run the following commands to fetch the credentials:

• 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>

Note that:

• Host Azure CLI logins don’t automatically propagate into containers without mounting ~/.azure.
• User ID should be set for option A, orelse the mcp user inside container won't be able to access the mounted files.

🤖 Custom MCP Client Installation

You can configure any MCP-compatible client to use the AKS-MCP server by running the binary directly:

# Run the server directly
./aks-mcp --transport stdio

🔧 Manual Binary Installation

For direct binary usage without package managers:

1. Download the latest release from the releases page
2. Extract the binary to your preferred location
3. Make it executable (on Unix systems):
   hljs language-bash

   Copy

   chmod +x aks-mcp
   

4. Configure your MCP client to use the binary path