🧵 feat: Background Tool Calls for Agents & Model Specs

api/server/controllers/agents/openai.js

@@ -335,6 +335,7 @@ const OpenAIChatCompletionController = async (req, res) => {
           ephemeralSkillsToggle,
         }),
         codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+        backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
         statefulSessionsAvailable: enabledCapabilities.has(
           AgentCapabilities.stateful_code_sessions,
         ),
@@ -415,6 +416,7 @@ const OpenAIChatCompletionController = async (req, res) => {
           defaultActiveOnShare,
           /** @see DiscoverConnectedAgentsParams.codeEnvAvailable */
           codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+          backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
           statefulSessionsAvailable: enabledCapabilities.has(
             AgentCapabilities.stateful_code_sessions,
           ),
@@ -500,6 +502,7 @@ const OpenAIChatCompletionController = async (req, res) => {
           agent: ctx.agent ?? agent,
           signal: abortController.signal,
           toolRegistry: ctx.toolRegistry,
+          backgroundToolNames: ctx.backgroundToolNames,
           mcpAvailableTools: ctx.mcpAvailableTools,
           requestScopedConnections: ctx.requestScopedConnections,
           userMCPAuthMap: ctx.userMCPAuthMap,

api/server/controllers/agents/responses.js

@@ -459,6 +459,7 @@ const createResponse = async (req, res) => {
           ephemeralSkillsToggle,
         }),
         codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+        backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
         statefulSessionsAvailable: enabledCapabilities.has(
           AgentCapabilities.stateful_code_sessions,
         ),
@@ -539,6 +540,7 @@ const createResponse = async (req, res) => {
           defaultActiveOnShare,
           /** @see DiscoverConnectedAgentsParams.codeEnvAvailable */
           codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
+          backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background),
           statefulSessionsAvailable: enabledCapabilities.has(
             AgentCapabilities.stateful_code_sessions,
           ),
@@ -720,6 +722,7 @@ const createResponse = async (req, res) => {
             agent: ctx.agent ?? agent,
             signal: abortController.signal,
             toolRegistry: ctx.toolRegistry,
+            backgroundToolNames: ctx.backgroundToolNames,
             mcpAvailableTools: ctx.mcpAvailableTools,
             requestScopedConnections: ctx.requestScopedConnections,
             userMCPAuthMap: ctx.userMCPAuthMap,
@@ -900,6 +903,7 @@ const createResponse = async (req, res) => {
             agent: ctx.agent ?? agent,
             signal: abortController.signal,
             toolRegistry: ctx.toolRegistry,
+            backgroundToolNames: ctx.backgroundToolNames,
             mcpAvailableTools: ctx.mcpAvailableTools,
             requestScopedConnections: ctx.requestScopedConnections,
             userMCPAuthMap: ctx.userMCPAuthMap,

api/server/services/Endpoints/agents/addedConvo.js

@@ -81,6 +81,7 @@ const processAddedConvo = async ({
   skillStates,
   defaultActiveOnShare,
   codeEnvAvailable,
+  backgroundToolsAvailable,
   statefulSessionsAvailable,
   memoryAvailable,
 }) => {
@@ -177,6 +178,7 @@ const processAddedConvo = async ({
           ephemeralSkillsToggle,
         }),
         codeEnvAvailable,
+        backgroundToolsAvailable,
         statefulSessionsAvailable,
         memoryAvailable,
         skillStates,

api/server/services/Endpoints/agents/initialize.js

@@ -149,6 +149,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
   const enabledCapabilities = new Set(appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities);
   const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills);
   const codeEnvAvailable = enabledCapabilities.has(AgentCapabilities.execute_code);
+  const backgroundToolsAvailable = enabledCapabilities.has(AgentCapabilities.run_in_background);
   const statefulSessionsAvailable = enabledCapabilities.has(
     AgentCapabilities.stateful_code_sessions,
   );
@@ -230,6 +231,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
         toolNames,
         agent: ctx.agent,
         toolRegistry: ctx.toolRegistry,
+        backgroundToolNames: ctx.backgroundToolNames,
         mcpAvailableTools: ctx.mcpAvailableTools,
         requestScopedConnections: ctx.requestScopedConnections,
         userMCPAuthMap: ctx.userMCPAuthMap,
@@ -408,6 +410,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
       accessibleSkillIds: primaryScopedSkillIds,
       skillAuthoringAvailable: primarySkillAuthoringAvailable,
       codeEnvAvailable,
+      backgroundToolsAvailable,
       statefulSessionsAvailable,
       memoryAvailable,
       skillStates,
@@ -485,6 +488,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
       skillStates,
       defaultActiveOnShare,
       codeEnvAvailable,
+      backgroundToolsAvailable,
       statefulSessionsAvailable,
       memoryAvailable,
     },
@@ -558,6 +562,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
     skillStates,
     defaultActiveOnShare,
     codeEnvAvailable,
+    backgroundToolsAvailable,
     statefulSessionsAvailable,
     memoryAvailable,
   });
@@ -698,6 +703,11 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
            *  false`, so `bash_tool` / `read_file` sandbox fallback are
            *  silently gated off even though the seed walk found it. */
           codeEnvAvailable,
+          /* Background tool calls are intentionally NOT enabled for pure
+           * subagents (spawn-tool child graphs): their tools don't reach the
+           * host ON_TOOL_EXECUTE background interceptor, so injecting the
+           * schema would advertise a poll tool the host can't honor. Backgrounding
+           * subagent work is the durable follow-up. */
           statefulSessionsAvailable,
           memoryAvailable,
           skillStates,

api/server/services/Endpoints/agents/skillDeps.js

@@ -278,6 +278,7 @@ function buildAgentToolContext({ agent, config }) {
      *  the producing agent's config in multi-endpoint graphs. */
     endpointTokenConfig: config.endpointTokenConfig,
     toolRegistry: config.toolRegistry,
+    backgroundToolNames: config.backgroundToolNames,
     mcpAvailableTools: config.mcpAvailableTools,
     requestScopedConnections: config.requestScopedConnections,
     userMCPAuthMap: config.userMCPAuthMap,

api/server/services/MCP.js

@@ -887,6 +887,14 @@ function createToolInstance({
   });
   toolInstance.mcp = true;
   toolInstance.mcpRawServerName = serverName;
+  // Ephemeral request-scoped servers (runtime body placeholders) tear their
+  // connection down at request end, so they must never be backgrounded. A
+  // missing/stale config means the server's lifetime is unknowable, so fail
+  // closed (foreground) rather than risk a detached call against a torn-down
+  // connection.
+  toolInstance.mcpRequiresEphemeralConnection = capturedServerConfig
+    ? requiresEphemeralUserConnection(capturedServerConfig)
+    : true;
   // On Google/Vertex, propagate the union-flattened schema so definitions extracted
   // from this instance don't reach the Gemini converter with unsupported unions.
   toolInstance.mcpJsonSchema = isGoogle ? schema : parameters;

api/server/services/ToolService.js

@@ -1450,6 +1450,7 @@ async function loadToolsForExecution({
   agent,
   toolNames,
   toolRegistry,
+  backgroundToolNames,
   mcpAvailableTools,
   requestScopedConnections,
   userMCPAuthMap,
@@ -1461,6 +1462,12 @@ async function loadToolsForExecution({
   const allLoadedTools = [];
   const mcpRequestScopedConnections = requestScopedConnections ?? getMCPRequestContext(req, res);
   const configurable = { userMCPAuthMap, requestScopedConnections: mcpRequestScopedConnections };
+  /** Per-agent set of tools that received the injected `run_in_background`
+   *  param; the event-driven executor gates background dispatch and the
+   *  `check_background_task` poll tool on this reliable per-agent channel. */
+  if (backgroundToolNames?.length) {
+    configurable.backgroundToolNames = backgroundToolNames;
+  }
 
   const isToolSearch = toolNames.includes(AgentConstants.TOOL_SEARCH);
   const ptcToolNames = [

client/src/components/SidePanel/Agents/MCPToolItem.tsx

@@ -1,7 +1,7 @@
 import { useState } from 'react';
-import { TooltipAnchor } from '@librechat/client';
-import { Check, Clock, Code2, Info } from 'lucide-react';
+import { Check, Clock, Code2, Info, Zap } from 'lucide-react';
 import type { AgentToolType } from 'librechat-data-provider';
+import OptionToggle from './OptionToggle';
 import { useLocalize } from '~/hooks';
 import { cn } from '~/utils';
 
@@ -10,11 +10,14 @@ interface MCPToolItemProps {
   isSelected: boolean;
   isDeferred: boolean;
   isProgrammatic: boolean;
+  isBackground: boolean;
   deferredToolsEnabled: boolean;
   programmaticToolsEnabled: boolean;
+  backgroundToolsEnabled: boolean;
   onToggleSelect: () => void;
   onToggleDefer: () => void;
   onToggleProgrammatic: () => void;
+  onToggleBackground: () => void;
 }
 
 const iconButton =
@@ -28,8 +31,11 @@ export default function MCPToolItem({
   onToggleSelect,
   isProgrammatic,
   onToggleProgrammatic,
+  isBackground,
+  onToggleBackground,
   deferredToolsEnabled,
   programmaticToolsEnabled,
+  backgroundToolsEnabled,
 }: MCPToolItemProps) {
   const localize = useLocalize();
   const [expanded, setExpanded] = useState(false);
@@ -65,45 +71,33 @@ export default function MCPToolItem({
         </button>
         <div className="flex shrink-0 items-center gap-0.5">
           {deferredToolsEnabled && (
-            <TooltipAnchor
-              description={localize('com_ui_mcp_click_to_defer')}
-              side="top"
-              render={
-                <button
-                  type="button"
-                  onClick={onToggleDefer}
-                  aria-pressed={isDeferred}
-                  aria-label={localize('com_ui_mcp_defer_loading')}
-                  className={cn(
-                    iconButton,
-                    isDeferred ? 'text-amber-500' : 'text-text-secondary hover:text-text-primary',
-                  )}
-                >
-                  <Clock className="size-4" aria-hidden="true" />
-                </button>
-              }
+            <OptionToggle
+              icon={Clock}
+              pressed={isDeferred}
+              label={localize('com_ui_mcp_defer_loading')}
+              tooltip={localize('com_ui_mcp_click_to_defer')}
+              activeClass="text-amber-500"
+              onToggle={onToggleDefer}
             />
           )}
           {programmaticToolsEnabled && (
-            <TooltipAnchor
-              description={localize('com_ui_mcp_click_to_programmatic')}
-              side="top"
-              render={
-                <button
-                  type="button"
-                  onClick={onToggleProgrammatic}
-                  aria-pressed={isProgrammatic}
-                  aria-label={localize('com_ui_mcp_programmatic')}
-                  className={cn(
-                    iconButton,
-                    isProgrammatic
-                      ? 'text-violet-500'
-                      : 'text-text-secondary hover:text-text-primary',
-                  )}
-                >
-                  <Code2 className="size-4" aria-hidden="true" />
-                </button>
-              }
+            <OptionToggle
+              icon={Code2}
+              pressed={isProgrammatic}
+              label={localize('com_ui_mcp_programmatic')}
+              tooltip={localize('com_ui_mcp_click_to_programmatic')}
+              activeClass="text-violet-500"
+              onToggle={onToggleProgrammatic}
+            />
+          )}
+          {backgroundToolsEnabled && (
+            <OptionToggle
+              icon={Zap}
+              pressed={isBackground}
+              label={localize('com_ui_mcp_background')}
+              tooltip={localize('com_ui_mcp_click_to_background')}
+              activeClass="text-sky-500"
+              onToggle={onToggleBackground}
             />
           )}
           <button

client/src/components/SidePanel/Agents/OptionToggle.tsx

@@ -0,0 +1,51 @@
+import { TooltipAnchor } from '@librechat/client';
+import type { LucideIcon } from 'lucide-react';
+import { cn } from '~/utils';
+
+interface OptionToggleProps {
+  icon: LucideIcon;
+  pressed: boolean;
+  label: string;
+  /** Defaults to `label` (bulk toggles use the same text for both). */
+  tooltip?: string;
+  /** Text color applied when pressed (e.g. `text-amber-500`). */
+  activeClass: string;
+  onToggle: () => void;
+  size?: 'sm' | 'md';
+}
+
+/**
+ * Icon toggle for a per-tool option (defer / programmatic / background), shared
+ * between the per-tool row (`sm`) and the section-header bulk action (`md`).
+ */
+export default function OptionToggle({
+  icon: Icon,
+  pressed,
+  label,
+  tooltip,
+  activeClass,
+  onToggle,
+  size = 'sm',
+}: OptionToggleProps) {
+  return (
+    <TooltipAnchor
+      description={tooltip ?? label}
+      side="top"
+      render={
+        <button
+          type="button"
+          onClick={onToggle}
+          aria-pressed={pressed}
+          aria-label={label}
+          className={cn(
+            'flex items-center justify-center rounded-md transition-colors hover:bg-surface-hover focus:outline-none focus-visible:ring-2 focus-visible:ring-ring-primary',
+            size === 'sm' ? 'size-6' : 'size-7',
+            pressed ? activeClass : 'text-text-secondary hover:text-text-primary',
+          )}
+        >
+          <Icon className="size-4" aria-hidden="true" />
+        </button>
+      }
+    />
+  );
+}

client/src/components/SidePanel/Agents/Tools/ItemDialog/__tests__/McpSection.spec.tsx

@@ -44,12 +44,16 @@ jest.mock('~/hooks', () => ({
   useMCPToolOptions: () => ({
     isToolDeferred: () => false,
     isToolProgrammatic: () => false,
+    isToolBackground: () => false,
     toggleToolDefer: jest.fn(),
     toggleToolProgrammatic: jest.fn(),
+    toggleToolBackground: jest.fn(),
     areAllToolsDeferred: () => false,
     areAllToolsProgrammatic: () => false,
+    areAllToolsBackground: () => false,
     toggleDeferAll: jest.fn(),
     toggleProgrammaticAll: jest.fn(),
+    toggleBackgroundAll: jest.fn(),
   }),
 }));