✂️ refactor: MCP UI Separation for Agents (#9237)

* refactor: MCP UI Separation for Agents (Dustin WIP)

feat: separate MCPs into their own lists away from tools + actions and add the status indicator functionality from chat to their dropdown ui

fix: spotify mcp was not persisting on agent creation

feat: show disconnected saved servers and their tools in agent mcp list in created agents

fix: select-all regression fixed (caused by deleting tools we were drawing from for rendering list)

fix: dont show all mcps, only those installed in agent in list

feat: separate ToolSelectDialog for MCPServerTools

fix: uninitialized mcp servers not showing as added in toolselectdialog

refactor: reduce looping in AgentPanelContext for categorizing groups and mcps

refactor: split ToolSelectDialog and MCPToolSelectDialog functionality (still needs customization for custom user vars)

chore: address ESLint comments

chore: address ESLint comments

feat: one-click initialization on MCP servers in agent builder

fix: stop propagation triggering reinit on caret click

refactor: split uninitialized MCPs component from initialized MCPs

feat: new mcp tool select dialog ui with custom user vars

feat: show initialization state for CUV configurable MCPs too

chore: remove unused localization string

fix: deselecting all tools caused a re-render

fix: remove subtools so removal from MCPToolSelectDialog works more consistently

feat: added servers have all tools enabled by default

feat: mcp server list now alphabetical to prevent annoying ui behavior of servers jumping around depending on tool selection

fix: filter out placeholder group mcp tools from any actual tool calls / definitions

feat: indicator now takes you to config dialog for uninitialized servers

feat: show previously configured mcp servers that are now missing from the yaml

feat: select all enabled by default on first add to mcp server list

chore: address ESLint comments

* refactor: MCP UI Separation for Agents (Danny WIP)

chore: remove use of `{serverName}_mcp_{serverName}`

chore: import order

WIP: separate component concerns

refactor: streamline agent mcp tools

refactor: unify MCP server handling and improve tool visibility logic, remove unnecessary normalization or sorting, remove nesting button, make variable names clear

refactor: rename mcpServerIds to mcpServerNames for clarity and consistency across components

refactor: remove groupedMCPTools and toolToServerMap, streamline MCP server handling in context and components to effectively utilize mcpServersMap

refactor: optimize tool selection logic by replacing array includes with Set for improved performance

chore: add error logging for failed auth URL parsing in ToolCall component

refactor: enhance MCP tool handling by improving server name management and updating UI elements for better clarity

* refactor: decouple connection status from useMCPServerManager with useMCPConnectionStatus

* fix: improve MCP tool validation logic to handle unconfigured servers

* chore: enhance log message clarity for MCP server disconnection in updateUserPluginsController

* refactor: simplify connection status extraction in useMCPConnectionStatus hook

* refactor: improve initializing UX

* chore: replace string literal with ResourceType constant in useResourcePermissions

* refactor: cleanup code, remove redundancies, rename variables for clarity

* chore: add back filtering and sorting for mcp tools dialog

* refactor: initializeServer to return response and early return

* refactor: enhance server initialization logic and improve UI for OAuth interaction

* chore: clarify warning message for unconfigured MCP server in handleTools

* refactor: prevent CustomUserVarsSection from submitting tools dialog form

* fix: nested button of button issue in UninitializedMCPTool

* feat: add functionality to revoke custom user variables in MCPToolSelectDialog

---------

Co-authored-by: Danny Avila <danny@librechat.ai>

client/src/hooks/MCP/index.ts

@@ -1,3 +1,5 @@
-export * from './useMCPSelect';
 export * from './useGetMCPTools';
+export * from './useMCPConnectionStatus';
+export * from './useMCPSelect';
+export * from './useVisibleTools';
 export { useMCPServerManager } from './useMCPServerManager';

client/src/hooks/MCP/useMCPConnectionStatus.ts

@@ -0,0 +1,11 @@
+import { useMCPConnectionStatusQuery } from '~/data-provider/Tools/queries';
+
+export function useMCPConnectionStatus({ enabled }: { enabled?: boolean } = {}) {
+  const { data } = useMCPConnectionStatusQuery({
+    enabled,
+  });
+
+  return {
+    connectionStatus: data?.connectionStatus,
+  };
+}

client/src/hooks/MCP/useMCPServerManager.ts

@@ -9,8 +9,7 @@ import {
 } from 'librechat-data-provider/react-query';
 import type { TUpdateUserPlugins, TPlugin } from 'librechat-data-provider';
 import type { ConfigFieldDetail } from '~/common';
-import { useMCPConnectionStatusQuery } from '~/data-provider/Tools/queries';
-import { useLocalize, useMCPSelect, useGetMCPTools } from '~/hooks';
+import { useLocalize, useMCPSelect, useGetMCPTools, useMCPConnectionStatus } from '~/hooks';
 import { useGetStartupConfig } from '~/data-provider';
 
 interface ServerState {
@@ -21,7 +20,7 @@ interface ServerState {
   pollInterval: NodeJS.Timeout | null;
 }
 
-export function useMCPServerManager({ conversationId }: { conversationId?: string | null }) {
+export function useMCPServerManager({ conversationId }: { conversationId?: string | null } = {}) {
   const localize = useLocalize();
   const queryClient = useQueryClient();
   const { showToast } = useToastContext();
@@ -83,13 +82,9 @@ export function useMCPServerManager({ conversationId }: { conversationId?: strin
     return initialStates;
   });
 
-  const { data: connectionStatusData } = useMCPConnectionStatusQuery({
+  const { connectionStatus } = useMCPConnectionStatus({
     enabled: !!startupConfig?.mcpServers && Object.keys(startupConfig.mcpServers).length > 0,
   });
-  const connectionStatus = useMemo(
-    () => connectionStatusData?.connectionStatus || {},
-    [connectionStatusData?.connectionStatus],
-  );
 
   /** Filter disconnected servers when values change, but only after initial load
    This prevents clearing selections on page refresh when servers haven't connected yet
@@ -97,7 +92,7 @@ export function useMCPServerManager({ conversationId }: { conversationId?: strin
   const hasInitialLoadCompleted = useRef(false);
 
   useEffect(() => {
-    if (!connectionStatusData || Object.keys(connectionStatus).length === 0) {
+    if (!connectionStatus || Object.keys(connectionStatus).length === 0) {
       return;
     }
 
@@ -115,7 +110,7 @@ export function useMCPServerManager({ conversationId }: { conversationId?: strin
     if (connectedSelected.length !== mcpValues.length) {
       setMCPValues(connectedSelected);
     }
-  }, [connectionStatus, connectionStatusData, mcpValues, setMCPValues]);
+  }, [connectionStatus, mcpValues, setMCPValues]);
 
   const updateServerState = useCallback((serverName: string, updates: Partial<ServerState>) => {
     setServerStates((prev) => {
@@ -229,46 +224,46 @@ export function useMCPServerManager({ conversationId }: { conversationId?: strin
   const initializeServer = useCallback(
     async (serverName: string, autoOpenOAuth: boolean = true) => {
       updateServerState(serverName, { isInitializing: true });
-
       try {
         const response = await reinitializeMutation.mutateAsync(serverName);
-
-        if (response.success) {
-          if (response.oauthRequired && response.oauthUrl) {
-            updateServerState(serverName, {
-              oauthUrl: response.oauthUrl,
-              oauthStartTime: Date.now(),
-              isCancellable: true,
-              isInitializing: true,
-            });
-
-            if (autoOpenOAuth) {
-              window.open(response.oauthUrl, '_blank', 'noopener,noreferrer');
-            }
-
-            startServerPolling(serverName);
-          } else {
-            await queryClient.refetchQueries([QueryKeys.mcpConnectionStatus]);
-
-            showToast({
-              message: localize('com_ui_mcp_initialized_success', { 0: serverName }),
-              status: 'success',
-            });
-
-            const currentValues = mcpValues ?? [];
-            if (!currentValues.includes(serverName)) {
-              setMCPValues([...currentValues, serverName]);
-            }
-
-            cleanupServerState(serverName);
-          }
-        } else {
+        if (!response.success) {
           showToast({
             message: localize('com_ui_mcp_init_failed', { 0: serverName }),
             status: 'error',
           });
           cleanupServerState(serverName);
+          return response;
         }
+
+        if (response.oauthRequired && response.oauthUrl) {
+          updateServerState(serverName, {
+            oauthUrl: response.oauthUrl,
+            oauthStartTime: Date.now(),
+            isCancellable: true,
+            isInitializing: true,
+          });
+
+          if (autoOpenOAuth) {
+            window.open(response.oauthUrl, '_blank', 'noopener,noreferrer');
+          }
+
+          startServerPolling(serverName);
+        } else {
+          await queryClient.invalidateQueries([QueryKeys.mcpConnectionStatus]);
+
+          showToast({
+            message: localize('com_ui_mcp_initialized_success', { 0: serverName }),
+            status: 'success',
+          });
+
+          const currentValues = mcpValues ?? [];
+          if (!currentValues.includes(serverName)) {
+            setMCPValues([...currentValues, serverName]);
+          }
+
+          cleanupServerState(serverName);
+        }
+        return response;
       } catch (error) {
         console.error(`[MCP Manager] Failed to initialize ${serverName}:`, error);
         showToast({
@@ -351,7 +346,7 @@ export function useMCPServerManager({ conversationId }: { conversationId?: strin
           return;
         }
 
-        const serverStatus = connectionStatus[serverName];
+        const serverStatus = connectionStatus?.[serverName];
         if (serverStatus?.connectionState === 'connected') {
           connectedServers.push(serverName);
         } else {
@@ -381,7 +376,7 @@ export function useMCPServerManager({ conversationId }: { conversationId?: strin
         const filteredValues = currentValues.filter((name) => name !== serverName);
         setMCPValues(filteredValues);
       } else {
-        const serverStatus = connectionStatus[serverName];
+        const serverStatus = connectionStatus?.[serverName];
         if (serverStatus?.connectionState === 'connected') {
           setMCPValues([...currentValues, serverName]);
         } else {
@@ -455,7 +450,7 @@ export function useMCPServerManager({ conversationId }: { conversationId?: strin
   const getServerStatusIconProps = useCallback(
     (serverName: string) => {
       const tool = mcpToolDetails?.find((t) => t.name === serverName);
-      const serverStatus = connectionStatus[serverName];
+      const serverStatus = connectionStatus?.[serverName];
       const serverConfig = startupConfig?.mcpServers?.[serverName];
 
       const handleConfigClick = (e: React.MouseEvent) => {
@@ -532,7 +527,7 @@ export function useMCPServerManager({ conversationId }: { conversationId?: strin
 
     return {
       serverName: selectedToolForConfig.name,
-      serverStatus: connectionStatus[selectedToolForConfig.name],
+      serverStatus: connectionStatus?.[selectedToolForConfig.name],
       isOpen: isConfigModalOpen,
       onOpenChange: handleDialogOpenChange,
       fieldsSchema,
@@ -553,7 +548,6 @@ export function useMCPServerManager({ conversationId }: { conversationId?: strin
 
   return {
     configuredServers,
-    connectionStatus,
     initializeServer,
     cancelOAuthFlow,
     isInitializing,

client/src/hooks/MCP/useVisibleTools.ts

@@ -0,0 +1,79 @@
+import { useMemo } from 'react';
+import { Constants } from 'librechat-data-provider';
+import type { AgentToolType } from 'librechat-data-provider';
+import type { MCPServerInfo } from '~/common';
+
+type GroupedToolType = AgentToolType & { tools?: AgentToolType[] };
+type GroupedToolsRecord = Record<string, GroupedToolType>;
+
+interface VisibleToolsResult {
+  toolIds: string[];
+  mcpServerNames: string[];
+}
+
+/**
+ * Custom hook to calculate visible tool IDs based on selected tools and their parent groups.
+ * If any subtool of a group is selected, the parent group tool is also made visible.
+ *
+ * @param selectedToolIds - Array of selected tool IDs
+ * @param allTools - Record of all available tools
+ * @param mcpServersMap - Map of all MCP servers
+ * @returns Object containing separate arrays of visible tool IDs for regular and MCP tools
+ */
+export function useVisibleTools(
+  selectedToolIds: string[] | undefined,
+  allTools: GroupedToolsRecord | undefined,
+  mcpServersMap: Map<string, MCPServerInfo>,
+): VisibleToolsResult {
+  return useMemo(() => {
+    const mcpServers = new Set<string>();
+    const selectedSet = new Set<string>();
+    const regularToolIds = new Set<string>();
+
+    for (const toolId of selectedToolIds ?? []) {
+      if (!toolId.includes(Constants.mcp_delimiter)) {
+        selectedSet.add(toolId);
+        continue;
+      }
+      const serverName = toolId.split(Constants.mcp_delimiter)[1];
+      if (!serverName) {
+        continue;
+      }
+      mcpServers.add(serverName);
+    }
+
+    if (allTools) {
+      for (const [toolId, toolObj] of Object.entries(allTools)) {
+        if (selectedSet.has(toolId)) {
+          regularToolIds.add(toolId);
+        }
+
+        if (toolObj.tools?.length) {
+          for (const subtool of toolObj.tools) {
+            if (selectedSet.has(subtool.tool_id)) {
+              regularToolIds.add(toolId);
+              break;
+            }
+          }
+        }
+      }
+    }
+
+    if (mcpServersMap) {
+      for (const [mcpServerName] of mcpServersMap) {
+        if (mcpServers.has(mcpServerName)) {
+          continue;
+        }
+        /** Legacy check */
+        if (selectedSet.has(mcpServerName)) {
+          mcpServers.add(mcpServerName);
+        }
+      }
+    }
+
+    return {
+      toolIds: Array.from(regularToolIds).sort((a, b) => a.localeCompare(b)),
+      mcpServerNames: Array.from(mcpServers).sort((a, b) => a.localeCompare(b)),
+    };
+  }, [allTools, mcpServersMap, selectedToolIds]);
+}