TL;DR: If your MongoDB password contains `@`, `/`, `?`, `#` or `%`, the connection string parser eats them as URL syntax and auth fails. Percent-encode each special character (`@` to `%40`, `/` to `%2F`) and the same credentials will connect.

```text
MongoServerError: bad auth : authentication failed
```

(Variant: connection string parse errors mentioning unexpected characters.)

## Fix it

1. Identify URL-reserved characters in the password value `@ : / ? # [ ]` and `%` itself.

2. Percent-encode them:
   - `@` becomes `%40`
   - `/` becomes `%2F`
   - `?` becomes `%3F`
   - `#` becomes `%23`
   - `%` becomes `%25` (do this one first)

   `p@ss/word` becomes `p%40ss%2Fword`.

3. Update `MDB_MCP_CONNECTION_STRING` in the client config `env` block and restart the client.

   Expected: the server connects and tools work. No auth error.

4. Verify independently with mongosh before blaming the MCP layer:

```bash
mongosh "mongodb+srv://cluster.mongodb.net/mydb"
```

   Expected: a connected shell prompt.

## When to use this

- Auth fails through the MCP server but the same credentials work when typed into mongosh or Compass (which handle encoding for you).
- The password was auto-generated and contains symbols.

## When NOT to use this

- The error is a timeout or `ServerSelectionTimeoutError`. That is network or IP-allowlist, not encoding.
- The username itself is wrong. Encoding will not fix a bad username.

## Compatibility

- mongodb-mcp-server, any MongoDB driver-based tool.
- MongoDB Atlas and self-hosted.

## Why it happens

A connection string is a URL. `@` separates credentials from the host, `/` starts the path, `?` starts query options. An unencoded `@` in the password makes the parser split the string at the wrong point, so the driver sends a truncated password and the server rejects it. Percent-encoding is the URL-standard way to say these characters are literal.

## Edge cases

- Encode `%` first. Encoding it last double-encodes the `%` signs you just added.
- Atlas passwords with only alphanumerics never hit this. If you control password generation, avoiding symbols sidesteps it entirely.
- Some clients also need the username encoded if it contains special characters.