MCP Toolkit for Azure Cosmos DB Reaches General Availability, Saving You From Integration Hell

Your AI Agent Can Finally Talk to Cosmos DB Without the Homework

Microsoft just announced general availability of the MCP Toolkit for Azure Cosmos DB (v1.1.2), an open-source server that lets AI agents query your production Cosmos DB using natural language. No custom integration scripts. No fragile middleware. No praying that your embedding provider config survives a deployment.

The toolkit exposes eight MCP tools covering the common agent-to-database patterns: list databases, list containers, retrieve documents by ID, run full-text search, run vector search, fetch recent documents, and inspect approximate schema. Under the hood it runs on .NET 9.0, authenticates via Microsoft Entra ID with JWT bearer tokens, and deploys to Azure Container Apps with one-click Bicep templates.

What Changed Since Preview

The toolkit originally shipped in preview at Ignite 2025 with seven tools. The GA release adds three things developers were asking for most:

• Multi-provider embedding support. Vector search is no longer locked to a single provider. You can use Azure AI Services, Azure AI Foundry project endpoints, or native OpenAI. The system detects your endpoint type from the URL pattern. An IEmbeddingClient abstraction means you swap providers without touching agent code (source).
• Improved reliability. Better error handling, health checks, and troubleshooting guides. The GA release explicitly addresses the brittleness that plagued preview deployments when configurations or permissions changed.
• Deeper Microsoft Foundry integration. You can wire Foundry projects to the MCP server in one PowerShell command, then prompt agents with natural language like “find all orders from last week” or “search products containing waterproof” (source).

The toolkit also now supports multi-resource group deployments for enterprise scenarios where Cosmos DB, ACR, and Container Apps live in separate resource groups. Automated RBAC role assignment handles the cross-resource-group permissions, or the scripts give you step-by-step instructions if you lack the rights to auto-assign.

How to Get Started

Prerequisites: an Azure subscription with Contributor access, Azure CLI, PowerShell 7+, Git, Docker Desktop, and .NET 9.0 SDK (full list). For vector search you also need an Azure OpenAI service with an embedding deployment.

1. Clone the repo: git clone https://github.com/AzureCosmosDB/MCPToolKit.git
2. Deploy infrastructure: Either use the “Deploy to Azure” button or run azd up for the full automation path (source).
3. Run the MCP server: Execute .\scripts\Deploy-Cosmos-MCP-Toolkit.ps1 -ResourceGroup "YOUR-RG" which provisions the Container App, configures Entra ID, and wires up RBAC (source).
4. Validate: Open your Container App URL in a browser, sign in with Entra ID, and use the built-in test UI to invoke tools without writing code (source).
5. Connect your agent: For Foundry, run Setup-AIFoundry-RoleAssignment.ps1 then add the MCP endpoint as a custom tool in Foundry. For VS Code / GitHub Copilot, add the server URL to your mcp.servers config in settings.json (source).

Configuration is three environment variables: Cosmos DB endpoint, embedding endpoint, and API key. The toolkit auto-detects whether you pointed it at Azure Cognitive Services, a Foundry project, or OpenAI directly (source).

Known Pain Points

Only four open issues on the GitHub repo at time of writing, but a few are worth flagging if you are planning a deployment:

• Emulator support is still missing. You cannot run the toolkit locally against the Azure Cosmos DB emulator (GitHub issue #92). Local development requires a cloud Cosmos DB instance, which means real RU consumption during testing.
• Authentication defaults are not optional yet. The minimum deployment contract still requires Entra ID and embedding configuration even if you only need the read-only list and search tools. There is an open feature request to make auth and embedding settings optional for simpler deployments (GitHub issue #138).
• Observability is a work in progress. There is no OpenTelemetry support yet. An open issue requests OTLP traces, metrics, and logs for hosted MCP integrations (GitHub issue #137).
• Toolkit is read-only by design. The MCP server exposes query and search operations only. You cannot write, update, or delete documents through it. If your agent needs to mutate data, you still need the Cosmos DB SDK directly (source).

What This Means

This GA release signals that MCP is graduating from “interesting demo” to “production contract” in the Azure ecosystem. The fact that Microsoft shipped multi-resource group RBAC automation, auto-detecting embedding providers, and a one-step PowerShell deployment script tells you they have heard the same feedback the community has been giving since Ignite: connecting LLMs to real data is still too much work. The toolkit does not solve every problem. Emulator support, optional auth, and OpenTelemetry are all on the public backlog. But for teams building RAG systems, support bots, or data exploration agents on top of Cosmos DB, the “write a custom connector for every agent” phase is officially over. You can now treat your database as just another MCP tool your model can call, which is exactly what the protocol promised.