--- title: "Azure Cosmos DB MCPサーバーの使い方｜Azure MCP ServerとMCP Toolkitの接続・権限設計" url: "https://www.issoh.co.jp/tech/details/6258/" published: 2025-04-11 updated: 2026-09-27 categories: ["Azure"] publisher: "株式会社一創" --- # Azure Cosmos DB MCPサーバーの使い方｜Azure MCP ServerとMCP Toolkitの接続・権限設計 Azure Cosmos DBをAIエージェントから自然言語で検索したい場合、MCP（Model Context Protocol）サーバーを自分でゼロから書く必要はありません。この記事では、Microsoftが公開している実装のうち、Azure全体を扱う**Azure MCP Server**に含まれるcosmosツールと、Cosmos DB専用の**Azure Cosmos DB MCP Toolkit**の2つを比較します。両者の違いと選び方、VS CodeやClaude Desktopからの接続手順、見落とされやすいデータプレーンRBACの設定までを、各リポジトリのソースコードと公式ドキュメント（2026-09-27時点）に基づいて解説します。 ## まとめ：Azure MCP ServerとMCP Toolkitの選び分けと権限の要点 - **手元のエディタから試すならAzure MCP Server**。`npx -y @azure/mcp@2.0.5 server start`で起動でき、cosmosツールは7種です（2.0.5時点）。認証は資格情報チェーンで行い、`az login`の資格情報もその候補の1つです。 - **チームで共有するなら、利用者ごとの権限で読むか、共有IDで読むかで選びます**。Azure MCP Server 2.0はリモート（HTTP）でも動き、既定のOn-Behalf-Ofで利用者本人の権限を引き継ぎます。MCP ToolkitはContainer AppsのマネージドIDという共有IDで読み、Microsoft Foundryのカタログから選べます。 - **どちらも書き込み用のツールは持っていません**。作成・更新・削除をエージェントにさせたい場合は自作が必要です。 - **権限はデータプレーンRBACで付与します**。Azure Portalの「アクセス制御（IAM）」で付けるReader等では、ドキュメントを読めません。 - **`@azure/mcp@latest`はベータ版を取得します**。npmのlatestタグは3.0.0-beta.47を指しているため、安定版を使うなら版番号を固定します。 以下では、選び方、ツールの中身、接続手順、権限設計、よくあるエラーの順に説明します。 ## Cosmos DB用MCPサーバーの2系統と選び方 「Cosmos DB MCP」で検索すると、GitHub上に個人の実装も多数見つかります。Microsoft Learnには、Azure Cosmos DB ShellのMCPサーバー機能（手元のShellとVS Code拡張で動かす方式）も載っています。この記事で比較するのは、Azure上のアカウントにエージェントを直接つなぐ次の2つです。Azure MCP Serverは2.0の安定版が2026-04-10に発表されました。MCP Toolkitは2025-11-18にパブリックプレビューとして公開され、2026-06-02（Microsoft Build 2026）に一般提供（GA）になっています。MCP自体の仕組みについては[MCP（Model Context Protocol）の仕組みの解説](/tech/details/5736/)を参照してください。 | 比較項目 | Azure MCP Server（cosmosツール） | Azure Cosmos DB MCP Toolkit | | ----------------- | --------------------------- | --------------------------- | | リポジトリ | microsoft/mcp | AzureCosmosDB/MCPToolKit | | 安定版（2026-09-27時点） | 2.0.5（2026-07-10） | v1.1.2（2026-05-29） | | 実行場所 | ローカル（stdio）／リモート（HTTP） | Azure Container Apps（HTTP） | | 実装言語 | .NET（npm・PyPI・NuGetで配布） | .NET 9.0 | | Cosmos DBへの認証 | 資格情報チェーン／OBO／ホストのID | マネージドID | | クライアント側の認証 | ローカルは不要／リモートはEntra ID | Entra IDのJWT | | Cosmos DB用ツール数 | 7 | 8 | | 書き込み用ツール | なし | なし | | ライセンス | MIT | MIT | 判断の分かれ目は、誰の権限でデータを読むかです。ローカルのAzure MCP Serverは、資格情報チェーンで最初に見つかったIDの権限で動きます。`az login`だけを済ませた環境なら本人のIDですが、`AZURE_CLIENT_ID`などの環境変数が設定されていれば、そちらのサービスプリンシパルが優先されます。リモートで動かす場合は、`--outgoing-auth-strategy`の既定値`UseOnBehalfOf`により、利用者のトークンを交換して本人の権限でCosmos DBを読みます。Cosmos DBへのアクセスも利用者本人のIDで行われるため、診断設定でリソースログを収集しておけば、利用者単位で追跡できます。 一方のMCP Toolkitは、サーバーに割り当てたマネージドIDの権限で動きます。Toolkitを呼び出せる人は全員、マネージドIDと同じ範囲のデータを読めることになります。利用者ごとにアクセス範囲を変えたいならAzure MCP ServerのOBO構成を選びます。全員に同じ範囲を見せてよく、ハイブリッド検索を含むCosmos DB専用のツールをFoundryから手早く使いたいならToolkitが向いています。 本文で扱う版固有の仕様は、Azure MCP Server 2.0.5の[コマンド一覧](https://github.com/microsoft/mcp/blob/Azure.Mcp.Server-2.0.5/servers/Azure.Mcp.Server/docs/azmcp-commands.md)、MCP Toolkit v1.1.2の[ツール実装](https://github.com/AzureCosmosDB/MCPToolKit/blob/v1.1.2/src/AzureCosmosDB.MCP.Toolkit/Services/CosmosDbToolsService.cs)と[デプロイスクリプト](https://github.com/AzureCosmosDB/MCPToolKit/blob/v1.1.2/scripts/Deploy-Cosmos-MCP-Toolkit.ps1)、Microsoft Learnの[データプレーンのセキュリティ解説](https://learn.microsoft.com/en-us/azure/cosmos-db/reference-data-plane-security)で確認できます。 検索・参照だけで要件を満たせるなら、VMを立てて自作のMCPサーバーを動かし、.envに接続文字列を書くような構成を選ぶ必要はありません。どちらの公式実装も、キーを設定ファイルに置かずにEntra IDで接続できます。 ## Azure MCP ServerのCosmos DBツール7種と制約 Azure MCP Server 2.0.5のコマンド一覧（`azmcp-commands.md`）には、Cosmos DB関連のコマンドが7つあります。すべてに「ReadOnly」「Destructiveではない」という注記が付いています。このうち5つ（schema infer以下）は、3.0.0-beta.14（2026-05-28）で追加されたものです。 | コマンド | できること | | ---------------------------------------------- | --------------------- | | `cosmos list` | アカウント・DB・コンテナーの一覧 | | `cosmos database container item query` | SELECT文でアイテムを検索 | | `cosmos database container schema infer` | サンプルからスキーマを推定 | | `cosmos database container item list-recent` | 更新が新しい順に取得 | | `cosmos database container item get` | idで1件取得 | | `cosmos database container item text-search` | FullTextContainsで全文検索 | | `cosmos database container item vector-search` | VectorDistanceでベクトル検索 | `item query`には任意のSQLを渡せますが、ソースの`CosmosQueryValidator`がSELECT以外を拒否します。具体的には、SELECTで始まらない文、`--`や`/*`を含むコメント、セミコロンで連結した複数文、`OR 1=1`型のトートロジーを弾き、`exec`・`sproc`・`trigger`等の語も通しません。クエリ長の上限は5,000文字です。LLMが書いたクエリをそのまま渡しても、ストアドプロシージャの呼び出しにはならない作りになっています。 残りのツールには前提条件や注意点があります。`text-search`について、Azure MCP Serverのコマンド一覧は全文インデックスを要件としています。一方、Cosmos DBのドキュメントによると、全文ポリシーやインデックスがなくても全文検索クエリ自体は実行できます。ただしインデックスを使わないため、RU消費が増え、実行時間も長くなります。実運用では全文インデックスを設定しておくべきです。`vector-search`はベクトルインデックスに加えて、`--openai-endpoint`と`--embedding-deployment`でAzure OpenAIの埋め込みモデルを指定する必要があります。`schema infer`が返すのはトップレベルのプロパティだけで、入れ子の中身は`object`や`array`としか表示されません。ベクトル検索の仕組みやインデックス設定は[Cosmos DB for NoSQLのAPI選定とベクトル検索の記事](/tech/details/4678/)で扱っています。 ## ローカル接続手順：VS Code・Claude Desktop・Claude Code ### 前準備：az loginとデータプレーンのロール付与 Azure MCP Serverは、資格情報を次の順に探します。環境変数（EnvironmentCredential）、Visual Studio、VS Code、Azure CLI、Azure PowerShell、Azure Developer CLI、最後にブラウザでの対話ログインです。最初に成功したものが使われます。npxで起動する場合はNode.jsも必要です。READMEには「20 LTS以降」と書かれていますが、Node.js 20はすでにサポートが終了しているため、現行のLTS（2026年9月時点ではNode.js 24）を使ってください。`az login`はこのチェーンにIDを渡すための操作で、Cosmos DBの権限そのものは次に説明するロールで別途付与します。探索順を固定したい場合は、`AZURE_TOKEN_CREDENTIALS=AzureCliCredential`のように環境変数で指定します。 ここで最もつまずきやすいのがロールの付与です。Cosmos DBのドキュメントを読むには、Azure RBACのReaderやContributorとは別の、**データプレーン用の組み込みロール**が必要です。読み取りだけなら「Cosmos DB Built-in Data Reader」（ロールID `00000000-0000-0000-0000-000000000001`）を、サインインしているユーザーに付与します。 ``` PRINCIPAL_ID=$(az ad signed-in-user show --query id -o tsv) az cosmosdb sql role assignment create \ --account-name \ --resource-group \ --role-definition-id 00000000-0000-0000-0000-000000000001 \ --principal-id $PRINCIPAL_ID \ --scope "/dbs//colls/" ``` `--scope`に`/`を指定するとアカウント全体が対象になります。エージェントに見せてよいコンテナーが決まっているなら、上の例のようにコンテナー単位まで絞ってください。なお、このコマンドを実行する人には、データを読む権限とは別に、管理プレーンでロール割り当てを作成する権限（`Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write`。アカウントのOwnerなどが持つ）が必要です。 ### VS Codeのmcp.jsonとcosmosツールだけを公開する起動オプション 公式READMEの設定例は`@azure/mcp@latest`を指定しています。しかし2026-09-27時点で、npmのlatestタグは**3.0.0-beta.47**を指しています。この例をそのまま使うと、ベータ版が毎回取得されます。安定版を使うなら、次の例のように版番号を固定してください。 ``` { "servers": { "azure-mcp-server": { "type": "stdio", "command": "npx", "args": [ "-y", "@azure/mcp@2.0.5", "server", "start", "--namespace", "cosmos", "--read-only" ], "env": { "AZURE_MCP_COLLECT_TELEMETRY": "false" } } } } ``` これはワークスペースの`.vscode/mcp.json`に置く例です。`--namespace cosmos`を付けないと、Storage・Key Vault・Monitorなど他のサービスのツールもエージェントに公開されます。既定の起動モードはnamespaceモードで、サービスごとに1つのツールへまとめて公開する方式です。VS Codeでは1回のチャット要求で有効にできるツールが最大128個なので、それを超えないようにこの方式が既定になっています。`--read-only`はサーバー全体で書き込み系ツールを無効にするオプションです。cosmosツールはもともと読み取り専用ですが、ほかのnamespaceを追加したときの安全策として付けておきます。テレメトリは既定でMicrosoftに送信されます。`AZURE_MCP_COLLECT_TELEMETRY=false`で送信を止められます。 ### Claude DesktopとClaude Codeへの登録 Claude Desktopでは、リリースページで配布されている`.mcpb`ファイル（例：`Azure.Mcp.Server-osx-arm64.mcpb`）をアプリのウィンドウにドラッグするとインストールできます。Node.jsや.NETを別途用意する必要はありません。起動オプションを指定したい場合は、設定ファイル`claude_desktop_config.json`の`mcpServers`に上と同じ`command`・`args`を書きます。設定ファイルの場所は、macOSでは`~/Library/Application Support/Claude/`、Windowsでは`%APPDATA%\Claude\`です。Azure MCP ServerのREADMEの一覧表にはmacOSの場所が`~/.claude/`と書かれていますが、Claude Desktop側の案内とは一致しません。 Claude Codeでは、公式プラグインマーケットプレイスの`/plugin install azure@claude-plugins-official`でAzure MCP Serverを導入できます。cosmosツールだけに絞りたい場合は、`claude mcp add`でnpxの起動コマンドを直接登録します。 ``` claude mcp add azure-cosmos -- npx -y @azure/mcp@2.0.5 server start --namespace cosmos --read-only ``` 登録できたら、「myaccountアカウントのshopdbデータベースにあるordersコンテナーのスキーマを推定して」のように、アカウント・データベース・コンテナーを特定できる形で話しかけてみます。動作確認では、エージェントの返答文ではなく、ツール呼び出しの履歴を見てください。cosmosのツールが実行され、推定したスキーマ（プロパティ名と型）が結果に返っていれば接続は成功しています。Claude Codeでは`/mcp`で接続状態も確認できます。 ## MCP ToolkitのContainer AppsデプロイとFoundry接続 ### MCP Toolkitのデプロイ手順と提供ツール8種 MCP Toolkitのデプロイは2段階です。まず「Deploy to Azure」ボタンか`azd up`で、インフラ一式（Container Apps環境、Container Registry、マネージドIDとロール割り当て）を作成します。次にPowerShell 7以降で`.\scripts\Deploy-Cosmos-MCP-Toolkit.ps1 -ResourceGroup `を実行し、コンテナーイメージのビルドとEntra IDアプリの登録を行います。前提として、Azure CLI、Docker Desktop、.NET 9.0 SDKが必要です。ベクトル検索を使う場合は、埋め込みモデル（Azure AI Services、Microsoft Foundry、OpenAI APIのいずれか）も用意します。 公開されるツールは`list_databases`、`list_collections`、`get_approximate_schema`、`get_recent_documents`、`find_document_by_id`、`text_search`、`vector_search`、`hybrid_search`の8種です。`hybrid_search`はv1.1.2で追加され、ベクトル類似度と全文検索の結果をRRF（Reciprocal Rank Fusion）で統合します。ソースを見ると、`get_recent_documents`と`text_search`の取得件数は1〜20件の範囲外だとエラーになります。`get_approximate_schema`は先頭10件だけを見てスキーマを推定します。 ### VS CodeやFoundryからの接続とトークンの期限 Microsoft Foundryから使う場合は、先に`.\scripts\Setup-AIFoundry-Connection.ps1`を実行します（`-AIFoundryProjectResourceId`、または`-AIFoundryProjectName`と`-AIFoundryAccountName`を指定）。このスクリプトが、FoundryのプロジェクトからMCPサーバーを呼び出すためのロールを割り当てます。Microsoft LearnのToolkitページには`Setup-AIFoundry-RoleAssignment.ps1`という名前が載っていますが、v1.1.2のリポジトリにあるのは`Setup-AIFoundry-Connection.ps1`です。そのうえで、エージェントのツール追加画面で「Catalog」から「Azure Cosmos DB」を選びます。認証方式にはMicrosoft Entraの「Project Managed Identity」を選び、audienceにはデプロイ時に出力された`ENTRA_APP_CLIENT_ID`を入力します。VS CodeなどのMCPクライアントから使う場合は、`az account get-access-token --resource `で取得したトークンを、`Authorization: Bearer <トークン>`というヘッダーに設定します。接続先はContainer AppのURLそのものではなく、末尾に`/mcp`を付けた`https://<アプリ名>.<環境>.<リージョン>.azurecontainerapps.io/mcp`です。READMEにあるとおり、このトークンは通常1時間で期限が切れます。長時間使い続ける場合は、定期的にトークンを取り直す運用が必要です。 利用者に割り当てるアプリロールは`Mcp.Tool.Executor`です。デプロイスクリプトは実行者自身への割り当てを試みます。ただし、Microsoft Graphの`AppRoleAssignment.ReadWrite.All`権限がないと割り当てに失敗します。その場合は`Assign-Role-To-Current-User.ps1`を実行するか、Enterprise Applicationsの画面から手動で割り当てます。 ## 権限設計：読み取り専用の範囲指定と書き込みサーバーの分離 MCP ToolkitのREADMEは、「What You Get」の節で「Full CRUD operations」と説明しています。しかし、v1.1.2のツール実装（`CosmosDbToolsService.cs`）にある公開メソッドは上の8つだけで、作成・更新・削除のメソッドは存在しません。デプロイスクリプトがマネージドIDに付与するロールも「Cosmos DB Built-in Data Reader」だけです。同じREADMEのSecurity節には、付与後はアカウント内のすべてのデータベースとコンテナーを読めるようになる、と注意書きがあります。READMEの売り文句を読んで、エージェントにデータを書き込ませる設計を立てないようにしてください。 問題になりやすいのは、この読み取り権限がアカウント全体に付く点です。スクリプトはロールをスコープ`/`（アカウント全体）に割り当てています。個人情報を含むコンテナーが同じアカウントにある場合は、デプロイ後にその割り当てを削除し、`/dbs//colls/`単位で付け直してください。そのうえでEntra IDのアプリロール（`Mcp.Tool.Executor`）で利用者を限定します。この2段構えにしないと、エージェントに話しかけられる人は全員、アカウント内の全データを読めることになります。 Azure MCP Serverにも同じ種類の落とし穴があります。`--auth-method key`を指定すると、サーバーはAzure Resource Manager経由でプライマリキーを取得して接続します（`CosmosService.cs`の`GetKeysAsync`）。アカウントキーは書き込みも含めた全権限を持つため、読み取り専用のツールを使っていても、手元のプロセスは全権限の資格情報を保持することになります。既定の`credential`のまま使い、データプレーンRBACで権限を絞るのが安全です。アカウントのローカル認証を無効（`disableLocalAuth`）にしている環境では、そもそもキー認証は使えません。 エージェントにデータを書き込ませたい場合は、公式実装に書き込みツールを足すのではなく、書き込み専用のMCPサーバーを別に作ることをおすすめします。そのサーバーには、書き込み先のコンテナーに限定した「Cosmos DB Built-in Data Contributor」（ロールID `00000000-0000-0000-0000-000000000002`）を付けます。土台には、Microsoftのサンプル集`AzureCosmosDB/azure-cosmos-mcp-server-samples`が使えます。JavaScript・Go・Java・Pythonの4言語の実装があり、たとえばJava版はPut Item（挿入または置換）とUpdate Item（部分更新）を持っています。ただしこれはサンプル集で、リポジトリの最終コミットは2025-11-25です。JavaScript版は`COSMOSDB_KEY`によるキー認証を前提にしているため、Entra IDの認証に書き換えてから使ってください。読み取りと書き込みを別のサーバーに分けておけば、エージェントに与える権限をサーバーの単位で切り替えられます。AWS側の同種の設計は[AWS MCP Serverの全ツールと権限設計](/tech/details/17726/)、Terraformの場合は[Terraform MCP Serverのtoolset権限設計](/tech/details/16551/)が参考になります。 ## 接続エラーの切り分け：403・401・検索結果が空の場合 - **Azure MCP Serverで403（Forbidden）**：権限とネットワークの両方を確認します。権限は`az cosmosdb sql role assignment list --account-name --resource-group `で、自分のプリンシパルIDとスコープを見ます。IAMでOwnerになっていても、データプレーンのロールがなければ読めません。ネットワークは、IPファイアウォールで手元のIPが許可されているか、プライベートエンドポイント構成でDNSがプライベートIPに解決されているかを確認します。 - **MCP Toolkitで401**：トークンの期限切れ、audienceの不一致、`Mcp.Tool.Executor`が未割り当て、のいずれかが原因です。READMEのトラブルシューティングもこの3つを挙げています。 - **text-searchが空になる、またはエラーになる**：まずエラー本文と、指定したプロパティ名（大文字小文字を含む）を確認します。照合は部分文字列ではなく単語単位で、全文ポリシーの言語設定に従って語幹処理がかかります。ストップワードの除外は現時点では英語（en-US）だけの機能で、「the」のような語では一致しません。 - **アカウントが見つからない**：Azure MCP Serverの`cosmos list`はサブスクリプション単位で探索します。`--resource-group`を指定すれば、探索範囲をリソースグループに絞れます。複数のテナントに所属している場合は`--tenant`も指定します。 なお、Azure MCP Serverは手元の[Azure Cosmos DBエミュレーター](/tech/details/6259/)には接続できません。アカウントをAzure Resource Manager経由でサブスクリプションから探し、接続先を`https://.documents.azure.com:443/`の形で組み立てる実装だからです（`CosmosService.cs`の`GetCosmosBaseUri`）。動作を試す場合も、Azure上に検証用のアカウントを用意してください。 ## よくある質問 ### Azure Cosmos DB MCPサーバーは無料で使えますか？ Azure MCP ServerとMCP Toolkitは、どちらもMITライセンスのOSSです。ソフトウェア自体は無料で使えます。ただし、ツールが実行するクエリにはCosmos DBのRU（要求ユニット）が消費されます。MCP ToolkitではContainer AppsとContainer Registryの料金もかかります。 ### Cosmos DB MCPサーバーでデータの登録や更新はできますか？ 2026年9月時点では、Azure MCP ServerにもMCP Toolkitにも書き込み用のツールはありません。Azure MCP Serverの`item query`もSELECT以外を拒否します。書き込みが必要な場合は、Microsoftのサンプル集（azure-cosmos-mcp-server-samples）を土台にして、書き込み先を限定したロールを持つMCPサーバーを別に用意してください。 ### MongoDB用APIのCosmos DBでも使えますか？ 両実装のツールは、NoSQL用APIのSQLクエリ（SELECT文、FullTextContains、VectorDistance）を前提に作られています。MongoDB用API（RUベース）やAzure DocumentDB（旧vCore）のデータは、この2つの実装の対象外と考えてください。Cosmos DBのAPI種別の違いは[Azure Cosmos DBの仕組みと採用判断の記事](/tech/details/15525/)で整理しています。 ### Claude DesktopとVS Codeで設定ファイルの書き方は違いますか？ 最上位のキー名が異なります。Claude Desktopの`claude_desktop_config.json`は`mcpServers`、VS Codeの`.vscode/mcp.json`は`servers`を使います。`command`と`args`の中身は共通です。 ### Microsoft Learn MCP Serverとは何が違いますか？ Microsoft Learn MCP Serverが検索するのはMicrosoftの公式ドキュメントで、利用者のAzureリソースにはアクセスしません。Cosmos DBのデータそのものを検索したい場合は、この記事で紹介した2つの実装を使います。Learn MCP Serverについては[Microsoft Docs MCP Serverの機能と接続方法](/tech/details/7269/)を参照してください。 ## 関連記事 - [MCP（Model Context Protocol）とは？AIと外部ツールをつなぐ標準規格の仕組みをわかりやすく解説](/tech/details/5736/) - [Azure Cosmos DBとは？マルチモデルNoSQLの仕組み・整合性レベル・RU課金と採用判断を実装者目線で解説](/tech/details/15525/) - [Azure Cosmos DB for NoSQLとは｜API選定・RU料金・整合性・ベクトル検索](/tech/details/4678/) - [Azure Cosmos DB エミュレーターの使い方｜vNextのDocker起動とWindows版の選び方](/tech/details/6259/) - [AWS MCP Serverとは？GA版の接続手順と全ツール・権限設計【2026年版】](/tech/details/17726/) --- 出典: [Azure Cosmos DB MCPサーバーの使い方｜Azure MCP ServerとMCP Toolkitの接続・権限設計]()（株式会社一創）