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.

```text
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.

2. 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.

3. 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.