Run Claude Code on Microsoft Foundry: Step-by-Step Setup for VS Code and the CLI

Claude Code can run against Claude models deployed in your own Microsoft Foundry resource,
authenticated with Microsoft Entra ID — az login on a workstation, managed identity on
Azure compute. No Anthropic account, no API key on disk, no proxy.

This is the procedure. Steps 1–3 are shared setup, Step 4 is the VS Code extension, Step 5
is the CLI, Step 6 verifies. Steps 4 and 5 are independent — do either or both.

Verified on 13 Aug 2026, Claude Code v2.1.223, against claude-sonnet-5 and
claude-opus-5 in East US 2.

Step 0 — Find your values (start here)

The whole setup needs five values. Here is what each one looks like, where it lives, and the
command that prints it. Examples below are real values from my own subscription with a few
characters masked.

Where they live in the Azure portal

Open portal.azure.com → search your Foundry resource by name →
Overview. Everything except the deployment names is on this one blade:

Read off:

• Resource name — the page title. API Kind must say AIServices.
• Resource group and Subscription / Subscription ID — in Essentials.
• Location — the region, for Step 1.
• Keys and Endpoint (left nav, under Resource Management) — the endpoint URLs.
• Access control (IAM) (left nav) — where you add the role in Step 2.

Deployment names are not in the Azure portal. Click Go to Foundry portal at the top of
that blade, then View deployments on the project home — or just use the CLI below, which is
faster.

Or get everything from the CLI

az login

# subscription + tenant
az account show --query "{subscription:id, tenant:tenantId, user:user.name}" -o table

# every Foundry resource you can see, with its resource group and region
az cognitiveservices account list `
    --query "[?kind=='AIServices'].{name:name, rg:resourceGroup, region:location}" -o table

# the deployment names on one of them
az cognitiveservices account deployment list -n <resource> -g <rg> -o table

Or run Get-FoundryValues.ps1,
which finds every value, checks the RBAC role, and prints the exact config block to paste into
Steps 4 and 5. With no arguments it scans your subscription and picks a resource that actually
has Claude deployments. Add -Mask when screenshotting or pasting into a ticket:

.\Get-FoundryValues.ps1 -Mask

The last block is the config you need — copy it straight into Step 4.2 or 5.2.

Prerequisites

If you don't yet know your resource name, resource group or deployment names, do Step 0 first.

Step 1 — Confirm your Claude deployments

az cognitiveservices account deployment list -n <resource> -g <rg> -o table

Note the deployment names in the output. These are the names you configure later — they are
yours, not Anthropic's catalogue names.

To create a deployment:

az cognitiveservices account deployment create `
    -n <resource> -g <rg> `
    --deployment-name claude-haiku-4-5 `
    --model-name claude-haiku-4-5 --model-version 2 --model-format Anthropic `
    --sku-name GlobalStandard --sku-capacity 1

To list what your region offers:

az cognitiveservices model list -l <region> -o json |
    ConvertFrom-Json |
    Where-Object { $_.model.format -eq 'Anthropic' } |
    ForEach-Object { $_.model.name } | Sort-Object -Unique

If deployment creation fails with a Marketplace error — Claude models bill through Azure
Marketplace. Internal, sandbox, CSP, student and sponsored-credit subscriptions are blocked
from creating them:

ERROR: Marketplace purchases are disabled for this subscription due to policy restrictions.

Existing deployments keep working. Map the missing alias to a deployment you do have (Step 4.2).

Step 2 — Grant data-plane access

Owner on the subscription is not sufficient — that is control plane. Inference needs the
data-plane role Cognitive Services User (a97b65f3-24c7-4388-baec-2e87135dc908).

$scope = az cognitiveservices account show -n <resource> -g <rg> --query id -o tsv

az role assignment create `
    --assignee "<upn-or-object-id>" `
    --role "Cognitive Services User" `
    --scope $scope

Verify:

az role assignment list --assignee "<you>" --scope $scope --include-inherited -o table

Step 3 — Sign in with Entra ID

Workstation:

az login
az account set --subscription <subscription-id>

Azure compute (VM, Container App, DevBox) — managed identity:

az login --identity                          # system-assigned
az login --identity --username <client-id>   # user-assigned

Assign the same role from Step 2 to the identity:

az role assignment create `
    --assignee-object-id <managed-identity-principal-id> `
    --assignee-principal-type ServicePrincipal `
    --role "Cognitive Services User" `
    --scope $scope

Confirm a token is obtainable:

az account get-access-token --resource https://cognitiveservices.azure.com --query expiresOn -o tsv

Both https://cognitiveservices.azure.com and https://ai.azure.com are accepted scopes.

Optional — prove the endpoint answers before involving Claude Code at all:

$t = az account get-access-token --resource https://cognitiveservices.azure.com --query accessToken -o tsv

Invoke-RestMethod -Method Post `
    -Uri "https://<resource>.services.ai.azure.com/anthropic/v1/messages" `
    -Headers @{ Authorization = "Bearer $t"; 'anthropic-version' = '2023-06-01' } `
    -ContentType 'application/json' `
    -Body '{"model":"claude-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"Reply with exactly: FOUNDRY-OK"}]}'

Step 4 — VS Code extension setup

4.1 Install the extension

code --install-extension anthropic.claude-code

Or: Ctrl+Shift+X → search Claude Code → Install (publisher: Anthropic).

The extension bundles its own engine. The npm CLI in Step 5 is not required for the panel to work.

4.2 Configure

Open Ctrl+Shift+P → Preferences: Open User Settings (JSON) and add:

{
  "claudeCode.environmentVariables": [
    { "name": "CLAUDE_CODE_USE_FOUNDRY",        "value": "1" },
    { "name": "ANTHROPIC_FOUNDRY_RESOURCE",     "value": "<your-resource-name>" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL",   "value": "claude-opus-5" },
    { "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL",  "value": "claude-haiku-4-5" }
  ]
}

Rules:

1. ANTHROPIC_FOUNDRY_RESOURCE is the resource name, not a URL. Claude Code expands it to https://<resource>.services.ai.azure.com/anthropic.
2. Pin all three model aliases to deployment names that exist. Foundry mode does no start-up model check, so a wrong alias fails mid-task as DeploymentNotFound, not at launch. If claude-haiku-4-5 is not deployed, set the haiku alias to your Sonnet deployment.
3. Set no key. Leaving ANTHROPIC_FOUNDRY_API_KEY and ANTHROPIC_FOUNDRY_AUTH_TOKEN unset is what makes Claude Code fall through to DefaultAzureCredential.

If you also complete Step 5, ~/.claude/settings.json alone is sufficient for the extension and
this block is redundant — I tested that by deleting it and re-running. Either location works.

4.3 Reload and open the panel

1. Ctrl+Shift+P → Developer: Reload Window
2. Ctrl+Shift+P → Claude Code: Open in Side Bar

The panel opens straight into a usable prompt. There is no sign-in step — that absence is the
first signal Entra ID resolved.

4.4 Confirm it answers

Type any question about the open folder and send it. The panel calls its normal file tools and
answers from your Foundry deployment.

/status does not work in the panel — it returns "/status isn't available in this
environment." Use Step 5.3 to inspect the provider.

Step 5 — Claude Code CLI setup

5.1 Install

npm install -g @anthropic-ai/claude-code
claude --version

5.2 Configure

Create or edit %USERPROFILE%\.claude\settings.json (~/.claude/settings.json on macOS/Linux):

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_RESOURCE": "<your-resource-name>",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Same three rules as 4.2. For a one-off session, use environment variables instead:

$env:CLAUDE_CODE_USE_FOUNDRY    = "1"
$env:ANTHROPIC_FOUNDRY_RESOURCE = "<your-resource-name>"
claude

5.3 Verify the provider

claude auth status

{ "loggedIn": true, "authMethod": "third_party", "apiProvider": "foundry" }

claude doctor

CLAUDE_CODE_USE_FOUNDRY is set, so this session is using Microsoft Foundry
- Not connected to the Anthropic API (api.anthropic.com)
- Not signed in to claude.ai

Then start an interactive session and run /status — it reports API provider: Microsoft
Foundry and the resource name (the screenshot at the top of this post).

claude

5.4 One headless check

claude -p "Reply with exactly: FOUNDRY-OK" --output-format json

Look for "provider":"foundry" and "canonicalModel":"claude-sonnet-5" in modelUsage.

Step 6 — Verify end to end

Run the seven-point check (Test-ClaudeFoundry.ps1):

.\Test-ClaudeFoundry.ps1 -Resource <resource> -ResourceGroup <rg>

It exits non-zero on failure, so it drops into CI unchanged.

Confirm from the Azure side that traffic reached the resource:

$rid = az cognitiveservices account show -n <resource> -g <rg> --query id -o tsv
az monitor metrics list --resource $rid --metric TokenTransaction `
    --start-time (Get-Date).ToUniversalTime().AddHours(-1).ToString('yyyy-MM-ddTHH:mm:ssZ') `
    --interval PT5M --aggregation Total -o table

Reference

Endpoint

POST https://<resource>.services.ai.azure.com/anthropic/v1/messages
     Authorization: Bearer <entra-id-token>
     anthropic-version: 2023-06-01
     Content-Type: application/json

Foundry exposes Claude through the native Anthropic Messages API, which is why no proxy is
needed. Verified on a live resource:

Streaming (SSE), tool use and count_tokens all work. ?api-version= is optional.

Environment variables

Auth precedence: ANTHROPIC_FOUNDRY_AUTH_TOKEN → ANTHROPIC_FOUNDRY_API_KEY →
DefaultAzureCredential.

CLAUDE_CODE_USE_AZURE does not exist. Scanning the v2.1.223 binary shows all five
*_FOUNDRY_* variables present and no CLAUDE_CODE_USE_AZURE.

Troubleshooting

Scripts

• Get-FoundryValues.ps1 — finds every value in Step 0 and prints the config block (-Mask to share safely)
• Setup-ClaudeFoundry.ps1 — writes both config files, backs up what is already there
• Test-ClaudeFoundry.ps1 — the seven checks in Step 6
• get-foundry-token.sh — optional token helper for CI (Azure CLI, then IMDS)

Docs: Anthropic — Claude Code on Microsoft Foundry ·
Microsoft Learn — Deploy and use Claude models in Foundry