Azure Cosmos DB MCP Server

Azure Cosmos DB

Cosmos DB is a document database. Applications store JSON documents in containers grouped by database, usually partitioned for scale and query cost control.

First moves

1. List databases when the target database id is unknown.
2. List containers in the chosen database when container names are unknown.
3. Describe container — partition key path, indexing policy, and throughput settings before heavy work.
4. Container stats — document count and storage footprint for a quick health check.
5. Count items or infer schema — profile shape and volume before wide queries.
6. Query documents — run read-only Cosmos SQL with partition-aware filters when possible.
7. Export matches — paginated query with automatic spill to a download link when result sets are large.
8. Read one document by id and partition key when you already know both.

Data model

Account → Database → Container → Document. Each container declares a partition key path; every document carries that key value. Queries that filter on the partition key cost less than cross-partition scans.

Operational order

1. Resolve database and container ids from list calls — do not guess names when multiple environments share an account.
2. Read container metadata before bulk export or writes so partition key path and indexing behavior are clear.
3. Keep first queries small (top N rows, selective WHERE) to estimate result size and request charge.
4. Paginate with continuation tokens from prior query responses when more pages exist.
5. For large extracts, use the export query path so oversized JSON spills to a download URL instead of inline payloads.
6. Document writes need the partition key value matching the container path; deletes require confirm_write after user approval.

Query and exploration

Use count and schema inference for discovery on unfamiliar containers. Cross-partition queries are valid but consume more request units — enable only when the question truly spans partitions. Read-only SELECT queries are the default exploration pattern; avoid mutating statements in query slots meant for reads.

Document lifecycle

Create inserts a new document with id and partition key. Upsert inserts or replaces by id. Replace updates an existing document and can carry an etag from a prior read for optimistic concurrency. Delete removes one document by id and partition key. Container creation is available when the connected account has control-plane permission on the target database.

Gotchas

• Partition key required — point reads and writes fail without the correct partition key value even when document id is known.
• Request units — cross-partition scans and large page sizes burn RU/s; start with modest page limits.
• Continuation tokens — treat tokens as opaque; pass through exactly as returned to fetch the next page.
• Export spillover — very large query exports return a download link rather than inline JSON; follow the link in the same session.
• Default database — when configured on the credential, tools may assume that database id; still list when the user names a different database.
• Writes need confirmation — document delete is destructive; expect confirm_write on delete actions.