MongoDB MCP: bad auth authentication failed (percent-encode special chars in password)
Fixes the MongoDB MCP server failing to connect when the database password contains special characters. Characters like @, /, ? and # break connection-string parsing and must be percent-encoded. Use when valid credentials are rejected with a parse or auth error; not for IP-allowlist timeouts.
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
- Identify URL-reserved characters in the password value
@ : / ? # [ ]and%itself.
- Percent-encode them:
@becomes%40/becomes%2F?becomes%3F#becomes%23%becomes%25(do this one first)
p@ss/word becomes p%40ss%2Fword.
- Update
MDB_MCP_CONNECTION_STRINGin the client configenvblock and restart the client.
Expected: the server connects and tools work. No auth error.
- 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.
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.