MCP(모델 컨텍스트 프로토콜) 서버를 사용하여 AKS(Azure Kubernetes Service) 클러스터를 AI 에이전트에 연결

AKS-MCP 시작하는 가장 쉬운 방법은 VS Code용 Azure Kubernetes 서비스 확장을 사용하는 것입니다. AKS 확장은 이진 다운로드, 업데이트 및 구성을 자동으로 처리하여 최적의 설정으로 항상 최신 버전을 사용할 수 있도록 합니다.

1단계: AKS 확장 설치

1. VS Code를 열고 확장(Ctrl+Shift+X Windows/Linux 또는 Cmd+Shift+X macOS)으로 이동합니다.
2. Azure Kubernetes Service를 검색합니다.
3. 공식 Microsoft AKS 확장을 설치합니다.

2단계: AKS-MCP 서버 시작

1. 명령 팔레트(Ctrl+Shift+PWindows/Linux 또는 Cmd+Shift+P macOS)를 엽니다.
2. 검색 및 실행: AKS: AKS MCP 서버를 설치합니다.

설치가 성공하면 서버가 MCP: 목록 서버 (명령 팔레트를 통해)에 표시됩니다. 여기에서 MCP 서버를 시작하거나 해당 상태를 볼 수 있습니다.

3단계: AKS-MCP 사용 시작

시작되면 MCP 서버는 코-파일럿 채팅: 도구 구성 드롭다운에 MCP Server: AKS MCP 나타나며, AKS 환경에 맞춰 상황별 프롬프트를 개선할 준비가 됩니다. 기본적으로 모든 AKS-MCP 서버 도구가 사용하도록 설정됩니다. 사용 가능한 도구 목록을 검토하고 시나리오에 필요하지 않은 도구를 사용하지 않도록 설정할 수 있습니다.

"모든 AKS 클러스터 나열"이라는 프롬프트를 사용하여 AKS-MCP 서버의 도구 사용을 시작합니다.

VS Code 확장 없이 직접 이진 사용의 경우:

1단계: 이진 파일 다운로드

플랫폼을 선택하고 최신 AKS-MCP 이진 파일을 다운로드합니다.

2단계: VS Code 구성

작업 공간의 루트에 다운로드한 바이너리 경로를 포함한 .vscode/mcp.json 파일을 생성합니다.

작업 영역별 구성 (프로젝트별 사용에 권장):

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

사용자 수준 구성 (모든 작업 영역에서 영구):

VS Code 사용자 설정 JSON에 Ctrl+, 또는 Cmd+,을 추가한 후 "mcp"를 검색합니다.

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

3단계: AKS-MCP 서버 도구 로드

1. VS Code를 다시 시작하여 새 MCP 서버 구성을 로드합니다.
2. VS Code에서 GitHub Copilot를 열고 에이전트 모드로 전환합니다.
3. 도구 단추를 선택하여 사용 가능한 도구 목록을 확인합니다.
4. AKS-MCP 도구가 목록에 표시되는지 확인합니다.
5. "구독 xxx에 내 AKS 클러스터를 모두 나열합니다."와 같은 프롬프트를 시도합니다.

Docker MCP 도구 키트의 공식 Docker 이미지를 사용하거나 컨테이너화된 MCP 구성으로 AKS-MCP 서버를 실행할 수 있습니다.

옵션 1: Docker MCP 도구 키트

1. Docker Desktop을 엽니다.
2. 왼쪽 사이드바에서 MCP 도구 키트 를 선택합니다.
3. 카탈로그 탭에서 "aks"를 검색합니다.
4. AKS-MCP 서버 카드를 선택합니다.
5. 오른쪽 위 모서리를 선택하여 + 서버를 사용하도록 설정합니다.
6. 구성 탭을 사용하여 서버를 구성합니다.
   • [REQUIRED]azure_dir: Azure 자격 증명 디렉터리에 대한 절대 경로(예: /home/user/.azure)
   • kubeconfig[REQUIRED]: kubeconfig 파일의 절대 경로(예: /home/user/.kube/config)
   • 접근 수준:[REQUIRED] 필요에 따라 readonly, readwrite, 또는 admin로 설정하십시오.
   • [OPTIONAL]container_user: 컨테이너를 실행할 사용자 이름 또는 UID입니다(기본값은 mcp). Linux에서 Docker 엔진을 실행하는 경우 호스트 사용자 ID(예 1000: )를 사용합니다.

옵션 2: 컨테이너화된 MCP 구성

호스트에서 자격 증명 탑재(권장):

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

대신 컨테이너 내에서 자격 증명을 가져오려면 볼륨 탑재를 생략하고 컨테이너를 시작한 후 다음 명령을 실행합니다.

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

Claude Desktop과 같은 다른 MCP 호환 AI 클라이언트의 경우 MCP 구성에서 서버를 구성합니다.

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

명령줄에서 직접 서버를 실행할 수도 있습니다.

./aks-mcp --transport stdio

명령줄 옵션:

환경 변수:

• USE_LEGACY_TOOLS: 통합 도구 대신 레거시 특수 도구를 사용하도록 설정 true (기본값: false)
• 표준 Azure 인증 환경 변수가 지원됩니다(AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET) AZURE_SUBSCRIPTION_ID

워크로드 ID는 Kubernetes ServiceAccount를 Azure 관리 ID에 연결하여 암호 없는 인증을 제공합니다.

1. AKS 클러스터에서 OIDC 사용

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

2. 관리 ID 만들기 및 RBAC 권한 할당

# Create identity
az identity create --resource-group <your-resource-group> --name aks-mcp-identity --location <your-location>

# Get IDs
IDENTITY_CLIENT_ID=$(az identity show --resource-group <your-resource-group> --name aks-mcp-identity --query "clientId" -o tsv)
IDENTITY_PRINCIPAL_ID=$(az identity show --resource-group <your-resource-group> --name aks-mcp-identity --query "principalId" -o tsv)

# Assign Reader role (use Contributor for readwrite access)
az role assignment create --role "Reader" --assignee-object-id $IDENTITY_PRINCIPAL_ID --assignee-principal-type ServicePrincipal --scope "/subscriptions/<subscription-id>"

3. 페더레이션 ID 자격 증명 만들기

AKS_OIDC_ISSUER=$(az aks show --resource-group <your-resource-group> --name <your-aks-cluster> --query "oidcIssuerProfile.issuerUrl" -o tsv)

az identity federated-credential create \
  --name "aks-mcp-federated-credential" \
  --identity-name aks-mcp-identity \
  --resource-group <your-resource-group> \
  --issuer $AKS_OIDC_ISSUER \
  --subject "system:serviceaccount:aks-mcp:aks-mcp" \
  --audience api://AzureADTokenExchange

4. 워크로드 ID를 사용하도록 설정하여 설치

helm install aks-mcp . \
  --namespace aks-mcp \
  --create-namespace \
  --set workloadIdentity.enabled=true \
  --set azure.clientId=$IDENTITY_CLIENT_ID \
  --set azure.subscriptionId=<your-subscription-id>

읽기/쓰기 또는 관리자 작업을 위해 사용자 로그인을 요구하도록 OAuth 인증을 사용하도록 설정합니다.

helm install aks-mcp . \
  --namespace aks-mcp \
  --create-namespace \
  --set app.accessLevel=readwrite \
  --set oauth.enabled=true \
  --set oauth.tenantId=<your-tenant-id> \
  --set oauth.clientId=<your-oauth-client-id> \
  --set azure.subscriptionId=<your-subscription-id>

서비스 주체 자격 증명을 포함하는 Kubernetes 비밀을 사용합니다.

# Create secret first
kubectl create secret generic azure-credentials \
  --namespace aks-mcp \
  --from-literal=tenant-id=<your-tenant-id> \
  --from-literal=client-id=<your-client-id> \
  --from-literal=client-secret=<your-client-secret> \
  --from-literal=subscription-id=<your-subscription-id>

# Install with existing secret
helm install aks-mcp . \
  --namespace aks-mcp \
  --set app.accessLevel=readonly \
  --set azure.existingSecret=azure-credentials

Helm 값을 통해 자격 증명을 직접 전달합니다(프로덕션 환경에서는 권장되지 않습니다).

helm install aks-mcp . \
  --namespace aks-mcp \
  --create-namespace \
  --set azure.tenantId=<your-tenant-id> \
  --set azure.clientId=<your-client-id> \
  --set azure.clientSecret=<your-client-secret>

AKS 확장을 사용하는 VS Code

1. 명령 팔레트(Ctrl+Shift+PWindows/Linux 또는 Cmd+Shift+P macOS)를 엽니다.
2. MCP 실행: 서버 나열
3. 목록에서 AKS MCP 를 선택합니다.
4. 서버 중지를 선택하여 실행 중인 서버를 중지합니다.
5. 구성을 제거하려면 서버 구성 삭제를 선택합니다.

또는 서버 구성을 수동으로 제거합니다.

1. .vscode/mcp.json 파일 또는 VS Code 사용자 설정을 엽니다.
2. aks-mcp-server 또는 servers 개체에서 github.copilot.chat.mcp.servers 항목을 삭제합니다.
3. 시스템에서 AKS-MCP 이진 파일을 삭제합니다(위치는 설치 방법에 따라 다름).

도커

Docker MCP 도구 키트를 사용하는 경우:

1. Docker Desktop을 엽니다.
2. 왼쪽 사이드바에서 MCP 도구 키트 를 선택합니다.
3. AKS-MCP 서버를 찾아 사용하지 않도록 설정합니다.

컨테이너화된 구성을 사용하는 경우 컨테이너를 중지하고 제거합니다.

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

기타 MCP 클라이언트

aks 또는 aks-mcp 항목을 MCP 클라이언트 구성 파일(예: Claude Desktop의 경우)에서 제거합니다.

Helm 릴리스 제거

helm uninstall aks-mcp --namespace aks-mcp

네임스페이스 정리(선택 사항)

kubectl delete namespace aks-mcp

Azure 리소스 정리(워크로드 ID에만 해당)

워크로드 ID를 구성한 경우 연결된 Azure 리소스를 제거합니다.

# Delete the federated credential
az identity federated-credential delete \
  --name "aks-mcp-federated-credential" \
  --identity-name aks-mcp-identity \
  --resource-group <your-resource-group>

# Remove role assignments
IDENTITY_PRINCIPAL_ID=$(az identity show --resource-group <your-resource-group> --name aks-mcp-identity --query "principalId" -o tsv)
az role assignment delete --assignee $IDENTITY_PRINCIPAL_ID --scope "/subscriptions/<subscription-id>"

# Delete the managed identity
az identity delete --resource-group <your-resource-group> --name aks-mcp-identity

Kubernetes 비밀 삭제(서비스 주체만 해당)

서비스 주체 자격 증명에 대한 비밀을 생성한 경우:

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