Databases, containers, SQL queries and items. Changes wait for approval.
The screenshots show GateRook 2.0.0: the Azure Cosmos DB form, the endpoint selector, and this connector’s actual tool preview. The form and preview have not been saved. Select a screenshot to open it at full size.
1. Create a connection and enter the settings
In GateRook, open Connections, select Add connection, search for Azure Cosmos DB, choose its card and select Continue to configure.
Use this connector for an Azure Cosmos DB account with the NoSQL API. For an account’s MongoDB-compatible interface, choose the separate MongoDB-compatible service instead.
Copy the account URI and prepare a read-only account key or an Entra service principal with the appropriate Cosmos DB data-plane role.
Enter a Name, for example cosmosdb-demo. Your AI app uses this name to choose the connection.
Enter Account endpoint from the account’s Keys page. Restrict Databases and Containers; a container can be named as database/container.
For Account key, select the actual kind of key in Key and paste Account key. GateRook cannot determine whether a key is read-only without attempting a write, so this choice must match the key you provide.
For Microsoft Entra ID (service principal), enter Directory (tenant) ID, Application (client) ID and the Client secret value. Review Read consistency and leave Cross-partition queries off when queries should always name a partition key.
Choose Development, Staging or Production to match the service. Review the connector’s limit and access settings before continuing.
2. Test the connection and add it to an endpoint
Select Continue to test. GateRook checks the settings from your computer. Review the result and resolve any connection, certificate or permission error before continuing.
Check the account’s network access rules and the selected key or data-plane role. A management-plane Reader role alone does not grant document access. For partition errors, supply the container’s correct partition-key value.
After the test passes, select Continue to add to an endpoint. Choose the endpoint your AI app uses, review its tool modes, then select Save connection. GateRook offers default as the starter endpoint.
3. Use the connection from your AI IDE
After saving Azure Cosmos DB on the endpoint and passing its connection test, ask your AI app to use cosmosdb-demo, or the name you chose. If its tools are missing, confirm the endpoint assignment and refresh the MCP connection or start a new chat.
The preview below shows this connector’s default tools before saving. The table explains what each tool can do; connection settings, credentials and endpoint policies can restrict access further.
Start with a small read request. Replace example resource names with existing resources your connection may access. Open Activity after the call to inspect its connection, tool, arguments, policy decision and result metadata.
Ask your AI, for example
- “List the containers in the app database on cosmosdb-demo.”
- “Describe the partition key of app/orders on cosmosdb-demo.”
- “Using cosmosdb-demo, read order-123 in app/orders with its known partition-key value.”
| Tool | What it does | Starts as |
|---|---|---|
cosmosdb_list_databases | IDs of the databases agents may use in the account. | Read only |
cosmosdb_list_containers | Containers of one database that agents may use, with their partition key paths. | Read only |
cosmosdb_describe_container | Partition key, indexing policy, default time to live, unique keys and, when the credentials may read it, the throughput of one container. | Read only |
cosmosdb_query | One Cosmos DB SQL SELECT on one container, with @name parameters. Give partitionKey to read one partition; without it the query fans out over every partition, where Cosmos DB's gateway refuses TOP, ORDER BY, OFFSET LIMIT, DISTINCT, GROUP BY and aggregates. Pages with nextCursor and reports the request units used. | Read only |
cosmosdb_read_item | One item by its id and partition key value, with its _etag for a later change. | Read only |
cosmosdb_execute | One create, upsert, replace, patch or delete of one item in one container. You approve the exact request. | Approval |
You can change each tool’s mode on the endpoint. Every call your AI makes appears in Activity.