documentdb-mcp-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DocumentDB MCP Server Setup

DocumentDB MCP 服务器配置指南

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

本技能指导用户完成DocumentDB MCP服务器的配置，使其可与智能客户端配合使用，对接Azure DocumentDB。

Overview

概述

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

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

DocumentDB MCP服务器需要连接字符串以接入你的Azure DocumentDB集群。用户有三种配置选项：

Azure DocumentDB连接字符串（选项A）：直接连接至Azure DocumentDB集群
- 推荐大多数用户使用
- 需要配置
```
DOCUMENTDB_URI
```
  环境变量
- 连接字符串可从Azure门户获取
本地MongoDB（选项B）：连接至本地MongoDB实例用于开发
- 最适合本地测试——所需配置极少
- 使用默认地址
```
mongodb://localhost:27017
```
- 无需Azure凭证
自定义MongoDB兼容端点（选项C）：连接至任意MongoDB兼容数据库
- 适用于自托管MongoDB部署、其他DocumentDB兼容服务或MongoDB Atlas
- 需要配置
```
DOCUMENTDB_URI
```
  环境变量并填入自定义连接字符串

本指南为交互式分步教程，智能体将检测用户环境并提供定制化指导。

Step 1: Check Existing Configuration

步骤1：检查现有配置

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)

开始配置前，先检查用户是否已配置所需环境变量。

运行以下命令检查现有配置（掩码处理值以避免泄露凭证）：

bash

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

结果解读：

若
```
DOCUMENTDB_URI
```
已设置→连接已配置完成
若
```
TRANSPORT
```
已设置→传输模式已配置
若两者均未设置→继续完成完整配置

部分配置的处理方式：

用户已设置
```
DOCUMENTDB_URI
```
且仅需更改传输模式→跳转至步骤4
用户想要切换连接目标→继续步骤2至5
用户想要更新凭证→跳转至步骤5（配置文件编辑说明）

Step 2: Present Configuration Options

步骤2：展示配置选项

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.

若不存在有效配置，展示以下选项：

Azure DocumentDB（选项A）——最适合：

使用Azure DocumentDB的生产与开发环境
完整的MongoDB有线协议兼容性
与Azure集成的托管数据库

本地MongoDB（选项B）——最适合：

无需云服务的本地开发与测试
配置最快，无需凭证
仅使用
```
mongodb://localhost:27017
```

自定义端点（选项C）——最适合：

自托管MongoDB部署
MongoDB Atlas或其他MongoDB兼容服务
非标准连接配置

询问用户想要选择哪个选项继续。

Step 3a: Azure DocumentDB Setup

步骤3a：Azure DocumentDB配置

If the user chooses Option A:

若用户选择选项A：

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

3a.1：说明如何获取连接字符串

Go to the Azure portal
Navigate to your Azure DocumentDB cluster
In the left menu, select Settings → Connection strings

Copy the connection string — it will look like:

mongodb+srv://<username>:<password>@<cluster-name>.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256

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

访问Azure门户
导航至你的Azure DocumentDB集群
在左侧菜单中选择设置→连接字符串

复制连接字符串——格式如下：

mongodb+srv://<username>:<password>@<cluster-name>.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256

将
```
<username>
```
和
```
<password>
```
替换为你的数据库用户凭证

预期格式：

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

重要提示：Azure DocumentDB要求启用TLS。确保连接字符串中包含

tls=true

。

继续步骤4（配置传输模式）。

Step 3b: Local MongoDB Setup

步骤3b：本地MongoDB配置

If the user chooses Option B:

若用户选择选项B：

3b.1: Verify Local MongoDB is Running

3b.1：验证本地MongoDB是否运行

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

Proceed to Step 4 (Configure Transport Mode).

bash

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

若MongoDB未安装或未运行，引导用户访问： https://www.mongodb.com/docs/manual/installation/

将使用默认连接字符串

mongodb://localhost:27017

，无需配置

DOCUMENTDB_URI

环境变量（为服务器默认值）。

继续步骤4（配置传输模式）。

Step 3c: Custom Endpoint Setup

步骤3c：自定义端点配置

If the user chooses Option C:

Ask the user for their MongoDB-compatible connection string.

Expected formats:

mongodb://<user>:<password>@host:port/database

mongodb+srv://<user>:<password>@host/database

```
mongodb://host:port
```
(no auth)

Proceed to Step 4 (Configure Transport Mode).

若用户选择选项C：

询问用户提供其MongoDB兼容连接字符串。

预期格式：

mongodb://<user>:<password>@host:port/database

mongodb+srv://<user>:<password>@host/database

```
mongodb://host:port
```
（无认证）

继续步骤4（配置传输模式）。

Step 4: Configure Transport Mode

步骤4：配置传输模式

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

DocumentDB MCP服务器支持两种传输模式：

stdio（默认）——推荐用于大多数MCP客户端集成：

通过标准输入/输出流通信
无需额外配置
最适合Claude、Cursor、Copilot CLI及大多数编码智能体

streamable-http——适用于基于HTTP的集成：

作为HTTP服务器运行
可配置主机与端口
最适合基于浏览器的客户端或自定义HTTP集成

对于大多数用户，stdio是正确选择。仅当明确需要基于HTTP的访问时，才选择streamable-http。

若选择streamable-http，还需配置：

```
HOST
```
——服务器主机（默认值：
```
localhost
```
）
```
PORT
```
——服务器端口（默认值：
```
8070
```
）

继续步骤5（更新Shell配置文件）。

Step 5: Update Shell Profile

步骤5：更新Shell配置文件

Help the user add the environment variables to their shell profile. Do not ask for or handle credentials — provide exact instructions so the user can add them directly.

帮助用户将环境变量添加至其Shell配置文件。请勿询问或处理凭证——提供明确说明，让用户自行添加。

5.1: Detect Shell and Profile File

5.1：检测Shell与配置文件

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

bash

echo $SHELL

Based on the result, identify the appropriate profile file.

若用户使用Windows，默认假设为PowerShell，但需请用户确认。对于Unix/macOS，检测Shell：

bash

echo $SHELL

根据结果确定对应的配置文件。

5.2: Show the Exact Snippet to Add

5.2：展示需添加的代码片段

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

bash

undefined

告知用户将连接字符串存储在专用的

~/.documentdb-env

文件中。这样可避免凭证出现在默认情况下常被组/全局可读的文件中，同时防止意外提交至git。

步骤1：创建/编辑

~/.documentdb-env

（例如：

nano ~/.documentdb-env

）并添加：

对于Azure DocumentDB（选项A）：

bash

undefined

DocumentDB MCP Server Configuration

export DOCUMENTDB_URI="<paste-your-connection-string-here>"


**For Custom Endpoint (Option C):**

```bash

export DOCUMENTDB_URI="<paste-your-connection-string-here>"


**对于自定义端点（选项C）：**

```bash

DocumentDB MCP Server Configuration

export DOCUMENTDB_URI="<paste-your-connection-string-here>"


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

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

Step 2: Restrict permissions on the file:

bash

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:

bash

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

export DOCUMENTDB_URI="<paste-your-connection-string-here>"


**若选择了streamable-http传输模式（步骤4），还需添加：**

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

步骤2：限制文件权限：

bash

chmod 600 ~/.documentdb-env

步骤3：从Shell配置文件中引入该文件。告知用户打开其配置文件（例如：

code ~/.zshrc

、

nano ~/.zshrc

）并添加：

bash

source ~/.documentdb-env

根据检测到的Shell调整语法（例如：对于fish：

bass source ~/.documentdb-env

或直接使用

set -x

设置变量；对于PowerShell：点源引入

.ps1

文件）。

5.3: After Editing — Reload and Verify

5.3：编辑完成后——重新加载并验证

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

Reload the profile:

bash

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

Verify the variables are set (masking values):

bash

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

用户保存文件后，提供重新加载与验证的命令：

重新加载配置文件：

bash

source ~/.zshrc  # 根据用户的配置文件路径调整

验证变量已设置（掩码处理值）：

bash

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

预期输出应显示用户刚添加的变量名称。

继续步骤6（后续操作）。

Step 6: Next Steps

步骤6：后续操作

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

对于选项A与C（Azure DocumentDB / 自定义端点）：

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

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

重启智能客户端：完全退出客户端，然后在终端中运行
```
source <profile-file>
```
（例如：
```
source ~/.zshrc
```
）以加载新变量。从同一Shell会话中打开客户端，使其继承环境变量。
验证MCP服务器：重启后，通过执行DocumentDB操作进行测试：
- 尝试
```
list_databases
```
  查看可用数据库
- 尝试
```
get_connection_status
```
  验证连接状态

使用工具：

数据库操作：
```
list_databases
```
、
```
db_stats
```
、
```
get_db_info
```
集合操作：
```
collection_stats
```
、
```
sample_documents
```
文档操作：
```
find_documents
```
、
```
count_documents
```
、
```
aggregate
```
索引操作：
```
list_indexes
```
、
```
index_stats
```
、
```
create_index
```

查询优化：

optimize_find_query

、

explain_aggregate_query

For Option B (Local MongoDB):

对于选项B（本地MongoDB）：

Ready to use: No additional configuration needed if using the default connection string.
Start the MCP server: The server will connect to
```
mongodb://localhost:27017
```
by default.
Verify: Try
```
list_databases
```
to confirm connectivity.

即可使用：若使用默认连接字符串，无需额外配置。
启动MCP服务器：服务器将默认连接至
```
mongodb://localhost:27017
```
。
验证：尝试
```
list_databases
```
确认连接性。

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: Verify username and password in the connection string are correct; check that the user exists in 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
```

执行
source
后变量未显示：检查配置文件路径并确认文件已保存
客户端未获取到变量：确保完全重启（退出并重新打开），而非仅重新加载
Azure DocumentDB出现TLS错误：确保连接字符串中包含
```
tls=true
```
认证错误：验证连接字符串中的用户名与密码是否正确；检查用户是否存在于Azure门户中
连接超时：检查网络连通性与防火墙规则；Azure DocumentDB可能需要在Azure门户的网络设置中允许你的IP地址
fish/PowerShell：语法不同——使用
```
set -x
```
（fish）或
```
$env:
```
（PowerShell）替代
```
export
```