MongoDB MCP setup: connection strings and read-only access

Start a MongoDB MCP connection with a specific database and collection. Prepare an unimportant test document and record its identifier and two expected fields. Use a database user with suitable read permissions. A cluster name alone is not enough to validate the result: several databases may contain collections with the same name. Define the intended location before asking the connection to find it.

Three decisions before starting

MongoDB documents the mongodb-mcp-server package, the MDB_MCP_CONNECTION_STRING environment variable and the --readOnly option. Its official example configurations include read-only mode. That setting does not replace choosing a limited database user. Plan any later write task separately, and avoid broadening permissions simply to get past an unexplained error.

VS Code: enter the connection string as a secret input

Extend the workspace .vscode/mcp.json. This example prompts for a masked connection string and passes it to the server process. Keep passwords out of shared configuration files. Node.js and npx must be available to the process started by the editor. Also check whether network access rules allow this machine to reach the intended cluster.

{
  "inputs": [
    {
      "id": "mongodb-uri",
      "type": "promptString",
      "description": "MongoDB connection string",
      "password": true
    }
  ],
  "servers": {
    "mongodb": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mongodb-mcp-server@latest",
        "--readOnly"
      ],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "${input:mongodb-uri}"
      }
    }
  }
}

A masked prompt protects the value displayed in the dialog; the server process still receives the connection string. Keep it out of tickets, screenshots and public search fields. When adding to existing inputs, use a unique identifier for this prompt. The guides to environment variables and VS Code explain the surrounding configuration. Keep a copy of the previous configuration before editing an established workspace.

Read one document before querying broadly

1. Open the prepared document independently and record the database, collection, identifier and expected field values.

2. Start MCP with --readOnly. Inspect the available functions and whether the database connection actually succeeded.

3. Retrieve the known document with a narrow filter and a small result limit. Request only the fields needed for this check.

4. Compare the identifier and values with your independent note. If several documents appear, inspect the filter before turning the output into a report.

Diagnose the layer that failed

A startup failure first points to the local process. An authentication failure calls for checking the connection string, database user and authentication database. For an empty response, first check the database, collection and query filter instead. The identifier type matters: a string and an ObjectId may be treated differently. Use the database planner to record the intended scope and the troubleshooting navigator to separate startup from access problems.

After a successful check, record the package version and test scope without storing credentials in the note. Repeat the same read after an update. The MongoDB registry search also returns other implementations whose settings may differ. The data app guides offer further database and file connections with their own setup instructions.

Is the connection string a public MCP URL?

No. It connects the server process to MongoDB and may include credentials.

Does --readOnly replace a limited database user?

No. Inspect the tool mode and database account permissions independently.

Does an empty response prove the collection is empty?

No. Check database, collection, query filter and the identifier data type first.

Is this a hosted MCP server?

This example runs the official package locally through stdio. The database itself may still be remote.

Provider sources checked on 2 October 2026. Test procedures are editorial suggestions.

1. MongoDB: MCP server and configuration
   Show retrieval command

   curl -s https://github.com/mongodb-js/mongodb-mcp-server
2. VS Code: MCP configuration and input variables
   Show retrieval command

   curl -s https://code.visualstudio.com/docs/copilot/customization/mcp-servers

All posts