Azure Cosmos DB MCP Client and Server Infrastructure

This repository encapsulates a complete demonstration project showcasing the implementation of an MCP Server and companion client specifically tailored for interaction with Azure Cosmos DB.

The architecture is segmented into two primary operational units:

• Presentation Layer (Frontend): Built on NextJS 15, this component renders a dynamic product showcase and incorporates an advanced AI Assistant designed to facilitate product discovery and historical order lookups.
• Data Access Layer (MCP Server): This service component establishes a reliable connection to the Azure Cosmos DB NoSQL database instance, managing all read operations concerning product inventory and transactional order records.

Architectural Blueprint (Azure Infrastructure)

• Data Store: An Azure Cosmos DB instance configured for NoSQL API, housing the core product catalog information.
• Application Server: A Node.js-based server acting as the central hub for the MCP communication protocol.

Supplementary Resources

• Provisioning an Azure Cosmos DB for NoSQL Account
• Creating an Azure Storage Account Instance
• Deploying a Windows Virtual Machine in Azure
• Managing Windows Execution Policies

Setup and Deployment Guide

Initial Provisioning

Azure Cosmos DB Setup

Provision an Azure Cosmos DB for NoSQL account via the Azure portal.

• Assign a globally unique identifier to the Cosmos DB instance (e.g., cosmos-eastus2-nosql-2 for this guide).

• Proceed to the "Global distribution" tab (accept defaults).

• Proceed to the "Networking" tab (accept defaults).

• Navigate to "Backup Policy":

  • Set policy to "Periodic".
  • Select "Locally-redundant backup storage".

• Proceed to the "Encryption" tab.

• Initiate validation by clicking "Review and Create".

• Finalize creation by clicking "Create".

Crucially, activate vector search capabilities on the newly created Cosmos DB instance: - Within the account settings, locate 'Features' and enable "Vector Search for NoSQL API". - In the corresponding configuration panel, select the 'Enable' option.

Database and Container Creation (eShop Schema):

• Establish the eshop database within the Cosmos DB instance.
• Create the primary products container.

Ensure the partition key for the products container is explicitly set to /id (case sensitivity matters).

Expand the "Container Vector Policy" section and use the "Add vector embedding" feature to configure vector support.

• Provision the auxiliary carts container within the eshop database.

Azure Storage Account Setup

1. Establish a dedicated storage account to host product visual assets (images).

Refer to the official documentation for detailed storage account creation steps: https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal

Prerequisite Software Installation

1. Provision an Azure VM or utilize a local development environment.
2. Install Node.js, specifically version v22.13.1 (LTS), obtainable from https://nodejs.org/en/download
3. Install Visual Studio Code x64 v1.97.0 from https://code.visualstudio.com/download
4. Install Git v2.47.12 x64 from https://git-scm.com/downloads
5. Install .NET SDK x64 v9.0.102 from https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/sdk-9.0.102-windows-x64-installer
6. Open a terminal and register the NuGet source:

dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org

1. For Windows systems, elevate PowerShell execution policies if necessary. Open PowerShell with administrator privileges and execute:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

1. Install required package managers and Azure CLI tools:

# Install Azure CLI
winget install -e --id Microsoft.AzureCLI

# Install NuGet package provider and register source
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force

# Update to the latest stable PowerShell release (version 7.5 at this writing)
winget install --id Microsoft.PowerShell --source winget

# Install Azure PowerShell modules
Install-Module -Name Az -Repository PSGallery -Force -AllowClobber

1. Clone the repository source code:

git clone https://github.com/patrice-truong/cosmosdb-mcp.git
cd cosmosdb-mcp

1. Navigate into the frontend directory and resolve dependencies:

cd cosmosdb-mcp/nextjs
npm install  --legacy-peer-deps

1. Configure environment variables in the nextjs directory by creating an .env file populated with the following settings:

AZURE_COSMOSDB_NOSQL_ENDPOINT=https://<cosmosdb_account_name>.documents.azure.com:443/
AZURE_COSMOSDB_NOSQL_DATABASE=eshop
AZURE_COSMOSDB_NOSQL_PRODUCTS_CONTAINER=products
AZURE_COSMOSDB_NOSQL_CARTS_CONTAINER=carts
AZURE_COSMOSDB_NOSQL_ORDERS_CONTAINER=orders
AZURE_STORAGE_ACCOUNT_NAME=<storage_account_name>
AZURE_STORAGE_CONTAINER_NAME=<container_name>

1. Obtain the Azure Tenant ID by authenticating via CLI:

az login
az account show --query tenantId -o tsv

1. Update the webapi/appsettings.json configuration file, substituting the placeholder <tenant_id> with the retrieved value:

{
  "CosmosDb": {
    "Endpoint": "https:/<cosmosdb_account_name>.documents.azure.com:443/",
    "TenantId": "<tenant_id>",
    "DatabaseName": "eshop",
    "ProductsContainerName": "products",
    "CartsContainerName": "carts",
    "OrdersContainerName": "orders"
  },
  "AzureBlobStorage": {
    "AccountName": "<storage_account_name>"
  }
}

1. Register an Application within the Azure Portal (Entra ID).
2. Generate a client secret for the newly created application registration.
3. Configure Role-Based Access Control (RBAC) to grant the application access to Cosmos DB. Retrieve the four required identifiers and update the populate/set_rbac.ps1 script accordingly.

Identifier	Source Location in Azure Portal
Subscription Id	Cosmos DB > Overview > Subscription Id
Azure Cosmos DB account name	cosmos-eastus2-nosql-2 (Example)
Resource group name	Cosmos DB > Overview > Resource group name
Principal Id	App registration Object ID (Entra ID)

PowerShell script update:

$SubscriptionId = "<subscription-id>"   # Azure subscription identifier
$AccountName = "<cosmosdb-account-name>"    # Cosmos DB account identifier
$ResourceGroupName = "<resource-group-name>" # Resource group housing the Cosmos DB account
$PrincipalId = "<principal-id>"   # Object ID of the Entra ID application registration

1. In a PowerShell session, execute Connect-AzAccount and then run the RBAC setup script: ./set_rbac.ps1

2. Grant the application (or VM) permissions to interact with the storage account:

3. Navigate to the storage account in the Azure portal.

4. Select "Access Control (IAM)" from the navigation pane.

5. Click "Add role assignment".

6. Search for and select the role: "Storage Blob Data Contributor".

7. Navigate to the "Members" tab.

8. Locate and select the registered application's identity.

9. Confirm selection by clicking "Select", then finalize the assignment by clicking "Review and assign".

10. Provision the necessary container within the storage account and transfer the contents of the local azure-storage directory into it.

11. Compile the backend Web API project using the .NET CLI:

cd webapi
dotnet build

1. (If deploying to a secondary region VM, e.g., Australia East) Update the local .env file with the network socket address of the primary region's server (East US 2).

2. Authentication Note: This project currently lacks integrated authentication mechanisms. The demonstration user email is hardcoded in /nextjs/models/constants.ts. Adjust this value as needed for your testing scenarios.

3. In both the mcp-server and nextjs directories, duplicate .env.template to .env and populate all required parameters:

AZURE_COSMOSDB_NOSQL_ENDPOINT=https://<cosmosdb_account>.documents.azure.com:443/
AZURE_COSMOSDB_NOSQL_DATABASE=eshop
AZURE_COSMOSDB_NOSQL_PRODUCTS_CONTAINER=products
AZURE_COSMOSDB_NOSQL_CARTS_CONTAINER=carts
AZURE_COSMOSDB_NOSQL_ORDERS_CONTAINER=orders

NEXT_PUBLIC_AZURE_TENANT_ID=<tenant_id>
NEXT_PUBLIC_AZURE_CLIENT_ID=<client_id>
NEXT_PUBLIC_AZURE_CLIENT_SECRET=<client_secret>

NEXT_PUBLIC_AZURE_STORAGE_ACCOUNT_NAME=<storage_account_name>
NEXT_PUBLIC_AZURE_STORAGE_CONTAINER_NAME=img

AZURE_OPENAI_ENDPOINT=https://<azure_openai_account>.openai.azure.com/
AZURE_OPENAI_API_KEY=<azure_openai_key>
AZURE_OPENAI_EMBEDDING_MODEL=text-embedding-3-small
AZURE_OPENAI_API_VERSION=2024-05-01-preview

1. Build the NextJS frontend application assets:

cd nextjs
npm run build

Populating the Product Inventory

This section details the process for ingesting product data from the local populate/catalog.json file into the Azure Cosmos DB NoSQL database.

1. Update appsettings.json with your specific Cosmos DB account endpoint information:

{
  "CosmosDb": {
    "Endpoint": "https://<cosmosdb_account_name>.documents.azure.com:443/",
    "TenantId": "<tenant_id>",
    "DatabaseName": "eshop",
    "ProductsContainerName": "products",
    "OrdersContainerName": "orders",
  }
}

1. Execute az login in a terminal, navigate to the populate directory, and run the data seeding application via dotnet run.

2. Validate successful population by inspecting the contents of the respective Azure Cosmos DB container.

Demonstration Execution Sequence

Initialization Steps:

1. Initiate the MCP server process from your workstation:

cd mcp-server
npx ts-node src/server.ts

1. Launch the client-side application (store front):

2. Navigate to the NextJS project directory (cd nextjs)

3. Execute the start command: npm start

4. Optionally, for protocol inspection, open a separate console and execute the MCP inspector utility: npx -y @modelcontextprotocol/inspector

Interactive Scenario Walkthrough:

1. Access the application interface via a web browser at http://localhost:3002.
3. Engage the AI Assistant (top-right icon) and input: "I'm interested in backpacks" (Observe the product list dynamically filter to show relevant backpacks).
4. Engage the AI Assistant again and input: "Get my orders" (Observe the data display update to show past order history).