[Feature Request]: Add index check before query

[Crushdada]

Feature: Index Check Before Query

To improve query performance and prevent slow queries, add an indexCheck environment variable to MCP Server. When indexCheck=true, all MongoDB queries (find, aggregate, update, etc.) will first use explain('queryPlanner') to check if the query will hit an index. If not, the query is rejected and a friendly error message is returned, prompting the user to optimize the query or add an index. This feature helps avoid accidental collection scans and protects database performance.

Key Points:

• Controlled by MDB_MCP_INDEX_CHECK environment variable

• Automatically checks index usage with explain('queryPlanner') before executing queries

• If no index is used, returns an error and does not execute the query

• Applies to all query operations (find, aggregate, update, etc.)

[Crushdada]

Hello, just checking if this issue has been noted. I'm interested in it and happy to help solve it. Let me know if you need any info or preliminary work. Thanks!

[kmruiz]

Hey @Crushdada , thanks for opening the feature request!

The MongoDB MCP Server currently supports an explain plan to check if a query would run in a COLLSCAN or not. I was playing a bit with Claude to understand your use case, and with the current list of tools, it seems to work fine. Let me attach that part of the conversation as an image.

With proper prompting it works fine, would it work for you or are you expecting something else?

If you want more safety, you can configure the server to reject COLLSCANS: https://www.mongodb.com/docs/manual/reference/parameters/#mongodb-parameter-param.notablescan

This is also available in Atlas: https://www.mongodb.com/docs/atlas/cluster-additional-settings/#require-indexes-for-all-queries

[Crushdada]

Hey @Crushdada , thanks for opening the feature request!嘿，感谢你提交这个功能请求！

The MongoDB MCP Server currently supports an explain plan to check if a query would run in a COLLSCAN or not. I was playing a bit with Claude to understand your use case, and with the current list of tools, it seems to work fine. Let me attach that part of the conversation as an image.MongoDB MCP Server 目前支持一个解释计划来检查查询是否会在 COLLSCAN 中运行。我稍微和 Claude 一起研究了下你的用例，根据当前的工具列表，似乎运行得很好。让我把那部分对话附上作为图片。

With proper prompting it works fine, would it work for you or are you expecting something else?通过适当的提示，它可以正常运行，你觉得这样对你来说可以吗，还是你期待其他功能？

If you want more safety, you can configure the server to reject COLLSCANS: https://www.mongodb.com/docs/manual/reference/parameters/#mongodb-parameter-param.notablescan如果您需要更高的安全性，可以配置服务器拒绝 COLLSCANS：https://www.mongodb.com/docs/manual/reference/parameters/#mongodb-parameter-param.notablescan

This is also available in Atlas: https://www.mongodb.com/docs/atlas/cluster-additional-settings/#require-indexes-for-all-queries在 Atlas 中也可以使用此功能：https://www.mongodb.com/docs/atlas/cluster-additional-settings/#require-indexes-for-all-queries

Thank you for your reply. This solution is quite good and can solve my problem to a certain extent. However, if it could support user configuration to make this index check the default behavior, then users wouldn't have to input prompts each time and then tell the ai to explain first instead of querying directly. I believe this will significantly improve the availability of the mcp server.

If you agree with implementing this feature, I’m very interested in working on it! However, I might need some guidance along the way.

Do you think this would be a relatively low-effort task? Would you be open to helping me implement it? :)

[kmruiz]

I think it should be relatively low-effort. We would need something similar to what we do for --readOnly, but the main difference is that the tool will be always available and the --requireIndexUsage flag (or something similar!) would be checked in the execute method.

What you would need to change is:

• Add the new configuration file to config.ts.
• In find.ts, in the execute method, you can access your new flag in this.config.yourNewFlag
• If the flag is true: run the explain plan and check if it's a collection scan and reject the query. You can see how in explain.ts
• If it's false, the behaviour is as it is.

If you open a PR with these changes (or part of them!) I'll follow up and help you on whatever you need to move this forward.

[Crushdada]

@kmruiz Hi，I've created a PR to address this issue: #PR-309. Could you please take a look when you have time? :)