documentdb-mcp-setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# DocumentDB MCP Server Setup

This skill guides users through wiring the
[`microsoft/documentdb-mcp`](https://github.com/microsoft/documentdb-mcp)
server into an agentic client and pointing it at Azure DocumentDB (or another
MongoDB-compatible endpoint).

The DocumentDB MCP server is **stateless** and **administrator-controlled**:
backend connection details live in a `CONNECTION_PROFILES` JSON map defined in
the MCP client's config. Tools never accept a connection string as a runtime
argument — they reference a named profile via `connection_profile`.

## 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, or token into
   the chat.** Always instruct the user to add the value directly to their
   local MCP config file themselves (or run the bundled installer, which
   prompts via stdin instead of chat).
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 your
   client's MCP config instead," and continue with placeholders 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.**
4. **Never write the credential to any file the agent itself creates or
   edits.** The agent only writes 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.

## Fastest path: bundled installer

If the user wants the quickest path and is willing to run a script, point them
at the kit's installer, which installs both this skill pack and the MCP server
into every detected client in one command:

```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.ps1 | iex
```

The installer prompts for a connection string, writes it as the `default`
profile, and configures all detected clients. The rest of this skill covers
the manual path (and is also the right reference when the installer fails or
the user wants to customize).

## Manual setup overview

Setup is per-client. For each client the user has installed:

1. Make sure Node.js 20+ is available (the MCP server runs on Node).
2. Find that client's MCP config file.
3. Add a `DocumentDB` server entry that launches the upstream MCP server and
   passes `CONNECTION_PROFILES` (and `TRANSPORT=stdio` + `AUTH_REQUIRED=false`
   + `TRUST_LOCAL_STDIO=true` for local stdio use).
4. Restart the client.

## Step 1: Confirm prerequisites

```bash
node --version   # must be >= 20
git --version    # required by `npx -y github:microsoft/documentdb-mcp`
```

If either is missing, install them before continuing.

## Step 2: Pick the connection target

| Option | When to use | Example URI |
|---|---|---|
| **A. Azure DocumentDB** | Production / cloud dev | `mongodb+srv://<user>:<pw>@<cluster>.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256` |
| **B. Local MongoDB / DocumentDB** | Local dev | `mongodb://localhost:27017` |
| **C. Custom MongoDB-compatible** | Atlas, self-hosted, third-party | `mongodb://<user>:<pw>@host:port/?tls=true` |

**Azure DocumentDB connection string:** Azure portal → your DocumentDB cluster
→ **Settings** → **Connection strings**. Replace `<username>` / `<password>`
with database user credentials. TLS is required (`tls=true` must be present).

## Step 3: Pick a transport

- **`stdio`** (default, recommended) — the client launches the server as a
  subprocess. Use this for every client below.
- **`streamable-http`** — only for browser clients or custom HTTP integrations
  where you have a separate, long-running server with Entra-authenticated
  bearer tokens. Not covered here; see the upstream README.

For stdio, set `AUTH_REQUIRED=false` and `TRUST_LOCAL_STDIO=true`.
The server defaults `AUTH_REQUIRED=true` and **exits at startup** unless
`ENTRA_TENANT_ID` / `ENTRA_AUDIENCE` are set, even for stdio.
(`TRUST_LOCAL_STDIO` was named `ALLOW_UNAUTHENTICATED_STDIO` before
[microsoft/documentdb-mcp#83](https://github.com/microsoft/documentdb-mcp/pull/83)
— if you're on an older server build, use that name instead.)

**`AUTH_REQUIRED=false` does not weaken your cluster's auth.** It gates only
the Entra-JWT bearer-token check on the MCP server's HTTP/SSE transport —
i.e., calls from the MCP client to this server. It is fully independent
from how the MCP server talks to your DocumentDB cluster: SCRAM
username/password (from the connection-string URI) and Entra-to-cluster
tokens (`authMode: "entra"`) flow through `CONNECTION_PROFILES` and stay
active regardless of `AUTH_REQUIRED`. TLS to the cluster (`tls=true`),
capability gates (`ENABLE_*_TOOLS`), and tool-tier authorization are also
unaffected.

This setup is safe **only because `TRANSPORT=stdio`**: the MCP server runs
as a subprocess of the trusted local client — no network listener is
opened. If you ever switch `TRANSPORT` to `streamable-http` or `sse`, set
`AUTH_REQUIRED=true` and provide the Entra tenant/audience, or the `/mcp`
endpoint will be exposed unauthenticated.

From Azure/documentdb-agent-kit, MIT.

More from Azure/documentdb-agent-kit