feat(config): add maxTimeMs configuration for query timeout protection by jahales · Pull Request #830 · mongodb-js/mongodb-mcp-server

jahales · 2026-01-06T16:57:02Z

Description

Add a maxTimeMs configuration option to automatically terminate long-running find and aggregate operations after a specified duration. This provides resource protection for AI-generated queries that may inadvertently perform expensive operations.

Closes #829

Jira: MCP-349

Motivation

When using the MongoDB MCP server with AI assistants, there's a risk of generating queries that scan large collections or perform expensive aggregations. Without a timeout, these queries can:

Block the MCP session
Consume excessive database resources
Lead to poor user experience

Changes

Configuration

Added maxTimeMs config option (default: 30000ms / 30 seconds)
Setting to 0 disables the timeout
Uses onlyLowerThanBaseValueOverride for safe config merging

Tools Updated

find.ts: Added maxTimeMS to cursor options
aggregate.ts: Added maxTimeMS to aggregate options
export.ts: Added maxTimeMS to both find and aggregate cursors

Tests

Updated config.test.ts with maxTimeMs in expectedDefaults
Added integration tests for find tool with maxTimeMs enabled/disabled
Added integration tests for aggregate tool with maxTimeMs enabled/disabled

Documentation

Updated README with new configuration option

Example Configuration

{
  "maxTimeMs": 30000
}

Checklist

Code follows project style guidelines
All tests pass (pnpm run check)
Documentation updated
Integration tests added
Related issue linked (Feature Request: Add maxTimeMS Configuration Option for Query Timeout #829)

Copilot

Pull request overview

This PR introduces a maxTimeMs configuration option to protect against long-running MongoDB queries by automatically terminating find and aggregate operations after a specified duration. The default timeout is 30 seconds, and setting it to 0 disables the feature.

Key changes:

Added maxTimeMs config parameter with safe override behavior using onlyLowerThanBaseValueOverride()
Updated find, aggregate, and export tools to apply the timeout via maxTimeMS cursor option
Added comprehensive integration tests verifying both enabled and disabled timeout scenarios

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/common/config/userConfig.ts	Adds the `maxTimeMs` configuration schema with a 30-second default
src/tools/mongodb/read/find.ts	Applies maxTimeMS to find cursor operations
src/tools/mongodb/read/aggregate.ts	Applies maxTimeMS to aggregate operations
src/tools/mongodb/read/export.ts	Applies maxTimeMS to both find and aggregate cursors in export operations
tests/unit/common/config.test.ts	Updates expected defaults to include the new maxTimeMs setting
tests/integration/tools/mongodb/read/find.test.ts	Adds integration tests for find tool with maxTimeMs enabled and disabled
tests/integration/tools/mongodb/read/aggregate.test.ts	Adds integration tests for aggregate tool with maxTimeMs enabled and disabled
README.md	Documents the new configuration option

tests/integration/tools/mongodb/read/find.test.ts

tests/integration/tools/mongodb/read/aggregate.test.ts

addaleax · 2026-01-06T17:01:25Z

src/tools/mongodb/read/aggregate.ts

-            aggregationCursor = provider.aggregate(database, collection, cappedResultsPipeline);
+            aggregationCursor = provider.aggregate(database, collection, cappedResultsPipeline, {
+                maxTimeMS: this.config.maxTimeMs || undefined,
+            });


Since the option is set on the MCP-server-wide config, should we set it on the MongoClient or NodeDriverServiceProvider instead? Or otherwise, if it's not meant to apply to all operations and really only find and aggregate, should it be named differently so it's clear that it's not the standard driver maxTimeMs option?

Great question! After checking, the MongoDB driver's maxTimeMS option is per-operation, not a MongoClient-level setting, so setting it globally on the client isn't directly possible.

Given that, I see a few options:

Rename to clarify scope - Something like queryMaxTimeMs or readMaxTimeMs to indicate it only applies to find/aggregate/export operations

Extend to more operations - Apply maxTimeMS to other read operations like count, listCollections, etc.

Keep as-is - The current name matches the MongoDB driver option name, which might be intuitive for users familiar with MongoDB

What would you prefer? I'm happy to adjust based on your guidance.

We have timeoutMS that is being set to 30s when constructing the driver options:

mongodb-mcp-server/src/common/connectionManager.ts

Line 45 in e885fa8

timeoutMS: 30_000,

Should this be the thing we configure instead?

Yeah, that should be the right place to consume this if we make it configurable

I was also wondering about maxTimeMS vs timeoutMS here, for a lot of devtools things the former is what makes the most sense since the primary concern is avoiding runaway tasks on the cluster and it's generally fine if the rest of the operation (e.g. network handling) takes a bit longer, I think a similar logic applies for MCP but I could see an argument to be made that if a response doesn't come within a specific amount of time, it's fine to fail it

I intentionally use maxTimeMS (per-operation) rather than timeoutMS (client-wide) because the goal is server-side protection against expensive AI-generated queries. maxTimeMS is enforced by MongoDB itself and only counts server execution time, whereas timeoutMS includes network latency and is client-enforced.

That said, I think making timeoutMS configurable makes sense as a separate feature for controlling deterministic MCP behavior (i.e., "the MCP should respond within X ms or fail"). Happy to add that in a follow-up PR if there's interest.

For this PR, I can rename the config to queryMaxTimeMs to clarify it applies to query operations (find/aggregate) and isn't the standard driver option. I can also extend it to other potentially expensive read operations like count and listCollections.

@addaleax @nirinchev Updated the PR: queryMaxTimeMs & applied to key read operations

jahales · 2026-01-06T17:09:10Z

Note this PR was generated with LLM assistance (Claude Opus 4.5)

- Add queryMaxTimeMs config option for server-side query timeout - Apply to read operations: find, aggregate, count, export - Default: 30 seconds, set to 0 to disable - Update README documentation - Add unit and integration tests

github-actions · 2026-03-03T00:26:55Z

This PR has gone 30 days without any activity and meets the project's definition of "stale". This will be auto-closed if there is no new activity over the next 30 days. If the issue is still relevant and active, you can simply comment with a "bump" to keep it open, or add the label "not_stale". Thanks for keeping our repository healthy!

jahales requested a review from a team as a code owner January 6, 2026 16:57

Copilot AI review requested due to automatic review settings January 6, 2026 16:57

Copilot AI reviewed Jan 6, 2026

View reviewed changes

tests/integration/tools/mongodb/read/find.test.ts Show resolved Hide resolved

tests/integration/tools/mongodb/read/aggregate.test.ts Show resolved Hide resolved

addaleax reviewed Jan 6, 2026

View reviewed changes

jahales force-pushed the feature/max-time-ms-config branch from 81c98d7 to ac5126a Compare January 21, 2026 02:32

jahales added 5 commits January 20, 2026 19:39

test: add queryMaxTimeMs tests for count and export operations

50ce0c0

fix: correct database name usage in export queryMaxTimeMs tests

cc0961e

fix: add exportsPath config to export queryMaxTimeMs tests

b1d574a

fix: use correct export tool parameter names (exportTarget, exportTitle)

0b07403

Merge branch 'main' into feature/max-time-ms-config

9a7e5a9

github-actions bot added the no-pr-activity label Mar 3, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(config): add maxTimeMs configuration for query timeout protection#830

feat(config): add maxTimeMs configuration for query timeout protection#830
jahales wants to merge 6 commits intomongodb-js:mainfrom
jahales:feature/max-time-ms-config

jahales commented Jan 6, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

addaleax Jan 6, 2026 •

edited

Loading

Uh oh!

jahales Jan 6, 2026

Uh oh!

nirinchev Jan 7, 2026

Uh oh!

addaleax Jan 8, 2026

Uh oh!

jahales Jan 8, 2026

Uh oh!

ghost Jan 21, 2026

Uh oh!

jahales commented Jan 6, 2026

Uh oh!

github-actions bot commented Mar 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

jahales commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Changes

Configuration

Tools Updated

Tests

Documentation

Example Configuration

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

addaleax Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jahales Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

nirinchev Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

addaleax Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

jahales Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

ghost Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

jahales commented Jan 6, 2026

Uh oh!

github-actions bot commented Mar 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jahales commented Jan 6, 2026 •

edited

Loading

addaleax Jan 6, 2026 •

edited

Loading