mongodb-mcp-setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# MongoDB MCP Server Setup

This skill guides users through configuring the MongoDB MCP server for use with an agentic client.

## Overview

The MongoDB MCP server requires authentication. Users have three options:

1. **Connection String** (Option A): Direct connection to a specific cluster
   - Quick setup for single cluster
   - Requires `MDB_MCP_CONNECTION_STRING` environment variable

2. **Service Account Credentials** (Option B): MongoDB Atlas Admin API access
   - **Recommended for Atlas users** - simplifies authentication and data access
   - Access to Atlas Admin API and dynamic cluster connection via `atlas-connect-cluster`
   - No manual DB user credential management
   - Requires `MDB_MCP_API_CLIENT_ID` and `MDB_MCP_API_CLIENT_SECRET` environment variables

3. **Atlas Local** (Option C): Local development with Docker
   - **Best for local testing** - zero configuration required
   - Runs Atlas locally in Docker, requires Docker installed
   - No credentials or cloud cluster access

This is an interactive step-by-step guide. The agent detects the user's environment and provides tailored instructions, but **never asks for or handles credentials** — users add those directly to their shell profile or agentic client config in Step 5. Make this clear to the user whenever credentials come up in Steps 3a and 3b.

## Step 0: Detect Client

Before anything else, determine which agentic client the user is running. This controls how credentials are configured in Step 1 and Step 5.

Run:

```bash
env | grep "^CODEX_"
```

- **If no `CODEX_*` variables are present** → the user is running a **shell-based client** (Claude, Cursor, Gemini CLI, Copilot CLI, etc.). Credentials are configured via shell profile environment variables.
- **If any `CODEX_*` variables are present** → the user is running **Codex**. Credentials are stored in `~/.codex/config.toml` (macOS/Linux) or `%USERPROFILE%\.codex\config.toml` (Windows), not in shell environment variables. The desktop app does not inherit shell env vars when launched from Finder, Launchpad, or the Windows Start menu.

Carry this **client type** (Codex vs. shell-based) forward through every subsequent step.

## Step 1: Check Existing Configuration

Check whether credentials are already configured.

**For shell-based clients** — check the current environment:

```bash
env | grep "^MDB_MCP" | sed '/^MDB_MCP_READ_ONLY=/!s/=.*/=[set]/'
```

**For Codex** — search `~/.codex/config.toml` (macOS/Linux) or `%USERPROFILE%\.codex\config.toml` (Windows):

```bash
grep -E 'MDB_MCP_(CONNECTION_STRING|API_CLIENT_ID|API_CLIENT_SECRET|READ_ONLY)' ~/.codex/config.toml 2>/dev/null | sed '/MDB_MCP_READ_ONLY/!s/[[:space:]]*=[[:space:]].*/ = "[set]"/'
```

**Interpretation (both):**

- If `MDB_MCP_CONNECTION_STRING` appears → connection string auth is configured
- If both `MDB_MCP_API_CLIENT_ID` and `MDB_MCP_API_CLIENT_SECRET` appear → service account auth is configured. If only one is present, treat it as incomplete.
- If `MDB_MCP_READ_ONLY` appears → read-only mode is enabled

**Partial Configuration Handling:**

- User wants to add read-only to existing setup (has auth, no read-only flag) → skip to Step 4
- User wants to switch authentication methods → explain they should remove the old credentials first (from `config.toml` for Codex, from their shell profile for shell-based clients), then proceed with Steps 2–5
- User wants to update credentials → skip to Step 5

**Important**: If the user wants an Atlas Admin API action (managing clusters, creating users, performance advisor) but only has `MDB_MCP_CONNECTION_STRING`, explain they need service account credentials and offer to walk through setup.

## Step 2: Present Configuration Options

If no valid configuration exists, present the options:

**Connection String (Option A)** — Best for:

- Single cluster access
- Existing database credentials
- Self-hosted MongoDB or no Atlas Admin API needs

**Service Account Credentials (Option B)** — Best for:

- MongoDB Atlas users (recommended)
- Multi-cluster switching
- Atlas Admin API access (cluster management, user creation, performance monitoring)

**Atlas Local (Option C)** — Best for:

- Local development/testing without cloud setup
- Fastest setup with Docker, no credentials required

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

## Step 3a: Connection String Setup

If the user chooses Option A:

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

Explain where and how to obtain their connection string:

**For MongoDB Atlas:**

1. Go to [cloud.mongodb.com](https://cloud.mongodb.com)
2. Select your cluster → click **Connect**
3. Choose **Drivers** or **Shell** → copy the connection string
4. Replace `<username>` and `<password>` with your database user credentials

**For self-hosted MongoDB:**

- The connection string is typically configured by your DBA or in your application config
- Format: `mongodb://username:password@host:port/database`

**Expected formats:**

- `mongodb://username:password@host:port/database`
- `mongodb+srv://username:password@cluster.mongodb.net/database`
- `mongodb://host:port` (local, no auth)

From mongodb/agent-skills, Apache-2.0.

More from mongodb/agent-skills