MongoDB Integration

The MongoDB integration provides a secure, schema-aware interface between MCP Express and your MongoDB clusters. It abstracts connection handling and action execution so AI tools can query and modify data within clearly defined guardrails.

Capabilities

• Action-Based Operations: Expose deterministic find, insert, update, delete, and count actions as MCP tools.
• Scoped Collections: Bind tools to explicit databases and collections to enforce least-privilege access.
• Typed JSON Payloads: Validate JSON input for filters, projections, and updates before execution.

Integration

Configure MongoDB connectivity so MCP Express can authenticate, confirm database access, and prepare collection-aware tools. This sets the trust boundary for read and write operations.

Connection Parameters

Configure the following fields using a dedicated database user with the minimum permissions required.

Parameter	Technical Description	Required
Host	MongoDB host or cluster endpoint.	Yes
Port	MongoDB port (Default: 27017).	Optional
Database Name	Database scope for the integration.	Yes
Username	Database user name.	Yes
Password	Password for the database user.	Yes

Required Permissions

Ensure the database user can access only the collections and actions you plan to expose.

Network Access

Ensure the MCP server can reach the MongoDB host on the configured port and that any firewall or network rules allow access.

Connection Validation

When you test the connection, MCP Express performs the following checks:

• Credential Verification: Confirms the username and password.
• Database Reachability: Verifies the target database is accessible.
• Collection Access: Checks that collections are visible for configuration.

If validation fails, the test output shows what went wrong so you can fix connection or access issues.

Configuration

Once the MongoDB connection is validated, configuration defines how MCP Express exposes collection operations as callable tools. Most actions require a collection and may include a filter, update document, or data payload depending on the tool.

Tool Orchestration

MongoDB uses an action-oriented model where each tool maps to a bounded database operation. Configuration should keep collection scope explicit and expose only the runtime fields needed by that action.

Action Configuration

Use action configuration to define which database operation the tool performs and which parameters are resolved at runtime. Filters, updates, and documents can include placeholders like {{email}}.

Supported Actions

• Find: Retrieve documents using a filter, projection, and optional limit.
• Insert One: Insert a single document.
• Insert Many: Insert a list of documents.
• Update One: Update a single document using a filter and update document.
• Update Many: Update multiple documents using a filter and update document.
• Delete One: Delete a single document using a filter.
• Delete Many: Delete multiple documents using a filter.
• Count: Count documents using a filter.

Common Runtime Parameters

Use the following parameters according to the configured action.

Parameter	Required	Description
Action	Yes	The operation to run: find, insert_one, insert_many, update_one, update_many, delete_one, delete_many, or count.
Collection	Yes	The target collection for the action.
Filter	Some	JSON filter used by find, count, update_*, and delete_*.
Update Document	Some	JSON update document for update_one and update_many (for example, $set).
Document	Some	JSON document for insert_one.
Documents	Some	JSON array of documents for insert_many.
Projection	No	JSON projection to limit returned fields for find.
Limit	No	Maximum number of documents to return for find.

Governance Controls

Limit tools to approved databases and collections, and avoid broad filters in production. Require explicit filters for updates and deletes, and keep projections narrow so only expected fields are returned.

Test Tool Contracts Before Deployment

Use the built-in testing utility to verify placeholder resolution, required field behavior, and permissions before enabling tools in production.

Security & Patterns

This section outlines the guardrails and usage patterns that keep MongoDB tools safe for production. The main risks are overly broad filters, unbounded updates or deletes, and large result sets that return too much data.

Guardrails & Collection Scope

Keep operations inside approved databases and collections. That matters most for:

• Find and Count, which can scan large data sets.
• Insert and Update, which can change production data.
• Delete, which can remove data permanently.

Collection Scope Must Be Enforced

Unvalidated filters or collection names can expose unintended data. Enforce allowlists, collection-level permissions, and input validation before allowing runtime substitution.

Query and Update Safety

MongoDB filters and update documents are powerful, so keep them narrow and predictable.

Recommended practices:

• Use allowlists for filter keys, especially for mutation tools.
• Prefer exact-key filters (for example, _id) for update or delete actions.
• Require $set-only updates when you want to prevent document replacement.
• Avoid $where or unbounded logical conditions unless you control the inputs.

Fully Dynamic AI Queries

The special {{query}} argument allows the AI to generate the full MongoDB filter or pipeline at runtime from natural language. This is useful when you do not have a fixed tool for a one-off question, but it increases risk because the AI controls the entire query shape.

Use case example: If a user asks, "Show the 10 newest paid orders from enterprise customers," the AI can build a filtered query with a sort and a limit without a pre-defined tool.

Security Risks of Dynamic Queries

Using {{query}} gives the AI broad control over filters and pipeline stages. Only enable it with strict collection allowlists, key allowlists, and a database role that limits reads and writes.

Action-Specific Safety

Find and Count

Discovery tools should be bounded carefully.

• Use a conservative limit to keep result sets small.
• Add a projection so only needed fields are returned.
• Keep filters narrow and indexed to avoid slow scans.

Insert and Update

Write actions are where data integrity matters most.

• Validate required fields before inserts.
• Use $set updates to avoid replacing entire documents.
• Require filters for updates; never allow an empty filter for mutation tools.

Delete

Deletes are high-risk and should be used sparingly.

• Restrict delete tools to service accounts with narrow scope.
• Require explicit filters and block empty filters.
• Prefer delete_one over delete_many unless the use case is tightly controlled.

Performance Optimization

Pattern	Description	Benefit
Indexed Filters	Index fields used in filters.	Reduces query latency.
Limit Clauses	Set a limit for find results.	Prevents large result sets.
Narrow Projections	Return only needed fields.	Reduces payload size.
Bounded Updates	Require filters for all updates.	Avoids full-collection writes.

Protocol Limitations

• Large binary fields can exceed response size limits if returned in queries.
• Long-running queries may time out if filters are unbounded or unindexed.