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/[email protected] 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）の仕組みの解説を参照してください。
| 比較項目 | 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のコマンド一覧、MCP Toolkit v1.1.2のツール実装とデプロイスクリプト、Microsoft Learnのデータプレーンのセキュリティ解説で確認できます。
検索・参照だけで要件を満たせるなら、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選定とベクトル検索の記事で扱っています。
ローカル接続手順：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 <cosmos-account> \
--resource-group <resource-group> \
--role-definition-id 00000000-0000-0000-0000-000000000001 \
--principal-id $PRINCIPAL_ID \
--scope "/dbs/<database>/colls/<container>"--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/[email protected]",
"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/[email protected] 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 <RG>を実行し、コンテナーイメージのビルドと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 <ENTRA_APP_CLIENT_ID>で取得したトークンを、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/<db>/colls/<container>単位で付け直してください。そのうえで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の全ツールと権限設計、Terraformの場合はTerraform MCP Serverのtoolset権限設計が参考になります。
接続エラーの切り分け：403・401・検索結果が空の場合
- Azure MCP Serverで403（Forbidden）：権限とネットワークの両方を確認します。権限は
az cosmosdb sql role assignment list --account-name <account> --resource-group <RG>で、自分のプリンシパル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エミュレーターには接続できません。アカウントをAzure Resource Manager経由でサブスクリプションから探し、接続先をhttps://<account>.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の仕組みと採用判断の記事で整理しています。
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の機能と接続方法を参照してください。
