Azure DocumentDB MCP Toolkit: Agentic AI for MongoDB-Compatible Workloads

Developers are moving quickly to build AI-powered experiences, but there is a gap between what an agent can say and what it can actually do. To be useful, an agent needs secure access to live systems, real data, and the same operational context developers already rely on. That is why we are pleased to announce the Azure DocumentDB MCP Toolkit in public preview. It is an open-source implementation of the Model Context Protocol (MCP) that gives AI agents and LLMs direct, secure access to Azure DocumentDB, the fully managed Azure service built on the open-source DocumentDB project. Instead of guessing from training material, agents can query collections, inspect indexes, run aggregations, and reason over what is actually in your database. 

The toolkit pairs with the DocumentDB Agent Kit, a bundle of agent skills that carries DocumentDB design guidance into the workflow. Together, they help developers spend less time wiring up custom integrations and more time building agents that can work against MongoDB-compatible workloads with real context and better guardrails. 

What is the Model Context Protocol (MCP)? 

MCP is an open standard that lets AI applications connect to external data sources and tools through a single, well-defined contract. For developers, that matters because it replaces one-off integrations with a consistent way to give models access to the systems where real work happens. Think of it as a universal adapter so AI models can read from databases, APIs, and services without bespoke integrations: 

• AI agents can discover available data sources. 

• Models execute database operations through standardized tools. 

• Security is enforced at the protocol level. 

• Context flows between the application, the model, and the database. 

Introducing the Azure DocumentDB MCP Toolkit 

The Azure DocumentDB MCP Toolkit exposes DocumentDB through MCP and ships with tools grouped by capability tier. That means developers can start with a read-safe posture for exploration, debugging, and analysis, then opt into writes or DDL only when the workflow calls for it. Reads are on by default; writes and DDL are gated behind explicit environment flags. 

Index 

• list_indexes (read), create_index (management), drop_index (management). 

Database and collection 

• list_databases, sample_documents, get_statistics (read). 

• drop_database, drop_collection, rename_collection, current_ops (management). 

Document and query 

• find_documents, count_documents, aggregate, explain_operation (read). 

• insert_documents, update_documents, delete_documents, find_and_modify (write). 

Vector search (cosmosSearch with DiskANN, HNSW, IVF) and full-text search (BM25 via $search over createSearchIndexes) run through aggregate. For developers, that keeps the experience familiar: the same pipeline you would write by hand is the pipeline the agent submits. You do not need a separate mental model just because an agent is involved. 

Enterprise-Ready Security 

For developers and platform teams, security is part of the adoption story. If an agent can reach production data, the controls around that access need to be explicit, reviewable, and easy to reason about. The toolkit is designed with that reality in mind. 

• Connection profiles, not chat strings. Profiles are defined by the administrator at deployment time. The tools never accept a runtime connection string from the agent. 

• Microsoft Entra ID via authMode=entra so backend access uses Azure Identity (Entra OIDC) instead of database secrets. 

• Capability gates. ENABLE_WRITE_TOOLS=true for writes; ENABLE_MANAGEMENT_TOOLS=true for DDL. $out and $merge in aggregations are disabled unless explicitly enabled. 

• Allow lists on host names so a profile cannot be redirected to an unintended cluster. 

• SCRAM-SHA-256 for local and non-Entra setups. 

Why Use the Azure DocumentDB MCP Toolkit? 

The value of the toolkit is not just that it exposes database operations to an agent. It is that it helps developers move from experimentation to production-minded workflows faster, while staying grounded in the tools, query patterns, and controls they already know. 

• Accelerate development. Ship agent features in hours, not weeks, with a curated tool surface instead of building custom database plumbing from scratch. 

• MongoDB-compatible. Your existing drivers, connection strings, and aggregation pipelines carry forward, so teams can adopt agent workflows without relearning their stack. 

• Honest answers. Tools return the cluster’s real indexes, real explain plans, and real errors, which helps developers debug against reality instead of training-data approximations. 

• Read-safe by default. A production-friendly posture makes it easier to explore, troubleshoot, and validate workflows before expanding permissions. 

• Vector and full-text. RAG and keyword search run through the same aggregate tool, so developers can build richer retrieval experiences without provisioning a separate service. 

• Wide client coverage. Works with Claude Code, Cursor, Codex, Gemini CLI, and GitHub Copilot, which helps teams meet developers where they already work. 

Getting Started 

You can run the server with npx directly from GitHub, which makes it easy to try the toolkit in an existing local workflow without a global install. 

npx -y github:microsoft/documentdb-mcp 

Most MCP clients want the command as part of their configuration. Add a block like this to the client’s MCP settings file. Claude Code, Cursor, Codex, Gemini CLI, and GitHub Copilot all use the same shape, which keeps setup simple across the tools many developers already use. 

{ 
  "mcpServers": { 
    "DocumentDB": { 
      "command": "npx", 
      "args": ["-y", "github:microsoft/documentdb-mcp"], 
      "env": { 
        "TRANSPORT": "stdio", 
        "TRUST_LOCAL_STDIO": "true", 
        "CONNECTION_PROFILES": "{\"local\":{\"authMode\":\"connectionString\",\"uri\":\"mongodb://localhost:27017\"}}" 
      } 
    } 
  } 
} 

 Tool calls then pass connection_profile: “local” (or whatever profile name you defined). To enable writes or DDL, also set ENABLE_WRITE_TOOLS=true or ENABLE_MANAGEMENT_TOOLS=true in the env block. That default matters: developers can start by inspecting and understanding a system before deciding whether an agent should be allowed to change it. 

Fully quit and reopen the client. MCP config is read only at process start. 

Real-World Use Cases 

The most useful way to think about the toolkit is not as a list of commands, but as a way to shorten common developer loops. Instead of switching between dashboards, shells, and ad hoc scripts, developers can let an agent inspect the database, surface evidence, and help decide on the next action. 

Query and index review 

Scenario: A developer is trying to understand why an /orders listing is slow at p99 and needs something more useful than a generic tuning suggestion. 

Agent actions: 

• list_indexes on the collection. 

• explain_operation on the suspect query. 

• Recommend an ESR-shaped compound index, then create_index (if writes are enabled) and re-explain. 

The result is a faster troubleshooting loop grounded in the actual query plan and index state, not guesswork. 

RAG over a product catalog 

Scenario: A team is building a product assistant that needs to find similar items and answer questions based on what is actually available, not just what sounds plausible. 

Agent actions: 

• aggregate with a $search.cosmosSearch stage (vector, path, k, filter) for the semantic recall step. 

• find_documents to enrich the top-k with stock and region. 

That gives developers a practical path to retrieval-based experiences over operational data while keeping the logic close to the database they already manage. 

Operational triage 

Scenario: An engineer or operator needs to understand what the cluster is doing right now and where to look first, without manually stitching together multiple views. 

Agent actions: 

• current_ops for in-flight operations. 

• get_statistics for database, collection, and index sizes. 

• sample_documents to spot-check the largest collection’s shape. 

For operations work, that means less time gathering context and more time acting on it. 

Extending the Toolkit 

The server is open source, which gives developers room to adapt it to their own workflows. Add a tool by extending the tool registry in microsoft/documentdb-mcp and opening a pull request. Skills are plain Markdown; contribute new rules or skills to Azure/documentdb-agent-kit. That makes the toolkit something teams can shape over time instead of treating as a fixed black box. 

Learn More 

• DocumentDB MCP server: github.com/microsoft/documentdb-mcp 

• DocumentDB Agent Kit: github.com/Azure/documentdb-agent-kit 

• Azure DocumentDB docs: learn.microsoft.com/azure/documentdb 

Conclusion 

The Azure DocumentDB MCP Toolkit helps close the gap between AI agents and the systems developers actually run. Instead of building custom integration layers, teams can give agents a secure, structured way to inspect data, understand schema and performance signals, and participate in real workflows against Azure DocumentDB. The result is faster experimentation, more grounded answers, and a clearer path from prototype to production for support agents, RAG over operational data, and ad hoc database exploration. 

About Azure DocumentDB 

Azure DocumentDB is a fully managed document database service for building and modernizing MongoDB-compatible applications. Powered by the open-source DocumentDB engine, it combines familiar APIs, tools, and workflows with Azure’s security, scalability, and operational simplicity. Whether you’re developing new applications or migrating existing MongoDB workloads, Azure DocumentDB helps you get started quickly and scale with confidence.