documentdb-mcp-setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

## 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):

```bash
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](https://portal.azure.com)
2. Navigate to your Azure DocumentDB cluster
3. In the left menu, select **Settings** → **Connection strings**
4. Copy the connection string — it will look like:
   `mongodb+srv://<username>:<password>@<cluster-name>.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256`
5. Replace `<username>` and `<password>` with your database user credentials

**Expected formats:**

- `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. Ensure `tls=true` is in the
connection string.

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

```bash
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).

From khelanmodi/documentdb-agent-kit, MIT.

More from khelanmodi/documentdb-agent-kit