To configure the MongoDB MCP Server to connect to your MongoDB cluster and set other MCP Server options, use any of these methods:
JSON configuration file with MCP Server options
Command line options
Operating system environment variables
The MCP Server uses Atlas API credentials or a connection string to access a cluster.
MCP Server Cluster Connection Methods and Options
To configure the MCP Server to connect to a cluster and set other MCP Server options, use a method described in this section.
Note
The MCP Server configuration file examples include --readOnly
to ensure read-only access to data. Typically, enable read-only
mode to prevent data changes.
To enable write operations, omit --readOnly or set the
operating system environment variable MDB_MCP_READ_ONLY to
false. For more information, see
Enabling MCP Server Read-Only Mode.
The MCP Server configuration file examples set the type field to
"stdio".
type can be set to one of the following:
"stdio", which uses the standard input and output for communications with the MCP Server.stdiois suitable for most AI clients. Typically usestdio."http", which enables HTTP communications with the MCP Server. You can then use HTTP to interact with the MCP Server from a Web client.Warning
HTTP is NOT recommended for production use without implementing authentication and security.
The MCP Server configuration file examples also set the MCP Server name
to "MongoDB". You can change the server name to match the name of
your MCP Server after you start it. The server name identifies the MCP
Server to the AI client.
Connecting with Atlas API Credentials
You can use the Atlas API credentials obtained in MongoDB MCP Server Prerequisites for Running Atlas Tools to connect to an Atlas cluster.
Note
As you'll see in the next section, you can also connect to an Atlas cluster using a MongoDB connection string if you don't want to use Atlas API credentials for security or another reason.
Use environment variables instead of command line arguments for
sensitive configuration settings such as login credentials and
connection information. For example, use MDB_MCP_API_CLIENT_ID and
MDB_MCP_API_CLIENT_SECRET for API client settings, and
MDB_MCP_CONNECTION_STRING for connection strings.
Environment variables are more secure than command line arguments. Command line arguments can be tracked, cached, included in process lists, and logged in various locations.
To connect with Atlas API credentials, set the MDB_MCP_API_CLIENT_ID
and MDB_MCP_API_CLIENT_SECRET environment variables in the env
section of the JSON configuration file for the AI client:
... "args": [ "-y", "mongodb-mcp-server@latest", "--readOnly" ], "env": { "MDB_MCP_API_CLIENT_ID": "<atlas-service-account-client-id>", "MDB_MCP_API_CLIENT_SECRET": "<atlas-service-account-client-secret>" } ...
Replace <atlas-service-account-client-id> and
<atlas-service-account-client-secret> with your Atlas information.
For complete JSON configuration file examples for various AI clients, see Get Started with the MongoDB MCP Server.
Connecting with Cluster Connection String
If you don't want to use Atlas API credentials for security or another reason, you can connect to a cluster using a MongoDB connection string.
The following example shows a connection string to connect to an Atlas cluster:
... "args": [ "-y", "mongodb-mcp-server@latest", "--readOnly" ], "env": { "MDB_MCP_CONNECTION_STRING": "mongodb+srv://<user-name>:<password>@<cluster-name>.mongodb.net/<database-name>" } ...
Replace <user-name>, <password>, <cluster-name>, and
<database-name> with your Atlas information.
You can also connect to a local cluster with a connection string. For example:
... "args": [ "-y", "mongodb-mcp-server@latest", "--readOnly" ], "env": { "MDB_MCP_CONNECTION_STRING": "mongodb://127.0.0.1:27019/?directConnection=true" } ...
Important
The --connectionString CLI argument is deprecated. Use
the MDB_MCP_CONNECTION_STRING environment variable instead.
If environment variables are not an option,
use the first positional argument.
Defining MCP Server Environment Variables in the Operating System
You can define environment variables to set various configuration options for the MCP Server.
To define operating system environment variables for the MCP Server, use
the prefix MDB_MCP_ followed by the variable name in uppercase with
underscores. For example, use MDB_MCP_CONNECTION_STRING to set the
connectionString option.
Use environment variables instead of command line arguments for
sensitive configuration settings such as login credentials and
connection information. For example, use MDB_MCP_API_CLIENT_ID and
MDB_MCP_API_CLIENT_SECRET for API client settings, and
MDB_MCP_CONNECTION_STRING for connection strings.
Environment variables are more secure than command line arguments. Command line arguments can be tracked, cached, included in process lists, and logged in various locations.
In the examples in the following sections, replace
<atlas-service-account-client-id>,
<atlas-service-account-client-secret>, <user-name>,
<password>, <cluster-name>, and <database-name> with your
Atlas information.
Unix Environment Variables
The following examples show how to define MCP Server environment variables in a Unix-based operating system:
# Set Atlas API credentials for a service account export MDB_MCP_API_CLIENT_ID="<atlas-service-account-client-id>" export MDB_MCP_API_CLIENT_SECRET="<atlas-service-account-client-secret>" # Set a MongoDB connection string export MDB_MCP_CONNECTION_STRING="mongodb+srv://<user-name>:<password>@<cluster-name>.mongodb.net/<database-name>" # Change the MCP Server log path from the default export MDB_MCP_LOG_PATH="/mcp/logs"
Windows Command Line Environment Variables
The following examples set the variables using in a Windows command line:
:: Set Atlas API credentials for a service account set MDB_MCP_API_CLIENT_ID=<atlas-service-account-client-id> set MDB_MCP_API_CLIENT_SECRET=<atlas-service-account-client-secret> :: Set a MongoDB connection string set MDB_MCP_CONNECTION_STRING="mongodb+srv://<user-name>:<password>@<cluster-name>.mongodb.net/<database-name>" :: Change the MCP Server log path from the default set MDB_MCP_LOG_PATH="C:\mcp\logs"
Windows PowerShell Environment Variables
The following examples set the variables in a Windows PowerShell session:
# Set Atlas API credentials for a service account $env:MDB_MCP_API_CLIENT_ID="<atlas-service-account-client-id>" $env:MDB_MCP_API_CLIENT_SECRET="<atlas-service-account-client-secret>" # Set a MongoDB connection string $env:MDB_MCP_CONNECTION_STRING="mongodb+srv://<user-name>:<password>@<cluster-name>.mongodb.net/<database-name>" # Change the MCP Server log path from the default $env:MDB_MCP_LOG_PATH="C:\mcp\logs"