Skip to main content

MongoDB

MongoDB is a document-oriented NoSQL database platform that provides flexible schema design, powerful querying capabilities, and horizontal scalability. MongoDB Atlas is the fully-managed cloud database service.

This connector provides comprehensive access to both Atlas management operations (cluster management, user administration, backups, monitoring) and database operations (CRUD, queries, aggregations, indexes).

Authentication Types​

MongoDB supports 1 authentication method:

  • OAuth 2.0 (Client Credentials) - Uses Atlas service accounts for API authentication. Secure, automated access for managing Atlas resources and databases.
    • Pros: Secure, no password rotation needed, production-ready, supports programmatic access
    • Cons: Requires Atlas organization or project admin access to create service accounts
    • Best for: Automated workflows, CI/CD pipelines, production deployments, application integrations

Setting up OAuth 2.0​

MongoDB Atlas uses service accounts for OAuth 2.0 authentication. Follow these steps:

1. Create a Service Account​

  1. Log in to MongoDB Atlas

  2. Navigate to Organization Settings or Project Settings (depending on desired scope)

    • Organization level: In the left sidebar under Identity & Access, click Applications.
    • Project level: Select your project, then in the left sidebar under Security, click Project Identity & Access, then click Applications.

  3. The Service Accounts tab is selected by default — click Create service account

    • On Organization level: Can use also the Add new button in the top right and select Service Account.
    • On Project level: Can use also the Create Application button in the top right and select Service Account.

  4. Enter a descriptive name (e.g., "Webrix Integration")

  5. Enter a short description

  6. Assign Organization Permissions or Project Permissions

    • Organization Permissions
      • Root access to the organization: Organization Owner
      • Project creation access: Organization Project Creator
      • Read-only access to everything in the organization: Organization Read Only
    • Project Permissions
      • For full management access: Project Owner
      • For database access only: Project Data Access Admin
      • For read-only access: Project Read Only

  7. Click Create

  8. Copy the Client ID and Client Secret immediately - the secret will not be shown again

    tip

    Store these credentials securely. If you lose the secret, you'll need to regenerate it, which will invalidate the old credentials.

  1. In your Atlas project, go to Network Access under Security - Database & Network Access.

  2. Click IP Access List

  3. Click Add IP Address

  4. Add the IP addresses or CIDR blocks that will access your databases:

    • For Webrix cloud: Add Webrix's IP addresses (provided in the platform)
    • For development: Add your local IP or use 0.0.0.0/0 (not recommended for production)

  5. Add a comment to identify the purpose (e.g., "Webrix Integration")

  6. Click Confirm

3. Get Your Project ID​

  1. In Atlas, navigate to your project

  2. Click the cog next to Project Overview

  3. Copy the Project ID (also shown as Group ID in some places)

    Example: 507f1f77bcf86cd799439011

4. Set Up a Data API Base URL​

The Data API Base URL is used for database operations (CRUD, queries, aggregations). It points to an HTTP endpoint that exposes your MongoDB cluster via a REST interface.

info

MongoDB Atlas discontinued its built-in Data API on September 30, 2025. To use data operation tools (find, insert, update, delete, aggregate, etc.), you need to self-host a compatible REST wrapper that exposes the same /action/* endpoints.

We recommend Delbridge or RESTHeart as drop-in replacements. Both can be deployed alongside your Atlas cluster and expose the same HTTP interface that the data operation tools expect.

Option A: Delbridge (purpose-built Data API replacement)​

Delbridge is an open-source server designed specifically as a replacement for the MongoDB Atlas Data API. It exposes the same /action/find, /action/insertOne, etc. endpoints.

  1. Clone and deploy Delbridge following its setup instructions
  2. Connect it to your Atlas cluster using a MongoDB connection string
  3. Note the base URL of your deployed Delbridge instance (e.g., https://your-delbridge-host.com/api/v1)

Option B: RESTHeart​

RESTHeart is a lightweight platform that wraps MongoDB as a REST/GraphQL service.

  1. Deploy RESTHeart following its getting started guide
  2. Connect it to your Atlas cluster
  3. Note the base URL of your deployed RESTHeart instance

Option C: Custom Express/Node.js wrapper​

You can also build a minimal Express app that mirrors the Data API interface and deploy it to any cloud provider (AWS Lambda, Railway, Render, etc.).

Once deployed, your Data API Base URL will look like:

https://your-host.com/api/v1

5. Configure in Webrix​

  1. In Webrix, go to MCP Servers → + Add MCP server

  2. Select MongoDB and click + Use

  3. In MongoDB select Settings

  4. Under Auth Settings, select Client Credentials

  5. Enter your credentials:

    • Client ID: Paste the service account Client ID from step 1
    • Client Secret: Paste the service account Client Secret from step 1
    • Token URL: https://cloud.mongodb.com/api/oauth/token

  6. Click on Save Changes

  7. Under General Settings:

    • Atlas Project ID: Paste your project ID from step 3
    • Data API Base URL: Paste the base URL of your self-hosted REST wrapper from step 4 (e.g., https://your-delbridge-host.com/api/v1)

  8. Click Save Changes

6. Test the Connection​

After saving, the integration will automatically authenticate using OAuth 2.0 and you can start using MongoDB tools.

Common Use Cases​

Cluster Management​

  • List and monitor all clusters in your project
  • Create new clusters for development or production
  • Scale clusters up or down by changing instance sizes
  • Pause clusters during non-usage periods to save costs
  • Test failover to verify high availability

Database User Management​

  • Create database users with specific roles and permissions
  • Update user roles and passwords
  • Scope users to specific clusters for enhanced security
  • Delete users when access is no longer needed

Data Operations​

  • Query documents with complex filters and aggregations
  • Insert, update, and delete documents
  • Create and manage collections
  • Build aggregation pipelines for analytics
  • Get collection statistics and monitor data growth

Index Management​

  • List all indexes on collections
  • Create indexes to improve query performance
  • Create Atlas Search indexes for full-text search
  • Drop unused indexes to improve write performance

Backup & Recovery​

  • List all available snapshots
  • Create on-demand snapshots before major changes
  • Restore data from snapshots to the same or different cluster
  • Monitor restore job progress

Monitoring & Alerts​

  • Configure alert rules for CPU, memory, disk space, connections
  • List active alerts and their status
  • Acknowledge alerts during incident response
  • Set up notifications for proactive monitoring

Troubleshooting​

"Unauthorized" or "Invalid Access Token" Error​

Cause: The OAuth token may have expired, or the service account credentials are incorrect.

Solution:

  1. Verify that the Client ID and Client Secret are correct
  2. Check that the service account hasn't been deleted or disabled in Atlas
  3. Ensure the service account has appropriate roles assigned
  4. Try regenerating the service account secret in Atlas and updating it in Webrix

"Project Not Found" Error​

Cause: The Project ID is incorrect, or the service account doesn't have access to the project.

Solution:

  1. Verify the Project ID is correct - check Atlas Project Settings
  2. Ensure the service account is created at the organization level and has project access, or is created within the specific project
  3. Check that the service account role includes the target project

Connection String Authentication Failed​

Cause: Database user credentials in the connection string are incorrect, or the user doesn't exist.

Solution:

  1. Verify the username and password in the connection string are correct
  2. Check that the database user exists in Database Access in Atlas
  3. Ensure the user has appropriate roles for the databases you're accessing
  4. Verify the authentication database (usually admin for SCRAM users)
  5. Check that the user isn't restricted to specific IP addresses

IP Access List Blocking Connections​

Cause: The IP address attempting to connect is not in the project's IP access list.

Solution:

  1. Go to Network Access in Atlas
  2. Add the IP address or CIDR block that needs access
  3. For Webrix cloud, add the IP addresses provided by Webrix
  4. Remember: IP access list changes take a few moments to propagate

"Cluster Not Found" Error for Data Operations​

Cause: The connection string points to a non-existent cluster, or the cluster name is misspelled.

Solution:

  1. Verify the cluster name in the connection string matches the cluster name in Atlas
  2. Check that the cluster is in a running state (not paused or terminated)
  3. Ensure the cluster is in the correct project

Rate Limiting​

Cause: MongoDB Atlas enforces API rate limits (100 requests per minute per project for most endpoints).

Solution:

  1. Implement retry logic with exponential backoff
  2. Batch operations where possible
  3. For data operations, use aggregation pipelines instead of multiple queries
  4. Monitor your API usage in Atlas Project Settings

Atlas Search Index Not Available​

Cause: Atlas Search is only available on M10+ clusters (not M0, M2, M5 free/shared tiers).

Solution:

  1. Verify your cluster tier - go to Atlas and check cluster configuration
  2. Upgrade to M10 or higher if you need Atlas Search functionality
  3. Use regular indexes and MongoDB's text search operators as an alternative on smaller tiers

Token Expiration​

Note: OAuth tokens expire after 1 hour. The connector automatically refreshes tokens as needed, but if you see intermittent authentication errors, this is normal behavior during token refresh.

Data API Base URL Format​

The Data API Base URL points to your self-hosted REST wrapper. It must expose the /action/* endpoints used by the data operation tools (/action/find, /action/insertOne, /action/updateOne, etc.).

The URL format depends on your chosen wrapper:

Delbridge:

https://your-delbridge-host.com/api/v1

RESTHeart:

https://your-restheart-host.com

Custom wrapper:

https://your-custom-host.com/api/v1

The connector appends action paths to this base URL, so ensure your service handles routes like {baseUrl}/action/find.

Additional Resources​