An agent I was pairing with last week wrote a perfectly valid Cosmos DB query. SELECT * FROM c WHERE c.customerId = @id, partition key set to customerId, all the SDK boilerplate correct. It ran. It returned nothing. The container partitioned on /tenantId, and the field the documents actually stored was customer_id, snake-case, because that data had been migrated from a Postgres export three years earlier. The model didn't get anything wrong by its own logic. It was reasoning about a schema it had never been allowed to look at.
That is the recurring failure with coding agents and databases. The model has your code, your tests, sometimes your ADRs — and zero visibility into the one thing that would settle the question: the data itself. It guesses at field names, invents container names, and picks partition keys from vibes. In a schema-free store like Cosmos DB, where two documents in the same container can have entirely different shapes, guessing is close to the worst possible strategy.
The Azure Cosmos DB MCP Toolkit, open-sourced by Microsoft and in public preview since late 2025, is the piece that closes that gap. It is a Model Context Protocol server that gives an agent a narrow, read-only window into a live Cosmos DB account. Not to run your app — to understand it.
Awareness is a read problem, not a write problem
The toolkit exposes seven tools, and the interesting thing is what they collectively refuse to do.
| Tool |
What the agent gets |
list_databases |
Every database in the account |
list_collections |
Containers inside a database |
get_approximate_schema |
Inferred document shape, from sampling |
get_recent_documents |
The 1–20 most recent documents |
find_document_by_id |
A single record by id |
text_search |
Keyword search over document properties |
vector_search |
Semantic search over stored embeddings |
Discovery, inspection, retrieval. There is no create, no update, no delete, no arbitrary write of any kind. The Microsoft Learn reference is blunt about it: the toolkit "provides query and search capabilities only." That constraint is the whole design, not a preview limitation someone forgot to remove.
I've come to think this is the correct default for any database MCP server, and I say that as someone who ships one. An agent that can read your schema makes your next query correct. An agent that can write your database makes your next incident. The blast radius of a hallucinated DELETE is unbounded; the blast radius of a hallucinated SELECT is a wasted request unit or two. Give the model awareness and keep the mutations behind a human — or behind explicit, reviewed code — and you get most of the value with almost none of the risk.
The tool I reach for most is get_approximate_schema. Because Cosmos is schema-on-read, there is no catalog to query; the toolkit samples real documents and infers the structure. That is exactly the information my query-writing agent was missing. Handed the actual shape, customer_id and /tenantId stop being guesses.
What it takes to wire in
The toolkit is a .NET 9 service that deploys to Azure Container Apps — one-click via the portal button, azd up, or a PowerShell script. It does not hand out connection strings or shared keys. Every request carries a Microsoft Entra ID JWT, the server validates the token's audience and role membership, and the Container App reaches Cosmos DB through its own managed identity. No stored credentials anywhere in the path.
Access is gated by two role assignments worth knowing by name: callers need the Mcp.Tool.Executor app role to invoke tools at all, and the server's managed identity holds Cosmos DB Data Reader — a data-plane read role, not an account-management one. The identity literally cannot mutate data, so even a compromised agent prompt has nothing to escalate to.
Pointing a client at it is a few lines. For GitHub Copilot or any VS Code MCP client, the server URL goes into settings.json:
{
"mcp.servers": {
"cosmosdb": {
"url": "https://YOUR-CONTAINER-APP.azurecontainerapps.io/mcp",
"headers": {
"Authorization": "Bearer YOUR-JWT-TOKEN"
}
}
}
}
One gotcha that bites everyone once: those Entra tokens expire after roughly an hour. Refresh with az account get-access-token --resource YOUR-ENTRA-APP-CLIENT-ID and drop the new value back in. If your agent suddenly starts claiming the database is unreachable, check the clock before you check anything else.
Vector search has its own prerequisites — an Azure OpenAI embedding deployment, embeddings actually stored in your documents, and a vector index policy on the container. If you haven't set that up, the other six tools work regardless; vector_search is the only one that leans on it.
Rules are the other half of awareness
Live schema tells an agent what your data is. It says nothing about what your data should be — and that is where agents quietly make expensive mistakes, like choosing a low-cardinality partition key that turns into a hot partition at scale.
The companion Azure Cosmos DB plugin for Cursor pairs the same MCP connection with ten curated rule sets — partition key design, data modeling, query optimization, indexing, throughput and scaling, global distribution, monitoring, and vector search among them. The rules are static, encoded expertise; the MCP server is the live view. An agent with both stops proposing a partition key in the abstract and starts proposing one against your real cardinality.
Static rules keep the agent from designing a hot partition. Live schema keeps it from querying a field that doesn't exist. You want both wired in, because they fail in different directions.
The takeaway
If you are giving a coding agent anything to do with a database, split the grant deliberately: read to the agent, writes to a human. The Cosmos DB MCP Toolkit is a working template for the read half — seven inspection-only tools, identity-scoped through Entra ID, backed by a managed identity that holds nothing stronger than Data Reader. Stand it up, point Copilot or Cursor at the /mcp endpoint, and let the model call get_approximate_schema before it writes a single query. The queries it writes afterward are against your actual data instead of its best guess — and that one change is the difference between an agent that looks helpful in a demo and one that is correct in your repo.
Sources: Introducing the Azure Cosmos DB MCP Toolkit (Azure Cosmos DB Blog), Model Context Protocol (MCP) Toolkit — Microsoft Learn, Introducing the Azure Cosmos DB Plugin for Cursor, AzureCosmosDB/MCPToolKit on GitHub