How mongodb-js/mongodb-mcp-server works
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: setupMcpServer.ts Setup · base.ts Transports · server.test.ts Tests · tools.ts MongoDB Tools
Components 22
Runtime
Server entrypoints, setup, transports, and shared runtime infrastructure.
- Entrypoints · Main server boot paths for CLI, stdio, and web/HTTP modes.
src/index.ts - Server Core · Assembles the MCP server from shared setup and tool registration.
src/server.ts - Setup · Shared initialization for tools, telemetry, and MCP wiring.
src/setup/setupMcpServer.ts - 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 · Direct database operations, metadata, read/write, and connection switching.
src/tools/mongodb/tools.ts - Atlas Tools · Atlas organization, project, cluster, user, access list, and stream processing tools.
src/tools/atlas/tools.ts - Local Tools · Local deployment create/connect/list/delete operations.
src/tools/atlasLocal/tools.ts - Assistant 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 · Read-side MCP resources for config, debug context, and exported data.
src/resources/resources.ts - UI Preview · Optional preview/embedding UI layer and registry for client presentation.
src/ui/index.ts
Shared
Common infrastructure and cross-cutting packages.
- Config · Merges file, env, and CLI settings; governs transport, logging, guardrails, and secrets.
src/common/config/parseUserConfig.ts - MongoDB Core · Connection manager and session helpers for direct MongoDB execution.
src/common/connectionManager.ts - Atlas Core · Atlas API client, auth, cluster/role helpers, and advisor utilities.
src/common/atlas/apiClient.ts - Logging · Console, disk, MCP, and composite loggers for server-side events.
src/common/logging/index.ts - Telemetry · Usage events and timers for product telemetry.
src/telemetry/telemetry.ts - State · Session persistence, keychain storage, and export-file management.
src/common/sessionStore.ts - Types · Cross-cutting public types for clients, transports, tools, telemetry, and UI.
packages/types/src/index.ts - Metrics · Prometheus metric definitions and helpers shared across the repo.
packages/metrics/src/index.ts
Delivery
Deployment, packaging, and release automation.
Tests
Test suites mirroring the main architecture.
- Tests · Unit, integration, browser, e2e, and accuracy suites spanning the full stack.
tests/integration/server.test.ts
Connections 25
- 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.