Important
The feature described on this page is not currently supported on Atlas Infinite clusters during public preview. For the features supported in public preview, see Public Preview Availability.
In this guide, you learn how to get started with the MongoDB MCP Server by configuring and using it in your AI client.
Before You Begin
Before you begin, review MongoDB MCP Server Prerequisites for Running Atlas Tools to ensure you meet all the requirements to configure the MongoDB MCP Server.
Tip
Select your desired AI Client from the AI Client dropdown below for setup instructions.
Claude Code supports the following setup methods:
- Plugin for MongoDB Atlas (Managed MCP Server) (Recommended): This option allows you to connect to your MongoDB Atlas cluster using the plugin.
- Manual Setup for MongoDB Atlas Managed MCP Server: This option allows you to connect to your MongoDB Atlas cluster after you set up Atlas access using the Atlas CLI or Atlas API.
- Plugin for Local MCP: This option allows you to connect to your local MongoDB cluster using the plugin.
- Manual Setup for Local MCP: This option allows you to connect to your local MongoDB cluster after you manually set up the Local MCP environment.
MongoDB Atlas
Important
An organization owner must enable the AI Clients setting before members can connect with a plugin. To learn how to enable AI client connections, see Enable AI Clients.
Confirm the requested permissions.
Complete the guided Atlas OAuth flow and click Authorize.
Login to Atlas.
Important
You need Atlas CLI 1.58.0 or later to complete this procedure. You can check your version by running atlas --version in your terminal. If you need to upgrade, see MongoDB Atlas CLI Download.
In your terminal, run the following command:
atlas auth login -P mcp
Select UserAccount. This returns a one-time verification code and directs you to an external browser window. Log in and verify your account using the one-time code, then come back to the terminal.
Follow the prompts in terminal to finish configuring your profile.
Set your organization or project ID environment variable.
Run the following command in your terminal to set your environment variables for an organization-level configuration, replacing <ORG_ID> with your organization ID.
export ORG_ID="<ORG_ID>" # Set to use org-level config
Tip
If you want to use project-level configuration instead, you can set your project ID instead of your organization ID. Replace <GROUP_ID> with your project ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following commands to create an organization-level configuration, adding roles and your IP address for access:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["ORG_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createOrgMcpConfig \ --orgId "$ORG_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["GROUP_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createGroupMcpConfig \ --groupId "$GROUP_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Generate your client secret.
Run the following commands to create a secret for your created organization-level configuration. Set the expiration time for the secret you are creating in secretExpiresAfterHours.
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createOrgMcpSecret \ --orgId "$ORG_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createGroupMcpSecret \ --groupId "$GROUP_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > mcp-client-config.json <<EOF { "mcpServers": { "mongodb-atlas-mcp-remote": { "type": "stdio", "command": "npx", "args": ["-y", "mongodb-atlas-mcp-remote@latest"], "env": { "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID", "MDB_MCP_API_CLIENT_SECRET": "$SECRET" } } } } EOF
Open mcp-client-config.json and paste its contents into your MCP client's settings.
Create your public API key.
To create your public key, follow the steps in Get Started with the Atlas Administration API.
Set your API key environment variables.
Run the following commands in your terminal to set your Atlas API environment variables, replacing:
<PUBLIC_API_KEY>with your public API key<PRIVATE_API_KEY>with your private API key
export PUBLIC_API_KEY="<PUBLIC_API_KEY>" export PRIVATE_API_KEY="<PRIVATE_API_KEY>"
Set your organization or project ID environment variable.
Run the following command, replacing <ORG_ID> with your organization ID for an organization-level configuration:
export ORG_ID="<ORG_ID>" # Set to use org-level config instead of GROUP_ID
Tip
If you want to use project-level configuration instead, you can set your group ID instead of your organization ID. Replace <GROUP_ID> with your group ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following and extract both mcpConfigId and clientId from the response for an organization-level configuration:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["ORG_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["GROUP_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs"
To learn more about user roles, see:
For details on the mcpConfigs API endpoint, see Remote MCP Configurations.
Set your Client ID and MCP Configuration ID environment variables.
Run the following command, replacing:
<CLIENT_ID>with theclientIdyou extracted in the previous step<MCP_CONFIG_ID>with themcpConfigIdyou extracted in the previous step
export CLIENT_ID="<CLIENT_ID>" export MCP_CONFIG_ID="<MCP_CONFIG_ID>"
Generate your MCP client secret.
Run the following command and extract the secret from the response for an organization-level configuration:
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > mcp-client-config.json <<EOF { "mcpServers": { "mongodb-atlas-mcp-remote": { "type": "stdio", "command": "npx", "args": ["-y", "mongodb-atlas-mcp-remote@latest"], "env": { "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID", "MDB_MCP_API_CLIENT_SECRET": "$SECRET" } } } } EOF
Open mcp-client-config.json and paste its contents into your MCP client's settings.
Self-Managed MongoDB
To set up the Local MCP, ensure you have Node.js installed using version 22.12.0 or later.
To examine your Node.js version, run the following command:
node --version
You can use the Local MCP with local Atlas deployments. To do so, you must install Docker. For an introduction to local Atlas deployments, see Create a Local Atlas Deployment.
Run the set up utility.
The set up utility guides you through the process of creating an initial JSON configuration file. This JSON configuration file tells the server how to connect to MongoDB and how to share that data with MCP clients.
From the command line, run:
npx mongodb-mcp-server@latest setup
Note
Alternatively, you can run the Local MCP in a Docker container, which does not require Node.js. To learn more, see Using Docker.
Provide read-only mode setting.
You can limit the MCP Server to perform only read operations using read-only mode. To enable read-only mode, enter Y.
For security, always enable read-only mode unless you must perform write operations. You can enable write operations later. For details, see MCP Server Read-Only Mode.
Enter connection string.
Enter the connection string for your MongoDB cluster.
For example, mongodb+srv://user:D1fficultP%40ssw0rd@mycluster.abcd1.mongodb.net/myDatabase?retryWrites=true&w=majority.
To learn more, see Find Your Connection String.
If you have issues with your Local MCP for MongoDB MCP Server configuration, see Troubleshoot the Local MCP Server.
For complete configuration options, see Configure MCP Server and Connections.
Claude Desktop & Web support the following setup methods:
- Connector for MongoDB Atlas (Managed MCP Server) (Recommended): This option allows you to connect to your MongoDB Atlas cluster using the connector.
- Manual Setup for MongoDB Atlas Managed MCP Server: This option allows you to connect to your MongoDB Atlas cluster after you set up Atlas access using the Atlas CLI or Atlas API.
- Manual Setup for Local MCP: This option allows you to connect to your local MongoDB cluster after you manually set up the Local MCP environment.
MongoDB Atlas
Important
An organization owner must enable the AI Clients setting before members can connect with a plugin. To learn how to enable AI client connections, see Enable AI Clients.
Login to Atlas.
Important
You need Atlas CLI 1.58.0 or later to complete this procedure. You can check your version by running atlas --version in your terminal. If you need to upgrade, see MongoDB Atlas CLI Download.
In your terminal, run the following command:
atlas auth login -P mcp
Select UserAccount. This returns a one-time verification code and directs you to an external browser window. Log in and verify your account using the one-time code, then come back to the terminal.
Follow the prompts in terminal to finish configuring your profile.
Set your organization or project ID environment variable.
Run the following command in your terminal to set your environment variables for an organization-level configuration, replacing <ORG_ID> with your organization ID.
export ORG_ID="<ORG_ID>" # Set to use org-level config
Tip
If you want to use project-level configuration instead, you can set your project ID instead of your organization ID. Replace <GROUP_ID> with your project ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following commands to create an organization-level configuration, adding roles and your IP address for access:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["ORG_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createOrgMcpConfig \ --orgId "$ORG_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["GROUP_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createGroupMcpConfig \ --groupId "$GROUP_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Generate your client secret.
Run the following commands to create a secret for your created organization-level configuration. Set the expiration time for the secret you are creating in secretExpiresAfterHours.
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createOrgMcpSecret \ --orgId "$ORG_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createGroupMcpSecret \ --groupId "$GROUP_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > mcp-client-config.json <<EOF { "mcpServers": { "mongodb-atlas-mcp-remote": { "type": "stdio", "command": "npx", "args": ["-y", "mongodb-atlas-mcp-remote@latest"], "env": { "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID", "MDB_MCP_API_CLIENT_SECRET": "$SECRET" } } } } EOF
Open mcp-client-config.json and paste its contents into your Claude/claude_desktop_config.json file. If you have other MCP servers configured, you can add only the mongodb-atlas-mcp-remote configuration to your existing mcpServers object.
Restart Claude Desktop to apply the new configuration.
Create your public API key.
To create your public key, follow the steps in Get Started with the Atlas Administration API.
Set your API key environment variables.
Run the following commands in your terminal to set your Atlas API environment variables, replacing:
<PUBLIC_API_KEY>with your public API key<PRIVATE_API_KEY>with your private API key
export PUBLIC_API_KEY="<PUBLIC_API_KEY>" export PRIVATE_API_KEY="<PRIVATE_API_KEY>"
Set your organization or project ID environment variable.
Run the following command, replacing <ORG_ID> with your organization ID for an organization-level configuration:
export ORG_ID="<ORG_ID>" # Set to use org-level config instead of GROUP_ID
Tip
If you want to use project-level configuration instead, you can set your group ID instead of your organization ID. Replace <GROUP_ID> with your group ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following and extract both mcpConfigId and clientId from the response for an organization-level configuration:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["ORG_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["GROUP_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs"
To learn more about user roles, see:
For details on the mcpConfigs API endpoint, see Remote MCP Configurations.
Set your Client ID and MCP Configuration ID environment variables.
Run the following command, replacing:
<CLIENT_ID>with theclientIdyou extracted in the previous step<MCP_CONFIG_ID>with themcpConfigIdyou extracted in the previous step
export CLIENT_ID="<CLIENT_ID>" export MCP_CONFIG_ID="<MCP_CONFIG_ID>"
Generate your MCP client secret.
Run the following command and extract the secret from the response for an organization-level configuration:
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > mcp-client-config.json <<EOF { "mcpServers": { "mongodb-atlas-mcp-remote": { "type": "stdio", "command": "npx", "args": ["-y", "mongodb-atlas-mcp-remote@latest"], "env": { "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID", "MDB_MCP_API_CLIENT_SECRET": "$SECRET" } } } } EOF
Open mcp-client-config.json and paste its contents into your Claude/claude_desktop_config.json file. If you have other MCP servers configured, you can add only the mongodb-atlas-mcp-remote configuration to your existing mcpServers object.
Restart Claude Desktop to apply the new configuration.
Self-Managed MongoDB
To set up the Local MCP, ensure you have Node.js installed using version 22.12.0 or later.
To examine your Node.js version, run the following command:
node --version
You can use the Local MCP with local Atlas deployments. To do so, you must install Docker. For an introduction to local Atlas deployments, see Create a Local Atlas Deployment.
Run the set up utility.
The set up utility guides you through the process of creating an initial JSON configuration file. This JSON configuration file tells the server how to connect to MongoDB and how to share that data with MCP clients.
From the command line, run:
npx mongodb-mcp-server@latest setup
Note
Alternatively, you can run the Local MCP in a Docker container, which does not require Node.js. To learn more, see Using Docker.
Provide read-only mode setting.
You can limit the MCP Server to perform only read operations using read-only mode. To enable read-only mode, enter Y.
For security, always enable read-only mode unless you must perform write operations. You can enable write operations later. For details, see MCP Server Read-Only Mode.
Enter connection string.
Enter the connection string for your MongoDB cluster.
For example, mongodb+srv://user:D1fficultP%40ssw0rd@mycluster.abcd1.mongodb.net/myDatabase?retryWrites=true&w=majority.
To learn more, see Find Your Connection String.
If you have issues with your Local MCP for MongoDB MCP Server configuration, see Troubleshoot the Local MCP Server.
For complete configuration options, see Configure MCP Server and Connections.
ChatGPT Desktop & Web support the following setup method:
- Plugin for MongoDB Atlas (Managed MCP Server) (Recommended): This option allows you to connect to your MongoDB Atlas cluster using the plugin.
Note
ChatGPT does not support Self-Managed MongoDB.
MongoDB Atlas
Important
An organization owner must enable the AI Clients setting before members can connect with a plugin. To learn how to enable AI client connections, see Enable AI Clients.
To set up the MongoDB Atlas plugin in ChatGPT Desktop or Web, follow these steps:
Login to Atlas.
Click Connect to MongoDB Atlas and complete the guided Atlas OAuth flow.
Cursor supports the following setup methods:
- Plugin for MongoDB Atlas (Managed MCP Server) (Recommended): This option allows you to connect to your MongoDB Atlas cluster using the plugin.
- Manual Setup for MongoDB Atlas Managed MCP Server: This option allows you to connect to your MongoDB Atlas cluster after you set up Atlas access using the Atlas CLI or Atlas API.
- Plugin for Local MCP: This option allows you to connect to your local MongoDB cluster using the plugin.
- Manual Setup for Local MCP: This option allows you to connect to your local MongoDB cluster after you manually set up the Local MCP environment.
MongoDB Atlas
Important
An organization owner must enable the AI Clients setting before members can connect with a plugin. To learn how to enable AI client connections, see Enable AI Clients.
Login to Atlas.
Go to Tools & MCPs → Authenticate → MongoDB-Atlas and complete the guided OAuth flow.
Login to Atlas.
Important
You need Atlas CLI 1.58.0 or later to complete this procedure. You can check your version by running atlas --version in your terminal. If you need to upgrade, see MongoDB Atlas CLI Download.
In your terminal, run the following command:
atlas auth login -P mcp
Select UserAccount. This returns a one-time verification code and directs you to an external browser window. Log in and verify your account using the one-time code, then come back to the terminal.
Follow the prompts in terminal to finish configuring your profile.
Set your organization or project ID environment variable.
Run the following command in your terminal to set your environment variables for an organization-level configuration, replacing <ORG_ID> with your organization ID.
export ORG_ID="<ORG_ID>" # Set to use org-level config
Tip
If you want to use project-level configuration instead, you can set your project ID instead of your organization ID. Replace <GROUP_ID> with your project ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following commands to create an organization-level configuration, adding roles and your IP address for access:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["ORG_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createOrgMcpConfig \ --orgId "$ORG_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["GROUP_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createGroupMcpConfig \ --groupId "$GROUP_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Generate your client secret.
Run the following commands to create a secret for your created organization-level configuration. Set the expiration time for the secret you are creating in secretExpiresAfterHours.
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createOrgMcpSecret \ --orgId "$ORG_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createGroupMcpSecret \ --groupId "$GROUP_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > mcp-client-config.json <<EOF { "mcpServers": { "mongodb-atlas-mcp-remote": { "type": "stdio", "command": "npx", "args": ["-y", "mongodb-atlas-mcp-remote@latest"], "env": { "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID", "MDB_MCP_API_CLIENT_SECRET": "$SECRET" } } } } EOF
Open mcp-client-config.json and paste its contents into your .cursor/mcp.json file in your project or home directory.
Create your public API key.
To create your public key, follow the steps in Get Started with the Atlas Administration API.
Set your API key environment variables.
Run the following commands in your terminal to set your Atlas API environment variables, replacing:
<PUBLIC_API_KEY>with your public API key<PRIVATE_API_KEY>with your private API key
export PUBLIC_API_KEY="<PUBLIC_API_KEY>" export PRIVATE_API_KEY="<PRIVATE_API_KEY>"
Set your organization or project ID environment variable.
Run the following command, replacing <ORG_ID> with your organization ID for an organization-level configuration:
export ORG_ID="<ORG_ID>" # Set to use org-level config instead of GROUP_ID
Tip
If you want to use project-level configuration instead, you can set your group ID instead of your organization ID. Replace <GROUP_ID> with your group ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following and extract both mcpConfigId and clientId from the response for an organization-level configuration:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["ORG_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["GROUP_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs"
To learn more about user roles, see:
For details on the mcpConfigs API endpoint, see Remote MCP Configurations.
Set your Client ID and MCP Configuration ID environment variables.
Run the following command, replacing:
<CLIENT_ID>with theclientIdyou extracted in the previous step<MCP_CONFIG_ID>with themcpConfigIdyou extracted in the previous step
export CLIENT_ID="<CLIENT_ID>" export MCP_CONFIG_ID="<MCP_CONFIG_ID>"
Generate your MCP client secret.
Run the following command and extract the secret from the response for an organization-level configuration:
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > mcp-client-config.json <<EOF { "mcpServers": { "mongodb-atlas-mcp-remote": { "type": "stdio", "command": "npx", "args": ["-y", "mongodb-atlas-mcp-remote@latest"], "env": { "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID", "MDB_MCP_API_CLIENT_SECRET": "$SECRET" } } } } EOF
Open mcp-client-config.json and paste its contents into your .cursor/mcp.json file in your project or home directory.
Self-Managed MongoDB
To set up the Local MCP, ensure you have Node.js installed using version 22.12.0 or later.
To examine your Node.js version, run the following command:
node --version
You can use the Local MCP with local Atlas deployments. To do so, you must install Docker. For an introduction to local Atlas deployments, see Create a Local Atlas Deployment.
Run the set up utility.
The set up utility guides you through the process of creating an initial JSON configuration file. This JSON configuration file tells the server how to connect to MongoDB and how to share that data with MCP clients.
From the command line, run:
npx mongodb-mcp-server@latest setup
Note
Alternatively, you can run the Local MCP in a Docker container, which does not require Node.js. To learn more, see Using Docker.
Provide read-only mode setting.
You can limit the MCP Server to perform only read operations using read-only mode. To enable read-only mode, enter Y.
For security, always enable read-only mode unless you must perform write operations. You can enable write operations later. For details, see MCP Server Read-Only Mode.
Enter connection string.
Enter the connection string for your MongoDB cluster.
For example, mongodb+srv://user:D1fficultP%40ssw0rd@mycluster.abcd1.mongodb.net/myDatabase?retryWrites=true&w=majority.
To learn more, see Find Your Connection String.
If you have issues with your Local MCP for MongoDB MCP Server configuration, see Troubleshoot the Local MCP Server.
For complete configuration options, see Configure MCP Server and Connections.
Codex supports the following setup methods:
- Plugin for MongoDB Atlas (Managed MCP Server) (Recommended): This option allows you to connect to your MongoDB Atlas cluster using the plugin.
- Manual Setup for MongoDB Atlas Managed MCP Server: This option allows you to connect to your MongoDB Atlas cluster after you set up Atlas access using the Atlas CLI or Atlas API.
- Manual Setup for Local MCP: This option allows you to connect to your local MongoDB cluster after you manually set up the Local MCP environment.
MongoDB Atlas
Important
An organization owner must enable the AI Clients setting before members can connect with a plugin. To learn how to enable AI client connections, see Enable AI Clients.
Authorize the plugin.
Click Continue to MongoDB Atlas and complete the guided Atlas OAuth flow.
Login to Atlas.
Important
You need Atlas CLI 1.58.0 or later to complete this procedure. You can check your version by running atlas --version in your terminal. If you need to upgrade, see MongoDB Atlas CLI Download.
In your terminal, run the following command:
atlas auth login -P mcp
Select UserAccount. This returns a one-time verification code and directs you to an external browser window. Log in and verify your account using the one-time code, then come back to the terminal.
Follow the prompts in terminal to finish configuring your profile.
Set your organization or project ID environment variable.
Run the following command in your terminal to set your environment variables for an organization-level configuration, replacing <ORG_ID> with your organization ID.
export ORG_ID="<ORG_ID>" # Set to use org-level config
Tip
If you want to use project-level configuration instead, you can set your project ID instead of your organization ID. Replace <GROUP_ID> with your project ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following commands to create an organization-level configuration, adding roles and your IP address for access:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["ORG_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createOrgMcpConfig \ --orgId "$ORG_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["GROUP_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createGroupMcpConfig \ --groupId "$GROUP_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Generate your client secret.
Run the following commands to create a secret for your created organization-level configuration. Set the expiration time for the secret you are creating in secretExpiresAfterHours.
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createOrgMcpSecret \ --orgId "$ORG_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createGroupMcpSecret \ --groupId "$GROUP_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > mcp-client-config.toml <<EOF [mcp_servers.mongodb-atlas-mcp-remote] command = "npx" args = ["-y", "mongodb-atlas-mcp-remote@latest"] [mcp_servers.mongodb-atlas-mcp-remote.env] MDB_MCP_API_CLIENT_ID = "$CLIENT_ID" MDB_MCP_API_CLIENT_SECRET = "$SECRET" EOF
Copy the contents of mcp-client-config.toml and paste it at the end of your ~/.codex/config.toml file.
Create your public API key.
To create your public key, follow the steps in Get Started with the Atlas Administration API.
Set your API key environment variables.
Run the following commands in your terminal to set your Atlas API environment variables, replacing:
<PUBLIC_API_KEY>with your public API key<PRIVATE_API_KEY>with your private API key
export PUBLIC_API_KEY="<PUBLIC_API_KEY>" export PRIVATE_API_KEY="<PRIVATE_API_KEY>"
Set your organization or project ID environment variable.
Run the following command, replacing <ORG_ID> with your organization ID for an organization-level configuration:
export ORG_ID="<ORG_ID>" # Set to use org-level config instead of GROUP_ID
Tip
If you want to use project-level configuration instead, you can set your group ID instead of your organization ID. Replace <GROUP_ID> with your group ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following and extract both mcpConfigId and clientId from the response for an organization-level configuration:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["ORG_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["GROUP_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs"
To learn more about user roles, see:
For details on the mcpConfigs API endpoint, see Remote MCP Configurations.
Set your Client ID and MCP Configuration ID environment variables.
Run the following command, replacing:
<CLIENT_ID>with theclientIdyou extracted in the previous step<MCP_CONFIG_ID>with themcpConfigIdyou extracted in the previous step
export CLIENT_ID="<CLIENT_ID>" export MCP_CONFIG_ID="<MCP_CONFIG_ID>"
Generate your MCP client secret.
Run the following command and extract the secret from the response for an organization-level configuration:
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > mcp-client-config.toml <<EOF [mcp_servers.mongodb-atlas-mcp-remote] command = "npx" args = ["-y", "mongodb-atlas-mcp-remote@latest"] [mcp_servers.mongodb-atlas-mcp-remote.env] MDB_MCP_API_CLIENT_ID = "$CLIENT_ID" MDB_MCP_API_CLIENT_SECRET = "$SECRET" EOF
Copy the contents of mcp-client-config.toml and paste it at the end of your ~/.codex/config.toml file.
Self-Managed MongoDB
To set up the Local MCP, ensure you have Node.js installed using version 22.12.0 or later.
To examine your Node.js version, run the following command:
node --version
You can use the Local MCP with local Atlas deployments. To do so, you must install Docker. For an introduction to local Atlas deployments, see Create a Local Atlas Deployment.
Run the set up utility.
The set up utility guides you through the process of creating an initial JSON configuration file. This JSON configuration file tells the server how to connect to MongoDB and how to share that data with MCP clients.
From the command line, run:
npx mongodb-mcp-server@latest setup
Note
Alternatively, you can run the Local MCP in a Docker container, which does not require Node.js. To learn more, see Using Docker.
Provide read-only mode setting.
You can limit the MCP Server to perform only read operations using read-only mode. To enable read-only mode, enter Y.
For security, always enable read-only mode unless you must perform write operations. You can enable write operations later. For details, see MCP Server Read-Only Mode.
Enter connection string.
Enter the connection string for your MongoDB cluster.
For example, mongodb+srv://user:D1fficultP%40ssw0rd@mycluster.abcd1.mongodb.net/myDatabase?retryWrites=true&w=majority.
To learn more, see Find Your Connection String.
If you have issues with your Local MCP for MongoDB MCP Server configuration, see Troubleshoot the Local MCP Server.
For complete configuration options, see Configure MCP Server and Connections.
Devin AI supports the following setup methods:
- Plugin for MongoDB Atlas (Managed MCP Server) (Recommended): This option allows you to connect to your MongoDB Atlas cluster using the plugin.
- Manual Setup for MongoDB Atlas Managed MCP Server: This option allows you to connect to your MongoDB Atlas cluster after you set up Atlas access using the Atlas CLI or Atlas API.
MongoDB Atlas
Important
An organization owner must enable the AI Clients setting before members can connect with a plugin. To learn how to enable AI client connections, see Enable AI Clients.
Login to Atlas.
Complete the guided Atlas OAuth flow.
Login to Atlas.
Important
You need Atlas CLI 1.58.0 or later to complete this procedure. You can check your version by running atlas --version in your terminal. If you need to upgrade, see MongoDB Atlas CLI Download.
In your terminal, run the following command:
atlas auth login -P mcp
Select UserAccount. This returns a one-time verification code and directs you to an external browser window. Log in and verify your account using the one-time code, then come back to the terminal.
Follow the prompts in terminal to finish configuring your profile.
Set your organization or project ID environment variable.
Run the following command in your terminal to set your environment variables for an organization-level configuration, replacing <ORG_ID> with your organization ID.
export ORG_ID="<ORG_ID>" # Set to use org-level config
Tip
If you want to use project-level configuration instead, you can set your project ID instead of your organization ID. Replace <GROUP_ID> with your project ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following commands to create an organization-level configuration, adding roles and your IP address for access:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["ORG_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createOrgMcpConfig \ --orgId "$ORG_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["GROUP_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createGroupMcpConfig \ --groupId "$GROUP_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Generate your client secret.
Run the following commands to create a secret for your created organization-level configuration. Set the expiration time for the secret you are creating in secretExpiresAfterHours.
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createOrgMcpSecret \ --orgId "$ORG_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createGroupMcpSecret \ --groupId "$GROUP_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > mcp-client-config.json <<EOF { "mcpServers": { "mongodb-atlas-mcp-remote": { "type": "stdio", "command": "npx", "args": ["-y", "mongodb-atlas-mcp-remote@latest"], "env": { "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID", "MDB_MCP_API_CLIENT_SECRET": "$SECRET" } } } } EOF
In Devin, click Add a Custom MCP. Click Import JSON, then paste the contents of mcp-client-config.json.
Create your public API key.
To create your public key, follow the steps in Get Started with the Atlas Administration API.
Set your API key environment variables.
Run the following commands in your terminal to set your Atlas API environment variables, replacing:
<PUBLIC_API_KEY>with your public API key<PRIVATE_API_KEY>with your private API key
export PUBLIC_API_KEY="<PUBLIC_API_KEY>" export PRIVATE_API_KEY="<PRIVATE_API_KEY>"
Set your organization or project ID environment variable.
Run the following command, replacing <ORG_ID> with your organization ID for an organization-level configuration:
export ORG_ID="<ORG_ID>" # Set to use org-level config instead of GROUP_ID
Tip
If you want to use project-level configuration instead, you can set your group ID instead of your organization ID. Replace <GROUP_ID> with your group ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following and extract both mcpConfigId and clientId from the response for an organization-level configuration:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["ORG_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["GROUP_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs"
To learn more about user roles, see:
For details on the mcpConfigs API endpoint, see Remote MCP Configurations.
Set your Client ID and MCP Configuration ID environment variables.
Run the following command, replacing:
<CLIENT_ID>with theclientIdyou extracted in the previous step<MCP_CONFIG_ID>with themcpConfigIdyou extracted in the previous step
export CLIENT_ID="<CLIENT_ID>" export MCP_CONFIG_ID="<MCP_CONFIG_ID>"
Generate your MCP client secret.
Run the following command and extract the secret from the response for an organization-level configuration:
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > mcp-client-config.json <<EOF { "mcpServers": { "mongodb-atlas-mcp-remote": { "type": "stdio", "command": "npx", "args": ["-y", "mongodb-atlas-mcp-remote@latest"], "env": { "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID", "MDB_MCP_API_CLIENT_SECRET": "$SECRET" } } } } EOF
In Devin, click Add a Custom MCP. Click Import JSON, then paste the contents of mcp-client-config.json.
Self-Managed MongoDB
Note
Devin AI does not support Self-Managed MongoDB.
Grok Build supports the following setup methods:
- Plugin for MongoDB Atlas (Managed MCP Server) (Recommended): This option allows you to connect to your MongoDB Atlas cluster using the plugin.
- Manual Setup for MongoDB Atlas Managed MCP Server: This option allows you to connect to your MongoDB Atlas cluster after you set up Atlas access using the Atlas CLI or Atlas API.
- Plugin for Local MCP: This option allows you to connect to your local MongoDB cluster using the plugin.
- Manual Setup for Local MCP: This option allows you to connect to your local MongoDB cluster after you manually set up the Local MCP environment.
MongoDB Atlas
Important
An organization owner must enable the AI Clients setting before members can connect with a plugin. To learn how to enable AI client connections, see Enable AI Clients.
Login to Atlas.
Important
You need Atlas CLI 1.58.0 or later to complete this procedure. You can check your version by running atlas --version in your terminal. If you need to upgrade, see MongoDB Atlas CLI Download.
In your terminal, run the following command:
atlas auth login -P mcp
Select UserAccount. This returns a one-time verification code and directs you to an external browser window. Log in and verify your account using the one-time code, then come back to the terminal.
Follow the prompts in terminal to finish configuring your profile.
Set your organization or project ID environment variable.
Run the following command in your terminal to set your environment variables for an organization-level configuration, replacing <ORG_ID> with your organization ID.
export ORG_ID="<ORG_ID>" # Set to use org-level config
Tip
If you want to use project-level configuration instead, you can set your project ID instead of your organization ID. Replace <GROUP_ID> with your project ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following commands to create an organization-level configuration, adding roles and your IP address for access:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["ORG_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createOrgMcpConfig \ --orgId "$ORG_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["GROUP_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createGroupMcpConfig \ --groupId "$GROUP_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Generate your client secret.
Run the following commands to create a secret for your created organization-level configuration. Set the expiration time for the secret you are creating in secretExpiresAfterHours.
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createOrgMcpSecret \ --orgId "$ORG_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createGroupMcpSecret \ --groupId "$GROUP_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > ~/.mcp-env <<EOF export MDB_MCP_API_CLIENT_ID="$CLIENT_ID" export MDB_MCP_API_CLIENT_SECRET="$SECRET" EOF chmod 600 ~/.mcp-env
After you create your configuration file, run the following command to load your configuration into your current shell session:
source ~/.mcp-env
Create your public API key.
To create your public key, follow the steps in Get Started with the Atlas Administration API.
Set your API key environment variables.
Run the following commands in your terminal to set your Atlas API environment variables, replacing:
<PUBLIC_API_KEY>with your public API key<PRIVATE_API_KEY>with your private API key
export PUBLIC_API_KEY="<PUBLIC_API_KEY>" export PRIVATE_API_KEY="<PRIVATE_API_KEY>"
Set your organization or project ID environment variable.
Run the following command, replacing <ORG_ID> with your organization ID for an organization-level configuration:
export ORG_ID="<ORG_ID>" # Set to use org-level config instead of GROUP_ID
Tip
If you want to use project-level configuration instead, you can set your group ID instead of your organization ID. Replace <GROUP_ID> with your group ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following and extract both mcpConfigId and clientId from the response for an organization-level configuration:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["ORG_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["GROUP_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs"
To learn more about user roles, see:
For details on the mcpConfigs API endpoint, see Remote MCP Configurations.
Set your Client ID and MCP Configuration ID environment variables.
Run the following command, replacing:
<CLIENT_ID>with theclientIdyou extracted in the previous step<MCP_CONFIG_ID>with themcpConfigIdyou extracted in the previous step
export CLIENT_ID="<CLIENT_ID>" export MCP_CONFIG_ID="<MCP_CONFIG_ID>"
Generate your MCP client secret.
Run the following command and extract the secret from the response for an organization-level configuration:
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > ~/.mcp-env <<EOF export MDB_MCP_API_CLIENT_ID="$CLIENT_ID" export MDB_MCP_API_CLIENT_SECRET="$SECRET" EOF chmod 600 ~/.mcp-env
After you create your configuration file, run the following command to load your configuration into your current shell session:
source ~/.mcp-env
Self-Managed MongoDB
To set up the Local MCP, ensure you have Node.js installed using version 22.12.0 or later.
To examine your Node.js version, run the following command:
node --version
You can use the Local MCP with local Atlas deployments. To do so, you must install Docker. For an introduction to local Atlas deployments, see Create a Local Atlas Deployment.
Run the set up utility.
The set up utility guides you through the process of creating an initial JSON configuration file. This JSON configuration file tells the server how to connect to MongoDB and how to share that data with MCP clients.
From the command line, run:
npx mongodb-mcp-server@latest setup
Note
Alternatively, you can run the Local MCP in a Docker container, which does not require Node.js. To learn more, see Using Docker.
Provide read-only mode setting.
You can limit the MCP Server to perform only read operations using read-only mode. To enable read-only mode, enter Y.
For security, always enable read-only mode unless you must perform write operations. You can enable write operations later. For details, see MCP Server Read-Only Mode.
Enter connection string.
Enter the connection string for your MongoDB cluster.
For example, mongodb+srv://user:D1fficultP%40ssw0rd@mycluster.abcd1.mongodb.net/myDatabase?retryWrites=true&w=majority.
To learn more, see Find Your Connection String.
If you have issues with your Local MCP for MongoDB MCP Server configuration, see Troubleshoot the Local MCP Server.
For complete configuration options, see Configure MCP Server and Connections.
The fx CLI supports the following setup methods:
- MongoDB Atlas Managed MCP Server (User Delegation) (Recommended): This option allows you to connect to your MongoDB Atlas cluster by authorizing your AI client to act with your Atlas identity.
- Manual Setup for MongoDB Atlas Managed MCP Server: This option allows you to connect to your MongoDB Atlas cluster after you set up Atlas access using the Atlas CLI or Atlas API.
- Manual Setup for Local MCP: This option allows you to connect to your local MongoDB cluster after you manually set up the Local MCP environment.
MongoDB Atlas
Important
An organization owner must enable the AI Clients setting before members can connect with a plugin. To learn how to enable AI client connections, see Enable AI Clients.
Enable the MongoDB MCP Server in fx.
Open an fx session and run:
/mcp auth mongodb --open
Complete the guided OAuth flow.
Login to Atlas.
Important
You need Atlas CLI 1.58.0 or later to complete this procedure. You can check your version by running atlas --version in your terminal. If you need to upgrade, see MongoDB Atlas CLI Download.
In your terminal, run the following command:
atlas auth login -P mcp
Select UserAccount. This returns a one-time verification code and directs you to an external browser window. Log in and verify your account using the one-time code, then come back to the terminal.
Follow the prompts in terminal to finish configuring your profile.
Set your organization or project ID environment variable.
Run the following command in your terminal to set your environment variables for an organization-level configuration, replacing <ORG_ID> with your organization ID.
export ORG_ID="<ORG_ID>" # Set to use org-level config
Tip
If you want to use project-level configuration instead, you can set your project ID instead of your organization ID. Replace <GROUP_ID> with your project ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following commands to create an organization-level configuration, adding roles and your IP address for access:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["ORG_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createOrgMcpConfig \ --orgId "$ORG_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["GROUP_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createGroupMcpConfig \ --groupId "$GROUP_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Generate your client secret.
Run the following commands to create a secret for your created organization-level configuration. Set the expiration time for the secret you are creating in secretExpiresAfterHours.
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createOrgMcpSecret \ --orgId "$ORG_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createGroupMcpSecret \ --groupId "$GROUP_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > mcp-client-config.json <<EOF { "mcp": { "mongodb-atlas-mcp-remote": { "type": "stdio", "command": ["npx", "-y", "mongodb-atlas-mcp-remote@latest"], "environment": { "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID", "MDB_MCP_API_CLIENT_SECRET": "$SECRET" } } } } EOF
Open mcp-client-config.json and paste its contents into your ~/.fx/mcp.json file.
Create your public API key.
To create your public key, follow the steps in Get Started with the Atlas Administration API.
Set your API key environment variables.
Run the following commands in your terminal to set your Atlas API environment variables, replacing:
<PUBLIC_API_KEY>with your public API key<PRIVATE_API_KEY>with your private API key
export PUBLIC_API_KEY="<PUBLIC_API_KEY>" export PRIVATE_API_KEY="<PRIVATE_API_KEY>"
Set your organization or project ID environment variable.
Run the following command, replacing <ORG_ID> with your organization ID for an organization-level configuration:
export ORG_ID="<ORG_ID>" # Set to use org-level config instead of GROUP_ID
Tip
If you want to use project-level configuration instead, you can set your group ID instead of your organization ID. Replace <GROUP_ID> with your group ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following and extract both mcpConfigId and clientId from the response for an organization-level configuration:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["ORG_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["GROUP_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs"
To learn more about user roles, see:
For details on the mcpConfigs API endpoint, see Remote MCP Configurations.
Set your Client ID and MCP Configuration ID environment variables.
Run the following command, replacing:
<CLIENT_ID>with theclientIdyou extracted in the previous step<MCP_CONFIG_ID>with themcpConfigIdyou extracted in the previous step
export CLIENT_ID="<CLIENT_ID>" export MCP_CONFIG_ID="<MCP_CONFIG_ID>"
Generate your MCP client secret.
Run the following command and extract the secret from the response for an organization-level configuration:
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Write your MCP client configuration.
Run the following command to create your configuration file:
cat > mcp-client-config.json <<EOF { "mcp": { "mongodb-atlas-mcp-remote": { "type": "stdio", "command": ["npx", "-y", "mongodb-atlas-mcp-remote@latest"], "environment": { "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID", "MDB_MCP_API_CLIENT_SECRET": "$SECRET" } } } } EOF
Open mcp-client-config.json and paste its contents into your ~/.fx/mcp.json file.
Self-Managed MongoDB
To set up the Local MCP, ensure you have Node.js installed using version 22.12.0 or later.
To examine your Node.js version, run the following command:
node --version
You can use the Local MCP with local Atlas deployments. To do so, you must install Docker. For an introduction to local Atlas deployments, see Create a Local Atlas Deployment.
Run the set up utility.
The set up utility guides you through the process of creating an initial JSON configuration file. This JSON configuration file tells the server how to connect to MongoDB and how to share that data with MCP clients.
From the command line, run:
npx mongodb-mcp-server@latest setup
Note
Alternatively, you can run the Local MCP in a Docker container, which does not require Node.js. To learn more, see Using Docker.
Provide read-only mode setting.
You can limit the MCP Server to perform only read operations using read-only mode. To enable read-only mode, enter Y.
For security, always enable read-only mode unless you must perform write operations. You can enable write operations later. For details, see MCP Server Read-Only Mode.
Enter connection string.
Enter the connection string for your MongoDB cluster.
For example, mongodb+srv://user:D1fficultP%40ssw0rd@mycluster.abcd1.mongodb.net/myDatabase?retryWrites=true&w=majority.
To learn more, see Find Your Connection String.
If you have issues with your Local MCP for MongoDB MCP Server configuration, see Troubleshoot the Local MCP Server.
For complete configuration options, see Configure MCP Server and Connections.
You can use any other AI client with the following setup methods:
- Manual Setup for MongoDB Atlas Managed MCP Server: This option allows you to connect to your MongoDB Atlas cluster after you set up Atlas access using the Atlas CLI or Atlas API.
- Manual Setup for Local MCP: This option allows you to connect to your local MongoDB cluster after you manually set up the Local MCP environment.
MongoDB Atlas
Login to Atlas.
Important
You need Atlas CLI 1.58.0 or later to complete this procedure. You can check your version by running atlas --version in your terminal. If you need to upgrade, see MongoDB Atlas CLI Download.
In your terminal, run the following command:
atlas auth login -P mcp
Select UserAccount. This returns a one-time verification code and directs you to an external browser window. Log in and verify your account using the one-time code, then come back to the terminal.
Follow the prompts in terminal to finish configuring your profile.
Set your organization or project ID environment variable.
Run the following command in your terminal to set your environment variables for an organization-level configuration, replacing <ORG_ID> with your organization ID.
export ORG_ID="<ORG_ID>" # Set to use org-level config
Tip
If you want to use project-level configuration instead, you can set your project ID instead of your organization ID. Replace <GROUP_ID> with your project ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following commands to create an organization-level configuration, adding roles and your IP address for access:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["ORG_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createOrgMcpConfig \ --orgId "$ORG_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["GROUP_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createGroupMcpConfig \ --groupId "$GROUP_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Generate your client secret.
Run the following commands to create a secret for your created organization-level configuration. Set the expiration time for the secret you are creating in secretExpiresAfterHours.
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createOrgMcpSecret \ --orgId "$ORG_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createGroupMcpSecret \ --groupId "$GROUP_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Create your public API key.
To create your public key, follow the steps in Get Started with the Atlas Administration API.
Set your API key environment variables.
Run the following commands in your terminal to set your Atlas API environment variables, replacing:
<PUBLIC_API_KEY>with your public API key<PRIVATE_API_KEY>with your private API key
export PUBLIC_API_KEY="<PUBLIC_API_KEY>" export PRIVATE_API_KEY="<PRIVATE_API_KEY>"
Set your organization or project ID environment variable.
Run the following command, replacing <ORG_ID> with your organization ID for an organization-level configuration:
export ORG_ID="<ORG_ID>" # Set to use org-level config instead of GROUP_ID
Tip
If you want to use project-level configuration instead, you can set your group ID instead of your organization ID. Replace <GROUP_ID> with your group ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following and extract both mcpConfigId and clientId from the response for an organization-level configuration:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["ORG_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["GROUP_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs"
To learn more about user roles, see:
For details on the mcpConfigs API endpoint, see Remote MCP Configurations.
Set your Client ID and MCP Configuration ID environment variables.
Run the following command, replacing:
<CLIENT_ID>with theclientIdyou extracted in the previous step<MCP_CONFIG_ID>with themcpConfigIdyou extracted in the previous step
export CLIENT_ID="<CLIENT_ID>" export MCP_CONFIG_ID="<MCP_CONFIG_ID>"
Generate your MCP client secret.
Run the following command and extract the secret from the response for an organization-level configuration:
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Self-Managed MongoDB
To set up the Local MCP, ensure you have Node.js installed using version 22.12.0 or later.
To examine your Node.js version, run the following command:
node --version
You can use the Local MCP with local Atlas deployments. To do so, you must install Docker. For an introduction to local Atlas deployments, see Create a Local Atlas Deployment.
Run the set up utility.
The set up utility guides you through the process of creating an initial JSON configuration file. This JSON configuration file tells the server how to connect to MongoDB and how to share that data with MCP clients.
From the command line, run:
npx mongodb-mcp-server@latest setup
Note
Alternatively, you can run the Local MCP in a Docker container, which does not require Node.js. To learn more, see Using Docker.
Provide read-only mode setting.
You can limit the MCP Server to perform only read operations using read-only mode. To enable read-only mode, enter Y.
For security, always enable read-only mode unless you must perform write operations. You can enable write operations later. For details, see MCP Server Read-Only Mode.
Enter connection string.
Enter the connection string for your MongoDB cluster.
For example, mongodb+srv://user:D1fficultP%40ssw0rd@mycluster.abcd1.mongodb.net/myDatabase?retryWrites=true&w=majority.
To learn more, see Find Your Connection String.
If you have issues with your Local MCP for MongoDB MCP Server configuration, see Troubleshoot the Local MCP Server.
For complete configuration options, see Configure MCP Server and Connections.
Login to Atlas.
Important
You need Atlas CLI 1.58.0 or later to complete this procedure. You can check your version by running atlas --version in your terminal. If you need to upgrade, see MongoDB Atlas CLI Download.
In your terminal, run the following command:
atlas auth login -P mcp
Select UserAccount. This returns a one-time verification code and directs you to an external browser window. Log in and verify your account using the one-time code, then come back to the terminal.
Follow the prompts in terminal to finish configuring your profile.
Set your organization or project ID environment variable.
Run the following command in your terminal to set your environment variables for an organization-level configuration, replacing <ORG_ID> with your organization ID.
export ORG_ID="<ORG_ID>" # Set to use org-level config
Tip
If you want to use project-level configuration instead, you can set your project ID instead of your organization ID. Replace <GROUP_ID> with your project ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following commands to create an organization-level configuration, adding roles and your IP address for access:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["ORG_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createOrgMcpConfig \ --orgId "$ORG_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-config.json <<EOF { "mcpConfigName": "my-config", "roles": ["GROUP_OWNER"], "ipAccessList": [{"ipAddress": "$MY_IP"}] } EOF read -r MCP_CONFIG_ID CLIENT_ID <<< "$( atlas api remoteMcpConfigurations createGroupMcpConfig \ --groupId "$GROUP_ID" \ --file /tmp/mcp-config.json \ -P mcp \ -o '{{.mcpConfigId}} {{.clientId}}' )" export MCP_CONFIG_ID export CLIENT_ID
Generate your client secret.
Run the following commands to create a secret for your created organization-level configuration. Set the expiration time for the secret you are creating in secretExpiresAfterHours.
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createOrgMcpSecret \ --orgId "$ORG_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Tip
If you want to use project-level configuration instead, run the following commands:
cat > /tmp/mcp-secret.json <<EOF {"secretExpiresAfterHours": 8760} EOF SECRET=$( atlas api remoteMcpConfigurations createGroupMcpSecret \ --groupId "$GROUP_ID" \ --mcpConfigId "$MCP_CONFIG_ID" \ --file /tmp/mcp-secret.json \ -P mcp \ -o '{{.secret}}' ) export SECRET
Access the MCP Server using Agent Frameworks.
For programmatic access to the MCP server using agent frameworks like LangChain, you must fetch an access token and then call the MCP server from your application.
Tip
The following example assumes you have mcp[cli], httpx, and httpx2 installed. You can install them using pip:
python3 -m pip install "mcp[cli]" httpx httpx2
Here is an example Python script that uses the MCP SDK to access the MCP server:
import asyncio import base64 import os import httpx import httpx2 from mcp import ClientSession from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client async def fetch_access_token(client_id: str, client_secret: str) -> str: credentials = base64.b64encode( f"{client_id}:{client_secret}".encode() ).decode() async with httpx.AsyncClient() as client: response = await client.post( "https://cloud.mongodb.com/api/oauth/token", headers={ "Authorization": f"Basic {credentials}", "Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json", }, data={"grant_type": "client_credentials"}, ) response.raise_for_status() return response.json()["access_token"] async def main() -> None: client_id = os.environ["CLIENT_ID"] client_secret = os.environ["SECRET"] mcp_url = os.getenv("MCP_URL", "https://mcp.mongodb.com") token = await fetch_access_token(client_id, client_secret) headers = { "Authorization": f"Bearer {token}", "Accept": "application/json, text/event-stream", "MCP-Protocol-Version": "2025-11-25", } http_client = create_mcp_http_client( headers=headers, timeout=httpx2.Timeout(30.0), ) async with http_client: async with streamable_http_client( mcp_url, http_client=http_client, ) as (read_stream, write_stream): async with ClientSession(read_stream, write_stream) as session: init_result = await session.initialize() print("Initialized:", init_result.protocol_version) result = await session.list_tools() for tool in result.tools: print(tool.name) if tool.description: print(f" {tool.description}") if __name__ == "__main__": asyncio.run(main())
Create your public API key.
To create your public key, follow the steps in Get Started with the Atlas Administration API.
Set your API key environment variables.
Run the following commands in your terminal to set your Atlas API environment variables, replacing:
<PUBLIC_API_KEY>with your public API key<PRIVATE_API_KEY>with your private API key
export PUBLIC_API_KEY="<PUBLIC_API_KEY>" export PRIVATE_API_KEY="<PRIVATE_API_KEY>"
Set your organization or project ID environment variable.
Run the following command, replacing <ORG_ID> with your organization ID for an organization-level configuration:
export ORG_ID="<ORG_ID>" # Set to use org-level config instead of GROUP_ID
Tip
If you want to use project-level configuration instead, you can set your group ID instead of your organization ID. Replace <GROUP_ID> with your group ID and run:
export GROUP_ID="<GROUP_ID>" # Set to use project-level config instead of ORG_ID
Create your MCP configuration.
Run the following and extract both mcpConfigId and clientId from the response for an organization-level configuration:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["ORG_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.atlas.2025-03-12+json" \ -d "$(jq -n --arg ip "$MY_IP" '{ mcpConfigName: "my-config", roles: ["GROUP_OWNER"], ipAccessList: [ {ipAddress: $ip}, {cidrBlock: "10.0.0.0/24"} ] }')" \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs"
To learn more about user roles, see:
For details on the mcpConfigs API endpoint, see Remote MCP Configurations.
Set your Client ID and MCP Configuration ID environment variables.
Run the following command, replacing:
<CLIENT_ID>with theclientIdyou extracted in the previous step<MCP_CONFIG_ID>with themcpConfigIdyou extracted in the previous step
export CLIENT_ID="<CLIENT_ID>" export MCP_CONFIG_ID="<MCP_CONFIG_ID>"
Generate your MCP client secret.
Run the following command and extract the secret from the response for an organization-level configuration:
Important
You can only retrieve the secret once. If you lose it, regenerate it by creating a new secret.
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/orgs/$ORG_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Tip
If you want to use project-level configuration instead, run:
curl -s --digest -u "$PUBLIC_API_KEY:$PRIVATE_API_KEY" \ -X POST \ -H 'Content-Type: application/vnd.atlas.2025-03-12+json' \ -H 'Accept: application/vnd.atlas.2025-03-12+json' \ -d '{"secretExpiresAfterHours": 8760}' \ "https://cloud.mongodb.com/api/atlas/v2/groups/$GROUP_ID/mcpConfigs/$MCP_CONFIG_ID/secrets"
Access the MCP Server using Agent Frameworks.
For programmatic access to the MCP server using agent frameworks like LangChain, you must fetch an access token and then call the MCP server from your application.
Tip
The following example assumes you have mcp[cli], httpx, and httpx2 installed. You can install them using pip:
python3 -m pip install "mcp[cli]" httpx httpx2
Here is an example Python script that uses the MCP SDK to access the MCP server:
import asyncio import base64 import os import httpx import httpx2 from mcp import ClientSession from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client async def fetch_access_token(client_id: str, client_secret: str) -> str: credentials = base64.b64encode( f"{client_id}:{client_secret}".encode() ).decode() async with httpx.AsyncClient() as client: response = await client.post( "https://cloud.mongodb.com/api/oauth/token", headers={ "Authorization": f"Basic {credentials}", "Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json", }, data={"grant_type": "client_credentials"}, ) response.raise_for_status() return response.json()["access_token"] async def main() -> None: client_id = os.environ["CLIENT_ID"] client_secret = os.environ["SECRET"] mcp_url = os.getenv("MCP_URL", "https://mcp.mongodb.com") token = await fetch_access_token(client_id, client_secret) headers = { "Authorization": f"Bearer {token}", "Accept": "application/json, text/event-stream", "MCP-Protocol-Version": "2025-11-25", } http_client = create_mcp_http_client( headers=headers, timeout=httpx2.Timeout(30.0), ) async with http_client: async with streamable_http_client( mcp_url, http_client=http_client, ) as (read_stream, write_stream): async with ClientSession(read_stream, write_stream) as session: init_result = await session.initialize() print("Initialized:", init_result.protocol_version) result = await session.list_tools() for tool in result.tools: print(tool.name) if tool.description: print(f" {tool.description}") if __name__ == "__main__": asyncio.run(main())
Next Steps
For a list of the tools available for the MongoDB MCP Server, see Supported Tools.
For examples of how to use the MongoDB MCP Server, see MongoDB MCP Server Usage Examples.