Claude Code on Microsoft Foundry

Claude Code를 Microsoft Foundry를 통해 사용하도록 구성하는 가이드예요. 설정·구성·트러블슈팅을 다룬다. 전제조건은 Microsoft Foundry 접근 권한이 있는 Azure 구독, Foundry 리소스·배포를 만들 RBAC 권한, Azure CLI 설치·구성(선택)이에요. 여러 사용자에게 배포한다면 모델 버전을 먼저 고정하세요.

출처: 공식문서

본문

설정하기

1. Microsoft Foundry 리소스 프로비저닝 — Microsoft Foundry 포털에서 Claude 리소스를 만들어요. 리소스 이름을 기록하고, Claude Opus·Sonnet·Haiku의 배포를 만들며 각 배포 이름을 기록해요(4단계에서 모델 변수로 씀). 배포 구성 시 호스팅 옵션(추론이 Azure에서 돌지 Anthropic 인프라에서 돌지 결정)도 선택해요.

2. Azure 자격 증명 구성 — 세 가지 인증 방법을 지원해요.

Option A: API 키 인증 — Foundry 포털의 리소스 → Endpoints and keys 섹션에서 API Key를 복사해 환경변수로 설정.

export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key

Option B: Microsoft Entra ID 인증 — ANTHROPIC_FOUNDRY_API_KEY도 ANTHROPIC_FOUNDRY_AUTH_TOKEN도 설정 안 하면 Azure SDK default credential chain을 자동 사용해요. 로컬에선 Azure CLI를 주로 써요.

az login

Option C: Bearer 토큰 인증 — ANTHROPIC_FOUNDRY_AUTH_TOKEN 값을 매 요청마다 Authorization 헤더로 보내요. 호스트 앱·로그인 스크립트 같은 다른 프로세스가 이미 access token을 얻은 경우에 사용(v2.1.203+). ANTHROPIC_FOUNDRY_AUTH_TOKEN은 ANTHROPIC_FOUNDRY_API_KEY와 기본 credential chain보다 우선해요.

export ANTHROPIC_FOUNDRY_AUTH_TOKEN=your-entra-access-token

Foundry 사용 시 /logout은 사용 불가(Azure 자격 증명으로 인증하므로).

3. Claude Code 구성

# Enable Microsoft Foundry integration
export CLAUDE_CODE_USE_FOUNDRY=1

# Azure resource name (replace {resource} with your resource name)
export ANTHROPIC_FOUNDRY_RESOURCE={resource}
# Or provide the full base URL:
# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com/anthropic

4. 모델 버전 고정

모든 배포에 대해 특정 모델 버전을 고정해야 해요. 고정하지 않으면 sonnet·opus 별칭이 Foundry용 내장 기본값으로 해석되고, Foundry는 시작 시 모델 검사가 없어 기본이 없으면 요청이 실패해요. Azure 배포를 만들 때 "auto-update to latest" 대신 특정 버전을 선택하세요.

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

백그라운드 작업(세션 제목 생성)은 보통 Haiku급 모델을 쓰는데 Foundry에선 모든 계정에 Haiku 배포가 있는 게 아니라 기본 primary 모델로 설정돼요. Haiku를 쓰려면 ANTHROPIC_DEFAULT_HAIKU_MODEL을 계정에서 쓸 수 있는 Haiku 배포로 설정하세요.

프롬프트 캐싱은 자동 활성화. 기본 5분 대신 1시간 TTL은 ENABLE_PROMPT_CACHING_1H=1(높은 요율로 청구).

5. Claude Code 실행

환경변수가 설정되면 프로젝트 디렉터리에서 claude를 실행해요. Claude Code는 CLAUDE_CODE_USE_FOUNDRY와 다른 Foundry 변수를 환경에서 읽고 첫 프롬프트에서 Azure 리소스에 연결해요. Amazon Bedrock·Google Cloud's Agent Platform과 달리 Foundry는 대화형 설정 마법사가 없어서 3·4단계의 환경변수가 유일한 구성 경로예요. /status에서 API provider 줄에 Microsoft Foundry가 보이면 성공.

Azure RBAC 구성

Azure AI User와 Cognitive Services User 기본 역할엔 Claude 모델 호출에 필요한 모든 권한이 포함돼요. 더 제한하려면 다음 권한으로 커스텀 역할을 만들어요.

{
  "permissions": [
    {
      "dataActions": [
        "Microsoft.CognitiveServices/accounts/providers/*"
      ]
    }
  ]
}

트러블슈팅

"Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed": 환경에 Entra ID를 구성하거나 ANTHROPIC_FOUNDRY_API_KEY 설정.
첫 프롬프트에서 반복 연결 오류: ANTHROPIC_FOUNDRY_RESOURCE가 실제 리소스 이름인지 확인하세요. Claude Code가 이 값으로 엔드포인트 URL을 만들기 때문에 잘못된 이름은 존재하지 않는 호스트를 가리켜요.

Claude Code on Microsoft Foundry