This article goes over creating an assistant on Ejento with the Azure MCP (Model Context Protocol) Server to interact with Azure Cosmos DB resource through natural language. This guide focuses on configuring Azure Cosmos DB to query NoSQL databases and containers using conversational prompts.

Prerequisites
Active subscription with a Cosmos DB resource
A Cosmos DB Account e.g., cosmosdb-xxxx-xxxx-eastus-001
Database & Container At least one database (e.g., SampleDB) and container (e.g., SampleContainer)
MCP Server deployed and accessible to the assistant
In case of a private network, add the network configuration
Permissions to list, query, and manage Cosmos DB resource
For complete Azure MCP setup and configuration, visit: Azure MCP Server Configuration Guide

Azure Cosmos DB is a fully managed database service that supports document, key-value, graph, and column-family data models. The tool supports querying databases, listing containers, and executing SQL-like queries against JSON documents. Below are the tools available via the MCP

Tool/Operation	Description
Account: List	List all Cosmos DB accounts in your subscription
Database: List	List all databases in a Cosmos DB account
Database: List containers	List all containers in a Cosmos DB database
Database: Query container items	Execute SQL queries against items in a Cosmos DB container

Tool parameters are defined for each operation. Some are specific to individual tools, while others are global and shared. See Tool parameters documentation for details.

For detailed tool documentation: Azure Cosmos DB Tool Reference

Use Case

How It Works

Natural Language Querying:
Users ask questions or request data in plain language. The agent translates these into Cosmos DB SQL queries.

Schema Discovery:
Before querying, the agent verifies the schema (e.g., SELECT TOP 1 * FROM c) to ensure accurate field selection and case normalization.

Query Execution:
The agent executes queries directly against the specified Cosmos DB database and container using the MCP server.

Example Workflow

User:
Find all products with price less than $50 in the 'products' container in database 'inventory'.

Assistant:

Discovers schema

Crafts and executes SQL:
SELECT c.id, c.name, c.price FROM c WHERE c.price < 50

Returns results in a table with query metrics

Recommended Prompts

Assistant Role

Custom Instructions

For cosmos related, always assume parameters': {'subscription': 'xxxx-xxxx-xxxx-xxxx-add-your-subid', 'account': 'cosmosdb-xxxx-xxxx-eastus-001', 'database': 'SampleDB', 'container': 'SampleContainer'

when doing the queries, normalize the cases so we get consistent results.

Before searching for data, verify the schema by running SELECT TOP 1 FROM c to get fields

Select an appropriate assistant name and description that reflect its purpose. Set the Assistant type to "QnA" for question-and-answer scenarios, and choose a language model that best fits your requirements.

For reasoning pattern, consider the complexity of your use case:

ReAct is recommended for straightforward queries and quick responses.

Reflection provides critique on the responses

DeepAgent provides more advanced planning and reasoning, suitable for complex tasks, but may result in longer response times.

1. Click on Create Assistant

2. Click on Select project...

3. Click on General - Assistant

4. Type "You are an assistant that utilizes Azure MCP - particularly the cosmos db"

5. Click on Add Assistant

6. Click on Assistant Tools

7. Turn off Rag Tool

8. Turn off Attachment Tool

9. Turn on Azure MCP

10. Click on Azure MCP

11. Disable all tools except for cosmos

About the Cosmos DB Tool:
Cosmos DB operations provide commands for managing and querying Azure Cosmos DB resources. This includes operations for databases, containers, and document queries. This is a hierarchical MCP command router where sub-commands require specific fields in the "parameters" object. Set "learn=true" to discover available operations for different database and container operations.

12. Click on customize

13. Click on Add custom instruction

14. Add an instruction so the agent knows which database and container to query

Add this custom instruction with your specific subscription, account, database, and container details:

For cosmos related, always assume parameters': {'subscription': 'Subscription of cosmosdb', 'account': 'Your cosmos account name', 'database': 'Your database name', 'container': 'Your container name'}

15. Add an instruction so agent learns the structure of the data

Add this instruction to help the assistant understand your data schema:

Before searching for data, verify the schema by running SELECT TOP 1 * FROM c to get fields

16. Click on Save

17. Write any natural language question to query database

Best Practices for Ejento AI Integration

Required Parameters

Always provide these parameters in your custom instructions for optimal results:

subscription: Your Azure subscription ID

account: Your Cosmos DB account name

database: The database to query

container: The specific container within the database

Schema Discovery

Before running complex queries, it's recommended to verify the data structure:

Use SELECT TOP 1 * FROM c to see available fields

This helps the assistant understand your document schema

Improves query accuracy and reduces errors

Effective Prompting Tips

Use natural language: Describe what data you want in plain terms

Be specific about filters: Mention conditions like "where status is active" or "created after 2024"

Request aggregations clearly: "Count by category" or "Sum total by region"

Provide context: Mention the type of documents stored (e.g., "user profiles", "order records")

Example Queries

"Show me all orders placed in the last 30 days"

"Count how many users have premium subscriptions"

"Find documents where price is greater than 100"

"List all products in the electronics category"

Query Translation

The assistant automatically translates natural language into Cosmos DB SQL syntax:

Natural: "Find active users"

SQL: SELECT * FROM c WHERE c.status = 'active'

Pro Tip: Follow this official documentation to know how to format your query

Azure Cosmos DB Agent Documentation

1. Overview

The Azure Cosmos DB Agent enables conversational access to Azure Cosmos DB—a globally distributed, fully managed NoSQL database service. Integrated with the Azure MCP Server, this agent translates natural language prompts into secure, optimized Cosmos DB queries and operations. It is ideal for support, analytics, documentation retrieval, and internal data management scenarios.

Key Benefits:

Query and manage Cosmos DB resources using natural language

Automate data retrieval and reporting for documentation and support

Enforce best practices for query performance and security

2. Prerequisites

Azure Subscription: Active subscription with Cosmos DB resources

Cosmos DB Account: e.g., cosmosdb-ejento-mcp-eastus-001

Database & Container: At least one database (e.g., SampleDB) and container (e.g., SampleContainer)

MCP Server Integration: MCP enabled for Cosmos DB

Permissions: Sufficient rights to list, query, and manage Cosmos DB resources

Azure Cosmos DB

Use Case#

How It Works#

Recommended Prompts#

Assistant Role#

Custom Instructions#

1. Click on Create Assistant#

2. Click on Select project...#

3. Click on General - Assistant#

4. Type "You are an assistant that utilizes Azure MCP - particularly the cosmos db"#

5. Click on Add Assistant#

6. Click on Assistant Tools#

7. Turn off Rag Tool#

8. Turn off Attachment Tool#

9. Turn on Azure MCP#

10. Click on Azure MCP#

11. Disable all tools except for cosmos#

12. Click on customize#

13. Click on Add custom instruction#

14. Add an instruction so the agent knows which database and container to query#

15. Add an instruction so agent learns the structure of the data#

16. Click on Save#

17. Write any natural language question to query database#

Best Practices for Ejento AI Integration#

Required Parameters#

Schema Discovery#

Effective Prompting Tips#

Example Queries#

Query Translation#

Azure Cosmos DB Agent Documentation#

1. Overview#

2. Prerequisites#

Use Case

How It Works

Recommended Prompts

Assistant Role

Custom Instructions

1. Click on Create Assistant

2. Click on Select project...

3. Click on General - Assistant

4. Type "You are an assistant that utilizes Azure MCP - particularly the cosmos db"

5. Click on Add Assistant

6. Click on Assistant Tools

7. Turn off Rag Tool

8. Turn off Attachment Tool

9. Turn on Azure MCP

10. Click on Azure MCP

11. Disable all tools except for cosmos

12. Click on customize

13. Click on Add custom instruction

14. Add an instruction so the agent knows which database and container to query

15. Add an instruction so agent learns the structure of the data

16. Click on Save

17. Write any natural language question to query database

Best Practices for Ejento AI Integration

Required Parameters

Schema Discovery

Effective Prompting Tips

Example Queries

Query Translation

Azure Cosmos DB Agent Documentation

1. Overview

2. Prerequisites