It provides a MongoDB MCP server to query and manipulate MongoDB databases through any MCP client.
Discover collections and schemas (listCollections, getSchema)
Query documents (find, findOne, count, distinct)
Run aggregation pipelines (aggregate)
Modify data (insertOne, updateOne, deleteOne)
Support filtering, sorting, pagination, projections, and upserts
Automatically handle ObjectId conversion
Integrate with Claude, Codex, Cursor, VS Code, Zed, and other MCP clients via stdio
Provides tools for interacting with MongoDB, including schema discovery, document querying, aggregation, and CRUD operations on collections.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MongoDB That Works - MCP Server get schema for users collection"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A reliable MongoDB MCP (Model Context Protocol) server with built-in schema discovery and field validation. It's a standard MCP server over stdio, so it connects to any MCP client — Claude Desktop, Claude Code, OpenAI Codex, Cursor, VS Code / GitHub Copilot, Zed, and more.
Published on npm:
@sourabhshegane/mongodb-mcp-that-works· Install withnpx -y @sourabhshegane/mongodb-mcp-that-works
This server connects to your MongoDB withfull read/write access to whatever user and database you supply via MONGODB_URI, and it exposes write tools (insertOne, updateOne, deleteOne) to any connected client. Only register it with MCP clients you trust. For high-risk environments, use a read-only MongoDB user or a dedicated database.
🔍 Schema Discovery: Automatically analyze collection structures
✅ Field Validation: Prevent field name mistakes
📊 Full MongoDB Support: Find, aggregate, insert, update, delete operations
🚀 High Performance: Efficient connection pooling and query optimization
🔐 Secure: Support for MongoDB Atlas and authentication
🎯 Type-Safe: Built with TypeScript and Zod validation
Related MCP server: Mongo-MCP
npm install -g @sourabhshegane/mongodb-mcp-that-worksThis is a standard stdio MCP server. Any MCP client launches it with npx and passes two environment variables:
Variable | Required | Description |
| Yes | MongoDB connection string, e.g. |
| No | Default database name (falls back to the URI's database) |
Every client below uses the same launch command:
npx -y @sourabhshegane/mongodb-mcp-that-works@latestThe -y flag auto-confirms the install so the client never hangs on an interactive prompt.
Security: never commit a real connection string. The examples use placeholders, or reference environment variables (
${env:...},env_vars,${input:...}) so credentials stay out of version control.
Edit your Claude Desktop config:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
"env": {
"MONGODB_URI": "mongodb+srv://<user>:<password>@cluster.mongodb.net/<database>",
"MONGODB_DATABASE": "your_database_name"
}
}
}
}Add it with the CLI (anything after -- is the server command):
claude mcp add mongodb --scope user \
--env MONGODB_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/<database> \
-- npx -y @sourabhshegane/mongodb-mcp-that-works@latestOr commit a project-scoped .mcp.json (secrets referenced with ${VAR}):
{
"mcpServers": {
"mongodb": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
"env": {
"MONGODB_URI": "${MONGODB_URI}",
"MONGODB_DATABASE": "${MONGODB_DATABASE:-your_database_name}"
}
}
}
}Scopes: local → ~/.claude.json, project → .mcp.json, user → ~/.claude.json. Verify with claude mcp list.
Codex uses TOML (not JSON). Add to ~/.codex/config.toml (or project-scoped .codex/config.toml):
[mcp_servers.mongodb]
command = "npx"
args = ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"]
env = { MONGODB_URI = "mongodb+srv://<user>:<password>@cluster.mongodb.net/<database>", MONGODB_DATABASE = "your_database_name" }
startup_timeout_sec = 30Or forward variables from your shell instead of inlining them:
[mcp_servers.mongodb]
command = "npx"
args = ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"]
env_vars = ["MONGODB_URI", "MONGODB_DATABASE"]Or add it with the CLI: codex mcp add mongodb -- npx -y @sourabhshegane/mongodb-mcp-that-works@latest. Verify with codex mcp list.
Project scope — .cursor/mcp.json (commit it to share with your team). Global scope — ~/.cursor/mcp.json.
{
"mcpServers": {
"mongodb": {
"command": "npx",
"args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
"env": {
"MONGODB_URI": "${env:MONGODB_URI}",
"MONGODB_DATABASE": "${env:MONGODB_DATABASE}"
}
}
}
}For quick installation, click the buttons below. After install, replace the placeholder connection string in your config:
Note: VS Code's root key is servers (other clients use mcpServers), and type is required. .vscode/mcp.json:
{
"servers": {
"mongodb": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
"env": {
"MONGODB_URI": "${input:mongodb-uri}"
}
}
},
"inputs": [
{
"id": "mongodb-uri",
"type": "promptString",
"description": "MongoDB connection string",
"password": true
}
]
}Add to settings.json (~/.config/zed/settings.json or .zed/settings.json):
{
"mcp": {
"mongodb": {
"command": "npx",
"args": ["-y", "@sourabhshegane/mongodb-mcp-that-works@latest"],
"env": {
"MONGODB_URI": "mongodb+srv://<user>:<password>@cluster.mongodb.net/<database>"
}
}
}
}listCollectionsList all collections in the database.
// Example
mcp.listCollections({ filter: {} })findFind documents in a collection with filtering, sorting, and pagination.
// Example
mcp.find({
collection: "users",
filter: { status: "active" },
sort: { createdAt: -1 },
limit: 10
})findOneFind a single document.
// Example
mcp.findOne({
collection: "users",
filter: { email: "user@example.com" }
})aggregateRun aggregation pipelines.
// Example
mcp.aggregate({
collection: "orders",
pipeline: [
{ $match: { status: "completed" } },
{ $group: { _id: "$userId", total: { $sum: "$amount" } } }
]
})countCount documents matching a filter.
// Example
mcp.count({
collection: "products",
filter: { inStock: true }
})distinctGet distinct values for a field.
// Example
mcp.distinct({
collection: "orders",
field: "status"
})insertOneInsert a single document.
// Example
mcp.insertOne({
collection: "users",
document: { name: "John Doe", email: "john@example.com" }
})updateOneUpdate a single document.
// Example
mcp.updateOne({
collection: "users",
filter: { _id: "123" },
update: { $set: { status: "active" } }
})deleteOneDelete a single document.
// Example
mcp.deleteOne({
collection: "users",
filter: { _id: "123" }
})getSchemaAnalyze collection structure and discover field names.
// Example
mcp.getSchema({
collection: "users",
sampleSize: 100
})
// Returns:
{
"collection": "users",
"sampleSize": 100,
"fields": {
"_id": {
"types": ["ObjectId"],
"examples": ["507f1f77bcf86cd799439011"],
"frequency": "100/100",
"percentage": 100
},
"email": {
"types": ["string"],
"examples": ["user@example.com"],
"frequency": "100/100",
"percentage": 100
}
}
}Tools are annotated with MCP ToolAnnotations so clients can distinguish read-only tools from write-capable tools and flag operations that are destructive:
Tool | readOnlyHint | idempotentHint | destructiveHint | Notes |
|
| – | – | Pure read |
|
| – | – | Pure read |
|
| – | – | Pure read |
|
| – | – | Pure read (may also run write stages) |
|
| – | – | Pure read |
|
| – | – | Pure read |
|
| – | – | Pure read |
|
|
|
| Additive; retrying inserts a new document |
|
|
|
| Modifies existing docs; |
|
|
|
| Deleting an already-absent document is a no-op |
Note:
aggregateis annotated read-only, but it can contain write stages (e.g.$out,$merge) — inspect pipelines before running.
Use Schema Discovery First: Before querying, run getSchema to understand field names
Handle ObjectIds: The server automatically converts string IDs to ObjectIds
Use Projections: Limit returned fields to improve performance
Batch Operations: Use aggregation pipelines for complex queries
// Get schema first to avoid field name mistakes
const schema = await mcp.getSchema({ collection: "reports" });
// Use correct field names from schema
const reports = await mcp.find({
collection: "reports",
filter: { organization_id: "64ba7374f8b63db2083b2665" },
limit: 10
});const analytics = await mcp.aggregate({
collection: "orders",
pipeline: [
{ $match: { createdAt: { $gte: new Date("2024-01-01") } } },
{ $group: {
_id: { $dateToString: { format: "%Y-%m", date: "$createdAt" } },
revenue: { $sum: "$amount" },
count: { $sum: 1 }
}},
{ $sort: { _id: 1 } }
]
});You can use the MCP Inspector to debug the server, inspect tool schemas, and call tools interactively:
npx @modelcontextprotocol/inspector npx -y @sourabhshegane/mongodb-mcp-that-works@latestSet MONGODB_URI (and optionally MONGODB_DATABASE) in your environment before launching the inspector.
Verify your MongoDB URI is correct
Check network connectivity to MongoDB Atlas
Ensure IP whitelist includes your current IP
Always use getSchema to discover correct field names
Remember MongoDB is case-sensitive
Check for typos in nested field paths (e.g., "user.profile.name")
Use indexes for frequently queried fields
Limit result sets with limit parameter
Use projections to return only needed fields
The repo ships an automated test suite (node:test, no extra framework):
npm testThis first builds, then runs:
Unit tests (tests/unit.test.mjs) — MCP protocol: negotiated version, the 10 tool schemas, ToolAnnotations, and error handling. No database required.
End-to-end tests (tests/e2e.test.mjs) — full CRUD tour against a real MongoDB (insertOne → find/findOne/count/distinct/aggregate → updateOne → getSchema → deleteOne), plus ObjectId auto-conversion and idempotency checks. Auto-skips with a note when no MongoDB is reachable.
The suite connects to MongoDB at MONGODB_URI (default mongodb://127.0.0.1:27017) and uses a throwaway database it deletes afterward, so it's safe against any existing data. CI runs both suites against a real MongoDB (Docker mongo:7) on every push/PR.
Contributions are welcome — new tools, bug fixes, examples, and documentation improvements. Pull requests and issues are appreciated. See CHANGELOG.md for release history. For examples of other MCP servers, see the reference implementations.
MIT License - see LICENSE file for details
See CHANGELOG.md for the full history.
Version | npm | GitHub Release | Highlights |
0.1.8 | Automated unit + e2e MongoDB test suite | ||
0.1.7 | ToolAnnotations, SDK 1.30, repo-standard docs | ||
0.1.6 | CI/CD, changelog, and repo badges | ||
0.1.5 | Post-migration metadata & ownership fixes | ||
0.1.3 | Published with | ||
0.1.2 | Repo URLs updated to mongodb-mcp-that-works | ||
0.1.0 | Initial release |
All versions published to npm also have tagged GitHub Releases with build checks. The repo uses GitHub Actions for continuous integration and automated publishing:
Tag pushes (v*) trigger lint/build checks and, once checks pass, an automated npm publish
Every published version has a matching GitHub Release
Made out of pain since the official MongoDB MCP didn't work for me
Run an aggregation pipeline on a MongoDB collection
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum documents to return | |
| pipeline | Yes | MongoDB aggregation pipeline | |
| collection | Yes | Collection name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description is consistent with these. However, the description adds no extra behavioral context such as return type, potential performance implications, or pipeline limitations, which would be useful beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, directly stating the core functionality. It is front-loaded with the action and resource, making it immediately clear what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and the presence of annotations and complete schema, the description is adequate but not rich. It does not mention return values or explain pipeline structure, but for an aggregation tool this is not a critical omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for all three parameters (collection, pipeline, limit) with 100% coverage, so the description adds no additional meaning. The baseline is 3, and no extra semantic detail is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (run) and the resource (an aggregation pipeline on a MongoDB collection). It distinguishes from siblings like find by focusing on the pipeline execution, though it doesn't explicitly contrast with find or other read tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use aggregation versus alternatives such as find, distinct, or count. The description does not specify scenarios where an aggregation pipeline is preferred or mention any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count documents in a MongoDB collection
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | MongoDB filter query | |
| collection | Yes | Collection name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds little about behavior beyond the count semantics (e.g., it does not state that an omitted filter counts all documents), but it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 8-word sentence with the key action and resource front-loaded. There is no filler or redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple count tool with a 100%-described schema and read-only annotations, the description is nearly sufficient. It does not explicitly state the return value, but 'Count' strongly implies a numeric result, making the omission minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both 'collection' and 'filter'. The description references collection but adds no parameter detail beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Count'), a resource ('documents in a MongoDB collection'), and the operation is immediately distinguishable from sibling read tools like find, findOne, distinct, and aggregate. The word 'Count' makes the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear this is for counting documents in a collection, which is the relevant context for selecting it over find/aggregate. It does not explicitly name alternatives or state when not to use it, but the operation itself provides enough contextual guidance for a simple count.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a single document from a MongoDB collection
| Name | Required | Description | Default |
|---|---|---|---|
| filter | Yes | Filter to find document | |
| collection | Yes | Collection name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey destructive and non-read-only behavior. The description adds only the 'single document' scope and does not disclose additional behavioral traits such as irreversibility, behavior when multiple documents match, or response contents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to identifying the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a basic two-parameter CRUD tool this is minimally adequate, but there is no output schema and the description does not mention what happens if the filter matches multiple documents or what result the caller receives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so both parameters are already documented. The description adds no extra meaning about how the filter should be formed or how collection name semantics behave.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Delete') and resource ('a single document from a MongoDB collection'). It is distinct from the sibling read/update tools, though it mostly expands the tool name without adding a differentiating scope condition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is used when exactly one document should be removed, but it gives no explicit guidance about when to prefer it over alternatives such as updateOne or findOne. There are no stated exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get distinct values for a field in a MongoDB collection
| Name | Required | Description | Default |
|---|---|---|---|
| field | Yes | Field to get distinct values for | |
| filter | No | MongoDB filter query | |
| collection | Yes | Collection name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context, such as the return format (an array of distinct values) or how the optional filter interacts with the query. With annotations present, the bar is lower, but the description still fails to enrich the agent's understanding of what happens at runtime.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with zero filler. It front-loads the core purpose and is appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should specify what the tool returns. It only says 'Get distinct values', which does not clarify that the result is an array, nor does it mention that the optional filter parameter can be used to restrict the query. The filter object is described in the schema but the description never hints at its role. This leaves the agent uncertain about output structure and usage nuances, making the definition incomplete for a tool with a nested object parameter and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (field, filter, collection) are individually described in the schema. The description adds no extra meaning beyond what the schema already provides; it merely restates the purpose. The baseline of 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a clear resource ('distinct values for a field in a MongoDB collection'), and the operation is unambiguous. It distinguishes from siblings like find/findOne (which return documents) and aggregate (which handles complex pipelines) by focusing on unique values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as aggregate or find. The description does not mention any exclusions, prerequisites, or conditions that would help an agent choose between distinct and other query tools. This is a single declarative sentence with no comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find documents in a MongoDB collection
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | Number of documents to skip | |
| sort | No | Sort specification | |
| limit | No | Maximum documents to return | |
| filter | No | MongoDB filter query | |
| collection | Yes | Collection name | |
| projection | No | Fields to include/exclude |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is known. The description adds no behavioral detail such as return format or pagination, but it does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste. It is front-loaded with the core purpose and does not repeat schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but adequate for a simple read operation given that the schema covers all parameters. However, it does not mention that it returns multiple documents or that it supports filtering/sorting, which could be relevant given the number of parameters and siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all six parameters, so the schema documents their purpose. The description adds no extra parameter context beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds documents in a MongoDB collection, specifying the verb and resource. It distinguishes from siblings like findOne (single document) and aggregate (pipeline) by the generic 'find' action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like findOne, aggregate, or count. The description does not mention exclusions or conditions for choosing it over siblings, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a single document in a MongoDB collection
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | MongoDB filter query | |
| collection | Yes | Collection name | |
| projection | No | Fields to include/exclude |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint), but the description adds no additional behavioral context. There is no mention of what happens if multiple documents match, whether a null result is returned when no document is found, or any error semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant filler. It is appropriately sized for a simple read tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The complete schema and annotations make the tool minimally usable, but the description leaves unspecified the return contract and behavior for non-matches or multiple matches. Since there is no output schema, a brief note about the returned document or null would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for all three parameters (filter, collection, projection), so the schema itself documents the parameters. The description adds no further parameter-specific meaning, so the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Find' and specifies the resource as 'a single document in a MongoDB collection.' The word 'single' clearly distinguishes it from the sibling tool find, making the tool's scope immediately obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use findOne versus the sibling find, aggregate, or count tools, and no exclusions or conditions are provided. The intended use-case is only implied by the word 'single.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze collection structure and return field names with types
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name | |
| sampleSize | No | Number of documents to sample |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that it returns field names with types, which is part of its behavior, but doesn't disclose that it samples documents (implied by sampleSize param) or that results are approximate. No contradiction, but no additional behavioral context beyond the purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the main action ('Analyze collection structure') and the outcome ('return field names with types'). No redundant words, and it is immediately scannable by an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only analysis tool with two well-documented parameters, the description is sufficient. It states the return content (field names with types) and the tool's purpose. It could mention that results are based on sampling (given the sampleSize parameter), but that is inferable. No output schema exists, so the description covers the essential return information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage: both 'collection' and 'sampleSize' have descriptive text. The description does not add any parameter-specific details beyond what the schema provides. Since the schema already documents the parameters adequately, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: analyze collection structure and return field names with types. This distinguishes it from siblings like find (returns documents), aggregate (returns computed results), and listCollections (lists collections). The verb 'analyze' is specific and the resource 'collection structure' is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for schema introspection rather than data retrieval. While it doesn't explicitly name alternatives or state when not to use it, the contrast with sibling tools is clear enough for an agent to select it appropriately. A mention of 'use this instead of find when you need structure' would make it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a single document into a MongoDB collection
| Name | Required | Description | Default |
|---|---|---|---|
| document | Yes | Document to insert | |
| collection | Yes | Collection name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, and the description adds no behavior beyond restating the insert operation. It does not disclose return value behavior, duplicate-insert consequences, or any required permissions, so it provides little value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that is front-loaded and contains no filler. Every word contributes to the core meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with full schema coverage and annotations present, the description is minimally adequate. However, there is no mention of the return value or what happens on repeated insertions, and since there is no output schema, the description could usefully provide more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented. The description mentions 'collection' and 'document' only as part of the sentence and adds no extra semantic detail beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('insert') and a specific resource ('a single document into a MongoDB collection'), making the core operation clear. It is distinguishable from siblings like updateOne and deleteOne, though it does not explicitly name or contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'insert' implies this tool is for adding new documents rather than updating or deleting them, so usage is indirectly conveyed. However, there is no explicit guidance about when to prefer this over updateOne/deleteOne or any prerequisites such as needing an existing collection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all collections in the database
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Optional filter for collections |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds that it enumerates collections, but does not clarify behavior such as whether system collections are included or how the optional filter affects results. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler, front-loading the action and resource. It is as concise as possible while stating the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with a single optional parameter, the description is mostly adequate. However, the filter parameter's semantics remain vague, and with no output schema the agent gets little detail about what a successful result looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the filter parameter is documented as 'Optional filter for collections.' The description adds no additional meaning about the filter's shape, allowed keys, or filtering behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('collections'), and the scope ('all in the database'). It distinguishes from document-level siblings like find and count, though it does not explicitly name an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: enumerate collections rather than documents. However, there is no explicit when-to-use guidance, no exclusion of document-level tools, and no mention of how this relates to getSchema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a single document in a MongoDB collection
| Name | Required | Description | Default |
|---|---|---|---|
| filter | Yes | Filter to find document | |
| update | Yes | Update operations | |
| upsert | No | Create if not exists | |
| collection | Yes | Collection name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. However, the description adds no extra behavioral context—no mention of return value, error behavior if no document matches, or consequences of the upsert option. It contributes nothing beyond the schema and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no redundant words. It is appropriately sized for a simple tool and front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with destructiveHint, this is under-specified. There is no output schema, so the description should explain what the tool returns (e.g., modified count, updated document) and how it handles non-matching filters or upsert behavior. The tool also has nested objects, but the schema covers those. Overall, the description leaves important operational details unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (collection, filter, update, upsert) are documented in the schema. The description adds no parameter details, but the baseline of 3 applies because the schema carries the full load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Update) and resource (a single document in a MongoDB collection). It clearly differentiates from read siblings (find, findOne) and delete (deleteOne) by its action, though it doesn't explicitly contrast with insertOne or mention that it targets exactly one document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It doesn't mention when to prefer updateOne over insertOne (if document may not exist), or over bulk update operations. The sibling list implies context, but the description provides no explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.8aggregatecountdistinctfindfindOneinsertOnelistCollectionsupdateOnev0.1.3deleteOnegetSchemaEach tool targets a distinct MongoDB operation: find vs findOne are clearly differentiated (multiple vs single document), and aggregate, count, distinct, listCollections, insertOne, updateOne, deleteOne, and getSchema have no overlapping responsibilities. The descriptions clarify the purpose of each, leaving no ambiguity for an agent.
All tool names follow a consistent lowerCamelCase convention with a verb-first pattern (find, findOne, aggregate, count, distinct, listCollections, insertOne, updateOne, deleteOne, getSchema). The style is uniform and predictable, making it easy to infer tool behavior from the name.
With 10 tools, the server is well-scoped for a MongoDB interface. It covers querying, aggregation, schema inspection, and basic CRUD operations without unnecessary bloat. Each tool serves a clear purpose, and the count is ideal for an MCP server of this domain.
The tool surface covers the core CRUD operations (insertOne, updateOne, deleteOne, find, findOne) and includes useful extras like aggregate, count, distinct, and getSchema. However, it lacks bulk operations (insertMany, updateMany, deleteMany) and collection management (createCollection, dropCollection), which are common in MongoDB workflows. These are minor gaps that an agent can work around by composing single-document calls, but they are noticeable.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
PostgreSQL, MySQL, OpenAPI/Swagger, and shared Agent Memory with scoped access.
Read, create, update and delete records; inspect objects, fields and schema in your Knack database.
Build multi-tenant apps over MCP. Schemas, CRUD, deploys — access control enforced server-side.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sourabhshegane/mongodb-mcp-that-works'
If you have feedback or need assistance with the MCP directory API, please join our Discord server