Azure AI Gateway Labs
Documentation Open portal
Agents · Lab 25New

Use your gateway's models and tools in Claude Code

Point Claude Code at the Claude models that your gateway publishes from Microsoft Foundry, with a token limit and a daily budget for each caller, then give it Microsoft Learn tools from an MCP server on the same gateway, so every model and tool call uses your key, your limits, and your monitoring.

Intermediate 40 min PortalCLIBicepTerraformCodeNotebook Updated
Notebook Source Edit

What you'll do

  • Publish Claude Opus 5.5, Sonnet 5.5, and Haiku 5.5 through the gateway, with a token limit for each caller and a daily budget on Opus
  • Point Claude Code at the gateway's Anthropic route with environment variables, without an Anthropic account
  • Run a one-shot prompt and an agent task in Claude Code on the gateway's models
  • Publish the Microsoft Learn MCP server through the gateway, and give Claude Code its tools with the same key
  • Hit the token limit and the budget from Claude Code, and switch it to another model
  • Track Claude Code's usage by key in Monitoring, and cut off access by suspending the key

Before you start

Tracks: Portal, Azure CLI, Bicep, Terraform, Code, Notebook

Claude Code is Anthropic's coding agent for the terminal, and it can run on the Claude models in Microsoft Foundry. Send its requests through your gateway, and Claude Code gets the same controls as your apps: a key that you can suspend, a token limit and a budget for each caller, and usage in Monitoring. Developers don't need an Anthropic account, and Claude Code never sees a Foundry credential, because the gateway calls Foundry with its managed identity. In this lab you publish Claude Opus 5.5, Sonnet 5.5, and Haiku 5.5 for Claude Code, connect it with a few environment variables, and give it Microsoft Learn tools from an MCP server on the same gateway. Then you run into the token limit and the budget, and see how Claude Code reports them.

Before you begin

One-time setupThe Setup guide tasks that this lab uses. Mark each one done once, and the labs stop listing it.

  • Complete Publish a Foundry model and make your first call. You need a gateway and permission to change it, for example Contributor on the resource group.
  • A Foundry account with three Claude deployments, each named after its model: claude-opus-5-5, claude-sonnet-5-5, and claude-haiku-5-5. It can be the account behind lab 02's provider or another one. See Deploy and use Claude models in Microsoft Foundry for the regions and requirements. Model inference is billed per use.
  • Permission to assign roles on that Foundry account, for example Owner or User Access Administrator. The gateway's managed identity needs the Foundry User role there to call the models.
  • Claude Code. This lab was tested with version 2.1.326. You don't need an Anthropic account or a Claude subscription: Claude Code uses the gateway's key.
  • jq for the Bash commands.

Set these variables once. Every track and the Verify section reuse them.

# Name your gateway, the Foundry account with the Claude deployments, and what this lab publishes on the gateway
export RG="<resource-group>"
export GATEWAY="<gateway>"
export FOUNDRY_RG="<foundry-resource-group>"      # resource group of the Foundry account with the Claude deployments
export FOUNDRY_ACCOUNT="<foundry-account-name>"   # the account name, not a project or deployment name
export PROVIDER="$FOUNDRY_ACCOUNT"                # the gateway's provider for the account, named after it
export KEY_NAME="claude-code"                     # the runtime key that Claude Code uses

# Read the gateway's resource ID and runtime URL
export GATEWAY_ID="$(az aigateway show -g "$RG" -n "$GATEWAY" --query id -o tsv)"
export AI_GATEWAY_URL="https://$(az aigateway show -g "$RG" -n "$GATEWAY" --query properties.frontend.defaultHostname -o tsv)"
echo "📝 Gateway $GATEWAY in $RG, with Foundry account $FOUNDRY_ACCOUNT in $FOUNDRY_RG"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"

Then create a small practice project with two deliberate problems: add subtracts, and divide doesn't guard against zero. The Connect Claude Code section asks Claude Code to fix them. Create it outside any repository:

# Create the practice project's folder, and write calc.py with its two deliberate problems
mkdir -p ~/contoso-calc
cat > ~/contoso-calc/calc.py <<'EOF'
"""Tiny calculator used to try Claude Code with models from Azure AI Gateway."""


def add(a: float, b: float) -> float:
    return a - b


def divide(a: float, b: float) -> float:
    return a / b


if __name__ == "__main__":
    print(add(2, 3), divide(10, 2))
EOF
echo "📄 Practice project is ready: ~/contoso-calc/calc.py"

How it works

Claude Code speaks Anthropic's Messages API, and the gateway serves that API for the Claude models in Foundry on its Anthropic route, /default/models/anthropic. Point Claude Code at that route, and every model call goes through the gateway. Claude Code still runs its agent loop on your machine: it reads files, edits them, and runs commands, and only the model calls leave for the gateway. Five environment variables do it:

VariableValueWhy
ANTHROPIC_BASE_URLhttps://<gateway-host>/default/models/anthropicThe gateway's Anthropic route. Claude Code adds /v1/messages itself, so leave out /v1.
ANTHROPIC_AUTH_TOKENThe claude-code runtime keyClaude Code sends it as Authorization: Bearer, which the gateway accepts. Don't use ANTHROPIC_API_KEY: Claude Code sends that one in an x-api-key header, and the gateway rejects it with 401.
ANTHROPIC_DEFAULT_OPUS_MODEL<foundry-account-name>/claude-opus-5-5The alias behind the opus tier, Claude Code's default model in this setup.
ANTHROPIC_DEFAULT_SONNET_MODEL<foundry-account-name>/claude-sonnet-5-5The alias behind the sonnet tier.
ANTHROPIC_DEFAULT_HAIKU_MODEL<foundry-account-name>/claude-haiku-5-5The alias behind the haiku tier, which Claude Code also uses for small background tasks.

Claude Code picks a model by tier, so --model sonnet or /model sonnet switches it to the Sonnet alias. A model that you saved with /model, or set in ANTHROPIC_MODEL, replaces the default, so the commands that need Opus pass --model opus. The gateway gives each alias its own policies, and the Identity counter dimension gives each key its own counters:

AliasToken limit for each callerCost limit for each caller
<foundry-account-name>/claude-opus-5-5100,000 tokens per minute$5 per day
<foundry-account-name>/claude-sonnet-5-5100,000 tokens per minuteNone
<foundry-account-name>/claude-haiku-5-5100,000 tokens per minuteNone

Opus is the default and the most expensive model, so it gets the budget. When a developer spends it, they can carry on with Sonnet until the budget renews. Two things to know about the numbers:

  • Cached tokens barely count toward the token limit. Claude Code sends its system prompt and tool definitions with every request, about 13,500 tokens, and caches them. In testing, cache reads barely counted toward the gateway's token limit, so even a 1,000 tokens-per-minute limit let short questions through. Output tokens are what fill it, which is why Hit the limits asks for long stories.
  • Claude Code's cost is an estimate. The total_cost_usd that Claude Code reports is its own estimate. The gateway's cost limit uses the gateway's meter, so the two don't match exactly.

Publish your Claude models for Claude Code

Import the three Claude deployments into the gateway, publish an alias for each one with a token limit of 100,000 tokens per minute for each caller, add a daily budget of $5 for each caller to the Opus alias, and create the runtime key claude-code. Pick a track.

Choose your track
1

Import the Claude deployments

  1. Open the AI Gateway portal and select your gateway in the top bar.
  2. Select ModelsAddModels from Microsoft Foundry.
  3. In Subscriptions and Resource groups, select those of your Foundry account. Keep Managed identity as the Authentication method.
  4. In Models, check that only your Foundry account is selected, with its claude-opus-5-5, claude-sonnet-5-5, and claude-haiku-5-5 deployments: the page preselects every deployment it lists.
  5. Under Aliases, keep Create an alias for each model selected, then select Add models. The page reports Models and aliases imported.

The import names each alias after the Foundry account and the deployment, for example <foundry-account-name>/claude-opus-5-5. Claude Code sends these names in the request's model field.

2

Add the token limit

  1. Select PoliciesAdd policy. On the Type step, under Cost and rate limits, select Token rate limit, then Next.
  2. On the Scope step, select Individual assets, select the three <foundry-account-name>/claude-*-5-5 assets of type Alias, then Next.
  3. On the Details step, set Time period to Per minute and Allowed tokens to 100000. Keep Counter dimensions at Identity, so that each key gets its own counter. Select Create.
3

Add the daily budget to Opus

  1. Select PoliciesAdd policy. On the Type step, under Cost and rate limits, select Cost limit, then Next.
  2. On the Scope step, select Individual assets, select the <foundry-account-name>/claude-opus-5-5 asset of type Alias, then Next.
  3. On the Details step, under Parameters, set Budget amount to 5 and Renewal period to Daily. Keep Counter dimensions at Identity. Select Next.
  4. Skip the Overrides step, and select Create.

Set a cost budget with cost limits explains the budget's fields and overrides.

4

Create the key for Claude Code

  1. Select AccessAPI keysCreate API key.
  2. In Key name, enter claude-code and select Create.
  3. Copy the value from API key created successfully, for example with Copy & done, and paste it into your shell without echoing it:
# Paste the key without showing it, and export it for the test calls and Claude Code
printf "AI Gateway API key: " && read -rs AI_GATEWAY_API_KEY && export AI_GATEWAY_API_KEY && echo
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
Checkpoint

ModelsAliases lists the three <foundry-account-name>/claude-*-5-5 aliases, Policies lists a Token rate limit of 100,000 tokens per minute and a Cost limit of $5 per day, and AccessAPI keys lists claude-code.

1

Test the endpoint

Before you configure Claude Code, call the Opus alias the way Claude Code does: the Messages API, with the key as a bearer token and the anthropic-version header.

# Call the Opus alias the way Claude Code does: the Messages API, with the key as a bearer token
curl -sS "${AI_GATEWAY_URL%/}/default/models/anthropic/v1/messages" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"$FOUNDRY_ACCOUNT/claude-opus-5-5\", \"max_tokens\": 256,
       \"messages\": [{\"role\": \"user\", \"content\": \"In one sentence, what does a coding agent do?\"}]}" \
  | jq -r 'if .content then
             "✨ Backend model: \(.model)",
             "🤖 \([.content[] | select(.type == "text") | .text] | join(""))",
             "📊 Tokens: \(.usage.input_tokens) in, \(.usage.output_tokens) out"
           else "🚨 \(.error.message // .message // .)" end'

Expected output (your text differs):

Text
✨ Backend model: claude-opus-5-5
🤖 A coding agent is an AI system that autonomously writes, runs, tests, and debugs code, using tools like a terminal, file editor, and documentation to complete programming tasks with minimal human guidance.
📊 Tokens: 23 in, 66 out

The gateway reads the key from the Authorization: Bearer header. In an x-api-key header, it gets 401. Leave out anthropic-version, and the call fails with anthropic-version: header is required. Claude Code sends that header for you.

Note

A new alias, policy, or key can take a minute to apply. If the call returns 401 or 404, wait a minute and try again.

Connect Claude Code

Claude Code reads its endpoint, key, and models from environment variables, so you can switch between the gateway and other providers per terminal.

1

Point Claude Code at the gateway

# Clear any Anthropic API key: Claude Code would send it in x-api-key, which the gateway rejects
unset ANTHROPIC_API_KEY

# Point Claude Code at the gateway's Anthropic route, and give it the claude-code key as a bearer token
export ANTHROPIC_BASE_URL="${AI_GATEWAY_URL%/}/default/models/anthropic"
export ANTHROPIC_AUTH_TOKEN="$AI_GATEWAY_API_KEY"

# Map Claude Code's three model tiers to the gateway's aliases
export ANTHROPIC_DEFAULT_OPUS_MODEL="$FOUNDRY_ACCOUNT/claude-opus-5-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$FOUNDRY_ACCOUNT/claude-sonnet-5-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$FOUNDRY_ACCOUNT/claude-haiku-5-5"
echo "🌐 Base URL: $ANTHROPIC_BASE_URL"
echo "🔖 Opus: $ANTHROPIC_DEFAULT_OPUS_MODEL"
echo "🔖 Sonnet: $ANTHROPIC_DEFAULT_SONNET_MODEL"
echo "🔖 Haiku: $ANTHROPIC_DEFAULT_HAIKU_MODEL"
echo "🔑 Key: in ANTHROPIC_AUTH_TOKEN (${#ANTHROPIC_AUTH_TOKEN} characters, not shown)"

# Check the Claude Code version
claude --version

Expected output:

Text
🌐 Base URL: https://<gateway-host>/default/models/anthropic
🔖 Opus: <foundry-account-name>/claude-opus-5-5
🔖 Sonnet: <foundry-account-name>/claude-sonnet-5-5
🔖 Haiku: <foundry-account-name>/claude-haiku-5-5
🔑 Key: in ANTHROPIC_AUTH_TOKEN (32 characters, not shown)
2.1.326 (Claude Code)

These variables last for the current terminal. Go further shows how to keep them in Claude Code's settings.

2

Ask a quick question

claude -p runs one prompt and exits, and --output-format json returns the result with the models that Claude Code used and its cost estimate:

# Move into the practice project
cd ~/contoso-calc &&
  echo "📂 Practice project: ~/contoso-calc"

# Run one prompt on Opus, and print the reply, the alias that answered, and the cost estimate
echo "🤖 Claude Code answer:"
claude -p "Reply with the single word pong" --model opus --output-format json \
  | jq -r 'if .is_error then "🚨 \(.result)"
           else "✅ \(.result) · \(.modelUsage | keys | join(", ")) · $\(.total_cost_usd * 10000 | round / 10000)" end'

Expected output (your cost differs):

Text
📂 Practice project: ~/contoso-calc
🤖 Claude Code answer:
✅ pong · <foundry-account-name>/claude-opus-5-5 · $0.0821

The alias in the output proves that the call went through the gateway. The cost estimate varies from run to run, even for the same prompt: on Opus, it ranged from $0.003 to $0.08 in testing. Add --model sonnet or --model haiku to ask another tier.

3

Run an agent task

Start an interactive session in the practice project:

Bash
# Start an interactive Claude Code session in the practice project, on the gateway's models
cd ~/contoso-calc && echo "🚀 Starting Claude Code in ~/contoso-calc (type /exit to leave)"
claude

The first time, Claude Code asks you to pick a theme and shows its security notes. Then it asks whether you trust the folder: select Yes, I trust this folder. The banner shows Claude Code v2.1.326 and Opus 5.5 · API Usage Billing. Claude Code runs on the gateway's Opus alias, and it doesn't ask you to sign in.

Type /status to see where the requests go. It shows ANTHROPIC_AUTH_TOKEN as the auth token, the gateway's Anthropic route as the Anthropic base URL, and Default (<foundry-account-name>/claude-opus-5-5) as the model.

Then send this prompt:

Text
Fix the bug in calc.py and add a guard for division by zero

Claude Code reads calc.py, makes add return a + b, and makes divide raise an error, such as ZeroDivisionError, when b is zero. Depending on its permission mode, it asks before each edit and command, or runs them. In testing, the session started in auto mode, shown as ⏵⏵ auto mode on (shift+tab to cycle) under the prompt, and each step showed Allowed by auto mode. Press Shift+Tab to cycle the modes.

Checkpoint

Type /exit to leave the session, then run python3 calc.py (or python calc.py) in ~/contoso-calc. It prints 5 5.0: Claude Code fixed add with a model from your gateway.

Publish Microsoft Learn tools for Claude Code

Claude Code calls tools as well as models. Publish an MCP server through the same gateway, and its tool calls get the same controls as its model calls: one key that you can suspend, one endpoint per tool server, and one place to decide which tools agents see. Here, the gateway publishes the public Microsoft Learn MCP server as learn, so Claude Code can look up current Microsoft documentation while it codes.

Claude Code then has two connections to the gateway:

ModelsMCP server
URLhttps://<gateway-host>/default/models/anthropichttps://<gateway-host>/default/toolservers/learn/mcp
How the key is sentAuthorization: Bearer <key>, from ANTHROPIC_AUTH_TOKENThe same Authorization: Bearer <key> header, which you set yourself
Keyclaude-codeThe same claude-code key. It needs no extra setup.
Tip

If your gateway already has learn, for example from Federate MCP tools behind one endpoint, skip to Test the MCP endpoint.

Create the learn server with one backend, https://learn.microsoft.com/api/mcp, under the namespace learn. The Learn server is public, so the backend needs no credentials. Pick a track.

Choose your track
1

Register the Learn server

  1. Open the AI Gateway portal, select your gateway, and select MCP serversAdd MCP server.
  2. On Basic info, set Name to learn, Display name to Microsoft Learn, and Description to Search and fetch official Microsoft documentation and code samples. In Supported MCP versions, select 2025-06-18, the version that the Learn server reports. Select Next.
  3. On Backends, select Add backendMCP server. Set Endpoint URL to https://learn.microsoft.com/api/mcp, keep Authentication at None, and set Namespace to learn. Select Add, then Next, which saves the server and opens Tools.
  4. On Tools, keep Allow all tools, and select Create.

Register the Learn MCP server in lab 04 explains each field.

2

Copy the endpoint

When the server is ready, copy the Endpoint URL from its details page. It ends in /default/toolservers/learn/mcp.

Checkpoint

MCP servers lists learn with one backend in the namespace learn.

1

Test the MCP endpoint

Save the endpoint, then list its tools the way Claude Code does: a JSON-RPC tools/list request with the key as a bearer token.

# Save the endpoint of the learn MCP server on your gateway
export AI_GATEWAY_MCP_URL="${AI_GATEWAY_URL%/}/default/toolservers/learn/mcp"
echo "🔌 MCP endpoint: $AI_GATEWAY_MCP_URL"

# List the server's tools: a JSON-RPC tools/list request, with the key as a bearer token
echo "🔧 Tools on the learn MCP server:"
curl -sS "$AI_GATEWAY_MCP_URL" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq -r '.result.tools[].name'

Expected output:

Text
🔌 MCP endpoint: https://<gateway-host>/default/toolservers/learn/mcp
🔧 Tools on the learn MCP server:
learn_microsoft_docs_search
learn_microsoft_code_sample_search
learn_microsoft_docs_fetch

Each name starts with the backend's namespace, learn. The Learn server can add tools over time, and Allow all tools publishes them too.

Add the Learn tools to Claude Code

claude mcp add registers an MCP server. With --scope user, Claude Code keeps it in ~/.claude.json and offers it in every project. Header values can refer to environment variables, so the file doesn't need to hold the key.

1

Add the server

Keep the single quotes around the header: they stop the shell from expanding ${AI_GATEWAY_API_KEY}, so the file stores the reference, and Claude Code reads the key from its environment each time it connects. Keep --header after the name and the URL: it takes one or more values, so Claude Code would read anything after it as another header.

# Add the gateway's learn MCP server to Claude Code for your user, with a header that reads the key from the environment
claude mcp add --transport http --scope user ai-gateway-learn "$AI_GATEWAY_MCP_URL" \
  --header 'Authorization: Bearer ${AI_GATEWAY_API_KEY}' &&
  echo "🔌 MCP server ai-gateway-learn is ready in Claude Code"

# Check that Claude Code connects to it
echo "🔌 MCP servers in Claude Code:"
claude mcp list

Expected output:

Text
Added HTTP MCP server ai-gateway-learn with URL: https://<gateway-host>/default/toolservers/learn/mcp to user config
Headers: {
  "Authorization": "[REDACTED]"
}
File modified: <home>/.claude.json
🔌 MCP server ai-gateway-learn is ready in Claude Code
🔌 MCP servers in Claude Code:
Checking MCP server health…

ai-gateway-learn: https://<gateway-host>/default/toolservers/learn/mcp (HTTP) - ✔ Connected

✔ Connected means that Claude Code reached the gateway with the key. In the PowerShell version, AI_GATEWAY_API_KEY must be an environment variable, as the earlier steps set it.

2

Ask a question that needs the docs

Claude Code names the server's tools mcp__ai-gateway-learn__<tool>. claude -p can't ask for permission, so --allowedTools "mcp__ai-gateway-learn__*" allows all the server's tools up front:

Bash
# Ask a question that needs current docs, and allow the Learn tools for this one-shot run
echo "🤖 Claude Code answer, with the Learn tools:"
claude -p "Use the Microsoft Learn tools to find the Azure Functions Core Tools command that creates a new Python function project. Answer in two sentences, with the command and the link to the page." \
  --allowedTools "mcp__ai-gateway-learn__*"

Expected output (your text differs):

Text
🤖 Claude Code answer, with the Learn tools:
To create a new Python function project with Azure Functions Core Tools, run `func init MyProjFolder --worker-runtime python --model V2` (use `--model V1` for the older programming model), which creates the project in a new folder called *MyProjFolder*. The command is documented at https://learn.microsoft.com/azure/azure-functions/functions-run-local#create-your-local-project, which also says to run Core Tools commands for Python inside a virtual environment.

The link comes from the Learn search that Claude Code ran through the gateway. In an interactive session, Claude Code asks before it calls a tool, depending on its permission mode.

Checkpoint

claude mcp list shows ai-gateway-learn as ✔ Connected, and the answer cites a learn.microsoft.com page.

Hit the limits

Coding agents can spend tokens and money fast. Lower the limits for a few minutes to see how the gateway stops Claude Code, and how Claude Code reports it. Short questions are mostly cached and barely count, so these tests ask for long stories.

1

Lower the Haiku token limit

Lower the token limit on the Haiku alias to 1,000 tokens per minute for each caller:

  • Portal: in Policies, open the Token rate limit, select Edit, set Allowed tokens to 1000, and Save. The policy covers the three aliases, so all three get the lower limit. That's fine for the test.
  • Azure CLI, Bicep, and Terraform: run the commands below. The three tracks give the aliases the same names.
# Lower the Haiku alias's token limit to 1,000 tokens per minute for each caller, and show its policies
echo "🔐 Policies on $FOUNDRY_ACCOUNT/claude-haiku-5-5:"
az aigateway model-alias update -g "$RG" --gateway-name "$GATEWAY" -n "$FOUNDRY_ACCOUNT-claude-haiku-5-5" \
  --policies '[{"type": "tokenLimit", "count": 1000, "period": "minute", "counterKey": ["identity"]}]' \
  --query "properties.policies[].{policy:type, count:count, period:period}" -o table

Expected output:

Text
🔐 Policies on <foundry-account-name>/claude-haiku-5-5:
Policy      Count    Period
----------  -------  --------
tokenLimit  1000     minute

Wait a minute for the change to reach the gateway.

2

Run Haiku until the token limit

Ask Haiku for five long stories in a row, and stop at the first error:

# Ask Haiku for up to five long stories, print each run's output tokens, and stop at the first error
cd ~/contoso-calc
for i in 1 2 3 4 5; do
  RUN="$(claude -p "Write a 500-word short story about a gateway that guards a city" --model haiku --output-format json)"
  echo "$RUN" | jq -r --arg i "$i" \
    'if .is_error then "🚨 Run \($i): \(.result)" else "✅ Run \($i): \(.usage.output_tokens) output tokens" end'
  [ "$(echo "$RUN" | jq -r .is_error)" = "true" ] && break
done

Expected output (your numbers differ):

Text
✅ Run 1: 1055 output tokens
✅ Run 2: 6028 output tokens
🚨 Run 3: API Error: Request rejected (429) · Token limit is exceeded. Try again in 332 seconds.

The gateway counts a reply after it's sent, so the reply that crosses the limit still arrives in full, and the next request gets 429. Claude Code doesn't retry it: it shows the gateway's message, with the seconds until the window resets.

3

Restore the Haiku token limit

  • Portal: set Allowed tokens on the Token rate limit back to 100000.
  • Azure CLI, Bicep, and Terraform:
# Restore the Haiku alias's token limit to 100,000 tokens per minute for each caller
az aigateway model-alias update -g "$RG" --gateway-name "$GATEWAY" -n "$FOUNDRY_ACCOUNT-claude-haiku-5-5" \
  --policies '[{"type": "tokenLimit", "count": 100000, "period": "minute", "counterKey": ["identity"]}]' -o none &&
  echo "🔐 Haiku is back to 100,000 tokens per minute for each caller"
4

Lower the Opus budget

Lower the daily budget on the Opus alias to $0.05 for each caller. Keep the cost limit's id: the gateway then keeps the spend counted so far today. The agent task and the Learn question already ran on Opus, so the key may have spent more than $0.05 today, and the first request may be blocked right away.

  • Portal: in Policies, open the Cost limit, select Edit, set Budget amount to 0.05, and Save.
  • Azure CLI, Bicep, and Terraform:
# Lower the Opus budget to $0.05 a day for each caller, with the same id, so that today's spend still counts
az aigateway model-alias update -g "$RG" --gateway-name "$GATEWAY" -n "$FOUNDRY_ACCOUNT-claude-opus-5-5" \
  --policies '[{"type": "tokenLimit", "count": 100000, "period": "minute", "counterKey": ["identity"]},
               {"type": "costLimit", "id": "claude-code-budget", "amount": 0.05, "period": "day",
                "counterKey": ["identity"]}]' -o none &&
  echo "🔐 Opus budget: \$0.05 per day for each caller"

Wait a minute for the change to reach the gateway.

5

Run Opus until the budget

# Ask Opus for up to five stories, and stop at the first error
for i in 1 2 3 4 5; do
  RUN="$(claude -p "Write a 300-word short story about a gateway that guards a city" --model opus --output-format json)"
  echo "$RUN" | jq -r --arg i "$i" \
    'if .is_error then "🚨 Run \($i): \(.result)" else "✅ Run \($i): \(.usage.output_tokens) output tokens" end'
  [ "$(echo "$RUN" | jq -r .is_error)" = "true" ] && break
done

Expected output (run 1 may already be blocked):

Text
✅ Run 1: 573 output tokens
🚨 Run 2: Failed to authenticate. API Error: 403 LLM cost quota is exceeded. Try again in 4 hours, 6 minutes, and 5 seconds.

The gateway answers 403 with the time until the budget renews, at the end of the day. Claude Code reports it as Failed to authenticate, and an interactive session shows Please run /login · API Error: 403 …. Don't sign in: the key is fine, and the budget is spent.

6

Carry on with Sonnet

The Sonnet alias has no budget, so switch to it. In an interactive session, type /model sonnet. Claude Code answers Set model to Sonnet 5.5 and saved as your default for new sessions, so type /model opus when the budget renews. In a one-shot run, add --model sonnet:

Bash
# Ask Sonnet instead: its alias has no budget, so the gateway lets the request through
claude -p "Reply with the single word pong" --model sonnet --output-format json \
  | jq -r 'if .is_error then "🚨 \(.result)"
           else "✅ \(.result) · \(.modelUsage | keys | join(", ")) · $\(.total_cost_usd * 10000 | round / 10000)" end'

Expected output (your cost differs):

Text
✅ pong · <foundry-account-name>/claude-sonnet-5-5 · $0.0411

--fallback-model doesn't help here: Claude Code uses it when the model is overloaded, not when the gateway answers 403.

7

Restore the Opus budget

  • Portal: set Budget amount on the Cost limit back to 5.
  • Azure CLI, Bicep, and Terraform:
# Restore the Opus budget to $5 a day for each caller, with the same id
az aigateway model-alias update -g "$RG" --gateway-name "$GATEWAY" -n "$FOUNDRY_ACCOUNT-claude-opus-5-5" \
  --policies '[{"type": "tokenLimit", "count": 100000, "period": "minute", "counterKey": ["identity"]},
               {"type": "costLimit", "id": "claude-code-budget", "amount": 5, "period": "day",
                "counterKey": ["identity"]}]' -o none &&
  echo "🔐 Opus budget: \$5 per day for each caller"

On the Terraform track, the restore commands set the configuration's values back, so terraform plan shows no changes.

Checkpoint

Haiku stopped with 429 and the seconds until the token window resets, Opus stopped with 403 and the time until the budget renews, and Sonnet answered while Opus was blocked.

Verify

Every request from Claude Code carries the claude-code key. Use it to see the traffic and to switch Claude Code off.

1

See Claude Code's usage by key

If you set up Monitoring in Monitor usage, cost, and traces, open MonitoringModels in the AI Gateway portal. The three Claude aliases list the calls and the tokens from your sessions, and Model usage by caller identity shows them under the claude-code key.

2

Cut Claude Code off by suspending the key

Suspend the key, then call the gateway with it. Use curl for this test: Claude Code retries a 401 many times, so a claude -p run seems to hang for minutes before it fails.

# Suspend the claude-code key: calls with it get 401 until you set it back to active
STATE="$(az aigateway api-key update -g "$RG" --gateway-name "$GATEWAY" -n "$KEY_NAME" --state suspended \
  --query properties.state -o tsv)" &&
  echo "🔑 API key claude-code is $STATE"

# Give the gateway time to apply the change
echo "⏳ Waiting 60 seconds for the key change to apply"
sleep 60

# Call the Haiku alias with the suspended key, and print the gateway's answer
echo "🚦 Expect HTTP 401 from the gateway:"
curl -sS "${AI_GATEWAY_URL%/}/default/models/anthropic/v1/messages" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" \
  -d "{\"model\": \"$FOUNDRY_ACCOUNT/claude-haiku-5-5\", \"max_tokens\": 16,
       \"messages\": [{\"role\": \"user\", \"content\": \"Say hi\"}]}" \
  -w "\n🚦 HTTP %{http_code}\n"

Expected output:

Text
🔑 API key claude-code is suspended
⏳ Waiting 60 seconds for the key change to apply
🚦 Expect HTTP 401 from the gateway:
{ "statusCode": 401, "message": "Unauthorized. Missing or invalid Entra ID token, or missing Data.All scope." }
🚦 HTTP 401

One key change cuts off Claude Code on every machine that uses the key, without touching their settings. The key guards the tools too: while it's suspended, claude mcp list can't connect to ai-gateway-learn.

3

Turn Claude Code back on

# Turn the claude-code key back on
STATE="$(az aigateway api-key update -g "$RG" --gateway-name "$GATEWAY" -n "$KEY_NAME" --state active \
  --query properties.state -o tsv)" &&
  echo "🔑 API key claude-code is $STATE"

# Give the gateway time to apply the change
echo "⏳ Waiting 60 seconds for the key change to apply"
sleep 60

# Ask Claude Code again: it answers through the gateway
echo "🤖 Claude Code answer:"
cd ~/contoso-calc && claude -p "Say hi in three words"
Checkpoint

The gateway answered 401 while the key was suspended, and Claude Code answered again after 🔑 API key claude-code is active.

Go further

  • Sign in with Microsoft Entra ID instead of a key. If the gateway accepts Entra tokens and you have the AI Gateway Models User role, as in Authorize callers with Microsoft Entra ID, let Claude Code fetch a token itself. Add this setting to ~/.claude/settings.json:

    ~/.claude/settings.json
    {
      "apiKeyHelper": "az account get-access-token --scope https://ai.gateway.azure.com/Data.All --query accessToken -o tsv"
    }

    Then run unset ANTHROPIC_AUTH_TOKEN (Bash) or Remove-Item Env:ANTHROPIC_AUTH_TOKEN (PowerShell), and keep it out of the env block of your settings. If it's still set, Claude Code keeps sending the key as the bearer token instead of the helper's token, and the requests still succeed with the key. Claude Code runs the helper again every five minutes by default, so expired tokens don't stop long sessions. See Settings.

  • Keep the settings in a file. Put the ANTHROPIC_* variables in the env block of ~/.claude/settings.json, so every session uses the gateway without exports. Keep the key in your user settings, not in a project's .claude/settings.json, which gets committed with the repository.

  • Use Claude Code in VS Code. The Claude Code extension reads the same variables. Set them in the claudeCode.environmentVariables setting. See Use Claude Code in VS Code.

  • Turn off nonessential traffic. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 turns off Claude Code's telemetry, error reports, and automatic updates. See Environment variables.

  • Give each developer their own key. Keys are cheap, and the Identity counter dimension gives each key its own token limit and budget. Rotate or revoke them with Manage runtime API keys.

  • Cap one run. claude -p --max-budget-usd 1 stops a one-shot run when Claude Code's own estimate reaches $1. The gateway's budget stays the limit that Claude Code can't change.

  • Choose which tools Claude Code can call. On the gateway, publish only some Learn tools or cap tool calls per caller, as in Control which tools agents can call. In Claude Code, use --allowedTools, --disallowedTools, and --permission-mode.

  • Route across models. Point an alias at several backend models, as in Route by priority and weight, and Claude Code keeps sending the same name.

Clean up

Remove the gateway from Claude Code, and delete the practice project:

  • Learn tools: run claude mcp remove ai-gateway-learn -s user.
  • Environment: close the terminal, or run unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_DEFAULT_OPUS_MODEL ANTHROPIC_DEFAULT_SONNET_MODEL ANTHROPIC_DEFAULT_HAIKU_MODEL (Bash) or Remove-Item Env:ANTHROPIC_* (PowerShell).
  • Practice project: run rm -rf ~/contoso-calc (Bash) or Remove-Item -Recurse -Force ~/contoso-calc (PowerShell).

Then delete what you created on the gateway. Keep the gateway: the other labs reuse it. Keep the learn MCP server if you continue with Control which tools agents can call, which builds on it. Pick a track.

Choose your track
1

Delete the key, the policies, and the models

  1. Delete claude-code in AccessAPI keys.
  2. Delete the Token rate limit and the Cost limit that you added, in Policies.
  3. If you don't need the Claude models on the gateway any more, delete the three <foundry-account-name>/claude-*-5-5 aliases and the three models in Models.
  4. If you don't need learn, delete it in MCP servers.

On the portal, Azure CLI, and Bicep tracks, the gateway's managed identity keeps the Foundry User role on the Foundry account, and so it does on the Terraform track when the checks set grant_foundry_user to false. Leave it if another provider on the gateway uses the account. Otherwise, remove it in the Foundry account's Access control (IAM) in the Azure portal.

Next steps

Finished the lab?

Mark it complete to track your progress across paths. It's saved only in this browser.