We’re excited to announce the Azure Cosmos DB MCP Toolkit in public preview. This open-source implementation of the Model Context Protocol (MCP) gives AI agents and LLMs direct, secure access to Azure Cosmos DB. The toolkit bridges intelligent applications and globally distributed databases, enabling AI agents to query, search, and understand data autonomously.

The MCP Toolkit seamlessly integrates with Microsoft Foundry, a platform for building intelligent agents, AI workflows, and deploying AI models at scale. Developers can experiment, orchestrate, and manage AI applications from development to production.

What is the Model Context Protocol (MCP)?

The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect to external data sources and tools. Think of it as a universal adapter that lets AI models “see” and “use” databases, APIs, and services without hard-coded integrations.

• AI agents can discover available data sources
• Models can execute database operations through standardized tools
• Security is enforced at the protocol level
• Context flows seamlessly between your app, the AI model, and your data

Introducing the Azure Cosmos DB MCP Toolkit

The Azure Cosmos DB MCP Toolkit exposes Cosmos DB through MCP and provides 7 essential tools:

• list_databases – Discover all databases in your Cosmos DB account
• list_collections – Explore containers within a database
• get_recent_documents – Retrieve the most recent documents (sorted by timestamp)
• find_document_by_id – Look up specific documents by ID
• text_search – Search documents by property values using CONTAINS
• vector_search – Perform semantic search using vector embeddings
• get_approximate_schema – Sample and infer the schema of a container

Enterprise-Ready Security

• Microsoft Entra ID Authentication (OAuth 2.0)
• Role-Based Access Control (RBAC) with custom app roles
• Managed Identity Support for password-less access
• CORS configuration for secure web applications

Why Use the Azure Cosmos DB MCP Toolkit?

• Accelerate Development: Build AI agents in hours, not weeks, with pre-built MCP tools.
• Highly Elastic: Cosmos DB automatically scales to meet workload demand.
• Serverless at Low Cost: Build PoCs affordably with Azure Cosmos DB Serverless.
• Security with RBAC: Enterprise-grade authentication with Microsoft Entra ID, RBAC, and managed identities.
• Global Scale: Query data anywhere with single-digit millisecond latency.
• Intelligent Search: Vector search enables RAG scenarios for semantic understanding.
• Developer Friendly: Interactive web UI, logging, and integration with LangChain, Semantic Kernel, and other AI frameworks.

Getting Started

Follow the Quick Start Guide → to deploy in minutes.

Real-World Use Cases

1. AI-Powered Customer Support

Scenario: Customer asks “What’s the status of my recent order?”

Agent Action:

• Use find_document_by_id to retrieve order by customer ID
• Analyze order status and shipping information
• Provide personalized response with tracking details

2. Semantic Knowledge Base Search

Scenario: User asks, “What are the troubleshooting steps for a premium subscription quota limit?”

Agent Action:

• Use vector_search to find relevant documentation
• Retrieve top 3 semantically similar articles
• Synthesize answers from multiple sources

3. Data Exploration and Analytics

Scenario: Business analyst asks “Show me the latest user signups”

Agent Action:

• Use list_collections to find user data container
• Use get_recent_documents to sample recent signups
• Use text_search to filter by specific criteria
• Generate insights and visualizations

Key Features

Vector Search for RAG

Build agents that understand context, not just keywords. vector_search automatically generates embeddings and finds semantically similar documents for knowledge bases, recommendation engines, and question-answering systems.

Schema Discovery

get_approximate_schema samples documents and infers schemas automatically to help AI agents understand data without manual documentation.

Microsoft Foundry Integration

The MCP Toolkit integrates with Microsoft Foundry to leverage Azure OpenAI embeddings for semantic search. LLM reasoning combines with Cosmos DB’s global scale and low latency. Steps:

1. Navigate to your Foundry project
2. Go to Build → Create agent
3. Select + Add in the tools section
4. Select Catalog tab
5. Choose Azure Cosmos DB and click Create

Extending the Toolkit

Extend the CosmosDbToolsService class to add custom tools. Submit pull requests via our contribution guidelines.

Learn More

• Explore additional resources: Full Documentation
• Star the Repo → GitHub Repo

Conclusion

The MCP Toolkit eliminates complexity in connecting AI agents to Cosmos DB. Focus on building intelligent applications, not integration code. Ideal for support bots, RAG knowledge bases, and data exploration agents.

About Azure Cosmos DB

Azure Cosmos DB is a fully managed, serverless NoSQL and vector database for modern app development, including AI applications. With SLA-backed speed and dynamic scalability, it supports high-performance distributed computing. To stay in the loop on Azure Cosmos DB updates, follow us on X, YouTube, and LinkedIn.