npx claudepluginhub fcakyon/claude-codex-settings --plugin mongodb-skillsThis skill uses the workspace's default tool permissions.
This skill guides users through configuring the MongoDB MCP server for use with an agentic client.
Guides configuration of MongoDB MCP server via connection strings, Atlas API credentials, or local Docker. Useful when env vars missing post-install or for MongoDB/Atlas connections.
Troubleshoots MongoDB connection errors including authentication failures, invalid strings, authSource issues, and timeouts with quick fixes like IP whitelisting and MCP setup.
Verifies MongoDB Atlas setup for Next.js and NestJS apps. Checks connection strings, environment variables, pooling, IP whitelists, driver installation, and common issues.
Share bugs, ideas, or general feedback.
This skill guides users through configuring the MongoDB MCP server for use with an agentic client.
The MongoDB MCP server requires authentication. Users have three options:
Connection String (Option A): Direct connection to a specific cluster
MDB_MCP_CONNECTION_STRING environment variableService Account Credentials (Option B): MongoDB Atlas Admin API access
atlas-connect-clusterMDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET environment variablesAtlas Local (Option C): Local development with Docker
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 in Step 5. Make this clear to the user whenever credentials come up in Steps 3a and 3b.
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):
env | grep "^MDB_MCP" | sed '/^MDB_MCP_READ_ONLY=/!s/=.*/=[set]/'
Interpretation:
MDB_MCP_CONNECTION_STRING is set → connection string auth is configuredMDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET are set → service account auth is configured. If only one is set, treat it as incomplete.MDB_MCP_READ_ONLY=true → read-only mode is enabledPartial Configuration Handling:
MDB_MCP_READ_ONLY) → skip to Step 4Important: 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.
If no valid configuration exists, present the options:
Connection String (Option A) — Best for:
Service Account Credentials (Option B) — Best for:
Atlas Local (Option C) — Best for:
Ask the user which option they'd like to proceed with.
If the user chooses Option A:
Explain where and how to obtain their connection string:
For MongoDB Atlas:
<username> and <password> with your database user credentialsFor self-hosted MongoDB:
mongodb://username:password@host:port/databaseExpected formats:
mongodb://username:password@host:port/databasemongodb+srv://username:password@cluster.mongodb.net/databasemongodb://host:port (local, no auth)Proceed to Step 4 (Determine Read-Only Access).
If the user chooses Option B:
Direct the user to create a MongoDB Atlas Service Account:
Full documentation: https://www.mongodb.com/docs/mcp-server/prerequisites/
Walk them through the key steps:
⚠️ CRITICAL: The user MUST add their IP address to the service account's API Access List, or all Atlas Admin API operations will fail.
Steps:
0.0.0.0/0 allows access from any IP — this is a significant security risk. Only use it as a last resort for temporary testing and remove it immediately afterward. It should never be used in production.This is more secure than global Network Access settings as it only affects API access, not database connections.
Proceed to Step 4 (Determine Read-Only Access).
If the user chooses Option C:
Verify Docker is installed:
docker info
If not installed, direct them to: https://www.docker.com/get-started
Atlas Local requires no credentials — the user is ready to go:
atlas-local-create-deploymentatlas-local-list-deploymentsSkip Steps 4 and 5 (no configuration needed) and proceed to Step 6 (Next Steps).
Only applies to Options A and B. Skip to Step 6 for Option C.
Ask whether they want read-only or read-write access:
Read-Write (default): Full data access, modifications allowed
Read-Only: Data reads only, no modifications
If read-only: include export MDB_MCP_READ_ONLY="true" in the profile snippet in Step 5.
If read-write: omit MDB_MCP_READ_ONLY (defaults to read-write).
Proceed to Step 5 (Update Shell Profile).
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.
If the user is on Windows, assume PowerShell but ask the user to confirm. For Unix/macOS, detect the shell to determine the correct profile file by running:
echo $SHELL
Based on the result, identify the appropriate profile file using your training data. If unsure which shell or profile they are using, ask them to specify the path.
Tell the user to store credentials in a dedicated ~/.mcp-env file (not directly in their shell profile). This keeps credentials out of files that are often group/world readable by default and prevents accidentally committing them to git. Make sure to adapt the path in the instructions to be in the same folder as the shell profile file.
Step 1: Create/edit ~/.mcp-env (e.g. nano ~/.mcp-env) and add:
For Connection String (Option A):
# MongoDB MCP Server Configuration
export MDB_MCP_CONNECTION_STRING="<paste-your-connection-string-here>"
For Service Account (Option B):
# MongoDB MCP Server Configuration (Atlas Service Account)
export MDB_MCP_API_CLIENT_ID="<paste-your-client-id-here>"
export MDB_MCP_API_CLIENT_SECRET="<paste-your-client-secret-here>"
If read-only was chosen (Step 4), also add:
export MDB_MCP_READ_ONLY="true"
Step 2: Restrict permissions on the file so only the owner can read it:
chmod 600 ~/.mcp-env # adapt command for Windows if needed
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 this line:
source ~/.mcp-env
Adjust syntax for the detected shell (e.g. for fish: bass source ~/.mcp-env or set variables directly with set -x; for PowerShell: dot-source a .ps1 file instead).
Once the user has saved the file, provide the commands to reload and verify:
Reload the profile:
source ~/.zshrc # adjust path to match their profile file
Verify the variables are set (masking values to avoid exposing credentials):
env | grep "^MDB_MCP" | sed '/^MDB_MCP_READ_ONLY=/!s/=.*/=[set]/'
Expected output should show the variable name(s) they just added, each with =[set]. If nothing appears, check that source ~/.mcp-env is in the profile file, the profile was reloaded, and ~/.mcp-env was saved.
Proceed to Step 6 (Next Steps).
Restart the agentic client: Fully quit the client, then in your terminal run source <profile-file> (e.g. source ~/.zshrc, adjust command and path based on the user shell) to load the new variables into the current shell session. Open the client from that same shell session so it inherits the environment.
Verify MCP Server: After restart, test by performing a MongoDB operation.
Using the Tools:
atlas-connect-clusterReady to use: No restart or configuration needed!
Next steps:
atlas-local-create-deploymentatlas-local-list-deploymentssource: Check the profile file path and confirm the file was savedmongodb:// or mongodb+srv://MDB_MCP_READ_ONLY=true is set — run env | grep ^MDB_MCP_READ_ONLYset -x (fish) or $env: (PowerShell) instead of export