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: Normalize Legacy MCP Header Maps on Cached Reads (#16200)

lia-by-librechat[bot]f192308f4c2c
diff --git a/packages/api/src/mcp/registry/MCPServersRegistry.ts b/packages/api/src/mcp/registry/MCPServersRegistry.ts
index 90372d76ec..6d4a0a9717 100644
--- a/packages/api/src/mcp/registry/MCPServersRegistry.ts
+++ b/packages/api/src/mcp/registry/MCPServersRegistry.ts
@@ -10,6 +10,7 @@ import {
CONFIG_CACHE_NAMESPACE,
} from './cache/ServerConfigsCacheFactory';
import { MCPInspectionFailedError, isMCPDomainNotAllowedError } from '~/mcp/errors';
+import { normalizeLegacyHeaderMaps, normalizeLegacyHeaderMapsIn } from './compat';
import { canBackfillSharedServerInstructions, isUserSourced } from '~/mcp/utils';
import { ReadThroughAllCache } from './cache/ReadThroughAllCache';
import { isPluginSourced, MCP_PLUGIN_SOURCE } from '~/utils/env';
@@ -29,11 +30,19 @@ export class MCPConfigInitializationCanceledError extends Error {}
/** Cached configs carry decrypted oauth/apiKey credentials, so the shared
* stores only ever see ciphertext; plaintext stays in process memory,
- * exactly where it lived before these caches became shared. */
-function encryptedStoreTransforms<T>(): ReadThroughTransforms<T> {
+ * exactly where it lived before these caches became shared.
+ *
+ * Decoding also normalizes legacy header maps, because a replica running older
+ * code fills these stores from its own database reads: without it, a rolling
+ * deployment would keep serving a config the runtime schemas reject, from a
+ * cache hit that never reaches the repository's own normalization. */
+function serverMapStoreTransforms(): ReadThroughTransforms<Record<string, t.ParsedServerConfig>> {
return {
encode: async (value) => encryptV2(JSON.stringify(value)),
- decode: async (raw) => JSON.parse(await decryptV2(raw)),
+ decode: async (raw) =>
+ normalizeLegacyHeaderMapsIn(
+ JSON.parse(await decryptV2(raw)) as Record<string, t.ParsedServerConfig>,
+ ),
};
}
@@ -46,7 +55,7 @@ function perServerStoreTransforms(): ReadThroughTransforms<t.ParsedServerConfig
const decoded = JSON.parse(await decryptV2(raw)) as {
config: t.ParsedServerConfig | null;
};
- return decoded.config ?? undefined;
+ return decoded.config == null ? undefined : normalizeLegacyHeaderMaps(decoded.config);
},
};
}
@@ -284,7 +293,7 @@ export class MCPServersRegistry {
this.readThroughCacheAll = new ReadThroughAllCache<Record<string, t.ParsedServerConfig>>(
'mcp-registry-read-through-all',
ttl,
- encryptedStoreTransforms<Record<string, t.ParsedServerConfig>>(),
+ serverMapStoreTransforms(),
);
}
diff --git a/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts b/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts
index ce15ea4430..d746d50f0d 100644
--- a/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts
+++ b/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts
@@ -7,6 +7,7 @@ import {
MCPConfigInitializationCanceledError,
} from '~/mcp/registry/MCPServersRegistry';
import { ServerConfigsCacheInMemory } from '~/mcp/registry/cache/ServerConfigsCacheInMemory';
+import { getMCPAppToolsPublicationGeneration } from '~/mcp/toolsChanged';
import { MCPServerInspector } from '~/mcp/registry/MCPServerInspector';
import { MCPInspectionFailedError } from '~/mcp/errors';
import { processMCPEnv } from '~/utils/env';
@@ -1549,6 +1550,77 @@ describe('MCPServersRegistry', () => {
expect(cacheRepoGetAllSpy).toHaveBeenCalledTimes(3);
});
});
+
+ /** A replica running older code fills these stores from its own DB reads, so a
+ * cache hit has to carry the same normalization the repository applies. */
+ describe('configs stored by an older replica', () => {
+ const storedByOlderReplica = {
+ type: 'streamable-http',
+ url: 'https://example.com/mcp',
+ source: 'user',
+ dbId: 'db-legacy-1',
+ requiresOAuth: true,
+ headers: null,
+ requestHeaders: null,
+ } as unknown as t.ParsedServerConfig;
+
+ it('normalizes null header maps served from a per-server cache hit', async () => {
+ const dbGet = jest
+ .spyOn(registry['dbConfigsRepo'], 'get')
+ .mockResolvedValue(storedByOlderReplica);
+
+ await registry.getServerConfig('legacy_server', 'user-1');
+ expect(dbGet).toHaveBeenCalledTimes(1);
+
+ const cached = await registry.getServerConfig('legacy_server', 'user-1');
+ expect(dbGet).toHaveBeenCalledTimes(1);
+ expect(cached).toMatchObject({ dbId: 'db-legacy-1', source: 'user' });
+ expect(cached).not.toHaveProperty('headers');
+ expect(cached).not.toHaveProperty('requestHeaders');
+ expect(() => getMCPAppToolsPublicationGeneration(cached!)).not.toThrow();
+ });
+
+ it('normalizes null header maps served from an all-servers cache hit', async () => {
+ const dbGetAll = jest
+ .spyOn(registry['dbConfigsRepo'], 'getAll')
+ .mockResolvedValue({ legacy_server: storedByOlderReplica });
+
+ await registry.getAllServerConfigs('user-1');
+ expect(dbGetAll).toHaveBeenCalledTimes(1);
+
+ /** Drop this replica's process memo only; the shared entry stays as the
+ * older replica encoded it, which is what another pod would read. */
+ registry['readThroughCacheAll']['memo'].clear();
+
+ const cached = (await registry.getAllServerConfigs('user-1')).legacy_server;
+ expect(dbGetAll).toHaveBeenCalledTimes(1);
+ expect(cached).toMatchObject({ dbId: 'db-legacy-1', source: 'user' });
+ expect(cached).not.toHaveProperty('headers');
+ expect(cached).not.toHaveProperty('requestHeaders');
+ expect(() => getMCPAppToolsPublicationGeneration(cached)).not.toThrow();
+ });
+
+ it('preserves populated header maps across both cache hits', async () => {
+ const headers = { 'X-Shared': 'value' };
+ const requestHeaders = { 'X-Request': 'value' };
+ const config = { ...storedByOlderReplica, headers, requestHeaders };
+ jest.spyOn(registry['dbConfigsRepo'], 'get').mockResolvedValue(config);
+ jest
+ .spyOn(registry['dbConfigsRepo'], 'getAll')
+ .mockResolvedValue({ header_server: config });
+
+ await registry.getServerConfig('header_server', 'user-1');
+ await registry.getAllServerConfigs('user-1');
+ registry['readThroughCacheAll']['memo'].clear();
+
+ const single = await registry.getServerConfig('header_server', 'user-1');
+ const all = (await registry.getAllServerConfigs('user-1')).header_server;
+ for (const cached of [single, all]) {
+ expect(cached).toMatchObject({ headers, requestHeaders });
+ expect(() => getMCPAppToolsPublicationGeneration(cached!)).not.toThrow();
+ }
+ });
+ });
});
describe('admin-panel overrides for YAML-defined servers', () => {
diff --git a/packages/api/src/mcp/registry/compat.ts b/packages/api/src/mcp/registry/compat.ts
new file mode 100644
index 0000000000..6307741287
--- /dev/null
+++ b/packages/api/src/mcp/registry/compat.ts
@@ -0,0 +1,50 @@
+import type { ParsedServerConfig } from '~/mcp/types';
+
+/** Optional header maps a stored config may carry as an explicit null. */
+type LegacyHeaderMaps = {
+ headers?: Record<string, string> | null;
+ requestHeaders?: Record<string, string> | null;
+};
+
+/**
+ * Drops `headers` and `requestHeaders` stored as null by a writer that
+ * serialized an absent map: BSON materializes an explicit undefined property as
+ * null, and both fields are optional objects in the MCP transport schemas, so a
+ * stored null fails the runtime validation every connection and catalog
+ * generation depends on.
+ *
+ * Every store a config is read back from is a compatibility boundary, because a
+ * replica running older code can write into it while this replica reads. The
+ * same value is returned when there is nothing to normalize, so the hot path
+ * allocates nothing.
+ */
+export function normalizeLegacyHeaderMaps(config: ParsedServerConfig): ParsedServerConfig {
+ const persistedConfig = config as ParsedServerConfig & LegacyHeaderMaps;
+ if (persistedConfig.headers !== null && persistedConfig.requestHeaders !== null) {
+ return config;
+ }
+
+ const { headers, requestHeaders, ...rest } = persistedConfig;
+ return {
+ ...rest,
+ ...(headers != null && { headers }),
+ ...(requestHeaders != null && { requestHeaders }),
+ } as ParsedServerConfig;
+}
+
+/** The same normalization across a stored server map, reusing the input map when every entry is current. */
+export function normalizeLegacyHeaderMapsIn<T extends Record<string, ParsedServerConfig>>(
+ configs: T,
+): T {
+ let normalized: Record<string, ParsedServerConfig> | undefined;
+ for (const serverName of Object.keys(configs)) {
+ const config = configs[serverName];
+ const normalizedConfig = normalizeLegacyHeaderMaps(config);
+ if (normalizedConfig === config) {
+ continue;
+ }
+ normalized ??= { ...configs };
+ normalized[serverName] = normalizedConfig;
+ }
+ return (normalized as T) ?? configs;
+}
diff --git a/packages/api/src/mcp/registry/db/ServerConfigsDB.ts b/packages/api/src/mcp/registry/db/ServerConfigsDB.ts
index 109d0572c1..ffe7abe631 100644
--- a/packages/api/src/mcp/registry/db/ServerConfigsDB.ts
+++ b/packages/api/src/mcp/registry/db/ServerConfigsDB.ts
@@ -11,6 +11,7 @@ import type { IServerConfigsRepositoryInterface } from '~/mcp/registry/ServerCon
import type { ParsedServerConfig, AddServerResult } from '~/mcp/types';
import type { ResolvedPrincipal } from '~/types/principal';
import { requireApiKeyReentryForRebinding } from '~/mcp/registry/binding';
+import { normalizeLegacyHeaderMaps } from '~/mcp/registry/compat';
import { MCPOAuthSecretReentryRequiredError } from '~/mcp/errors';
import { AccessControlService } from '~/acl/accessControlService';
@@ -118,24 +119,6 @@ function sanitizeUserManagedOAuthConfig(config: ParsedServerConfig): ParsedServe
};
}
-/** Normalizes legacy values that predate the current runtime config schemas. */
-function normalizePersistedConfig(config: ParsedServerConfig): ParsedServerConfig {
- const persistedConfig = config as ParsedServerConfig & {
- headers?: Record<string, string> | null;
- requestHeaders?: Record<string, string> | null;
- };
- if (persistedConfig.headers !== null && persistedConfig.requestHeaders !== null) {
- return config;
- }
-
- const { headers, requestHeaders, ...rest } = persistedConfig;
- return {
- ...rest,
- ...(headers != null && { headers }),
- ...(requestHeaders != null && { requestHeaders }),
- } as ParsedServerConfig;
-}
-
function normalizeOAuthUrl(value?: string): string | undefined {
if (!value) {
return value;
@@ -663,7 +646,7 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
...(authorId ? { author: authorId } : {}),
};
return sanitizeUserManagedOAuthConfig(
- await this.decryptConfig(normalizePersistedConfig(config)),
+ await this.decryptConfig(normalizeLegacyHeaderMaps(config)),
);
}