Inspect Azure Cosmos DB with Azure MCP Server

In this exercise, you connect an AI assistant to the CosmicWorks product catalog through a Model Context Protocol (MCP) server. You inspect and query the catalog with natural-language requests, then verify the tool calls and results.

Before you start

❗ You need a GitHub account with access to GitHub Copilot for the Copilot tasks in this exercise. If you don’t have an account, create a free GitHub account and verify your email address before starting. GitHub Copilot Free is available with usage limits.

To complete this exercise, you need an Azure subscription with permission to create resources and assign roles.

If your lab environment isn’t set up yet, follow Set up your lab environment to install Visual Studio Code, Git, the Azure CLI, and PowerShell 7.

This exercise also requires:

• Node.js 22 or later, which supplies the npx command the MCP server runs under.
• Visual Studio Code with the GitHub Copilot extension.

GitHub Copilot supplies the model for Chat. You don’t deploy a chat or embedding model for this exercise.

Set up your Azure Cosmos DB resources

This exercise uses the core profile, which creates the CosmicWorks catalog and supporting containers. The MCP tasks inspect and query only the cosmicworks/product container.

To create the lab resources and load the catalog data, run setup once.

1. Start Visual Studio Code.

2. If you don’t have the lab code yet, clone the repository for DP-420: open the command palette with Ctrl+Shift+P, run Git: Clone, and enter the following URL. Choose a local folder when prompted. Otherwise, open the folder from your previous clone.

    https://github.com/microsoftlearning/dp-420-cosmos-db-dev
   

3. Once the repository is cloned, open that local folder in Visual Studio Code.

4. In the Explorer pane, browse to the Allfiles/Labs/Shared folder.

5. Open the context menu for the folder and select Open in Integrated Terminal. If the terminal isn’t PowerShell, select the dropdown beside the + in the terminal toolbar and choose PowerShell.

6. Sign in to the Azure CLI. A browser window opens so you can sign in to Azure.

    az login
   

7. Set variables for the resource group and region. If your lab environment provides a resource group, use that name. Otherwise, use a new group that contains only this exercise’s resources.

    $resourceGroup = "ResourceGroup1"
    $location = "westus2"
   

8. Run the setup script.

    ./setup.ps1 -ResourceGroup $resourceGroup -Location $location -NamePrefix dp420lab08 -LabProfile core
   

   Azure Cosmos DB account names have to be globally unique, so the script builds one for you by adding six random characters to the prefix, giving a name like dp420lab08a7f3k9.

9. Wait for Setup complete in the terminal. Deployment failures stop setup and appear in the log.

10. Record the Account name and Account endpoint values the script prints. The Cosmos DB endpoint looks like https://<your-account-name>.documents.azure.com:443/.

11. Set a variable for the account name so the Azure CLI commands in this exercise can use it.

     $accountName = "<your-account-name>"
    

12. Run verification to check the resources.

     ./verify.ps1 -ResourceGroup $resourceGroup -AccountName $accountName -LabProfile core
    

    Continue only after setup and verification succeed. To resume a failed setup, replace -NamePrefix dp420lab08 with -AccountName <your-account-name> in the setup command. Keep the resource group and profile unchanged.

Setup creates these resources:

Because key-based authentication is disabled, no key or connection string appears anywhere in this exercise. Every operation authenticates with the identity from your az login session, which is the recommended approach for new accounts.

📝 A new role assignment takes a few minutes to propagate. If a later step fails with a 403 error, wait a moment and try again.

Task 1: Configure and start Azure MCP Server

The tasks use the existing cosmicworks/product catalog. You interact with its data through the Azure MCP Server tools in Chat.

1. In Explorer, under Allfiles/Labs/Shared, create a folder called ai-tools-lab. If the folder already exists, reuse it.

2. If ai-tools-lab isn’t already the open workspace folder, select File > Open Folder and choose it. Changing the terminal’s directory doesn’t change the VS Code workspace.

Under the ai-tools-lab folder, create a folder called .vscode. Inside .vscode, create a file called mcp.json and add this configuration:

{
  "servers": {
    "Azure MCP Server": {
      "command": "npx",
      "args": ["-y", "@azure/mcp@latest", "server", "start"]
    }
  }
}

1. If the Chat pane isn’t open, select View > Chat from the menu bar.

2. Check the mode selector in the chat input area. If Agent is already selected, keep it selected. Otherwise, open the selector showing the current mode, such as Ask, and choose Agent.

3. Open the model picker in the chat input area. It can display Models, Auto, or a model name. If it shows Sign in to use Copilot, select that option and sign in with a GitHub account that has access to Copilot. After signing in, reopen the model picker. Keep an existing model or Auto selection. If no model is selected, choose a model available for Agent mode.

4. Press Ctrl+Shift+P, enter MCP: List Servers, and select the command. Choose Azure MCP Server. If it isn’t running, select Start Server. Review any server-trust prompt before continuing. If the server is missing or disabled, use the recovery steps in this task.

5. If the Azure MCP Server isn’t listed, select Add Server and follow the prompts to add it. If you still don’t see it, select Browse MCP Server (Enable the Marketplace if needed) and search and install it.

Continue only when the Azure MCP Server is running and its tools are available in Chat.

Task 2: Inspect and query the catalog through MCP

Keep the same Chat conversation for these requests. Replace **** with the account name recorded during setup. If the assistant asks for a subscription or resource group, provide the values you used for this exercise.

Start by checking the catalog count through MCP:

In the chat input area, enter the following request, allow access if needed:

Use the Azure MCP Server to count all items in the product container
in the cosmicworks database for account <your-account-name>.
Return the total count, not a sample of documents. Use this account
and database for my remaining requests.

Review the tool call and approve it if prompted. Confirm that it targets your lab account and returns a count of 295. If the count differs, check the target account, database, and container against your setup values before continuing. Don’t change the data to match the expected count.

Next, ask the assistant to inspect the document structure:

Infer the schema of the product container in the cosmicworks database
for my Azure Cosmos DB account.

Note that this might ask for confirmation or additional information depending on the assistant’s configuration and the state of your Azure Cosmos DB account.

The schema tool samples documents and reports top-level properties, inferred types, and property occurrence counts. Compare the result with the catalog fields: id, categoryId, categoryName, sku, name, description, price, and tags. The sample is not a guarantee that every document has the same structure.

Ask for the most recently modified items:

Show me the 5 most recently modified items in the product container.

Inspect the returned documents and their _ts values. The recent-items tool orders documents by this system timestamp in descending order. Documents can share a timestamp, so the exact items and their order can vary. Keep one returned item’s id and categoryId for Task 3.

Then filter the catalog and request only the fields you need:

Query the product container for items where categoryId is
3E4CEACD-D007-46EB-82D7-31F6141752B2, and return only name and price.

Review and approve each tool call when prompted. For the filtered request, check that the query uses the specified category ID and projects name and price. Inspect the returned values, not only the assistant’s statement that it ran a query.

📝 The server also carries text search and vector similarity search. Neither is exercised here, because text search needs a full-text index on the target property and vector search needs both a vector index and an embedding deployment. The product container has neither. That constraint belongs to the tools, not to your prompt: they operate on the indexing policy you configured.

Task 3: Verify the results and the tool’s scope

An assistant’s explanation is not a substitute for checking the tool output. Verify one catalog item and identify what the tool does and doesn’t establish.

1. Expand a tool call from Task 2. Confirm that it comes from Azure MCP Server and targets your account, cosmicworks, and product. A Query Editor extension or another database tool is not the Azure MCP Server used in this exercise. If a different tool ran, return to Task 1 and confirm the server is available before repeating the request.

2. Use the id and categoryId you recorded from the recent-items result. Replace both placeholders in this request:

    Retrieve item <item-id> from the product container in the cosmicworks
    database for the same account, using the Azure MCP Server.
    Use partition key <category-id>. Show its id, categoryId, name, and price.
   

3. Inspect the tool’s arguments and returned document. Confirm that the partition key matches the item’s categoryId and that name and price agree with the earlier result. Supplying the partition key scopes the item lookup to that partition.

4. Explain the limits of the schema result. Which properties appear in the sample? Does a top-level array or object type describe all nested fields? The schema tool doesn’t inspect nested structures recursively. To inspect any nested values it contains, use the retrieved document.

The catalog tools used here are read-only. Other tools enabled in Copilot can have different permissions, so inspect the tool source and requested action before approval. The setup script grants Cosmos DB Built-in Data Contributor to load the data; that role allows writes even though these MCP calls only read.

Identify one decision the MCP tools don’t make for you, such as choosing the partition key, setting throughput, or granting access. Describe what evidence you need before making that decision. The tools help inspect data, but your team remains responsible for database design and access control.

Clean up resources

When you finish this exercise, delete its resources if you no longer need them. Delete the resource group only if you created it for this exercise and every resource in it can be removed:

az group delete --name $resourceGroup --yes --no-wait

If your lab environment provided the resource group, keep it. Delete only the Cosmos DB account you created for this exercise, after confirming that no other application uses it:

az cosmosdb delete --name $accountName --resource-group $resourceGroup --yes

Keep shared and lab-provided resource groups. Don’t delete a reused Cosmos DB account that other exercises or applications use.

The provisioned-throughput containers in this exercise incur throughput and storage charges while they exist.