Azure AI Gateway MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

Azure OpenAI / MCP 서버 앞의 APIM을 거버넌스 계층으로 사용
구독별, 모델별, 팀별 토큰 할당량
확정적 완성의 캐싱을 통한 비용 절감
여러 AOAI 지역 간 로드 밸런싱 + 페일오버
감사를 위한 App Insights로의 전체 요청/응답 로깅

라이브 데모

실제 사용 모습

azure-ai-gateway.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "azure-ai-gateway": {
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "azure-ai-gateway": {
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "azure-ai-gateway": {
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "azure-ai-gateway": {
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "azure-ai-gateway",
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "azure-ai-gateway": {
      "command": {
        "path": "uvx",
        "args": [
          "azure-ai-gateway-mcp"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add azure-ai-gateway -- uvx azure-ai-gateway-mcp

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Azure AI Gateway

Azure OpenAI 배포 전체에서 팀별 토큰 할당량 적용

👤 LLM 지출을 관리하는 중앙 플랫폼 팀 ⏱ ~30 min advanced

언제 쓸까: 여러 제품 팀이 AOAI를 공유할 때; 한 팀의 폭발적 증가가 공유 TPM 예산을 소모해서는 안 됩니다.

사전 조건

AI-Gateway 패턴이 적용된 APIM 인스턴스 — Azure-Samples/AI-Gateway 저장소에서 참조 아키텍처 배포
팀별 APIM 구독 키 — 각 팀은 Ocp-Apim-Subscription-Key 헤더에 포함시키는 고유한 APIM 구독(키)을 받습니다

흐름

현재 할당량 검토

AOAI 제품의 현재 TPM 및 RPM 할당량을 가진 APIM 구독을 나열하세요.✓ 복사됨

→ 팀별 할당량 표
시끄러운 팀의 할당량 감소

'growth' 팀이 일일 90% TPM 소모로 진행 중입니다. 할당량을 200k → 100k TPM으로 감소하세요. 다른 팀은 변경하지 않습니다.✓ 복사됨

→ 할당량 업데이트됨; 확인
변경 후 모니터링

다음 1시간 동안 구독별 429(속도 제한) 카운트를 수집하세요. growth 팀이 제한되고 있지만 프로덕션 핵심 팀은 영향을 받지 않는지 확인합니다.✓ 복사됨

→ 메트릭에서 적용 가능 확인

결과: 합법적인 높은 우선순위 트래픽을 방해하지 않으면서 공유 AOAI 지출을 제어합니다.

함정

할당량을 너무 낮게 설정하면 합법적인 워크로드가 기아 상태가 됩니다 — 먼저 섀도우 모드(로그만)로 배포한 후, 실제 패턴을 이해하면 적용하세요

Azure OpenAI 배포를 위한 다중 지역 페일오버 구성

👤 프로덕션 AI 워크로드를 운영하는 SRE ⏱ ~45 min advanced

언제 쓸까: 지역 AOAI 중단(드물지만 실제)이 다른 지역으로 투명하게 페일오버되어야 합니다.

사전 조건

2개 이상 지역의 AOAI 배포(예: East US, West Europe) — Azure 포털을 통해 프로비저닝하세요; 모델 + 버전 일치

흐름

현재 백엔드 풀 검사

우리의 AOAI API에 대한 APIM 백엔드 풀을 보여주세요. 백엔드 수, 우선순위, 회로 차단기 구성은?✓ 복사됨

→ 현재 풀 구성
보조 지역 추가

West Europe AOAI 엔드포인트를 priority=2로 추가하고 회로 차단기: 1분에 5회 실패 → 5분 개방. East US는 기본으로 유지하세요.✓ 복사됨

→ 풀 업데이트됨, 2개 백엔드 구성됨
페일오버 테스트

East US 백엔드를 2분간 비활성화하여 기본 중단을 시뮬레이션합니다. 트래픽이 West Europe으로 이동하는지 확인한 후 롤백합니다.✓ 복사됨

→ 트래픽 이동 확인됨; 롤백 확인됨

결과: 필요하기 전에 작동하는 증거가 있는 투명한 페일오버.

함정

다른 지역에는 배포된 모델의 다른 버전이 있습니다 — 두 지역 모두에 존재하는 모델 버전으로 고정하세요; 불일치하는 버전은 조용히 다른 품질을 반환합니다

반복 프롬프트 비용을 줄이기 위해 의미론적 캐싱 배포

👤 비용 의식이 있는 플랫폼 팀 ⏱ ~30 min advanced

언제 쓸까: 사용자가 반복적으로 유사한 질문을 할 때; 호출의 30–60%가 효과적으로 캐시 히트입니다.

흐름

의미론적 캐시 정책 활성화

AOAI 완성 API에서 APIM 의미론적 캐시 조회 정책을 활성화하세요. 유사성 임계값 0.95, TTL 1시간.✓ 복사됨

→ 정책 적용됨
히트율 관찰

24시간 후 App Insights에서 캐시 히트율 및 토큰 절감을 수집하세요.✓ 복사됨

→ 히트율 % + 절감된 토큰
임계값 조정

히트율이 20% 미만이면 임계값을 0.92로 낮추고 다시 관찰하세요. 품질 불만이 있으면 0.97로 다시 올리세요.✓ 복사됨

→ 측정을 통한 반복적 조정

결과: 출력 품질을 저하시키지 않으면서 반복 쿼리의 측정된 비용 절감.

함정

과도하게 적극적인 캐싱은 유사하지만 다른 질문에 대해 잘못된 답을 제공합니다 — 높게(0.97) 시작하고 관찰된 품질을 기반으로만 낮추세요

조합

다른 MCP와 조합해 10배 효율

azure-ai-gateway + sentry

APIM 5xx 스파이크를 애플리케이션 측 오류와 연관시키기

Sentry가 10:02에 앱 X에서 5xx 스파이크를 표시하면, 같은 시간 창에 대한 APIM 메트릭을 수집하고 게이트웨이가 원인인지 확인합니다.✓ 복사됨

azure-ai-gateway + notion

Notion에 주간 AI 트래픽 거버넌스 보고서

주간 팀별 TPM 사용, 429 카운트, 캐시 히트율을 컴파일하여 Notion 페이지로 게시합니다.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
list_subscriptions	product_id?	게이트웨이를 사용하는 팀의 인벤토리	무료(ARM API 호출)
update_quota	subscription_id, tpm?, rpm?	팀의 토큰/요청 한도 조정	무료
get_backend_pool	api_id	라우팅 및 페일오버 구성 검사	무료
update_backend_pool	api_id, backends, policies	우선순위, 회로 차단기, 로드 밸런싱 변경	무료
apply_policy	api_id, policy_xml	APIM 정책 배포(캐시, 인증, 로깅)	무료
get_metrics	api_id, since, until	API별 트래픽 형태 관찰	무료

비용 및 제한

운영 비용

API 쿼터: Azure Resource Manager 속도 제한(테넌트당 넉넉함)
호출당 토큰: 정책/백엔드 풀 읽기: 500–2000 토큰
금액: APIM 가격은 월 약 $40부터 시작(기본 계층); 프로덕션의 경우 표준 계층 권장
팁: 의미론적 캐싱은 트래픽이 반복되면 APIM의 비용을 여러 배로 절감합니다. 히트율을 측정하여 정당화하세요.

보안

권한, 시크릿, 파급범위

최소 스코프: 대상 APIM 인스턴스에 대한 APIM 기여자

자격 증명 저장: 환경의 Azure 서비스 주체 자격 증명(클라이언트 id/시크릿/테넌트)

데이터 외부 송신: management.azure.com으로의 ARM API 호출; 프롬프트/응답 본문은 APIM 자체를 통과합니다

절대 부여 금지: 구독의 소유자 전역 관리자

AI-Gateway 저장소는 참조/샘플 코드입니다; 프로덕션에 있는 그대로 배포하기 전에 검토하세요.
요청/응답 로깅은 PII를 캡처할 수 있으므로 App Insights로 전송하기 전에 정책에서 마스킹하세요.

문제 해결

자주 발생하는 오류와 해결

ARM API 호출에서 401

서비스 주체가 리소스 그룹에 대한 APIM 기여자 역할이 없습니다. 포털 또는 az cli를 통해 권한을 부여하세요.

확인: az role assignment list --assignee <sp>

정책 적용 실패 — XML 유효성 검사 오류

APIM 정책 XML은 엄격합니다; 포털의 정책 편집기를 사용하여 유효성을 검사한 후 복사-붙여넣기를 하세요.

TPM 할당량 증가 후에도 429가 지속됩니다

기본 AOAI 배포 자체가 병목이 될 수 있습니다. APIM 구독 TPM만 아니라 배포 TPM을 확인하세요.

의미론적 캐시 히트율이 0%입니다

캐시 조회용 임베딩 백엔드가 구성되지 않았습니다; 캐시 정책의 임베딩 참조를 확인하세요.

대안

Azure AI Gateway 다른 것과 비교

대안	언제 쓰나	단점/장점
Cloudflare AI Gateway	Cloudflare를 사용 중이고 다중 제공자 LLM 라우팅을 기본으로 원하는 경우	Azure 호스팅 모델과의 덜 깊은 통합
Portkey / LiteLLM	제공자와 무관한 대시보드가 있는 게이트웨이를 원하는 경우	타사 SaaS; 데이터가 클라우드를 벗어납니다

Azure AI Gateway

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: Azure AI Gateway

사전 조건

흐름

함정

사전 조건

흐름

함정

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

Azure AI Gateway 다른 것과 비교

더 보기

리소스