Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
📣 fix: Surface MCP Credential Failures During Tool Loading (#16323)
lia-by-librechat[bot]dd21e7fb6d53
diff --git a/api/app/clients/tools/util/handleTools.js b/api/app/clients/tools/util/handleTools.jsindex d2a5ee02e0..463402e489 100644--- a/api/app/clients/tools/util/handleTools.js+++ b/api/app/clients/tools/util/handleTools.js@@ -6,6 +6,7 @@ const {toolRolePermissions,checkToolRolePermission,createSafeUser,+ loadMCPTools,createAuthIdentityContext,selectMCPUpstreamTokenProvider,mcpToolPattern,@@ -621,10 +622,6 @@ const loadTools = async ({}const loadedTools = (await Promise.all(toolPromises)).flatMap((plugin) => plugin || []);- const mcpToolPromises = [];- /** MCP server tools are initialized sequentially by server */- let index = -1;- const failedMCPServers = new Set();const safeUser = createSafeUser(options.req?.user);const requestScopedConnections =options.requestScopedConnections ?? getMCPRequestContext(options.req, options.res);@@ -653,83 +650,33 @@ const loadTools = async ({}),});- for (const [serverName, toolConfigs] of Object.entries(requestedMCPTools)) {- index++;- /** @type {LCAvailableTools} */- let availableTools = options.mcpAvailableTools?.[serverName];- for (const config of toolConfigs) {- try {- if (failedMCPServers.has(serverName)) {- continue;- }- const mcpParams = {- mcpPermissionContext,- index,- signal,- user: safeUser,- userMCPAuthMap,- configServers,- requestBody: options.requestBody ?? options.req?.body,- requestScopedConnections,- res: options.res,- upstreamTokenProvider,- upstreamTokenProviderResolver,- oboIdentityContext,- streamId: options.req?._resumableStreamId || null,- jobCreatedAt: options.jobCreatedAt,- model: agent?.model ?? model,- serverName: config.serverName,- provider: agent?.provider ?? endpoint,- config: config.config,- };-- if (config.type === 'all' && toolConfigs.length === 1) {- /** Handle async loading for single 'all' tool config */- mcpToolPromises.push(- createMCPTools(mcpParams).catch((error) => {- logger.error(`Error loading ${serverName} tools:`, error);- return null;- }),- );- continue;- }- if (!availableTools) {- try {- availableTools = await getMCPServerTools(safeUser.id, serverName, config.config);- } catch (error) {- logger.error(`Error fetching available tools for MCP server ${serverName}:`, error);- }- }-- /** Handle synchronous loading */- const mcpTool =- config.type === 'all'- ? await createMCPTools(mcpParams)- : await createMCPTool({- ...mcpParams,- availableTools,- toolKey: config.toolKey,- onAvailableTools: (tools) => {- availableTools = tools;- },- });-- if (Array.isArray(mcpTool)) {- loadedTools.push(...mcpTool);- } else if (mcpTool) {- loadedTools.push(mcpTool);- } else {- failedMCPServers.add(serverName);- logger.warn(- `MCP tool creation failed for "${config.toolKey}", server may be unavailable or unauthenticated.`,- );- }- } catch (error) {- logger.error(`Error loading MCP tool for server ${serverName}:`, error);- }- }- }- loadedTools.push(...(await Promise.all(mcpToolPromises)).flatMap((plugin) => plugin || []));+ loadedTools.push(+ ...(await loadMCPTools({+ userId: user,+ requestedTools: requestedMCPTools,+ availableTools: options.mcpAvailableTools,+ createTools: createMCPTools,+ createTool: createMCPTool,+ getAvailableTools: getMCPServerTools,+ context: {+ mcpPermissionContext,+ signal,+ user: safeUser,+ userMCPAuthMap,+ configServers,+ requestBody: options.requestBody ?? options.req?.body,+ requestScopedConnections,+ res: options.res,+ upstreamTokenProvider,+ upstreamTokenProviderResolver,+ oboIdentityContext,+ streamId: options.req?._resumableStreamId || null,+ jobCreatedAt: options.jobCreatedAt,+ model: agent?.model ?? model,+ provider: agent?.provider ?? endpoint,+ },+ })),+ );return { loadedTools, toolContextMap, dynamicToolContextMap, primedCodeFiles };};diff --git a/api/app/clients/tools/util/handleTools.test.js b/api/app/clients/tools/util/handleTools.test.jsindex 8c6c1ecc40..f1c885690c 100644--- a/api/app/clients/tools/util/handleTools.test.js+++ b/api/app/clients/tools/util/handleTools.test.js@@ -401,6 +401,145 @@ describe('Tool Handlers', () => {);});+ describe('MCP credential failure propagation', () => {+ const {+ OpenIDReauthRequiredError,+ MCPAuthenticationRejectedError,+ MCPAuthenticationRefreshError,+ OboTokenResolutionError,+ } = require('@librechat/api');+ const failures = [+ new OpenIDReauthRequiredError('Please sign in again'),+ new MCPAuthenticationRejectedError('private-mcp', false),+ new MCPAuthenticationRejectedError('private-mcp', true),+ new MCPAuthenticationRefreshError(new Error('temporarily unavailable')),+ new OboTokenResolutionError('session_refresh_failed', 'Please sign in again', false),+ new OboTokenResolutionError('session_refresh_failed', 'Retry later', true),+ ];+ const toolKey = (name, server = 'private-mcp') =>+ `${name}${Constants.mcp_delimiter}${server}`;+ const load = (tools, signal) =>+ loadTools({+ user: fakeUser._id.toString(),+ tools,+ signal,+ options: { req: { user: { id: fakeUser._id.toString(), role: 'USER' }, body: {} } },+ });++ beforeEach(() => {+ mockGetServerConfig.mockResolvedValue({+ type: 'streamable-http',+ url: 'https://example.com/mcp',+ source: 'yaml',+ });+ mockGetMCPServerTools.mockResolvedValue({});+ mockCreateMCPTool.mockReset();+ mockCreateMCPTools.mockReset();+ });++ it.each(failures)('preserves an all-tools credential failure: %s', async (error) => {+ mockCreateMCPTools.mockRejectedValueOnce(error);+ await expect(load([toolKey(Constants.mcp_all)])).rejects.toBe(error);+ });++ it.each(failures)('preserves a selected-tool credential failure: %s', async (error) => {+ mockCreateMCPTool.mockRejectedValueOnce(error);+ await expect(load([toolKey('search')])).rejects.toBe(error);+ });++ it('keeps ordinary unavailable servers optional and loads healthy tools', async () => {+ mockCreateMCPTools.mockRejectedValueOnce(new Error('server offline'));+ const healthyTool = { name: toolKey('search', 'healthy') };+ mockCreateMCPTool.mockResolvedValueOnce(healthyTool);+ await expect(load([toolKey(Constants.mcp_all), healthyTool.name])).resolves.toMatchObject({+ loadedTools: [healthyTool],+ });+ });++ it('preserves owned cancellation but not a dependency abort of a live run', async () => {+ const controller = new AbortController();+ const error = new DOMException('Stopped', 'AbortError');+ mockCreateMCPTool.mockRejectedValueOnce(error);+ await expect(load([toolKey('search')], controller.signal)).resolves.toMatchObject({+ loadedTools: [],+ });+ mockCreateMCPTool.mockRejectedValueOnce(error);+ controller.abort(error);+ await expect(load([toolKey('search')], controller.signal)).rejects.toBe(error);+ });++ it('observes early bulk rejection while a selected tool is still loading', async () => {+ const error = failures[0];+ mockCreateMCPTools.mockRejectedValueOnce(error);+ mockCreateMCPTool.mockImplementationOnce(+ () => new Promise((resolve) => setImmediate(() => resolve({ name: 'healthy' }))),+ );+ await expect(load([toolKey(Constants.mcp_all), toolKey('search', 'healthy')])).rejects.toBe(+ error,+ );+ });++ it('settles outstanding bulk loads before surfacing a selected-tool failure', async () => {+ const error = failures[0];+ let bulkSettled = false;+ mockCreateMCPTools.mockImplementationOnce(+ () =>+ new Promise((resolve) =>+ setImmediate(() => {+ bulkSettled = true;+ resolve([{ name: 'healthy' }]);+ }),+ ),+ );+ mockCreateMCPTool.mockRejectedValueOnce(error);+ await expect(load([toolKey(Constants.mcp_all, 'healthy'), toolKey('search')])).rejects.toBe(+ error,+ );+ expect(bulkSettled).toBe(true);+ });++ it.each([false, true])(+ 'lets cancellation supersede an auth failure after sibling settlement: authFailure=%s',+ async (authFailure) => {+ const controller = new AbortController();+ const stopped = new Error('request cancelled');+ let siblingSettled = false;+ mockCreateMCPTools.mockImplementationOnce(async () => {+ if (authFailure) {+ throw failures[0];+ }+ return [{ name: 'first' }];+ });+ mockCreateMCPTools.mockImplementationOnce(+ () =>+ new Promise((resolve) =>+ setImmediate(() => {+ controller.abort(stopped);+ siblingSettled = true;+ resolve([{ name: 'sibling' }]);+ }),+ ),+ );+ await expect(+ load(+ [toolKey(Constants.mcp_all), toolKey(Constants.mcp_all, 'healthy')],+ controller.signal,+ ),+ ).rejects.toBe(stopped);+ expect(siblingSettled).toBe(true);+ },+ );++ it('allows a later request to recover after re-authentication', async () => {+ mockCreateMCPTools.mockRejectedValueOnce(failures[0]);+ await expect(load([toolKey(Constants.mcp_all)])).rejects.toBe(failures[0]);+ mockCreateMCPTools.mockResolvedValueOnce([{ name: 'search' }]);+ await expect(load([toolKey(Constants.mcp_all)])).resolves.toMatchObject({+ loadedTools: [{ name: 'search' }],+ });+ });+ });+it('passes request body to chat MCP tool creation and skips stale cache for BODY-scoped servers', async () => {const serverName = 'body-scoped';const toolKey = `search${Constants.mcp_delimiter}${serverName}`;diff --git a/api/server/controllers/agents/__tests__/openai.spec.js b/api/server/controllers/agents/__tests__/openai.spec.jsindex 1ba6190482..8659082215 100644--- a/api/server/controllers/agents/__tests__/openai.spec.js+++ b/api/server/controllers/agents/__tests__/openai.spec.js@@ -174,6 +174,8 @@ jest.mock('@librechat/agents', () => ({}));jest.mock('@librechat/api', () => ({+ getAgentErrorMetadata: (...args) =>+ jest.requireActual('@librechat/api').getAgentErrorMetadata(...args),/* Provisioning moved into this package; the controllers build the callback from it. */createProvisionFilesCallback: () => async () => {},createAgentExecutionContext: (context) => context,@@ -428,8 +430,8 @@ jest.mock('~/cache', () => ({jest.mock('~/server/services/ToolService', () => ({loadAgentTools: jest.fn().mockResolvedValue([]),loadToolsForExecution: jest.fn().mockResolvedValue([]),- isFatalAgentInitializationError: jest.fn((error) =>- ['AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE', 'resource_recovery_required'].includes(error?.code),+ isFatalAgentInitializationError: jest.fn((...args) =>+ jest.requireActual('@librechat/api').isFatalAgentInitializationError(...args),),}));@@ -1674,6 +1676,63 @@ describe('OpenAIChatCompletionController', () => {);});+ const credentialCases = () => {+ const {+ OpenIDReauthRequiredError,+ MCPAuthenticationRejectedError,+ MCPAuthenticationRefreshError,+ OboTokenResolutionError,+ } = jest.requireActual('@librechat/api');+ return [+ [new OpenIDReauthRequiredError('Please sign in again'), 401, undefined],+ [+ new MCPAuthenticationRejectedError('private-mcp', false),+ 403,+ 'MCP_AUTHENTICATION_REJECTED',+ ],+ [+ new MCPAuthenticationRefreshError(new Error('temporary failure')),+ 503,+ 'MCP_AUTHENTICATION_REFRESH_FAILED',+ ],+ [+ new OboTokenResolutionError('session_refresh_failed', 'Please sign in again', false),+ 403,+ 'MCP_AUTHENTICATION_REJECTED',+ ],+ [+ new OboTokenResolutionError('exchange_failed', 'Temporary exchange failure', true),+ 503,+ 'MCP_AUTHENTICATION_REFRESH_FAILED',+ ],+ ];+ };+ it.each(credentialCases())(+ 'preserves remote chat credential response metadata: %s',+ async (error, status, code) => {+ const { initializeAgent, createErrorResponse } = require('@librechat/api');+ const { loadAgentTools } = require('~/server/services/ToolService');+ loadAgentTools.mockRejectedValueOnce(error);+ initializeAgent.mockImplementationOnce(async ({ req, res, loadTools, agent }) => {+ await loadTools({+ req,+ res,+ tools: ['search_mcp_private'],+ model: agent.model,+ agentId: agent.id,+ provider: agent.provider,+ });+ });+ await OpenAIChatCompletionController(req, res);+ expect(res.status).toHaveBeenCalledWith(status);+ expect(createErrorResponse).toHaveBeenCalledWith(+ error.message,+ status < 500 ? 'invalid_request_error' : 'server_error',+ code ?? null,+ );+ },+ );+it('returns 503 when an agent expects MCP tools but resolves none', async () => {const { initializeAgent } = require('@librechat/api');const { loadAgentTools } = require('~/server/services/ToolService');diff --git a/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js b/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.jsindex 437e74c45d..43e0f23daa 100644--- a/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js+++ b/api/server/controllers/agents/__tests__/request.partialDisconnect.spec.js@@ -47,6 +47,8 @@ jest.mock('@librechat/data-schemas', () => ({}));jest.mock('@librechat/api', () => ({+ getAgentErrorMetadata: (...args) =>+ jest.requireActual('@librechat/api').getAgentErrorMetadata(...args),sendEvent: jest.fn(),isScheduleFireRequest: jest.fn(() => false),exemptFromConcurrencyLimiter: jest.fn(() => false),diff --git a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.jsindex 058d3302dc..b3408f34cd 100644--- a/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js+++ b/api/server/controllers/agents/__tests__/request.resumeMetadata.spec.js@@ -252,6 +252,8 @@ jest.mock('@librechat/data-schemas', () => ({}));jest.mock('@librechat/api', () => ({+ getAgentErrorMetadata: (...args) =>+ jest.requireActual('@librechat/api').getAgentErrorMetadata(...args),sendEvent: jest.fn(),logAgentMemorySnapshot: jest.fn(),isScheduleFireRequest: (...args) => mockIsScheduleFireRequest(...args),@@ -4070,6 +4072,71 @@ describe('ResumableAgentController resume metadata', () => {});});+ it.each([+ new (jest.requireActual('@librechat/api').OpenIDReauthRequiredError)(+ 'Please sign in again to continue using this MCP server.',+ ),+ new (jest.requireActual('@librechat/api').MCPAuthenticationRejectedError)('private-mcp', false),+ new (jest.requireActual('@librechat/api').MCPAuthenticationRefreshError)(+ new Error('upstream refresh unavailable'),+ ),+ new (jest.requireActual('@librechat/api').OboTokenResolutionError)(+ 'session_refresh_failed',+ 'Please sign in again',+ false,+ ),+ new (jest.requireActual('@librechat/api').OboTokenResolutionError)(+ 'exchange_failed',+ 'Temporary exchange failure',+ true,+ ),+ ])(+ 'publishes an actionable MCP initialization failure without an HTTP 401: %s',+ async (error) => {+ const initializeClient = jest.fn().mockRejectedValue(error);+ const req = {+ user: { id: 'user-123' },+ body: {+ text: 'Use the private tool.',+ messageId: 'user-msg',+ clientRequestId: 'req-abc',+ conversationId: 'conversation-123',+ endpointOption: { endpoint: 'agents', modelOptions: { model: 'gpt-4.1' } },+ },+ config: {},+ };+ const res = createResumableResponse();++ await AgentController(req, res, jest.fn(), initializeClient, null);++ expect(res.status).toHaveBeenCalledWith(200);+ expect(res.status).not.toHaveBeenCalledWith(401);+ expect(initializeClient).toHaveBeenCalledTimes(1);+ let metadata = {+ status: error.status ?? error.statusCode,+ ...(error.code ? { code: error.code } : {}),+ };+ if (error.name === 'OboTokenResolutionError') {+ metadata = {+ status: error.retryable ? 503 : 403,+ code: error.retryable+ ? 'MCP_AUTHENTICATION_REFRESH_FAILED'+ : 'MCP_AUTHENTICATION_REJECTED',+ retryable: error.retryable,+ };+ }+ expect(mockGenerationJobManager.completeJob).toHaveBeenCalledWith(+ 'conversation-123',+ JSON.stringify({+ ...metadata,+ error: error.message,+ }),+ 1000,+ expect.objectContaining({ beforeErrorPublication: expect.any(Function) }),+ );+ },+ );+it('finalizes the failed job before releasing the idempotency claim', async () => {mockGenerationJobManager.claimGeneration.mockResolvedValue(wonGenerationClaim());const initializeClient = jest.fn().mockRejectedValue(new Error('init boom after res.json'));diff --git a/api/server/controllers/agents/__tests__/responses.unit.spec.js b/api/server/controllers/agents/__tests__/responses.unit.spec.jsindex 069ad64c29..1eb14ff974 100644--- a/api/server/controllers/agents/__tests__/responses.unit.spec.js+++ b/api/server/controllers/agents/__tests__/responses.unit.spec.js@@ -197,6 +197,8 @@ jest.mock('@librechat/agents', () => ({}));jest.mock('@librechat/api', () => ({+ getAgentErrorMetadata: (...args) =>+ jest.requireActual('@librechat/api').getAgentErrorMetadata(...args),/* Provisioning moved into this package; the controllers build the callback from it. */createProvisionFilesCallback: () => async () => {},createAgentExecutionContext: (context) => context,@@ -1820,6 +1822,53 @@ describe('createResponse controller', () => {});describe('safe error logging', () => {+ const credentialCases = () => {+ const {+ OpenIDReauthRequiredError,+ MCPAuthenticationRejectedError,+ MCPAuthenticationRefreshError,+ OboTokenResolutionError,+ } = jest.requireActual('@librechat/api');+ return [+ [new OpenIDReauthRequiredError('Please sign in again'), 401, undefined],+ [+ new MCPAuthenticationRejectedError('private-mcp', false),+ 403,+ 'MCP_AUTHENTICATION_REJECTED',+ ],+ [+ new MCPAuthenticationRefreshError(new Error('temporary failure')),+ 503,+ 'MCP_AUTHENTICATION_REFRESH_FAILED',+ ],+ [+ new OboTokenResolutionError('session_refresh_failed', 'Please sign in again', false),+ 403,+ 'MCP_AUTHENTICATION_REJECTED',+ ],+ [+ new OboTokenResolutionError('exchange_failed', 'Temporary exchange failure', true),+ 503,+ 'MCP_AUTHENTICATION_REFRESH_FAILED',+ ],+ ];+ };+ it.each(credentialCases())(+ 'preserves remote Responses credential metadata: %s',+ async (error, status, code) => {+ const api = require('@librechat/api');+ api.initializeAgent.mockRejectedValueOnce(error);+ await createResponse(req, res);+ expect(api.sendResponsesErrorResponse).toHaveBeenCalledWith(+ res,+ status,+ error.message,+ status < 500 ? 'invalid_request' : 'server_error',+ ...(code ? [code] : []),+ );+ },+ );+it('does not classify a client disconnect as an upstream model error', async () => {const api = require('@librechat/api');const { logger } = require('@librechat/data-schemas');diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.jsindex 76d60a7c45..23fa533a1d 100644--- a/api/server/controllers/agents/openai.js+++ b/api/server/controllers/agents/openai.js@@ -55,6 +55,7 @@ const {isContentFilterError,getSafeErrorMetadata,getUserFacingProviderError,+ getAgentErrorMetadata,getRemoteAgentPermissions,createToolExecuteHandler,createOwnedToolEndHandler,@@ -260,13 +261,11 @@ function handleExecutionError({ error, res, context, appConfig }) {error.body.error,);}- const statusCode =- typeof error?.status === 'number' && error.status >= 400 && error.status < 600- ? error.status- : 500;+ const errorMetadata = getAgentErrorMetadata(error);+ const statusCode = errorMetadata?.status ?? 500;const errorType =statusCode >= 400 && statusCode < 500 ? 'invalid_request_error' : 'server_error';- const errorCode = !protectionEnabled && typeof error?.code === 'string' ? error.code : null;+ const errorCode = !protectionEnabled ? (errorMetadata?.code ?? null) : null;sendErrorResponse(res, statusCode, errorMessage, errorType, errorCode);}diff --git a/api/server/controllers/agents/request.js b/api/server/controllers/agents/request.jsindex 3cfa9d71ae..79dd2d2fbe 100644--- a/api/server/controllers/agents/request.js+++ b/api/server/controllers/agents/request.js@@ -46,6 +46,7 @@ const {resolveAgentTurnExecutionPlan,logAgentMemorySnapshot,getCodeWorkspaceSelectionErrorDetails,+ getAgentErrorMetadata,shouldPersistCodeWorkspaceInitializationError,resolvePersistableCodeEnvironmentDecision,getFailedTurnTraceFields,@@ -113,13 +114,12 @@ function getInitializationFailure(error) {};}- const candidateStatus = error?.status ?? error?.statusCode;- if (!Number.isInteger(candidateStatus) || candidateStatus < 400 || candidateStatus >= 600) {+ const metadata = getAgentErrorMetadata(error);+ if (!metadata?.status) {return null;}return {- status: candidateStatus,- ...(typeof error?.code === 'string' ? { code: error.code } : {}),+ ...metadata,...getCodeWorkspaceSelectionErrorDetails(error),error: error?.message || 'Failed to start generation',};diff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.jsindex f44a9c37c5..f09f292dd6 100644--- a/api/server/controllers/agents/responses.js+++ b/api/server/controllers/agents/responses.js@@ -53,6 +53,7 @@ const {isContentFilterError,getSafeErrorMetadata,getUserFacingProviderError,+ getAgentErrorMetadata,createToolExecuteHandler,createOwnedToolEndHandler,resolveRecursionLimit,@@ -147,12 +148,10 @@ function handleExecutionError({ error, res, appConfig }) {error.body.error,);}- const statusCode =- typeof error?.status === 'number' && error.status >= 400 && error.status < 600- ? error.status- : 500;+ const errorMetadata = getAgentErrorMetadata(error);+ const statusCode = errorMetadata?.status ?? 500;const errorType = statusCode >= 400 && statusCode < 500 ? 'invalid_request' : 'server_error';- const errorCode = !protectionEnabled && typeof error?.code === 'string' ? error.code : undefined;+ const errorCode = !protectionEnabled ? errorMetadata?.code : undefined;if (errorCode === undefined) {sendResponsesErrorResponse(res, statusCode, errorMessage, errorType);} else {diff --git a/api/server/services/Endpoints/agents/initialize.spec.js b/api/server/services/Endpoints/agents/initialize.spec.jsindex fe65c2493a..62b05309f0 100644--- a/api/server/services/Endpoints/agents/initialize.spec.js+++ b/api/server/services/Endpoints/agents/initialize.spec.js@@ -69,13 +69,8 @@ jest.mock('~/server/services/ToolService', () => ({loadAgentTools: jest.fn(),loadToolsForExecution: (...args) => mockLoadToolsForExecution(...args),getAccessibleMcpServerNames: (...args) => mockGetAccessibleMcpServerNames(...args),- isFatalAgentInitializationError: (error) =>- [- 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',- 'resource_recovery_required',- 'stateful_code_environment_not_allowed',- 'code_workspace_unavailable',- ].includes(error?.code),+ isFatalAgentInitializationError:+ jest.requireActual('@librechat/api').isFatalAgentInitializationError,}));jest.mock('~/server/controllers/ModelController', () => ({@@ -452,6 +447,34 @@ describe('initializeClient — processAgent ACL gate', () => {).rejects.toBe(toolError);});+ it.each([+ new (require('@librechat/api').OpenIDReauthRequiredError)('Please sign in again'),+ new (require('@librechat/api').MCPAuthenticationRejectedError)('private-mcp', false),+ new (require('@librechat/api').MCPAuthenticationRefreshError)(new Error('Retry later')),+ ])('preserves credential failure through the runtime agent loader: %s', async (toolError) => {+ loadAgentTools.mockRejectedValueOnce(toolError);+ mockInitializeAgent.mockImplementationOnce(async ({ req, res, loadTools, agent }) => {+ await loadTools({+ req,+ res,+ tools: ['run_query_mcp_warehouse'],+ model: agent.model,+ agentId: agent.id,+ provider: agent.provider,+ });+ return makePrimaryConfig([]);+ });++ await expect(+ initializeClient({+ req: makeReq(),+ res: {},+ signal: new AbortController().signal,+ endpointOption: makeEndpointOption(),+ }),+ ).rejects.toBe(toolError);+ });+it('aborts the run when a handoff target resolves none of its expected MCP tools', async () => {const target = await createAgent({id: AUTHORIZED_ID,diff --git a/packages/api/src/agents/errors.spec.ts b/packages/api/src/agents/errors.spec.tsindex 868e60ea77..bc621f2baf 100644--- a/packages/api/src/agents/errors.spec.ts+++ b/packages/api/src/agents/errors.spec.ts@@ -7,12 +7,28 @@ import {resolveLangChainError,getUserFacingProviderError,isFatalAgentInitializationError,+ getAgentErrorMetadata,AGENT_ATTACHMENT_LIMIT_EXCEEDED,AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE,isStepLimitError,} from './errors';+import { MCPAuthenticationRejectedError, MCPAuthenticationRefreshError } from '~/mcp/errors';+import { OboTokenResolutionError } from '~/mcp/oauth/obo';+import { OpenIDReauthRequiredError } from '~/utils/oidc';describe('isFatalAgentInitializationError', () => {+ it.each([+ new OpenIDReauthRequiredError('Please sign in again'),+ new MCPAuthenticationRejectedError('private-mcp', false),+ new MCPAuthenticationRejectedError('private-mcp', true),+ new MCPAuthenticationRefreshError(new Error('temporarily unavailable')),+ new OboTokenResolutionError('session_refresh_failed', 'Please sign in again', false),+ new OboTokenResolutionError('session_refresh_failed', 'Retry later', true),+ ])('never hides a credential outcome behind optional-tool fallback: %s', (error) => {+ expect(isFatalAgentInitializationError(error)).toBe(true);+ expect(isFatalAgentInitializationError(error, { allowExpectedMCPFallback: true })).toBe(true);+ });+it('propagates cancellation even when optional MCP fallback is allowed', () => {const abort = new DOMException('Stopped', 'AbortError');const controller = new AbortController();@@ -254,3 +270,39 @@ describe('isStepLimitError', () => {expect(isStepLimitError(error)).toBe(false);});});++describe('getAgentErrorMetadata', () => {+ it.each([+ [new OpenIDReauthRequiredError('Sign in again'), 401, undefined],+ [new MCPAuthenticationRejectedError('private', false), 403, 'MCP_AUTHENTICATION_REJECTED'],+ [new MCPAuthenticationRefreshError(), 503, 'MCP_AUTHENTICATION_REFRESH_FAILED'],+ ])('preserves typed MCP statusCode and code: %s', (error, status, code) => {+ expect(getAgentErrorMetadata(error)).toEqual({ status, ...(code ? { code } : {}) });+ });++ it.each([false, true])(+ 'classifies OBO failure without rewriting the original error: retryable=%s',+ (retryable) => {+ const error = new OboTokenResolutionError('exchange_failed', 'Exchange failed', retryable);+ expect(getAgentErrorMetadata(error)).toEqual({+ status: retryable ? 503 : 403,+ code: retryable ? 'MCP_AUTHENTICATION_REFRESH_FAILED' : 'MCP_AUTHENTICATION_REJECTED',+ retryable,+ });+ expect(error.reason).toBe('exchange_failed');+ expect(error).not.toHaveProperty('statusCode');+ },+ );++ it('keeps status precedence and code-only provider failures', () => {+ expect(getAgentErrorMetadata({ status: 409, statusCode: 401, code: 'RUN_REPLACED' })).toEqual({+ status: 409,+ code: 'RUN_REPLACED',+ });+ expect(getAgentErrorMetadata({ code: 'ERR_REMOTE' })).toEqual({ code: 'ERR_REMOTE' });+ });++ it.each([null, 'bad', 399, 600, 401.5, NaN])('rejects invalid outward status: %s', (status) => {+ expect(getAgentErrorMetadata({ status })).toEqual({});+ });+});diff --git a/packages/api/src/agents/errors.ts b/packages/api/src/agents/errors.tsindex c2caff0a7e..38777e7656 100644--- a/packages/api/src/agents/errors.ts+++ b/packages/api/src/agents/errors.ts@@ -4,7 +4,8 @@ import {parseLangChainErrorCode,stripLangChainTroubleshootingUrl,} from 'librechat-data-provider';-import { isOwnedAbortError } from '~/utils/errors';+import { MCPErrorCodes, isMCPInitializationError } from '~/mcp/errors';+import { OboTokenResolutionError } from '~/mcp/oauth/obo';export const AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE = 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE';export const AGENT_ATTACHMENT_LIMIT_EXCEEDED = 'AGENT_ATTACHMENT_LIMIT_EXCEEDED';@@ -58,7 +59,7 @@ export function isFatalAgentInitializationError(): boolean {const code = getErrorCode(error);return (- isOwnedAbortError(error, options.signal) ||+ isMCPInitializationError(error, options.signal) ||FATAL_AGENT_INITIALIZATION_CODES.has(code as string) ||(code === AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE && options.allowExpectedMCPFallback !== true));@@ -190,3 +191,29 @@ export function isStepLimitError(error: unknown): boolean {}return false;}++/** Outward metadata shared by UI generation failures and both remote agent APIs. */+export function getAgentErrorMetadata(+ error: unknown,+): { status?: number; code?: string; retryable?: boolean } | undefined {+ if (error instanceof OboTokenResolutionError) {+ return {+ status: error.retryable ? 503 : 403,+ code: error.retryable+ ? MCPErrorCodes.AUTHENTICATION_REFRESH_FAILED+ : MCPErrorCodes.AUTHENTICATION_REJECTED,+ retryable: error.retryable,+ };+ }+ if (!error || typeof error !== 'object') {+ return undefined;+ }+ const candidate = error as { status?: unknown; statusCode?: unknown; code?: unknown };+ const status = candidate.status ?? candidate.statusCode;+ return {+ ...(typeof status === 'number' && Number.isInteger(status) && status >= 400 && status < 600+ ? { status }+ : {}),+ ...(typeof candidate.code === 'string' ? { code: candidate.code } : {}),+ };+}diff --git a/packages/api/src/index.ts b/packages/api/src/index.tsindex 83a0cc9b63..c84b2d2732 100644--- a/packages/api/src/index.ts+++ b/packages/api/src/index.ts@@ -26,6 +26,7 @@ export * from './mcp/oauth';export * from './mcp/auth';export * from './mcp/zod';export * from './mcp/errors';+export * from './mcp/loading';export * from './mcp/openid';export * from './mcp/cache';export * from './mcp/tools';diff --git a/packages/api/src/mcp/loading.spec.ts b/packages/api/src/mcp/loading.spec.tsnew file mode 100644index 0000000000..59c388b6a9--- /dev/null+++ b/packages/api/src/mcp/loading.spec.ts@@ -0,0 +1,121 @@+import { OpenIDReauthRequiredError } from '~/utils/oidc';+import { loadMCPTools } from './loading';++const request = (serverName: string, type: 'all' | 'single' = 'all') => ({+ type,+ serverName,+ toolKey: `${type}:${serverName}`,+ config: { serverName },+});++function setup(signal?: AbortSignal) {+ return {+ userId: 'user-id',+ context: { user: { id: 'safe-user-id' }, signal },+ requestedTools: { first: [request('first')] },+ getAvailableTools: jest.fn().mockResolvedValue(undefined),+ createTools: jest.fn().mockResolvedValue([{ name: 'bulk' }]),+ createTool: jest.fn().mockResolvedValue({ name: 'selected' }),+ };+}++describe('loadMCPTools', () => {+ it('does not schedule any work after an already-cancelled request', async () => {+ const controller = new AbortController();+ controller.abort(new Error('stopped'));+ const options = setup(controller.signal);+ await expect(loadMCPTools(options)).rejects.toBe(controller.signal.reason);+ expect(options.createTools).not.toHaveBeenCalled();+ });++ it.each([false, true])(+ 'settles siblings then prefers cancellation: authFailure=%s',+ async (authFailure) => {+ const controller = new AbortController();+ const options = setup(controller.signal);+ const stopped = new Error('stopped');+ let settled = false;+ options.createTools.mockImplementationOnce(async () => {+ if (authFailure) {+ throw new OpenIDReauthRequiredError('Please sign in again');+ }+ return [];+ });+ options.createTools.mockImplementationOnce(+ () =>+ new Promise((resolve) =>+ setImmediate(() => {+ settled = true;+ controller.abort(stopped);+ resolve([]);+ }),+ ),+ );+ await expect(+ loadMCPTools({+ ...options,+ requestedTools: {+ first: [request('first')],+ second: [request('second')],+ },+ }),+ ).rejects.toBe(stopped);+ expect(settled).toBe(true);+ },+ );++ it('does not create selected tools after cancellation during catalog loading', async () => {+ const controller = new AbortController();+ const options = setup(controller.signal);+ options.getAvailableTools.mockImplementationOnce(async () => {+ controller.abort();+ return {};+ });+ await expect(+ loadMCPTools({+ ...options,+ requestedTools: {+ first: [request('first', 'single')],+ },+ }),+ ).rejects.toBe(controller.signal.reason);+ expect(options.createTool).not.toHaveBeenCalled();+ });++ it('preserves the first typed error without treating ordinary optional errors as fatal', async () => {+ const options = setup();+ const error = new OpenIDReauthRequiredError('Please sign in again');+ options.createTools.mockRejectedValueOnce(new Error('optional tool unavailable'));+ await expect(loadMCPTools(options)).resolves.toEqual([]);+ options.createTools.mockRejectedValueOnce(error);+ await expect(loadMCPTools(options)).rejects.toBe(error);+ await expect(loadMCPTools(options)).resolves.toEqual([{ name: 'bulk' }]);+ });++ it('reuses the refreshed catalog for sequential tools without changing parameters', async () => {+ const options = setup();+ const catalog = { search: true };+ options.createTool.mockImplementationOnce(async ({ onAvailableTools }) => {+ onAvailableTools(catalog);+ return { name: 'one' };+ });+ await loadMCPTools({+ ...options,+ requestedTools: {+ first: [request('first', 'single'), request('first', 'single')],+ },+ });+ expect(options.getAvailableTools).toHaveBeenCalledTimes(1);+ expect(options.getAvailableTools).toHaveBeenCalledWith('user-id', 'first', {+ serverName: 'first',+ });+ expect(options.createTool).toHaveBeenLastCalledWith(+ expect.objectContaining({+ user: { id: 'safe-user-id' },+ index: 0,+ availableTools: catalog,+ config: { serverName: 'first' },+ }),+ );+ });+});diff --git a/packages/api/src/mcp/loading.ts b/packages/api/src/mcp/loading.tsnew file mode 100644index 0000000000..30e4fe8822--- /dev/null+++ b/packages/api/src/mcp/loading.ts@@ -0,0 +1,131 @@+import { logger } from '@librechat/data-schemas';+import { isMCPInitializationError } from './errors';++interface MCPToolRequest<Config> {+ type: 'all' | 'single';+ toolKey: string;+ serverName: string;+ config: Config;+}++interface MCPToolParameters<Config> {+ index: number;+ serverName: string;+ config: Config;+}++interface MCPLoadContext {+ signal?: AbortSignal;+}++interface MCPToolLoadOptions<Tool, Catalog, Config, Context extends MCPLoadContext> {+ userId: string;+ requestedTools: Record<string, MCPToolRequest<Config>[]>;+ context: Context;+ availableTools?: Record<string, Catalog>;+ getAvailableTools: (+ userId: string,+ server: string,+ config: Config,+ ) => Promise<Catalog | undefined>;+ createTools: (params: Context & MCPToolParameters<Config>) => Promise<Tool[] | null | undefined>;+ createTool: (+ params: Context &+ MCPToolParameters<Config> & {+ toolKey: string;+ availableTools?: Catalog;+ onAvailableTools: (tools: Catalog) => void;+ },+ ) => Promise<Tool | Tool[] | null | undefined>;+}++/**+ * Bulk loads overlap while selected tools reuse each server's catalog in order.+ * Settle every started load before cleanup can begin, then prefer request cancellation+ * over any saved credential failure. Ordinary optional-tool failures stay soft.+ */+export async function loadMCPTools<Tool, Catalog, Config, Context extends MCPLoadContext>({+ userId,+ requestedTools,+ context,+ availableTools: catalogs,+ getAvailableTools,+ createTools,+ createTool,+}: MCPToolLoadOptions<Tool, Catalog, Config, Context>): Promise<Tool[]> {+ const { signal } = context;+ const loaded: Tool[] = [];+ const pending: Promise<Tool[] | null | undefined>[] = [];+ const failedServers = new Set<string>();+ let failure: { error: unknown } | undefined;+ const capture = (error: unknown) => {+ if (!failure && isMCPInitializationError(error, signal)) {+ failure = { error };+ }+ };++ let index = -1;+ for (const [serverName, configs] of Object.entries(requestedTools)) {+ index++;+ let availableTools = catalogs?.[serverName];+ for (const config of configs) {+ if (signal?.aborted || failedServers.has(serverName)) {+ break;+ }+ try {+ const params = { ...context, index, serverName: config.serverName, config: config.config };+ if (config.type === 'all' && configs.length === 1) {+ pending.push(+ createTools(params).catch((error: unknown) => {+ capture(error);+ logger.error(`Error loading ${serverName} tools:`, error);+ return null;+ }),+ );+ continue;+ }+ if (!availableTools) {+ try {+ availableTools = await getAvailableTools(userId, serverName, config.config);+ } catch (error) {+ capture(error);+ logger.error(`Error fetching available tools for MCP server ${serverName}:`, error);+ }+ }+ if (signal?.aborted) {+ break;+ }+ const tool =+ config.type === 'all'+ ? await createTools(params)+ : await createTool({+ ...params,+ availableTools,+ toolKey: config.toolKey,+ onAvailableTools: (tools) => {+ availableTools = tools;+ },+ });+ if (Array.isArray(tool)) {+ loaded.push(...tool);+ } else if (tool) {+ loaded.push(tool);+ } else {+ failedServers.add(serverName);+ logger.warn(+ `MCP tool creation failed for "${config.toolKey}", server may be unavailable or unauthenticated.`,+ );+ }+ } catch (error) {+ capture(error);+ logger.error(`Error loading MCP tool for server ${serverName}:`, error);+ }+ }+ }+ loaded.push(...(await Promise.all(pending)).flatMap((tools) => tools ?? []));+ signal?.throwIfAborted();+ if (failure) {+ throw failure.error;+ }+ return loaded;+}