Retry failed MCP servers from the MCP list

The list only stores live status. After a persist-then-connect failure the
settings row already exists, so Enter reconnects that config instead of
adding a duplicate name.

Author: TheGreatAxios

src/tui/command-surfaces.test.ts

@@ -782,37 +782,50 @@ describe("mcp surface", () => {
   test("Enter on an unauthorized server opens the browser and copies the link", async () => {
     await withShell((shell) => {
       const opened: string[] = [];
+      const retried: string[] = [];
       openCommandSurface(shell, "mcp", {
         notify: () => {},
-        mcp: { list: () => entries, openAuthURL: (url) => opened.push(url) },
+        mcp: {
+          list: () => entries,
+          openAuthURL: (url) => opened.push(url),
+          retryServer: async (name) => {
+            retried.push(name);
+            return { ok: true, message: "should not retry" };
+          },
+        },
       });
       moveOverlaySelection(shell, 1);
       acceptOverlaySelection(shell);
       expect(opened).toEqual(["https://notion.test/auth"]);
+      expect(retried).toEqual([]);
       expect(shell.statusFlash).toContain("notion");
       // The echo would quote "notion — needs auth" back forever, moments
       // after the operator authorized it.
       expect(shell.streamLog.filter((r) => r.meta === "overlay")).toEqual([]);
     });
   });
 
-  test("Enter on non-auth rows releases the status subscription", async () => {
-    const nonAuthEntries: readonly McpEntry[] = [
+  test("Enter on connecting and connected rows releases the status subscription", async () => {
+    const nonActionEntries: readonly McpEntry[] = [
       { name: "connected", state: "connected", toolCount: 1 },
       { name: "connecting", state: "connecting" },
-      { name: "failed", state: "failed", error: "offline" },
     ];
 
-    for (const entry of nonAuthEntries) {
+    for (const entry of nonActionEntries) {
       await withShell((shell) => {
         const listeners = new Set<() => void>();
         let unsubscribeCalls = 0;
         const opened: string[] = [];
+        const retried: string[] = [];
         openCommandSurface(shell, "mcp", {
           notify: () => {},
           mcp: {
             list: () => [entry],
             openAuthURL: (url) => opened.push(url),
+            retryServer: async (name) => {
+              retried.push(name);
+              return { ok: true, message: "should not retry" };
+            },
             subscribe: (listener) => {
               listeners.add(listener);
               return () => {
@@ -826,12 +839,120 @@ describe("mcp surface", () => {
         expect(listeners.size).toBe(1);
         acceptOverlaySelection(shell);
         expect(opened).toEqual([]);
+        expect(retried).toEqual([]);
         expect(unsubscribeCalls).toBe(1);
         expect(listeners.size).toBe(0);
       });
     }
   });
 
+  test("Enter on a failed server retries connect once without adding again", async () => {
+    await withShell(async (shell) => {
+      const added: { name: string; url: string }[] = [];
+      const retried: string[] = [];
+      const opened: string[] = [];
+      const notes: string[] = [];
+      let liveEntries: readonly McpEntry[] = [
+        { name: "sentry", state: "failed", error: "ECONNREFUSED" },
+      ];
+      openCommandSurface(shell, "mcp", {
+        notify: (note) => notes.push(note),
+        mcp: {
+          list: () => liveEntries,
+          openAuthURL: (url) => opened.push(url),
+          addServer: async (name, url) => {
+            added.push({ name, url });
+            return { ok: true, message: "should not add" };
+          },
+          retryServer: async (name) => {
+            retried.push(name);
+            liveEntries = [{ name, state: "connecting" }];
+            return { ok: true, message: `Retrying ${name}; connecting now.` };
+          },
+        },
+      });
+      acceptOverlaySelection(shell);
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(retried).toEqual(["sentry"]);
+      expect(added).toEqual([]);
+      expect(opened).toEqual([]);
+      expect(notes).toEqual(["Retrying sentry; connecting now."]);
+      expect(shell.overlayItems[0]).toBe("sentry — connecting");
+    });
+  });
+
+  test("Enter on a failed row without retry still releases the status subscription", async () => {
+    await withShell((shell) => {
+      const listeners = new Set<() => void>();
+      let unsubscribeCalls = 0;
+      const added: { name: string; url: string }[] = [];
+      openCommandSurface(shell, "mcp", {
+        notify: () => {},
+        mcp: {
+          list: () => [{ name: "sentry", state: "failed", error: "offline" }],
+          openAuthURL: () => {},
+          addServer: async (name, url) => {
+            added.push({ name, url });
+            return { ok: true, message: "should not add" };
+          },
+          subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+              unsubscribeCalls += 1;
+              listeners.delete(listener);
+            };
+          },
+        },
+      });
+
+      expect(listeners.size).toBe(1);
+      acceptOverlaySelection(shell);
+      expect(added).toEqual([]);
+      expect(unsubscribeCalls).toBe(1);
+      expect(listeners.size).toBe(0);
+    });
+  });
+
+  test("Alt+A of a failed name still persists through addServer", async () => {
+    await withShell(async (shell) => {
+      const added: { name: string; url: string }[] = [];
+      const retried: string[] = [];
+      const notes: string[] = [];
+      openCommandSurface(shell, "mcp", {
+        notify: (note) => notes.push(note),
+        mcp: {
+          list: () => [{ name: "sentry", state: "failed" as const, error: "offline" }],
+          openAuthURL: () => {},
+          addServer: async (name, url) => {
+            added.push({ name, url });
+            return {
+              ok: false,
+              message: `An MCP server named "${name}" already exists or is connecting.`,
+            };
+          },
+          retryServer: async (name) => {
+            retried.push(name);
+            return { ok: true, message: "should not retry" };
+          },
+        },
+      });
+
+      expect(runOverlayAction(shell, altKey("a"))).toBe(true);
+      for (const ch of "sentry") runOverlayAction(shell, charKey(ch));
+      acceptOverlaySelection(shell);
+      for (const ch of "https://sentry.test/mcp") runOverlayAction(shell, charKey(ch));
+      acceptOverlaySelection(shell);
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(added).toEqual([{ name: "sentry", url: "https://sentry.test/mcp" }]);
+      expect(retried).toEqual([]);
+      expect(notes.at(-1)).toContain("already exists");
+    });
+  });
+
   test("Alt+A collects a name and absolute HTTP URL before adding", async () => {
     await withShell(async (shell) => {
       const added: { name: string; url: string }[] = [];

src/tui/command-surfaces.ts

@@ -145,6 +145,8 @@ export interface McpSurfaceDeps {
   readonly openAuthURL: (url: string) => void;
   readonly subscribe?: (listener: () => void) => () => void;
   readonly addServer?: (name: string, url: string) => Promise<PluginActionResult>;
+  /** Reconnect a failed persisted server without writing a second settings row. */
+  readonly retryServer?: (name: string) => Promise<PluginActionResult>;
   readonly mcpServersSource?: "local" | "global" | "none";
 }
 
@@ -958,14 +960,42 @@ function mcpDescription(entry: McpEntry): ItemDescription {
         impact: "Enter opens the authorization page and copies the link.",
       };
     case "failed":
-      return { what: entry.error ?? "Did not connect.", tone: "consequence" };
+      return {
+        what: entry.error ?? "Did not connect.",
+        impact: "Enter retries the existing persisted config without adding a second server.",
+        tone: "consequence",
+      };
   }
 }
 
 function canAddMCPServer(mcp: McpSurfaceDeps): boolean {
   return mcp.mcpServersSource !== "local";
 }
 
+function runMcpSurfaceAction(
+  shell: AppShell,
+  deps: CommandSurfaceDeps,
+  action: Promise<PluginActionResult>,
+  failPrefix: string,
+): void {
+  const continuation = captureOverlayContinuation(shell);
+  void action
+    .then(
+      (result) => {
+        if (!isOverlayContinuationCurrent(shell, continuation)) return;
+        deps.notify(result.message);
+        if (isOverlayContinuationCurrent(shell, continuation)) openMcpSurface(shell, deps);
+      },
+      (err: unknown) => {
+        if (!isOverlayContinuationCurrent(shell, continuation)) return;
+        deps.notify(`${failPrefix}: ${errorText(err)}`);
+      },
+    )
+    .catch(() => {
+      // UI continuation failures must not escape a fire-and-forget command.
+    });
+}
+
 function mcpSurfaceRows(entries: readonly McpEntry[], canAdd: boolean): ResidualCatalogEntry[] {
   const rows: ResidualCatalogEntry[] = entries.map((e) => ({
     id: e.name,
@@ -1000,22 +1030,7 @@ function openAddMcpURLPane(
           deps.notify("Adding MCP servers is not available in this session.");
           return;
         }
-        const continuation = captureOverlayContinuation(shell);
-        void addServer(name, url)
-          .then(
-            (result) => {
-              if (!isOverlayContinuationCurrent(shell, continuation)) return;
-              deps.notify(result.message);
-              if (isOverlayContinuationCurrent(shell, continuation)) openMcpSurface(shell, deps);
-            },
-            (err: unknown) => {
-              if (!isOverlayContinuationCurrent(shell, continuation)) return;
-              deps.notify(`Add failed: ${errorText(err)}`);
-            },
-          )
-          .catch(() => {
-            // UI continuation failures must not escape a fire-and-forget command.
-          });
+        runMcpSurfaceAction(shell, deps, addServer(name, url), "Add failed");
       },
     },
     buffer,
@@ -1047,7 +1062,7 @@ function openAddMcpNamePane(
   );
 }
 
-/** Configured MCP servers and their live state; Enter authorizes an unauthorized one. */
+/** Configured MCP servers and their live state; Enter authorizes or retries. */
 export function openMcpSurface(
   shell: AppShell,
   deps: CommandSurfaceDeps,
@@ -1090,8 +1105,15 @@ export function openMcpSurface(
         return;
       }
       const target = byName.get(id);
-      const url = target?.authURL;
-      if (target === undefined || target.state !== "needs-auth" || url === undefined) return;
+      if (target === undefined) return;
+      if (target.state === "failed") {
+        const retryServer = mcp.retryServer;
+        if (retryServer === undefined) return;
+        runMcpSurfaceAction(shell, deps, retryServer(target.name), "Retry failed");
+        return;
+      }
+      const url = target.authURL;
+      if (target.state !== "needs-auth" || url === undefined) return;
       mcp.openAuthURL(url);
       // The copy is the fallback that makes this work over SSH, where the
       // browser that must receive the redirect is not on this machine.

src/tui/runner.ts

@@ -43,6 +43,7 @@ import {
   type Settings,
   type LocalSettings,
   type PluginConfig,
+  type MCPServerConfig,
 } from "../config/settings.js";
 import { addProviderSelectorChoices, providerChoices } from "./provider-setup.js";
 import { persistConnectedSelection } from "./provider-setup-submit.js";
@@ -2233,6 +2234,23 @@ export async function runTUI(initialConfig: Config): Promise<number> {
         directorHolder.instance?.updateToolDefinitions(computeAdvertised(definitions)),
     };
 
+    const connectLateMCPServer = (server: MCPServerConfig): void => {
+      void toolset
+        .connectMCPServer(server, mcpConnectCallbacks, mcpConnectController.signal)
+        .catch((err: unknown) => {
+          if (err instanceof Error && err.name === "AbortError") return;
+          tuiLogger.error("Late MCP connect failed: {error}", {
+            error: err instanceof Error ? err.message : String(err),
+          });
+        });
+    };
+
+    const persistedMCPServer = (name: string): MCPServerConfig | undefined =>
+      (config.mcpServers ?? []).find((server) => server.name === name) ??
+      (config.settings?.mcpServers ?? []).find(
+        (server): server is MCPServerConfig => server.name === name && !("enabled" in server),
+      );
+
     const host = await mountRunnerHost({
       // An unnamed session shows nothing rather than a placeholder.
       title: runTaskTitle,
@@ -2560,17 +2578,28 @@ export async function runTUI(initialConfig: Config): Promise<number> {
                         : "Enter an absolute HTTP(S) URL first.";
               return { ok: false, message };
             }
-            config = { ...config, settings: result.settings };
-            void toolset
-              .connectMCPServer(result.server, mcpConnectCallbacks, mcpConnectController.signal)
-              .catch((err: unknown) => {
-                if (err instanceof Error && err.name === "AbortError") return;
-                tuiLogger.error("Late MCP connect failed: {error}", {
-                  error: err instanceof Error ? err.message : String(err),
-                });
-              });
+            config = {
+              ...config,
+              settings: result.settings,
+              mcpServers: [
+                ...(config.mcpServers ?? []).filter((server) => server.name !== result.server.name),
+                result.server,
+              ],
+            };
+            connectLateMCPServer(result.server);
             return { ok: true, message: `Added ${result.server.name}; connecting now.` };
           },
+          retryServer: async (name) => {
+            const server = persistedMCPServer(name);
+            if (server === undefined) {
+              return {
+                ok: false,
+                message: `No persisted MCP server named "${name}" to retry.`,
+              };
+            }
+            connectLateMCPServer(server);
+            return { ok: true, message: `Retrying ${server.name}; connecting now.` };
+          },
         },
         hooks: {
           list: () =>