Feature: MongoDB Atlas Service Discovery (UX)

[tnaum-ms]

Add MongoDB Atlas Service Discovery Plugin

Background

DocumentDB for VS Code includes an open Service Discovery architecture that allows plugins to authenticate with a vendor environment, navigate its resource hierarchy, discover database services, and surface connection strings back to the extension. Today, three Azure-based plugins are available:

• Azure Cosmos DB for MongoDB (RU)
• Azure DocumentDB (vCore)
• Azure VMs (DocumentDB)

This issue proposes a new MongoDB Atlas service discovery plugin so users who host clusters on Atlas can discover and connect to them without manually copying connection strings.

Prior Work and Related Provider

There are two relevant prior efforts:

1. PR #267 (linked to #259 and #261) implements a first cut of the programmatic access layer for Atlas under src/plugins/service-mongo-atlas/. As shipped, it covers:

   • Authentication. Both OAuth 2.0 Client Credentials and HTTP Digest (Atlas API Keys), with token caching and automatic refresh.
   • API client. Typed methods to list projects, list and get clusters (including connection strings), list database users, and manage IP access list entries. Pagination is supported.
   • Tests. Unit tests with mocked HTTP responses where feasible at low dev time cost.

   Caveat to verify early. This layer was written some time ago and has not been actively maintained. It may be out of date with the current Atlas Admin API, may not be well structured for the way the Discovery View consumes providers today (especially after the K8s provider work), and may be insufficient to cover the hierarchy and connection string variants we want to surface. Before any UI work starts, the data layer needs to be revalidated against the live Atlas API and against the current internal discovery plugin contract. Expect non-trivial refactoring or partial rewrites here; do not assume it is drop-in.

2. PR #621 (feat(kubernetes): add multi-source service discovery) is the most recent end-to-end example of a non-Azure discovery provider and is the closest reference implementation for what Atlas needs. It is worth treating as the template for this work because it covers the full vertical:

   • a data access layer (kubeconfig parsing, multi-source kubeconfig management, context aliases, service-driven connection resolution, port-forward lifecycle handling), which is the K8s equivalent of what PR Implementation for Atlas Service Discovery Programmatic Access #267 attempted to provide for Atlas,
   • a plugin integration into the Discovery View (provider registration, Manage Credentials and Filter entry points, tree-item affordances, telemetry, localization, tests), which is the layer this issue is specifically about,
   • a small internal Discovery API expansion to cover cases the Azure-only providers never exercised (service-driven connections, provider-managed lifecycle behaviors).

   That API expansion is expected and acceptable. The internal discovery plugin API is intentionally pre-public, and each new non-Azure provider is how we surface its limitations before it graduates into a public extension API for service discovery. Atlas is likely to push on the same shape (org/project hierarchy, non-Azure credential models, paginated remote listing), so further small API adjustments here are anticipated.

This issue covers everything above the data layer: the Discovery View integration, user-facing wizards, and tree view experience, plus whatever refresh of the PR #267 code turns out to be necessary.

Goal

Users should be able to:

1. Enable the Atlas plugin from the Service Discovery panel, the same way they enable existing providers.
2. Authenticate via the Manage Credentials entry point. The user provides either OAuth 2.0 credentials (Service Account client ID + secret) or HTTP Digest credentials (API public + private key), scoped to an Atlas Organization.
3. Browse their Atlas estate in the Discovery tree view (Organizations, Projects, and Clusters) with cluster type, state, and region visible at a glance.
4. Filter visible resources via the Filter entry point to narrow which organizations or projects appear, mirroring how Azure plugins filter by tenant and subscription.
5. Select a cluster to have its connection string resolved and added to the Connections view.

UX Expectations

• Follow the same UX patterns established by existing plugins. Use the existing service discovery plugin infrastructure, including the DiscoveryProvider registration, the Manage Credentials entry point, and the Filter entry point.
• The Manage Credentials wizard should let users add, view, and remove Atlas credentials. Unlike Azure plugins (which use VS Code's Azure account login), Atlas requires user-entered API key pairs, so the UX should guide users through this clearly.
• The Filter wizard should let users scope which parts of their Atlas estate are visible in the tree.
• Tree items should have the same affordances as existing plugins: refresh, retry on error, learn more link, etc.
• See Managing Azure Discovery for the credential and filter UX to emulate.

Open Questions for Scoping

Even after PR #267, the following should still be resolved during scoping (and several of them depend on first validating that the existing data layer is current and complete):

• Data layer health. Is the PR Implementation for Atlas Service Discovery Programmatic Access #267 client still aligned with the current Atlas Admin API v2? Does it still build against the current provider contract used by the Azure and K8s plugins? Are there endpoints or response fields it never modeled that we now need? This determines how much of the work is "wire up UX" vs. "rebuild the client."
• Organization listing. The API client lists projects but not organizations. Is there an endpoint to list orgs, or should the user enter their Org ID during credential setup?
• Hierarchy in the tree. Do we surface Organizations -> Projects -> Clusters as three tree levels, or Projects -> Clusters with org only as a credential scope? Decision should be informed by rough customer cardinality numbers (orgs per user, projects per org, clusters per project) for the personas we care about.
• Teams and groupings. Does Atlas have Teams or other structures that affect API key scoping or project visibility? Should these appear in the tree or filter?
• Connection string variants. Atlas clusters expose SRV, standard, private, and private-endpoint connection strings. Which should the plugin prefer? Should the user choose?
• IP Access List. The API layer already supports managing IP access list entries. Should the discovery flow offer to add the user's current IP if the cluster is unreachable? This is a common Atlas onboarding friction point.
• Minimum permissions. What Atlas role is required for read-only discovery? Document this for users.

Working Model

This feature spans more than one PR (data layer refresh, any internal Discovery API adjustments, Manage Credentials wizard, Filter wizard, tree provider, telemetry, l10n, docs). It should be developed against a long-lived feature branch, for example feature/atlas-discovery, with topic PRs merging into that branch and a single integration PR into main at the end. Same pattern as the K8s work in PR #621.

Next Steps

1. Scoping and design discussion. Confirm v1 surface area (auth methods, hierarchy, connection string variants), and decide which parts of the K8s PR's internal API changes Atlas should reuse vs. propose a new shape for.
2. Validate the existing data layer. Before assuming PR Implementation for Atlas Service Discovery Programmatic Access #267 is the foundation, run it against the current Atlas Admin API and against the current provider contract. Decide whether to refresh in place, refactor, or partially rewrite. Capture the gaps.
3. User flow and scenarios. Produce a short scenarios doc with 3 to 5 personas (single-project hobbyist, multi-project team, multi-org consultant, enterprise with many orgs, CI / service-account user). The goal is to clarify the hierarchy question above using realistic cardinality numbers.
4. POC, only if needed. On top of the (validated or refreshed) data layer, confirm that the chosen hierarchy can actually be extracted from the Atlas Admin API with acceptable pagination behavior, and confirm connection string variant selection.
5. ASCII art design. Before any UI code, produce ASCII art variants of the Discovery tree (org/project/cluster levels, badges for cluster type/state/region), the Manage Credentials wizard steps, and the Filter wizard steps. Same approach as PR #653 for Local Quick Start.
6. Implementation. Topic PRs into feature/atlas-discovery:
   • data layer refresh / refactor as needed,
   • any internal Discovery API adjustments surfaced by the design,
   • Manage Credentials wizard,
   • Filter wizard,
   • tree provider and item affordances (refresh, retry, learn more),
   • telemetry, l10n, docs,
   • integration PR feature/atlas-discovery into main.

Out of Scope

• Atlas management features beyond discovery (scaling, metrics, alerts).
• Public extension API for service discovery. The internal API may evolve to accommodate Atlas; graduating it to a public API is a separate effort informed by Azure, K8s, and Atlas together.

References

• Prior work. PR #267, #259, #261
• Reference provider. PR #621 (Kubernetes service discovery)
• Service Discovery overview
• Managing Azure Discovery (credentials and filtering UX)
• Existing plugins under src/plugins/service-azure-* for patterns to follow
• MongoDB Atlas Administration API v2 docs

[tnaum-ms]

Pre-read for the sync

This is a short orientation for everyone joining the initial sync. The full details live in the issue description above; this comment is just enough context to have the conversation.

What this is

A new Service Discovery plugin for MongoDB Atlas, alongside the existing Azure providers. A first cut of the programmatic access layer exists from PR #267; what is left is the Discovery View integration (Manage Credentials, Filter, tree experience), plus whatever refresh of that data layer turns out to be necessary.

Caveat on the existing data layer

PR #267 was written some time ago and has not been actively maintained. It may be out of date with the current Atlas Admin API, may not be well structured for the current discovery provider contract (especially after the K8s provider work), and may be insufficient to cover the hierarchy and connection string variants we want to surface. This needs to be tested early. Do not assume it is drop-in; expect some refactoring or partial rewrite.

Why now / why it is interesting

The recent Kubernetes Service Discovery work in PR #621 is the closest reference: it ships both a data access layer and a full plugin integration into the Discovery View, and it had to extend the internal discovery plugin API a little to express things the Azure-only providers never exercised. That is expected and acceptable. Each new non-Azure provider is how we surface the limits of the current internal API before it graduates into a public extension API for service discovery. Atlas will likely push on it again (org/project hierarchy, non-Azure credentials, paginated remote listing), and that input is valuable.

Working model

This feature will span multiple PRs (data layer refresh, API tweaks, Manage Credentials wizard, Filter wizard, tree provider, telemetry, l10n, docs). It should be developed against a long-lived feature branch, for example feature/atlas-discovery, with topic PRs merging into that branch and a single integration PR into main at the end. Same pattern as the K8s work.

Proposed next steps

1. Scoping and design discussion (this sync). Confirm v1 surface area and which K8s API changes Atlas should reuse vs. propose new shape for.
2. Validate the existing data layer from PR Implementation for Atlas Service Discovery Programmatic Access #267 against the live Atlas API and the current provider contract. Decide: refresh, refactor, or partial rewrite.
3. User flow and scenarios. Main open question: how do we structure the hierarchy? Organizations -> Projects -> Clusters in the tree, or Projects -> Clusters with org only as a credential scope? We need rough customer cardinality numbers (orgs per user, projects per org, clusters per project) to decide.
4. POC, only if needed, on top of the validated data layer, to confirm the chosen hierarchy can actually be extracted from the Atlas Admin API with acceptable pagination behavior.
5. ASCII art design of the tree, Manage Credentials wizard, and Filter wizard before any UI code (same approach as PR #653).
6. Implementation as topic PRs into feature/atlas-discovery.

What we need from the sync

• Agreement on the feature-branch working model.
• A first cut on the hierarchy question (org as tree level vs. credential scope).
• An owner for the issue, including the data layer validation step.