feat(web): recover from mid-turn MCP connector auth failures in chat

When a connector tool call fails with a reconnectable auth error, the agent
ends tool use for the response, summarizes completed work, and the failed
tool result offers inline Reconnect and Continue actions that reuse the
existing OAuth flow and return to the exact thread.

Author: jsourcebot

packages/web/src/ee/features/chat/agent.ts

@@ -26,6 +26,12 @@ import { addLineNumbers, fileReferenceToString, formatAttachmentsForPrompt, getA
 import { createTools } from "./tools";
 import { getConnectedMcpClients } from "@/ee/features/chat/mcp/mcpClientFactory";
 import { getMcpTools, McpToolsResult } from "@/ee/features/chat/mcp/mcpToolSets";
+import {
+    createMcpAuthInterruptionDirective,
+    denyApprovedToolApprovalsForAuthInterruption,
+    getMcpAuthRequiredFailureFromAssistantMessage,
+    McpToolAuthFailure,
+} from "@/ee/features/chat/mcp/mcpAuthFailure";
 import { buildMcpToolRegistry, McpToolRegistryEntry } from "@/ee/features/chat/mcp/mcpToolRegistry";
 import { PromptCacheStrategy, mergeProviderOptions, detectPromptCacheBreak, detectUnexpectedCacheMiss } from "./promptCaching";
 import { hasEntitlement } from '@/lib/entitlements';
@@ -332,9 +338,21 @@ export const createMessageStream = async ({
         ? (lastMsg.metadata as SBChatMessageMetadata | undefined)
         : undefined;
 
+    // When the response was interrupted by a reconnect-required authentication
+    // failure (detected via the safe tool error's marker text), the
+    // continuation must run its final step with tool use disabled. Any
+    // approval that was still approved is rewritten to a denial: once the
+    // response is authentication-terminal, later approval actions are invalid.
+    const priorMcpAuthFailure = hasApprovalContinuationReady
+        ? getMcpAuthRequiredFailureFromAssistantMessage(lastMsg)
+        : undefined;
+
     if (hasApprovalContinuationReady) {
+        const continuationMessage = priorMcpAuthFailure
+            ? denyApprovedToolApprovalsForAuthInterruption(lastMsg, priorMcpAuthFailure.serverName)
+            : lastMsg;
         const fullLastTurn = await convertToModelMessages(
-            [lastMsg],
+            [continuationMessage],
             { ignoreIncompleteToolCalls: true }
         );
         messageHistory = [...messageHistory, ...fullLastTurn];
@@ -381,6 +399,16 @@ export const createMessageStream = async ({
                         data: { serverName },
                     });
                 },
+                onMcpAuthRequired: (failure) => {
+                    // Transient: consumed live by the client to surface the
+                    // inline reconnect UI, never folded into persisted parts.
+                    writer.write({
+                        type: 'data-mcp-auth-required',
+                        data: failure,
+                        transient: true,
+                    });
+                },
+                priorMcpAuthFailure,
                 traceId,
                 chatId,
                 prisma,
@@ -509,6 +537,13 @@ interface AgentOptions {
     onMcpServerDiscovered: (sanitizedName: string, faviconUrl: string) => void;
     onMcpToolDiscovered: (modelToolName: string, rawToolName: string) => void;
     onMcpServerFailed: (serverName: string) => void;
+    // Fired at most once per connector per response when a tool call fails
+    // with a reconnect-required authentication failure.
+    onMcpAuthRequired: (failure: McpToolAuthFailure) => void;
+    // Set when the incoming messages show this response was already
+    // interrupted by an authentication failure (approval continuation): the
+    // stream must run its final step with tool use disabled from step one.
+    priorMcpAuthFailure?: { serverName: string };
     traceId: string;
     chatId: string;
     prisma: PrismaClient;
@@ -529,6 +564,8 @@ const createAgentStream = async ({
     onMcpServerDiscovered,
     onMcpToolDiscovered,
     onMcpServerFailed,
+    onMcpAuthRequired,
+    priorMcpAuthFailure,
     traceId,
     chatId,
     prisma,
@@ -564,6 +601,15 @@ const createAgentStream = async ({
         }))
     ).filter((source) => source !== undefined);
 
+    // Mutable, response-scoped authentication failure state. `serverName` is
+    // the first failed connector's display name (V1 supports recovery for a
+    // single failed connector). Failures are deduplicated by connector so the
+    // client sees at most one transient event per connector per response.
+    const mcpAuthFailureState: { failure?: { serverName: string } } = {
+        ...(priorMcpAuthFailure ? { failure: { serverName: priorMcpAuthFailure.serverName } } : {}),
+    };
+    const reportedMcpAuthFailureServerIds = new Set<string>();
+
     let mcpToolSetsObj: McpToolsResult = { tools: {}, failedServers: [], serverFaviconUrls: {}, toolDisplayNames: {}, cleanup: async () => {} };
     if (userId && orgId && await hasEntitlement('ask') && disabledMcpServerIds !== undefined) {
         try {
@@ -573,6 +619,16 @@ const createAgentStream = async ({
                 chatId,
                 traceId,
                 source: 'sourcebot-ask-agent',
+            }, {
+                onAuthFailure: (failure) => {
+                    if (!mcpAuthFailureState.failure) {
+                        mcpAuthFailureState.failure = { serverName: failure.serverName };
+                    }
+                    if (!reportedMcpAuthFailureServerIds.has(failure.serverId)) {
+                        reportedMcpAuthFailureServerIds.add(failure.serverId);
+                        onMcpAuthRequired(failure);
+                    }
+                },
             });
 
             for (const [sanitizedName, faviconUrl] of Object.entries(mcpToolSetsObj.serverFaviconUrls)) {
@@ -715,14 +771,34 @@ const createAgentStream = async ({
             // rebuilds the step's messages each time as the original input plus
             // its own accumulated response messages. Re-applying the moving tail marker
             // to the new last message each step is safe and does not accumulate.
-            prepareStep: (tailMarker || hasMcpTools) ? ({ steps, messages }) => {
+            prepareStep: (tailMarker || hasMcpTools || mcpAuthFailureState.failure) ? ({ steps, messages }) => {
                 const stepMessages = (tailMarker && messages.length > 0)
                     ? messages.map((message, index) =>
                         index === messages.length - 1
                             ? { ...message, providerOptions: mergeProviderOptions(message.providerOptions, tailMarker) }
                             : message)
                     : undefined;
 
+                // Once a reconnect-required authentication failure occurs, the
+                // response is terminal for tool use: every remaining step runs
+                // with tool calling disabled (`toolChoice: 'none'` keeps the
+                // tool definitions byte-stable for prompt caching) plus an
+                // ephemeral directive to summarize completed work and prompt
+                // the user to reconnect. In-flight tool calls of the failing
+                // step have already run to completion by the time this fires.
+                if (mcpAuthFailureState.failure) {
+                    return {
+                        messages: [
+                            ...(stepMessages ?? messages),
+                            {
+                                role: 'user' as const,
+                                content: createMcpAuthInterruptionDirective(mcpAuthFailureState.failure.serverName),
+                            },
+                        ],
+                        toolChoice: 'none' as const,
+                    };
+                }
+
                 if (!hasMcpTools) {
                     return stepMessages ? { messages: stepMessages } : {};
                 }

packages/web/src/ee/features/chat/components/chatThread/chatThread.tsx

@@ -29,6 +29,8 @@ import { generateAndUpdateChatNameFromMessage } from '@/ee/features/chat/actions
 import { isServiceError } from '@/lib/utils';
 import { NotConfiguredErrorBanner } from '@/features/chat/components/notConfiguredErrorBanner';
 import { McpServerIconContext, McpServerIconMap, McpToolNameContext, McpToolNameMap } from '../../mcpDisplayMetadataContext';
+import { McpReconnectContext } from '../../mcpReconnectContext';
+import { McpAuthRequiredData, useMcpReconnectController } from './useMcpReconnectController';
 import { ToolApprovalProvider } from '../../toolApprovalContext';
 import useCaptureEvent from '@/hooks/useCaptureEvent';
 import { SignInPromptBanner } from './signInPromptBanner';
@@ -153,6 +155,11 @@ export const ChatThread = ({
         disabledMcpServerIds: disabledMcpRef.current,
     }), []);
 
+    // The reconnect controller is created after useChat (it needs the chat's
+    // messages and status), so transient auth-required events received in
+    // onData are forwarded to it through a ref.
+    const onMcpAuthRequiredRef = useRef<((data: McpAuthRequiredData) => void) | null>(null);
+
     // Transport with dynamic body, resolved on every request, including auto-resends
     // triggered by sendAutomaticallyWhen after tool approval.
     // eslint-disable-next-line react-hooks/refs -- DefaultChatTransport stores the body callback and invokes it during requests, not during render.
@@ -203,6 +210,9 @@ export const ChatThread = ({
                 });
                 setIsFailedMcpBannerVisible(true);
             }
+            if (dataPart.type === 'data-mcp-auth-required') {
+                onMcpAuthRequiredRef.current?.(dataPart.data);
+            }
         }
     });
 
@@ -276,6 +286,23 @@ export const ChatThread = ({
         confirm: () => window.confirm("You have unsaved changes that will be lost."),
     });
 
+    const {
+        contextValue: mcpReconnectContextValue,
+        onAuthRequired: onMcpAuthRequired,
+    } = useMcpReconnectController({
+        status,
+        messages,
+        isTurnInProgress,
+        addToolApprovalResponse,
+        sendMessage,
+        selectedSearchScopes,
+        disabledMcpServerIds,
+    });
+
+    useEffect(() => {
+        onMcpAuthRequiredRef.current = onMcpAuthRequired;
+    }, [onMcpAuthRequired]);
+
     // When the chat is finished, refresh the page to update the chat history.
     const prevStatus = usePrevious(status);
     useEffect(() => {
@@ -395,6 +422,7 @@ export const ChatThread = ({
 
     return (
         <ToolApprovalProvider value={addToolApprovalResponse}>
+        <McpReconnectContext.Provider value={mcpReconnectContextValue}>
         <McpServerIconContext.Provider value={mcpServerIconMap}>
         <McpToolNameContext.Provider value={mcpToolNameMap}>
         <ChatPaneDropzone
@@ -547,6 +575,7 @@ export const ChatThread = ({
         </ChatPaneDropzone>
         </McpToolNameContext.Provider>
         </McpServerIconContext.Provider>
+        </McpReconnectContext.Provider>
         </ToolApprovalProvider>
     );
 }

packages/web/src/ee/features/chat/components/chatThread/detailsCard.tsx

@@ -548,6 +548,7 @@ export const StepPartRenderer = ({ part, toolTokenUsageMap }: { part: SBChatMess
         case 'data-mcp-server':
         case 'data-mcp-tool':
         case 'data-mcp-failed-server':
+        case 'data-mcp-auth-required':
         case 'data-attachment':
         case 'file':
         case 'source-document':

packages/web/src/ee/features/chat/components/chatThread/tools/mcpToolComponent.test.tsx

@@ -1,9 +1,14 @@
-import { render, screen } from '@testing-library/react';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
 import type { DynamicToolUIPart } from 'ai';
-import { describe, expect, test } from 'vitest';
+import { afterEach, describe, expect, test, vi } from 'vitest';
 import { McpToolNameContext } from '@/ee/features/chat/mcpDisplayMetadataContext';
+import { McpReconnectContext, McpReconnectContextValue, McpReconnectState } from '@/ee/features/chat/mcpReconnectContext';
 import { getMcpToolDisplayParts, McpToolComponent } from './mcpToolComponent';
 
+// React Testing Library's automatic cleanup relies on vitest globals, which
+// this project does not enable.
+afterEach(cleanup);
+
 describe('getMcpToolDisplayParts', () => {
     test('maps provider-safe MCP tool names back to raw tool names for display', () => {
         expect(getMcpToolDisplayParts(
@@ -50,3 +55,145 @@ describe('McpToolComponent', () => {
         expect(screen.queryByText('backstage: catalog_query-catalog-entities')).toBeNull();
     });
 });
+
+const createErrorPart = (toolCallId = 'tool-call-1'): DynamicToolUIPart => ({
+    type: 'dynamic-tool',
+    toolName: 'mcp_linear__list_issues',
+    toolCallId,
+    state: 'output-error',
+    input: { query: 'open issues' },
+    errorText: 'Authentication required: the connection to "Linear" is no longer authorized.',
+} as DynamicToolUIPart);
+
+const createReconnectContext = (
+    state: McpReconnectState,
+    overrides: Partial<McpReconnectContextValue> = {},
+): McpReconnectContextValue => ({
+    reconnectStates: { [state.serverId]: state },
+    isReconnectAllowed: true,
+    isContinueAllowed: false,
+    reconnect: vi.fn(),
+    continueAfterReconnect: vi.fn(),
+    ...overrides,
+});
+
+const createReconnectState = (overrides: Partial<McpReconnectState> = {}): McpReconnectState => ({
+    serverId: 'server-1',
+    serverName: 'Linear',
+    toolCallId: 'tool-call-1',
+    status: 'authentication-required',
+    ...overrides,
+});
+
+describe('McpToolComponent reconnect recovery UI', () => {
+    test('shows the concise reconnect message and an enabled Reconnect action once the response settles', () => {
+        const contextValue = createReconnectContext(createReconnectState());
+
+        render(
+            <McpReconnectContext.Provider value={contextValue}>
+                <McpToolComponent part={createErrorPart()} />
+            </McpReconnectContext.Provider>
+        );
+
+        expect(screen.getByText('Linear needs to be reconnected.')).toBeTruthy();
+        const button = screen.getByRole('button', { name: 'Reconnect Linear' }) as HTMLButtonElement;
+        expect(button.disabled).toBe(false);
+
+        fireEvent.click(button);
+        expect(contextValue.reconnect).toHaveBeenCalledWith('server-1');
+    });
+
+    test('keeps Reconnect disabled while the assistant response has not settled', () => {
+        const contextValue = createReconnectContext(createReconnectState(), { isReconnectAllowed: false });
+
+        render(
+            <McpReconnectContext.Provider value={contextValue}>
+                <McpToolComponent part={createErrorPart()} />
+            </McpReconnectContext.Provider>
+        );
+
+        const button = screen.getByRole('button', { name: 'Reconnect Linear' }) as HTMLButtonElement;
+        expect(button.disabled).toBe(true);
+    });
+
+    test('shows a loading state while OAuth is starting', () => {
+        const contextValue = createReconnectContext(createReconnectState({ status: 'reconnecting' }));
+
+        render(
+            <McpReconnectContext.Provider value={contextValue}>
+                <McpToolComponent part={createErrorPart()} />
+            </McpReconnectContext.Provider>
+        );
+
+        const button = screen.getByRole('button', { name: /Reconnecting/ }) as HTMLButtonElement;
+        expect(button.disabled).toBe(true);
+    });
+
+    test('shows Reconnected and Continue after a successful reconnect', () => {
+        const contextValue = createReconnectContext(
+            createReconnectState({ status: 'reconnected' }),
+            { isContinueAllowed: true },
+        );
+
+        render(
+            <McpReconnectContext.Provider value={contextValue}>
+                <McpToolComponent part={createErrorPart()} />
+            </McpReconnectContext.Provider>
+        );
+
+        expect(screen.getByText('Reconnected')).toBeTruthy();
+        const button = screen.getByRole('button', { name: 'Continue' });
+        fireEvent.click(button);
+        expect(contextValue.continueAfterReconnect).toHaveBeenCalledWith('server-1');
+    });
+
+    test('hides Continue when it is not allowed (e.g. multiple failed connectors)', () => {
+        const contextValue = createReconnectContext(
+            createReconnectState({ status: 'reconnected' }),
+            { isContinueAllowed: false },
+        );
+
+        render(
+            <McpReconnectContext.Provider value={contextValue}>
+                <McpToolComponent part={createErrorPart()} />
+            </McpReconnectContext.Provider>
+        );
+
+        expect(screen.getByText('Reconnected')).toBeTruthy();
+        expect(screen.queryByRole('button', { name: 'Continue' })).toBeNull();
+    });
+
+    test('keeps the technical error inside the expandable details section', () => {
+        const contextValue = createReconnectContext(createReconnectState());
+
+        render(
+            <McpReconnectContext.Provider value={contextValue}>
+                <McpToolComponent part={createErrorPart()} />
+            </McpReconnectContext.Provider>
+        );
+
+        expect(screen.queryByText(/is no longer authorized/)).toBeNull();
+        fireEvent.click(screen.getByText('Details'));
+        expect(screen.getByText(/is no longer authorized/)).toBeTruthy();
+    });
+
+    test('only decorates the tool result whose call failed authentication', () => {
+        const contextValue = createReconnectContext(createReconnectState());
+
+        render(
+            <McpReconnectContext.Provider value={contextValue}>
+                <McpToolComponent part={createErrorPart('tool-call-other')} />
+            </McpReconnectContext.Provider>
+        );
+
+        expect(screen.queryByText('Linear needs to be reconnected.')).toBeNull();
+        expect(screen.queryByRole('button', { name: 'Reconnect Linear' })).toBeNull();
+    });
+
+    test('falls back to the plain error rendering without a reconnect provider', () => {
+        render(<McpToolComponent part={createErrorPart()} />);
+
+        expect(screen.queryByText('Linear needs to be reconnected.')).toBeNull();
+        expect(screen.getByText(/failed:/)).toBeTruthy();
+    });
+});