MongoDB MCP: Atlas API auth failed (connection string vs API credential modes)

TL;DR: The MongoDB MCP server has two auth modes and they do not mix. Use MDB_MCP_CONNECTION_STRING for a normal database user, or MDB_MCP_API_CLIENT_ID plus MDB_MCP_API_CLIENT_SECRET for an Atlas service account with the Atlas API access steps completed. Pick one, configure it fully, remove the other.

Error: Atlas API authentication failed

Fix it

1. Decide which mode you want:

• Connection string (simplest): a database user and password, MDB_MCP_CONNECTION_STRING set.
• Atlas API (for Atlas admin operations): a service account, MDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET set.

1. For Atlas API mode, complete the Atlas side first: create a service account in Atlas, grant it project roles that cover what the server needs, and copy the client ID and secret. The README's Atlas API Access section lists the required steps. Skipping the role grants is the most common failure.

1. Put exactly one mode's variables in the client config env block. Remove the other mode's variables entirely. Restart the client.

Expected: the server starts and authenticates under the chosen mode.

When to use this

• You set Atlas API credentials and get auth failures.
• You have both MDB_MCP_CONNECTION_STRING and MDB_MCP_API_CLIENT_ID set and things behave unpredictably.

When NOT to use this

• You only want to query data with a database user. Use the connection string and ignore Atlas API mode completely.
• The error is a network timeout. That is the IP access list, not the auth mode.

Compatibility

• mongodb-mcp-server with Atlas.

Why it happens

The two modes authenticate against different Atlas systems: the connection string uses database-user credentials against the cluster, while the API credentials use OAuth-style service accounts against the Atlas admin API. Each needs its own setup. Half-configuring the API path (credentials without roles) or leaving both sets of variables in place produces confusing failures.

Edge cases

• Service account secrets are shown once at creation. If you lost it, create a new secret rather than debugging the old one.
• Atlas API mode is for admin operations (listing clusters, etc.). Plain data queries only need the connection string.
• Rotated secrets need a client restart. The server reads them once at startup.