🍵 fix: Support Renewable MCP Credentials for Schedules (#15908)

* fix(schedules): forward renewable MCP credentials

* fix(schedules): require unattended MCP credentials

* fix(schedules): resolve MCP credentials during execution

* refactor(schedules): inject unattended credentials

* fix(schedules): scope renewable credential resolution

* fix: isolate lazy scheduled OBO credentials across MCP lifecycle

* fix: preserve MCP cancellation and retryable credential lookup

* fix: bind MCP cancellation to the owning run signal

* test: supply flow manager in OBO cancellation regression

* fix: preserve MCP cancellation across exchange and API ingress

* style: sort MCP manager imports

* fix: propagate cancellation through agent discovery

* test: preserve agent discovery edge literals

* fix: propagate agent initialization cancellation

* fix: expose initialization signal in OpenAI adapter
This commit is contained in:
Danny Avila 2026-09-14 10:27:47 -04:00 • committed by GitHub
parent b204216c64
commit 345cf8877f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
40 changed files with 1705 additions and 176 deletions

View file

@ -421,8 +421,9 @@ jest.mock('~/cache', () => ({
jest.mock('~/server/services/ToolService', () => ({
loadAgentTools: jest.fn().mockResolvedValue([]),
loadToolsForExecution: jest.fn().mockResolvedValue([]),
isFatalAgentInitializationError: (error) =>
isFatalAgentInitializationError: jest.fn((error) =>
['AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE', 'resource_recovery_required'].includes(error?.code),
),
}));
const mockGetMultiplier = jest.fn().mockReturnValue(1);
@ -630,6 +631,7 @@ describe('OpenAIChatCompletionController', () => {
expect.objectContaining({
primaryConfig,
rootConfigs: [primaryConfig],
signal: mockExecution.signal,
resourceType: ResourceType.REMOTE_AGENT,
memoryAvailable: true,
}),
@ -1435,6 +1437,9 @@ describe('OpenAIChatCompletionController', () => {
await OpenAIChatCompletionController(req, res);
expect(res.status).toHaveBeenCalledWith(503);
expect(
require('~/server/services/ToolService').isFatalAgentInitializationError,
).toHaveBeenCalledWith(toolError, { signal: loadAgentTools.mock.calls.at(-1)[0].signal });
});
it('returns the resource recovery status and code before model invocation', async () => {

View file

@ -462,8 +462,9 @@ jest.mock('@librechat/api', () => ({
jest.mock('~/server/services/ToolService', () => ({
loadAgentTools: jest.fn().mockResolvedValue([]),
loadToolsForExecution: jest.fn().mockResolvedValue([]),
isFatalAgentInitializationError: (error) =>
isFatalAgentInitializationError: jest.fn((error) =>
['AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE', 'resource_recovery_required'].includes(error?.code),
),
}));
const mockGetMultiplier = jest.fn().mockReturnValue(1);
@ -840,6 +841,7 @@ describe('createResponse controller', () => {
expect.objectContaining({
primaryConfig,
rootConfigs: [primaryConfig],
signal: mockExecution.signal,
resourceType: ResourceType.REMOTE_AGENT,
memoryAvailable: true,
}),
@ -920,6 +922,9 @@ describe('createResponse controller', () => {
'server_error',
'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',
);
expect(
require('~/server/services/ToolService').isFatalAgentInitializationError,
).toHaveBeenCalledWith(toolError, { signal: loadAgentTools.mock.calls.at(-1)[0].signal });
});
it('returns the resource recovery status and code before model invocation', async () => {

View file

@ -144,7 +144,7 @@ function createToolLoader({ req, res, signal, definitionsOnly = true }) {
streamId: null, // No resumable stream for OpenAI compat
});
} catch (error) {
if (isFatalAgentInitializationError(error) || isContentFilterError(error)) {
if (isFatalAgentInitializationError(error, { signal }) || isContentFilterError(error)) {
throw error;
}
logger.error('Error loading tools for agent ' + agentId, getSafeErrorMetadata(error));
@ -627,6 +627,7 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
skillStates,
defaultActiveOnShare,
manualSkills,
signal: execution.signal,
},
dbMethods,
);
@ -663,6 +664,7 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
const discoveryParams = {
req,
res,
signal: execution.signal,
primaryConfig,
endpointOption,
allowedProviders,

View file

@ -196,7 +196,7 @@ function createToolLoader({ req, res, signal, definitionsOnly = true }) {
streamId: null,
});
} catch (error) {
if (isFatalAgentInitializationError(error) || isContentFilterError(error)) {
if (isFatalAgentInitializationError(error, { signal }) || isContentFilterError(error)) {
throw error;
}
logger.error('Error loading tools for agent ' + agentId, getSafeErrorMetadata(error));
@ -883,6 +883,7 @@ const executeResponse = async (envelope, { req, res }) => {
skillStates,
defaultActiveOnShare,
manualSkills,
signal: execution.signal,
},
dbMethods,
);
@ -919,6 +920,7 @@ const executeResponse = async (envelope, { req, res }) => {
const discoveryParams = {
req,
res,
signal: execution.signal,
primaryConfig,
endpointOption,
allowedProviders,

View file

@ -66,6 +66,7 @@ const loadAddedAgent = (params) =>
* `codeEnvAvailable`. @see InitializeAgentParams.fileSearchAvailable.
* @param {boolean} [params.statefulSessionsAvailable] - `stateful_code_sessions`
* capability flag; forwarded verbatim alongside `codeEnvAvailable`.
* @param {AbortSignal} [params.signal] - Owning run cancellation signal.
* @returns {Promise<{userMCPAuthMap: Object|undefined}>} The updated userMCPAuthMap
*/
const processAddedConvo = async ({
@ -97,6 +98,7 @@ const processAddedConvo = async ({
toolIntentsAvailable,
statefulSessionsAvailable,
memoryAvailable,
signal,
}) => {
const addedConvo = endpointOption.addedConvo;
if (addedConvo == null) {
@ -200,6 +202,7 @@ const processAddedConvo = async ({
memoryAvailable,
skillStates,
defaultActiveOnShare,
signal,
},
{
getFiles: db.getFiles,
@ -240,7 +243,7 @@ const processAddedConvo = async ({
return { userMCPAuthMap };
} catch (err) {
if (isFatalAgentInitializationError(err)) {
if (isFatalAgentInitializationError(err, { signal })) {
throw err;
}
logger.error('[processAddedConvo] Error processing addedConvo for parallel agent', err);

View file

@ -42,7 +42,8 @@ jest.mock('~/server/services/MCP', () => ({
}));
jest.mock('~/server/services/ToolService', () => ({
isFatalAgentInitializationError: (error) =>
isFatalAgentInitializationError: (error, { signal } = {}) =>
(signal?.aborted === true && (error === signal.reason || error?.name === 'AbortError')) ||
['AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE', 'resource_recovery_required'].includes(error?.code),
}));
@ -173,6 +174,19 @@ describe('processAddedConvo', () => {
await expect(processAddedConvo(baseParams())).rejects.toBe(toolError);
});
it('forwards and propagates owning-run cancellation from added-agent initialization', async () => {
const controller = new AbortController();
const reason = new Error('parallel agent stopped');
controller.abort(reason);
mockInitializeAgent.mockRejectedValueOnce(reason);
await expect(processAddedConvo(baseParams({ signal: controller.signal }))).rejects.toBe(reason);
expect(mockInitializeAgent).toHaveBeenCalledWith(
expect.objectContaining({ signal: controller.signal }),
expect.anything(),
);
});
it('keeps deployment-aware skill metadata on a persisted added-agent config', async () => {
const deploymentSkillId = { toString: () => 'deployment-skill' };
const agentConfigs = new Map();

View file

@ -40,6 +40,7 @@ const {
encodeAndFormatAudios,
encodeAndFormatVideos,
extractFileContext,
createScheduleUpstreamTokenProviderResolver,
} = require('@librechat/api');
const {
ResourceType,
@ -123,6 +124,8 @@ function createToolLoader(
streamId = null,
definitionsOnly = false,
jobCreatedAt,
upstreamTokenProvider,
upstreamTokenProviderResolver,
) {
/**
* @param {object} params
@ -164,9 +167,11 @@ function createToolLoader(
codeExecutionContext,
definitionsOnly,
accessibleMcpServerNames,
upstreamTokenProvider,
upstreamTokenProviderResolver,
});
} catch (error) {
if (isFatalAgentInitializationError(error) || isContentFilterError(error)) {
if (isFatalAgentInitializationError(error, { signal }) || isContentFilterError(error)) {
throw error;
}
logger.error('Error loading tools for agent ' + agentId, error);
@ -185,8 +190,10 @@ function createToolLoader(
* @param {string} [params.checkpointNamespace] Immutable saver-level generation scope
* @param {string} [params.foregroundRunId] Canonical response identity for foreground execution
* @param {import('@librechat/api').MCPRuntimeRequestBody} [params.requestBody]
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider]
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
*/
const initializeClient = async ({
const initializeClientWithProvider = async ({
req,
res,
signal,
@ -195,6 +202,8 @@ const initializeClient = async ({
checkpointNamespace,
foregroundRunId,
requestBody,
upstreamTokenProvider,
upstreamTokenProviderResolver,
}) => {
if (!endpointOption) {
throw new Error('Endpoint option not provided');
@ -463,6 +472,8 @@ const initializeClient = async ({
mcpAvailableTools: ctx.mcpAvailableTools,
requestScopedConnections: ctx.requestScopedConnections,
userMCPAuthMap: ctx.userMCPAuthMap,
upstreamTokenProvider,
upstreamTokenProviderResolver,
tool_resources: ctx.tool_resources,
actionsEnabled: ctx.actionsEnabled,
accessibleMcpServerNames: ctx.accessibleMcpServerNames,
@ -624,7 +635,16 @@ const initializeClient = async ({
const allowedProviders = new Set(appConfig?.endpoints?.[EModelEndpoint.agents]?.allowedProviders);
/** Event-driven mode: only load tool definitions, not full instances */
const loadTools = createToolLoader(req, res, signal, streamId, true, jobCreatedAt);
const loadTools = createToolLoader(
req,
res,
signal,
streamId,
true,
jobCreatedAt,
upstreamTokenProvider,
upstreamTokenProviderResolver,
);
/** @type {Array<MongoFile>} */
const requestFiles = req.body.files ?? [];
/** @type {string | undefined} */
@ -712,6 +732,7 @@ const initializeClient = async ({
skillStates,
defaultActiveOnShare,
manualSkills,
signal,
},
{
getFiles: db.getFiles,
@ -760,6 +781,7 @@ const initializeClient = async ({
{
req,
res,
signal,
primaryConfig,
agent_ids: primaryConfig.agent_ids,
endpointOption,
@ -884,6 +906,7 @@ const initializeClient = async ({
toolIntentsAvailable,
statefulSessionsAvailable,
memoryAvailable,
signal,
});
if (updatedMCPAuthMap) {
@ -1160,7 +1183,7 @@ const initializeClient = async ({
try {
return await loading;
} catch (error) {
if (isFatalAgentInitializationError(error)) {
if (isFatalAgentInitializationError(error, { signal })) {
throw error;
}
logger.error(`[initializeClient] Error loading subagent metadata ${agentId}:`, error);
@ -1248,7 +1271,16 @@ const initializeClient = async ({
req,
res,
agent,
loadTools: createToolLoader(req, res, context.signal, streamId, true, jobCreatedAt),
loadTools: createToolLoader(
req,
res,
context.signal,
streamId,
true,
jobCreatedAt,
upstreamTokenProvider,
upstreamTokenProviderResolver,
),
requestFiles,
authorizedRunFiles: getAuthorizedRunFileSnapshot({
policy: appConfig.endpoints?.agents?.fileSharing,
@ -1277,6 +1309,7 @@ const initializeClient = async ({
memoryAvailable,
skillStates,
defaultActiveOnShare,
signal: context.signal,
},
{
getFiles: db.getFiles,
@ -1461,7 +1494,7 @@ const initializeClient = async ({
graphMemberConfigsById.set(memberId, config);
return config;
} catch (error) {
if (isFatalAgentInitializationError(error)) {
if (isFatalAgentInitializationError(error, { signal })) {
throw error;
}
logger.error(`[initializeClient] Error initializing graph member ${memberId}:`, error);
@ -1834,4 +1867,25 @@ const initializeClient = async ({
return { client, userMCPAuthMap };
};
module.exports = { initializeClient };
/**
* Creates an agent initializer whose host may resolve renewable credentials at
* the execution boundary. The resolver returns a provider closure rather than
* token material so refresh remains owned by the host integration.
*
* @param {object} [dependencies]
* @param {(user: import('@librechat/data-schemas').IUser, options: { signal?: AbortSignal }) => import('@librechat/api').UpstreamTokenProvider | undefined | Promise<import('@librechat/api').UpstreamTokenProvider | undefined>} [dependencies.resolveUpstreamTokenProvider]
*/
function createInitializeClient(dependencies = {}) {
return async (params) => {
const upstreamTokenProviderResolver = createScheduleUpstreamTokenProviderResolver(
params.req,
dependencies.resolveUpstreamTokenProvider,
params.signal,
);
return initializeClientWithProvider({ ...params, upstreamTokenProviderResolver });
};
}
const initializeClient = createInitializeClient();
module.exports = { createInitializeClient, initializeClient };

View file

@ -98,7 +98,7 @@ jest.mock('~/cache', () => ({
logViolation: jest.fn(),
}));
const { initializeClient } = require('./initialize');
const { createInitializeClient, initializeClient } = require('./initialize');
const { processAddedConvo } = require('./addedConvo');
const { getSkillDbMethods, getSkillToolDeps } = require('./skillDeps');
const { loadAgentTools } = require('~/server/services/ToolService');
@ -182,6 +182,53 @@ describe('initializeClient — processAgent ACL gate', () => {
},
});
it('defers host credential resolution during scheduled agent initialization', async () => {
const upstreamTokenProvider = jest.fn();
const resolveUpstreamTokenProvider = jest.fn().mockResolvedValue(upstreamTokenProvider);
const hostInitializeClient = createInitializeClient({ resolveUpstreamTokenProvider });
const req = makeReq();
req._isScheduledFire = true;
const signal = new AbortController().signal;
mockInitializeAgent.mockImplementationOnce(async ({ loadTools, agent }) => {
await loadTools({
tools: ['run_query_mcp_warehouse'],
model: agent.model,
agentId: agent.id,
provider: agent.provider,
});
return makePrimaryConfig([]);
});
await hostInitializeClient({
req,
res: {},
signal,
endpointOption: makeEndpointOption(),
});
expect(resolveUpstreamTokenProvider).not.toHaveBeenCalled();
const toolLoadParams = loadAgentTools.mock.calls[0][0];
expect(toolLoadParams.upstreamTokenProvider).toBeUndefined();
const resolver = toolLoadParams.upstreamTokenProviderResolver;
await expect(resolver({ signal })).resolves.toBe(upstreamTokenProvider);
expect(resolveUpstreamTokenProvider).toHaveBeenCalledWith(req.user, { signal });
});
it('keeps interactive agent initialization independent of the host resolver', async () => {
const resolveUpstreamTokenProvider = jest.fn();
const hostInitializeClient = createInitializeClient({ resolveUpstreamTokenProvider });
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));
await hostInitializeClient({
req: makeReq(),
res: {},
signal: new AbortController().signal,
endpointOption: makeEndpointOption(),
});
expect(resolveUpstreamTokenProvider).not.toHaveBeenCalled();
});
it('replaces untrusted artifact route metadata with the executing agent context', async () => {
mockInitializeAgent.mockResolvedValue(makePrimaryConfig([]));

View file

@ -736,6 +736,7 @@ function resolveToolCallUserId({ effectiveUser, capturedUser, invocationUserId,
* @param {Object} params
* @param {ServerResponse} params.res - The Express response object for sending events.
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO, built at the request boundary so this layer never receives the raw Express request.
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.
* @param {IUser} params.user - The user from the request object.
* @param {string} params.serverName
@ -761,6 +762,7 @@ async function reconnectServer({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
streamId = null,
jobCreatedAt,
@ -829,6 +831,7 @@ async function reconnectServer({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
recoveryPolicy,
oboIdentityContext,
forceNew: true,
@ -859,6 +862,7 @@ async function reconnectServer({
* @param {import('@librechat/api').RequestScopedMCPConnectionStore} [params.requestScopedConnections]
* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap]
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO, built at the request boundary.
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.
* @returns { Promise<Array<typeof tool | { _call: (toolInput: Object | string) => unknown}>> } An object with `_call` method to execute the tool input.
*/
@ -876,6 +880,7 @@ async function createMCPTools({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
streamId = null,
jobCreatedAt,
@ -920,6 +925,7 @@ async function createMCPTools({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
streamId,
jobCreatedAt,
@ -959,6 +965,7 @@ async function createMCPTools({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
config: serverConfig,
});
@ -988,6 +995,7 @@ async function createMCPTools({
* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap]
* @param {import('@librechat/api').ParsedServerConfig} [params.config]
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO, built at the request boundary.
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.
* @param {string} [params.serverName] - Resolved raw MCP server name from tool loading.
* @param {(availableTools: LCAvailableTools) => void} [params.onAvailableTools]
@ -1009,6 +1017,7 @@ async function createMCPTool({
config,
configServers,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
serverName: resolvedServerName,
onAvailableTools,
@ -1141,6 +1150,7 @@ async function createMCPTool({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
streamId,
jobCreatedAt,
@ -1186,6 +1196,7 @@ async function createMCPTool({
serverConfig,
toolDefinition: toolEntry['function'],
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
streamId,
jobCreatedAt,
@ -1207,6 +1218,7 @@ function createToolInstance({
toolDefinition,
provider: capturedProvider,
upstreamTokenProvider: capturedUpstreamTokenProvider = null,
upstreamTokenProviderResolver: capturedUpstreamTokenProviderResolver = null,
oboIdentityContext: capturedOboIdentityContext = null,
streamId = null,
jobCreatedAt,
@ -1337,6 +1349,7 @@ function createToolInstance({
oboTokenResolver: exchangeOboToken,
oboTrustChecker: createOboTrustChecker(),
upstreamTokenProvider: capturedUpstreamTokenProvider,
upstreamTokenProviderResolver: capturedUpstreamTokenProviderResolver,
oboIdentityContext: capturedOboIdentityContext,
});
@ -1350,10 +1363,14 @@ function createToolInstance({
* alerts; the wrapping below still reports it to the turn. The error has
* to look like an abort as well: a permission, OAuth, or upstream failure
* can reject in the same tick as the Stop and must stay visible. */
if (config?.signal?.aborted === true && isAbortError(error)) {
if (
config?.signal?.aborted === true &&
(isAbortError(error) || error === config.signal.reason)
) {
logger.debug(
`[MCP][${serverName}][${toolName}][User: ${userId}] Tool call cancelled by user abort`,
);
throw error;
} else {
logger.error(
`[MCP][${serverName}][${toolName}][User: ${userId}] Error calling MCP tool:`,

View file

@ -1684,6 +1684,51 @@ describe('User parameter passing tests', () => {
);
});
it('preserves AbortError from the MCP tool implementation', async () => {
const mockUser = { id: 'cancel-user', role: 'USER' };
const abortController = new AbortController();
const abort = Object.assign(new Error('Stopped'), { name: 'AbortError' });
const { getRoleByName } = require('~/models');
getRoleByName.mockResolvedValue({
permissions: {
[PermissionTypes.MCP_SERVERS]: {
[Permissions.USE]: true,
},
},
});
mockGetMCPManager.mockReturnValue({
callTool: jest.fn(async () => {
abortController.abort(abort);
throw abort;
}),
});
const mcpTool = await createMCPTool({
user: mockUser,
config: { url: 'https://cancel.example.com/mcp' },
toolKey: `test-tool${D}test-server`,
provider: 'openai',
userMCPAuthMap: {},
availableTools: {
[`test-tool${D}test-server`]: {
function: {
description: 'Cached tool',
parameters: { type: 'object', properties: {} },
},
},
},
});
await expect(
mcpTool.func({}, undefined, {
signal: abortController.signal,
configurable: { user: mockUser },
metadata: { provider: 'openai', thread_id: 'thread-1', run_id: 'run-1' },
toolCall: {},
}),
).rejects.toBe(abort);
});
it('keeps a real failure racing the Stop at error level', async () => {
const mockUser = { id: 'race-user', role: 'USER' };
const mockRes = { write: jest.fn(), flush: jest.fn() };

View file

@ -9,30 +9,44 @@ const { createOboTrustChecker } = require('~/server/services/OboPolicyService');
const { getLogStores } = require('~/cache');
const methods = require('~/models');
module.exports = createScheduleMCPPreflight({
getRoleByName: methods.getRoleByName,
resolveAgentGraphAccess: methods.resolveAgentGraphAccess,
getAgentGraphNodes: methods.getAgentGraphNodes,
getModelsConfig: (user) => getModelsConfig({ user }),
getUser: (id) => methods.findUser({ _id: id }),
getAppConfig,
ensureConfigServers: (config, limit) =>
getMCPServersRegistry().ensureConfigServers(config, limit),
getServerConfigs: (userId, config, role) =>
getMCPServersRegistry().getAllServerConfigs(userId, config, role),
findPluginAuthsByKeys: methods.findPluginAuthsByKeys,
connect: (options) =>
getMCPManager().getConnection({
...options,
flowManager: getFlowStateManager(getLogStores(CacheKeys.FLOWS)),
tokenMethods: {
findToken: methods.findToken,
updateToken: methods.updateToken,
createToken: methods.createToken,
deleteTokens: methods.deleteTokens,
},
graphTokenResolver: getGraphApiToken,
oboTokenResolver: exchangeOboToken,
oboTrustChecker: createOboTrustChecker(),
}),
});
/**
* Builds the schedule MCP preflight with an optional host-owned renewable
* credential resolver. The default application has no durable upstream
* credential source and therefore remains fail-closed for unattended OBO.
*
* @param {object} [options]
* @param {(user: import('@librechat/data-schemas').IUser, options: { signal?: AbortSignal }) => import('@librechat/api').UpstreamTokenProvider | undefined | Promise<import('@librechat/api').UpstreamTokenProvider | undefined>} [options.resolveUpstreamTokenProvider]
*/
function createMCPPreflight(options = {}) {
return createScheduleMCPPreflight({
getRoleByName: methods.getRoleByName,
resolveAgentGraphAccess: methods.resolveAgentGraphAccess,
getAgentGraphNodes: methods.getAgentGraphNodes,
getModelsConfig: (user) => getModelsConfig({ user }),
getUser: (id) => methods.findUser({ _id: id }),
getAppConfig,
ensureConfigServers: (config, limit) =>
getMCPServersRegistry().ensureConfigServers(config, limit),
getServerConfigs: (userId, config, role) =>
getMCPServersRegistry().getAllServerConfigs(userId, config, role),
findPluginAuthsByKeys: methods.findPluginAuthsByKeys,
resolveUpstreamTokenProvider: options.resolveUpstreamTokenProvider,
connect: (connectionOptions) =>
getMCPManager().getConnection({
...connectionOptions,
flowManager: getFlowStateManager(getLogStores(CacheKeys.FLOWS)),
tokenMethods: {
findToken: methods.findToken,
updateToken: methods.updateToken,
createToken: methods.createToken,
deleteTokens: methods.deleteTokens,
},
graphTokenResolver: getGraphApiToken,
oboTokenResolver: exchangeOboToken,
oboTrustChecker: createOboTrustChecker(),
}),
});
}
module.exports = createMCPPreflight();
module.exports.createMCPPreflight = createMCPPreflight;

View file

@ -12,6 +12,7 @@ const {
getToolkitKey,
getUserMCPAuthMap,
createAuthIdentityContext,
selectMCPUpstreamTokenProvider,
loadToolDefinitions,
GenerationJobManager,
isActionDomainAllowed,
@ -783,6 +784,8 @@ const isBuiltInTool = (toolName) =>
* @param {string|null} [params.streamId] - Stream ID for resumable mode
* @param {number} [params.jobCreatedAt] - The generation epoch that owns emitted tool events
* @param {AbortSignal} [params.signal] - Effective run cancellation signal
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider]
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @returns {Promise<{
* toolDefinitions?: import('@librechat/api').LCTool[];
* toolRegistry?: Map<string, import('@librechat/api').LCTool>;
@ -803,6 +806,8 @@ async function loadToolDefinitionsWrapper({
codeExecutionContext,
accessibleMcpServerNames,
signal,
upstreamTokenProvider: suppliedUpstreamTokenProvider,
upstreamTokenProviderResolver,
}) {
if (!agent.tools || agent.tools.length === 0) {
return { toolDefinitions: [] };
@ -988,22 +993,21 @@ async function loadToolDefinitionsWrapper({
/** @type {Record<string, import('@librechat/api').LCAvailableTools>} */
const mcpAvailableTools = {};
const requestScopedConnections = getMCPRequestContext(req, res);
/**
* Build the OBO upstream-token closure once at this request boundary and pass
* the function into MCP handling, so `reinitMCPServer` never receives the raw
* Express request. `res` is forwarded so a rotated refresh token can be
* mirrored to the `refreshToken` cookie when the response is still writable.
*/
const oboIdentityContext = createAuthIdentityContext({
user: req.user,
tenantId: getTenantId(),
});
const upstreamTokenProvider = createOpenIDSessionTokenProvider({
req,
res,
user: req.user,
identityContext: oboIdentityContext,
tokenPreference: 'access_token',
const upstreamTokenProvider = selectMCPUpstreamTokenProvider({
upstreamTokenProvider: suppliedUpstreamTokenProvider,
upstreamTokenProviderResolver,
createSessionProvider: () =>
createOpenIDSessionTokenProvider({
req,
res,
user: req.user,
identityContext: oboIdentityContext,
tokenPreference: 'access_token',
}),
});
const rememberMCPAvailableTools = (serverName, availableTools) => {
if (!availableTools || Object.keys(availableTools).length === 0) {
@ -1182,6 +1186,7 @@ async function loadToolDefinitionsWrapper({
};
const result = await reinitMCPServer({
signal,
user: req.user,
oauthStart,
flowManager,
@ -1191,6 +1196,7 @@ async function loadToolDefinitionsWrapper({
requestBody: runtimeRequestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
recoveryPolicy: appConfig?.mcpSettings?.catalogRecovery,
});
@ -1211,6 +1217,7 @@ async function loadToolDefinitionsWrapper({
}
};
const result = await reinitMCPServer({
signal,
user: req.user,
forceNew: true,
oauthStart,
@ -1221,6 +1228,7 @@ async function loadToolDefinitionsWrapper({
requestBody: runtimeRequestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
recoveryPolicy: appConfig?.mcpSettings?.catalogRecovery,
});
@ -1361,6 +1369,7 @@ async function loadToolDefinitionsWrapper({
}
const result = await reinitMCPServer({
signal,
user: req.user,
serverName,
configServers,
@ -1372,6 +1381,7 @@ async function loadToolDefinitionsWrapper({
oauthEnd: createOAuthEndEmitter(serverName),
connectionTimeout: Time.TWO_MINUTES,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
recoveryPolicy: appConfig?.mcpSettings?.catalogRecovery,
});
@ -1382,16 +1392,19 @@ async function loadToolDefinitionsWrapper({
return { serverName, success: true };
}
return { serverName, success: false };
} catch {
} catch (error) {
if (isFatalAgentInitializationError(error, { signal })) {
throw error;
}
logger.debug('[Tool Definitions] MCP OAuth wait failed for one server');
return { serverName, success: false };
}
});
const results = await Promise.allSettled(oauthWaitPromises);
const results = await Promise.all(oauthWaitPromises);
const successfulServers = results
.filter((r) => r.status === 'fulfilled' && r.value.success)
.map((r) => r.value.serverName);
.filter((result) => result.success)
.map((result) => result.serverName);
if (successfulServers.length > 0) {
logger.info(
@ -1477,7 +1490,7 @@ async function loadToolDefinitionsWrapper({
primedCodeFiles = files;
}
} catch (error) {
if (isFatalAgentInitializationError(error)) {
if (isFatalAgentInitializationError(error, { signal })) {
throw error;
}
logger.error(
@ -1567,6 +1580,8 @@ async function loadToolDefinitionsWrapper({
* @param {boolean} [params.definitionsOnly=true] - When true, returns only serializable
* tool definitions without creating full tool instances. Use for event-driven mode
* where tools are loaded on-demand during execution.
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider]
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
*/
async function loadAgentTools({
req,
@ -1582,6 +1597,8 @@ async function loadAgentTools({
definitionsOnly = true,
codeExecutionContext: providedCodeExecutionContext,
accessibleMcpServerNames,
upstreamTokenProvider,
upstreamTokenProviderResolver,
}) {
if (definitionsOnly) {
try {
@ -1597,10 +1614,12 @@ async function loadAgentTools({
codeExecutionContext: providedCodeExecutionContext,
accessibleMcpServerNames,
signal,
upstreamTokenProvider,
upstreamTokenProviderResolver,
});
} catch (error) {
if (
isFatalAgentInitializationError(error) ||
isFatalAgentInitializationError(error, { signal }) ||
isContentFilterError(error) ||
!agent.tools?.some(isExpectedMCPTool)
) {
@ -1759,6 +1778,8 @@ async function loadAgentTools({
returnMetadata: true,
mcpPermissionContext,
requestScopedConnections: getMCPRequestContext(req, res),
upstreamTokenProvider,
upstreamTokenProviderResolver,
codeExecutionContext,
[Tools.web_search]: webSearchCallbacks,
},
@ -2023,6 +2044,8 @@ async function loadAgentTools({
* @param {Record<string, import('@librechat/api').LCAvailableTools>} [params.mcpAvailableTools] - Run-scoped MCP tool definitions
* @param {import('@librechat/api').RequestScopedMCPConnectionStore} [params.requestScopedConnections] - Run-scoped MCP connections
* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap] - User MCP auth map
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider]
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @param {Object} [params.tool_resources] - Tool resources
* @param {string|null} [params.streamId] - Stream ID for web search callbacks
* @param {number} [params.jobCreatedAt] - The generation epoch that owns emitted tool events
@ -2046,6 +2069,8 @@ async function loadToolsForExecution({
mcpAvailableTools,
requestScopedConnections,
userMCPAuthMap,
upstreamTokenProvider,
upstreamTokenProviderResolver,
tool_resources,
streamId = null,
jobCreatedAt,
@ -2355,6 +2380,8 @@ async function loadToolsForExecution({
* turn already advertised. */
accessibleMcpServerNames,
requestScopedConnections: mcpRequestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
[Tools.web_search]: webSearchCallbacks,
},
webSearch: appConfig?.webSearch,

View file

@ -7,9 +7,7 @@ const {
resolveMCPReinitializeConfig,
requiresEphemeralUserConnection,
getMissingRuntimeBodyPlaceholderFields,
MCPAuthenticationRejectedError,
MCPAuthenticationRefreshError,
OpenIDReauthRequiredError,
isMCPInitializationError,
prepareMCPAuthorizationMutation,
} = require('@librechat/api');
const { CacheKeys, Constants } = require('librechat-data-provider');
@ -43,16 +41,12 @@ const MCP_REINITIALIZE_FAILURE_REASONS = {
INITIALIZATION_FAILED: 'initialization_failed',
};
const isMCPReauthenticationError = (error) =>
error instanceof MCPAuthenticationRejectedError ||
error instanceof MCPAuthenticationRefreshError ||
error instanceof OpenIDReauthRequiredError;
/** Wires application dependencies into the passive, request-local catalog recovery service.
* @param {Object} params
* @param {IUser} params.user
* @param {Array<{ serverName: string, serverConfig: object }>} params.servers
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO discovery, built at the request boundary so this layer never receives the raw Express request.
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.
* @param {AbortSignal} [params.signal] - Cancels queued and in-flight catalog reads when the request ends.
* @param {import('@librechat/api').MCPServerCatalogRecoveryPolicy} [params.recoveryPolicy]
@ -61,6 +55,7 @@ async function loadMCPServerCatalogs({
user,
servers,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
signal,
recoveryPolicy,
@ -96,6 +91,7 @@ async function loadMCPServerCatalogs({
oboTokenResolver: exchangeOboToken,
oboTrustChecker: createOboTrustChecker(),
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
}),
onOAuthCredentialsChanging,
@ -117,6 +113,7 @@ async function loadMCPServerCatalogs({
* @param {Object} params
* @param {IUser} params.user - The user from the request object.
* @param {import('@librechat/api').UpstreamTokenProvider} [params.upstreamTokenProvider] - Live upstream-token closure for OBO connection establishment, built at the request boundary so this layer never receives the raw Express request.
* @param {import('@librechat/api').UpstreamTokenProviderResolver} [params.upstreamTokenProviderResolver]
* @param {import('@librechat/api').AuthIdentityContext} [params.oboIdentityContext] - Non-template-visible OBO identity context built from the real request user.
* @param {string} params.serverName - The name of the MCP server
* @param {boolean} params.returnOnOAuth - Whether to initiate OAuth and return, or wait for OAuth flow to finish
@ -146,6 +143,7 @@ async function reinitMCPServer({
requestBody,
requestScopedConnections,
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
oauthEnd,
recoveryPolicy,
@ -281,12 +279,13 @@ async function reinitMCPServer({
oboTokenResolver: exchangeOboToken,
oboTrustChecker: createOboTrustChecker(),
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
});
logger.info('[MCP Reinitialize] Successfully established connection');
} catch (err) {
if (isMCPReauthenticationError(err)) {
if (isMCPInitializationError(err, signal)) {
throw err;
}
logger.info('[MCP Reinitialize] Connection attempt failed');
@ -322,6 +321,7 @@ async function reinitMCPServer({
oboTokenResolver: exchangeOboToken,
oboTrustChecker: createOboTrustChecker(),
upstreamTokenProvider,
upstreamTokenProviderResolver,
oboIdentityContext,
});
@ -332,7 +332,7 @@ async function reinitMCPServer({
);
}
} catch (error) {
if (isMCPReauthenticationError(error)) {
if (isMCPInitializationError(error, signal)) {
throw error;
}
logger.debug('[MCP Reinitialize] Tool discovery failed');
@ -347,9 +347,9 @@ async function reinitMCPServer({
mcpManager.getToolPublicationGeneration(connection) ?? publicationGeneration;
let snapshot;
if (typeof connection.fetchOrderedToolsSnapshot === 'function') {
snapshot = await connection.fetchOrderedToolsSnapshot();
snapshot = await connection.fetchOrderedToolsSnapshot(undefined, signal);
} else if (typeof connection.fetchToolsSnapshot === 'function') {
snapshot = await connection.fetchToolsSnapshot();
snapshot = await connection.fetchToolsSnapshot(undefined, signal);
} else {
snapshot = { tools: await connection.fetchTools(), complete: true };
}
@ -451,7 +451,7 @@ async function reinitMCPServer({
return result;
} catch (error) {
if (isMCPReauthenticationError(error)) {
if (isMCPInitializationError(error, signal)) {
throw error;
}
logger.error('[MCP Reinitialize] Error loading MCP tools; servers may still be initializing');

View file

@ -314,6 +314,7 @@ describe('reinitMCPServer — customUserVars gating (issue #10969)', () => {
});
it('preserves cached tools when live recovery returns an incomplete snapshot', async () => {
const signal = new AbortController().signal;
const fetchOrderedToolsSnapshot = jest.fn().mockResolvedValue({
tools: [{ name: 'partial', inputSchema: { type: 'object' } }],
complete: false,
@ -325,11 +326,13 @@ describe('reinitMCPServer — customUserVars gating (issue #10969)', () => {
const result = await reinitMCPServer({
user,
serverName,
signal,
serverConfig: { type: 'streamable-http', url: 'https://thingy.example.com/mcp' },
});
expect(result.tools).toBeNull();
expect(fetchOrderedToolsSnapshot).toHaveBeenCalledTimes(1);
expect(fetchOrderedToolsSnapshot).toHaveBeenCalledWith(undefined, signal);
expect(mockUpdateMCPServerTools).not.toHaveBeenCalled();
});
@ -552,6 +555,47 @@ describe('reinitMCPServer — direct bearer authentication outcomes', () => {
}),
).rejects.toBe(rejection);
});
it('propagates cancellation instead of hiding the server tool', async () => {
const abort = new DOMException('Stopped', 'AbortError');
const controller = new AbortController();
controller.abort(abort);
mockGetConnection.mockRejectedValue(abort);
await expect(
reinitMCPServer({
user: { id: 'user-123' },
serverName: 'example-mcp',
signal: controller.signal,
serverConfig: { type: 'streamable-http', url: 'https://mcp.example.com', source: 'yaml' },
}),
).rejects.toBe(abort);
});
it.each([false, true])(
'preserves a typed OBO resolution failure (retryable=%s)',
async (retryable) => {
const { OboTokenResolutionError } = require('@librechat/api');
const rejection = new OboTokenResolutionError(
'session_refresh_failed',
'Sign-in expired.',
retryable,
);
mockGetConnection.mockRejectedValue(rejection);
await expect(
reinitMCPServer({
user: { id: 'user-123' },
serverName: 'private-mcp',
serverConfig: {
type: 'streamable-http',
url: 'https://mcp.example.com',
source: 'yaml',
obo: { scopes: 'api://mcp/.default' },
},
}),
).rejects.toBe(rejection);
},
);
});
describe('reinitMCPServer — runtime BODY placeholder pre-check (issue #14074)', () => {

View file

@ -94,8 +94,17 @@ const mockGetUserMCPAuthMap = jest.fn();
jest.mock('@librechat/api', () => ({
...jest.requireActual('@librechat/api'),
AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE: 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',
isFatalAgentInitializationError: (error) =>
isFatalAgentInitializationError: (error, { signal } = {}) =>
(signal?.aborted === true && (error === signal.reason || error?.name === 'AbortError')) ||
['AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE', 'resource_recovery_required'].includes(error?.code),
selectMCPUpstreamTokenProvider: ({
upstreamTokenProvider,
upstreamTokenProviderResolver,
createSessionProvider,
}) =>
upstreamTokenProviderResolver
? upstreamTokenProvider
: (upstreamTokenProvider ?? createSessionProvider()),
loadToolDefinitions: (...args) => mockLoadToolDefinitions(...args),
getUserMCPAuthMap: (...args) => mockGetUserMCPAuthMap(...args),
createAuthIdentityContext: ({ user, tenantId }) => ({
@ -191,7 +200,6 @@ jest.mock('~/server/services/MCP', () => ({
jest.mock('~/cache', () => ({
getLogStores: jest.fn(() => ({})),
}));
const {
loadAgentTools,
loadToolsForExecution,
@ -1922,6 +1930,55 @@ describe('ToolService - Action Capability Gating', () => {
);
});
it('propagates owning-run cancellation from the pending OAuth fan-out', async () => {
const serverName = 'Google-Workspace';
const authorizationUrl = 'https://auth.example.com/Google-Workspace';
const mcpTool = `${Constants.mcp_all}${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
const res = { writableEnded: false };
const controller = new AbortController();
const reason = new Error('generation stopped');
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockGetServerConfig.mockResolvedValue({
type: 'streamable-http',
url: 'https://demo.librechat.ai/mcp',
requiresOAuth: true,
});
mockGetMCPServerTools.mockResolvedValue(null);
mockFlowManager.getFlowState.mockResolvedValue({
status: 'PENDING',
createdAt: Date.now(),
metadata: { authorizationUrl },
});
mockLoadToolDefinitions.mockImplementation(async (params, deps) => {
await deps.getOrFetchMCPServerTools(params.userId, serverName);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
reinitMCPServer.mockImplementation(
({ signal }) =>
new Promise((_resolve, reject) => {
signal.addEventListener('abort', () => reject(signal.reason), { once: true });
}),
);
const loading = loadAgentTools({
req,
res,
signal: controller.signal,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
});
await new Promise((resolve) => setImmediate(resolve));
controller.abort(reason);
await expect(loading).rejects.toBe(reason);
});
it('should re-emit pending MCP OAuth prompts when selected MCP tools are already concrete', async () => {
const serverName = `Google${Constants.mcp_delimiter}Workspace`;
const authorizationUrl = 'https://auth.example.com/Google-Workspace';
@ -2175,6 +2232,96 @@ describe('ToolService - Action Capability Gating', () => {
);
});
it('uses host-supplied renewable upstream credentials when loading tools', async () => {
const serverName = 'Scheduled-OBO';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
req.body = { conversationId: 'conv-123', messageId: 'msg-123' };
req.user = {
id: 'user_123',
provider: 'openid',
openidId: 'oidc-sub-123',
tenantId: 'tenant-1',
openidIssuer: 'https://issuer.example.com',
};
const scheduledProvider = jest.fn().mockResolvedValue({ access_token: 'renewed-token' });
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockGetServerConfig.mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/obo',
obo: { scopes: 'api://obo/Mcp.Tools.ReadWrite' },
});
mockLoadToolDefinitions.mockImplementation(async (params, dependencies) => {
await dependencies.refreshMCPServerTools(params.userId, serverName);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
reinitMCPServer.mockResolvedValue({ availableTools: {} });
const signal = new AbortController().signal;
await loadAgentTools({
req,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
signal,
upstreamTokenProvider: scheduledProvider,
});
expect(reinitMCPServer).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
forceNew: true,
upstreamTokenProvider: scheduledProvider,
}),
);
});
it('keeps a deferred OBO resolver separate from direct-bearer credentials', async () => {
const serverName = 'Scheduled-OBO';
const mcpTool = `search${Constants.mcp_delimiter}${serverName}`;
const capabilities = [AgentCapabilities.tools];
const req = createMockReq(capabilities);
const upstreamTokenProviderResolver = jest.fn();
mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
mockGetServerConfig.mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/obo',
obo: { scopes: 'api://obo/Mcp.Tools.ReadWrite' },
});
mockLoadToolDefinitions.mockImplementation(async (params, dependencies) => {
await dependencies.refreshMCPServerTools(params.userId, serverName);
return {
toolDefinitions: [],
toolRegistry: new Map(),
hasDeferredTools: false,
};
});
reinitMCPServer.mockResolvedValue({ availableTools: {} });
await loadAgentTools({
req,
agent: { id: 'agent_123', tools: [mcpTool] },
definitionsOnly: true,
upstreamTokenProviderResolver,
});
expect(reinitMCPServer).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
forceNew: true,
upstreamTokenProvider: undefined,
upstreamTokenProviderResolver,
}),
);
expect(upstreamTokenProviderResolver).not.toHaveBeenCalled();
});
it('returns run-scoped MCP tool definitions for request-scoped servers', async () => {
const serverName = 'ClickHouse';
const mcpTool = `list_tables${Constants.mcp_delimiter}${serverName}`;