🗝️ feat: User Provided Credentials for MCP Servers (#7980)

* 🗝️ feat: Per-User Credentials for MCP Servers

chore: add aider to gitignore

feat: fill custom variables to MCP server

feat: replace placeholders with custom user MCP variables

feat: handle MCP install/uninstall (uses pluginauths)

feat: add MCP custom variables dialog to MCPSelect

feat: add MCP custom variables dialog to the side panel

feat: do not require to fill MCP credentials for in tools dialog

feat: add translations keys (en+cs) for custom MCP variables

fix: handle LIBRECHAT_USER_ID correctly during MCP var replacement

style: remove unused MCP translation keys

style: fix eslint for MCP custom vars

chore: move aider gitignore to AI section

* feat: Add Plugin Authentication Methods to data-schemas

* refactor: Replace PluginAuth model methods with new utility functions for improved code organization and maintainability

* refactor: Move IPluginAuth interface to types directory for better organization and update pluginAuth schema to use the new import

* refactor: Remove unused getUsersPluginsAuthValuesMap function and streamline PluginService.js; add new getPluginAuthMap function for improved plugin authentication handling

* chore: fix typing for optional tools property with GenericTool[] type

* chore: update librechat-data-provider version to 0.7.88

* refactor: optimize getUserMCPAuthMap function by reducing variable usage and improving server key collection logic

* refactor: streamline MCP tool creation by removing customUserVars parameter and enhancing user-specific authentication handling to avoid closure encapsulation

* refactor: extract processSingleValue function to streamline MCP environment variable processing and enhance readability

* refactor: enhance MCP tool processing logic by simplifying conditions and improving authentication handling for custom user variables

* ci: fix action tests

* chore: fix imports, remove comments

* chore: remove non-english translations

* fix: remove newline at end of translation.json file

---------

Co-authored-by: Aleš Kůtek <kutekales@gmail.com>

api/server/controllers/PluginController.js

@@ -5,6 +5,7 @@ const { getToolkitKey } = require('~/server/services/ToolService');
 const { getMCPManager, getFlowStateManager } = require('~/config');
 const { availableTools } = require('~/app/clients/tools');
 const { getLogStores } = require('~/cache');
+const { Constants } = require('librechat-data-provider');
 
 /**
  * Filters out duplicate plugins from the list of plugins.
@@ -173,16 +174,56 @@ const getAvailableTools = async (req, res) => {
     });
 
     const toolDefinitions = await getCachedTools({ includeGlobal: true });
-    const tools = authenticatedPlugins.filter(
-      (plugin) =>
-        toolDefinitions[plugin.pluginKey] !== undefined ||
-        (plugin.toolkit === true &&
-          Object.keys(toolDefinitions).some((key) => getToolkitKey(key) === plugin.pluginKey)),
-    );
 
-    await cache.set(CacheKeys.TOOLS, tools);
-    res.status(200).json(tools);
+    const toolsOutput = [];
+    for (const plugin of authenticatedPlugins) {
+      const isToolDefined = toolDefinitions[plugin.pluginKey] !== undefined;
+      const isToolkit =
+        plugin.toolkit === true &&
+        Object.keys(toolDefinitions).some((key) => getToolkitKey(key) === plugin.pluginKey);
+
+      if (!isToolDefined && !isToolkit) {
+        continue;
+      }
+
+      const toolToAdd = { ...plugin };
+
+      if (!plugin.pluginKey.includes(Constants.mcp_delimiter)) {
+        toolsOutput.push(toolToAdd);
+        continue;
+      }
+
+      const parts = plugin.pluginKey.split(Constants.mcp_delimiter);
+      const serverName = parts[parts.length - 1];
+      const serverConfig = customConfig?.mcpServers?.[serverName];
+
+      if (!serverConfig?.customUserVars) {
+        toolsOutput.push(toolToAdd);
+        continue;
+      }
+
+      const customVarKeys = Object.keys(serverConfig.customUserVars);
+
+      if (customVarKeys.length === 0) {
+        toolToAdd.authConfig = [];
+        toolToAdd.authenticated = true;
+      } else {
+        toolToAdd.authConfig = Object.entries(serverConfig.customUserVars).map(([key, value]) => ({
+          authField: key,
+          label: value.title || key,
+          description: value.description || '',
+        }));
+        toolToAdd.authenticated = false;
+      }
+
+      toolsOutput.push(toolToAdd);
+    }
+
+    const finalTools = filterUniquePlugins(toolsOutput);
+    await cache.set(CacheKeys.TOOLS, finalTools);
+    res.status(200).json(finalTools);
   } catch (error) {
+    logger.error('[getAvailableTools]', error);
     res.status(500).json({ message: error.message });
   }
 };

api/server/controllers/UserController.js

@@ -1,5 +1,6 @@
 const {
   Tools,
+  Constants,
   FileSources,
   webSearchKeys,
   extractWebSearchEnvVars,
@@ -23,6 +24,7 @@ const { processDeleteRequest } = require('~/server/services/Files/process');
 const { Transaction, Balance, User } = require('~/db/models');
 const { deleteToolCalls } = require('~/models/ToolCall');
 const { deleteAllSharedLinks } = require('~/models');
+const { getMCPManager } = require('~/config');
 
 const getUserController = async (req, res) => {
   /** @type {MongoUser} */
@@ -102,10 +104,22 @@ const updateUserPluginsController = async (req, res) => {
     }
 
     let keys = Object.keys(auth);
-    if (keys.length === 0 && pluginKey !== Tools.web_search) {
+    const values = Object.values(auth); // Used in 'install' block
+
+    const isMCPTool = pluginKey.startsWith('mcp_') || pluginKey.includes(Constants.mcp_delimiter);
+
+    // Early exit condition:
+    // If keys are empty (meaning auth: {} was likely sent for uninstall, or auth was empty for install)
+    // AND it's not web_search (which has special key handling to populate `keys` for uninstall)
+    // AND it's NOT (an uninstall action FOR an MCP tool - we need to proceed for this case to clear all its auth)
+    // THEN return.
+    if (
+      keys.length === 0 &&
+      pluginKey !== Tools.web_search &&
+      !(action === 'uninstall' && isMCPTool)
+    ) {
       return res.status(200).send();
     }
-    const values = Object.values(auth);
 
     /** @type {number} */
     let status = 200;
@@ -132,16 +146,53 @@ const updateUserPluginsController = async (req, res) => {
         }
       }
     } else if (action === 'uninstall') {
-      for (let i = 0; i < keys.length; i++) {
-        authService = await deleteUserPluginAuth(user.id, keys[i]);
+      // const isMCPTool was defined earlier
+      if (isMCPTool && keys.length === 0) {
+        // This handles the case where auth: {} is sent for an MCP tool uninstall.
+        // It means "delete all credentials associated with this MCP pluginKey".
+        authService = await deleteUserPluginAuth(user.id, null, true, pluginKey);
         if (authService instanceof Error) {
-          logger.error('[authService]', authService);
+          logger.error(
+            `[authService] Error deleting all auth for MCP tool ${pluginKey}:`,
+            authService,
+          );
           ({ status, message } = authService);
         }
+      } else {
+        // This handles:
+        // 1. Web_search uninstall (keys will be populated with all webSearchKeys if auth was {}).
+        // 2. Other tools uninstall (if keys were provided).
+        // 3. MCP tool uninstall if specific keys were provided in `auth` (not current frontend behavior).
+        // If keys is empty for non-MCP tools (and not web_search), this loop won't run, and nothing is deleted.
+        for (let i = 0; i < keys.length; i++) {
+          authService = await deleteUserPluginAuth(user.id, keys[i]); // Deletes by authField name
+          if (authService instanceof Error) {
+            logger.error('[authService] Error deleting specific auth key:', authService);
+            ({ status, message } = authService);
+          }
+        }
       }
     }
 
     if (status === 200) {
+      // If auth was updated successfully, disconnect MCP sessions as they might use these credentials
+      if (pluginKey.startsWith(Constants.mcp_prefix)) {
+        try {
+          const mcpManager = getMCPManager(user.id);
+          if (mcpManager) {
+            logger.info(
+              `[updateUserPluginsController] Disconnecting MCP connections for user ${user.id} after plugin auth update for ${pluginKey}.`,
+            );
+            await mcpManager.disconnectUserConnections(user.id);
+          }
+        } catch (disconnectError) {
+          logger.error(
+            `[updateUserPluginsController] Error disconnecting MCP connections for user ${user.id} after plugin auth update:`,
+            disconnectError,
+          );
+          // Do not fail the request for this, but log it.
+        }
+      }
       return res.status(status).send();
     }
 

api/server/controllers/agents/client.js

@@ -31,11 +31,15 @@ const {
 } = require('librechat-data-provider');
 const { DynamicStructuredTool } = require('@langchain/core/tools');
 const { getBufferString, HumanMessage } = require('@langchain/core/messages');
-const { getCustomEndpointConfig, checkCapability } = require('~/server/services/Config');
+const {
+  getCustomEndpointConfig,
+  createGetMCPAuthMap,
+  checkCapability,
+} = require('~/server/services/Config');
 const { addCacheControl, createContextHandlers } = require('~/app/clients/prompts');
 const { initializeAgent } = require('~/server/services/Endpoints/agents/agent');
 const { spendTokens, spendStructuredTokens } = require('~/models/spendTokens');
-const { setMemory, deleteMemory, getFormattedMemories } = require('~/models');
+const { getFormattedMemories, deleteMemory, setMemory } = require('~/models');
 const { encodeAndFormat } = require('~/server/services/Files/images/encode');
 const initOpenAI = require('~/server/services/Endpoints/openAI/initialize');
 const { checkAccess } = require('~/server/middleware/roles/access');
@@ -679,6 +683,8 @@ class AgentClient extends BaseClient {
         version: 'v2',
       };
 
+      const getUserMCPAuthMap = await createGetMCPAuthMap();
+
       const toolSet = new Set((this.options.agent.tools ?? []).map((tool) => tool && tool.name));
       let { messages: initialMessages, indexTokenCountMap } = formatAgentMessages(
         payload,
@@ -798,6 +804,20 @@ class AgentClient extends BaseClient {
           run.Graph.contentData = contentData;
         }
 
+        try {
+          if (getUserMCPAuthMap) {
+            config.configurable.userMCPAuthMap = await getUserMCPAuthMap({
+              tools: agent.tools,
+              userId: this.options.req.user.id,
+            });
+          }
+        } catch (err) {
+          logger.error(
+            `[api/server/controllers/agents/client.js #chatCompletion] Error getting custom user vars for agent ${agent.id}`,
+            err,
+          );
+        }
+
         await run.processStream({ messages }, config, {
           keepContent: i !== 0,
           tokenCounter: createTokenCounter(this.getEncoding()),

api/server/routes/config.js

@@ -1,10 +1,11 @@
 const express = require('express');
+const { logger } = require('@librechat/data-schemas');
 const { CacheKeys, defaultSocialLogins, Constants } = require('librechat-data-provider');
+const { getCustomConfig } = require('~/server/services/Config/getCustomConfig');
 const { getLdapConfig } = require('~/server/services/Config/ldap');
 const { getProjectByName } = require('~/models/Project');
 const { isEnabled } = require('~/server/utils');
 const { getLogStores } = require('~/cache');
-const { logger } = require('~/config');
 
 const router = express.Router();
 const emailLoginEnabled =
@@ -21,12 +22,15 @@ const publicSharedLinksEnabled =
 
 router.get('/', async function (req, res) {
   const cache = getLogStores(CacheKeys.CONFIG_STORE);
+
   const cachedStartupConfig = await cache.get(CacheKeys.STARTUP_CONFIG);
   if (cachedStartupConfig) {
     res.send(cachedStartupConfig);
     return;
   }
 
+  const config = await getCustomConfig();
+
   const isBirthday = () => {
     const today = new Date();
     return today.getMonth() === 1 && today.getDate() === 11;
@@ -96,6 +100,17 @@ router.get('/', async function (req, res) {
       bundlerURL: process.env.SANDPACK_BUNDLER_URL,
       staticBundlerURL: process.env.SANDPACK_STATIC_BUNDLER_URL,
     };
+
+    payload.mcpServers = {};
+    if (config.mcpServers) {
+      for (const serverName in config.mcpServers) {
+        const serverConfig = config.mcpServers[serverName];
+        payload.mcpServers[serverName] = {
+          customUserVars: serverConfig?.customUserVars || {},
+        };
+      }
+    }
+
     /** @type {TCustomConfig['webSearch']} */
     const webSearchConfig = req.app.locals.webSearch;
     if (

api/server/services/Config/getCustomConfig.js

@@ -1,6 +1,10 @@
+const { logger } = require('@librechat/data-schemas');
+const { getUserMCPAuthMap } = require('@librechat/api');
 const { CacheKeys, EModelEndpoint } = require('librechat-data-provider');
 const { normalizeEndpointName, isEnabled } = require('~/server/utils');
 const loadCustomConfig = require('./loadCustomConfig');
+const { getCachedTools } = require('./getCachedTools');
+const { findPluginAuthsByKeys } = require('~/models');
 const getLogStores = require('~/cache/getLogStores');
 
 /**
@@ -50,4 +54,46 @@ const getCustomEndpointConfig = async (endpoint) => {
   );
 };
 
-module.exports = { getCustomConfig, getBalanceConfig, getCustomEndpointConfig };
+async function createGetMCPAuthMap() {
+  const customConfig = await getCustomConfig();
+  const mcpServers = customConfig?.mcpServers;
+  const hasCustomUserVars = Object.values(mcpServers).some((server) => server.customUserVars);
+  if (!hasCustomUserVars) {
+    return;
+  }
+
+  /**
+   * @param {Object} params
+   * @param {GenericTool[]} [params.tools]
+   * @param {string} params.userId
+   * @returns {Promise<Record<string, Record<string, string>> | undefined>}
+   */
+  return async function ({ tools, userId }) {
+    try {
+      if (!tools || tools.length === 0) {
+        return;
+      }
+      const appTools = await getCachedTools({
+        userId,
+      });
+      return await getUserMCPAuthMap({
+        tools,
+        userId,
+        appTools,
+        findPluginAuthsByKeys,
+      });
+    } catch (err) {
+      logger.error(
+        `[api/server/controllers/agents/client.js #chatCompletion] Error getting custom user vars for agent`,
+        err,
+      );
+    }
+  };
+}
+
+module.exports = {
+  getCustomConfig,
+  getBalanceConfig,
+  createGetMCPAuthMap,
+  getCustomEndpointConfig,
+};

api/server/services/MCP.js

@@ -168,6 +168,9 @@ async function createMCPTool({ req, res, toolKey, provider: _provider }) {
         derivedSignal.addEventListener('abort', abortHandler, { once: true });
       }
 
+      const customUserVars =
+        config?.configurable?.userMCPAuthMap?.[`${Constants.mcp_prefix}${serverName}`];
+
       const result = await mcpManager.callTool({
         serverName,
         toolName,
@@ -175,8 +178,9 @@ async function createMCPTool({ req, res, toolKey, provider: _provider }) {
         toolArguments,
         options: {
           signal: derivedSignal,
-          user: config?.configurable?.user,
         },
+        user: config?.configurable?.user,
+        customUserVars,
         flowManager,
         tokenMethods: {
           findToken,

api/server/services/PluginService.js

@@ -1,6 +1,6 @@
 const { logger } = require('@librechat/data-schemas');
 const { encrypt, decrypt } = require('@librechat/api');
-const { PluginAuth } = require('~/db/models');
+const { findOnePluginAuth, updatePluginAuth, deletePluginAuth } = require('~/models');
 
 /**
  * Asynchronously retrieves and decrypts the authentication value for a user's plugin, based on a specified authentication field.
@@ -25,7 +25,7 @@ const { PluginAuth } = require('~/db/models');
  */
 const getUserPluginAuthValue = async (userId, authField, throwError = true) => {
   try {
-    const pluginAuth = await PluginAuth.findOne({ userId, authField }).lean();
+    const pluginAuth = await findOnePluginAuth({ userId, authField });
     if (!pluginAuth) {
       throw new Error(`No plugin auth ${authField} found for user ${userId}`);
     }
@@ -79,23 +79,12 @@ const getUserPluginAuthValue = async (userId, authField, throwError = true) => {
 const updateUserPluginAuth = async (userId, authField, pluginKey, value) => {
   try {
     const encryptedValue = await encrypt(value);
-    const pluginAuth = await PluginAuth.findOne({ userId, authField }).lean();
-    if (pluginAuth) {
-      return await PluginAuth.findOneAndUpdate(
-        { userId, authField },
-        { $set: { value: encryptedValue } },
-        { new: true, upsert: true },
-      ).lean();
-    } else {
-      const newPluginAuth = await new PluginAuth({
-        userId,
-        authField,
-        value: encryptedValue,
-        pluginKey,
-      });
-      await newPluginAuth.save();
-      return newPluginAuth.toObject();
-    }
+    return await updatePluginAuth({
+      userId,
+      authField,
+      pluginKey,
+      value: encryptedValue,
+    });
   } catch (err) {
     logger.error('[updateUserPluginAuth]', err);
     return err;
@@ -105,26 +94,25 @@ const updateUserPluginAuth = async (userId, authField, pluginKey, value) => {
 /**
  * @async
  * @param {string} userId
- * @param {string} authField
- * @param {boolean} [all]
+ * @param {string | null} authField - The specific authField to delete, or null if `all` is true.
+ * @param {boolean} [all=false] - Whether to delete all auths for the user (or for a specific pluginKey if provided).
+ * @param {string} [pluginKey] - Optional. If `all` is true and `pluginKey` is provided, delete all auths for this user and pluginKey.
  * @returns {Promise<import('mongoose').DeleteResult>}
  * @throws {Error}
  */
-const deleteUserPluginAuth = async (userId, authField, all = false) => {
-  if (all) {
-    try {
-      const response = await PluginAuth.deleteMany({ userId });
-      return response;
-    } catch (err) {
-      logger.error('[deleteUserPluginAuth]', err);
-      return err;
-    }
-  }
-
+const deleteUserPluginAuth = async (userId, authField, all = false, pluginKey) => {
   try {
-    return await PluginAuth.deleteOne({ userId, authField });
+    return await deletePluginAuth({
+      userId,
+      authField,
+      pluginKey,
+      all,
+    });
   } catch (err) {
-    logger.error('[deleteUserPluginAuth]', err);
+    logger.error(
+      `[deleteUserPluginAuth] Error deleting ${all ? 'all' : 'single'} auth(s) for userId: ${userId}${pluginKey ? ` and pluginKey: ${pluginKey}` : ''}`,
+      err,
+    );
     return err;
   }
 };