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: Reuse Request-Scoped MCP Connections per Run (#13673)
Danny Avila139d61c437e6
diff --git a/api/app/clients/tools/util/handleTools.js b/api/app/clients/tools/util/handleTools.jsindex b29e5bcad1..3f0dc8ab9b 100644--- a/api/app/clients/tools/util/handleTools.js+++ b/api/app/clients/tools/util/handleTools.js@@ -42,6 +42,7 @@ const {createMCPPermissionContext,resolveConfigServers,} = require('~/server/services/MCP');+const { getMCPRequestContext } = require('~/server/services/MCPRequestContext');const { createFileSearchTool, primeFiles: primeSearchFiles } = require('./fileSearch');const { primeFiles: primeCodeFiles } = require('~/server/services/Files/Code/process');const { getUserPluginAuthValue } = require('~/server/services/PluginService');@@ -452,6 +453,8 @@ const loadTools = async ({let index = -1;const failedMCPServers = new Set();const safeUser = createSafeUser(options.req?.user);+ const requestScopedConnections =+ options.requestScopedConnections ?? getMCPRequestContext(options.req, options.res);for (const [serverName, toolConfigs] of Object.entries(requestedMCPTools)) {index++;@@ -470,6 +473,7 @@ const loadTools = async ({userMCPAuthMap,configServers,requestBody: options.req?.body,+ requestScopedConnections,res: options.res,streamId: options.req?._resumableStreamId || null,model: agent?.model ?? model,diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.jsindex ff4d5f6dc9..5d50ae4d9d 100644--- a/api/server/controllers/agents/openai.js+++ b/api/server/controllers/agents/openai.js@@ -348,6 +348,7 @@ const OpenAIChatCompletionController = async (req, res) => {* @type {Map<string, {* agent: object,* toolRegistry?: import('@librechat/agents').LCToolRegistry,+ * requestScopedConnections?: import('@librechat/api').RequestScopedMCPConnectionStore,* userMCPAuthMap?: Record<string, Record<string, string>>,* tool_resources?: object,* actionsEnabled?: boolean,@@ -493,6 +494,7 @@ const OpenAIChatCompletionController = async (req, res) => {signal: abortController.signal,toolRegistry: ctx.toolRegistry,mcpAvailableTools: ctx.mcpAvailableTools,+ requestScopedConnections: ctx.requestScopedConnections,userMCPAuthMap: ctx.userMCPAuthMap,tool_resources: ctx.tool_resources,actionsEnabled: ctx.actionsEnabled,diff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.jsindex 4247c99702..220209fff8 100644--- a/api/server/controllers/agents/responses.js+++ b/api/server/controllers/agents/responses.js@@ -467,6 +467,7 @@ const createResponse = async (req, res) => {* @type {Map<string, {* agent: object,* toolRegistry?: import('@librechat/agents').LCToolRegistry,+ * requestScopedConnections?: import('@librechat/api').RequestScopedMCPConnectionStore,* userMCPAuthMap?: Record<string, Record<string, string>>,* tool_resources?: object,* actionsEnabled?: boolean,@@ -685,6 +686,7 @@ const createResponse = async (req, res) => {signal: abortController.signal,toolRegistry: ctx.toolRegistry,mcpAvailableTools: ctx.mcpAvailableTools,+ requestScopedConnections: ctx.requestScopedConnections,userMCPAuthMap: ctx.userMCPAuthMap,tool_resources: ctx.tool_resources,actionsEnabled: ctx.actionsEnabled,@@ -860,6 +862,7 @@ const createResponse = async (req, res) => {signal: abortController.signal,toolRegistry: ctx.toolRegistry,mcpAvailableTools: ctx.mcpAvailableTools,+ requestScopedConnections: ctx.requestScopedConnections,userMCPAuthMap: ctx.userMCPAuthMap,tool_resources: ctx.tool_resources,actionsEnabled: ctx.actionsEnabled,diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.jsindex 478c6c4e12..eb0655d886 100644--- a/api/server/services/Endpoints/agents/initialize.js+++ b/api/server/services/Endpoints/agents/initialize.js@@ -184,6 +184,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {* agent?: object,* tool_resources?: object,* toolRegistry?: import('@librechat/agents').LCToolRegistry,+ * requestScopedConnections?: import('@librechat/api').RequestScopedMCPConnectionStore,* openAIApiKey?: string* }>}*/@@ -204,6 +205,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {agent: ctx.agent,toolRegistry: ctx.toolRegistry,mcpAvailableTools: ctx.mcpAvailableTools,+ requestScopedConnections: ctx.requestScopedConnections,userMCPAuthMap: ctx.userMCPAuthMap,tool_resources: ctx.tool_resources,actionsEnabled: ctx.actionsEnabled,diff --git a/api/server/services/Endpoints/agents/skillDeps.js b/api/server/services/Endpoints/agents/skillDeps.jsindex f47541bf05..83d287fc08 100644--- a/api/server/services/Endpoints/agents/skillDeps.js+++ b/api/server/services/Endpoints/agents/skillDeps.js@@ -266,6 +266,7 @@ function buildSkillPrimedIdsByName(manualSkillPrimes, alwaysApplySkillPrimes) {* @param {object} params.agent* @param {object} params.config* @param {Record<string, import('@librechat/api').LCAvailableTools>} [params.config.mcpAvailableTools]+ * @param {import('@librechat/api').RequestScopedMCPConnectionStore} [params.config.requestScopedConnections]* @returns {object}*/function buildAgentToolContext({ agent, config }) {@@ -273,6 +274,7 @@ function buildAgentToolContext({ agent, config }) {agent,toolRegistry: config.toolRegistry,mcpAvailableTools: config.mcpAvailableTools,+ requestScopedConnections: config.requestScopedConnections,userMCPAuthMap: config.userMCPAuthMap,tool_resources: config.tool_resources,actionsEnabled: config.actionsEnabled,diff --git a/api/server/services/MCP.js b/api/server/services/MCP.jsindex 4c6daa3682..46971a416e 100644--- a/api/server/services/MCP.js+++ b/api/server/services/MCP.js@@ -387,6 +387,7 @@ function createOAuthCallback({ runStepEmitter, runStepDeltaEmitter }) {* @param {number} [params.index]* @param {string | null} [params.streamId] - The stream ID for resumable mode.* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap]+ * @param {import('@librechat/api').RequestScopedMCPConnectionStore} [params.requestScopedConnections]* @param {import('@librechat/api').ParsedServerConfig} [params.serverConfig] - Used to bypass reconnect throttling for request-scoped servers.* @returns { Promise<Array<typeof tool | { _call: (toolInput: Object | string) => unknown}>> } An object with `_call` method to execute the tool input.*/@@ -400,6 +401,7 @@ async function reconnectServer({configServers,userMCPAuthMap,requestBody,+ requestScopedConnections,streamId = null,}) {logger.debug(@@ -477,6 +479,7 @@ async function reconnectServer({flowManager,userMCPAuthMap,requestBody,+ requestScopedConnections,forceNew: true,returnOnOAuth: false,connectionTimeout: Time.THIRTY_SECONDS,@@ -507,6 +510,7 @@ async function reconnectServer({* @param {string | null} [params.streamId] - The stream ID for resumable mode.* @param {import('@librechat/api').ParsedServerConfig} [params.config]* @param {import('@librechat/api').RequestBody} [params.requestBody]+ * @param {import('@librechat/api').RequestScopedMCPConnectionStore} [params.requestScopedConnections]* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap]* @returns { Promise<Array<typeof tool | { _call: (toolInput: Object | string) => unknown}>> } An object with `_call` method to execute the tool input.*/@@ -522,6 +526,7 @@ async function createMCPTools({configServers,userMCPAuthMap,requestBody,+ requestScopedConnections,streamId = null,}) {const serverConfig =@@ -560,6 +565,7 @@ async function createMCPTools({configServers,userMCPAuthMap,requestBody,+ requestScopedConnections,streamId,});if (result === null) {@@ -584,6 +590,7 @@ async function createMCPTools({availableTools: result.availableTools,toolKey: `${tool.name}${Constants.mcp_delimiter}${serverName}`,requestBody,+ requestScopedConnections,config: serverConfig,});if (toolInstance) {@@ -608,6 +615,7 @@ async function createMCPTools({* @param {Providers | EModelEndpoint} params.provider - The provider for the tool.* @param {LCAvailableTools} [params.availableTools]* @param {import('@librechat/api').RequestBody} [params.requestBody]+ * @param {import('@librechat/api').RequestScopedMCPConnectionStore} [params.requestScopedConnections]* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap]* @param {import('@librechat/api').ParsedServerConfig} [params.config]* @param {(availableTools: LCAvailableTools) => void} [params.onAvailableTools]@@ -624,6 +632,7 @@ async function createMCPTool({userMCPAuthMap,availableTools,requestBody,+ requestScopedConnections,config,configServers,onAvailableTools,@@ -683,6 +692,7 @@ async function createMCPTool({configServers,userMCPAuthMap,requestBody,+ requestScopedConnections,streamId,});if (result?.availableTools) {@@ -708,6 +718,7 @@ async function createMCPTool({mcpPermissionContext,user,requestBody,+ requestScopedConnections,provider,toolName,serverName,@@ -722,6 +733,7 @@ function createToolInstance({mcpPermissionContext,user: capturedUser = null,requestBody: capturedRequestBody,+ requestScopedConnections: capturedRequestScopedConnections,toolName,serverName,serverConfig: capturedServerConfig,@@ -816,6 +828,8 @@ function createToolInstance({},user: effectiveUser,requestBody: config?.configurable?.requestBody ?? capturedRequestBody,+ requestScopedConnections:+ config?.configurable?.requestScopedConnections ?? capturedRequestScopedConnections,customUserVars,flowManager,tokenMethods: {diff --git a/api/server/services/MCPRequestContext.js b/api/server/services/MCPRequestContext.jsnew file mode 100644index 0000000000..e4e7936d2d--- /dev/null+++ b/api/server/services/MCPRequestContext.js@@ -0,0 +1,69 @@+const { logger } = require('@librechat/data-schemas');++const MCP_REQUEST_CONTEXT = Symbol.for('librechat.mcpRequestContext');++function createMCPRequestContext() {+ return {+ connections: new Map(),+ pending: new Map(),+ cleanupStarted: false,+ };+}++async function cleanupMCPRequestContext(context) {+ if (!context || context.cleanupStarted) {+ return;+ }+ context.cleanupStarted = true;++ const connections = new Set(context.connections.values());+ const pending = Array.from(context.pending.values());+ if (pending.length > 0) {+ const settled = await Promise.allSettled(pending);+ for (const result of settled) {+ if (result.status === 'fulfilled' && result.value) {+ connections.add(result.value);+ }+ }+ }++ await Promise.allSettled(+ Array.from(connections).map(async (connection) => {+ try {+ await connection.disconnect();+ } catch (error) {+ logger.warn('[MCP Request Context] Failed to disconnect request-scoped connection', error);+ }+ }),+ );++ context.connections.clear();+ context.pending.clear();+}++function getMCPRequestContext(req, res) {+ if (!req) {+ return undefined;+ }++ if (!req[MCP_REQUEST_CONTEXT]) {+ const context = createMCPRequestContext();+ req[MCP_REQUEST_CONTEXT] = context;++ const cleanup = () => {+ cleanupMCPRequestContext(context).catch((error) => {+ logger.warn('[MCP Request Context] Cleanup failed', error);+ });+ };+ res?.once?.('finish', cleanup);+ res?.once?.('close', cleanup);+ }++ return req[MCP_REQUEST_CONTEXT];+}++module.exports = {+ cleanupMCPRequestContext,+ createMCPRequestContext,+ getMCPRequestContext,+};diff --git a/api/server/services/ToolService.js b/api/server/services/ToolService.jsindex 8cf71c0c02..52d9f713ad 100644--- a/api/server/services/ToolService.js+++ b/api/server/services/ToolService.js@@ -70,6 +70,7 @@ const { manifestToolMap, toolkits } = require('~/app/clients/tools/manifest');const { createOnSearchResults } = require('~/server/services/Tools/search');const { reinitMCPServer } = require('~/server/services/Tools/mcp');const { createMCPPermissionContext, resolveConfigServers } = require('~/server/services/MCP');+const { getMCPRequestContext } = require('~/server/services/MCPRequestContext');const { recordUsage } = require('~/server/services/Threads');const { loadTools } = require('~/app/clients/tools/util');const { redactMessage } = require('~/config/parsers');@@ -608,6 +609,7 @@ async function loadToolDefinitionsWrapper({ req, res, agent, streamId = null, toconst oauthStepIndexes = new Map();/** @type {Record<string, import('@librechat/api').LCAvailableTools>} */const mcpAvailableTools = {};+ const requestScopedConnections = getMCPRequestContext(req, res);const rememberMCPAvailableTools = (serverName, availableTools) => {if (!availableTools || Object.keys(availableTools).length === 0) {return;@@ -784,6 +786,7 @@ async function loadToolDefinitionsWrapper({ req, res, agent, streamId = null, toconfigServers,userMCPAuthMap,requestBody: req.body,+ requestScopedConnections,});rememberMCPAvailableTools(serverName, result?.availableTools);@@ -1041,6 +1044,7 @@ async function loadToolDefinitionsWrapper({ req, res, agent, streamId = null, toreturn {toolRegistry,mcpAvailableTools,+ requestScopedConnections,userMCPAuthMap,toolContextMap,dynamicToolContextMap,@@ -1167,6 +1171,7 @@ async function loadAgentTools({uploadImageBuffer,returnMetadata: true,mcpPermissionContext,+ requestScopedConnections: getMCPRequestContext(req, res),[Tools.web_search]: webSearchCallbacks,},webSearch: appConfig.webSearch,@@ -1242,6 +1247,7 @@ async function loadAgentTools({if (!hasActionTools) {return {toolRegistry,+ requestScopedConnections: getMCPRequestContext(req, res),userMCPAuthMap,toolContextMap,dynamicToolContextMap,@@ -1260,6 +1266,7 @@ async function loadAgentTools({}return {toolRegistry,+ requestScopedConnections: getMCPRequestContext(req, res),userMCPAuthMap,toolContextMap,dynamicToolContextMap,@@ -1388,6 +1395,7 @@ async function loadAgentTools({return {toolRegistry,+ requestScopedConnections: getMCPRequestContext(req, res),toolContextMap,dynamicToolContextMap,userMCPAuthMap,@@ -1414,6 +1422,7 @@ async function loadAgentTools({* @param {string[]} params.toolNames - Names of tools to load* @param {Map} [params.toolRegistry] - Tool registry* @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 {Object} [params.tool_resources] - Tool resources* @param {string|null} [params.streamId] - Stream ID for web search callbacks@@ -1428,6 +1437,7 @@ async function loadToolsForExecution({toolNames,toolRegistry,mcpAvailableTools,+ requestScopedConnections,userMCPAuthMap,tool_resources,streamId = null,@@ -1435,7 +1445,8 @@ async function loadToolsForExecution({}) {const appConfig = req.config;const allLoadedTools = [];- const configurable = { userMCPAuthMap };+ const mcpRequestScopedConnections = requestScopedConnections ?? getMCPRequestContext(req, res);+ const configurable = { userMCPAuthMap, requestScopedConnections: mcpRequestScopedConnections };const isToolSearch = toolNames.includes(AgentConstants.TOOL_SEARCH);const ptcToolNames = [@@ -1556,6 +1567,7 @@ async function loadToolsForExecution({uploadImageBuffer,returnMetadata: true,mcpAvailableTools,+ requestScopedConnections: mcpRequestScopedConnections,[Tools.web_search]: webSearchCallbacks,},webSearch: appConfig?.webSearch,diff --git a/api/server/services/Tools/mcp.js b/api/server/services/Tools/mcp.jsindex d0b37a0b87..5a2dcf8fcc 100644--- a/api/server/services/Tools/mcp.js+++ b/api/server/services/Tools/mcp.js@@ -24,6 +24,7 @@ const { getLogStores } = require('~/cache');* @param {(authURL: string, options?: { expiresAt?: number }) => Promise<void>} [params.oauthStart]* @param {() => Promise<void>} [params.oauthEnd]* @param {import('@librechat/api').RequestBody} [params.requestBody]+ * @param {import('@librechat/api').RequestScopedMCPConnectionStore} [params.requestScopedConnections]* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap]*/async function reinitMCPServer({@@ -39,6 +40,7 @@ async function reinitMCPServer({flowManager: _flowManager,serverConfig: providedConfig,requestBody,+ requestScopedConnections,oauthEnd,}) {/** @type {MCPConnection | null} */@@ -144,6 +146,7 @@ async function reinitMCPServer({oauthEnd,customUserVars,requestBody,+ requestScopedConnections,connectionTimeout,serverConfig,graphTokenResolver: getGraphApiToken,@@ -265,7 +268,7 @@ async function reinitMCPServer({error,);} finally {- if (connection && ephemeralServer) {+ if (connection && ephemeralServer && !requestScopedConnections) {try {await connection.disconnect();} catch (error) {diff --git a/api/server/services/__tests__/ToolService.spec.js b/api/server/services/__tests__/ToolService.spec.jsindex 80b7e8c317..cd8d05478c 100644--- a/api/server/services/__tests__/ToolService.spec.js+++ b/api/server/services/__tests__/ToolService.spec.js@@ -778,7 +778,7 @@ describe('ToolService - Action Capability Gating', () => {mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));mockGetServerConfig.mockResolvedValue({type: 'streamable-http',- url: 'https://mcp.example.com/{{LIBRECHAT_OPENID_ACCESS_TOKEN}}/mcp',+ url: 'https://mcp.example.com/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',source: 'yaml',});mockGetMCPServerTools.mockResolvedValue(null);diff --git a/packages/api/src/agents/initialize.ts b/packages/api/src/agents/initialize.tsindex 82ca0e4ad3..9dc39176ec 100644--- a/packages/api/src/agents/initialize.ts+++ b/packages/api/src/agents/initialize.ts@@ -24,9 +24,9 @@ import type { GenericTool, LCToolRegistry, ToolMap, LCTool } from '@librechat/agimport type { Response as ServerResponse } from 'express';import type { IMongoFile } from '@librechat/data-schemas';import type { InitializeResultBase, ServerRequest, EndpointDbMethods } from '~/types';+import type { LCAvailableTools, RequestScopedMCPConnectionStore } from '../mcp/types';import type { ResolvedManualSkill, ResolvedAlwaysApplySkill } from './skills';import type { TFilterFilesByAgentAccess } from './resources';-import type { LCAvailableTools } from '../mcp/types';import {injectSkillCatalog,resolveManualSkills,@@ -244,6 +244,8 @@ export type InitializedAgent = Agent & {toolRegistry?: LCToolRegistry;/** Run-scoped MCP tool definitions for request-scoped servers. */mcpAvailableTools?: Record<string, LCAvailableTools>;+ /** Run-scoped MCP connections for request-scoped servers. */+ requestScopedConnections?: RequestScopedMCPConnectionStore;/** Serializable tool definitions for event-driven execution */toolDefinitions?: LCTool[];/** Precomputed flag indicating if any tools have defer_loading enabled (for efficient runtime checks) */@@ -348,6 +350,7 @@ export interface InitializeAgentParams {userMCPAuthMap?: Record<string, Record<string, string>>;toolRegistry?: LCToolRegistry;mcpAvailableTools?: Record<string, LCAvailableTools>;+ requestScopedConnections?: RequestScopedMCPConnectionStore;/** Serializable tool definitions for event-driven mode */toolDefinitions?: LCTool[];hasDeferredTools?: boolean;@@ -880,6 +883,7 @@ export async function initializeAgent(userMCPAuthMap,toolDefinitions: loadedToolDefinitions,mcpAvailableTools,+ requestScopedConnections,hasDeferredTools,actionsEnabled,tools: structuredTools,@@ -891,6 +895,7 @@ export async function initializeAgent(userMCPAuthMap: undefined,toolRegistry: undefined,mcpAvailableTools: undefined,+ requestScopedConnections: undefined,toolDefinitions: [],hasDeferredTools: false,actionsEnabled: undefined,@@ -1196,6 +1201,7 @@ export async function initializeAgent(resendFiles,toolRegistry,mcpAvailableTools,+ requestScopedConnections,tool_resources,userMCPAuthMap,toolDefinitions,diff --git a/packages/api/src/mcp/MCPConnectionFactory.ts b/packages/api/src/mcp/MCPConnectionFactory.tsindex be1639048e..a7808feaab 100644--- a/packages/api/src/mcp/MCPConnectionFactory.ts+++ b/packages/api/src/mcp/MCPConnectionFactory.ts@@ -54,6 +54,7 @@ export class MCPConnectionFactory {protected readonly useSSRFProtection: boolean;protected readonly allowedDomains?: string[] | null;protected readonly allowedAddresses?: string[] | null;+ protected readonly ephemeralConnection: boolean;// OAuth-related properties (only set when useOAuth is true)protected readonly userId?: string;@@ -175,6 +176,7 @@ export class MCPConnectionFactory {oauthTokens,useSSRFProtection: this.useSSRFProtection,allowedAddresses: this.allowedAddresses,+ ephemeralConnection: this.ephemeralConnection,});const oauthHandler = () => {@@ -248,6 +250,7 @@ export class MCPConnectionFactory {oauthTokens: null,useSSRFProtection: this.useSSRFProtection,allowedAddresses: this.allowedAddresses,+ ephemeralConnection: this.ephemeralConnection,});unauthConnection.on('oauthRequired', () => {@@ -299,6 +302,7 @@ export class MCPConnectionFactory {this.useSSRFProtection = basic.useSSRFProtection === true;this.allowedDomains = basic.allowedDomains;this.allowedAddresses = basic.allowedAddresses;+ this.ephemeralConnection = basic.ephemeralConnection === true;this.connectionTimeout = options?.connectionTimeout;this.tenantContext = tenantStorage?.getStore?.();this.tenantId = this.tenantContext?.tenantId ?? getTenantId();@@ -396,6 +400,7 @@ export class MCPConnectionFactory {oauthTokens,useSSRFProtection: this.useSSRFProtection,allowedAddresses: this.allowedAddresses,+ ephemeralConnection: this.ephemeralConnection,});let cleanupOAuthHandlers: (() => void) | null = null;diff --git a/packages/api/src/mcp/MCPManager.ts b/packages/api/src/mcp/MCPManager.tsindex e8663c598e..6b26bc709a 100644--- a/packages/api/src/mcp/MCPManager.ts+++ b/packages/api/src/mcp/MCPManager.ts@@ -350,6 +350,7 @@ Please follow these instructions when using tools from the respective MCP serveroptions,tokenMethods,requestBody,+ requestScopedConnections,flowManager,oauthStart,oauthEnd,@@ -367,6 +368,7 @@ Please follow these instructions when using tools from the respective MCP servertoolArguments?: Record<string, unknown>;options?: RequestOptions;requestBody?: RequestBody;+ requestScopedConnections?: t.RequestScopedMCPConnectionStore;tokenMethods?: TokenMethods;customUserVars?: Record<string, string>;flowManager: FlowStateManager<MCPOAuthTokens | null>;@@ -399,6 +401,7 @@ Please follow these instructions when using tools from the respective MCP serversignal: options?.signal,customUserVars,requestBody,+ requestScopedConnections,serverConfig: providedConfig,});@@ -419,7 +422,8 @@ Please follow these instructions when using tools from the respective MCP server);}const isDbSourced = isUserSourced(rawConfig);- disconnectAfterCall = !!userId && requiresEphemeralUserConnection(rawConfig);+ disconnectAfterCall =+ !!userId && requiresEphemeralUserConnection(rawConfig) && !requestScopedConnections;/** Pre-process Graph token placeholders (async) before the synchronous processMCPEnv pass */const graphProcessedConfig = isDbSourceddiff --git a/packages/api/src/mcp/UserConnectionManager.ts b/packages/api/src/mcp/UserConnectionManager.tsindex 6c02852586..e12720dc01 100644--- a/packages/api/src/mcp/UserConnectionManager.ts+++ b/packages/api/src/mcp/UserConnectionManager.ts@@ -85,6 +85,72 @@ export abstract class UserConnectionManager {);}const ephemeralConnection = config ? requiresEphemeralUserConnection(config) : false;+ const requestScopedConnections = ephemeralConnection+ ? opts.requestScopedConnections+ : undefined;+ if (requestScopedConnections) {+ const requestConnectionKey = `${userId}:${serverName}`;+ const existing = requestScopedConnections.connections.get(requestConnectionKey) as+ | MCPConnection+ | undefined;+ if (existing) {+ if (!config || (config.updatedAt && existing.isStale(config.updatedAt))) {+ await existing.disconnect().catch((error) => {+ logger.warn(+ `[MCP][User: ${userId}][${serverName}] Failed to disconnect stale request-scoped connection`,+ error,+ );+ });+ requestScopedConnections.connections.delete(requestConnectionKey);+ } else if (await existing.isConnected()) {+ logger.debug(`[MCP][User: ${userId}][${serverName}] Reusing request-scoped connection`);+ this.updateUserLastActivity(userId);+ return existing;+ } else {+ requestScopedConnections.connections.delete(requestConnectionKey);+ }+ }++ const pending = requestScopedConnections.pending.get(requestConnectionKey) as+ | Promise<MCPConnection>+ | undefined;+ if (pending) {+ logger.debug(+ `[MCP][User: ${userId}][${serverName}] Joining in-flight request-scoped connection attempt`,+ );+ return pending;+ }++ const pendingOAuth = this.createPendingOAuthState(opts.oauthStart);+ const connectionPromise = this.createUserConnectionInternal(+ {+ ...opts,+ forceNew: true,+ ephemeralConnection: true,+ serverConfig: config,+ oauthStart: this.createPendingOAuthStart(serverName, userId, pendingOAuth),+ },+ userId,+ forceNew === true,+ ).then((connection) => {+ requestScopedConnections.connections.set(requestConnectionKey, connection);+ return connection;+ });++ requestScopedConnections.pending.set(+ requestConnectionKey,+ connectionPromise as Promise<unknown>,+ );++ try {+ return await connectionPromise;+ } finally {+ if (requestScopedConnections.pending.get(requestConnectionKey) === connectionPromise) {+ requestScopedConnections.pending.delete(requestConnectionKey);+ }+ }+ }+const forceNewConnection = forceNew || ephemeralConnection;const clearCooldown = forceNew === true;@@ -406,6 +472,7 @@ export abstract class UserConnectionManager {useSSRFProtection: registry.shouldEnableSSRFProtection(),allowedDomains,allowedAddresses,+ ephemeralConnection,};const useOAuth = requiresOAuthMachinery(runtimeConfig);diff --git a/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts b/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.tsindex fdf9c472ac..73048c7ab3 100644--- a/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts+++ b/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts@@ -167,6 +167,8 @@ describe('MCPConnectionFactory', () => {userId: undefined,oauthTokens: null,useSSRFProtection: false,+ allowedAddresses: undefined,+ ephemeralConnection: false,});expect(mockConnectionInstance.connect).toHaveBeenCalled();});@@ -286,6 +288,8 @@ describe('MCPConnectionFactory', () => {userId: 'user123',oauthTokens: mockTokens,useSSRFProtection: false,+ allowedAddresses: undefined,+ ephemeralConnection: false,});});@@ -380,6 +384,8 @@ describe('MCPConnectionFactory', () => {userId: 'user123',oauthTokens: null,useSSRFProtection: false,+ allowedAddresses: undefined,+ ephemeralConnection: false,});expect(mockLogger.debug).toHaveBeenCalledWith(expect.stringContaining('No existing tokens found or error loading tokens'),diff --git a/packages/api/src/mcp/__tests__/MCPManager.test.ts b/packages/api/src/mcp/__tests__/MCPManager.test.tsindex 04b6ae2ac0..0a0b519f24 100644--- a/packages/api/src/mcp/__tests__/MCPManager.test.ts+++ b/packages/api/src/mcp/__tests__/MCPManager.test.ts@@ -1815,6 +1815,55 @@ describe('MCPManager', () => {expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(2);});+ it('should reuse BODY-scoped connections within a request-scoped connection store', async () => {+ const bodyUrlConfig: t.ParsedServerConfig = {+ type: 'streamable-http',+ url: 'https://api.example.com/messages/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',+ source: 'yaml',+ requiresOAuth: false,+ };+ const requestScopedConnection = {+ isConnected: jest.fn().mockResolvedValue(true),+ } as unknown as MCPConnection;+ const requestScopedConnections: t.RequestScopedMCPConnectionStore = {+ connections: new Map(),+ pending: new Map(),+ };++ mockAppConnections({+ has: jest.fn().mockResolvedValue(false),+ });+ (mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(bodyUrlConfig);+ mockProcessMCPEnv.mockImplementation(({ options, body }) => ({+ ...options,+ ...('url' in options && {+ url: options.url?.replace('{{LIBRECHAT_BODY_MESSAGEID}}', body?.messageId ?? ''),+ }),+ }));+ (MCPConnectionFactory.create as jest.Mock).mockResolvedValue(requestScopedConnection);++ const manager = await MCPManager.createInstance(newMCPServersConfig());+ const first = await manager.getUserConnection({+ serverName,+ user: mockUser,+ requestBody: { messageId: 'message-1' },+ requestScopedConnections,+ });+ const second = await manager.getUserConnection({+ serverName,+ user: mockUser,+ requestBody: { messageId: 'message-1' },+ requestScopedConnections,+ });++ expect(first).toBe(requestScopedConnection);+ expect(second).toBe(requestScopedConnection);+ expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);+ expect(requestScopedConnections.connections.get(`${mockUser.id}:${serverName}`)).toBe(+ requestScopedConnection,+ );+ });+it('should not clear server cooldowns for ephemeral runtime connections', async () => {const bodyUrlConfig: t.ParsedServerConfig = {type: 'streamable-http',diff --git a/packages/api/src/mcp/__tests__/utils.test.ts b/packages/api/src/mcp/__tests__/utils.test.tsindex 199f259434..bd6baa2fa0 100644--- a/packages/api/src/mcp/__tests__/utils.test.ts+++ b/packages/api/src/mcp/__tests__/utils.test.ts@@ -557,26 +557,28 @@ describe('getMissingRuntimeBodyPlaceholderFields', () => {});describe('requiresEphemeralUserConnection', () => {- it('returns true when request-varying placeholders affect oauth_headers', () => {+ it('returns true when BODY placeholders affect oauth_headers', () => {expect(requiresEphemeralUserConnection({source: 'yaml',url: 'https://example.com/mcp',oauth_headers: {- Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',+ 'X-Message': '{{LIBRECHAT_BODY_MESSAGEID}}',},}),).toBe(true);});- it('returns true when request-varying placeholders affect connection fields', () => {+ it('returns true when BODY placeholders affect connection fields', () => {expect(requiresEphemeralUserConnection({source: 'yaml',url: 'https://example.com/messages/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',}),).toBe(true);+ });+ it('does not treat Graph placeholders as request-scoped by themselves', () => {expect(requiresEphemeralUserConnection({source: 'config',@@ -584,16 +586,16 @@ describe('requiresEphemeralUserConnection', () => {GRAPH_TOKEN: '{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}',},}),- ).toBe(true);+ ).toBe(false);});- it('returns true when OpenID token placeholders affect connection fields', () => {+ it('does not treat OpenID token placeholders as request-scoped by themselves', () => {expect(requiresEphemeralUserConnection({source: 'yaml',args: ['--id-token={{LIBRECHAT_OPENID_ID_TOKEN}}'],}),- ).toBe(true);+ ).toBe(false);expect(requiresEphemeralUserConnection({@@ -602,16 +604,15 @@ describe('requiresEphemeralUserConnection', () => {Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',},}),- ).toBe(true);+ ).toBe(false);});- it('returns true when request-varying placeholders affect remote transport headers', () => {+ it('returns true when BODY placeholders affect remote transport headers', () => {expect(requiresEphemeralUserConnection({source: 'yaml',headers: {'X-Message': '{{LIBRECHAT_BODY_MESSAGEID}}',- 'X-Graph': '{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}',},}),).toBe(true);diff --git a/packages/api/src/mcp/connection.ts b/packages/api/src/mcp/connection.tsindex 217a44d89a..2366181684 100644--- a/packages/api/src/mcp/connection.ts+++ b/packages/api/src/mcp/connection.ts@@ -1092,6 +1092,7 @@ interface MCPConnectionParams {oauthTokens?: MCPOAuthTokens | null;useSSRFProtection?: boolean;allowedAddresses?: string[] | null;+ ephemeralConnection?: boolean;}export class MCPConnection extends EventEmitter {@@ -1116,6 +1117,7 @@ export class MCPConnection extends EventEmitter {private oauthRecovery = false;private readonly useSSRFProtection: boolean;private readonly allowedAddresses?: string[] | null;+ private readonly ephemeralConnection: boolean;private readonly proxyConfig?: MCPProxyConfig;iconPath?: string;timeout?: number;@@ -1232,6 +1234,7 @@ export class MCPConnection extends EventEmitter {this.userId = params.userId;this.useSSRFProtection = params.useSSRFProtection === true;this.allowedAddresses = params.allowedAddresses ?? null;+ this.ephemeralConnection = params.ephemeralConnection === true;this.proxyConfig = getMCPProxyConfig(params.serverConfig);this.iconPath = params.serverConfig.iconPath;this.timeout = params.serverConfig.timeout;@@ -2026,8 +2029,13 @@ export class MCPConnection extends EventEmitter {async connect(): Promise<void> {try {- // preserve cycle tracking across reconnects so the circuit breaker can detect rapid cycling- await this.disconnect(false);+ /**+ * Persistent connections preserve cycle tracking across reconnects so the+ * circuit breaker can detect storms. Request-scoped connections are+ * intentionally short-lived per tool call, so their clean lifecycle should+ * not consume the reconnect-storm cycle budget.+ */+ await this.disconnect(this.ephemeralConnection);await this.connectClient();if (!(await this.isConnected())) {throw new Error('Connection not established');diff --git a/packages/api/src/mcp/types/index.ts b/packages/api/src/mcp/types/index.tsindex 253d7c43c2..852dc0b837 100644--- a/packages/api/src/mcp/types/index.ts+++ b/packages/api/src/mcp/types/index.ts@@ -194,6 +194,8 @@ export interface BasicConnectionOptions {dbSourced?: boolean;/** When true, serverConfig has already gone through processMCPEnv for this request */skipEnvProcessing?: boolean;+ /** When true, the connection is intentionally short-lived for a single request/tool call */+ ephemeralConnection?: boolean;}/** User context for placeholder resolution in MCP connections (non-OAuth and OAuth alike) */@@ -201,10 +203,16 @@ export interface UserConnectionContext {user?: IUser;customUserVars?: Record<string, string>;requestBody?: RequestBody;+ requestScopedConnections?: RequestScopedMCPConnectionStore;graphTokenResolver?: GraphTokenResolver;connectionTimeout?: number;}+export interface RequestScopedMCPConnectionStore {+ connections: Map<string, unknown>;+ pending: Map<string, Promise<unknown>>;+}+export interface OAuthStartOptions {expiresAt?: number;}diff --git a/packages/api/src/mcp/utils.ts b/packages/api/src/mcp/utils.tsindex 9d58c10358..12829a93e1 100644--- a/packages/api/src/mcp/utils.ts+++ b/packages/api/src/mcp/utils.ts@@ -5,7 +5,6 @@ import type { RequestBody } from '~/types';export const mcpToolPattern: RegExp = new RegExp(`^.+${Constants.mcp_delimiter}.+$`);const RUNTIME_CONTEXT_PLACEHOLDER_PATTERN = /\{\{LIBRECHAT_(?:USER|OPENID|GRAPH|BODY)_[^}]+\}\}/;-const EPHEMERAL_CONNECTION_PLACEHOLDER_PATTERN = /\{\{LIBRECHAT_(?:OPENID|GRAPH|BODY)_[^}]+\}\}/;const RUNTIME_BODY_PLACEHOLDER_PATTERN = /\{\{LIBRECHAT_BODY_[^}]+\}\}/;const RUNTIME_BODY_PLACEHOLDER_CAPTURE_PATTERN = /\{\{LIBRECHAT_BODY_([^}]+)\}\}/g;@@ -76,10 +75,6 @@ function hasRuntimeContextPlaceholder(value: PlaceholderValue): boolean {return hasPlaceholder(value, RUNTIME_CONTEXT_PLACEHOLDER_PATTERN);}-function hasEphemeralConnectionPlaceholder(value: PlaceholderValue): boolean {- return hasPlaceholder(value, EPHEMERAL_CONNECTION_PLACEHOLDER_PATTERN);-}-function hasPlaceholder(value: PlaceholderValue, pattern: RegExp): boolean {if (typeof value === 'string') {return pattern.test(value);@@ -176,19 +171,25 @@ export function getMissingRuntimeBodyPlaceholderFields(}/**- * `GRAPH` and `BODY` placeholders can change per request. If they affect the- * connection-defining parts of a config, the normal userId:serverName cache- * would reuse a connection built with stale request context.+ * `BODY` placeholders vary by chat request, so the normal userId:serverName+ * cache would reuse a connection built with stale request context.** Ephemeral connections are created and torn down per tool call — configs using* these placeholders pay a full connect + initialize on every invocation.+ *+ * User/OpenID/Graph placeholders still require user-scoped connections, but they+ * are not request-scoped by themselves. HTTP transports refresh resolved headers+ * before each tool call, so token/user headers can remain on the cached user+ * connection without forcing a reconnect for every invocation.*/export function requiresEphemeralUserConnection(config: UserScopedConnectionConfig): boolean {if (isUserSourced(config)) {return false;}- return placeholderBearingFields(config).some(hasEphemeralConnectionPlaceholder);+ return placeholderBearingFields(config).some((value) =>+ hasPlaceholder(value, RUNTIME_BODY_PLACEHOLDER_PATTERN),+ );}/**