diff --git a/client/src/hooks/MCP/__tests__/useMCPServerManager.spec.tsx b/client/src/hooks/MCP/__tests__/useMCPServerManager.spec.tsx index 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/react import 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() { } 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 }) => ( + + {children} + + ); + 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.ts index 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.ts index 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.ts index 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.ts index 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; } @@ -142,6 +144,7 @@ export async function createOAuthMCPServer( requireResourceParameter = false, rejectRefreshTokens = 0, echoHandler, + refreshFailure, } = options; const sessions = new Map(); @@ -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.ts index 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 { + 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.ts index 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 (