When ANTHROPIC_FOUNDRY_API_KEY is not set, Claude Code automatically uses the Azure SDK default credential chain.
This supports a variety of methods for authenticating local and remote workloads.
On local environments, you commonly may use the Azure CLI:
az login
3. Configure Claude Code
Set the following environment variables to enable Microsoft Foundry:
# Enable Microsoft Foundry integrationexport 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. Pin model versions
Set the model variables to match the deployment names you created in step 1.
Without ANTHROPIC_DEFAULT_OPUS_MODEL, the opus alias on Microsoft Foundry resolves to Opus 4.6. Set it to the Opus 4.8 ID to use the latest model:
Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Microsoft Foundry, Claude Code defaults this to the primary model because not every account has a Haiku deployment. To use Haiku for background tasks, set ANTHROPIC_DEFAULT_HAIKU_MODEL to a Haiku deployment that is available in your account, as shown above.
Prompt caching is enabled automatically. To request a 1-hour cache TTL instead of the 5-minute default, set the following variable; cache writes with a 1-hour TTL are billed at a higher rate:
export ENABLE_PROMPT_CACHING_1H=1
5. Run Claude Code
With the environment variables set, start Claude Code from your project directory:
claude
Claude Code reads CLAUDE_CODE_USE_FOUNDRY and the other Microsoft Foundry variables from the environment and connects to your Azure resource on the first prompt. Unlike Amazon Bedrock and Google Cloud's Agent Platform, Microsoft Foundry has no interactive setup wizard, so the environment variables in steps 3 and 4 are the only configuration path.
Azure RBAC configuration
The Azure AI User and Cognitive Services User default roles include all required permissions for invoking Claude models.
For more restrictive permissions, create a custom role with the following:
150### 4. Pin model versions150### 4. Pin model versions
151151
152<Warning>152<Warning>
153 Pin specific model versions for every deployment. Without pinning, model aliases such as `sonnet` and `opus` resolve to Claude Code's built-in default for Foundry, which can lag the newest release and may not yet be available in your account. Foundry has no startup model check, so requests fail when the default is unavailable. When you create Azure deployments, select a specific model version rather than "auto-update to latest."153 Pin specific model versions for every deployment. Without pinning, model aliases such as `sonnet` and `opus` resolve to Claude Code's built-in default for Microsoft Foundry, which can lag the newest release and may not yet be available in your account. Microsoft Foundry has no startup model check, so requests fail when the default is unavailable. When you create Azure deployments, select a specific model version rather than "auto-update to latest."
154</Warning>154</Warning>
155155
156Set the model variables to match the deployment names you created in step 1.156Set the model variables to match the deployment names you created in step 1.
157157
158Without `ANTHROPIC_DEFAULT_OPUS_MODEL`, the `opus` alias on Foundry resolves to Opus 4.6. Set it to the Opus 4.8 ID to use the latest model:158Without `ANTHROPIC_DEFAULT_OPUS_MODEL`, the `opus` alias on Microsoft Foundry resolves to Opus 4.6. Set it to the Opus 4.8 ID to use the latest model:
166Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Foundry, Claude Code defaults this to the primary model because not every account has a Haiku deployment. To use Haiku for background tasks, set `ANTHROPIC_DEFAULT_HAIKU_MODEL` to a Haiku deployment that is available in your account, as shown above.166Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Microsoft Foundry, Claude Code defaults this to the primary model because not every account has a Haiku deployment. To use Haiku for background tasks, set `ANTHROPIC_DEFAULT_HAIKU_MODEL` to a Haiku deployment that is available in your account, as shown above.
167167
168For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) for the full list of environment variables.168For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) for the full list of environment variables.
169169
181claude181claude
182```182```
183183
184Claude Code reads `CLAUDE_CODE_USE_FOUNDRY` and the other Foundry variables from the environment and connects to your Azure resource on the first prompt. Unlike Bedrock and VertexAI, Foundry has no interactive setup wizard, so the environment variables in steps 3 and 4 are the only configuration path.184Claude Code reads `CLAUDE_CODE_USE_FOUNDRY` and the other Microsoft Foundry variables from the environment and connects to your Azure resource on the first prompt. Unlike Amazon Bedrock and GoogleCloud's Agent Platform, Microsoft Foundry has no interactive setup wizard, so the environment variables in steps 3 and 4 are the only configuration path.
