# Azure Cosmos DB Container MCP for AI Agents MCP

> Azure Cosmos DB Container MCP gives your AI agent secure access to one specific NoSQL database container. It lets you read, write, update, and query structured documents without any risk of accessing other parts of your cloud environment. This is critical for managing chat history, application state, or complex records securely.

## Overview
- **Category:** industry-titans
- **Price:** Free
- **Tags:** nosql, document-database, data-storage, scoped-access, cloud-database, json-storage

## Description

This MCP connects your AI client directly to a single Azure Cosmos DB Container. Think of it like giving your agent a dedicated safe deposit box for all structured data, and nothing else. You get the ability to manage documents—inserting new ones, pulling specific records by ID, updating old entries, or running complex searches across the entire container.

Because access is strictly scoped to this one container, you don't have to worry about your agent accidentally touching critical system databases or listing other resources. It’s a surgical level of control that lets developers store everything from user profile data and chat histories to complex application state in a scalable NoSQL format. When you connect it through Vinkius, your AI client gets instant access to reliable document management without needing heavy backend engineering. This means your agent can handle complex data workflows right out of the box.

## Tools

### create_document
Creates a new document record within the Cosmos DB Container.

### delete_document
Permanently removes an existing document from the container.

### get_document
Retrieves a specific, single document by its unique ID.

### query_documents
Runs a full SQL query against the container to find multiple documents matching complex criteria.

## Prompt Examples

**Prompt:** 
```
Find all user records from Q1 2023 where the status was 'pending review'.
```

**Response:** 
```
**Query Results: Pending Records**

| ID | User Name | Status |
| :--- | :--- | :--- |
| user_456 | Jane Smith | pending review |
| user_789 | Mike Jones | pending review |

*Action:* Found 2 records ready for manual review. You should prioritize the record belonging to Jane Smith.
```

**Prompt:** 
```
I need to save a new chat history session for user ID 'client-101'.
```

**Response:** 
```
**Document Creation Successful**

A new document was successfully created in the container. Here are the details:

*   **ID:** `chat_20230612`
*   **Partition Key:** `client-101`
*   **Content Summary:** Initial inquiry regarding billing cycle changes.

This record is now available for future queries.
```

**Prompt:** 
```
What's the current status of document 'report_q2_23'? And please delete it if it's marked as archived.
```

**Response:** 
```
**Status Check:** The document `report_q2_23` was found. Status: *archived*.

**Action Taken:** Because the status matched 'archived', I ran the deletion command. ✅ Document `report_q2_23` has been permanently removed from the container.
```

## Capabilities

### Querying Document Data
Run custom SQL queries against the container to find documents based on specific criteria.

### Retrieving Documents by ID
Fetch a single document directly using its unique identifier and partition key.

### Creating New Records
Add brand new documents to the container, ensuring they are properly indexed with an ID and Partition Key.

### Deleting Documents
Permanently remove a document from the container using its specific ID and partition key.

## Use Cases

### Archiving old user session data
A support manager needs to review a customer's interaction from six months ago. Instead of digging through logs, the agent uses `query_documents` with date ranges and specific IDs to pull all relevant chat history records in one query.

### Updating user preferences after checkout
A marketing automation workflow needs to update a user's preferred communication method. The agent calls `get_document` first to verify the current record, then uses `create_document` or similar logic to write the updated data safely.

### Cleaning up outdated records
The ops team runs a script that identifies and archives stale data. The agent executes `query_documents` for documents marked 'expired' and then uses `delete_document` to clean them up permanently, confirming the operation each time.

### Building a knowledge base from unstructured inputs
A content editor needs to store newly drafted articles. The agent creates structured records using `create_document`, ensuring every article gets a unique ID and is immediately available for querying by other parts of the system.

## Benefits

- Absolute containment means the agent can only interact with this single container. It won't list or access your other databases, keeping your production environment safe.
- Need to save chat transcripts? Use `create_document` to reliably store session histories in a scalable NoSQL format for later retrieval by your AI client.
- Running complex reports used to mean writing dedicated backend microservices. Now, you can use `query_documents` to run advanced SQL queries directly via your agent's natural language prompt.
- Retrieving a single user profile is simple. The `get_document` tool lets your agent pull specific records instantly using the document ID, making data access fast and reliable.
- It removes the risk of over-permissioning. Instead of giving global database read/write rights, you grant precise access to just this one container.

## How It Works

The bottom line is, you tell your agent what data you need—whether it's a list of records or a single chat history—and it performs the exact action within the secure boundaries of this one database container.

1. Your AI client connects to Vinkius, selecting this MCP for Azure Cosmos DB Container.
2. The agent uses natural language to specify whether it needs to read data (query), write new data (create), or delete an entry.
3. The system executes the precise database operation against the container and returns the resulting document(s) or a success confirmation.

## Frequently Asked Questions

**Can Azure Cosmos DB Container MCP handle chat history storage and retrieval?**
Yes, absolutely. You can use this MCP to treat chat histories as structured documents, creating a dedicated record for each session. This makes it easy for your AI agent to pull up long-term context when needed.

**Is the Azure Cosmos DB Container MCP safe regarding permissions?**
It is designed with extreme security in mind. The MCP only grants access to one specific container, meaning your agent cannot interact with or view any other databases you have running in Azure.

**How do I use this MCP if I need to search across multiple criteria?**
You must use the query function. Instead of asking for everything, phrase your request like: 'Find all documents where status is pending AND created before last month.' This allows precise filtering.

**Does Azure Cosmos DB Container MCP work with other cloud databases?**
No. This MCP is specifically built to manage one single, isolated container within the Azure Cosmos DB ecosystem. It will not connect to external or different database types.

**What if I need to update an existing document's data?**
You first retrieve the current document using its ID and then use the appropriate tool function to write the updated version back. This ensures you don't overwrite critical information accidentally.