This MongoDB MCP server has clear tool registration with complete JSON schemas and reasonable descriptions, but falls short of production quality due to missing output schema documentation, underdescribed parameters, and lack of error guidance for LLMs. Both tools are registered with proper input schemas (properties, types, descriptions), which is a strong foundation. However, the output format is nowhere documented, LLMs cannot know what structure to expect from mongo_execute or mongo_collections responses, forcing them to guess and potentially misparse results. Parameter descriptions, while present, are brief and lack actionable detail: 'MongoDB command to execute' does not explain what syntax is supported, what happens on error, or what the output looks like. The 'connectionString' parameter is repeated across tools but never explains how to format it or where to get it. Error handling is generic ('throw McpError'), no guidance for LLMs on recovery steps. The server implements a SafeResponseHandler to cap response sizes, but this is not documented in tool descriptions, so LLMs may pass unbounded queries unaware of limits. Overall, the tools are functional and the schema structure is sound, but the descriptions and output documentation fall short of the 194-character average for production tools and lack the LLM-facing guidance needed for reliable multi-step reasoning.
Output schemas are not documented. Tool descriptions do not specify what mongo_execute or mongo_collections return. LLMs cannot plan downstream operations or validate responses.
Parameter descriptions lack actionable constraints and examples of valid input. 'MongoDB command to execute' does not explain mongosh syntax, supported commands, or error handling. 'MongoDB connection string' does not explain format (URI syntax, authentication, database selection).
No error recovery guidance. If a MongoDB command fails, the server throws McpError with a raw error message. LLMs receive no hint on what to do next: retry? Call a different tool? Ask the user? This violates the recovery-guide pattern.
mongo_executemongo_collections
Recommendations
Document the output schema for both tools. Specify the structure of mongo_execute result (e.g., {success: boolean, data: any[], executionTime: number, message?: string}) and mongo_collections result (e.g., for 'list': {collections: [{name: string, count: number, avgDocSize: number}]}, for 'describe': {...}, etc.). Include these in the ListTools response under an outputSchema field or in the tool description with JSON examples.
Expand parameter descriptions to 60 - 100 characters with concrete constraints. Example for 'command': 'MongoDB command in mongosh syntax (e.g., db.users.find({age: {$gt: 18}}), db.products.updateMany({}, {$set: {active: true}})). Commands are executed in the context of the specified database. Supports find, findOne, insertOne, updateOne, updateMany, deleteOne, deleteMany, and aggregation pipelines.'
Add a required 'connectionString' format guideline: 'MongoDB connection string in URI format (mongodb://[username:password@]host[:port]/[database][?options]). Example: mongodb://root:password@localhost:27017/mydb. Omit password if not required; it is passed securely server-side.'
Document the maxResults cap in mongo_execute description: 'Maximum results returned capped at 100 documents (configurable via MAX_RESPONSE_DOCUMENTS). If your query matches more, only the first 100 are returned. Use skip/limit in the MongoDB command to paginate.'
Add actionable error responses. In the execute handlers (execute.ts, collections.ts), catch MongoDB errors and return structured responses like: {success: false, error: 'InvalidSyntax', message: 'Syntax error in command', suggestion: 'Check mongosh syntax. Example: db.users.find({})'}. This guides LLMs to retry or refine the query.
Tool 'mongo_collections' conflates multiple distinct operations under one 'action' enum (list, describe, indexes, stats). Reduces clarity on what each variant does. The 'collection' parameter is optional for 'list' but required for others, dependency undocumented.
Response size limits (maxResults=100, SafeResponseHandler caps) are implemented server-side but not documented in tool descriptions. LLMs cannot anticipate truncation and may form incorrect assumptions about result completeness.
mongo_execute
Split mongo_collections into separate tools if feasible: mongo_list_collections, mongo_describe_collection, mongo_collection_indexes, mongo_collection_stats. Alternatively, document each action variant's output schema separately in the description.
Add 'explain' parameter documentation: 'When true, returns MongoDB query execution plan (winning plan, rejected plans, execution stats) instead of results. Use to optimize slow queries. Note: only applies to find() and aggregation commands; not supported for insert/update/delete.'
Validate and document timeout behavior. The 'timeout' parameter (default 30000ms) is present but never explained in context. Add: 'Timeout in milliseconds (1000 - 300000; default: 30000). Commands exceeding this timeout are aborted. Large aggregations may need higher timeouts.'
Include examples in the description of what mongo_collections returns for each action. E.g., 'action=list returns [{name: "users", type: "collection", count: 1234}, ...]. action=describe returns {name: "users", ns: "mydb.users", count: 1234, avgObjSize: 256, indexes: [...]}'.