MCP Toolbox for Databases vs MongoDB MCP Server

MCP Toolbox for Databases is an open source Model Context Protocol (MCP) server that connects your AI agents, IDEs, and applications directly to your enterprise databases.

It serves a dual purpose:

1. Ready-to-use MCP Server (Build-Time): Instantly connect Gemini CLI, Google Antigravity, Claude Code, Codex, or other MCP clients to your databases using our prebuilt generic tools. Talk to your data, explore schemas, and generate code without writing boilerplate.
2. Custom Tools Framework (Run-Time): A robust framework to build specialized, highly secure AI tools for your production agents. Define structured queries, semantic search, and NL2SQL capabilities safely and easily.

This README provides a brief overview. For comprehensive details, see the full documentation.

[!IMPORTANT]
Repository Name Update: The genai-toolbox repository has been officially renamed to mcp-toolbox. To ensure your local environment reflects the new name, you may update your remote:
git remote set-url origin https://github.com/googleapis/mcp-toolbox.git

[!NOTE]
This solution was originally named “Gen AI Toolbox for Databases” (github.com/googleapis/genai-toolbox) as its initial development predated MCP, but was renamed to align with the MCP compatibility.

Table of Contents

• Why MCP Toolbox?
• Quick Start: Prebuilt Tools
• Quick Start: Custom Tools
• Install & Run the Toolbox server
• Connect to Toolbox
  • MCP Client
  • Toolbox SDKs: Integrate with your Application
• Additional Features
• Versioning
• Contributing
• Community

Why MCP Toolbox?

• Out-of-the-Box Database Access: Prebuilt generic tools for instant data exploration (e.g., list_tables, execute_sql) directly from your IDE or CLI.
• Custom Tools Framework: Build production-ready tools with your own predefined logic, ensuring safety through Restricted Access, Structured Queries, and Semantic Search.
• Simplified Development: Integrate tools into your Agent Development Kit (ADK), LangChain, LlamaIndex, or custom agents in less than 10 lines of code.
• Better Performance: Handles connection pooling, integrated auth (IAM), and end-to-end observability (OpenTelemetry) out of the box.
• Enhanced Security: Integrated authentication for more secure access to your data.
• End-to-end Observability: Out of the box metrics and tracing with built-in support for OpenTelemetry.

Quick Start: Prebuilt Tools

Stop context-switching and let your AI assistant become a true co-developer. By connecting your IDE to your databases with MCP Toolbox, you can query your data in plain English, automate schema discovery and management, and generate database-aware code.

You can use the Toolbox in any MCP-compatible IDE or client (e.g., Gemini CLI, Google Antigravity, Claude Code, Codex, etc.) by configuring the MCP server.

Prebuilt tools are also conveniently available via the Google Antigravity MCP Store with a simple click-to-install experience.

1. Add the following to your client's MCP configuration file (usually mcp.json or claude_desktop_config.json):

   {
     "mcpServers": {
       "toolbox-postgres": {
         "command": "npx",
         "args": [
           "-y",
           "@toolbox-sdk/server",
           "--prebuilt=postgres",
           "--stdio"
         ]
       }
     }
   }
   

   Copy

2. Set the appropriate environment variables to connect, see the Prebuilt Tools Reference.

When you run Toolbox with a --prebuilt=<database> flag, you instantly get access to standard tools to interact with that database. You can also specify a specific toolset using the --prebuilt=<database>/<toolset> syntax (e.g., --prebuilt=postgres/data to only load SQL tools).

Supported databases currently include:

• Google Cloud: AlloyDB, BigQuery, Cloud SQL (PostgreSQL, MySQL, SQL Server), Spanner, Firestore, Knowledge Catalog (formerly known as Dataplex).
• Other Databases: PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, MongoDB, Redis, Elasticsearch, CockroachDB, ClickHouse, Couchbase, Neo4j, Snowflake, Trino, and more.

For a full list of available tools and their capabilities across all supported databases, see the Prebuilt Tools Reference.

See the Install & Run the Toolbox server section for different execution methods like Docker or binaries.

[!TIP]
For users looking for a managed solution, Google Cloud MCP Servers
provide a managed MCP experience with prebuilt tools; you can learn more about the differences here.

Quick Start: Custom Tools

Toolbox can also be used as a framework for customized tools.
The primary way to configure Toolbox is through the tools.yaml file. If you
have multiple files, you can tell Toolbox which to load with the --config tools.yaml flag.

You can find more detailed reference documentation to all resource types in the
Resources.

Sources

The sources section of your tools.yaml defines what data sources your
Toolbox should have access to. Most tools will have at least one source to
execute against.

kind: source
name: my-pg-source
type: postgres
host: 127.0.0.1
port: 5432
database: toolbox_db
user: toolbox_user
password: my-password

For more details on configuring different types of sources, see the
Sources.

Tools

The tools section of a tools.yaml define the actions an agent can take: what
type of tool it is, which source(s) it affects, what parameters it uses, etc.

kind: tool
name: search-hotels-by-name
type: postgres-sql
source: my-pg-source
description: Search for hotels based on name.
parameters:
  - name: name
    type: string
    description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';

For more details on configuring different types of tools, see the
Tools.

Toolsets

The toolsets section of your tools.yaml allows you to define groups of tools
that you want to be able to load together. This can be useful for defining
different groups based on agent or application.

kind: toolset
name: my_first_toolset
tools:
    - my_first_tool
    - my_second_tool
---
kind: toolset
name: my_second_toolset
tools:
    - my_second_tool
    - my_third_tool

Prompts

The prompts section of a tools.yaml defines prompts that can be used for
interactions with LLMs.

kind: prompt
name: code_review
description: "Asks the LLM to analyze code quality and suggest improvements."
messages:
  - content: >
         Please review the following code for quality, correctness,
         and potential improvements: \n\n{{.code}}
arguments:
  - name: "code"
    description: "The code to review"

For more details on configuring prompts, see the
Prompts.

Resources

The resources and resourceTemplates sections of your tools.yaml define read-only
content, files, or parameterized directory trees that can be discovered and retrieved
by MCP clients:

kind: resource
name: database_schema_ddl
type: text
description: "Core table definitions and constraints."
mimeType: text/x-sql
text: |
  CREATE TABLE customers (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL
  );
---
kind: resource
name: database_schema
type: file
description: "PostgreSQL schema definition."
path: "./schema.sql"
---
kind: resourceTemplate
name: server_logs
type: file
description: "Application log files."
uriTemplate: "file:///var/log/{path}"
allowedPaths:
  - "/var/log"

For more details on configuring resources and resource templates, see
Resources.

Install & Run the Toolbox server

You can run Toolbox directly with a configuration file:

npx @toolbox-sdk/server --config tools.yaml

This runs the latest version of the Toolbox server with your configuration file.

[!NOTE]
This method is optimized for convenience rather than performance.
For a more standard and reliable installation, please use the binary
or container image as described in Install & Run the Toolbox server.

Install Toolbox

For the latest version, check the releases page and use the
following instructions for your OS and CPU architecture.

## see releases page for other versions
export VERSION=1.16.0
docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION

brew install mcp-toolbox

go install github.com/googleapis/mcp-toolbox@v1.16.0

## Install Gemini CLI
npm install -g @google/gemini-cli
## Install the extension
gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgres
## Run Gemini CLI
gemini

## Install the extension
gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

Run Toolbox

Configure a tools.yaml to define your tools, and then
execute toolbox to start the server:

./toolbox --config "tools.yaml"

export VERSION=0.24.0 # Use the version you pulled
docker run -p 5000:5000 \
-v $(pwd)/tools.yaml:/app/tools.yaml \
us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION \
--config "/app/tools.yaml"

go run .

toolbox --config "tools.yaml"

npx @toolbox-sdk/server --config tools.yaml

## Run Gemini CLI
gemini

## List extensions
/extensions list
## List MCP servers
/mcp list

You can use toolbox help for a full list of flags! To stop the server, send a
terminate signal (ctrl+c on most platforms).

For more detailed documentation on deploying to different environments, check
out the resources in the Deploy Toolbox
section

Connect to Toolbox

Once your Toolbox server is up and running, you can load tools into your MCP-compatible client or
application.

MCP Client

Add the following configuration to your MCP client configuration:

{
  "mcpServers": {
    "toolbox": {
      "type": "http",
      "url": "http://127.0.0.1:5000/mcp",
    }
  }
}

If you would like to connect to a specific toolset, replace url with "http://127.0.0.1:5000/mcp/{toolset_name}".

Toolbox SDKs: Integrate with your Application

Toolbox Client SDKs provide the easy-to-use building blocks and advanced features for connecting your custom applications to the MCP Toolbox server. See below the list of Client SDKs for using various frameworks:

Additional Features

Test tools with the Toolbox UI

To launch Toolbox's interactive UI, use the --ui flag. This allows you to test
tools and toolsets with features such as authorized parameters. To learn more,
visit Toolbox UI.

./toolbox --ui

Telemetry

Toolbox emits traces and metrics via OpenTelemetry. Use --telemetry-otlp=<endpoint>
to export to any OTLP-compatible backend like Google Cloud Monitoring, Agnost AI, or
others. See the telemetry docs for details.

Generate Agent Skills

The skills-generate command allows you to convert a toolset into an Agent Skill compatible with the Agent Skill specification. This is useful for distributing tools as portable skill packages.

toolbox --config tools.yaml skills-generate \
  --name "my-skill" \
  --toolset "my_toolset" \
  --description "A skill containing multiple tools"

Once generated, you can install the skill into the Gemini CLI:

gemini skills install ./skills/my-skill

For more details, see the Generating Skills guide. To serve a skill you already have over MCP, see Serving Skills over MCP.

The repository also ships ready-to-use Agent Skills (e.g. maintainer workflows). See skills/ for the catalog and install instructions.

Versioning

MCP Toolbox for Databases follows Semantic Versioning.

The Public API includes the Toolbox Server (CLI, configuration manifests, and pre-built toolsets) and the Client SDKs.

• Major versions are incremented for breaking changes, such as incompatible CLI or manifest changes.
• Minor versions are incremented for new features, including modifications to pre-built toolsets or beta features.
• Patch versions are incremented for backward-compatible bug fixes.

For more details, including our Container Tagging Policy, see our Full Versioning Policy.

Contributing

Contributions are welcome. Please, see the CONTRIBUTING guide to get started.

For technical details on setting up a environment for developing on Toolbox itself, see the DEVELOPER guide.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Contributor Code of Conduct for more information.

Community

Join our Discord community to connect with our developers!

MongoDB MCP Server

A Model Context Protocol server for interacting with MongoDB Databases and MongoDB Atlas.

Quick Start

Using the official MongoDB plugins for AI agents

MongoDB MCP Server comes bundled with the official MongoDB plugins for AI agents. The following plugins are available:

mongodb-atlas — connects to the MongoDB-hosted Atlas MCP server over OAuth. This does not require you to run anything locally, and is the recommended way to connect to MongoDB Atlas from your AI agent:

• Cursor: marketplace
• VSCode: Open the Extensions view (⇧⌘X / Ctrl+Shift+X), search for @agentPlugins, and install mongodb-atlas.
• Claude: marketplace
• Codex: Open /plugins and install mongodb-atlas.
• GitHub Copilot CLI: Run copilot plugin install mongodb-atlas.
• Grok: Open /marketplace in Grok Build and install mongodb-atlas.

mongodb — runs the MongoDB MCP server locally and connects to any self-managed deployment:

• Cursor: marketplace
• Claude: marketplace
• Gemini: marketplace
• Codex: Run codex plugin marketplace add mongodb/agent-skills, then open /plugins and install mongodb.
• GitHub Copilot CLI: Run copilot plugin install mongodb.
• Grok: Open /marketplace in Grok Build and install mongodb.

Using the setup script

You can manually set up the local MCP server by running the following command:

npx -y mongodb-mcp-server@latest setup

This will guide you through an interactive setup process, including configuring your MongoDB connection string or Atlas API credentials.

For more advanced setup options, see the Manual Setup section below.

Using the MongoDB MCP Server setup skill

You can add and use the MongoDB MCP Server setup skill to configure your local MCP server using an AI agent.

npx skills add https://github.com/mongodb/agent-skills --skill mongodb-mcp-setup

Using manual configuration

See Manual Setup for instructions on how to manually configure the MongoDB MCP Server.

📚 Table of Contents

• 🚀 Getting Started
  • Prerequisites
  • Manual Setup
• 🛠️ Supported Tools
  • MongoDB Atlas Tools
  • MongoDB Database Tools
  • MongoDB Assistant Tools
• 📄 Supported Resources
• ⚙️ Configuration
  • Configuration Options
  • Atlas API Access
  • Configuration Methods
    • Environment Variables
    • Command-Line Arguments
    • MCP Client Configuration
    • Proxy Support
• 🚀 Deploy on Public Clouds
  • Azure Cloud
• 🤝 Contributing

Prerequisites

[!NOTE]
Node 20.x support is deprecated and will be removed in a future release. Please upgrade to Node 22.13 or later. See https://nodejs.org/en/blog/migrations/v20-to-v22 for migration details.

• Node.js

  • At least v22.13.0. Check with node -v.

• A MongoDB connection string or Atlas API credentials.

  • Service Accounts Atlas API credentials are required to use the Atlas tools. You can create a service account in MongoDB Atlas and use its credentials for authentication. See Atlas API Access for more details.
  • If you have a MongoDB connection string, you can use it directly to connect to your MongoDB instance.

Manual Setup

🔒 Security Recommendation 1: When using Atlas API credentials, be sure to assign only the minimum required permissions to your service account. See Atlas API Permissions for details.

🔒 Security Recommendation 2: For enhanced security, we strongly recommend using environment variables to pass sensitive configuration such as connection strings and API credentials instead of command line arguments. Command line arguments can be visible in process lists and logged in various system locations, potentially exposing your secrets. Environment variables provide a more secure way to handle sensitive information.

Most MCP clients require a configuration file to be created or modified to add the MCP server.

Note: The configuration file syntax can be different across clients. Please refer to the following links for the latest expected syntax:

• Devin AI
• Claude Desktop & Web
• Cursor
• Codex
• Other AI clients

Default Safety Notice: All examples below include --readOnly by default to ensure safe, read-only access to your data. Remove --readOnly if you need to enable write operations.

Option 1: Connection String

You can pass your connection string via environment variables, make sure to use a valid username and password.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/myDatabase"
      }
    }
  }
}

NOTE: The connection string can be configured to connect to any MongoDB cluster, whether it's a local instance or an Atlas cluster.

Option 2: Connect to the MongoDB Atlas-Managed MCP Server

When working with MongoDB Atlas, the recommended approach is to install the mongodb-atlas plugin for your AI agent, which handles OAuth authentication automatically.

For manual configuration, see the client-specific instructions for setting up the Atlas Remote MCP server with OAuth. Alternatively, you can connect using the mongodb-atlas-mcp-remote package with Service Account credentials — see the package README for setup instructions.

Note: You cannot authenticate to the remote MongoDB MCP server using a static API key over HTTP. You must either:

• Use a client that supports the OAuth flow.
• Use the mongodb-atlas-mcp-remote stdio server, which you can authenticate into using the static MDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET environment variables.

To connect with the mongodb-atlas-mcp-remote stdio server using Service Account credentials, add it to your client's MCP configuration:

{
  "mcpServers": {
    "mongodb-atlas-mcp-remote": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mongodb-atlas-mcp-remote@latest"],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "$CLIENT_ID",
        "MDB_MCP_API_CLIENT_SECRET": "$SECRET"
      }
    }
  }
}

Option 3: Atlas API Credentials

Use your Atlas API Service Accounts credentials. Must follow all the steps in Atlas API Access section.

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
        "MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
      }
    }
  }
}

Option 4: Standalone Service using environment variables and command line arguments

You can source environment variables defined in a config file or explicitly set them like we do in the example below and run the server via npx.

## Set your credentials as environment variables first
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

## Then start the server
npx -y mongodb-mcp-server@latest --readOnly

💡 Platform Note: The examples above use Unix/Linux/macOS syntax. For Windows users, see Environment Variables for platform-specific instructions.

• For a complete list of configuration options see Configuration Options
• To configure your Atlas Service Accounts credentials please refer to Atlas API Access
• Connection String via environment variables in the MCP file example
• Atlas API credentials via environment variables in the MCP file example

Option 5: Using Docker

You can run the MongoDB MCP Server in a Docker container, which provides isolation and doesn't require a local Node.js installation.

Run with Environment Variables

You may provide either a MongoDB connection string OR Atlas API credentials:

Option A: No configuration

docker run --rm -i \
  mongodb/mongodb-mcp-server:latest

Option B: With MongoDB connection string

## Set your credentials as environment variables first
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

## Then start the docker container
docker run --rm -i \
  -e MDB_MCP_CONNECTION_STRING \
  -e MDB_MCP_READ_ONLY="true" \
  mongodb/mongodb-mcp-server:latest

💡 Platform Note: The examples above use Unix/Linux/macOS syntax. For Windows users, see Environment Variables for platform-specific instructions.

Option C: With Atlas API credentials

## Set your credentials as environment variables first
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

## Then start the docker container
docker run --rm -i \
  -e MDB_MCP_API_CLIENT_ID \
  -e MDB_MCP_API_CLIENT_SECRET \
  -e MDB_MCP_READ_ONLY="true" \
  mongodb/mongodb-mcp-server:latest

💡 Platform Note: The examples above use Unix/Linux/macOS syntax. For Windows users, see Environment Variables for platform-specific instructions.

Docker in MCP Configuration File

Without options:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-e",
        "MDB_MCP_READ_ONLY=true",
        "-i",
        "mongodb/mongodb-mcp-server:latest"
      ]
    }
  }
}

With connection string:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_CONNECTION_STRING",
        "-e",
        "MDB_MCP_READ_ONLY=true",
        "mongodb/mongodb-mcp-server:latest"
      ],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      }
    }
  }
}

With Atlas API credentials:

{
  "mcpServers": {
    "MongoDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MDB_MCP_READ_ONLY=true",
        "-e",
        "MDB_MCP_API_CLIENT_ID",
        "-e",
        "MDB_MCP_API_CLIENT_SECRET",
        "mongodb/mongodb-mcp-server:latest"
      ],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
        "MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
      }
    }
  }
}

HTTP Compatibility

For custom HTTP clients and hosts, see the library guide's HTTP compatibility requirements, including protocol headers, redirects, legacy sessions, and request size limits.

🛠️ Supported Tools

Tool List

MongoDB Database Tools

• aggregate - Run an aggregation against a MongoDB collection
• aggregate-db - Run an aggregation against a MongoDB database
• collection-indexes - Describe the indexes for a collection
• collection-schema - Describe the schema for a collection
• collection-storage-size - Gets the size of the collection
• connect - Connect to a MongoDB instance
• count - Gets the number of documents in a MongoDB collection using db.collection.count() and query as an optional filter parameter
• create-collection - Creates a new collection in a database. If the database doesn't exist, it will be created automatically.
• create-index - Create an index for a collection
• db-stats - Returns statistics that reflect the use state of a single database
• delete-many - Removes all documents that match the filter from a MongoDB collection
• disconnect - Close a MongoDB connection and revoke its connectionId.
• drop-collection - Removes a collection or view from the database. The method also removes any indexes associated with the dropped collection.
• drop-database - Removes the specified database, deleting the associated data files
• drop-index - Drop an index for the provided database and collection.
• explain - Returns statistics describing the execution of the winning plan chosen by the query optimizer for the evaluated method
• export - Export a query or aggregation results in the specified EJSON format.
• find - Run a find query against a MongoDB collection
• insert-many - Insert an array of documents into a MongoDB collection. If the list of documents is above com.mongodb/maxRequestPayloadBytes, consider inserting them in batches.
• list-collections - List all collections for a given database
• list-connections - List the active MongoDB connections and their connectionIds. Use this to find a connectionId established earlier.
• list-databases - List all databases for a MongoDB connection
• mongodb-logs - Returns the most recent logged mongod events
• rename-collection - Renames a collection in a MongoDB database
• update-many - Updates all documents that match the specified filter for a collection. If the list of documents is above com.mongodb/maxRequestPayloadBytes, consider updating them in batches.

MongoDB Atlas Tools

• atlas-connect-cluster - Connect to MongoDB Atlas cluster and get back a connectionId to pass to the other MongoDB tools. Each call establishes a new, independent connection — multiple connections can be active at the same time.
• atlas-create-access-list - Allow Ip/CIDR ranges to access your MongoDB Atlas clusters.
• atlas-create-cluster - Create a MongoDB Atlas cluster (M10–M80, replica set or single shard). Compute autoscaling is enabled by default: min instance size is set to the selected instance size, max is set two tiers above. Disk autoscaling is always enabled. Encryption at rest with customer-managed keys (CMK) is supported, the CMK provider must already have a valid encryption at rest configuration in the project. The tool returns immediately, use the atlas-inspect-cluster tool to poll the cluster state for readiness (state: IDLE). Connection strings are unavailable until the cluster reaches IDLE state.
• atlas-create-db-user - Create an MongoDB Atlas database user
• atlas-create-free-cluster - Create a free MongoDB Atlas cluster
• atlas-create-project - Create a MongoDB Atlas project
• atlas-get-performance-advisor - Get MongoDB Atlas performance advisor recommendations and suggestions, which includes the operations: suggested indexes, drop index suggestions, schema suggestions, and a sample of the most recent (max 50) slow query logs
• atlas-get-regions - List supported MongoDB Atlas regions for a cloud provider.
• atlas-inspect-access-list - Inspect Ip/CIDR ranges with access to your MongoDB Atlas clusters.
• atlas-inspect-cluster - Inspect metadata of a MongoDB Atlas cluster
• atlas-list-alerts - List triggered alerts for a MongoDB Atlas project. These are alerts Atlas has raised, not the alert configurations that define them. Defaults to OPEN alerts; set status to TRACKING or CLOSED to see others.
• atlas-list-clusters - List MongoDB Atlas clusters
• atlas-list-db-users - List MongoDB Atlas database users
• atlas-list-orgs - List MongoDB Atlas organizations
• atlas-list-projects - List MongoDB Atlas projects.
• atlas-load-sample-dataset - Load a MongoDB sample dataset into an Atlas cluster, or check the status of a previously-initiated load. To start a new load, provide clusterName — the load runs asynchronously and the response includes a jobId and initial state. To check progress, call this tool again with jobId (sample dataset loads typically take 1–5 minutes). State can be WORKING, COMPLETED, or FAILED.
• atlas-pause-resume-cluster - Pause or resume a dedicated (M10+) MongoDB Atlas cluster.
• atlas-streams-build - Create Atlas Stream Processing resources. Use this tool for 'set up a Kafka pipeline', 'create a workspace', 'add a connection', or 'deploy a processor'. Use resource='workspace' to create a new workspace (specify cloud provider, region, and tier). Use resource='connection' to add a data source or sink to an existing workspace. Use resource='processor' to deploy a stream processor with a pipeline. Use resource='privatelink' to set up private networking. Typical workflow: create workspace → add connections → deploy processor.
• atlas-streams-discover - Discover and inspect Atlas Stream Processing resources. Also use for 'why is my processor failing', 'what workspaces do I have', 'show processor stats', or 'check processor health'. Use 'list-workspaces' to see all workspaces in a project. Use inspect actions for details on a specific resource. Use 'diagnose-processor' for a combined health report including state, stats, connection health, and recent errors. Use 'get-networking' for PrivateLink and account details.
• atlas-streams-manage - Manage Atlas Stream Processing resources: start/stop processors, modify pipelines, update configurations. Also use for 'change the pipeline', 'scale up my processor', or 'update my workspace tier'. Common workflow: action='stop-processor' → action='modify-processor' → action='start-processor'. Use atlas-streams-discover with action 'inspect-processor' to check state before managing.
• atlas-streams-teardown - Delete Atlas Stream Processing resources. Also use for 'remove my workspace', 'disconnect a source', 'delete all processors', or 'clean up my streams environment'. Performs basic safety checks before deletion: summarizes counts of processors and connections, highlights connections referenced by processors where possible, and surfaces API errors if processors are still running when deletion is attempted. Use atlas-streams-discover to review resources before deleting.
• atlas-upgrade-cluster - Upgrade or scale a MongoDB Atlas cluster. Free and Flex clusters can be upgraded to Flex or M10 Dedicated. Dedicated clusters can be scaled to a different instance size, and compute autoscaling settings can be updated. When scaling a Dedicated cluster, at least one of targetTier, computeAutoScaling, minInstanceSize, or maxInstanceSize must be provided. Compute autoscaling defaults to enabled when upgrading to M10 Dedicated: min instance size is set to the selected instance size, max is set two tiers above, unless overridden. Note to LLM: If provider and region are not already known, ask for both together in a single question before calling this tool. Use atlas-get-regions to resolve natural-language locations or uncertain region codes before calling this tool.

NOTE: atlas tools are only available when you set credentials on configuration section.

MongoDB Atlas Local Tools

• atlas-local-connect-deployment - Connect to a MongoDB Atlas Local deployment and get back a connectionId to pass to the other MongoDB tools
• atlas-local-create-deployment - Create a MongoDB Atlas local deployment. Default image is latest. When the user does not specify an image tag, inform them that latest is used by default and provide this link for more information: https://hub.docker.com/r/mongodb/mongodb-atlas-local
• atlas-local-delete-deployment - Delete a MongoDB Atlas local deployment
• atlas-local-list-deployments - List MongoDB Atlas local deployments

MongoDB Assistant Tools

• list-knowledge-sources - List available data sources in the MongoDB Assistant knowledge base. Use this to explore available data sources or to find search filter parameters to use in search-knowledge.
• search-knowledge - Search for information in the MongoDB Assistant knowledge base. This includes official documentation, curated expert guidance, and other resources provided by MongoDB. Supports filtering by data source and version.

📄 Supported Resources

• config - Server configuration, supplied by the user either as environment variables or as startup arguments with sensitive parameters redacted. The resource can be accessed under URI config://config.
• debug - Debugging information for MongoDB connectivity issues. Tracks the last connectivity attempt and error information. The resource can be accessed under URI debug://mongodb.
• exported-data - A resource template to access the data exported using the export tool. The template can be accessed under URI exported-data://{exportName} where exportName is the unique name for an export generated by the export tool.

Configuration

🔒 Security Best Practice: We strongly recommend using environment variables for sensitive configuration such as API credentials (MDB_MCP_API_CLIENT_ID, MDB_MCP_API_CLIENT_SECRET) and connection strings (MDB_MCP_CONNECTION_STRING) instead of command-line arguments. Environment variables are not visible in process lists and provide better security for your sensitive data.

The MongoDB MCP Server can be configured using multiple methods, with the following precedence (highest to lowest):

1. Command-line arguments
2. Environment variables
3. Configuration File

Configuration Options

Logger Options

The loggers configuration option controls where logs are sent. You can specify one or more logger types as a comma-separated list. The available options are:

• mcp: Sends logs to the MCP client (if supported by the client/transport).
• disk: Writes logs to disk files. Log files are stored in the log path (see logPath above).
• stderr: Outputs logs to standard error (stderr), useful for debugging or when running in containers.

Default: disk,mcp (logs are written to disk and sent to the MCP client).

You can combine multiple loggers, e.g. --loggers disk stderr or export MDB_MCP_LOGGERS="mcp,stderr".

Example: Set logger via environment variable

export MDB_MCP_LOGGERS="disk,stderr"

💡 Platform Note: For Windows users, see Environment Variables for platform-specific instructions.

Example: Set logger via command-line argument

npx -y mongodb-mcp-server@latest --loggers mcp stderr

Log File Location

When using the disk logger, log files are stored in:

• Windows: %LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs
• macOS/Linux: ~/.mongodb/mongodb-mcp/.app-logs

You can override the log directory with the logPath option.

🔒 Security Guideline: The user account running the MCP server must have both read and write permissions to the logPath directory. Ensure this directory is properly secured with appropriate file system permissions to prevent unauthorized access to log files.

Disabled Tools

You can disable specific tools or categories of tools by using the disabledTools option. This option accepts an array of strings,
where each string can be a tool name, operation type, or category.

The way the array is constructed depends on the type of configuration method you use:

• For environment variable configuration, use a comma-separated string: export MDB_MCP_DISABLED_TOOLS="create,update,delete,atlas,collectionSchema".
• For command-line argument configuration, use a space-separated string: --disabledTools create update delete atlas collectionSchema.

Categories of tools:

• atlas - MongoDB Atlas tools, such as list clusters, create cluster, etc.
• mongodb - MongoDB database tools, such as find, aggregate, etc.

Operation types:

• create - Tools that create resources, such as create cluster, insert document, etc.
• update - Tools that update resources, such as update document, rename collection, etc.
• delete - Tools that delete resources, such as delete document, drop collection, etc.
• read - Tools that read resources, such as find, aggregate, list clusters, etc.
• metadata - Tools that read metadata, such as list databases/collections/indexes, infer collection schema, etc.
• connect - Tools that allow you to connect or switch the connection to a MongoDB instance. If this is disabled, you will need to provide a connection string through the config when starting the server.

Require Confirmation

If your client supports elicitation, you can set the MongoDB MCP server to request user confirmation before executing certain tools.

When a tool is marked as requiring confirmation, the server will send an elicitation request to the client. The client with elicitation support will then prompt the user for confirmation and send the response back to the server. If the client does not support elicitation, the tool will execute without confirmation.

You can set the confirmationRequiredTools configuration option to specify the names of tools which require confirmation. By default, the following tools have this setting enabled: drop-database, drop-collection, delete-many, drop-index, atlas-create-db-user, atlas-create-access-list, atlas-streams-manage, atlas-streams-teardown.

In addition, the aggregate and aggregate-db tools always request confirmation before running a pipeline that contains a $out or $merge stage, regardless of whether they appear in confirmationRequiredTools. Those stages write to a collection — $out replaces its contents entirely — so this confirmation names the affected collection and what will happen to it. Pipelines without a write stage are not confirmed.

Adding either tool to confirmationRequiredTools is broader: every call is then confirmed up front with the standard tool-level message, and a write stage does not raise a second prompt.

Unattended and CI agents

Some clients advertise elicitation support but have no user to answer the prompt, for example when running non-interactively (such as codex exec) or in CI. In that case the elicitation is not accepted, the server treats it as a decline, and the tool returns User did not confirm the execution of the `<tool>` tool so the operation was not performed. Nothing is changed, and the agent run may still exit successfully, so the failure is easy to miss.

If you run the server with an unattended agent and want confirmation-gated tools (such as delete-many) to execute, disable the confirmation prompts by setting confirmationRequiredTools to an empty value:

MDB_MCP_CONFIRMATION_REQUIRED_TOOLS="" npx -y mongodb-mcp-server

or pass --confirmationRequiredTools "". Only do this when the agent is trusted to run destructive operations without a human in the loop. Consider combining it with a read-only or disabled tools configuration, or with a database user that has limited privileges.

Read-Only Mode

The readOnly configuration option allows you to restrict the MCP server to only use tools with "read", "connect", and "metadata" operation types. When enabled, all tools that have "create", "update" or "delete" operation types will not be registered with the server.

This is useful for scenarios where you want to provide access to MongoDB data for analysis without allowing any modifications to the data or infrastructure.

You can enable read-only mode using:

• Environment variable: export MDB_MCP_READ_ONLY=true
• Command-line argument: --readOnly

💡 Platform Note: For Windows users, see Environment Variables for platform-specific instructions.

When read-only mode is active, you'll see a message in the server logs indicating which tools were prevented from registering due to this restriction.

Index Check Mode

The indexCheck configuration option allows you to enforce that query operations must use an index. When enabled, queries that perform a collection scan will be rejected to ensure better performance.

This is useful for scenarios where you want to ensure that database queries are optimized.

You can enable index check mode using:

• Environment variable: export MDB_MCP_INDEX_CHECK=true
• Command-line argument: --indexCheck

💡 Platform Note: For Windows users, see Environment Variables for platform-specific instructions.

When index check mode is active, you'll see an error message if a query is rejected due to not using an index.

Exports

The data exported by the export tool is temporarily stored in the configured exportsPath on the machine running the MCP server until cleaned up by the export cleanup process. If the exportsPath configuration is not provided, the following defaults are used:

• Windows: %LOCALAPPDATA%\mongodb\mongodb-mcp\exports
• macOS/Linux: ~/.mongodb/mongodb-mcp/exports

The exportTimeoutMs configuration controls the time after which the exported data is considered expired and eligible for cleanup. By default, exports expire after 5 minutes (300000ms).

The exportCleanupIntervalMs configuration controls how frequently the cleanup process runs to remove expired export files. By default, cleanup runs every 2 minutes (120000ms).

🔒 Security Guideline: The user account running the MCP server must have both read and write permissions to the exportsPath directory. Ensure this directory is properly secured with appropriate file system permissions to prevent unauthorized access to exported data files, which may contain sensitive MongoDB data. Consider the sensitivity of your data when choosing the export location and apply restrictive permissions accordingly.

Telemetry

The telemetry configuration option allows you to disable telemetry collection. When enabled, the MCP server will collect usage data and send it to MongoDB.

You can disable telemetry using:

• Environment variable: export MDB_MCP_TELEMETRY=disabled
• Command-line argument: --telemetry disabled
• DO_NOT_TRACK environment variable: export DO_NOT_TRACK=1

💡 Platform Note: For Windows users, see Environment Variables for platform-specific instructions.

Opting into Preview Features

The MongoDB MCP Server may offer functionality that is still in development and may change in future releases. These features are considered "preview features" and are not enabled by default. Generally, these features are well tested, but may not offer the complete functionality we intend to provide in the final release or we'd like to gather feedback before making them generally available. To enable one or more preview features, use the previewFeatures configuration option.

• For environment variable configuration, use a comma-separated string: export MDB_MCP_PREVIEW_FEATURES="feature1,feature2".
• For command-line argument configuration, use a space-separated string: --previewFeatures feature1 feature2.

List of available preview features:

• mcpUI - Enables an optional web-based UI for interacting with the MCP server.

Monitoring Server (Health Check & Metrics)

When running with --transport http, you can expose a separate monitoring HTTP server for health checks and metrics. This server is only started when both monitoringServerHost and monitoringServerPort are set, and it listens on its own host/port (independent from the main httpHost/httpPort).

The features exposed are controlled by monitoringServerFeatures (default: health-check). Available features and their endpoints:

The /health response is sent with Cache-Control: no-store and has the following shape (status is always "ok" while the process is alive):

{
  "status": "ok",
  "version": "1.13.0",
  "uptimeSeconds": 42,
  "timestamp": "2026-06-20T12:00:00.000Z"
}

Example: start the server with the monitoring server enabled and call the health-check endpoint:

npx -y mongodb-mcp-server@latest --transport http --httpHost 0.0.0.0 --httpPort 3000 --monitoringServerHost 0.0.0.0 --monitoringServerPort 8080 &
curl http://0.0.0.0:8080/health
## => {"status":"ok","version":"1.13.0","uptimeSeconds":42,"timestamp":"2026-06-20T12:00:00.000Z"}

To expose both endpoints, pass the features explicitly:

npx -y mongodb-mcp-server@latest --transport http --monitoringServerHost 0.0.0.0 --monitoringServerPort 8080 --monitoringServerFeatures health-check,metrics

Select process-metrics to expose /metrics with both MCP server metrics and Node.js process metrics. You do not need to select metrics as well:

npx -y mongodb-mcp-server@latest --transport http --monitoringServerHost 127.0.0.1 --monitoringServerPort 8080 --monitoringServerFeatures health-check,process-metrics
curl http://127.0.0.1:8080/metrics

💡 Note: healthCheckHost / healthCheckPort are deprecated aliases for monitoringServerHost / monitoringServerPort and continue to serve the same /health endpoint.

Atlas API Access

To use the Atlas API tools, you'll need to create a service account in MongoDB Atlas:

ℹ️ Note: For a detailed breakdown of the minimum required permissions for each Atlas operation, see the Atlas API Permissions section below.

1. Create a Service Account:
   • Log in to MongoDB Atlas at cloud.mongodb.com
   • Navigate to Access Manager > Organization Access
   • Click Add New > Applications > Service Accounts
   • Enter name, description and expiration for your service account (e.g., "MCP, MCP Server Access, 7 days")
   • Assign only the minimum permissions needed for your use case.
     • See Atlas API Permissions for details.
   • Click "Create"

To learn more about Service Accounts, check the MongoDB Atlas documentation.

2. Save Client Credentials:

   • After creation, you'll be shown the Client ID and Client Secret
   • Important: Copy and save the Client Secret immediately as it won't be displayed again

3. Add Access List Entry:

   • Add your IP address to the API access list

4. Configure the MCP Server:

   • Use one of the configuration methods below to set your apiClientId and apiClientSecret

Atlas API Permissions

Security Warning: Granting the Organization Owner role is rarely necessary and can be a security risk. Assign only the minimum permissions needed for your use case.

Quick Reference: Required roles per operation

• Prefer project-level roles for most operations. Assign only to the specific projects you need to manage or view.
• Avoid Organization Owner unless you require full administrative control over all projects and settings in the organization.

For a full list of roles and their privileges, see the Atlas User Roles documentation.

Configuration Methods

Configuration File

Store configuration in a JSON file and load it using the MDB_MCP_CONFIG environment variable.

🔒 Security Best Practice: Prefer using the MDB_MCP_CONFIG environment variable for sensitive fields over the configuration file or --config CLI argument. Command-line arguments are visible in process listings.

🔒 File Security: Ensure your configuration file has proper ownership and permissions, limited to the user running the MongoDB MCP server:

Linux/macOS:

chmod 600 /path/to/config.json
chown your-username /path/to/config.json

Copy

Windows: Right-click the file → Properties → Security → Restrict access to your user account only.

Create a JSON file with your configuration (all keys use camelCase):

{
  "connectionString": "mongodb://localhost:27017",
  "readOnly": true,
  "loggers": ["stderr", "mcp"],
  "apiClientId": "your-atlas-service-accounts-client-id",
  "apiClientSecret": "your-atlas-service-accounts-client-secret",
  "maxDocumentsPerQuery": 100
}

Linux/macOS (bash/zsh):

export MDB_MCP_CONFIG="/path/to/config.json"
npx -y mongodb-mcp-server@latest

Windows Command Prompt (cmd):

set "MDB_MCP_CONFIG=C:\path\to\config.json"
npx -y mongodb-mcp-server@latest

Windows PowerShell:

$env:MDB_MCP_CONFIG="C:\path\to\config.json"
npx -y mongodb-mcp-server@latest

Environment Variables

Set environment variables with the prefix MDB_MCP_ followed by the option name in uppercase with underscores:

Linux/macOS (bash/zsh):

## Set Atlas API credentials (via Service Accounts)
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

## Set a custom MongoDB connection string
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

## Set log path
export MDB_MCP_LOG_PATH="/path/to/logs"

Windows Command Prompt (cmd):

set "MDB_MCP_API_CLIENT_ID=your-atlas-service-accounts-client-id"
set "MDB_MCP_API_CLIENT_SECRET=your-atlas-service-accounts-client-secret"

set "MDB_MCP_CONNECTION_STRING=mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

set "MDB_MCP_LOG_PATH=C:\path\to\logs"

Windows PowerShell:

## Set Atlas API credentials (via Service Accounts)
$env:MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
$env:MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"

## Set a custom MongoDB connection string
$env:MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

## Set log path
$env:MDB_MCP_LOG_PATH="C:\path\to\logs"

MCP configuration file examples

Connection String with environment variables

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://username:password@cluster.mongodb.net/myDatabase"
      }
    }
  }
}

Atlas API credentials with environment variables

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server"],
      "env": {
        "MDB_MCP_API_CLIENT_ID": "your-atlas-service-accounts-client-id",
        "MDB_MCP_API_CLIENT_SECRET": "your-atlas-service-accounts-client-secret"
      }
    }
  }
}

Command-Line Arguments

Pass configuration options as command-line arguments when starting the server:

🔒 Security Note: For sensitive configuration like API credentials and connection strings, use environment variables instead of command-line arguments.

## Set sensitive data as environment variable
export MDB_MCP_API_CLIENT_ID="your-atlas-service-accounts-client-id"
export MDB_MCP_API_CLIENT_SECRET="your-atlas-service-accounts-client-secret"
export MDB_MCP_CONNECTION_STRING="mongodb+srv://username:password@cluster.mongodb.net/myDatabase"

## Start the server with command line arguments
npx -y mongodb-mcp-server@latest --logPath=/path/to/logs --readOnly --indexCheck

💡 Platform Note: The examples above use Unix/Linux/macOS syntax. For Windows users, see Environment Variables for platform-specific instructions.

MCP configuration file examples

Connection String with command-line arguments

🔒 Security Note: We do not recommend passing connection string as command line argument. Connection string might contain credentials which can be visible in process lists and logged in various system locations, potentially exposing your credentials. Instead configure connection string through environment variables

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "mongodb+srv://username:password@cluster.mongodb.net/myDatabase",
        "--readOnly"
      ]
    }
  }
}

Atlas API credentials with command-line arguments

🔒 Security Note: We do not recommend passing Atlas API credentials as command line argument. The provided credentials can be visible in process lists and logged in various system locations, potentially exposing your credentials. Instead configure Atlas API credentials through environment variables

{
  "mcpServers": {
    "MongoDB": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server",
        "--apiClientId",
        "your-atlas-service-accounts-client-id",
        "--apiClientSecret",
        "your-atlas-service-accounts-client-secret",
        "--readOnly"
      ]
    }
  }
}

Proxy Support

The MCP Server detects standard proxy environment variables and uses them for supported
outbound connections, including the Atlas Administration API, MongoDB cluster connections,
OIDC identity providers, and the MongoDB Assistant. The behaviour matches mongosh
(both rely on @mongodb-js/devtools-proxy-support),
so any proxy configuration that works with mongosh also works here.

Environment variables

Set the relevant variable before starting the server. The conventional *_PROXY
variables are honored:

## Route outbound traffic through a corporate proxy, except internal hosts
export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,*.internal.example.com"

Proxy in the connection string

For the MongoDB cluster connection specifically, you can configure a SOCKS5 proxy
directly in the connection string instead of using environment variables:

mongodb+srv://<host>/?proxyHost=127.0.0.1&proxyPort=1080&proxyUsername=user&proxyPassword=pass

Supported parameters: proxyHost, proxyPort, proxyUsername, proxyPassword.

Certificate authorities

For the HTTP(S) requests handled by @mongodb-js/devtools-proxy-support (the Atlas API,
OIDC, and the MongoDB Assistant), the operating system's certificate store is trusted in
addition to the bundled CAs — the same way mongosh does — so corporate root certificates
installed at the OS level are picked up automatically.

🚀Deploy on Public Clouds

You can deploy the MongoDB MCP Server to your preferred cloud provider using the deployment assets under deploy/. Each guide explains the prerequisites, configuration, and automation scripts that streamline the rollout.

Azure

For detailed Azure instructions, see deploy/azure/README.md.

Deployment Constraints

The CLI tool (mongodb-mcp-server / npx mongodb-mcp-server) is designed for single-user, localhost (or private) deployments where the operating user is the only principal. It ships with no built-in authentication, and the MCP protocol does not carry a verified end-user identity. It is not meant to serve multiple users — there is no authentication middleware in front of it to distinguish callers or control connection isolation.

As a result, if you expose it to a network — or run it as a shared server — you are responsible for the isolation guarantees:

• Internet exposure: binding to 0.0.0.0 / :: (or any non-loopback host) with no auth exposes an unauthenticated endpoint that can run MongoDB operations (including destructive ones) against the configured connection string. If you intentionally bind to a non-loopback host, you must set MDB_MCP_DANGEROUS_HOST_BINDING=true (see Configuration Options).
• Multi-user isolation: connections are scoped by the (soon-to-be-removed) connectionScope option, whose default is moving to global — every request shares one scope. The mcp-session-id header that keys the scope on the sessionless path is client-asserted, not a security boundary, and requests without it fall into the shared scope. So multiple users can see and operate on each other's connections, including any Atlas temporary database user credentials. The server does not distinguish callers. To ensure proper isolation, you can either setup an authenticated middleware which controls the mcp-session-id header or provide a custom scoping mechanism using the @mongodb-js/mcp-* library packages.

Do not run the CLI tool as a shared, internet-facing endpoint without adding your own authentication and identity layer in front of it.

Use the library and add your own auth

For multi-tenant or public deployments, build an authenticated solution using the @mongodb-js/mcp-* library packages instead:

• Terminate authentication / user identity at your own proxy or middleware, and pass a verified principal into the request via authInfo (the SDK's createMcpHandler and the legacy handler both forward it).
• Supply a connectionScope policy that keys on your verified end-user identity (e.g. the OIDC sub claim) so each user's connections and credentials are isolated — do not let it fall back to the shared global scope for multi-user traffic.

Already on MongoDB Atlas? For multi-tenant Atlas cluster usage, the simplest alternative is the MongoDB Atlas-Managed MCP server — a hosted, authenticated deployment that handles per-user identity (OAuth / service-account) for you instead of you standing up your own. See Option 2 above.

See MCP_SERVER_LIBRARY.md for the embedding API, createHttpTransportRunnerFromConfig / CliMcpHttpServer and the connectionScope policy seam, and the per-user scoping example to copy.

🤝Contributing

Interested in contributing? Great! Please check our Contributing Guide for guidelines on code contributions, standards, adding new tools, and troubleshooting information.