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
import { logger } from '@librechat/data-schemas';
import { ToolMessage } from '@librechat/agents/langchain/messages';
import { DynamicStructuredTool } from '@librechat/agents/langchain/tools';
import { patchConfig, pickRunnableConfigKeys } from '@langchain/core/runnables';
import { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';
import {
Constants,
buildServerNameAliases,
normalizeServerName,
stripServerNamePrefixes,
} from 'librechat-data-provider';
import type { JsonSchemaType, SubagentExecutionContext } from '@librechat/agents';
import type { Tool } from '@modelcontextprotocol/sdk/types.js';
import type { LCAvailableTools, LCFunctionTool, ParsedServerConfig } from './types';
import type { MCPClientCapabilityProfile } from './capabilities';
import { assertToolApprovalExecution, withToolApprovalTransport } from '~/tools/approval';
import { canUseAppConnection, requiresEphemeralUserConnection } from './utils';
import { normalizeJsonSchema, resolveJsonSchemaRefs } from './zod';
import { STANDARD_MCP_CAPABILITY_PROFILE } from './capabilities';
import { getMCPToolCatalogGeneration } from './toolsChanged';
import { isMCPToolResultError } from './status';
import { isToolHiddenFromModel } from './apps';
type DynamicStructuredToolFields = ConstructorParameters<typeof DynamicStructuredTool>[0];
type DynamicStructuredToolFunction = DynamicStructuredToolFields['func'];
export function createMCPStructuredTool(
func: (
input: Parameters<DynamicStructuredToolFunction>[0],
config?: Parameters<DynamicStructuredToolFunction>[2],
) => ReturnType<DynamicStructuredToolFunction>,
fields: Omit<DynamicStructuredToolFields, 'func'>,
): DynamicStructuredTool<unknown> {
const tool = new DynamicStructuredTool({
...fields,
func: async (input, runManager, config) => {
const invocation = config as typeof config & {
toolCall?: { id?: string };
configurable?: { __librechatBackgroundToolInvocation?: boolean };
metadata?: {
executingAgentId?: string;
activeAgentId?: string;
agentId?: string;
executionContext?: SubagentExecutionContext;
};
};
const approvalInvocation = await assertToolApprovalExecution(tool, invocation);
const childConfig = patchConfig(config, { callbacks: runManager?.getChild() });
const result = await AsyncLocalStorageProviderSingleton.runWithConfig(
pickRunnableConfigKeys(childConfig),
() =>
withToolApprovalTransport(invocation, () => func(input, childConfig), approvalInvocation),
);
if (Array.isArray(result) && result.length === 2 && isMCPToolResultError(result)) {
return [
new ToolMessage({
content: result[0],
artifact: result[1],
status: 'error',
tool_call_id: invocation?.toolCall?.id ?? '',
name: fields.name,
}),
result[1],
];
}
return result;
},
});
return tool;
}
/** `_meta` carries the MCP Apps `ui.visibility` used to hide app-only tools from the model. */
export type MCPToolInput = Pick<Tool, 'name' | 'description'> &
Partial<Pick<Tool, 'inputSchema' | '_meta'>>;
export interface MCPToolCacheDeps {
getCachedTools: (options?: {
userId?: string;
serverName?: string;
configGeneration?: string;
allowLegacyMigration?: boolean;
}) => Promise<LCAvailableTools | null>;
updateCachedGlobalTools?: (
update: (tools: LCAvailableTools) => LCAvailableTools,
) => Promise<void>;
setCachedTools: (
tools: LCAvailableTools,
options?: { userId?: string; serverName?: string; configGeneration?: string },
) => Promise<boolean>;
setCachedToolsIfCurrent?: (
tools: LCAvailableTools,
options: {
userId: string;
serverName: string;
configGeneration: string;
publicationGeneration: string;
},
) => Promise<boolean>;
getCachedAppServerTools: (
serverName: string,
configGeneration: string,
) => Promise<LCAvailableTools | null>;
setCachedAppServerTools: (
serverName: string,
configGeneration: string,
tools: LCAvailableTools,
publicationRevision?: string,
) => Promise<boolean>;
getServerConfig: (serverName: string, userId?: string) => Promise<ParsedServerConfig | undefined>;
getAllServerConfigs?: () => Promise<Record<string, ParsedServerConfig>>;
isAppServerConfig?: (serverName: string, effectiveConfig: ParsedServerConfig) => Promise<boolean>;
}
export interface MCPToolCacheService {
updateMCPServerTools: (params: {
userId?: string;
serverName: string;
tools: MCPToolInput[] | null;
serverConfig?: ParsedServerConfig;
publicationGeneration?: string;
publicationRevision?: string;
capabilityProfile?: MCPClientCapabilityProfile;
}) => Promise<LCAvailableTools | null>;
syncStaticTools: (staticTools: LCAvailableTools) => Promise<void>;
mergeAppTools: (appTools: LCAvailableTools, staticTools: LCAvailableTools) => Promise<void>;
replaceAppServerTools: (params: {
serverName: string;
serverTools: LCAvailableTools;
publicationGeneration?: string;
publicationRevision?: string;
}) => Promise<boolean>;
cacheMCPServerTools: (params: {
userId: string;
serverName: string;
serverTools: LCAvailableTools;
serverConfig?: ParsedServerConfig;
publicationGeneration?: string;
publicationRevision?: string;
capabilityProfile?: MCPClientCapabilityProfile;
}) => Promise<void>;
getMCPServerTools: (
userId: string,
serverName: string,
serverConfig?: ParsedServerConfig,
capabilityProfile?: MCPClientCapabilityProfile,
) => Promise<LCAvailableTools | null>;
}
/** Converts an MCP tools/list response into LibreChat's server-qualified catalog format. */
export function formatMCPServerTools(serverName: string, tools: MCPToolInput[]): LCAvailableTools {
const serverTools: LCAvailableTools = {};
const keyServerName = normalizeServerName(serverName);
const keyToolNames = stripServerNamePrefixes(
tools.map((tool) => tool.name),
keyServerName,
);
for (const tool of tools) {
if (isToolHiddenFromModel(tool)) {
continue;
}
const keyToolName = keyToolNames.get(tool.name) ?? tool.name;
const name = `${keyToolName}${Constants.mcp_delimiter}${keyServerName}`;
const entry: LCFunctionTool = {
type: 'function',
['function']: {
name,
description: tool.description ?? '',
parameters: tool.inputSchema
? (normalizeJsonSchema(resolveJsonSchemaRefs(tool.inputSchema)) as JsonSchemaType)
: ({ type: 'object', properties: {} } as JsonSchemaType),
},
};
if (keyToolName !== tool.name) {
entry.serverToolName = tool.name;
}
serverTools[name] = entry;
}
return serverTools;
}
interface AppServerBoundary {
serverName: string;
suffix: string;
}
export function createMCPToolCacheService(deps: MCPToolCacheDeps): MCPToolCacheService {
const {
getCachedTools,
updateCachedGlobalTools,
setCachedTools,
setCachedToolsIfCurrent,
getCachedAppServerTools,
setCachedAppServerTools,
getServerConfig,
getAllServerConfigs,
isAppServerConfig,
} = deps;
async function writeCachedTools(
tools: LCAvailableTools,
options?: { userId?: string; serverName?: string; configGeneration?: string },
): Promise<void> {
const success = options ? await setCachedTools(tools, options) : await setCachedTools(tools);
if (success === false) {
throw new Error('Tool cache rejected the write');
}
}
async function isAppSharedConfig(
serverName: string,
config: ParsedServerConfig | undefined,
): Promise<boolean> {
if (!config || !canUseAppConnection(config)) {
return false;
}
if (isAppServerConfig) {
return isAppServerConfig(serverName, config);
}
if (!getAllServerConfigs) {
return true;
}
try {
const appConfigs = await getAllServerConfigs();
return appConfigs[serverName] != null;
} catch {
logger.debug('[MCP Cache] Could not verify app ownership; using user scope');
return false;
}
}
async function resolveCacheConfig(
userId: string | undefined,
serverName: string,
serverConfig?: ParsedServerConfig,
): Promise<ParsedServerConfig | undefined> {
if (serverConfig) {
return serverConfig;
}
try {
return await getServerConfig(serverName, userId);
} catch (error) {
logger.debug(
`[MCP Cache] Could not resolve config for ${serverName} (user: ${userId}), preserving legacy cache scope:`,
error,
);
return undefined;
}
}
function buildAppServerBoundaries(serverNames: readonly string[]): AppServerBoundary[] {
const names = Array.from(new Set(serverNames));
const boundaryOwners = new Map<string, string>();
for (const rawName of names) {
if (normalizeServerName(rawName) !== rawName) {
boundaryOwners.set(`${Constants.mcp_delimiter}${rawName}`, rawName);
}
}
for (const [normalizedName, rawName] of buildServerNameAliases(names)) {
boundaryOwners.set(`${Constants.mcp_delimiter}${normalizedName}`, rawName);
}
return Array.from(boundaryOwners, ([suffix, rawName]) => ({
serverName: rawName,
suffix,
})).sort((left, right) => right.suffix.length - left.suffix.length);
}
async function getAppServerNames(): Promise<string[]> {
if (!getAllServerConfigs) {
return [];
}
return Object.entries(await getAllServerConfigs())
.filter(([, config]) => canUseAppConnection(config))
.map(([name]) => name);
}
async function getAppServerBoundaries(serverName: string): Promise<AppServerBoundary[]> {
const names = await getAppServerNames();
if (!names.includes(serverName)) {
names.push(serverName);
}
return buildAppServerBoundaries(names);
}
function resolveToolServerName(
toolName: string,
boundaries: readonly AppServerBoundary[],
): string | null {
for (const boundary of boundaries) {
if (toolName.endsWith(boundary.suffix)) {
return boundary.serverName;
}
}
return null;
}
function getAppServerSlice(
tools: LCAvailableTools,
serverName: string,
boundaries: readonly AppServerBoundary[],
): LCAvailableTools {
return Object.fromEntries(
Object.entries(tools).filter(
([name]) => resolveToolServerName(name, boundaries) === serverName,
),
);
}
async function updateMCPServerTools(params: {
userId?: string;
serverName: string;
tools: MCPToolInput[] | null;
serverConfig?: ParsedServerConfig;
publicationGeneration?: string;
publicationRevision?: string;
capabilityProfile?: MCPClientCapabilityProfile;
}): Promise<LCAvailableTools | null> {
const { userId, serverName, tools, serverConfig, publicationGeneration, publicationRevision } =
params;
const capabilityProfile = params.capabilityProfile ?? STANDARD_MCP_CAPABILITY_PROFILE;
try {
if (tools == null) {
logger.debug('[MCP Cache] No tools to update');
return {};
}
/** Cache keys are model-facing and must match runtime tool instance names. */
const serverTools = formatMCPServerTools(serverName, tools);
const resolvedConfig = await resolveCacheConfig(userId, serverName, serverConfig);
const configGeneration = resolvedConfig
? getMCPToolCatalogGeneration(resolvedConfig, capabilityProfile)
: undefined;
if (resolvedConfig && requiresEphemeralUserConnection(resolvedConfig)) {
logger.debug(`[MCP Cache] Built ${tools.length} request-scoped tool(s) without caching`);
return serverTools;
}
if (
userId &&
(capabilityProfile !== STANDARD_MCP_CAPABILITY_PROFILE ||
!(await isAppSharedConfig(serverName, resolvedConfig)))
) {
if (setCachedToolsIfCurrent) {
if (!publicationGeneration || !configGeneration) {
logger.debug('[MCP Cache] Skipped unfenced or unaddressed tool publication');
return null;
}
const current = await setCachedToolsIfCurrent(serverTools, {
userId,
serverName,
configGeneration,
publicationGeneration,
});
if (!current) {
logger.debug('[MCP Cache] Ignored stale tool publication');
return null;
}
} else {
await writeCachedTools(serverTools, { userId, serverName, configGeneration });
}
} else {
const appConfigGeneration =
userId == null
? (publicationGeneration ?? configGeneration)
: (configGeneration ?? publicationGeneration);
/** Only the shared catalog write needs ordering. These tools were just read from the
* server, so the caller should still serve them; discarding a correct tool list because
* its write could not be ordered is what makes a cache failure look to the user like a
* server with no tools at all (#14857). A superseded write is different — another
* replica holds something newer — and still discards below. */
if (!publicationRevision) {
logger.warn(
`[MCP Cache] Serving ${tools.length} unpublished tools for ${serverName}: this snapshot reserved no revision, so every request re-fetches them`,
);
return serverTools;
}
const replaced = await replaceAppServerTools({
serverName,
serverTools,
publicationGeneration: appConfigGeneration,
publicationRevision,
});
if (!replaced) {
return null;
}
}
logger.debug(`[MCP Cache] Updated ${tools.length} server tool(s)`);
return serverTools;
} catch (error) {
logger.error('[MCP Cache] Failed to update server tools');
throw error;
}
}
async function mergeAppTools(
appTools: LCAvailableTools,
staticTools: LCAvailableTools,
): Promise<void> {
try {
const count = Object.keys(appTools).length;
const appConfigs = getAllServerConfigs
? Object.entries(await getAllServerConfigs()).filter(([, config]) =>
canUseAppConnection(config),
)
: [];
const boundaries = buildAppServerBoundaries(appConfigs.map(([serverName]) => serverName));
await syncStaticTools(staticTools);
await Promise.all(
appConfigs
.filter(([, config]) => config.toolFunctions != null)
.map(async ([serverName, config]) => {
const serverTools = getAppServerSlice(appTools, serverName, boundaries);
const configGeneration = getMCPToolCatalogGeneration(
config,
STANDARD_MCP_CAPABILITY_PROFILE,
);
await setCachedAppServerTools(serverName, configGeneration, serverTools);
}),
);
logger.debug(`Synchronized ${count} app-level MCP tools`);
} catch (error) {
logger.error('Failed to merge app-level tools:', error);
throw error;
}
}
async function syncStaticTools(staticTools: LCAvailableTools): Promise<void> {
await updateCachedGlobalTools?.(() => staticTools);
}
/**
* Replaces one server's configuration-addressed app-level snapshot. Old and new replicas may
* publish concurrently without overwriting each other; readers select the current config key.
*/
async function replaceAppServerTools(params: {
serverName: string;
serverTools: LCAvailableTools;
publicationGeneration?: string;
publicationRevision?: string;
}): Promise<boolean> {
const { serverName, serverTools, publicationGeneration, publicationRevision } = params;
try {
const boundaries = await getAppServerBoundaries(serverName);
for (const name of Object.keys(serverTools)) {
const owner = resolveToolServerName(name, boundaries);
if (owner && owner !== serverName) {
throw new Error(`Tool ${name} belongs to app server ${owner}, not ${serverName}`);
}
}
let configGeneration = publicationGeneration;
if (!configGeneration) {
const config = await resolveCacheConfig(undefined, serverName);
configGeneration = config
? getMCPToolCatalogGeneration(config, STANDARD_MCP_CAPABILITY_PROFILE)
: undefined;
}
/** Discarding a publication is warned, not debugged: #14857 was invisible for a release
* because the only trace of a dropped app catalog was a debug line no deployment runs.
* A drop here means this server's tools are missing for every agent that needs them. */
if (!configGeneration) {
logger.warn(
`[MCP Cache] Skipped unaddressed app-level publication for ${serverName}; its tools stay unavailable to agents`,
);
return false;
}
/** Ordering is reserved before the `tools/list` that produced these tools and travels with
* the snapshot, so a publisher that lost it fetched at an unknown time and cannot be
* ordered against concurrent replicas. Allocating one here instead would let a slow fetch
* of an old catalog outrank a newer one that reserved after it started. */
if (!publicationRevision) {
logger.warn(
`[MCP Cache] Skipped unordered app-level publication for ${serverName}: its snapshot carried no reserved revision, so its tools stay unavailable to agents`,
);
return false;
}
const replaced = await setCachedAppServerTools(
serverName,
configGeneration,
serverTools,
publicationRevision,
);
/** Expected whenever replicas publish concurrently: the winner already holds newer tools. */
if (replaced === false) {
logger.debug(
`[MCP Cache] Ignored superseded app-level tools for ${serverName} at revision ${publicationRevision}`,
);
return false;
}
logger.debug(
`[MCP Cache] Replaced app-level tools for ${serverName} with ${Object.keys(serverTools).length} tool(s)`,
);
return true;
} catch (error) {
logger.error(`[MCP Cache] Failed to replace app-level tools for ${serverName}:`, error);
throw error;
}
}
async function cacheMCPServerTools(params: {
userId: string;
serverName: string;
serverTools: LCAvailableTools;
serverConfig?: ParsedServerConfig;
publicationGeneration?: string;
publicationRevision?: string;
capabilityProfile?: MCPClientCapabilityProfile;
}): Promise<void> {
const {
userId,
serverName,
serverTools,
serverConfig,
publicationGeneration,
publicationRevision,
capabilityProfile = STANDARD_MCP_CAPABILITY_PROFILE,
} = params;
try {
const count = Object.keys(serverTools).length;
const resolvedConfig = await resolveCacheConfig(userId, serverName, serverConfig);
const configGeneration = resolvedConfig
? getMCPToolCatalogGeneration(resolvedConfig, capabilityProfile)
: undefined;
if (resolvedConfig && requiresEphemeralUserConnection(resolvedConfig)) {
logger.debug(`[MCP Cache] Skipped caching ${count} request-scoped tool(s)`);
return;
}
if (
capabilityProfile === STANDARD_MCP_CAPABILITY_PROFILE &&
(await isAppSharedConfig(serverName, resolvedConfig))
) {
const appConfigGeneration =
userId == null
? (publicationGeneration ?? configGeneration)
: (configGeneration ?? publicationGeneration);
const replaced = await replaceAppServerTools({
serverName,
serverTools,
publicationGeneration: appConfigGeneration,
publicationRevision,
});
if (!replaced) {
return;
}
logger.debug('[MCP Cache] Refreshed app-level server tools');
return;
}
if (setCachedToolsIfCurrent) {
if (!publicationGeneration || !configGeneration) {
logger.debug('[MCP Cache] Skipped unfenced or unaddressed discovered tools');
return;
}
const current = await setCachedToolsIfCurrent(serverTools, {
userId,
serverName,
configGeneration,
publicationGeneration,
});
if (!current) {
logger.debug('[MCP Cache] Ignored stale discovered tools');
return;
}
} else {
await writeCachedTools(serverTools, { userId, serverName, configGeneration });
}
logger.debug(`[MCP Cache] Cached ${count} server tool(s)`);
} catch (error) {
logger.error('[MCP Cache] Failed to cache server tools');
throw error;
}
}
/**
* Heals cache entries written before keys embedded the normalized server
* name. The definitions-only loader treats the returned map as
* authoritative — a per-key miss does NOT trigger a reconnect the way the
* instance path does — so a stale raw-keyed entry would make the server's
* tools vanish for up to the cache TTL after rollout. Rewriting at read
* time covers every consumer without a coordinated invalidation; safe
* server names (the common case) return the map untouched.
*/
function normalizeCachedToolKeys(
tools: LCAvailableTools | null,
serverName: string,
): LCAvailableTools | null {
if (!tools) {
return tools;
}
const normalized = normalizeServerName(serverName);
if (normalized === serverName) {
return tools;
}
const legacySuffix = `${Constants.mcp_delimiter}${serverName}`;
let changed = false;
const next: LCAvailableTools = {};
for (const [key, entry] of Object.entries(tools)) {
if (!key.endsWith(legacySuffix)) {
next[key] = entry;
continue;
}
const rebuiltKey = `${key.slice(0, key.length - serverName.length)}${normalized}`;
next[rebuiltKey] = {
...entry,
['function']: { ...entry['function'], name: rebuiltKey },
};
changed = true;
}
return changed ? next : tools;
}
async function getMCPServerTools(
userId: string,
serverName: string,
serverConfig?: ParsedServerConfig,
capabilityProfile: MCPClientCapabilityProfile = STANDARD_MCP_CAPABILITY_PROFILE,
): Promise<LCAvailableTools | null> {
const resolvedConfig = await resolveCacheConfig(userId, serverName, serverConfig);
if (resolvedConfig && requiresEphemeralUserConnection(resolvedConfig)) {
return null;
}
try {
if (
capabilityProfile === STANDARD_MCP_CAPABILITY_PROFILE &&
(await isAppSharedConfig(serverName, resolvedConfig))
) {
if (!resolvedConfig) {
return null;
}
const configGeneration = getMCPToolCatalogGeneration(resolvedConfig, capabilityProfile);
const serverTools = await getCachedAppServerTools(serverName, configGeneration);
if (serverTools == null) {
return null;
}
return normalizeCachedToolKeys(serverTools, serverName);
}
const configGeneration = resolvedConfig
? getMCPToolCatalogGeneration(resolvedConfig, capabilityProfile)
: undefined;
const cached =
(await getCachedTools({
userId,
serverName,
configGeneration,
allowLegacyMigration: false,
})) ?? null;
if (!cached) {
return null;
}
return normalizeCachedToolKeys(cached, serverName);
} catch {
logger.error('[MCP Cache] Error fetching cached server tools');
return null;
}
}
return {
updateMCPServerTools,
syncStaticTools,
mergeAppTools,
replaceAppServerTools,
cacheMCPServerTools,
getMCPServerTools,
};
}