Claude Code Microsoft Foundry設定ガイド

Microsoft Foundryとは何か

Microsoft FoundryはAzure上でClaudeモデルを含む各種モデルをデプロイ・運用するためのプラットフォームです。Claude CodeはAzureにデプロイしたClaude Opus・Sonnet・Haikuを、環境変数だけで呼び出せます。

Amazon BedrockやGoogle Cloud's Agent Platformと違い、Microsoft Foundryには対話的なセットアップウィザードがありません。手順3・4で設定する環境変数が唯一の設定経路です。

CLI本体ではなくVS Code拡張からサードパーティプロバイダーを使いたい場合は、VS Code拡張でサードパーティプロバイダーを使う設定を参照してください。Foundry側のサービス全体はClaude in Microsoft Foundryの解説、3クラウドの機能差はBedrock・Vertex・Foundryの機能比較にあります。

前提条件

Microsoft FoundryにアクセスできるAzureサブスクリプションと、Foundryリソースおよびデプロイを作成できるRBAC権限が必要です。Azure CLIは、他に認証情報を得る手段がない場合のみ入れれば足ります。

複数ユーザーへ展開するなら、手順4のモデル固定を済ませてからにします。Azureリソース自体を操作したい場合はAzure MCPサーバーが使えます。

1. Foundryリソースをプロビジョニングする

Microsoft Foundryポータルでリソースを新規作成し、リソース名を控えます。続けてClaude Opus・Sonnet・Haikuのデプロイを作成し、それぞれのデプロイ名も控えます。この名前が手順4の環境変数に入ります。

デプロイ作成の「Custom settings」では、ホスティングオプションを選びます。「Default settings」を選ぶと、両方のオプションで提供されるモデルはAzureホスティングで構成されます。デプロイ名の既定値はモデルIDで、作成後は変更できません。

この選択は後の手順にも響きます。

2. Azure認証を構成する

Claude CodeはMicrosoft Foundryに対して3種類の認証方式に対応しています。

方式A: APIキー認証。Foundryポータルでリソースの「Endpoints and keys」を開き、APIキーをコピーして環境変数に設定します。

export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key

方式B: Microsoft Entra ID認証。ANTHROPIC_FOUNDRY_API_KEYもANTHROPIC_FOUNDRY_AUTH_TOKENも未設定なら、Claude CodeはAzure SDKの既定の認証情報チェーンを自動的に使います。ローカル環境ではaz loginが一般的です。

az login

方式C: ベアラートークン認証(Claude Code v2.1.203以降)。ホストアプリケーションやサインインスクリプトなど、別のプロセスがアクセストークンを取得済みの場合に使います。値はリクエストごとにAuthorization: Bearerヘッダーで送られます。

export ANTHROPIC_FOUNDRY_AUTH_TOKEN=your-entra-access-token

複数の方式が同時に設定されていると、次の順で採用されます。

Foundryを使う場合、認証はAzure認証情報で扱われるため/logoutコマンドは使えません。

社内のプロキシやゲートウェイがAuthorizationヘッダーを自前で付ける構成には、CLAUDE_CODE_SKIP_FOUNDRY_AUTHがあります。Azure認証情報なしでリクエストを送り、ANTHROPIC_CUSTOM_HEADERSなどで渡したヘッダーを保ちます。APIキーかトークンが設定されていると無視されます。v2.1.203より前は、この変数を設定してもAPIキーが無いとリクエストを送れませんでした。

3. Claude Codeの環境変数を設定する

Foundry統合を有効にする環境変数を設定します。

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=my-resource

my-resourceは手順1で控えたリソース名に置き換えます。リソース名だけを書く点が肝心で、URLやホスト名は受け付けられません。フルのベースURLを渡したいときは、代わりにANTHROPIC_FOUNDRY_BASE_URLを使います(例: https://my-resource.services.ai.azure.com/anthropic)。

4. モデルバージョンを固定する

固定しないと、opusやsonnetなどのエイリアスはClaude Code組み込みの既定値に解決されます。この既定値は最新リリースに追いつかないことがあり、自分のアカウントで未提供の場合もあります。Foundryには起動時のモデル確認がないため、使えないと分かるのはリクエストが失敗した時です。

ここに落とし穴があります。Foundryの提供表では、Opus 4.6とSonnet 4.5は「Hosted on Anthropic」の列にだけ印が付いています。Azureホスティングで作ったデプロイしか持たないアカウントが固定なしで起動すると、既定のエイリアスが指すモデルのデプロイが存在しないことになります。

手順1で付けたデプロイ名に合わせて、モデル変数を設定します。

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

値はモデルIDではなくデプロイ名です。上の3つは各モデルの既定のデプロイ名と同じなので、手順1で名前を変えていなければそのまま通ります。my-claude-deploymentのように変えた場合は、その名前を書きます。

デプロイ名はユーザーが自由に決められるため、Claude Codeは固定したIDをモデルとして認識できません。/modelピッカーの行にはデプロイ名がそのまま出ます。

1Mコンテキストの扱いはモデルで分かれます。v2.1.287以降、Opus 4.7以降とFableはFoundryでも[1m]なしで1Mウィンドウで動きます。Sonnet 5も接尾辞は要りません。[1m]が要るのは接尾辞で1Mにするモデルで、Opus 4.6とSonnet 4.6が該当します(例: claude-opus-4-6[1m])。接尾辞は変数ごとに読まれます。

200Kに戻したいときはCLAUDE_CODE_DISABLE_1M_CONTEXT=1を設定します。changelogのv2.1.287の項では上のとおりですが、model-configページには接尾辞なしを200Kとする旧来の記述が残っており、両者は食い違っています。

FableはHosted on Anthropicのデプロイでのみ使えます。fableエイリアスとANTHROPIC_DEFAULT_FABLE_MODELで固定できます。

セッションタイトル生成などのバックグラウンドタスクは通常Haikuクラスのモデルが担います。ただしFoundryには全アカウントにHaikuデプロイがあるとは限らないため、既定ではプライマリモデルが代わりに使われます。Haikuを使うなら、アカウントにあるデプロイをANTHROPIC_DEFAULT_HAIKU_MODELに指定します。

プロンプトキャッシュは追加設定なしで有効です。既定のTTLは5分で、ENABLE_PROMPT_CACHING_1H=1を設定すると1時間になります。1時間TTLのキャッシュ書き込みは単価が高く、メインの会話とそれ以外のリクエストでTTLを分けたい場合は別の変数で個別に選べます。

5. Claude Codeを起動して確認する

環境変数を設定したら、プロジェクトディレクトリで起動します。

claude

Claude CodeはCLAUDE_CODE_USE_FOUNDRYなどの変数を読み込み、最初のプロンプトでAzureリソースに接続します。/statusを実行すると、APIプロバイダー行にMicrosoft Foundryと、設定したリソース名かベースURLが表示されます。想定と違う値が出たら、手順3・4の環境変数を見直します。

ホスティングオプションでClaude Codeの挙動が変わる点

環境変数の設定自体は、どちらのオプションでも同じです。違いはClaude Codeが組み立てる機能セットに出ます。Azureホスティングのデプロイに対して、Claude Codeはそれを検出して機能セットを自動調整します。

目に見える例がMCPツール検索です。ENABLE_TOOL_SEARCHが未設定なら、Claude Codeは通常MCPツールを後から読み込む形(遅延)にします。Azureホスティングのデプロイでは、これを使わず全MCPツールを最初から読み込みます。ENABLE_TOOL_SEARCH=trueを指定しても、Azureホスティングのデプロイでは遅延になりません。MCPサーバーを多数つなぐ構成では、最初のコンテキスト消費が増える側に倒れます。

Azureホスティングで使えないAPI機能もあります。Claude Codeの外から同じデプロイをAPI呼び出しする場合、コード実行・Agent Skills・Files API・プログラムによるツール呼び出しは400 Bad Requestになります。

そのほかの環境変数側の違いとして、CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMINGはFoundryでは既定でオフです。大きなツール入力はClaudeの生成が終わってから届くため、長いファイル書き込みで固まったように見えることがあります。

Azure RBACの設定

Claudeモデルの呼び出しに必要な権限は、既定ロールのAzure AI UserとCognitive Services Userのどちらにも含まれています。権限をさらに絞りたい場合は、次のカスタムロールを作ります。

{
  "permissions": [
    {
      "dataActions": [
        "Microsoft.CognitiveServices/accounts/providers/*"
      ]
    }
  ]
}

カスタムロールが許可するのはMicrosoft.CognitiveServices/accounts/providers/*のデータ操作だけです。

つまずきやすいポイント

症状ごとに、見る場所を分けます。

最初の症状の正確な文面は「Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed」です。設定後に401や403で拒否されたときは、Microsoft Foundry authentication failedの原因と対処で切り分けます。

モデルが呼び出せない場合、起動時の確認がない分、原因の切り分けは自分で行います。/statusでリソース名とモデルを確認し、Foundryポータルでそのデプロイ名が実在するかを見る順番が近道です。

リソース名の誤りは「実在しないホストに接続しようとして失敗し続ける」形で現れます。Claude Codeはこの値からエンドポイントURLを組み立てるためです。

まとめ

Foundry経由の設定は環境変数が唯一の経路で、失敗はすべてリクエスト時に初めて表に出ます。展開前に、Azureホスティングのデプロイ名とANTHROPIC_DEFAULT_*_MODELを揃えておくことが、起動後の失敗を避ける近道です。

AWSやGCP経由との権限設計の違いは、Claude Code Vertex AI IAM設定とチーム展開ガイドとClaude Code Bedrock Mantleエンドポイントの使い方で比べられます。