### Start Azure Fleet Update Run

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-fleet-tools.md

Example of how to initiate a previously created update run for an Azure fleet.

```bash
# Start the update run
az fleet updaterun start --name myUpdateRun --fleet-name myFleet --resource-group myResourceGroup
```

--------------------------------

### Adding logging to new MCP tools

Source: https://github.com/azure/aks-mcp/blob/main/docs/logging.md

A comprehensive example demonstrating how to integrate logging into new MCP tools. It covers logging operation start, parameter validation, important steps, error handling, and successful completion.

```go
func HandleNewTool(params map[string]interface{}, cfg *config.ConfigData) (string, error) {
    // Log the start of the operation
    log.Printf("[NEWTOOL] Starting operation with params: %v", params)
    
    // Validate parameters with logging
    requiredParam, ok := params["required_param"].(string)
    if !ok {
        log.Println("[NEWTOOL] Missing required_param parameter")
        return "", fmt.Errorf("required_param parameter is required")
    }
    
    // Log important steps
    log.Printf("[NEWTOOL] Processing with parameter: %s", requiredParam)
    
    // Execute operations with error logging
    result, err := someOperation(requiredParam)
    if err != nil {
        log.Printf("[NEWTOOL] Operation failed: %v", err)
        return "", fmt.Errorf("operation failed: %w", err)
    }
    
    // Log successful completion
    log.Printf("[NEWTOOL] Operation completed successfully")
    return result, nil
}
```

--------------------------------

### Configure Fleet Server Access Level

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-fleet-tools.md

Examples of starting the fleet server with different access levels: readonly, readwrite, and admin.

```bash
./aks-mcp --access-level readonly
```

```bash
./aks-mcp --access-level readwrite
```

```bash
./aks-mcp --access-level admin
```

--------------------------------

### Setup Python Environment and Dependencies

Source: https://github.com/azure/aks-mcp/blob/main/docs/labs/README.md

Set up a Python virtual environment and install necessary dependencies, including semantic-kernel and python-dotenv. Configure your Azure OpenAI settings in the .env file.

```bash
# Optional: Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install Python dependencies
pip install semantic-kernel[mcp] python-dotenv
# Copy and configure environment variables
cp .env.example .env
# Edit .env with your Azure OpenAI settings:
# AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
# AZURE_OPENAI_API_KEY=your-api-key
# AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
```

--------------------------------

### Install Jupyter and Dependencies

Source: https://github.com/azure/aks-mcp/blob/main/docs/labs/README.md

Install Jupyter, semantic-kernel, and python-dotenv to run the demonstration notebook.

```bash
# Install Jupyter and notebook dependencies
pip install jupyter semantic-kernel[mcp] python-dotenv pandas
```

--------------------------------

### Example Usage: Get Recent Requests

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-application-insights.md

Demonstrates how to use the `az_monitor_app_insights_query` tool to retrieve recent requests from Application Insights.

```bash
# Get recent requests
az_monitor_app_insights_query \
  --subscription-id 82d6efa7-b1b6-4aa0-ab12-d10788552670 \
  --resource-group thomas \
  --app-insights-name thomastest39-insights \
  --query "requests | where timestamp > ago(1h) | limit 10"
```

--------------------------------

### Start Jupyter Notebook Server

Source: https://github.com/azure/aks-mcp/blob/main/docs/labs/README.md

Start the Jupyter notebook server to access and run the 'aks-mcp-demo.ipynb' notebook.

```bash
# Start Jupyter
jupyter notebook aks-mcp-demo.ipynb
```

--------------------------------

### Contributor Quick Start

Source: https://github.com/azure/aks-mcp/blob/main/README.md

Steps for contributors to quickly set up the development environment, build, and test the project.

```bash
make deps && make build
make test
make check

```

--------------------------------

### Example AKS Cluster Resource Health Query (Bash)

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-resource-health.md

This example demonstrates how to query resource health events for a specific AKS cluster using concrete subscription, resource group, cluster name, and start time.

```bash
# Example with specific parameters
az monitor activity-log list \
  --resource-id /subscriptions/82d6efa7-b1b6-4aa0-ab12-d10788552670/resourceGroups/thomas/providers/Microsoft.ContainerService/managedClusters/thomastest39 \
  --start-time 2025-01-01T00:00:00Z \
  --query "[?category.value=='ResourceHealth']" \
  --output json
```

--------------------------------

### Install Dependencies

Source: https://github.com/azure/aks-mcp/blob/main/docs/labs/aks-mcp-demo.ipynb

Installs the necessary Semantic Kernel packages with MCP support and python-dotenv for environment variable management. Uncomment and run if packages are not installed.

```python
# Install required dependencies (run this first)
# Uncomment and run if packages are not installed
%pip install semantic-kernel[mcp] python-dotenv

print("📦 If you see import errors below, uncomment and run the pip install above")
```

--------------------------------

### Start AKS-MCP with OAuth (Environment Variables)

Source: https://github.com/azure/aks-mcp/blob/main/docs/oauth-authentication.md

Simplified command to start AKS-MCP with OAuth enabled when AZURE_TENANT_ID and AZURE_CLIENT_ID environment variables are already set.

```bash
./aks-mcp --transport=streamable-http --port=8000 --oauth-enabled --access-level=readonly
```

--------------------------------

### List Operation Output Example

Source: https://github.com/azure/aks-mcp/blob/main/docs/azure-advisor-usage.md

Example structure of the output when using the 'list' operation. It includes basic details for each recommendation.

```json
[
  {
    "id": "/subscriptions/.../recommendations/rec1",
    "category": "Cost",
    "impact": "High",
    "cluster_name": "aks-cluster-1",
    "resource_group": "my-rg",
    "impacted_resource": "/subscriptions/.../managedClusters/aks-cluster-1",
    "description": "Underutilized AKS cluster nodes Consider reducing node count or using smaller VM sizes",
    "severity": "High",
    "last_updated": "2024-01-15T10:30:00Z",
    "status": "Active",
    "aks_specific": {
      "configuration_area": "compute"
    }
  }
]
```

--------------------------------

### Details Operation Output Example

Source: https://github.com/azure/aks-mcp/blob/main/docs/azure-advisor-usage.md

Example structure of the output when using the 'details' operation. It provides in-depth information for a single recommendation, including potential savings.

```json
{
  "id": "/subscriptions/.../recommendations/rec1",
  "category": "Cost",
  "impact": "High",
  "cluster_name": "aks-cluster-1",
  "resource_group": "my-rg",
  "impacted_resource": "/subscriptions/.../managedClusters/aks-cluster-1",
  "description": "Detailed recommendation description with implementation guidance",
  "severity": "High",
  "potential_savings": {
    "currency": "USD",
    "annual_savings": 1200.00,
    "monthly_savings": 100.00
  },
  "last_updated": "2024-01-15T10:30:00Z",
  "status": "Active",
  "aks_specific": {
    "cluster_version": "1.28.5",
    "node_pool_names": ["nodepool1", "nodepool2"],
    "workload_type": "production",
    "configuration_area": "compute"
  }
}
```

--------------------------------

### Start SSE Server and Run Lab Client

Source: https://github.com/azure/aks-mcp/blob/main/docs/labs/README.md

Start the AKS-MCP server with SSE transport and verbose logging in one terminal, then run the lab client connecting to it in another.

```bash
# Terminal 1: Start SSE server with verbose logging
./aks-mcp --transport sse --port 8000 --access-level admin --verbose

# Terminal 2: Run lab client
python test_aks_mcp.py --transport sse --host localhost --port 8000
```

--------------------------------

### List Azure Fleet Update Strategies

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-fleet-tools.md

Example of how to list all defined update strategies for a specific Azure fleet.

```bash
# List update strategies
az fleet updatestrategy list --fleet-name myFleet --resource-group myResourceGroup
```

--------------------------------

### Run AKS-MCP with Enabled Components

Source: https://context7.com/azure/aks-mcp/llms.txt

Start AKS-MCP with stdio transport, enabling only specific components like kubectl and monitoring. This allows for a more tailored and potentially more secure setup.

```bash
# Enable only specific components (e.g., kubectl and monitoring only)
./aks-mcp \
  --transport stdio \
  --enabled-components "kubectl,monitor"
```

--------------------------------

### Show Azure Fleet Details

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-fleet-tools.md

Example of how to display detailed information about a specific Azure fleet.

```bash
# Show fleet details
az fleet show --name myFleet --resource-group myResourceGroup
```

--------------------------------

### Start Streamable HTTP Server and Run Lab Client

Source: https://github.com/azure/aks-mcp/blob/main/docs/labs/README.md

Start the AKS-MCP server with Streamable HTTP transport and verbose logging in one terminal, then run the lab client connecting to it in another.

```bash
# Terminal 1: Start HTTP server with verbose logging  
./aks-mcp --transport streamable-http --port 8000 --access-level admin --verbose

# Terminal 2: Run lab client
python test_aks_mcp.py --transport streamable-http --host localhost --port 8000
```

--------------------------------

### Install Inspektor Gadget with Helm

Source: https://github.com/azure/aks-mcp/blob/main/docs/inspektor-gadget-usage.md

Installs the latest version of Inspektor Gadget using the official Helm chart. Ensure you have Helm and jq installed.

```bash
IG_VERSION=$(curl -s https://api.github.com/repos/inspektor-gadget/inspektor-gadget/releases/latest | jq -r '.tag_name' | sed 's/^v//')
helm install gadget --namespace=gadget --create-namespace oci://ghcr.io/inspektor-gadget/inspektor-gadget/charts/gadget --version=$IG_VERSION
```

--------------------------------

### Verify AKS-MCP Installation

Source: https://github.com/azure/aks-mcp/blob/main/CONTRIBUTING.md

Run the AKS-MCP binary with the --help flag or use 'make run' to verify the installation.

```bash
# Run the binary to see help
./aks-mcp --help

# Or using make
make run
```

--------------------------------

### Install with Service Principal Credentials (Values)

Source: https://github.com/azure/aks-mcp/blob/main/docs/helm-workload-identity.md

Installs the Helm chart using Service Principal authentication by providing credentials directly via Helm values. Workload Identity is disabled by default.

```bash
# Or provide credentials directly via values:
helm install aks-mcp ./chart \
  --set azure.tenantId=$TENANT_ID \
  --set azure.clientId=$SP_CLIENT_ID \
  --set azure.clientSecret=$SP_CLIENT_SECRET \
  --set azure.subscriptionId=$SUBSCRIPTION_ID
```

--------------------------------

### Start Continuous Inspektor Gadget Monitoring

Source: https://context7.com/azure/aks-mcp/llms.txt

Start a background monitoring gadget, such as 'observe_tcp', for continuous observation on a specific namespace and pod. Requires a 'gadget_name', 'namespace', and 'pod'.

```json
{
  "tool": "inspektor_gadget_observability",
  "arguments": {
    "action": "start",
    "gadget_name": "observe_tcp",
    "namespace": "production",
    "pod": "my-pod-abc123"
  }
}
```

--------------------------------

### KQL Query Examples for Application Insights

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-application-insights.md

Provides examples of common KQL queries for retrieving various types of telemetry data from Application Insights.

```kql
# Recent requests
requests | where timestamp > ago(1h) | limit 10
```

```kql
# Request performance over time
requests | where timestamp > ago(1h) | summarize avg(duration), count() by bin(timestamp, 5m)
```

```kql
# Error rate by operation
requests | where timestamp > ago(1h) | summarize total=count(), errors=countif(success == false) by operation_Name
```

```kql
# External dependency calls
dependencies | where timestamp > ago(1h) | summarize count(), avg(duration) by type, target
```

```kql
# Recent exceptions
exceptions | where timestamp > ago(1h) | project timestamp, type, method, outerMessage
```

--------------------------------

### Cache Key Structure Examples

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-resource-caching.md

Examples demonstrating the hierarchical cache key structure for various Azure resources. This format ensures predictable structure, collision avoidance, scope isolation, and type organization.

```text
resource:cluster:12345678-1234-1234-1234-123456789012:myRG:myCluster
```

```text
resource:vnet:12345678-1234-1234-1234-123456789012:networkRG:myVNet
```

```text
resource:nsg:12345678-1234-1234-1234-123456789012:aksRG:myNSG
```

```text
resource:routetable:12345678-1234-1234-1234-123456789012:aksRG:myRT
```

--------------------------------

### Example output of Azure Advisor tool logging

Source: https://github.com/azure/aks-mcp/blob/main/docs/logging.md

This is an example of the log output generated by the Azure Advisor tool, showing operation tracking, command execution, and result processing.

```text
[ADVISOR] Handling operation: list
[ADVISOR] Listing recommendations for subscription: c4528d9e-c99a-48bb-b12d-fde2176a43b8, resource_group: thomas, category: , severity: 
[ADVISOR] Executing command: az advisor recommendation list --subscription c4528d9e-c99a-48bb-b12d-fde2176a43b8 --resource-group thomas --output json
[ADVISOR] Command output length: 2 characters
[ADVISOR] Successfully parsed 0 recommendations from CLI output
[ADVISOR] Found 0 total recommendations
[ADVISOR] Found 0 AKS-related recommendations
[ADVISOR] Returning 0 recommendation summaries
```

--------------------------------

### Start MCP Inspector

Source: https://github.com/azure/aks-mcp/blob/main/docs/development/mcp-inspector-port-forward.md

Starts the MCP Inspector tool, which will open a web browser at http://localhost:6274.

```bash
# Start MCP Inspector
npx @modelcontextprotocol/inspector
```

--------------------------------

### Install AKS-MCP Helm Chart from Source

Source: https://github.com/azure/aks-mcp/blob/main/chart/README.md

Clone the AKS-MCP repository and install the Helm chart locally. Ensure you have Helm 3.8+ and Kubernetes 1.19+.

```bash
# Clone the repository
git clone https://github.com/Azure/aks-mcp.git
cd aks-mcp/chart

# Install the chart
helm install my-aks-mcp . --namespace aks-mcp --create-namespace
```

--------------------------------

### Example Usage: Dependency Analysis with Time Range

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-application-insights.md

Shows how to perform dependency analysis with a specified time range using the `az_monitor_app_insights_query` tool.

```bash
# Get dependency analysis with time range
az_monitor_app_insights_query \
  --subscription-id 82d6efa7-b1b6-4aa0-ab12-d10788552670 \
  --resource-group thomas \
  --app-insights-name thomastest39-insights \
  --query "dependencies | summarize count() by type, target" \
  --start-time 2025-07-17T00:00:00Z \
  --end-time 2025-07-18T00:00:00Z
```

--------------------------------

### Report Operation Output Example

Source: https://github.com/azure/aks-mcp/blob/main/docs/azure-advisor-usage.md

Example structure of the output when using the 'report' operation. It includes a summary, action items, and cluster-specific breakdowns.

```json
{
  "subscription_id": "12345678-1234-1234-1234-123456789012",
  "generated_at": "2024-07-08T19:30:00Z",
  "summary": {
    "total_recommendations": 5,
    "by_category": {
      "Cost": 2,
      "Security": 2,
      "Performance": 1
    },
    "by_severity": {
      "High": 2,
      "Medium": 2,
      "Low": 1
    },
    "clusters_affected": 3
  },
  "recommendations": [...],
  "action_items": [
    {
      "priority": 1,
      "recommendation_id": "/subscriptions/.../recommendations/rec1",
      "cluster_name": "aks-cluster-1",
      "category": "Cost",
      "description": "High-priority cost optimization",
      "estimated_effort": "Medium",
      "potential_impact": "High"
    }
  ],
  "cluster_breakdown": [
    {
      "cluster_name": "aks-cluster-1",
      "resource_group": "my-rg",
      "recommendations": [...],
      "total_savings": {
        "currency": "USD",
        "annual_savings": 1200.00,
        "monthly_savings": 100.00
      }
    }
  ]
}
```

--------------------------------

### Start AKS-MCP with OAuth (HTTP Streamable Transport)

Source: https://github.com/azure/aks-mcp/blob/main/docs/oauth-authentication.md

Recommended method to start AKS-MCP with OAuth enabled using HTTP Streamable transport. Ensure environment variables AZURE_TENANT_ID and AZURE_CLIENT_ID are set, or provide them directly.

```bash
./aks-mcp \
  --transport=streamable-http \
  --port=8000 \
  --oauth-enabled \
  --oauth-tenant-id="$AZURE_TENANT_ID" \
  --oauth-client-id="$AZURE_CLIENT_ID" \
  --oauth-redirects="http://localhost:8000/oauth/callback" \
  --access-level=readonly
```

--------------------------------

### Show Azure Fleet Update Run Details

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-fleet-tools.md

Example of how to view the status and details of an Azure fleet update run.

```bash
# Monitor update run progress
az fleet updaterun show --name myUpdateRun --fleet-name myFleet --resource-group myResourceGroup
```

--------------------------------

### Create Azure Fleet

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-fleet-tools.md

Example of how to create a new Azure fleet. Requires specifying the fleet name, resource group, and location.

```bash
# Create a new fleet
az fleet create --name myFleet --resource-group myResourceGroup --location eastus
```

--------------------------------

### Install Azure Fleet Extension

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-fleet-tools.md

Command to install the Azure CLI fleet extension if it is not already present.

```bash
az extension add --name fleet
```

--------------------------------

### Start AKS-MCP with OAuth (SSE Transport)

Source: https://github.com/azure/aks-mcp/blob/main/docs/oauth-authentication.md

Alternative method to start AKS-MCP with OAuth enabled using SSE transport. Ensure environment variables AZURE_TENANT_ID and AZURE_CLIENT_ID are set, or provide them directly.

```bash
./aks-mcp \
  --transport=sse \
  --port=8000 \
  --oauth-enabled \
  --oauth-tenant-id="$AZURE_TENANT_ID" \
  --oauth-client-id="$AZURE_CLIENT_ID" \
  --oauth-redirects="http://localhost:8000/oauth/callback" \
  --access-level=readonly
```

--------------------------------

### Install with Service Principal Credentials (Secret)

Source: https://github.com/azure/aks-mcp/blob/main/docs/helm-workload-identity.md

Installs the Helm chart using Service Principal authentication by providing credentials via a Kubernetes secret. Workload Identity is disabled by default.

```bash
# Create a secret with Service Principal credentials
kubectl create secret generic aks-mcp-azure-credentials \
  --from-literal=tenant-id=$TENANT_ID \
  --from-literal=client-id=$SP_CLIENT_ID \
  --from-literal=client-secret=$SP_CLIENT_SECRET \
  --from-literal=subscription-id=$SUBSCRIPTION_ID

# Install with default settings (Workload Identity disabled)
helm install aks-mcp ./chart \
  --set azure.existingSecret=aks-mcp-azure-credentials
```

--------------------------------

### List Azure Fleets

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-fleet-tools.md

Example of how to list all Azure fleets within a specified resource group.

```bash
# List all fleets
az fleet list --resource-group myResourceGroup
```

--------------------------------

### List available metrics for AKS cluster

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-monitor-tools.md

Example of how to list available metric definitions for an AKS cluster. This helps in identifying specific metrics to monitor.

```bash
# List available metrics for AKS cluster
az monitor metrics list-definitions --resource /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ContainerService/managedClusters/{cluster}
```

--------------------------------

### Create Azure Fleet Update Strategy

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-fleet-tools.md

Example of how to define an update strategy for fleet operations, specifying stages for the update process.

```bash
# Create an update strategy
az fleet updatestrategy create --name myStrategy --fleet-name myFleet --resource-group myResourceGroup --stages stage1
```

--------------------------------

### Start AKS-MCP with Restricted Scope using Command Line

Source: https://github.com/azure/aks-mcp/blob/main/docs/oauth-authentication.md

Start AKS-MCP with OAuth enabled and a restricted scope, requiring specific user or service principal assignments.

```bash
# Restricted scope (only assigned users/SPNs)
./aks-mcp --transport=streamable-http --oauth-enabled=true \
  --oauth-tenant-id="12345678-1234-1234-1234-123456789012" \
  --oauth-client-id="87654321-4321-4321-4321-210987654321" \
  --oauth-scopes="api://87654321-4321-4321-4321-210987654321/.default"
```

--------------------------------

### Start Update Run using Azure CLI

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-fleet-tools.md

Use the `az fleet updaterun start` command to begin executing an update run that has been created. This command triggers the deployment process defined in the update run.

```bash
az fleet updaterun start --fleet-name myFleet --name myUpdateRun --resource-group myResourceGroup
```

--------------------------------

### List Azure Fleet Members

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-fleet-tools.md

Example of how to list all clusters that are members of a specific Azure fleet.

```bash
# List fleet members
az fleet member list --fleet-name myFleet --resource-group myResourceGroup
```

--------------------------------

### Initialize and Use DetectorClient (Go)

Source: https://context7.com/azure/aks-mcp/llms.txt

Demonstrates how to create a DetectorClient, list detectors, run a specific detector, get detectors by category, and run detectors by category. The client caches results for 1 minute.

```go
import (
    "context"
    "github.com/Azure/aks-mcp/internal/components/detectors"
    "github.com/Azure/aks-mcp/internal/azureclient"
)

// Create a detector client (azClient is initialized from config)
azClient, _ := azureclient.NewAzureClient(cfg)
client := detectors.NewDetectorClient(azClient)

ctx := context.Background()

// List all available detectors (result is cached for 1 minute)
list, err := client.ListDetectors(ctx, "sub-id", "myRG", "myCluster")
if err != nil {
    log.Fatalf("failed to list detectors: %v", err)
}
for _, d := range list.Value {
    fmt.Println(d.Properties.Metadata.Name, d.Properties.Metadata.Category)
}

// Run a specific detector by ID
result, err := client.RunDetector(ctx,
    "sub-id", "myRG", "myCluster",
    "node-health-detector",
    "2024-01-15T10:00:00Z",
    "2024-01-15T12:00:00Z",
)

// Get all detectors in a category (uses cached list)
nodeHealthDetectors, err := client.GetDetectorsByCategory(ctx,
    "sub-id", "myRG", "myCluster", "Node Health",
)

// Run all detectors in a category
results, err := client.RunDetectorsByCategory(ctx,
    "sub-id", "myRG", "myCluster",
    "Connectivity Issues",
    "2024-01-15T10:00:00Z",
    "2024-01-15T12:00:00Z",
)
```

--------------------------------

### Get cluster metrics

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-monitor-tools.md

Example of how to get metrics for an AKS cluster using the Azure CLI. Replace placeholders with your actual subscription, resource group, and cluster name.

```bash
# Get cluster metrics
az monitor metrics list --resource /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ContainerService/managedClusters/{cluster}
```

--------------------------------

### Example Verbose Output from AKS-MCP Server

Source: https://github.com/azure/aks-mcp/blob/main/docs/labs/README.md

Illustrates the detailed output format when verbose logging is enabled, showing tool calls and their results or errors.

```text
>>> [az_aks_operations] {"args":"","operation":"list"}
    Result: 20291 bytes (truncated): [{"aadProfile":{"enableAzureRbac":true...

>>> [aks_monitoring] {"cluster_name":"hub","operation":"resource_health","parameters":{"start_time":"2025-01-01T00:00:00Z"}}
    ERROR: missing or invalid start_time parameter
```

--------------------------------

### Get Azure Fleet Kubeconfig Credentials

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-fleet-tools.md

Example of how to retrieve kubeconfig credentials for accessing a specific Azure fleet.

```bash
# Get fleet kubeconfig credentials
az fleet get-credentials --name myFleet --resource-group myResourceGroup
```

--------------------------------

### Good logging examples with component prefixes

Source: https://github.com/azure/aks-mcp/blob/main/docs/logging.md

Demonstrates effective logging practices using component prefixes for different modules like ADVISOR. Avoid logging sensitive information such as tokens.

```go
// Good logging examples
log.Printf("[ADVISOR] Starting recommendation list for subscription: %s", subscriptionID)
log.Printf("[ADVISOR] Found %d total recommendations, %d AKS-related", total, aksCount)
log.Printf("[ADVISOR] Command execution failed: %v", err)
```

```go
// Avoid logging sensitive information
log.Printf("[ADVISOR] Processing subscription: %s", subscriptionID) // OK
log.Printf("[ADVISOR] Using token: %s", token) // BAD - don't log secrets
```

--------------------------------

### Start AKS-MCP with Default Scope

Source: https://github.com/azure/aks-mcp/blob/main/docs/oauth-authentication.md

Launch AKS-MCP with OAuth enabled using the default scope, allowing any Azure AD user to authenticate.

```bash
# Default scope (any Azure AD user)
./aks-mcp --transport=sse --oauth-enabled=true \
  --oauth-tenant-id="12345678-1234-1234-1234-123456789012" \
  --oauth-client-id="87654321-4321-4321-4321-210987654321"
```

--------------------------------

### Start MCP Inspector

Source: https://github.com/azure/aks-mcp/blob/main/docs/development/mcp-inspector-azure-app-routing-deployment.md

Launches the MCP Inspector application using npx. This is typically used for local development and debugging.

```bash
npx @modelcontextprotocol/inspector
```

--------------------------------

### Setup and Connect AKS MCP Plugin

Source: https://github.com/azure/aks-mcp/blob/main/docs/labs/aks-mcp-demo.ipynb

Sets up the AKS MCP Stdio Plugin, connecting to the AKS MCP executable. It requires the 'aks-mcp' directory to exist and be built. The plugin is added to the kernel with the name 'akstool'.

```python
# Setup AKS MCP Plugin
aks_mcp_path = "../../aks-mcp"
if not Path(aks_mcp_path).exists():
    print(f"❌ AKS-MCP not found at {aks_mcp_path}")
    raise FileNotFoundError("Build with: make build")

mcp_plugin = MCPStdioPlugin(
    name="AKSMCP",
    command=aks_mcp_path,
    args=["--transport", "stdio", "--access-level", "admin"],
)

await mcp_plugin.connect()
kernel.add_plugin(mcp_plugin, plugin_name="akstool")
print("✅ MCP connected")
```

--------------------------------

### Typical Development Session Workflow

Source: https://github.com/azure/aks-mcp/blob/main/docs/development/mcp-inspector-port-forward.md

Outlines the steps for a typical development session, including deploying AKS-MCP, starting port-forwarding, launching Inspector, and updating configuration.

```bash
# Deploy AKS-MCP
helm upgrade --install aks-mcp-inspector .
  --namespace aks-mcp-inspector
  -f ./values-mcp-inspector.yaml

# Start port-forward
kubectl port-forward service/aks-mcp-inspector 8081:8081 -n aks-mcp-inspector &

npx @modelcontextprotocol/inspector
```

--------------------------------

### Helm Chart Deployment for In-Cluster Remote MCP

Source: https://context7.com/azure/aks-mcp/llms.txt

Deploy AKS-MCP using a Helm chart for in-cluster remote access. This involves adding configuration values and installing the chart. Examples include basic installation and deployment with OAuth and workload identity.

```bash
# Add configuration — values.yaml
cat > my-values.yaml << 'EOF'
image:
  repository: ghcr.io/azure/aks-mcp
  tag: "v0.0.16"

args:
  - --transport
  - streamable-http
  - --access-level
  - readwrite
  - --port
  - "8000"

service:
  type: ClusterIP
  port: 8000
EOF
```

```bash
# Install the Helm chart
helm install aks-mcp ./chart \
  --namespace aks-mcp \
  --create-namespace \
  -f my-values.yaml
```

```bash
# With OAuth and workload identity
helm install aks-mcp ./chart \
  --namespace aks-mcp \
  --create-namespace \
  -f chart/values-mcp-inspector.yaml \
  --set "extraEnv[0].name=AZURE_CLIENT_ID,extraEnv[0].value=your-managed-identity-client-id"
```

--------------------------------

### Automated macOS/Linux Setup Script for AKS-MCP

Source: https://github.com/azure/aks-mcp/blob/main/README.md

This Bash script downloads the AKS-MCP binary for Linux and creates the necessary VS Code configuration file.

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

--------------------------------

### Get specific cluster metric with aggregation and output

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-monitor-tools.md

Example of retrieving a specific metric (apiserver_cpu_usage_percentage) for an AKS cluster, specifying aggregation type and output format.

```bash
az monitor metrics list --resource /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ContainerService/managedClusters/{cluster} --metric apiserver_cpu_usage_percentage   --interval PT1M   --aggregation Average   --output table
```

--------------------------------

### Get Access Token for Custom Scope

Source: https://github.com/azure/aks-mcp/blob/main/chart/README.md

Examples for obtaining an access token for a custom scope using Azure CLI for user authentication or curl for Managed Identity.

```bash
# User authentication
az account get-access-token --resource api://your-oauth-client-id --query accessToken -o tsv
```

```bash
# Managed Identity (from Azure VM/AKS)
curl -s 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=api://your-oauth-client-id' \
  -H 'Metadata: true' | jq -r '.access_token'
```

--------------------------------

### Configure OpenTelemetry with Helm

Source: https://github.com/azure/aks-mcp/blob/main/chart/README.md

Install or upgrade the chart to set the OpenTelemetry endpoint for telemetry data collection. Ensure the OTLP endpoint is correctly formatted.

```bash
helm install my-aks-mcp . \
  --set telemetry.otlpEndpoint=http://jaeger:14268/api/traces
```

--------------------------------

### Test Release Build

Source: https://github.com/azure/aks-mcp/blob/main/CONTRIBUTING.md

Execute make commands to prepare and verify the release build and generate checksums.

```bash
make release
make checksums
```

--------------------------------

### Containerized AKS-MCP Server: Fetch Credentials Inside Container

Source: https://github.com/azure/aks-mcp/blob/main/README.md

Configure the AKS-MCP server for containerized deployment where credentials are fetched inside the container. This requires logging into Azure CLI and getting kubeconfig using `docker exec` commands after the container starts.

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

--------------------------------

### Get Resource Health Events (Last 7 Days)

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-resource-health.md

Retrieves resource health events for an AKS cluster for the last 7 days using Azure CLI. Requires subscription ID, resource group, cluster name, and start time.

```bash
# Get health events for the last 7 days
az_monitor_activity_log_resource_health \
  --subscription-id 82d6efa7-b1b6-4aa0-ab12-d10788552670 \
  --resource-group thomas \
  --cluster-name thomastest39 \
  --start-time 2025-07-03T00:00:00Z
```

--------------------------------

### Get Resource Health Events (Specific Time Range)

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-resource-health.md

Retrieves resource health events for an AKS cluster within a specific time range and optionally filters by status. Requires subscription ID, resource group, cluster name, start time, and end time.

```bash
# Get health events for a specific time range
az_monitor_activity_log_resource_health \
  --subscription-id 82d6efa7-b1b6-4aa0-ab12-d10788552670 \
  --resource-group thomas \
  --cluster-name thomastest39 \
  --start-time 2025-07-01T00:00:00Z \
  --end-time 2025-07-10T00:00:00Z \
  --status Available
```

--------------------------------

### Display Makefile Help

Source: https://github.com/azure/aks-mcp/blob/main/README.md

Use this command to view all available targets and their descriptions in the project's Makefile.

```bash
make help

```

--------------------------------

### Get AKS MCP Server Help

Source: https://github.com/azure/aks-mcp/blob/main/docs/labs/README.md

Run this command to display the help information for the AKS MCP server. Use `--help` for detailed options.

```bash
# Server help
./aks-mcp --help
```

--------------------------------

### Install MCP Inspector Globally

Source: https://github.com/azure/aks-mcp/blob/main/docs/development/mcp-inspector-port-forward.md

Installs the MCP Inspector tool globally using npm. Alternatively, you can run it without installation using npx.

```bash
# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Or run without installing
npx @modelcontextprotocol/inspector
```

--------------------------------

### Initialize Azure Default Credential

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-diagnostics.md

Demonstrates how to initialize the Azure SDK's default credential chain for authentication. This is a common setup for interacting with Azure services.

```go
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    return fmt.Errorf("failed to create Azure credential: %w", err)
}
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/azure/aks-mcp/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits format for different types of changes.

```text
feat(azure): add support for AKS diagnostic settings
```

```text
fix(security): validate access level for admin operations
```

```text
docs: update contribution guidelines
```

--------------------------------

### Build and Test with Make

Source: https://github.com/azure/aks-mcp/blob/main/README.md

Common development tasks using the Makefile, including building the binary, running tests, checking code quality, and creating releases.

```bash
# Build the binary
make build

# Run tests
make test

# Run tests with coverage
make test-coverage

# Format and lint code
make check

# Build for all platforms
make release

```

--------------------------------

### Install Helm Chart with Workload Identity

Source: https://github.com/azure/aks-mcp/blob/main/docs/helm-workload-identity.md

Installs the AKS-MCP Helm chart with Workload Identity enabled. This is the recommended method for authentication.

```bash
# Install with Workload Identity enabled (readonly mode)
helm install aks-mcp ./chart \
  --set workloadIdentity.enabled=true \
  --set azure.clientId=$IDENTITY_CLIENT_ID \
  --set azure.subscriptionId=$SUBSCRIPTION_ID
```

```bash
helm install aks-mcp ./chart \
  --namespace aks-mcp \
  --create-namespace \
  --set workloadIdentity.enabled=true \
  --set azure.clientId=$IDENTITY_CLIENT_ID \
  --set azure.subscriptionId=$SUBSCRIPTION_ID
```

--------------------------------

### Alternative Port Forwarding Syntaxes

Source: https://github.com/azure/aks-mcp/blob/main/docs/development/mcp-inspector-port-forward.md

Demonstrates alternative kubectl commands for port forwarding, either to the deployment or a specific pod.

```bash
# Alternative port-forward syntax
kubectl port-forward deployment/aks-mcp-inspector 8081:8081 -n aks-mcp-inspector

# Or port-forward to a specific pod
kubectl port-forward pod/<pod-name> 8081:8081 -n aks-mcp-inspector
```

--------------------------------

### Display Client Help Information

Source: https://github.com/azure/aks-mcp/blob/main/docs/labs/README.md

Command to display the help message for the lab client, showing available options and arguments.

```bash
# Help
python test_aks_mcp.py --help
```

--------------------------------

### Common Development Tasks with Make

Source: https://github.com/azure/aks-mcp/blob/main/README.md

Essential development tasks managed by the Makefile, such as installing dependencies, running the application, cleaning build artifacts, and installing the binary.

```bash
# Install dependencies
make deps

# Build and run with --help
make run

# Clean build artifacts
make clean

# Install binary to GOBIN
make install

```

--------------------------------

### Start AKS Cluster with az_aks_operations

Source: https://github.com/azure/aks-mcp/blob/main/README.md

This operation requires `readwrite` or `admin` access level and is available when `USE_LEGACY_TOOLS` is set to `true`. It starts a stopped AKS cluster.

```json
{
  "operation": "start",
  "cluster_name": "myAKSCluster",
  "resource_group": "myResourceGroup"
}
```

--------------------------------

### Build and Run E2E Test Client Locally

Source: https://github.com/azure/aks-mcp/blob/main/test/e2e/README.md

Builds the E2E test client executable and runs it locally. It requires setting up port-forwarding to the MCP server and exporting necessary environment variables.

```bash
cd test/e2e

# Build the test client
go build -o e2e-test ./cmd/e2e-test

# Start port-forward
kubectl port-forward svc/aks-mcp 8000:8000 &
PF_PID=$!

# Wait for port-forward to be ready
sleep 3

# Set environment variables
export MCP_SERVER_URL=http://localhost:8000
export AZURE_SUBSCRIPTION_ID=<your-subscription-id>
export RESOURCE_GROUP=<your-resource-group>
export CLUSTER_NAME=<your-cluster-name>

# Run tests (with verbose output to see parameters and results)
./e2e-test --verbose

# Or run without verbose
./e2e-test

# Stop port-forward when done
kill $PF_PID
```

--------------------------------

### Run All Tests

Source: https://github.com/azure/aks-mcp/blob/main/CONTRIBUTING.md

Execute all tests in the project using the make command.

```bash
# Run all tests
make test
```

--------------------------------

### Register All VMSS by Cluster Tool

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-vmss-tools.md

Registers the 'get_all_vmss_by_cluster' tool with its required string parameters.

```go
func RegisterAllVMSSByClusterTool() mcp.Tool {
    return mcp.NewTool(
        "get_all_vmss_by_cluster",
        mcp.WithDescription("Get detailed VMSS configuration for all node pools"),
        mcp.WithString("subscription_id", mcp.Required()),
        mcp.WithString("resource_group", mcp.Required()),
        mcp.WithString("cluster_name", mcp.Required()),
    )
}
```

--------------------------------

### Manual Go Build

Source: https://github.com/azure/aks-mcp/blob/main/README.md

Build the aks-mcp binary manually using the Go build command without the Makefile.

```bash
go build -o aks-mcp ./cmd/aks-mcp

```

--------------------------------

### Automated Windows Setup Script for AKS-MCP

Source: https://github.com/azure/aks-mcp/blob/main/README.md

This PowerShell script downloads the AKS-MCP binary for Windows and creates the necessary VS Code configuration file.

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

--------------------------------

### Install AKS-MCP using Existing Secret for Azure Credentials

Source: https://github.com/azure/aks-mcp/blob/main/chart/README.md

Create a Kubernetes secret containing Azure credentials and then install the AKS-MCP Helm chart referencing this secret. This avoids hardcoding credentials in deployment configurations.

```bash
# Create secret first
kubectl create secret generic azure-credentials \
  --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 my-aks-mcp .
  --set azure.existingSecret=azure-credentials
```

--------------------------------

### Initialize Kernel and Configure Azure OpenAI

Source: https://github.com/azure/aks-mcp/blob/main/docs/labs/aks-mcp-demo.ipynb

Initializes the Semantic Kernel and configures it to use Azure OpenAI for chat completions. Ensure AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, and AZURE_OPENAI_DEPLOYMENT_NAME environment variables are set.

```python
# Initialize kernel
kernel = Kernel()

# Configure Azure OpenAI
azure_openai = AzureChatCompletion(
    endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    deployment_name=os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME", "gpt-4o"),
    api_version=os.getenv("AZURE_OPENAI_API_VERSION", "2024-08-01-preview")
)

kernel.add_service(azure_openai)
print("✅ Kernel initialized")
```

--------------------------------

### Get AKS MCP Client Help

Source: https://github.com/azure/aks-mcp/blob/main/docs/labs/README.md

Execute this command to view the help options for the AKS MCP client script. This is useful for understanding available client-side arguments.

```bash
# Client help  
python test_aks_mcp.py --help
```

--------------------------------

### Validate Resource Health Parameters

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-resource-health.md

Validates required parameters like subscription ID, resource group, cluster name, and start time. It also checks for correct RFC3339 time format for start and end times.

```go
func validateResourceHealthParams(params map[string]interface{}) error {
    // Validate required parameters
    required := []string{"subscription_id", "resource_group", "cluster_name", "start_time"}
    for _, param := range required {
        if value, ok := params[param].(string); !ok || value == "" {
            return fmt.Errorf("missing or invalid %s parameter", param)
        }
    }
    
    // Validate time format
    startTime := params["start_time"].(string)
    if _, err := time.Parse(time.RFC3339, startTime); err != nil {
        return fmt.Errorf("invalid start_time format, expected RFC3339 (ISO 8601): %w", err)
    }
    
    // Validate end_time if provided
    if endTime, ok := params["end_time"].(string); ok && endTime != "" {
        if _, err := time.Parse(time.RFC3339, endTime); err != nil {
            return fmt.Errorf("invalid end_time format, expected RFC3339 (ISO 8601): %w", err)
        }
    }
    
    return nil
}
```

--------------------------------

### Validate Time Range Go Function

Source: https://github.com/azure/aks-mcp/blob/main/prompts/aks-control-plane.md

Validates the start and end times for log queries, ensuring they are in the correct format and within specified limits (max 7 days ago for start, max 24 hours duration).

```go
func validateTimeRange(startTime, endTime string) error {
    start, err := time.Parse(time.RFC3339, startTime)
    if err != nil {
        return fmt.Errorf("invalid start_time format: %w", err)
    }

    // Check if start time is not more than 7 days ago
    sevenDaysAgo := time.Now().AddDate(0, 0, -7)
    if start.Before(sevenDaysAgo) {
        return fmt.Errorf("start_time cannot be more than 7 days ago")
    }

    if endTime != "" {
        end, err := time.Parse(time.RFC3339, endTime)
        if err != nil {
            return fmt.Errorf("invalid end_time format: %w", err)
        }

        // Check if time range is not more than 24 hours
        if end.Sub(start) > 24*time.Hour {
            return fmt.Errorf("time range cannot exceed 24 hours")
        }

        if end.Before(start) {
            return fmt.Errorf("end_time must be after start_time")
        }
    }

    return nil
}
```

--------------------------------

### Register CLI Tool

Source: https://github.com/azure/aks-mcp/blob/main/CONTRIBUTING.md

Define tool metadata and parameters for CLI-based tools.

```go
// internal/components/yourcomponent/registry.go
func RegisterYourTool(cfg *config.ConfigData) mcp.Tool {
    return mcp.NewTool(
        "your_tool_name",
        mcp.WithDescription("Description of your tool"),
        mcp.WithString("operation", mcp.Description("Operation to perform"), mcp.Required()),
        // Add other parameters as needed
    )
}
```

--------------------------------

### Expected Pod Labels

Source: https://github.com/azure/aks-mcp/blob/main/docs/helm-workload-identity.md

Example of the expected labels on a pod when Workload Identity is enabled.

```yaml
metadata:
  labels:
    azure.workload.identity/use: "true"
```

--------------------------------

### Import the log package in Go

Source: https://github.com/azure/aks-mcp/blob/main/docs/logging.md

To use logging functionalities, import the standard 'log' package. This is the first step before adding any logging statements.

```go
import (
    "log"
    // ... other imports
)
```

--------------------------------

### Expected ServiceAccount Annotations

Source: https://github.com/azure/aks-mcp/blob/main/docs/helm-workload-identity.md

Example of the expected annotations on a ServiceAccount when Workload Identity is enabled.

```yaml
metadata:
  annotations:
    azure.workload.identity/client-id: "<your-client-id>"
  labels:
    azure.workload.identity/use: "true"
```

--------------------------------

### Register SDK Component in Server

Source: https://github.com/azure/aks-mcp/blob/main/CONTRIBUTING.md

Integrate SDK-based tools into the MCP server by registering the tool and its handler.

```go
// internal/server/server.go - Add to appropriate register function
func (s *Service) registerYourComponent() {
    log.Println("Registering your tool: your_tool_name")
    yourTool := yourcomponent.RegisterYourTool()
    s.mcpServer.AddTool(yourTool, tools.CreateResourceHandler(yourcomponent.GetYourHandler(s.azClient, s.cfg), s.cfg))
}
```

--------------------------------

### Get Build Version Information (Go)

Source: https://context7.com/azure/aks-mcp/llms.txt

Retrieves build version details, including the version string and full version information map. This is useful for understanding the build context of the application.

```go
import "github.com/Azure/aks-mcp/internal/version"

// Get the current version string
v := version.GetVersion()
// Returns: "dev" (local build) or "v0.0.16" (release build)

// Get full version details map
info := version.GetVersionInfo()
// Returns:
// {
//   "version":      "v0.0.16",
//   "gitCommit":    "abc1234",
//   "gitTreeState": "clean",
//   "goVersion":    "go1.25.0",
//   "platform":     "linux/amd64"
// }

// Build-time ldflags injection (used in Makefile/goreleaser):
// -ldflags="-X github.com/Azure/aks-mcp/internal/version.GitVersion=v0.0.16
//           -X github.com/Azure/aks-mcp/internal/version.GitCommit=abc1234
//           -X github.com/Azure/aks-mcp/internal/version.GitTreeState=clean"
```

--------------------------------

### Run AKS-MCP with stdio Transport

Source: https://github.com/azure/aks-mcp/blob/main/CONTRIBUTING.md

Start the MCP server locally using standard input/output for communication. Use 'readwrite' or 'admin' for elevated permissions during testing.

```bash
# Run with default settings (readonly access)
./aks-mcp --transport stdio

# Run with elevated permissions for testing
./aks-mcp --transport stdio --access-level readwrite

# Run with admin permissions (full access)
./aks-mcp --transport stdio --access-level admin
```

--------------------------------

### Get Resource Health Status

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-diagnostics.md

Access the current resource health status for one or more AKS clusters.

```APIDOC
## get_resource_health_status

### Description
Access current resource health status for AKS clusters.

### Parameters
#### Path Parameters
- `resource_ids` (array[string]) - Required - Array of Azure resource IDs (supports multiple clusters).
#### Query Parameters
- `include_history` (boolean) - Optional - Boolean to include recent health events.

### Expected Outputs
- Current health status (Available, Unavailable, Degraded, Unknown).
- Health summary with key metrics.
- Active health issues and their impact.
- Recommended actions for degraded health.
```

--------------------------------

### Configure Read-Only Access Level

Source: https://github.com/azure/aks-mcp/blob/main/prompts/azure-cli-tools.md

Start the MCP server with read-only access level, allowing only read operations.

```bash
./aks-mcp --access-level readonly
```

--------------------------------

### Format Code

Source: https://github.com/azure/aks-mcp/blob/main/CONTRIBUTING.md

Apply standard code formatting to the project files.

```bash
# Individual checks
make fmt      # Format code
```