How do I run Claude Code through Azure AI Foundry?

Azure AI Foundry routes Claude Code through your Azure subscription, subject to your Microsoft data agreements. It is the deployment path for organizations that require all AI traffic to stay within Azure infrastructure.

Step 1: Deploy Claude in Azure AI Foundry

Before configuring Claude Code, you need a Claude model deployed in your Azure AI Foundry resource:

1. In the Azure AI Foundry portal, create or open a project
2. Go to Model catalog and deploy a Claude model
3. Note the Endpoint URL and the Resource name

Your Azure account needs either the Azure AI User or Cognitive Services User role on the Foundry resource. Without one of these roles, every API call will return a 403.

Step 2: Configure Claude Code

Using the resource name:

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name

Or using the full base URL directly:

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_BASE_URL=https://your-resource.services.ai.azure.com

Step 3: Authenticate

Entra ID (recommended for interactive use):

az login

Once logged in, Claude Code uses your Entra ID token automatically. No additional environment variables needed.

API key auth (for CI and service accounts):

export ANTHROPIC_FOUNDRY_API_KEY=your-api-key

Find the API key in the Azure AI Foundry portal under your resource’s keys and endpoints page.

The API key and Entra ID paths are mutually exclusive. If ANTHROPIC_FOUNDRY_API_KEY is set, it takes precedence over the Entra ID token.

Error behavior

Foundry handles startup errors differently from Bedrock and Vertex. On Bedrock and Vertex, a misconfigured model silently falls back to a default. On Foundry, errors surface immediately at startup.

If the model deployment is not available or your credentials lack the required role, Claude Code exits with an explicit error message rather than starting and failing later. This is more helpful for debugging, but it means you need to resolve the error before the session starts.

What Foundry does NOT support

These features require claude.ai infrastructure.

Foundry vs Bedrock vs Vertex

Foundry’s single-deployment model simplifies region routing: you pick the region when you deploy, and Claude Code uses that deployment. No cross-region routing configuration.

Footguns

Azure role assignments take a few minutes to propagate. If you assign the Azure AI User role and immediately try to authenticate, you may see a 403 for 2-5 minutes. Wait before testing.

az login tokens expire after roughly 1 hour, and there is no gcpAuthRefresh-equivalent for Foundry. For sessions longer than an hour, use an API key or implement token refresh in your environment separately.

ANTHROPIC_FOUNDRY_RESOURCE takes the resource name, not the project name. Azure AI Foundry projects contain resources. Use the resource name shown in the endpoint URL.

Model names in Foundry use the deployment name you assigned, not the Anthropic model ID format. If you deployed Claude Sonnet as claude-sonnet-4-6, set ANTHROPIC_MODEL=claude-sonnet-4-6. Check the deployment name in the Foundry portal.

When NOT to use Foundry

• Your organization uses AWS or GCP. Use Bedrock or Vertex for consistent cloud provider coverage.
• You need fast mode or ultraplan. Use claude.ai directly.
• You need credential rotation automation. Foundry does not have a built-in refresh hook; build your own or use API keys with long expiration.
• You need the GitHub App, Code Review, or Remote Control features. None of these are available outside claude.ai.