🗝️ 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>

packages/api/src/agents/auth.ts

@@ -0,0 +1,93 @@
+import { logger } from '@librechat/data-schemas';
+import type { IPluginAuth, PluginAuthMethods } from '@librechat/data-schemas';
+import { decrypt } from '../crypto/encryption';
+
+export interface GetPluginAuthMapParams {
+  userId: string;
+  pluginKeys: string[];
+  throwError?: boolean;
+  findPluginAuthsByKeys: PluginAuthMethods['findPluginAuthsByKeys'];
+}
+
+export type PluginAuthMap = Record<string, Record<string, string>>;
+
+/**
+ * Retrieves and decrypts authentication values for multiple plugins
+ * @returns A map where keys are pluginKeys and values are objects of authField:decryptedValue pairs
+ */
+export async function getPluginAuthMap({
+  userId,
+  pluginKeys,
+  throwError = true,
+  findPluginAuthsByKeys,
+}: GetPluginAuthMapParams): Promise<PluginAuthMap> {
+  try {
+    /** Early return for empty plugin keys */
+    if (!pluginKeys?.length) {
+      return {};
+    }
+
+    /** All plugin auths for current user query */
+    const pluginAuths = await findPluginAuthsByKeys({ userId, pluginKeys });
+
+    /** Group auth records by pluginKey for efficient lookup */
+    const authsByPlugin = new Map<string, IPluginAuth[]>();
+    for (const auth of pluginAuths) {
+      if (!auth.pluginKey) {
+        logger.warn(`[getPluginAuthMap] Missing pluginKey for userId ${userId}`);
+        continue;
+      }
+      const existing = authsByPlugin.get(auth.pluginKey) || [];
+      existing.push(auth);
+      authsByPlugin.set(auth.pluginKey, existing);
+    }
+
+    const authMap: PluginAuthMap = {};
+    const decryptionPromises: Promise<void>[] = [];
+
+    /** Single loop through requested pluginKeys */
+    for (const pluginKey of pluginKeys) {
+      authMap[pluginKey] = {};
+      const auths = authsByPlugin.get(pluginKey) || [];
+
+      for (const auth of auths) {
+        decryptionPromises.push(
+          (async () => {
+            try {
+              const decryptedValue = await decrypt(auth.value);
+              authMap[pluginKey][auth.authField] = decryptedValue;
+            } catch (error) {
+              const message = error instanceof Error ? error.message : 'Unknown error';
+              logger.error(
+                `[getPluginAuthMap] Decryption failed for userId ${userId}, plugin ${pluginKey}, field ${auth.authField}: ${message}`,
+              );
+
+              if (throwError) {
+                throw new Error(
+                  `Decryption failed for plugin ${pluginKey}, field ${auth.authField}: ${message}`,
+                );
+              }
+            }
+          })(),
+        );
+      }
+    }
+
+    await Promise.all(decryptionPromises);
+    return authMap;
+  } catch (error) {
+    if (!throwError) {
+      /** Empty objects for each plugin key on error */
+      return pluginKeys.reduce((acc, key) => {
+        acc[key] = {};
+        return acc;
+      }, {} as PluginAuthMap);
+    }
+
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    logger.error(
+      `[getPluginAuthMap] Failed to fetch auth values for userId ${userId}, plugins: ${pluginKeys.join(', ')}: ${message}`,
+    );
+    throw error;
+  }
+}

packages/api/src/agents/run.ts

@@ -1,6 +1,12 @@
 import { Run, Providers } from '@librechat/agents';
 import { providerEndpointMap, KnownEndpoints } from 'librechat-data-provider';
-import type { StandardGraphConfig, EventHandler, GraphEvents, IState } from '@librechat/agents';
+import type {
+  StandardGraphConfig,
+  EventHandler,
+  GenericTool,
+  GraphEvents,
+  IState,
+} from '@librechat/agents';
 import type { Agent } from 'librechat-data-provider';
 import type * as t from '~/types';
 
@@ -32,7 +38,7 @@ export async function createRun({
   streaming = true,
   streamUsage = true,
 }: {
-  agent: Agent;
+  agent: Omit<Agent, 'tools'> & { tools?: GenericTool[] };
   signal: AbortSignal;
   runId?: string;
   streaming?: boolean;

packages/api/src/index.ts

@@ -1,6 +1,7 @@
 /* MCP */
 export * from './mcp/manager';
 export * from './mcp/oauth';
+export * from './mcp/auth';
 /* Utilities */
 export * from './mcp/utils';
 export * from './utils';

packages/api/src/mcp/auth.ts

@@ -0,0 +1,58 @@
+import { logger } from '@librechat/data-schemas';
+import { Constants } from 'librechat-data-provider';
+import type { PluginAuthMethods } from '@librechat/data-schemas';
+import type { GenericTool } from '@librechat/agents';
+import { getPluginAuthMap } from '~/agents/auth';
+import { mcpToolPattern } from './utils';
+
+export async function getUserMCPAuthMap({
+  userId,
+  tools,
+  appTools,
+  findPluginAuthsByKeys,
+}: {
+  userId: string;
+  tools: GenericTool[] | undefined;
+  appTools: Record<string, unknown>;
+  findPluginAuthsByKeys: PluginAuthMethods['findPluginAuthsByKeys'];
+}) {
+  if (!tools || tools.length === 0) {
+    return {};
+  }
+
+  const uniqueMcpServers = new Set<string>();
+
+  for (const tool of tools) {
+    const toolKey = tool.name;
+    if (toolKey && appTools[toolKey] && mcpToolPattern.test(toolKey)) {
+      const parts = toolKey.split(Constants.mcp_delimiter);
+      const serverName = parts[parts.length - 1];
+      uniqueMcpServers.add(`${Constants.mcp_prefix}${serverName}`);
+    }
+  }
+
+  if (uniqueMcpServers.size === 0) {
+    return {};
+  }
+
+  const mcpPluginKeysToFetch = Array.from(uniqueMcpServers);
+
+  let allMcpCustomUserVars: Record<string, Record<string, string>> = {};
+  try {
+    allMcpCustomUserVars = await getPluginAuthMap({
+      userId,
+      pluginKeys: mcpPluginKeysToFetch,
+      throwError: false,
+      findPluginAuthsByKeys,
+    });
+  } catch (err) {
+    logger.error(
+      `[handleTools] Error batch fetching customUserVars for MCP tools (keys: ${mcpPluginKeysToFetch.join(
+        ', ',
+      )}), user ${userId}: ${err instanceof Error ? err.message : 'Unknown error'}`,
+      err,
+    );
+  }
+
+  return allMcpCustomUserVars;
+}

packages/api/src/mcp/manager.ts

@@ -14,10 +14,6 @@ import { MCPTokenStorage } from './oauth/tokens';
 import { formatToolContent } from './parsers';
 import { MCPConnection } from './connection';
 
-export interface CallToolOptions extends RequestOptions {
-  user?: TUser;
-}
-
 export class MCPManager {
   private static instance: MCPManager | null = null;
   /** App-level connections initialized at startup */
@@ -28,7 +24,11 @@ export class MCPManager {
   private userLastActivity: Map<string, number> = new Map();
   private readonly USER_CONNECTION_IDLE_TIMEOUT = 15 * 60 * 1000; // 15 minutes (TODO: make configurable)
   private mcpConfigs: t.MCPServers = {};
-  private processMCPEnv?: (obj: MCPOptions, user?: TUser) => MCPOptions; // Store the processing function
+  private processMCPEnv?: (
+    obj: MCPOptions,
+    user?: TUser,
+    customUserVars?: Record<string, string>,
+  ) => MCPOptions; // Store the processing function
   /** Store MCP server instructions */
   private serverInstructions: Map<string, string> = new Map();
 
@@ -63,7 +63,6 @@ export class MCPManager {
     if (!tokenMethods) {
       logger.info('[MCP] No token methods provided, token persistence will not be available');
     }
-
     const entries = Object.entries(mcpServers);
     const initializedServers = new Set();
     const connectionResults = await Promise.allSettled(
@@ -382,6 +381,7 @@ export class MCPManager {
     user,
     serverName,
     flowManager,
+    customUserVars,
     tokenMethods,
     oauthStart,
     oauthEnd,
@@ -390,6 +390,7 @@ export class MCPManager {
     user: TUser;
     serverName: string;
     flowManager: FlowStateManager<MCPOAuthTokens | null>;
+    customUserVars?: Record<string, string>;
     tokenMethods?: TokenMethods;
     oauthStart?: (authURL: string) => Promise<void>;
     oauthEnd?: () => Promise<void>;
@@ -444,9 +445,8 @@ export class MCPManager {
     }
 
     if (this.processMCPEnv) {
-      config = { ...(this.processMCPEnv(config, user) ?? {}) };
+      config = { ...(this.processMCPEnv(config, user, customUserVars) ?? {}) };
     }
-
     /** If no in-memory tokens, tokens from persistent storage */
     let tokens: MCPOAuthTokens | null = null;
     if (tokenMethods?.findToken) {
@@ -752,7 +752,6 @@ export class MCPManager {
     getServerTools?: (serverName: string) => Promise<t.LCManifestTool[] | undefined>;
   }): Promise<t.LCToolManifest> {
     const mcpTools: t.LCManifestTool[] = [];
-
     for (const [serverName, connection] of this.connections.entries()) {
       try {
         /** Attempt to ensure connection is active, with reconnection if needed */
@@ -784,13 +783,21 @@ export class MCPManager {
         const serverTools: t.LCManifestTool[] = [];
         for (const tool of tools) {
           const pluginKey = `${tool.name}${CONSTANTS.mcp_delimiter}${serverName}`;
+
+          const config = this.mcpConfigs[serverName];
           const manifestTool: t.LCManifestTool = {
             name: tool.name,
             pluginKey,
             description: tool.description ?? '',
             icon: connection.iconPath,
+            authConfig: config?.customUserVars
+              ? Object.entries(config.customUserVars).map(([key, value]) => ({
+                  authField: key,
+                  label: value.title || key,
+                  description: value.description || '',
+                }))
+              : undefined,
           };
-          const config = this.mcpConfigs[serverName];
           if (config?.chatMenu === false) {
             manifestTool.chatMenu = false;
           }
@@ -814,6 +821,7 @@ export class MCPManager {
    * for user-specific connections upon successful call initiation.
    */
   async callTool({
+    user,
     serverName,
     toolName,
     provider,
@@ -823,20 +831,22 @@ export class MCPManager {
     flowManager,
     oauthStart,
     oauthEnd,
+    customUserVars,
   }: {
+    user?: TUser;
     serverName: string;
     toolName: string;
     provider: t.Provider;
     toolArguments?: Record<string, unknown>;
-    options?: CallToolOptions;
+    options?: RequestOptions;
     tokenMethods?: TokenMethods;
+    customUserVars?: Record<string, string>;
     flowManager: FlowStateManager<MCPOAuthTokens | null>;
     oauthStart?: (authURL: string) => Promise<void>;
     oauthEnd?: () => Promise<void>;
   }): Promise<t.FormattedToolResponse> {
     /** User-specific connection */
     let connection: MCPConnection | undefined;
-    const { user, ...callOptions } = options ?? {};
     const userId = user?.id;
     const logPrefix = userId ? `[MCP][User: ${userId}][${serverName}]` : `[MCP][${serverName}]`;
 
@@ -852,6 +862,7 @@ export class MCPManager {
           oauthStart,
           oauthEnd,
           signal: options?.signal,
+          customUserVars,
         });
       } else {
         /** App-level connection */
@@ -883,7 +894,7 @@ export class MCPManager {
         CallToolResultSchema,
         {
           timeout: connection.timeout,
-          ...callOptions,
+          ...options,
         },
       );
       if (userId) {

packages/api/src/mcp/types/index.ts

@@ -14,7 +14,15 @@ export type StdioOptions = z.infer<typeof StdioOptionsSchema>;
 export type WebSocketOptions = z.infer<typeof WebSocketOptionsSchema>;
 export type SSEOptions = z.infer<typeof SSEOptionsSchema>;
 export type StreamableHTTPOptions = z.infer<typeof StreamableHTTPOptionsSchema>;
-export type MCPOptions = z.infer<typeof MCPOptionsSchema>;
+export type MCPOptions = z.infer<typeof MCPOptionsSchema> & {
+  customUserVars?: Record<
+    string,
+    {
+      title: string;
+      description: string;
+    }
+  >;
+};
 export type MCPServers = z.infer<typeof MCPServersSchema>;
 export interface MCPResource {
   uri: string;

packages/api/src/mcp/utils.ts

@@ -1,3 +1,6 @@
+import { Constants } from 'librechat-data-provider';
+
+export const mcpToolPattern = new RegExp(`^.+${Constants.mcp_delimiter}.+$`);
 /**
  * Normalizes a server name to match the pattern ^[a-zA-Z0-9_.-]+$
  * This is required for Azure OpenAI models with Tool Calling