Azure SQLで「VS CodeからAIエージェントにデータベースを参照させたい」「SQL MCP Serverをローカルで試したい」と考えている開発者にとって、今回の公式クイックスタートの要点は明確です。Data API builderを使い、.NET Aspireやコンテナーを用意しなくても、Visual Studio CodeからSQL MCP Serverへ接続できるローカル検証ルートが整理されました。 ただし、本番データに接続する前に、接続文字列、MCPの公開範囲、ロール、フィールド説明、VS Codeのワークスペース設定を必ず確認する必要があります。Microsoft Learnの手順では、Data API builder CLIでSQL MCP Serverを起動し、VS Codeの.vscode/mcp.jsonから接続する流れが示されています。(Microsoft Learn)
Azure SQLのSQL MCP Serverクイックスタートで押さえるべき結論
今回の「Quickstart – Visual Studio Code local – SQL MCP Server」は、Azure SQLやSQL Server系データベースをAI開発ワークフローに組み込むための、ローカル開発向けの入り口と考えると分かりやすいです。
ポイントは次の3つです。
| 観点 | 押さえるべき内容 |
|---|---|
| 開発体験 | VS CodeからMCPサーバーを起動または接続し、Copilot ChatなどのMCP対応クライアントからデータ操作ツールを利用できる |
| セキュリティ | AIエージェントがDBへ直接自由にSQLを投げるのではなく、Data API builderのエンティティ、権限、ロール、ポリシーを通して操作する |
| 導入判断 | まずはローカルでstdio接続を使い、チーム展開やクラウド配置ではHTTP接続と認証・監視を設計する |
SQL MCP ServerはData API builder 1.7以降で利用でき、Microsoftは最新機能や不具合修正には2.0 previewの利用にも触れています。ローカル開発では、HTTPポートを開かずにVS CodeがDABプロセスを管理するstdio接続が推奨されています。(Microsoft Learn)
何が変わるのか
これまでAzure SQLをAI開発に組み込む場合、独自APIを作る、SQLを直接生成させる、MCPサーバーを個別に構築する、といった選択肢がありました。今回の公式クイックスタートでは、Data API builderを使うことで、DB接続、エンティティ公開、権限制御、MCPツール化を1つの構成ファイルに寄せられる点が大きな意味を持ちます。
特に重要なのは、SQL MCP Serverが単純な「自然言語からSQLを作る仕組み」ではないことです。Microsoftの説明では、SQL MCP ServerはNL2SQLではなく、Data API builderのエンティティ抽象化とクエリビルダーを通して、より制御された形でデータ操作を行う設計です。これにより、AIエージェントが内部スキーマへ無制限に触れるのではなく、設定されたテーブル、ビュー、ストアドプロシージャ、権限の範囲で操作します。(Microsoft Learn)
対象者は誰か
このクイックスタートの影響を受けるのは、Azure SQLを運用しているすべての利用者ではありません。主な対象は、Azure SQLを使ったアプリ開発やAIエージェント連携を進めるチームです。
| 対象者 | 確認すべきこと |
|---|---|
| アプリ開発者 | VS CodeのMCP設定、DAB CLI、dab-config.json、エンティティ説明の追加 |
| データベース管理者 | Azure SQLの接続許可、公開するテーブル・ビュー・ストアドプロシージャの範囲 |
| セキュリティ管理者 | anonymousロールの扱い、読み取り専用ロール、更新・削除操作の制限 |
| DevOps担当者 | ローカル検証とクラウド展開の切り分け、環境変数、Key Vault、監視ログ |
| AI活用推進担当 | CopilotやAIエージェントに許可する業務操作の定義 |
既存のAzure SQLデータベースが自動的に変更されるわけではありません。変更されるのは、開発者がData API builderを使ってどのDBオブジェクトをMCPツールとして公開するかというアプリケーション側の設計です。
ローカル構成の全体像
公式クイックスタートの基本構成はシンプルです。
VS Code / Copilot Chat
↓
.vscode/mcp.json
↓
SQL MCP Server
↓
Data API builder
↓
Azure SQL または SQL ServerData API builderは、Azure SQLやSQL Serverをリレーショナルバックエンドとしてサポートし、mssqlのデータソースとして接続できます。DABはMicrosoft.Data.SqlClientを使い、Azure SQL DatabaseやオンプレミスSQL Serverの両方に対応します。(Microsoft Learn)
公式手順のサンプルではローカルSQL ServerやLocalDB、Docker上のSQL Serverが前提に含まれていますが、Azure SQLで試す場合は接続文字列とネットワーク許可をAzure SQL向けに置き換える必要があります。
ローカルで試す最短手順
Azure SQLで試す場合も、考え方は公式クイックスタートと同じです。まずは本番DBではなく、検証用データベースか最小権限のユーザーで始めてください。
前提ツールを確認する
公式手順では、.NET 9以降、SQL Server 2016以降またはSQL Server系データベースへのアクセス、Data API builder CLIが前提として示されています。(Microsoft Learn)
dotnet --version
dotnet new tool-manifest
dotnet tool install microsoft.dataapibuilder
dotnet tool restoreすでにData API builderを使っている場合でも、SQL MCP Server機能を使うにはDABのバージョンを確認します。
dab --versionAzure SQL向けの接続文字列を環境変数で管理する
公式クイックスタートでは.envファイルにMSSQL_CONNECTION_STRINGを置く形が紹介されています。Azure SQLに接続する場合、ローカル開発ではMicrosoft Entra IDの既定資格情報を使う構成が扱いやすいです。Data API builderの公式ドキュメントでも、Azure SQL向けのローカル開発ではAuthentication=Active Directory Defaultを使う例が示されています。(Microsoft Learn)
MSSQL_CONNECTION_STRING=Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Default;Encrypt=True;この方式を使う場合は、事前にAzure CLIでサインインします。
az loginSQL認証を使う場合でも、パスワード入りの接続文字列をdab-config.jsonやGitリポジトリに直接書かないでください。Microsoftのドキュメントでも、パスワードを含む接続文字列はソース管理へコミットせず、環境変数やAzure Key Vaultを使うべきだと説明されています。(Microsoft Learn)
Data API builderを初期化する
作業フォルダーで、DAB設定ファイルを作成します。
dab init --database-type mssql --connection-string "@env('MSSQL_CONNECTION_STRING')" --host-mode Development --config dab-config.json次に、AIエージェントに公開するエンティティを追加します。最初は読み取り専用にするのが安全です。
dab add Products --source dbo.Products --permissions "anonymous:read" --description "Product catalog with inventory, price, and cost."公式サンプルではanonymous:readが使われていますが、これはクイックスタート用の簡易設定です。実データや社内データで試す場合は、anonymousではなく検証用ロールを作り、読み取り対象のテーブルや列を絞ってください。
フィールド説明を追加する
SQL MCP Serverでは、フィールド説明が非常に重要です。説明がないと、AIエージェントはエンティティ名だけを見て列名や意味を推測しやすくなります。Microsoftのドキュメントでも、フィールドメタデータがない場合はエージェントが列名を誤って推測する可能性があるため、説明の追加が推奨されています。(Microsoft Learn)
dab update Products --fields.name Id --fields.primary-key true --fields.description "Product Id"
dab update Products --fields.name Name --fields.description "Product name"
dab update Products --fields.name Inventory --fields.description "Units in stock"
dab update Products --fields.name Price --fields.description "Retail price"
dab update Products --fields.name Cost --fields.description "Store cost"実務では、単に「価格」「在庫」と書くよりも、単位や業務上の意味まで入れると精度が上がります。
| 悪い説明 | 良い説明 |
|---|---|
| Price | Retail price in JPY, excluding tax |
| Status | Order status. Valid values: Pending, Approved, Shipped, Cancelled |
| CreatedAt | Order creation timestamp in UTC |
| Inventory | Current sellable stock count. Excludes reserved items |
固定値を持つ列では、許可される値を説明に明記してください。たとえばEnvironment列なら「Valid values: Prod, Dev, Test, UAT」のように書くと、AIエージェントが似た値を作ってしまうリスクを減らせます。(Microsoft Learn)
stdioとHTTPのどちらを選ぶべきか
今回のクイックスタートで実務上もっとも迷いやすいのが、SQL MCP Serverの起動方式です。ローカル開発ではstdio、クラウド展開や複数クライアントからの共有ではHTTPを選ぶのが基本です。
| 利用シーン | 推奨方式 | 理由 |
|---|---|---|
| 自分のPCでVS Codeから試す | stdio | VS CodeがDABプロセスを管理し、HTTPポートを開かずに済む |
| Copilot Chatでローカル検証する | stdio | ターミナルでdab startを起動し続ける必要がない |
| Azure Container AppsやApp Serviceに配置する | HTTP | ネットワーク越しにMCPエンドポイントへ接続するため |
| チームや複数エージェントで共有する | HTTP | 共通エンドポイントとして管理しやすい |
| CI/CDやスクリプトから直接呼び出す | stdioまたはHTTP | 実行環境と認証方式に合わせて選ぶ |
stdioモードでは、DABは標準入力・標準出力を通じてMCPクライアントと通信し、HTTPサーバーやネットワークポートを起動しません。公式ドキュメントでは、ローカル開発やVS Code with GitHub Copilotではstdio、クラウドホスティングや共有エンドポイントではHTTPが推奨されています。(Microsoft Learn)
VS CodeのMCP設定で確認すべきこと
VS Codeから接続するには、単一ファイルを開くのではなく、dab-config.jsonを含むフォルダーをワークスペースとして開く必要があります。公式手順でも、VS Codeの設定やMCPサーバー定義はワークスペース内でのみ有効になると説明されています。(Microsoft Learn)
ローカル開発では、.vscode/mcp.jsonに次のような設定を置きます。
{
"servers": {
"sql-mcp-server": {
"type": "stdio",
"command": "dab",
"args": [
"start",
"--mcp-stdio",
"role:anonymous",
"--loglevel",
"error",
"--config",
"${workspaceFolder}/dab-config.json"
]
}
}
}本番相当の検証では、role:anonymousのままにしないでください。エンティティのpermissionsで定義したロールに置き換え、読み取り、作成、更新、削除、ストアドプロシージャ実行のどこまで許可するかを明確にします。
また、stdioトランスポートではdab-config.jsonのruntimeセクションに"mcp": { "enabled": true }が必要と説明されています。設定が欠けているとstdioモードでDABが起動しないため、明示的に入れておくと切り分けがしやすくなります。(Microsoft Learn)
{
"runtime": {
"mcp": {
"enabled": true,
"path": "/mcp",
"dml-tools": {
"describe-entities": true,
"create-record": false,
"read-records": true,
"update-record": false,
"delete-record": false,
"execute-entity": false,
"aggregate-records": false
}
}
}
}最初の検証では、read-recordsとdescribe-entitiesだけを有効にするのが安全です。作成・更新・削除を有効にするのは、ロール設計、監査、テストデータ、誤操作時の復旧方法を確認してからにしてください。
Azure SQLで管理者が確認すべき設定
Azure SQLに接続する場合、ローカルDBでの検証とは違い、接続と認証の設計が重要になります。
| 確認項目 | 実務での判断基準 |
|---|---|
| ネットワーク | 開発PCからAzure SQLへ接続できるか。IPファイアウォール、Private Link、VPNなどの方針を確認する |
| 認証 | ローカル検証はActive Directory Default、Azure上の展開はマネージドIDを優先する |
| 権限 | DAB用ユーザーまたはIDに、必要最小限のDB権限だけを付与する |
| 接続文字列 | 環境変数またはKey Vaultで管理し、Gitに含めない |
| 監査 | MCP経由の操作をDABログ、Azure SQL監査、Application Insightsなどで追跡できるようにする |
| ロール | anonymousを実データに使わず、用途別ロールを作る |
Azure SQL Databaseでは、インターネットからの接続はファイアウォール規則の確認を受けます。接続元IPがデータベースレベルまたはサーバーレベルのIPファイアウォール規則に含まれていない場合、接続は失敗します。可能な場合は、全DBに広く効くサーバーレベル規則ではなく、対象DBに絞れるデータベースレベル規則の利用も検討してください。(Microsoft Learn)
開発者が確認すべきMCPツールの範囲
SQL MCP Serverは、DAB設定に基づいてMCPツールを公開します。代表的なDMLツールは次のとおりです。
| ツール | 用途 | 最初に有効化すべきか |
|---|---|---|
describe_entities | 利用可能なエンティティ、フィールド、操作を確認する | 有効化する |
read_records | テーブルやビューからデータを読む | 検証初期は有効化しやすい |
create_record | レコードを追加する | テストDB以外では慎重に扱う |
update_record | 既存レコードを更新する | 誤更新対策が必要 |
delete_record | レコードを削除する | 原則、初期検証では無効化 |
execute_entity | ストアドプロシージャを実行する | 業務処理の副作用を確認してから |
aggregate_records | 集計クエリを実行する | 利用バージョンを確認する |
DMLツールはRBAC、エンティティ権限、ポリシーに従って動作します。なお、aggregate_recordsは1.7.xでは利用できず、2.0 preview以降の機能として説明されています。バージョン差に依存する動作をアプリや運用手順に組み込む前に、実際にインストールしているDABのバージョンでツール一覧を確認してください。(Microsoft Learn)
移行時の注意点
既存のData API builder構成がある場合、SQL MCP Serverの導入は「新しいDBを作る」作業ではなく、既存のDAB設定をAIエージェント向けに見直す作業です。
特に次の点を確認してください。
| 移行ポイント | 注意点 |
|---|---|
| 既存エンティティ | REST/GraphQL向けに公開していたエンティティが、MCPでも使われる前提で問題ないか確認する |
| 権限 | anonymous:*のような広すぎる権限をそのまま使わない |
| フィールド | 機密列、内部メモ、原価、個人情報などをMCP経由で返してよいか確認する |
| 説明文 | AIが誤解しやすい略語や社内コードに説明を追加する |
| 複雑なSQL | JOINや複雑な集計は、ビューやストアドプロシージャで明示的に設計する |
| バージョン | 1.7.xと2.0 previewで使えるMCPツールの差を確認する |
read_recordsは単一のテーブルまたはビューを対象とする設計で、JOIN操作はサポートされません。複雑な問い合わせが必要な場合は、ビューを作るか、パラメーター付きストアドプロシージャをexecute_entityで扱う構成を検討します。(Microsoft Learn)
また、SQL MCP Serverはデータ操作を中心に設計されており、DDLによるスキーマ変更を行うための仕組みではありません。テーブル作成やスキーマ変更は、MCP経由ではなく、通常のDB管理手順やVS CodeのMSSQL拡張などで扱うのが適切です。(Microsoft Learn)
展開時の注意点
ローカルで動いた設定を、そのままチームや本番環境へ展開するのは避けてください。ローカルのstdio構成と、クラウド上のHTTP構成では、考えるべき論点が変わります。
ローカル検証
ローカル検証では、stdioを使うとHTTPポートを開かずに済みます。VS CodeがDABを子プロセスとして起動・停止するため、開発者のPCで試すには扱いやすい構成です。
ただし、ローカル検証でもAzure SQLへ接続する場合は、Azure SQLのファイアウォール、Entra IDログイン、DAB用のDB権限を確認してください。AIエージェントの操作は便利ですが、接続先が本番DBであればリスクは通常のアプリケーションと同じです。
クラウド展開
Azure Container AppsやApp ServiceなどにSQL MCP Serverを配置する場合は、HTTPトランスポートを前提にします。クラウド上では、接続文字列にSQL認証を埋め込むよりも、マネージドIDやKey Vaultを使う構成を優先します。Data API builderの認証ドキュメントでも、Azure SQLの本番シナリオではマネージドIDを使う接続例が示されています。(Microsoft Learn)
クラウド展開で確認すべき項目は次のとおりです。
| 項目 | 確認内容 |
|---|---|
| 認証方式 | Entra ID、App Service認証、JWT、マネージドIDのどれを使うか |
| ネットワーク | Azure SQLのパブリックアクセス、Private Link、VNet統合の方針 |
| 監視 | Application Insights、Log Analytics、OpenTelemetryでMCP操作を追跡できるか |
| 権限分離 | 開発、検証、本番でDAB設定と接続先を分離しているか |
| シークレット管理 | .envではなくKey Vaultやアプリ設定を使っているか |
| 破壊的操作 | delete_recordやupdate_recordを本当に公開する必要があるか |
SQL MCP Serverはログやテレメトリにも対応しており、Application Insights、Azure Log Analytics、OpenTelemetryを使った監視に関する説明も公式ドキュメントに含まれています。(Microsoft Learn)
失敗しやすいポイントと対処法
VS CodeでMCPサーバーが表示されない
まず、VS Codeで単一ファイルではなくフォルダーを開いているか確認します。.vscode/mcp.jsonはワークスペース内で有効になるため、dab-config.jsonを含むプロジェクトフォルダーを開く必要があります。(Microsoft Learn)
次に、次の項目を確認してください。
| 確認項目 | 対処 |
|---|---|
.vscode/mcp.jsonの場所 | プロジェクト直下の.vscodeフォルダー内に置く |
dabコマンド | dotnet tool restore後にターミナルを開き直す |
--configのパス | ${workspaceFolder}/dab-config.jsonが実ファイルを指しているか確認する |
| MCP有効化 | runtime.mcp.enabledがtrueになっているか確認する |
| ロール | role:<name>がエンティティのpermissionsに存在するか確認する |
Azure SQLに接続できない
Azure SQLに接続できない場合は、MCPやVS Codeより前に、通常のDB接続として切り分けます。
| 症状 | 主な原因 |
|---|---|
| ログインできない | Entra IDログイン、SQLユーザー、DBユーザー作成の不備 |
| 接続が拒否される | Azure SQLのIPファイアウォールまたはネットワーク設定 |
| ローカルでは動くがクラウドで失敗する | マネージドIDのDB権限不足、接続文字列の環境差 |
| DAB起動時に失敗する | 接続文字列の形式、環境変数名、dab-config.jsonの誤り |
Azure SQLでは、接続元IPが許可されていないと接続要求が失敗します。開発PCから接続する場合でも、必要なIPファイアウォール規則が設定されているか確認してください。(Microsoft Learn)
ツール呼び出しで権限エラーになる
role:anonymousやrole:authenticatedなど、VS Code側で指定したロールと、DABエンティティのpermissionsが一致しているか確認します。stdioモードではrole:<name>を--mcp-stdioの直後に置く必要があり、省略するとanonymousが既定になります。(Microsoft Learn)
たとえば、読み取り専用ロールを使うなら次のようにします。
dab add Products --source dbo.Products --permissions "mcp-reader:read" --description "Product catalog".vscode/mcp.jsonでは、次のように指定します。
"args": [
"start",
"--mcp-stdio",
"role:mcp-reader",
"--loglevel",
"error",
"--config",
"${workspaceFolder}/dab-config.json"
]AIエージェントが意図しない列を選ぶ
この場合は、フィールド説明が不足している可能性があります。特に、略語、コード値、単位、業務ルール、日時のタイムゾーン、金額の税込・税抜は必ず説明に含めてください。
例として、次のような説明が実務では有効です。
dab update Orders --fields.name Status --fields.description "Order status. Valid values: Pending, Approved, Shipped, Cancelled"
dab update Orders --fields.name CreatedAt --fields.description "Order creation timestamp in UTC"
dab update Products --fields.name Cost --fields.description "Internal product cost. Do not expose to public users"機密列を公開したくない場合は、説明を書く前に、そもそもそのフィールドを対象ロールから除外することを検討してください。
orderbyや集計で想定どおり動かない
DMLツールには仕様上の制約があります。read_recordsのorderbyは文字列ではなく文字列配列として渡す必要があり、単一文字列を渡すとエラーになります。また、aggregate_recordsはバージョンによって利用可否が異なります。(Microsoft Learn)
検証時は、AIエージェントに任せきりにせず、次の順で確認します。
describe_entitiesで対象エンティティとフィールドが見えているか確認する- 単純な
read_recordsで読み取りを確認する - フィルターや並び替えを追加する
- 必要に応じてビューやストアドプロシージャに切り出す
Azure SQLで使う前に決めておくべき運用ルール
SQL MCP Serverは便利ですが、「AIがDBを触れる」仕組みである以上、運用ルールを先に決める必要があります。
最低限、次のルールをチームで合意してください。
| ルール | 具体例 |
|---|---|
| 最初は読み取り専用 | describe_entitiesとread_recordsだけを有効にする |
| 本番DBへ直接つながない | 検証DB、ステージングDB、読み取りレプリカなどから始める |
anonymousを使わない | 検証用ロール、業務別ロールを明示する |
| 機密情報を除外する | 個人情報、原価、内部メモ、認証情報を返さない |
| 説明文をレビューする | AIが誤解しないよう、列の意味と有効値を明記する |
| 操作ログを残す | DABログ、Azure SQL監査、Application Insightsを確認する |
| 破壊的操作を制限する | delete_recordは原則無効。必要な場合は専用ロールに限定する |
特に注意したいのは、クイックスタートのサンプル設定をそのまま社内DBに適用しないことです。anonymous:readは動作確認には便利ですが、実データでは「誰が、どの目的で、どの範囲を読めるのか」を明確にする必要があります。
まず何から始めるべきか
Azure SQLでSQL MCP Serverを試すなら、次の順番で進めるのが安全です。
- 検証用Azure SQL DatabaseまたはローカルSQL Serverを用意する
- Data API builder CLIをインストールし、DABのバージョンを確認する
- 接続文字列を環境変数で管理する
- 読み取り専用のエンティティを1つだけ追加する
- フィールド説明を丁寧に追加する
.vscode/mcp.jsonをstdioで作成する- VS Codeで
MCP: List Serversから接続する - Copilot Chatで単純な読み取り質問を試す
- 権限、ログ、公開範囲を確認する
- 必要があればHTTP構成やクラウド展開を検討する
VS CodeのMCPサポートは今後も変わる可能性があるため、設定スキーマやクライアント側の操作は固定的に決め打ちしない方が安全です。公式クイックスタートでも、VS Code MCPサポートは進化中であり、構成スキーマが将来変更される可能性に触れています。(Microsoft Learn)
まとめ
Azure SQLの「Quickstart – Visual Studio Code local – SQL MCP Server」は、AIエージェントとデータベースを安全に接続するための第一歩です。大きな価値は、VS CodeからData API builderを介してSQL MCP Serverを使えるようになり、DB操作をDABのエンティティ、ロール、権限、説明メタデータで制御できる点にあります。
まずはローカルのstdio接続で、読み取り専用の検証から始めてください。そのうえで、Azure SQLの接続方式、ファイアウォール、マネージドID、フィールド説明、DMLツールの有効範囲を確認します。チーム展開や本番利用を考える場合は、HTTPトランスポート、監視、Key Vault、権限分離まで含めて設計することが重要です。
コメント