MongoDB MCP: bad auth authentication failed (percent-encode special chars in password)

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.

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.

1. Percent-encode them:

• @ becomes %40
• / becomes %2F
• ? becomes %3F
• # becomes %23
• % becomes %25 (do this one first)

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

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

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

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.