オプションの Azure Cosmos DB シェル モデル コンテキスト プロトコル (MCP) サーバーを使用すると、互換性のある AI クライアントがシェル ツールを検出して呼び出すことができます。 ローカルで実行され、シェルの接続、ナビゲーション、構成済みの ID を共有します。 これは、Microsoft によってホストされる MCP エンドポイントではありません。
データベース アクセスなしでドキュメントを取得する場合は、代わりに Microsoft Learn MCP サーバーを使用してください。
Prerequisites
- Azure Cosmos DB Shell をインストールします。
- 適切なデータ プレーンのアクセス許可やネットワーク接続など、Azure Cosmos DB アカウントへのアクセス。
- Streamable HTTP またはレガシ HTTP+SSE をサポートする MCP クライアント。 一部のツールでは、クライアントがユーザー確認要求をサポートしている必要があります。
- ツールの呼び出しを許可する前に、AI クライアントがモデル プロバイダーに送信するデータを確認します。
MCP サーバーを有効にする
オペレーティング システムのターミナルからシェルを起動します:
cosmosdbshell --mcp
既定のポートは 6128 です。 別のローカル ポートを選択するには:
cosmosdbshell --mcp 6129
そのシェル内で、目的のアカウントに接続し、アカウント ルート メタデータを確認します。
connect https://<account-name>.documents.azure.com/ --tenant=<tenant-id>
info --format=json
アカウント名とテナント ID を置き換え、サインインを完了し、返された accountId と uriを確認します。 MCP は、アカウントのアクセス許可を付与したり、ネットワーク ルールをバイパスしたりしません。
サーバーは、同じポートで次のトランスポートをサポートします。
| Transport | 既定のエンドポイント |
|---|---|
| ストリーミング可能な HTTP(推奨) | http://127.0.0.1:6128/ |
| レガシー HTTP+SSE | http://127.0.0.1:6128/sse |
起動時に選択したポートを使用します。 サーバーは、ホストと配信元の検証を使用してループバックにバインドされています。 信頼できるローカル クライアントからの接続のみを許可し、パブリック リスナー、トンネル、またはポートフォワーディングを介してエンドポイントを公開しないでください。
シェルは stdio ではなく HTTP MCP を提供します。
cosmosdbshell --mcpを stdio サーバーとして起動するように MCP クライアントを構成しないでください。
Visual Studio Code から接続する
拡張機能で管理される登録または手動で構成された HTTP クライアントを選択します。 重複するツール セットを公開する場合を除き、両方を同じシェルに登録しないでください。
拡張機能による登録管理
- Azure Cosmos DB拡張機能をインストールします。
-
[設定] を開き、
cosmosDB.shell.MCP.enabledを有効にします。 - 必要に応じて、
cosmosDB.shell.MCP.portを既定値6128から変更します。 - コマンド パレットからAzure Cosmos DB Shell の起動を実行します。
- インストールまたは接続のプロンプトを完了し、起動されたシェルでアカウントを確認します。
- MCP: List Servers を使用して、拡張機能で登録された Azure Cosmos DB シェル サーバーを検索し、求められた場合はクライアント接続を開始します。
- 使用を承認する前に、検出されたツールを調べます。
シェルが MCP なしで既に実行されていた場合は、それを終了し、設定を有効にした後で新しいシェルを起動します。 設定を変更しても、サーバーが既存のプロセスに後から組み込まれることはありません。
サポートされているシェル設定は次のとおりです。
| Setting | Default | Purpose |
|---|---|---|
cosmosDB.shell.path |
空。 | シェルの実行可能パスをオーバーライドします。 |
cosmosDB.shell.MCP.enabled |
false |
拡張機能によって起動されたシェルで MCP を起動します。 |
cosmosDB.shell.MCP.port |
6128 |
拡張機能によって起動されたサーバー ポートを選択します。 |
これらの設定では、他のクライアントの Cosmos アカウントのアクセス許可や認証は構成されません。
HTTP の手動構成
シェルを起動する場合は、MCP: Add Server からその Streamable HTTP URL を追加するか、ワークスペースの MCP 構成で同等のエントリを使用します。
{
"servers": {
"cosmosdb-shell": {
"type": "http",
"url": "http://127.0.0.1:6128/"
}
}
}
別の MCP クライアントの場合は、同じ URL でその HTTP サーバーの構成形式を使用します。 クライアント構成スキーマは異なります。この JSON の例では、Visual Studio Codeのservers形式を使用します。
クライアントがシェル プロセスを使用している間は、シェル プロセスを実行したままにします。 ローカル サーバーを停止するには、そのシェルに「exit」と入力します。 クライアント接続のみを停止しても、独立して起動されたシェル プロセスが停止されるとは限りません。
ツールの検出と使用
接続後、クライアントのツール検出結果を調べます。 シェル ツールでは、 info、 schema、 query、 printなどのコマンド名が使用されます。クライアントはサーバー プレフィックスを追加することがあります。
リテラルのコマンド ライン フラグではなく、 構造化された引数を使用してツールを呼び出します。 たとえば、アカウントを確認した後、有界 query ツールの呼び出しで次を使用できます。
{
"query": "SELECT c.id FROM c",
"database": "MyDatabase",
"container": "MyContainer",
"max": 5
}
リソース名を意図したターゲットに置き換えてください。 この JSON はツールの引数であり、 /query エンドポイントの HTTP REST 要求本文ではありません。 クライアントを介して MCP プロトコルを使用します。
同等の対話型シェル構文は次のとおりです。
query "SELECT c.id FROM c" --database=MyDatabase --container=MyContainer --max=5
アシスタントにスキーマの検査を依頼し、必須フィールドのみを選択し、提案された書き込みを説明し、返された結果から実際のコストと完全性を報告します。
共有状態とページング
すべてのクライアントは、対話型シェルの接続とナビゲーションを共有します。 呼び出しはシリアル化されますが、1 つのクライアントの接続またはナビゲーションの変更が他のクライアントに影響します。 サポートされている場合は常に、明示的な database 引数と container 引数を渡します。 Visual Studio Code クエリ エディターがシェルの接続を共有していると想定しないでください。
MCP query と item-listing ls は、既定で 100 個のアイテムを含む制限付きのページを返します。 結果に null 以外の continuationTokenが含まれている場合は、同じオプションを持つ次の呼び出しの continuation 引数として変更せずに渡します。 この引数は MCP 専用です。対話型シェルでは、継続トークン フラグは受け入れられません。
null 以外のトークン、 resultIncomplete: true、または limitReached は、結果が完了していないことを示します。
resultIncomplete: trueを持つ null トークンは、切り捨てられた結果を再開できないことを意味します。完了として報告するのではなく、要求を絞り込むか、その上限を増やしてください。
ツールへのアクセスと確認について
シェルは、構成された接続の ID とアクセス許可を使用します。 Azure Cosmos DBデータのアクセス許可を管理プレーンのアクセス許可から分離し、タスクに必要なアクションのみを付与します。
| Capability | MCP の動作 |
|---|---|
| 診断、スキーマ検出、クエリ、およびポイント読み取り | 検出されたツール スキーマを通じて使用できます。 読み取りと診断プローブは RU を消費する可能性があります。 |
| トランザクション バッチ | 1 ショットの batch runのみ。ステートフル サブコマンドは対話型のままです。 |
| 独立した一括操作 |
bulk run、 bulk patch、および bulk delete; ステートフル ジョブは対話型のままです。 |
| ストアド プロシージャ、ユーザー定義関数、およびトリガー |
sproc、 udf、および trigger は MCP を介して公開されません。 |
| 変更フィードのストリーミング |
watch
/
tail は MCP を介して公開されません。 |
Important
シェル MCP は、構成されたアクセス許可でリソースとデータを変更または削除できます。 破壊的操作の前に、最小限の特権 ID を使用し、要求されたツールを確認し、重要なデータをバックアップします。 プロンプトで資格情報や機密性の高いドキュメントを共有しないでください。
delete、rm、rmcon、rmdbなどの破壊的コマンドには、明示的なユーザー確認が必要です。 force 引数は、その MCP 確認をバイパスしません。 一括書き込みでも確認が必要です。 save を使用せずに一括ドライ ランを実行しても、プランを保存するとローカル ファイルが書き込まれます。確認が必要です。
クライアントが必要な確認を提示できない場合、または拒否した場合、ツールは実行されずに失敗します。 別のコマンドまたは実行ルートでその結果をバイパスしないでください。 後で以前の場所に戻った場合でも、接続またはナビゲーションが変更されると、保留中の承認は無効になります。再び承認を要求する前に、ターゲットを再検証します。
項目を正確に削除するには、レビューと実行の間に同じデータベース、コンテナー、ID、完全に入力したパーティション キー、および実際のプレビュー ETag を保持します。 安全な削除手順に従います。
MCP コマンドは、接続文字列を含め、再生可能なシェル履歴に記録できます。 履歴を機密性の高いものとして扱い、Microsoft Entra認証を優先します。
MCP 接続のトラブルシューティング
環境を変更する前に、不足している実行可能ファイル、サーバー起動エラー、クライアント トランスポートまたは構成エラー、アカウント接続エラーを区別します。
- サーバーは使用できません。 シェル プロセスが
--mcpで実行されていることを確認するか、拡張機能の MCP 設定を有効にした後でシェル プロセスを再起動します。 - 誤ったトランスポートです。 Streamable HTTP にはルート URL、従来の SSE クライアントには
/sseを使用します。 MCP の初期化とツールの検出をクライアントで確認します。/healthエンドポイントは使用しないでください。 - ポートの競合。
6129などの別のポートを選択し、一致するようにクライアント URL を更新してください。 ポートを解放するために、無関係なプロセスを終了しないでください。 - アカウントへのアクセス権がありません。 シェルで、
doctor --no-update-check、whoami、スコープ付きのcan-i queryプローブを実行します。 認証、データのアクセス許可、およびネットワークの制限を個別に確認します。 - 結果が遅いか不完全です。 クエリを絞り込み、正の上限値を指定し、ページネーションを確認します。 呼び出しは 1 つの実行ゲートを共有します。並列要求を増やすと、同時に実行されることはありません。
- Legacy SSE の過負荷。 サーバーは、未処理のレガシー SSE リクエスト数を制限します。 HTTP
429では、Retry-Afterに従い、未処理の呼び出しを減らします。 この受付制限は、Streamable HTTP には適用されません。
AI ツール
これらのアクションを使用して、シェル MCP 構成を計画します。
ドキュメントのみの取得には、Microsoft Learn MCP サーバーを使用し、Shell MCP サーバーは使用しません。 コンパクト ガイド インデックスの場合は、 Shell ドキュメント インデックス (llms.txt) を使用します。 インデックスによってクローラーのアクセス許可が変更されたり、取得が保証されたりすることはありません。
シェル MCP には個別のセットアップが必要であり、構成されたアクセス許可でデータを読み取ったり変更したりできるため、承認する前にツールの呼び出しを確認してください。 資格情報や機密データを共有しないでください。
AI エージェントを接続する
この記事の Shell MCP の構成手順に従ってください。Markdown として読み取る
アシスタントに貼り付けるためにテキスト バージョンを開きます。ChatGPT に質問する
構成、認証、およびツールのアクセス許可を計画します。クロードに質問する
プランの構成、認証、およびツールのアクセス許可。
ChatGPT と Claude は、パブリック記事の URL とスターター プロンプトのみを受け取ります。 ここで、サインインを求められる場合があります。 取得に失敗した場合は、Markdown テキストをコピーしてください。 これらのリンクでは、データベース アクセスを構成することはできません。