feat(elicitation): add user consent configuration through elicitation MCP-185

Adds an option to require confirmation for certain tools using the new elicitation API. This is not supported by most client yet, only notably VSCode.

Clients which support it will see a confirmation option with a summary before the action is run. If the client doesn't support elicitation, the action will simply be auto-approved.

This option can be confirmed with `confirmationRequiredTools` and has a default set of `drop-database`, `drop-collection`, `delete-many`, `atlas-create-db-user`, `atlas-create-access-list` enabled.

In VSCode one must first click "Respond" (which sets action to "accepted") and then choose a value. I decided to let there be an explcit choice of Yes / No in JSON schema instead of opting to just rely on "Respond" as it is not immediately clear that `Respond = Yes` and I imagine this vagueness in the API spec will lead to confusion across clients so it's best to have an explicit JSON schema value for confirmation.

I also went with enum string Yes / No and not boolean since the displayed value for this is more user friendly.

Author: gagik

README.md

@@ -331,6 +331,7 @@ The MongoDB MCP Server can be configured using multiple methods, with the follow
 | `loggers`                 | `MDB_MCP_LOGGERS`                    | disk,mcp   | Comma separated values, possible values are `mcp`, `disk` and `stderr`. See [Logger Options](#logger-options) for details.                                    |
 | `logPath`                 | `MDB_MCP_LOG_PATH`                   | see note\* | Folder to store logs.                                                                                                                                         |
 | `disabledTools`           | `MDB_MCP_DISABLED_TOOLS`             | <not set>  | An array of tool names, operation types, and/or categories of tools that will be disabled.                                                                    |
+| `confirmationRequiredTools` | `MDB_MCP_CONFIRMATION_REQUIRED_TOOLS` | create-access-list,create-db-user,drop-database,drop-collection,delete-many  | An array of tool names that require user confirmation before execution. **Requires the client to support [elicitation](https://modelcontextprotocol.io/specification/draft/client/elicitation)**.                                                                                      |
 | `readOnly`                | `MDB_MCP_READ_ONLY`                  | false      | When set to true, only allows read, connect, and metadata operation types, disabling create/update/delete operations.                                         |
 | `indexCheck`              | `MDB_MCP_INDEX_CHECK`                | false      | When set to true, enforces that query operations must use an index, rejecting queries that perform a collection scan.                                         |
 | `telemetry`               | `MDB_MCP_TELEMETRY`                  | enabled    | When set to disabled, disables telemetry collection.                                                                                                          |
@@ -400,6 +401,14 @@ Operation types:
 - `metadata` - Tools that read metadata, such as list databases, list collections, collection schema, etc.
 - `connect` - Tools that allow you to connect or switch the connection to a MongoDB instance. If this is disabled, you will need to provide a connection string through the config when starting the server.
 
+#### Require Confirmation
+
+If your client supports [elicitation](https://modelcontextprotocol.io/specification/draft/client/elicitation), you can set the MongoDB MCP server to request user confirmation before executing certain tools.
+
+When a tool is marked as requiring confirmation, the server will send an elicitation request to the client. The client with elicitation support will then prompt the user for confirmation and send the response back to the server. If the client does not support elicitation, the tool will execute without confirmation.
+
+You can set the `confirmationRequiredTools` configuration option to specify the names of tools which require confirmation. By default, the following tools have this setting enabled: `drop-database`, `drop-collection`, `delete-many`, `atlas-create-db-user`, `atlas-create-access-list`.
+
 #### Read-Only Mode
 
 The `readOnly` configuration option allows you to restrict the MCP server to only use tools with "read", "connect", and "metadata" operation types. When enabled, all tools that have "create", "update" or "delete" operation types will not be registered with the server.

src/common/config.ts

@@ -151,7 +151,9 @@ export interface UserConfig extends CliOptions {
     exportTimeoutMs: number;
     exportCleanupIntervalMs: number;
     connectionString?: string;
+    // TODO: Use a type tracking all tool names.
     disabledTools: Array<string>;
+    confirmationRequiredTools: Array<string>;
     readOnly?: boolean;
     indexCheck?: boolean;
     transport: "stdio" | "http";
@@ -173,6 +175,13 @@ export const defaultUserConfig: UserConfig = {
     telemetry: "enabled",
     readOnly: false,
     indexCheck: false,
+    confirmationRequiredTools: [
+        "atlas-create-access-list",
+        "atlas-create-db-user",
+        "drop-database",
+        "drop-collection",
+        "delete-many",
+    ],
     transport: "stdio",
     httpPort: 3000,
     httpHost: "127.0.0.1",
@@ -431,6 +440,7 @@ export function setupUserConfig({
 
     userConfig.disabledTools = commaSeparatedToArray(userConfig.disabledTools);
     userConfig.loggers = commaSeparatedToArray(userConfig.loggers);
+    userConfig.confirmationRequiredTools = commaSeparatedToArray(userConfig.confirmationRequiredTools);
 
     if (userConfig.connectionString && userConfig.connectionSpecifier) {
         const connectionInfo = generateConnectionInfoFromCliArgs(userConfig);

src/elicitation.ts

@@ -0,0 +1,59 @@
+import type { PrimitiveSchemaDefinition } from "@modelcontextprotocol/sdk/types.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export class Elicitation {
+    private readonly server: McpServer["server"];
+    constructor({ server }: { server: McpServer["server"] }) {
+        this.server = server;
+    }
+
+    /**
+     * Checks if the client supports elicitation capabilities.
+     * @returns True if the client supports elicitation, false otherwise.
+     */
+    public supportsElicitation(): boolean {
+        const clientCapabilities = this.server.getClientCapabilities();
+        return clientCapabilities?.elicitation !== undefined;
+    }
+
+    /**
+     * Requests a boolean confirmation from the user.
+     * @param message - The message to display to the user.
+     * @returns True if the user confirms the action or the client does not support elicitation, false otherwise.
+     */
+    public async requestConfirmation(message: string): Promise<boolean> {
+        if (!this.supportsElicitation()) {
+            return true;
+        }
+
+        const result = await this.server.elicitInput({
+            message,
+            requestedSchema: Elicitation.CONFIRMATION_SCHEMA,
+        });
+        return result.action === "accept" && result.content?.confirmation === "Yes";
+    }
+
+    /**
+     * The schema for the confirmation question.
+     * TODO: In the future would be good to use Zod 4's toJSONSchema() to generate the schema.
+     */
+    public static CONFIRMATION_SCHEMA: MCPElicitationSchema = {
+        type: "object",
+        properties: {
+            confirmation: {
+                type: "string",
+                title: "Would you like to confirm?",
+                description: "Would you like to confirm?",
+                enum: ["Yes", "No"],
+                enumNames: ["Yes, I confirm", "No, I do not confirm"],
+            },
+        },
+        required: ["confirmation"],
+    };
+}
+
+export type MCPElicitationSchema = {
+    type: "object";
+    properties: Record<string, PrimitiveSchemaDefinition>;
+    required?: string[];
+};

src/server.ts

@@ -22,12 +22,14 @@ import type { ToolBase } from "./tools/tool.js";
 import { validateConnectionString } from "./helpers/connectionOptions.js";
 import { packageInfo } from "./common/packageInfo.js";
 import { type ConnectionErrorHandler } from "./common/connectionErrorHandler.js";
+import type { Elicitation } from "./elicitation.js";
 
 export interface ServerOptions {
     session: Session;
     userConfig: UserConfig;
     mcpServer: McpServer;
     telemetry: Telemetry;
+    elicitation: Elicitation;
     connectionErrorHandler: ConnectionErrorHandler;
 }
 
@@ -36,6 +38,7 @@ export class Server {
     public readonly mcpServer: McpServer;
     private readonly telemetry: Telemetry;
     public readonly userConfig: UserConfig;
+    public readonly elicitation: Elicitation;
     public readonly tools: ToolBase[] = [];
     public readonly connectionErrorHandler: ConnectionErrorHandler;
 
@@ -48,12 +51,13 @@ export class Server {
     private readonly startTime: number;
     private readonly subscriptions = new Set<string>();
 
-    constructor({ session, mcpServer, userConfig, telemetry, connectionErrorHandler }: ServerOptions) {
+    constructor({ session, mcpServer, userConfig, telemetry, connectionErrorHandler, elicitation }: ServerOptions) {
         this.startTime = Date.now();
         this.session = session;
         this.telemetry = telemetry;
         this.mcpServer = mcpServer;
         this.userConfig = userConfig;
+        this.elicitation = elicitation;
         this.connectionErrorHandler = connectionErrorHandler;
     }
 
@@ -184,6 +188,7 @@ export class Server {
             event.properties.startup_time_ms = commandDuration;
             event.properties.read_only_mode = this.userConfig.readOnly || false;
             event.properties.disabled_tools = this.userConfig.disabledTools || [];
+            event.properties.confirmation_required_tools = this.userConfig.confirmationRequiredTools || [];
         }
         if (command === "stop") {
             event.properties.runtime_duration_ms = Date.now() - this.startTime;
@@ -193,12 +198,17 @@ export class Server {
             }
         }
 
-        this.telemetry.emitEvents([event]);
+        void this.telemetry.emitEvents([event]);
     }
 
     private registerTools(): void {
         for (const toolConstructor of [...AtlasTools, ...MongoDbTools]) {
-            const tool = new toolConstructor(this.session, this.userConfig, this.telemetry);
+            const tool = new toolConstructor({
+                session: this.session,
+                config: this.userConfig,
+                telemetry: this.telemetry,
+                elicitation: this.elicitation,
+            });
             if (tool.register(this)) {
                 this.tools.push(tool);
             }

src/telemetry/types.ts

@@ -45,6 +45,7 @@ export type ServerEventProperties = {
     runtime_duration_ms?: number;
     read_only_mode?: boolean;
     disabled_tools?: string[];
+    confirmation_required_tools?: string[];
 };
 
 export type ServerEvent = TelemetryEvent<ServerEventProperties>;

src/tools/atlas/create/createAccessList.ts

@@ -75,4 +75,31 @@ export class CreateAccessListTool extends AtlasToolBase {
             ],
         };
     }
+
+    protected getConfirmationMessage({
+        projectId,
+        ipAddresses,
+        cidrBlocks,
+        comment,
+        currentIpAddress,
+    }: ToolArgs<typeof this.argsShape>): string {
+        const accessDescription = [];
+        if (ipAddresses?.length) {
+            accessDescription.push(`- **IP addresses**: ${ipAddresses.join(", ")}`);
+        }
+        if (cidrBlocks?.length) {
+            accessDescription.push(`- **CIDR blocks**: ${cidrBlocks.join(", ")}`);
+        }
+        if (currentIpAddress) {
+            accessDescription.push("- **Current IP address**");
+        }
+
+        return (
+            `You are about to add the following entries to the access list for Atlas project "${projectId}":\n\n` +
+            accessDescription.join("\n") +
+            `\n\n**Comment**: ${comment || DEFAULT_ACCESS_LIST_COMMENT}\n\n` +
+            "This will allow network access to your MongoDB Atlas clusters from these IP addresses/ranges. " +
+            "Do you want to proceed?"
+        );
+    }
 }

src/tools/atlas/create/createDBUser.ts

@@ -92,4 +92,22 @@ export class CreateDBUserTool extends AtlasToolBase {
             ],
         };
     }
+
+    protected getConfirmationMessage({
+        projectId,
+        username,
+        password,
+        roles,
+        clusters,
+    }: ToolArgs<typeof this.argsShape>): string {
+        return (
+            `You are about to create a database user in Atlas project \`${projectId}\`:\n\n` +
+            `**Username**: \`${username}\`\n\n` +
+            `**Password**: ${password ? "(User-provided password)" : "(Auto-generated secure password)"}\n\n` +
+            `**Roles**: ${roles.map((role) => `${role.roleName}${role.collectionName ? ` on ${role.databaseName}.${role.collectionName}` : ` on ${role.databaseName}`}`).join(", ")}\n\n` +
+            `**Cluster Access**: ${clusters?.length ? clusters.join(", ") : "All clusters in the project"}\n\n` +
+            "This will create a new database user with the specified permissions. " +
+            "**Do you confirm the execution of the action?**"
+        );
+    }
 }

src/tools/mongodb/connect/connect.ts

@@ -1,11 +1,8 @@
 import { z } from "zod";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { MongoDBToolBase } from "../mongodbTool.js";
-import type { ToolArgs, OperationType } from "../../tool.js";
+import type { ToolArgs, OperationType, ToolConstructorParams } from "../../tool.js";
 import assert from "assert";
-import type { UserConfig } from "../../../common/config.js";
-import type { Telemetry } from "../../../telemetry/telemetry.js";
-import type { Session } from "../../../common/session.js";
 import type { Server } from "../../../server.js";
 
 const disconnectedSchema = z
@@ -44,8 +41,8 @@ export class ConnectTool extends MongoDBToolBase {
 
     public operationType: OperationType = "connect";
 
-    constructor(session: Session, config: UserConfig, telemetry: Telemetry) {
-        super(session, config, telemetry);
+    constructor({ session, config, telemetry, elicitation }: ToolConstructorParams) {
+        super({ session, config, telemetry, elicitation });
         session.on("connect", () => {
             this.updateMetadata();
         });

src/tools/mongodb/delete/deleteMany.ts

@@ -3,6 +3,7 @@ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
 import type { ToolArgs, OperationType } from "../../tool.js";
 import { checkIndexUsage } from "../../../helpers/indexCheck.js";
+import { EJSON } from "bson";
 
 export class DeleteManyTool extends MongoDBToolBase {
     public name = "delete-many";
@@ -55,4 +56,17 @@ export class DeleteManyTool extends MongoDBToolBase {
             ],
         };
     }
+
+    protected getConfirmationMessage({ database, collection, filter }: ToolArgs<typeof this.argsShape>): string {
+        const filterDescription =
+            filter && Object.keys(filter).length > 0 ? EJSON.stringify(filter) : "All documents (No filter)";
+        return (
+            `You are about to delete documents from the \`${collection}\` collection in the \`${database}\` database:\n\n` +
+            "```json\n" +
+            `{ "filter": ${filterDescription} }\n` +
+            "```\n\n" +
+            "This operation will permanently remove all documents matching the filter.\n\n" +
+            "**Do you confirm the execution of the action?**"
+        );
+    }
 }

src/tools/mongodb/delete/dropCollection.ts

@@ -24,4 +24,12 @@ export class DropCollectionTool extends MongoDBToolBase {
             ],
         };
     }
+
+    protected getConfirmationMessage({ database, collection }: ToolArgs<typeof this.argsShape>): string {
+        return (
+            `You are about to drop the \`${collection}\` collection from the \`${database}\` database:\n\n` +
+            "This operation will permanently remove the collection and all its data, including indexes.\n\n" +
+            "**Do you confirm the execution of the action?**"
+        );
+    }
 }