Optional MCP servers on model specs: attach a server only for users who have authorized it

[vari-ltech]

Problem. With modelSpecs.enforce: true, the only way to give every chat a server's tools without a manual pick is mcpServers on the spec. For an OAuth server, that makes the server mandatory. A user who has not authorized it waits up to two minutes for sign-in (ToolService.js), and then the run fails with AgentToolInitializationError. The picker avoids this, but the selection resets to the spec's mcpServers in every new chat while a spec is active. So an admin cannot offer a server that only some users connect. We reproduced this on v0.8.8 with a streamable-http server using per-user OAuth against Microsoft Entra.

Proposal. Add modelSpecs.list[].optionalMcpServers: string[] beside mcpServers:

• An OAuth server listed there is attached only when the user has a usable stored authorization. Otherwise it is left out: no OAuth wait, no failure.
• A non-OAuth server listed there loads as usual. If a server is in both lists, mcpServers wins.
• If the user ticks the server in the picker, today's behaviour applies, including the sign-in prompt.
• It covers model-spec chats and added conversations. Persisted agents are unchanged.
• The client keeps optional attachments apart from the user's explicit selection, and shows a skipped server as not equipped.
• If the authorization check itself fails, today's behaviour stays: the server is not dropped silently.

Out of scope. Deferred sign-in when the model selects a tool, and resuming that call (#16765). Also a server that is down for a user who has authorized it, which keeps today's error behaviour.

Affected areas. The model spec schema (packages/data-provider), one shared selection policy in packages/api used by loadEphemeralAgent and the added-conversation loader, the wiring in api/server/services/Endpoints/agents/, the client's spec-to-selection mapping (client/src/utils/endpoints.ts, useApplyModelSpecAgents.ts), and a docs PR to librechat.ai.

Tests. The schema; both loaders for authorized and unauthorized users, overlaps with mcpServers and the picker, and non-OAuth servers; the stored-authorization states (valid, refresh only, expired, rejected, check failure); a ToolService test that a left-out server never enters the OAuth wait; and the client's selection state.

I'd like to implement this if it fits your plans. I use AI assistance for the investigation and the implementation, and I review and verify everything I submit. Once it is approved and an issue is assigned to me, I will open one PR against dev.

[dfetterman]

Thanks for documenting this. We’re hitting the same problem on 0.8.8-rc2 which is an issue with a large user base that needs access to a diverse set of tools via MCP. - Dane Fetterman