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 the cluster (via the AKS cluster extension)
• undeploy: Remove the Inspektor Gadget cluster extension from the 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"
      ]
    }
  }
}

🐧 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"
      ]
    }
  }
}

🔧 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

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=@()}}} | 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":[]}}}' > .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": []
    }
  }
}