MongoDB MCP Server Security Best Practices

JSON Configuration File Example

The following example shows --readOnly in the MCP client JSON configuration file for the Claude Desktop client application:

{
   "mcpServers": {
      "MongoDB": {
         "type": "stdio",
         "command": "npx",
         "args": [
            "-y",
            "mongodb-mcp-server@latest",
            "--readOnly"
         ],
         "env": {
            "MDB_MCP_CONNECTION_STRING":
            "mongodb://localhost:27017/myDatabase"
         }
      }
   }
}

For other example client JSON configuration files, see Configure the MCP Server.

Command Line Example

The following example defines the MCP Server connection string in a Unix environment variable to connect to an Atlas cluster:

export MDB_MCP_CONNECTION_STRING="mongodb://localhost:27017/myDatabase"

The following example uses the previous environment variable, and also sets an additional command line option:

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

Secrets and Environment Variables

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.

The following example sets the MDB_MCP_READ_ONLY environment variable to true and sets the MDB_MCP_CONNECTION_STRING environment variable:

"MongoDB": {
   "type": "stdio",
   "command": "npx",
   "args": [
      "-y",
      "mongodb-mcp-server@latest",
   ],
   "env": {
      "MDB_MCP_READ_ONLY": "true",
      "MDB_MCP_CONNECTION_STRING":
      "mongodb://127.0.0.1:27019/?directConnection=true"
   }
}

For more information about environment variables, see Defining MCP Server Environment Variables in the Operating System.

Local MCP Server

In a local MCP Server, the MCP Server and the client application run on the same computer.

A local MCP Server enables control over the installation environment:

• Configuration and dependencies: you manage the MCP Server software dependencies. To define the MCP Server parameters and database connections, edit files on the local computer.

• Credentials security: sensitive information for API keys and connection strings are stored locally in configuration files or environment variables. You secure the credentials.

• Manual software updates: when a new MCP Server version is available, users can download and install the MCP Server software. This can cause users to run different MCP Server versions.

Remote MCP Server

In a remote MCP Server deployment, the MCP Server runs on a computer in the cloud or on an on-premises server.

Client applications connect to the MCP Server over the network and use Streamable HTTP. This provides a central shared environment that is accessible to multiple users, automated systems, applications, and AI agents.

Consider the following points for MCP Server remote deployments:

• Remote deployment has extra security risks and requires a secure configuration.

• At minimum, you need to configure network isolation, authentication to the MCP Server, and set up secrets management in the cloud or on premises.

Delegated Authorization

In delegated authorization, the user delegates a subset of their authority to an agent. MongoDB recommends the use of OAuth 2.1 with the MCP Server.

To operate with the MCP Server, a deployment must have an OAuth Authorization Server (AS) protected by authenticated user accounts, and a proxy in front of the MCP Server that operates as an OAuth Resource Server (RS). The agent operates as an OAuth client.

OAuth delegation operates as follows:

1. Agent requests access to the MCP Server. The MCP Server is protected by a proxy.

2. Proxy sends the agent to the AS, which starts an authorization request

3. User logs in to the AS and authorizes the agent to access the RS, which is the proxy that protects the MCP Server.

4. Agent is given an access token to access the RS.

5. Agent uses the access token to call the MCP Server through the proxy.

6. Proxy validates the access token and allows the call to the MCP Server.

7. MCP Server receives the proxy request and runs the command on the database through the statically configured secure connection.

The MCP Server and the database never read the access token. The proxy is trusted to protect the MCP Server. Bypassing the proxy risks access to the MCP Server and the databases that the MCP Server can access.

The format of the token is hidden. JWTs are a common format that allow the proxy to independently verify the token issued by the AS.

Direct Authentication

Direct authentication isn't recommended.

With direct authentication, the agent provides credentials to the proxy. The proxy authenticates the credentials. The credentials can be an API key or other credential that identifies the agent. The pattern is simple but has the following problems:

• Only the agent is identified, not the user for which the agent is acting.

• There is no method to audit who is taking which action through the MCP Server.

• Access is usually controlled centrally for all users, or directly at the proxy.

User Impersonation

Do not use user impersonation.

With user impersonation, the user provides their credentials directly to the agent. The agent sends the credentials to the proxy for authentication. User impersonation has the following problems:

• Only the user is identified. The fact that the agent acts on the user's behalf is hidden.

• User credentials are leaked to intermediate systems. This puts user accounts at risk.

• Actions the user can perform are allowed for the agent, and limited release of functions is impossible.

• Disconnecting an agent requires rotation of user credentials, which disrupts user accounts and systems.

• Non-phishable and non-replayable credentials cannot operate.

Pass-Through Authentication

Do not use pass-through authentication.

In pass-through authentication, the agent obtains and passes credentials to access the database to the proxy. The proxy validates the credentials and passes the credentials to the MCP Server. The MCP Server uses the credentials to connect to the database. Pass-through authentication has the following problems:

• Only copyable and replayable credentials can operate, which limits connections to low security options.

• The connection chain is hidden from the system.

• Anyone can potentially omit the next part of the chain.

Database Authentication and Authorization

The MCP Server supports the following database authentication methods:

• Enterprise authentication with LDAP, X.509 certificates, OIDC, and Kerberos.

• Default SCRAM-SHA-256 authentication to provide strong password authentication.

• mTLS certificate authentication for service accounts and inter-cluster communication.

The MongoDB database supports the following authorization methods:

• RBAC to limit database access.

• Granular database permissions to limit access to specific databases, individual collections, and operations like read, write, and administrative actions.

• Custom database roles for teams. For example, read-only access for analytics team and read-write access for operations team.

• Additional collection security to limit collection access.

Network Security

Recommendations for network isolation:

• Deploy clusters in a private VPC or VNet without direct Internet access.

• Secure connections to cloud private network with VPC peering and private endpoints.

• Restrict database access to specific IP addresses or CIDR blocks.

Recommendations for firewall configuration:

• Restrict access to MongoDB server port 27017 to authorized application servers only.

• Configure cloud firewall rules with security groups and an ACL for incoming and outgoing network traffic.

• Disable non-encrypted ports and enforce TLS 1.2+ for all connections.