How to run Claude Code on Microsoft Foundry
To run Claude Code on Microsoft Foundry, create a Foundry resource in the Azure portal and deploy the Claude models you want to use. Then set CLAUDE_CODE_USE_FOUNDRY=1, set ANTHROPIC_FOUNDRY_RESOURCE to your resource name, give Claude Code a way to sign in to Azure, pin your model deployments, and run claude. Run /status to confirm the API provider line says Microsoft Foundry.
The one thing that surprises people coming from the other clouds: Foundry has no setup wizard. On Amazon Bedrock and Google Vertex AI you can pick the provider from the login menu and answer a few prompts. On Foundry, Anthropic's docs say the environment variables are the only configuration path. So this setup is a short list of variables, and getting each one right is the whole job.
Once it works, model requests go to your Azure resource and you pay through your Azure subscription. CLAUDE.md, skills, subagents, hooks, MCP servers, plugins, checkpoints and the VS Code and JetBrains extensions all work the same as they do on a Claude plan.
Should you use Microsoft Foundry or a Claude plan?
If you are building for yourself, start with a Claude plan and the Claude Code desktop app. It is the easiest setup and it includes features no cloud provider can reach. Which Claude plan for Claude Code covers that choice. Foundry earns the extra setup when your company already runs on Azure and wants Claude on the same bill, under the same identity system.
- Your company already pays Microsoft for Azure and wants Claude usage on that invoice.
- Your team signs in with Microsoft Entra ID and security wants access managed through Azure roles, not separate keys.
- You run Claude Code in GitHub Actions and want those runs billed to Azure instead of a Claude API key.
If none of those apply, the cloud route mostly costs you features. The table at the end of this post lists what you give up.
Step 1: create the resource and deploy the models
- Check access. You need an Azure subscription with access to Microsoft Foundry and permission to create Foundry resources and deployments. The Azure CLI is optional and only needed if you plan to sign in with az login.
- Create the resource. In the Microsoft Foundry portal, create a new resource and write down its name. Claude Code builds the endpoint from it.
- Deploy the models. Create a deployment for Claude Opus, Claude Sonnet and Claude Haiku. Write down each deployment name, because those names are what you set as Claude Code's model variables later.
- Pick a fixed version. When you create each deployment, choose a specific model version rather than auto-update to latest. The Claude Code docs ask for this so the model under a name does not change on your team.
When you configure a deployment you also pick a hosting option. Hosted on Azure runs an Anthropic-operated service on Azure infrastructure and is the recommended choice for most workloads. Hosted on Anthropic runs on Anthropic's infrastructure and gives access to models or features not yet hosted on Azure. The deployment name defaults to the model ID and cannot be changed after you create it, so keep that default unless you have a reason not to. It makes the 1M context step below easier.
Step 2: pick how Claude Code signs in to Azure
The three ways Claude Code authenticates to Microsoft Foundry
| Method | What you set | Best for |
|---|---|---|
| API key | ANTHROPIC_FOUNDRY_API_KEY, copied from Endpoints and keys on your resource | A quick personal test |
| Microsoft Entra ID | Nothing. Leave both key variables unset and sign in with az login | Teams that already use Azure sign-in, with no key to store |
| Bearer token | ANTHROPIC_FOUNDRY_AUTH_TOKEN, a token another process got from Entra ID | A host app or sign-in script that already fetches tokens |
If more than one is present, ANTHROPIC_FOUNDRY_AUTH_TOKEN wins over ANTHROPIC_FOUNDRY_API_KEY and over the default credential chain. Because sign-in runs through Azure, /logout does not work on this provider.
My pick for anything beyond a solo test is Entra ID. There is no long-lived key sitting in a shell profile or a settings file, and access is granted and removed with the same Azure roles your company already manages.
Step 3: set the Foundry variables
- CLAUDE_CODE_USE_FOUNDRY=1 turns the Foundry provider on.
- ANTHROPIC_FOUNDRY_RESOURCE is your resource name on its own, such as my-resource. Do not paste a URL or host name here. Claude Code refuses it when you send a message.
- ANTHROPIC_FOUNDRY_BASE_URL is the alternative if you would rather give the full address, in the form https://{resource}.services.ai.azure.com/anthropic.
Put these in the env block of your settings file so they load every time, not only in the shell where you exported them. The settings.json guide shows where that block goes, and Claude Code environment variables covers the other places you can set them.
Step 4: pin your models (do not skip this)
Pinning matters more on Foundry than anywhere else in this series. Without a pin, aliases like opus and sonnet resolve to Claude Code's built-in default for Foundry, which can lag the newest release or not exist in your account. And because Foundry has no startup model check, nothing warns you. Your requests just fail.
- Set ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL and ANTHROPIC_DEFAULT_HAIKU_MODEL to the deployment names you created in step 1. The docs' example uses claude-opus-4-8, claude-sonnet-5 and claude-haiku-4-5.
- Without ANTHROPIC_DEFAULT_OPUS_MODEL, the opus alias on Foundry resolves to Opus 4.6, so set it if you want a newer Opus.
- Background jobs like naming your session normally use a small, fast model. On Foundry, Claude Code uses your primary model for them, because not every account has a Haiku deployment. Set ANTHROPIC_DEFAULT_HAIKU_MODEL to a Haiku deployment you have if you want Haiku there.
- Prompt caching is on automatically. Set ENABLE_PROMPT_CACHING_1H=1 only if you want a 1-hour cache instead of the 5-minute default, and know that 1-hour cache writes are billed at a higher rate.
Model choice is the biggest lever on what this costs you, whichever cloud you are on. How much Claude Code costs per month breaks that down.
Get the 1M token context window
Claude Code reads which model you are using from the deployment name. When it can tell, Fable models, Sonnet 5 and later, and Opus 4.7 and later get the 1M token context window by default on Foundry. That is why keeping the model ID as the deployment name helps.
- If your deployment has a custom name, such as team-opus-prod, map it with modelOverrides in settings.json so Claude Code knows which model it serves.
- For a name it cannot match to a model, Claude Code assumes a 200K window.
- Opus 4.6 and Sonnet 4.6 reach 1M when you add [1m] to the end of the deployment name in the model variable.
- To stay at 200K on purpose, set CLAUDE_CODE_DISABLE_1M_CONTEXT=1.
The Azure role Claude Code needs
The built-in Azure AI User and Cognitive Services User roles both include everything Claude Code needs to call Claude models. Give one of them to the identity Claude Code runs as, whether that is a person signed in with az login or a service principal in CI.
If your security team wants the narrowest access, the docs give a custom role with a single data action: Microsoft.CognitiveServices/accounts/providers/*. That is enough to invoke the models and nothing else.
What you give up on Microsoft Foundry
The core of Claude Code runs on Foundry, but anything that needs a claude.ai sign-in does not. Here is what Anthropic's feature availability page lists for this provider.
Claude Code features not available or limited on Microsoft Foundry
| Feature | On Microsoft Foundry | Use instead |
|---|---|---|
| Cloud scheduled tasks (/schedule) | Not available | /loop, which runs on your machine |
| Cloud sessions and Claude Code on mobile | Not available | GitHub Actions |
| GitLab CI/CD | Not available | GitHub Actions |
| Remote Control, Chrome extension, computer use, voice dictation | Not available | No direct replacement |
| Fast mode, Advisor, Channels, server-managed settings, analytics dashboard | Not available | No direct replacement |
| MCP tool search | Not supported on deployments hosted on Azure | A Hosted on Anthropic deployment |
| Auto mode | Only on Sonnet 5 or later, Opus 4.7 or later, Haiku 5.5 and Fable models | Pin a supported model |
| The standard desktop app | Partial | Claude Desktop on 3P |
Two of these are specific to Foundry. GitLab CI/CD works on Bedrock and Vertex AI but not here, so a GitLab shop should weigh that before choosing Azure. And MCP tool search is off on deployments hosted on Azure, which matters if you connect a lot of MCP servers. Error reporting and telemetry to Anthropic are off by default on this provider.
Fixes for common Microsoft Foundry errors
- "Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed": Claude Code found no key and no working Entra ID sign-in. Run az login, or set ANTHROPIC_FOUNDRY_API_KEY.
- Repeated connection errors on the first prompt: ANTHROPIC_FOUNDRY_RESOURCE is probably still a placeholder or a typo. Claude Code builds the endpoint from it, so a wrong name points at a host that does not exist.
- An error about the resource name when you send a message: you set a URL or host name in ANTHROPIC_FOUNDRY_RESOURCE. Use the bare resource name, or move the full URL to ANTHROPIC_FOUNDRY_BASE_URL.
- Requests fail with no clear reason after an update: an unpinned alias now points at a model you have not deployed. Pin all three model variables to your deployment names.
If you want Claude Code running in CI against Azure instead of in cloud sessions, Claude Code GitHub Actions covers the workflow side.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
How do I use Claude Code with Microsoft Foundry?
Create a Foundry resource in Azure and deploy the Claude models you want. Then set CLAUDE_CODE_USE_FOUNDRY=1, ANTHROPIC_FOUNDRY_RESOURCE to your resource name, a sign-in method and your model pins, and run claude. Check /status for Microsoft Foundry on the API provider line.
Is there a setup wizard for Claude Code on Microsoft Foundry?
No. Amazon Bedrock and Google Vertex AI have one, but on Microsoft Foundry environment variables are the only way to configure Claude Code.
Do I need an API key to use Claude Code on Foundry?
No. You can leave the key unset and sign in with Microsoft Entra ID, for example through az login. You can also pass a bearer token in ANTHROPIC_FOUNDRY_AUTH_TOKEN, or use an API key from the Endpoints and keys section of your resource.
Which Azure role does Claude Code need on Microsoft Foundry?
Azure AI User or Cognitive Services User both include the permissions needed to call Claude models. For the narrowest access, use a custom role with the Microsoft.CognitiveServices/accounts/providers/* data action.
Does GitLab CI/CD work with Claude Code on Microsoft Foundry?
No. GitLab CI/CD is listed as not available on Microsoft Foundry. Use GitHub Actions for CI runs, or /loop for scheduled work on your own machine.
Last reviewed by David Iya on October 26, 2026
