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: Recover Quietly From Stale MCP SSE Stream Conflicts (#14816)
Danny Avila6cbfd827722a
diff --git a/packages/api/src/mcp/__tests__/MCPConnection.test.ts b/packages/api/src/mcp/__tests__/MCPConnection.test.tsindex 2ca6a966dc..cfbba3a00c 100644--- a/packages/api/src/mcp/__tests__/MCPConnection.test.ts+++ b/packages/api/src/mcp/__tests__/MCPConnection.test.ts@@ -1,16 +1,21 @@/*** Tests for MCPConnection error detection methods.*- * Rate-limit and SSE tests use standalone implementations that mirror private methods in- * MCPConnection. OAuth classification exercises the production helper shared by the connection- * and factory.+ * Rate-limit tests use a standalone implementation that mirrors a private method in+ * MCPConnection. OAuth and SSE classification exercise the production helpers shared by the+ * connection and factory.** Alternative approaches considered:* 1. Reflection/type casting - fragile and breaks with refactoring* 2. Protected methods with test subclass - changes public API for testing* 3. Integration tests - tested separately in the full MCP test suite*/-import { isOAuthAuthenticationError } from '~/mcp/errors';+import { StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';+import {+ extractSSEErrorMessage,+ isOAuthAuthenticationError,+ isStandaloneSseConflict,+} from '~/mcp/errors';describe('MCPConnection Error Detection', () => {/**@@ -173,119 +178,6 @@ describe('MCPConnection Error Detection', () => {* particularly handling the "SSE error: undefined" case from the MCP SDK.*/describe('extractSSEErrorMessage', () => {- /**- * Standalone implementation of extractSSEErrorMessage for testing.- * This mirrors the function in connection.ts.- * Keep in sync with the actual implementation.- */- function extractSSEErrorMessage(error: unknown): {- message: string;- code?: number;- isProxyHint: boolean;- isTransient: boolean;- } {- if (!error || typeof error !== 'object') {- return {- message: 'Unknown SSE transport error',- isProxyHint: true,- isTransient: true,- };- }-- const errorObj = error as { message?: string; code?: number; event?: unknown };- const rawMessage = errorObj.message ?? '';- const code = errorObj.code;-- // Handle the common "SSE error: undefined" case- if (rawMessage === 'SSE error: undefined' || rawMessage === 'undefined' || !rawMessage) {- return {- message:- 'SSE connection closed. This can occur due to: (1) idle connection timeout (normal), ' +- '(2) reverse proxy buffering (check proxy_buffering config), or (3) network interruption.',- code,- isProxyHint: true,- isTransient: true,- };- }-- // Check for timeout patterns with case-insensitive matching- const lowerMessage = rawMessage.toLowerCase();- if (- rawMessage.includes('ETIMEDOUT') ||- rawMessage.includes('ESOCKETTIMEDOUT') ||- lowerMessage.includes('timed out') ||- lowerMessage.includes('timeout after') ||- lowerMessage.includes('request timeout')- ) {- return {- message: `SSE connection timed out: ${rawMessage}. If behind a reverse proxy, increase proxy_read_timeout.`,- code,- isProxyHint: true,- isTransient: true,- };- }-- // Connection reset is often transient- if (rawMessage.includes('ECONNRESET')) {- return {- message: `SSE connection reset: ${rawMessage}. The server or proxy may have restarted.`,- code,- isProxyHint: false,- isTransient: true,- };- }-- // Connection refused is more serious- if (rawMessage.includes('ECONNREFUSED')) {- return {- message: `SSE connection refused: ${rawMessage}. Verify the MCP server is running and accessible.`,- code,- isProxyHint: false,- isTransient: false,- };- }-- // DNS failure- if (rawMessage.includes('ENOTFOUND') || rawMessage.includes('getaddrinfo')) {- return {- message: `SSE DNS resolution failed: ${rawMessage}. Check the server URL is correct.`,- code,- isProxyHint: false,- isTransient: false,- };- }-- // Check for HTTP status codes- const statusMatch = rawMessage.match(/\b(4\d{2}|5\d{2})\b/);- if (statusMatch) {- const statusCode = parseInt(statusMatch[1], 10);- const isServerError = statusCode >= 500 && statusCode < 600;- return {- message: rawMessage,- code: statusCode,- isProxyHint: statusCode === 502 || statusCode === 503 || statusCode === 504,- isTransient: isServerError,- };- }-- if (rawMessage === 'fetch failed') {- return {- message:- 'fetch failed (request aborted, likely after a timeout — connection may still be usable)',- code,- isProxyHint: false,- isTransient: true,- };- }-- return {- message: rawMessage,- code,- isProxyHint: false,- isTransient: false,- };- }-describe('undefined/empty error handling', () => {it('should handle "SSE error: undefined" from MCP SDK', () => {const error = { message: 'SSE error: undefined', code: undefined };@@ -536,6 +428,73 @@ describe('extractSSEErrorMessage', () => {expect(result.isTransient).toBe(false);});});++ describe('status carried on code rather than in the message', () => {+ it('should classify a 409 standalone SSE stream conflict as transient', () => {+ const error = new StreamableHTTPError(409, 'Failed to open SSE stream: Conflict');+ const result = extractSSEErrorMessage(error);++ expect(result.code).toBe(409);+ expect(result.isTransient).toBe(true);+ expect(result.isProxyHint).toBe(false);+ });++ it('should classify a 5xx as transient when the message carries no digits', () => {+ const error = new StreamableHTTPError(503, 'Failed to open SSE stream: Service Unavailable');+ const result = extractSSEErrorMessage(error);++ expect(result.code).toBe(503);+ expect(result.isTransient).toBe(true);+ expect(result.isProxyHint).toBe(true);+ });++ it('should keep other 4xx non-transient when the message carries no digits', () => {+ const error = new StreamableHTTPError(403, 'Failed to open SSE stream: Forbidden');+ const result = extractSSEErrorMessage(error);++ expect(result.code).toBe(403);+ expect(result.isTransient).toBe(false);+ });++ it('should ignore non-HTTP codes so they do not reach the status branch', () => {+ const error = { message: 'Something went wrong', code: 42 };+ const result = extractSSEErrorMessage(error);++ expect(result.code).toBe(42);+ expect(result.isTransient).toBe(false);+ });+ });+});++describe('isStandaloneSseConflict', () => {+ it('should detect the SDK 409 raised when opening the standalone SSE stream', () => {+ const error = new StreamableHTTPError(409, 'Failed to open SSE stream: Conflict');++ expect(isStandaloneSseConflict(error)).toBe(true);+ });++ it('should not match a 409 raised for anything other than the SSE stream', () => {+ const error = new StreamableHTTPError(409, 'Failed to send message');++ expect(isStandaloneSseConflict(error)).toBe(false);+ });++ it('should not match other statuses on the SSE stream', () => {+ const error = new StreamableHTTPError(500, 'Failed to open SSE stream: Internal Server Error');++ expect(isStandaloneSseConflict(error)).toBe(false);+ });++ it('should not match a look-alike error from another transport', () => {+ const error = Object.assign(new Error('Failed to open SSE stream: Conflict'), { code: 409 });++ expect(isStandaloneSseConflict(error)).toBe(false);+ });++ it('should not match non-error values', () => {+ expect(isStandaloneSseConflict(undefined)).toBe(false);+ expect(isStandaloneSseConflict('Conflict')).toBe(false);+ });});/**diff --git a/packages/api/src/mcp/__tests__/MCPConnectionSseConflict.test.ts b/packages/api/src/mcp/__tests__/MCPConnectionSseConflict.test.tsnew file mode 100644index 0000000000..f016fcfee2--- /dev/null+++ b/packages/api/src/mcp/__tests__/MCPConnectionSseConflict.test.ts@@ -0,0 +1,272 @@+/**+ * Integration tests for the `409` a Streamable HTTP server returns when the standalone `GET`+ * SSE stream is already mapped to the session.+ *+ * These drive a real client transport against a real in-process server that reproduces the+ * production sequence: the stream opens, dies at the socket (undici surfaces this as+ * `TypeError: terminated`), and every reconnect then conflicts because the server never+ * observed the disconnect and still holds the previous stream.+ */++import * as net from 'net';+import * as http from 'http';+import { randomUUID } from 'crypto';+import { logger } from '@librechat/data-schemas';+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';+import type { Socket } from 'net';+import { MCPConnection } from '~/mcp/connection';++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),+ isOAuthUrlAllowed: jest.fn(() => false),+ isSSRFTarget: jest.fn(() => false),+ resolveHostnameSSRF: jest.fn(async () => false),+}));++jest.mock('~/mcp/mcpConfig', () => ({+ mcpConfig: {+ CONNECTION_CHECK_TTL: 0,+ TOOLS_LIST_MAX_PAGES: 50,+ TOOLS_LIST_MAX_TOOLS: 1000,+ TOOLS_LIST_MAX_BYTES: 5 * 1024 * 1024,+ TOOLS_LIST_TIMEOUT_MS: 30000,+ },+}));++interface ConflictTestServer {+ url: string;+ getRequests: () => number;+ close: () => Promise<void>;+}++function listenOnEphemeralPort(httpServer: http.Server): Promise<number> {+ return new Promise((resolve) => {+ httpServer.listen(0, '127.0.0.1', () => {+ const addr = httpServer.address() as net.AddressInfo;+ 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());+ });+}++/**+ * Serves `initialize` from a real `StreamableHTTPServerTransport` so the client negotiates a+ * genuine session, then models a server holding a leaked stream. The leak is per-session, as it+ * is in the SDK: the first session's stream has its socket destroyed underneath the client and+ * every later `GET` carrying that session id conflicts, while a rebuilt session gets a healthy+ * stream — so recovery is only possible by replacing the session.+ */+async function createConflictingServer(): Promise<ConflictTestServer> {+ const sessions = new Map<string, StreamableHTTPServerTransport>();+ const streamedSessions = new Set<string>();+ let getRequests = 0;++ const httpServer = http.createServer(async (req, res) => {+ if (req.method === 'GET') {+ getRequests += 1;+ const streamSid = (req.headers['mcp-session-id'] as string | undefined) ?? '';++ if (streamedSessions.has(streamSid)) {+ res.writeHead(409, { 'Content-Type': 'application/json' });+ res.end(+ JSON.stringify({+ jsonrpc: '2.0',+ error: {+ code: -32000,+ message: 'Conflict: Only one SSE stream is allowed per session',+ },+ id: null,+ }),+ );+ return;+ }++ const isFirstStream = streamedSessions.size === 0;+ streamedSessions.add(streamSid);+ res.writeHead(200, {+ 'Content-Type': 'text/event-stream',+ 'Cache-Control': 'no-cache, no-transform',+ });+ res.write(': open\n\n');++ if (isFirstStream) {+ setTimeout(() => req.socket.destroy(), 50);+ }+ return;+ }++ const sid = req.headers['mcp-session-id'] as string | undefined;+ let transport = sid ? sessions.get(sid) : undefined;+ const isNewTransport = !transport;++ if (!transport) {+ transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });+ const mcp = new McpServer({ name: 'test-conflict', version: '0.0.1' });+ await mcp.connect(transport);+ }++ await transport.handleRequest(req, res);++ if (isNewTransport && transport.sessionId) {+ const registeredId = transport.sessionId;+ sessions.set(registeredId, transport);+ transport.onclose = () => sessions.delete(registeredId);+ }+ });++ const destroySockets = trackSockets(httpServer);+ const port = await listenOnEphemeralPort(httpServer);++ return {+ url: `http://127.0.0.1:${port}/`,+ getRequests: () => getRequests,+ close: async () => {+ const closing = [...sessions.values()].map((t) => t.close().catch(() => undefined));+ sessions.clear();+ await Promise.all(closing);+ await destroySockets();+ },+ };+}++async function waitForCondition(+ predicate: () => boolean,+ timeoutMs = 10000,+ intervalMs = 25,+): Promise<void> {+ const deadline = Date.now() + timeoutMs;+ while (!predicate()) {+ if (Date.now() > deadline) {+ throw new Error('Timed out waiting for condition');+ }+ await new Promise((resolve) => setTimeout(resolve, intervalMs));+ }+}++function loggedMessages(mock: jest.Mock): string[] {+ return mock.mock.calls.map((call) => String(call[0]));+}++function countMatching(mock: jest.Mock, needle: string): number {+ return loggedMessages(mock).filter((message) => message.includes(needle)).length;+}++async function safeDisconnect(conn: MCPConnection | null): Promise<void> {+ if (!conn) {+ return;+ }+ (conn as unknown as { shouldStopReconnecting: boolean }).shouldStopReconnecting = true;+ conn.removeAllListeners();+ await conn.disconnect();+}++describe('MCPConnection standalone SSE stream conflict', () => {+ let server: ConflictTestServer | null;+ let conn: MCPConnection | null;++ beforeEach(() => {+ server = null;+ conn = null;+ jest.clearAllMocks();+ });++ afterEach(async () => {+ MCPConnection.clearCooldown('test');+ await safeDisconnect(conn);+ conn = null;+ await server?.close();+ });++ it('escalates the first conflict for rebuild and reports the rest as follow-on noise', async () => {+ const srv = await createConflictingServer();+ server = srv;+ conn = new MCPConnection({+ serverName: 'test',+ serverConfig: { type: 'streamable-http', url: srv.url },+ useSSRFProtection: false,+ });++ const escalations: string[] = [];+ conn.on('connectionChange', (state: string) => {+ if (state === 'error') {+ escalations.push(state);+ }+ });++ await conn.connect();++ /**+ * Let the SDK exhaust its own retry budget without the rebuild closing the transport+ * partway through, so the full sequence of repeat conflicts is observable.+ */+ (conn as unknown as { shouldStopReconnecting: boolean }).shouldStopReconnecting = true;++ const warnMock = logger.warn as jest.Mock;+ const errorMock = logger.error as jest.Mock;+ const debugMock = logger.debug as jest.Mock;++ await waitForCondition(+ () => countMatching(warnMock, 'conflicted with a stale server-side') > 0,+ );+ await waitForCondition(() => srv.getRequests() >= 3);+ await waitForCondition(+ () => countMatching(debugMock, 'SDK reconnection budget exhausted') > 0,+ 10000,+ );++ expect(countMatching(warnMock, 'conflicted with a stale server-side')).toBe(1);+ expect(escalations).toEqual(['error']);++ expect(countMatching(debugMock, 'still conflicting; session rebuild already underway')).toBe(1);+ expect(countMatching(errorMock, 'may require manual intervention')).toBe(0);+ expect(countMatching(errorMock, 'Maximum reconnection attempts')).toBe(0);+ }, 20000);++ it('rebuilds the session so the connection recovers from the conflict', async () => {+ const srv = await createConflictingServer();+ server = srv;+ conn = new MCPConnection({+ serverName: 'test',+ serverConfig: { type: 'streamable-http', url: srv.url },+ useSSRFProtection: false,+ });++ await conn.connect();+ const firstSessionId = (conn as unknown as { transport?: { sessionId?: string } }).transport+ ?.sessionId;+ expect(firstSessionId).toBeTruthy();++ await waitForCondition(() => {+ const current = (conn as unknown as { transport?: { sessionId?: string } }).transport+ ?.sessionId;+ return Boolean(current) && current !== firstSessionId;+ }, 15000);++ expect(await conn.isConnected()).toBe(true);+ }, 25000);+});diff --git a/packages/api/src/mcp/connection.ts b/packages/api/src/mcp/connection.tsindex e186e481f6..54805d95b7 100644--- a/packages/api/src/mcp/connection.ts+++ b/packages/api/src/mcp/connection.ts@@ -23,10 +23,14 @@ import type {import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';import type { MCPOAuthTokens } from './oauth/types';import type * as t from './types';+import {+ extractSSEErrorMessage,+ isOAuthAuthenticationError,+ isStandaloneSseConflict,+} from './errors';import { createSSRFSafeUndiciConnect, isSSRFTarget, resolveHostnameSSRF } from '~/auth';import { reserveMCPToolsChangedRevision } from './toolsChanged';import { isOAuthServer, sanitizeUrlForLogging } from './utils';-import { isOAuthAuthenticationError } from './errors';import { runOutsideTracing } from '~/utils/tracing';import { isAddressAllowed } from '~/auth/domain';import { withTimeout } from '~/utils/promise';@@ -965,6 +969,7 @@ const DEFAULT_SSE_READ_TIMEOUT = FIVE_MINUTES;*/const SDK_SSE_STREAM_DISCONNECTED = 'SSE stream disconnected';const SDK_SSE_RECONNECT_FAILED = 'Failed to reconnect SSE stream';+const SDK_SSE_RETRIES_EXHAUSTED = 'Maximum reconnection attempts';/*** Headers for SSE connections.@@ -980,144 +985,6 @@ const SSE_REQUEST_HEADERS = {'Cache-Control': 'no-cache',};-/**- * Extracts a meaningful error message from SSE transport errors.- * The MCP SDK's SSEClientTransport can produce "SSE error: undefined" when the- * underlying eventsource library encounters connection issues without a specific message.- *- * @returns Object containing:- * - message: Human-readable error description- * - code: HTTP status code if available- * - isProxyHint: Whether this error suggests proxy misconfiguration- * - isTransient: Whether this is likely a transient error that will auto-reconnect- */-function extractSSEErrorMessage(error: unknown): {- message: string;- code?: number;- isProxyHint: boolean;- isTransient: boolean;-} {- if (!error || typeof error !== 'object') {- return {- message: 'Unknown SSE transport error',- isProxyHint: true,- isTransient: true,- };- }-- const errorObj = error as { message?: string; code?: number; event?: unknown };- const rawMessage = errorObj.message ?? '';- const code = errorObj.code;-- /**- * Handle the common "SSE error: undefined" case.- * This typically occurs when:- * 1. A reverse proxy buffers the SSE stream (proxy issue)- * 2. The server closes an idle connection (normal SSE behavior)- * 3. Network interruption without specific error details- *- * In all cases, the eventsource library will attempt to reconnect automatically.- */- if (rawMessage === 'SSE error: undefined' || rawMessage === 'undefined' || !rawMessage) {- return {- message:- 'SSE connection closed. This can occur due to: (1) idle connection timeout (normal), ' +- '(2) reverse proxy buffering (check proxy_buffering config), or (3) network interruption.',- code,- isProxyHint: true,- isTransient: true,- };- }-- /**- * Check for timeout patterns. Use case-insensitive matching for common timeout error codes:- * - ETIMEDOUT: TCP connection timeout- * - ESOCKETTIMEDOUT: Socket timeout- * - "timed out" / "timeout": Generic timeout messages- */- const lowerMessage = rawMessage.toLowerCase();- if (- rawMessage.includes('ETIMEDOUT') ||- rawMessage.includes('ESOCKETTIMEDOUT') ||- lowerMessage.includes('timed out') ||- lowerMessage.includes('timeout after') ||- lowerMessage.includes('request timeout')- ) {- return {- message: `SSE connection timed out: ${rawMessage}. If behind a reverse proxy, increase proxy_read_timeout.`,- code,- isProxyHint: true,- isTransient: true,- };- }-- // Connection reset is often transient (server restart, proxy reload)- if (rawMessage.includes('ECONNRESET')) {- return {- message: `SSE connection reset: ${rawMessage}. The server or proxy may have restarted.`,- code,- isProxyHint: false,- isTransient: true,- };- }-- // Connection refused is more serious - server may be down- if (rawMessage.includes('ECONNREFUSED')) {- return {- message: `SSE connection refused: ${rawMessage}. Verify the MCP server is running and accessible.`,- code,- isProxyHint: false,- isTransient: false,- };- }-- // DNS failure is usually a configuration issue, not transient- if (rawMessage.includes('ENOTFOUND') || rawMessage.includes('getaddrinfo')) {- return {- message: `SSE DNS resolution failed: ${rawMessage}. Check the server URL is correct.`,- code,- isProxyHint: false,- isTransient: false,- };- }-- // Check for HTTP status codes in the message- const statusMatch = rawMessage.match(/\b(4\d{2}|5\d{2})\b/);- if (statusMatch) {- const statusCode = parseInt(statusMatch[1], 10);- // 5xx errors are often transient, 4xx are usually not- const isServerError = statusCode >= 500 && statusCode < 600;- return {- message: rawMessage,- code: statusCode,- isProxyHint: statusCode === 502 || statusCode === 503 || statusCode === 504,- isTransient: isServerError,- };- }-- /**- * "fetch failed" is a generic undici TypeError that occurs when an in-flight HTTP request- * is aborted (e.g. after an MCP protocol-level timeout fires). The transport itself is still- * functional — only the individual request was lost — so treat this as transient.- */- if (rawMessage === 'fetch failed') {- return {- message:- 'fetch failed (request aborted, likely after a timeout — connection may still be usable)',- code,- isProxyHint: false,- isTransient: true,- };- }-- return {- message: rawMessage,- code,- isProxyHint: false,- isTransient: false,- };-}-interface MCPConnectionParams {serverName: string;serverConfig: t.MCPOptions;@@ -1148,6 +1015,8 @@ export class MCPConnection extends EventEmitter {private isReconnecting = false;private isInitializing = false;private reconnectAttempts = 0;+ /** Set once per transport, so only the first of a conflict's repeat reports escalates. */+ private reportedStandaloneSseConflict = false;private agents: Dispatcher[] = [];private readonly userId?: string;private lastPingTime: number;@@ -2264,6 +2133,8 @@ export class MCPConnection extends EventEmitter {}private setupTransportErrorHandlers(transport: Transport): void {+ this.reportedStandaloneSseConflict = false;+transport.onerror = (error) => {const rawMessage =error && typeof error === 'object' ? ((error as { message?: string }).message ?? '') : '';@@ -2285,6 +2156,41 @@ export class MCPConnection extends EventEmitter {return;}+ /**+ * A stale server-side stream can only be cleared by rebuilding the session, so escalate+ * on the first report and treat the rest as the echo they are: the SDK keeps retrying the+ * `GET` on its own schedule, and each of those retries conflicts for the same reason while+ * the rebuild triggered here is already running.+ */+ if (isStandaloneSseConflict(error)) {+ if (this.reportedStandaloneSseConflict) {+ logger.debug(+ `${this.getLogPrefix()} SSE stream still conflicting; session rebuild already underway`,+ );+ return;+ }++ this.reportedStandaloneSseConflict = true;+ logger.warn(+ `${this.getLogPrefix()} SSE stream conflicted with a stale server-side stream for this ` ++ `session (409). Rebuilding the session; no action needed.`,+ );+ this.emit('connectionChange', 'error');+ return;+ }++ /**+ * The SDK announcing it is out of retries normally has to fall through so our reconnection+ * takes over, but adds nothing once a conflict rebuild is already running — that rebuild is+ * what exhausted the retries, and it is the recovery.+ */+ if (this.reportedStandaloneSseConflict && rawMessage.startsWith(SDK_SSE_RETRIES_EXHAUSTED)) {+ logger.debug(+ `${this.getLogPrefix()} SDK reconnection budget exhausted; session rebuild already underway`,+ );+ return;+ }+const {message: errorMessage,code: errorCode,diff --git a/packages/api/src/mcp/errors.ts b/packages/api/src/mcp/errors.tsindex f503e8dbb5..3c356b3bad 100644--- a/packages/api/src/mcp/errors.ts+++ b/packages/api/src/mcp/errors.ts@@ -1,6 +1,7 @@/*** MCP-specific error classes*/+import { StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';export const MCPErrorCodes = {DOMAIN_NOT_ALLOWED: 'MCP_DOMAIN_NOT_ALLOWED',@@ -51,6 +52,180 @@ export function isOAuthAuthenticationError(error: unknown): boolean {);}+/** The SDK's wording when the standalone `GET` SSE stream could not be opened. */+const SDK_SSE_OPEN_FAILED = 'Failed to open SSE stream';++/**+ * A `409` opening the standalone `GET` SSE stream means the server still has the previous+ * stream mapped to our session. The spec allows only one such stream per session, and the+ * server drops its mapping from the response stream's cancel callback — which never runs when+ * the connection dies at a proxy instead of at the client, leaving the server holding a stream+ * no one is reading.+ *+ * Retrying cannot clear it: every `GET` carrying that session id conflicts for the same reason.+ * Only a transport rebuild does, because the teardown `DELETE` drops the server's session along+ * with the stream it leaked.+ */+export function isStandaloneSseConflict(error: unknown): boolean {+ return (+ error instanceof StreamableHTTPError &&+ error.code === 409 &&+ error.message.includes(SDK_SSE_OPEN_FAILED)+ );+}++export interface SSEErrorDetails {+ message: string;+ code?: number;+ isProxyHint: boolean;+ isTransient: boolean;+}++/**+ * Extracts a meaningful error message from SSE transport errors.+ * The MCP SDK's SSEClientTransport can produce "SSE error: undefined" when the+ * underlying eventsource library encounters connection issues without a specific message.+ *+ * @returns Object containing:+ * - message: Human-readable error description+ * - code: HTTP status code if available+ * - isProxyHint: Whether this error suggests proxy misconfiguration+ * - isTransient: Whether this is likely a transient error that will auto-reconnect+ */+export function extractSSEErrorMessage(error: unknown): SSEErrorDetails {+ if (!error || typeof error !== 'object') {+ return {+ message: 'Unknown SSE transport error',+ isProxyHint: true,+ isTransient: true,+ };+ }++ const errorObj = error as { message?: string; code?: number; event?: unknown };+ const rawMessage = errorObj.message ?? '';+ const code = errorObj.code;++ /**+ * Handle the common "SSE error: undefined" case.+ * This typically occurs when:+ * 1. A reverse proxy buffers the SSE stream (proxy issue)+ * 2. The server closes an idle connection (normal SSE behavior)+ * 3. Network interruption without specific error details+ *+ * In all cases, the eventsource library will attempt to reconnect automatically.+ */+ if (rawMessage === 'SSE error: undefined' || rawMessage === 'undefined' || !rawMessage) {+ return {+ message:+ 'SSE connection closed. This can occur due to: (1) idle connection timeout (normal), ' ++ '(2) reverse proxy buffering (check proxy_buffering config), or (3) network interruption.',+ code,+ isProxyHint: true,+ isTransient: true,+ };+ }++ /**+ * Check for timeout patterns. Use case-insensitive matching for common timeout error codes:+ * - ETIMEDOUT: TCP connection timeout+ * - ESOCKETTIMEDOUT: Socket timeout+ * - "timed out" / "timeout": Generic timeout messages+ */+ const lowerMessage = rawMessage.toLowerCase();+ if (+ rawMessage.includes('ETIMEDOUT') ||+ rawMessage.includes('ESOCKETTIMEDOUT') ||+ lowerMessage.includes('timed out') ||+ lowerMessage.includes('timeout after') ||+ lowerMessage.includes('request timeout')+ ) {+ return {+ message: `SSE connection timed out: ${rawMessage}. If behind a reverse proxy, increase proxy_read_timeout.`,+ code,+ isProxyHint: true,+ isTransient: true,+ };+ }++ // Connection reset is often transient (server restart, proxy reload)+ if (rawMessage.includes('ECONNRESET')) {+ return {+ message: `SSE connection reset: ${rawMessage}. The server or proxy may have restarted.`,+ code,+ isProxyHint: false,+ isTransient: true,+ };+ }++ // Connection refused is more serious - server may be down+ if (rawMessage.includes('ECONNREFUSED')) {+ return {+ message: `SSE connection refused: ${rawMessage}. Verify the MCP server is running and accessible.`,+ code,+ isProxyHint: false,+ isTransient: false,+ };+ }++ // DNS failure is usually a configuration issue, not transient+ if (rawMessage.includes('ENOTFOUND') || rawMessage.includes('getaddrinfo')) {+ return {+ message: `SSE DNS resolution failed: ${rawMessage}. Check the server URL is correct.`,+ code,+ isProxyHint: false,+ isTransient: false,+ };+ }++ /**+ * `StreamableHTTPError` and `SseError` carry the status on `code`, and their messages do not+ * always repeat it — "Failed to open SSE stream: Conflict" arrives here with no digits to+ * scan, so reading the message alone classified a 409 as an unrecognized fatal error. Prefer+ * the structured status; keep scanning the message for transports that only stringify it.+ */+ const statusMatch = rawMessage.match(/\b(4\d{2}|5\d{2})\b/);+ const scannedStatus = statusMatch ? parseInt(statusMatch[1], 10) : undefined;+ const carriesHttpStatus = code != null && code >= 400 && code < 600;+ const httpStatus = carriesHttpStatus ? code : scannedStatus;++ if (httpStatus != null) {+ /**+ * 5xx is transient by nature. 409 is transient by recovery: it reports a stale server-side+ * session that the rebuild clears on its own, with nothing for an operator to do. Every+ * other 4xx stays non-transient.+ */+ const isServerError = httpStatus >= 500 && httpStatus < 600;+ return {+ message: rawMessage,+ code: httpStatus,+ isProxyHint: httpStatus === 502 || httpStatus === 503 || httpStatus === 504,+ isTransient: isServerError || httpStatus === 409,+ };+ }++ /**+ * "fetch failed" is a generic undici TypeError that occurs when an in-flight HTTP request+ * is aborted (e.g. after an MCP protocol-level timeout fires). The transport itself is still+ * functional — only the individual request was lost — so treat this as transient.+ */+ if (rawMessage === 'fetch failed') {+ return {+ message:+ 'fetch failed (request aborted, likely after a timeout — connection may still be usable)',+ code,+ isProxyHint: false,+ isTransient: true,+ };+ }++ return {+ message: rawMessage,+ code,+ isProxyHint: false,+ isTransient: false,+ };+}+/*** Custom error for MCP domain restriction violations.* Thrown when a user attempts to connect to an MCP server whose domain is not in the allowlist.