mcp-mongo-server 3.0.1 → 3.1.0

package/README.md

@@ -91,6 +91,7 @@ npx -y mcp-mongo-server "mongodb://..." --transport http --port 3001 --allowed-o
 | Variable | Description |
 |----------|-------------|
 | `MCP_MONGODB_URI` | MongoDB connection URI (alternative to the argument) |
+| `MCP_MONGODB_CONNECTIONS` | JSON object of named MongoDB connections and their database permissions |
 | `MCP_MONGODB_READONLY` | Enable read-only mode (`"true"`) |
 | `MCP_MONGODB_ALLOW_CROSS_DB` | Allow cross-database aggregation stages (`"true"`) |
 | `MCP_MONGODB_ALLOW_SERVER_JS` | Allow server-side JavaScript operators (`"true"`) |
@@ -99,22 +100,50 @@ npx -y mcp-mongo-server "mongodb://..." --transport http --port 3001 --allowed-o
 | `MCP_HTTP_JSON_LIMIT` | Max HTTP request body size (default `10mb`) |
 | `MCP_HTTP_AUTH_TOKEN` | Bearer token required to access the HTTP endpoint |
 
+### Named connections
+
+Set `MCP_MONGODB_CONNECTIONS` to a JSON string. This MCP client configuration
+uses a local build and the two [Docker test databases](docs/development.md#local-mongodb-test-environment).
+
+```json
+{
+  "mcpServers": {
+    "mongodb": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/mcp-mongo-server/build/index.js"
+      ],
+      "env": {
+        "MCP_MONGODB_CONNECTIONS": "{\"default\":{\"uri\":\"mongodb://127.0.0.1:37017/mcp_test\"},\"analytics\":{\"uri\":\"mongodb://127.0.0.1:37018/mcp_test?directConnection=true\",\"databases\":[\"mcp_test\",\"mcp_test_secondary\"],\"readOnly\":true}}"
+      }
+    }
+  }
+}
+```
+
+- Discover targets with `listConnections` and `listDatabases`. Pass `connectionId` and `database` to database tools and the collection analysis prompt. Omitted selectors use the `default` connection and its URI database.
+- Omit `databases` to allow only the URI database. If supplied, the list must include the URI database. Global read-only mode applies to every connection.
+- A positional URI or `MCP_MONGODB_URI` can supply `default` when the JSON contains only secondary connections. Named connections default to a 5-second server selection timeout. Set `serverSelectionTimeoutMS` in the URI to override it.
+- If a connection is offline, `resources/list` reports its ID and fails. Tools targeting other connections remain usable.
+
 ## Security
 
-**Database scope.** The server operates on the database in your connection
-string. Aggregation stages that reach another database (`$out`, `$merge`,
+**Database scope.** The server operates on the selected database.
+Named connections restrict selection to their configured databases.
+Aggregation stages that reach another database (`$out`, `$merge`,
 `$lookup` with an explicit `db`) are rejected by default, so a pipeline can't
 quietly read from or write to databases you didn't point it at. Enable them
-with `--allow-cross-db` if you need them.
+with `--allow-cross-db` if you need them. Named connections still enforce their
+database allowlist.
 
-**Server-side JavaScript.** The aggregation operators `$function`, `$where`,
-and `$accumulator` run arbitrary JavaScript on the MongoDB server. They are
-rejected by default; enable them with `--allow-server-js` if you trust the
-pipelines being run.
+**Server-side JavaScript.** The operators `$function`, `$where`, and
+`$accumulator` are blocked by default in aggregation pipelines and in the
+filters for `query`, `count`, and `update`. In read-write mode,
+`--allow-server-js` enables these operators.
 
-**Read-only mode** blocks every write path, including aggregation stages that
-write or run server-side JavaScript (`$out`, `$merge`, `$function`, `$where`,
-`$accumulator`).
+**Read-only mode** blocks writes, including the `$out` and `$merge`
+aggregation stages. It also blocks server-side JavaScript even when
+`--allow-server-js` is set.
 
 **Least privilege.** Application-level checks only go so far — the strongest
 guarantee comes from the database. Connect with a MongoDB user scoped to just

package/build/index.js

@@ -7,36 +7,184 @@ import { createMcpHandler } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { createMcpExpressApp } from "@modelcontextprotocol/express";
 
-// src/mongo.ts
+// src/connections.ts
+import { randomUUID } from "crypto";
+import { ProtocolError, ProtocolErrorCode } from "@modelcontextprotocol/server";
 import { MongoClient } from "mongodb";
-async function connectToMongoDB(url, readOnly) {
-  try {
-    const client = new MongoClient(url);
-    await client.connect();
-    const db = client.db();
-    console.warn(`Connected to MongoDB database: ${db.databaseName}`);
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+var Connections = class {
+  cursorScope = randomUUID();
+  named;
+  entries = /* @__PURE__ */ new Map();
+  closing;
+  constructor(legacyUri, configuration, readOnly) {
+    this.named = configuration !== void 0;
+    let config = {};
+    if (configuration !== void 0) {
+      try {
+        config = JSON.parse(configuration);
+      } catch {
+        throw new Error("MCP_MONGODB_CONNECTIONS must be valid JSON");
+      }
+    }
+    if (!isRecord(config))
+      throw new Error("MCP_MONGODB_CONNECTIONS must be an object");
+    if (legacyUri && Object.hasOwn(config, "default")) {
+      throw new Error("The legacy URI and named default connection conflict");
+    }
+    const entries = legacyUri ? { ...config, default: { uri: legacyUri } } : config;
+    if (!Object.hasOwn(entries, "default"))
+      throw new Error("A default MongoDB connection is required");
+    for (const [id, entry] of Object.entries(entries)) {
+      if (!/^[A-Za-z0-9_-]+$/.test(id))
+        throw new Error("Invalid connection ID");
+      if (!isRecord(entry) || Object.keys(entry).some(
+        (key) => !["uri", "databases", "readOnly"].includes(key)
+      )) {
+        throw new Error(`Invalid configuration for connection '${id}'`);
+      }
+      const { uri, databases, readOnly: localReadOnly } = entry;
+      if (typeof uri !== "string" || !/^mongodb(?:\+srv)?:\/\//.test(uri)) {
+        throw new Error(`Invalid MongoDB URI for connection '${id}'`);
+      }
+      if (localReadOnly !== void 0 && typeof localReadOnly !== "boolean") {
+        throw new Error(`Invalid readOnly setting for connection '${id}'`);
+      }
+      let client;
+      const query = uri.indexOf("?");
+      const uriOptions = new URLSearchParams(
+        query < 0 ? "" : uri.slice(query + 1)
+      );
+      const hasSelectionTimeout = [...uriOptions.keys()].some(
+        (key) => key.toLowerCase() === "serverselectiontimeoutms"
+      );
+      const selectionTimeout = this.named && !hasSelectionTimeout ? 5e3 : void 0;
+      try {
+        client = new MongoClient(uri, {
+          serverSelectionTimeoutMS: selectionTimeout
+        });
+      } catch {
+        throw new Error(`Invalid MongoDB URI for connection '${id}'`);
+      }
+      const defaultDatabase = client.db().databaseName;
+      if (databases !== void 0 && (!Array.isArray(databases) || !databases.includes(defaultDatabase) || databases.some(
+        (name) => typeof name !== "string" || !name.trim() || /[/\\. "$]/.test(name) || name.includes("\0")
+      ))) {
+        throw new Error(`Invalid database allowlist for connection '${id}'`);
+      }
+      this.entries.set(id, {
+        connectionId: id,
+        uri,
+        selectionTimeout,
+        client,
+        defaultDatabase,
+        databases: databases === void 0 ? [defaultDatabase] : [...new Set(databases)].sort(),
+        readOnly: readOnly || localReadOnly === true
+      });
+    }
+  }
+  connection(id = "default") {
+    const entry = typeof id === "string" ? this.entries.get(id) : void 0;
+    if (!entry) throw new Error("Unknown or invalid MongoDB connection ID");
+    return entry;
+  }
+  list() {
+    return [...this.entries.keys()].sort().map((id) => {
+      const { connectionId, defaultDatabase, readOnly } = this.connection(id);
+      return { connectionId, defaultDatabase, readOnly };
+    });
+  }
+  allowedDatabases(id) {
+    return this.connection(id).databases;
+  }
+  async resolve({ connectionId, database } = {}) {
+    const entry = this.connection(connectionId);
+    const name = database === void 0 ? entry.defaultDatabase : database;
+    if (typeof name !== "string" || !entry.databases.includes(name)) {
+      throw new Error(
+        `Database is invalid or not allowed on connection '${entry.connectionId}'`
+      );
+    }
+    if (this.closing) throw new Error("MongoDB connections are shutting down");
+    if (!entry.pending) {
+      const client2 = entry.client ?? new MongoClient(entry.uri, {
+        serverSelectionTimeoutMS: entry.selectionTimeout
+      });
+      entry.client = client2;
+      entry.pending = client2.connect().catch(async () => {
+        await client2.close().catch(() => void 0);
+        entry.client = void 0;
+        entry.pending = void 0;
+        throw new Error(
+          `Failed to connect to MongoDB connection '${entry.connectionId}'`
+        );
+      });
+    }
+    const client = await entry.pending;
     return {
       client,
-      db,
-      isConnected: true,
-      isReadOnlyMode: readOnly
-    };
-  } catch (error) {
-    console.error("Failed to connect to MongoDB:", error);
-    return {
-      client: null,
-      db: null,
-      isConnected: false,
-      isReadOnlyMode: readOnly
+      db: client.db(name),
+      isReadOnlyMode: entry.readOnly,
+      connectionId: entry.connectionId
     };
   }
+  async listDatabases(connectionId) {
+    const { db } = await this.resolve({ connectionId });
+    const allowed = this.allowedDatabases(connectionId);
+    const { databases } = await db.admin().listDatabases({
+      nameOnly: true,
+      authorizedDatabases: true,
+      filter: { name: { $in: [...allowed] } }
+    });
+    return databases.map(({ name }) => name).filter((name) => allowed.includes(name)).sort();
+  }
+  async close() {
+    this.closing ??= Promise.allSettled(
+      [...this.entries.values()].map(async ({ client, pending }) => {
+        await pending?.catch(() => void 0);
+        await client?.close();
+      })
+    ).then(() => void 0);
+    await this.closing;
+  }
+};
+function resourceSelectors(uri) {
+  let url;
+  try {
+    url = new URL(uri);
+    if (url.protocol !== "mongodb:") throw new Error("Invalid scheme");
+    decodeURIComponent(url.search);
+  } catch {
+    throw new ProtocolError(
+      ProtocolErrorCode.InvalidParams,
+      "Invalid MongoDB resource URI"
+    );
+  }
+  const selectors = {};
+  for (const key of ["connectionId", "database"]) {
+    const values = url.searchParams.getAll(key);
+    if (values.length > 1) {
+      throw new ProtocolError(
+        ProtocolErrorCode.InvalidParams,
+        `Duplicate resource selector '${key}'`
+      );
+    }
+    if (values.length === 1) selectors[key] = values[0];
+  }
+  return selectors;
 }
 
 // src/server.ts
-import { Server } from "@modelcontextprotocol/server";
+import {
+  ProtocolError as ProtocolError4,
+  ProtocolErrorCode as ProtocolErrorCode4,
+  Server
+} from "@modelcontextprotocol/server";
 
 // src/schemas/call.ts
-import { ProtocolError, ProtocolErrorCode } from "@modelcontextprotocol/server";
+import { ProtocolError as ProtocolError2, ProtocolErrorCode as ProtocolErrorCode2 } from "@modelcontextprotocol/server";
 import { ObjectId } from "mongodb";
 var COLLECTION_OPERATIONS = [
   "query",
@@ -82,6 +230,14 @@ function findAggOperator(value, operators, depth = 0) {
   }
   return null;
 }
+function assertNoServerJs(value) {
+  const operator = findAggOperator(value, SERVER_JS_AGG_OPERATORS);
+  if (operator) {
+    throw new Error(
+      `Server-side JavaScript operator '${operator}' is disabled by the current server policy.`
+    );
+  }
+}
 function findCrossDbTarget(pipeline, connectedDb) {
   const foreignDb = (target) => {
     if (target && typeof target === "object" && "db" in target) {
@@ -111,6 +267,7 @@ async function handleCallToolRequest({
   isReadOnlyMode,
   allowCrossDb = false,
   allowServerJs = false,
+  connections: connections2,
   signal
 }) {
   const { name, arguments: args = {} } = request.params;
@@ -126,8 +283,32 @@ async function handleCallToolRequest({
     args.sort = parseSort(args.sort);
   }
   Object.assign(args, filteredArgs);
-  validateOperation(operation);
+  if (!connections2 || name !== "listConnections" && name !== "listDatabases") {
+    validateOperation(operation);
+  }
   try {
+    signal?.throwIfAborted();
+    if (connections2 && name === "listConnections") {
+      return formatResponse({ connections: connections2.list() });
+    }
+    if (connections2 && name === "listDatabases") {
+      return formatResponse({
+        databases: await connections2.listDatabases(args.connectionId)
+      });
+    }
+    if (connections2 && operation !== "convertTime") {
+      const target = await connections2.resolve(args);
+      db = target.db;
+      isReadOnlyMode = target.isReadOnlyMode;
+      if (connections2.named && operation === "aggregate" && Array.isArray(args.pipeline)) {
+        const allowed = connections2.allowedDatabases(target.connectionId);
+        checkNamedAggregationDatabases(
+          args.pipeline,
+          db.databaseName,
+          allowCrossDb ? allowed : [db.databaseName]
+        );
+      }
+    }
     checkReadOnlyMode(operation, isReadOnlyMode);
     let collection = null;
     if (COLLECTION_OPERATIONS.includes(operation)) {
@@ -153,7 +334,7 @@ async function handleCallToolRequest({
       signal
     );
   } catch (error) {
-    if (error instanceof ProtocolError || signal?.aborted) {
+    if (error instanceof ProtocolError2 || signal?.aborted) {
       throw error;
     }
     return toolExecutionError(
@@ -161,10 +342,50 @@ async function handleCallToolRequest({
     );
   }
 }
+function checkNamedAggregationDatabases(pipeline, database, allowed, depth = 0) {
+  if (depth > MAX_OBJECT_DEPTH)
+    throw new Error("Aggregation pipeline nesting is too deep");
+  for (const stage of pipeline) {
+    if (!stage || typeof stage !== "object") continue;
+    const { $out, $merge, $lookup, $unionWith, $facet } = stage;
+    for (const target of [$out, $merge, $lookup, $unionWith]) {
+      if (!target || typeof target !== "object") continue;
+      const value = target;
+      for (const reference of [value, value.into, value.from]) {
+        if (!reference || typeof reference !== "object" || !("db" in reference))
+          continue;
+        if (typeof reference.db !== "string" || !allowed.includes(reference.db)) {
+          throw new Error(
+            `Aggregation references a database outside the allowed scope of '${database}'`
+          );
+        }
+      }
+      if (Array.isArray(value.pipeline))
+        checkNamedAggregationDatabases(
+          value.pipeline,
+          database,
+          allowed,
+          depth + 1
+        );
+    }
+    if ($facet && typeof $facet === "object") {
+      for (const nested of Object.values($facet)) {
+        if (Array.isArray(nested))
+          checkNamedAggregationDatabases(nested, database, allowed, depth + 1);
+      }
+    }
+  }
+}
 async function executeOperation(operation, collection, db, isReadOnlyMode, allowCrossDb, allowServerJs, args, objectIdMode, signal) {
   switch (operation) {
     case "query":
-      return handleQuery(collection, args, objectIdMode, signal);
+      return handleQuery(
+        collection,
+        args,
+        objectIdMode,
+        allowServerJs && !isReadOnlyMode,
+        signal
+      );
     case "aggregate":
       return handleAggregate(
         collection,
@@ -176,7 +397,13 @@ async function executeOperation(operation, collection, db, isReadOnlyMode, allow
         signal
       );
     case "update":
-      return handleUpdate(collection, args, objectIdMode, signal);
+      return handleUpdate(
+        collection,
+        args,
+        objectIdMode,
+        allowServerJs,
+        signal
+      );
     case "serverInfo":
       return handleServerInfo(db, isReadOnlyMode, args, signal);
     case "insert":
@@ -184,13 +411,22 @@ async function executeOperation(operation, collection, db, isReadOnlyMode, allow
     case "createIndex":
       return handleCreateIndex(collection, args, objectIdMode, signal);
     case "count":
-      return handleCount(collection, args, objectIdMode, signal);
+      return handleCount(
+        collection,
+        args,
+        objectIdMode,
+        allowServerJs && !isReadOnlyMode,
+        signal
+      );
     case "listCollections":
       return handleListCollections(db, args, objectIdMode, signal);
     case "convertTime":
       return handleConvertTime(args);
     default:
-      throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown tool: ${operation}`);
+      throw new ProtocolError2(
+        ProtocolErrorCode2.InvalidParams,
+        `Unknown tool: ${operation}`
+      );
   }
 }
 function validateOperation(operation) {
@@ -206,7 +442,10 @@ function validateOperation(operation) {
     "convertTime"
   ];
   if (!validOperations.includes(operation)) {
-    throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown tool: ${operation}`);
+    throw new ProtocolError2(
+      ProtocolErrorCode2.InvalidParams,
+      `Unknown tool: ${operation}`
+    );
   }
 }
 function validateCollection(collection) {
@@ -377,7 +616,7 @@ function handleError(error, operation, collectionName) {
   const message = error instanceof Error ? error.message : "Unknown error";
   return toolExecutionError(`Failed to ${operation} ${context}: ${message}`);
 }
-async function handleQuery(collection, args, objectIdMode = "auto", signal) {
+async function handleQuery(collection, args, objectIdMode = "auto", allowServerJs = false, signal) {
   if (!collection) {
     throw new Error("Collection is required for query operation");
   }
@@ -385,6 +624,9 @@ async function handleQuery(collection, args, objectIdMode = "auto", signal) {
   const limit = args.limit || 10;
   const skip = args.skip || 0;
   const queryFilter = parseFilter(filter, objectIdMode);
+  if (!allowServerJs) {
+    assertNoServerJs(queryFilter);
+  }
   try {
     if (explain) {
       signal?.throwIfAborted();
@@ -440,12 +682,7 @@ async function handleAggregate(collection, args, objectIdMode = "auto", isReadOn
     }
   }
   if (!allowServerJs) {
-    const js = findAggOperator(pipeline, SERVER_JS_AGG_OPERATORS);
-    if (js) {
-      throw new Error(
-        `Server-side JavaScript operator '${js}' is not allowed. Enable it with --allow-server-js or MCP_MONGODB_ALLOW_SERVER_JS=true.`
-      );
-    }
+    assertNoServerJs(pipeline);
   }
   if (!allowCrossDb) {
     const foreignDb = findCrossDbTarget(pipeline, collection.dbName);
@@ -486,12 +723,15 @@ async function handleAggregate(collection, args, objectIdMode = "auto", isReadOn
     return handleError(error, "aggregate", collection.collectionName);
   }
 }
-async function handleUpdate(collection, args, objectIdMode = "auto", signal) {
+async function handleUpdate(collection, args, objectIdMode = "auto", allowServerJs = false, signal) {
   if (!collection) {
     throw new Error("Collection is required for update operation");
   }
   const { filter, update, upsert, multi } = args;
   const queryFilter = parseFilter(filter, objectIdMode);
+  if (!allowServerJs) {
+    assertNoServerJs(queryFilter);
+  }
   let processedUpdate = update;
   if (update && typeof update === "object" && !Array.isArray(update)) {
     processedUpdate = processObjectIdInFilter(
@@ -652,7 +892,7 @@ async function handleCreateIndex(collection, args, objectIdMode = "auto", signal
       "Write concern must be a valid MongoDB write concern object"
     );
   }
-  if (commitQuorum && typeof commitQuorum !== "string" && typeof commitQuorum !== "number") {
+  if (commitQuorum !== void 0 && typeof commitQuorum !== "string" && typeof commitQuorum !== "number") {
     throw new Error("Commit quorum must be a string or number");
   }
   const processedIndexes = indexes.map((index) => {
@@ -666,7 +906,7 @@ async function handleCreateIndex(collection, args, objectIdMode = "auto", signal
   });
   try {
     const indexOptions = {
-      commitQuorum: typeof commitQuorum === "number" ? commitQuorum : void 0
+      commitQuorum
     };
     signal?.throwIfAborted();
     const createdIndexes = await collection.createIndexes(
@@ -682,12 +922,15 @@ async function handleCreateIndex(collection, args, objectIdMode = "auto", signal
     return handleError(error, "create indexes", collection.collectionName);
   }
 }
-async function handleCount(collection, args, objectIdMode = "auto", signal) {
+async function handleCount(collection, args, objectIdMode = "auto", allowServerJs = false, signal) {
   if (!collection) {
     throw new Error("Collection is required for count operation");
   }
   const { query, limit, skip, hint, readConcern, maxTimeMS, collation } = args;
   const countQuery = parseFilter(query, objectIdMode);
+  if (!allowServerJs) {
+    assertNoServerJs(countQuery);
+  }
   try {
     const options = {
       limit: typeof limit === "number" ? limit : void 0,
@@ -758,17 +1001,10 @@ async function handleListCollections(db, args, objectIdMode = "auto", signal) {
   const { nameOnly, filter } = args;
   const skip = args.skip || 0;
   const limit = args.limit || 20;
-  let processedFilter = filter;
-  if (filter && typeof filter === "object") {
-    processedFilter = processObjectIdInFilter(
-      filter,
-      objectIdMode
-    );
-  }
   try {
-    const options = processedFilter ? { filter: processedFilter } : {};
+    const processedFilter = parseFilter(filter, objectIdMode);
     signal?.throwIfAborted();
-    const collections = await db.listCollections(options).toArray();
+    const collections = await db.listCollections(processedFilter).toArray();
     const allResults = nameOnly ? collections.map((collection) => collection.name) : collections;
     const total = allResults.length;
     const paged = allResults.slice(skip, skip + limit);
@@ -948,7 +1184,8 @@ async function handleListPromptsRequest({
   client,
   db,
   isReadOnlyMode,
-  signal
+  signal,
+  connectionSelection = false
 }) {
   return {
     prompts: [
@@ -960,7 +1197,17 @@ async function handleListPromptsRequest({
             name: "collection",
             description: "Name of the collection to analyze",
             required: true
-          }
+          },
+          ...connectionSelection ? [
+            {
+              name: "connectionId",
+              description: "Configured MongoDB connection ID"
+            },
+            {
+              name: "database",
+              description: "Allowed MongoDB database name"
+            }
+          ] : []
         ]
       }
     ]
@@ -972,7 +1219,9 @@ async function handleGetPromptRequest({
   db,
   isReadOnlyMode,
   signal,
-  sendProgress
+  sendProgress,
+  connectionId,
+  showTarget = false
 }) {
   const { name, arguments: args = {} } = request.params;
   if (name !== "analyze_collection") {
@@ -1004,7 +1253,9 @@ async function handleGetPromptRequest({
           content: {
             type: "text",
             text: `Please analyze the following MongoDB collection:
-Collection: ${collectionName}
+Collection: ${collectionName}${showTarget ? `
+Connection: ${connectionId}
+Database: ${db.databaseName}` : ""}
 
 Schema:
 ${JSON.stringify(schemaSample, null, 2)}
@@ -1033,8 +1284,8 @@ ${JSON.stringify(sampleDocs, null, 2)}`
 
 // src/schemas/resource.ts
 import {
-  ProtocolError as ProtocolError2,
-  ProtocolErrorCode as ProtocolErrorCode2
+  ProtocolError as ProtocolError3,
+  ProtocolErrorCode as ProtocolErrorCode3
 } from "@modelcontextprotocol/server";
 import { ObjectId as ObjectId2 } from "mongodb";
 function detectMongoType(value) {
@@ -1137,28 +1388,28 @@ async function handleReadResourceRequest({
   try {
     const url = new URL(request.params.uri);
     if (url.protocol !== "mongodb:") {
-      throw new ProtocolError2(
-        ProtocolErrorCode2.InvalidParams,
+      throw new ProtocolError3(
+        ProtocolErrorCode3.InvalidParams,
         `Unsupported resource URI scheme '${url.protocol}': expected 'mongodb:'`
       );
     }
-    collectionName = url.pathname.replace(/^\//, "");
+    collectionName = decodeURIComponent(url.pathname.replace(/^\//, ""));
   } catch (error) {
-    if (error instanceof ProtocolError2) throw error;
-    throw new ProtocolError2(
-      ProtocolErrorCode2.InvalidParams,
+    if (error instanceof ProtocolError3) throw error;
+    throw new ProtocolError3(
+      ProtocolErrorCode3.InvalidParams,
       `Invalid resource URI: ${request.params.uri}`
     );
   }
   if (!collectionName) {
-    throw new ProtocolError2(
-      ProtocolErrorCode2.InvalidParams,
+    throw new ProtocolError3(
+      ProtocolErrorCode3.InvalidParams,
       "Resource URI is missing a collection name"
     );
   }
   if (collectionName.startsWith("system.")) {
-    throw new ProtocolError2(
-      ProtocolErrorCode2.InvalidParams,
+    throw new ProtocolError3(
+      ProtocolErrorCode3.InvalidParams,
       "Access to system collections is not allowed"
     );
   }
@@ -1250,7 +1501,7 @@ async function handleListResourcesRequest({
     signal?.throwIfAborted();
     const collections = await db.listCollections().toArray();
     const allResources = collections.map((collection) => ({
-      uri: `mongodb:///${collection.name}`,
+      uri: `mongodb:///${encodeURIComponent(collection.name)}`,
       mimeType: "application/json",
       name: collection.name,
       description: `MongoDB collection: ${collection.name}`
@@ -1322,13 +1573,14 @@ async function handleListToolsRequest({
   client,
   db,
   isReadOnlyMode,
-  signal
+  signal,
+  connectionSelection = false
 }) {
-  return {
+  const result = {
     tools: [
       {
         name: "query",
-        description: "Execute a MongoDB query with optional execution plan analysis",
+        description: "Find documents in one collection using a filter, projection, or sort. Use aggregate for grouping or joins. Request an execution plan to inspect the query.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1375,7 +1627,7 @@ async function handleListToolsRequest({
       },
       {
         name: "aggregate",
-        description: "Execute a MongoDB aggregation pipeline with optional execution plan analysis",
+        description: "Run a MongoDB aggregation pipeline for grouping, joins, or multi-stage transformations. Request an execution plan to inspect the pipeline.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1407,7 +1659,7 @@ async function handleListToolsRequest({
       },
       {
         name: "update",
-        description: "Update documents in a MongoDB collection",
+        description: "Modify matching documents using operators such as $set, $unset, or $inc. Enable multi to update all matches or upsert to create a document when the filter matches none.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1443,7 +1695,7 @@ async function handleListToolsRequest({
       },
       {
         name: "serverInfo",
-        description: "Get MongoDB server information including version, storage engine, and other details",
+        description: "Inspect MongoDB server metadata such as version and storage engine. Enable includeDebugInfo for additional diagnostics.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1456,7 +1708,7 @@ async function handleListToolsRequest({
       },
       {
         name: "insert",
-        description: "Insert one or more documents into a MongoDB collection",
+        description: "Insert new documents into a MongoDB collection. Use update to modify existing records.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1493,7 +1745,7 @@ async function handleListToolsRequest({
       },
       {
         name: "createIndex",
-        description: "Create one or more indexes on a MongoDB collection",
+        description: "Create indexes to improve query performance, enforce uniqueness, or expire documents with a TTL index.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1544,8 +1796,8 @@ async function handleListToolsRequest({
               description: "Write concern for index creation"
             },
             commitQuorum: {
-              type: "string",
-              description: "Number of members required to create the index"
+              type: ["string", "number"],
+              description: "Replica-set commit quorum as a member count or a mode such as majority"
             },
             objectIdMode: {
               type: "string",
@@ -1559,7 +1811,7 @@ async function handleListToolsRequest({
       },
       {
         name: "count",
-        description: "Count documents in a collection matching a query",
+        description: "Count documents matching a filter in one collection. Use aggregate for counts grouped by field.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1589,7 +1841,7 @@ async function handleListToolsRequest({
       },
       {
         name: "listCollections",
-        description: "List all collections in the MongoDB database",
+        description: "List collections in the connected database. Filter by name or other collection properties and request names only for a compact result.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1635,6 +1887,39 @@ async function handleListToolsRequest({
       }
     ]
   };
+  const { tools } = result;
+  if (connectionSelection) {
+    const connectionId = {
+      type: "string",
+      description: "Configured connection ID. Defaults to default."
+    };
+    const database = {
+      type: "string",
+      description: "Allowed database name. Defaults to the database in the connection URI."
+    };
+    for (const tool of tools) {
+      if (tool.name !== "convertTime") {
+        tool.inputSchema.properties = {
+          ...tool.inputSchema.properties,
+          connectionId,
+          database
+        };
+      }
+    }
+    tools.push(
+      {
+        name: "listConnections",
+        description: "List configured connection IDs, default databases, and read-only policies.",
+        inputSchema: { type: "object", properties: {} }
+      },
+      {
+        name: "listDatabases",
+        description: "List existing authorized databases on a configured connection.",
+        inputSchema: { type: "object", properties: { connectionId } }
+      }
+    );
+  }
+  return result;
 }
 
 // src/server.ts
@@ -1645,12 +1930,13 @@ function createSendProgress(progressToken, notify) {
     params: { progressToken, progress, total, message }
   });
 }
-function createServer(client, db, isReadOnlyMode = false, allowCrossDb = false, allowServerJs = false, options = {}) {
+function createServer(client, db, isReadOnlyMode = false, allowCrossDb = false, allowServerJs = false, options = {}, connections2) {
+  const defaultTarget = { client, db, isReadOnlyMode };
   const server = new Server(
     {
       name: "mongodb",
       title: "MongoDB MCP Server",
-      version: "3.0.1",
+      version: "3.1.0",
       description: "MCP server for MongoDB: query, aggregate, and manage collections with read-only mode, progress notifications, and cancellation",
       websiteUrl: "https://github.com/kiliczsh/mcp-mongo-server",
       ...options
@@ -1675,23 +1961,27 @@ function createServer(client, db, isReadOnlyMode = false, allowCrossDb = false,
       signal: ctx.mcpReq.signal
     })
   );
-  server.setRequestHandler(
-    "resources/list",
-    (request, ctx) => handleListResourcesRequest({
+  server.setRequestHandler("resources/list", (request, ctx) => {
+    if (connections2?.named) {
+      return listNamedResources(
+        connections2,
+        request.params?.cursor,
+        ctx.mcpReq.signal
+      );
+    }
+    return handleListResourcesRequest({
       request,
       client,
       db,
       isReadOnlyMode,
       signal: ctx.mcpReq.signal
-    })
-  );
+    });
+  });
   server.setRequestHandler(
     "resources/read",
-    (request, ctx) => handleReadResourceRequest({
+    async (request, ctx) => handleReadResourceRequest({
       request,
-      client,
-      db,
-      isReadOnlyMode,
+      ...connections2 ? await connections2.resolve(resourceSelectors(request.params.uri)) : defaultTarget,
       signal: ctx.mcpReq.signal,
       sendProgress: createSendProgress(
         request.params._meta?.progressToken,
@@ -1706,6 +1996,7 @@ function createServer(client, db, isReadOnlyMode = false, allowCrossDb = false,
       client,
       db,
       isReadOnlyMode,
+      connectionSelection: !!connections2,
       signal: ctx.mcpReq.signal
     })
   );
@@ -1718,6 +2009,7 @@ function createServer(client, db, isReadOnlyMode = false, allowCrossDb = false,
       isReadOnlyMode,
       allowCrossDb,
       allowServerJs,
+      connections: connections2,
       signal: ctx.mcpReq.signal
     })
   );
@@ -1728,16 +2020,16 @@ function createServer(client, db, isReadOnlyMode = false, allowCrossDb = false,
       client,
       db,
       isReadOnlyMode,
+      connectionSelection: !!connections2,
       signal: ctx.mcpReq.signal
     })
   );
   server.setRequestHandler(
     "prompts/get",
-    (request, ctx) => handleGetPromptRequest({
+    async (request, ctx) => handleGetPromptRequest({
       request,
-      client,
-      db,
-      isReadOnlyMode,
+      ...connections2 ? await connections2.resolve(request.params.arguments) : defaultTarget,
+      showTarget: !!connections2?.named,
       signal: ctx.mcpReq.signal,
       sendProgress: createSendProgress(
         request.params._meta?.progressToken,
@@ -1745,31 +2037,94 @@ function createServer(client, db, isReadOnlyMode = false, allowCrossDb = false,
       )
     })
   );
-  server.setRequestHandler(
-    "resources/templates/list",
-    (request, ctx) => handleListResourceTemplatesRequest({
+  server.setRequestHandler("resources/templates/list", async (request, ctx) => {
+    const result = await handleListResourceTemplatesRequest({
       request,
       client,
       db,
       isReadOnlyMode,
       signal: ctx.mcpReq.signal
-    })
-  );
-  server.setRequestHandler(
-    "completion/complete",
-    (request, ctx) => handleCompletionRequest({
+    });
+    if (connections2?.named) {
+      result.resourceTemplates.push({
+        ...result.resourceTemplates[0],
+        name: "mongodb_connection_collection",
+        uriTemplate: "mongodb:///{collection}{?connectionId,database}"
+      });
+    }
+    return result;
+  });
+  server.setRequestHandler("completion/complete", async (request, ctx) => {
+    const { ref, argument, context } = request.params;
+    const selectors = {
+      ...context?.arguments,
+      ...ref.type === "ref/resource" ? resourceSelectors(ref.uri) : {}
+    };
+    if (connections2 && (argument.name === "connectionId" || argument.name === "database")) {
+      const candidates = argument.name === "connectionId" ? connections2.list().map(({ connectionId }) => connectionId) : await connections2.listDatabases(selectors.connectionId);
+      const matches = candidates.filter(
+        (value) => value.startsWith(argument.value)
+      );
+      return {
+        completion: {
+          values: matches.slice(0, 100),
+          total: matches.length,
+          hasMore: matches.length > 100
+        }
+      };
+    }
+    return handleCompletionRequest({
       request,
-      client,
-      db,
-      isReadOnlyMode,
+      ...connections2 ? await connections2.resolve(selectors) : defaultTarget,
       signal: ctx.mcpReq.signal
-    })
-  );
+    });
+  });
   return server;
 }
+async function listNamedResources(connections2, cursor, signal) {
+  const prefix = `${connections2.cursorScope}.`;
+  const offsetCursor = cursor?.slice(prefix.length);
+  const offset = decodeCursor(offsetCursor);
+  if (cursor !== void 0 && (!cursor.startsWith(prefix) || !Number.isSafeInteger(offset) || encodeCursor(offset) !== offsetCursor)) {
+    throw new ProtocolError4(
+      ProtocolErrorCode4.InvalidParams,
+      "Invalid resource cursor for the current connection configuration"
+    );
+  }
+  const resources = [];
+  for (const { connectionId, defaultDatabase } of connections2.list()) {
+    try {
+      signal?.throwIfAborted();
+      for (const database of await connections2.listDatabases(connectionId)) {
+        const { db } = await connections2.resolve({ connectionId, database });
+        const collections = await db.listCollections({}, { nameOnly: true }).toArray();
+        for (const name of collections.map(({ name: name2 }) => name2).sort()) {
+          if (name.startsWith("system.")) continue;
+          const query = connectionId === "default" && database === defaultDatabase ? "" : `?${new URLSearchParams({ connectionId, database })}`;
+          resources.push({
+            uri: `mongodb:///${encodeURIComponent(name)}${query}`,
+            name,
+            mimeType: "application/json",
+            description: `MongoDB collection: ${connectionId}/${database}/${name}`
+          });
+        }
+      }
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      throw new Error(
+        `Failed to list resources for MongoDB connection '${connectionId}'`
+      );
+    }
+  }
+  const { items, nextCursor } = paginate(resources, offsetCursor);
+  return {
+    resources: items,
+    ...nextCursor ? { nextCursor: prefix + nextCursor } : {}
+  };
+}
 
 // src/index.ts
-var mongoClient = null;
+var connections;
 async function main() {
   const args = process.argv.slice(2);
   let connectionUrl = "";
@@ -1818,34 +2173,13 @@ async function main() {
   if (!connectionUrl) {
     connectionUrl = process.env.MCP_MONGODB_URI || "";
   }
-  if (!connectionUrl) {
-    console.error(
-      "Please provide a MongoDB connection URL via command-line argument or MCP_MONGODB_URI environment variable"
-    );
-    console.error(
-      "Usage: command <mongodb-url> [--read-only|-r] [--transport stdio|http] [--port 3001]"
-    );
-    console.error(
-      "   or: MCP_MONGODB_URI=<mongodb-url> [MCP_MONGODB_READONLY=true] command"
-    );
-    process.exit(1);
-  }
-  if (!connectionUrl.startsWith("mongodb://") && !connectionUrl.startsWith("mongodb+srv://")) {
-    console.error(
-      "Invalid MongoDB connection URL. URL must start with 'mongodb://' or 'mongodb+srv://'"
-    );
-    process.exit(1);
-  }
   try {
-    const { client, db, isConnected, isReadOnlyMode } = await connectToMongoDB(
+    connections = new Connections(
       connectionUrl,
+      process.env.MCP_MONGODB_CONNECTIONS,
       readOnlyMode
     );
-    mongoClient = client;
-    if (!isConnected || !client || !db) {
-      console.error("Failed to connect to MongoDB");
-      process.exit(1);
-    }
+    const { client, db, isReadOnlyMode } = await connections.resolve();
     if (transportMode === "http") {
       await startHttpServer(
         client,
@@ -1853,6 +2187,7 @@ async function main() {
         isReadOnlyMode,
         allowCrossDb,
         allowServerJs,
+        connections,
         port,
         allowedOrigins,
         jsonLimit,
@@ -1864,20 +2199,27 @@ async function main() {
         db,
         isReadOnlyMode,
         allowCrossDb,
-        allowServerJs
+        allowServerJs,
+        connections
       );
     }
   } catch (error) {
     console.error("Failed to connect to MongoDB:", error);
-    if (mongoClient) {
-      await mongoClient.close();
-    }
+    await connections?.close();
     process.exit(1);
   }
 }
-async function startStdioServer(client, db, isReadOnlyMode, allowCrossDb, allowServerJs) {
+async function startStdioServer(client, db, isReadOnlyMode, allowCrossDb, allowServerJs, connections2) {
   serveStdio(
-    () => createServer(client, db, isReadOnlyMode, allowCrossDb, allowServerJs)
+    () => createServer(
+      client,
+      db,
+      isReadOnlyMode,
+      allowCrossDb,
+      allowServerJs,
+      {},
+      connections2
+    )
   );
   console.warn("Server connected successfully via stdio");
 }
@@ -1904,7 +2246,7 @@ function bearerTokenValid(authorization, expected) {
   const wanted = Buffer.from(expected);
   return provided.length === wanted.length && timingSafeEqual(provided, wanted);
 }
-async function startHttpServer(client, db, isReadOnlyMode, allowCrossDb, allowServerJs, port, allowedOrigins, jsonLimit, authToken) {
+async function startHttpServer(client, db, isReadOnlyMode, allowCrossDb, allowServerJs, connections2, port, allowedOrigins, jsonLimit, authToken) {
   const app = createMcpExpressApp({ host: "0.0.0.0", jsonLimit });
   app.use((req, res, next) => {
     const start = Date.now();
@@ -1955,7 +2297,15 @@ async function startHttpServer(client, db, isReadOnlyMode, allowCrossDb, allowSe
     });
   }
   const mcpHandler = createMcpHandler(
-    (_ctx) => createServer(client, db, isReadOnlyMode, allowCrossDb, allowServerJs)
+    (_ctx) => createServer(
+      client,
+      db,
+      isReadOnlyMode,
+      allowCrossDb,
+      allowServerJs,
+      {},
+      connections2
+    )
   );
   const nodeHandler = toNodeHandler(mcpHandler, {
     onerror: (error) => console.error("Error handling MCP request:", error)
@@ -1982,15 +2332,11 @@ async function startHttpServer(client, db, isReadOnlyMode, allowCrossDb, allowSe
   });
 }
 process.on("SIGINT", async () => {
-  if (mongoClient) {
-    await mongoClient.close();
-  }
+  await connections?.close();
   process.exit(0);
 });
 process.on("SIGTERM", async () => {
-  if (mongoClient) {
-    await mongoClient.close();
-  }
+  await connections?.close();
   process.exit(0);
 });
 main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-mongo-server",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "A Model Context Protocol server for MongoDB connections",
   "private": false,
   "type": "module",
@@ -21,6 +21,8 @@
     "format": "biome format --write .",
     "format:check": "biome format .",
     "lint": "biome lint .",
+    "test:connections": "bun test tests/connections.lifecycle.test.ts && node --test tests/connections.e2e.test.mjs",
+    "test:connections:legacy": "MCP_TEST_PROTOCOL=legacy node --test tests/connections.e2e.test.mjs",
     "lint:fix": "biome lint --write .",
     "check": "biome check --write .",
     "inspector": "mcp-inspector --config inspector-config.json --server mongodb"
@@ -35,6 +37,7 @@
     "@biomejs/biome": "^2.5.5",
     "@modelcontextprotocol/client": "^2.0.0",
     "@modelcontextprotocol/inspector": "^1.0.0",
+    "@types/express": "5",
     "@types/node": "^26.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"