MongoDB MCP Server Configuration

The MongoDB MCP Server is currently in Public Preview.

You must configure the MCP Server to connect an AI client to the cluster. You can then use an AI client to perform cluster operations.

This page describes AI client compatibility, how to configure the MCP Server, troubleshooting, and disabling MCP Server tools and telemetry.

AI Client Compatibility

The MCP Server is compatible with many AI clients that support MCP. For example, you can use these AI clients:

The JSON configuration file structure can vary for each AI client. Read the AI client documentation for details.

Prerequisites

Ensure you have already installed the software as specified in MCP Server software prerequisites.

The MCP Server can run Atlas tools that perform various Atlas operations. To run the Atlas tools, your Atlas cluster requires a service account with the appropriate permissions.

To set up a service account, see MongoDB MCP Server Prerequisites for Running Atlas Tools.

For a list of the tools, see MongoDB MCP Server Tools.

MCP Server Configuration Options

The MCP Server has various options that you can set to connect to a cluster and control MCP Server operations. You can set the options in a JSON configuration file, on a command line, or in operating system environment variables.

The following table shows the main MCP Server configuration options.

Important

If you're a MongoDB Enterprise or MongoDB Atlas user and you require a specific authentication mechanism, see the MongoDB MCP Server Security section to learn about the configuration options for your authentication method.

CLI Option Name	OS Environment Variable Name	Type	Default	Description
`apiClientId`	`MDB_MCP_API_CLIENT_ID`	string	Not set	Atlas API client ID for authentication.
`apiClientSecret`	`MDB_MCP_API_CLIENT_SECRET`	string	Not set	Atlas API client secret for authentication.
`connectionString`	`MDB_MCP_CONNECTION_STRING`	string	Not set	Connection string for a direct database connection. Sets the connection string at runtime to allow the client to directly connect to a cluster. Note Typically, avoid providing the connection string at runtime because you expose the connection credentials to the large language model. The connection string is used if the client has never connected before, or the client switches the connection to a new cluster if the client was previously connected. After the client calls the connect or switch connection tool, the client reuses the same connection for subsequent operations. Therefore, you only need to call the connect or swtich connection tool once or if you need to switch to a different connection.
`loggers`	`MDB_MCP_LOGGERS`	string	`disk mcp`	Specifies where the MCP Server sends the logs. Set `loggers` to one or more of the following options: `disk`, which writes logs to disk files located in the path specified in the `logPath` option. `mcp`, which sends the logs to the AI client, if the client supports logging and transport protocol. `stderr`, which sends the logs to the standard error output. This setting is useful for debugging or when running MCP in a container. For example, to set `loggers` to `mcp` and `stderr` in the AI client JSON configuration file or the operating system command line, use `--loggers mcp stderr`. To set the `MDB_MCP_LOGGERS` operating system environment variable to `disk` and `stderr`, use `export MDB_MCP_LOGGERS="disk,stderr"`. For more information about the logging options, see Troubleshooting MCP Server.
`logPath`	`MDB_MCP_LOG_PATH`	string	Depends on the operating system	Directory that stores the MCP Server logs. For more information about the log path and operating system specifics, see Troubleshooting MCP Server.
`disabledTools`	`MDB_MCP_DISABLED_TOOLS`	array	Not set	An array of MCP tool names, operation types, or tool categories to disable. For more information, see Disabling MCP Server Tools.
`readOnly`	`MDB_MCP_READ_ONLY`	boolean	`false`	To disable cluster write operations, set `--readOnly` in the configuration file or command line, or set the `MDB_MCP_READ_ONLY` operating system environment variable to `true`. Default is to allow cluster write operations. Typically, always enable read-only mode. For more information, see Enabling MCP Server Read-Only Mode.
`indexCheck`	`MDB_MCP_INDEX_CHECK`	boolean	`false`	If `true`, enforces that query operations must use an index and rejects queries that perform collection scans. For more information, see Enabling Index Check.
`telemetry`	`MDB_MCP_TELEMETRY`	string	`enabled`	If `disabled`, MCP Server usage data collection is stopped. For more information, see Disabling MCP Server Telemetry.
`transport`	`MDB_MCP_TRANSPORT`	string	`stdio`	Transport protocol for communications with the MCP Server. Set `transport` to one of the following options: `stdio`, which is the default. Uses the standard input and output for communications with the MCP Server. `stdio` is suitable for most AI clients. `http`, which enables HTTP communications with the MCP Server. You can then use HTTP to interact with the MCP Server from a Web client or communicate with the MCP Server on a specific HTTP IP port. Warning HTTP transport is NOT recommended for production use without implementing proper authentication and security measures.
`httpPort`	`MDB_MCP_HTTP_PORT`	integer	`3000`	IP port number for HTTP communications with the MCP Server.
`httpHost`	`MDB_MCP_HTTP_HOST`	string	`127.0.0.1`	IP address for HTTP communications with the MCP Server.
`idleTimeoutMs`	`MDB_MCP_IDLE_TIMEOUT_MS`	integer	`600000`	Idle timeout for a client to disconnect. Only applies to HTTP transport.
`notificationTimeoutMs`	`MDB_MCP_NOTIFICATION_TIMEOUT_MS`	integer	`540000`	Notification timeout for a client to be aware of disconnect. Only applies to HTTP transport.
`authenticationMechanism`	`MDB_MCP_AUTHENTICATION_MECHANISM`	string	`SCRAM-SHA-256`	SCRAM is the default authentication mechanism for MongoDB. To connect to your MongoDB deployments with the MongoDB MCP server using other authentication methods, see the following pages: Connect with OpenID Connect (OIDC) Connect with LDAP Connect with Kerberos Connect with X.509 Certificates Connect with Proxy

MCP Server Configuration Methods

To configure the MCP Server, 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. stdio is suitable for most AI clients. Typically use stdio.
"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.

To connect with Atlas API credentials, set the apiClientId and apiClientSecret options in the "args" section of the JSON configuration file for the AI client:

...
"args": [
   "-y",
   "mongodb-mcp-server",
   "--apiClientId", "<atlas-service-accounts-client-id>",
   "--apiClientSecret", "<atlas-service-accounts-client-secret>",
   "--readOnly"
]
...

For a complete JSON configuration file example for your AI client, 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 connectionString to connect to an Atlas cluster in the "args" section:

...
"args": [
   "-y",
   "mongodb-mcp-server",
   "--connectionString",
   "mongodb+srv://<user-name>:<password>@<cluster-name>.mongodb.net/",
   "--readOnly"
]
...

Replace <user-name>, <password>, and <cluster-name> with your Atlas information.

You can also connect to a local cluster with a connection string. For example:

...
"args": [
   "-y",
   "mongodb-mcp-server",
   "--connectionString",
   "mongodb://127.0.0.1:27019/?directConnection=true",
   "--readOnly"
]
...

Defining MCP Server Environment Variables

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.

For a list of options, see MCP Server Configuration Options.

Defining Environment Variables in Operating System

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-accounts-client-id>"
export MDB_MCP_API_CLIENT_SECRET="<atlas-service-accounts-client-secret>"
# Set a MongoDB connection string
export MDB_MCP_CONNECTION_STRING="mongodb+srv://testUsername:testPassword@testCluster.mongodb.net/testDatabase"
# Change the MCP Server log path from the default
export MDB_MCP_LOG_PATH="/mcp/logs"

The following examples set the same variables using in a Windows command line:

:: Set Atlas API credentials for a service account
set MDB_MCP_API_CLIENT_ID=<atlas-service-accounts-client-id>
set MDB_MCP_API_CLIENT_SECRET=<atlas-service-accounts-client-secret>
:: Set a MongoDB connection string
set MDB_MCP_CONNECTION_STRING="mongodb+srv://testUsername::testPassword@testCluster.mongodb.net/testDatabase"
:: Change the MCP Server log path from the default
set MDB_MCP_LOG_PATH="C:\mcp\logs"

The following examples set the same variables in a Windows PowerShell session:

# Set Atlas API credentials for a service account
$env:MDB_MCP_API_CLIENT_ID="<atlas-service-accounts-client-id>"
$env:MDB_MCP_API_CLIENT_SECRET="<atlas-service-accounts-client-secret>"
# Set a MongoDB connection string
$env:MDB_MCP_CONNECTION_STRING="mongodb+srv://testUsername::testPassword@testCluster.mongodb.net/testDatabase"
# Change the MCP Server log path from the default
$env:MDB_MCP_LOG_PATH="C:\mcp\logs"

Defining Connection String Environment Variable in Configuration File

The following example shows how to define the connection string environment variable in the "env" section of a JSON configuration file:

...
"args": ["-y", "mongodb-mcp-server"],
"env": {
   "MDB_MCP_CONNECTION_STRING":
   "mongodb+srv://<user-name>:<password>@<cluster-name>.mongodb.net/testDatabase"
}
...

Replace <user-name>, <password>, and <cluster-name> with your Atlas information.

Defining Atlas API Environment Variables in Configuration File

The following example shows how to define Atlas API environment variables in the "env" section of a JSON configuration file:

...
"args": ["-y", "mongodb-mcp-server"],
"env": {
   "MDB_MCP_API_CLIENT_ID": "<atlas-service-accounts-client-id>",
   "MDB_MCP_API_CLIENT_SECRET": "<atlas-service-accounts-client-secret>"
}
...

Enabling MCP Server Read-Only Mode

You can limit the MCP Server to perform only read operations using read-only mode.

Default is to allow cluster write operations. Typically, always enable read-only mode.

To enable read-only mode with a command line option, use:

--readOnly

To enable read-only mode using an environment variable, set the MDB_MCP_READ_ONLY environment variable to true:

export MDB_MCP_READ_ONLY=true

When you enable read-only mode, a message is added to the MCP Server log that indicates the tools that perform write operations are prevented from running.

Troubleshooting MCP Server

If you have issues with the MCP Server, examine the MCP Server logs for information that can help troubleshoot the problem.

By default, the MCP Server writes the logs to disk and also sends the logs to the MCP client. You can change the loggers option to specify where the logs are sent. For details about the MCP Server options, see MCP Server Configuration Options.

The following table shows the default directories where the MCP Server stores the log files:

Operating System	Default Log Directory
Windows	`%LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs`
macOS and Linux	`~/.mongodb/mongodb-mcp/.app-logs`

You can change the log path if required. To do that, set one of these:

logPath option in a JSON configuration file or command line
MDB_MCP_LOG_PATH environment variable

Disabling MCP Server Tools

To restrict access to Atlas and database operations, you can disable specific MCP Server tools or categories of tools.

To disable tools, set the disabledTools MCP Server configuration option, which is an array of strings. Each string can be a tool name or tool category.

The following table shows the tool names that you can disable:

Tool Name	Description	Example Operations Disabled
`create`	Create resources	Create cluster Insert document
`update`	Update resources	Update document Rename collection
`delete`	Delete resources	Delete document Drop collection
`read`	Read resources	Find Aggregate List clusters
`metadata`	Read metadata	List databases List collections Read collection schema

The following table shows the tool categories that you can disable:

Tool Category	Description	Example Operations Disabled
`atlas`	Atlas tools	List clusters Create cluster
`mongodb`	Database tools	Find Aggregate

To disable tools with the disabledTools command line option, use a space-separated list. For example:

--disabledTools create update delete atlas

To disable tools with the MDB_MCP_DISABLED_TOOLS environment variable, use a comma-separated string. For example:

export MDB_MCP_DISABLED_TOOLS="create,update,delete,atlas"

Disabling MCP Server Telemetry

To prevent the MCP Server from collecting data about usage, you can disable telemetry.

To disable telemetry using an environment variable, set either of these:

export MDB_MCP_TELEMETRY=disabled
export DO_NOT_TRACK=1

To disable telemetry using a command line option, use:

--telemetry disabled

Enabling Index Check

To ensure query operations use an index, enable the index check option. When enabled, the MCP Server rejects queries that perform a collection scan to improve performance and ensure queries are optimized.

To enable the index check with a command line option, use:

--indexCheck

To enable the index check with an environment variable, use:

export MDB_MCP_INDEX_CHECK=true

If you enable the index check, the MCP Server logs an error message if a query is rejected because it doesn't use an index.

Starting MCP Server as Standalone Service Using npx Command

To start the MCP Server as a standalone service, use the npx command.

Standalone Service Using Command Line Options

The following example starts the MCP Server with npx and sets the command line options to connect to an Atlas cluster:

npx -y mongodb-mcp-server@latest \
   --apiClientId="<atlas-service-accounts-client-id>" \
   --apiClientSecret="<atlas-service-accounts-client-secret>" \
   --connectionString="mongodb+srv://<user-name>:<password>@<cluster-name>.mongodb.net/<database-name>" \
   --logPath=</path/to/logs> --readOnly --indexCheck --loggers mcp stderr

Replace the option values with your connection information and other details. To examine the list of MCP Server options, see MCP Server Configuration Options.

To create an Atlas service account, see MongoDB MCP Server Prerequisites for Running Atlas Tools.

Standalone Service Using Environment Variables

You can use npx to start the MCP Server and use environment variables. You must have already defined the environment variables before running npx.

To define environment variables in a configuration file or the operating system, see Defining MCP Server Environment Variables.

The following example assumes environment variables have been defined with the connection information, and also sets read-only mode as a command line option:

npx -y mongodb-mcp-server@latest --readOnly

Standalone Service Running as an HTTP Server

The default MCP Server transport protocol is stdio, which is suitable for integration with most MCP clients.

You can also use the HTTP transport protocol with the MCP Server. HTTP is useful if you want to interact with the MCP Server from a Web client or to configure the MCP Server to respond to requests on a specific port.

Note

HTTP transport is not recommended for production use without implementing authentication and security measures. Only use HTTP transport if you must use HTTP to interact with the MCP Server.

Security guidelines:

Implement authentication. For example, use an API gateway or a reverse proxy.
Use HTTPS/TLS encryption.
Deploy the MCP Server behind a firewall or in a private network.
Implement rate limiting.
Never expose connection credentials.

A complete security guide will be available shortly.

To start the MCP Server with HTTP transport, use --transport http. For example:

npx -y mongodb-mcp-server@latest --transport http --readOnly

By default, the MCP Server responds to requests on http://127.0.0.1:3000. To change the host and port, use the --httpHost and --httpPort options. For example:

npx -y mongodb-mcp-server@latest \
   --transport http --httpHost=324.1.5.7 --httpPort=8080 --readOnly

Learn More

Back

Prerequisites

Security

AI Client Compatibility

Prerequisites

MCP Server Configuration Options

Important

Note

Warning

MCP Server Configuration Methods

MCP Server Cluster Connection Methods and Options

Note

Warning

Connecting with Atlas API Credentials

Note

Connecting with Cluster Connection String

Defining MCP Server Environment Variables

Defining Environment Variables in Operating System

Defining Connection String Environment Variable in Configuration File

Defining Atlas API Environment Variables in Configuration File

Enabling MCP Server Read-Only Mode

Troubleshooting MCP Server

Disabling MCP Server Tools

Disabling MCP Server Telemetry

Enabling Index Check

Starting MCP Server as Standalone Service Using npx Command

Standalone Service Using Command Line Options

Standalone Service Using Environment Variables

Standalone Service Running as an HTTP Server

Note

Learn More