List all available CosmosDB connections configured in this MCP server. Use this to discover which connection_id values you can use. Each connection points to a different CosmosDB account/database.

List all databases in the CosmosDB account. Use this to discover available databases before querying containers. Returns database IDs, timestamps, and ETags.

List all containers in the connected CosmosDB database. Use this to discover available containers and their partition key configurations before querying data. Returns container IDs, partition key paths, and indexing policies.

Get detailed configuration of a specific container including partition key, indexing policy, and throughput settings. Use this to understand the container structure before writing queries. Example: mcp_get_container_definition({container_id: 'users', connection_id: 'athlete'})

Get statistical information about a container including document count, estimated size, and partition key distribution. Use this for capacity planning and performance analysis. Example: mcp_get_container_stats({container_id: 'orders', sample_size: 500})

Execute a CosmosDB SQL query against a container. Use this for complex queries with JOINs, aggregations, or custom SQL syntax.

⚠️ IMPORTANT - AVOID SELECT *:

• NEVER use SELECT * in large containers - it causes timeouts and high RU consumption

• ALWAYS use TOP N to limit results: SELECT TOP 10 c.id, c.name FROM c

• ALWAYS specify only the fields you need: SELECT c.id, c.name, c.email FROM c

COSMOSDB SQL SYNTAX EXAMPLES:

• Basic: SELECT TOP 10 c.id, c.name FROM c WHERE c.status = @status

• With projection: SELECT c.id, c.name, c.email FROM c

• Aggregation: SELECT VALUE COUNT(1) FROM c

• Array contains: SELECT TOP 20 c.id FROM c WHERE ARRAY_CONTAINS(c.tags, 'urgent')

• Nested: SELECT TOP 10 c.id, c.address FROM c WHERE c.address.city = 'Madrid'

• ORDER BY: SELECT TOP 10 c.id, c._ts FROM c ORDER BY c._ts DESC

PARAMETERS: Use @paramName syntax and provide values in the 'parameters' object. Example: query="SELECT TOP 10 c.id, c.type FROM c WHERE c.type = @type", parameters={type: "order"}

Get documents from a container with simple filters and ordering. Use this for basic queries without complex SQL syntax.

FOR COMPLEX QUERIES: Use mcp_cosmos_query instead. THIS TOOL IS BEST FOR:

• Getting all documents (with limit)

• Simple equality filters on fields

• Filtering by partition key for performance

• Getting the most recent or oldest documents using order_by

Example: mcp_get_documents({container_id: 'users', limit: 10, order_by: '_ts', order_direction: 'DESC', connection_id: 'athlete'}) Example: mcp_get_documents({container_id: 'users', limit: 50, filter_conditions: {status: 'active'}})

Get a single document by its ID and partition key. This is the most efficient way to retrieve a specific document.

IMPORTANT: Both document_id and partition_key are required for a point read in CosmosDB. The partition_key type must match your container's partition key type.

Example: mcp_get_document_by_id({container_id: 'users', document_id: 'user-123', partition_key: 'user-123', connection_id: 'athlete'})

Analyze the schema/structure of documents in a container. Samples documents to discover field names, data types, and frequency. Use this to understand the data model before writing queries.

Create a new document in a CosmosDB container.

REQUIREMENTS:

• The document MUST have an 'id' field (string)

• The document MUST have the partition key field with a value

• The 'id' must be unique within the partition

Example: mcp_create_document({ container_id: 'users', document: {id: 'user-456', email: 'test@example.com', status: 'active'}, partition_key: 'user-456', connection_id: 'athlete' })

Update (replace) an existing document in a CosmosDB container.

NOTE: This performs a full document replacement. Include ALL fields you want to keep. For partial updates, first get the document with mcp_get_document_by_id, modify it, then update.

Example: mcp_update_document({ container_id: 'users', document_id: 'user-456', document: {id: 'user-456', email: 'new@example.com', status: 'inactive'}, partition_key: 'user-456', connection_id: 'athlete' })

Delete a document from a CosmosDB container.

WARNING: This operation is irreversible. The document will be permanently deleted.

Example: mcp_delete_document({ container_id: 'users', document_id: 'user-456', partition_key: 'user-456', connection_id: 'athlete' })

Create or update a document in a CosmosDB container (upsert operation).

If a document with the same id and partition key exists, it will be replaced. If it doesn't exist, a new document will be created.

Example: mcp_upsert_document({ container_id: 'users', document: {id: 'user-456', email: 'test@example.com', lastUpdated: '2024-01-15'}, partition_key: 'user-456', connection_id: 'athlete' })