Azure DocumentDB MCP Toolkit

The Azure DocumentDB MCP Toolkit is an open-source Model Context Protocol (MCP) server that lets AI agents and MCP-aware applications operate against Azure DocumentDB through a curated, audited tool surface. The toolkit runs on Node.js 20+, uses TypeScript, and ships from the microsoft/documentdb-mcp repository.

The toolkit is a tools-only server: database connection details (endpoints, credentials, auth modes) are administrator-controlled and never accepted as MCP arguments. Agents only ever name a profile.

What is Model Context Protocol (MCP)?

The Model Context Protocol is an open JSON-RPC protocol that standardizes how a large language model (LLM) client discovers and invokes:

• Tools – functions the model can call.
• Resources – addressable read-only data the host can attach to context.
• Prompts – reusable templates.

A typical deployment has one MCP host (the application running the LLM, such as GitHub Copilot CLI, Claude Code, or VS Code) connected to one or more MCP servers that expose tools, resources, and prompts. Communication runs over stdio, streamable HTTP, or SSE.

Use cases

Key features

Enterprise-grade security

• Microsoft Entra ID authentication. Token-based access with role-based authorization on every tool call.
• Managed identity support. No connection strings or shared secrets in production; the server exchanges its workload identity for a DocumentDB access token.
• Role-based access. Each tool is gated on a read, write, or management role; capability flags let operators disable entire tool classes.
• Secure communication. TLS-only transport to the DocumentDB cluster; HTTPS endpoints with bearer-token auth between MCP clients and the server.
• Safety guardrails. Retype-to-confirm on destructive tools (drop_database, drop_collection, drop_index) and a write-stage guard that blocks $out / $merge in aggregate unless explicitly allowed.

Flexible deployment

• Multiple transports. Run over stdio for local agents (Copilot CLI, Claude Code, VS Code) or streamable-http / sse for shared and production deployments.
• Run anywhere. Self-host on Azure Container Apps, AKS, a VM, or any container runtime; the server is a standard Node.js 20+ container with no Azure-specific runtime dependencies.
• Auditable operations. Structured logs and an [MCP-AUDIT] JSON stream record every allow or deny decision for ingestion into Log Analytics, Application Insights, or any log aggregator.

Architecture

Tool catalog

The server registers 18 tools. Every tool requires a connection_profile argument; tool inputs without a valid profile are rejected.

Prerequisites

Before you deploy the Azure DocumentDB MCP Toolkit:

• Azure subscription with access to your Azure DocumentDB cluster. Create a free account.
• Azure CLI installed and signed in. Install Azure CLI.
• Existing Azure DocumentDB cluster with data. The toolkit connects to your existing cluster and doesn't provision one.
• Microsoft Entra ID permissions to register an application and assign roles on the DocumentDB cluster (required for streamable-http / sse deployments).
• Optional: Azure OpenAI service if your agent generates embeddings for vector queries that it runs through the aggregate tool. Embedding generation happens on the agent side; the toolkit doesn't call Azure OpenAI directly.
• Optional: Docker for local container development. Install Docker Desktop.
• Optional: Node.js 20+ for running the server locally outside containers. Install Node.js.

Quickstart configurations

For VS Code and Cursor, use these one-click install links. Each link prompts for a DocumentDB connection string and registers the server with the local stdio configuration.

GitHub Copilot CLI

In ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "DocumentDB": {
      "command": "npx",
      "args": ["-y", "github:microsoft/documentdb-mcp"],
      "env": {
        "TRANSPORT": "stdio",
        "ALLOW_UNAUTHENTICATED_STDIO": "true",
        "CONNECTION_PROFILES": "{\"local\":{\"authMode\":\"connectionString\",\"uri\":\"mongodb://localhost:27017\"}}"
      }
    }
  }
}

Claude Code

Either add the server to .mcp.json at your project root using the same JSON shape as the GitHub Copilot CLI configuration, or register it from the command line:

claude mcp add DocumentDB \
  -e TRANSPORT=stdio \
  -e ALLOW_UNAUTHENTICATED_STDIO=true \
  -e 'CONNECTION_PROFILES={"local":{"authMode":"connectionString","uri":"mongodb://localhost:27017"}}' \
  -- npx -y github:microsoft/documentdb-mcp

Visual Studio Code

For local stdio use with GitHub Copilot in Visual Studio Code, add the server to settings.json:

{
  "mcp.servers": {
    "documentdb": {
      "command": "npx",
      "args": ["-y", "github:microsoft/documentdb-mcp"],
      "env": {
        "TRANSPORT": "stdio",
        "ALLOW_UNAUTHENTICATED_STDIO": "true",
        "CONNECTION_PROFILES": "..."
      }
    }
  }
}

To connect to a remote server (streamable-http transport with Microsoft Entra), reference its URL and supply a Microsoft Entra bearer token instead:

{
  "mcp.servers": {
    "documentdb": {
      "url": "https://<your-mcp-host>/mcp",
      "headers": {
        "Authorization": "Bearer <entra-jwt>"
      }
    }
  }
}

Production (HTTP, Microsoft Entra, managed identity)

TRANSPORT=streamable-http
HOST=0.0.0.0
PORT=8070

AUTH_REQUIRED=true
ENTRA_TENANT_ID=<tenant>
ENTRA_AUDIENCE=<app-id-uri-or-client-id>

ENABLE_READ_TOOLS=true
ENABLE_WRITE_TOOLS=false
ENABLE_MANAGEMENT_TOOLS=false

CONNECTION_PROFILES={"prod":{"authMode":"entra","endpoint":"<cluster>.mongocluster.cosmos.azure.com","tokenScope":"https://ossrdbms-aad.database.windows.net/.default","allowedHosts":["*.mongocluster.cosmos.azure.com"]}}

Configuration reference

All configuration is environment-driven. The repository's .env.example documents every variable, and dotenv loads .env automatically.

Transport and binding

MCP authentication

Rate limiting

Connection profiles

Define profiles either inline in CONNECTION_PROFILES or in a JSON file referenced by CONNECTION_PROFILES_FILE. The recommended profile mode is entra; the connectionString form is a legacy SCRAM fallback for local or sandbox use.

{
  "prod": {
    "authMode": "entra",
    "endpoint": "<cluster>.mongocluster.cosmos.azure.com",
    "tokenScope": "https://ossrdbms-aad.database.windows.net/.default",
    "allowedHosts": ["*.mongocluster.cosmos.azure.com"],
    "tls": true,
    "retryWrites": true,
    "appName": "documentdb-mcp"
  },
  "local": {
    "uriEnv": "DOCUMENTDB_LOCAL_URI"
  }
}

The local profile shown above is a legacy SCRAM connection-string profile. The server resolves the URI from the environment variable named in uriEnv (for example, DOCUMENTDB_LOCAL_URI=mongodb://localhost:27017). Use it only for local or sandbox development; production deployments should use the entra profile mode with a managed identity.

Deployment topologies

In Azure, prefer the entra profile mode with a managed identity granted backend access through the cluster's RBAC. This avoids storing database credentials at rest.

Authentication

MCP-side authentication (HTTP and SSE)

• Microsoft Entra ID JWT bearer tokens.
• The server validates the JWT issuer, audience, and signature (via JWKS) against the tenant and audience that the operator configures.
• Authentication is required by default. On stdio, authentication can be skipped only behind an explicit opt-in, intended for trusted local development.
• Authentication failures return JSON-RPC error code -32001 and HTTP 401.

For the exact environment variables, see Configuration reference.

Backend authentication

Each connection profile uses one of two modes:

• entra – the server uses DefaultAzureCredential (Azure CLI, managed identity, workload identity, Visual Studio, and so on) to acquire an OAuth 2.0 token for the configured token scope and presents it to the cluster. No database password on disk.
• connectionString – the server reads the URI from configuration. Suitable for local development.

Each profile's allowedHosts allow list enforces that the resolved endpoint matches an expected host pattern, mitigating misconfigured profiles. Profile structure and configuration variables are in Configuration reference.

Authorization

Role hierarchy

A management caller can invoke write and read tools; a write caller can invoke read tools.

Roles are derived from JWT claims (roles, groups, or scp) and mapped through these variables:

Capability flags

Capability flags are independent of the caller's role. If a flag is off, the corresponding tools are denied even for callers with the matching role. They act as a deployment-wide kill switch.

Safety guardrails

For destructive and high-impact tools, the server stacks four independent layers, each of which can deny the call:

Deleting databases, collections, or indexes

Drop operations (drop_database, drop_collection, drop_index) are classified as management tools. Every drop call must clear all of the following. Failing any single check denies the request:

1. ENABLE_MANAGEMENT_TOOLS=true is set on the server. This flag is off by default; management tools aren't even registered until an operator opts in.
2. The caller's token carries a claim that maps to the management MCP role (for example, DocumentDB.MCP.Management via MCP_MANAGEMENT_ROLE_VALUES).
3. The tool call names a valid administrator-defined connection_profile.
4. The caller retypes the target name in the matching confirmation field (see the table below). The confirmation must match exactly. The server rejects mismatches before issuing the drop.

Read and write roles cannot invoke drop tools even if ENABLE_MANAGEMENT_TOOLS=true, and a management caller cannot drop anything while ENABLE_MANAGEMENT_TOOLS=false. Keep off the flag in any deployment that does not need destructive operations.

Retype-to-confirm

This pattern hardens against prompt injection: an attacker would have to coerce the model into both naming the target and producing the matching confirmation in the same call.

Aggregate write-stage guard

The aggregate tool rejects $out and $merge stages unless ALLOW_AGGREGATE_WRITE_STAGES=true.

Other invariants

• Tools never accept connection strings as MCP arguments. Connection strings are server-side process configuration only.
• No tool exposes a raw shell or eval-style operation.
• Profile names are not enumerable before authentication.
• HTTP and SSE always require an explicit connection_profile. Implicit single-profile selection is gated to stdio only.

Audit log

Every allow or deny decision is written to stderr as a single JSON line prefixed with [MCP-AUDIT]:

{
  "timestamp": "2026-05-06T17:00:00.123Z",
  "toolName": "find_documents",
  "requiredRole": "read",
  "decision": "allow",
  "reason": null,
  "connectionProfile": "prod",
  "transport": "streamable-http",
  "sessionId": "...",
  "requestId": "...",
  "principal": { "oid": "...", "sub": "...", "tid": "...", "upn": "...", "name": "..." }
}

Limitations

Functional

• Tools-only. MCP resources and prompts are not implemented.
• MongoDB-compatible API surface only.
• No transaction tool. Multi-document transactions are not surfaced.
• No bulk import tool. Use mongoimport and equivalents.
• No first-class vector-search tool. Vector queries can be issued through aggregate if the backend supports them.
• Schema discovery is sample-based and best-effort.

Security and data handling

• No data masking. Tool results are returned verbatim, and documents flow into the LLM context (and any provider logging or memory). Use database-side masked views for sensitive workloads.
• No field- or row-level access control inside the server. The profile's identity is the data plane.
• No outbound proxy or egress isolation. The server connects directly to allowed hosts.

Operational

• No persistent state. Connection pools are per process, and there's no hot reload of configuration; restart to apply changes.
• Per-IP rate limit only.
• The audit log is stderr-only.
• No first-party metrics endpoint; instrument at the reverse-proxy or sidecar layer if needed.
• Public preview. The API surface and configuration may evolve.

Compatibility

• Requires Node.js 20+.
• Validated against Azure DocumentDB. Other MongoDB-compatible engines might work where they implement the same wire-protocol commands but aren't validated in CI.
• No published npm package yet. Install from source (git clone https://github.com/microsoft/documentdb-mcp.git && npm install && npm run build) or run directly with npx -y github:microsoft/documentdb-mcp.

Related content

• Azure DocumentDB integrations for AI applications
• DocumentDB MCP server (GitHub)
• Model Context Protocol