⏲️ feat: Defer Loading MCP Tools

[danny-avila]

No description provided.

[github-actions]

🚨 Unused i18next Keys Detected

The following translation keys are defined in translation.json but are not used in the codebase:

• com_ui_mcp_defer_all_description
• com_ui_mcp_defer_loading_description
• com_ui_mcp_deferred

⚠️ Please remove these unused keys to keep the translation files clean.

[Copilot]

Pull request overview

This pull request implements deferred loading for MCP (Model Context Protocol) tools, allowing tools to be discoverable via search but not loaded until needed. This helps conserve context window tokens and improves agent performance.

Key Changes

• Adds tool_options field to agent schema for per-tool configuration (defer_loading, allowed_callers)
• Implements tool classification system via environment variables and agent-level configuration
• Adds tool search functionality to discover deferred tools and Programmatic Tool Calling (PTC) for code execution
• Updates UI to allow configuring deferred loading per tool or per server
• Updates @librechat/agents dependency from 3.0.66 to 3.0.75

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/data-schemas/src/types/agent.ts	Adds tool_options type definition to IAgent interface
packages/data-schemas/src/schema/agent.ts	Adds tool_options schema field with Mixed type
packages/data-provider/src/types/assistants.ts	Defines AllowedCaller, ToolOptions, and AgentToolOptions types
packages/data-provider/src/schemas.ts	Adds tool_options to default agent form values
packages/data-provider/src/config.ts	Adds PROGRAMMATIC_TOOL_CALLING constant
packages/api/src/tools/index.ts	Exports new classification module
packages/api/src/tools/classification.ts	New comprehensive tool classification system with registry building and management
packages/api/src/mcp/types/index.ts	Removes duplicate LCTool type, imports from @librechat/agents
packages/api/src/agents/validation.ts	Adds validation schemas for tool_options
packages/api/src/agents/run.ts	Implements discovered tools extraction and defer_loading override logic
packages/api/src/agents/initialize.ts	Updates agent initialization to pass tool_options and return toolRegistry
client/src/locales/en/translation.json	Adds localization strings for defer loading UI
client/src/components/SidePanel/Agents/MCPTool.tsx	Implements defer loading UI controls with optimistic updates
client/src/components/SidePanel/Agents/AgentSelect.tsx	Adds tool_options handling in form reset
client/src/components/SidePanel/Agents/AgentPanel.tsx	Updates avatar upload mutation property reference
client/src/components/Chat/Messages/Content/Parts/ExecuteCode.tsx	Adds default value for lang parameter
client/src/components/Chat/Messages/Content/Part.tsx	Adds PROGRAMMATIC_TOOL_CALLING to code execution check
client/src/common/agents-types.ts	Adds tool_options to AgentForm type
api/server/services/ToolService.js	Integrates buildToolClassification and returns toolRegistry
api/server/services/MCP.js	Attaches mcpJsonSchema to tool instances for registry building
api/server/services/Endpoints/agents/initialize.js	Updates loadTools to accept and pass tool_options
api/server/controllers/agents/client.js	Passes messages to createRun for discovered tools extraction
api/server/controllers/agents/callbacks.js	Updates code tool detection to include PROGRAMMATIC_TOOL_CALLING
package-lock.json	Updates @librechat/agents dependency and adds okapibm25

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The defer_loading logic in buildToolRegistryFromAgentOptions ignores environment variable configuration. Unlike allowed_callers which falls back to env vars when not set in agentOptions, defer_loading is only set to true when explicitly set in agentOptions. This means that if an agent doesn't have tool_options but TOOL_DEFERRED env var is set, the defer_loading won't be applied. This inconsistency could cause unexpected behavior where some classification works from env vars but defer_loading doesn't.

Suggested change

	/** Determine defer_loading: agent options take precedence (explicit true/false) */
	const defer_loading = agentOptions?.defer_loading === true;
	/** Determine defer_loading: agent options take precedence (explicit true/false), then env vars */
	let defer_loading: boolean;
	if (typeof agentOptions?.defer_loading === 'boolean') {
	defer_loading = agentOptions.defer_loading;
	} else if (toolMatchesPatterns(name, deferred, deferredExclude)) {
	defer_loading = true;
	} else {
	defer_loading = false;
	}

[Copilot]

The clean-up logic for tool_options when only defer_loading remains is checking if the object has exactly 1 key, but it should check if it's empty after deletion. If there were other options like allowed_callers and only defer_loading is being removed, Object.keys would return more than 1 key before deletion, so the cleanup wouldn't happen even though after deleting defer_loading the object might be left with just allowed_callers (which is still valid). However, checking length === 1 after setting defer_loading means it will delete when defer_loading is the only property, which is correct. But this logic is inconsistent with the toggleDeferAll logic below which checks length === 0 after deletion.

Suggested change

	[toolId]: {
	...currentToolOptions,
	defer_loading: newDeferred,
	},
	};
	/** Clean up if no options remain for this tool */
	if (!newDeferred && Object.keys(updatedOptions[toolId]).length === 1) {
	delete updatedOptions[toolId];
	};
	if (newDeferred) {
	/** Enabling defer_loading: add or update this option for the tool */
	updatedOptions[toolId] = {
	...currentToolOptions,
	defer_loading: true,
	};
	} else {
	/** Disabling defer_loading: remove it and clean up if no options remain */
	const { defer_loading, ...restOptions } = currentToolOptions as typeof currentToolOptions;
	if (Object.keys(restOptions).length === 0) {
	delete updatedOptions[toolId];
	} else {
	updatedOptions[toolId] = restOptions;
	}

[Copilot]

The change from uploadAvatarMutation.isPending to uploadAvatarMutation.isLoading appears to be inconsistent with TanStack Query v4+ API. Modern versions of React Query (TanStack Query) use isPending instead of the deprecated isLoading. This change might break functionality or cause type errors if the project is using a newer version of React Query. Please verify which version is being used and use the appropriate property.

Suggested change

	isAvatarUploading={isAvatarUploadInFlight || uploadAvatarMutation.isLoading}
	isAvatarUploading={isAvatarUploadInFlight || uploadAvatarMutation.isPending}

[Copilot]

The default value assignment for lang uses object destructuring with a default, but the condition ?? ({} as ParsedArgs) means that if useParseArgs returns null, the destructuring will fail before the default value can be applied. The correct approach is to use optional chaining and nullish coalescing before destructuring, or handle the null case explicitly.

Suggested change

	const { lang = 'py', code } = useParseArgs(args) ?? ({} as ParsedArgs);
	const parsedArgs = useParseArgs(args);
	const lang = parsedArgs?.lang ?? 'py';
	const code = parsedArgs?.code;

[github-actions]

🚨 Unused i18next Keys Detected

The following translation keys are defined in translation.json but are not used in the codebase:

• com_ui_mcp_defer_all_description
• com_ui_mcp_defer_loading_description
• com_ui_mcp_deferred

⚠️ Please remove these unused keys to keep the translation files clean.