🦥 feat: Server-Level deferLoading Default for MCP Servers

[sindriii]

Stacked on the fix/mcp-tools-list-pagination-rc image-build branch so apro-sandbox can validate this change on top of the currently-deployed pagination fix (ae33e210d). The diff here is only the defer-loading change. A separate, clean PR off main will go upstream to danny-avila/LibreChat.

Summary

Adds an optional per-MCP-server deferLoading: boolean config flag so all of a server's tools default to deferred loading: the model receives the tool_search tool plus a name-only listing instead of each tool's full schema. Saves context on large tool sets and — unlike the existing per-agent tool_options toggle — applies to ephemeral agents (plain model + attached MCP), which carry no tool_options and previously could never defer.

This extends the maintainer's own deferred_tools capability (danny-avila#11295) to the server-config level and the ephemeral path. It composes with, and is complementary to, the proposed MCP toolFilter (danny-avila#13346 / issue danny-avila#11088): filtering selects which tools exist; deferLoading defers their schemas.

Behavior

• Schema: deferLoading on BaseOptionsSchema (packages/data-provider/src/mcp.ts); optional, defaults to undefined/false — fully backward compatible.
• Precedence: per-agent tool_options[toolId].defer_loading (true OR false) wins; else server deferLoading; else false. Gated by the existing deferred_tools agent capability (capability off ⇒ no deferral, no tool_search).
• Mechanism: a per-tool serverDeferLoading stamp applied at the tool-registry build:
  • live path — stamped at the MCP tool factory (MCP.js) from the resolved merged server config.
  • event-driven path — stamped in definitions.ts via a new getServerDeferLoading resolver wired through ToolService.js.
  • Registry build (classification.ts) reads the stamp, so saved agents, ephemeral agents, and the mcp_all placeholder all defer uniformly.
• UI: three-state checkbox reflecting the inherited server default (inherit / explicit-on / explicit-off; toggling back to the default collapses the explicit key).

Tests

• classification.spec.ts — precedence matrix (server default applies, ephemeral fallback, explicit override wins, capability-off clears, mixed servers, stamp extraction).
• definitions.spec.ts — event-driven parity with the live path; tool_search injection on a server default with no per-agent options.
• packages/data-provider/src/mcp.spec.ts — schema parse / optional / reject.
• useMCPToolOptions.spec.ts — three-state inheritance + collapse-to-default.

Notes for review

• The token pre-count exclusion for deferred tools lives in @librechat/agents (keyed off defer_loading); the repo-boundary guard here is the classification/definitions tests proving server-defaulted tools carry defer_loading: true into the registry the agents lib consumes.
• librechat.example.yaml documents the new option.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4ac03568-2d77-45aa-bdb0-936e0cbcb718

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/mcp-server-defer-loading-rc

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}