Azure MCP ServerでAzure SQL Databaseを作成・更新した際、「指定した設定が反映されていないのにエラーも出ない」と困っていた場合は、--read-scaleの値が原因かもしれません。
2026年7月28日に公開されたAzure MCP Server 3.0.0-beta.30では、SQLデータベースの作成・更新時に、認識できない--read-scaleの値が黙って無視される問題が修正されました。無効な値は検証エラーとして返されるため、利用者やAIエージェントが設定ミスを把握できるようになります。
同時に、新しいツール設計への移行が完了し、Coreツールの未使用パラメーターと旧ツール作成基盤が削除されています。SQLツールを利用していない環境でも、固定プロンプト、ラッパースクリプト、キャッシュ済みのツール定義を使っている場合は、更新前の互換性確認が必要です。(GitHub)
Azure MCP Server beta.30でSQLツールのエラー処理を修正
Azure MCP Server 3.0.0-beta.30の主な変更点は、次のとおりです。
| 項目 | 変更内容 | 利用者への影響 |
|---|---|---|
| SQLツールの修正 | 不正な--read-scaleを検証エラーに変更 | 設定値が黙って無視されなくなる |
| Coreツールの整理 | 未使用パラメーターを削除 | 古い引数を送信するスクリプトは修正が必要になる可能性がある |
| ツール設計の刷新 | 新ツール設計への移行を完了 | ツール定義と入力検証の一貫性が高まる |
| 旧基盤の削除 | 従来のツール作成フレームワークを削除 | 独自ビルドや拡張コードでは移行確認が必要 |
| 依存関係の更新 | ModelContextProtocolを2.0.0-preview.3へ更新 | MCPクライアントとの接続をテストした方がよい |
| ツール数 | 個別ツールは427個 | ツール追加よりも内部設計の整理が中心 |
このリリースはプレリリース版です。また、未使用パラメーターと旧ツール作成基盤の削除は、変更履歴上「Breaking Changes」に分類されています。本番環境へ直接適用するのではなく、検証環境でツール一覧と主要な操作を確認してから切り替えるのが安全です。(GitHub)
修正対象はread-scaleの無効な値が無視される問題
今回修正されたのは、SQLツール全体のエラー処理ではありません。対象は、Azure SQL Databaseの作成または更新時に指定するreadScaleオプションです。
CLI上では、次の2つのコマンドが該当します。
azmcp sql db create
azmcp sql db updateGitHubの変更履歴では説明上、sql database createとsql database updateと表記されていますが、Azure MCP CLIのコマンド参照ではazmcp sql db createとazmcp sql db updateです。どちらのコマンドも、--read-scaleにはEnabledまたはDisabledを指定します。(GitHub)
beta.29以前で起きていたこと
修正前は、readScaleが文字列として処理されていました。
たとえば、次のようにサポートされていないBothを指定しても、その値が無効であることを示すエラーが返されませんでした。
azmcp sql db update \
--subscription <subscription-id> \
--resource-group <resource-group> \
--server <server-name> \
--database <database-name> \
--read-scale BothBothは有効な値ではありません。しかし修正前は、この値だけが黙って破棄される可能性がありました。そのため、呼び出し元のスクリプトやAIエージェントは、次の2つを区別できませんでした。
readScaleが正しく適用された- 不正な値が無視され、設定されなかった
ほかの更新項目が正常に処理された場合、操作全体が成功したように見える点が特に問題です。AIエージェントが「読み取りスケールを変更しました」と回答しても、実際には設定が変わっていない可能性がありました。(GitHub)
beta.30では無効な値を明示的に拒否する
beta.30では、readScaleが型付きの列挙値として扱われます。有効な値は次の2つです。
| 指定値 | 意味 | beta.30での処理 |
|---|---|---|
Enabled | 読み取り専用ルーティングを有効化 | 正常に受け付ける |
Disabled | 読み取り専用ルーティングを無効化 | 正常に受け付ける |
Bothなど | 未定義の値 | 検証エラーを返す |
不正な値は、コマンドの実行やAzure Resource Managerへの処理が始まる前に拒否されます。サーバー実装上はHTTP 400の検証エラーとして扱われるため、認証失敗やAzure側の障害と区別しやすくなります。
有効な値は大文字と小文字を区別せずに処理されますが、プロンプト、ログ、構成ファイルの表記を統一するため、EnabledまたはDisabledと記述するのが分かりやすいでしょう。(GitHub)
read-scaleは何を設定するパラメーターか
Azure SQL Databaseの読み取りスケールアウトは、読み取り専用の処理を読み取り専用レプリカへ振り分けるための機能です。
readScaleを有効にすると、接続文字列でアプリケーションの意図を読み取り専用に設定している接続が、同じリージョンの読み取り専用セカンダリレプリカへルーティングされる場合があります。分析処理や参照系APIなど、書き込み処理と分離できるワークロードの負荷軽減に利用できます。(Microsoft Learn)
正常な更新例は次のとおりです。
azmcp sql db update \
--subscription <subscription-id> \
--resource-group <resource-group> \
--server <server-name> \
--database <database-name> \
--read-scale Enabled無効化する場合は、次のように指定します。
azmcp sql db update \
--subscription <subscription-id> \
--resource-group <resource-group> \
--server <server-name> \
--database <database-name> \
--read-scale Disabledただし、読み取りスケールアウトを利用できる条件は、Azure SQL Databaseのサービスレベルや構成によって異なります。引数が正しくても、対象データベースが機能をサポートしているとは限りません。Azure MCP Serverの入力検証と、Azureサービス側の利用条件は分けて確認する必要があります。(Microsoft Learn)
この修正がAIエージェント運用で重要な理由
人がCLIを操作している場合は、実行後にAzure portalを確認することで設定ミスに気付けることがあります。一方、AIエージェントによる自動操作では、返却された結果をもとに次の処理へ進むため、値が黙って無視される動作は大きな問題になります。
たとえば、次のような処理を自動化しているケースです。
- AIエージェントがデータベースの性能要件を判断する
- SQLデータベースのSKUと
readScaleを同時に更新する - 成功レスポンスを受けて構成管理システムへ完了を記録する
- 後続のアプリケーション展開を開始する
修正前は、SKUだけが変更され、readScaleは無視された状態でも処理が継続する可能性がありました。
beta.30では不正な値が明示的な検証エラーになるため、AIエージェントはエラー内容を読み、EnabledまたはDisabledへ修正して再実行できます。不要なAzure Resource Manager呼び出しより前に失敗することも、エージェントが原因を切り分けるうえで有効です。(GitHub)
過去の実行結果も確認する
beta.30へ更新しても、以前に無視された設定が自動的に適用されるわけではありません。
過去にAzure MCP ServerでSQLデータベースを作成・更新した場合は、実行ログやプロンプト履歴を検索し、readScaleに次のような値を渡していなかったか確認してください。
BothOnOffTrueFalseAuto- 自然言語からそのまま生成された任意の文字列
該当する履歴があれば、Azure portalの対象データベースにある「コンピューティングとストレージ」から、現在の読み取りスケールアウト設定を確認します。意図した状態と異なる場合は、EnabledまたはDisabledを明示して再実行してください。(Microsoft Learn)
新ツール設計への移行完了とは
beta.30では、Azure MCP ServerのCoreツールが新しいツール設計へ移行し、従来のツール作成フレームワークが削除されました。
これは「新しいAzure操作が大量に追加された」という意味ではありません。ツールを定義し、オプションを受け取り、コマンドへ値を渡す内部基盤の刷新です。
主な変更は次のとおりです。
| 従来の設計 | 新しい設計 |
|---|---|
| オプション定義とコマンド内のバインド処理を個別に実装 | 属性ベースでオプションを定義 |
| 旧来のコマンド基底クラスを使用 | 型付きの新しいコマンド基底クラスを使用 |
| 一部で静的なサブスクリプション解決を使用 | ISubscriptionResolverへ統一 |
ServiceStart系の内部名称 | ServerStart系の名称へ変更 |
CommandHelperやGlobalOptionsなどの旧基盤 | 不要な旧基盤を削除 |
実装上は、[Option]や[OptionContainer]を使った属性駆動のオプション定義と、型付きのBaseCommandまたはAuthenticatedCommandへ移行しています。サブスクリプション解決もインターフェース経由となり、テスト時に差し替えやすい構成へ変更されました。(GitHub)
通常の利用者がazmcp server startのコマンド名を変更する必要はありません。一方、Azure MCP Serverをソースコードから独自ビルドしている場合や、旧クラスを参照する独自ツールを組み込んでいる場合は、コンパイルエラーやテスト失敗が発生しないか確認が必要です。
未使用パラメーター削除は破壊的変更
「未使用パラメーターなら削除されても影響はない」と考えがちですが、呼び出し側にとってはツールスキーマの変更です。
古いパラメーターが実際のAzure操作に使われていなかったとしても、固定スクリプトやAIエージェントがそのパラメーターを送信していた場合、更新後は次のような問題が発生する可能性があります。
- 未知のパラメーターとして拒否される
- 生成済みの型定義と実際のツール定義が一致しなくなる
- キャッシュされたツールスキーマをAIエージェントが参照し続ける
- 固定プロンプトに古い引数名が残る
- 独自のラッパーやテストが失敗する
特に、MCPクライアントがツール一覧をキャッシュしている場合は、Azure MCP Serverだけを更新しても新しいスキーマが反映されないことがあります。サーバーを再起動したうえで、MCPクライアント側でもツール一覧を更新してください。
Coreツールの未使用パラメーター削除と旧ツール設計の廃止は、公式変更履歴で破壊的変更として扱われています。SQL修正だけを目的に更新する場合も、SQL以外の主要ツールを含めたスモークテストが必要です。(GitHub)
自分の環境が影響を受けるか判断する
| 利用状況 | 影響度 | 対応 |
|---|---|---|
SQLデータベースの作成・更新でreadScaleを指定している | 高 | beta.30以降で動作確認する |
| AIにSQLデータベース設定を自動生成させている | 高 | 生成される値とエラー時の再試行処理を確認する |
| 固定スクリプトで余分な引数を送っている | 高 | 現行スキーマと引数を照合する |
| Azure MCP Serverの独自ビルドや拡張コードがある | 高 | 旧ツール基盤への依存を確認する |
| MCPツール定義からコードを自動生成している | 中 | ツール一覧を再取得し、型を再生成する |
| SQLの取得・一覧表示だけを使っている | 低 | SQL修正の直接影響は小さいが、主要操作は再テストする |
| SQLツールを使っていない | 低 | Coreツールの破壊的変更だけ確認する |
とくに注意したいのは、AIエージェントがreadScaleの値を自由生成している環境です。プロンプトに「読み取りを有効化する」などとだけ記述すると、モデルがOnやTrueなどを選ぶ可能性があります。
固定プロンプトやツール呼び出しルールには、次のように許容値を明記してください。
readScaleには必ずEnabledまたはDisabledのどちらかを指定する。ほかの値は使用しない。
beta.30への更新と確認手順
現在のバージョンを確認する
Azure MCP CLIを直接実行できる環境では、次のコマンドでサーバー名とバージョンを確認できます。
azmcp server infoNPMパッケージを直接検証する場合は、バージョンを固定して実行できます。
npx -y @azure/[email protected] server infoAzure MCP ServerはNPM、NuGet、PyPI、Docker、IDE拡張機能など複数の形態で配布されています。確認対象が、MCPクライアントから実際に起動されている実行ファイルと一致していることが重要です。(GitHub)
検証環境ではバージョンを固定する
NPMでプロジェクトへインストールする場合は、次のようにバージョンを固定できます。
npm install @azure/[email protected]NuGetのグローバルツールを新しい検証環境へ導入する場合は、次の形式です。
dotnet tool install --global Azure.Mcp --version 3.0.0-beta.30@latestを使用すると、検証中に別のプレリリースへ切り替わる可能性があります。再現性が必要な検証環境やCI/CDでは、修正を確認できるバージョンを明示してください。NuGet上でも3.0.0-beta.30はプレリリースとして提供されています。
更新後のツール定義を確認する
Azure MCP CLIには、Azure操作を実行せずにコマンドとパラメーターを確認する--learnがあります。
SQLデータベースの作成・更新で利用できる引数を確認するには、次のように実行します。
azmcp sql db create --learn
azmcp sql db update --learnこの結果と、既存のスクリプト、固定プロンプト、ツールラッパーが送信しているパラメーターを比較します。
--learnはAzure操作を実行せずに、コマンド名、説明、CLIパス、サポート対象のオプションを取得するための機能です。破壊的な作成・更新コマンドのスキーマを安全に確認できます。
MCPクライアントのツール一覧を更新する
サーバー更新後は、次の順番で再読み込みします。
- Azure MCP Serverのプロセスを停止する
- MCPクライアントを再起動する
- ツール一覧を更新する
- SQLツールの入力スキーマを確認する
- 検証用データベースで作成・更新を試す
VS CodeなどのIDEでは、サーバーを再起動しただけでなく、チャット画面のツール一覧も更新してください。公式READMEでも、導入後にツール一覧を更新し、Azure MCP Serverのツールが表示されることを確認する手順が案内されています。
正常系と異常系を確認する
検証用データベースでは、少なくとも次の3パターンを確認します。
| テスト | 指定値 | 期待結果 |
|---|---|---|
| 正常系1 | Enabled | 更新処理が受け付けられる |
| 正常系2 | Disabled | 更新処理が受け付けられる |
| 異常系 | Both | Azure操作前に検証エラーになる |
異常系の例は次のとおりです。
azmcp sql db update \
--subscription <test-subscription-id> \
--resource-group <test-resource-group> \
--server <test-server-name> \
--database <test-database-name> \
--read-scale Bothこのコマンドは、必ず検証環境で実施してください。beta.30ではBothが黙って無視されるのではなく、無効な列挙値として明示的に拒否されることを確認します。(GitHub)
更新時の注意点
HTTP 400は修正後の正常なエラー動作
beta.30へ更新後、不正なreadScaleに対してHTTP 400相当のエラーが返るのは、新たな障害ではありません。
これまで見逃されていた入力ミスが、正しく検出されるようになった結果です。エラーを一律に再試行するのではなく、レスポンスを確認してEnabledまたはDisabledへ修正してください。
SQL接続やクエリのエラー修正ではない
今回の修正対象に、次の問題は含まれていません。
- SQL認証の失敗
- Microsoft Entra認証の失敗
- ファイアウォールやPrivate Endpointの問題
- T-SQLクエリの構文エラー
- 接続タイムアウト
- データベースサーバーの作成失敗
- SKUやリージョンの非対応
これらの問題が発生している場合、beta.30へ更新するだけでは解消しません。エラーコード、Azure Activity Log、MCPサーバーの標準エラー出力を確認し、別の原因として切り分ける必要があります。
プレリリース版として評価する
3.0.0-beta.30にはSQLツールの重要な修正が含まれますが、同時にCoreツールの破壊的変更とMCP SDKのプレビュー版更新も含まれています。(GitHub)
本番適用前には、少なくとも次を確認してください。
- MCPクライアントが正常に接続できる
- ツール一覧を取得できる
- Azure認証が成功する
- 利用中の名前空間とツールが表示される
- 読み取り操作が成功する
- 作成・更新操作の確認画面が表示される
- 固定プロンプトから不要なパラメーターが送信されない
- 問題発生時に旧バージョンへ戻せる
beta.30適用後に行うべきこと
Azure MCP Server 3.0.0-beta.30で最も重要な修正は、SQLデータベースの--read-scaleに無効な値を渡した際、黙って無視せず検証エラーを返すようになったことです。
SQLデータベースの作成・更新をAIエージェントへ任せている場合は、beta.30またはこの修正を含む後続版を検証し、プロンプト内でEnabledとDisabledの許容値を明示してください。
同時に、新ツール設計への移行と未使用パラメーターの削除が含まれるため、更新後はMCPクライアントのツール一覧を再取得します。--learnで現行パラメーターを確認し、固定スクリプトやラッパーから古い引数を削除してください。
最後に、過去の操作履歴も確認します。以前に不正なreadScaleを送信していた可能性がある場合は、Azure上の実設定を確認し、正しい値で再適用することが必要です。
コメント