MongoDB MCP Server for Windsurf: Setup & Config

What you can do with MongoDB in Windsurf

A broad MongoDB toolset with read-only onboarding and integrated MongoDB knowledge search.

• Run document searches and aggregation pipelines from an assistant.
• Search MongoDB documentation and curated knowledge sources.

Before you start: MongoDB in Windsurf

• Node.js 22.13.0 or later
• A MongoDB connection string or Atlas service-account credentials
• An MCP-compatible client

This is the README's read-only connection-string setup. Atlas operations instead need MDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET. Docker and HTTP alternatives are documented; HTTP needs deployment-level authentication and protection.

MongoDB Windsurf configuration

1. Choose Windsurf configuration scope

   For MongoDB MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add MongoDB MCP Server to Windsurf

   Use the mongodb-mcp-server entry below in mcpServers. Keep MongoDB MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check MongoDB MCP Server in Windsurf

   MongoDB MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "mongodb-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server@latest",
        "--readOnly"
      ],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "<MongoDB connection string with appropriate credentials>"
      }
    }
  }
}

MongoDB tools available to Windsurf

MongoDB's stored tool list documents 27 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

aggregate-db

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for aggregate-db.

Execute a database-level aggregation pipeline.

aggregate

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for aggregate.

Execute an aggregation pipeline on a collection.

collection-indexes

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for collection-indexes.

collection-schema

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for collection-schema.

collection-storage-size

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for collection-storage-size.

connect

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for connect.

count

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for count.

create-collection

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for create-collection.

create-index

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for create-index.

Add an index to a collection.

db-stats

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for db-stats.

Report usage statistics for one database.

delete-many

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for delete-many.

Delete collection documents selected by a filter.

disconnect

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for disconnect.

Close a connection; a configured default connection can reopen on later use.

drop-collection

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for drop-collection.

Remove a collection or view together with its indexes.

drop-database

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for drop-database.

Delete a database and its associated data files.

drop-index

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for drop-index.

explain

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for explain.

export

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for export.

find

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for find.

insert-many

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for insert-many.

list-collections

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for list-collections.

list-connections

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for list-connections.

list-databases

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for list-databases.

Enumerate databases reachable through a connection.

mongodb-logs

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for mongodb-logs.

Read recent events logged by mongod.

rename-collection

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for rename-collection.

Change a collection's name.

update-many

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for update-many.

Modify collection documents that satisfy a filter.

list-knowledge-sources

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for list-knowledge-sources.

Discover sources and filtering options in the MongoDB Assistant knowledge base.

search-knowledge

After refreshing MongoDB in Windsurf settings, check Cascade's tool list for search-knowledge.

Search MongoDB documentation and expert resources with source and version filters.

MongoDB: full stored tool descriptions

Troubleshooting MongoDB in Windsurf

• Check npx mongodb-mcp-server@latest (Node.js/npm) on the machine running Windsurf's MCP integration for MongoDB MCP Server; refresh MCP and inspect Cascade's tools.
• Check MDB_MCP_CONNECTION_STRING for MongoDB MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• MongoDB MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Atlas tools require separate service-account credentials.
• Known limitation: HTTP deployments need additional security controls.
• Known limitation: Write-enabled tools can delete data and database objects.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions