documentdb-mcp-setup

name	documentdb-mcp-setup
description	Guide users through configuring the DocumentDB MCP server for Azure DocumentDB. Use this skill when a user has the DocumentDB MCP server installed but hasn't configured the required environment variables, or when they ask about connecting to Azure DocumentDB and don't have the credentials set up.

DocumentDB MCP Server Setup

This skill guides users through configuring the DocumentDB MCP server for use with an agentic client, targeting Azure DocumentDB.

Overview

The DocumentDB MCP server requires a connection string to your Azure DocumentDB cluster. Users have three options:

1. Azure DocumentDB Connection String (Option A): Direct connection to an Azure DocumentDB cluster

   • Recommended for most users
   • Requires DOCUMENTDB_URI environment variable
   • Connection string from Azure portal

2. Local MongoDB (Option B): Connect to a local MongoDB instance for development

   • Best for local testing — minimal configuration required
   • Uses default mongodb://localhost:27017
   • No Azure credentials needed

3. Custom MongoDB-compatible endpoint (Option C): Connect to any MongoDB-compatible database

   • For self-hosted MongoDB, other DocumentDB-compatible services, or MongoDB Atlas
   • Requires DOCUMENTDB_URI environment variable with custom connection string

This is an interactive step-by-step guide. The agent detects the user's environment and provides tailored instructions.

Safety: Never Receive Credentials In-Chat

The DocumentDB connection string is a secret — it contains a username and password that grant database access. The agent MUST follow these rules:

1. Never ask the user to paste a connection string, password, token, or any other credential into the chat. Always instruct the user to write the value directly into a local file (~/.documentdb-env or a PowerShell profile) themselves.
2. Never read, echo, log, or repeat back a credential the user pasted by mistake. If the user pastes one anyway, respond with: "I won't process that value — please delete it from the chat history and add it directly to ~/.documentdb-env instead," and continue with placeholder instructions only. The agent itself cannot remove messages it has already received — only the user can delete the message from their chat history.
3. Never run a shell command that would print a credential to stdout. All verification commands in this skill mask the value (e.g. [set]).
4. Never write the credential to any file the agent itself creates or edits. The agent only writes the placeholder [USER]:[PASSWORD]@... (square brackets defeat the mongodb://[^:]+:[^@]+@ secret-scanner regex); the user replaces it locally.
5. Never include a credential in a generated explanation, summary, commit message, or example. Use <redacted> if you must reference its position.

If any step below appears to require a credential value, treat it as a placeholder for the user to fill in locally.

Step 1: Check Existing Configuration

Before starting the setup, check if the user already has the required environment variables configured.

Run this command to check for existing configuration (masking values to avoid exposing credentials):

env | grep "^DOCUMENTDB_URI\|^TRANSPORT\|^HOST\|^PORT" | sed 's/DOCUMENTDB_URI=.*/DOCUMENTDB_URI=[set]/'

Interpretation:

• If DOCUMENTDB_URI is set → connection is already configured
• If TRANSPORT is set → transport mode is configured
• If neither is set → proceed with full setup

Partial Configuration Handling:

• User already has DOCUMENTDB_URI set and just wants to change transport → skip to Step 4
• User wants to switch connection targets → proceed with Steps 2–5
• User wants to update credentials → skip to Step 5 (profile editing instructions)

Step 2: Present Configuration Options

If no valid configuration exists, present the options:

Azure DocumentDB (Option A) — Best for:

• Production and development with Azure DocumentDB
• Full MongoDB wire protocol compatibility
• Managed database with Azure integration

Local MongoDB (Option B) — Best for:

• Local development and testing without cloud setup
• Fastest setup, no credentials required
• Just uses mongodb://localhost:27017

Custom Endpoint (Option C) — Best for:

• Self-hosted MongoDB deployments
• MongoDB Atlas or other MongoDB-compatible services
• Non-standard connection configurations

Ask the user which option they'd like to proceed with.

Step 3a: Azure DocumentDB Setup

If the user chooses Option A:

3a.1: Explain How to Find the Connection String

1. Go to the Azure portal
2. Navigate to your Azure DocumentDB cluster
3. In the left menu, select Settings → Connection strings
4. Copy the connection string — its shape will be: mongodb+srv://[USER]:[PASSWORD]@<cluster-name>.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256
5. The user fills in their own username and password locally (see Step 5). Do not paste the completed connection string into this chat.

Expected shapes (placeholders only — do not substitute real values here):

• mongodb+srv://[USER]:[PASSWORD]@cluster.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256
• mongodb://[USER]:[PASSWORD]@cluster.mongocluster.cosmos.azure.com:10255/?tls=true&authMechanism=SCRAM-SHA-256

Important: Azure DocumentDB requires TLS. The user should ensure tls=true is in their connection string when they save it locally.

Proceed to Step 4 (Configure Transport Mode).

Step 3b: Local MongoDB Setup

If the user chooses Option B:

3b.1: Verify Local MongoDB is Running

mongosh --eval "db.runCommand({ping: 1})" 2>/dev/null || echo "MongoDB not reachable"

If MongoDB is not installed or running, direct them to: https://www.mongodb.com/docs/manual/installation/

The default connection string mongodb://localhost:27017 will be used. No DOCUMENTDB_URI environment variable is needed (it's the server default).

Proceed to Step 4 (Configure Transport Mode).

Step 3c: Custom Endpoint Setup

If the user chooses Option C:

Do NOT ask the user to paste their connection string into the chat. A connection string is a credential. Instead, tell the user the supported shapes so they can recognize their own value and add it directly to their local ~/.documentdb-env file in Step 5. Do not paste the completed connection string into this chat.

Supported shapes (placeholders only):

• mongodb://[USER]:[PASSWORD]@host:port/database
• mongodb+srv://[USER]:[PASSWORD]@host/database
• mongodb://host:port (no auth)

If the user pastes a real connection string anyway, refuse to process it (see the Safety section) and continue to Step 4 with placeholders only.

Proceed to Step 4 (Configure Transport Mode).

Step 4: Configure Transport Mode

The DocumentDB MCP server supports two transport modes:

stdio (Default) — Recommended for most MCP client integrations:

• Communicates over standard input/output streams
• No additional configuration needed
• Best for Claude, Cursor, Copilot CLI, and most coding agents

streamable-http — For HTTP-based integrations:

• Runs as an HTTP server
• Configurable host and port
• Best for browser-based clients or custom HTTP integrations

For most users, stdio is the right choice. Only choose streamable-http if you specifically need HTTP-based access.

If streamable-http is chosen, also configure:

• HOST — Server host (default: localhost)
• PORT — Server port (default: 8070)

Proceed to Step 5 (Update Shell Profile).

Step 5: Update Shell Profile

Help the user add the environment variables to their shell profile.

Strict rule (see Safety section): the agent must never ask the user to paste their connection string into the chat, and must never write the actual credential value into any file. The agent only emits the placeholder <paste-your-connection-string-here>; the user opens the file in their own editor and substitutes the real value locally.

5.1: Detect Shell and Profile File

If the user is on Windows, assume PowerShell but ask the user to confirm. For Unix/macOS, detect the shell:

echo $SHELL

Based on the result, identify the appropriate profile file.

5.2: Show the Exact Snippet to Add

Tell the user to store the connection string in a dedicated ~/.documentdb-env file. This keeps credentials out of files that are often group/world readable by default and prevents accidentally committing them to git.

Step 1: Create/edit ~/.documentdb-env (e.g., nano ~/.documentdb-env) and add:

For Azure DocumentDB (Option A):

# DocumentDB MCP Server Configuration
export DOCUMENTDB_URI="<paste-your-connection-string-here>"

For Custom Endpoint (Option C):

# DocumentDB MCP Server Configuration
export DOCUMENTDB_URI="<paste-your-connection-string-here>"

If streamable-http transport was chosen (Step 4), also add:

export TRANSPORT="streamable-http"
export HOST="localhost"
export PORT="8070"

Step 2: Restrict permissions on the file:

chmod 600 ~/.documentdb-env

Step 3: Source the file from the shell profile. Tell the user to open their profile file (e.g., code ~/.zshrc, nano ~/.zshrc) and add:

source ~/.documentdb-env

Adjust syntax for the detected shell (e.g., for fish: bass source ~/.documentdb-env or set variables directly with set -x; for PowerShell: dot-source a .ps1 file instead).

5.3: After Editing — Reload and Verify

Once the user has saved the file, provide the commands to reload and verify:

Reload the profile:

source ~/.zshrc  # adjust path to match their profile file

Verify the variables are set (masking values):

env | grep "^DOCUMENTDB_URI\|^TRANSPORT\|^HOST\|^PORT" | sed 's/DOCUMENTDB_URI=.*/DOCUMENTDB_URI=[set]/'

Expected output should show the variable name(s) they just added.

Proceed to Step 6 (Next Steps).

Step 6: Next Steps

For Options A & C (Azure DocumentDB / Custom Endpoint):

1. Restart the agentic client: Fully quit the client, then in your terminal run source <profile-file> (e.g., source ~/.zshrc) to load the new variables. Open the client from that same shell session so it inherits the environment.

2. Verify MCP Server: After restart, test by performing a DocumentDB operation:

   • Try list_databases to see available databases
   • Try get_connection_status to verify the connection

3. Using the Tools:

   • Database operations: list_databases, db_stats, get_db_info
   • Collection operations: collection_stats, sample_documents
   • Document operations: find_documents, count_documents, aggregate
   • Index operations: list_indexes, index_stats, create_index
   • Query optimization: optimize_find_query, explain_aggregate_query

For Option B (Local MongoDB):

1. Ready to use: No additional configuration needed if using the default connection string.

2. Start the MCP server: The server will connect to mongodb://localhost:27017 by default.

3. Verify: Try list_databases to confirm connectivity.

Troubleshooting

• Variables not appearing after source: Check the profile file path and confirm the file was saved
• Client doesn't pick up variables: Ensure full restart (quit + reopen), not just a reload
• TLS errors with Azure DocumentDB: Ensure tls=true is in the connection string
• Authentication errors: Ask the user to re-check their credentials locally in ~/.documentdb-env (never in chat) and to confirm the database user exists in the Azure portal
• Connection timeout: Check network connectivity and firewall rules; Azure DocumentDB may require allowlisting your IP in the Azure portal under Networking settings
• fish/PowerShell: Syntax differs — use set -x (fish) or $env: (PowerShell) instead of export