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

🐇 perf: Bound MCP Agent Access Scan by MCP Referencing Agents and Share the Read-Through Cache (#15028)

Marco Beretta57f3cb750b87
diff --git a/packages/api/src/acl/accessControlService.ts b/packages/api/src/acl/accessControlService.ts
index fbd41f0210..e3f09ee78d 100644
--- a/packages/api/src/acl/accessControlService.ts
+++ b/packages/api/src/acl/accessControlService.ts
@@ -126,6 +126,8 @@ export class AccessControlService {
* @param {string} [params.role] - Optional user role (if not provided, will query from DB)
* @param {string} params.resourceType - Type of resource (e.g., 'agent')
* @param {number} params.requiredPermissions - The minimum permission bits required (e.g., 1 for VIEW, 3 for VIEW+EDIT)
+ * @param {Types.ObjectId[]} [params.resourceIds] - Optional candidate bound; only these
+ * resources are considered, so the query cost scales with the candidate set
* @returns {Promise<Array>} Array of resource IDs
*/
public async findAccessibleResources({
@@ -133,11 +135,13 @@ export class AccessControlService {
role,
resourceType,
requiredPermissions,
+ resourceIds,
}: {
userId: string | Types.ObjectId;
role?: string;
resourceType: string;
requiredPermissions: number;
+ resourceIds?: Types.ObjectId[];
}): Promise<Types.ObjectId[]> {
try {
const principalsList = await this.getUserPrincipals({ userId, role });
@@ -145,6 +149,7 @@ export class AccessControlService {
principalsList,
resourceType,
requiredPermissions,
+ resourceIds,
});
} catch (error) {
if (error instanceof Error) {
@@ -172,10 +177,12 @@ export class AccessControlService {
principalsList,
resourceType,
requiredPermissions,
+ resourceIds,
}: {
principalsList: ResolvedPrincipal[];
resourceType: string;
requiredPermissions: number;
+ resourceIds?: Types.ObjectId[];
}): Promise<Types.ObjectId[]> {
try {
if (typeof requiredPermissions !== 'number' || requiredPermissions < 1) {
@@ -192,6 +199,7 @@ export class AccessControlService {
principalsList,
resourceType,
requiredPermissions,
+ resourceIds,
);
} catch (error) {
if (error instanceof Error) {
@@ -211,14 +219,18 @@ export class AccessControlService {
* @param {Object} params - Parameters for finding publicly accessible resources
* @param {ResourceType} params.resourceType - Type of resource (e.g., 'agent')
* @param {number} params.requiredPermissions - The minimum permission bits required (e.g., 1 for VIEW, 3 for VIEW+EDIT)
+ * @param {Types.ObjectId[]} [params.resourceIds] - Optional candidate bound; only these
+ * resources are considered, so the query cost scales with the candidate set
* @returns {Promise<Types.ObjectId[]>} Array of resource IDs
*/
public async findPubliclyAccessibleResources({
resourceType,
requiredPermissions,
+ resourceIds,
}: {
resourceType: ResourceType;
requiredPermissions: number;
+ resourceIds?: Types.ObjectId[];
}): Promise<Types.ObjectId[]> {
try {
if (typeof requiredPermissions !== 'number' || requiredPermissions < 1) {
@@ -227,7 +239,11 @@ export class AccessControlService {
this.validateResourceType(resourceType);
- return await this._dbMethods.findPublicResourceIds(resourceType, requiredPermissions);
+ return await this._dbMethods.findPublicResourceIds(
+ resourceType,
+ requiredPermissions,
+ resourceIds,
+ );
} catch (error) {
if (error instanceof Error) {
logger.error(`[PermissionService.findPubliclyAccessibleResources] Error: ${error.message}`);
diff --git a/packages/api/src/mcp/registry/MCPServersRegistry.ts b/packages/api/src/mcp/registry/MCPServersRegistry.ts
index 7bd6a75a98..e3382f3bbb 100644
--- a/packages/api/src/mcp/registry/MCPServersRegistry.ts
+++ b/packages/api/src/mcp/registry/MCPServersRegistry.ts
@@ -1,8 +1,8 @@
-import { Keyv } from 'keyv';
import { createHash } from 'crypto';
-import { logger } from '@librechat/data-schemas';
import { isProcessMCPServerConfig } from 'librechat-data-provider';
+import { logger, encryptV2, decryptV2, scopedCacheKey } from '@librechat/data-schemas';
import type { IServerConfigsRepositoryInterface } from './ServerConfigsRepositoryInterface';
+import type { ReadThroughTransforms, FillToken } from './cache/ReadThroughAllCache';
import type * as t from '~/mcp/types';
import {
ServerConfigsCacheFactory,
@@ -10,15 +10,41 @@ import {
CONFIG_CACHE_NAMESPACE,
} from './cache/ServerConfigsCacheFactory';
import { MCPInspectionFailedError, isMCPDomainNotAllowedError } from '~/mcp/errors';
+import { ReadThroughAllCache } from './cache/ReadThroughAllCache';
import { isPluginSourced, MCP_PLUGIN_SOURCE } from '~/utils/env';
+import { ReadThroughCache } from './cache/ReadThroughCache';
import { MCPServerInspector } from './MCPServerInspector';
import { ServerConfigsDB } from './db/ServerConfigsDB';
-import { cacheConfig } from '~/cache/cacheConfig';
+import { cacheConfig } from '~/cache';
import { withTimeout } from '~/utils';
/** How long a failure stub is considered fresh before re-attempting inspection (5 minutes). */
const CONFIG_STUB_RETRY_MS = 5 * 60 * 1000;
+/** 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> {
+ return {
+ encode: async (value) => encryptV2(JSON.stringify(value)),
+ decode: async (raw) => JSON.parse(await decryptV2(raw)),
+ };
+}
+
+/** The per-server cache also negative-caches lookups, so its envelope keeps a
+ * stored "absent" (null) distinguishable from "not cached". */
+function perServerStoreTransforms(): ReadThroughTransforms<t.ParsedServerConfig | undefined> {
+ return {
+ encode: async (value) => encryptV2(JSON.stringify({ config: value ?? null })),
+ decode: async (raw) => {
+ const decoded = JSON.parse(await decryptV2(raw)) as {
+ config: t.ParsedServerConfig | null;
+ };
+ return decoded.config ?? undefined;
+ },
+ };
+}
+
/**
* Provenance to persist for a config being stored in `tier`.
*
@@ -170,11 +196,14 @@ export class MCPServersRegistry {
private readonly allowedAddresses?: string[] | null;
/** Resolves the per-request (tenant-scoped) merged allowlists; falls back to the base above. */
private readonly allowlistResolver?: MCPAllowlistResolver;
- private readonly readThroughCache: Keyv<t.ParsedServerConfig>;
- private readonly readThroughCacheAll: Keyv<Record<string, t.ParsedServerConfig>>;
+ private readonly readThroughCache: ReadThroughCache<t.ParsedServerConfig | undefined>;
+ private readonly readThroughCacheAll: ReadThroughAllCache<Record<string, t.ParsedServerConfig>>;
private readonly pendingGetAllPromises = new Map<
string,
- Promise<Record<string, t.ParsedServerConfig>>
+ {
+ generation: string;
+ promise: Promise<Record<string, t.ParsedServerConfig>>;
+ }
>();
/** Tracks in-flight config server initializations to prevent duplicate work. */
@@ -202,15 +231,18 @@ export class MCPServersRegistry {
const ttl = cacheConfig.MCP_REGISTRY_CACHE_TTL;
- this.readThroughCache = new Keyv<t.ParsedServerConfig>({
- namespace: 'mcp-registry-read-through',
+ /** Per-server entries are invalidated by targeted deletes. */
+ this.readThroughCache = new ReadThroughCache<t.ParsedServerConfig | undefined>(
+ 'mcp-registry-read-through',
ttl,
- });
+ perServerStoreTransforms(),
+ );
- this.readThroughCacheAll = new Keyv<Record<string, t.ParsedServerConfig>>({
- namespace: 'mcp-registry-read-through-all',
+ this.readThroughCacheAll = new ReadThroughAllCache<Record<string, t.ParsedServerConfig>>(
+ 'mcp-registry-read-through-all',
ttl,
- });
+ encryptedStoreTransforms<Record<string, t.ParsedServerConfig>>(),
+ );
}
/** Creates and initializes the singleton MCPServersRegistry instance */
@@ -324,8 +356,9 @@ export class MCPServersRegistry {
const cacheKey = this.getReadThroughCacheKey(serverName, userId);
let base: t.ParsedServerConfig | undefined;
- if (await this.readThroughCache.has(cacheKey)) {
- base = await this.readThroughCache.get(cacheKey);
+ const cached = await this.readThroughCache.getEntry(cacheKey);
+ if (cached.hit) {
+ base = cached.value;
} else {
const configFromYaml = await this.cacheConfigsRepo.get(serverName);
if (configFromYaml) {
@@ -333,7 +366,7 @@ export class MCPServersRegistry {
} else {
base = await this.dbConfigsRepo.get(serverName, userId);
}
- await this.readThroughCache.set(cacheKey, base);
+ await this.readThroughCache.set(cacheKey, base, cached.fill);
}
if (!candidate) return base;
@@ -405,24 +438,36 @@ export class MCPServersRegistry {
userId?: string,
role?: string,
): Promise<Record<string, t.ParsedServerConfig>> {
- const cacheKey = userId ?? '__no_user__';
+ /** Tenant-scoped (also covering the single-flight map): the DB read behind
+ * a miss is filtered by the active tenant, so entries and in-flight
+ * builds must partition the same way. */
+ const cacheKey = scopedCacheKey(userId ?? '__no_user__');
+
+ const cached = await this.readThroughCacheAll.get(cacheKey);
+ if (cached.hit) {
+ return cached.value ?? {};
+ }
- if (await this.readThroughCacheAll.has(cacheKey)) {
- return (await this.readThroughCacheAll.get(cacheKey)) ?? {};
+ const fill = cached.fill;
+ if (fill?.generation == null) {
+ return this.fetchBaseServerConfigs(cacheKey, userId, role, fill);
}
const pending = this.pendingGetAllPromises.get(cacheKey);
- if (pending) {
- return pending;
+ if (pending?.generation === fill.generation) {
+ return pending.promise;
}
- const fetchPromise = this.fetchBaseServerConfigs(cacheKey, userId, role);
- this.pendingGetAllPromises.set(cacheKey, fetchPromise);
+ const fetchPromise = this.fetchBaseServerConfigs(cacheKey, userId, role, fill);
+ const pendingFill = { generation: fill.generation, promise: fetchPromise };
+ this.pendingGetAllPromises.set(cacheKey, pendingFill);
try {
return await fetchPromise;
} finally {
- this.pendingGetAllPromises.delete(cacheKey);
+ if (this.pendingGetAllPromises.get(cacheKey) === pendingFill) {
+ this.pendingGetAllPromises.delete(cacheKey);
+ }
}
}
@@ -430,6 +475,7 @@ export class MCPServersRegistry {
cacheKey: string,
userId?: string,
role?: string,
+ fill?: FillToken,
): Promise<Record<string, t.ParsedServerConfig>> {
const [dbConfigs, yamlConfigs] = await Promise.all([
this.dbConfigsRepo.getAll(userId, role),
@@ -440,7 +486,7 @@ export class MCPServersRegistry {
const result = { ...dbConfigs, ...yamlConfigs };
- await this.readThroughCacheAll.set(cacheKey, result);
+ await this.readThroughCacheAll.set(cacheKey, result, fill);
return result;
}
@@ -461,7 +507,7 @@ export class MCPServersRegistry {
source: resolveServerSource(config, 'yaml'),
};
const result = await configRepo.add(serverName, stubConfig, userId);
- await this.invalidateServerReadCaches(result.serverName, userId);
+ await this.invalidateServerReadCaches(result.serverName, userId, 'CACHE');
this.resetYamlServerNamesMemo();
return result;
}
@@ -506,7 +552,7 @@ export class MCPServersRegistry {
await this.getOperatorManagedServerNames(reservedServerNames),
)
: await configRepo.add(serverName, tagged, userId);
- await this.invalidateServerReadCaches(result.serverName, userId);
+ await this.invalidateServerReadCaches(result.serverName, userId, storageLocation);
if (storageLocation === 'CACHE') {
this.resetYamlServerNamesMemo();
}
@@ -554,7 +600,7 @@ export class MCPServersRegistry {
const updatedConfig = { ...parsedConfig, updatedAt: Date.now() };
await configRepo.update(serverName, updatedConfig, userId);
- await this.invalidateServerReadCaches(serverName, userId);
+ await this.invalidateServerReadCaches(serverName, userId, storageLocation);
return { serverName, config: updatedConfig };
}
@@ -616,7 +662,7 @@ export class MCPServersRegistry {
): Promise<t.ParsedServerConfig> {
const configRepo = this.getConfigRepository(storageLocation);
await configRepo.update(serverName, parsedConfig, userId);
- await this.invalidateServerReadCaches(serverName, userId);
+ await this.invalidateServerReadCaches(serverName, userId, storageLocation);
return parsedConfig;
}
@@ -824,9 +870,10 @@ export class MCPServersRegistry {
await Promise.all([
this.configCacheRepo.reset(),
- // Only clear readThroughCacheAll (merged results that may include stale config servers).
+ // Only invalidate readThroughCacheAll (merged results that may include stale config servers).
// readThroughCache (individual YAML/user lookups) is unaffected by config mutations.
- this.readThroughCacheAll.clear(),
+ // Operator config changes are global, so the eviction crosses tenants.
+ this.readThroughCacheAll.invalidateAllGlobal(),
]);
if (evictedNames.length > 0) {
@@ -851,7 +898,7 @@ export class MCPServersRegistry {
await this.cacheConfigsRepo.reset();
await this.configCacheRepo.reset();
await this.readThroughCache.clear();
- await this.readThroughCacheAll.clear();
+ await this.readThroughCacheAll.invalidateAllGlobal();
this.resetYamlServerNamesMemo();
}
@@ -862,7 +909,7 @@ export class MCPServersRegistry {
): Promise<void> {
const configRepo = this.getConfigRepository(storageLocation);
await configRepo.remove(serverName, userId);
- await this.invalidateServerReadCaches(serverName, userId);
+ await this.invalidateServerReadCaches(serverName, userId, storageLocation);
if (storageLocation === 'CACHE') {
this.resetYamlServerNamesMemo();
}
@@ -881,14 +928,35 @@ export class MCPServersRegistry {
}
}
+ /** Tenant-scoped because DB-backed lookups are filtered by the active tenant:
+ * an entry populated in one tenant's context must never satisfy another's. */
private getReadThroughCacheKey(serverName: string, userId?: string): string {
- return userId ? `${serverName}::${userId}` : serverName;
+ return scopedCacheKey(userId ? `${serverName}::${userId}` : serverName);
}
- private async invalidateServerReadCaches(serverName: string, userId?: string): Promise<void> {
+ /**
+ * DB-backed servers and their ACL grants are tenant-scoped data, so their
+ * invalidation stays within the acting tenant. CACHE-tier (YAML/App
+ * repository) entries are global, so those mutations evict across tenants:
+ * the per-server cache cannot enumerate tenant-scoped keys, so it clears the
+ * namespace, and the aggregate map uses its global path.
+ */
+ private async invalidateServerReadCaches(
+ serverName: string,
+ userId?: string,
+ storageLocation?: 'CACHE' | 'DB',
+ ): Promise<void> {
+ if (storageLocation === 'CACHE') {
+ await Promise.all([
+ this.readThroughCache.clear(),
+ this.readThroughCacheAll.invalidateAllGlobal(),
+ ]);
+ return;
+ }
+
const deletes = [
this.readThroughCache.delete(this.getReadThroughCacheKey(serverName)),
- this.readThroughCacheAll.clear(),
+ this.readThroughCacheAll.invalidateAll(),
];
if (userId) {
diff --git a/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.test.ts b/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.test.ts
index 8964c15c19..d5a97b239b 100644
--- a/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.test.ts
+++ b/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.test.ts
@@ -29,6 +29,7 @@ jest.mock('@librechat/data-schemas', () => ({
error: jest.fn(),
debug: jest.fn(),
},
+ scopedCacheKey: (baseKey: string) => baseKey,
}));
// Mock ServerConfigsDB to avoid mongoose dependency
diff --git a/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.cache_integration.spec.ts b/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.cache_integration.spec.ts
index 3521f7f83e..85fd7105ce 100644
--- a/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.cache_integration.spec.ts
+++ b/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.cache_integration.spec.ts
@@ -67,6 +67,10 @@ describe('MCPServersRegistry Redis Integration Tests', () => {
process.env.REDIS_KEY_PREFIX =
process.env.REDIS_KEY_PREFIX ??
`MCPServersRegistry-IntegrationTest-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+ // The read-through caches encrypt entries before they reach the shared store
+ process.env.CREDS_KEY =
+ process.env.CREDS_KEY ?? '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+ process.env.CREDS_IV = process.env.CREDS_IV ?? '0123456789abcdef0123456789abcdef';
// Import modules after setting env vars
const registryModule = await import('../MCPServersRegistry');
@@ -244,7 +248,7 @@ describe('MCPServersRegistry Redis Integration Tests', () => {
await registry.addServer('server2', testRawConfig, 'CACHE');
await registry.addServer('server3', testRawConfig, 'CACHE');
- await registry['readThroughCacheAll'].clear();
+ await registry['readThroughCacheAll'].invalidateAll();
const cacheRepoGetAllSpy = jest.spyOn(registry['cacheConfigsRepo'], 'getAll');
@@ -268,7 +272,7 @@ describe('MCPServersRegistry Redis Integration Tests', () => {
it('should handle different userIds independently', async () => {
await registry.addServer('shared_server', testRawConfig, 'CACHE');
- await registry['readThroughCacheAll'].clear();
+ await registry['readThroughCacheAll'].invalidateAll();
const cacheRepoGetAllSpy = jest.spyOn(registry['cacheConfigsRepo'], 'getAll');
@@ -290,7 +294,7 @@ describe('MCPServersRegistry Redis Integration Tests', () => {
await registry.addServer(`stress_server_${i}`, testRawConfig, 'CACHE');
}
- await registry['readThroughCacheAll'].clear();
+ await registry['readThroughCacheAll'].invalidateAll();
const concurrentCalls = 50;
const startTime = Date.now();
@@ -320,7 +324,7 @@ describe('MCPServersRegistry Redis Integration Tests', () => {
'CACHE',
);
- await registry['readThroughCacheAll'].clear();
+ await registry['readThroughCacheAll'].invalidateAll();
const results = await Promise.all([
registry.getAllServerConfigs(),
diff --git a/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts b/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts
index 5833d68be4..29d0db03ec 100644
--- a/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts
+++ b/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts
@@ -1,3 +1,4 @@
+import './helpers/setupCredsEnv';
import { logger } from '@librechat/data-schemas';
import type * as t from '~/mcp/types';
import { MCPServersRegistry } from '~/mcp/registry/MCPServersRegistry';
@@ -105,6 +106,89 @@ describe('MCPServersRegistry', () => {
expect(configs).toHaveProperty('user_server');
});
+ it('should partition read-through entries by tenant', async () => {
+ const { tenantStorage } = await import('@librechat/data-schemas');
+ const dbGetAll = jest.spyOn(registry['dbConfigsRepo'], 'getAll');
+ dbGetAll.mockResolvedValueOnce({ tenant_a_server: testParsedConfig });
+ dbGetAll.mockResolvedValueOnce({ tenant_b_server: testParsedConfig });
+
+ /** The DB read behind each miss is tenant-filtered, so the cached maps
+ * must never cross tenants even for the same userId. */
+ const inA = await tenantStorage.run(
+ { tenantId: 'tenant-a' },
+ async () => await registry.getAllServerConfigs('user-1'),
+ );
+ const inB = await tenantStorage.run(
+ { tenantId: 'tenant-b' },
+ async () => await registry.getAllServerConfigs('user-1'),
+ );
+
+ expect(Object.keys(inA)).toEqual(['tenant_a_server']);
+ expect(Object.keys(inB)).toEqual(['tenant_b_server']);
+ expect(dbGetAll).toHaveBeenCalledTimes(2);
+
+ /** Within one tenant the entry is reused without a second DB read. */
+ const inAAgain = await tenantStorage.run(
+ { tenantId: 'tenant-a' },
+ async () => await registry.getAllServerConfigs('user-1'),
+ );
+ expect(Object.keys(inAAgain)).toEqual(['tenant_a_server']);
+ expect(dbGetAll).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not join or erase a single-flight fetch from another generation', async () => {
+ let resolveOld!: (value: Record<string, t.ParsedServerConfig>) => void;
+ let resolveFresh!: (value: Record<string, t.ParsedServerConfig>) => void;
+ let signalOldStarted!: () => void;
+ let signalFreshStarted!: () => void;
+ const oldResult = new Promise<Record<string, t.ParsedServerConfig>>((resolve) => {
+ resolveOld = resolve;
+ });
+ const freshResult = new Promise<Record<string, t.ParsedServerConfig>>((resolve) => {
+ resolveFresh = resolve;
+ });
+ const oldStarted = new Promise<void>((resolve) => {
+ signalOldStarted = resolve;
+ });
+ const freshStarted = new Promise<void>((resolve) => {
+ signalFreshStarted = resolve;
+ });
+ const dbGetAll = jest
+ .spyOn(registry['dbConfigsRepo'], 'getAll')
+ .mockImplementationOnce(async () => {
+ signalOldStarted();
+ return oldResult;
+ })
+ .mockImplementationOnce(async () => {
+ signalFreshStarted();
+ return freshResult;
+ });
+
+ const oldRequest = registry.getAllServerConfigs('user-1');
+ await oldStarted;
+ expect(dbGetAll).toHaveBeenCalledTimes(1);
+
+ await registry['readThroughCacheAll'].invalidateAll();
+ const freshRequest = registry.getAllServerConfigs('user-1');
+ await freshStarted;
+ expect(dbGetAll).toHaveBeenCalledTimes(2);
+
+ resolveOld({ old_server: testParsedConfig });
+ await expect(oldRequest).resolves.toEqual({ old_server: testParsedConfig });
+
+ const joinedFreshRequest = registry.getAllServerConfigs('user-1');
+
+ resolveFresh({ fresh_server: testParsedConfig });
+ await expect(freshRequest).resolves.toEqual({ fresh_server: testParsedConfig });
+ await expect(joinedFreshRequest).resolves.toEqual({ fresh_server: testParsedConfig });
+ expect(dbGetAll).toHaveBeenCalledTimes(2);
+
+ await expect(registry.getAllServerConfigs('user-1')).resolves.toEqual({
+ fresh_server: testParsedConfig,
+ });
+ expect(dbGetAll).toHaveBeenCalledTimes(2);
+ });
+
it('should keep YAML servers authoritative when a DB server has the same name', async () => {
const warnSpy = jest.spyOn(logger, 'warn').mockImplementation();
const yamlConfig = { ...testParsedConfig, source: 'yaml' as const, title: 'YAML Slack' };
diff --git a/packages/api/src/mcp/registry/__tests__/ServerConfigsDB.test.ts b/packages/api/src/mcp/registry/__tests__/ServerConfigsDB.test.ts
index 45536f2e4d..8b36ef6437 100644
--- a/packages/api/src/mcp/registry/__tests__/ServerConfigsDB.test.ts
+++ b/packages/api/src/mcp/registry/__tests__/ServerConfigsDB.test.ts
@@ -40,6 +40,13 @@ const createSSEConfig = (
let dbMethods: ReturnType<CreateMethodsType>;
+/** `Model.find` overloads reduce the spy's inferred arguments to an empty tuple,
+ * so the recorded calls are re-typed here and mapped to their filter. */
+function aclFindFilters(spy: jest.SpyInstance): Array<Record<string, unknown>> {
+ const calls = spy.mock.calls as unknown as Array<[Record<string, unknown>]>;
+ return calls.map(([filter]) => filter);
+}
+
beforeAll(async () => {
// Set encryption keys BEFORE importing modules that use crypto
process.env.CREDS_KEY = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
@@ -1359,6 +1366,103 @@ describe('ServerConfigsDB', () => {
expect(result['agent-only-server'].consumeOnly).toBe(true);
});
+ it('should bound the agent ACL query to agents that reference MCP servers', async () => {
+ const config = createSSEConfig('Bounded Server');
+ const created = await serverConfigsDB.add('temp', config, userId);
+
+ const Agent = mongoose.models.Agent;
+ const referencingAgent = await Agent.create({
+ id: 'referencing-agent',
+ name: 'Referencing Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: new mongoose.Types.ObjectId(userId),
+ mcpServerNames: [created.serverName],
+ });
+ // Accessible to userId2 but references no MCP server: these must not
+ // inflate the agent-side ACL query (#14016)
+ const spectatorAgent = await Agent.create({
+ id: 'spectator-agent',
+ name: 'Spectator Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: new mongoose.Types.ObjectId(userId),
+ });
+
+ const agentRole = await mongoose.models.AccessRole.findOne({
+ accessRoleId: AccessRoleIds.AGENT_VIEWER,
+ });
+ for (const agent of [referencingAgent, spectatorAgent]) {
+ await mongoose.models.AclEntry.create({
+ principalType: PrincipalType.USER,
+ principalModel: PrincipalModel.USER,
+ principalId: new mongoose.Types.ObjectId(userId2),
+ resourceType: ResourceType.AGENT,
+ resourceId: agent._id,
+ permBits: PermissionBits.VIEW,
+ roleId: agentRole!._id,
+ grantedBy: new mongoose.Types.ObjectId(userId),
+ });
+ }
+
+ const findSpy = jest.spyOn(mongoose.models.AclEntry, 'find');
+ try {
+ const result = await serverConfigsDB.getAll(userId2);
+ expect(result['bounded-server']?.consumeOnly).toBe(true);
+
+ const agentSideFilters = aclFindFilters(findSpy).filter(
+ (filter) => filter.resourceType === ResourceType.AGENT,
+ );
+ expect(agentSideFilters).toHaveLength(1);
+ const boundIds = (agentSideFilters[0]?.resourceId as { $in?: unknown[] } | undefined)
+ ?.$in;
+ expect(boundIds).toHaveLength(1);
+ expect(String(boundIds?.[0])).toBe(referencingAgent._id.toString());
+ } finally {
+ findSpy.mockRestore();
+ }
+ });
+
+ it('should skip the agent ACL query entirely when no agent references MCP servers', async () => {
+ const config = createSSEConfig('Unreferenced Server');
+ await serverConfigsDB.add('temp', config, userId);
+
+ const Agent = mongoose.models.Agent;
+ const agent = await Agent.create({
+ id: 'plain-agent',
+ name: 'Plain Agent',
+ provider: 'openai',
+ model: 'gpt-4',
+ author: new mongoose.Types.ObjectId(userId),
+ });
+ const agentRole = await mongoose.models.AccessRole.findOne({
+ accessRoleId: AccessRoleIds.AGENT_VIEWER,
+ });
+ await mongoose.models.AclEntry.create({
+ principalType: PrincipalType.USER,
+ principalModel: PrincipalModel.USER,
+ principalId: new mongoose.Types.ObjectId(userId2),
+ resourceType: ResourceType.AGENT,
+ resourceId: agent._id,
+ permBits: PermissionBits.VIEW,
+ roleId: agentRole!._id,
+ grantedBy: new mongoose.Types.ObjectId(userId),
+ });
+
+ const findSpy = jest.spyOn(mongoose.models.AclEntry, 'find');
+ try {
+ const result = await serverConfigsDB.getAll(userId2);
+ expect(result['unreferenced-server']).toBeUndefined();
+
+ const agentSideFilters = aclFindFilters(findSpy).filter(
+ (filter) => filter.resourceType === ResourceType.AGENT,
+ );
+ expect(agentSideFilters).toHaveLength(0);
+ } finally {
+ findSpy.mockRestore();
+ }
+ });
+
it('should deduplicate servers with both direct and agent access', async () => {
const config = createSSEConfig('Dedup Server');
const created = await serverConfigsDB.add('temp', config, userId);
diff --git a/packages/api/src/mcp/registry/__tests__/helpers/setupCredsEnv.ts b/packages/api/src/mcp/registry/__tests__/helpers/setupCredsEnv.ts
new file mode 100644
index 0000000000..d90f0da513
--- /dev/null
+++ b/packages/api/src/mcp/registry/__tests__/helpers/setupCredsEnv.ts
@@ -0,0 +1,7 @@
+/** The registry read-through caches encrypt entries before they reach the
+ * shared store, and the crypto module captures CREDS_KEY/CREDS_IV at import
+ * time. Importing this module first lets static-import suites provide them. */
+process.env.CREDS_KEY ??= '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+process.env.CREDS_IV ??= '0123456789abcdef0123456789abcdef';
+
+export {};
diff --git a/packages/api/src/mcp/registry/cache/ReadThroughAllCache.ts b/packages/api/src/mcp/registry/cache/ReadThroughAllCache.ts
new file mode 100644
index 0000000000..667100839d
--- /dev/null
+++ b/packages/api/src/mcp/registry/cache/ReadThroughAllCache.ts
@@ -0,0 +1,298 @@
+import { Keyv } from 'keyv';
+import { randomUUID } from 'crypto';
+import { logger, scopedCacheKey, getTenantId, SYSTEM_TENANT_ID } from '@librechat/data-schemas';
+import { standardCache } from '~/cache';
+
+/** Base key holding the active generation tag; the effective key is
+ * tenant-scoped, so one tenant's mutations cannot orphan another's entries. */
+const GENERATION_KEY = '__generation__';
+const GLOBAL_GENERATION_KEY = '__global_generation__';
+
+interface MemoEntry<T> {
+ value: T;
+ expiresAt: number;
+ /** Tenant the entry was memoized under, so a tenant-scoped invalidation
+ * evicts only that tenant's memo entries. */
+ tenantId: string | undefined;
+}
+
+/** State a miss observed, handed back with the miss so the matching fill (and
+ * only that fill) can be fenced when an invalidation completed first. */
+export interface FillToken {
+ key: string;
+ generation: string | null;
+}
+
+/** Result of one read: `hit` distinguishes a stored value from a miss, and
+ * `fill` is present exactly when the caller should thread it into set(). */
+export interface CacheRead<T> {
+ hit: boolean;
+ value: T | undefined;
+ fill?: FillToken;
+}
+
+/** Store-side value transforms; the shared store only ever sees `encode` output. */
+export interface ReadThroughTransforms<T> {
+ encode?: (value: T) => Promise<string> | string;
+ decode?: (raw: string) => Promise<T> | T;
+}
+
+/**
+ * Redis-capable read-through cache for per-user aggregate config maps.
+ *
+ * The backing store comes from {@link standardCache}, so entries live in Redis
+ * when it is configured (shared across instances, see #14016) and in process
+ * memory otherwise. Hot-path invalidation never scans the keyspace:
+ * {@link invalidateAll} swaps the active generation tag for a fresh UUID,
+ * orphaning every entry written under a previous generation, and the store TTL
+ * reclaims them. This mirrors the aggregate-key lesson from #11624/#12408,
+ * where SCAN-based invalidation stalled large deployments. The generation tag
+ * is tenant-scoped (entries are too) and lives in its own store created
+ * without a TTL so it can never expire before the entries written under it;
+ * {@link invalidateAllGlobal} provides the scanning variant for genuinely
+ * cross-tenant resets.
+ *
+ * Values may carry secrets (decrypted MCP credentials), so the caller can
+ * inject {@link ReadThroughTransforms} to keep the shared store ciphertext
+ * only; the process-local memo keeps working with plaintext, matching the
+ * pre-Redis status quo where these values never left the process.
+ *
+ * A process-local memo absorbs repeated reads within one TTL window, the same
+ * pattern as the local snapshot in `ServerConfigsCacheRedisAggregateKey`, added
+ * because the registry resolves all-server configs many times per chat request.
+ * An opportunistic sweep bounds the memo so one-time users cannot accumulate.
+ * Each miss returns a fill token capturing the generation it observed, and the
+ * matching set() is fenced by it, so a value computed before an invalidation
+ * cannot be written or memoized after it, even when concurrent fills for the
+ * same key straddle the invalidation.
+ * Cross-instance worst-case staleness is therefore bounded by the memo TTL,
+ * matching the documented 2x MCP_REGISTRY_CACHE_TTL trade-off.
+ *
+ * A ttl of zero or less disables the cache entirely: entries derive from ACL
+ * access, and without a TTL there is no bound on how long a revoked user could
+ * keep receiving a stale map.
+ */
+export class ReadThroughAllCache<T> {
+ private readonly cache: Keyv;
+ private readonly generationCache: Keyv;
+ private readonly ttl: number;
+ private readonly transforms?: ReadThroughTransforms<T>;
+ private readonly memo = new Map<string, MemoEntry<T>>();
+ private lastSweepAt = 0;
+
+ constructor(namespace: string, ttl: number, transforms?: ReadThroughTransforms<T>) {
+ this.cache = standardCache(namespace, ttl);
+ this.generationCache = standardCache(`${namespace}::generation`);
+ this.ttl = ttl;
+ this.transforms = transforms;
+ }
+
+ private get enabled(): boolean {
+ return this.ttl > 0;
+ }
+
+ private entryKey(generation: string, key: string): string {
+ return `${generation}::${key}`;
+ }
+
+ /** Never throws. Returns undefined when the generation cannot be read: that
+ * must surface as a miss, not as generation "0", which is a real first
+ * generation whose unexpired entries could otherwise be revived by a
+ * transient read failure. */
+ private async readGeneration(): Promise<string | undefined> {
+ let globalGeneration: unknown;
+ let tenantGeneration: unknown;
+ try {
+ [globalGeneration, tenantGeneration] = await Promise.all([
+ this.generationCache.get(GLOBAL_GENERATION_KEY),
+ this.generationCache.get(scopedCacheKey(GENERATION_KEY)),
+ ]);
+ } catch (error) {
+ logger.warn('[ReadThroughAllCache] Generation read failed:', error);
+ return undefined;
+ }
+ const global = typeof globalGeneration === 'string' ? globalGeneration : '0';
+ const tenant = typeof tenantGeneration === 'string' ? tenantGeneration : '0';
+ return `${global}:${tenant}`;
+ }
+
+ /** Effective tenant for cache scoping, mirroring scopedCacheKey: the system
+ * context and absent context both address the unscoped partition. */
+ private currentTenantId(): string | undefined {
+ const tenantId = getTenantId();
+ return !tenantId || tenantId === SYSTEM_TENANT_ID ? undefined : tenantId;
+ }
+
+ /** At most one pass per TTL window, so expired entries from one-time users
+ * cannot accumulate unboundedly between global invalidations. */
+ private sweepMemo(): void {
+ const now = Date.now();
+ if (now - this.lastSweepAt < this.ttl) {
+ return;
+ }
+ this.lastSweepAt = now;
+ for (const [key, entry] of this.memo) {
+ if (now >= entry.expiresAt) {
+ this.memo.delete(key);
+ }
+ }
+ }
+
+ async get(key: string): Promise<CacheRead<T>> {
+ if (!this.enabled) {
+ return { hit: false, value: undefined };
+ }
+ const memoized = this.memo.get(key);
+ if (memoized != null) {
+ if (Date.now() < memoized.expiresAt) {
+ return { hit: true, value: memoized.value };
+ }
+ this.memo.delete(key);
+ }
+ const generation = await this.readGeneration();
+ if (generation == null) {
+ return { hit: false, value: undefined, fill: { key, generation: null } };
+ }
+ let raw: unknown;
+ try {
+ raw = await this.cache.get(this.entryKey(generation, key));
+ } catch (error) {
+ logger.warn('[ReadThroughAllCache] Store read failed; treating as a miss:', error);
+ return { hit: false, value: undefined, fill: { key, generation } };
+ }
+ if (raw === undefined) {
+ return { hit: false, value: undefined, fill: { key, generation } };
+ }
+ let value: T;
+ if (!this.transforms?.decode) {
+ value = raw as T;
+ } else {
+ try {
+ value = await this.transforms.decode(raw as string);
+ } catch (error) {
+ /** Fail open to a miss: an undecodable entry is stale across a key
+ * rotation, not a reason to break the request. */
+ logger.warn(
+ '[ReadThroughAllCache] Failed to decode cached entry; treating as a miss:',
+ error,
+ );
+ return { hit: false, value: undefined, fill: { key, generation } };
+ }
+ }
+ /** Re-check after the full read (decode included): an invalidation landing
+ * mid-read must not have its pre-mutation value memoized for a full TTL
+ * window. */
+ if ((await this.readGeneration()) !== generation) {
+ return { hit: false, value: undefined, fill: { key, generation } };
+ }
+ return { hit: true, value: this.memoize(key, value) };
+ }
+
+ private memoize(key: string, value: T): T {
+ this.memo.set(key, {
+ value,
+ expiresAt: Date.now() + this.ttl,
+ tenantId: this.currentTenantId(),
+ });
+ this.sweepMemo();
+ return value;
+ }
+
+ async set(key: string, value: T, fill?: FillToken): Promise<void> {
+ if (!this.enabled) {
+ return;
+ }
+ if (fill != null && fill.key === key && fill.generation == null) {
+ return;
+ }
+ const current = await this.readGeneration();
+ if (current == null) {
+ return;
+ }
+ if (fill != null && fill.key === key && current !== fill.generation) {
+ /** Fenced: this value was computed before an invalidation completed, so
+ * writing it (store or memo) would resurrect the pre-mutation map. */
+ return;
+ }
+ const generation = current;
+ try {
+ const stored = this.transforms?.encode ? await this.transforms.encode(value) : value;
+ await this.cache.set(this.entryKey(generation, key), stored);
+ } catch (error) {
+ /** A failed store write degrades to the memo only; the caller's result
+ * is already computed and must still be served. */
+ logger.warn('[ReadThroughAllCache] Failed to write cache entry:', error);
+ }
+ /** Same recheck as get(): skip the memo when an invalidation landed while
+ * this write was in flight, so the next read recomputes. */
+ if ((await this.readGeneration()) !== generation) {
+ return;
+ }
+ this.memo.set(key, {
+ value,
+ expiresAt: Date.now() + this.ttl,
+ tenantId: this.currentTenantId(),
+ });
+ this.sweepMemo();
+ }
+
+ /**
+ * Orphans the calling tenant's entries without scanning the keyspace.
+ * DB-backed MCP servers and ACL grants are tenant-scoped data, so one
+ * tenant's mutation has no business evicting another tenant's entries, in
+ * the store or in the process-local memo. Rejects when the shared generation
+ * cannot be rotated, so a persisted mutation is never reported as fully
+ * invalidated while stale shared entries remain addressable.
+ */
+ async invalidateAll(): Promise<void> {
+ const tenantId = this.currentTenantId();
+ this.evictTenantMemo(tenantId);
+ if (!this.enabled) {
+ return;
+ }
+ try {
+ /** A fresh UUID cannot regress: two racing invalidations may overwrite each
+ * other's tag, but neither can resurrect a prior generation's entries. */
+ await this.generationCache.set(scopedCacheKey(GENERATION_KEY), randomUUID());
+ } catch (error) {
+ logger.warn('[ReadThroughAllCache] Generation write failed:', error);
+ throw error;
+ }
+ /** A read that completed against the old generation while the write was in
+ * flight may have repopulated the memo after the first eviction. */
+ this.evictTenantMemo(tenantId);
+ }
+
+ /**
+ * Clears every entry across tenants by scanning the namespace. Reserved for
+ * genuinely global events (operator config changes, lifecycle resets) where
+ * the SCAN cost is rare and cross-tenant eviction is the point. Rejects when
+ * the shared global fence cannot be rotated.
+ */
+ async invalidateAllGlobal(): Promise<void> {
+ this.memo.clear();
+ if (!this.enabled) {
+ return;
+ }
+ try {
+ await this.generationCache.set(GLOBAL_GENERATION_KEY, randomUUID());
+ } catch (error) {
+ logger.warn('[ReadThroughAllCache] Global generation write failed:', error);
+ throw error;
+ }
+ this.memo.clear();
+ try {
+ await this.cache.clear();
+ } catch (error) {
+ logger.warn('[ReadThroughAllCache] Global clear failed:', error);
+ }
+ }
+
+ private evictTenantMemo(tenantId: string | undefined): void {
+ for (const [key, entry] of this.memo) {
+ if (entry.tenantId === tenantId) {
+ this.memo.delete(key);
+ }
+ }
+ }
+}
diff --git a/packages/api/src/mcp/registry/cache/ReadThroughCache.ts b/packages/api/src/mcp/registry/cache/ReadThroughCache.ts
new file mode 100644
index 0000000000..716c49bf98
--- /dev/null
+++ b/packages/api/src/mcp/registry/cache/ReadThroughCache.ts
@@ -0,0 +1,201 @@
+import { Keyv } from 'keyv';
+import { randomUUID } from 'crypto';
+import { logger, scopedCacheKey } from '@librechat/data-schemas';
+import type { ReadThroughTransforms } from './ReadThroughAllCache';
+import { standardCache } from '~/cache';
+
+const GENERATION_KEY = '__generation__';
+const GLOBAL_GENERATION_KEY = '__global_generation__';
+
+/** Invalidation state a per-server miss observed, handed back with the miss so
+ * the matching fill (and only that fill) can be fenced when a targeted delete
+ * or namespace clear completed first. */
+export interface FillToken {
+ key: string;
+ generation: string | null;
+}
+
+/**
+ * Redis-capable read-through cache for per-server config entries, the
+ * single-entry counterpart to {@link ReadThroughAllCache}.
+ *
+ * The store comes from {@link standardCache} (Redis when configured, process
+ * memory otherwise), values may be kept ciphertext via
+ * {@link ReadThroughTransforms}, and a ttl of zero or less disables the cache
+ * entirely because entries encode ACL decisions that must not outlive a
+ * revocation without a TTL bound.
+ *
+ * Each miss returns a fill token capturing the shared tenant and global
+ * generations it observed. A targeted mutation rotates the tenant generation,
+ * while a namespace reset rotates the global generation. The matching set() is
+ * fenced by that token, so a fill that straddles an invalidation remains under
+ * its old generation and cannot become visible again on any replica.
+ *
+ * Read and fill-write failures never reject: a Redis outage degrades reads to a
+ * miss and writes to a skip so the shared store stays an optimization on the
+ * request path. Mutation invalidations reject when their shared generation
+ * cannot be rotated, rather than reporting stale data as invalidated.
+ */
+export class ReadThroughCache<T> {
+ private readonly cache: Keyv;
+ private readonly generationCache: Keyv;
+ private readonly ttl: number;
+ private readonly transforms?: ReadThroughTransforms<T>;
+
+ constructor(namespace: string, ttl: number, transforms?: ReadThroughTransforms<T>) {
+ this.cache = standardCache(namespace, ttl);
+ this.generationCache = standardCache(`${namespace}::generation`);
+ this.ttl = ttl;
+ this.transforms = transforms;
+ }
+
+ private get enabled(): boolean {
+ return this.ttl > 0;
+ }
+
+ private entryKey(generation: string, key: string): string {
+ return `${generation}::${key}`;
+ }
+
+ private async readGeneration(): Promise<string | undefined> {
+ let globalGeneration: unknown;
+ let tenantGeneration: unknown;
+ try {
+ [globalGeneration, tenantGeneration] = await Promise.all([
+ this.generationCache.get(GLOBAL_GENERATION_KEY),
+ this.generationCache.get(scopedCacheKey(GENERATION_KEY)),
+ ]);
+ } catch (error) {
+ logger.warn('[ReadThroughCache] Generation read failed:', error);
+ return undefined;
+ }
+ const global = typeof globalGeneration === 'string' ? globalGeneration : '0';
+ const tenant = typeof tenantGeneration === 'string' ? tenantGeneration : '0';
+ return `${global}:${tenant}`;
+ }
+
+ /** Single decoded read: `hit` distinguishes a stored value (which may
+ * legitimately be absent) from a miss, so callers can negative-cache. An
+ * undecodable entry (e.g. after a credentials-key rotation) self-heals: it
+ * is deleted and reported as a miss so the caller refetches. */
+ async getEntry(key: string): Promise<{
+ hit: boolean;
+ value: T | undefined;
+ fill?: FillToken;
+ }> {
+ if (!this.enabled) {
+ return { hit: false, value: undefined };
+ }
+ const generation = await this.readGeneration();
+ if (generation == null) {
+ return { hit: false, value: undefined, fill: { key, generation: null } };
+ }
+ const cacheKey = this.entryKey(generation, key);
+ let raw: unknown;
+ try {
+ raw = await this.cache.get(cacheKey);
+ } catch (error) {
+ logger.warn('[ReadThroughCache] Store read failed; treating as a miss:', error);
+ return { hit: false, value: undefined, fill: { key, generation } };
+ }
+ if (raw === undefined) {
+ return { hit: false, value: undefined, fill: { key, generation } };
+ }
+ let value: T;
+ if (!this.transforms?.decode) {
+ value = raw as T;
+ } else {
+ try {
+ value = await this.transforms.decode(raw as string);
+ } catch (error) {
+ logger.warn(
+ '[ReadThroughCache] Failed to decode cached entry; deleting and missing:',
+ error,
+ );
+ try {
+ await this.cache.delete(cacheKey);
+ } catch (deleteError) {
+ logger.warn('[ReadThroughCache] Failed to delete undecodable cache entry:', deleteError);
+ }
+ return { hit: false, value: undefined, fill: { key, generation } };
+ }
+ }
+ const current = await this.readGeneration();
+ if (current !== generation) {
+ return { hit: false, value: undefined, fill: { key, generation: current ?? null } };
+ }
+ return { hit: true, value };
+ }
+
+ async set(key: string, value: T, fill?: FillToken): Promise<void> {
+ if (!this.enabled) {
+ return;
+ }
+ if (fill != null && fill.key === key && fill.generation == null) {
+ return;
+ }
+ const generation = await this.readGeneration();
+ if (generation == null) {
+ return;
+ }
+ if (fill != null && fill.key === key && fill.generation !== generation) {
+ /** Fenced: an invalidation completed while this value was being computed;
+ * writing it would undo the mutation for every replica. */
+ return;
+ }
+ const cacheKey = this.entryKey(generation, key);
+ try {
+ const stored = this.transforms?.encode ? await this.transforms.encode(value) : value;
+ await this.cache.set(cacheKey, stored);
+ } catch (error) {
+ logger.warn('[ReadThroughCache] Failed to write cache entry:', error);
+ return;
+ }
+ if ((await this.readGeneration()) !== generation) {
+ try {
+ await this.cache.delete(cacheKey);
+ } catch (error) {
+ logger.warn('[ReadThroughCache] Failed to delete stale cache write:', error);
+ }
+ }
+ }
+
+ async delete(key: string): Promise<void> {
+ if (!this.enabled) {
+ return;
+ }
+ const generation = await this.readGeneration();
+ try {
+ await this.generationCache.set(scopedCacheKey(GENERATION_KEY), randomUUID());
+ } catch (error) {
+ logger.warn('[ReadThroughCache] Generation write failed during delete:', error);
+ throw error;
+ }
+ if (generation == null) {
+ return;
+ }
+ try {
+ await this.cache.delete(this.entryKey(generation, key));
+ } catch (error) {
+ logger.warn('[ReadThroughCache] Failed to delete orphaned cache entry:', error);
+ }
+ }
+
+ /** Lifecycle resets only; not a hot-path invalidation. */
+ async clear(): Promise<void> {
+ if (!this.enabled) {
+ return;
+ }
+ try {
+ await this.generationCache.set(GLOBAL_GENERATION_KEY, randomUUID());
+ } catch (error) {
+ logger.warn('[ReadThroughCache] Global generation write failed:', error);
+ throw error;
+ }
+ try {
+ await this.cache.clear();
+ } catch (error) {
+ logger.warn('[ReadThroughCache] Failed to clear cache:', error);
+ }
+ }
+}
diff --git a/packages/api/src/mcp/registry/cache/__tests__/ReadThroughAllCache.cache_integration.spec.ts b/packages/api/src/mcp/registry/cache/__tests__/ReadThroughAllCache.cache_integration.spec.ts
new file mode 100644
index 0000000000..2a25cce14a
--- /dev/null
+++ b/packages/api/src/mcp/registry/cache/__tests__/ReadThroughAllCache.cache_integration.spec.ts
@@ -0,0 +1,115 @@
+import { randomUUID } from 'crypto';
+import { closeRedisClients } from '~/cache/__tests__/redisClients.helper';
+
+/**
+ * Redis-backed integration tests for the registry read-through cache (#14016).
+ * Two instances over one namespace model two containers: they share entries
+ * through Redis, and a generation invalidation on one orphans the entries for
+ * the other without any keyspace scan.
+ */
+describe('ReadThroughAllCache (Redis backing)', () => {
+ let originalEnv: NodeJS.ProcessEnv;
+ const testPrefix = 'RTAC-Integration-Test';
+
+ beforeEach(() => {
+ originalEnv = { ...process.env };
+ process.env.REDIS_PING_INTERVAL = '0';
+ process.env.REDIS_KEY_PREFIX = testPrefix;
+ process.env.REDIS_RETRY_MAX_ATTEMPTS = '5';
+ process.env.USE_REDIS = 'true';
+ process.env.USE_REDIS_CLUSTER = 'false';
+ process.env.REDIS_URI = 'redis://127.0.0.1:6379';
+ jest.resetModules();
+ });
+
+ afterEach(async () => {
+ const redisClients = await import('~/cache/redisClients');
+ const { ioredisClient } = redisClients;
+ if (ioredisClient && ioredisClient.status === 'ready') {
+ try {
+ const keys = await ioredisClient.keys(`${testPrefix}*`);
+ if (keys.length > 0) {
+ await ioredisClient.del(...keys);
+ }
+ } catch (error: unknown) {
+ if (error instanceof Error) {
+ console.warn('Error cleaning up test keys:', error.message);
+ }
+ }
+ }
+ await closeRedisClients(redisClients);
+ process.env = originalEnv;
+ });
+
+ test('entries are shared across instances through Redis', async () => {
+ const { ReadThroughAllCache } = await import('../ReadThroughAllCache');
+ const namespace = `rtac-redis-${randomUUID()}`;
+ const writer = new ReadThroughAllCache<string>(namespace, 60_000);
+ const reader = new ReadThroughAllCache<string>(namespace, 60_000);
+
+ await writer.set('user-1', 'written-by-other-instance');
+
+ await expect(reader.get('user-1')).resolves.toEqual({
+ hit: true,
+ value: 'written-by-other-instance',
+ });
+ });
+
+ test('invalidateAll on one instance orphans entries for the other', async () => {
+ const { ReadThroughAllCache } = await import('../ReadThroughAllCache');
+ const namespace = `rtac-redis-${randomUUID()}`;
+ const writer = new ReadThroughAllCache<string>(namespace, 60_000);
+ const reader = new ReadThroughAllCache<string>(namespace, 60_000);
+
+ await writer.set('user-1', 'stale-soon');
+ await writer.invalidateAll();
+
+ /** The reader never memoized the pre-invalidation value, so its read must
+ * miss through Redis under the new generation. */
+ await expect(reader.get('user-1')).resolves.toEqual(expect.objectContaining({ hit: false }));
+
+ await writer.set('user-1', 'fresh');
+ await expect(reader.get('user-1')).resolves.toEqual({ hit: true, value: 'fresh' });
+ });
+
+ test('stores per-user entries under distinct keys in Redis', async () => {
+ const { ReadThroughAllCache } = await import('../ReadThroughAllCache');
+ const namespace = `rtac-redis-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+
+ await cache.set('user-1', 'a');
+ await cache.set('user-2', 'b');
+
+ const { ioredisClient } = await import('~/cache/redisClients');
+ if (!ioredisClient) {
+ throw new Error('ioredisClient is null');
+ }
+ const keys = await ioredisClient.keys(`${testPrefix}*${namespace}*`);
+ expect(keys.some((key) => key.includes('user-1'))).toBe(true);
+ expect(keys.some((key) => key.includes('user-2'))).toBe(true);
+ });
+
+ test('with transforms, the shared store only ever holds ciphertext', async () => {
+ const { ReadThroughAllCache } = await import('../ReadThroughAllCache');
+ const namespace = `rtac-redis-${randomUUID()}`;
+ const transforms = {
+ encode: (value: string) => `enc:${Buffer.from(value).toString('base64')}`,
+ decode: (raw: string) => Buffer.from(raw.slice(4), 'base64').toString('utf8'),
+ };
+ const writer = new ReadThroughAllCache<string>(namespace, 60_000, transforms);
+ const reader = new ReadThroughAllCache<string>(namespace, 60_000, transforms);
+ /** A reader without transforms returns whatever the shared store holds. */
+ const plainReader = new ReadThroughAllCache<string>(namespace, 60_000);
+
+ await writer.set('user-1', 'super-secret-credential');
+
+ await expect(reader.get('user-1')).resolves.toEqual({
+ hit: true,
+ value: 'super-secret-credential',
+ });
+
+ const stored = await plainReader.get('user-1');
+ expect(stored).toEqual({ hit: true, value: expect.stringContaining('enc:') });
+ expect(stored.value).not.toBe('super-secret-credential');
+ });
+});
diff --git a/packages/api/src/mcp/registry/cache/__tests__/ReadThroughAllCache.spec.ts b/packages/api/src/mcp/registry/cache/__tests__/ReadThroughAllCache.spec.ts
new file mode 100644
index 0000000000..adc18f28f9
--- /dev/null
+++ b/packages/api/src/mcp/registry/cache/__tests__/ReadThroughAllCache.spec.ts
@@ -0,0 +1,142 @@
+import { randomUUID } from 'crypto';
+
+type CacheCtor = typeof import('../ReadThroughAllCache').ReadThroughAllCache;
+
+describe('ReadThroughAllCache (in-memory backing)', () => {
+ let originalEnv: NodeJS.ProcessEnv;
+
+ const load = async (): Promise<CacheCtor> =>
+ (await import('../ReadThroughAllCache')).ReadThroughAllCache;
+
+ beforeEach(() => {
+ originalEnv = { ...process.env };
+ process.env.USE_REDIS = 'false';
+ jest.resetModules();
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ test('stores and returns values per key', async () => {
+ const Cache = await load();
+ const cache = new Cache<Record<string, number>>(`rtac-${randomUUID()}`, 60_000);
+ await cache.set('user-1', { a: 1 });
+
+ await expect(cache.get('user-1')).resolves.toEqual({ hit: true, value: { a: 1 } });
+ await expect(cache.get('user-2')).resolves.toEqual(expect.objectContaining({ hit: false }));
+ });
+
+ test('shares entries across instances of the same namespace', async () => {
+ const Cache = await load();
+ const namespace = `rtac-${randomUUID()}`;
+ const writer = new Cache<string>(namespace, 60_000);
+ const reader = new Cache<string>(namespace, 60_000);
+
+ await writer.set('user-1', 'value-a');
+
+ await expect(reader.get('user-1')).resolves.toEqual({ hit: true, value: 'value-a' });
+ });
+
+ test('invalidateAll orphans every entry without a keyspace scan', async () => {
+ const Cache = await load();
+ const namespace = `rtac-${randomUUID()}`;
+ const writer = new Cache<string>(namespace, 60_000);
+ /** A reader with no memoized entries: its next read must observe the new
+ * generation through the shared store, proving eviction comes from the
+ * generation tag rather than a local clear. */
+ const reader = new Cache<string>(namespace, 60_000);
+
+ await writer.set('user-1', 'value-a');
+ await writer.set('user-2', 'value-b');
+ await writer.invalidateAll();
+
+ await expect(reader.get('user-1')).resolves.toEqual(expect.objectContaining({ hit: false }));
+ await expect(reader.get('user-2')).resolves.toEqual(expect.objectContaining({ hit: false }));
+ });
+
+ test('entries expire after the ttl', async () => {
+ const Cache = await load();
+ const cache = new Cache<string>(`rtac-${randomUUID()}`, 40);
+ await cache.set('user-1', 'ephemeral');
+ await expect(cache.get('user-1')).resolves.toEqual({ hit: true, value: 'ephemeral' });
+
+ await new Promise((resolve) => setTimeout(resolve, 80));
+
+ await expect(cache.get('user-1')).resolves.toEqual(expect.objectContaining({ hit: false }));
+ });
+
+ test('a value written after invalidateAll is served under the new generation', async () => {
+ const Cache = await load();
+ const cache = new Cache<string>(`rtac-${randomUUID()}`, 60_000);
+ await cache.set('user-1', 'before');
+ await cache.invalidateAll();
+ await cache.set('user-1', 'after');
+
+ await expect(cache.get('user-1')).resolves.toEqual({ hit: true, value: 'after' });
+ });
+
+ test('ttl of 0 disables the cache entirely', async () => {
+ /** Entries derive from ACL access, so without a TTL there is no bound on
+ * how long a revoked user could keep receiving a stale map. */
+ const Cache = await load();
+ const cache = new Cache<string>(`rtac-${randomUUID()}`, 0);
+ await cache.set('user-1', 'never-cached');
+
+ await expect(cache.get('user-1')).resolves.toEqual(expect.objectContaining({ hit: false }));
+ await cache.invalidateAll();
+ await expect(cache.get('user-1')).resolves.toEqual(expect.objectContaining({ hit: false }));
+ });
+
+ test('transforms keep the shared store ciphertext while serving plaintext', async () => {
+ const Cache = await load();
+ const namespace = `rtac-${randomUUID()}`;
+ const writer = new Cache<Record<string, string>>(namespace, 60_000, {
+ encode: (value) => `enc:${JSON.stringify(value)}`,
+ decode: (raw) => JSON.parse(raw.slice(4)),
+ });
+ const reader = new Cache<Record<string, string>>(namespace, 60_000, {
+ encode: (value) => `enc:${JSON.stringify(value)}`,
+ decode: (raw) => JSON.parse(raw.slice(4)),
+ });
+
+ await writer.set('user-1', { secret: 'plaintext-value' });
+
+ await expect(reader.get('user-1')).resolves.toEqual({
+ hit: true,
+ value: { secret: 'plaintext-value' },
+ });
+ });
+
+ test('an undecodable stored entry fails open to a miss', async () => {
+ const Cache = await load();
+ const namespace = `rtac-${randomUUID()}`;
+ /** Writer without transforms stores plaintext JSON-shaped data. */
+ const plainWriter = new Cache<Record<string, string>>(namespace, 60_000);
+ const decodingReader = new Cache<Record<string, string>>(namespace, 60_000, {
+ encode: (value) => JSON.stringify(value),
+ decode: () => {
+ throw new Error('key rotation');
+ },
+ });
+
+ await plainWriter.set('user-1', { secret: 'stale-across-rotation' });
+
+ await expect(decodingReader.get('user-1')).resolves.toEqual(
+ expect.objectContaining({ hit: false }),
+ );
+ });
+
+ test('a failing encode degrades to the memo without failing the set', async () => {
+ const Cache = await load();
+ const cache = new Cache<string>(`rtac-${randomUUID()}`, 60_000, {
+ encode: () => {
+ throw new Error('no CREDS key');
+ },
+ decode: (raw) => raw,
+ });
+
+ await expect(cache.set('user-1', 'memo-only')).resolves.toBeUndefined();
+ await expect(cache.get('user-1')).resolves.toEqual({ hit: true, value: 'memo-only' });
+ });
+});
diff --git a/packages/api/src/mcp/registry/cache/__tests__/ReadThroughCache.resilience.spec.ts b/packages/api/src/mcp/registry/cache/__tests__/ReadThroughCache.resilience.spec.ts
new file mode 100644
index 0000000000..623bdce0d5
--- /dev/null
+++ b/packages/api/src/mcp/registry/cache/__tests__/ReadThroughCache.resilience.spec.ts
@@ -0,0 +1,549 @@
+import { randomUUID } from 'crypto';
+import { ReadThroughAllCache } from '../ReadThroughAllCache';
+import { ReadThroughCache } from '../ReadThroughCache';
+
+interface MockStore {
+ get: jest.Mock;
+ set: jest.Mock;
+ delete: jest.Mock;
+ clear: jest.Mock;
+}
+
+/** Stores created by the mocked `standardCache`, keyed by namespace, so tests
+ * can drive the exact boundary failures and interleavings the real Redis
+ * client cannot be asked to produce deterministically. */
+const mockStores = new Map<string, MockStore>();
+
+jest.mock('~/cache', () => {
+ const actual = jest.requireActual('~/cache');
+ return {
+ ...actual,
+ standardCache: (namespace: string) => {
+ const existing = mockStores.get(namespace);
+ if (existing) {
+ return existing;
+ }
+ const store: MockStore = {
+ get: jest.fn(async () => undefined),
+ set: jest.fn(async () => true),
+ delete: jest.fn(async () => true),
+ clear: jest.fn(async () => undefined),
+ };
+ mockStores.set(namespace, store);
+ return store;
+ },
+ };
+});
+
+function storesFor(namespace: string): { entry: MockStore; generation: MockStore } {
+ const entry = mockStores.get(namespace);
+ const generation = mockStores.get(`${namespace}::generation`);
+ if (!entry || !generation) {
+ throw new Error(`stores not created for ${namespace}`);
+ }
+ return { entry, generation };
+}
+
+function storeFor(namespace: string): MockStore {
+ const store = mockStores.get(namespace);
+ if (!store) {
+ throw new Error(`store not created for ${namespace}`);
+ }
+ return store;
+}
+
+function installGenerationStore(
+ generation: MockStore,
+ initial: Record<string, string> = {},
+): Map<string, string> {
+ const values = new Map(Object.entries(initial));
+ generation.get.mockImplementation(async (key: string) => values.get(key));
+ generation.set.mockImplementation(async (key: string, value: string) => {
+ values.set(key, value);
+ return true;
+ });
+ return values;
+}
+
+function deferred<T = void>(): {
+ promise: Promise<T>;
+ resolve: (value: T) => void;
+} {
+ let resolve!: (value: T) => void;
+ const promise = new Promise<T>((res) => {
+ resolve = res;
+ });
+ return { promise, resolve };
+}
+
+describe('read-through cache resilience', () => {
+ test('entry store failure on get degrades to a miss', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { entry } = storesFor(namespace);
+ entry.get.mockRejectedValueOnce(new Error('redis unavailable'));
+
+ await expect(cache.get('user-1')).resolves.toEqual(expect.objectContaining({ hit: false }));
+ });
+
+ test('generation store failure on get degrades to a miss', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { generation } = storesFor(namespace);
+ generation.get.mockRejectedValue(new Error('redis unavailable'));
+
+ await expect(cache.get('user-1')).resolves.toEqual(expect.objectContaining({ hit: false }));
+ });
+
+ test('a generation-read failure marks the fill as uncacheable', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { entry, generation } = storesFor(namespace);
+ generation.get.mockRejectedValue(new Error('redis unavailable'));
+
+ const miss = await cache.get('user-1');
+ expect(miss.fill).toEqual({ key: 'user-1', generation: null });
+
+ generation.get.mockResolvedValue(undefined);
+ await cache.set('user-1', 'must-not-be-shared', miss.fill);
+ expect(entry.set).not.toHaveBeenCalled();
+ });
+
+ test('a generation failure cannot revive generation-zero entries', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { entry, generation } = storesFor(namespace);
+ entry.get.mockResolvedValue('stale-from-generation-0');
+ generation.get.mockRejectedValue(new Error('transient'));
+
+ /** The unreadable generation must be a miss, not a fallback to "0", or an
+ * unexpired pre-invalidation entry could be served for another TTL. */
+ await expect(cache.get('user-1')).resolves.toEqual(expect.objectContaining({ hit: false }));
+ expect(entry.get).not.toHaveBeenCalled();
+ });
+
+ test('store failure on set never rejects and keeps the process-local memo', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { entry, generation } = storesFor(namespace);
+ entry.set.mockRejectedValue(new Error('redis unavailable'));
+ generation.set.mockRejectedValue(new Error('redis unavailable'));
+
+ await expect(cache.set('user-1', 'computed')).resolves.toBeUndefined();
+ /** The memo still serves the caller's own computed value; only the
+ * cross-instance sharing is lost while the store is unavailable. */
+ await expect(cache.get('user-1')).resolves.toEqual(
+ expect.objectContaining({ hit: true, value: 'computed' }),
+ );
+ });
+
+ test('generation write failure on invalidateAll is propagated', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { generation } = storesFor(namespace);
+ generation.set.mockRejectedValue(new Error('redis unavailable'));
+
+ await expect(cache.invalidateAll()).rejects.toThrow('redis unavailable');
+ });
+
+ test('an invalidation landing mid-read is not memoized', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { entry, generation } = storesFor(namespace);
+ entry.get.mockResolvedValue('pre-mutation-value');
+ /** First read sees g1; the recheck after the entry fetch observes the
+ * invalidation that landed in between. */
+ generation.get.mockImplementation(async (key: string) => {
+ if (key === '__global_generation__') {
+ return 'global';
+ }
+ return generation.get.mock.calls.filter(([calledKey]) => calledKey === '__generation__')
+ .length === 1
+ ? 'g1'
+ : 'g2';
+ });
+
+ const raced = await cache.get('user-1');
+ expect(raced.hit).toBe(false);
+ /** The racing fill observes g1 and the generation has moved, so it stays
+ * fenced when its caller finishes computing. */
+ await cache.set('user-1', 'stale-computed', raced.fill);
+ expect(entry.set).not.toHaveBeenCalled();
+
+ /** The value was never memoized, so the next read recomputes from the
+ * store under the new generation rather than replaying the stale hit. */
+ entry.get.mockClear();
+ await expect(cache.get('user-1')).resolves.toEqual(
+ expect.objectContaining({ hit: true, value: 'pre-mutation-value' }),
+ );
+ expect(entry.get).toHaveBeenCalledWith('global:g2::user-1');
+ });
+
+ test('a fill computed across an invalidation is fenced', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { entry, generation } = storesFor(namespace);
+ /** The miss happens under g1; the caller is still computing when the
+ * generation moves to g2, so the fill must not be written or memoized. */
+ const values = installGenerationStore(generation, {
+ __global_generation__: 'global',
+ __generation__: 'g1',
+ });
+ entry.get.mockResolvedValueOnce(undefined);
+ const miss = await cache.get('user-1');
+ expect(miss.fill).toEqual({ key: 'user-1', generation: 'global:g1' });
+
+ values.set('__generation__', 'g2');
+ await cache.set('user-1', 'stale-computed', miss.fill);
+
+ expect(entry.set).not.toHaveBeenCalled();
+ await expect(cache.get('user-1')).resolves.toEqual(expect.objectContaining({ hit: false }));
+ });
+
+ test('a store-failure miss still fences its fill across an invalidation', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { entry, generation } = storesFor(namespace);
+ /** The Redis read fails under g1 but recovers by the time the fill lands,
+ * after an invalidation moved the generation: the fill is still stale. */
+ const values = installGenerationStore(generation, {
+ __global_generation__: 'global',
+ __generation__: 'g1',
+ });
+ entry.get.mockRejectedValueOnce(new Error('redis unavailable'));
+ const miss = await cache.get('user-1');
+ expect(miss.hit).toBe(false);
+
+ values.set('__generation__', 'g2');
+ await cache.set('user-1', 'stale-computed', miss.fill);
+
+ expect(entry.set).not.toHaveBeenCalled();
+ });
+
+ test('a fence survives fills slower than one TTL window', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 40);
+ const { entry, generation } = storesFor(namespace);
+ const values = installGenerationStore(generation, {
+ __global_generation__: 'global',
+ __generation__: 'g1',
+ });
+ entry.get.mockResolvedValueOnce(undefined);
+ const miss = await cache.get('user-1');
+ expect(miss.hit).toBe(false);
+
+ await new Promise((resolve) => setTimeout(resolve, 80));
+ values.set('__generation__', 'g2');
+
+ /** The miss generation travels with the fill, so a compute slower than the
+ * entry TTL is still fenced when it lands. */
+ await cache.set('user-1', 'slow-stale-computed', miss.fill);
+ expect(entry.set).not.toHaveBeenCalled();
+ });
+
+ test('concurrent fills for one key keep distinct fences', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { entry, generation } = storesFor(namespace);
+ /** Fill A misses under g1; an invalidation moves to g2; fill B misses
+ * under g2. A's later set must stay fenced even though B's fence is
+ * current, which a shared per-key marker could not express. */
+ const values = installGenerationStore(generation, {
+ __global_generation__: 'global',
+ __generation__: 'g1',
+ });
+ entry.get.mockResolvedValueOnce(undefined);
+ const missA = await cache.get('user-1');
+
+ values.set('__generation__', 'g2');
+ entry.get.mockResolvedValueOnce(undefined);
+ const missB = await cache.get('user-1');
+ expect(missB.fill).toEqual({ key: 'user-1', generation: 'global:g2' });
+
+ await cache.set('user-1', 'stale-from-A', missA.fill);
+ expect(entry.set).not.toHaveBeenCalled();
+
+ await cache.set('user-1', 'fresh-from-B', missB.fill);
+ expect(entry.set).toHaveBeenCalledWith('global:g2::user-1', 'fresh-from-B');
+ });
+
+ test('invalidateAll evicts a memo repopulated while the generation write is pending', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { entry, generation } = storesFor(namespace);
+ const values = installGenerationStore(generation, {
+ __global_generation__: 'global',
+ __generation__: 'g1',
+ });
+ const generationWrite = deferred<void>();
+ generation.set.mockImplementation(async (key: string, value: string) => {
+ await generationWrite.promise;
+ values.set(key, value);
+ return true;
+ });
+
+ await cache.set('user-1', 'memoized-old');
+ entry.get.mockResolvedValue('stored-old');
+
+ const invalidation = cache.invalidateAll();
+ const racedRead = await cache.get('user-1');
+ expect(racedRead).toEqual(expect.objectContaining({ hit: true, value: 'stored-old' }));
+
+ generationWrite.resolve();
+ await invalidation;
+
+ entry.get.mockClear();
+ await cache.get('user-1');
+ expect(entry.get).toHaveBeenCalled();
+ });
+
+ test('invalidateAllGlobal rotates the shared fence for in-flight fills', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { entry, generation } = storesFor(namespace);
+ installGenerationStore(generation, {
+ __global_generation__: 'global-1',
+ __generation__: 'tenant-1',
+ });
+ entry.get.mockResolvedValueOnce(undefined);
+ const miss = await cache.get('user-1');
+
+ await cache.invalidateAllGlobal();
+ await cache.set('user-1', 'pre-reset-value', miss.fill);
+
+ expect(generation.set).toHaveBeenCalledWith('__global_generation__', expect.any(String));
+ expect(entry.set).not.toHaveBeenCalled();
+ });
+
+ test("invalidation in one tenant does not orphan another tenant's entries", async () => {
+ const { tenantStorage } = await import('@librechat/data-schemas');
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { entry, generation } = storesFor(namespace);
+ generation.get.mockImplementation(async (key: string) => {
+ if (key === '__generation__:tenant-a') {
+ return 'ga1';
+ }
+ if (key === '__generation__:tenant-b') {
+ return 'gb1';
+ }
+ return 'g0';
+ });
+
+ await tenantStorage.run({ tenantId: 'tenant-a' }, () => cache.set('user:tenant-a', 'value-a'));
+ entry.get.mockImplementation(async (key: string) =>
+ key === 'ga1::user:tenant-a' ? 'value-a' : undefined,
+ );
+
+ await tenantStorage.run({ tenantId: 'tenant-b' }, () => cache.invalidateAll());
+ expect(generation.set).toHaveBeenCalledWith('__generation__:tenant-b', expect.any(String));
+
+ /** Tenant B's invalidation left tenant A's memo entry in place, so this
+ * read never even reaches the shared store. */
+ entry.get.mockClear();
+ const survived = await tenantStorage.run({ tenantId: 'tenant-a' }, () =>
+ cache.get('user:tenant-a'),
+ );
+ expect(survived).toEqual(expect.objectContaining({ hit: true, value: 'value-a' }));
+ expect(entry.get).not.toHaveBeenCalled();
+ });
+
+ test('invalidateAllGlobal clears the shared namespace across tenants', async () => {
+ const namespace = `rtac-r-${randomUUID()}`;
+ const cache = new ReadThroughAllCache<string>(namespace, 60_000);
+ const { entry, generation } = storesFor(namespace);
+ installGenerationStore(generation);
+ entry.get.mockResolvedValue('stored-value');
+ await cache.set('user-1', 'memoized');
+
+ await cache.invalidateAllGlobal();
+
+ /** The namespace-wide clear ran and the memo was evicted with it, so the
+ * next read goes back to the shared store instead of replaying it. */
+ expect(entry.clear).toHaveBeenCalled();
+ await cache.get('user-1');
+ expect(entry.get).toHaveBeenCalledWith(expect.stringMatching(/^[^:]+:0::user-1$/));
+ });
+});
+
+describe('per-server ReadThroughCache resilience', () => {
+ test('ttl of 0 disables the cache entirely', async () => {
+ const namespace = `rtc-r-${randomUUID()}`;
+ const cache = new ReadThroughCache<string>(namespace, 0);
+ const store = storeFor(namespace);
+
+ await cache.set('server::user', 'never-cached');
+ await expect(cache.getEntry('server::user')).resolves.toEqual(
+ expect.objectContaining({ hit: false }),
+ );
+ expect(store.set).not.toHaveBeenCalled();
+ });
+
+ test('store failures degrade to misses and skipped writes', async () => {
+ const namespace = `rtc-r-${randomUUID()}`;
+ const cache = new ReadThroughCache<string>(namespace, 60_000);
+ const store = storeFor(namespace);
+ store.get.mockRejectedValue(new Error('redis unavailable'));
+ store.set.mockRejectedValue(new Error('redis unavailable'));
+ store.delete.mockRejectedValue(new Error('redis unavailable'));
+
+ await expect(cache.getEntry('server::user')).resolves.toEqual(
+ expect.objectContaining({ hit: false }),
+ );
+ await expect(cache.set('server::user', 'value')).resolves.toBeUndefined();
+ await expect(cache.delete('server::user')).resolves.toBeUndefined();
+ });
+
+ test('transforms keep the store ciphertext while serving plaintext', async () => {
+ const namespace = `rtc-r-${randomUUID()}`;
+ const cache = new ReadThroughCache<string>(namespace, 60_000, {
+ encode: (value) => Buffer.from(value).toString('base64'),
+ decode: (raw) => Buffer.from(raw, 'base64').toString('utf8'),
+ });
+
+ await cache.set('server::user', 'secret-value');
+
+ const store = storeFor(namespace);
+ const [, stored] = store.set.mock.calls[0];
+ expect(String(stored)).not.toContain('secret-value');
+ store.get.mockResolvedValueOnce(stored);
+ await expect(cache.getEntry('server::user')).resolves.toEqual(
+ expect.objectContaining({ hit: true, value: 'secret-value' }),
+ );
+ });
+
+ test('an undecodable entry is deleted and reported as a miss', async () => {
+ const namespace = `rtc-r-${randomUUID()}`;
+ const cache = new ReadThroughCache<string>(namespace, 60_000, {
+ encode: (value) => value,
+ decode: () => {
+ throw new Error('key rotation');
+ },
+ });
+ const store = storeFor(namespace);
+ store.get.mockResolvedValueOnce('stale-ciphertext');
+
+ await expect(cache.getEntry('server::user')).resolves.toEqual(
+ expect.objectContaining({ hit: false }),
+ );
+ expect(store.delete).toHaveBeenCalledWith('0:0::server::user');
+ });
+
+ test('a fill finishing after a targeted delete is fenced', async () => {
+ const namespace = `rtc-r-${randomUUID()}`;
+ const cache = new ReadThroughCache<string>(namespace, 60_000);
+ const { entry: store, generation } = storesFor(namespace);
+ installGenerationStore(generation);
+ store.get.mockResolvedValueOnce(undefined);
+ const miss = await cache.getEntry('server::user');
+ expect(miss.hit).toBe(false);
+
+ /** The server is updated and the cache key deleted while the original
+ * request was still fetching; its write must not undo the mutation. */
+ await cache.delete('server::user');
+ await cache.set('server::user', 'pre-mutation-value', miss.fill);
+
+ expect(store.set).not.toHaveBeenCalled();
+ });
+
+ test('a fill finishing after a namespace clear is fenced', async () => {
+ const namespace = `rtc-r-${randomUUID()}`;
+ const cache = new ReadThroughCache<string>(namespace, 60_000);
+ const { entry: store, generation } = storesFor(namespace);
+ installGenerationStore(generation);
+ store.get.mockResolvedValueOnce(undefined);
+ const miss = await cache.getEntry('server::user');
+ expect(miss.hit).toBe(false);
+
+ await cache.clear();
+ await cache.set('server::user', 'pre-reset-value', miss.fill);
+
+ expect(store.set).not.toHaveBeenCalled();
+ });
+
+ test('a fill is allowed when no invalidation intervened', async () => {
+ const namespace = `rtc-r-${randomUUID()}`;
+ const cache = new ReadThroughCache<string>(namespace, 60_000);
+ const store = storeFor(namespace);
+ store.get.mockResolvedValueOnce(undefined);
+ const miss = await cache.getEntry('server::user');
+ expect(miss.hit).toBe(false);
+
+ await cache.set('server::user', 'fresh', miss.fill);
+
+ expect(store.set).toHaveBeenCalledWith('0:0::server::user', 'fresh');
+ });
+
+ test('concurrent fills for one key keep distinct fences', async () => {
+ const namespace = `rtc-r-${randomUUID()}`;
+ const cache = new ReadThroughCache<string>(namespace, 60_000);
+ const { entry: store, generation } = storesFor(namespace);
+ installGenerationStore(generation);
+ /** Fill A misses; a targeted delete lands; fill B misses. A's later write
+ * must stay fenced even though B's fence is current. */
+ store.get.mockResolvedValue(undefined);
+ const missA = await cache.getEntry('server::user');
+
+ await cache.delete('server::user');
+ const missB = await cache.getEntry('server::user');
+
+ await cache.set('server::user', 'stale-from-A', missA.fill);
+ expect(store.set).not.toHaveBeenCalled();
+
+ await cache.set('server::user', 'fresh-from-B', missB.fill);
+ expect(store.set).toHaveBeenCalledWith(
+ expect.stringContaining('::server::user'),
+ 'fresh-from-B',
+ );
+ });
+
+ test('a cross-instance invalidation fences a write already awaiting encode', async () => {
+ const namespace = `rtc-r-${randomUUID()}`;
+ const encodeStarted = deferred<void>();
+ const releaseEncode = deferred<void>();
+ const writer = new ReadThroughCache<string>(namespace, 60_000, {
+ encode: async (value) => {
+ encodeStarted.resolve();
+ await releaseEncode.promise;
+ return value;
+ },
+ });
+ const invalidator = new ReadThroughCache<string>(namespace, 60_000);
+ const { entry, generation } = storesFor(namespace);
+ installGenerationStore(generation, {
+ __global_generation__: 'global',
+ __generation__: 'tenant-1',
+ });
+ entry.get.mockResolvedValueOnce(undefined);
+ const miss = await writer.getEntry('server::user');
+
+ const write = writer.set('server::user', 'pre-mutation-value', miss.fill);
+ await encodeStarted.promise;
+ await invalidator.delete('server::user');
+ releaseEncode.resolve();
+ await write;
+
+ expect(entry.set).toHaveBeenCalledWith('global:tenant-1::server::user', 'pre-mutation-value');
+ expect(entry.delete).toHaveBeenLastCalledWith('global:tenant-1::server::user');
+
+ entry.get.mockClear();
+ await expect(invalidator.getEntry('server::user')).resolves.toEqual(
+ expect.objectContaining({ hit: false }),
+ );
+ expect(entry.get).toHaveBeenCalledWith(expect.not.stringContaining('tenant-1'));
+ });
+
+ test('targeted invalidations reuse one shared tenant generation key', async () => {
+ const namespace = `rtc-r-${randomUUID()}`;
+ const cache = new ReadThroughCache<string>(namespace, 60_000);
+ const { generation } = storesFor(namespace);
+ installGenerationStore(generation);
+
+ await cache.delete('server-a::user');
+ await cache.delete('server-b::user');
+ await cache.delete('server-c::user');
+
+ expect(generation.set).toHaveBeenCalledTimes(3);
+ expect(generation.set.mock.calls.every(([key]) => key === '__generation__')).toBe(true);
+ });
+});
diff --git a/packages/api/src/mcp/registry/db/ServerConfigsDB.ts b/packages/api/src/mcp/registry/db/ServerConfigsDB.ts
index f561332233..b05a7d3f48 100644
--- a/packages/api/src/mcp/registry/db/ServerConfigsDB.ts
+++ b/packages/api/src/mcp/registry/db/ServerConfigsDB.ts
@@ -6,10 +6,11 @@ import {
PrincipalType,
PermissionBits,
} from 'librechat-data-provider';
-import type { AllMethods, MCPServerDocument } from '@librechat/data-schemas';
+import type { AllMethods, MCPServerDocument, IAgent } from '@librechat/data-schemas';
import type { IServerConfigsRepositoryInterface } from '~/mcp/registry/ServerConfigsRepositoryInterface';
import type { ParsedServerConfig, AddServerResult } from '~/mcp/types';
+import type { ResolvedPrincipal } from '~/types/principal';
import { MCPOAuthSecretReentryRequiredError } from '~/mcp/errors';
import { AccessControlService } from '~/acl/accessControlService';
@@ -201,6 +202,27 @@ function getChangedOAuthSecretBindingFields(
return fields.filter(([, existing, updated]) => existing !== updated).map(([field]) => field);
}
+/** Unions `mcpServerNames` over the candidate agents the caller can access. */
+function unionMCPServerNames(
+ candidates: Array<Pick<IAgent, '_id' | 'mcpServerNames'>>,
+ accessibleAgentIds: Types.ObjectId[],
+): string[] {
+ if (accessibleAgentIds.length === 0) {
+ return [];
+ }
+ const accessible = new Set(accessibleAgentIds.map((id) => id.toString()));
+ const serverNames = new Set<string>();
+ for (const agent of candidates) {
+ if (!accessible.has(agent._id.toString())) {
+ continue;
+ }
+ for (const serverName of agent.mcpServerNames ?? []) {
+ serverNames.add(serverName);
+ }
+ }
+ return Array.from(serverNames);
+}
+
/**
* DB backed config storage
* Handles CRUD Methods of dynamic mcp servers
@@ -220,36 +242,33 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
/**
* Checks if user has access to an MCP server via an agent they can VIEW.
+ * Starts from the agents that reference `serverName` (typically few, and an
+ * index-covered lookup) and bounds the ACL query to those ids, instead of
+ * materializing every accessible agent and scanning it (#14016).
* @param serverName - The MCP server name to check
* @param userId - The user ID (optional - if not provided, checks publicly accessible agents)
* @returns true if user has VIEW access to at least one agent that has this MCP server
*/
private async hasAccessViaAgent(serverName: string, userId?: string): Promise<boolean> {
- let accessibleAgentIds: Types.ObjectId[];
-
- if (!userId) {
- /** Publicly accessible agents */
- accessibleAgentIds = await this._aclService.findPubliclyAccessibleResources({
- resourceType: ResourceType.AGENT,
- requiredPermissions: PermissionBits.VIEW,
- });
- } else {
- /** User-accessible agents */
- accessibleAgentIds = await this._aclService.findAccessibleResources({
- userId,
- requiredPermissions: PermissionBits.VIEW,
- resourceType: ResourceType.AGENT,
- });
- }
-
- if (accessibleAgentIds.length === 0) {
+ const candidateIds = await this._dbMethods.getAgentIdsByMCPServerName(serverName);
+ if (candidateIds.length === 0) {
return false;
}
- return await this._dbMethods.hasAgentWithMCPServerName({
- agentIds: accessibleAgentIds,
- serverName,
- });
+ const accessibleAgentIds = userId
+ ? await this._aclService.findAccessibleResources({
+ userId,
+ requiredPermissions: PermissionBits.VIEW,
+ resourceType: ResourceType.AGENT,
+ resourceIds: candidateIds,
+ })
+ : await this._aclService.findPubliclyAccessibleResources({
+ resourceType: ResourceType.AGENT,
+ requiredPermissions: PermissionBits.VIEW,
+ resourceIds: candidateIds,
+ });
+
+ return accessibleAgentIds.length > 0;
}
/**
@@ -484,58 +503,88 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
return undefined;
}
+ /**
+ * Agent-side access resolution bounded to the MCP-referencing candidate ids,
+ * so the ACL query cost scales with agents that use MCP servers instead of
+ * every accessible agent (#14016).
+ */
+ private findAccessibleAgentIds(
+ candidateIds: Types.ObjectId[],
+ userId?: string,
+ principalsList: ResolvedPrincipal[] = [],
+ ): Promise<Types.ObjectId[]> {
+ if (candidateIds.length === 0) {
+ return Promise.resolve([]);
+ }
+ if (userId) {
+ return this._aclService.findAccessibleResourcesForPrincipals({
+ principalsList,
+ requiredPermissions: PermissionBits.VIEW,
+ resourceType: ResourceType.AGENT,
+ resourceIds: candidateIds,
+ });
+ }
+ return this._aclService.findPubliclyAccessibleResources({
+ resourceType: ResourceType.AGENT,
+ requiredPermissions: PermissionBits.VIEW,
+ resourceIds: candidateIds,
+ });
+ }
+
/**
* Return all DB stored configs (scoped by user Id if provided)
* @param userId optional user id. if not provided only publicly shared mcp configs will be returned
* @returns record of parsed configs
*/
public async getAll(userId?: string, role?: string): Promise<Record<string, ParsedServerConfig>> {
- let directlyAccessibleMCPIds: Types.ObjectId[] = [];
- let accessibleAgentIds: Types.ObjectId[] = [];
-
- if (!userId) {
- logger.debug(`[ServerConfigsDB.getAll] fetching all publicly shared mcp servers`);
- [directlyAccessibleMCPIds, accessibleAgentIds] = await Promise.all([
- this._aclService.findPubliclyAccessibleResources({
- resourceType: ResourceType.MCPSERVER,
- requiredPermissions: PermissionBits.VIEW,
- }),
- this._aclService.findPubliclyAccessibleResources({
- resourceType: ResourceType.AGENT,
- requiredPermissions: PermissionBits.VIEW,
- }),
- ]);
- } else {
- logger.debug(
- `[ServerConfigsDB.getAll] fetching mcp servers directly shared with the user with ID: ${userId}`,
- );
- const principalsList = await this._aclService.getUserPrincipals({ userId, role });
- [directlyAccessibleMCPIds, accessibleAgentIds] = await Promise.all([
- this._aclService.findAccessibleResourcesForPrincipals({
+ const candidatesPromise = this._dbMethods.getAgentsWithMCPServerNames();
+ const principalsPromise: Promise<ResolvedPrincipal[]> | undefined = userId
+ ? this._aclService.getUserPrincipals({ userId, role })
+ : undefined;
+ const principalsResolved = principalsPromise ?? Promise.resolve([] as ResolvedPrincipal[]);
+
+ /** Direct-server ids depend on principals only for the user path; chaining
+ * attaches a rejection handler at creation for both branches, and the
+ * direct-server fetch follows the ids immediately. */
+ const directResultsPromise = (
+ principalsPromise
+ ? principalsPromise.then((principalsList) =>
+ this._aclService.findAccessibleResourcesForPrincipals({
+ principalsList,
+ requiredPermissions: PermissionBits.VIEW,
+ resourceType: ResourceType.MCPSERVER,
+ }),
+ )
+ : this._aclService.findPubliclyAccessibleResources({
+ resourceType: ResourceType.MCPSERVER,
+ requiredPermissions: PermissionBits.VIEW,
+ })
+ ).then((ids) => this._dbMethods.getListMCPServersByIds({ ids }));
+
+ /** The agent-side ACL needs only candidates and principals; chaining it
+ * from those keeps the independent direct-server path off its critical
+ * path, and the outer settlement attaches handlers to everything else. */
+ const agentAccessPromise = Promise.all([candidatesPromise, principalsResolved]).then(
+ ([agentCandidates, principalsList]) =>
+ this.findAccessibleAgentIds(
+ agentCandidates.map((agent) => agent._id),
+ userId,
principalsList,
- requiredPermissions: PermissionBits.VIEW,
- resourceType: ResourceType.MCPSERVER,
- }),
- this._aclService.findAccessibleResourcesForPrincipals({
- principalsList,
- requiredPermissions: PermissionBits.VIEW,
- resourceType: ResourceType.AGENT,
- }),
- ]);
- }
+ ),
+ );
- const agentMCPServerNamesPromise: Promise<string[]> =
- accessibleAgentIds.length > 0
- ? this._dbMethods.getMCPServerNamesByAgentIds(accessibleAgentIds)
- : Promise.resolve([]);
- const directResultsPromise = this._dbMethods.getListMCPServersByIds({
- ids: directlyAccessibleMCPIds,
- });
- const [agentMCPServerNames, directResults] = await Promise.all([
- agentMCPServerNamesPromise,
+ const [agentCandidates, accessibleAgentIds, directResults] = await Promise.all([
+ candidatesPromise,
+ agentAccessPromise,
directResultsPromise,
]);
+ logger.debug(
+ `[ServerConfigsDB.getAll] resolving access for ${userId ?? 'public'}; ${agentCandidates.length} agent candidate(s) reference MCP servers`,
+ );
+
+ const agentMCPServerNames = unionMCPServerNames(agentCandidates, accessibleAgentIds);
+
const parsedConfigs: Record<string, ParsedServerConfig> = {};
const directData = directResults.data || [];
const directServerNames = new Set(directData.map((s: MCPServerDocument) => s.serverName));
diff --git a/packages/data-schemas/src/methods/aclEntry.spec.ts b/packages/data-schemas/src/methods/aclEntry.spec.ts
index 68e2307830..908fe36c45 100644
--- a/packages/data-schemas/src/methods/aclEntry.spec.ts
+++ b/packages/data-schemas/src/methods/aclEntry.spec.ts
@@ -1411,6 +1411,68 @@ describe('AclEntry Model Tests', () => {
expect(result).toHaveLength(1);
expect(result[0].toString()).toBe(viewEdit.toString());
});
+
+ describe('resourceIds bound', () => {
+ const otherResource = new mongoose.Types.ObjectId();
+ beforeEach(async () => {
+ await methods.grantPermission(
+ PrincipalType.USER,
+ userId,
+ ResourceType.AGENT,
+ resourceId,
+ PermissionBits.VIEW,
+ grantedById,
+ );
+ await methods.grantPermission(
+ PrincipalType.USER,
+ userId,
+ ResourceType.AGENT,
+ otherResource,
+ PermissionBits.VIEW,
+ grantedById,
+ );
+ });
+
+ test('intersects access with the bound candidate ids only', async () => {
+ const result = await methods.findAccessibleResources(
+ [{ principalType: PrincipalType.USER, principalId: userId }],
+ ResourceType.AGENT,
+ PermissionBits.VIEW,
+ [resourceId, new mongoose.Types.ObjectId()],
+ );
+ expect(result).toHaveLength(1);
+ expect(result[0].toString()).toBe(resourceId.toString());
+ });
+
+ test('returns nothing when every accessible resource is outside the bound', async () => {
+ const result = await methods.findAccessibleResources(
+ [{ principalType: PrincipalType.USER, principalId: userId }],
+ ResourceType.AGENT,
+ PermissionBits.VIEW,
+ [new mongoose.Types.ObjectId()],
+ );
+ expect(result).toHaveLength(0);
+ });
+
+ test('an empty bound matches nothing rather than lifting the filter', async () => {
+ const result = await methods.findAccessibleResources(
+ [{ principalType: PrincipalType.USER, principalId: userId }],
+ ResourceType.AGENT,
+ PermissionBits.VIEW,
+ [],
+ );
+ expect(result).toHaveLength(0);
+ });
+
+ test('an unbound call still returns every accessible resource', async () => {
+ const result = await methods.findAccessibleResources(
+ [{ principalType: PrincipalType.USER, principalId: userId }],
+ ResourceType.AGENT,
+ PermissionBits.VIEW,
+ );
+ expect(result).toHaveLength(2);
+ });
+ });
});
describe('findPublicResourceIds', () => {
@@ -1433,6 +1495,42 @@ describe('AclEntry Model Tests', () => {
expect(result[0].toString()).toBe(shared.toString());
});
+ test('with resourceIds bound, intersects public access with the candidate ids', async () => {
+ const shared = new mongoose.Types.ObjectId();
+ const unreachable = new mongoose.Types.ObjectId();
+ await methods.grantPermission(
+ PrincipalType.PUBLIC,
+ null,
+ ResourceType.AGENT,
+ shared,
+ PermissionBits.VIEW,
+ grantedById,
+ );
+ await methods.grantPermission(
+ PrincipalType.PUBLIC,
+ null,
+ ResourceType.AGENT,
+ unreachable,
+ PermissionBits.VIEW,
+ grantedById,
+ );
+
+ const result = await methods.findPublicResourceIds(
+ ResourceType.AGENT,
+ PermissionBits.VIEW,
+ [shared, new mongoose.Types.ObjectId()],
+ );
+ expect(result).toHaveLength(1);
+ expect(result[0].toString()).toBe(shared.toString());
+
+ const emptyBound = await methods.findPublicResourceIds(
+ ResourceType.AGENT,
+ PermissionBits.VIEW,
+ [],
+ );
+ expect(emptyBound).toHaveLength(0);
+ });
+
test('deduplicates when duplicate public entries exist for the same resource', async () => {
/**
* `grantPermission` upserts, so duplicates are not reachable through the
diff --git a/packages/data-schemas/src/methods/aclEntry.ts b/packages/data-schemas/src/methods/aclEntry.ts
index 105d55a1d1..d8995a0026 100644
--- a/packages/data-schemas/src/methods/aclEntry.ts
+++ b/packages/data-schemas/src/methods/aclEntry.ts
@@ -138,6 +138,7 @@ export function createAclEntryMethods(mongoose: typeof import('mongoose')): {
principalsList: Array<{ principalType: string; principalId?: string | Types.ObjectId }>,
resourceType: string,
requiredPermBit: number,
+ resourceIds?: Types.ObjectId[],
) => Promise<Types.ObjectId[]>;
deleteAclEntries: (
filter: Record<string, unknown>,
@@ -150,6 +151,7 @@ export function createAclEntryMethods(mongoose: typeof import('mongoose')): {
findPublicResourceIds: (
resourceType: string,
requiredPermissions: number,
+ resourceIds?: Types.ObjectId[],
) => Promise<Types.ObjectId[]>;
aggregateAclEntries: (pipeline: PipelineStage[]) => Promise<unknown[]>;
getSoleOwnedResourceIds: (
@@ -486,12 +488,17 @@ export function createAclEntryMethods(mongoose: typeof import('mongoose')): {
* @param principalsList - List of principals, each containing { principalType, principalId }
* @param resourceType - The type of resource
* @param requiredPermBit - Required permission bit (use PermissionBits enum)
+ * @param resourceIds - Optional candidate bound. When provided, only these
+ * resources are considered, so the query cost scales with the candidate set
+ * instead of every accessible resource of the type. An empty array matches
+ * nothing rather than lifting the bound.
* @returns Array of resource IDs
*/
async function findAccessibleResources(
principalsList: Array<{ principalType: string; principalId?: string | Types.ObjectId }>,
resourceType: string,
requiredPermBit: number,
+ resourceIds?: Types.ObjectId[],
): Promise<Types.ObjectId[]> {
const AclEntry = mongoose.models.AclEntry as Model<IAclEntry>;
const principalsQuery = principalsList.map((p) => ({
@@ -501,6 +508,7 @@ export function createAclEntryMethods(mongoose: typeof import('mongoose')): {
return await AclEntry.find({
$or: principalsQuery,
+ ...(resourceIds !== undefined && { resourceId: { $in: resourceIds } }),
resourceType,
permBits: { $in: permissionBitSupersets(requiredPermBit) },
}).distinct('resourceId');
@@ -537,14 +545,17 @@ export function createAclEntryMethods(mongoose: typeof import('mongoose')): {
* See {@link permissionBitSupersets} for the Cosmos-compatible bit filter.
* @param resourceType - The type of resource
* @param requiredPermissions - Required permission bits
+ * @param resourceIds - Optional candidate bound; see {@link findAccessibleResources}
*/
async function findPublicResourceIds(
resourceType: string,
requiredPermissions: number,
+ resourceIds?: Types.ObjectId[],
): Promise<Types.ObjectId[]> {
const AclEntry = mongoose.models.AclEntry as Model<IAclEntry>;
return await AclEntry.find({
principalType: PrincipalType.PUBLIC,
+ ...(resourceIds !== undefined && { resourceId: { $in: resourceIds } }),
resourceType,
permBits: { $in: permissionBitSupersets(requiredPermissions) },
}).distinct('resourceId');
diff --git a/packages/data-schemas/src/methods/agent.spec.ts b/packages/data-schemas/src/methods/agent.spec.ts
index a440dfc882..f110188627 100644
--- a/packages/data-schemas/src/methods/agent.spec.ts
+++ b/packages/data-schemas/src/methods/agent.spec.ts
@@ -20,6 +20,7 @@ import type {
} from 'mongoose';
import type { IAgent, IAclEntry, IUser, IAccessRole } from '..';
import { createAgentMethods, type AgentMethods } from './agent';
+import { tenantStorage } from '~/config/tenantContext';
import { createAclEntryMethods } from './aclEntry';
import { createModels } from '~/models';
@@ -550,6 +551,129 @@ describe('Agent Methods', () => {
expect(newAgent.mcpServerNames).toEqual(['authorizedServer']);
});
+ describe('MCP server name candidate lookups', () => {
+ test('getAgentsWithMCPServerNames returns only agents with a non-empty list, projected', async () => {
+ const { agentId, authorId } = createTestIds();
+ await createAgent({
+ id: agentId,
+ name: 'MCP Agent',
+ provider: 'test',
+ model: 'test-model',
+ author: authorId,
+ mcpServerNames: ['server-a', 'server-b'],
+ });
+ await createAgent({
+ id: `no-mcp-${agentId}`,
+ name: 'Plain Agent',
+ provider: 'test',
+ model: 'test-model',
+ author: authorId,
+ });
+
+ const candidates = await methods.getAgentsWithMCPServerNames();
+
+ expect(candidates).toHaveLength(1);
+ expect(candidates[0].mcpServerNames).toEqual(['server-a', 'server-b']);
+ expect(Object.keys(candidates[0]).sort()).toEqual(['_id', 'mcpServerNames']);
+ });
+
+ test('getAgentsWithMCPServerNames returns empty when no agent references MCP servers', async () => {
+ const { agentId, authorId } = createTestIds();
+ await createAgent({
+ id: agentId,
+ name: 'Plain Agent',
+ provider: 'test',
+ model: 'test-model',
+ author: authorId,
+ });
+
+ expect(await methods.getAgentsWithMCPServerNames()).toEqual([]);
+ });
+
+ test('getAgentsWithMCPServerNames stays within the active tenant', async () => {
+ const tenantA = `tenant-a-${uuidv4()}`;
+ const tenantB = `tenant-b-${uuidv4()}`;
+ const { agentId, authorId } = createTestIds();
+ const agentA = await tenantStorage.run({ tenantId: tenantA }, async () =>
+ createAgent({
+ id: agentId,
+ name: 'Tenant A MCP Agent',
+ provider: 'test',
+ model: 'test-model',
+ author: authorId,
+ mcpServerNames: ['server-a'],
+ }),
+ );
+ const agentB = await tenantStorage.run({ tenantId: tenantB }, async () =>
+ createAgent({
+ id: agentId,
+ name: 'Tenant B MCP Agent',
+ provider: 'test',
+ model: 'test-model',
+ author: authorId,
+ mcpServerNames: ['server-b'],
+ }),
+ );
+
+ const inA = await tenantStorage.run({ tenantId: tenantA }, () =>
+ methods.getAgentsWithMCPServerNames(),
+ );
+ const inB = await tenantStorage.run({ tenantId: tenantB }, () =>
+ methods.getAgentsWithMCPServerNames(),
+ );
+
+ expect(inA.map((agent) => agent._id.toString())).toEqual([agentA._id.toString()]);
+ expect(inB.map((agent) => agent._id.toString())).toEqual([agentB._id.toString()]);
+ });
+
+ test('getAgentIdsByMCPServerName returns ids of agents referencing the server', async () => {
+ const { agentId, authorId } = createTestIds();
+ const withServer = await createAgent({
+ id: agentId,
+ name: 'Gitlab Agent',
+ provider: 'test',
+ model: 'test-model',
+ author: authorId,
+ mcpServerNames: ['gitlab', 'other'],
+ });
+ await createAgent({
+ id: `second-${agentId}`,
+ name: 'Second Agent',
+ provider: 'test',
+ model: 'test-model',
+ author: authorId,
+ mcpServerNames: ['gitlab'],
+ });
+ await createAgent({
+ id: `unrelated-${agentId}`,
+ name: 'Unrelated Agent',
+ provider: 'test',
+ model: 'test-model',
+ author: authorId,
+ mcpServerNames: ['not-gitlab'],
+ });
+
+ const ids = (await methods.getAgentIdsByMCPServerName('gitlab')).map((id) => id.toString());
+
+ expect(ids).toHaveLength(2);
+ expect(ids).toContain(withServer._id.toString());
+ });
+
+ test('getAgentIdsByMCPServerName returns empty when no agent references the server', async () => {
+ const { agentId, authorId } = createTestIds();
+ await createAgent({
+ id: agentId,
+ name: 'Agent',
+ provider: 'test',
+ model: 'test-model',
+ author: authorId,
+ mcpServerNames: ['other-server'],
+ });
+
+ expect(await methods.getAgentIdsByMCPServerName('gitlab')).toEqual([]);
+ });
+ });
+
test('should derive the server from a key whose raw tool name contains the delimiter', async () => {
const { agentId, authorId } = createTestIds();
/** DB server names are slugs and cannot contain the delimiter, so the trailing
diff --git a/packages/data-schemas/src/methods/agent.ts b/packages/data-schemas/src/methods/agent.ts
index 22b0412e1b..c374f7475e 100644
--- a/packages/data-schemas/src/methods/agent.ts
+++ b/packages/data-schemas/src/methods/agent.ts
@@ -447,14 +447,8 @@ export function createAgentMethods(
) => Promise<(IAgent & { version: number }) | null>;
getAgents: (searchParameter: FilterQuery<IAgent>) => Promise<IAgent[]>;
createAgent: (agentData: Record<string, unknown>) => Promise<IAgent>;
- hasAgentWithMCPServerName: ({
- agentIds,
- serverName,
- }: {
- agentIds: Types.ObjectId[];
- serverName: string;
- }) => Promise<boolean>;
- getMCPServerNamesByAgentIds: (agentIds: Types.ObjectId[]) => Promise<string[]>;
+ getAgentIdsByMCPServerName: (serverName: string) => Promise<Types.ObjectId[]>;
+ getAgentsWithMCPServerNames: () => Promise<Array<Pick<IAgent, '_id' | 'mcpServerNames'>>>;
updateAgent: (
searchParameter: FilterQuery<IAgent>,
updateData: Record<string, unknown>,
@@ -609,48 +603,26 @@ export function createAgentMethods(
return await Agent.find(searchParameter).lean<IAgent[]>();
}
- async function hasAgentWithMCPServerName({
- agentIds,
- serverName,
- }: {
- agentIds: Types.ObjectId[];
- serverName: string;
- }): Promise<boolean> {
- if (agentIds.length === 0) {
- return false;
- }
-
+ /** Returns the ids of every agent referencing `serverName`, the candidate set
+ * for agent-mediated MCP access checks. Index-covered by `mcpServerNames`. */
+ async function getAgentIdsByMCPServerName(serverName: string): Promise<Types.ObjectId[]> {
const Agent = mongoose.models.Agent as Model<IAgent>;
- const agent = await Agent.exists({
- _id: { $in: agentIds },
- mcpServerNames: serverName,
- });
-
- return agent !== null;
+ const agents = await Agent.find({ mcpServerNames: serverName }, { _id: 1 }).lean<
+ Array<Pick<IAgent, '_id'>>
+ >();
+ return agents.map((agent) => agent._id);
}
- async function getMCPServerNamesByAgentIds(agentIds: Types.ObjectId[]): Promise<string[]> {
- if (agentIds.length === 0) {
- return [];
- }
-
+ /** Returns every agent with a non-empty `mcpServerNames`, so access
+ * calculations can start from the (typically small) set of agents that
+ * actually reference MCP servers instead of every accessible agent. */
+ async function getAgentsWithMCPServerNames(): Promise<
+ Array<Pick<IAgent, '_id' | 'mcpServerNames'>>
+ > {
const Agent = mongoose.models.Agent as Model<IAgent>;
- const agents = await Agent.find(
- {
- _id: { $in: agentIds },
- mcpServerNames: { $exists: true, $not: { $size: 0 } },
- },
- { mcpServerNames: 1 },
- ).lean<Array<Pick<IAgent, 'mcpServerNames'>>>();
-
- const serverNames = new Set<string>();
- for (const agent of agents) {
- for (const serverName of agent.mcpServerNames ?? []) {
- serverNames.add(serverName);
- }
- }
-
- return Array.from(serverNames);
+ return await Agent.find({ mcpServerNames: { $type: 'string' } }, { mcpServerNames: 1 }).lean<
+ Array<Pick<IAgent, '_id' | 'mcpServerNames'>>
+ >();
}
/**
@@ -1264,8 +1236,8 @@ export function createAgentMethods(
getAgentWithVersionCount,
getAgents,
createAgent,
- hasAgentWithMCPServerName,
- getMCPServerNamesByAgentIds,
+ getAgentIdsByMCPServerName,
+ getAgentsWithMCPServerNames,
updateAgent,
deleteAgent,
deleteUserAgents,