[Feature] Support Atlas CLI-style OAuth device flow auth (avoid storing Service Account secret locally)

[zerocolds]

Summary

Add support for OAuth device flow authentication for Atlas Admin API, similar to how atlas auth login works in the official Atlas CLI.

Motivation

Today, the only options for Atlas Admin API auth in the MCP server are:

• MDB_MCP_API_CLIENT_ID + MDB_MCP_API_CLIENT_SECRET (Service Account via OAuth 2.0 client_credentials grant)
• MDB_MCP_CONNECTION_STRING (DB-user level, no Admin API)

For developers running the MCP server locally (e.g. inside Claude Code, Cursor, Cline), the Service Account path requires:

1. Creating a long-lived Client Secret
2. Storing it in ~/.mcp-env or a shell profile
3. Manually managing rotation and IP allowlists

This is a meaningful difference vs. the user-flow OAuth that atlas auth login, gh auth login, az login, and gcloud auth login all provide — where credentials live in OS-managed storage and inherit the user's existing org permissions without a separate principal.

Proposed feature

Add a new auth mode, e.g.:

MDB_MCP_AUTH_MODE=oauth-device

When set, the server should:

1. On first start, perform an OAuth 2.0 device authorization flow against account.mongodb.com (the same endpoint Atlas CLI uses).
2. Display the verification URL + user code in stderr.
3. Persist the resulting refresh token in the OS-native keychain (macOS Keychain / Windows Credential Manager / libsecret), or fall back to a token file at ~/.config/mongodb-mcp/credentials.json with chmod 600.
4. Refresh access tokens transparently before they expire.
5. Use the access token as Authorization: Bearer ... against the Atlas Admin API.

Alternatively (or in addition), the server could read the existing Atlas CLI token from ~/Library/Application Support/atlascli/config.toml (or platform equivalent) — letting users authenticate once via atlas auth login and have the MCP server pick it up automatically.

Why this matters

• Security: no long-lived secret on disk; refresh tokens are revocable; access tokens expire short.
• Permissions parity: the user gets the exact set of permissions they have in the Atlas web UI, no risk of granting an over-privileged Service Account.
• Onboarding: removes the Service Account creation + Client ID/Secret + API Access List dance for individual developers.
• Precedent: this is the standard pattern across major cloud CLIs and developer tools.

Acceptance criteria

• New MDB_MCP_AUTH_MODE=oauth-device option (or equivalent)
• Device authorization flow implemented against MongoDB's existing OAuth provider
• Refresh-token storage in keychain or chmod 600 file
• Documentation updated in https://www.mongodb.com/docs/mcp-server/prerequisites/
• Existing Service Account auth remains supported

Related

• Atlas CLI implements this: https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-quickstart/
• Prior auth-related work: [Atlas] Use service accounts for auth #39, feat: Add configurable api / auth client support #836, feat: support for OIDC connectivity between the MCP Server and a MongoDB Cluster MCP-84 #450

[github-actions]

Thanks for opening this issue. The ticket MCP-492 was created for internal tracking.