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: Resolve MCP Server Instructions for Startup-Deferred Servers (#15361)
Danny Avila29b3e2ef3eba
diff --git a/packages/api/src/mcp/UserConnectionManager.ts b/packages/api/src/mcp/UserConnectionManager.tsindex 9d3ab98071..5d6dd40f38 100644--- a/packages/api/src/mcp/UserConnectionManager.ts+++ b/packages/api/src/mcp/UserConnectionManager.ts@@ -2,19 +2,20 @@ import { logger } from '@librechat/data-schemas';import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';import type * as t from './types';import {- cancelMCPToolsChanged,- getMCPAppToolsPublicationGeneration,- getMCPToolsChangedGeneration,- notifyMCPToolsChanged,- renewMCPToolsChangedGeneration,-} from '~/mcp/toolsChanged';-import {+ canBackfillSharedServerInstructions,getMissingRuntimeBodyPlaceholderFields,hasRuntimeUrlPlaceholders,isUserSourced,requiresEphemeralUserConnection,requiresOAuthMachinery,} from './utils';+import {+ cancelMCPToolsChanged,+ getMCPAppToolsPublicationGeneration,+ getMCPToolsChangedGeneration,+ notifyMCPToolsChanged,+ renewMCPToolsChangedGeneration,+} from '~/mcp/toolsChanged';import { MCPServersRegistry } from '~/mcp/registry/MCPServersRegistry';import { ConnectionsRepository } from '~/mcp/ConnectionsRepository';import { MCPConnectionFactory } from '~/mcp/MCPConnectionFactory';@@ -25,6 +26,7 @@ import { detectOAuthRequirement } from '~/mcp/oauth';import { isMCPDomainAllowed } from '~/auth/domain';import { MCPConnection } from './connection';import { mcpConfig } from './mcpConfig';+import { isEnabled } from '~/utils';type PendingConnection = {promise: Promise<MCPConnection>;@@ -733,7 +735,8 @@ export abstract class UserConnectionManager {this.userConnections.get(userId)?.set(serverName, connection);}- logger.info(`[MCP][User: ${userId}] Connection successfully established`);+ logger.info(`[MCP][User: ${userId}][${serverName}] Connection successfully established`);+ await this.backfillResolvedInstructions(serverName, config, connection, userId);if (!ephemeralConnection) {await this.updateUserLastActivity(userId);await this.assertToolPublicationLeaseCurrent(connection, userId, serverName, creationGuard);@@ -755,6 +758,65 @@ export abstract class UserConnectionManager {}}+ /**+ * An explicitly startup-deferred, context-independent YAML server has no+ * fetched text until its first live connection. Persist that static text so+ * subsequent context builds include it. OAuth/OBO, user credentials, custom+ * variables, and runtime placeholders stay connection-scoped: their+ * instructions can vary by identity or request and must never enter the+ * shared registry. Best-effort: a failure here must never break connection+ * creation.+ */+ protected async backfillResolvedInstructions(+ serverName: string,+ config: t.ParsedServerConfig | undefined,+ connection: MCPConnection,+ userId: string,+ ): Promise<void> {+ try {+ if (!config || !isEnabled(config.serverInstructions)) {+ return;+ }+ /** Only the YAML tier is writable here, and a config-overlay, user, or plugin+ * server would otherwise spend a cache round-trip per connection to rediscover+ * that. An unset source is left to proceed: it predates per-tier stamping and+ * the registry still resolves it by name. A config-tier override shadowing a+ * YAML base keeps the base's 'yaml' tag (`overlaySource`), so `config` is also+ * passed through for the registry's field-level identity check. */+ if (+ isUserSourced(config) ||+ isPluginSourced(config) ||+ config.source === 'config' ||+ !canBackfillSharedServerInstructions(config)+ ) {+ return;+ }+ const instructions = connection.client.getInstructions();+ if (!instructions) {+ return;+ }+ if (config.resolvedInstructions != null) {+ return;+ }+ const updated = await MCPServersRegistry.getInstance().setResolvedInstructions(+ serverName,+ instructions,+ userId,+ config,+ );+ if (updated) {+ logger.info(+ `[MCP][User: ${userId}][${serverName}] Stored server instructions from live connection`,+ );+ }+ } catch (error) {+ logger.warn(+ `[MCP][User: ${userId}][${serverName}] Failed to store server instructions from live connection`,+ error,+ );+ }+ }+/*** Mirrors the resolution MCPConnectionFactory performs internally* (preProcessGraphTokens + processMCPEnv). Both must stay in sync so thediff --git a/packages/api/src/mcp/__tests__/utils.test.ts b/packages/api/src/mcp/__tests__/utils.test.tsindex 53cb788f29..5c212fdff9 100644--- a/packages/api/src/mcp/__tests__/utils.test.ts+++ b/packages/api/src/mcp/__tests__/utils.test.ts@@ -769,6 +769,26 @@ describe('hasRuntimeContextPlaceholders', () => {).toBe(true);});+ it('detects trusted runtime placeholders introduced by environment expansion', () => {+ const envName = 'MCP_UTILS_RUNTIME_IDENTITY_TEST';+ const previous = process.env[envName];+ process.env[envName] = '{{LIBRECHAT_USER_ID}}';+ try {+ expect(+ hasRuntimeContextPlaceholders({+ source: 'yaml',+ headers: { 'X-User': `\${${envName}}` },+ }),+ ).toBe(true);+ } finally {+ if (previous == null) {+ delete process.env[envName];+ } else {+ process.env[envName] = previous;+ }+ }+ });+it('ignores custom user variable placeholders', () => {expect(hasRuntimeContextPlaceholders({@@ -833,6 +853,26 @@ describe('getMCPRequestScope', () => {).toBe(true);});+ it('tracks BODY placeholders introduced by environment expansion', () => {+ const envName = 'MCP_UTILS_RUNTIME_BODY_TEST';+ const previous = process.env[envName];+ process.env[envName] = '{{LIBRECHAT_BODY_MESSAGEID}}';+ try {+ const config = {+ source: 'yaml' as const,+ headers: { 'X-Message': `\${${envName}}` },+ };+ expect(getMCPRequestScope(config).requestScoped).toBe(true);+ expect(getRuntimeBodyPlaceholderFields(config)).toEqual(['messageId']);+ } finally {+ if (previous == null) {+ delete process.env[envName];+ } else {+ process.env[envName] = previous;+ }+ }+ });+it('ignores BODY placeholders in user-sourced configs', () => {expect(getMCPRequestScope({diff --git a/packages/api/src/mcp/registry/MCPServersRegistry.ts b/packages/api/src/mcp/registry/MCPServersRegistry.tsindex ad2eedf0ef..bd07a3fa01 100644--- a/packages/api/src/mcp/registry/MCPServersRegistry.ts+++ b/packages/api/src/mcp/registry/MCPServersRegistry.ts@@ -11,6 +11,7 @@ import {} from './cache/ServerConfigsCacheFactory';import { MCPInspectionFailedError, isMCPDomainNotAllowedError } from '~/mcp/errors';import { ReadThroughAllCache } from './cache/ReadThroughAllCache';+import { canBackfillSharedServerInstructions } from '~/mcp/utils';import { isPluginSourced, MCP_PLUGIN_SOURCE } from '~/utils/env';import { ReadThroughCache } from './cache/ReadThroughCache';import { MCPServerInspector } from './MCPServerInspector';@@ -144,6 +145,23 @@ function deepEqual(a: unknown, b: unknown): boolean {return true;}+/**+ * True when `candidate` matches `yamlEntry` on every admin-configurable field.+ * Field-wise comparison rather than whole-object equality: inspector-derived+ * fields (`tools`, `updatedAt`, `resolvedInstructions`, ...) may legitimately+ * differ between a stored entry and the effective config a connection used.+ */+function matchesAdminConfigurableFields(+ yamlEntry: t.ParsedServerConfig,+ candidate: t.ParsedServerConfig,+): boolean {+ const yamlRecord = yamlEntry as unknown as Record<string, unknown>;+ const candidateRecord = candidate as unknown as Record<string, unknown>;+ return ADMIN_CONFIGURABLE_FIELDS.every((field) =>+ deepEqual(yamlRecord[field], candidateRecord[field]),+ );+}+const CONFIG_SERVER_INIT_TIMEOUT_MS = (() => {const raw = process.env.MCP_INIT_TIMEOUT_MS;if (raw == null) {@@ -560,6 +578,73 @@ export class MCPServersRegistry {return result;}+ /**+ * Backfills the inspector-derived `resolvedInstructions` for a server whose+ * operator explicitly deferred startup inspection. An enabled+ * `serverInstructions` declaration has no fetched text to resolve in that+ * case. Identity- or request-scoped servers are deliberately rejected:+ * their live instructions cannot safely be stored in a shared config.+ *+ * First write wins: once the stored entry carries any text, later calls are+ * no-ops. Without this, identities racing the first backfill under stale+ * config snapshots would churn the shared copy and rotate the global read+ * caches on every divergence.+ *+ * YAML-tier servers only. Config-overlay servers are cached under+ * config-hash keys and cannot be addressed by name here; DB-backed user+ * servers need an identity-preserving write through mongoose timestamps and+ * the credential-sanitization pipeline, which is its own change. Both are+ * left untouched. An overlaid effective config carries its base's `'yaml'`+ * source tag (`overlaySource`), so `connectedConfig` — the config the+ * delivering connection was actually created from — is compared against the+ * stored entry on every admin-configurable field: text fetched from an+ * overridden endpoint must never be stored as the shared base's.+ *+ * The entry's `updatedAt` is deliberately preserved (the storage `patch`+ * contract): the config identity did not change, and bumping it would mark+ * every live connection for this server stale.+ *+ * @returns true when a stored config was updated.+ */+ public async setResolvedInstructions(+ serverName: string,+ instructions: string,+ userId?: string,+ connectedConfig?: t.ParsedServerConfig,+ ): Promise<boolean> {+ if (!this.cacheConfigsRepo.patch) {+ return false;+ }+ const yamlEntry = await this.cacheConfigsRepo.get(serverName);+ if (+ !yamlEntry ||+ yamlEntry.resolvedInstructions != null ||+ !canBackfillSharedServerInstructions(yamlEntry)+ ) {+ return false;+ }+ if (connectedConfig && !matchesAdminConfigurableFields(yamlEntry, connectedConfig)) {+ logger.debug(+ `[MCPServersRegistry][${serverName}] Connection config differs from the stored YAML entry (config-tier override or stale snapshot); not storing its instructions`,+ );+ return false;+ }+ /** The identity comparison above ran against a snapshot that can lag by the+ * registry cache TTL; passing the validated entry's `updatedAt` makes the+ * store-side patch a compare-and-set, so instructions never land on an+ * entry another replica replaced in between. */+ const patched = await this.cacheConfigsRepo.patch(+ serverName,+ { resolvedInstructions: instructions },+ yamlEntry.updatedAt,+ );+ if (!patched) {+ return false;+ }+ await this.invalidateServerReadCaches(serverName, userId, 'CACHE');+ return true;+ }+/*** Re-inspects a server that previously failed initialization.* Uses the stored stub config to attempt a full inspection and replaces the stub on success.diff --git a/packages/api/src/mcp/registry/ServerConfigsRepositoryInterface.ts b/packages/api/src/mcp/registry/ServerConfigsRepositoryInterface.tsindex 71eac64908..3a855ecf80 100644--- a/packages/api/src/mcp/registry/ServerConfigsRepositoryInterface.ts+++ b/packages/api/src/mcp/registry/ServerConfigsRepositoryInterface.ts@@ -12,6 +12,22 @@ export interface IServerConfigsRepositoryInterface {/** Atomic add-or-update without requiring callers to inspect error messages. */upsert(serverName: string, config: ParsedServerConfig, userId?: string): Promise<void>;+ /**+ * Merges inspector-derived fields into an existing entry WITHOUT bumping+ * `updatedAt`: the config identity is unchanged, and a bump would mark every+ * live connection for the server stale. Returns false when the server is+ * unknown. Optional: DB-backed storage does not implement it yet — an+ * identity-preserving write there has to thread mongoose timestamps and the+ * credential-sanitization pipeline, which is its own change. When the patch+ * includes `resolvedInstructions`, a previously stored value wins so a+ * concurrent first connection cannot replace shared instructions.+ */+ patch?(+ serverName: string,+ fields: Partial<ParsedServerConfig>,+ expectedUpdatedAt?: number,+ ): Promise<boolean>;+//ACL Entry check if remove is possibleremove(serverName: string, userId?: string): Promise<void>;diff --git a/packages/api/src/mcp/registry/__tests__/resolvedInstructionsBackfill.test.ts b/packages/api/src/mcp/registry/__tests__/resolvedInstructionsBackfill.test.tsnew file mode 100644index 0000000000..4239734bc8--- /dev/null+++ b/packages/api/src/mcp/registry/__tests__/resolvedInstructionsBackfill.test.ts@@ -0,0 +1,504 @@+import './helpers/setupCredsEnv';+import { tenantStorage } from '@librechat/data-schemas';+import type { MCPConnection } from '~/mcp/connection';+import type * as t from '~/mcp/types';+import { MCPServersRegistry } from '~/mcp/registry/MCPServersRegistry';+import { UserConnectionManager } from '~/mcp/UserConnectionManager';+import { resolveServerInstructions } from '~/mcp/utils';++jest.mock('~/mcp/registry/db/ServerConfigsDB', () => ({+ ServerConfigsDB: jest.fn().mockImplementation(() => ({+ get: jest.fn().mockResolvedValue(undefined),+ getAll: jest.fn().mockResolvedValue({}),+ add: jest.fn().mockResolvedValue(undefined),+ update: jest.fn().mockResolvedValue(undefined),+ upsert: jest.fn().mockResolvedValue(undefined),+ remove: jest.fn().mockResolvedValue(undefined),+ reset: jest.fn().mockResolvedValue(undefined),+ })),+}));++const mockMongoose = {} as typeof import('mongoose');+const INSTRUCTIONS = 'Prefer $select on list operations. Never invent addresses.';+const FIXED_TIME = 1699564800000;+const RUNTIME_IDENTITY_ENV_NAME = 'MCP_BACKFILL_RUNTIME_IDENTITY_TEST';+const previousRuntimeIdentityEnv = process.env[RUNTIME_IDENTITY_ENV_NAME];++beforeAll(() => {+ process.env[RUNTIME_IDENTITY_ENV_NAME] = '{{LIBRECHAT_USER_ID}}';+});++afterAll(() => {+ if (previousRuntimeIdentityEnv == null) {+ delete process.env[RUNTIME_IDENTITY_ENV_NAME];+ } else {+ process.env[RUNTIME_IDENTITY_ENV_NAME] = previousRuntimeIdentityEnv;+ }+});++/** A YAML server whose startup inspection was deferred, leaving the enabled+ * declaration without fetched text. */+const startupDeferredYamlEntry: t.ParsedServerConfig = {+ type: 'streamable-http',+ url: 'https://mcp.example.com/mcp',+ requiresOAuth: false,+ startup: false,+ serverInstructions: true,+ source: 'yaml',+ updatedAt: FIXED_TIME,+};++const oauthDeferredYamlEntry: t.ParsedServerConfig = {+ ...startupDeferredYamlEntry,+ startup: true,+ requiresOAuth: true,+};++const runtimePlaceholderYamlEntry: t.ParsedServerConfig = {+ ...startupDeferredYamlEntry,+ headers: { 'X-User-Id': '{{LIBRECHAT_USER_ID}}' },+};++const runtimeApiKeyPlaceholderYamlEntry: t.ParsedServerConfig = {+ ...startupDeferredYamlEntry,+ apiKey: {+ source: 'admin',+ authorization_type: 'bearer',+ key: '{{LIBRECHAT_OPENID_ACCESS_TOKEN}}',+ },+};++const envExpandedRuntimeApiKeyPlaceholderYamlEntry: t.ParsedServerConfig = {+ ...startupDeferredYamlEntry,+ apiKey: {+ source: 'admin',+ authorization_type: 'bearer',+ key: `\${${RUNTIME_IDENTITY_ENV_NAME}}`,+ },+};++describe('MCPServersRegistry.setResolvedInstructions', () => {+ let registry: MCPServersRegistry;++ beforeEach(async () => {+ (MCPServersRegistry as unknown as { instance: undefined }).instance = undefined;+ MCPServersRegistry.createInstance(mockMongoose);+ registry = MCPServersRegistry.getInstance();+ await registry.reset();+ });++ it('backfills a YAML-tier server and preserves its updatedAt', async () => {+ const { config: stored } = await registry['cacheConfigsRepo'].add(+ 'deferred_server',+ startupDeferredYamlEntry,+ );++ const updated = await registry.setResolvedInstructions('deferred_server', INSTRUCTIONS);++ expect(updated).toBe(true);+ const config = await registry.getServerConfig('deferred_server');+ expect(config?.resolvedInstructions).toBe(INSTRUCTIONS);+ expect(config?.serverInstructions).toBe(true);+ expect(config?.updatedAt).toBe(stored.updatedAt);+ expect(resolveServerInstructions(config!)).toBe(INSTRUCTIONS);+ });++ it('invalidates the read-through cache so a primed read sees the backfill', async () => {+ await registry['cacheConfigsRepo'].add('deferred_server', startupDeferredYamlEntry);++ const before = await registry.getServerConfig('deferred_server');+ expect(before?.resolvedInstructions).toBeUndefined();++ await registry.setResolvedInstructions('deferred_server', INSTRUCTIONS);++ const after = await registry.getServerConfig('deferred_server');+ expect(after?.resolvedInstructions).toBe(INSTRUCTIONS);+ });++ it('invalidates YAML read-through caches across tenants', async () => {+ await registry['cacheConfigsRepo'].add('deferred_server', startupDeferredYamlEntry);+ const getInTenant = (tenantId: string) =>+ tenantStorage.run({ tenantId }, () => registry.getServerConfig('deferred_server'));++ expect((await getInTenant('tenant-a'))?.resolvedInstructions).toBeUndefined();+ expect((await getInTenant('tenant-b'))?.resolvedInstructions).toBeUndefined();++ await tenantStorage.run({ tenantId: 'tenant-a' }, () =>+ registry.setResolvedInstructions('deferred_server', INSTRUCTIONS, 'user-1'),+ );++ expect((await getInTenant('tenant-b'))?.resolvedInstructions).toBe(INSTRUCTIONS);+ });++ /** `MCPManager.getInstructions` reads through `getAllServerConfigs`, a different+ * read-through cache than `getServerConfig`. Backfilling into a cache the context+ * path never consults would leave the reported bug unfixed. */+ it('reaches the model-context read path through getAllServerConfigs', async () => {+ await registry['cacheConfigsRepo'].add('deferred_server', startupDeferredYamlEntry);++ const primed = await registry.getAllServerConfigs();+ expect(resolveServerInstructions(primed['deferred_server'])).toBeUndefined();++ await registry.setResolvedInstructions('deferred_server', INSTRUCTIONS);++ const after = await registry.getAllServerConfigs();+ expect(resolveServerInstructions(after['deferred_server'])).toBe(INSTRUCTIONS);+ });++ it('is a no-op when the stored instructions already match', async () => {+ await registry['cacheConfigsRepo'].add('deferred_server', startupDeferredYamlEntry);++ await registry.setResolvedInstructions('deferred_server', INSTRUCTIONS);+ const updated = await registry.setResolvedInstructions('deferred_server', INSTRUCTIONS);++ expect(updated).toBe(false);+ });++ it('keeps the first stored text when a later connection delivers different instructions', async () => {+ await registry['cacheConfigsRepo'].add('deferred_server', startupDeferredYamlEntry);++ await registry.setResolvedInstructions('deferred_server', INSTRUCTIONS);+ const updated = await registry.setResolvedInstructions(+ 'deferred_server',+ 'per-identity text for someone else',+ );++ expect(updated).toBe(false);+ const config = await registry.getServerConfig('deferred_server');+ expect(config?.resolvedInstructions).toBe(INSTRUCTIONS);+ });++ it.each([+ ['OAuth', oauthDeferredYamlEntry],+ ['runtime placeholders', runtimePlaceholderYamlEntry],+ ['runtime placeholders in an admin API key', runtimeApiKeyPlaceholderYamlEntry],+ ['env-expanded runtime placeholders', envExpandedRuntimeApiKeyPlaceholderYamlEntry],+ [+ 'configured-oauth-block',+ {+ ...startupDeferredYamlEntry,+ oauth: { authorization_url: 'https://idp.example.com/authorize' },+ } as unknown as t.ParsedServerConfig,+ ],+ [+ 'placeholder-bearing-admin-key',+ {+ ...startupDeferredYamlEntry,+ apiKey: { source: 'admin', authorization_type: 'bearer', key: '{{LIBRECHAT_USER_ID}}' },+ } as unknown as t.ParsedServerConfig,+ ],+ ])('refuses a %s-deferred server at the shared-registry boundary', async (_reason, config) => {+ await registry['cacheConfigsRepo'].add('deferred_server', config);++ const updated = await registry.setResolvedInstructions('deferred_server', INSTRUCTIONS);++ expect(updated).toBe(false);+ expect(+ (await registry.getServerConfig('deferred_server'))?.resolvedInstructions,+ ).toBeUndefined();+ });++ it('stores instructions when the connected config matches the stored YAML entry', async () => {+ await registry['cacheConfigsRepo'].add('deferred_server', startupDeferredYamlEntry);++ const updated = await registry.setResolvedInstructions(+ 'deferred_server',+ INSTRUCTIONS,+ 'user-1',+ {+ ...startupDeferredYamlEntry,+ },+ );++ expect(updated).toBe(true);+ const config = await registry.getServerConfig('deferred_server');+ expect(config?.resolvedInstructions).toBe(INSTRUCTIONS);+ });++ /** A config-tier override shadowing a YAML base keeps the base's 'yaml' source+ * tag (`overlaySource`), so the connection manager's tier guard cannot see it.+ * The shared base entry must not adopt instructions fetched from the+ * override's endpoint. */+ it('refuses instructions delivered by a config-overlaid connection', async () => {+ await registry['cacheConfigsRepo'].add('deferred_server', startupDeferredYamlEntry);++ const updated = await registry.setResolvedInstructions(+ 'deferred_server',+ INSTRUCTIONS,+ 'user-1',+ {+ ...startupDeferredYamlEntry,+ url: 'https://tenant-override.example.com/mcp',+ },+ );++ expect(updated).toBe(false);+ const config = await registry.getServerConfig('deferred_server');+ expect(config?.resolvedInstructions).toBeUndefined();+ });++ it('returns false for an unknown server without a user', async () => {+ const updated = await registry.setResolvedInstructions('missing_server', INSTRUCTIONS);+ expect(updated).toBe(false);+ });++ it('leaves DB-tier user servers untouched (identity-preserving DB write is a follow-up)', async () => {+ const dbRepo = registry['dbConfigsRepo'] as unknown as {+ get: jest.Mock;+ update: jest.Mock;+ };+ dbRepo.get.mockResolvedValue({ ...startupDeferredYamlEntry, source: 'user' });++ const updated = await registry.setResolvedInstructions('db_server', INSTRUCTIONS, 'user-1');++ expect(updated).toBe(false);+ expect(dbRepo.update).not.toHaveBeenCalled();+ });++ it('patch on the cache repo merges fields without bumping updatedAt', async () => {+ const repo = registry['cacheConfigsRepo'];+ await repo.add('deferred_server', startupDeferredYamlEntry);+ const stored = await repo.get('deferred_server');++ const patched = await repo.patch!('deferred_server', { resolvedInstructions: INSTRUCTIONS });++ expect(patched).toBe(true);+ const after = await repo.get('deferred_server');+ expect(after?.resolvedInstructions).toBe(INSTRUCTIONS);+ expect(after?.updatedAt).toBe(stored?.updatedAt);+ expect(await repo.patch!('unknown_server', { resolvedInstructions: INSTRUCTIONS })).toBe(false);+ });++ /** The registry validates config identity against a snapshot that can lag by+ * the cache TTL; the store-side compare-and-set on `updatedAt` is what stops+ * instructions landing on an entry another replica replaced in between. */+ it('refuses a patch whose expectedUpdatedAt no longer matches the entry', async () => {+ const repo = registry['cacheConfigsRepo'];+ await repo.add('deferred_server', startupDeferredYamlEntry);+ const stale = (await repo.get('deferred_server'))!.updatedAt!;+ const nowSpy = jest.spyOn(Date, 'now').mockReturnValue(stale + 5000);+ await repo.update('deferred_server', {+ ...startupDeferredYamlEntry,+ url: 'https://replaced.example.com/mcp',+ });+ nowSpy.mockRestore();++ const patched = await repo.patch!(+ 'deferred_server',+ { resolvedInstructions: INSTRUCTIONS },+ stale,+ );++ expect(patched).toBe(false);+ expect((await repo.get('deferred_server'))?.resolvedInstructions).toBeUndefined();+ });++ it('passes the validated entry updatedAt into the store patch', async () => {+ const repo = registry['cacheConfigsRepo'];+ await repo.add('deferred_server', startupDeferredYamlEntry);+ const stored = await repo.get('deferred_server');+ const patchSpy = jest.spyOn(repo, 'patch');++ const updated = await registry.setResolvedInstructions('deferred_server', INSTRUCTIONS);++ expect(updated).toBe(true);+ expect(patchSpy).toHaveBeenCalledWith(+ 'deferred_server',+ { resolvedInstructions: INSTRUCTIONS },+ stored?.updatedAt,+ );+ });++ it('keeps the first resolved instructions when patches race', async () => {+ const repo = registry['cacheConfigsRepo'];+ await repo.add('deferred_server', startupDeferredYamlEntry);++ await expect(+ repo.patch!('deferred_server', { resolvedInstructions: INSTRUCTIONS }),+ ).resolves.toBe(true);+ await expect(+ repo.patch!('deferred_server', { resolvedInstructions: 'later connection instructions' }),+ ).resolves.toBe(false);+ expect((await repo.get('deferred_server'))?.resolvedInstructions).toBe(INSTRUCTIONS);+ });+});++describe('UserConnectionManager.backfillResolvedInstructions', () => {+ class TestConnectionManager extends UserConnectionManager {}++ let manager: TestConnectionManager;+ let setResolvedInstructions: jest.Mock;++ const connectionWith = (instructions?: string): MCPConnection =>+ ({+ client: { getInstructions: () => instructions },+ }) as unknown as MCPConnection;++ const backfill = (+ config: t.ParsedServerConfig | undefined,+ connection: MCPConnection,+ ): Promise<void> =>+ manager['backfillResolvedInstructions']('deferred_server', config, connection, 'user-1');++ beforeEach(() => {+ manager = new TestConnectionManager();+ setResolvedInstructions = jest.fn().mockResolvedValue(true);+ jest.spyOn(MCPServersRegistry, 'getInstance').mockReturnValue({+ setResolvedInstructions,+ } as unknown as MCPServersRegistry);+ });++ afterEach(() => {+ jest.restoreAllMocks();+ });++ it('persists instructions delivered by the live connection', async () => {+ const config = { ...startupDeferredYamlEntry };+ await backfill(config, connectionWith(INSTRUCTIONS));++ expect(setResolvedInstructions).toHaveBeenCalledWith(+ 'deferred_server',+ INSTRUCTIONS,+ 'user-1',+ config,+ );+ });++ it('does not persist instructions for servers with runtime user placeholders', async () => {+ const config = { ...runtimePlaceholderYamlEntry };+ await backfill(config, connectionWith(INSTRUCTIONS));++ expect(setResolvedInstructions).not.toHaveBeenCalled();+ });++ it('skips servers that do not enable serverInstructions', async () => {+ await backfill(+ { ...startupDeferredYamlEntry, serverInstructions: undefined },+ connectionWith(INSTRUCTIONS),+ );+ expect(setResolvedInstructions).not.toHaveBeenCalled();+ });++ it('skips servers whose declaration is already a literal string', async () => {+ await backfill(+ { ...startupDeferredYamlEntry, serverInstructions: 'operator-provided text' },+ connectionWith(INSTRUCTIONS),+ );+ expect(setResolvedInstructions).not.toHaveBeenCalled();+ });++ it('skips servers whose instructions were already resolved', async () => {+ await backfill(+ { ...startupDeferredYamlEntry, resolvedInstructions: INSTRUCTIONS },+ connectionWith('newer text'),+ );+ expect(setResolvedInstructions).not.toHaveBeenCalled();+ });++ it('does not reach the registry when instructions are already resolved', async () => {+ await backfill(+ { ...startupDeferredYamlEntry, resolvedInstructions: INSTRUCTIONS },+ connectionWith('per-identity text for someone else'),+ );++ expect(setResolvedInstructions).not.toHaveBeenCalled();+ });++ it.each([+ ['user', { source: 'user' as const, dbId: 'server-1' }],+ ['plugin', { source: 'plugin' as const }],+ ['config', { source: 'config' as const }],+ ])('does not reach the registry for a %s-tier server', async (_label, overrides) => {+ await backfill({ ...startupDeferredYamlEntry, ...overrides }, connectionWith(INSTRUCTIONS));+ expect(setResolvedInstructions).not.toHaveBeenCalled();+ });++ it.each([+ ['OAuth', oauthDeferredYamlEntry],+ ['OBO', { ...startupDeferredYamlEntry, obo: {} } as unknown as t.ParsedServerConfig],+ [+ 'user API keys',+ {+ ...startupDeferredYamlEntry,+ apiKey: { source: 'user' },+ } as unknown as t.ParsedServerConfig,+ ],+ [+ 'custom user variables',+ {+ ...startupDeferredYamlEntry,+ customUserVars: { apiKey: { title: 'API key', description: 'Per-user credential' } },+ },+ ],+ ['runtime placeholders', runtimePlaceholderYamlEntry],+ ['runtime placeholders in an admin API key', runtimeApiKeyPlaceholderYamlEntry],+ ['env-expanded runtime placeholders', envExpandedRuntimeApiKeyPlaceholderYamlEntry],+ [+ 'a configured oauth block with requiresOAuth stamped false',+ {+ ...startupDeferredYamlEntry,+ oauth: { authorization_url: 'https://idp.example.com/authorize' },+ } as unknown as t.ParsedServerConfig,+ ],+ [+ 'configured oauth_headers with requiresOAuth stamped false',+ {+ ...startupDeferredYamlEntry,+ oauth_headers: { 'X-Tenant': 'per-user' },+ } as unknown as t.ParsedServerConfig,+ ],+ [+ 'an admin API key whose value is a runtime identity placeholder',+ {+ ...startupDeferredYamlEntry,+ apiKey: {+ source: 'admin',+ authorization_type: 'bearer',+ key: '{{LIBRECHAT_OPENID_ACCESS_TOKEN}}',+ },+ } as unknown as t.ParsedServerConfig,+ ],+ ])('does not persist instructions for %s context', async (_reason, config) => {+ await backfill(config, connectionWith(INSTRUCTIONS));+ expect(setResolvedInstructions).not.toHaveBeenCalled();+ });++ it('still persists instructions for a static admin API key', async () => {+ const config = {+ ...startupDeferredYamlEntry,+ apiKey: { source: 'admin', authorization_type: 'bearer', key: 'static-shared-secret' },+ } as unknown as t.ParsedServerConfig;++ await backfill(config, connectionWith(INSTRUCTIONS));++ expect(setResolvedInstructions).toHaveBeenCalledWith(+ 'deferred_server',+ INSTRUCTIONS,+ 'user-1',+ config,+ );+ });++ it('still backfills when the stored config carries no source stamp', async () => {+ const { source: _source, ...unstamped } = startupDeferredYamlEntry;+ await backfill(unstamped as t.ParsedServerConfig, connectionWith(INSTRUCTIONS));+ expect(setResolvedInstructions).toHaveBeenCalledWith(+ 'deferred_server',+ INSTRUCTIONS,+ 'user-1',+ unstamped,+ );+ });++ it('skips connections that advertise no instructions', async () => {+ await backfill({ ...startupDeferredYamlEntry }, connectionWith(undefined));+ expect(setResolvedInstructions).not.toHaveBeenCalled();+ });++ it('never propagates a persistence failure into connection creation', async () => {+ setResolvedInstructions.mockRejectedValue(new Error('cache down'));+ await expect(+ backfill({ ...startupDeferredYamlEntry }, connectionWith(INSTRUCTIONS)),+ ).resolves.toBeUndefined();+ });+});diff --git a/packages/api/src/mcp/registry/cache/ServerConfigsCacheInMemory.ts b/packages/api/src/mcp/registry/cache/ServerConfigsCacheInMemory.tsindex 5a7fd35b9f..72e648ca45 100644--- a/packages/api/src/mcp/registry/cache/ServerConfigsCacheInMemory.ts+++ b/packages/api/src/mcp/registry/cache/ServerConfigsCacheInMemory.ts@@ -32,6 +32,29 @@ export class ServerConfigsCacheInMemory {this.cache.set(serverName, { ...config, updatedAt: Date.now() });}+ /** Merges derived fields into an existing entry without bumping `updatedAt` —+ * see the interface doc: a bump would mark live connections stale. */+ public async patch(+ serverName: string,+ fields: Partial<ParsedServerConfig>,+ expectedUpdatedAt?: number,+ ): Promise<boolean> {+ const existing = this.cache.get(serverName);+ if (!existing) {+ return false;+ }+ if (expectedUpdatedAt != null && existing.updatedAt !== expectedUpdatedAt) {+ return false;+ }+ if (fields.resolvedInstructions != null && existing.resolvedInstructions != null) {+ return false;+ }+ /** Spreading a Partial over the transport-discriminated union widens it past the+ * discriminant; the merge only touches shared inspector-derived fields. */+ this.cache.set(serverName, { ...existing, ...fields } as ParsedServerConfig);+ return true;+ }+public async remove(serverName: string): Promise<void> {if (!this.cache.delete(serverName)) {throw new Error(`Failed to remove server "${serverName}" in cache.`);diff --git a/packages/api/src/mcp/registry/cache/ServerConfigsCacheRedis.ts b/packages/api/src/mcp/registry/cache/ServerConfigsCacheRedis.tsindex 902a561665..8483394dd4 100644--- a/packages/api/src/mcp/registry/cache/ServerConfigsCacheRedis.ts+++ b/packages/api/src/mcp/registry/cache/ServerConfigsCacheRedis.ts@@ -3,7 +3,15 @@ import { logger } from '@librechat/data-schemas';import type Keyv from 'keyv';import type { IServerConfigsRepositoryInterface } from '~/mcp/registry/ServerConfigsRepositoryInterface';import type { ParsedServerConfig, AddServerResult } from '~/mcp/types';-import { keyvRedisClient, observeRedisOperation, RedisUseCases, standardCache } from '~/cache';+import {+ cacheConfig,+ evalKeyvRedisScript,+ keyvRedisClient,+ observeRedisOperation,+ RedisUseCases,+ standardCache,+} from '~/cache';+import { PRESERVE_EMPTY_ARRAYS_LUA } from './preserveEmptyArraysLua';import { BaseRegistryCache } from './BaseRegistryCache';/**@@ -15,6 +23,23 @@ import { BaseRegistryCache } from './BaseRegistryCache';*/const BATCH_SIZE = 100;+const PATCH_ENTRY = `+${PRESERVE_EMPTY_ARRAYS_LUA}+local encoded = redis.call('GET', KEYS[1])+if not encoded then return 0 end+local sentinel = emptyArraySentinel(encoded, ARGV[1])+local envelope = cjson.decode(protectEmptyArrays(encoded, sentinel))+if not envelope.value then return 0 end+local fields = cjson.decode(protectEmptyArrays(ARGV[1], sentinel))+if ARGV[2] ~= '' and tonumber(ARGV[2]) ~= envelope.value.updatedAt then return 0 end+if fields.resolvedInstructions and envelope.value.resolvedInstructions then return 0 end+local ttl = redis.call('PTTL', KEYS[1])+for field, value in pairs(fields) do envelope.value[field] = value end+redis.call('SET', KEYS[1], restoreEmptyArrays(cjson.encode(envelope), sentinel))+if ttl > 0 then redis.call('PEXPIRE', KEYS[1], ttl) end+return 1+`;+export class ServerConfigsCacheRedisextends BaseRegistryCacheimplements IServerConfigsRepositoryInterface@@ -28,6 +53,22 @@ export class ServerConfigsCacheRedisthis.cache = standardCache(`${this.PREFIX}::Servers::${namespace}`);}+ private usesRedisStore(): boolean {+ const namespace = this.cache.namespace;+ return (+ keyvRedisClient != null &&+ namespace != null &&+ !cacheConfig.FORCED_IN_MEMORY_CACHE_NAMESPACES?.includes(namespace)+ );+ }++ private redisKey(serverName: string): string {+ const prefix = cacheConfig.REDIS_KEY_PREFIX+ ? `${cacheConfig.REDIS_KEY_PREFIX}${cacheConfig.GLOBAL_PREFIX_SEPARATOR}`+ : '';+ return `${prefix}${this.cache.namespace}:${serverName}`;+ }+public async add(serverName: string, config: ParsedServerConfig): Promise<AddServerResult> {if (this.leaderOnly) await this.leaderCheck(`add ${this.namespace} MCP servers`);const exists = await this.cache.has(serverName);@@ -58,6 +99,39 @@ export class ServerConfigsCacheRedisthis.successCheck(`upsert ${this.namespace} server "${serverName}"`, success);}+ /** Merges derived fields into an existing entry without bumping `updatedAt` —+ * see the interface doc: a bump would mark live connections stale. */+ public async patch(+ serverName: string,+ fields: Partial<ParsedServerConfig>,+ expectedUpdatedAt?: number,+ ): Promise<boolean> {+ if (this.leaderOnly) await this.leaderCheck(`patch ${this.namespace} MCP servers`);+ if (this.usesRedisStore()) {+ const result = await evalKeyvRedisScript(PATCH_ENTRY, {+ keys: [this.redisKey(serverName)],+ arguments: [+ JSON.stringify(fields),+ expectedUpdatedAt != null ? String(expectedUpdatedAt) : '',+ ],+ });+ return result === 1;+ }+ const existing = (await this.cache.get(serverName)) as ParsedServerConfig | undefined;+ if (!existing) {+ return false;+ }+ if (expectedUpdatedAt != null && existing.updatedAt !== expectedUpdatedAt) {+ return false;+ }+ if (fields.resolvedInstructions != null && existing.resolvedInstructions != null) {+ return false;+ }+ const success = await this.cache.set(serverName, { ...existing, ...fields });+ this.successCheck(`patch ${this.namespace} server "${serverName}"`, success);+ return true;+ }+public async remove(serverName: string): Promise<void> {if (this.leaderOnly) await this.leaderCheck(`remove ${this.namespace} MCP servers`);const success = await this.cache.delete(serverName);diff --git a/packages/api/src/mcp/registry/cache/ServerConfigsCacheRedisAggregateKey.ts b/packages/api/src/mcp/registry/cache/ServerConfigsCacheRedisAggregateKey.tsindex 5fc32bd7aa..94043d1dfe 100644--- a/packages/api/src/mcp/registry/cache/ServerConfigsCacheRedisAggregateKey.ts+++ b/packages/api/src/mcp/registry/cache/ServerConfigsCacheRedisAggregateKey.ts@@ -1,8 +1,9 @@import type Keyv from 'keyv';import type { IServerConfigsRepositoryInterface } from '~/mcp/registry/ServerConfigsRepositoryInterface';import type { ParsedServerConfig, AddServerResult } from '~/mcp/types';+import { cacheConfig, evalKeyvRedisScript, keyvRedisClient, standardCache } from '~/cache';+import { PRESERVE_EMPTY_ARRAYS_LUA } from './preserveEmptyArraysLua';import { BaseRegistryCache } from './BaseRegistryCache';-import { cacheConfig, standardCache } from '~/cache';/*** Redis-backed MCP server configs cache that stores all entries under a single aggregate key.@@ -13,22 +14,69 @@ import { cacheConfig, standardCache } from '~/cache';* caused by SCAN under concurrent load in large deployments (see GitHub #11624, #12408).** Trade-offs:- * - `add/update/remove` use a serialized read-modify-write on the aggregate key via a- * promise-based mutex. This prevents concurrent writes from racing within a single- * process (e.g., during `Promise.allSettled` initialization of multiple servers).+ * - In-memory writes use a serialized read-modify-write via a promise-based mutex.+ * Redis writes use single-key Lua mutations, so replicas cannot overwrite one another.* - The entire config map is serialized/deserialized on every operation. With typical MCP* deployments (~5-50 servers), the JSON payload is small (10-50KB).* - Cross-instance visibility is preserved: all instances read/write the same Redis key,* so reinspection results propagate automatically after readThroughCache TTL expiry.*- * IMPORTANT: The promise-based writeLock serializes writes within a single Node.js process- * only. Concurrent writes from separate instances race at the Redis level (last-write-wins).- * This is acceptable because writes are performed exclusively by the leader during- * initialization via {@link MCPServersInitializer}. `reinspectServer` is manual and rare.- * Callers must enforce this single-writer invariant externally.+ * All mutations use Redis-side Lua when Redis backs this cache. This keeps+ * simultaneous replicas from losing one another's changes and makes+ * `resolvedInstructions` first-write-wins.*/const AGGREGATE_KEY = '__all__';+const MUTATE_AGGREGATE_ENTRY = `+${PRESERVE_EMPTY_ARRAYS_LUA}+local operation = ARGV[1]+local serverName = ARGV[2]+local encoded = redis.call('GET', KEYS[1])+local sentinel = emptyArraySentinel(encoded, ARGV[3])+local envelope+if encoded then+ envelope = cjson.decode(protectEmptyArrays(encoded, sentinel))+else+ envelope = { value = {} }+end+if not envelope.value then envelope.value = {} end+local existing = envelope.value[serverName]+if operation == 'add' and existing then return -1 end+if (operation == 'update' or operation == 'remove') and not existing then return 0 end+local ttl = redis.call('PTTL', KEYS[1])+if operation == 'remove' then+ envelope.value[serverName] = nil+else+ local config = cjson.decode(protectEmptyArrays(ARGV[3], sentinel))+ config.updatedAt = tonumber(ARGV[4])+ envelope.value[serverName] = config+end+redis.call('SET', KEYS[1], restoreEmptyArrays(cjson.encode(envelope), sentinel))+if ttl > 0 then redis.call('PEXPIRE', KEYS[1], ttl) end+return 1+`;++/** Keyv stores its serialized value in an envelope with a `value` member. This script+ * updates that envelope atomically and preserves a configured Redis expiration. */+const PATCH_AGGREGATE_ENTRY = `+${PRESERVE_EMPTY_ARRAYS_LUA}+local encoded = redis.call('GET', KEYS[1])+if not encoded then return 0 end+local sentinel = emptyArraySentinel(encoded, ARGV[2])+local envelope = cjson.decode(protectEmptyArrays(encoded, sentinel))+if not envelope.value then return 0 end+local entry = envelope.value[ARGV[1]]+if not entry then return 0 end+local fields = cjson.decode(protectEmptyArrays(ARGV[2], sentinel))+if ARGV[3] ~= '' and tonumber(ARGV[3]) ~= entry.updatedAt then return 0 end+if fields.resolvedInstructions and entry.resolvedInstructions then return 0 end+local ttl = redis.call('PTTL', KEYS[1])+for field, value in pairs(fields) do entry[field] = value end+redis.call('SET', KEYS[1], restoreEmptyArrays(cjson.encode(envelope), sentinel))+if ttl > 0 then redis.call('PEXPIRE', KEYS[1], ttl) end+return 1+`;+export class ServerConfigsCacheRedisAggregateKeyextends BaseRegistryCacheimplements IServerConfigsRepositoryInterface@@ -66,6 +114,40 @@ export class ServerConfigsCacheRedisAggregateKeythis.localSnapshotExpiry = 0;}+ private usesRedisStore(): boolean {+ const namespace = this.cache.namespace;+ return (+ keyvRedisClient != null &&+ namespace != null &&+ !cacheConfig.FORCED_IN_MEMORY_CACHE_NAMESPACES?.includes(namespace)+ );+ }++ private aggregateRedisKey(): string {+ const prefix = cacheConfig.REDIS_KEY_PREFIX+ ? `${cacheConfig.REDIS_KEY_PREFIX}${cacheConfig.GLOBAL_PREFIX_SEPARATOR}`+ : '';+ return `${prefix}${this.cache.namespace}:${AGGREGATE_KEY}`;+ }++ private async mutateRedisEntry(+ operation: 'add' | 'update' | 'upsert' | 'remove',+ serverName: string,+ config?: ParsedServerConfig,+ updatedAt?: number,+ ): Promise<number> {+ const result = await evalKeyvRedisScript(MUTATE_AGGREGATE_ENTRY, {+ keys: [this.aggregateRedisKey()],+ arguments: [+ operation,+ serverName,+ config ? JSON.stringify(config) : '',+ updatedAt != null ? String(updatedAt) : '',+ ],+ });+ return typeof result === 'number' ? result : 0;+ }+/*** Serializes write operations to prevent concurrent read-modify-write races.* Reads (`get`, `getAll`) are not serialized — they can run concurrently.@@ -115,6 +197,22 @@ export class ServerConfigsCacheRedisAggregateKeypublic async add(serverName: string, config: ParsedServerConfig): Promise<AddServerResult> {if (this.leaderOnly) await this.leaderCheck('add MCP servers');return this.withWriteLock(async () => {+ const storedConfig = { ...config, updatedAt: Date.now() };+ if (this.usesRedisStore()) {+ const result = await this.mutateRedisEntry(+ 'add',+ serverName,+ storedConfig,+ storedConfig.updatedAt,+ );+ if (result === -1) {+ throw new Error(+ `Server "${serverName}" already exists in cache. Use update() to modify existing configs.`,+ );+ }+ this.successCheck(`add ${this.namespace} server "${serverName}"`, result === 1);+ return { serverName, config: storedConfig };+ }// Force fresh Redis read so the read-modify-write uses current data,// not a snapshot that may predate this write. Distinct from the finally-block// invalidation which cleans up after the write completes or throws.@@ -125,7 +223,6 @@ export class ServerConfigsCacheRedisAggregateKey`Server "${serverName}" already exists in cache. Use update() to modify existing configs.`,);}- const storedConfig = { ...config, updatedAt: Date.now() };const newAll = { ...all, [serverName]: storedConfig };const success = await this.cache.set(AGGREGATE_KEY, newAll);this.successCheck(`add ${this.namespace} server "${serverName}"`, success);@@ -136,6 +233,17 @@ export class ServerConfigsCacheRedisAggregateKeypublic async update(serverName: string, config: ParsedServerConfig): Promise<void> {if (this.leaderOnly) await this.leaderCheck('update MCP servers');return this.withWriteLock(async () => {+ const updatedAt = Date.now();+ if (this.usesRedisStore()) {+ const result = await this.mutateRedisEntry('update', serverName, config, updatedAt);+ if (result === 0) {+ throw new Error(+ `Server "${serverName}" does not exist in cache. Use add() to create new configs.`,+ );+ }+ this.successCheck(`update ${this.namespace} server "${serverName}"`, result === 1);+ return;+ }this.invalidateLocalSnapshot(); // Force fresh Redis read (see add() comment)const all = await this.getAll();if (!all[serverName]) {@@ -143,7 +251,7 @@ export class ServerConfigsCacheRedisAggregateKey`Server "${serverName}" does not exist in cache. Use add() to create new configs.`,);}- const newAll = { ...all, [serverName]: { ...config, updatedAt: Date.now() } };+ const newAll = { ...all, [serverName]: { ...config, updatedAt } };const success = await this.cache.set(AGGREGATE_KEY, newAll);this.successCheck(`update ${this.namespace} server "${serverName}"`, success);});@@ -152,17 +260,70 @@ export class ServerConfigsCacheRedisAggregateKeypublic async upsert(serverName: string, config: ParsedServerConfig): Promise<void> {if (this.leaderOnly) await this.leaderCheck('upsert MCP servers');return this.withWriteLock(async () => {+ const updatedAt = Date.now();+ if (this.usesRedisStore()) {+ const result = await this.mutateRedisEntry('upsert', serverName, config, updatedAt);+ this.successCheck(`upsert ${this.namespace} server "${serverName}"`, result === 1);+ return;+ }this.invalidateLocalSnapshot();const all = await this.getAll();- const newAll = { ...all, [serverName]: { ...config, updatedAt: Date.now() } };+ const newAll = { ...all, [serverName]: { ...config, updatedAt } };const success = await this.cache.set(AGGREGATE_KEY, newAll);this.successCheck(`upsert ${this.namespace} server "${serverName}"`, success);});}+ /** Merges derived fields into an existing entry without bumping `updatedAt` —+ * see the interface doc: a bump would mark live connections stale. */+ public async patch(+ serverName: string,+ fields: Partial<ParsedServerConfig>,+ expectedUpdatedAt?: number,+ ): Promise<boolean> {+ if (this.leaderOnly) await this.leaderCheck('patch MCP servers');+ return this.withWriteLock(async () => {+ if (this.usesRedisStore()) {+ const result = await evalKeyvRedisScript(PATCH_AGGREGATE_ENTRY, {+ keys: [this.aggregateRedisKey()],+ arguments: [+ serverName,+ JSON.stringify(fields),+ expectedUpdatedAt != null ? String(expectedUpdatedAt) : '',+ ],+ });+ return result === 1;+ }+ this.invalidateLocalSnapshot(); // Force fresh Redis read (see add() comment)+ const all = await this.getAll();+ const existing = all[serverName];+ if (!existing) {+ return false;+ }+ if (expectedUpdatedAt != null && existing.updatedAt !== expectedUpdatedAt) {+ return false;+ }+ if (fields.resolvedInstructions != null && existing.resolvedInstructions != null) {+ return false;+ }+ const newAll = { ...all, [serverName]: { ...existing, ...fields } };+ const success = await this.cache.set(AGGREGATE_KEY, newAll);+ this.successCheck(`patch ${this.namespace} server "${serverName}"`, success);+ return true;+ });+ }+public async remove(serverName: string): Promise<void> {if (this.leaderOnly) await this.leaderCheck('remove MCP servers');return this.withWriteLock(async () => {+ if (this.usesRedisStore()) {+ const result = await this.mutateRedisEntry('remove', serverName);+ if (result === 0) {+ throw new Error(`Failed to remove server "${serverName}" in cache.`);+ }+ this.successCheck(`remove ${this.namespace} server "${serverName}"`, result === 1);+ return;+ }this.invalidateLocalSnapshot(); // Force fresh Redis read (see add() comment)const all = await this.getAll();if (!all[serverName]) {diff --git a/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedis.cache_integration.spec.ts b/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedis.cache_integration.spec.tsindex 25238cf830..5663150160 100644--- a/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedis.cache_integration.spec.ts+++ b/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedis.cache_integration.spec.ts@@ -3,6 +3,8 @@ import type { RedisClientsModule } from '~/cache/__tests__/redisClients.helper';import { closeRedisClients } from '~/cache/__tests__/redisClients.helper';import { ParsedServerConfig } from '~/mcp/types';+type StdioServerConfig = Extract<ParsedServerConfig, { type: 'stdio' }>;+describe('ServerConfigsCacheRedis Integration Tests', () => {let ServerConfigsCacheRedis: typeof import('../ServerConfigsCacheRedis').ServerConfigsCacheRedis;let keyvRedisClient: Awaited<typeof import('~/cache/redisClients')>['keyvRedisClient'];@@ -10,19 +12,19 @@ describe('ServerConfigsCacheRedis Integration Tests', () => {let cache: InstanceType<typeof import('../ServerConfigsCacheRedis').ServerConfigsCacheRedis>;- const mockConfig1 = {+ const mockConfig1: StdioServerConfig = {type: 'stdio',command: 'node',args: ['server1.js'],env: { TEST: 'value1' },- } as ParsedServerConfig;+ };- const mockConfig2 = {+ const mockConfig2: StdioServerConfig = {type: 'stdio',command: 'python',args: ['server2.py'],env: { TEST: 'value2' },- } as ParsedServerConfig;+ };const mockConfig3 = {type: 'sse',@@ -132,6 +134,21 @@ describe('ServerConfigsCacheRedis Integration Tests', () => {});});+ describe('patch operation', () => {+ it('preserves empty arrays in a patched per-key entry', async () => {+ const emptyArgsConfig: StdioServerConfig = { ...mockConfig1, args: [] };+ const { config } = await cache.add('empty-arrays', emptyArgsConfig);++ await expect(+ cache.patch('empty-arrays', { resolvedInstructions: 'patched' }, config.updatedAt),+ ).resolves.toBe(true);++ const result = await cache.get('empty-arrays');+ expect(result).toMatchObject({ args: [] });+ expect(result?.resolvedInstructions).toBe('patched');+ });+ });+describe('getAll operation', () => {it('should return empty object when no servers exist', async () => {const result = await cache.getAll();diff --git a/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedisAggregateKey.cache_integration.spec.ts b/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedisAggregateKey.cache_integration.spec.tsindex 2cc7f159ed..99cac18319 100644--- a/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedisAggregateKey.cache_integration.spec.ts+++ b/packages/api/src/mcp/registry/cache/__tests__/ServerConfigsCacheRedisAggregateKey.cache_integration.spec.ts@@ -2,6 +2,8 @@ import { expect } from '@playwright/test';import type { ParsedServerConfig } from '~/mcp/types';import { closeRedisClients } from '~/cache/__tests__/redisClients.helper';+type StdioServerConfig = Extract<ParsedServerConfig, { type: 'stdio' }>;+describe('ServerConfigsCacheRedisAggregateKey Integration Tests', () => {let ServerConfigsCacheRedisAggregateKey: typeof import('../ServerConfigsCacheRedisAggregateKey').ServerConfigsCacheRedisAggregateKey;let keyvRedisClient: Awaited<typeof import('~/cache/redisClients')>['keyvRedisClient'];@@ -10,19 +12,19 @@ describe('ServerConfigsCacheRedisAggregateKey Integration Tests', () => {typeof import('../ServerConfigsCacheRedisAggregateKey').ServerConfigsCacheRedisAggregateKey>;- const mockConfig1 = {+ const mockConfig1: StdioServerConfig = {type: 'stdio',command: 'node',args: ['server1.js'],env: { TEST: 'value1' },- } as ParsedServerConfig;+ };- const mockConfig2 = {+ const mockConfig2: StdioServerConfig = {type: 'stdio',command: 'python',args: ['server2.py'],env: { TEST: 'value2' },- } as ParsedServerConfig;+ };const mockConfig3 = {type: 'sse',@@ -229,6 +231,87 @@ describe('ServerConfigsCacheRedisAggregateKey Integration Tests', () => {expect(result.server3).toMatchObject(mockConfig3);}});++ it('atomically preserves concurrent instruction backfills from separate replicas', async () => {+ const replicaA = new ServerConfigsCacheRedisAggregateKey('agg-test', false);+ const replicaB = new ServerConfigsCacheRedisAggregateKey('agg-test', false);+ await cache.add('server1', mockConfig1);+ await cache.add('server2', mockConfig2);++ await expect(+ Promise.all([+ replicaA.patch('server1', { resolvedInstructions: 'server one instructions' }),+ replicaB.patch('server2', { resolvedInstructions: 'server two instructions' }),+ ]),+ ).resolves.toEqual([true, true]);++ const result = await cache.getAll();+ expect(result.server1.resolvedInstructions).toBe('server one instructions');+ expect(result.server2.resolvedInstructions).toBe('server two instructions');+ });++ it('routes every aggregate mutation through Redis-side atomic updates', async () => {+ const replica = new ServerConfigsCacheRedisAggregateKey('agg-test', false);+ const cacheSetSpy = jest.spyOn(replica['cache'], 'set');++ await replica.add('atomic-server', mockConfig1);+ await replica.update('atomic-server', mockConfig2);+ await replica.upsert('atomic-server', mockConfig3);+ await replica.remove('atomic-server');++ expect(cacheSetSpy.mock.calls).toHaveLength(0);+ cacheSetSpy.mockRestore();+ });++ it('preserves patches concurrent with whole-entry mutations on other replicas', async () => {+ const patchReplica = new ServerConfigsCacheRedisAggregateKey('agg-test', false);+ const writerReplica = new ServerConfigsCacheRedisAggregateKey('agg-test', false);++ for (let i = 0; i < 20; i++) {+ const patchedName = `patched-${i}`;+ const updatedName = `updated-${i}`;+ await cache.add(patchedName, mockConfig1);+ await cache.add(updatedName, mockConfig2);++ await expect(+ Promise.all([+ patchReplica.patch(patchedName, { resolvedInstructions: `instructions-${i}` }),+ writerReplica.update(updatedName, { ...mockConfig3, description: `updated-${i}` }),+ ]),+ ).resolves.toEqual([true, undefined]);++ const result = await cache.getAll();+ expect(result[patchedName].resolvedInstructions).toBe(`instructions-${i}`);+ expect(result[updatedName].description).toBe(`updated-${i}`);+ }+ });++ it('preserves empty arrays through every Redis-side mutation path', async () => {+ const emptyArgsConfig: StdioServerConfig = { ...mockConfig1, args: [] };++ await cache.add('empty-arrays', emptyArgsConfig);+ expect(await cache.get('empty-arrays')).toMatchObject({ args: [] });++ await cache.patch('empty-arrays', { resolvedInstructions: 'patched' });+ expect(await cache.get('empty-arrays')).toMatchObject({ args: [] });++ await cache.update('empty-arrays', { ...mockConfig2, args: [] });+ expect(await cache.get('empty-arrays')).toMatchObject({ args: [] });++ await cache.upsert('empty-arrays', { ...mockConfig1, command: 'updated', args: [] });+ expect(await cache.get('empty-arrays')).toMatchObject({ args: [] });+ });++ it('preserves empty arrays in an untouched entry when another entry is patched', async () => {+ const emptyArgsConfig: StdioServerConfig = { ...mockConfig1, args: [] };+ await cache.add('untouched-empty-arrays', emptyArgsConfig);+ await cache.add('patched-entry', mockConfig2);++ await cache.patch('patched-entry', { resolvedInstructions: 'patched' });++ expect(await cache.get('untouched-empty-arrays')).toMatchObject({ args: [] });+ expect((await cache.get('patched-entry'))?.resolvedInstructions).toBe('patched');+ });});describe('reset operation', () => {diff --git a/packages/api/src/mcp/registry/cache/preserveEmptyArraysLua.ts b/packages/api/src/mcp/registry/cache/preserveEmptyArraysLua.tsnew file mode 100644index 0000000000..40137d661c--- /dev/null+++ b/packages/api/src/mcp/registry/cache/preserveEmptyArraysLua.ts@@ -0,0 +1,70 @@+/**+ * Lua CJSON cannot distinguish decoded empty arrays from empty objects. These helpers protect+ * structural empty arrays with a collision-free string sentinel before decoding, then restore+ * them after encoding. The scanner skips JSON string contents, so literal `[]` text is unchanged.+ */+export const PRESERVE_EMPTY_ARRAYS_LUA = `+local function emptyArraySentinel(...)+ local sentinel = '__librechat_empty_array__'+ while true do+ local collision = false+ for index = 1, select('#', ...) do+ local json = select(index, ...)+ if json and string.find(json, sentinel, 1, true) then+ collision = true+ break+ end+ end+ if not collision then return sentinel end+ sentinel = sentinel .. '_'+ end+end++local function protectEmptyArrays(json, sentinel)+ local output = {}+ local inString = false+ local escaped = false+ local index = 1+ while index <= #json do+ local character = string.sub(json, index, index)+ if inString then+ table.insert(output, character)+ if escaped then+ escaped = false+ elseif string.byte(character) == 92 then+ escaped = true+ elseif character == '"' then+ inString = false+ end+ index = index + 1+ elseif character == '"' then+ inString = true+ table.insert(output, character)+ index = index + 1+ elseif character == '[' then+ local closeIndex = index + 1+ while closeIndex <= #json do+ local candidate = string.sub(json, closeIndex, closeIndex)+ if not string.find(' \\t\\r\\n', candidate, 1, true) then break end+ closeIndex = closeIndex + 1+ end+ if string.sub(json, closeIndex, closeIndex) == ']' then+ table.insert(output, '"' .. sentinel .. '"')+ index = closeIndex + 1+ else+ table.insert(output, character)+ index = index + 1+ end+ else+ table.insert(output, character)+ index = index + 1+ end+ end+ return table.concat(output)+end++local function restoreEmptyArrays(json, sentinel)+ local restored = string.gsub(json, '"' .. sentinel .. '"', '[]')+ return restored+end+`;diff --git a/packages/api/src/mcp/utils.ts b/packages/api/src/mcp/utils.tsindex 62918ef1fa..9910def2cc 100644--- a/packages/api/src/mcp/utils.ts+++ b/packages/api/src/mcp/utils.ts@@ -1,6 +1,7 @@import {Constants,MCPOptionsSchema,+ extractEnvVariable,normalizeServerName,normalizeMCPToolKey,buildServerNameAliases,@@ -211,6 +212,9 @@ type UserScopedConnectionConfig = Pick<ParsedServerConfig,'requiresOAuth' | 'source' | 'dbId' | 'startup'> & {+ /** Loosened like the fields below: raw (pre-inspection) configs carry+ * optional API-key fields, and the gating predicates only inspect them. */+ apiKey?: { key?: string; source?: 'user' | 'admin' } | null;args?: string[];/** Loosened from the parsed shapes so raw (pre-inspection) configs qualify;* scoping predicates only check key presence */@@ -227,7 +231,15 @@ type UserScopedConnectionConfig = Pick<};function placeholderBearingFields(config: UserScopedConnectionConfig): PlaceholderValue[] {- return [config.args, config.env, config.headers, config.oauth, config.oauth_headers, config.url];+ return [+ config.apiKey?.key,+ config.args,+ config.env,+ config.headers,+ config.oauth,+ config.oauth_headers,+ config.url,+ ];}/** Whether a server should use MCP OAuth handling. */@@ -273,7 +285,7 @@ function hasRuntimeContextPlaceholder(value: PlaceholderValue): boolean {function hasPlaceholder(value: PlaceholderValue, pattern: RegExp): boolean {if (typeof value === 'string') {- return pattern.test(value);+ return pattern.test(value) || pattern.test(extractEnvVariable(value));}if (Array.isArray(value)) {return value.some((item) => hasPlaceholder(item, pattern));@@ -291,11 +303,13 @@ function addRuntimeBodyPlaceholderFields(fields: Set<keyof RequestBody>,): void {if (typeof value === 'string') {- for (const match of value.matchAll(RUNTIME_BODY_PLACEHOLDER_CAPTURE_PATTERN)) {- const placeholderKey = match[1];- const field = placeholderKey ? BODY_PLACEHOLDER_FIELDS[placeholderKey] : undefined;- if (field) {- fields.add(field);+ for (const candidate of new Set([value, extractEnvVariable(value)])) {+ for (const match of candidate.matchAll(RUNTIME_BODY_PLACEHOLDER_CAPTURE_PATTERN)) {+ const placeholderKey = match[1];+ const field = placeholderKey ? BODY_PLACEHOLDER_FIELDS[placeholderKey] : undefined;+ if (field) {+ fields.add(field);+ }}}return;@@ -409,6 +423,27 @@ export function canUseAppConnection(config: UserScopedConnectionConfig): boolean);}+/**+ * Server instructions fetched from a connection are safe to retain in the+ * shared YAML registry only when the connection cannot vary by identity or+ * request. `startup: false` is the one context-independent reason startup+ * inspection leaves instructions unresolved; every other deferred case can+ * expose authenticated or request-specific instructions to another user.+ */+export function canBackfillSharedServerInstructions(config: UserScopedConnectionConfig): boolean {+ return (+ config.startup === false &&+ !requiresUserScopedConnection(config) &&+ /** A configured `oauth` block is identity-scoped even when `requiresOAuth`+ * is unset or was stamped `false` by the skipped startup inspection —+ * `requiresUserScopedConnection` alone would let it through while+ * `isOAuthServer` still arms the OAuth machinery for the unstamped case. */+ config.oauth == null &&+ config.oauth_headers == null &&+ config.apiKey?.source !== 'user'+ );+}+/*** Returns the names of `customUserVars` declared on the server config for which* the user has not supplied a non-blank value (unset, empty, or whitespace-only