Azure Cosmos DB

References: GitHub Repo · Official Docs

What is the MCP Toolkit?

The Azure Cosmos DB MCP Toolkit is a purpose-built MCP server that lets AI agents query, filter, and semantically search Cosmos DB using natural language — deployed as a containerised Azure Container App with managed identity and optional Entra ID authentication.

Why use this over the Azure MCP Server?

Microsoft's generic Azure MCP Server covers broad Azure services but has significant gaps when it comes to Cosmos DB:

Capability	Azure MCP Server	Cosmos DB MCP Toolkit
Vector / semantic search	Not supported	Native — uses Azure OpenAI embeddings
Focus	Broad Azure surface	Purpose-built for Cosmos DB
Deployment	Local / stdio only	Azure Container App with managed identity
Authentication	CLI credential passthrough	Managed identity + Entra ID SSO

The biggest differentiator is vector search — the Toolkit vectorizes a user's query at runtime using Azure OpenAI and runs a cosine-similarity search across your container. The Azure MCP Server has no equivalent capability.

Prerequisites

Azure subscription (Contributor or Owner)

Azure Container Registry (ACR) — external, not provisioned by the template

Azure Cosmos DB for NoSQL account

Azure OpenAI resource with an embedding model deployed (e.g. text-embedding-3-small)

Azure CLI (az login authenticated)

Docker Desktop

Cloned repo: git clone https://github.com/AzureCosmosDB/MCPToolKit.git

1. Deploy Infrastructure

The repo includes a Bicep template that provisions:

Resource	Type
`mcp-toolkit-app-identity`	User-assigned Managed Identity
`mcp-toolkit-env`	Container Apps Environment
`mcp-toolkit-app`	Container App

The ACR is not included — you'll connect yours in Step 4.

Required parameters:

Parameter	Description	Example
`cosmosEndpoint`	Cosmos DB endpoint	`https://<account>.documents.azure.com:443/`
`aifProjectEndpoint`	Azure OpenAI endpoint	`https://<resource>.openai.azure.com/`
`embeddingDeploymentName`	Embedding model name	`text-embedding-3-small`
`embeddingDimensions`	Dimension size (`0` for ada-002)	`1536`

After deployment, save these outputs — you'll need them later:

managedIdentityPrincipalId

managedIdentityClientId

containerAppUrl

2. Build & Push the Docker Image

From the repo root, authenticate to your ACR and push the image:

3. Assign Roles to the Managed Identity

The user-assigned identity needs permissions on three resources.

Important: The Container App has two identities — a user-assigned (mcp-toolkit-app-identity) and a system-assigned one Azure creates automatically. Always assign roles to the user-assigned identity. Since AZURE_CLIENT_ID points to the user-assigned identity, DefaultAzureCredential ignores the system-assigned one entirely — roles on it have no effect.

First, retrieve the identity IDs:

3A — Cosmos DB: Control Plane (optional)

Portal: Cosmos DB → Access control (IAM) → Add role assignment → Cosmos DB Account Reader → mcp-toolkit-app-identity

3B — Cosmos DB: Data Plane (required)

The portal IAM blade is control-plane only. Without this step you'll get 403 readMetadata errors even if 3B is done. Data-plane roles are invisible in the portal — use the CLI.

Verify:

Role propagation can take 1–2 minutes.

3C — Azure OpenAI: Cognitive Services User

Portal: Azure OpenAI → Access control (IAM) → Add role assignment → Cognitive Services User → mcp-toolkit-app-identity

4. Configure the Container App

Open mcp-toolkit-app in the Azure Portal.

Registry

In the Container App, set the image source to Azure Container Registry and authentication to Secrets — Azure will automatically retrieve the ACR username and password.

Field	Value
Image source	Azure Container Registry
Authentication	Secrets
Registry	`<acr-name>.azurecr.io`
Image	`cosmos-mcp`
Image tag	`latest`

Environment Variables

Name	Value
`COSMOS_ENDPOINT`	`https://<cosmos-account>.documents.azure.com:443/`
`OPENAI_ENDPOINT`	`https://<openai-resource>.openai.azure.com/`
`OPENAI_EMBEDDING_DEPLOYMENT`	Your embedding model name
`OPENAI_EMBEDDING_DIMENSIONS`	`0` for ada-002, or model dimension (e.g. `1536`)
`ASPNETCORE_ENVIRONMENT`	`Production`
`ASPNETCORE_URLS`	`http://+:8080`
`AZURE_CLIENT_ID`	Managed identity client ID ← see note below
`AzureAd__TenantId`	Entra app registration tenant ID
`AzureAd__Audience`	Entra app registration client ID
`AzureAd__ClientId`	Entra app registration client ID

AZURE_CLIENT_ID = the managed identity's client ID (from az identity show --query clientId).
AzureAd__ClientId = the Entra app registration client ID.
These are different objects — mixing them up causes auth failures.

After saving, create a new revision to apply changes.

5. Entra ID App Registration

Step 1 — Authentication & Redirect URIs

Entra ID → App registrations → open your app registration

Authentication → Add a platform

Add redirect URIs:

https://<container-app-url>/ → Single-page application

https://<container-app-url>/signin-oidc → Single-page application

https://<apim-ejento-url>/auth-service/api/v2/mcp-sso/azure/callback

Leave implicit grant flows unchecked

Save

Step 2 — Expose an API

Expose an API → Add Application ID URI: api://<client-id>

Add a scope:

Field	Value
Scope name	`access_as_user`
Who can consent	Admins only
Admin consent display name	Access Azure Cosmos DB MCP Toolkit API as user
Admin consent description	Allows the app to access the API on behalf of the signed-in user
State	Enabled

Under Authorized client applications, add the app registration's own Client ID

Step 3 — Create the App Role

App roles → Create app role:

Field	Value
Display name	`MCP Tool Executor`
Allowed member types	Users/Groups
Value	`Mcp.Tool.Executor`
Description	Grants permission to execute MCP tools
Enable	✅

The MCP server checks for the exact value Mcp.Tool.Executor — it must match exactly.

Step 4 — API Permissions

API permissions → Add a permission → My APIs → select this app

Delegated → access_as_user → Add

Add Microsoft Graph → Delegated → User.Read

Grant admin consent

Step 5 — Container App Env Vars

Add these and create a new revision:

Name	Value
`AzureAd__TenantId`	`<tenant-id>`
`AzureAd__ClientId`	`<app-registration-client-id>`
`AzureAd__Audience`	`<client-id>` or `api://<client-id>`

Step 6 — Assign Users

Enterprise Applications → find your app → Users and groups → assign users to the MCP Tool Executor role.

From the App Registration Overview, record:

Application (Client) ID

Directory (Tenant) ID

6. Enable CORS (if using the test UI)

7. Verify

Check	How
Health	`GET https://<container-app-url>/health` → should return healthy
Test UI	Open `https://<container-app-url>/` in a browser
MCP endpoint	`POST /mcp` with a bearer token

Get a test token:

Checklist

#	Step	Notes
1	Deploy Bicep template	Creates identity, env, container app
2	Build & push image	To your ACR
3a	Cosmos: Account Reader	Optional, portal IAM
3b	Cosmos: Data-plane RBAC	Required — CLI only. Role `00000000-0000-0000-0000-000000000001`, scope `/`
3c	OpenAI: Cognitive Services User	Portal IAM
4	Container App config	Registry (Secrets auth) + env vars + new revision
5	Entra ID auth	Optional — SPA platform, redirect URIs, app role, permissions, user assignment
6	CORS	`--allowed-origins "*"`
7	Test	`/health` healthy, test UI loads, MCP endpoint accepts token

Troubleshooting

403 readMetadata (Substatus 5301)

→ Missing data-plane RBAC. Run the CLI command in Step 3C. Portal IAM alone is not enough.

403 errors after assigning roles

→ Roles were assigned to the system-assigned identity. Re-run all assignments targeting the user-assigned identity's principal ID.

Container won't start / image pull error

→ Confirm the ACR admin user is enabled (ACR → Access keys) and the Container App registry is set to Secrets auth. Create a new revision after any changes.

AADSTS50011 — redirect URI mismatch

→ Confirm the redirect URI in the App Registration exactly matches the Container App URL, and is listed under Single-page application (not Web).

DefaultAzureCredential failure

→ AZURE_CLIENT_ID is wrong or missing. Retrieve it: az identity show --query clientId and set it in the Container App env vars, then create a new revision.

What is the MCP Toolkit?#

Why use this over the Azure MCP Server?#

Prerequisites#

1. Deploy Infrastructure#

2. Build & Push the Docker Image#

3. Assign Roles to the Managed Identity#

3A — Cosmos DB: Control Plane (optional)#

3B — Cosmos DB: Data Plane (required)#

3C — Azure OpenAI: Cognitive Services User#

4. Configure the Container App#

Registry#

Environment Variables#

5. Entra ID App Registration#

Step 1 — Authentication & Redirect URIs#

Step 2 — Expose an API#

Step 3 — Create the App Role#

Step 4 — API Permissions#

Step 5 — Container App Env Vars#

Step 6 — Assign Users#

6. Enable CORS (if using the test UI)#

7. Verify#

Checklist#

Troubleshooting#