# mongodb-js/mongodb-mcp-server architecture

> Architecture diagram of the GitHub repository mongodb-js/mongodb-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mongodb-js/mongodb-mcp-server
- Repository: https://github.com/mongodb-js/mongodb-mcp-server

## Overview

1. This repository is a TypeScript/Node.js MCP server for MongoDB. Its job is to expose MongoDB Database tools, MongoDB Atlas tools, Atlas Local tools, and MongoDB Assistant search tools to MCP clients over either stdio or HTTP.

2. The main runtime entrypoints are `src/index.ts`, `src/server.ts`, `src/lib.ts`, and `src/web.ts`. The server is assembled from shared setup code under `src/setup`, then started through a transport layer that determines how MCP requests enter the system.

3. Configuration is a first-class boundary. `src/common/config` parses and merges configuration from a JSON config file, environment variables, and CLI flags, with CLI taking precedence. Sensitive values include MongoDB connection strings and Atlas service account credentials. This config also controls read-only mode, disabled tools, telemetry, logging, export retention, and HTTP transport settings.

4. The transport layer is isolated under `src/transports`. It supports:
   - stdio for normal MCP client integration,
   - Streamable HTTP / SSE or JSON responses for remote use,
   - an in-memory transport used by tests,
   - a monitoring server for health-style endpoints,
   - a dry-run mode for validating config and enabled tools without starting a live server.
   This is the main boundary between external MCP clients and the tool execution core.

5. Tools are organized by domain under `src/tools`:
   - `mongodb` for direct database operations,
   - `atlas` for Atlas org/project/cluster/admin operations,
   - `atlasLocal` for local Atlas deployment management,
   - `assistant` for knowledge-base search and source listing.
   Each domain has its own `tools.ts` registry and operation-specific subfolders for create/read/update/delete/connect/metadata concerns.

6. The MongoDB tool path is the database execution pipeline. `src/common/connectionManager.ts` and related connection/session helpers manage the active connection, while MongoDB tools call into it for reads, writes, schema inspection, indexes, aggregation, exports, and connection switching. Guardrails such as read-only mode, index checks, max document/byte limits, and confirmation-required tools are enforced before or during execution.

7. The Atlas path is a separate API boundary. `src/common/atlas` contains Atlas API client logic, auth providers, cluster and role helpers, and performance-advisor utilities. Atlas tools use service-account credentials and operate on organizations, projects, clusters, access lists, database users, and Atlas Stream Processing resources. This is distinct from direct MongoDB data access.

8. Atlas Local is another isolated subsystem under `src/tools/atlasLocal`, covering create/connect/list/delete of local deployments. It sits between the server and a local deployment manager/containerized environment, and is separate from both Atlas cloud API calls and direct database tools.

9. State and observability are handled through common infrastructure. `src/common/logging` provides console, disk, MCP, and composite loggers. `src/telemetry` tracks usage events and timers. `packages/metrics` contains Prometheus metric definitions and helpers. `src/common/sessionStore.ts`, `src/common/keychain.ts`, and `src/common/exportsManager.ts` manage server-side session persistence, credential storage, and temporary export files.

10. Resources exposed to MCP clients live under `src/resources`. The server publishes configuration, debugging information for connectivity failures, and exported data via URI-backed resources. These are read-side views into server state rather than user commands.

11. The optional UI preview path lives under `src/ui` and is wired by preview features. It includes a registry, loaders, a React component set, and a build mount/template. This is a separate presentation layer on top of the MCP server, not the primary control path.

12. Shared contracts are split into packages. `packages/types` defines cross-cutting public types for API clients, logging, telemetry, transport, sessions, UI, tools, and resources. This package stabilizes interfaces between the server, transports, tests, and generated API surfaces. `packages/metrics` similarly isolates metrics definitions.

13. Deployment and packaging are explicit subsystems. `Dockerfile`, `deploy/aws`, `deploy/azure`, and `packaging/mcpb` provide container and cloud rollout assets, while `scripts/` contains release-note generation, package-version updates, MCPB creation, and test-support tooling. This repo is intended to ship as a server binary/container, not just a library.

14. The tests mirror the architecture: unit tests validate helpers and registries, integration tests exercise transports and real tool flows, browser tests cover UI/embedding behavior, and accuracy tests verify tool outputs against fixtures. This indicates the repo’s main integration boundary is the MCP protocol plus live MongoDB/Atlas behavior, not an internal application domain model.

Main entry points: [`src/setup/setupMcpServer.ts`](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/setup/setupMcpServer.ts) (Setup), [`src/transports/base.ts`](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/transports/base.ts) (Transports), [`tests/integration/server.test.ts`](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/tests/integration/server.test.ts) (Tests), [`src/tools/mongodb/tools.ts`](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/tools/mongodb/tools.ts) (MongoDB Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_entry["Entrypoints<br/>[index.ts]"]
  node_server["Server Core<br/>mcp assembly<br/>[server.ts]"]
  node_setup["Setup<br/>[setupMcpServer.ts]"]
  node_transports["Transports<br/>[base.ts]"]
end

subgraph group_domains["Domains"]
  node_mongo["MongoDB Tools<br/>tool domain<br/>[tools.ts]"]
  node_atlas["Atlas Tools<br/>tool domain<br/>[tools.ts]"]
  node_atlaslocal["Local Tools<br/>tool domain<br/>[tools.ts]"]
  node_assistant["Assistant Tools<br/>search tools<br/>[tools.ts]"]
end

subgraph group_surface["Surface"]
  node_resources["Resources<br/>[resources.ts]"]
  node_ui["UI Preview<br/>react ui<br/>[index.ts]"]
end

subgraph group_shared["Shared"]
  node_config["Config<br/>[parseUserConfig.ts]"]
  node_connection[("MongoDB Core<br/>db connection")]
  node_atlascore["Atlas Core<br/>atlas client<br/>[apiClient.ts]"]
  node_logging["Logging<br/>observability<br/>[index.ts]"]
  node_telemetry["Telemetry<br/>usage metrics<br/>[telemetry.ts]"]
  node_state[("State<br/>[sessionStore.ts]")]
  node_types["Types<br/>shared contracts<br/>[index.ts]"]
  node_metrics["Metrics<br/>prometheus defs<br/>[index.ts]"]
end

subgraph group_delivery["Delivery"]
  node_packaging["Packaging<br/>ship assets<br/>[manifest.json]"]
  node_deploy["Deploy<br/>cloud assets<br/>[README.md]"]
  node_scripts["Scripts<br/>automation<br/>[index.ts]"]
end

subgraph group_tests["Tests"]
  node_testsuite["Tests<br/>verification<br/>[server.test.ts]"]
end

node_entry -->|"bootstraps"| node_server
node_entry -->|"chooses"| node_transports
node_server -->|"assembles"| node_setup
node_setup -->|"reads"| node_config
node_setup -->|"wires"| node_logging
node_setup -->|"instruments"| node_telemetry
node_setup -->|"initializes"| node_state
node_transports -->|"uses"| node_config
node_transports -->|"implements"| node_types
node_mongo -->|"executes on"| node_connection
node_mongo -->|"enforces"| node_config
node_mongo -->|"shares contracts"| node_types
node_atlas -->|"calls"| node_atlascore
node_atlas -->|"auth from"| node_config
node_atlaslocal -->|"exposed via"| node_transports
node_assistant -->|"pairs with"| node_resources
node_resources -->|"reads"| node_state
node_ui -->|"shares contracts"| node_types
node_metrics -->|"feeds"| node_telemetry
node_packaging -->|"built by"| node_scripts
node_deploy -->|"ships"| node_packaging
node_testsuite -->|"validates"| node_transports
node_testsuite -->|"validates"| node_mongo
node_testsuite -->|"validates"| node_atlas
node_testsuite -->|"validates"| node_ui

click node_entry "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/index.ts"
click node_server "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/server.ts"
click node_setup "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/setup/setupMcpServer.ts"
click node_transports "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/transports/base.ts"
click node_config "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/common/config/parseUserConfig.ts"
click node_connection "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/common/connectionManager.ts"
click node_atlascore "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/common/atlas/apiClient.ts"
click node_logging "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/common/logging/index.ts"
click node_telemetry "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/telemetry/telemetry.ts"
click node_state "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/common/sessionStore.ts"
click node_mongo "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/tools/mongodb/tools.ts"
click node_atlas "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/tools/atlas/tools.ts"
click node_atlaslocal "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/tools/atlasLocal/tools.ts"
click node_assistant "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/tools/assistant/tools.ts"
click node_resources "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/resources/resources.ts"
click node_ui "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/ui/index.ts"
click node_types "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/packages/types/src/index.ts"
click node_metrics "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/packages/metrics/src/index.ts"
click node_packaging "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/packaging/mcpb/manifest.json"
click node_deploy "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/deploy/aws/README.md"
click node_scripts "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/scripts/generate/index.ts"
click node_testsuite "https://github.com/mongodb-js/mongodb-mcp-server/blob/main/tests/integration/server.test.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_server,node_setup,node_transports toneBlue
class node_mongo,node_atlas,node_atlaslocal,node_assistant toneAmber
class node_resources,node_ui toneMint
class node_config,node_connection,node_atlascore,node_logging,node_telemetry,node_state,node_types,node_metrics toneRose
class node_packaging,node_deploy,node_scripts toneIndigo
class node_testsuite toneTeal
```

## Components

### Runtime

Server entrypoints, setup, transports, and shared runtime infrastructure.

- [Entrypoints](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/index.ts): ts runtime entrypoints · Main server boot paths for CLI, stdio, and web/HTTP modes. · `src/index.ts`
- [Server Core](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/server.ts): mcp assembly · Assembles the MCP server from shared setup and tool registration. · `src/server.ts`
- [Setup](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/setup/setupMcpServer.ts): server setup · Shared initialization for tools, telemetry, and MCP wiring. · `src/setup/setupMcpServer.ts`
- [Transports](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/transports/base.ts): mcp transports · Boundary for stdio, HTTP/SSE, in-memory, monitoring, and dry-run execution. · `src/transports/base.ts`

### Domains

Primary tool families exposed to MCP clients.

- [MongoDB Tools](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/tools/mongodb/tools.ts): tool domain · Direct database operations, metadata, read/write, and connection switching. · `src/tools/mongodb/tools.ts`
- [Atlas Tools](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/tools/atlas/tools.ts): tool domain · Atlas organization, project, cluster, user, access list, and stream processing tools. · `src/tools/atlas/tools.ts`
- [Local Tools](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/tools/atlasLocal/tools.ts): tool domain · Local deployment create/connect/list/delete operations. · `src/tools/atlasLocal/tools.ts`
- [Assistant Tools](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/tools/assistant/tools.ts): search tools · Knowledge source listing and search tools for assistant workflows. · `src/tools/assistant/tools.ts`

### Surface

Client-facing resources and optional UI preview layer.

- [Resources](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/resources/resources.ts): uri resources · Read-side MCP resources for config, debug context, and exported data. · `src/resources/resources.ts`
- [UI Preview](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/ui/index.ts): react ui · Optional preview/embedding UI layer and registry for client presentation. · `src/ui/index.ts`

### Shared

Common infrastructure and cross-cutting packages.

- [Config](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/common/config/parseUserConfig.ts): config boundary · Merges file, env, and CLI settings; governs transport, logging, guardrails, and secrets. · `src/common/config/parseUserConfig.ts`
- [MongoDB Core](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/common/connectionManager.ts): db connection · Connection manager and session helpers for direct MongoDB execution. · `src/common/connectionManager.ts`
- [Atlas Core](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/common/atlas/apiClient.ts): atlas client · Atlas API client, auth, cluster/role helpers, and advisor utilities. · `src/common/atlas/apiClient.ts`
- [Logging](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/common/logging/index.ts): observability · Console, disk, MCP, and composite loggers for server-side events. · `src/common/logging/index.ts`
- [Telemetry](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/telemetry/telemetry.ts): usage metrics · Usage events and timers for product telemetry. · `src/telemetry/telemetry.ts`
- [State](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/src/common/sessionStore.ts): server state · Session persistence, keychain storage, and export-file management. · `src/common/sessionStore.ts`
- [Types](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/packages/types/src/index.ts): shared contracts · Cross-cutting public types for clients, transports, tools, telemetry, and UI. · `packages/types/src/index.ts`
- [Metrics](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/packages/metrics/src/index.ts): prometheus defs · Prometheus metric definitions and helpers shared across the repo. · `packages/metrics/src/index.ts`

### Delivery

Deployment, packaging, and release automation.

- [Packaging](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/packaging/mcpb/manifest.json): ship assets · MCPB packaging entrypoint and manifest for distribution. · `packaging/mcpb/manifest.json`
- [Deploy](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/deploy/aws/README.md): cloud assets · Docker, AWS, and Azure rollout assets. · `deploy/aws/README.md`
- [Scripts](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/scripts/generate/index.ts): automation · Release notes, versioning, generation, accuracy, and packaging helpers. · `scripts/generate/index.ts`

### Tests

Test suites mirroring the main architecture.

- [Tests](https://github.com/mongodb-js/mongodb-mcp-server/blob/main/tests/integration/server.test.ts): verification · Unit, integration, browser, e2e, and accuracy suites spanning the full stack. · `tests/integration/server.test.ts`

## Connections

- Entrypoints → Server Core: bootstraps · Entrypoints select and start the assembled server.
- Entrypoints → Transports: chooses · Runtime entrypoints route requests through the transport layer.
- Server Core → Setup: assembles · Server construction is driven by shared setup.
- Setup → Config: reads · Server setup depends on resolved configuration.
- Setup → Logging: wires · Initialization installs logging implementations.
- Setup → Telemetry: instruments · Telemetry is enabled during server setup.
- Setup → State: initializes · Session and export state are prepared as part of setup.
- Transports → Config: uses · Transport selection and options are controlled by config.
- Transports → Types: implements · Transport contracts are shared through public types.
- MongoDB Tools → MongoDB Core: executes on · MongoDB tools use the shared connection/session pipeline.
- MongoDB Tools → Config: enforces · Read-only mode, limits, and disabled tools are config-driven.
- MongoDB Tools → Types: shares contracts · Tool schemas and client-facing shapes come from shared types.
- Atlas Tools → Atlas Core: calls · Atlas tools use the shared Atlas API client and auth helpers.
- Atlas Tools → Config: auth from · Atlas credentials and feature flags are config-driven.
- Local Tools → Transports: exposed via · Local deployment tools are served through the MCP transport boundary.
- Assistant Tools → Resources: pairs with · Assistant search and source tools complement read-side resources.
- Resources → State: reads · Resource handlers surface server-side state and exports.
- UI Preview → Types: shares contracts · UI components and registry use shared public UI/tool types.
- Metrics → Telemetry: feeds · Metrics and telemetry form the observability surface.
- Packaging → Scripts: built by · Release/package artifacts are created by repo automation.
- Deploy → Packaging: ships · Deployment assets target packaged server delivery.
- Tests → Transports: validates · Integration tests exercise transport entry boundaries.
- Tests → MongoDB Tools: validates · Accuracy and integration suites cover MongoDB tool behavior.
- Tests → Atlas Tools: validates · Integration and accuracy suites cover Atlas tool behavior.
- Tests → UI Preview: validates · Browser and integration tests cover UI/embedding behavior.
