Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

📜 fix: 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.ts
index 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 the
diff --git a/packages/api/src/mcp/__tests__/utils.test.ts b/packages/api/src/mcp/__tests__/utils.test.ts
index 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.ts
index 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.ts
index 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 possible
remove(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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 ServerConfigsCacheRedis
extends BaseRegistryCache
implements IServerConfigsRepositoryInterface
@@ -28,6 +53,22 @@ export class ServerConfigsCacheRedis
this.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 ServerConfigsCacheRedis
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 ${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.ts
index 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 ServerConfigsCacheRedisAggregateKey
extends BaseRegistryCache
implements IServerConfigsRepositoryInterface
@@ -66,6 +114,40 @@ export class ServerConfigsCacheRedisAggregateKey
this.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 ServerConfigsCacheRedisAggregateKey
public 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 ServerConfigsCacheRedisAggregateKey
public 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 ServerConfigsCacheRedisAggregateKey
public 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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