mongodb-mcp-setup

Name: mongodb-mcp-setup
Author: mongodb

161stars29forks

How to install mongodb-mcp-setup?

mongodb/agent-skills/mongodb-mcp-setup

$npx -y skills add mongodb/agent-skills --skill mongodb-mcp-setup

Installs into the current project.

Summary

Guide users through configuring key MongoDB MCP server options. Use this skill when a user has the MongoDB MCP server installed but hasn't configured the required environment variables, or when they ask about connecting to MongoDB/Atlas and don't have the credentials set up.

Files · 1

View on GitHub

SKILL.md

1	# MongoDB MCP Server Setup
2
3	This skill guides users through configuring the MongoDB MCP server for use with an agentic client.
4
5	## Overview
6
7	The MongoDB MCP server requires authentication. Users have three options:
8
9	1. Connection String (Option A): Direct connection to a specific cluster
10	- Quick setup for single cluster
11	- Requires `MDB_MCP_CONNECTION_STRING` environment variable
12
13	2. Service Account Credentials (Option B): MongoDB Atlas Admin API access
14	- Recommended for Atlas users - simplifies authentication and data access
15	- Access to Atlas Admin API and dynamic cluster connection via `atlas-connect-cluster`
16	- No manual DB user credential management
17	- Requires `MDB_MCP_API_CLIENT_ID` and `MDB_MCP_API_CLIENT_SECRET` environment variables
18
19	3. Atlas Local (Option C): Local development with Docker
20	- Best for local testing - zero configuration required
21	- Runs Atlas locally in Docker, requires Docker installed
22	- No credentials or cloud cluster access
23
24	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.
25
26	## Step 0: Detect Client
27
28	Before anything else, determine which agentic client the user is running. This controls how credentials are configured in Step 1 and Step 5.
29
30	Run:
31
32	```bash
33	env \| grep "^CODEX_"
34	```
35
36	- *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.
37	- *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.
38
39	Carry this client type (Codex vs. shell-based) forward through every subsequent step.
40
41	## Step 1: Check Existing Configuration
42
43	Check whether credentials are already configured.
44
45	For shell-based clients — check the current environment:
46
47	```bash
48	env \| grep "^MDB_MCP" \| sed '/^MDB_MCP_READ_ONLY=/!s/=.*/=[set]/'
49	```
50
51	For Codex — search `~/.codex/config.toml` (macOS/Linux) or `%USERPROFILE%\.codex\config.toml` (Windows):
52
53	```bash
54	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]"/'
55	```
56
57	Interpretation (both):
58
59	- If `MDB_MCP_CONNECTION_STRING` appears → connection string auth is configured
60	- 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.
61	- If `MDB_MCP_READ_ONLY` appears → read-only mode is enabled
62
63	Partial Configuration Handling:
64
65	- User wants to add read-only to existing setup (has auth, no read-only flag) → skip to Step 4
66	- 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
67	- User wants to update credentials → skip to Step 5
68
69	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.
70
71	## Step 2: Present Configuration Options
72
73	If no valid configuration exists, present the options:
74
75	Connection String (Option A) — Best for:
76
77	- Single cluster access
78	- Existing database credentials
79	- Self-hosted MongoDB or no Atlas Admin API needs
80
81	Service Account Credentials (Option B) — Best for:
82
83	- MongoDB Atlas users (recommended)
84	- Multi-cluster switching
85	- Atlas Admin API access (cluster management, user creation, performance monitoring)
86
87	Atlas Local (Option C) — Best for:
88
89	- Local development/testing without cloud setup
90	- Fastest setup with Docker, no credentials required
91
92	Ask the user which option they'd like to proceed with.
93
94	## Step 3a: Connection String Setup
95
96	If the user chooses Option A:
97
98	### 3a.1: Explain How to Find the Connection String
99
100	Explain where and how to obtain their connection string:
101
102	For MongoDB Atlas:
103
104	1. Go to [cloud.mongodb.com](https://cloud.mongodb.com)
105	2. Select your cluster → click

People who liked this also viewed

6 picks

Type

mongodb-mcp-setup

161stars29forks

View on GitHub

How to install mongodb-mcp-setup?

mongodb/agent-skills/mongodb-mcp-setup

$npx -y skills add mongodb/agent-skills --skill mongodb-mcp-setup

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# MongoDB MCP Server Setup
2
3	This skill guides users through configuring the MongoDB MCP server for use with an agentic client.
4
5	## Overview
6
7	The MongoDB MCP server requires authentication. Users have three options:
8
9	1. Connection String (Option A): Direct connection to a specific cluster
10	- Quick setup for single cluster
11	- Requires `MDB_MCP_CONNECTION_STRING` environment variable
12
13	2. Service Account Credentials (Option B): MongoDB Atlas Admin API access
14	- Recommended for Atlas users - simplifies authentication and data access
15	- Access to Atlas Admin API and dynamic cluster connection via `atlas-connect-cluster`
16	- No manual DB user credential management
17	- Requires `MDB_MCP_API_CLIENT_ID` and `MDB_MCP_API_CLIENT_SECRET` environment variables
18
19	3. Atlas Local (Option C): Local development with Docker
20	- Best for local testing - zero configuration required
21	- Runs Atlas locally in Docker, requires Docker installed
22	- No credentials or cloud cluster access
23
24	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.
25
26	## Step 0: Detect Client
27
28	Before anything else, determine which agentic client the user is running. This controls how credentials are configured in Step 1 and Step 5.
29
30	Run:
31
32	```bash
33	env \| grep "^CODEX_"
34	```
35
36	- *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.
37	- *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.
38
39	Carry this client type (Codex vs. shell-based) forward through every subsequent step.
40
41	## Step 1: Check Existing Configuration
42
43	Check whether credentials are already configured.
44
45	For shell-based clients — check the current environment:
46
47	```bash
48	env \| grep "^MDB_MCP" \| sed '/^MDB_MCP_READ_ONLY=/!s/=.*/=[set]/'
49	```
50
51	For Codex — search `~/.codex/config.toml` (macOS/Linux) or `%USERPROFILE%\.codex\config.toml` (Windows):
52
53	```bash
54	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]"/'
55	```
56
57	Interpretation (both):
58
59	- If `MDB_MCP_CONNECTION_STRING` appears → connection string auth is configured
60	- 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.
61	- If `MDB_MCP_READ_ONLY` appears → read-only mode is enabled
62
63	Partial Configuration Handling:
64
65	- User wants to add read-only to existing setup (has auth, no read-only flag) → skip to Step 4
66	- 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
67	- User wants to update credentials → skip to Step 5
68
69	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.
70
71	## Step 2: Present Configuration Options
72
73	If no valid configuration exists, present the options:
74
75	Connection String (Option A) — Best for:
76
77	- Single cluster access
78	- Existing database credentials
79	- Self-hosted MongoDB or no Atlas Admin API needs
80
81	Service Account Credentials (Option B) — Best for:
82
83	- MongoDB Atlas users (recommended)
84	- Multi-cluster switching
85	- Atlas Admin API access (cluster management, user creation, performance monitoring)
86
87	Atlas Local (Option C) — Best for:
88
89	- Local development/testing without cloud setup
90	- Fastest setup with Docker, no credentials required
91
92	Ask the user which option they'd like to proceed with.
93
94	## Step 3a: Connection String Setup
95
96	If the user chooses Option A:
97
98	### 3a.1: Explain How to Find the Connection String
99
100	Explain where and how to obtain their connection string:
101
102	For MongoDB Atlas:
103
104	1. Go to [cloud.mongodb.com](https://cloud.mongodb.com)
105	2. Select your cluster → click

People who liked this also viewed

6 picks

Type