feat(servers): hot-reload server list on external mcp.json edits (#1345)

Watch ~/.mcp-inspector/mcp.json from the backend and push a change event
on a new /api/servers/events SSE channel. The web client subscribes via
fetch + ReadableStream (so the existing bearer-auth contract is
preserved — EventSource can't send custom headers) and re-fetches on
each event. The watcher is lazy: it starts on the first SSE subscriber
and stops when the last one disconnects, so tests that never open the
channel don't spin up a real fs watcher. Self-fires from the backend's
own POST/PUT/DELETE are suppressed by capturing the post-write mtime and
comparing it on each watcher event.

Chokidar is used for cross-platform editor-save semantics (temp-file +
rename produces unlink+add sequences that bare fs.watch handles poorly
on macOS/Linux); awaitWriteFinish coalesces those into a single event.

createRemoteApp now returns a close() to release the watcher, which the
standalone server and the vite dev plugin chain into their existing
close paths.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: cliffhall

clients/web/package-lock.json

@@ -33,6 +33,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ajv": "^8.17.1",
     "atomically": "^2.1.1",
+    "chokidar": "^4.0.3",
     "hono": "^4.12.18",
     "open": "^10.2.0",
     "pino": "^9.14.0",

clients/web/package.json

@@ -45,7 +45,7 @@ export async function startHonoServer(
 
   const rootPath = config.staticRoot ?? __dirname;
 
-  const { app: apiApp } = createRemoteApp({
+  const { app: apiApp, close: closeApi } = createRemoteApp({
     authToken: config.dangerouslyOmitAuth ? undefined : resolvedAuthToken,
     dangerouslyOmitAuth: config.dangerouslyOmitAuth,
     storageDir: config.storageDir,
@@ -117,6 +117,7 @@ export async function startHonoServer(
 
   return {
     async close(): Promise<void> {
+      await closeApi();
       await sandboxController.close();
       if ("closeAllConnections" in httpServer) {
         httpServer.closeAllConnections();

clients/web/server/server.ts

@@ -23,6 +23,11 @@ export function getViteBaseConfig() {
         // keeps Vite's dev-time scanner from chasing it through the plugin's
         // node-only import chain.
         "atomically",
+        // `chokidar` is only loaded inside `core/mcp/remote/node/server.ts`
+        // when the lazy mcp.json watcher starts. It transitively imports
+        // `readdirp` and core node fs/os modules; excluding it keeps Vite's
+        // dep scanner from walking into them during dev startup.
+        "chokidar",
         "cross-spawn",
         "which",
       ],

clients/web/server/vite-base-config.ts

@@ -53,13 +53,11 @@ export function honoMiddlewarePlugin(config: WebServerConfig): Plugin {
       });
       await sandboxController.start();
 
-      const originalClose = server.close.bind(server);
-      server.close = async () => {
-        await sandboxController.close();
-        return originalClose();
-      };
-
-      const { app: honoApp, authToken: resolvedToken } = createRemoteApp({
+      const {
+        app: honoApp,
+        authToken: resolvedToken,
+        close: closeApi,
+      } = createRemoteApp({
         authToken: config.dangerouslyOmitAuth ? undefined : config.authToken,
         dangerouslyOmitAuth: config.dangerouslyOmitAuth,
         storageDir: config.storageDir,
@@ -69,6 +67,15 @@ export function honoMiddlewarePlugin(config: WebServerConfig): Plugin {
         initialConfig: webServerConfigToInitialPayload(config),
       });
 
+      // Chain the API close (mcp.json watcher) and the sandbox into the
+      // Vite server's close so dev-server restarts release both resources.
+      const originalClose = server.close.bind(server);
+      server.close = async () => {
+        await closeApi();
+        await sandboxController.close();
+        return originalClose();
+      };
+
       const sandboxUrl = sandboxController.getUrl();
 
       const logBanner = () => {

clients/web/server/vite-hono-plugin.ts

@@ -19,12 +19,13 @@ interface Harness {
   fetchFn: typeof fetch;
   configPath: string;
   tempDir: string;
+  closeApi: () => Promise<void>;
 }
 
 function setupHarness(): Harness {
   const tempDir = mkdtempSync(join(tmpdir(), "inspector-useServers-"));
   const configPath = join(tempDir, "mcp.json");
-  const { app } = createRemoteApp({
+  const { app, close: closeApi } = createRemoteApp({
     dangerouslyOmitAuth: true,
     mcpConfigPath: configPath,
     initialConfig: { defaultEnvironment: {} },
@@ -38,10 +39,16 @@ function setupHarness(): Harness {
         : new Request(input as string | URL, init);
     return app.fetch(req) as Promise<Response>;
   };
-  return { fetchFn, configPath, tempDir };
+  return { fetchFn, configPath, tempDir, closeApi };
 }
 
-function teardownHarness(h: Harness): void {
+async function teardownHarness(h: Harness): Promise<void> {
+  // Closing here releases the lazy chokidar watcher started by the SSE
+  // subscription useServers opens on mount. Without it the watcher would
+  // hang around for the lifetime of the vitest worker — harmless for the
+  // suite as a whole, but it would slow worker exit and could leak inotify
+  // watches on Linux.
+  await h.closeApi();
   try {
     rmSync(h.tempDir, { recursive: true });
   } catch {
@@ -60,8 +67,8 @@ describe("useServers", () => {
     h = setupHarness();
   });
 
-  afterEach(() => {
-    teardownHarness(h);
+  afterEach(async () => {
+    await teardownHarness(h);
   });
 
   it("starts in loading state, then loads and converts the seed config", async () => {
@@ -218,6 +225,40 @@ describe("useServers", () => {
     expect(result.current.servers.map((s) => s.id)).toEqual(["hand"]);
   });
 
+  it("auto-refreshes when the /api/servers/events SSE channel signals a change", async () => {
+    // Mount the hook (which also opens the SSE subscription) and let the
+    // initial GET settle so we're observing a steady state before mutating
+    // the file.
+    const { result } = renderHook(() =>
+      useServers({ baseUrl: "http://test.local", fetchFn: h.fetchFn }),
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    // Give chokidar a beat to register with the now-seeded file. The lazy
+    // watcher inside createRemoteApp starts on the first SSE subscriber, so
+    // by the time the initial GET resolves the watcher is already attached.
+    // The pause covers any platform-specific scan-stabilization window
+    // before we mutate.
+    await new Promise((r) => setTimeout(r, 200));
+
+    // Simulate an external editor save. The watcher fires → SSE broadcasts
+    // → the hook's reader-loop calls refresh() without us touching the
+    // exposed refresh() API.
+    writeFileSync(
+      h.configPath,
+      JSON.stringify({
+        mcpServers: { external: { type: "stdio", command: "outside" } },
+      }) + "\n",
+    );
+
+    await waitFor(
+      () => {
+        expect(result.current.servers.map((s) => s.id)).toEqual(["external"]);
+      },
+      { timeout: 3000 },
+    );
+  });
+
   it("captures the error message on fetch network failure", async () => {
     const failingFetch = vi
       .fn<typeof fetch>()