Skip to content

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

📣 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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;
+}