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: Preserve MCP Authorization During Token Endpoint Outages (#16126)
lia-by-librechat[bot]ceecedaf7aab
diff --git a/client/src/hooks/MCP/__tests__/useMCPServerManager.spec.tsx b/client/src/hooks/MCP/__tests__/useMCPServerManager.spec.tsxindex 263382214b..34a3b2b47c 100644--- a/client/src/hooks/MCP/__tests__/useMCPServerManager.spec.tsx+++ b/client/src/hooks/MCP/__tests__/useMCPServerManager.spec.tsx@@ -6,6 +6,9 @@ import { QueryClient, QueryClientProvider, QueryObserver } from '@tanstack/reactimport type { MCPReinitializeResponse } from 'librechat-data-provider';import { useMCPServerManager } from '../useMCPServerManager';+const mockOpenInNewTab = jest.fn();+jest.mock('~/utils', () => ({ openInNewTab: (...args: unknown[]) => mockOpenInNewTab(...args) }));+const mockShowToast = jest.fn();const mockSetMCPValues = jest.fn();const mockReinitialize = jest.fn();@@ -48,6 +51,68 @@ function deferred<T>() {}describe('useMCPServerManager initialization', () => {+ it.each(['response', 'http'] as const)(+ 'clears the spinner after a transient %s failure and lets retry succeed without OAuth',+ async (failure) => {+ mockReinitialize.mockReset();+ mockSetMCPValues.mockClear();+ mockShowToast.mockClear();+ mockOpenInNewTab.mockClear();+ const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });+ const wrapper = ({ children }: { children: React.ReactNode }) => (+ <Provider>+ <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>+ </Provider>+ );+ const { result, unmount } = renderHook(() => useMCPServerManager(), { wrapper });+ const consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);+ try {+ if (failure === 'http') {+ mockReinitialize.mockRejectedValueOnce(new Error('Service temporarily unavailable'));+ } else {+ mockReinitialize.mockResolvedValueOnce({+ success: false,+ serverName: 'test-server',+ oauthRequired: false,+ failureReason: 'initialization_failed',+ });+ }+ await act(async () => {+ await result.current.initializeServer('test-server');+ });+ expect(result.current.isInitializing('test-server')).toBe(false);+ expect(result.current.isCancellable('test-server')).toBe(false);+ expect(mockOpenInNewTab).not.toHaveBeenCalled();+ expect(mockSetMCPValues).not.toHaveBeenCalled();+ expect(mockShowToast).toHaveBeenLastCalledWith({+ message: 'com_ui_mcp_init_failed',+ status: 'error',+ });++ mockReinitialize.mockResolvedValueOnce({+ success: true,+ serverName: 'test-server',+ oauthRequired: false,+ });+ await act(async () => {+ await result.current.initializeServer('test-server');+ });+ expect(mockReinitialize).toHaveBeenCalledTimes(2);+ expect(result.current.isInitializing('test-server')).toBe(false);+ expect(mockOpenInNewTab).not.toHaveBeenCalled();+ expect(mockSetMCPValues).toHaveBeenCalledWith(['test-server']);+ expect(mockShowToast).toHaveBeenLastCalledWith({+ message: 'com_ui_mcp_initialized_success',+ status: 'success',+ });+ } finally {+ consoleError.mockRestore();+ unmount();+ queryClient.clear();+ }+ },+ );+it('keeps passive authorization observers opt-in for shared hook callers', () => {const queryClient = new QueryClient();const wrapper = ({ children }: { children: React.ReactNode }) => (diff --git a/packages/api/src/mcp/__tests__/MCPConnectionFactory.oauthSdk.integration.test.ts b/packages/api/src/mcp/__tests__/MCPConnectionFactory.oauthSdk.integration.test.tsindex 180d4ae4ae..c723985eca 100644--- a/packages/api/src/mcp/__tests__/MCPConnectionFactory.oauthSdk.integration.test.ts+++ b/packages/api/src/mcp/__tests__/MCPConnectionFactory.oauthSdk.integration.test.ts@@ -313,6 +313,142 @@ describe('MCPConnectionFactory OAuth against real SDK Streamable HTTP server', (expect(server.tokenRequests.filter((r) => r.grantType === 'refresh_token')).toHaveLength(1);});+ it.each([+ {+ status: 503,+ error: 'temporarily_unavailable',+ scope: 'read',+ discovery: false,+ coordinate: false,+ },+ { status: 503, error: 'invalid_client', scope: 'read', discovery: false, coordinate: false },+ { status: 429, error: 'invalid_grant', scope: '', discovery: false, coordinate: false },+ { status: 429, error: 'invalid_scope', scope: 'read', discovery: true, coordinate: true },+ { status: 503, error: 'invalid_client', scope: 'read', discovery: true, coordinate: true },+ { status: 408, error: 'invalid_grant', scope: '', discovery: false, coordinate: true },+ ])(+ 'preserves authorization through HTTP $status ($error, discovery=$discovery), then retries without consent',+ async ({ status, error, scope, discovery, coordinate }) => {+ let unavailable = true;+ server = await createOAuthMCPServer({+ issueRefreshTokens: true,+ rotateRefreshTokens: true,+ requireResourceParameter: true,+ refreshFailure: () =>+ unavailable ? { status, body: JSON.stringify({ error }) } : undefined,+ });+ const initial = await issueTokens(server, scope);+ await storeTokens(tokenStore, server, { ...initial, expires_at: Date.now() - 1000 }, scope);+ const flowManager = createFlowManager();+ const oauthStart = jest.fn();+ const tokenMethods = {+ findToken: tokenStore.findToken,+ createToken: tokenStore.createToken,+ updateToken: tokenStore.updateToken,+ deleteTokens: tokenStore.deleteTokens,+ };+ const snapshot = () =>+ Promise.all([+ tokenStore.findToken({+ userId: USER_ID,+ type: 'mcp_oauth_refresh',+ identifier: `mcp:${SERVER_NAME}:refresh`,+ }),+ tokenStore.findToken({+ userId: USER_ID,+ type: 'mcp_oauth_client',+ identifier: `mcp:${SERVER_NAME}:client`,+ }),+ ]);+ const before = await snapshot();+ const basic = {+ serverName: SERVER_NAME,+ serverConfig: {+ type: 'streamable-http' as const,+ url: server.url,+ initTimeout: 15000,+ requiresOAuth: true,+ oauthRefreshCoordination: coordinate,+ },+ };+ const options = {+ useOAuth: true as const,+ user: { id: USER_ID } as IUser,+ flowManager,+ tokenMethods,+ oauthStart,+ returnOnOAuth: true,+ };+ const attempt = () =>+ discovery+ ? MCPConnectionFactory.discoverTools(basic, options)+ : MCPConnectionFactory.create(basic, options);+ await expect(attempt()).rejects.toMatchObject({ name: 'MCPTokenRefreshUnavailableError' });+ expect(oauthStart).not.toHaveBeenCalled();+ expect(await snapshot()).toEqual(before);+ expect(server.issuedRefreshTokens.has(initial.refresh_token!)).toBe(true);+ expect(server.tokenRequests.filter((r) => r.grantType === 'refresh_token')).toHaveLength(1);++ unavailable = false;+ const recovered = await attempt();+ connection = 'connection' in recovered ? recovered.connection : recovered;+ expect(connection).not.toBeNull();+ expect(await connection!.isConnected()).toBe(true);+ expect((await connection!.fetchTools()).some((tool) => tool.name === 'echo')).toBe(true);+ expect(oauthStart).not.toHaveBeenCalled();+ expect(server.tokenRequests.filter((r) => r.grantType === 'authorization_code')).toHaveLength(+ 1,+ );+ expect(server.tokenRequests.filter((r) => r.grantType === 'refresh_token')).toHaveLength(2);+ const [rotated] = await snapshot();+ expect(rotated?.token).not.toBe(before[0]?.token);+ expect(server.issuedRefreshTokens.has(rotated!.token.replace(/^enc:/, ''))).toBe(true);+ },+ );++ it.each(['invalid_client', 'invalid_grant'])(+ 'still requests consent for a permanent HTTP 400 %s',+ async (error) => {+ server = await createOAuthMCPServer({+ issueRefreshTokens: true,+ refreshFailure: () => ({ status: 400, body: JSON.stringify({ error }) }),+ });+ const initial = await issueTokens(server);+ await storeTokens(tokenStore, server, { ...initial, expires_at: Date.now() - 1000 });+ const oauthStart = jest.fn();+ const flowManager = createFlowManager();+ try {+ await expect(+ MCPConnectionFactory.create(+ {+ serverName: SERVER_NAME,+ serverConfig: { type: 'streamable-http', url: server.url, requiresOAuth: true },+ },+ {+ useOAuth: true,+ user: { id: USER_ID } as IUser,+ flowManager,+ returnOnOAuth: true,+ oauthStart,+ tokenMethods: {+ findToken: tokenStore.findToken,+ createToken: tokenStore.createToken,+ updateToken: tokenStore.updateToken,+ deleteTokens: tokenStore.deleteTokens,+ },+ },+ ),+ ).rejects.toThrow('OAuth flow initiated');+ expect(oauthStart).toHaveBeenCalledTimes(1);+ } finally {+ await flowManager.deleteFlow(+ MCPOAuthHandler.generateFlowId(USER_ID, SERVER_NAME),+ 'mcp_oauth',+ );+ }+ },+ );+it('silently refreshes a server-rejected token and reconnects with the MCP resource parameter', async () => {server = await createOAuthMCPServer({issueRefreshTokens: true,diff --git a/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts b/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.tsindex e635d9f140..454d7014aa 100644--- a/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts+++ b/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts@@ -1174,6 +1174,47 @@ describe('MCPTokenStorage', () => {);});+ it.each(['invalid_client', 'invalid_grant', 'invalid_scope', 'unauthorized_client'])(+ 'preserves a typed temporary failure even when its message contains %s',+ async (serverName) => {+ await createBoundToken(store, {+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ token: 'enc:expired-token',+ expiresIn: -1,+ });+ await createBoundToken(store, {+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:srv1:refresh',+ token: 'enc:rt',+ expiresIn: 86400,+ });+ const failure = new MCPTokenRefreshUnavailableError(serverName, new Error('HTTP 503'));+ const deleteTokens = jest.fn(store.deleteTokens);+ await expect(+ MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ createToken: store.createToken,+ updateToken: store.updateToken,+ deleteTokens,+ refreshTokens: jest.fn().mockRejectedValue(failure),+ }),+ ).rejects.toBe(failure);+ expect(deleteTokens).not.toHaveBeenCalled();+ expect(+ await store.findToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:srv1:refresh',+ }),+ ).toMatchObject({ token: 'enc:rt' });+ },+ );+it('reports transient refresh failures separately from reauthentication', async () => {await createBoundToken(store, {userId: 'u1',diff --git a/packages/api/src/mcp/__tests__/handler.refreshScope.test.ts b/packages/api/src/mcp/__tests__/handler.refreshScope.test.tsindex cb80058d6b..5ecc613b15 100644--- a/packages/api/src/mcp/__tests__/handler.refreshScope.test.ts+++ b/packages/api/src/mcp/__tests__/handler.refreshScope.test.ts@@ -100,6 +100,71 @@ describe('MCPOAuthHandler.refreshOAuthTokens — scope parameter fallback', () =global.fetch = originalFetch;});+ it.each([408, 429, 500, 502, 503, 504])(+ 'keeps HTTP %i retryable without reading or logging misleading scope/client errors',+ async (status) => {+ const cancel = jest.fn().mockResolvedValue(undefined);+ const text = jest.fn(async () => 'invalid_client invalid_grant invalid_scope not supported');+ responseQueue = [{ status, ok: false, text, body: { cancel } } as unknown as Response];+ await expect(+ MCPOAuthHandler.refreshOAuthTokens(refreshToken, metadata, {}, {}),+ ).rejects.toMatchObject({+ name: 'MCPTokenRefreshUnavailableError',+ cause: { message: `Token refresh temporarily unavailable (HTTP ${status})` },+ });+ expect(sentBodies).toHaveLength(1);+ expect(text).not.toHaveBeenCalled();+ expect(cancel).toHaveBeenCalledTimes(1);+ },+ );++ it('keeps an outage after the scope fallback retryable', async () => {+ responseQueue = [scopeRejection, new Response('{"error":"invalid_client"}', { status: 503 })];+ await expect(+ MCPOAuthHandler.refreshOAuthTokens(refreshToken, metadata, {}, {}),+ ).rejects.toMatchObject({ name: 'MCPTokenRefreshUnavailableError' });+ expect(sentBodies).toHaveLength(2);+ expect(sentBodies[1]).not.toContain('scope=');+ });++ it('keeps an outage retryable even when cancelling its response stream fails', async () => {+ responseQueue = [+ {+ status: 503,+ body: {+ cancel: async () => {+ throw new Error('invalid_client');+ },+ },+ } as unknown as Response,+ ];+ await expect(+ MCPOAuthHandler.refreshOAuthTokens(refreshToken, metadata, {}, {}),+ ).rejects.toMatchObject({ name: 'MCPTokenRefreshUnavailableError' });+ });++ it.each(['configured', 'discovered'] as const)(+ 'preserves outage status in the %s refresh path',+ async (mode) => {+ responseQueue = [new Response('{"error":"invalid_grant"}', { status: 503 })];+ await expect(+ MCPOAuthHandler.refreshOAuthTokens(+ refreshToken,+ { serverName: metadata.serverName, serverUrl: metadata.serverUrl },+ {},+ mode === 'configured'+ ? {+ token_url: discovered.token_endpoint,+ client_id: 'configured-client',+ scope: 'read',+ }+ : {},+ ),+ ).rejects.toMatchObject({ name: 'MCPTokenRefreshUnavailableError' });+ expect(sentBodies).toHaveLength(1);+ },+ );+it('retries without scope when the server rejects the scope parameter, then succeeds', async () => {responseQueue = [scopeRejection, success];diff --git a/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts b/packages/api/src/mcp/__tests__/helpers/oauthTestServer.tsindex 422fda3911..5975b678c3 100644--- a/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts+++ b/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts@@ -72,6 +72,8 @@ export interface OAuthTestServerOptions {requireResourceParameter?: boolean;/** Number of refresh-grant access tokens the MCP resource should reject after issuance. */rejectRefreshTokens?: number;+ /** Injects an endpoint failure before redemption; undefined resumes normal refresh behavior. */+ refreshFailure?: () => { status: number; body: string } | undefined;/** Optional test hook for controlling echo-tool completion. */echoHandler?: (message: string) => string | Promise<string>;}@@ -142,6 +144,7 @@ export async function createOAuthMCPServer(requireResourceParameter = false,rejectRefreshTokens = 0,echoHandler,+ refreshFailure,} = options;const sessions = new Map<string, StreamableHTTPServerTransport>();@@ -397,6 +400,13 @@ export async function createOAuthMCPServer(}if (grantType === 'refresh_token' && issueRefreshTokens) {+ const failure = refreshFailure?.();+ if (failure) {+ res.writeHead(failure.status, { 'Content-Type': 'application/json' });+ res.end(failure.body);+ return;+ }+const refreshToken = params.get('refresh_token');if (!refreshToken || !issuedRefreshTokens.has(refreshToken)) {res.writeHead(400, { 'Content-Type': 'application/json' });diff --git a/packages/api/src/mcp/oauth/handler.ts b/packages/api/src/mcp/oauth/handler.tsindex 6dcf8a5653..3123163cdf 100644--- a/packages/api/src/mcp/oauth/handler.ts+++ b/packages/api/src/mcp/oauth/handler.ts@@ -33,10 +33,10 @@ import {inferClientAuthMethod,} from './methods';import { isSSRFTarget, resolveHostnameSSRF, isOAuthUrlAllowed } from '~/auth';+import { MCPTokenStorage, MCPTokenRefreshUnavailableError } from './tokens';import { probeResourceMetadataHint } from './resourceHint';import { createHardenedOAuthFetch } from './hardenedFetch';import { sanitizeUrlForLogging } from '~/mcp/utils';-import { MCPTokenStorage } from './tokens';import { getOAuthUrlPort } from './url';/** Type for the OAuth metadata from the SDK */@@ -1720,6 +1720,23 @@ export class MCPOAuthHandler {} as MCPOAuthTokens;}+ /** HTTP outage/rate-limit status is authoritative, even if a proxy body names a bad grant. */+ private static async assertRefreshEndpointAvailable(+ response: Response,+ serverName: string,+ ): Promise<void> {+ if (!(response.status === 408 || response.status === 429 || response.status >= 500)) {+ return;+ }+ // Do not feed an outage body into the legacy invalid_client/invalid_grant message classifiers,+ // or log provider-controlled text that may contain credentials. No automatic redemption retry.+ await response.body?.cancel().catch(() => undefined);+ throw new MCPTokenRefreshUnavailableError(+ serverName,+ new Error(`Token refresh temporarily unavailable (HTTP ${response.status})`),+ );+ }+/*** Posts a `refresh_token` grant, transparently retrying without the `scope`* parameter when — and only when — the authorization server rejects the request@@ -1747,6 +1764,7 @@ export class MCPOAuthHandler {serverName,);const response = await oauthFetch(tokenUrl, { method: 'POST', headers, body, signal });+ await this.assertRefreshEndpointAvailable(response, serverName);if (response.ok || !body.has('scope')) {return response;}@@ -1763,7 +1781,9 @@ export class MCPOAuthHandler {`[MCPOAuth] ${serverName} rejected the scope parameter on token refresh (HTTP ${response.status}); retrying without scope per RFC 6749 §6`,);body.delete('scope');- return oauthFetch(tokenUrl, { method: 'POST', headers, body, signal });+ const retried = await oauthFetch(tokenUrl, { method: 'POST', headers, body, signal });+ await this.assertRefreshEndpointAvailable(retried, serverName);+ return retried;}/**@@ -2185,6 +2205,7 @@ export class MCPOAuthHandler {},);+ await this.assertRefreshEndpointAvailable(response, metadata.serverName);if (!response.ok) {const errorText = await response.text();throw new Error(diff --git a/packages/api/src/mcp/oauth/tokens.ts b/packages/api/src/mcp/oauth/tokens.tsindex be0fbf6357..ce58734728 100644--- a/packages/api/src/mcp/oauth/tokens.ts+++ b/packages/api/src/mcp/oauth/tokens.ts@@ -1658,6 +1658,9 @@ export class MCPTokenStorage {try {newTokens = await refreshTokens(decryptedRefreshToken, metadata, signal);} catch (error) {+ if (error instanceof MCPTokenRefreshUnavailableError) {+ throw error;+ }// These endpoint responses reject the refresh request permanently; a new grant can recover.// Classify only provider failures here, never a similarly worded persistence failure.const message = error instanceof Error ? error.message : String(error);@@ -1743,7 +1746,10 @@ export class MCPTokenStorage {return storedTokens;} catch (refreshError) {logger.error(`${logPrefix} Failed to refresh tokens`, refreshError);- if (refreshError instanceof ReauthenticationRequiredError) {+ if (+ refreshError instanceof ReauthenticationRequiredError ||+ refreshError instanceof MCPTokenRefreshUnavailableError+ ) {throw refreshError;}if (