Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🩹 fix: MCP Server Recovery from Startup Inspection Failures (#12145)
Danny Avila32cadb1cc580
diff --git a/api/server/services/Tools/mcp.js b/api/server/services/Tools/mcp.jsindex 10f2d71a18..7589043e10 100644--- a/api/server/services/Tools/mcp.js+++ b/api/server/services/Tools/mcp.js@@ -1,8 +1,8 @@const { logger } = require('@librechat/data-schemas');const { CacheKeys, Constants } = require('librechat-data-provider');+const { getMCPManager, getMCPServersRegistry, getFlowStateManager } = require('~/config');const { findToken, createToken, updateToken, deleteTokens } = require('~/models');const { updateMCPServerTools } = require('~/server/services/Config');-const { getMCPManager, getFlowStateManager } = require('~/config');const { getLogStores } = require('~/cache');/**@@ -41,6 +41,33 @@ async function reinitMCPServer({let oauthUrl = null;try {+ const registry = getMCPServersRegistry();+ const serverConfig = await registry.getServerConfig(serverName, user?.id);+ if (serverConfig?.inspectionFailed) {+ logger.info(+ `[MCP Reinitialize] Server ${serverName} had failed inspection, attempting reinspection`,+ );+ try {+ const storageLocation = serverConfig.dbId ? 'DB' : 'CACHE';+ await registry.reinspectServer(serverName, storageLocation, user?.id);+ logger.info(`[MCP Reinitialize] Reinspection succeeded for server: ${serverName}`);+ } catch (reinspectError) {+ logger.error(+ `[MCP Reinitialize] Reinspection failed for server ${serverName}:`,+ reinspectError,+ );+ return {+ availableTools: null,+ success: false,+ message: `MCP server '${serverName}' is still unreachable`,+ oauthRequired: false,+ serverName,+ oauthUrl: null,+ tools: null,+ };+ }+ }+const customUserVars = userMCPAuthMap?.[`${Constants.mcp_prefix}${serverName}`];const flowManager = _flowManager ?? getFlowStateManager(getLogStores(CacheKeys.FLOWS));const mcpManager = getMCPManager();diff --git a/packages/api/src/mcp/ConnectionsRepository.ts b/packages/api/src/mcp/ConnectionsRepository.tsindex edd1eabc2e..e629934dda 100644--- a/packages/api/src/mcp/ConnectionsRepository.ts+++ b/packages/api/src/mcp/ConnectionsRepository.ts@@ -140,6 +140,9 @@ export class ConnectionsRepository {}private isAllowedToConnectToServer(config: t.ParsedServerConfig) {+ if (config.inspectionFailed) {+ return false;+ }//the repository is not allowed to be connected in case the Connection repository is shared (ownerId is undefined/null) and the server requires Auth or startup false.if (this.ownerId === undefined && (config.startup === false || config.requiresOAuth)) {return false;diff --git a/packages/api/src/mcp/registry/MCPServersInitializer.ts b/packages/api/src/mcp/registry/MCPServersInitializer.tsindex 92505db12b..a8b8e3ca8a 100644--- a/packages/api/src/mcp/registry/MCPServersInitializer.ts+++ b/packages/api/src/mcp/registry/MCPServersInitializer.ts@@ -1,11 +1,10 @@-import { registryStatusCache as statusCache } from './cache/RegistryStatusCache';-import { isLeader } from '~/cluster';-import { withTimeout } from '~/utils';import { logger } from '@librechat/data-schemas';-import { ParsedServerConfig } from '~/mcp/types';-import { sanitizeUrlForLogging } from '~/mcp/utils';import type * as t from '~/mcp/types';+import { registryStatusCache as statusCache } from './cache/RegistryStatusCache';import { MCPServersRegistry } from './MCPServersRegistry';+import { sanitizeUrlForLogging } from '~/mcp/utils';+import { withTimeout } from '~/utils';+import { isLeader } from '~/cluster';const MCP_INIT_TIMEOUT_MS =process.env.MCP_INIT_TIMEOUT_MS != null ? parseInt(process.env.MCP_INIT_TIMEOUT_MS) : 30_000;@@ -80,11 +79,22 @@ export class MCPServersInitializer {MCPServersInitializer.logParsedConfig(serverName, result.config);} catch (error) {logger.error(`${MCPServersInitializer.prefix(serverName)} Failed to initialize:`, error);+ try {+ await MCPServersRegistry.getInstance().addServerStub(serverName, rawConfig, 'CACHE');+ logger.info(+ `${MCPServersInitializer.prefix(serverName)} Stored stub config for recovery via reinitialize`,+ );+ } catch (stubError) {+ logger.error(+ `${MCPServersInitializer.prefix(serverName)} Failed to store stub config:`,+ stubError,+ );+ }}}// Logs server configuration summary after initialization- private static logParsedConfig(serverName: string, config: ParsedServerConfig): void {+ private static logParsedConfig(serverName: string, config: t.ParsedServerConfig): void {const prefix = MCPServersInitializer.prefix(serverName);logger.info(`${prefix} -------------------------------------------------┐`);logger.info(`${prefix} URL: ${config.url ? sanitizeUrlForLogging(config.url) : 'N/A'}`);diff --git a/packages/api/src/mcp/registry/MCPServersRegistry.ts b/packages/api/src/mcp/registry/MCPServersRegistry.tsindex 0264a8ed7a..506f5b1baa 100644--- a/packages/api/src/mcp/registry/MCPServersRegistry.ts+++ b/packages/api/src/mcp/registry/MCPServersRegistry.ts@@ -144,6 +144,24 @@ export class MCPServersRegistry {return result;}+ /**+ * Stores a minimal config stub so the server remains "known" to the registry+ * even when inspection fails at startup. This enables reinitialize to recover.+ */+ public async addServerStub(+ serverName: string,+ config: t.MCPOptions,+ storageLocation: 'CACHE' | 'DB',+ userId?: string,+ ): Promise<t.AddServerResult> {+ const configRepo = this.getConfigRepository(storageLocation);+ const stubConfig: t.ParsedServerConfig = { ...config, inspectionFailed: true };+ const result = await configRepo.add(serverName, stubConfig, userId);+ await this.readThroughCache.delete(this.getReadThroughCacheKey(serverName, userId));+ await this.readThroughCache.delete(this.getReadThroughCacheKey(serverName));+ return result;+ }+public async addServer(serverName: string,config: t.MCPOptions,@@ -170,6 +188,52 @@ export class MCPServersRegistry {return await configRepo.add(serverName, parsedConfig, userId);}+ /**+ * Re-inspects a server that previously failed initialization.+ * Uses the stored stub config to attempt a full inspection and replaces the stub on success.+ */+ public async reinspectServer(+ serverName: string,+ storageLocation: 'CACHE' | 'DB',+ userId?: string,+ ): Promise<t.AddServerResult> {+ const configRepo = this.getConfigRepository(storageLocation);+ const existing = await configRepo.get(serverName, userId);+ if (!existing) {+ throw new Error(`Server "${serverName}" not found in ${storageLocation} for reinspection.`);+ }+ if (!existing.inspectionFailed) {+ throw new Error(+ `Server "${serverName}" is not in a failed state. Use updateServer() instead.`,+ );+ }++ const { inspectionFailed: _, ...configForInspection } = existing;+ let parsedConfig: t.ParsedServerConfig;+ try {+ parsedConfig = await MCPServerInspector.inspect(+ serverName,+ configForInspection,+ undefined,+ this.allowedDomains,+ );+ } catch (error) {+ logger.error(`[MCPServersRegistry] Reinspection failed for server "${serverName}":`, error);+ if (isMCPDomainNotAllowedError(error)) {+ throw error;+ }+ throw new MCPInspectionFailedError(serverName, error as Error);+ }++ const updatedConfig = { ...parsedConfig, updatedAt: Date.now() };+ await configRepo.update(serverName, updatedConfig, userId);+ await this.readThroughCache.delete(this.getReadThroughCacheKey(serverName, userId));+ await this.readThroughCache.delete(this.getReadThroughCacheKey(serverName));+ // Full clear required: getAllServerConfigs is keyed by userId with no reverse index to enumerate cached keys+ await this.readThroughCacheAll.clear();+ return { serverName, config: updatedConfig };+ }+public async updateServer(serverName: string,config: t.MCPOptions,diff --git a/packages/api/src/mcp/registry/__tests__/MCPReinitRecovery.integration.test.ts b/packages/api/src/mcp/registry/__tests__/MCPReinitRecovery.integration.test.tsnew file mode 100644index 0000000000..b171e84d13--- /dev/null+++ b/packages/api/src/mcp/registry/__tests__/MCPReinitRecovery.integration.test.ts@@ -0,0 +1,488 @@+/**+ * Integration tests for MCP server reinitialize recovery (issue #12143).+ *+ * Reproduces the bug: when an MCP server is unreachable at startup,+ * inspection fails and the server config is never stored — making the+ * reinitialize button return 404 and blocking all recovery.+ *+ * These tests spin up a real in-process MCP server using the SDK's+ * StreamableHTTPServerTransport and exercise the full+ * MCPServersInitializer → MCPServersRegistry → MCPServerInspector pipeline+ * with real connections — no mocked transports, no mocked inspections.+ *+ * Minimal mocks: only logger, auth/SSRF, cluster, mcpConfig, and DB repo+ * (to avoid MongoDB). Everything else — the inspector, registry, cache,+ * initializer, and MCP connection — runs for real.+ */++import * as net from 'net';+import * as http from 'http';+import { Agent } from 'undici';+import { randomUUID } from 'crypto';+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';+import { Keyv } from 'keyv';+import { Types } from 'mongoose';+import type { IUser } from '@librechat/data-schemas';+import type { Socket } from 'net';+import type * as t from '~/mcp/types';+import { MCPInspectionFailedError } from '~/mcp/errors';+import { registryStatusCache } from '~/mcp/registry/cache/RegistryStatusCache';+import { MCPServersInitializer } from '~/mcp/registry/MCPServersInitializer';+import { MCPServersRegistry } from '~/mcp/registry/MCPServersRegistry';+import { ConnectionsRepository } from '~/mcp/ConnectionsRepository';+import { FlowStateManager } from '~/flow/manager';+import { MCPConnection } from '~/mcp/connection';+import { MCPManager } from '~/mcp/MCPManager';++jest.mock('@librechat/data-schemas', () => ({+ logger: {+ info: jest.fn(),+ warn: jest.fn(),+ error: jest.fn(),+ debug: jest.fn(),+ },+}));++jest.mock('~/auth', () => ({+ createSSRFSafeUndiciConnect: jest.fn(() => undefined),+ resolveHostnameSSRF: jest.fn(async () => false),+}));++jest.mock('~/cluster', () => ({+ isLeader: jest.fn().mockResolvedValue(true),+}));++jest.mock('~/mcp/mcpConfig', () => ({+ mcpConfig: { CONNECTION_CHECK_TTL: 0 },+}));++jest.mock('~/mcp/registry/db/ServerConfigsDB', () => ({+ ServerConfigsDB: jest.fn().mockImplementation(() => ({+ get: jest.fn().mockResolvedValue(undefined),+ getAll: jest.fn().mockResolvedValue({}),+ add: jest.fn().mockResolvedValue(undefined),+ update: jest.fn().mockResolvedValue(undefined),+ remove: jest.fn().mockResolvedValue(undefined),+ reset: jest.fn().mockResolvedValue(undefined),+ })),+}));++const mockMongoose = {} as typeof import('mongoose');++const allAgentsCreated: Agent[] = [];+const OriginalAgent = Agent;+const PatchedAgent = new Proxy(OriginalAgent, {+ construct(target, args) {+ const instance = new target(...(args as [Agent.Options?]));+ allAgentsCreated.push(instance);+ return instance;+ },+});+(global as Record<string, unknown>).__undiciAgent = PatchedAgent;++afterAll(async () => {+ const destroying = allAgentsCreated.map((a) => {+ if (!a.destroyed && !a.closed) {+ return a.destroy().catch(() => undefined);+ }+ return Promise.resolve();+ });+ allAgentsCreated.length = 0;+ await Promise.all(destroying);+});++async function safeDisconnect(conn: MCPConnection | null): Promise<void> {+ if (!conn) return;+ (conn as unknown as { shouldStopReconnecting: boolean }).shouldStopReconnecting = true;+ conn.removeAllListeners();+ await conn.disconnect();+}++function getFreePort(): Promise<number> {+ return new Promise((resolve, reject) => {+ const srv = net.createServer();+ srv.listen(0, '127.0.0.1', () => {+ const addr = srv.address() as net.AddressInfo;+ srv.close((err) => (err ? reject(err) : resolve(addr.port)));+ });+ });+}++function trackSockets(httpServer: http.Server): () => Promise<void> {+ const sockets = new Set<Socket>();+ httpServer.on('connection', (socket: Socket) => {+ sockets.add(socket);+ socket.once('close', () => sockets.delete(socket));+ });+ return () =>+ new Promise<void>((resolve) => {+ for (const socket of sockets) socket.destroy();+ sockets.clear();+ httpServer.close(() => resolve());+ });+}++interface TestServer {+ url: string;+ port: number;+ close: () => Promise<void>;+}++async function createMCPServerOnPort(port: number): Promise<TestServer> {+ const sessions = new Map<string, StreamableHTTPServerTransport>();++ const httpServer = http.createServer(async (req, res) => {+ const sid = req.headers['mcp-session-id'] as string | undefined;+ let transport = sid ? sessions.get(sid) : undefined;++ if (!transport) {+ transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });+ const mcp = new McpServer({ name: 'recovery-test-server', version: '0.0.1' });+ mcp.tool('echo', 'Echo tool for testing', {}, async () => ({+ content: [{ type: 'text', text: 'ok' }],+ }));+ mcp.tool('greet', 'Greeting tool', {}, async () => ({+ content: [{ type: 'text', text: 'hello' }],+ }));+ await mcp.connect(transport);+ }++ await transport.handleRequest(req, res);++ if (transport.sessionId && !sessions.has(transport.sessionId)) {+ sessions.set(transport.sessionId, transport);+ transport.onclose = () => sessions.delete(transport!.sessionId!);+ }+ });++ const destroySockets = trackSockets(httpServer);+ await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', resolve));++ return {+ url: `http://127.0.0.1:${port}/`,+ port,+ close: async () => {+ const closing = [...sessions.values()].map((t) => t.close().catch(() => undefined));+ sessions.clear();+ await Promise.all(closing);+ await destroySockets();+ },+ };+}++describe('MCP reinitialize recovery – integration (issue #12143)', () => {+ let server: TestServer | null = null;+ let conn: MCPConnection | null = null;+ let registry: MCPServersRegistry;++ beforeEach(async () => {+ (MCPServersRegistry as unknown as { instance: undefined }).instance = undefined;+ MCPServersRegistry.createInstance(mockMongoose, ['127.0.0.1']);+ registry = MCPServersRegistry.getInstance();+ await registryStatusCache.reset();+ await registry.reset();+ MCPServersInitializer.resetProcessFlag();+ });++ afterEach(async () => {+ await safeDisconnect(conn);+ conn = null;+ // Reset MCPManager if it was created during the test+ try {+ const mgr = MCPManager.getInstance();+ await Promise.all(mgr.appConnections?.disconnectAll() ?? []);+ } catch {+ // Not initialized — nothing to clean up+ }+ (MCPManager as unknown as { instance: null }).instance = null;+ if (server) {+ await server.close();+ server = null;+ }+ });++ it('should store a stub config when the MCP server is unreachable at startup', async () => {+ const deadPort = await getFreePort();+ const configs: t.MCPServers = {+ 'speedy-mcp': {+ type: 'streamable-http',+ url: `http://127.0.0.1:${deadPort}/`,+ },+ };++ await MCPServersInitializer.initialize(configs);++ // Before the fix: getServerConfig would return undefined here+ // After the fix: a stub with inspectionFailed=true is stored+ const config = await registry.getServerConfig('speedy-mcp');+ expect(config).toBeDefined();+ expect(config!.inspectionFailed).toBe(true);+ expect(config!.url).toBe(`http://127.0.0.1:${deadPort}/`);+ expect(config!.tools).toBeUndefined();+ expect(config!.capabilities).toBeUndefined();+ expect(config!.toolFunctions).toBeUndefined();+ });++ it('should recover via reinspectServer after the MCP server comes back online', async () => {+ // Phase 1: Server is down at startup+ const deadPort = await getFreePort();+ const configs: t.MCPServers = {+ 'speedy-mcp': {+ type: 'streamable-http',+ url: `http://127.0.0.1:${deadPort}/`,+ },+ };++ await MCPServersInitializer.initialize(configs);++ const stubConfig = await registry.getServerConfig('speedy-mcp');+ expect(stubConfig).toBeDefined();+ expect(stubConfig!.inspectionFailed).toBe(true);++ // Phase 2: Start the real server on the same (previously dead) port+ server = await createMCPServerOnPort(deadPort);++ // Phase 3: Reinspect — this is what the reinitialize button triggers+ const result = await registry.reinspectServer('speedy-mcp', 'CACHE');++ // Verify the stub was replaced with a fully inspected config+ expect(result.config.inspectionFailed).toBeUndefined();+ expect(result.config.tools).toContain('echo');+ expect(result.config.tools).toContain('greet');+ expect(result.config.capabilities).toBeDefined();+ expect(result.config.toolFunctions).toBeDefined();++ // Verify the registry now returns the real config+ const realConfig = await registry.getServerConfig('speedy-mcp');+ expect(realConfig).toBeDefined();+ expect(realConfig!.inspectionFailed).toBeUndefined();+ expect(realConfig!.tools).toContain('echo');+ });++ it('should allow a real client connection after reinspection succeeds', async () => {+ // Phase 1: Server is down at startup+ const deadPort = await getFreePort();+ const configs: t.MCPServers = {+ 'speedy-mcp': {+ type: 'streamable-http',+ url: `http://127.0.0.1:${deadPort}/`,+ },+ };++ await MCPServersInitializer.initialize(configs);+ expect((await registry.getServerConfig('speedy-mcp'))!.inspectionFailed).toBe(true);++ // Phase 2: Server comes back online on the same port+ server = await createMCPServerOnPort(deadPort);++ // Phase 3: Reinspect+ await registry.reinspectServer('speedy-mcp', 'CACHE');++ // Phase 4: Establish a real client connection+ conn = new MCPConnection({+ serverName: 'speedy-mcp',+ serverConfig: { type: 'streamable-http', url: server.url },+ useSSRFProtection: false,+ });++ await conn.connect();+ const tools = await conn.fetchTools();++ expect(tools).toHaveLength(2);+ expect(tools.map((t) => t.name)).toContain('echo');+ expect(tools.map((t) => t.name)).toContain('greet');+ });++ it('should not attempt connections to stub servers via ConnectionsRepository', async () => {+ const deadPort = await getFreePort();+ await MCPServersInitializer.initialize({+ 'stub-srv': { type: 'streamable-http', url: `http://127.0.0.1:${deadPort}/` },+ });+ expect((await registry.getServerConfig('stub-srv'))!.inspectionFailed).toBe(true);++ const repo = new ConnectionsRepository(undefined);+ expect(await repo.has('stub-srv')).toBe(false);+ expect(await repo.get('stub-srv')).toBeNull();++ const all = await repo.getAll();+ expect(all.has('stub-srv')).toBe(false);+ });++ it('addServerStub should clear negative read-through cache entries', async () => {+ // Query a server that doesn't exist — result is negative-cached+ const config1 = await registry.getServerConfig('late-server');+ expect(config1).toBeUndefined();++ // Store a stub (simulating a failed init that runs after the lookup)+ await registry.addServerStub(+ 'late-server',+ { type: 'streamable-http', url: 'http://127.0.0.1:9999/' },+ 'CACHE',+ );++ // The stub should be found despite the earlier negative cache entry+ const config2 = await registry.getServerConfig('late-server');+ expect(config2).toBeDefined();+ expect(config2!.inspectionFailed).toBe(true);+ });++ it('concurrent reinspectServer calls should not crash or corrupt state', async () => {+ const deadPort = await getFreePort();+ await MCPServersInitializer.initialize({+ 'race-server': {+ type: 'streamable-http',+ url: `http://127.0.0.1:${deadPort}/`,+ },+ });+ expect((await registry.getServerConfig('race-server'))!.inspectionFailed).toBe(true);++ server = await createMCPServerOnPort(deadPort);++ // Simulate multiple users clicking Reinitialize at the same time.+ // reinitMCPServer calls reinspectServer internally — this tests the critical section.+ const n = 3 + Math.floor(Math.random() * 8); // 3–10 concurrent calls+ const results = await Promise.allSettled(+ Array.from({ length: n }, () => registry.reinspectServer('race-server', 'CACHE')),+ );++ const successes = results.filter((r) => r.status === 'fulfilled');+ const failures = results.filter((r) => r.status === 'rejected');++ // At least one must succeed+ expect(successes.length).toBeGreaterThanOrEqual(1);++ // Any failure must be the "not in a failed state" guard (the first call already+ // replaced the stub), not an unhandled crash or data corruption.+ for (const f of failures) {+ expect((f as PromiseRejectedResult).reason.message).toMatch(/not in a failed state/);+ }++ // Final state must be fully recovered regardless of how many succeeded+ const config = await registry.getServerConfig('race-server');+ expect(config).toBeDefined();+ expect(config!.inspectionFailed).toBeUndefined();+ expect(config!.tools).toContain('echo');+ });++ it('concurrent reinitMCPServer-equivalent flows should not crash or corrupt state', async () => {+ const deadPort = await getFreePort();+ const serverName = 'concurrent-reinit';+ const configs: t.MCPServers = {+ [serverName]: {+ type: 'streamable-http',+ url: `http://127.0.0.1:${deadPort}/`,+ },+ };++ // Reset MCPManager singleton so createInstance works+ (MCPManager as unknown as { instance: null }).instance = null;++ // Initialize with dead server — this sets up both registry (stub) and MCPManager+ await MCPManager.createInstance(configs);+ const mcpManager = MCPManager.getInstance();++ expect((await registry.getServerConfig(serverName))!.inspectionFailed).toBe(true);++ // Server comes back online+ server = await createMCPServerOnPort(deadPort);++ const flowManager = new FlowStateManager<null>(new Keyv(), { ttl: 60_000 });+ const makeUser = (): IUser =>+ ({+ _id: new Types.ObjectId(),+ id: new Types.ObjectId().toString(),+ username: 'testuser',+ email: '[email protected]',+ name: 'Test',+ avatar: '',+ provider: 'email',+ role: 'user',+ emailVerified: true,+ createdAt: new Date(),+ updatedAt: new Date(),+ }) as IUser;++ /**+ * Replicate reinitMCPServer logic: check inspectionFailed → reinspect → getConnection.+ * Each call uses a distinct user to simulate concurrent requests from different users.+ */+ async function simulateReinitMCPServer(): Promise<{ success: boolean; tools: number }> {+ const user = makeUser();+ const config = await registry.getServerConfig(serverName, user.id);+ if (config?.inspectionFailed) {+ try {+ const storageLocation = config.dbId ? 'DB' : 'CACHE';+ await registry.reinspectServer(serverName, storageLocation, user.id);+ } catch {+ // Mirrors reinitMCPServer early return on failed reinspection+ return { success: false, tools: 0 };+ }+ }++ const connection = await mcpManager.getConnection({+ serverName,+ user,+ flowManager,+ forceNew: true,+ });++ const tools = await connection.fetchTools();+ return { success: true, tools: tools.length };+ }++ const n = 3 + Math.floor(Math.random() * 5); // 3–7 concurrent calls+ const results = await Promise.allSettled(+ Array.from({ length: n }, () => simulateReinitMCPServer()),+ );++ // All promises should resolve (no unhandled throws)+ for (const r of results) {+ expect(r.status).toBe('fulfilled');+ }++ const values = (results as PromiseFulfilledResult<{ success: boolean; tools: number }>[]).map(+ (r) => r.value,+ );++ // At least one full reinit must succeed with tools+ const succeeded = values.filter((v) => v.success);+ expect(succeeded.length).toBeGreaterThanOrEqual(1);+ for (const s of succeeded) {+ expect(s.tools).toBe(2);+ }++ // Any that returned success: false hit the reinspect guard — that's fine+ const earlyReturned = values.filter((v) => !v.success);+ expect(earlyReturned.every((v) => v.tools === 0)).toBe(true);++ // Final registry state must be fully recovered+ const finalConfig = await registry.getServerConfig(serverName);+ expect(finalConfig).toBeDefined();+ expect(finalConfig!.inspectionFailed).toBeUndefined();+ expect(finalConfig!.tools).toContain('echo');+ });++ it('reinspectServer should throw MCPInspectionFailedError when the server is still unreachable', async () => {+ const deadPort = await getFreePort();+ const configs: t.MCPServers = {+ 'still-broken': {+ type: 'streamable-http',+ url: `http://127.0.0.1:${deadPort}/`,+ },+ };++ await MCPServersInitializer.initialize(configs);+ expect((await registry.getServerConfig('still-broken'))!.inspectionFailed).toBe(true);++ // Server is STILL down — reinspection should fail with MCPInspectionFailedError+ await expect(registry.reinspectServer('still-broken', 'CACHE')).rejects.toThrow(+ MCPInspectionFailedError,+ );++ // The stub should remain intact for future retry+ const config = await registry.getServerConfig('still-broken');+ expect(config).toBeDefined();+ expect(config!.inspectionFailed).toBe(true);+ });+});diff --git a/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.cache_integration.spec.ts b/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.cache_integration.spec.tsindex cb43cb68ce..12d2c9091f 100644--- a/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.cache_integration.spec.ts+++ b/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.cache_integration.spec.ts@@ -303,9 +303,10 @@ describe('MCPServersInitializer Redis Integration Tests', () => {const searchToolsServer = await registry.getServerConfig('search_tools_server');expect(searchToolsServer).toBeDefined();- // Verify file_tools_server was not added (due to inspection failure)+ // Verify file_tools_server was stored as a stub (for recovery via reinitialize)const fileToolsServer = await registry.getServerConfig('file_tools_server');- expect(fileToolsServer).toBeUndefined();+ expect(fileToolsServer).toBeDefined();+ expect(fileToolsServer?.inspectionFailed).toBe(true);});it('should set initialized status after completion', async () => {diff --git a/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.test.ts b/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.test.tsindex 255ef20760..2998b47d0b 100644--- a/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.test.ts+++ b/packages/api/src/mcp/registry/__tests__/MCPServersInitializer.test.ts@@ -1,11 +1,11 @@import { logger } from '@librechat/data-schemas';import * as t from '~/mcp/types';-import { MCPConnectionFactory } from '~/mcp/MCPConnectionFactory';-import { MCPServersInitializer } from '~/mcp/registry/MCPServersInitializer';-import { MCPConnection } from '~/mcp/connection';import { registryStatusCache } from '~/mcp/registry/cache/RegistryStatusCache';+import { MCPServersInitializer } from '~/mcp/registry/MCPServersInitializer';import { MCPServerInspector } from '~/mcp/registry/MCPServerInspector';import { MCPServersRegistry } from '~/mcp/registry/MCPServersRegistry';+import { MCPConnectionFactory } from '~/mcp/MCPConnectionFactory';+import { MCPConnection } from '~/mcp/connection';const FIXED_TIME = 1699564800000;const originalDateNow = Date.now;@@ -296,9 +296,10 @@ describe('MCPServersInitializer', () => {const searchToolsServer = await registry.getServerConfig('search_tools_server');expect(searchToolsServer).toBeDefined();- // Verify file_tools_server was not added (due to inspection failure)+ // Verify file_tools_server was stored as a stub (for recovery via reinitialize)const fileToolsServer = await registry.getServerConfig('file_tools_server');- expect(fileToolsServer).toBeUndefined();+ expect(fileToolsServer).toBeDefined();+ expect(fileToolsServer?.inspectionFailed).toBe(true);});it('should log server configuration after initialization', async () => {diff --git a/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts b/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.tsindex cc86f0e140..8891120717 100644--- a/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts+++ b/packages/api/src/mcp/registry/__tests__/MCPServersRegistry.test.ts@@ -1,4 +1,4 @@-import * as t from '~/mcp/types';+import type * as t from '~/mcp/types';import { MCPServersRegistry } from '~/mcp/registry/MCPServersRegistry';import { MCPServerInspector } from '~/mcp/registry/MCPServerInspector';@@ -193,6 +193,22 @@ describe('MCPServersRegistry', () => {});});+ describe('reinspectServer', () => {+ it('should throw when called on a healthy (non-stub) server', async () => {+ await registry.addServer('healthy_server', testParsedConfig, 'CACHE');++ await expect(registry.reinspectServer('healthy_server', 'CACHE')).rejects.toThrow(+ 'is not in a failed state',+ );+ });++ it('should throw when the server does not exist', async () => {+ await expect(registry.reinspectServer('ghost_server', 'CACHE')).rejects.toThrow(+ 'not found in CACHE',+ );+ });+ });+describe('Read-through cache', () => {describe('getServerConfig', () => {it('should cache repeated calls for the same server', async () => {diff --git a/packages/api/src/mcp/types/index.ts b/packages/api/src/mcp/types/index.tsindex 353bcb9c19..bbdabb4428 100644--- a/packages/api/src/mcp/types/index.ts+++ b/packages/api/src/mcp/types/index.ts@@ -156,6 +156,8 @@ export type ParsedServerConfig = MCPOptions & {dbId?: string;/** True if access is only via agent (not directly shared with user) */consumeOnly?: boolean;+ /** True when inspection failed at startup; the server is known but not fully initialized */+ inspectionFailed?: boolean;};export type AddServerResult = {