Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

☔ fix: 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.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<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.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<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.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<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.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 (