From 4379d17f7627c08e2cf6ff96f6d9f261dc54e193 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 09:21:46 -0400
Subject: [PATCH 01/35] fix(web): surface a failed post-write server-list
 reload
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`useServers`' mutators awaited `refresh()`, whose failure was swallowed
into the hook's `error` state rather than thrown. `ServerConfigModal`
renders `submitError` only for something `onSubmit` threw, so a
successful `POST /api/servers` followed by a failed `GET /api/servers`
closed the Add Server modal as though the whole thing had worked — no
inline error, no toast, and no new row, since the list read is what
would have produced it. That is the silent failure reported in #1914;
#1848 removed the trigger (a keyring-less container 500'ing the list
read) but not the swallow, so any other cause reproduces it.

Split the list read into `loadServers` and give the mutators their own
`refreshAfterWrite`, which records the failure in `error` as before and
then rethrows. `refreshInternal` is unchanged for the mount effect and
the SSE loop — neither has anywhere to put a rejection.

The thrown message says the write landed, because it did; only reading
the list back failed. A bare "could not add server" would send the user
straight into a retry that trips the duplicate-id check, which is the
dead end the original report described.

Every consumer of these mutators already handles a rejection:
ServerConfigModal and ServerRemoveConfirmModal into an inline error,
useSettingsDraft and the pagination toggle into a toast, and both
import flows into their per-entry outcome list.

Closes #1914

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UL9retfvAXRgvi6EWk4SY4
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../src/test/core/react/useServers.test.tsx   | 151 ++++++++++++++++++
 core/react/useServers.ts                      |  77 ++++++---
 2 files changed, 210 insertions(+), 18 deletions(-)

diff --git a/clients/web/src/test/core/react/useServers.test.tsx b/clients/web/src/test/core/react/useServers.test.tsx
index c0d5260c..0c011109 100644
--- a/clients/web/src/test/core/react/useServers.test.tsx
+++ b/clients/web/src/test/core/react/useServers.test.tsx
@@ -1199,6 +1199,157 @@ describe("useServers", () => {
     }
   });
 
+  /**
+   * #1914 — a write that lands but whose list reload fails must reject.
+   *
+   * `ServerConfigModal` renders `submitError` only for something `onSubmit`
+   * threw, so while the post-write refresh swallowed its failure into the
+   * `error` state the Add Server modal closed as though nothing had gone
+   * wrong. That is the "silent failure" in the report: the POST succeeded,
+   * the GET 500'd, and the user saw neither the new row nor an error.
+   *
+   * `failGetAfterWrite` lets the seed load and the write itself through, then
+   * fails every subsequent list read — the shape a container with no
+   * reachable keychain produced before #1848.
+   */
+  function failGetAfterWrite(message: string): {
+    fetchFn: typeof fetch;
+    startFailing: () => void;
+  } {
+    let failing = false;
+    const fetchFn: typeof fetch = async (input, init) => {
+      const req =
+        input instanceof Request
+          ? input
+          : new Request(input as string | URL, init);
+      if (failing && req.method === "GET" && req.url.endsWith("/api/servers")) {
+        return new Response(JSON.stringify({ error: message }), {
+          status: 500,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+      return h.fetchFn(req);
+    };
+    return {
+      fetchFn,
+      startFailing: () => {
+        failing = true;
+      },
+    };
+  }
+
+  it("addServer rejects when the post-write list reload fails (#1914)", async () => {
+    const { fetchFn, startFailing } = failGetAfterWrite("keyring unavailable");
+    const { result } = renderHook(() =>
+      useServers({ baseUrl: "http://test.local", fetchFn }),
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    startFailing();
+    await act(async () => {
+      await expect(
+        result.current.addServer("alpha", { type: "stdio", command: "node" }),
+      ).rejects.toThrow(
+        /The server was added, but the server list could not be reloaded: keyring unavailable/,
+      );
+    });
+
+    // The write itself landed, and the message says so — a bare failure would
+    // send the user into a retry that trips the duplicate-id check.
+    expect(readConfig(h.configPath).mcpServers.alpha).toEqual({
+      type: "stdio",
+      command: "node",
+    });
+    // Still recorded in `error` for any list-level UI reading it.
+    await waitFor(() =>
+      expect(result.current.error).toBe("keyring unavailable"),
+    );
+    expect(result.current.loading).toBe(false);
+  });
+
+  it("updateServer rejects when the post-write list reload fails (#1914)", async () => {
+    const { fetchFn, startFailing } = failGetAfterWrite("disk full");
+    const { result } = renderHook(() =>
+      useServers({ baseUrl: "http://test.local", fetchFn }),
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    const existing = result.current.servers[0]!.id;
+
+    startFailing();
+    await act(async () => {
+      await expect(
+        result.current.updateServer(existing, existing, {
+          type: "stdio",
+          command: "node",
+        }),
+      ).rejects.toThrow(
+        /The server was saved, but the server list could not be reloaded: disk full/,
+      );
+    });
+  });
+
+  it("updateServerSettings rejects when the post-write list reload fails (#1914)", async () => {
+    const { fetchFn, startFailing } = failGetAfterWrite("disk full");
+    const { result } = renderHook(() =>
+      useServers({ baseUrl: "http://test.local", fetchFn }),
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    const existing = result.current.servers[0]!.id;
+
+    startFailing();
+    await act(async () => {
+      await expect(
+        result.current.updateServerSettings(existing, {
+          headers: [],
+          env: [],
+          metadata: [],
+          roots: [],
+          connectionTimeout: 5000,
+          requestTimeout: 30000,
+          taskTtl: 30000,
+          maxFetchRequests: 1000,
+          paginatedLists: true,
+        }),
+      ).rejects.toThrow(
+        /The server was saved, but the server list could not be reloaded: disk full/,
+      );
+    });
+  });
+
+  it("removeServer rejects when the post-write list reload fails (#1914)", async () => {
+    const { fetchFn, startFailing } = failGetAfterWrite("disk full");
+    const { result } = renderHook(() =>
+      useServers({ baseUrl: "http://test.local", fetchFn }),
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    const existing = result.current.servers[0]!.id;
+
+    startFailing();
+    await act(async () => {
+      await expect(result.current.removeServer(existing)).rejects.toThrow(
+        /The server was removed, but the server list could not be reloaded: disk full/,
+      );
+    });
+    expect(readConfig(h.configPath).mcpServers[existing]).toBeUndefined();
+  });
+
+  it("a plain refresh() still resolves on a failed list read, recording the error (#1914)", async () => {
+    // The rethrow is scoped to post-write reloads. `refresh()` is awaited by
+    // the mount effect and the SSE loop, neither of which has anywhere to put
+    // a rejection, so it must keep swallowing into `error`.
+    const { fetchFn, startFailing } = failGetAfterWrite("keyring unavailable");
+    const { result } = renderHook(() =>
+      useServers({ baseUrl: "http://test.local", fetchFn }),
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    startFailing();
+    await act(async () => {
+      await expect(result.current.refresh()).resolves.toBeUndefined();
+    });
+    expect(result.current.error).toBe("keyring unavailable");
+  });
+
   it("uses DEFAULT_SEED_CONFIG keys on the first load (seed-write contract)", async () => {
     const { result } = renderHook(() =>
       useServers({ baseUrl: "http://test.local", fetchFn: h.fetchFn }),
diff --git a/core/react/useServers.ts b/core/react/useServers.ts
index c9713344..bcba4690 100644
--- a/core/react/useServers.ts
+++ b/core/react/useServers.ts
@@ -132,33 +132,74 @@ export function useServers(opts: UseServersOptions): UseServersResult {
   const [loading, setLoading] = useState<boolean>(true);
   const [error, setError] = useState<string | undefined>(undefined);
 
+  // The list read itself, throwing on failure. Every refresh path goes
+  // through it; they differ only in what they do with a rejection.
+  const loadServers = useCallback(async (): Promise<ServerEntry[]> => {
+    const res = await doFetch(`${base}/api/servers`, {
+      method: "GET",
+      headers: buildHeaders(authToken, false),
+    });
+    if (!res.ok) {
+      throw new Error(await readErrorMessage(res));
+    }
+    const body = (await res.json()) as MCPConfig;
+    return mcpConfigToServerEntries(body);
+  }, [base, authToken, doFetch]);
+
   // Inner refresh that the public `refresh` and the SSE-triggered background
   // refresh both share. `background` skips the loading-state toggle so
   // consumers rendering a spinner or skeleton don't flash on every external
   // mcp.json edit — the existing list stays on screen while the re-fetch
   // resolves. `error` is still reset / set either way so a real error
   // surfaces even from a background refresh.
+  //
+  // A failure is recorded in `error` and NOT rethrown: the two callers are
+  // the mount effect and the SSE loop, neither of which has anywhere to put
+  // a rejection. Post-write reloads use `refreshAfterWrite` instead.
   const refreshInternal = useCallback(
     async (background: boolean): Promise<void> => {
       if (!background) setLoading(true);
       setError(undefined);
       try {
-        const res = await doFetch(`${base}/api/servers`, {
-          method: "GET",
-          headers: buildHeaders(authToken, false),
-        });
-        if (!res.ok) {
-          throw new Error(await readErrorMessage(res));
-        }
-        const body = (await res.json()) as MCPConfig;
-        setServers(mcpConfigToServerEntries(body));
+        setServers(await loadServers());
       } catch (err) {
         setError(err instanceof Error ? err.message : String(err));
       } finally {
         if (!background) setLoading(false);
       }
     },
-    [base, authToken, doFetch],
+    [loadServers],
+  );
+
+  // Post-write reload, used by every mutator. Unlike `refreshInternal` it
+  // rethrows, because a mutator's caller learns that something went wrong
+  // only from a rejection — `ServerConfigModal` renders `submitError` for a
+  // thrown error and nothing else, so a successful POST followed by a failed
+  // GET closed the Add Server modal as though the whole thing had worked
+  // (#1914). The reported failure was silent for exactly this reason.
+  //
+  // The message says the write landed, because it did: only reading the list
+  // back failed. A bare "could not add server" would send the user straight
+  // into a retry that trips the duplicate-id check, which is the dead end the
+  // original report described.
+  const refreshAfterWrite = useCallback(
+    async (verb: string): Promise<void> => {
+      setLoading(true);
+      setError(undefined);
+      try {
+        setServers(await loadServers());
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        setError(message);
+        throw new Error(
+          `The server was ${verb}, but the server list could not be reloaded: ${message}`,
+          { cause: err },
+        );
+      } finally {
+        setLoading(false);
+      }
+    },
+    [loadServers],
   );
 
   const refresh = useCallback(
@@ -241,9 +282,9 @@ export function useServers(opts: UseServersOptions): UseServersResult {
       if (!res.ok) {
         throw new Error(await readErrorMessage(res));
       }
-      await refresh();
+      await refreshAfterWrite("added");
     },
-    [base, authToken, doFetch, refresh],
+    [base, authToken, doFetch, refreshAfterWrite],
   );
 
   const importSource = useCallback(
@@ -282,9 +323,9 @@ export function useServers(opts: UseServersOptions): UseServersResult {
       if (!res.ok) {
         throw new Error(await readErrorMessage(res));
       }
-      await refresh();
+      await refreshAfterWrite("saved");
     },
-    [base, authToken, doFetch, refresh],
+    [base, authToken, doFetch, refreshAfterWrite],
   );
 
   const updateServerSettings = useCallback(
@@ -307,9 +348,9 @@ export function useServers(opts: UseServersOptions): UseServersResult {
       if (!res.ok) {
         throw new Error(await readErrorMessage(res));
       }
-      await refresh();
+      await refreshAfterWrite("saved");
     },
-    [base, authToken, doFetch, refresh],
+    [base, authToken, doFetch, refreshAfterWrite],
   );
 
   const removeServer = useCallback(
@@ -324,9 +365,9 @@ export function useServers(opts: UseServersOptions): UseServersResult {
       if (!res.ok) {
         throw new Error(await readErrorMessage(res));
       }
-      await refresh();
+      await refreshAfterWrite("removed");
     },
-    [base, authToken, doFetch, refresh],
+    [base, authToken, doFetch, refreshAfterWrite],
   );
 
   const reorderServers = useCallback(

From fd21d0d52801c0dcad3ecf8803957db8a0bdbef7 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 09:39:47 -0400
Subject: [PATCH 02/35] fix(web): don't roll back an optimistic setting a
 failed reload didn't undo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review r1. `updateServerSettings` is also driven by the pagination
toggle, which updates optimistically and — on any rejection — reverts the
override and rolls the live client back to `prevSettings` (#1721). Making
the post-write reload throw handed that catch a rejection whose PUT had
*succeeded*, so it reverted the UI and the client to a value that no
longer matched disk.

Give the reload failure its own type, `ServerListReloadError`, and branch
on it at that call site: report it, leave the optimistic state alone. The
distinction is what the callers need — a failed write must roll back, a
failed read-back must not — and a type carries it without the call site
matching on a message.

The `useServers` mock in App.test.tsx now spreads `importOriginal()` so
the class is the genuine one; a stub would make the `instanceof` check
vacuously false and the branch untestable.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UL9retfvAXRgvi6EWk4SY4
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/App.test.tsx                  | 47 ++++++++++++++++++-
 clients/web/src/App.tsx                       | 28 +++++++----
 .../src/test/core/react/useServers.test.tsx   | 34 +++++++++++++-
 core/react/useServers.ts                      | 25 +++++++++-
 4 files changed, 122 insertions(+), 12 deletions(-)

diff --git a/clients/web/src/App.test.tsx b/clients/web/src/App.test.tsx
index fdf01413..3d95bf9d 100644
--- a/clients/web/src/App.test.tsx
+++ b/clients/web/src/App.test.tsx
@@ -225,7 +225,13 @@ const { updateServerSettingsSpy } = vi.hoisted(() => ({
 const { clearToolsListChangedSpy } = vi.hoisted(() => ({
   clearToolsListChangedSpy: vi.fn(),
 }));
-vi.mock("@inspector/core/react/useServers.js", () => ({
+vi.mock("@inspector/core/react/useServers.js", async (importOriginal) => ({
+  // `ServerListReloadError` is a real class the pagination toggle branches on
+  // with `instanceof`, so it must be the genuine one — a stub would make the
+  // check vacuously false and the #1914 branch untestable (#1914 review r1).
+  ...(await importOriginal<
+    typeof import("@inspector/core/react/useServers.js")
+  >()),
   useServers: vi.fn(() => ({
     servers: [SERVER_A],
     addServer: vi.fn(),
@@ -584,7 +590,10 @@ import { usePagedTools } from "@inspector/core/react/usePagedTools.js";
 import { useMessageLog } from "@inspector/core/react/useMessageLog.js";
 import { useInspectorClient } from "@inspector/core/react/useInspectorClient.js";
 import { useSettingsDraft } from "@inspector/core/react/useSettingsDraft.js";
-import { useServers } from "@inspector/core/react/useServers.js";
+import {
+  ServerListReloadError,
+  useServers,
+} from "@inspector/core/react/useServers.js";
 import type {
   InspectorServerSettings,
   MessageEntry,
@@ -2423,6 +2432,40 @@ describe("App paginated list pagination toggle (#1721)", () => {
     };
     expect(lastPush?.paginatedLists).toBeFalsy();
   });
+
+  it("keeps the optimistic toggle when only the list reload failed (#1914)", async () => {
+    // The mirror of the test above. `refreshAfterWrite` rejects with a
+    // `ServerListReloadError` when the PUT landed and only reading the list
+    // back failed — the setting IS on disk, so the #1721 rollback would put
+    // the UI and the live client on the value the user just changed away
+    // from, and contradict what a reload would show.
+    const user = userEvent.setup();
+    updateServerSettingsSpy.mockRejectedValueOnce(
+      new ServerListReloadError(
+        "The server was saved, but the server list could not be reloaded: disk full",
+      ),
+    );
+    renderWithMantine(<App />);
+    await user.click(screen.getByText("connect"));
+    await waitFor(() => expect(clientInstances).toHaveLength(1));
+
+    await user.click(screen.getByText("paginated-on"));
+    await waitFor(() =>
+      expect(screen.getByTestId("tools-paginated")).toHaveTextContent("true"),
+    );
+    // Give the rejection a turn to land, then confirm nothing reverted it.
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(screen.getByTestId("tools-paginated")).toHaveTextContent("true");
+    const client = clientInstances[0] as unknown as {
+      setServerSettings: ReturnType<typeof vi.fn>;
+    };
+    const lastPush = client.setServerSettings.mock.calls.at(-1)?.[0] as {
+      paginatedLists?: boolean;
+    };
+    expect(lastPush?.paginatedLists).toBe(true);
+  });
 });
 
 // A background command runs through `runCommandInBackground`, which owns the
diff --git a/clients/web/src/App.tsx b/clients/web/src/App.tsx
index 67f7d0ff..a79098ca 100644
--- a/clients/web/src/App.tsx
+++ b/clients/web/src/App.tsx
@@ -98,7 +98,10 @@ import {
 } from "@inspector/core/auth/index.js";
 import { RemoteInspectorClientStorage } from "@inspector/core/mcp/remote/index.js";
 import { useInspectorClient } from "@inspector/core/react/useInspectorClient.js";
-import { useServers } from "@inspector/core/react/useServers.js";
+import {
+  ServerListReloadError,
+  useServers,
+} from "@inspector/core/react/useServers.js";
 import { useSettingsDraft } from "@inspector/core/react/useSettingsDraft.js";
 import { useClientSettingsDraft } from "@inspector/core/react/useClientSettingsDraft.js";
 import { useEmaIdpLoginState } from "@inspector/core/react/useEmaIdpLoginState.js";
@@ -3761,14 +3764,23 @@ function App() {
         activeServerId,
         next,
       ).catch((err: unknown) => {
-        // Persist failed: revert the optimistic override (the effect only
-        // clears it when the persisted value changes, which won't happen here)
-        // and roll the live client setting back, so the UI and client reflect
-        // the value that's actually on disk rather than the failed edit (#1721).
-        setPaginatedListsOverride(null);
-        inspectorClient?.setServerSettings(prevSettings);
+        // A ServerListReloadError means the PUT landed and only reading the
+        // list back failed, so the new setting IS on disk (#1914). Rolling
+        // back here would put the UI and the live client on the *old* value
+        // and contradict it — report it and leave the optimistic state alone.
+        const reloadFailed = err instanceof ServerListReloadError;
+        if (!reloadFailed) {
+          // Persist failed: revert the optimistic override (the effect only
+          // clears it when the persisted value changes, which won't happen here)
+          // and roll the live client setting back, so the UI and client reflect
+          // the value that's actually on disk rather than the failed edit (#1721).
+          setPaginatedListsOverride(null);
+          inspectorClient?.setServerSettings(prevSettings);
+        }
         notifications.show({
-          title: "Failed to save pagination setting",
+          title: reloadFailed
+            ? "Pagination setting saved, but the server list did not reload"
+            : "Failed to save pagination setting",
           message: err instanceof Error ? err.message : String(err),
           color: "red",
         });
diff --git a/clients/web/src/test/core/react/useServers.test.tsx b/clients/web/src/test/core/react/useServers.test.tsx
index 0c011109..2ca1d334 100644
--- a/clients/web/src/test/core/react/useServers.test.tsx
+++ b/clients/web/src/test/core/react/useServers.test.tsx
@@ -10,7 +10,10 @@ import { act, renderHook, waitFor } from "@testing-library/react";
 import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { useServers } from "@inspector/core/react/useServers";
+import {
+  ServerListReloadError,
+  useServers,
+} from "@inspector/core/react/useServers";
 import { createRemoteApp } from "@inspector/core/mcp/remote/node/server";
 import { DEFAULT_SEED_CONFIG } from "@inspector/core/mcp/serverList";
 import { InMemorySecretStore } from "@inspector/core/auth/node/secret-store";
@@ -1316,6 +1319,35 @@ describe("useServers", () => {
     });
   });
 
+  it("tags a post-write reload failure as ServerListReloadError, not a failed write (#1914)", async () => {
+    // The pagination toggle updates optimistically and reverts the live
+    // client on a rejection. That is right for a failed PUT and wrong for a
+    // failed reload — the setting IS on disk — so the two must be tellable
+    // apart by type, not by message matching.
+    const { fetchFn, startFailing } = failGetAfterWrite("disk full");
+    const { result } = renderHook(() =>
+      useServers({ baseUrl: "http://test.local", fetchFn }),
+    );
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    startFailing();
+    await act(async () => {
+      await expect(
+        result.current.addServer("alpha", { type: "stdio", command: "node" }),
+      ).rejects.toBeInstanceOf(ServerListReloadError);
+    });
+
+    // A rejected *write* stays a plain Error, so a caller branching on the
+    // type still rolls back for the case the rollback was written for.
+    await act(async () => {
+      const err = await result.current
+        .addServer("alpha", { type: "stdio", command: "node" })
+        .catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(Error);
+      expect(err).not.toBeInstanceOf(ServerListReloadError);
+    });
+  });
+
   it("removeServer rejects when the post-write list reload fails (#1914)", async () => {
     const { fetchFn, startFailing } = failGetAfterWrite("disk full");
     const { result } = renderHook(() =>
diff --git a/core/react/useServers.ts b/core/react/useServers.ts
index bcba4690..3b66a0c8 100644
--- a/core/react/useServers.ts
+++ b/core/react/useServers.ts
@@ -62,6 +62,25 @@ export interface UseServersResult {
   importSource: (type: string) => Promise<ImportSourceResult>;
 }
 
+/**
+ * Thrown when a mutation's *write* landed but reading the list back
+ * afterwards failed — see `refreshAfterWrite`.
+ *
+ * Distinct from a rejected write because the two call for opposite handling
+ * in an optimistic caller. The pagination toggle in `App.tsx` reverts its
+ * optimistic override and rolls the live client back on a rejection, which is
+ * right for a failed PUT and wrong here: the setting *is* on disk, so the
+ * rollback would show the user a value that no longer matches it. Callers
+ * that update optimistically must branch on this; callers that only report
+ * (the modals) can treat it as any other error.
+ */
+export class ServerListReloadError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ServerListReloadError";
+  }
+}
+
 function buildHeaders(
   authToken: string | undefined,
   includeJsonBody: boolean,
@@ -182,6 +201,10 @@ export function useServers(opts: UseServersOptions): UseServersResult {
   // back failed. A bare "could not add server" would send the user straight
   // into a retry that trips the duplicate-id check, which is the dead end the
   // original report described.
+  //
+  // The rejection is a `ServerListReloadError` rather than a bare `Error` so
+  // an optimistic caller can tell it from a failed write and skip its
+  // rollback — reverting here would contradict what is actually on disk.
   const refreshAfterWrite = useCallback(
     async (verb: string): Promise<void> => {
       setLoading(true);
@@ -191,7 +214,7 @@ export function useServers(opts: UseServersOptions): UseServersResult {
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         setError(message);
-        throw new Error(
+        throw new ServerListReloadError(
           `The server was ${verb}, but the server list could not be reloaded: ${message}`,
           { cause: err },
         );

From 269ff5fefcfcfa9a13bbe823df9bdf745d096ded Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 09:58:56 -0400
Subject: [PATCH 03/35] fix(web): follow a rename whose list reload failed, and
 drop a double cast
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review r2.

`onConfigSubmit` moved `activeServerId` to the renamed id only after
`updateServer` resolved. Once a failed list reload rejects, the rename is
still on disk — so the active id stayed on the old one and the next
successful refresh left it pointing at a row that no longer exists. Apply
the rename from the catch when the rejection is a `ServerListReloadError`,
then rethrow so the modal still shows the error. `addServerHighlighted`
gets the same treatment: the row is on disk, so it belongs in the
highlight batch the next successful refresh renders.

`activeServerId` is not rendered anywhere, so the test reads it back
through the one handler that hands it to a spy — the pagination toggle's
`updateServerSettings(activeServerId, …)` — after letting the renamed row
land as a later refresh would. It fails without the catch-side call. The
new describe installs its own `useServers` return value and restores the
previous implementation afterwards, since earlier describes' overrides
outlive them (which is why the first draft's spy was never called).

Also replaced the `as unknown as` in the new test with a single
`EventTarget & {…}` intersection, per the TypeScript rules. The other 19
in this file are the same pattern and are left for a separate sweep.

The third comment — that the pagination toggle's rollback baseline goes
stale after a failed list read — is a real defect but pre-existing and
unchanged by this PR; the end state is identical before and after it.
Filed as #2089 rather than widening this fix.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UL9retfvAXRgvi6EWk4SY4
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/App.test.tsx | 103 ++++++++++++++++++++++++++++++++++-
 clients/web/src/App.tsx      |  36 ++++++++++--
 2 files changed, 132 insertions(+), 7 deletions(-)

diff --git a/clients/web/src/App.test.tsx b/clients/web/src/App.test.tsx
index 3d95bf9d..fabee0b9 100644
--- a/clients/web/src/App.test.tsx
+++ b/clients/web/src/App.test.tsx
@@ -220,6 +220,12 @@ const SERVER_A = {
 const { updateServerSettingsSpy } = vi.hoisted(() => ({
   updateServerSettingsSpy: vi.fn(() => Promise.resolve()),
 }));
+
+// Same idea for the edit-modal rename path (#1914): the test needs to make the
+// PUT's *reload* fail, which only a spy it controls can do.
+const { updateServerSpy } = vi.hoisted(() => ({
+  updateServerSpy: vi.fn(() => Promise.resolve()),
+}));
 // Stable spy for the tools list-changed acknowledgement, so a test can assert
 // the paginated Refresh clears the indicator (#1721).
 const { clearToolsListChangedSpy } = vi.hoisted(() => ({
@@ -235,7 +241,7 @@ vi.mock("@inspector/core/react/useServers.js", async (importOriginal) => ({
   useServers: vi.fn(() => ({
     servers: [SERVER_A],
     addServer: vi.fn(),
-    updateServer: vi.fn(),
+    updateServer: updateServerSpy,
     updateServerSettings: updateServerSettingsSpy,
     removeServer: vi.fn(),
   })),
@@ -418,6 +424,7 @@ vi.mock("./components/views/InspectorView/InspectorView", () => ({
     onClearCompletedTasks: () => void;
     onRefreshTasks: () => void;
     onServerSettings: (id: string) => void;
+    onServerEdit: (id: string) => void;
     onClearProtocol: () => void;
     onReplayProtocol: (id: string) => void;
     onTogglePinProtocol: (id: string) => void;
@@ -543,6 +550,9 @@ vi.mock("./components/views/InspectorView/InspectorView", () => ({
       </button>
       <button onClick={() => props.onSetLogLevel("debug")}>set-level</button>
       <button onClick={() => props.onServerSettings("A")}>open-settings</button>
+      {/* The real server grid (and its Edit button) lives inside this mocked
+          view, so the edit modal is only reachable through its callback. */}
+      <button onClick={() => props.onServerEdit("A")}>edit-server</button>
       <span data-testid="pinned-history">
         {Array.from(props.pinnedProtocolIds ?? []).join(",")}
       </span>
@@ -2458,7 +2468,10 @@ describe("App paginated list pagination toggle (#1721)", () => {
       await Promise.resolve();
     });
     expect(screen.getByTestId("tools-paginated")).toHaveTextContent("true");
-    const client = clientInstances[0] as unknown as {
+    // Single intersection assertion rather than the `as unknown as` this file
+    // uses elsewhere: the fake client really is an EventTarget, and widening
+    // it keeps that relationship instead of erasing it (#1914 r2).
+    const client = clientInstances[0] as EventTarget & {
       setServerSettings: ReturnType<typeof vi.fn>;
     };
     const lastPush = client.setServerSettings.mock.calls.at(-1)?.[0] as {
@@ -2468,6 +2481,92 @@ describe("App paginated list pagination toggle (#1721)", () => {
   });
 });
 
+// `onConfigSubmit` moves `activeServerId` to the new id only after
+// `updateServer` *resolves*. Once a failed list reload rejects, the rename is
+// still on disk — so without the catch-side `followRename` the active id stays
+// on the old one, and the next successful refresh leaves it pointing at a row
+// that no longer exists (#1914 review r2).
+describe("App edit rename with a failed list reload (#1914)", () => {
+  // Earlier describes install their own `useServers` return value, which
+  // outlives them — so this block installs its own and puts the previous
+  // implementation back, rather than trusting whatever leaked in.
+  let restoreUseServers: (() => void) | undefined;
+
+  const serversResult = (ids: string[]): ReturnType<typeof useServers> => ({
+    servers: ids.map((id) => ({ ...SERVER_A, id }) as ServerEntry),
+    loading: false,
+    error: undefined,
+    refresh: vi.fn().mockResolvedValue(undefined),
+    addServer: vi.fn().mockResolvedValue(undefined),
+    updateServer: updateServerSpy,
+    updateServerSettings: updateServerSettingsSpy,
+    removeServer: vi.fn().mockResolvedValue(undefined),
+    reorderServers: vi.fn().mockResolvedValue(undefined),
+    importSource: vi.fn().mockResolvedValue({ servers: {} }),
+  });
+
+  beforeEach(() => {
+    clientInstances.length = 0;
+    const previous = vi.mocked(useServers).getMockImplementation();
+    restoreUseServers = previous
+      ? () => vi.mocked(useServers).mockImplementation(previous)
+      : undefined;
+    updateServerSpy.mockClear();
+    updateServerSettingsSpy.mockClear();
+    vi.mocked(useServers).mockReturnValue(serversResult(["A"]));
+  });
+
+  afterEach(() => {
+    restoreUseServers?.();
+  });
+
+  it("follows the rename so the active id isn't orphaned (#1914)", async () => {
+    // `activeServerId` isn't rendered anywhere, so it's read back through the
+    // one handler that passes it straight to a spy: the pagination toggle
+    // calls `updateServerSettings(activeServerId, …)`.
+    const user = userEvent.setup();
+    updateServerSpy.mockRejectedValueOnce(
+      new ServerListReloadError(
+        "The server was saved, but the server list could not be reloaded: disk full",
+      ),
+    );
+    renderWithMantine(<App />);
+    await user.click(screen.getByText("connect"));
+    await waitFor(() => expect(clientInstances).toHaveLength(1));
+
+    await user.click(screen.getByText("edit-server"));
+    const idField = await screen.findByLabelText(/Server ID/);
+    await user.clear(idField);
+    await user.type(idField, "A-renamed");
+    await user.click(screen.getByRole("button", { name: "Save" }));
+
+    await waitFor(() =>
+      expect(updateServerSpy).toHaveBeenCalledWith(
+        "A",
+        "A-renamed",
+        expect.anything(),
+      ),
+    );
+    // The rejection still reaches the modal, which stays open showing it.
+    expect(
+      await screen.findByText(/could not be reloaded: disk full/),
+    ).toBeInTheDocument();
+
+    // Now let the row land, as a later successful refresh would, and read the
+    // active id back off the toggle.
+    vi.mocked(useServers).mockReturnValue(serversResult(["A-renamed"]));
+    await user.click(screen.getByRole("button", { name: "Cancel" }));
+    await user.click(screen.getByText("paginated-on"));
+
+    await waitFor(() =>
+      expect(updateServerSettingsSpy).toHaveBeenCalledWith(
+        "A-renamed",
+        expect.objectContaining({ paginatedLists: true }),
+      ),
+    );
+  });
+});
+
 // A background command runs through `runCommandInBackground`, which owns the
 // rejection. Before #2049 the 17 `void runWithCommandAuthRecovery(...)` sites
 // had no handler, so any non-auth failure of the wrapped operation became an
diff --git a/clients/web/src/App.tsx b/clients/web/src/App.tsx
index a79098ca..169fd9c3 100644
--- a/clients/web/src/App.tsx
+++ b/clients/web/src/App.tsx
@@ -4075,8 +4075,20 @@ function App() {
   // opens (see the menu handlers).
   const addServerHighlighted = useCallback(
     async (id: string, config: MCPServerConfig) => {
-      await addServer(id, config);
-      setHighlightedServerIds((ids) => (ids.includes(id) ? ids : [...ids, id]));
+      const markAdded = () =>
+        setHighlightedServerIds((ids) =>
+          ids.includes(id) ? ids : [...ids, id],
+        );
+      try {
+        await addServer(id, config);
+      } catch (err) {
+        // A failed list reload still means the row is on disk, so it belongs
+        // in the highlight batch — the next successful refresh is what
+        // renders it, and it would otherwise arrive unmarked (#1914 r2).
+        if (err instanceof ServerListReloadError) markAdded();
+        throw err;
+      }
+      markAdded();
     },
     [addServer],
   );
@@ -4086,10 +4098,24 @@ function App() {
     async (id: string, config: MCPServerConfig) => {
       if (configModal?.mode === "edit" && configModal.targetId) {
         const originalId = configModal.targetId;
-        await updateServer(originalId, id, config);
-        if (originalId === activeServerId && id !== originalId) {
-          setActiveServerId(id);
+        const followRename = () => {
+          if (originalId === activeServerId && id !== originalId) {
+            setActiveServerId(id);
+          }
+        };
+        try {
+          await updateServer(originalId, id, config);
+        } catch (err) {
+          // A `ServerListReloadError` means the PUT landed and only reading
+          // the list back failed — the rename IS on disk. The active
+          // selection has to follow it anyway, or the next successful
+          // refresh leaves `activeServerId` pointing at an id that no longer
+          // exists (#1914 r2). Still rethrow, so the modal shows the reload
+          // error rather than closing as if nothing happened.
+          if (err instanceof ServerListReloadError) followRename();
+          throw err;
         }
+        followRename();
         return;
       }
       // add or clone

From b49d4f20f519c294933b85fd6be5b76a474ab86f Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 10:14:22 -0400
Subject: [PATCH 04/35] fix(web): stop the remaining consumers calling a landed
 write a failure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review r3. Three findings, all the same root: a
ServerListReloadError rejects after the write succeeded, so any consumer
still reading "rejection" as "the write failed" now says something false.

- `useImportClientConfig.applyEntry` gave a successfully imported server a
  red "Failed" badge. It now reports the intended status and puts the
  reload message in `detail`, which renders in red beneath it either way —
  so the failure stays visible without claiming the row wasn't created.
- The settings-draft toast said "Failed to save settings". It now branches
  its title; this toast is the only signal there, since the modal has
  usually closed by the time a flush rejects.
- An edit modal left open by a failed reload kept targeting the old id.
  When the row landed under the new one, `configModalTarget` went
  undefined and ServerConfigModal's own reset blanked the open form and
  cleared the error it was showing. An edit/clone modal whose target has
  left the list now closes — adjusted during render via `useValueChange`,
  so no frame paints the blanked form. That also covers the ordinary case
  of an external mcp.json edit removing the server being edited.

The reachability here is not remote: the write is what triggers the
backend's change broadcast, so the SSE-driven refresh that lands the
renamed row is the likely next event.

Also adds the regression test r3 asked for on the add path — the
highlight batch has to be marked from the catch for the same reason the
rename is. Both new App tests and the import one fail without their fix.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UL9retfvAXRgvi6EWk4SY4
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/App.test.tsx                  | 79 +++++++++++++++----
 clients/web/src/App.tsx                       | 34 +++++++-
 .../src/hooks/useImportClientConfig.test.tsx  | 26 ++++++
 .../web/src/hooks/useImportClientConfig.ts    | 17 ++--
 4 files changed, 134 insertions(+), 22 deletions(-)

diff --git a/clients/web/src/App.test.tsx b/clients/web/src/App.test.tsx
index fabee0b9..db5a28d5 100644
--- a/clients/web/src/App.test.tsx
+++ b/clients/web/src/App.test.tsx
@@ -223,8 +223,9 @@ const { updateServerSettingsSpy } = vi.hoisted(() => ({
 
 // Same idea for the edit-modal rename path (#1914): the test needs to make the
 // PUT's *reload* fail, which only a spy it controls can do.
-const { updateServerSpy } = vi.hoisted(() => ({
+const { updateServerSpy, addServerSpy } = vi.hoisted(() => ({
   updateServerSpy: vi.fn(() => Promise.resolve()),
+  addServerSpy: vi.fn(() => Promise.resolve()),
 }));
 // Stable spy for the tools list-changed acknowledgement, so a test can assert
 // the paginated Refresh clears the indicator (#1721).
@@ -240,7 +241,7 @@ vi.mock("@inspector/core/react/useServers.js", async (importOriginal) => ({
   >()),
   useServers: vi.fn(() => ({
     servers: [SERVER_A],
-    addServer: vi.fn(),
+    addServer: addServerSpy,
     updateServer: updateServerSpy,
     updateServerSettings: updateServerSettingsSpy,
     removeServer: vi.fn(),
@@ -425,6 +426,8 @@ vi.mock("./components/views/InspectorView/InspectorView", () => ({
     onRefreshTasks: () => void;
     onServerSettings: (id: string) => void;
     onServerEdit: (id: string) => void;
+    onServerAdd: () => void;
+    highlightedServerIds?: string[];
     onClearProtocol: () => void;
     onReplayProtocol: (id: string) => void;
     onTogglePinProtocol: (id: string) => void;
@@ -550,9 +553,14 @@ vi.mock("./components/views/InspectorView/InspectorView", () => ({
       </button>
       <button onClick={() => props.onSetLogLevel("debug")}>set-level</button>
       <button onClick={() => props.onServerSettings("A")}>open-settings</button>
-      {/* The real server grid (and its Edit button) lives inside this mocked
-          view, so the edit modal is only reachable through its callback. */}
+      {/* The real server grid (and its Add / Edit controls) lives inside this
+          mocked view, so the config modal is only reachable through these
+          callbacks — and the highlight batch only observable through this prop. */}
       <button onClick={() => props.onServerEdit("A")}>edit-server</button>
+      <button onClick={() => props.onServerAdd()}>add-server</button>
+      <span data-testid="highlighted-servers">
+        {(props.highlightedServerIds ?? []).join(",") || "none"}
+      </span>
       <span data-testid="pinned-history">
         {Array.from(props.pinnedProtocolIds ?? []).join(",")}
       </span>
@@ -2481,12 +2489,11 @@ describe("App paginated list pagination toggle (#1721)", () => {
   });
 });
 
-// `onConfigSubmit` moves `activeServerId` to the new id only after
-// `updateServer` *resolves*. Once a failed list reload rejects, the rename is
-// still on disk — so without the catch-side `followRename` the active id stays
-// on the old one, and the next successful refresh leaves it pointing at a row
-// that no longer exists (#1914 review r2).
-describe("App edit rename with a failed list reload (#1914)", () => {
+// A post-write reload failure rejects *after* the write landed, so every piece
+// of state `onConfigSubmit` used to apply on the resolve path has to be applied
+// on the reject path too — the rename target and the highlight batch both
+// describe a row that really is on disk (#1914 review r2 / r3).
+describe("App config submit with a failed list reload (#1914)", () => {
   // Earlier describes install their own `useServers` return value, which
   // outlives them — so this block installs its own and puts the previous
   // implementation back, rather than trusting whatever leaked in.
@@ -2497,7 +2504,7 @@ describe("App edit rename with a failed list reload (#1914)", () => {
     loading: false,
     error: undefined,
     refresh: vi.fn().mockResolvedValue(undefined),
-    addServer: vi.fn().mockResolvedValue(undefined),
+    addServer: addServerSpy,
     updateServer: updateServerSpy,
     updateServerSettings: updateServerSettingsSpy,
     removeServer: vi.fn().mockResolvedValue(undefined),
@@ -2512,6 +2519,7 @@ describe("App edit rename with a failed list reload (#1914)", () => {
       ? () => vi.mocked(useServers).mockImplementation(previous)
       : undefined;
     updateServerSpy.mockClear();
+    addServerSpy.mockClear();
     updateServerSettingsSpy.mockClear();
     vi.mocked(useServers).mockReturnValue(serversResult(["A"]));
   });
@@ -2530,7 +2538,7 @@ describe("App edit rename with a failed list reload (#1914)", () => {
         "The server was saved, but the server list could not be reloaded: disk full",
       ),
     );
-    renderWithMantine(<App />);
+    const { rerender } = renderWithMantine(<App />);
     await user.click(screen.getByText("connect"));
     await waitFor(() => expect(clientInstances).toHaveLength(1));
 
@@ -2552,12 +2560,19 @@ describe("App edit rename with a failed list reload (#1914)", () => {
       await screen.findByText(/could not be reloaded: disk full/),
     ).toBeInTheDocument();
 
-    // Now let the row land, as a later successful refresh would, and read the
-    // active id back off the toggle.
+    // Now let the row land, as the SSE refresh the write itself triggers
+    // would. The modal's target ("A") is gone, so it closes rather than
+    // blanking its own form — `initialId`/`initialConfig` would go undefined
+    // and ServerConfigModal's reset would wipe the open form and the error
+    // it is showing (#1914 r3).
     vi.mocked(useServers).mockReturnValue(serversResult(["A-renamed"]));
-    await user.click(screen.getByRole("button", { name: "Cancel" }));
-    await user.click(screen.getByText("paginated-on"));
+    rerender(<App />);
+    await waitFor(() =>
+      expect(screen.queryByLabelText(/Server ID/)).not.toBeInTheDocument(),
+    );
 
+    // With the modal gone, read the active id back off the toggle.
+    await user.click(screen.getByText("paginated-on"));
     await waitFor(() =>
       expect(updateServerSettingsSpy).toHaveBeenCalledWith(
         "A-renamed",
@@ -2565,6 +2580,38 @@ describe("App edit rename with a failed list reload (#1914)", () => {
       ),
     );
   });
+
+  it("keeps a successful add in the highlight batch when the reload failed (#1914)", async () => {
+    // `addServerHighlighted` marked the new id only after `addServer`
+    // resolved. The row is on disk either way, so on a reload failure it has
+    // to be marked from the catch — the next successful refresh is what
+    // renders it, and it would otherwise arrive unhighlighted.
+    const user = userEvent.setup();
+    addServerSpy.mockRejectedValueOnce(
+      new ServerListReloadError(
+        "The server was added, but the server list could not be reloaded: disk full",
+      ),
+    );
+    renderWithMantine(<App />);
+    expect(screen.getByTestId("highlighted-servers")).toHaveTextContent("none");
+
+    await user.click(screen.getByText("add-server"));
+    await user.type(await screen.findByLabelText(/Server ID/), "brand-new");
+    await user.type(screen.getByLabelText(/^Command/), "node");
+    await user.click(screen.getByRole("button", { name: "Add" }));
+
+    await waitFor(() =>
+      expect(addServerSpy).toHaveBeenCalledWith("brand-new", expect.anything()),
+    );
+    expect(
+      await screen.findByText(/could not be reloaded: disk full/),
+    ).toBeInTheDocument();
+    await waitFor(() =>
+      expect(screen.getByTestId("highlighted-servers")).toHaveTextContent(
+        "brand-new",
+      ),
+    );
+  });
 });
 
 // A background command runs through `runCommandInBackground`, which owns the
diff --git a/clients/web/src/App.tsx b/clients/web/src/App.tsx
index 169fd9c3..a99f212e 100644
--- a/clients/web/src/App.tsx
+++ b/clients/web/src/App.tsx
@@ -113,6 +113,7 @@ import { usePagedTools } from "@inspector/core/react/usePagedTools.js";
 import { usePagedPrompts } from "@inspector/core/react/usePagedPrompts.js";
 import { usePagedResources } from "@inspector/core/react/usePagedResources.js";
 import { usePaginatedList } from "./hooks/usePaginatedList";
+import { useValueChange } from "./hooks/useValueChange";
 import type { ListPaginationControlsProps } from "./components/elements/ListPaginationControls/ListPaginationControls";
 import { useManagedResourceTemplates } from "@inspector/core/react/useManagedResourceTemplates.js";
 import { useManagedRequestorTasks } from "@inspector/core/react/useManagedRequestorTasks.js";
@@ -4140,6 +4141,30 @@ function App() {
     return servers.find((s) => s.id === configModal.targetId);
   }, [configModal, servers]);
 
+  // An edit/clone modal whose target has left the list can no longer render a
+  // coherent form: `initialId`/`initialConfig` go undefined, and
+  // ServerConfigModal's own `useValueChange` reset then blanks the open form
+  // *and* clears the error it is showing.
+  //
+  // Only reachable since #1914 made the modal stay open on a failed post-write
+  // reload: rename A → B, the PUT lands, the reload fails, and the modal sits
+  // there targeting A. The write itself is what triggers the backend's change
+  // broadcast, so the SSE-driven background refresh that lands B (and drops A)
+  // is the *likely* next event, not a remote one. Closing is right — the edit
+  // is on disk and the list now agrees — and it covers the ordinary case too,
+  // where an external mcp.json edit removes the server being edited.
+  //
+  // Adjusted during render rather than in an effect (see `useValueChange`), so
+  // no frame ever paints the blanked form.
+  useValueChange(
+    configModal?.mode === "add" || configModal?.targetId === undefined
+      ? true
+      : servers.some((s) => s.id === configModal.targetId),
+    (targetPresent) => {
+      if (!targetPresent) setConfigModal(null);
+    },
+  );
+
   const settingsModalTarget = useMemo(() => {
     if (!settingsModalTargetId) return undefined;
     return servers.find((s) => s.id === settingsModalTargetId);
@@ -4188,7 +4213,14 @@ function App() {
     // didn't (especially painful for the OAuth client secret).
     onError: (id, err) => {
       notifications.show({
-        title: `Failed to save settings for "${id}"`,
+        // A `ServerListReloadError` means the PUT landed and only reading the
+        // list back failed, so "Failed to save" would be false — and this
+        // toast is the user's only signal here, since the modal has usually
+        // closed by the time a flush rejects (#1914 r3).
+        title:
+          err instanceof ServerListReloadError
+            ? `Saved settings for "${id}", but the server list did not reload`
+            : `Failed to save settings for "${id}"`,
         message: err instanceof Error ? err.message : String(err),
         color: "red",
       });
diff --git a/clients/web/src/hooks/useImportClientConfig.test.tsx b/clients/web/src/hooks/useImportClientConfig.test.tsx
index 9900f283..def42e7e 100644
--- a/clients/web/src/hooks/useImportClientConfig.test.tsx
+++ b/clients/web/src/hooks/useImportClientConfig.test.tsx
@@ -6,6 +6,7 @@ import {
 } from "./useImportClientConfig";
 import type { ImportSourceResult } from "@inspector/core/mcp/import/index.js";
 import type { MCPConfig } from "@inspector/core/mcp/types.js";
+import { ServerListReloadError } from "@inspector/core/react/useServers.js";
 
 function config(...ids: string[]): MCPConfig {
   const mcpServers: MCPConfig["mcpServers"] = {};
@@ -207,6 +208,31 @@ describe("useImportClientConfig", () => {
     expect(outcome.detail).toBe("add failed");
   });
 
+  it("reports a reload failure as imported-with-a-warning, not failed (#1914)", async () => {
+    // A `ServerListReloadError` rejects *after* the write landed, so the entry
+    // really was added. A red "Failed" badge would contradict the error's own
+    // message and invite a retry that then collides with the row it claims
+    // wasn't created. The reason still shows, as `detail`.
+    const onAddServer = vi.fn(async () => {
+      throw new ServerListReloadError(
+        "The server was added, but the server list could not be reloaded: disk full",
+      );
+    });
+    const { result } = setup({
+      onFetchSource: vi.fn(async () => foundSource(config("alpha"))),
+      onAddServer,
+    });
+    await act(async () => {
+      await result.current.pickSource("claude");
+    });
+    await act(async () => {
+      await result.current.runImport();
+    });
+    const outcome = result.current.outcomes[0];
+    expect(outcome.status).toBe("added");
+    expect(outcome.detail).toMatch(/could not be reloaded: disk full/);
+  });
+
   it("resolves conflicts by overwrite, skip, and rename", async () => {
     const onAddServer = vi.fn(async () => {});
     const onUpdateServer = vi.fn(async () => {});
diff --git a/clients/web/src/hooks/useImportClientConfig.ts b/clients/web/src/hooks/useImportClientConfig.ts
index 61a01478..c5e439f8 100644
--- a/clients/web/src/hooks/useImportClientConfig.ts
+++ b/clients/web/src/hooks/useImportClientConfig.ts
@@ -8,6 +8,7 @@ import {
   type ImportSourceResult,
 } from "@inspector/core/mcp/import/index.js";
 import { validateStoreId } from "@inspector/core/storage/store-id.js";
+import { ServerListReloadError } from "@inspector/core/react/useServers.js";
 import type { MCPConfig, MCPServerConfig } from "@inspector/core/mcp/types.js";
 
 export type ImportPhase = "select" | "loading" | "review" | "summary";
@@ -198,11 +199,17 @@ export function useImportClientConfig({
       await write();
       return { id, status: outcome };
     } catch (err) {
-      return {
-        id,
-        status: "failed",
-        detail: err instanceof Error ? err.message : String(err),
-      };
+      const detail = err instanceof Error ? err.message : String(err);
+      // A `ServerListReloadError` means the write landed and only reading the
+      // list back failed, so this entry really was imported. Reporting it as
+      // `failed` would contradict the error's own message and invite a retry
+      // that then collides with the row it says wasn't created (#1914 r3).
+      // The status is the truth about the write; `detail` renders in red
+      // beneath it either way, so the reload failure is still visible.
+      if (err instanceof ServerListReloadError) {
+        return { id, status: outcome, detail };
+      }
+      return { id, status: "failed", detail };
     }
   }
 

From 6c1cc6c1ae0a1cf9774eb625e2b07730d82b5b42 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 10:27:28 -0400
Subject: [PATCH 05/35] test(web): cover the settings toast's reload-failure
 title
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review r4. The r3 title branch was the one modified behavior with
no test of its own — the existing ServerListReloadError cases cover the
pagination, add, and rename paths only, so a regression back to "Failed to
save settings" would have gone green.

`useSettingsDraft` is mocked in this suite, so the test invokes the
`onError` App handed it and asserts both titles: the reload-failure one,
and that a genuine write failure still reads as a failure. Forcing the
branch off fails it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UL9retfvAXRgvi6EWk4SY4
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/App.test.tsx | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/clients/web/src/App.test.tsx b/clients/web/src/App.test.tsx
index db5a28d5..032f46e9 100644
--- a/clients/web/src/App.test.tsx
+++ b/clients/web/src/App.test.tsx
@@ -2581,6 +2581,39 @@ describe("App config submit with a failed list reload (#1914)", () => {
     );
   });
 
+  it("labels a settings save whose reload failed as saved, not failed (#1914)", () => {
+    // The settings draft debounces and flushes on close, so this toast is the
+    // user's only signal — a flush that rejects usually does so after the
+    // modal is gone. `useSettingsDraft` is mocked here, so the App's `onError`
+    // is invoked directly with the options it was handed.
+    renderWithMantine(<App />);
+    const onError = vi.mocked(useSettingsDraft).mock.calls.at(-1)?.[0].onError;
+    expect(onError).toBeDefined();
+
+    act(() => {
+      onError!(
+        "A",
+        new ServerListReloadError(
+          "The server was saved, but the server list could not be reloaded: disk full",
+        ),
+      );
+    });
+    expect(notificationsMock.show).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: 'Saved settings for "A", but the server list did not reload',
+        message: expect.stringContaining("disk full"),
+      }),
+    );
+
+    // A genuinely failed write still reads as a failure.
+    act(() => {
+      onError!("A", new Error("disk full"));
+    });
+    expect(notificationsMock.show).toHaveBeenCalledWith(
+      expect.objectContaining({ title: 'Failed to save settings for "A"' }),
+    );
+  });
+
   it("keeps a successful add in the highlight batch when the reload failed (#1914)", async () => {
     // `addServerHighlighted` marked the new id only after `addServer`
     // resolved. The row is on disk either way, so on a reload failure it has

From b33532c024f1bd8fb1550f80dff5595bd9d33c99 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 12:23:40 -0400
Subject: [PATCH 06/35] feat: allow complex JSON values in request _meta
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #1910

`_meta` was typed `Record<string, string>` end to end in the Inspector —
on disk as a `{ key, value }[]` pair array, in the Server Settings form as
key/value rows, and in every request verb's per-call metadata parameter.
Nothing in the MCP spec restricts a `_meta` value to a string, and the SDK
models the field as a `z.looseObject`, so the restriction was ours alone.

Widen the whole path to `RequestMetadata` (`Record<string, JsonValue>`):

- Per-server default metadata is a JSON **object** on disk and in memory.
  The pre-#1910 pair array is still read (`normalizeStoredMetadata`) so an
  existing `mcp.json` keeps working; it is never written back, so a save
  migrates the entry.
- The Server Settings → Request Metadata section is a JSON editor
  (`JsonObjectInput`) instead of key/value rows — rows cannot express an
  object value. It keeps the typed text as the display source and emits
  only parsed JSON, the same draft split `SchemaJsonField` uses, so the box
  stays typeable; invalid text is flagged inline and not applied.
- The CLI stops flattening `--metadata` / `--tool-metadata` through
  `metaValueToString`. Those values were already JSON-parsed, so
  `trace={"id":"abc"}` used to reach the wire as the *string* `{"id":"abc"}`
  and now reaches it as an object.
- `servers/show` redaction replaces a sensitive key's whole value rather
  than a string, so a structured value cannot leak through its members.
- `progressTokenOf` narrows the reserved `progressToken` key back to
  `string | number` before it reaches the SDK; any other JSON still travels
  inside `_meta` but wires up no progress callback.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/cli/README.md                         |   6 +-
 .../cli/__tests__/helpers/oauth-test-fakes.ts |   2 +-
 clients/cli/__tests__/metadata.test.ts        |  27 +--
 clients/cli/__tests__/method-types.test.ts    |   9 -
 .../__tests__/programmatic-ergonomics.test.ts |   2 +-
 clients/cli/__tests__/servers-list.test.ts    |  23 ++-
 clients/cli/src/cli.ts                        |  23 +--
 clients/cli/src/handlers/collect-app-info.ts  |   3 +-
 clients/cli/src/handlers/connect-timeout.ts   |   2 +-
 clients/cli/src/handlers/method-types.ts      |  15 +-
 clients/cli/src/handlers/servers-list.ts      |  13 +-
 clients/tui/__tests__/App.test.tsx            |   2 +-
 .../tui/__tests__/helpers/oauth-test-fakes.ts |   2 +-
 clients/tui/src/App.tsx                       |  10 +-
 clients/web/src/App.test.tsx                  |   2 +-
 clients/web/src/App.tsx                       |  12 +-
 .../JsonObjectInput.stories.tsx               |  92 ++++++++++
 .../JsonObjectInput/JsonObjectInput.test.tsx  | 172 ++++++++++++++++++
 .../JsonObjectInput/JsonObjectInput.tsx       | 113 ++++++++++++
 .../ServerSettingsForm.stories.tsx            |  46 ++---
 .../ServerSettingsForm.test.tsx               |  83 +++------
 .../ServerSettingsForm/ServerSettingsForm.tsx |  42 ++---
 .../ServerSettingsModal.stories.tsx           |   6 +-
 .../ServerSettingsModal.test.tsx              |  95 ++--------
 .../ServerSettingsModal.tsx                   |  22 +--
 .../web/src/test/core/client/runner.test.ts   |  12 +-
 ...nspectorClient-peer-handler-timing.test.ts |   2 +-
 .../src/test/core/mcp/node/servers.test.ts    |   2 +-
 .../mcp/remote/remoteClientTransport.test.ts  |   2 +-
 .../web/src/test/core/mcp/serverList.test.ts  | 128 +++++++++++--
 .../mcp/state/managedPromptsState.test.ts     |   2 +-
 .../managedResourceTemplatesState.test.ts     |   2 +-
 .../mcp/state/managedResourcesState.test.ts   |   2 +-
 .../core/mcp/state/managedToolsState.test.ts  |   2 +-
 .../core/mcp/state/pagedPromptsState.test.ts  |   2 +-
 .../mcp/state/pagedResourcesState.test.ts     |   2 +-
 .../core/mcp/state/pagedToolsState.test.ts    |   2 +-
 .../src/test/core/react/useServers.test.tsx   |  10 +-
 .../inspectorClient-coverage-backfill.test.ts |   4 +-
 .../mcp/inspectorClient-modern-era.test.ts    |   6 +-
 .../integration/mcp/inspectorClient.test.ts   |  52 +++++-
 .../integration/mcp/node/transport.test.ts    |   8 +-
 .../mcp/remote/server-extra-coverage.test.ts  |   6 +-
 .../mcp/remote/servers-route.test.ts          |  83 ++++-----
 .../integration/mcp/remote/transport.test.ts  |   2 +-
 core/mcp/__tests__/fakeInspectorClient.ts     |  11 +-
 core/mcp/inspectorClient.ts                   | 107 ++++++-----
 core/mcp/inspectorClientEventTarget.ts        |   3 +-
 core/mcp/inspectorClientProtocol.ts           |  29 +--
 core/mcp/node/servers.ts                      |   2 +-
 core/mcp/remote/node/server.ts                |  28 ++-
 core/mcp/serverList.ts                        |  66 ++++++-
 core/mcp/state/managedListState.ts            |  11 +-
 core/mcp/state/pagedPromptsState.ts           |   3 +-
 core/mcp/state/pagedResourceTemplatesState.ts |   3 +-
 core/mcp/state/pagedResourcesState.ts         |   3 +-
 core/mcp/types.ts                             |  49 +++--
 core/react/usePagedPrompts.ts                 |   5 +-
 core/react/usePagedResourceTemplates.ts       |   5 +-
 core/react/usePagedResources.ts               |   5 +-
 docs/mcp-server-configuration.md              |  14 +-
 61 files changed, 1004 insertions(+), 495 deletions(-)
 create mode 100644 clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.stories.tsx
 create mode 100644 clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
 create mode 100644 clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx

diff --git a/clients/cli/README.md b/clients/cli/README.md
index d5c033df..976f2ec6 100644
--- a/clients/cli/README.md
+++ b/clients/cli/README.md
@@ -110,15 +110,15 @@ Options that specify the MCP server (catalog/config file, ad-hoc command/URL, en
 | `--prompt-name <name>`        | Prompt name (for `prompts/get`).                                                                                                                                                                                                                                                                                                                                                                                     |
 | `--prompt-args <key=value>`   | Prompt arguments; repeat for multiple.                                                                                                                                                                                                                                                                                                                                                                               |
 | `--log-level <level>`         | Logging level for `logging/setLevel` (e.g. `debug`, `info`).                                                                                                                                                                                                                                                                                                                                                         |
-| `--metadata <key=value>`      | General metadata (key=value); applied to all methods.                                                                                                                                                                                                                                                                                                                                                                |
-| `--tool-metadata <key=value>` | Tool-specific metadata for `tools/call`.                                                                                                                                                                                                                                                                                                                                                                             |
+| `--metadata <key=value>`      | General `_meta` entries (key=value); applied to all methods. The value is JSON-parsed when it parses, so `trace={"id":"abc"}` sends a real object and `n=3` a number; anything that is not valid JSON is sent as the literal string. |
+| `--tool-metadata <key=value>` | Tool-specific `_meta` entries for `tools/call`. Same JSON-parsed value handling as `--metadata`. |
 | `--connect-timeout <ms>`      | Connection timeout in ms. Defaults to `15000` for ad-hoc `--server-url`/target runs (so a black-holed host fails fast) and to the file-level timeout for `--catalog`/`--config` runs. `0` disables the timeout.                                                                                                                                                                                                      |
 | `--app-info`                  | Probe a tool's MCP App UI metadata without invoking it. With `--method tools/call --tool-name <name>`: prints one JSON line (`hasApp`, `resourceUri`, `csp`, `permissions`, `domain`, …) and exits `0` if the tool has an app or `2` (`no_app`) if not. With `--method tools/list`: emits NDJSON — one app-info line per tool over a single connection.                                                              |
 | `--format <text\|json>`       | Output format. `text` (default) pretty-prints the result. `json` emits a single JSON object on stdout (`{ "result": … }`, plus `{ "appInfo": … }` as a sibling key for App tools) with no banners, so the whole output pipes cleanly into `jq`.                                                                                                                                                                      |
 | `--relogin`                   | Delete stored OAuth for this server URL from the shared store before connect; interactive login still only runs if the server requires auth. Requires an HTTP/SSE URL (rejected for stdio). Conflicts with `--stored-auth-only` / `--use-stored-auth` / `--wait-for-auth` / catalog short-circuits.                                                                                                                  |
 | `--stored-auth-only`          | **CI / non-interactive safe:** never start interactive OAuth / step-up (and never auto-open a browser); use the shared store if present, otherwise fail immediately with `auth_required`. Prefer this over a bare pipe/CI run that would otherwise attempt interactive login.                                                                                                                                        |
 
-`servers/show` redacts secret-bearing fields (`env` values, sensitive headers / `settings.metadata` keys, `requestInit` / `eventSourceInit` headers, `oauthClientSecret`). It does **not** scrub credentials embedded in a server `url` (userinfo or query tokens) or in stdio `args` — treat `detail` / raw URL fields as potentially sensitive before pasting into issues.
+`servers/show` redacts secret-bearing fields (`env` values, sensitive headers, sensitive `settings.metadata` keys whose whole value is replaced whether or not it is structured, `requestInit` / `eventSourceInit` headers, `oauthClientSecret`). It does **not** scrub credentials embedded in a server `url` (userinfo or query tokens) or in stdio `args` — treat `detail` / raw URL fields as potentially sensitive before pasting into issues.
 
 #### App probing (`--app-info`) and machine-readable output (`--format json`)
 
diff --git a/clients/cli/__tests__/helpers/oauth-test-fakes.ts b/clients/cli/__tests__/helpers/oauth-test-fakes.ts
index b53e1570..8c5e91f9 100644
--- a/clients/cli/__tests__/helpers/oauth-test-fakes.ts
+++ b/clients/cli/__tests__/helpers/oauth-test-fakes.ts
@@ -63,7 +63,7 @@ export function makeFakeServerSettings(
 ): InspectorServerSettings {
   return {
     headers: [],
-    metadata: [],
+    metadata: {},
     env: [],
     connectionTimeout: 0,
     requestTimeout: 0,
diff --git a/clients/cli/__tests__/metadata.test.ts b/clients/cli/__tests__/metadata.test.ts
index b5867d50..a4cb05fc 100644
--- a/clients/cli/__tests__/metadata.test.ts
+++ b/clients/cli/__tests__/metadata.test.ts
@@ -373,16 +373,17 @@ describe("Metadata Tests", () => {
 
         expectCliSuccess(result);
 
-        // Validate metadata values are sent as strings
+        // A JSON-parseable value goes out as that JSON type, not as its
+        // string spelling (#1910) — `_meta` takes any JSON.
         const recordedRequests = server.getRecordedRequests();
         const toolsListRequest = recordedRequests.find(
           (r) => r.method === "tools/list",
         );
         expect(toolsListRequest).toBeDefined();
         expect(toolsListRequest?.metadata).toEqual({
-          integer_value: "42",
-          decimal_value: "3.14159",
-          negative_value: "-10",
+          integer_value: 42,
+          decimal_value: 3.14159,
+          negative_value: -10,
         });
       } finally {
         await server.stop();
@@ -428,7 +429,7 @@ describe("Metadata Tests", () => {
       }
     });
 
-    it("JSON.stringifies object/array metadata (not String → [object Object])", async () => {
+    it("sends object/array/boolean metadata as real JSON, not stringified (#1910)", async () => {
       const server = createTestServerHttp({
         serverInfo: createTestServerInfo(),
         tools: [createEchoTool()],
@@ -456,9 +457,9 @@ describe("Metadata Tests", () => {
           (r) => r.method === "tools/list",
         );
         expect(toolsListRequest?.metadata).toEqual({
-          nested: '{"key":"value"}',
-          list: "[1,2,3]",
-          flag: "true",
+          nested: { key: "value" },
+          list: [1, 2, 3],
+          flag: true,
         });
       } finally {
         await server.stop();
@@ -819,7 +820,7 @@ describe("Metadata Tests", () => {
         );
         expect(toolsListRequest).toBeDefined();
         expect(toolsListRequest?.metadata).toEqual({
-          integration_test: "true",
+          integration_test: true,
           test_phase: "all_methods",
         });
       } finally {
@@ -866,8 +867,8 @@ describe("Metadata Tests", () => {
         );
         expect(toolCallRequest).toBeDefined();
         expect(toolCallRequest?.metadata).toEqual({
-          session_id: "12345",
-          user_id: "67890",
+          session_id: 12345,
+          user_id: 67890,
           timestamp: "2024-01-01T00:00:00Z",
           request_id: "req-abc-123",
           tool_session: "session-xyz-789",
@@ -919,8 +920,8 @@ describe("Metadata Tests", () => {
         expect(toolCallRequest).toBeDefined();
         expect(toolCallRequest?.metadata).toEqual({
           valid_key: "valid_value",
-          numeric_key: "123",
-          boolean_key: "true",
+          numeric_key: 123,
+          boolean_key: true,
           json_key: '\'{"test":"value"}\'', // Single quotes are preserved
           special_key: "!@#$%^&*()",
           unicode_key: "🚀🎉✨",
diff --git a/clients/cli/__tests__/method-types.test.ts b/clients/cli/__tests__/method-types.test.ts
index 42c71025..85230043 100644
--- a/clients/cli/__tests__/method-types.test.ts
+++ b/clients/cli/__tests__/method-types.test.ts
@@ -1,7 +1,6 @@
 import { describe, it, expect } from "vitest";
 import {
   isOneShotMethod,
-  metaValueToString,
   ONE_SHOT_METHODS,
   SESSION_RPC_METHODS,
 } from "../src/handlers/method-types.js";
@@ -26,11 +25,3 @@ describe("ONE_SHOT_METHODS", () => {
     expect(ONE_SHOT_METHODS).not.toContain("logging/tail");
   });
 });
-
-describe("metaValueToString", () => {
-  it("passes strings through and JSON-encodes structured values", () => {
-    expect(metaValueToString("plain")).toBe("plain");
-    expect(metaValueToString({ a: 1 })).toBe('{"a":1}');
-    expect(metaValueToString([1, 2])).toBe("[1,2]");
-  });
-});
diff --git a/clients/cli/__tests__/programmatic-ergonomics.test.ts b/clients/cli/__tests__/programmatic-ergonomics.test.ts
index 1c6fdee7..88f42f10 100644
--- a/clients/cli/__tests__/programmatic-ergonomics.test.ts
+++ b/clients/cli/__tests__/programmatic-ergonomics.test.ts
@@ -12,7 +12,7 @@ import {
 describe("withConnectTimeout", () => {
   const baseSettings: InspectorServerSettings = {
     headers: [{ key: "X-Test", value: "1" }],
-    metadata: [],
+    metadata: {},
     env: [],
     connectionTimeout: 42,
     requestTimeout: 0,
diff --git a/clients/cli/__tests__/servers-list.test.ts b/clients/cli/__tests__/servers-list.test.ts
index 8ac7b599..5772ab3e 100644
--- a/clients/cli/__tests__/servers-list.test.ts
+++ b/clients/cli/__tests__/servers-list.test.ts
@@ -219,10 +219,14 @@ describe("showServerEntry / servers/show", () => {
         { key: "Authorization", value: "Bearer x" },
         { key: "X-Custom", value: "ok" },
       ],
-      metadata: [
-        { key: "Authorization", value: "Bearer meta" },
-        { key: "X-Custom", value: "ok" },
-      ],
+      metadata: {
+        Authorization: "Bearer meta",
+        "X-Custom": "ok",
+        // A structured value under a sensitive key: the redaction must replace
+        // the whole value, not walk into it (#1910).
+        "X-Api-Key": { primary: "sk-live-1", fallback: "sk-live-2" },
+        nested: { keep: true },
+      },
       env: [
         { key: "TOKEN", value: "secret" },
         { key: "", value: "still-secret" },
@@ -242,10 +246,13 @@ describe("showServerEntry / servers/show", () => {
       { key: "Authorization", value: "[redacted]" },
       { key: "X-Custom", value: "ok" },
     ]);
-    expect(sanitized.metadata).toEqual([
-      { key: "Authorization", value: "[redacted]" },
-      { key: "X-Custom", value: "ok" },
-    ]);
+    expect(sanitized.metadata).toEqual({
+      Authorization: "[redacted]",
+      "X-Custom": "ok",
+      "X-Api-Key": "[redacted]",
+      // A structured value under a non-sensitive key survives intact.
+      nested: { keep: true },
+    });
     expect(sanitized.env).toEqual([
       { key: "TOKEN", value: "[redacted]" },
       { key: "", value: "[redacted]" },
diff --git a/clients/cli/src/cli.ts b/clients/cli/src/cli.ts
index f4d418ae..35ca3dd9 100644
--- a/clients/cli/src/cli.ts
+++ b/clients/cli/src/cli.ts
@@ -33,7 +33,6 @@ import { consumeMethodOutcome } from "./handlers/consume-outcome.js";
 import { runMethod } from "./handlers/run-method.js";
 import {
   isOneShotMethod,
-  metaValueToString,
   ONE_SHOT_METHODS,
   type MethodArgs,
 } from "./handlers/method-types.js";
@@ -999,22 +998,12 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
     promptName: options.promptName,
     promptArgs: options.promptArgs,
     logLevel: options.logLevel,
-    metadata: options.metadata
-      ? Object.fromEntries(
-          Object.entries(options.metadata).map(([key, value]) => [
-            key,
-            metaValueToString(value),
-          ]),
-        )
-      : undefined,
-    toolMeta: options.toolMetadata
-      ? Object.fromEntries(
-          Object.entries(options.toolMetadata).map(([key, value]) => [
-            key,
-            metaValueToString(value),
-          ]),
-        )
-      : undefined,
+    // `--metadata`/`--tool-metadata` values are parsed as JSON, and `_meta`
+    // takes any JSON — so they go through unflattened (#1910). They used to be
+    // squeezed through `metaValueToString`, which sent `{"a":1}` as the
+    // *string* `'{"a":1}'`.
+    metadata: options.metadata,
+    toolMeta: options.toolMetadata,
     appInfo: options.appInfo === true,
     format: options.format,
   };
diff --git a/clients/cli/src/handlers/collect-app-info.ts b/clients/cli/src/handlers/collect-app-info.ts
index aa2df1fc..d46e3754 100644
--- a/clients/cli/src/handlers/collect-app-info.ts
+++ b/clients/cli/src/handlers/collect-app-info.ts
@@ -2,6 +2,7 @@ import { InspectorClient } from "@inspector/core/mcp/index.js";
 import { extractAppInfo } from "@inspector/core/mcp/apps.js";
 import type { AppInfo } from "@inspector/core/mcp/apps.js";
 import type { CliAppInfo } from "./method-types.js";
+import type { RequestMetadata } from "@inspector/core/mcp/types.js";
 
 /**
  * Build the CLI's app-info for a tool. Never throws — failures fold into
@@ -10,7 +11,7 @@ import type { CliAppInfo } from "./method-types.js";
 export async function collectAppInfo(
   client: Pick<InspectorClient, "readResource">,
   tool: Parameters<typeof extractAppInfo>[0],
-  metadata: Record<string, string> | undefined,
+  metadata: RequestMetadata | undefined,
 ): Promise<CliAppInfo> {
   let base: AppInfo;
   try {
diff --git a/clients/cli/src/handlers/connect-timeout.ts b/clients/cli/src/handlers/connect-timeout.ts
index 7d5a7b2c..8bd8cf65 100644
--- a/clients/cli/src/handlers/connect-timeout.ts
+++ b/clients/cli/src/handlers/connect-timeout.ts
@@ -22,7 +22,7 @@ export function withConnectTimeout(
   if (settings) return { ...settings, connectionTimeout };
   return {
     headers: [],
-    metadata: [],
+    metadata: {},
     env: [],
     connectionTimeout,
     requestTimeout: 0,
diff --git a/clients/cli/src/handlers/method-types.ts b/clients/cli/src/handlers/method-types.ts
index b0505425..424b941b 100644
--- a/clients/cli/src/handlers/method-types.ts
+++ b/clients/cli/src/handlers/method-types.ts
@@ -1,4 +1,5 @@
 import type { JsonValue } from "@inspector/core/mcp/index.js";
+import type { RequestMetadata } from "@inspector/core/mcp/types.js";
 import type { AppInfo } from "@inspector/core/mcp/apps.js";
 import type { LoggingLevel } from "@modelcontextprotocol/client";
 import type { OutputFormat } from "./format-output.js";
@@ -20,8 +21,8 @@ export type MethodArgs = {
   logLevel?: LoggingLevel;
   toolName?: string;
   toolArg?: Record<string, JsonValue>;
-  toolMeta?: Record<string, string>;
-  metadata?: Record<string, string>;
+  toolMeta?: RequestMetadata;
+  metadata?: RequestMetadata;
   appInfo?: boolean;
   format?: OutputFormat;
   /** Task id for tasks/get, tasks/cancel, tasks/result. */
@@ -110,13 +111,3 @@ export type OneShotMethod = (typeof ONE_SHOT_METHODS)[number];
 export function isOneShotMethod(method: string): method is OneShotMethod {
   return (ONE_SHOT_METHODS as readonly string[]).includes(method);
 }
-
-/**
- * Encode a metadata / tool-metadata value for MethodArgs (string map).
- * Strings pass through; objects/arrays use JSON.stringify so structure is kept
- * (avoids String(obj) → "[object Object]").
- */
-export function metaValueToString(value: JsonValue): string {
-  if (typeof value === "string") return value;
-  return JSON.stringify(value);
-}
diff --git a/clients/cli/src/handlers/servers-list.ts b/clients/cli/src/handlers/servers-list.ts
index 78bd896f..d0247851 100644
--- a/clients/cli/src/handlers/servers-list.ts
+++ b/clients/cli/src/handlers/servers-list.ts
@@ -157,10 +157,15 @@ export function sanitizeServerSettings(
       key: h.key,
       value: isSensitiveHeader(h.key) ? REDACTED : h.value,
     })),
-    metadata: (settings.metadata ?? []).map((m) => ({
-      key: m.key,
-      value: isSensitiveHeader(m.key) ? REDACTED : m.value,
-    })),
+    // Metadata is a JSON object whose values may be any JSON (#1910), so the
+    // redaction replaces the whole value rather than a string — a sensitive
+    // key holding an object must not leak through its members.
+    metadata: Object.fromEntries(
+      Object.entries(settings.metadata ?? {}).map(([key, value]) => [
+        key,
+        isSensitiveHeader(key) ? REDACTED : value,
+      ]),
+    ),
     env: (settings.env ?? []).map((e) => ({
       key: e.key,
       value: REDACTED,
diff --git a/clients/tui/__tests__/App.test.tsx b/clients/tui/__tests__/App.test.tsx
index a66fe603..3e749dff 100644
--- a/clients/tui/__tests__/App.test.tsx
+++ b/clients/tui/__tests__/App.test.tsx
@@ -340,7 +340,7 @@ function oneEmaHttp(): Record<string, TuiServer> {
       config: { type: "streamable-http", url: "http://localhost:8080/mcp" },
       settings: {
         requestTimeout: 0,
-        metadata: [],
+        metadata: {},
         headers: [],
         env: [],
         roots: [],
diff --git a/clients/tui/__tests__/helpers/oauth-test-fakes.ts b/clients/tui/__tests__/helpers/oauth-test-fakes.ts
index efff339e..5e6e0fae 100644
--- a/clients/tui/__tests__/helpers/oauth-test-fakes.ts
+++ b/clients/tui/__tests__/helpers/oauth-test-fakes.ts
@@ -19,7 +19,7 @@ export function makeFakeServerSettings(
 ): InspectorServerSettings {
   return {
     headers: [],
-    metadata: [],
+    metadata: {},
     env: [],
     connectionTimeout: 0,
     requestTimeout: 0,
diff --git a/clients/tui/src/App.tsx b/clients/tui/src/App.tsx
index 240bbd82..df88e3a9 100644
--- a/clients/tui/src/App.tsx
+++ b/clients/tui/src/App.tsx
@@ -291,13 +291,9 @@ function App({
           transport: createTransportNode,
           logger: getTuiLogger(),
         };
-        const defaultMetadata = savedSettings?.metadata
-          ? Object.fromEntries(
-              savedSettings.metadata
-                .filter((m) => m.key.trim() !== "")
-                .map((m) => [m.key, m.value]),
-            )
-          : undefined;
+        // Per-server default `_meta` is already a JSON object (#1910) — no
+        // pair-array flattening left to do; `{}` means "no defaults".
+        const defaultMetadata = savedSettings?.metadata;
         const clientAuthOptions = buildRunnerClientAuthOptions(
           clientConfig,
           savedSettings,
diff --git a/clients/web/src/App.test.tsx b/clients/web/src/App.test.tsx
index fdf01413..e5056190 100644
--- a/clients/web/src/App.test.tsx
+++ b/clients/web/src/App.test.tsx
@@ -1635,7 +1635,7 @@ const settingsWithRoots = (
 ): InspectorServerSettings => ({
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 0,
   requestTimeout: 0,
   taskTtl: 60000,
diff --git a/clients/web/src/App.tsx b/clients/web/src/App.tsx
index 67f7d0ff..1be3d046 100644
--- a/clients/web/src/App.tsx
+++ b/clients/web/src/App.tsx
@@ -384,7 +384,7 @@ async function replayProtocolRequest(
 const EMPTY_SETTINGS: InspectorServerSettings = {
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 0,
   requestTimeout: 0,
   taskTtl: DEFAULT_TASK_TTL_MS,
@@ -2466,13 +2466,9 @@ function App() {
       const activeCimdUrl = getActiveCimdClientMetadataUrl(clientConfig);
       // Flatten the persisted settings into the InspectorClient options shape.
       // Empty / zero values stay unset so the SDK defaults apply.
-      const defaultMetadata = savedSettings?.metadata
-        ? Object.fromEntries(
-            savedSettings.metadata
-              .filter((m) => m.key.trim() !== "")
-              .map((m) => [m.key, m.value]),
-          )
-        : undefined;
+      // Per-server default `_meta` is already a JSON object (#1910) — no
+      // pair-array flattening left to do; `{}` means "no defaults".
+      const defaultMetadata = savedSettings?.metadata;
       const serverAuthorizationParams = savedSettings
         ? oauthAuthorizationParamsFromSettings(savedSettings)
         : undefined;
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.stories.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.stories.tsx
new file mode 100644
index 00000000..51405384
--- /dev/null
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.stories.tsx
@@ -0,0 +1,92 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, within } from "storybook/test";
+import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
+import { JsonObjectInput } from "./JsonObjectInput";
+
+/**
+ * The component is controlled, so every story drives it through a small
+ * stateful wrapper — otherwise the box would not accept a keystroke and the
+ * play functions could not exercise the draft behavior at all.
+ */
+function ControlledJsonObjectInput({ initial }: { initial: JsonObject }) {
+  const [value, setValue] = useState<JsonObject>(initial);
+  return (
+    <JsonObjectInput
+      label="Request metadata"
+      aria-label="Request metadata JSON"
+      value={value}
+      onChange={setValue}
+    />
+  );
+}
+
+const meta: Meta<typeof ControlledJsonObjectInput> = {
+  title: "Elements/JsonObjectInput",
+  component: ControlledJsonObjectInput,
+};
+
+export default meta;
+type Story = StoryObj<typeof ControlledJsonObjectInput>;
+
+/** A structured payload renders as formatted JSON, nesting intact. */
+export const Populated: Story = {
+  args: {
+    initial: {
+      tenant: "acme",
+      trace: { id: "abc123", sampled: true },
+      features: ["apps", "tasks"],
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const box = await canvas.findByLabelText("Request metadata JSON");
+    await expect(JSON.parse((box as HTMLTextAreaElement).value)).toEqual({
+      tenant: "acme",
+      trace: { id: "abc123", sampled: true },
+      features: ["apps", "tasks"],
+    });
+  },
+};
+
+/** An empty payload opens as `{}` and carries no error. */
+export const Empty: Story = {
+  args: { initial: {} },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const box = await canvas.findByLabelText("Request metadata JSON");
+    await expect(box).toHaveValue("{}");
+    await expect(canvas.queryByText(/Not valid JSON/)).toBeNull();
+  },
+};
+
+/**
+ * Half-typed text is displayed as typed and flagged, rather than being
+ * re-escaped back into the box each keystroke (the #1928 failure this draft
+ * split exists to avoid).
+ */
+export const InvalidDraft: Story = {
+  args: { initial: {} },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const box = await canvas.findByLabelText("Request metadata JSON");
+    await userEvent.clear(box);
+    await userEvent.type(box, '{{"a":');
+    await expect(box).toHaveValue('{"a":');
+    await expect(await canvas.findByText(/Not valid JSON/)).toBeVisible();
+  },
+};
+
+/** Valid JSON that is not an object is rejected with its own message. */
+export const NotAnObject: Story = {
+  args: { initial: {} },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const box = await canvas.findByLabelText("Request metadata JSON");
+    await userEvent.clear(box);
+    await userEvent.type(box, "[[1,2]");
+    await expect(
+      await canvas.findByText(/Must be a JSON object/),
+    ).toBeVisible();
+  },
+};
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
new file mode 100644
index 00000000..37d02dfb
--- /dev/null
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
@@ -0,0 +1,172 @@
+import { useState } from "react";
+import { describe, it, expect, vi } from "vitest";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
+import { renderWithMantine } from "../../../test/renderWithMantine";
+import { JsonObjectInput, parseObjectDraft } from "./JsonObjectInput";
+
+const LABEL = "Payload JSON";
+
+/** Controlled harness: the component never owns the value, only the draft. */
+function Harness({
+  initial,
+  onChange,
+}: {
+  initial: JsonObject;
+  onChange?: (v: JsonObject) => void;
+}) {
+  const [value, setValue] = useState<JsonObject>(initial);
+  return (
+    <>
+      <JsonObjectInput
+        aria-label={LABEL}
+        value={value}
+        onChange={(next) => {
+          setValue(next);
+          onChange?.(next);
+        }}
+      />
+      <output data-testid="emitted">{JSON.stringify(value)}</output>
+    </>
+  );
+}
+
+function box() {
+  return screen.getByLabelText(LABEL) as HTMLTextAreaElement;
+}
+
+describe("parseObjectDraft", () => {
+  it("reads empty text as the empty object rather than an error", () => {
+    expect(parseObjectDraft("")).toEqual({ ok: true, value: {} });
+    expect(parseObjectDraft("   \n ")).toEqual({ ok: true, value: {} });
+  });
+
+  it("accepts a JSON object with values of any JSON type", () => {
+    const result = parseObjectDraft(
+      '{"s":"a","n":1,"b":true,"z":null,"arr":[1,{"k":2}],"o":{"deep":{"er":1}}}',
+    );
+    expect(result).toEqual({
+      ok: true,
+      value: {
+        s: "a",
+        n: 1,
+        b: true,
+        z: null,
+        arr: [1, { k: 2 }],
+        o: { deep: { er: 1 } },
+      },
+    });
+  });
+
+  it("rejects text that is not JSON", () => {
+    expect(parseObjectDraft('{"a":')).toEqual({
+      ok: false,
+      error: "Not valid JSON — changes are not applied",
+    });
+  });
+
+  it.each([
+    ["an array", "[1,2]"],
+    ["a string", '"hello"'],
+    ["a number", "42"],
+    ["null", "null"],
+  ])("rejects valid JSON that is not an object: %s", (_label, text) => {
+    const result = parseObjectDraft(text);
+    expect(result.ok).toBe(false);
+    expect(result.ok === false && result.error).toMatch(
+      /Must be a JSON object/,
+    );
+  });
+});
+
+describe("JsonObjectInput", () => {
+  it("opens with the value serialized two-space, nesting intact", () => {
+    renderWithMantine(<Harness initial={{ a: { b: [1, 2] } }} />);
+    expect(box().value).toBe(
+      '{\n  "a": {\n    "b": [\n      1,\n      2\n    ]\n  }\n}',
+    );
+  });
+
+  it("emits the parsed object — a structured value stays structured", async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    renderWithMantine(<Harness initial={{}} onChange={onChange} />);
+    await user.clear(box());
+    await user.type(box(), '{{"trace":{{"id":"x"},"n":3}');
+    expect(onChange).toHaveBeenLastCalledWith({ trace: { id: "x" }, n: 3 });
+  });
+
+  it("shows the text as typed while it is invalid and does not emit", async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    renderWithMantine(<Harness initial={{ keep: "me" }} onChange={onChange} />);
+    // Append a stray character rather than clearing: clearing is itself a
+    // valid edit (it means `{}`) and would emit, which is not what is under
+    // test here.
+    await user.click(box());
+    await user.keyboard("{End}x");
+    // Displayed verbatim — not re-escaped back through JSON.stringify.
+    expect(box().value.endsWith("}x")).toBe(true);
+    expect(
+      screen.getByText("Not valid JSON — changes are not applied"),
+    ).toBeInTheDocument();
+    // Nothing emitted, so the caller still holds the last valid object.
+    expect(onChange).not.toHaveBeenCalled();
+    expect(screen.getByTestId("emitted").textContent).toBe('{"keep":"me"}');
+  });
+
+  it("flags valid JSON that is not an object without emitting", async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    renderWithMantine(<Harness initial={{ keep: "me" }} onChange={onChange} />);
+    await user.clear(box());
+    // The clear is a legitimate edit to `{}`; only what follows is under test.
+    expect(onChange).toHaveBeenLastCalledWith({});
+    onChange.mockClear();
+    await user.type(box(), "[[1]");
+    expect(screen.getByText(/Must be a JSON object/)).toBeInTheDocument();
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("treats a cleared box as the empty object", async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    renderWithMantine(<Harness initial={{ a: 1 }} onChange={onChange} />);
+    await user.clear(box());
+    expect(onChange).toHaveBeenLastCalledWith({});
+    expect(screen.queryByText(/Not valid JSON/)).toBeNull();
+  });
+
+  it("re-syncs when the parent's value diverges from the draft", async () => {
+    // An external reset (switching servers, a reloaded catalog) must reach the
+    // box; an in-progress edit must not be overwritten by the value it emitted.
+    function Externally() {
+      const [value, setValue] = useState<JsonObject>({ a: 1 });
+      return (
+        <>
+          <JsonObjectInput
+            aria-label={LABEL}
+            value={value}
+            onChange={setValue}
+          />
+          <button onClick={() => setValue({ b: 2 })}>reset</button>
+        </>
+      );
+    }
+    const user = userEvent.setup();
+    renderWithMantine(<Externally />);
+    await user.click(screen.getByRole("button", { name: "reset" }));
+    expect(JSON.parse(box().value)).toEqual({ b: 2 });
+  });
+
+  it("leaves an in-progress edit alone when the parent echoes it back", async () => {
+    const user = userEvent.setup();
+    renderWithMantine(<Harness initial={{}} />);
+    await user.clear(box());
+    // Typed without the closing brace auto-pair: the text is what the user has
+    // so far, and the echo of the parsed value must not reformat it mid-edit.
+    await user.type(box(), '{{"a":1}');
+    expect(box().value).toBe('{"a":1}');
+  });
+});
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
new file mode 100644
index 00000000..93df2516
--- /dev/null
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
@@ -0,0 +1,113 @@
+import { useState } from "react";
+import { JsonInput } from "@mantine/core";
+import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
+import { useValueChange } from "../../../hooks/useValueChange";
+
+const ObjectJsonInput = JsonInput.withProps({
+  formatOnBlur: true,
+  autosize: true,
+  minRows: 4,
+  spellCheck: false,
+});
+
+/** Two-space canonical form — the same shape the catalog file is written in. */
+function serialize(value: JsonObject): string {
+  return JSON.stringify(value, null, 2);
+}
+
+/** A plain JSON object, i.e. not an array and not a scalar. */
+function isJsonObject(value: unknown): value is JsonObject {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * What a draft's text currently means: the object to emit, or why it can't be.
+ *
+ * Empty text is the object `{}` rather than an error — clearing the box is how
+ * "send no metadata" is spelled, and an empty editor showing a red error would
+ * read as broken.
+ */
+type DraftState =
+  | { ok: true; value: JsonObject }
+  | { ok: false; error: string };
+
+export function parseObjectDraft(text: string): DraftState {
+  if (text.trim() === "") return { ok: true, value: {} };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { ok: false, error: "Not valid JSON — changes are not applied" };
+  }
+  if (!isJsonObject(parsed)) {
+    return {
+      ok: false,
+      error: "Must be a JSON object (`{ … }`) — changes are not applied",
+    };
+  }
+  return { ok: true, value: parsed };
+}
+
+export interface JsonObjectInputProps {
+  value: JsonObject;
+  onChange: (value: JsonObject) => void;
+  label?: string;
+  description?: string;
+  placeholder?: string;
+  "aria-label"?: string;
+  "data-testid"?: string;
+}
+
+/**
+ * A JSON-object editor: the user types JSON, the parent receives the parsed
+ * object.
+ *
+ * This is the editor for payloads whose *values* may be any JSON, which is why
+ * it exists beside the key/value row editors used for headers and env. `_meta`
+ * is the case that forced it (#1910) — nothing in the MCP spec restricts a
+ * `_meta` value to a string, so a `{ key, value }` row editor cannot express
+ * what the protocol allows.
+ *
+ * The text the user is typing is the source of truth for what is *displayed*;
+ * the parent only ever sees a parsed object. That split is what makes the box
+ * typeable: driving it off the parent's value and stringifying on every render
+ * re-escapes half-typed text once per keystroke, which is the #1928 symptom.
+ * `SchemaJsonField` in `SchemaForm.tsx` carries the same split for the same
+ * reason — see the long comment there.
+ *
+ * While the text is invalid the parent is **not** told, so the last valid
+ * object stands. The alternative — emitting `{}` — would silently discard a
+ * user's configured metadata the moment they typed a stray character, and this
+ * form has no Save button to gate instead: `onChange` writes straight through.
+ * The state is not silent, though; the field says so on itself via `error`.
+ */
+export function JsonObjectInput({
+  value,
+  onChange,
+  ...inputProps
+}: JsonObjectInputProps) {
+  const [draft, setDraft] = useState(() => serialize(value));
+
+  // Re-sync only when the parent's value genuinely diverges from what the draft
+  // parses to, so an external reset (switching servers, a reloaded catalog)
+  // reaches the box while an in-progress edit is left alone. Compared through
+  // canonical JSON because the parent hands back a fresh object each time.
+  const parsed = parseObjectDraft(draft);
+  const draftJson = parsed.ok ? serialize(parsed.value) : null;
+  useValueChange(serialize(value), (next) => {
+    if (next !== draftJson) setDraft(next);
+  });
+
+  return (
+    <ObjectJsonInput
+      {...inputProps}
+      value={draft}
+      error={parsed.ok ? undefined : parsed.error}
+      onChange={(text) => {
+        setDraft(text);
+        const result = parseObjectDraft(text);
+        if (result.ok) onChange(result.value);
+      }}
+    />
+  );
+}
diff --git a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.stories.tsx b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.stories.tsx
index 19c54849..c6e6fb69 100644
--- a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.stories.tsx
+++ b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.stories.tsx
@@ -10,7 +10,7 @@ import {
 const defaultSettings: InspectorServerSettings = {
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 30000,
   requestTimeout: 60000,
   taskTtl: 60000,
@@ -57,34 +57,9 @@ function InteractiveRender(args: ServerSettingsFormProps) {
           },
         });
       }}
-      onAddMetadata={() => {
-        args.onAddMetadata();
-        updateArgs({
-          settings: {
-            ...args.settings,
-            metadata: [...args.settings.metadata, { key: "", value: "" }],
-          },
-        });
-      }}
-      onRemoveMetadata={(index) => {
-        args.onRemoveMetadata(index);
-        updateArgs({
-          settings: {
-            ...args.settings,
-            metadata: args.settings.metadata.filter((_, i) => i !== index),
-          },
-        });
-      }}
-      onMetadataChange={(index, key, value) => {
-        args.onMetadataChange(index, key, value);
-        updateArgs({
-          settings: {
-            ...args.settings,
-            metadata: args.settings.metadata.map((m, i) =>
-              i === index ? { key, value } : m,
-            ),
-          },
-        });
+      onMetadataChange={(metadata) => {
+        args.onMetadataChange(metadata);
+        updateArgs({ settings: { ...args.settings, metadata } });
       }}
       onAddEnv={() => {
         args.onAddEnv();
@@ -197,8 +172,6 @@ const meta: Meta<typeof ServerSettingsForm> = {
     onRemoveEnv: fn(),
     onEnvChange: fn(),
     onCwdChange: fn(),
-    onAddMetadata: fn(),
-    onRemoveMetadata: fn(),
     onMetadataChange: fn(),
     onTimeoutChange: fn(),
     onAutoRefreshChange: fn(),
@@ -278,10 +251,13 @@ export const AllConfigured: Story = {
         { key: "X-Request-Id", value: "req-456" },
       ],
       env: [],
-      metadata: [
-        { key: "userId", value: "user-789" },
-        { key: "sessionId", value: "session-012" },
-      ],
+      metadata: {
+        userId: "user-789",
+        sessionId: "session-012",
+        // A structured value — the case a `{ key, value }` row editor could
+        // not express (#1910).
+        client: { name: "inspector", features: ["apps", "tasks"], retries: 3 },
+      },
       connectionTimeout: 15000,
       requestTimeout: 45000,
       taskTtl: 45000,
diff --git a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.test.tsx b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.test.tsx
index 7ea0e396..cd5e168a 100644
--- a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.test.tsx
+++ b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.test.tsx
@@ -22,7 +22,7 @@ function clearButtonFor(input: HTMLElement): HTMLElement {
 const emptySettings: InspectorServerSettings = {
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 30000,
   requestTimeout: 60000,
   taskTtl: 60000,
@@ -33,7 +33,7 @@ const emptySettings: InspectorServerSettings = {
 const populatedSettings: InspectorServerSettings = {
   headers: [{ key: "Authorization", value: "Bearer abc" }],
   env: [],
-  metadata: [{ key: "userId", value: "u-1" }],
+  metadata: { userId: "u-1", tenant: { id: 7, tags: ["a"] } },
   connectionTimeout: 30000,
   requestTimeout: 60000,
   taskTtl: 60000,
@@ -63,8 +63,6 @@ const baseHandlers = {
   onRemoveEnv: vi.fn(),
   onEnvChange: vi.fn(),
   onCwdChange: vi.fn(),
-  onAddMetadata: vi.fn(),
-  onRemoveMetadata: vi.fn(),
   onMetadataChange: vi.fn(),
   onTimeoutChange: vi.fn(),
   onAutoRefreshChange: vi.fn(),
@@ -239,7 +237,7 @@ describe("ServerSettingsForm", () => {
     expect(screen.getByText("Log Level per Request")).toBeInTheDocument();
   });
 
-  it("shows empty hints for headers and metadata when no entries exist", () => {
+  it("shows the empty hint for headers, and an empty JSON object for metadata", () => {
     renderWithMantine(
       <ServerSettingsForm
         {...baseHandlers}
@@ -250,9 +248,9 @@ describe("ServerSettingsForm", () => {
     expect(
       screen.getByText("No custom headers configured"),
     ).toBeInTheDocument();
-    expect(
-      screen.getByText("No request metadata configured"),
-    ).toBeInTheDocument();
+    // Metadata has no rows to be absent — the editor is always present, and
+    // "none configured" is spelled `{}` in the box itself.
+    expect(screen.getByLabelText("Request metadata JSON")).toHaveValue("{}");
   });
 
   it("invokes onAddHeader when + Add Header is clicked", async () => {
@@ -270,21 +268,6 @@ describe("ServerSettingsForm", () => {
     expect(onAddHeader).toHaveBeenCalledTimes(1);
   });
 
-  it("invokes onAddMetadata when + Add Metadata is clicked", async () => {
-    const user = userEvent.setup();
-    const onAddMetadata = vi.fn();
-    renderWithMantine(
-      <ServerSettingsForm
-        {...baseHandlers}
-        onAddMetadata={onAddMetadata}
-        settings={emptySettings}
-        expandedSections={["metadata"]}
-      />,
-    );
-    await user.click(screen.getByRole("button", { name: "+ Add Metadata" }));
-    expect(onAddMetadata).toHaveBeenCalledTimes(1);
-  });
-
   it("invokes onHeaderChange when typing in header value input", async () => {
     const user = userEvent.setup();
     const onHeaderChange = vi.fn();
@@ -340,29 +323,38 @@ describe("ServerSettingsForm", () => {
     expect(onRemoveHeader).toHaveBeenCalledWith(0);
   });
 
-  it("invokes onMetadataChange and onRemoveMetadata for metadata rows", async () => {
-    const user = userEvent.setup();
-    const onMetadataChange = vi.fn();
-    const onRemoveMetadata = vi.fn();
+  it("renders the configured metadata as formatted JSON, nested values included", () => {
     renderWithMantine(
       <ServerSettingsForm
         {...baseHandlers}
-        onMetadataChange={onMetadataChange}
-        onRemoveMetadata={onRemoveMetadata}
         settings={populatedSettings}
         expandedSections={["metadata"]}
       />,
     );
-    const valueInput = screen.getByDisplayValue("u-1");
-    await user.type(valueInput, "Z");
-    expect(onMetadataChange).toHaveBeenCalled();
+    const editor = screen.getByLabelText("Request metadata JSON");
+    // The point of #1910: a nested object survives into the editor instead of
+    // being flattened into a `{ key, value }` string row.
+    expect(JSON.parse((editor as HTMLTextAreaElement).value)).toEqual({
+      userId: "u-1",
+      tenant: { id: 7, tags: ["a"] },
+    });
+  });
 
-    await user.click(
-      screen.getByRole("button", {
-        name: "Remove metadata entry, userId, row 1",
-      }),
+  it("reports the whole edited object through onMetadataChange", async () => {
+    const user = userEvent.setup();
+    const onMetadataChange = vi.fn();
+    renderWithMantine(
+      <ServerSettingsForm
+        {...baseHandlers}
+        onMetadataChange={onMetadataChange}
+        settings={emptySettings}
+        expandedSections={["metadata"]}
+      />,
     );
-    expect(onRemoveMetadata).toHaveBeenCalledWith(0);
+    const editor = screen.getByLabelText("Request metadata JSON");
+    await user.clear(editor);
+    await user.type(editor, '{{"n":[[1,2]}');
+    expect(onMetadataChange).toHaveBeenLastCalledWith({ n: [1, 2] });
   });
 
   it("invokes onTimeoutChange when typing in connection timeout", async () => {
@@ -1470,23 +1462,6 @@ describe("ServerSettingsForm", () => {
     expect(onClearStoredOAuth).toHaveBeenCalledTimes(1);
   });
 
-  it("clears a metadata value via its Clear button (onMetadataChange with empty value)", async () => {
-    const user = userEvent.setup();
-    const onMetadataChange = vi.fn();
-    renderWithMantine(
-      <ServerSettingsForm
-        {...baseHandlers}
-        onMetadataChange={onMetadataChange}
-        settings={populatedSettings}
-        expandedSections={["metadata"]}
-      />,
-    );
-    // populatedSettings has one metadata { key: "userId", value: "u-1" }
-    const valueInput = screen.getByDisplayValue("u-1");
-    await user.click(clearButtonFor(valueInput));
-    expect(onMetadataChange).toHaveBeenCalledWith(0, "userId", "");
-  });
-
   it("omits the Clear buttons for an empty header key/value row", () => {
     // A row whose key and value are both empty renders no Clear button in
     // either field (the null branch of `item.key ?` / `item.value ?`).
diff --git a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
index 18f0c522..36179c9b 100644
--- a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
+++ b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
@@ -4,6 +4,7 @@ import {
   Alert,
   Button,
   Checkbox,
+  Code,
   Flex,
   Group,
   NumberInput,
@@ -13,11 +14,13 @@ import {
   TextInput,
 } from "@mantine/core";
 import { ClearButton } from "../../elements/ClearButton/ClearButton";
+import { JsonObjectInput } from "../../elements/JsonObjectInput/JsonObjectInput";
 import type { ProtocolEra } from "@modelcontextprotocol/client";
 import type {
   InspectorServerSettings,
   ModernLogLevel,
   OAuthSettings,
+  RequestMetadata,
   ServerProtocolEra,
   ServerType,
 } from "@inspector/core/mcp/types.js";
@@ -78,9 +81,12 @@ export interface ServerSettingsFormProps {
   onRemoveEnv: (index: number) => void;
   onEnvChange: (index: number, key: string, value: string) => void;
   onCwdChange: (value: string) => void;
-  onAddMetadata: () => void;
-  onRemoveMetadata: (index: number) => void;
-  onMetadataChange: (index: number, key: string, value: string) => void;
+  /**
+   * Replace the whole default-`_meta` payload. Not the `(index, key, value)`
+   * row callback the header/env editors use — metadata is edited as a JSON
+   * object, since a `_meta` value may be any JSON (#1910).
+   */
+  onMetadataChange: (metadata: RequestMetadata) => void;
   onTimeoutChange: (
     field: "connectionTimeout" | "requestTimeout" | "taskTtl",
     value: number,
@@ -434,8 +440,6 @@ export function ServerSettingsForm({
   onRemoveEnv,
   onEnvChange,
   onCwdChange,
-  onAddMetadata,
-  onRemoveMetadata,
   onMetadataChange,
   onTimeoutChange,
   onAutoRefreshChange,
@@ -724,22 +728,18 @@ export function ServerSettingsForm({
         <Accordion.Control>Request Metadata</Accordion.Control>
         <Accordion.Panel>
           <Stack gap="md">
-            <Group justify="space-between">
-              <HintText>
-                Metadata sent with every MCP request (included in _meta field)
-              </HintText>
-              <AddButton onClick={onAddMetadata}>+ Add Metadata</AddButton>
-            </Group>
-            {settings.metadata.length === 0 ? (
-              <EmptyHint>No request metadata configured</EmptyHint>
-            ) : (
-              <KeyValueRows
-                items={settings.metadata}
-                entityLabel="metadata entry"
-                onChange={onMetadataChange}
-                onRemove={onRemoveMetadata}
-              />
-            )}
+            <HintText>
+              Metadata merged into the `_meta` field of every MCP request to
+              this server, as a JSON object. Values may be any JSON — objects,
+              arrays, numbers, booleans, `null` — not just strings. Leave it as{" "}
+              <Code>{"{}"}</Code> to send none.
+            </HintText>
+            <JsonObjectInput
+              aria-label="Request metadata JSON"
+              placeholder={'{\n  "example": { "nested": true }\n}'}
+              value={settings.metadata}
+              onChange={onMetadataChange}
+            />
           </Stack>
         </Accordion.Panel>
       </Accordion.Item>
diff --git a/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.stories.tsx b/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.stories.tsx
index e6cb9e14..453d41cb 100644
--- a/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.stories.tsx
+++ b/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.stories.tsx
@@ -14,7 +14,7 @@ const initialSettings: InspectorServerSettings = {
     { key: "X-Request-Id", value: "req-456" },
   ],
   env: [],
-  metadata: [{ key: "userId", value: "user-789" }],
+  metadata: { userId: "user-789", client: { name: "inspector" } },
   connectionTimeout: 30000,
   requestTimeout: 60000,
   taskTtl: 60000,
@@ -74,7 +74,7 @@ export const EmptySettings: Story = {
     settings: {
       headers: [],
       env: [],
-      metadata: [],
+      metadata: {},
       connectionTimeout: 30000,
       requestTimeout: 60000,
       taskTtl: 60000,
@@ -96,7 +96,7 @@ export const StdioServer: Story = {
         { key: "API_KEY", value: "abc-123" },
         { key: "LOG_LEVEL", value: "debug" },
       ],
-      metadata: [],
+      metadata: {},
       connectionTimeout: 0,
       requestTimeout: 0,
       taskTtl: 60000,
diff --git a/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.test.tsx b/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.test.tsx
index ba0303d4..c42fba16 100644
--- a/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.test.tsx
+++ b/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.test.tsx
@@ -7,7 +7,7 @@ import { ServerSettingsModal } from "./ServerSettingsModal";
 const initialSettings: InspectorServerSettings = {
   headers: [{ key: "Authorization", value: "Bearer abc" }],
   env: [],
-  metadata: [{ key: "userId", value: "u-1" }],
+  metadata: { userId: "u-1" },
   connectionTimeout: 30000,
   requestTimeout: 60000,
   taskTtl: 60000,
@@ -21,7 +21,7 @@ const initialSettings: InspectorServerSettings = {
 const emptySettings: InspectorServerSettings = {
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 30000,
   requestTimeout: 60000,
   taskTtl: 60000,
@@ -310,76 +310,6 @@ describe("ServerSettingsModal", () => {
     expect(lastCall.headers[0].value).toContain("Bearer abc");
   });
 
-  it("calls onSettingsChange when adding metadata after expanding the section", async () => {
-    const user = userEvent.setup();
-    const onSettingsChange = vi.fn();
-    renderWithMantine(
-      <ServerSettingsModal
-        opened
-        settings={emptySettings}
-        serverType="streamable-http"
-        isStdio={false}
-        onClose={vi.fn()}
-        onSettingsChange={onSettingsChange}
-      />,
-    );
-    await user.click(screen.getByRole("button", { name: "Request Metadata" }));
-    await user.click(screen.getByRole("button", { name: "+ Add Metadata" }));
-    expect(onSettingsChange).toHaveBeenCalledWith({
-      ...emptySettings,
-      metadata: [{ key: "", value: "" }],
-    });
-  });
-
-  it("calls onSettingsChange when removing metadata", async () => {
-    const user = userEvent.setup();
-    const onSettingsChange = vi.fn();
-    renderWithMantine(
-      <ServerSettingsModal
-        opened
-        settings={initialSettings}
-        serverType="streamable-http"
-        isStdio={false}
-        onClose={vi.fn()}
-        onSettingsChange={onSettingsChange}
-      />,
-    );
-    await user.click(screen.getByRole("button", { name: "Request Metadata" }));
-    // Both the header and metadata rows have a remove button; each is named
-    // for the row it belongs to, so no positional guess is needed.
-    await user.click(
-      screen.getByRole("button", {
-        name: "Remove metadata entry, userId, row 1",
-      }),
-    );
-    expect(onSettingsChange).toHaveBeenCalledWith({
-      ...initialSettings,
-      metadata: [],
-    });
-  });
-
-  it("calls onSettingsChange when typing in metadata key/value", async () => {
-    const user = userEvent.setup();
-    const onSettingsChange = vi.fn();
-    renderWithMantine(
-      <ServerSettingsModal
-        opened
-        settings={initialSettings}
-        serverType="streamable-http"
-        isStdio={false}
-        onClose={vi.fn()}
-        onSettingsChange={onSettingsChange}
-      />,
-    );
-    await user.click(screen.getByRole("button", { name: "Request Metadata" }));
-    const valueInput = screen.getByDisplayValue("u-1");
-    await user.type(valueInput, "9");
-    expect(onSettingsChange).toHaveBeenCalled();
-    const lastCall =
-      onSettingsChange.mock.calls[onSettingsChange.mock.calls.length - 1][0];
-    expect(lastCall.metadata[0].key).toBe("userId");
-  });
-
   it("calls onSettingsChange when changing timeouts", async () => {
     const user = userEvent.setup();
     const onSettingsChange = vi.fn();
@@ -703,20 +633,13 @@ describe("ServerSettingsModal", () => {
     expect(lastCall.headers[1]).toEqual({ key: "B", value: "2" });
   });
 
-  it("preserves sibling rows when editing one of several metadata entries", async () => {
+  it("replaces the whole metadata object when the JSON editor changes", async () => {
     const user = userEvent.setup();
     const onSettingsChange = vi.fn();
-    const twoMeta: InspectorServerSettings = {
-      ...emptySettings,
-      metadata: [
-        { key: "m1", value: "v1" },
-        { key: "m2", value: "v2" },
-      ],
-    };
     renderWithMantine(
       <ServerSettingsModal
         opened
-        settings={twoMeta}
+        settings={emptySettings}
         serverType="streamable-http"
         isStdio={false}
         onClose={vi.fn()}
@@ -724,9 +647,15 @@ describe("ServerSettingsModal", () => {
       />,
     );
     await user.click(screen.getByRole("button", { name: "Request Metadata" }));
-    await user.type(screen.getByDisplayValue("v1"), "x");
+    const editor = screen.getByLabelText("Request metadata JSON");
+    await user.clear(editor);
+    await user.type(editor, '{{"trace":{{"id":"abc"}}}');
     const lastCall = onSettingsChange.mock.calls.at(-1)?.[0];
-    expect(lastCall.metadata[1]).toEqual({ key: "m2", value: "v2" });
+    // The nested object arrives as an object, not a stringified one — the
+    // whole point of #1910.
+    expect(lastCall.metadata).toEqual({ trace: { id: "abc" } });
+    // Every other setting is carried through untouched.
+    expect(lastCall.headers).toEqual(emptySettings.headers);
   });
 
   it("preserves sibling rows when editing one of several roots", async () => {
diff --git a/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.tsx b/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.tsx
index e2af62f5..fbdfa7ee 100644
--- a/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.tsx
+++ b/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.tsx
@@ -5,6 +5,7 @@ import type {
   InspectorServerSettings,
   ModernLogLevel,
   OAuthSettings,
+  RequestMetadata,
   ServerProtocolEra,
   ServerType,
 } from "@inspector/core/mcp/types.js";
@@ -155,24 +156,7 @@ export function ServerSettingsModal({
     onSettingsChange({ ...settings, cwd: value });
   }
 
-  function handleAddMetadata() {
-    onSettingsChange({
-      ...settings,
-      metadata: [...settings.metadata, { key: "", value: "" }],
-    });
-  }
-
-  function handleRemoveMetadata(index: number) {
-    onSettingsChange({
-      ...settings,
-      metadata: settings.metadata.filter((_, i) => i !== index),
-    });
-  }
-
-  function handleMetadataChange(index: number, key: string, value: string) {
-    const metadata = settings.metadata.map((m, i) =>
-      i === index ? { key, value } : m,
-    );
+  function handleMetadataChange(metadata: RequestMetadata) {
     onSettingsChange({ ...settings, metadata });
   }
 
@@ -303,8 +287,6 @@ export function ServerSettingsModal({
             onRemoveEnv={handleRemoveEnv}
             onEnvChange={handleEnvChange}
             onCwdChange={handleCwdChange}
-            onAddMetadata={handleAddMetadata}
-            onRemoveMetadata={handleRemoveMetadata}
             onMetadataChange={handleMetadataChange}
             onTimeoutChange={handleTimeoutChange}
             onAutoRefreshChange={handleAutoRefreshChange}
diff --git a/clients/web/src/test/core/client/runner.test.ts b/clients/web/src/test/core/client/runner.test.ts
index 06dd0e1b..0c8660a4 100644
--- a/clients/web/src/test/core/client/runner.test.ts
+++ b/clients/web/src/test/core/client/runner.test.ts
@@ -76,7 +76,7 @@ describe("runner client auth options", () => {
       taskTtl: 60000,
       maxFetchRequests: 10,
       autoRefreshOnListChanged: false,
-      metadata: [],
+      metadata: {},
       headers: [],
       env: [],
       roots: [],
@@ -99,7 +99,7 @@ describe("runner client auth options", () => {
       taskTtl: 60000,
       maxFetchRequests: 10,
       autoRefreshOnListChanged: false,
-      metadata: [],
+      metadata: {},
       headers: [],
       env: [],
       roots: [],
@@ -116,7 +116,7 @@ describe("runner client auth options", () => {
       taskTtl: 60000,
       maxFetchRequests: 10,
       autoRefreshOnListChanged: false,
-      metadata: [],
+      metadata: {},
       headers: [],
       env: [],
       roots: [],
@@ -135,7 +135,7 @@ describe("runner client auth options", () => {
       taskTtl: 60000,
       maxFetchRequests: 10,
       autoRefreshOnListChanged: false,
-      metadata: [],
+      metadata: {},
       headers: [],
       env: [],
       roots: [],
@@ -156,7 +156,7 @@ describe("runner client auth options", () => {
       taskTtl: 60000,
       maxFetchRequests: 10,
       autoRefreshOnListChanged: false,
-      metadata: [],
+      metadata: {},
       headers: [],
       env: [],
       roots: [],
@@ -187,7 +187,7 @@ describe("runner client auth options", () => {
       taskTtl: 60000,
       maxFetchRequests: 10,
       autoRefreshOnListChanged: false,
-      metadata: [],
+      metadata: {},
       headers: [],
       env: [],
       roots: [],
diff --git a/clients/web/src/test/core/mcp/inspectorClient-peer-handler-timing.test.ts b/clients/web/src/test/core/mcp/inspectorClient-peer-handler-timing.test.ts
index 84f019cc..cfc22003 100644
--- a/clients/web/src/test/core/mcp/inspectorClient-peer-handler-timing.test.ts
+++ b/clients/web/src/test/core/mcp/inspectorClient-peer-handler-timing.test.ts
@@ -854,7 +854,7 @@ describe("InspectorClient peer-handler timing (#1797)", () => {
         serverSettings: {
           headers: [],
           env: [],
-          metadata: [],
+          metadata: {},
           connectionTimeout: 0,
           requestTimeout: 0,
           taskTtl: 0,
diff --git a/clients/web/src/test/core/mcp/node/servers.test.ts b/clients/web/src/test/core/mcp/node/servers.test.ts
index 05373af5..a54aaa8d 100644
--- a/clients/web/src/test/core/mcp/node/servers.test.ts
+++ b/clients/web/src/test/core/mcp/node/servers.test.ts
@@ -30,7 +30,7 @@ describe("headersToServerSettings", () => {
     expect(settings?.headers).toEqual([
       { key: "Authorization", value: "Bearer t" },
     ]);
-    expect(settings?.metadata).toEqual([]);
+    expect(settings?.metadata).toEqual({});
     expect(settings?.roots).toEqual([]);
   });
 });
diff --git a/clients/web/src/test/core/mcp/remote/remoteClientTransport.test.ts b/clients/web/src/test/core/mcp/remote/remoteClientTransport.test.ts
index c0478851..c2ddcc2a 100644
--- a/clients/web/src/test/core/mcp/remote/remoteClientTransport.test.ts
+++ b/clients/web/src/test/core/mcp/remote/remoteClientTransport.test.ts
@@ -361,7 +361,7 @@ describe("RemoteClientTransport", () => {
     const settings = {
       headers: [{ key: "X-Tenant", value: "acme" }],
       env: [],
-      metadata: [],
+      metadata: {},
       connectionTimeout: 0,
       requestTimeout: 0,
       taskTtl: 0,
diff --git a/clients/web/src/test/core/mcp/serverList.test.ts b/clients/web/src/test/core/mcp/serverList.test.ts
index 0492622d..13559751 100644
--- a/clients/web/src/test/core/mcp/serverList.test.ts
+++ b/clients/web/src/test/core/mcp/serverList.test.ts
@@ -11,6 +11,7 @@ import {
   mcpConfigToServerEntries,
   mergeSecretsIntoStored,
   normalizeServerType,
+  normalizeStoredMetadata,
   oauthAuthorizationParamsFromSettings,
   oauthEndpointOverridesFromSettings,
   serverEntriesToMcpConfig,
@@ -240,7 +241,7 @@ describe("serverEntriesToMcpConfig", () => {
   });
 
   it("round-trips a populated set of Inspector-extension fields (post-#1358 flat shape)", () => {
-    // Disk shape: top-level `headers` (Record), `metadata` (pair-array),
+    // Disk shape: top-level `headers` (Record), `metadata` (JSON object),
     // numeric timeouts, nested `oauth`. Round-trip must preserve the on-
     // disk shape byte-equivalent so a hand-edited file is stable.
     const original: MCPConfig = {
@@ -249,7 +250,7 @@ describe("serverEntriesToMcpConfig", () => {
           type: "streamable-http",
           url: "https://x.test/mcp",
           headers: { Authorization: "Bearer xyz" },
-          metadata: [{ key: "tenant", value: "acme" }],
+          metadata: { tenant: "acme", limits: { rps: 10 } },
           connectionTimeout: 30000,
           requestTimeout: 60000,
           oauth: {
@@ -581,7 +582,7 @@ describe("serverEntriesToMcpConfig", () => {
       headers: [{ key: "X-Tenant", value: "acme" }],
       // Non-stdio server → empty env mirror in memory (for the form)
       env: [],
-      metadata: [],
+      metadata: {},
       connectionTimeout: 0,
       requestTimeout: 0,
       // Absent taskTtl on disk → product default in memory (for the form)
@@ -663,7 +664,7 @@ describe("serverEntriesToMcpConfig", () => {
             { key: "   ", value: "whitespace" },
           ],
           env: [],
-          metadata: [],
+          metadata: {},
           connectionTimeout: 0,
           requestTimeout: 0,
           taskTtl: 0,
@@ -690,7 +691,7 @@ describe("serverEntriesToMcpConfig", () => {
         settings: {
           headers: [],
           env: [],
-          metadata: [],
+          metadata: {},
           connectionTimeout: 0,
           requestTimeout: 0,
           taskTtl: 0,
@@ -719,7 +720,7 @@ describe("serverEntriesToMcpConfig", () => {
         settings: {
           headers: [],
           env: [],
-          metadata: [],
+          metadata: {},
           connectionTimeout: 0,
           requestTimeout: 0,
           taskTtl: 0,
@@ -758,7 +759,7 @@ describe("serverEntriesToMcpConfig", () => {
         settings: {
           headers: [],
           env: [],
-          metadata: [],
+          metadata: {},
           connectionTimeout: 0,
           requestTimeout: 0,
           taskTtl: 0,
@@ -785,7 +786,7 @@ describe("serverEntriesToMcpConfig", () => {
         settings: {
           headers: [],
           env: [],
-          metadata: [],
+          metadata: {},
           connectionTimeout: 0,
           requestTimeout: 0,
           taskTtl: 0,
@@ -1163,7 +1164,7 @@ describe("enterpriseManaged oauth settings", () => {
     const stored = inspectorSettingsToStoredFields({
       headers: [],
       env: [],
-      metadata: [],
+      metadata: {},
       connectionTimeout: 0,
       requestTimeout: 0,
       taskTtl: 60000,
@@ -1180,7 +1181,7 @@ describe("enterpriseManaged oauth settings", () => {
     const stored = inspectorSettingsToStoredFields({
       headers: [],
       env: [],
-      metadata: [],
+      metadata: {},
       connectionTimeout: 0,
       requestTimeout: 0,
       taskTtl: 60000,
@@ -1196,7 +1197,7 @@ describe("oauthOnInsufficientScope (SEP-2350)", () => {
   const baseSettings = {
     headers: [],
     env: [],
-    metadata: [],
+    metadata: {},
     connectionTimeout: 0,
     requestTimeout: 0,
     taskTtl: 60000,
@@ -1374,6 +1375,109 @@ describe("oauthOnInsufficientScope (SEP-2350)", () => {
   });
 });
 
+describe("normalizeStoredMetadata (#1910)", () => {
+  let warn: ReturnType<typeof vi.spyOn>;
+  beforeEach(() => {
+    warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    warn.mockRestore();
+  });
+
+  it("passes an object through, values of any JSON type intact", () => {
+    const meta = {
+      s: "a",
+      n: 1,
+      b: false,
+      z: null,
+      arr: [1, { k: 2 }],
+      o: { deep: true },
+    };
+    expect(normalizeStoredMetadata(meta)).toEqual(meta);
+  });
+
+  it("copies rather than aliasing the stored object", () => {
+    // The settings object is edited in place by the form; sharing the
+    // reference with the parsed catalog would mutate it behind the caller.
+    const meta = { a: 1 };
+    const out = normalizeStoredMetadata(meta);
+    out.b = 2;
+    expect(meta).toEqual({ a: 1 });
+  });
+
+  it("reads the pre-#1910 pair array so an existing mcp.json keeps working", () => {
+    expect(
+      normalizeStoredMetadata([
+        { key: "tenant", value: "acme" },
+        { key: "n", value: 3 },
+      ]),
+    ).toEqual({ tenant: "acme", n: 3 });
+  });
+
+  it("skips a blank-key legacy pair", () => {
+    expect(
+      normalizeStoredMetadata([
+        { key: "", value: "orphan" },
+        { key: "  ", value: "orphan" },
+        { key: "kept", value: "yes" },
+      ]),
+    ).toEqual({ kept: "yes" });
+  });
+
+  it("reads a legacy pair with no value as an empty string", () => {
+    expect(normalizeStoredMetadata([{ key: "k" }])).toEqual({ k: "" });
+  });
+
+  it("drops a malformed legacy entry with a warning, keeping its siblings", () => {
+    expect(
+      normalizeStoredMetadata([
+        "nope",
+        null,
+        { value: "no key" },
+        { key: "kept", value: 1 },
+      ]),
+    ).toEqual({ kept: 1 });
+    expect(warn).toHaveBeenCalledTimes(3);
+  });
+
+  it.each([
+    ["undefined", undefined],
+    ["null", null],
+  ])("reads %s as the empty object without warning", (_label, input) => {
+    expect(normalizeStoredMetadata(input)).toEqual({});
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["a string", "oops"],
+    ["a number", 7],
+    ["a boolean", true],
+  ])("drops %s with a warning", (_label, input) => {
+    expect(normalizeStoredMetadata(input)).toEqual({});
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("migrates a legacy file to the object shape on the next write", () => {
+    // Read side accepts the pair array; write side emits only the object, so
+    // one round-trip is the migration.
+    const entries = mcpConfigToServerEntries({
+      mcpServers: {
+        legacy: {
+          type: "streamable-http",
+          url: "https://x.test/mcp",
+          metadata: [{ key: "tenant", value: "acme" }] as unknown as Record<
+            string,
+            never
+          >,
+        },
+      },
+    });
+    expect(entries[0]?.settings?.metadata).toEqual({ tenant: "acme" });
+    const round = serverEntriesToMcpConfig(entries);
+    expect(round.mcpServers.legacy?.metadata).toEqual({ tenant: "acme" });
+  });
+});
+
 describe("envRecordToPairs / envPairsToRecord", () => {
   it("envRecordToPairs preserves key insertion order", () => {
     expect(envRecordToPairs({ B: "2", A: "1" })).toEqual([
@@ -1469,7 +1573,7 @@ describe("stdio env / cwd mirroring", () => {
       headers: [],
       env: [{ key: "API_KEY", value: "secret" }],
       cwd: "/srv/app",
-      metadata: [],
+      metadata: {},
       connectionTimeout: 0,
       requestTimeout: 0,
       taskTtl: 60000,
diff --git a/clients/web/src/test/core/mcp/state/managedPromptsState.test.ts b/clients/web/src/test/core/mcp/state/managedPromptsState.test.ts
index 939af2ef..1d0717f9 100644
--- a/clients/web/src/test/core/mcp/state/managedPromptsState.test.ts
+++ b/clients/web/src/test/core/mcp/state/managedPromptsState.test.ts
@@ -13,7 +13,7 @@ function prompt(name: string): Prompt {
 const AUTO_REFRESH_SETTINGS: InspectorServerSettings = {
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 0,
   requestTimeout: 0,
   taskTtl: 60000,
diff --git a/clients/web/src/test/core/mcp/state/managedResourceTemplatesState.test.ts b/clients/web/src/test/core/mcp/state/managedResourceTemplatesState.test.ts
index be88cd5f..643b9f8a 100644
--- a/clients/web/src/test/core/mcp/state/managedResourceTemplatesState.test.ts
+++ b/clients/web/src/test/core/mcp/state/managedResourceTemplatesState.test.ts
@@ -13,7 +13,7 @@ function template(name: string): ResourceTemplate {
 const AUTO_REFRESH_SETTINGS: InspectorServerSettings = {
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 0,
   requestTimeout: 0,
   taskTtl: 60000,
diff --git a/clients/web/src/test/core/mcp/state/managedResourcesState.test.ts b/clients/web/src/test/core/mcp/state/managedResourcesState.test.ts
index 7944f3a4..15fb404a 100644
--- a/clients/web/src/test/core/mcp/state/managedResourcesState.test.ts
+++ b/clients/web/src/test/core/mcp/state/managedResourcesState.test.ts
@@ -13,7 +13,7 @@ function resource(uri: string): Resource {
 const AUTO_REFRESH_SETTINGS: InspectorServerSettings = {
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 0,
   requestTimeout: 0,
   taskTtl: 60000,
diff --git a/clients/web/src/test/core/mcp/state/managedToolsState.test.ts b/clients/web/src/test/core/mcp/state/managedToolsState.test.ts
index 8455dd74..f62118b6 100644
--- a/clients/web/src/test/core/mcp/state/managedToolsState.test.ts
+++ b/clients/web/src/test/core/mcp/state/managedToolsState.test.ts
@@ -13,7 +13,7 @@ function tool(name: string): Tool {
 const AUTO_REFRESH_SETTINGS: InspectorServerSettings = {
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 0,
   requestTimeout: 0,
   taskTtl: 60000,
diff --git a/clients/web/src/test/core/mcp/state/pagedPromptsState.test.ts b/clients/web/src/test/core/mcp/state/pagedPromptsState.test.ts
index b82828b8..715facf2 100644
--- a/clients/web/src/test/core/mcp/state/pagedPromptsState.test.ts
+++ b/clients/web/src/test/core/mcp/state/pagedPromptsState.test.ts
@@ -11,7 +11,7 @@ function prompt(name: string): Prompt {
 const PAGINATED_SETTINGS: InspectorServerSettings = {
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 0,
   requestTimeout: 0,
   taskTtl: 60000,
diff --git a/clients/web/src/test/core/mcp/state/pagedResourcesState.test.ts b/clients/web/src/test/core/mcp/state/pagedResourcesState.test.ts
index c8fee7e7..87c405f4 100644
--- a/clients/web/src/test/core/mcp/state/pagedResourcesState.test.ts
+++ b/clients/web/src/test/core/mcp/state/pagedResourcesState.test.ts
@@ -11,7 +11,7 @@ function resource(uri: string): Resource {
 const PAGINATED_SETTINGS: InspectorServerSettings = {
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 0,
   requestTimeout: 0,
   taskTtl: 60000,
diff --git a/clients/web/src/test/core/mcp/state/pagedToolsState.test.ts b/clients/web/src/test/core/mcp/state/pagedToolsState.test.ts
index b8ee12f5..463a304f 100644
--- a/clients/web/src/test/core/mcp/state/pagedToolsState.test.ts
+++ b/clients/web/src/test/core/mcp/state/pagedToolsState.test.ts
@@ -11,7 +11,7 @@ function tool(name: string): Tool {
 const PAGINATED_SETTINGS: InspectorServerSettings = {
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 0,
   requestTimeout: 0,
   taskTtl: 60000,
diff --git a/clients/web/src/test/core/react/useServers.test.tsx b/clients/web/src/test/core/react/useServers.test.tsx
index c0d5260c..15cb01fb 100644
--- a/clients/web/src/test/core/react/useServers.test.tsx
+++ b/clients/web/src/test/core/react/useServers.test.tsx
@@ -412,7 +412,7 @@ describe("useServers", () => {
       await result.current.updateServerSettings("alpha", {
         headers: [{ key: "X-Tenant", value: "acme" }],
         env: [],
-        metadata: [{ key: "trace", value: "abc" }],
+        metadata: { trace: "abc" },
         connectionTimeout: 5000,
         requestTimeout: 30000,
         taskTtl: 30000,
@@ -425,7 +425,7 @@ describe("useServers", () => {
       expect(result.current.servers[0]?.settings).toEqual({
         headers: [{ key: "X-Tenant", value: "acme" }],
         env: [],
-        metadata: [{ key: "trace", value: "abc" }],
+        metadata: { trace: "abc" },
         connectionTimeout: 5000,
         requestTimeout: 30000,
         taskTtl: 30000,
@@ -444,7 +444,7 @@ describe("useServers", () => {
     expect(stored.url).toBe("https://x.test/mcp");
     expect(stored).not.toHaveProperty("settings");
     expect(stored.headers).toEqual({ "X-Tenant": "acme" });
-    expect(stored.metadata).toEqual([{ key: "trace", value: "abc" }]);
+    expect(stored.metadata).toEqual({ trace: "abc" });
     expect(stored.connectionTimeout).toBe(5000);
     expect(stored.requestTimeout).toBe(30000);
     expect(stored.taskTtl).toBe(30000);
@@ -461,7 +461,7 @@ describe("useServers", () => {
         await result.current.updateServerSettings("nonexistent", {
           headers: [],
           env: [],
-          metadata: [],
+          metadata: {},
           connectionTimeout: 0,
           requestTimeout: 0,
           taskTtl: 0,
@@ -511,7 +511,7 @@ describe("useServers", () => {
     expect(result.current.servers[0]?.settings).toEqual({
       headers: [{ key: "X-Keep", value: "yes" }],
       env: [],
-      metadata: [],
+      metadata: {},
       connectionTimeout: 0,
       requestTimeout: 0,
       // Absent taskTtl on disk reads back as the product default for the form.
diff --git a/clients/web/src/test/integration/mcp/inspectorClient-coverage-backfill.test.ts b/clients/web/src/test/integration/mcp/inspectorClient-coverage-backfill.test.ts
index d873453c..d0067baf 100644
--- a/clients/web/src/test/integration/mcp/inspectorClient-coverage-backfill.test.ts
+++ b/clients/web/src/test/integration/mcp/inspectorClient-coverage-backfill.test.ts
@@ -389,7 +389,7 @@ describe("InspectorClient coverage backfill", () => {
           serverSettings: {
             headers: [],
             env: [],
-            metadata: [{ key: "x-test", value: "1" }],
+            metadata: { "x-test": "1" },
             connectionTimeout: 0,
             requestTimeout: 0,
             taskTtl: 0,
@@ -655,7 +655,7 @@ describe("InspectorClient coverage backfill", () => {
           serverSettings: {
             headers: [],
             env: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 1,
             requestTimeout: 0,
             taskTtl: 0,
diff --git a/clients/web/src/test/integration/mcp/inspectorClient-modern-era.test.ts b/clients/web/src/test/integration/mcp/inspectorClient-modern-era.test.ts
index cb346ec0..06b932d5 100644
--- a/clients/web/src/test/integration/mcp/inspectorClient-modern-era.test.ts
+++ b/clients/web/src/test/integration/mcp/inspectorClient-modern-era.test.ts
@@ -506,7 +506,7 @@ describe("modern-era negotiation (2026-07-28)", () => {
         versionNegotiation: eraToVersionNegotiation("modern"),
         serverSettings: {
           headers: [],
-          metadata: [],
+          metadata: {},
           env: [],
           connectionTimeout: 0,
           requestTimeout: 0,
@@ -535,7 +535,7 @@ describe("modern-era negotiation (2026-07-28)", () => {
         versionNegotiation: eraToVersionNegotiation("modern"),
         serverSettings: {
           headers: [],
-          metadata: [],
+          metadata: {},
           env: [],
           connectionTimeout: 0,
           requestTimeout: 0,
@@ -586,7 +586,7 @@ describe("modern-era negotiation (2026-07-28)", () => {
         versionNegotiation: eraToVersionNegotiation("modern"),
         serverSettings: {
           headers: [],
-          metadata: [],
+          metadata: {},
           env: [],
           connectionTimeout: 0,
           requestTimeout: 0,
diff --git a/clients/web/src/test/integration/mcp/inspectorClient.test.ts b/clients/web/src/test/integration/mcp/inspectorClient.test.ts
index 8c05b7ed..9fbb0608 100644
--- a/clients/web/src/test/integration/mcp/inspectorClient.test.ts
+++ b/clients/web/src/test/integration/mcp/inspectorClient.test.ts
@@ -53,6 +53,7 @@ import type {
   MessageEntry,
   ConnectionStatus,
   FetchRequestEntryBase,
+  RequestMetadata,
 } from "@inspector/core/mcp/types.js";
 import type { JsonValue } from "@inspector/core/json/jsonUtils.js";
 import type {
@@ -164,7 +165,7 @@ function settleInFlight(call: Promise<unknown>): InFlightCall {
 /** Get all resources from the client via listResources() (paginates if needed). */
 async function getAllResources(
   client: InspectorClient,
-  metadata?: Record<string, string>,
+  metadata?: RequestMetadata,
 ): Promise<Resource[]> {
   const collected: Resource[] = [];
   let cursor: string | undefined;
@@ -180,7 +181,7 @@ async function getAllResources(
 /** Get all resource templates via listResourceTemplates() (paginates if needed). */
 async function getAllResourceTemplates(
   client: InspectorClient,
-  metadata?: Record<string, string>,
+  metadata?: RequestMetadata,
 ): Promise<ResourceTemplate[]> {
   const collected: ResourceTemplate[] = [];
   let cursor: string | undefined;
@@ -196,7 +197,7 @@ async function getAllResourceTemplates(
 /** Get all prompts via listPrompts() (paginates if needed). */
 async function getAllPrompts(
   client: InspectorClient,
-  metadata?: Record<string, string>,
+  metadata?: RequestMetadata,
 ): Promise<Prompt[]> {
   const collected: Prompt[] = [];
   let cursor: string | undefined;
@@ -386,7 +387,7 @@ describe("InspectorClient", () => {
           serverSettings: {
             headers: [],
             env: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 50,
             requestTimeout: 0,
             taskTtl: 0,
@@ -756,7 +757,7 @@ describe("InspectorClient", () => {
       const initial = {
         headers: [],
         env: [],
-        metadata: [],
+        metadata: {},
         connectionTimeout: 0,
         requestTimeout: 0,
         taskTtl: 0,
@@ -1372,6 +1373,45 @@ describe("InspectorClient", () => {
       messageLogState.destroy();
     });
 
+    it("sends a structured default _meta value as JSON, not as a string (#1910)", async () => {
+      // The whole point of #1910: a `_meta` value may be an object, an array,
+      // a number, a boolean or `null`. The Inspector used to type this map as
+      // `Record<string, string>`, so a nested payload could only be sent by
+      // stringifying it — which is a different wire message than the one the
+      // user configured.
+      const structured = {
+        trace: { id: "abc123", sampled: true, hops: [1, 2] },
+        retries: 3,
+        beta: false,
+        unset: null,
+      };
+      client = new InspectorClient(
+        {
+          type: "stdio",
+          command: serverCommand.command,
+          args: serverCommand.args,
+        },
+        {
+          environment: { transport: createTransportNode },
+          defaultMetadata: structured,
+        },
+      );
+      const messageLogState = new MessageLogState(client);
+      await client.connect();
+      await client.listTools();
+
+      const listToolsReq = messageLogState
+        .getMessages()
+        .find(
+          (m) =>
+            m.direction === "request" &&
+            (m.message as { method?: string }).method === "tools/list",
+        );
+      expect(listToolsReq).toBeDefined();
+      expect(metaOf(listToolsReq!)).toMatchObject(structured);
+      messageLogState.destroy();
+    });
+
     it("call-time metadata overrides defaultMetadata on key collision", async () => {
       client = new InspectorClient(
         {
@@ -4241,7 +4281,7 @@ describe("InspectorClient", () => {
         timestamp: Date;
         success: boolean;
         error?: string;
-        metadata?: Record<string, string>;
+        metadata?: RequestMetadata;
       }> = [];
 
       client!.addEventListener(
diff --git a/clients/web/src/test/integration/mcp/node/transport.test.ts b/clients/web/src/test/integration/mcp/node/transport.test.ts
index af68081f..97cedc9e 100644
--- a/clients/web/src/test/integration/mcp/node/transport.test.ts
+++ b/clients/web/src/test/integration/mcp/node/transport.test.ts
@@ -218,7 +218,7 @@ describe("Transport", () => {
             { key: "", value: "ignored-empty-key" },
           ],
           env: [],
-          metadata: [],
+          metadata: {},
           connectionTimeout: 0,
           requestTimeout: 0,
           taskTtl: 0,
@@ -267,7 +267,7 @@ describe("Transport", () => {
       const baseSettings: InspectorServerSettings = {
         headers: [],
         env: [],
-        metadata: [],
+        metadata: {},
         connectionTimeout: 0,
         requestTimeout: 0,
         taskTtl: 0,
@@ -305,7 +305,7 @@ describe("Transport", () => {
         const settings: InspectorServerSettings = {
           headers: [{ key: "X-Tenant", value: "acme" }],
           env: [],
-          metadata: [],
+          metadata: {},
           connectionTimeout: 0,
           requestTimeout: 0,
           taskTtl: 0,
@@ -350,7 +350,7 @@ describe("Transport", () => {
       const settings: InspectorServerSettings = {
         headers: [],
         env: [],
-        metadata: [],
+        metadata: {},
         connectionTimeout: 0,
         requestTimeout: 0,
         taskTtl: 0,
diff --git a/clients/web/src/test/integration/mcp/remote/server-extra-coverage.test.ts b/clients/web/src/test/integration/mcp/remote/server-extra-coverage.test.ts
index e6140467..cd95f46d 100644
--- a/clients/web/src/test/integration/mcp/remote/server-extra-coverage.test.ts
+++ b/clients/web/src/test/integration/mcp/remote/server-extra-coverage.test.ts
@@ -457,7 +457,7 @@ describe("server.ts supplemental coverage", () => {
 
     const base = {
       headers: [],
-      metadata: [],
+      metadata: {},
       connectionTimeout: 0,
       requestTimeout: 0,
     };
@@ -891,7 +891,7 @@ describe("server.ts supplemental coverage", () => {
             config: { type: "streamable-http", url: "https://x.test/mcp" },
             settings: {
               headers: [],
-              metadata: [],
+              metadata: {},
               connectionTimeout: 0,
               requestTimeout: 0,
               oauthClientSecret: "shh",
@@ -1039,7 +1039,7 @@ describe("server.ts supplemental coverage", () => {
             config: { type: "streamable-http", url: "https://x.test/mcp" },
             settings: {
               headers: [],
-              metadata: [],
+              metadata: {},
               connectionTimeout: 0,
               requestTimeout: 0,
               oauthClientSecret: "new-secret",
diff --git a/clients/web/src/test/integration/mcp/remote/servers-route.test.ts b/clients/web/src/test/integration/mcp/remote/servers-route.test.ts
index 9862f55d..d0f9d407 100644
--- a/clients/web/src/test/integration/mcp/remote/servers-route.test.ts
+++ b/clients/web/src/test/integration/mcp/remote/servers-route.test.ts
@@ -425,10 +425,11 @@ describe("/api/servers routes", () => {
           // Wire envelope unchanged from #1353: pair-array headers, flat
           // oauth* fields. Backend splats these into the flat disk shape:
           // object headers, nested oauth, plus the inspector-only fields
-          // at the top level.
+          // at the top level. Metadata is the exception — it crosses as a
+          // JSON object, since a `_meta` value may be any JSON (#1910).
           settings: {
             headers: [{ key: "Authorization", value: "Bearer xyz" }],
-            metadata: [{ key: "tenant", value: "acme" }],
+            metadata: { tenant: "acme", limits: { rps: 10 } },
             connectionTimeout: 30000,
             requestTimeout: 60000,
             oauthClientId: "client-abc",
@@ -442,7 +443,7 @@ describe("/api/servers routes", () => {
       // Disk shape: flat, no `settings` wrapper, object headers, nested oauth.
       expect(stored).not.toHaveProperty("settings");
       expect(stored.headers).toEqual({ Authorization: "Bearer xyz" });
-      expect(stored.metadata).toEqual([{ key: "tenant", value: "acme" }]);
+      expect(stored.metadata).toEqual({ tenant: "acme", limits: { rps: 10 } });
       expect(stored.connectionTimeout).toBe(30000);
       expect(stored.requestTimeout).toBe(60000);
       expect(stored.oauth).toEqual({
@@ -462,7 +463,7 @@ describe("/api/servers routes", () => {
           config: { type: "streamable-http", url: "https://x.test/mcp" },
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             oauthAuthorizationParams: [
@@ -488,7 +489,7 @@ describe("/api/servers routes", () => {
           config: { type: "streamable-http", url: "https://x.test/mcp" },
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             oauthAuthorizationParams: { kc_idp_hint: "corp" },
@@ -509,7 +510,7 @@ describe("/api/servers routes", () => {
           config: { type: "streamable-http", url: "https://x.test/mcp" },
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             oauthAuthorizationUrl: "https://staging.test/authorize",
@@ -534,7 +535,7 @@ describe("/api/servers routes", () => {
           config: { type: "streamable-http", url: "https://x.test/mcp" },
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             oauthAuthorizationUrl: "",
@@ -557,7 +558,7 @@ describe("/api/servers routes", () => {
           config: { type: "streamable-http", url: "https://x.test/mcp" },
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             oauthTokenUrl: 42,
@@ -583,7 +584,7 @@ describe("/api/servers routes", () => {
           config: { type: "streamable-http", url: "https://x.test/mcp" },
           settings: {
             headers: [{ key: "X-Tenant", value: "acme" }],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 45000,
           },
@@ -617,7 +618,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             autoRefreshOnListChanged: true,
@@ -649,7 +650,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             autoRefreshOnListChanged: false,
@@ -671,7 +672,7 @@ describe("/api/servers routes", () => {
           config: { type: "stdio", command: "node" },
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             autoRefreshOnListChanged: "yes",
@@ -696,7 +697,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             maxFetchRequests: 5000,
@@ -724,7 +725,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             maxFetchRequests: 0,
@@ -756,7 +757,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             maxFetchRequests: 1000,
@@ -778,7 +779,7 @@ describe("/api/servers routes", () => {
           config: { type: "stdio", command: "node" },
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             maxFetchRequests: -5,
@@ -884,7 +885,7 @@ describe("/api/servers routes", () => {
           // headers should be an array of {key, value}; "oops" is a string.
           settings: {
             headers: "oops",
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
           },
@@ -915,7 +916,7 @@ describe("/api/servers routes", () => {
           // write lock and apply only the settings patch.
           settings: {
             headers: [{ key: "X-Tenant", value: "acme" }],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
           },
@@ -957,7 +958,7 @@ describe("/api/servers routes", () => {
           config: { type: "streamable-http", url: "https://x.test/mcp" },
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             oauthClientId: "",
@@ -983,7 +984,7 @@ describe("/api/servers routes", () => {
           config: { type: "stdio", command: "node" },
           settings: {
             headers: [{ key: "X-A", value: "1" }],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             // Unknown stowaway — must not survive the validator.
@@ -1101,7 +1102,7 @@ describe("/api/servers routes", () => {
               url: "https://x.test/mcp",
               settings: {
                 headers: [{ key: "X-Tenant", value: "acme" }],
-                metadata: [],
+                metadata: {},
                 connectionTimeout: 30000,
                 requestTimeout: 0,
                 oauthClientId: "client-abc",
@@ -1207,7 +1208,7 @@ describe("/api/servers routes", () => {
           config: { type: "stdio", command: "node" },
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             roots: [
@@ -1255,7 +1256,7 @@ describe("/api/servers routes", () => {
           config: { type: "stdio", command: "node" },
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             roots: [{ uri: "  " }],
@@ -1285,7 +1286,7 @@ describe("/api/servers routes", () => {
           config: { type: "stdio", command: "node" },
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             // uri must be a string.
@@ -1336,7 +1337,7 @@ describe("/api/servers routes", () => {
               { key: "Authorization", value: "Bearer the-token" },
               { key: "X-Tenant", value: "acme" },
             ],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
           },
@@ -1368,7 +1369,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             env: [{ key: "API_KEY", value: "abc-123" }],
@@ -1416,7 +1417,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 5000,
             requestTimeout: 0,
           },
@@ -1484,7 +1485,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             env: [],
@@ -1516,7 +1517,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             env: [
@@ -1587,7 +1588,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             env: "nope",
@@ -1614,7 +1615,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             env: [],
@@ -1642,7 +1643,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             env: [],
@@ -1675,7 +1676,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             env: [{ key: "API_KEY", value: "abc" }],
@@ -1775,7 +1776,7 @@ describe("/api/servers routes", () => {
           config: { type: "streamable-http", url: "https://x.test/mcp" },
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             oauthClientId: "cid",
@@ -1935,7 +1936,7 @@ describe("/api/servers routes", () => {
         body: JSON.stringify({
           settings: {
             headers: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 0,
             requestTimeout: 0,
             oauthClientId: "cid",
@@ -2327,7 +2328,7 @@ describe("/api/servers routes", () => {
             config: { type: "streamable-http", url: "https://x.test/mcp" },
             settings: {
               headers: [],
-              metadata: [],
+              metadata: {},
               connectionTimeout: 0,
               requestTimeout: 0,
               oauthClientId: "cid",
@@ -2361,7 +2362,7 @@ describe("/api/servers routes", () => {
             config: { type: "streamable-http", url: "https://x.test/mcp" },
             settings: {
               headers: [],
-              metadata: [],
+              metadata: {},
               connectionTimeout: 0,
               requestTimeout: 0,
               oauthClientId: "cid",
@@ -2658,7 +2659,7 @@ describe("a config-only PUT must not delete stored secrets (#2083)", () => {
           settings: {
             headers: [],
             env: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 30000,
             requestTimeout: 60000,
             taskTtl: 60000,
@@ -2726,7 +2727,7 @@ describe("a config-only PUT must not delete stored secrets (#2083)", () => {
           settings: {
             headers: [],
             env: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 30000,
             requestTimeout: 60000,
             taskTtl: 60000,
@@ -2879,7 +2880,7 @@ describe("plaintext migration against a session-scoped store (#1950)", () => {
           settings: {
             headers: [],
             env: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 45000,
             requestTimeout: 60000,
             taskTtl: 60000,
@@ -2927,7 +2928,7 @@ describe("plaintext migration against a session-scoped store (#1950)", () => {
           settings: {
             headers: [],
             env: [],
-            metadata: [],
+            metadata: {},
             connectionTimeout: 30000,
             requestTimeout: 60000,
             taskTtl: 60000,
diff --git a/clients/web/src/test/integration/mcp/remote/transport.test.ts b/clients/web/src/test/integration/mcp/remote/transport.test.ts
index 2e2b55ec..98feef7e 100644
--- a/clients/web/src/test/integration/mcp/remote/transport.test.ts
+++ b/clients/web/src/test/integration/mcp/remote/transport.test.ts
@@ -412,7 +412,7 @@ describe("Remote transport e2e", () => {
           { key: "X-Trace", value: "abc123" },
         ],
         env: [],
-        metadata: [],
+        metadata: {},
         connectionTimeout: 0,
         requestTimeout: 0,
         taskTtl: 0,
diff --git a/core/mcp/__tests__/fakeInspectorClient.ts b/core/mcp/__tests__/fakeInspectorClient.ts
index 728ef5f7..8e3519e9 100644
--- a/core/mcp/__tests__/fakeInspectorClient.ts
+++ b/core/mcp/__tests__/fakeInspectorClient.ts
@@ -36,6 +36,7 @@ import type {
   ResourceSubscriptionStreamState,
   ToolCallInvocation,
   ExcludedTool,
+  RequestMetadata,
 } from "../types.js";
 import { INACTIVE_SUBSCRIPTION_STREAM_STATE } from "../types.js";
 import type { MalformedListItem } from "../listSalvage.js";
@@ -145,25 +146,25 @@ export class FakeInspectorClient
   listAllTools = vi.fn(
     async (_options?: {
       cacheMode?: CacheMode;
-      metadata?: Record<string, string>;
+      metadata?: RequestMetadata;
     }) => ({ tools: drainPages(this.toolPages, "tools") }),
   );
   listAllPrompts = vi.fn(
     async (_options?: {
       cacheMode?: CacheMode;
-      metadata?: Record<string, string>;
+      metadata?: RequestMetadata;
     }) => ({ prompts: drainPages(this.promptPages, "prompts") }),
   );
   listAllResources = vi.fn(
     async (_options?: {
       cacheMode?: CacheMode;
-      metadata?: Record<string, string>;
+      metadata?: RequestMetadata;
     }) => ({ resources: drainPages(this.resourcePages, "resources") }),
   );
   listAllResourceTemplates = vi.fn(
     async (_options?: {
       cacheMode?: CacheMode;
-      metadata?: Record<string, string>;
+      metadata?: RequestMetadata;
     }) => ({
       resourceTemplates: drainPages(
         this.resourceTemplatePages,
@@ -224,7 +225,7 @@ export class FakeInspectorClient
       _argumentName: string,
       _argumentValue: string,
       _context?: Record<string, string>,
-      _metadata?: Record<string, string>,
+      _metadata?: RequestMetadata,
     ): Promise<{ values: string[]; total?: number; hasMore?: boolean }> => ({
       values: [],
     }),
diff --git a/core/mcp/inspectorClient.ts b/core/mcp/inspectorClient.ts
index fb0ad80e..c4ad06db 100644
--- a/core/mcp/inspectorClient.ts
+++ b/core/mcp/inspectorClient.ts
@@ -17,6 +17,7 @@ import type {
   PendingRequestOrigin,
   ResourceSubscriptionStreamState,
   ExcludedTool,
+  RequestMetadata,
 } from "./types.js";
 import {
   scanXMcpHeaderDeclarations,
@@ -356,8 +357,8 @@ function notificationMethodFromSchema(schema: unknown): string | undefined {
 interface ToolCallRequest {
   tool: Tool;
   args: Record<string, JsonValue>;
-  generalMetadata?: Record<string, string>;
-  toolSpecificMetadata?: Record<string, string>;
+  generalMetadata?: RequestMetadata;
+  toolSpecificMetadata?: RequestMetadata;
   taskOptions?: { ttl?: number };
   options?: { skipOutputValidation?: boolean };
 }
@@ -420,7 +421,7 @@ export class InspectorClient extends InspectorClientEventTarget {
   private progress: boolean;
   private resetTimeoutOnProgress: boolean;
   private requestTimeout: number | undefined;
-  private defaultMetadata: Record<string, string> | undefined;
+  private defaultMetadata: RequestMetadata | undefined;
   private serverSettings: InspectorServerSettings | undefined;
   private versionNegotiation: VersionNegotiationOptions;
   private status: ConnectionStatus = "disconnected";
@@ -1035,7 +1036,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    * injecting an empty `_meta` field.
    */
   private mergeMeta(
-    callMetadata?: Record<string, string>,
+    callMetadata?: RequestMetadata,
   ): Record<string, string> | undefined {
     const defaults = this.defaultMetadata;
     // Modern-era per-request log level (#1629): stamp the opt-in `_meta` key on
@@ -1055,6 +1056,26 @@ export class InspectorClient extends InspectorClientEventTarget {
     return Object.keys(merged).length > 0 ? merged : undefined;
   }
 
+  /**
+   * The `progressToken` a caller stamped on its request metadata, when it is
+   * one the SDK will accept.
+   *
+   * `_meta` values are arbitrary JSON (#1910), but `progressToken` is a
+   * reserved key the spec types as `string | number`. Anything else — an
+   * object, an array, `null`, a boolean — is not a token the SDK can correlate
+   * a `notifications/progress` back to, so it is read as "no token" rather than
+   * forwarded. The key still reaches the wire inside `_meta`; this only governs
+   * whether the client wires up a progress callback for it.
+   */
+  private progressTokenOf(
+    metadata: RequestMetadata | undefined,
+  ): ProgressToken | undefined {
+    const token = metadata?.progressToken;
+    return typeof token === "string" || typeof token === "number"
+      ? token
+      : undefined;
+  }
+
   private getRequestOptions(
     progressToken?: ProgressToken,
     signal?: AbortSignal,
@@ -1110,7 +1131,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    * so the merge/omit branch is defined once.
    */
   private aggregateListParams(
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): { _meta: Record<string, string> } | undefined {
     const effectiveMeta = this.mergeMeta(metadata);
     return effectiveMeta ? { _meta: effectiveMeta } : undefined;
@@ -3405,7 +3426,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    */
   async listTools(
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<{ tools: Tool[]; nextCursor?: string }> {
     if (!this.client) {
       throw new Error("Client is not connected");
@@ -3423,7 +3444,7 @@ export class InspectorClient extends InspectorClientEventTarget {
       this.client!.request(
         { method: "tools/list", params },
         ListToolsResultSchema,
-        this.getRequestOptions(metadata?.progressToken),
+        this.getRequestOptions(this.progressTokenOf(metadata)),
       ),
     );
     const tools = [...(response.tools || [])];
@@ -3444,7 +3465,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    */
   async listAllTools(options?: {
     cacheMode?: CacheMode;
-    metadata?: Record<string, string>;
+    metadata?: RequestMetadata;
   }): Promise<{ tools: Tool[] }> {
     if (!this.client) {
       throw new Error("Client is not connected");
@@ -3596,7 +3617,7 @@ export class InspectorClient extends InspectorClientEventTarget {
      *  from it so every field except the entries is still validated. */
     resultSchema: z.ZodObject;
     aggregate: () => Promise<T[]>;
-    metadata?: Record<string, string>;
+    metadata?: RequestMetadata;
     /**
      * Filter applied to SALVAGED entries only, to reproduce a filter the SDK's
      * strict aggregate applies for us. Without it the fallback would return a
@@ -3674,7 +3695,7 @@ export class InspectorClient extends InspectorClientEventTarget {
     itemsKey: string;
     itemSchema: z.ZodType<T>;
     resultSchema: z.ZodObject;
-    metadata?: Record<string, string>;
+    metadata?: RequestMetadata;
     err: unknown;
   }): Promise<T[]> {
     const pageSchema = lenientListPageSchema(resultSchema, itemsKey);
@@ -3725,7 +3746,7 @@ export class InspectorClient extends InspectorClientEventTarget {
               : this.client!.request(
                   { method, params },
                   pageSchema,
-                  this.getRequestOptions(metadata?.progressToken),
+                  this.getRequestOptions(this.progressTokenOf(metadata)),
                 ),
           { method },
         );
@@ -3811,7 +3832,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    * stops the walk (non-converging-server guard, mirroring the SDK).
    */
   async refreshExcludedTools(
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<ExcludedTool[]> {
     const excluded: ExcludedTool[] = [];
     // Gated to connections that actually exclude; otherwise this is a pure
@@ -3881,7 +3902,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    */
   private async listToolsForScan(
     cursor: string | undefined,
-    metadata: Record<string, string> | undefined,
+    metadata: RequestMetadata | undefined,
   ): Promise<{
     tools: Tool[];
     nextCursor?: string;
@@ -3924,7 +3945,7 @@ export class InspectorClient extends InspectorClientEventTarget {
               : this.client!.request(
                   { method: "tools/list", params },
                   pageSchema,
-                  this.getRequestOptions(metadata?.progressToken),
+                  this.getRequestOptions(this.progressTokenOf(metadata)),
                 ),
           { method: "tools/list" },
         );
@@ -4016,8 +4037,8 @@ export class InspectorClient extends InspectorClientEventTarget {
   async callTool(
     tool: Tool,
     args: Record<string, JsonValue>,
-    generalMetadata?: Record<string, string>,
-    toolSpecificMetadata?: Record<string, string>,
+    generalMetadata?: RequestMetadata,
+    toolSpecificMetadata?: RequestMetadata,
     taskOptions?: { ttl?: number },
     options?: { skipOutputValidation?: boolean },
   ): Promise<ToolCallInvocation> {
@@ -4245,7 +4266,7 @@ export class InspectorClient extends InspectorClientEventTarget {
     const convertedArgs = this.convertStringToolArgs(tool, args);
 
     // Merge general metadata with tool-specific metadata; tool-specific wins.
-    const callMetadata: Record<string, string> | undefined =
+    const callMetadata: RequestMetadata | undefined =
       generalMetadata || toolSpecificMetadata
         ? { ...(generalMetadata || {}), ...(toolSpecificMetadata || {}) }
         : undefined;
@@ -4270,7 +4291,7 @@ export class InspectorClient extends InspectorClientEventTarget {
     }
 
     const requestOptions = this.getRequestOptions(
-      metadata?.progressToken,
+      this.progressTokenOf(metadata),
       signal,
     );
     this.applyMirroredParamHeaders(tool, convertedArgs, requestOptions);
@@ -4360,11 +4381,11 @@ export class InspectorClient extends InspectorClientEventTarget {
   private dispatchFailedToolCall(
     tool: Tool,
     args: Record<string, JsonValue>,
-    generalMetadata: Record<string, string> | undefined,
-    toolSpecificMetadata: Record<string, string> | undefined,
+    generalMetadata: RequestMetadata | undefined,
+    toolSpecificMetadata: RequestMetadata | undefined,
     errorMessage: string,
   ): void {
-    const callMetadata: Record<string, string> | undefined =
+    const callMetadata: RequestMetadata | undefined =
       generalMetadata || toolSpecificMetadata
         ? { ...(generalMetadata || {}), ...(toolSpecificMetadata || {}) }
         : undefined;
@@ -4848,8 +4869,8 @@ export class InspectorClient extends InspectorClientEventTarget {
   async callToolStream(
     tool: Tool,
     args: Record<string, JsonValue>,
-    generalMetadata?: Record<string, string>,
-    toolSpecificMetadata?: Record<string, string>,
+    generalMetadata?: RequestMetadata,
+    toolSpecificMetadata?: RequestMetadata,
     taskOptions?: { ttl?: number },
   ): Promise<ToolCallInvocation> {
     if (!this.client) {
@@ -4859,7 +4880,7 @@ export class InspectorClient extends InspectorClientEventTarget {
       const convertedArgs = this.convertStringToolArgs(tool, args);
 
       // Merge general metadata with tool-specific metadata; tool-specific wins.
-      const callMetadata: Record<string, string> | undefined =
+      const callMetadata: RequestMetadata | undefined =
         generalMetadata || toolSpecificMetadata
           ? { ...(generalMetadata || {}), ...(toolSpecificMetadata || {}) }
           : undefined;
@@ -4895,7 +4916,9 @@ export class InspectorClient extends InspectorClientEventTarget {
       // attach one here either — doing so would request a progress token (and
       // emit requestorTaskProgress) for task calls only, bypassing the toggle
       // that governs every other call path.
-      const requestOptions = this.getRequestOptions(metadata?.progressToken);
+      const requestOptions = this.getRequestOptions(
+        this.progressTokenOf(metadata),
+      );
       // The task-augmented `tools/call` needs the same SEP-2243 mirroring as the
       // plain one — a strict modern server rejects it with -32020 otherwise.
       this.applyMirroredParamHeaders(tool, convertedArgs, requestOptions);
@@ -5056,7 +5079,7 @@ export class InspectorClient extends InspectorClientEventTarget {
       return invocation;
     } catch (error) {
       // Merge general metadata with tool-specific metadata for error case
-      const callMetadata: Record<string, string> | undefined =
+      const callMetadata: RequestMetadata | undefined =
         generalMetadata || toolSpecificMetadata
           ? { ...(generalMetadata || {}), ...(toolSpecificMetadata || {}) }
           : undefined;
@@ -5086,7 +5109,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    */
   async listResources(
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<{ resources: Resource[]; nextCursor?: string }> {
     if (!this.client) {
       throw new Error("Client is not connected");
@@ -5100,7 +5123,7 @@ export class InspectorClient extends InspectorClientEventTarget {
       this.client!.request(
         { method: "resources/list", params },
         ListResourcesResultSchema,
-        this.getRequestOptions(metadata?.progressToken),
+        this.getRequestOptions(this.progressTokenOf(metadata)),
       ),
     );
     return {
@@ -5117,7 +5140,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    */
   async listAllResources(options?: {
     cacheMode?: CacheMode;
-    metadata?: Record<string, string>;
+    metadata?: RequestMetadata;
   }): Promise<{ resources: Resource[] }> {
     if (!this.client) {
       throw new Error("Client is not connected");
@@ -5148,7 +5171,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    */
   async readResource(
     uri: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<ResourceReadInvocation> {
     if (!this.client) {
       throw new Error("Client is not connected");
@@ -5167,7 +5190,7 @@ export class InspectorClient extends InspectorClientEventTarget {
           "resources/read",
           params,
           ReadResourceResultSchema,
-          this.getRequestOptions(metadata?.progressToken),
+          this.getRequestOptions(this.progressTokenOf(metadata)),
         ),
       { method: "resources/read" },
     );
@@ -5198,7 +5221,7 @@ export class InspectorClient extends InspectorClientEventTarget {
   async readResourceFromTemplate(
     uriTemplate: string,
     params: Record<string, string>,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<ResourceTemplateReadInvocation> {
     if (!this.client) {
       throw new Error("Client is not connected");
@@ -5260,7 +5283,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    */
   async listResourceTemplates(
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<{ resourceTemplates: ResourceTemplate[]; nextCursor?: string }> {
     if (!this.client) {
       throw new Error("Client is not connected");
@@ -5275,7 +5298,7 @@ export class InspectorClient extends InspectorClientEventTarget {
         this.client!.request(
           { method: "resources/templates/list", params },
           ListResourceTemplatesResultSchema,
-          this.getRequestOptions(metadata?.progressToken),
+          this.getRequestOptions(this.progressTokenOf(metadata)),
         ),
       { method: "resources/templates/list" },
     );
@@ -5293,7 +5316,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    */
   async listAllResourceTemplates(options?: {
     cacheMode?: CacheMode;
-    metadata?: Record<string, string>;
+    metadata?: RequestMetadata;
   }): Promise<{ resourceTemplates: ResourceTemplate[] }> {
     if (!this.client) {
       throw new Error("Client is not connected");
@@ -5324,7 +5347,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    */
   async listPrompts(
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<{ prompts: Prompt[]; nextCursor?: string }> {
     if (!this.client) {
       throw new Error("Client is not connected");
@@ -5338,7 +5361,7 @@ export class InspectorClient extends InspectorClientEventTarget {
       this.client!.request(
         { method: "prompts/list", params },
         ListPromptsResultSchema,
-        this.getRequestOptions(metadata?.progressToken),
+        this.getRequestOptions(this.progressTokenOf(metadata)),
       ),
     );
     return {
@@ -5355,7 +5378,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    */
   async listAllPrompts(options?: {
     cacheMode?: CacheMode;
-    metadata?: Record<string, string>;
+    metadata?: RequestMetadata;
   }): Promise<{ prompts: Prompt[] }> {
     if (!this.client) {
       throw new Error("Client is not connected");
@@ -5388,7 +5411,7 @@ export class InspectorClient extends InspectorClientEventTarget {
   async getPrompt(
     name: string,
     args?: Record<string, JsonValue>,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<PromptGetInvocation> {
     if (!this.client) {
       throw new Error("Client is not connected");
@@ -5412,7 +5435,7 @@ export class InspectorClient extends InspectorClientEventTarget {
           "prompts/get",
           params,
           GetPromptResultSchema,
-          this.getRequestOptions(metadata?.progressToken),
+          this.getRequestOptions(this.progressTokenOf(metadata)),
         ),
       { method: "prompts/get", toolName: name },
     );
@@ -5451,7 +5474,7 @@ export class InspectorClient extends InspectorClientEventTarget {
     argumentName: string,
     argumentValue: string,
     context?: Record<string, string>,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<{ values: string[]; total?: number; hasMore?: boolean }> {
     if (!this.client) {
       return { values: [] };
@@ -5473,7 +5496,7 @@ export class InspectorClient extends InspectorClientEventTarget {
         () =>
           this.client!.complete(
             params,
-            this.getRequestOptions(metadata?.progressToken),
+            this.getRequestOptions(this.progressTokenOf(metadata)),
           ),
         {
           method: "completion/complete",
diff --git a/core/mcp/inspectorClientEventTarget.ts b/core/mcp/inspectorClientEventTarget.ts
index 572909c8..58aa41f6 100644
--- a/core/mcp/inspectorClientEventTarget.ts
+++ b/core/mcp/inspectorClientEventTarget.ts
@@ -25,6 +25,7 @@ import type {
   ResourceTemplateReadInvocation,
   ResourceSubscriptionStreamState,
   ExcludedTool,
+  RequestMetadata,
 } from "./types.js";
 import type { MalformedListItem } from "./listSalvage.js";
 import type {
@@ -112,7 +113,7 @@ export interface InspectorClientEventMap {
     timestamp: Date;
     success: boolean;
     error?: string;
-    metadata?: Record<string, string>;
+    metadata?: RequestMetadata;
     /** Non-fatal outputSchema mismatch detected on the skipOutputValidation path. */
     outputValidationError?: string;
   };
diff --git a/core/mcp/inspectorClientProtocol.ts b/core/mcp/inspectorClientProtocol.ts
index 756b560f..ef290f9e 100644
--- a/core/mcp/inspectorClientProtocol.ts
+++ b/core/mcp/inspectorClientProtocol.ts
@@ -21,6 +21,7 @@ import type {
   ToolCallInvocation,
   ResourceSubscriptionStreamState,
   ExcludedTool,
+  RequestMetadata,
 } from "./types.js";
 import type {
   CacheMode,
@@ -82,19 +83,19 @@ export interface InspectorClientProtocol extends InspectorClientEventTarget {
   // Paginated list methods used by managed/paged state stores
   listTools(
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<{ tools: Tool[]; nextCursor?: string }>;
   listPrompts(
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<{ prompts: Prompt[]; nextCursor?: string }>;
   listResources(
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<{ resources: Resource[]; nextCursor?: string }>;
   listResourceTemplates(
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<{ resourceTemplates: ResourceTemplate[]; nextCursor?: string }>;
   listRequestorTasks(
     cursor?: string,
@@ -126,41 +127,41 @@ export interface InspectorClientProtocol extends InspectorClientEventTarget {
   // `cacheMode` uses the SDK default ('use').
   listAllTools(options?: {
     cacheMode?: CacheMode;
-    metadata?: Record<string, string>;
+    metadata?: RequestMetadata;
   }): Promise<{ tools: Tool[] }>;
   listAllPrompts(options?: {
     cacheMode?: CacheMode;
-    metadata?: Record<string, string>;
+    metadata?: RequestMetadata;
   }): Promise<{ prompts: Prompt[] }>;
   listAllResources(options?: {
     cacheMode?: CacheMode;
-    metadata?: Record<string, string>;
+    metadata?: RequestMetadata;
   }): Promise<{ resources: Resource[] }>;
   listAllResourceTemplates(options?: {
     cacheMode?: CacheMode;
-    metadata?: Record<string, string>;
+    metadata?: RequestMetadata;
   }): Promise<{ resourceTemplates: ResourceTemplate[] }>;
 
   // Invocation methods used by paged result panels
   callTool(
     tool: Tool,
     args: Record<string, JsonValue>,
-    generalMetadata?: Record<string, string>,
-    toolSpecificMetadata?: Record<string, string>,
+    generalMetadata?: RequestMetadata,
+    toolSpecificMetadata?: RequestMetadata,
   ): Promise<ToolCallInvocation>;
   readResource(
     uri: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<ResourceReadInvocation>;
   readResourceFromTemplate(
     uriTemplate: string,
     params: Record<string, string>,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<ResourceTemplateReadInvocation>;
   getPrompt(
     name: string,
     params?: Record<string, string>,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<PromptGetInvocation>;
 
   // Misc surface required by hooks/state
@@ -182,6 +183,6 @@ export interface InspectorClientProtocol extends InspectorClientEventTarget {
     argumentName: string,
     argumentValue: string,
     context?: Record<string, string>,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<{ values: string[]; total?: number; hasMore?: boolean }>;
 }
diff --git a/core/mcp/node/servers.ts b/core/mcp/node/servers.ts
index 9e10c69a..2f296c12 100644
--- a/core/mcp/node/servers.ts
+++ b/core/mcp/node/servers.ts
@@ -49,7 +49,7 @@ export function headersToServerSettings(
   return {
     headers: Object.entries(headers).map(([key, value]) => ({ key, value })),
     env: [],
-    metadata: [],
+    metadata: {},
     connectionTimeout: 0,
     requestTimeout: 0,
     taskTtl: DEFAULT_TASK_TTL_MS,
diff --git a/core/mcp/remote/node/server.ts b/core/mcp/remote/node/server.ts
index 6f778c66..0b3bffe5 100644
--- a/core/mcp/remote/node/server.ts
+++ b/core/mcp/remote/node/server.ts
@@ -41,6 +41,7 @@ import {
 } from "../../types.js";
 import type {
   InspectorServerSettings,
+  RequestMetadata,
   MCPConfig,
   MCPServerConfig,
   StdioServerConfig,
@@ -1212,6 +1213,11 @@ export function createRemoteApp(
   // credentials are intentionally lost on first read (hard cutover per
   // #1358 decision 4). Users re-enter via the form or hand-edit into the
   // flat shape.
+  // A plain JSON object — the container `_meta` requires. Values are
+  // deliberately unchecked: `_meta` takes arbitrary JSON (#1910), and anything
+  // that survived `JSON.parse` already is.
+  const isJsonObject = (v: unknown): v is RequestMetadata =>
+    v !== null && typeof v === "object" && !Array.isArray(v);
   const isStringRecord = (v: unknown): v is Record<string, string> => {
     if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
     for (const val of Object.values(v as Record<string, unknown>)) {
@@ -1324,10 +1330,18 @@ export function createRemoteApp(
         );
         delete valObj.headers;
       }
-      if ("metadata" in valObj && !isKvArray(valObj.metadata)) {
+      // A JSON object post-#1910; the pre-#1910 `{ key, value }[]` pair array
+      // is still accepted so an existing file keeps working (it is normalized
+      // by `normalizeStoredMetadata` on the way into the settings shape, and
+      // rewritten as an object on the next save).
+      if (
+        "metadata" in valObj &&
+        !isJsonObject(valObj.metadata) &&
+        !isKvArray(valObj.metadata)
+      ) {
         logWarn(
           { route: "/api/servers", id, droppedKey: "metadata" },
-          "Dropping malformed `metadata` field — expected `Array<{ key: string, value: string }>`.",
+          "Dropping malformed `metadata` field — expected a JSON object.",
         );
         delete valObj.metadata;
       }
@@ -1556,10 +1570,14 @@ export function createRemoteApp(
         error: "settings.headers must be an array of { key, value }",
       };
     }
-    if (!isKvArray(obj.metadata)) {
+    // `_meta` takes any JSON, so metadata crosses the wire as a plain JSON
+    // object rather than the `{ key, value }` rows headers/env still use
+    // (#1910). Only the container is checked — the values are arbitrary JSON
+    // by design, and anything that survived `c.req.json()` already is.
+    if (!isJsonObject(obj.metadata)) {
       return {
         ok: false,
-        error: "settings.metadata must be an array of { key, value }",
+        error: "settings.metadata must be a JSON object",
       };
     }
     // env is optional on the wire (older clients / non-stdio servers won't send
@@ -1735,7 +1753,7 @@ export function createRemoteApp(
       // Absent → empty list, matching the read side. The write-through drops
       // empty-key rows and clears `config.env` when the list is empty.
       env: isKvArray(obj.env) ? obj.env : [],
-      metadata: obj.metadata as { key: string; value: string }[],
+      metadata: obj.metadata as RequestMetadata,
       connectionTimeout: obj.connectionTimeout as number,
       requestTimeout: obj.requestTimeout as number,
       // Absent → product default, matching the read side
diff --git a/core/mcp/serverList.ts b/core/mcp/serverList.ts
index f4be5f4a..5f4b10bc 100644
--- a/core/mcp/serverList.ts
+++ b/core/mcp/serverList.ts
@@ -15,6 +15,7 @@ import {
 import type { Root } from "@modelcontextprotocol/client";
 import type {
   InspectorServerSettings,
+  RequestMetadata,
   MCPConfig,
   MCPServerConfig,
   ServerEntry,
@@ -28,6 +29,7 @@ import {
   envSecretField,
 } from "../auth/secret-fields.js";
 import { toRecord } from "../json/jsonUtils.js";
+import type { JsonValue } from "../json/jsonUtils.js";
 
 // The full set of valid `type` discriminator values, used to reject anything
 // else read off disk so unknown strings can't propagate to narrowing sites.
@@ -194,6 +196,60 @@ export function envPairsToRecord(
   return out;
 }
 
+/**
+ * Read a server's `metadata` off disk into the in-memory `RequestMetadata`
+ * object, accepting both the current object shape and the pre-#1910
+ * `{ key, value }[]` pair array.
+ *
+ * The pair array is the shape every `mcp.json` written before #1910 carries, so
+ * dropping it would silently stop sending a user's configured `_meta` on the
+ * first read of an existing file. It is read here and never written back:
+ * `inspectorSettingsToStoredFields` emits only the object form, so the file is
+ * migrated the next time the entry is saved.
+ *
+ * Anything else — a string, a number, an array of non-pairs — is not metadata
+ * the Inspector can send, so it is dropped with a warning rather than half-
+ * interpreted, following `cleanRoots` / `cleanAuthorizationParams` above. A
+ * pair whose key is blank is skipped for the same reason the write side omits
+ * it: `_meta` has no meaningful empty key.
+ */
+export function normalizeStoredMetadata(
+  metadata: StoredMCPServer["metadata"] | unknown,
+): RequestMetadata {
+  if (metadata === undefined || metadata === null) return {};
+
+  if (Array.isArray(metadata)) {
+    const out: RequestMetadata = {};
+    for (const entry of metadata) {
+      if (
+        typeof entry !== "object" ||
+        entry === null ||
+        typeof (entry as { key?: unknown }).key !== "string"
+      ) {
+        console.warn(
+          "Ignoring malformed legacy metadata entry (expected `{ key, value }`):",
+          entry,
+        );
+        continue;
+      }
+      const { key, value } = entry as { key: string; value?: JsonValue };
+      if (key.trim() === "") continue;
+      out[key] = value ?? "";
+    }
+    return out;
+  }
+
+  if (typeof metadata === "object") {
+    return { ...(metadata as RequestMetadata) };
+  }
+
+  console.warn(
+    "Ignoring malformed `metadata` (expected a JSON object):",
+    metadata,
+  );
+  return {};
+}
+
 /**
  * Validate a server's `oauth.authorizationParams` as it comes off disk, or
  * `undefined` when there is nothing usable. (#2018)
@@ -349,7 +405,7 @@ export function storedFieldsToInspectorSettings(
   const settings: InspectorServerSettings = {
     headers: headersPairs,
     env: envRecordToPairs(stored.env),
-    metadata: stored.metadata ?? [],
+    metadata: normalizeStoredMetadata(stored.metadata),
     connectionTimeout: stored.connectionTimeout ?? 0,
     requestTimeout: stored.requestTimeout ?? 0,
     // Unlike the timeouts (0 = "SDK default"), task TTL has a concrete product
@@ -458,9 +514,11 @@ export function inspectorSettingsToStoredFields(
     out.headers = headersRecord;
   }
 
-  const metadataFiltered = settings.metadata.filter((m) => m.key.trim() !== "");
-  if (metadataFiltered.length > 0) {
-    out.metadata = metadataFiltered;
+  // Blank-key entries can't exist in the object form (an object has no blank
+  // key the user can leave mid-edit, the way a `{key,value}` row could), so
+  // there is nothing to filter — only the empty-object case to omit.
+  if (Object.keys(settings.metadata).length > 0) {
+    out.metadata = settings.metadata;
   }
 
   if (settings.connectionTimeout > 0) {
diff --git a/core/mcp/state/managedListState.ts b/core/mcp/state/managedListState.ts
index eaf51f5d..bfe6467a 100644
--- a/core/mcp/state/managedListState.ts
+++ b/core/mcp/state/managedListState.ts
@@ -19,6 +19,7 @@ import type {
 } from "@modelcontextprotocol/client";
 import { isClientDecodeRejection } from "../listSalvage.js";
 import { isTerminalStatus } from "../types.js";
+import type { RequestMetadata } from "../types.js";
 import { TypedEventTarget } from "../typedEventTarget.js";
 
 /**
@@ -67,7 +68,7 @@ export interface ManagedListConfig<T, M extends ManagedListEventMap> {
   fetchAll: (
     client: InspectorClientProtocol,
     cacheMode: CacheMode | undefined,
-    metadata: Record<string, string> | undefined,
+    metadata: RequestMetadata | undefined,
   ) => Promise<T[]>;
   /**
    * Whether this list drives a list-changed indicator. When true, a
@@ -97,7 +98,7 @@ export abstract class ManagedListState<
   protected items: T[] = [];
   protected client: InspectorClientProtocol | null = null;
   private unsubscribe: (() => void) | null = null;
-  private _metadata: Record<string, string> | undefined = undefined;
+  private _metadata: RequestMetadata | undefined = undefined;
   private listChanged = false;
   // The last fetch's failure, kept as observable state so a load that fails
   // (a transport error, or a result the SDK codec rejects as invalid) is
@@ -282,7 +283,7 @@ export abstract class ManagedListState<
     this.emit("errorChange", value);
   }
 
-  setMetadata(metadata?: Record<string, string>): void {
+  setMetadata(metadata?: RequestMetadata): void {
     this._metadata = metadata;
   }
 
@@ -299,7 +300,7 @@ export abstract class ManagedListState<
    * the `list_changed` auto-refresh) catch it explicitly (#1953).
    */
   async refresh(
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
     cacheMode?: CacheMode,
   ): Promise<T[]> {
     let next: T[] | null;
@@ -336,7 +337,7 @@ export abstract class ManagedListState<
    * the console; empty list is the right semantics).
    */
   private async fetchItems(
-    metadata: Record<string, string> | undefined,
+    metadata: RequestMetadata | undefined,
     cacheMode: CacheMode | undefined,
   ): Promise<T[] | null> {
     const client = this.client;
diff --git a/core/mcp/state/pagedPromptsState.ts b/core/mcp/state/pagedPromptsState.ts
index 80fbe6ca..5d15ae5c 100644
--- a/core/mcp/state/pagedPromptsState.ts
+++ b/core/mcp/state/pagedPromptsState.ts
@@ -15,6 +15,7 @@
 import type { InspectorClientProtocol } from "../inspectorClientProtocol.js";
 import type { Prompt } from "@modelcontextprotocol/client";
 import { isTerminalStatus } from "../types.js";
+import type { RequestMetadata } from "../types.js";
 import { TypedEventTarget } from "../typedEventTarget.js";
 import type { PagePaginationState } from "./pagedToolsState.js";
 
@@ -112,7 +113,7 @@ export class PagedPromptsState extends TypedEventTarget<PagedPromptsStateEventMa
 
   async loadPage(
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<LoadPageResult> {
     const c = this.client;
     if (!c || c.getStatus() !== "connected") {
diff --git a/core/mcp/state/pagedResourceTemplatesState.ts b/core/mcp/state/pagedResourceTemplatesState.ts
index 2fd2e2af..efbedbd2 100644
--- a/core/mcp/state/pagedResourceTemplatesState.ts
+++ b/core/mcp/state/pagedResourceTemplatesState.ts
@@ -14,6 +14,7 @@
 import type { InspectorClientProtocol } from "../inspectorClientProtocol.js";
 import type { ResourceTemplateType as ResourceTemplate } from "@modelcontextprotocol/client";
 import { isTerminalStatus } from "../types.js";
+import type { RequestMetadata } from "../types.js";
 import { TypedEventTarget } from "../typedEventTarget.js";
 
 export interface PagedResourceTemplatesStateEventMap {
@@ -59,7 +60,7 @@ export class PagedResourceTemplatesState extends TypedEventTarget<PagedResourceT
 
   async loadPage(
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<LoadPageResult> {
     const c = this.client;
     if (!c || c.getStatus() !== "connected") {
diff --git a/core/mcp/state/pagedResourcesState.ts b/core/mcp/state/pagedResourcesState.ts
index bd5194ac..60640faf 100644
--- a/core/mcp/state/pagedResourcesState.ts
+++ b/core/mcp/state/pagedResourcesState.ts
@@ -16,6 +16,7 @@
 import type { InspectorClientProtocol } from "../inspectorClientProtocol.js";
 import type { Resource } from "@modelcontextprotocol/client";
 import { isTerminalStatus } from "../types.js";
+import type { RequestMetadata } from "../types.js";
 import { TypedEventTarget } from "../typedEventTarget.js";
 import type { PagePaginationState } from "./pagedToolsState.js";
 
@@ -113,7 +114,7 @@ export class PagedResourcesState extends TypedEventTarget<PagedResourcesStateEve
 
   async loadPage(
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ): Promise<LoadPageResult> {
     const c = this.client;
     if (!c || c.getStatus() !== "connected") {
diff --git a/core/mcp/types.ts b/core/mcp/types.ts
index 79475bc4..1b94f9ea 100644
--- a/core/mcp/types.ts
+++ b/core/mcp/types.ts
@@ -24,7 +24,7 @@ import type { OAuthClientProvider } from "@modelcontextprotocol/client";
 import type { Transport } from "@modelcontextprotocol/client";
 import type { InspectorLogger } from "../logging/logger.js";
 import type { AppElicitationRenderer } from "./appElicitation.js";
-import type { JsonValue } from "../json/jsonUtils.js";
+import type { JsonObject, JsonValue } from "../json/jsonUtils.js";
 import type {
   ClientConfig,
   EnterpriseManagedAuthIdpConfig,
@@ -99,11 +99,20 @@ export type StoredMCPServer = MCPServerConfig & {
    */
   headers?: Record<string, string>;
   /**
-   * Default `_meta` keys merged into every outgoing MCP request. Inspector-
-   * specific (no analog in the broader mcp.json ecosystem), so the pair-array
-   * shape is preserved on disk and in memory.
+   * Default `_meta` payload merged into every outgoing MCP request. Inspector-
+   * specific (no analog in the broader mcp.json ecosystem).
+   *
+   * A JSON object, so a value may be any JSON — object, array, number, boolean,
+   * `null` — not just a string (#1910). Nothing in the MCP spec restricts
+   * `_meta` to string values, and the SDK models it as a passthrough object;
+   * the string-pair restriction was the Inspector's own.
+   *
+   * The pre-#1910 on-disk shape was a `{ key, value }[]` pair array. It is
+   * still **read** (see `normalizeStoredMetadata` in `serverList.ts`) so an
+   * existing `mcp.json` keeps working, but it is never written back — a
+   * round-trip through the Inspector rewrites the field as an object.
    */
-  metadata?: { key: string; value: string }[];
+  metadata?: JsonObject;
   /**
    * Protocol era to negotiate with this server (`"legacy" | "auto" | "modern"`),
    * orthogonal to the transport `type`. Inspector-specific (no analog in the
@@ -361,6 +370,19 @@ export interface ServerState {
   stderrLogs: StderrLogEntry[];
 }
 
+/**
+ * A `_meta` payload: a JSON object whose values may be any JSON, not just
+ * strings (#1910).
+ *
+ * The MCP spec places no restriction on `_meta` value types and the SDK models
+ * the field as a passthrough object, so the Inspector must be able to send —
+ * and to record — nested objects, arrays, numbers, booleans and `null`. Used
+ * for both the per-server default payload (`InspectorServerSettings.metadata`,
+ * `InspectorClientOptions.defaultMetadata`) and the per-call metadata every
+ * request verb accepts.
+ */
+export type RequestMetadata = Record<string, JsonValue>;
+
 /**
  * Represents a complete resource read invocation, including request parameters,
  * response, and metadata.
@@ -369,7 +391,7 @@ export interface ResourceReadInvocation {
   result: ReadResourceResult;
   timestamp: Date;
   uri: string;
-  metadata?: Record<string, string>;
+  metadata?: RequestMetadata;
 }
 
 /**
@@ -382,7 +404,7 @@ export interface ResourceTemplateReadInvocation {
   result: ReadResourceResult;
   timestamp: Date;
   params: Record<string, string>;
-  metadata?: Record<string, string>;
+  metadata?: RequestMetadata;
 }
 
 /**
@@ -394,7 +416,7 @@ export interface PromptGetInvocation {
   timestamp: Date;
   name: string;
   params?: Record<string, string>;
-  metadata?: Record<string, string>;
+  metadata?: RequestMetadata;
 }
 
 /**
@@ -408,7 +430,7 @@ export interface ToolCallInvocation {
   timestamp: Date;
   success: boolean;
   error?: string;
-  metadata?: Record<string, string>;
+  metadata?: RequestMetadata;
   /**
    * Set only on the `skipOutputValidation` path: present when the (delivered)
    * result's structuredContent does NOT match the tool's declared outputSchema.
@@ -689,7 +711,12 @@ export function eraToVersionNegotiation(
  */
 export interface InspectorServerSettings {
   headers: { key: string; value: string }[];
-  metadata: { key: string; value: string }[];
+  /**
+   * Default `_meta` payload for this server, edited as a JSON object rather
+   * than key/value rows so a value can be any JSON (#1910). Always present;
+   * `{}` means "send no default metadata".
+   */
+  metadata: RequestMetadata;
   /**
    * Environment variables for stdio servers, edited as controlled key/value
    * rows (mirrors `headers`). Only meaningful for stdio transports; non-stdio
@@ -1075,7 +1102,7 @@ export interface InspectorClientOptions {
    * site metadata wins on key collision. Set this from `InspectorServerSettings.metadata`
    * so persisted server-wide metadata reaches the wire on the first request.
    */
-  defaultMetadata?: Record<string, string>;
+  defaultMetadata?: RequestMetadata;
 
   /**
    * Optional per-server runtime settings forwarded to the transport factory
diff --git a/core/react/usePagedPrompts.ts b/core/react/usePagedPrompts.ts
index 3e3efd44..6f62c524 100644
--- a/core/react/usePagedPrompts.ts
+++ b/core/react/usePagedPrompts.ts
@@ -1,5 +1,6 @@
 import { useState, useEffect, useCallback } from "react";
 import type { InspectorClientProtocol } from "../mcp/inspectorClientProtocol.js";
+import type { RequestMetadata } from "../mcp/types.js";
 import type {
   PagedPromptsState,
   PagedPromptsStateEventMap,
@@ -23,7 +24,7 @@ export interface UsePagedPromptsResult {
   error: Error | null;
   loadPage: (
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ) => Promise<LoadPageResult>;
   clear: () => void;
 }
@@ -84,7 +85,7 @@ export function usePagedPrompts(
   const loadPage = useCallback(
     async (
       cursor?: string,
-      metadata?: Record<string, string>,
+      metadata?: RequestMetadata,
     ): Promise<LoadPageResult> => {
       if (!pagedPromptsState || !client) {
         return { prompts: [], nextCursor: undefined };
diff --git a/core/react/usePagedResourceTemplates.ts b/core/react/usePagedResourceTemplates.ts
index ab4707a4..c5202596 100644
--- a/core/react/usePagedResourceTemplates.ts
+++ b/core/react/usePagedResourceTemplates.ts
@@ -1,5 +1,6 @@
 import { useState, useEffect, useCallback } from "react";
 import type { InspectorClientProtocol } from "../mcp/inspectorClientProtocol.js";
+import type { RequestMetadata } from "../mcp/types.js";
 import type {
   PagedResourceTemplatesState,
   PagedResourceTemplatesStateEventMap,
@@ -12,7 +13,7 @@ export interface UsePagedResourceTemplatesResult {
   resourceTemplates: ResourceTemplate[];
   loadPage: (
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ) => Promise<LoadPageResult>;
   clear: () => void;
 }
@@ -58,7 +59,7 @@ export function usePagedResourceTemplates(
   const loadPage = useCallback(
     async (
       cursor?: string,
-      metadata?: Record<string, string>,
+      metadata?: RequestMetadata,
     ): Promise<LoadPageResult> => {
       if (!pagedResourceTemplatesState || !client) {
         return { resourceTemplates: [], nextCursor: undefined };
diff --git a/core/react/usePagedResources.ts b/core/react/usePagedResources.ts
index 3e5e3f8a..00b52a26 100644
--- a/core/react/usePagedResources.ts
+++ b/core/react/usePagedResources.ts
@@ -1,5 +1,6 @@
 import { useState, useEffect, useCallback } from "react";
 import type { InspectorClientProtocol } from "../mcp/inspectorClientProtocol.js";
+import type { RequestMetadata } from "../mcp/types.js";
 import type {
   PagedResourcesState,
   PagedResourcesStateEventMap,
@@ -23,7 +24,7 @@ export interface UsePagedResourcesResult {
   error: Error | null;
   loadPage: (
     cursor?: string,
-    metadata?: Record<string, string>,
+    metadata?: RequestMetadata,
   ) => Promise<LoadPageResult>;
   clear: () => void;
 }
@@ -90,7 +91,7 @@ export function usePagedResources(
   const loadPage = useCallback(
     async (
       cursor?: string,
-      metadata?: Record<string, string>,
+      metadata?: RequestMetadata,
     ): Promise<LoadPageResult> => {
       if (!pagedResourcesState || !client) {
         return { resources: [], nextCursor: undefined };
diff --git a/docs/mcp-server-configuration.md b/docs/mcp-server-configuration.md
index ac105f3a..c6bbd29b 100644
--- a/docs/mcp-server-configuration.md
+++ b/docs/mcp-server-configuration.md
@@ -168,7 +168,7 @@ These have no analog in the broader `mcp.json` ecosystem. Each is **omitted on w
 | `protocolEra`                          | `"legacy"` | `"legacy"` \| `"auto"` \| `"modern"` — which protocol era to negotiate, orthogonal to the transport |
 | `modernLogLevel`                       | `"debug"`  | Per-request log level stamped on modern connections, or `"off"`. Legacy connections ignore it       |
 | `roots`                                | —          | Roots advertised via the `roots` client capability; each is `{ uri, name? }`                        |
-| `metadata`                             | —          | Default `_meta` keys merged into every outgoing request                                             |
+| `metadata`                             | —          | Default `_meta` payload merged into every outgoing request — a JSON object, values may be any JSON  |
 | `connectionTimeout` / `requestTimeout` | —          | Timeouts in ms                                                                                      |
 | `taskTtl`                              | `60000`    | TTL in ms for tasks created via "Run as task" (`DEFAULT_TASK_TTL_MS`)                               |
 | `autoRefreshOnListChanged`             | `false`    | Refresh lists automatically on `*/list_changed` instead of only flagging the indicator              |
@@ -177,6 +177,18 @@ These have no analog in the broader `mcp.json` ecosystem. Each is **omitted on w
 | `maxFetchRequests`                     | `1000`     | Network-log retention for this server (`DEFAULT_MAX_FETCH_REQUESTS`); `0` means unlimited           |
 | `oauth`                                | —          | `{ clientId, clientSecret, scopes, authorizationParams, authorizationUrl, tokenUrl, enterpriseManaged, onInsufficientScope }` |
 
+`metadata` is a JSON **object**, and its values may be any JSON — an object, an array, a number, a boolean, `null` — not only a string. Nothing in the MCP spec restricts `_meta` value types, and the SDK models the field as a passthrough object, so the Inspector does not narrow it either ([#1910](https://github.com/modelcontextprotocol/inspector/issues/1910)). Edit it in Server Settings → Request Metadata, which is a JSON editor rather than the key/value rows `headers` and `env` use; text that is not a JSON object is flagged inline and not applied.
+
+```jsonc
+"metadata": {
+  "tenant": "acme",
+  "trace": { "id": "abc123", "sampled": true },
+  "features": ["apps", "tasks"]
+}
+```
+
+> **Reading an older file.** Before #1910 this field was a `[{ "key": …, "value": … }]` pair array. That shape is still **read**, so an existing `mcp.json` keeps working unchanged; it is never written back, so the field is rewritten as an object the next time the Inspector saves the entry.
+
 `oauth.authorizationParams` is a string→string record of extra query parameters merged into the OAuth **authorization request** URL only — never the token request. Use it for provider-specific hints the core specs don't standardize (Keycloak's `kc_idp_hint`, OIDC's `login_hint` / `prompt` / `acr_values`, Auth0's `audience`). The protocol-critical parameters — `client_id`, `code_challenge`, `code_challenge_method`, `redirect_uri`, `resource`, `response_type`, `scope`, `state` — are **reserved**: the web form rejects them inline, and any that reach the merge anyway are dropped with a warning rather than overriding what the flow set (overriding them breaks PKCE, the CSRF state binding, or RFC 8707). Edit them in Server Settings → Authorization ("Additional authorization parameters"), beside Scopes.
 
 `oauth.authorizationUrl` and `oauth.tokenUrl` override the `authorization_endpoint` and `token_endpoint` that authorization-server metadata discovery resolved. The Inspector deliberately has no such fields by default — it resolves both from the AS's metadata document, exactly as a real MCP host does — but a server under development often advertises its *production* authorization server while you want to hit staging. Set either (they are independent) to an absolute `http(s)` URL and it replaces what the metadata returned, for both the authorization request and the token request; leave blank to use discovery. A malformed value is flagged inline in the form and dropped with a warning at connect time rather than failing the connection. Edit them in Server Settings → Authorization ("Authorization URL override" / "Token URL override").

From 3a64ce7f4e9d0fe6b1199b256d239f5694715b1f Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 12:29:27 -0400
Subject: [PATCH 07/35] refactor: move the JSON-object draft parser into utils

`react-refresh/only-export-components` rejects a non-component export from a
component module, so `parseObjectDraft` could not live beside
`JsonObjectInput`. It is a pure transform, which puts it in `utils` under the
`lib`/`utils` rule anyway.

Also render the metadata hint's inline literals through `<Code>` rather than
markdown backticks, which a Mantine `Text` shows verbatim.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../JsonObjectInput/JsonObjectInput.test.tsx  | 46 +-----------------
 .../JsonObjectInput/JsonObjectInput.tsx       | 38 ++-------------
 .../ServerSettingsForm/ServerSettingsForm.tsx |  8 ++--
 clients/web/src/utils/jsonObjectDraft.test.ts | 46 ++++++++++++++++++
 clients/web/src/utils/jsonObjectDraft.ts      | 47 +++++++++++++++++++
 5 files changed, 101 insertions(+), 84 deletions(-)
 create mode 100644 clients/web/src/utils/jsonObjectDraft.test.ts
 create mode 100644 clients/web/src/utils/jsonObjectDraft.ts

diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
index 37d02dfb..b1da0ffb 100644
--- a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
@@ -4,7 +4,7 @@ import { screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
 import { renderWithMantine } from "../../../test/renderWithMantine";
-import { JsonObjectInput, parseObjectDraft } from "./JsonObjectInput";
+import { JsonObjectInput } from "./JsonObjectInput";
 
 const LABEL = "Payload JSON";
 
@@ -36,50 +36,6 @@ function box() {
   return screen.getByLabelText(LABEL) as HTMLTextAreaElement;
 }
 
-describe("parseObjectDraft", () => {
-  it("reads empty text as the empty object rather than an error", () => {
-    expect(parseObjectDraft("")).toEqual({ ok: true, value: {} });
-    expect(parseObjectDraft("   \n ")).toEqual({ ok: true, value: {} });
-  });
-
-  it("accepts a JSON object with values of any JSON type", () => {
-    const result = parseObjectDraft(
-      '{"s":"a","n":1,"b":true,"z":null,"arr":[1,{"k":2}],"o":{"deep":{"er":1}}}',
-    );
-    expect(result).toEqual({
-      ok: true,
-      value: {
-        s: "a",
-        n: 1,
-        b: true,
-        z: null,
-        arr: [1, { k: 2 }],
-        o: { deep: { er: 1 } },
-      },
-    });
-  });
-
-  it("rejects text that is not JSON", () => {
-    expect(parseObjectDraft('{"a":')).toEqual({
-      ok: false,
-      error: "Not valid JSON — changes are not applied",
-    });
-  });
-
-  it.each([
-    ["an array", "[1,2]"],
-    ["a string", '"hello"'],
-    ["a number", "42"],
-    ["null", "null"],
-  ])("rejects valid JSON that is not an object: %s", (_label, text) => {
-    const result = parseObjectDraft(text);
-    expect(result.ok).toBe(false);
-    expect(result.ok === false && result.error).toMatch(
-      /Must be a JSON object/,
-    );
-  });
-});
-
 describe("JsonObjectInput", () => {
   it("opens with the value serialized two-space, nesting intact", () => {
     renderWithMantine(<Harness initial={{ a: { b: [1, 2] } }} />);
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
index 93df2516..fbec5ee4 100644
--- a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
@@ -2,6 +2,7 @@ import { useState } from "react";
 import { JsonInput } from "@mantine/core";
 import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
 import { useValueChange } from "../../../hooks/useValueChange";
+import { parseJsonObjectDraft } from "../../../utils/jsonObjectDraft";
 
 const ObjectJsonInput = JsonInput.withProps({
   formatOnBlur: true,
@@ -15,39 +16,6 @@ function serialize(value: JsonObject): string {
   return JSON.stringify(value, null, 2);
 }
 
-/** A plain JSON object, i.e. not an array and not a scalar. */
-function isJsonObject(value: unknown): value is JsonObject {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-/**
- * What a draft's text currently means: the object to emit, or why it can't be.
- *
- * Empty text is the object `{}` rather than an error — clearing the box is how
- * "send no metadata" is spelled, and an empty editor showing a red error would
- * read as broken.
- */
-type DraftState =
-  | { ok: true; value: JsonObject }
-  | { ok: false; error: string };
-
-export function parseObjectDraft(text: string): DraftState {
-  if (text.trim() === "") return { ok: true, value: {} };
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    return { ok: false, error: "Not valid JSON — changes are not applied" };
-  }
-  if (!isJsonObject(parsed)) {
-    return {
-      ok: false,
-      error: "Must be a JSON object (`{ … }`) — changes are not applied",
-    };
-  }
-  return { ok: true, value: parsed };
-}
-
 export interface JsonObjectInputProps {
   value: JsonObject;
   onChange: (value: JsonObject) => void;
@@ -92,7 +60,7 @@ export function JsonObjectInput({
   // parses to, so an external reset (switching servers, a reloaded catalog)
   // reaches the box while an in-progress edit is left alone. Compared through
   // canonical JSON because the parent hands back a fresh object each time.
-  const parsed = parseObjectDraft(draft);
+  const parsed = parseJsonObjectDraft(draft);
   const draftJson = parsed.ok ? serialize(parsed.value) : null;
   useValueChange(serialize(value), (next) => {
     if (next !== draftJson) setDraft(next);
@@ -105,7 +73,7 @@ export function JsonObjectInput({
       error={parsed.ok ? undefined : parsed.error}
       onChange={(text) => {
         setDraft(text);
-        const result = parseObjectDraft(text);
+        const result = parseJsonObjectDraft(text);
         if (result.ok) onChange(result.value);
       }}
     />
diff --git a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
index 36179c9b..0a61a8db 100644
--- a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
+++ b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
@@ -729,10 +729,10 @@ export function ServerSettingsForm({
         <Accordion.Panel>
           <Stack gap="md">
             <HintText>
-              Metadata merged into the `_meta` field of every MCP request to
-              this server, as a JSON object. Values may be any JSON — objects,
-              arrays, numbers, booleans, `null` — not just strings. Leave it as{" "}
-              <Code>{"{}"}</Code> to send none.
+              Metadata merged into the <Code>_meta</Code> field of every MCP
+              request to this server, as a JSON object. Values may be any JSON —
+              objects, arrays, numbers, booleans, <Code>null</Code> — not just
+              strings. Leave it as <Code>{"{}"}</Code> to send none.
             </HintText>
             <JsonObjectInput
               aria-label="Request metadata JSON"
diff --git a/clients/web/src/utils/jsonObjectDraft.test.ts b/clients/web/src/utils/jsonObjectDraft.test.ts
new file mode 100644
index 00000000..83298caf
--- /dev/null
+++ b/clients/web/src/utils/jsonObjectDraft.test.ts
@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { parseJsonObjectDraft } from "./jsonObjectDraft";
+
+describe("parseJsonObjectDraft", () => {
+  it("reads empty text as the empty object rather than an error", () => {
+    expect(parseJsonObjectDraft("")).toEqual({ ok: true, value: {} });
+    expect(parseJsonObjectDraft("   \n ")).toEqual({ ok: true, value: {} });
+  });
+
+  it("accepts a JSON object with values of any JSON type", () => {
+    const result = parseJsonObjectDraft(
+      '{"s":"a","n":1,"b":true,"z":null,"arr":[1,{"k":2}],"o":{"deep":{"er":1}}}',
+    );
+    expect(result).toEqual({
+      ok: true,
+      value: {
+        s: "a",
+        n: 1,
+        b: true,
+        z: null,
+        arr: [1, { k: 2 }],
+        o: { deep: { er: 1 } },
+      },
+    });
+  });
+
+  it("rejects text that is not JSON", () => {
+    expect(parseJsonObjectDraft('{"a":')).toEqual({
+      ok: false,
+      error: "Not valid JSON — changes are not applied",
+    });
+  });
+
+  it.each([
+    ["an array", "[1,2]"],
+    ["a string", '"hello"'],
+    ["a number", "42"],
+    ["null", "null"],
+  ])("rejects valid JSON that is not an object: %s", (_label, text) => {
+    const result = parseJsonObjectDraft(text);
+    expect(result.ok).toBe(false);
+    expect(result.ok === false && result.error).toMatch(
+      /Must be a JSON object/,
+    );
+  });
+});
diff --git a/clients/web/src/utils/jsonObjectDraft.ts b/clients/web/src/utils/jsonObjectDraft.ts
new file mode 100644
index 00000000..b5397079
--- /dev/null
+++ b/clients/web/src/utils/jsonObjectDraft.ts
@@ -0,0 +1,47 @@
+import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
+
+/**
+ * What a JSON-object editor's draft text currently means: the object to emit,
+ * or why it cannot be emitted.
+ */
+export type JsonObjectDraft =
+  | { ok: true; value: JsonObject }
+  | { ok: false; error: string };
+
+/** A plain JSON object, i.e. not an array and not a scalar. */
+export function isJsonObject(value: unknown): value is JsonObject {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Read a JSON-object editor's draft text.
+ *
+ * Empty text is the object `{}` rather than an error — clearing the box is how
+ * "send nothing" is spelled, and an empty editor wearing a red error would read
+ * as broken.
+ *
+ * The two failure modes are reported separately because they are different
+ * mistakes: text that is not JSON at all is usually mid-edit, while text that
+ * is valid JSON but not an object (`[1,2]`, `"a"`, `42`) is a shape the caller
+ * cannot use no matter how finished it is.
+ *
+ * Lives in `utils` rather than beside its component because it is a pure
+ * transform — and because exporting it from the component's module trips
+ * `react-refresh/only-export-components`.
+ */
+export function parseJsonObjectDraft(text: string): JsonObjectDraft {
+  if (text.trim() === "") return { ok: true, value: {} };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { ok: false, error: "Not valid JSON — changes are not applied" };
+  }
+  if (!isJsonObject(parsed)) {
+    return {
+      ok: false,
+      error: "Must be a JSON object (`{ … }`) — changes are not applied",
+    };
+  }
+  return { ok: true, value: parsed };
+}

From 04b5e70a5393f084394ec15ff26998a20f353e63 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 12:56:13 -0400
Subject: [PATCH 08/35] fix(a11y): make the form error color meet WCAG AA in
 both schemes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mantine's `--mantine-color-error` defaults to `red-6` in light and `red-8` in
dark. Both fail the 4.5:1 AA threshold that applies at the 12px size it renders
input error text: 4.48:1 on white, and 1.93:1 on our charcoal body. Override to
`red-7` (5.72:1) and `red-4` (6.44:1) — the latter matching the one-to-two-step
lift App.css already applies to the semantic status/log reds for dark.

Surfaced by the JsonObjectInput stories, which are the first in the repo to
render an input error state and so the first to put this in front of the
Storybook a11y gate. It is app-wide, not specific to that component — every
form error in the Inspector was affected.

It has to go through `cssVariablesResolver`: MantineProvider injects these
variables into a `<style>` block appended after the stylesheet imports, so a
`:root` rule in App.css loses to it on source order at equal specificity.

That resolver was duplicated in main.tsx and .storybook/preview.tsx and missing
from renderWithMantine, so the three could drift on any token they set. Extract
one `theme/cssVariables.ts` and use it at all three sites.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/.storybook/preview.tsx         | 17 ++---------
 clients/web/src/main.tsx                   | 15 ++--------
 clients/web/src/test/renderWithMantine.tsx |  8 ++++-
 clients/web/src/theme/cssVariables.ts      | 34 ++++++++++++++++++++++
 clients/web/src/theme/index.ts             |  1 +
 5 files changed, 48 insertions(+), 27 deletions(-)
 create mode 100644 clients/web/src/theme/cssVariables.ts

diff --git a/clients/web/.storybook/preview.tsx b/clients/web/.storybook/preview.tsx
index 6b419a43..e1669ea0 100644
--- a/clients/web/.storybook/preview.tsx
+++ b/clients/web/.storybook/preview.tsx
@@ -1,14 +1,11 @@
 import type { Preview } from "@storybook/react-vite";
-import {
-  MantineProvider,
-  useMantineColorScheme,
-  type CSSVariablesResolver,
-} from "@mantine/core";
+import { MantineProvider, useMantineColorScheme } from "@mantine/core";
 import { Notifications } from "@mantine/notifications";
 import "@mantine/core/styles.css";
 import "@mantine/notifications/styles.css";
 import "../src/App.css";
 import { theme } from "../src/theme/theme";
+import { cssVariablesResolver } from "../src/theme/cssVariables";
 import { useEffect } from "react";
 
 // eslint-disable-next-line react-refresh/only-export-components
@@ -28,14 +25,6 @@ function ColorSchemeWrapper({
   return <>{children}</>;
 }
 
-const resolver: CSSVariablesResolver = () => ({
-  variables: {},
-  light: {},
-  dark: {
-    "--mantine-color-body": "var(--mantine-color-dark-9)",
-  },
-});
-
 const preview: Preview = {
   globalTypes: {
     colorScheme: {
@@ -61,7 +50,7 @@ const preview: Preview = {
         <MantineProvider
           theme={theme}
           defaultColorScheme="light"
-          cssVariablesResolver={resolver}
+          cssVariablesResolver={cssVariablesResolver}
         >
           <ColorSchemeWrapper
             colorScheme={context.globals.colorScheme ?? "light"}
diff --git a/clients/web/src/main.tsx b/clients/web/src/main.tsx
index 662352e8..fb8a3562 100644
--- a/clients/web/src/main.tsx
+++ b/clients/web/src/main.tsx
@@ -1,29 +1,20 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
-import { MantineProvider, type CSSVariablesResolver } from "@mantine/core";
+import { MantineProvider } from "@mantine/core";
 import { Notifications } from "@mantine/notifications";
 import "@mantine/core/styles.css";
 import "@mantine/notifications/styles.css";
 import "./App.css";
 import { theme } from "./theme/theme";
+import { cssVariablesResolver } from "./theme/cssVariables";
 import App from "./App";
 
-const resolver: CSSVariablesResolver = () => ({
-  variables: {},
-  light: {},
-  dark: {
-    // Matches `.storybook/preview.tsx` so the dev app and the story preview
-    // share the same dark-mode page background.
-    "--mantine-color-body": "var(--mantine-color-dark-9)",
-  },
-});
-
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
     <MantineProvider
       theme={theme}
       defaultColorScheme="auto"
-      cssVariablesResolver={resolver}
+      cssVariablesResolver={cssVariablesResolver}
     >
       <Notifications position="bottom-right" />
       <App />
diff --git a/clients/web/src/test/renderWithMantine.tsx b/clients/web/src/test/renderWithMantine.tsx
index ea291c6b..677d9ca0 100644
--- a/clients/web/src/test/renderWithMantine.tsx
+++ b/clients/web/src/test/renderWithMantine.tsx
@@ -3,6 +3,7 @@ import { act, render, type RenderOptions } from "@testing-library/react";
 import { MantineProvider, type MantineColorScheme } from "@mantine/core";
 import { afterEach, expect, vi } from "vitest";
 import { theme } from "../theme/theme";
+import { cssVariablesResolver } from "../theme/cssVariables";
 
 // Options accepted by both render helpers: the standard RTL options (minus
 // `wrapper`, which we own) plus an optional forced `colorScheme`. The default
@@ -30,7 +31,12 @@ export type MantineTransitionsRenderOptions = MantineRenderOptions & {
 function makeWrapper(env: "test" | "default", colorScheme: MantineColorScheme) {
   return function Wrapper({ children }: { children: ReactNode }) {
     return (
-      <MantineProvider theme={theme} defaultColorScheme={colorScheme} env={env}>
+      <MantineProvider
+        theme={theme}
+        defaultColorScheme={colorScheme}
+        env={env}
+        cssVariablesResolver={cssVariablesResolver}
+      >
         {children}
       </MantineProvider>
     );
diff --git a/clients/web/src/theme/cssVariables.ts b/clients/web/src/theme/cssVariables.ts
new file mode 100644
index 00000000..11bad0f9
--- /dev/null
+++ b/clients/web/src/theme/cssVariables.ts
@@ -0,0 +1,34 @@
+import type { CSSVariablesResolver } from "@mantine/core";
+
+/**
+ * Overrides for the Mantine CSS variables that `MantineProvider` injects at
+ * runtime.
+ *
+ * These cannot be set from `App.css`: the provider appends its generated
+ * `<style>` block after the stylesheet imports, so a `:root` rule there loses
+ * to it on source order at equal specificity. `cssVariablesResolver` is the
+ * supported seam, which is why this lives in the theme layer beside the
+ * `Component.extend()` variants rather than with the `--inspector-*` tokens.
+ *
+ * Shared by all three `MantineProvider` sites — the app (`main.tsx`), the
+ * Storybook preview, and `renderWithMantine` — so the dev app, the story
+ * preview, and the tests cannot disagree about a token's value. It used to be
+ * duplicated in the first two and absent from the third.
+ */
+export const cssVariablesResolver: CSSVariablesResolver = () => ({
+  variables: {},
+  light: {
+    // Mantine defaults `--mantine-color-error` to `red-6`, which is 4.48:1 on
+    // white — under the 4.5:1 WCAG AA threshold that applies at the 12px size
+    // it renders input error text. `red-7` is 5.72:1.
+    "--mantine-color-error": "var(--mantine-color-red-7)",
+  },
+  dark: {
+    "--mantine-color-body": "var(--mantine-color-dark-9)",
+    // The dark default is `red-8`, which is 1.93:1 on this body color — far
+    // worse than the light-mode miss. `red-4` is 6.44:1, and is the same
+    // one-to-two-step lift `App.css` already applies to the semantic
+    // status/log reds for dark.
+    "--mantine-color-error": "var(--mantine-color-red-4)",
+  },
+});
diff --git a/clients/web/src/theme/index.ts b/clients/web/src/theme/index.ts
index 37ec7a43..313c2ac5 100644
--- a/clients/web/src/theme/index.ts
+++ b/clients/web/src/theme/index.ts
@@ -1,3 +1,4 @@
+export { cssVariablesResolver } from "./cssVariables";
 export { ThemeAccordion } from "./Accordion";
 export { ThemeActionIcon } from "./ActionIcon";
 export { ThemeAlert } from "./Alert";

From 0f628a81741b0c112683d615d09e2be5b4069fd7 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 13:13:04 -0400
Subject: [PATCH 09/35] fix: address Copilot review on the _meta widening
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Widen the three `_meta` annotations the bulk pass missed, all of them
  return types rather than identifier declarations: `mergeMeta`,
  `aggregateListParams`, and the `tools/call` params object. The second was
  unsound in a way callers could see — it advertised
  `{ _meta: Record<string, string> }` while the runtime carried nested JSON.

- `normalizeStoredMetadata`: keep an explicit `null` from a legacy pair
  instead of folding it into `""` (only a missing `value` defaults now), and
  store through `Object.defineProperty` so a legacy `__proto__` key becomes an
  own property rather than hitting the prototype setter.

- Drop the unjustified `as unknown as` from the migration test; the legacy
  fixture is untyped and cast once where it crosses into the typed parser.

- The TUI settings test asserted only that the app mounted, so it could not
  have caught a pair array being forwarded as numeric `_meta` keys. The fake
  client now captures its constructor options and the test asserts the nested
  object arrives intact.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/tui/__tests__/App.test.tsx            | 30 +++++++++++++----
 .../web/src/test/core/mcp/serverList.test.ts  | 33 +++++++++++++++----
 core/mcp/inspectorClient.ts                   |  6 ++--
 core/mcp/serverList.ts                        | 14 +++++++-
 4 files changed, 67 insertions(+), 16 deletions(-)

diff --git a/clients/tui/__tests__/App.test.tsx b/clients/tui/__tests__/App.test.tsx
index 3e749dff..13a13e08 100644
--- a/clients/tui/__tests__/App.test.tsx
+++ b/clients/tui/__tests__/App.test.tsx
@@ -102,7 +102,13 @@ const h = vi.hoisted(() => {
   // handler for the event (the common single-server case).
   type EventEntry = { client: unknown; fn: (event: unknown) => void };
   const clientEvents = new Map<string, Set<EventEntry>>();
-  const clientInstances: Array<{ cfg?: { type?: string; url?: string } }> = [];
+  const clientInstances: Array<{
+    cfg?: { type?: string; url?: string };
+    // The options the mount effect built for this server. Captured so a test
+    // can assert what was actually handed to the client — `defaultMetadata`
+    // in particular, which is otherwise invisible to a render-only assertion.
+    opts?: { defaultMetadata?: unknown };
+  }> = [];
   const fireClientEvent = (event: string, detail?: unknown) => {
     clientEvents.get(event)?.forEach((e) => e.fn({ detail }));
   };
@@ -127,8 +133,13 @@ const h = vi.hoisted(() => {
   }
   class FakeClient {
     cfg: { type?: string; url?: string } | undefined;
-    constructor(config?: { type?: string; url?: string }) {
+    opts: { defaultMetadata?: unknown } | undefined;
+    constructor(
+      config?: { type?: string; url?: string },
+      opts?: { defaultMetadata?: unknown },
+    ) {
       this.cfg = config;
+      this.opts = opts;
       clientInstances.push(this);
     }
     // Derive the transport type from the server config the client was built
@@ -393,10 +404,10 @@ function httpWithSettings(): Record<string, TuiServer> {
       config: { type: "streamable-http", url: "http://x" },
       settings: {
         requestTimeout: 5000,
-        metadata: [
-          { key: "team", value: "alpha" },
-          { key: "  ", value: "ignored" },
-        ],
+        // Object-shaped with a nested value (#1910) — the shape the TUI now
+        // forwards verbatim. As a pair array this would have reached the wire
+        // as numeric `_meta` keys.
+        metadata: { team: "alpha", trace: { id: "abc", hops: [1, 2] } },
         oauthClientId: "cid",
         oauthClientSecret: "secret",
         oauthScopes: "read write",
@@ -1114,6 +1125,13 @@ describe("App (input handling, focus, effects)", () => {
   it("builds a client with saved settings (metadata, oauth, timeout)", async () => {
     const r = await mount(httpWithSettings());
     await expectFrame(r, "MCP Servers");
+    // Not just "it mounted": the saved metadata must reach the client as the
+    // same object, nesting intact (#1910).
+    const web = h.clientInstances.find((c) => c.cfg?.url === "http://x");
+    expect(web?.opts?.defaultMetadata).toEqual({
+      team: "alpha",
+      trace: { id: "abc", hops: [1, 2] },
+    });
   });
 
   it("passes top-level oauth client credentials into an http client", async () => {
diff --git a/clients/web/src/test/core/mcp/serverList.test.ts b/clients/web/src/test/core/mcp/serverList.test.ts
index 13559751..2ad70e4c 100644
--- a/clients/web/src/test/core/mcp/serverList.test.ts
+++ b/clients/web/src/test/core/mcp/serverList.test.ts
@@ -1424,6 +1424,26 @@ describe("normalizeStoredMetadata (#1910)", () => {
     ).toEqual({ kept: "yes" });
   });
 
+  it("preserves an explicit null in a legacy pair rather than blanking it", () => {
+    // `null` is a legal `_meta` value, so the migration must not fold it into
+    // `""` — only a genuinely absent `value` defaults.
+    expect(normalizeStoredMetadata([{ key: "z", value: null }])).toEqual({
+      z: null,
+    });
+  });
+
+  it("stores a legacy `__proto__` key as an own property", () => {
+    // Plain assignment would hit the prototype setter: the entry would vanish
+    // (and an object value would mutate the prototype) instead of being stored.
+    const out = normalizeStoredMetadata([
+      { key: "__proto__", value: { polluted: true } },
+    ]);
+    expect(Object.hasOwn(out, "__proto__")).toBe(true);
+    expect(out["__proto__"]).toEqual({ polluted: true });
+    expect(Object.getPrototypeOf(out)).toBe(Object.prototype);
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+  });
+
   it("reads a legacy pair with no value as an empty string", () => {
     expect(normalizeStoredMetadata([{ key: "k" }])).toEqual({ k: "" });
   });
@@ -1460,18 +1480,19 @@ describe("normalizeStoredMetadata (#1910)", () => {
   it("migrates a legacy file to the object shape on the next write", () => {
     // Read side accepts the pair array; write side emits only the object, so
     // one round-trip is the migration.
-    const entries = mcpConfigToServerEntries({
+    // The legacy on-disk shape no longer matches `MCPConfig` — that is what
+    // the test is about — so the fixture is untyped and cast once where it
+    // crosses into the typed parser, the same boundary a real file crosses.
+    const legacyFile: unknown = {
       mcpServers: {
         legacy: {
           type: "streamable-http",
           url: "https://x.test/mcp",
-          metadata: [{ key: "tenant", value: "acme" }] as unknown as Record<
-            string,
-            never
-          >,
+          metadata: [{ key: "tenant", value: "acme" }],
         },
       },
-    });
+    };
+    const entries = mcpConfigToServerEntries(legacyFile as MCPConfig);
     expect(entries[0]?.settings?.metadata).toEqual({ tenant: "acme" });
     const round = serverEntriesToMcpConfig(entries);
     expect(round.mcpServers.legacy?.metadata).toEqual({ tenant: "acme" });
diff --git a/core/mcp/inspectorClient.ts b/core/mcp/inspectorClient.ts
index c4ad06db..f3febd33 100644
--- a/core/mcp/inspectorClient.ts
+++ b/core/mcp/inspectorClient.ts
@@ -1037,7 +1037,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    */
   private mergeMeta(
     callMetadata?: RequestMetadata,
-  ): Record<string, string> | undefined {
+  ): RequestMetadata | undefined {
     const defaults = this.defaultMetadata;
     // Modern-era per-request log level (#1629): stamp the opt-in `_meta` key on
     // every request so the server emits `notifications/message` on this
@@ -1132,7 +1132,7 @@ export class InspectorClient extends InspectorClientEventTarget {
    */
   private aggregateListParams(
     metadata?: RequestMetadata,
-  ): { _meta: Record<string, string> } | undefined {
+  ): { _meta: RequestMetadata } | undefined {
     const effectiveMeta = this.mergeMeta(metadata);
     return effectiveMeta ? { _meta: effectiveMeta } : undefined;
   }
@@ -4279,7 +4279,7 @@ export class InspectorClient extends InspectorClientEventTarget {
     const callParams: {
       name: string;
       arguments: Record<string, JsonValue>;
-      _meta?: Record<string, string>;
+      _meta?: RequestMetadata;
       task?: { ttl: number };
     } = {
       name: tool.name,
diff --git a/core/mcp/serverList.ts b/core/mcp/serverList.ts
index 5f4b10bc..405bbca2 100644
--- a/core/mcp/serverList.ts
+++ b/core/mcp/serverList.ts
@@ -234,7 +234,19 @@ export function normalizeStoredMetadata(
       }
       const { key, value } = entry as { key: string; value?: JsonValue };
       if (key.trim() === "") continue;
-      out[key] = value ?? "";
+      // `??`, not `||`: `null` is a legal `_meta` value and must survive the
+      // migration as `null`. Only a genuinely absent `value` becomes `""`.
+      //
+      // `defineProperty` rather than `out[key] = …` because a legacy key of
+      // `__proto__` would otherwise hit the prototype setter — silently
+      // dropping the entry (or, for an object value, mutating the prototype)
+      // instead of storing an own property under that name.
+      Object.defineProperty(out, key, {
+        value: value === undefined ? "" : value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
     }
     return out;
   }

From 01572c31b9ed7bfc7a88036c80ff5bc314f5be27 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 13:20:17 -0400
Subject: [PATCH 10/35] docs: note that the CLI does not yet apply catalog
 metadata
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The field table said this payload is "merged into every outgoing request",
which is true of web and the TUI but not the CLI — it never passes the
persisted value to its client, so the setting is inert for `--cli` runs
(#2093). Scope the claim and point at the per-invocation `--metadata` flag as
the CLI workaround, so a CLI user isn't told a setting works when it doesn't.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 docs/mcp-server-configuration.md | 34 +++++++++++++++++---------------
 1 file changed, 18 insertions(+), 16 deletions(-)

diff --git a/docs/mcp-server-configuration.md b/docs/mcp-server-configuration.md
index c6bbd29b..67f98b12 100644
--- a/docs/mcp-server-configuration.md
+++ b/docs/mcp-server-configuration.md
@@ -163,19 +163,19 @@ The file is the familiar MCP client-config shape — an `mcpServers` object keye
 
 These have no analog in the broader `mcp.json` ecosystem. Each is **omitted on write when it equals its default**, so a round-trip through the Inspector keeps the file diff minimal.
 
-| Field                                  | Default    | Meaning                                                                                             |
-| -------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------- |
-| `protocolEra`                          | `"legacy"` | `"legacy"` \| `"auto"` \| `"modern"` — which protocol era to negotiate, orthogonal to the transport |
-| `modernLogLevel`                       | `"debug"`  | Per-request log level stamped on modern connections, or `"off"`. Legacy connections ignore it       |
-| `roots`                                | —          | Roots advertised via the `roots` client capability; each is `{ uri, name? }`                        |
-| `metadata`                             | —          | Default `_meta` payload merged into every outgoing request — a JSON object, values may be any JSON  |
-| `connectionTimeout` / `requestTimeout` | —          | Timeouts in ms                                                                                      |
-| `taskTtl`                              | `60000`    | TTL in ms for tasks created via "Run as task" (`DEFAULT_TASK_TTL_MS`)                               |
-| `autoRefreshOnListChanged`             | `false`    | Refresh lists automatically on `*/list_changed` instead of only flagging the indicator              |
-| `paginatedLists`                       | `false`    | Fetch tools/resources/prompts one page at a time instead of auto-aggregating                        |
-| `advertisedExtensions`                 | —          | Per-extension overrides for what the Inspector declares in `capabilities.extensions`                |
-| `maxFetchRequests`                     | `1000`     | Network-log retention for this server (`DEFAULT_MAX_FETCH_REQUESTS`); `0` means unlimited           |
-| `oauth`                                | —          | `{ clientId, clientSecret, scopes, authorizationParams, authorizationUrl, tokenUrl, enterpriseManaged, onInsufficientScope }` |
+| Field                                  | Default    | Meaning                                                                                                                                            |
+| -------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `protocolEra`                          | `"legacy"` | `"legacy"` \| `"auto"` \| `"modern"` — which protocol era to negotiate, orthogonal to the transport                                                |
+| `modernLogLevel`                       | `"debug"`  | Per-request log level stamped on modern connections, or `"off"`. Legacy connections ignore it                                                      |
+| `roots`                                | —          | Roots advertised via the `roots` client capability; each is `{ uri, name? }`                                                                       |
+| `metadata`                             | —          | Default `_meta` payload merged into every outgoing request — a JSON object, values may be any JSON. Web and TUI only today; see the CLI note below |
+| `connectionTimeout` / `requestTimeout` | —          | Timeouts in ms                                                                                                                                     |
+| `taskTtl`                              | `60000`    | TTL in ms for tasks created via "Run as task" (`DEFAULT_TASK_TTL_MS`)                                                                              |
+| `autoRefreshOnListChanged`             | `false`    | Refresh lists automatically on `*/list_changed` instead of only flagging the indicator                                                             |
+| `paginatedLists`                       | `false`    | Fetch tools/resources/prompts one page at a time instead of auto-aggregating                                                                       |
+| `advertisedExtensions`                 | —          | Per-extension overrides for what the Inspector declares in `capabilities.extensions`                                                               |
+| `maxFetchRequests`                     | `1000`     | Network-log retention for this server (`DEFAULT_MAX_FETCH_REQUESTS`); `0` means unlimited                                                          |
+| `oauth`                                | —          | `{ clientId, clientSecret, scopes, authorizationParams, authorizationUrl, tokenUrl, enterpriseManaged, onInsufficientScope }`                      |
 
 `metadata` is a JSON **object**, and its values may be any JSON — an object, an array, a number, a boolean, `null` — not only a string. Nothing in the MCP spec restricts `_meta` value types, and the SDK models the field as a passthrough object, so the Inspector does not narrow it either ([#1910](https://github.com/modelcontextprotocol/inspector/issues/1910)). Edit it in Server Settings → Request Metadata, which is a JSON editor rather than the key/value rows `headers` and `env` use; text that is not a JSON object is flagged inline and not applied.
 
@@ -187,17 +187,19 @@ These have no analog in the broader `mcp.json` ecosystem. Each is **omitted on w
 }
 ```
 
+> **Not yet applied by the CLI.** The web client and the TUI both send this payload on every request. The CLI does not — it never passes the persisted value to its client, so a `metadata` entry is currently inert for `--cli` runs ([#2093](https://github.com/modelcontextprotocol/inspector/issues/2093)). Use the per-invocation `--metadata` flag there in the meantime.
+
 > **Reading an older file.** Before #1910 this field was a `[{ "key": …, "value": … }]` pair array. That shape is still **read**, so an existing `mcp.json` keeps working unchanged; it is never written back, so the field is rewritten as an object the next time the Inspector saves the entry.
 
 `oauth.authorizationParams` is a string→string record of extra query parameters merged into the OAuth **authorization request** URL only — never the token request. Use it for provider-specific hints the core specs don't standardize (Keycloak's `kc_idp_hint`, OIDC's `login_hint` / `prompt` / `acr_values`, Auth0's `audience`). The protocol-critical parameters — `client_id`, `code_challenge`, `code_challenge_method`, `redirect_uri`, `resource`, `response_type`, `scope`, `state` — are **reserved**: the web form rejects them inline, and any that reach the merge anyway are dropped with a warning rather than overriding what the flow set (overriding them breaks PKCE, the CSRF state binding, or RFC 8707). Edit them in Server Settings → Authorization ("Additional authorization parameters"), beside Scopes.
 
-`oauth.authorizationUrl` and `oauth.tokenUrl` override the `authorization_endpoint` and `token_endpoint` that authorization-server metadata discovery resolved. The Inspector deliberately has no such fields by default — it resolves both from the AS's metadata document, exactly as a real MCP host does — but a server under development often advertises its *production* authorization server while you want to hit staging. Set either (they are independent) to an absolute `http(s)` URL and it replaces what the metadata returned, for both the authorization request and the token request; leave blank to use discovery. A malformed value is flagged inline in the form and dropped with a warning at connect time rather than failing the connection. Edit them in Server Settings → Authorization ("Authorization URL override" / "Token URL override").
+`oauth.authorizationUrl` and `oauth.tokenUrl` override the `authorization_endpoint` and `token_endpoint` that authorization-server metadata discovery resolved. The Inspector deliberately has no such fields by default — it resolves both from the AS's metadata document, exactly as a real MCP host does — but a server under development often advertises its _production_ authorization server while you want to hit staging. Set either (they are independent) to an absolute `http(s)` URL and it replaces what the metadata returned, for both the authorization request and the token request; leave blank to use discovery. A malformed value is flagged inline in the form and dropped with a warning at connect time rather than failing the connection. Edit them in Server Settings → Authorization ("Authorization URL override" / "Token URL override").
 
-They redirect the **endpoints**, not the authorization server's identity: `issuer` is left exactly as discovery returned it, because that is what RFC 9207 / SEP-2352 validate the callback's `iss` against to defend against an authorization-server mix-up. So they fit alternate endpoints of the *same* logical issuer — a staging deployment fronting the same issuer, a local proxy. Point one at an authorization server advertising a **different** issuer and the callback is rejected as an issuer mismatch before the code is redeemed; that is the mix-up defense working, and it is not disabled to make the override succeed.
+They redirect the **endpoints**, not the authorization server's identity: `issuer` is left exactly as discovery returned it, because that is what RFC 9207 / SEP-2352 validate the callback's `iss` against to defend against an authorization-server mix-up. So they fit alternate endpoints of the _same_ logical issuer — a staging deployment fronting the same issuer, a local proxy. Point one at an authorization server advertising a **different** issuer and the callback is rejected as an issuer mismatch before the code is redeemed; that is the mix-up defense working, and it is not disabled to make the override succeed.
 
 They are **not applied under enterprise-managed authorization** (`oauth.enterpriseManaged`), for the same reason `oauth.authorizationParams` isn't: that flow authorizes against the enterprise IdP — a different authorization server, whose OIDC discovery would otherwise be rewritten too, pointing the IdP login (or the IdP code exchange) at the resource server's authorization server.
 
-> Because the override is applied to the *discovered metadata document*, a server whose authorization server publishes no metadata at all is unaffected — there the SDK falls back to `/authorize` and `/token` on the AS origin, and there is nothing to override.
+> Because the override is applied to the _discovered metadata document_, a server whose authorization server publishes no metadata at all is unaffected — there the SDK falls back to `/authorize` and `/token` on the AS origin, and there is nothing to override.
 
 A catalog carrying these fields:
 

From e9dc0e5e5fce9ccacb04c85db55a6ed631975cc7 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 13:36:45 -0400
Subject: [PATCH 11/35] fix: drop a schema-invalid `_meta.progressToken`
 instead of sending it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`progressToken` is a reserved `_meta` member the spec constrains to
`string | integer` (`ProgressTokenSchema = z.union([z.string(),
z.number().int()])`). Every other value may be any JSON after #1910, which is
what makes this one key need its own check: before the widening a value was
always a string and therefore always valid, but now a float, an object or an
array can land there, and a conforming server would reject the whole request.

`progressTokenOf` only governed whether a progress callback was wired up, so a
bad value still rode out inside `_meta`. Sanitize in `mergeMeta` instead — the
single point every `_meta` flows through — dropping just the offending member
with a warning. The key is optional, so the request stays well-formed and
simply asks for no progress.

Note the exposure only exists with `progress: false`. With progress on (the
default) the SDK sets `onprogress` and stamps its own message id over
`_meta.progressToken`, so a caller's value never reaches the wire either way.
The new tests therefore run with progress disabled, which is the configuration
that can actually ship a bad token: five invalid shapes dropped (float, object,
array, null, boolean) with the sibling keys left intact, and string/integer
preserved.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../integration/mcp/inspectorClient.test.ts   | 84 +++++++++++++++++++
 core/mcp/inspectorClient.ts                   | 35 +++++++-
 2 files changed, 116 insertions(+), 3 deletions(-)

diff --git a/clients/web/src/test/integration/mcp/inspectorClient.test.ts b/clients/web/src/test/integration/mcp/inspectorClient.test.ts
index 9fbb0608..78e25418 100644
--- a/clients/web/src/test/integration/mcp/inspectorClient.test.ts
+++ b/clients/web/src/test/integration/mcp/inspectorClient.test.ts
@@ -1412,6 +1412,90 @@ describe("InspectorClient", () => {
       messageLogState.destroy();
     });
 
+    it.each([
+      ["a float", 3.5],
+      ["an object", { id: 1 }],
+      ["an array", [1]],
+      ["null", null],
+      ["a boolean", true],
+    ])(
+      "drops a reserved progressToken that is %s rather than sending it",
+      async (_label, badToken) => {
+        // Every other `_meta` value may be any JSON (#1910), but the spec
+        // constrains `progressToken` to `string | integer`
+        // (`ProgressTokenSchema`). Sending a bad one would make a conforming
+        // server reject the whole request, so the member is dropped — the key
+        // is optional, so what goes out is still well-formed.
+        //
+        // `progress: false` is what makes this observable. With progress on
+        // (the default) the SDK sets `onprogress` and stamps its own message
+        // id over `_meta.progressToken`, so a caller's value never reaches the
+        // wire either way; with it off nothing overwrites the member and a bad
+        // one would ship.
+        client = new InspectorClient(
+          {
+            type: "stdio",
+            command: serverCommand.command,
+            args: serverCommand.args,
+          },
+          {
+            environment: { transport: createTransportNode },
+            progress: false,
+            defaultMetadata: { progressToken: badToken, keep: "me" },
+          },
+        );
+        const messageLogState = new MessageLogState(client);
+        await client.connect();
+        await client.listTools();
+
+        const listToolsReq = messageLogState
+          .getMessages()
+          .find(
+            (m) =>
+              m.direction === "request" &&
+              (m.message as { method?: string }).method === "tools/list",
+          );
+        expect(listToolsReq).toBeDefined();
+        const meta = metaOf(listToolsReq!);
+        expect(meta).not.toHaveProperty("progressToken");
+        // Only the offending member is dropped, not the whole payload.
+        expect(meta.keep).toBe("me");
+        messageLogState.destroy();
+      },
+    );
+
+    it.each([
+      ["a string", "tok-1"],
+      ["an integer", 7],
+    ])("keeps a valid progressToken that is %s", async (_label, token) => {
+      client = new InspectorClient(
+        {
+          type: "stdio",
+          command: serverCommand.command,
+          args: serverCommand.args,
+        },
+        {
+          environment: { transport: createTransportNode },
+          // See the note above: with progress on, the SDK overwrites this.
+          progress: false,
+          defaultMetadata: { progressToken: token },
+        },
+      );
+      const messageLogState = new MessageLogState(client);
+      await client.connect();
+      await client.listTools();
+
+      const listToolsReq = messageLogState
+        .getMessages()
+        .find(
+          (m) =>
+            m.direction === "request" &&
+            (m.message as { method?: string }).method === "tools/list",
+        );
+      expect(metaOf(listToolsReq!).progressToken).toBe(token);
+      messageLogState.destroy();
+    });
+
     it("call-time metadata overrides defaultMetadata on key collision", async () => {
       client = new InspectorClient(
         {
diff --git a/core/mcp/inspectorClient.ts b/core/mcp/inspectorClient.ts
index f3febd33..a51b0e2e 100644
--- a/core/mcp/inspectorClient.ts
+++ b/core/mcp/inspectorClient.ts
@@ -369,6 +369,22 @@ interface ToolCallRequest {
 // server can't spin a tight zero-delay loop; a successful acknowledgement resets
 // the count, and past the cap we give up (mark the stream ended) rather than
 // retry a persistently-failing re-list forever.
+/**
+ * Whether a `_meta.progressToken` value is one the protocol allows.
+ *
+ * The spec (and the SDK's `ProgressTokenSchema`,
+ * `z.union([z.string(), z.number().int()])`) constrains this reserved member to
+ * a string or an **integer** — a float is as invalid as an object. Everything
+ * else in `_meta` may be any JSON (#1910), which is exactly why this one key
+ * needs its own check.
+ */
+function isProgressToken(value: unknown): value is ProgressToken {
+  return (
+    typeof value === "string" ||
+    (typeof value === "number" && Number.isInteger(value))
+  );
+}
+
 const MODERN_RECONNECT_BASE_MS = 500;
 const MODERN_RECONNECT_MAX_MS = 15_000;
 const MODERN_RECONNECT_MAX_ATTEMPTS = 8;
@@ -1053,6 +1069,21 @@ export class InspectorClient extends InspectorClientEventTarget {
       ...(logMeta ?? {}),
       ...(callMetadata ?? {}),
     };
+    // `_meta` values are arbitrary JSON (#1910), but `progressToken` is a
+    // reserved member the spec constrains to `string | integer`
+    // (`ProgressTokenSchema = z.union([z.string(), z.number().int()])`). Now
+    // that a value can be an object, an array or a float, a bad one would ride
+    // out on the wire and a conforming server would reject the whole request —
+    // so drop the member rather than send something invalid. It is optional, so
+    // the request stays well-formed and simply asks for no progress. Warn,
+    // because a silently dropped key the user typed is worse than a noisy one.
+    if ("progressToken" in merged && !isProgressToken(merged.progressToken)) {
+      this.logger.warn(
+        { progressToken: merged.progressToken },
+        "Dropping `_meta.progressToken` — expected a string or an integer.",
+      );
+      delete merged.progressToken;
+    }
     return Object.keys(merged).length > 0 ? merged : undefined;
   }
 
@@ -1071,9 +1102,7 @@ export class InspectorClient extends InspectorClientEventTarget {
     metadata: RequestMetadata | undefined,
   ): ProgressToken | undefined {
     const token = metadata?.progressToken;
-    return typeof token === "string" || typeof token === "number"
-      ? token
-      : undefined;
+    return isProgressToken(token) ? token : undefined;
   }
 
   private getRequestOptions(

From f3878f94a902f75ea8fdaf20d1ed3d434f818fd9 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 13:49:55 -0400
Subject: [PATCH 12/35] fix: widen the test recorder's metadata type and
 correct a stale comment
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`RecordedRequest.metadata` was still `Record<string, string>`, so the recorder
advertised a string-only contract it no longer honors. The new CLI tests assert
objects and arrays against it and passed only because `toEqual` does not
enforce the declared type.

Typed as `Record<string, unknown>` rather than core's `RequestMetadata`:
test-servers compiles standalone (`tsc -p test-servers`, NodeNext, no `paths`),
so it has no `@inspector/core` alias to import through.

Also update `progressTokenOf`'s doc comment, which still claimed an invalid
token "reaches the wire inside `_meta`" — untrue since mergeMeta started
deleting it. It now names the split: progressTokenOf governs callback
correlation, mergeMeta governs wire sanitization, both via isProgressToken.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 core/mcp/inspectorClient.ts          | 12 ++++++------
 test-servers/src/test-server-http.ts | 13 ++++++++++++-
 2 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/core/mcp/inspectorClient.ts b/core/mcp/inspectorClient.ts
index a51b0e2e..ecec24ef 100644
--- a/core/mcp/inspectorClient.ts
+++ b/core/mcp/inspectorClient.ts
@@ -1091,12 +1091,12 @@ export class InspectorClient extends InspectorClientEventTarget {
    * The `progressToken` a caller stamped on its request metadata, when it is
    * one the SDK will accept.
    *
-   * `_meta` values are arbitrary JSON (#1910), but `progressToken` is a
-   * reserved key the spec types as `string | number`. Anything else — an
-   * object, an array, `null`, a boolean — is not a token the SDK can correlate
-   * a `notifications/progress` back to, so it is read as "no token" rather than
-   * forwarded. The key still reaches the wire inside `_meta`; this only governs
-   * whether the client wires up a progress callback for it.
+   * This governs only **callback correlation** — whether the client wires up an
+   * `onprogress` for the request. Keeping an invalid value off the **wire** is
+   * a separate concern handled in {@link mergeMeta}, which deletes the member
+   * from the outgoing `_meta` so a conforming server is never sent something
+   * `ProgressTokenSchema` rejects. The two use the same {@link isProgressToken}
+   * predicate, so they cannot disagree about what counts as valid.
    */
   private progressTokenOf(
     metadata: RequestMetadata | undefined,
diff --git a/test-servers/src/test-server-http.ts b/test-servers/src/test-server-http.ts
index bbbb47ce..b8a5007f 100644
--- a/test-servers/src/test-server-http.ts
+++ b/test-servers/src/test-server-http.ts
@@ -83,7 +83,18 @@ export interface RecordedRequest {
   method: string;
   params?: Record<string, unknown>;
   headers?: Record<string, string>;
-  metadata?: Record<string, string>;
+  /**
+   * The request's `_meta`, recorded verbatim. Values are arbitrary JSON —
+   * objects, arrays, numbers, booleans, `null` — not just strings (#1910), so
+   * a test asserting on a structured value gets a contract that matches what
+   * the recorder actually holds.
+   *
+   * Typed as `unknown` values rather than `@inspector/core`'s
+   * `RequestMetadata`: this package compiles standalone (`tsc -p test-servers`,
+   * NodeNext, no `paths`), so it has no `@inspector/core` alias to import
+   * through.
+   */
+  metadata?: Record<string, unknown>;
   response: unknown;
   timestamp: number;
 }

From 85e4a299905438b6c855c9fca02b9c839ceced97 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 14:03:40 -0400
Subject: [PATCH 13/35] fix: redact secrets nested inside metadata in
 `servers/show`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The redaction checked only top-level keys. That was sufficient while values
were strings — a secret could not hide beneath one — but #1910 lets a value be
an object, so `{ trace: { accessToken: "…" } }` printed in full: `trace` is not
sensitive, so the whole subtree went out with it. `servers/show` output is
meant to be safe to paste into an issue, so this is a regression this PR
introduced rather than a pre-existing gap.

`redactMetadataValue` walks the payload: a key matching `isSensitiveHeader`
replaces its entire value (so a sensitive key holding an object cannot leak
through its members either), anything else is descended into, and arrays are
mapped elementwise since objects inside them can carry sensitive keys.
Recursion is bounded — the payload came from `JSON.parse`, so it is a finite
tree with no cycles.

Tests cover a secret two levels under a non-sensitive key and one inside an
array element.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/cli/__tests__/servers-list.test.ts | 18 ++++++++-
 clients/cli/src/handlers/servers-list.ts   | 46 +++++++++++++++++-----
 2 files changed, 54 insertions(+), 10 deletions(-)

diff --git a/clients/cli/__tests__/servers-list.test.ts b/clients/cli/__tests__/servers-list.test.ts
index 5772ab3e..daa1c444 100644
--- a/clients/cli/__tests__/servers-list.test.ts
+++ b/clients/cli/__tests__/servers-list.test.ts
@@ -226,6 +226,15 @@ describe("showServerEntry / servers/show", () => {
         // the whole value, not walk into it (#1910).
         "X-Api-Key": { primary: "sk-live-1", fallback: "sk-live-2" },
         nested: { keep: true },
+        // A secret buried under a non-sensitive key. A top-level-only check
+        // would print `accessToken` in full.
+        trace: {
+          id: "t-1",
+          accessToken: "sk-live-3",
+          deeper: { refresh_token: "sk-live-4", ok: 1 },
+        },
+        // Objects inside an array are reached too.
+        attempts: [{ password: "hunter2" }, { attempt: 2 }],
       },
       env: [
         { key: "TOKEN", value: "secret" },
@@ -250,8 +259,15 @@ describe("showServerEntry / servers/show", () => {
       Authorization: "[redacted]",
       "X-Custom": "ok",
       "X-Api-Key": "[redacted]",
-      // A structured value under a non-sensitive key survives intact.
+      // A structured value under a non-sensitive key survives intact...
       nested: { keep: true },
+      // ...but a sensitive key nested inside one does not.
+      trace: {
+        id: "t-1",
+        accessToken: "[redacted]",
+        deeper: { refresh_token: "[redacted]", ok: 1 },
+      },
+      attempts: [{ password: "[redacted]" }, { attempt: 2 }],
     });
     expect(sanitized.env).toEqual([
       { key: "TOKEN", value: "[redacted]" },
diff --git a/clients/cli/src/handlers/servers-list.ts b/clients/cli/src/handlers/servers-list.ts
index d0247851..d580f47c 100644
--- a/clients/cli/src/handlers/servers-list.ts
+++ b/clients/cli/src/handlers/servers-list.ts
@@ -157,15 +157,10 @@ export function sanitizeServerSettings(
       key: h.key,
       value: isSensitiveHeader(h.key) ? REDACTED : h.value,
     })),
-    // Metadata is a JSON object whose values may be any JSON (#1910), so the
-    // redaction replaces the whole value rather than a string — a sensitive
-    // key holding an object must not leak through its members.
-    metadata: Object.fromEntries(
-      Object.entries(settings.metadata ?? {}).map(([key, value]) => [
-        key,
-        isSensitiveHeader(key) ? REDACTED : value,
-      ]),
-    ),
+    // Metadata values may be any JSON (#1910), so the redaction has to descend:
+    // a top-level key that is not itself sensitive can hold a nested one that
+    // is. See `redactMetadataValue`.
+    metadata: redactMetadataValue(settings.metadata ?? {}),
     env: (settings.env ?? []).map((e) => ({
       key: e.key,
       value: REDACTED,
@@ -217,6 +212,39 @@ function sanitizeInitRecord(
   return out;
 }
 
+/**
+ * Redact secret-bearing entries anywhere inside a `_meta` payload.
+ *
+ * The pre-#1910 version only had to check the top level, because a value was
+ * always a string — a secret could not hide below one. Now that a value may be
+ * an object or an array, `{ trace: { accessToken: "…" } }` would sail through a
+ * top-level-only check: `trace` is not sensitive, so the whole subtree,
+ * `accessToken` included, would print. `servers/show` output is meant to be
+ * safe to paste into an issue, so the walk has to reach every key.
+ *
+ * A key matching {@link isSensitiveHeader} replaces its **entire** value rather
+ * than being descended into, so a sensitive key holding an object cannot leak
+ * through its members either. Arrays are mapped elementwise: their indices are
+ * not names anyone can mark sensitive, but objects inside them can be.
+ *
+ * Recursion is bounded by the payload, which came from `JSON.parse` and so is a
+ * finite tree with no cycles.
+ */
+function redactMetadataValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(redactMetadataValue);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, member]) => [
+        key,
+        isSensitiveHeader(key) ? REDACTED : redactMetadataValue(member),
+      ]),
+    );
+  }
+  return value;
+}
+
 function isSensitiveHeader(key: string): boolean {
   const k = key.toLowerCase();
   return (

From ae9536b1710046f6aacc68946b6c53d7b04c4db6 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 14:19:48 -0400
Subject: [PATCH 14/35] fix: log the rejected progressToken's type, not its
 value
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The warning added one commit earlier echoed the rejected value. That is the
same leak class as the `servers/show` fix: `_meta` now carries arbitrary JSON,
so an invalid `progressToken` can be an object holding credentials — and this
logger is persisted by real clients (`clients/tui/src/logger.ts` writes it to
`~/.mcp-inspector/auth.log` via `pino.destination`, append mode).

Log `{ received: describeJsonType(value) }` instead — "object", "array",
"number". That is what makes the warning actionable; the value itself only
leaks.

Test asserts the record is exactly `{ received: "object" }` and that the
planted secret appears nowhere in the captured calls.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../integration/mcp/inspectorClient.test.ts   | 44 +++++++++++++++++++
 core/mcp/inspectorClient.ts                   | 17 ++++++-
 2 files changed, 60 insertions(+), 1 deletion(-)

diff --git a/clients/web/src/test/integration/mcp/inspectorClient.test.ts b/clients/web/src/test/integration/mcp/inspectorClient.test.ts
index 78e25418..f0c85846 100644
--- a/clients/web/src/test/integration/mcp/inspectorClient.test.ts
+++ b/clients/web/src/test/integration/mcp/inspectorClient.test.ts
@@ -55,6 +55,7 @@ import type {
   FetchRequestEntryBase,
   RequestMetadata,
 } from "@inspector/core/mcp/types.js";
+import type { InspectorLogger } from "@inspector/core/logging/logger.js";
 import type { JsonValue } from "@inspector/core/json/jsonUtils.js";
 import type {
   TypedEvent,
@@ -1464,6 +1465,49 @@ describe("InspectorClient", () => {
       },
     );
 
+    it("warns with the rejected progressToken's type, never its value", async () => {
+      // This logger is persisted by real clients (the TUI writes it to
+      // `~/.mcp-inspector/auth.log`), and an invalid `progressToken` can now be
+      // an object holding credentials — so the warning must not echo it.
+      const warn = vi.fn();
+      const noop = () => {};
+      const logger: InspectorLogger = {
+        level: "warn",
+        fatal: noop,
+        error: noop,
+        warn,
+        info: noop,
+        debug: noop,
+        trace: noop,
+        silent: noop,
+        child: () => logger,
+      };
+      client = new InspectorClient(
+        {
+          type: "stdio",
+          command: serverCommand.command,
+          args: serverCommand.args,
+        },
+        {
+          environment: { transport: createTransportNode, logger },
+          progress: false,
+          defaultMetadata: {
+            progressToken: { accessToken: "sk-live-should-not-appear" },
+          },
+        },
+      );
+      await client.connect();
+      await client.listTools();
+
+      const call = warn.mock.calls.find((c) =>
+        String(c[1]).includes("progressToken"),
+      );
+      expect(call).toBeDefined();
+      expect(call![0]).toEqual({ received: "object" });
+      // Belt and braces: the secret must not appear anywhere in the record.
+      expect(JSON.stringify(warn.mock.calls)).not.toContain("sk-live");
+    });
+
     it.each([
       ["a string", "tok-1"],
       ["an integer", 7],
diff --git a/core/mcp/inspectorClient.ts b/core/mcp/inspectorClient.ts
index ecec24ef..b1d6689f 100644
--- a/core/mcp/inspectorClient.ts
+++ b/core/mcp/inspectorClient.ts
@@ -369,6 +369,16 @@ interface ToolCallRequest {
 // server can't spin a tight zero-delay loop; a successful acknowledgement resets
 // the count, and past the cap we give up (mark the stream ended) rather than
 // retry a persistently-failing re-list forever.
+/**
+ * A one-word name for a JSON value's type, for diagnostics that must not
+ * disclose the value itself.
+ */
+function describeJsonType(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
 /**
  * Whether a `_meta.progressToken` value is one the protocol allows.
  *
@@ -1078,8 +1088,13 @@ export class InspectorClient extends InspectorClientEventTarget {
     // the request stays well-formed and simply asks for no progress. Warn,
     // because a silently dropped key the user typed is worse than a noisy one.
     if ("progressToken" in merged && !isProgressToken(merged.progressToken)) {
+      // Log the rejected value's *type*, never the value. `_meta` now carries
+      // arbitrary JSON, so an invalid `progressToken` can be an object holding
+      // credentials — and this logger is persisted by real clients (the TUI
+      // writes it to `~/.mcp-inspector/auth.log`). The type is what makes the
+      // warning actionable anyway; the value would only leak.
       this.logger.warn(
-        { progressToken: merged.progressToken },
+        { received: describeJsonType(merged.progressToken) },
         "Dropping `_meta.progressToken` — expected a string or an integer.",
       );
       delete merged.progressToken;

From ed799a0c0bddb4cc9749f2721e15d2b9bf019adc Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 16:54:58 -0400
Subject: [PATCH 15/35] feat(web): use the Ace editor for the request-metadata
 JSON
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A textarea is a poor place to hand-write a nested `_meta` payload. Ace closes a
brace when you open one, folds nested objects, and — through its JSON worker —
marks the offending line in the gutter instead of reporting one message for the
whole document.

Three things the swap turned up:

- Ace fires *two* change events for a replace (a remove, then an insert), so
  select-all-and-retype briefly leaves an empty document. Acting on the first
  emitted `{}` and wiped the user's saved metadata the instant they selected
  it. `handleChange` now coalesces the pair in a microtask, and the component
  tracks what it last emitted so the parent echoing that value back is not
  mistaken for an external reset.

- Ace's own `github` themes fail WCAG AA on the gutter — `#AAA` on `#e8e8e8` is
  1.89:1, and the dark theme is 4.13:1. Folding needs the gutter, so the colors
  are overridden with palette tokens (5.82:1 and 4.88:1) rather than hiding it.

- `textInputAriaLabel` alone never reaches the DOM: Ace composes the label as
  "<label>, Cursor at row N" and only recomputes it when the cursor moves, so
  it is forced once on load. Until then the control's only accessible name is a
  position readout.

Testing is split because Ace's input path does not work under happy-dom at all
— `userEvent.type` reaches the textarea and produces no edit, so a test written
that way asserts nothing. Unit tests drive the editor instance through a shared
`src/test/aceEditor.ts` helper; the real keyboard behaviour (`{` then Enter
giving `{\n  \n}`) is asserted by Storybook play functions in Chromium.

`react-ace`/`ace-builds` are declared in `clients/web` rather than the root, per
the rule for a dependency that renders React components.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/package-lock.json                 |  39 ++++
 clients/web/package.json                      |   2 +
 clients/web/src/App.css                       |  22 +++
 .../JsonObjectInput.stories.tsx               | 122 +++++++++++--
 .../JsonObjectInput/JsonObjectInput.test.tsx  |  91 ++++++----
 .../JsonObjectInput/JsonObjectInput.tsx       | 171 +++++++++++++++---
 .../ServerSettingsForm.test.tsx               |  13 +-
 .../ServerSettingsForm/ServerSettingsForm.tsx |   3 +-
 .../ServerSettingsModal.test.tsx              |   5 +-
 clients/web/src/test/aceEditor.ts             |  58 ++++++
 10 files changed, 432 insertions(+), 94 deletions(-)
 create mode 100644 clients/web/src/test/aceEditor.ts

diff --git a/clients/web/package-lock.json b/clients/web/package-lock.json
index b92eff57..e4233a49 100644
--- a/clients/web/package-lock.json
+++ b/clients/web/package-lock.json
@@ -16,6 +16,7 @@
         "@mantine/hooks": "^8.3.17",
         "@mantine/notifications": "^8.3.17",
         "@napi-rs/keyring": "^1.3.0",
+        "ace-builds": "^1.44.0",
         "ajv": "^8.17.1",
         "atomically": "^2.1.1",
         "chokidar": "^4.0.3",
@@ -25,6 +26,7 @@
         "papaparse": "^5.5.4",
         "pino": "^9.14.0",
         "react": "^19.2.4",
+        "react-ace": "^15.0.0",
         "react-dom": "^19.2.4",
         "react-icons": "^5.6.0",
         "react-markdown": "^10.1.0",
@@ -4383,6 +4385,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/ace-builds": {
+      "version": "1.44.0",
+      "resolved": "https://registry.npmjs.org/ace-builds/-/ace-builds-1.44.0.tgz",
+      "integrity": "sha512-PFNMSYqFdEUkul2Ntud0HvA09AgY+F1ag0UYdpMH60wNI/qOA8cB8tlTgoALMEwIdUPJK2CjrIQ7OnbiSS/ugQ==",
+      "license": "BSD-3-Clause"
+    },
     "node_modules/acorn": {
       "version": "8.18.0",
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.18.0.tgz",
@@ -5061,6 +5069,12 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/diff-match-patch": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/diff-match-patch/-/diff-match-patch-1.0.5.tgz",
+      "integrity": "sha512-IayShXAgj/QMXgB0IWmKx+rOPuGMhqm5w6jvFxmVenXKIzRqTAAsbBPT3kWQeGANj3jGgvcvv4yK6SxqYmikgw==",
+      "license": "Apache-2.0"
+    },
     "node_modules/doctrine": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/doctrine/-/doctrine-3.0.0.tgz",
@@ -5487,6 +5501,15 @@
       "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
       "license": "MIT"
     },
+    "node_modules/fast-equals": {
+      "version": "5.4.1",
+      "resolved": "https://registry.npmjs.org/fast-equals/-/fast-equals-5.4.1.tgz",
+      "integrity": "sha512-DjlFSM5Pk9cGcL0q5QXl66eGzx0N6szNgaswwc5ZphlBohjTVJSnGgI+rJVOgOi65qUoQnDZN4nDqi33udtydQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
     "node_modules/fast-json-stable-stringify": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz",
@@ -8294,6 +8317,22 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/react-ace": {
+      "version": "15.0.0",
+      "resolved": "https://registry.npmjs.org/react-ace/-/react-ace-15.0.0.tgz",
+      "integrity": "sha512-gdmS5ftF0hsbkcrAjZQqYbXwFg5JrHuxjki8mP6Bn9kfa6lHKfZk9sU9EfS0ifQ1CpGCmRxF/VC7GRvlJMBuZw==",
+      "license": "MIT",
+      "dependencies": {
+        "ace-builds": "^1.36.3",
+        "diff-match-patch": "^1.0.5",
+        "fast-equals": "^5.3.3",
+        "prop-types": "^15.8.1"
+      },
+      "peerDependencies": {
+        "react": "^0.13.0 || ^0.14.0 || ^15.0.1 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-dom": "^0.13.0 || ^0.14.0 || ^15.0.1 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
     "node_modules/react-docgen": {
       "version": "8.0.3",
       "resolved": "https://registry.npmjs.org/react-docgen/-/react-docgen-8.0.3.tgz",
diff --git a/clients/web/package.json b/clients/web/package.json
index 451c0767..8696fb25 100644
--- a/clients/web/package.json
+++ b/clients/web/package.json
@@ -42,6 +42,7 @@
     "@mantine/hooks": "^8.3.17",
     "@mantine/notifications": "^8.3.17",
     "@napi-rs/keyring": "^1.3.0",
+    "ace-builds": "^1.44.0",
     "ajv": "^8.17.1",
     "atomically": "^2.1.1",
     "chokidar": "^4.0.3",
@@ -51,6 +52,7 @@
     "papaparse": "^5.5.4",
     "pino": "^9.14.0",
     "react": "^19.2.4",
+    "react-ace": "^15.0.0",
     "react-dom": "^19.2.4",
     "react-icons": "^5.6.0",
     "react-markdown": "^10.1.0",
diff --git a/clients/web/src/App.css b/clients/web/src/App.css
index b208285c..a32c6435 100644
--- a/clients/web/src/App.css
+++ b/clients/web/src/App.css
@@ -73,6 +73,16 @@
      ScrollArea would break flex sizing, e.g. the Resources accordion) blend in. */
   --inspector-scrollbar-thumb: rgba(0, 0, 0, 0.4);
 
+  /* ── Code editor (Ace) ─────────────────────────────────── */
+  /* Ace's own `github` themes fail WCAG AA on the gutter: `#AAA` on the light
+     gutter's `#e8e8e8` is 1.89:1, and `#7388b5` on the dark gutter's `#24292e`
+     is 4.13:1 — both under 4.5:1 at the 12px the line numbers render. The
+     numbers are `aria-hidden`, which exempts nothing here: contrast is a
+     concern for sighted users, and axe flags them accordingly.
+     `gray-7` is 5.82:1 on the light gutter; the dark block lifts it to
+     `gray-5`, 4.88:1 on the dark one. */
+  --inspector-code-gutter-text: var(--mantine-color-gray-7);
+
   /* ── Connection status ─────────────────────────────────── */
   --inspector-status-connected: var(--mantine-color-green-6);
   --inspector-status-connecting: var(--mantine-color-yellow-6);
@@ -161,6 +171,9 @@
      schemes, which sits too dark on charcoal — lift them one to two steps so
      they stay legible in dark mode. Light-mode `:root` keeps the `*-6` values. */
 
+  /* Code editor (Ace) — see the note in `:root`. */
+  --inspector-code-gutter-text: var(--mantine-color-gray-5);
+
   /* Status */
   --inspector-status-connected: var(--mantine-color-green-4);
   --inspector-status-connecting: var(--mantine-color-yellow-4);
@@ -593,3 +606,12 @@ body.resizing-col {
   user-select: none;
   cursor: col-resize;
 }
+
+/* Ace renders its own DOM, so its gutter can only be reached by selector — it
+   is not a Mantine component with a theme entry. The doubled class raises
+   specificity above Ace's own `.ace-github .ace_gutter`, which is injected into
+   <head> at runtime and therefore wins on source order otherwise. */
+.ace_editor.ace-github .ace_gutter,
+.ace_editor.ace-github-dark .ace_gutter {
+  color: var(--inspector-code-gutter-text);
+}
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.stories.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.stories.tsx
index 51405384..cdbcfc0f 100644
--- a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.stories.tsx
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.stories.tsx
@@ -4,17 +4,23 @@ import { expect, userEvent, within } from "storybook/test";
 import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
 import { JsonObjectInput } from "./JsonObjectInput";
 
+const LABEL = "Request metadata JSON";
+
 /**
  * The component is controlled, so every story drives it through a small
- * stateful wrapper — otherwise the box would not accept a keystroke and the
+ * stateful wrapper — otherwise the editor would not accept a keystroke and the
  * play functions could not exercise the draft behavior at all.
+ *
+ * These stories run in real Chromium, which is what makes them the *only*
+ * place Ace's keyboard behavior can be tested: the unit suite runs in
+ * happy-dom, where Ace's hidden-textarea input path does not work at all.
  */
 function ControlledJsonObjectInput({ initial }: { initial: JsonObject }) {
   const [value, setValue] = useState<JsonObject>(initial);
   return (
     <JsonObjectInput
       label="Request metadata"
-      aria-label="Request metadata JSON"
+      ariaLabel={LABEL}
       value={value}
       onChange={setValue}
     />
@@ -29,6 +35,57 @@ const meta: Meta<typeof ControlledJsonObjectInput> = {
 export default meta;
 type Story = StoryObj<typeof ControlledJsonObjectInput>;
 
+/** The live editor instance, which Ace hangs off its container as `env.editor`. */
+function aceEditor(canvasElement: HTMLElement): {
+  focus(): void;
+  selectAll(): void;
+  getValue(): string;
+} {
+  const container = canvasElement.querySelector(".ace_editor");
+  const editor = (
+    container as
+      | (HTMLElement & {
+          env?: {
+            editor?: {
+              focus(): void;
+              selectAll(): void;
+              getValue(): string;
+            };
+          };
+        })
+      | null
+  )?.env?.editor;
+  if (!editor) throw new Error("Ace editor not mounted");
+  return editor;
+}
+
+/**
+ * Focus the editor and empty it, so the next keystrokes are the whole document
+ * and the typing itself — the thing under test — is left to `userEvent`.
+ *
+ * Emptied rather than merely selected: typing an opening brace or quote with a
+ * selection makes Ace **wrap** the selection instead of replacing it, so typing
+ * `{` over a selected `{}` yields `{{}}` and the assertion stops being about
+ * auto-closing at all.
+ *
+ * Focus and select go through Ace's API on purpose. `userEvent.click` does not
+ * focus the editor — Ace's input is a 1px offscreen textarea, so the click
+ * lands nowhere and the keystrokes reach the body instead. And select-all is
+ * not `Control+A` everywhere (Ace binds `Cmd-A` on mac), so pressing it would
+ * make these stories pass or fail by host OS.
+ */
+async function focusAndClear(canvasElement: HTMLElement): Promise<void> {
+  const editor = aceEditor(canvasElement);
+  editor.focus();
+  editor.selectAll();
+  await userEvent.keyboard("{Backspace}");
+}
+
+/** Ace renders each token in its own element, so read the document, not text. */
+function editorText(canvasElement: HTMLElement): string {
+  return aceEditor(canvasElement).getValue();
+}
+
 /** A structured payload renders as formatted JSON, nesting intact. */
 export const Populated: Story = {
   args: {
@@ -39,9 +96,7 @@ export const Populated: Story = {
     },
   },
   play: async ({ canvasElement }) => {
-    const canvas = within(canvasElement);
-    const box = await canvas.findByLabelText("Request metadata JSON");
-    await expect(JSON.parse((box as HTMLTextAreaElement).value)).toEqual({
+    await expect(JSON.parse(editorText(canvasElement))).toEqual({
       tenant: "acme",
       trace: { id: "abc123", sampled: true },
       features: ["apps", "tasks"],
@@ -54,8 +109,36 @@ export const Empty: Story = {
   args: { initial: {} },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    const box = await canvas.findByLabelText("Request metadata JSON");
-    await expect(box).toHaveValue("{}");
+    await expect(editorText(canvasElement)).toBe("{}");
+    await expect(canvas.queryByText(/Not valid JSON/)).toBeNull();
+  },
+};
+
+/**
+ * Opening a brace closes it — one of the two reasons this is an editor rather
+ * than a textarea, and the thing that makes hand-writing a nested `_meta`
+ * payload bearable.
+ *
+ * Deliberately one keystroke: Ace also auto-pairs quotes and skips over a
+ * closing character you type yourself, so a longer sequence asserts the sum of
+ * several behaviours and stops being a readable statement about this one.
+ */
+export const ClosesBracesWhileTyping: Story = {
+  args: { initial: {} },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await focusAndClear(canvasElement);
+    // `{{` is userEvent's escape for a literal `{`.
+    await userEvent.keyboard("{{");
+    // Ace does not close it on the keystroke — an opening brace at the end of a
+    // line is often the start of a block the user is about to fill in.
+    await expect(editorText(canvasElement)).toBe("{");
+    // Enter is what completes the pair, leaving the cursor indented between
+    // them. This is the behaviour that makes writing nested `_meta` by hand
+    // bearable, and the reason this is an editor rather than a textarea.
+    await userEvent.keyboard("{Enter}");
+    await expect(editorText(canvasElement)).toBe("{\n  \n}");
+    // The result parses, so nothing is flagged.
     await expect(canvas.queryByText(/Not valid JSON/)).toBeNull();
   },
 };
@@ -69,22 +152,31 @@ export const InvalidDraft: Story = {
   args: { initial: {} },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    const box = await canvas.findByLabelText("Request metadata JSON");
-    await userEvent.clear(box);
-    await userEvent.type(box, '{{"a":');
-    await expect(box).toHaveValue('{"a":');
+    await focusAndClear(canvasElement);
+    // Genuinely half-typed — the state a user is in partway through writing an
+    // entry, rather than a contrived bad string.
+    await userEvent.keyboard('{{"a":');
+    // Shown exactly as typed. The old textarea re-escaped its own contents on
+    // every keystroke here, which is what made it unusable (#1928).
+    await expect(editorText(canvasElement)).toBe('{"a":');
     await expect(await canvas.findByText(/Not valid JSON/)).toBeVisible();
   },
 };
 
-/** Valid JSON that is not an object is rejected with its own message. */
+/**
+ * Valid JSON that is not an object is rejected with its own message, distinct
+ * from unparseable text.
+ *
+ * A bare number rather than an array: brackets are auto-paired too, so typing
+ * one would test the pairing as much as the rejection.
+ */
 export const NotAnObject: Story = {
   args: { initial: {} },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    const box = await canvas.findByLabelText("Request metadata JSON");
-    await userEvent.clear(box);
-    await userEvent.type(box, "[[1,2]");
+    await focusAndClear(canvasElement);
+    await userEvent.keyboard("42");
+    await expect(editorText(canvasElement)).toBe("42");
     await expect(
       await canvas.findByText(/Must be a JSON object/),
     ).toBeVisible();
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
index b1da0ffb..e805e8d4 100644
--- a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
@@ -1,9 +1,9 @@
 import { useState } from "react";
 import { describe, it, expect, vi } from "vitest";
-import { screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
+import { act, screen } from "@testing-library/react";
 import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
 import { renderWithMantine } from "../../../test/renderWithMantine";
+import { aceLabel, getAceText, setAceText } from "../../../test/aceEditor";
 import { JsonObjectInput } from "./JsonObjectInput";
 
 const LABEL = "Payload JSON";
@@ -20,7 +20,7 @@ function Harness({
   return (
     <>
       <JsonObjectInput
-        aria-label={LABEL}
+        ariaLabel={LABEL}
         value={value}
         onChange={(next) => {
           setValue(next);
@@ -32,38 +32,60 @@ function Harness({
   );
 }
 
-function box() {
-  return screen.getByLabelText(LABEL) as HTMLTextAreaElement;
-}
-
 describe("JsonObjectInput", () => {
+  it("names the editor for assistive tech", () => {
+    renderWithMantine(<Harness initial={{}} />);
+    // Ace composes "<label>, Cursor at row N", so the match is by substring —
+    // the position readout is Ace's, the name is ours.
+    expect(screen.getByLabelText(aceLabel(LABEL))).toBeInTheDocument();
+  });
+
+  it("uses Ace's dark theme under a dark color scheme", () => {
+    // The editor picks its Ace theme from the computed scheme rather than
+    // inheriting Mantine tokens, so the dark branch is only exercised by
+    // actually rendering dark.
+    renderWithMantine(<Harness initial={{}} />, { colorScheme: "dark" });
+    // `ace-github-dark`, hyphenated — Ace's cssClass, not the module name
+    // (`theme-github_dark`). The App.css gutter-contrast override keys off this
+    // same class, so getting it wrong silently drops the fix in dark mode.
+    expect(document.querySelector(".ace-github-dark")).not.toBeNull();
+    expect(document.querySelector(".ace-github")).toBeNull();
+  });
+
+  it("uses Ace's light theme under a light color scheme", () => {
+    renderWithMantine(<Harness initial={{}} />, { colorScheme: "light" });
+    expect(document.querySelector(".ace-github")).not.toBeNull();
+    expect(document.querySelector(".ace-github_dark")).toBeNull();
+  });
+
   it("opens with the value serialized two-space, nesting intact", () => {
     renderWithMantine(<Harness initial={{ a: { b: [1, 2] } }} />);
-    expect(box().value).toBe(
+    expect(getAceText()).toBe(
       '{\n  "a": {\n    "b": [\n      1,\n      2\n    ]\n  }\n}',
     );
   });
 
   it("emits the parsed object — a structured value stays structured", async () => {
-    const user = userEvent.setup();
     const onChange = vi.fn();
     renderWithMantine(<Harness initial={{}} onChange={onChange} />);
-    await user.clear(box());
-    await user.type(box(), '{{"trace":{{"id":"x"},"n":3}');
+    await setAceText('{"trace":{"id":"x"},"n":3}');
     expect(onChange).toHaveBeenLastCalledWith({ trace: { id: "x" }, n: 3 });
   });
 
+  // Also the regression test for the paired-event bug `handleChange` coalesces:
+  // `setValue` is a remove followed by an insert, and acting on the remove
+  // emitted `{}` and wiped `keep` before the insert had landed.
   it("shows the text as typed while it is invalid and does not emit", async () => {
-    const user = userEvent.setup();
     const onChange = vi.fn();
     renderWithMantine(<Harness initial={{ keep: "me" }} onChange={onChange} />);
-    // Append a stray character rather than clearing: clearing is itself a
-    // valid edit (it means `{}`) and would emit, which is not what is under
-    // test here.
-    await user.click(box());
-    await user.keyboard("{End}x");
+    await setAceText('{"a":');
+    console.log("[dbg] emitted:", screen.getByTestId("emitted").textContent);
+    console.log(
+      "[dbg] body has error?",
+      document.body.textContent?.includes("Not valid JSON"),
+    );
     // Displayed verbatim — not re-escaped back through JSON.stringify.
-    expect(box().value.endsWith("}x")).toBe(true);
+    expect(getAceText()).toBe('{"a":');
     expect(
       screen.getByText("Not valid JSON — changes are not applied"),
     ).toBeInTheDocument();
@@ -73,36 +95,30 @@ describe("JsonObjectInput", () => {
   });
 
   it("flags valid JSON that is not an object without emitting", async () => {
-    const user = userEvent.setup();
     const onChange = vi.fn();
     renderWithMantine(<Harness initial={{ keep: "me" }} onChange={onChange} />);
-    await user.clear(box());
-    // The clear is a legitimate edit to `{}`; only what follows is under test.
-    expect(onChange).toHaveBeenLastCalledWith({});
-    onChange.mockClear();
-    await user.type(box(), "[[1]");
+    await setAceText("[1]");
     expect(screen.getByText(/Must be a JSON object/)).toBeInTheDocument();
     expect(onChange).not.toHaveBeenCalled();
   });
 
-  it("treats a cleared box as the empty object", async () => {
-    const user = userEvent.setup();
+  it("treats a cleared editor as the empty object", async () => {
     const onChange = vi.fn();
     renderWithMantine(<Harness initial={{ a: 1 }} onChange={onChange} />);
-    await user.clear(box());
+    await setAceText("");
     expect(onChange).toHaveBeenLastCalledWith({});
     expect(screen.queryByText(/Not valid JSON/)).toBeNull();
   });
 
   it("re-syncs when the parent's value diverges from the draft", async () => {
     // An external reset (switching servers, a reloaded catalog) must reach the
-    // box; an in-progress edit must not be overwritten by the value it emitted.
+    // editor; an in-progress edit must not be overwritten by what it emitted.
     function Externally() {
       const [value, setValue] = useState<JsonObject>({ a: 1 });
       return (
         <>
           <JsonObjectInput
-            aria-label={LABEL}
+            ariaLabel={LABEL}
             value={value}
             onChange={setValue}
           />
@@ -110,19 +126,18 @@ describe("JsonObjectInput", () => {
         </>
       );
     }
-    const user = userEvent.setup();
     renderWithMantine(<Externally />);
-    await user.click(screen.getByRole("button", { name: "reset" }));
-    expect(JSON.parse(box().value)).toEqual({ b: 2 });
+    await act(async () => {
+      screen.getByRole("button", { name: "reset" }).click();
+    });
+    expect(JSON.parse(getAceText())).toEqual({ b: 2 });
   });
 
   it("leaves an in-progress edit alone when the parent echoes it back", async () => {
-    const user = userEvent.setup();
     renderWithMantine(<Harness initial={{}} />);
-    await user.clear(box());
-    // Typed without the closing brace auto-pair: the text is what the user has
-    // so far, and the echo of the parsed value must not reformat it mid-edit.
-    await user.type(box(), '{{"a":1}');
-    expect(box().value).toBe('{"a":1}');
+    // The parent re-renders with the object this text parsed to; the draft must
+    // not be reformatted out from under the cursor.
+    await setAceText('{"a":1}');
+    expect(getAceText()).toBe('{"a":1}');
   });
 });
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
index fbec5ee4..8368b291 100644
--- a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
@@ -1,15 +1,21 @@
-import { useState } from "react";
-import { JsonInput } from "@mantine/core";
+import { useRef, useState } from "react";
+import { Input, useComputedColorScheme } from "@mantine/core";
+import AceEditor from "react-ace";
+import ace from "ace-builds/src-noconflict/ace";
+import "ace-builds/src-noconflict/mode-json";
+import "ace-builds/src-noconflict/theme-github";
+import "ace-builds/src-noconflict/theme-github_dark";
+// `?url` so Vite emits the worker as its own asset and hands back a real URL.
+// Without it Ace fetches `worker-json.js` from a path that does not exist in a
+// bundled app, silently loses its annotations, and logs a fetch error.
+import jsonWorkerUrl from "ace-builds/src-noconflict/worker-json.js?url";
 import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
 import { useValueChange } from "../../../hooks/useValueChange";
 import { parseJsonObjectDraft } from "../../../utils/jsonObjectDraft";
 
-const ObjectJsonInput = JsonInput.withProps({
-  formatOnBlur: true,
-  autosize: true,
-  minRows: 4,
-  spellCheck: false,
-});
+// Module scope: registering the worker URL is global to Ace and idempotent, so
+// it must not be repeated per mount.
+ace.config.setModuleUrl("ace/mode/json_worker", jsonWorkerUrl);
 
 /** Two-space canonical form — the same shape the catalog file is written in. */
 function serialize(value: JsonObject): string {
@@ -21,9 +27,16 @@ export interface JsonObjectInputProps {
   onChange: (value: JsonObject) => void;
   label?: string;
   description?: string;
-  placeholder?: string;
-  "aria-label"?: string;
-  "data-testid"?: string;
+  /**
+   * Accessible name for the editor's text input. Ace labels its hidden
+   * textarea "Cursor at row N" by default, which is a position readout rather
+   * than a name — so this is what makes the control identifiable to a screen
+   * reader, and what `getByLabelText` finds in a test.
+   */
+  ariaLabel: string;
+  /** Rows shown before the editor grows; it autosizes between these bounds. */
+  minLines?: number;
+  maxLines?: number;
 }
 
 /**
@@ -36,6 +49,11 @@ export interface JsonObjectInputProps {
  * `_meta` value to a string, so a `{ key, value }` row editor cannot express
  * what the protocol allows.
  *
+ * Built on Ace rather than a plain textarea because hand-writing JSON in a bare
+ * box is the actual pain: Ace closes a brace when you open one, folds nested
+ * objects, and — via its JSON worker — marks the offending line in the gutter
+ * instead of reporting one message for the whole document.
+ *
  * The text the user is typing is the source of truth for what is *displayed*;
  * the parent only ever sees a parsed object. That split is what makes the box
  * typeable: driving it off the parent's value and stringifying on every render
@@ -47,35 +65,132 @@ export interface JsonObjectInputProps {
  * object stands. The alternative — emitting `{}` — would silently discard a
  * user's configured metadata the moment they typed a stray character, and this
  * form has no Save button to gate instead: `onChange` writes straight through.
- * The state is not silent, though; the field says so on itself via `error`.
+ * The state is not silent, though: Ace flags the position in the gutter, and
+ * the wrapper repeats the reason underneath.
  */
 export function JsonObjectInput({
   value,
   onChange,
-  ...inputProps
+  label,
+  description,
+  ariaLabel,
+  minLines = 6,
+  maxLines = 24,
 }: JsonObjectInputProps) {
   const [draft, setDraft] = useState(() => serialize(value));
+  // The canonical JSON of the last value this component emitted.
+  //
+  // The re-sync below has to tell an *external* change apart from the parent
+  // echoing back what we just sent it, and the draft alone cannot: while the
+  // text is invalid it parses to nothing, so every parent change would look
+  // external and overwrite what is being typed.
+  //
+  // That is not hypothetical. Ace's `setValue` — which is what a select-all
+  // paste and any programmatic replace go through — fires *two* change events,
+  // a remove then an insert. The remove leaves an empty document, which is a
+  // valid `{}` and gets emitted; the insert then leaves invalid text. Comparing
+  // against the draft, the `{}` echo reads as an external reset and wipes the
+  // pasted text a keystroke after it lands.
+  const [echoed, setEchoed] = useState(() => serialize(value));
+  // `getInitialValueInEffect: false` so the first render already has the real
+  // scheme; otherwise the editor mounts light and repaints, which is visible.
+  const colorScheme = useComputedColorScheme("light", {
+    getInitialValueInEffect: false,
+  });
+
+  // Re-sync only on a value this component did not produce, so an external
+  // reset (switching servers, a reloaded catalog) reaches the editor while an
+  // in-progress edit is left alone. Compared through canonical JSON because the
+  // parent hands back a fresh object each time.
+  // Text from the most recent change event in the current tick, and whether a
+  // flush is already queued to consume it. Two refs rather than one nullable
+  // one so the flush reads a plain `string` — folding them together would add
+  // a null check that nothing can ever satisfy. See `handleChange`.
+  const pendingTextRef = useRef("");
+  const flushScheduledRef = useRef(false);
+
+  /**
+   * Coalesce the change events Ace fires within one edit, and act on the last.
+   *
+   * A replace — select-all-and-retype, or a paste over a selection — is a
+   * *remove* followed by an *insert*, and Ace fires a change event for each.
+   * Acting on the first would read the momentarily-empty document as the user
+   * clearing the field, emit `{}` to the parent, and so wipe their saved
+   * metadata the instant they selected it. If the replacement text then failed
+   * to parse, `{}` is what they would be left with.
+   *
+   * A microtask is enough because both events are dispatched synchronously
+   * inside the same edit, so the flush sees only the settled text.
+   */
+  const handleChange = (text: string) => {
+    pendingTextRef.current = text;
+    if (flushScheduledRef.current) return;
+    flushScheduledRef.current = true;
+    queueMicrotask(() => {
+      flushScheduledRef.current = false;
+      const settled = pendingTextRef.current;
+      setDraft(settled);
+      const result = parseJsonObjectDraft(settled);
+      if (!result.ok) return;
+      setEchoed(serialize(result.value));
+      onChange(result.value);
+    });
+  };
 
-  // Re-sync only when the parent's value genuinely diverges from what the draft
-  // parses to, so an external reset (switching servers, a reloaded catalog)
-  // reaches the box while an in-progress edit is left alone. Compared through
-  // canonical JSON because the parent hands back a fresh object each time.
   const parsed = parseJsonObjectDraft(draft);
-  const draftJson = parsed.ok ? serialize(parsed.value) : null;
   useValueChange(serialize(value), (next) => {
-    if (next !== draftJson) setDraft(next);
+    if (next !== echoed) setDraft(next);
   });
 
   return (
-    <ObjectJsonInput
-      {...inputProps}
-      value={draft}
+    <Input.Wrapper
+      label={label}
+      description={description}
       error={parsed.ok ? undefined : parsed.error}
-      onChange={(text) => {
-        setDraft(text);
-        const result = parseJsonObjectDraft(text);
-        if (result.ok) onChange(result.value);
-      }}
-    />
+      w="100%"
+    >
+      <AceEditor
+        mode="json"
+        theme={colorScheme === "dark" ? "github_dark" : "github"}
+        name="json-object-input"
+        value={draft}
+        onChange={handleChange}
+        width="100%"
+        minLines={minLines}
+        maxLines={maxLines}
+        tabSize={2}
+        showPrintMargin={false}
+        editorProps={{ $blockScrolling: Infinity }}
+        onLoad={(editor) => {
+          // `textInputAriaLabel` alone is not enough: Ace composes the hidden
+          // textarea's label as "<label>, Cursor at row N" inside
+          // `TextInput.setAriaLabel`, and only recomputes it when the cursor
+          // moves — so an option applied at mount does not reach the DOM until
+          // the user clicks into the editor. Until then the control's only
+          // accessible name is the position readout, which names nothing.
+          // Setting it here and recomputing once is what makes the editor
+          // identifiable from first paint.
+          editor.setOption("textInputAriaLabel", ariaLabel);
+          editor.textInput.setAriaLabel();
+        }}
+        setOptions={{
+          // The JSON worker is what puts a marker on the offending line rather
+          // than one message for the whole document.
+          useWorker: true,
+          // Closes a brace/bracket/quote when you open one, and skips over the
+          // closing one you then type. On by default; named because it is half
+          // of why this component exists.
+          behavioursEnabled: true,
+          // Roving-tabindex arrow-key navigation plus an Esc-to-exit-trap, so
+          // the editor does not swallow Tab for keyboard users.
+          enableKeyboardAccessibility: true,
+          textInputAriaLabel: ariaLabel,
+          showFoldWidgets: true,
+          displayIndentGuides: true,
+          useSoftTabs: true,
+          scrollPastEnd: false,
+        }}
+      />
+    </Input.Wrapper>
   );
 }
diff --git a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.test.tsx b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.test.tsx
index cd5e168a..9cc428ad 100644
--- a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.test.tsx
+++ b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.test.tsx
@@ -3,6 +3,7 @@ import userEvent from "@testing-library/user-event";
 import { within } from "@testing-library/react";
 import type { InspectorServerSettings } from "@inspector/core/mcp/types.js";
 import { renderWithMantine, screen } from "../../../test/renderWithMantine";
+import { getAceText, setAceText } from "../../../test/aceEditor";
 import {
   ServerSettingsForm,
   type ServerSettingsSection,
@@ -249,8 +250,8 @@ describe("ServerSettingsForm", () => {
       screen.getByText("No custom headers configured"),
     ).toBeInTheDocument();
     // Metadata has no rows to be absent — the editor is always present, and
-    // "none configured" is spelled `{}` in the box itself.
-    expect(screen.getByLabelText("Request metadata JSON")).toHaveValue("{}");
+    // "none configured" is spelled `{}` in it.
+    expect(getAceText()).toBe("{}");
   });
 
   it("invokes onAddHeader when + Add Header is clicked", async () => {
@@ -331,17 +332,15 @@ describe("ServerSettingsForm", () => {
         expandedSections={["metadata"]}
       />,
     );
-    const editor = screen.getByLabelText("Request metadata JSON");
     // The point of #1910: a nested object survives into the editor instead of
     // being flattened into a `{ key, value }` string row.
-    expect(JSON.parse((editor as HTMLTextAreaElement).value)).toEqual({
+    expect(JSON.parse(getAceText())).toEqual({
       userId: "u-1",
       tenant: { id: 7, tags: ["a"] },
     });
   });
 
   it("reports the whole edited object through onMetadataChange", async () => {
-    const user = userEvent.setup();
     const onMetadataChange = vi.fn();
     renderWithMantine(
       <ServerSettingsForm
@@ -351,9 +350,7 @@ describe("ServerSettingsForm", () => {
         expandedSections={["metadata"]}
       />,
     );
-    const editor = screen.getByLabelText("Request metadata JSON");
-    await user.clear(editor);
-    await user.type(editor, '{{"n":[[1,2]}');
+    await setAceText('{"n":[1,2]}');
     expect(onMetadataChange).toHaveBeenLastCalledWith({ n: [1, 2] });
   });
 
diff --git a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
index 0a61a8db..4abb41e7 100644
--- a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
+++ b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
@@ -735,8 +735,7 @@ export function ServerSettingsForm({
               strings. Leave it as <Code>{"{}"}</Code> to send none.
             </HintText>
             <JsonObjectInput
-              aria-label="Request metadata JSON"
-              placeholder={'{\n  "example": { "nested": true }\n}'}
+              ariaLabel="Request metadata JSON"
               value={settings.metadata}
               onChange={onMetadataChange}
             />
diff --git a/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.test.tsx b/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.test.tsx
index c42fba16..9e00e644 100644
--- a/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.test.tsx
+++ b/clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.test.tsx
@@ -2,6 +2,7 @@ import { describe, it, expect, vi } from "vitest";
 import userEvent from "@testing-library/user-event";
 import type { InspectorServerSettings } from "@inspector/core/mcp/types.js";
 import { renderWithMantine, screen } from "../../../test/renderWithMantine";
+import { setAceText } from "../../../test/aceEditor";
 import { ServerSettingsModal } from "./ServerSettingsModal";
 
 const initialSettings: InspectorServerSettings = {
@@ -647,9 +648,7 @@ describe("ServerSettingsModal", () => {
       />,
     );
     await user.click(screen.getByRole("button", { name: "Request Metadata" }));
-    const editor = screen.getByLabelText("Request metadata JSON");
-    await user.clear(editor);
-    await user.type(editor, '{{"trace":{{"id":"abc"}}}');
+    await setAceText('{"trace":{"id":"abc"}}');
     const lastCall = onSettingsChange.mock.calls.at(-1)?.[0];
     // The nested object arrives as an object, not a stringified one — the
     // whole point of #1910.
diff --git a/clients/web/src/test/aceEditor.ts b/clients/web/src/test/aceEditor.ts
new file mode 100644
index 00000000..1243926c
--- /dev/null
+++ b/clients/web/src/test/aceEditor.ts
@@ -0,0 +1,58 @@
+import { act } from "@testing-library/react";
+import type { Ace } from "ace-builds";
+
+/**
+ * Reach the live Ace editor a component mounted, and drive it.
+ *
+ * Typing is deliberately **not** simulated. Ace reads keystrokes through a 1px
+ * offscreen textarea plus selection and composition state that happy-dom does
+ * not implement, so `userEvent.type` reaches the element and produces no edit
+ * at all — a test written that way asserts nothing while looking like it
+ * asserts a lot. Real keyboard behaviour (auto-closing a brace on Enter, and
+ * the draft surviving invalid text) is covered by the `JsonObjectInput`
+ * Storybook play functions, which run in Chromium.
+ *
+ * Ace hangs the instance off its container element as `env.editor`; that is the
+ * supported way back to it from the DOM.
+ */
+export function getAceEditor(container: ParentNode = document): Ace.Editor {
+  const node = container.querySelector(".ace_editor");
+  const editor = (
+    node as (HTMLElement & { env?: { editor?: Ace.Editor } }) | null
+  )?.env?.editor;
+  if (!editor) throw new Error("Ace editor not mounted");
+  return editor;
+}
+
+/** The document the editor currently holds. */
+export function getAceText(container?: ParentNode): string {
+  return getAceEditor(container).getValue();
+}
+
+/**
+ * Replace the document the way a select-all-and-retype would, and let React
+ * flush.
+ *
+ * Async because `JsonObjectInput` coalesces the paired remove/insert events
+ * Ace fires for a replace; an `await act` is what drains that microtask.
+ */
+export async function setAceText(
+  text: string,
+  container?: ParentNode,
+): Promise<void> {
+  await act(async () => {
+    // `1` parks the cursor at the end, matching where typing would leave it.
+    getAceEditor(container).setValue(text, 1);
+  });
+}
+
+/**
+ * Matcher for an Ace-labelled control.
+ *
+ * Ace composes its text input's `aria-label` as `"<label>, Cursor at row N"`,
+ * so an exact-string `getByLabelText` never matches — the position readout is
+ * Ace's, only the prefix is ours.
+ */
+export function aceLabel(label: string): RegExp {
+  return new RegExp(label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+}

From 63f81151f5f9f705511ed32a07be2eb6ec7d59cf Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 16:55:17 -0400
Subject: [PATCH 16/35] test(web): stop the AppRenderer theme-flip test racing
 its MutationObserver
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Unrelated to this PR's subject, and pre-existing — it arrived with #1854. The
test set `data-mantine-color-scheme` and asserted the bridge push after a
single `await Promise.resolve()`, but how many ticks happy-dom takes to deliver
a MutationObserver callback is load-dependent. Observed failing once in a full
`npm run ci`, with 0 calls; passes standalone and on re-runs.

Adding a dependency the size of `ace-builds` shifts worker timing enough to
expose it, so fixing it here rather than leaving a known-intermittent failure
in the gate for whoever hits it next. `waitFor` retries the same assertion.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../elements/AppRenderer/AppRenderer.test.tsx | 22 ++++++++++++-------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/clients/web/src/components/elements/AppRenderer/AppRenderer.test.tsx b/clients/web/src/components/elements/AppRenderer/AppRenderer.test.tsx
index a9a167cc..2cf355be 100644
--- a/clients/web/src/components/elements/AppRenderer/AppRenderer.test.tsx
+++ b/clients/web/src/components/elements/AppRenderer/AppRenderer.test.tsx
@@ -1,5 +1,5 @@
 import { createRef, StrictMode } from "react";
-import { act } from "@testing-library/react";
+import { act, waitFor } from "@testing-library/react";
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import type { AppBridge } from "@modelcontextprotocol/ext-apps/app-bridge";
 import type { CallToolResult, Tool } from "@modelcontextprotocol/client";
@@ -546,15 +546,21 @@ describe("AppRenderer", () => {
         // MutationObserver callbacks are delivered on a microtask.
         await Promise.resolve();
       });
-      expect(bridge.sendHostContextChange).toHaveBeenCalledWith(
-        expect.objectContaining({
-          theme: "dark",
-          styles: expect.objectContaining({
-            variables: expect.objectContaining({
-              "--color-background-primary": "#101113",
+      // `waitFor`, not a bare assertion after the single microtask above: how
+      // many ticks happy-dom takes to deliver the MutationObserver callback is
+      // load-dependent, so under a full parallel run the observer can still be
+      // pending here. Observed failing exactly once that way, with 0 calls.
+      await waitFor(() =>
+        expect(bridge.sendHostContextChange).toHaveBeenCalledWith(
+          expect.objectContaining({
+            theme: "dark",
+            styles: expect.objectContaining({
+              variables: expect.objectContaining({
+                "--color-background-primary": "#101113",
+              }),
             }),
           }),
-        }),
+        ),
       );
     } finally {
       getComputedStyleSpy.mockRestore();

From 75f9c511469880043686740453b7ae7a074981b8 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 16:56:53 -0400
Subject: [PATCH 17/35] fix(web): update a fixture the merge brought in to the
 object metadata shape
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`useLastPersistedSettings.test.tsx` arrived on `v2/main` with
`metadata: []` — correct when it was written, but this branch changes
`InspectorServerSettings.metadata` to a JSON object (#1910). Caught by
`tsc -b`, not by the tests, which pass either way.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/hooks/useLastPersistedSettings.test.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clients/web/src/hooks/useLastPersistedSettings.test.tsx b/clients/web/src/hooks/useLastPersistedSettings.test.tsx
index 4141fe22..5c222b03 100644
--- a/clients/web/src/hooks/useLastPersistedSettings.test.tsx
+++ b/clients/web/src/hooks/useLastPersistedSettings.test.tsx
@@ -14,7 +14,7 @@ const settings = (
 ): InspectorServerSettings => ({
   headers: [],
   env: [],
-  metadata: [],
+  metadata: {},
   connectionTimeout: 0,
   requestTimeout: 0,
   taskTtl: 0,

From 7f10fa971c85d6f56ffcc1f75fbdc5bb428d49a2 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 17:36:43 -0400
Subject: [PATCH 18/35] fix: address the Copilot review of the Ace editor
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- `isProgressToken` used `Number.isInteger`, but zod 4's `.int()` rejects
  anything past `MAX_SAFE_INTEGER` — verified against the pinned zod — so an
  unsafe integer passed the guard and was left for the server to reject. Now
  `isSafeInteger`, with the boundary covered in both directions.

- `echoed` held only what this component last emitted, so it went stale the
  moment an external value was applied: A → B → A stranded the editor on B,
  because the second A matched the entry left from before B arrived and was
  dismissed as our own echo. It now advances to whatever is on screen.

- `Input.Wrapper` associates a *Mantine* input through context, and Ace is not
  one — it renders its own DOM. The wrapper's label and error node therefore
  pointed at nothing: the editor was never marked `aria-invalid`, never
  described by the error text, and its visible label did not focus it. Wired
  explicitly through the wrapper's id in an effect.

- Removed two leftover `[dbg]` logs an earlier regex cleanup missed.

- Documented the editor integration and the shared `cssVariablesResolver` in
  the web README, per the rule about new dependencies and patterns. Both
  footguns are recorded: the `?url` worker import, and the gutter override
  keying off Ace's cssClass rather than the theme module name.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/README.md                         | 100 ++++++++++--------
 .../JsonObjectInput/JsonObjectInput.test.tsx  |  75 ++++++++++++-
 .../JsonObjectInput/JsonObjectInput.tsx       |  40 ++++++-
 .../integration/mcp/inspectorClient.test.ts   |   6 ++
 core/mcp/inspectorClient.ts                   |   8 +-
 5 files changed, 178 insertions(+), 51 deletions(-)

diff --git a/clients/web/README.md b/clients/web/README.md
index 19f77385..db71915c 100644
--- a/clients/web/README.md
+++ b/clients/web/README.md
@@ -6,10 +6,10 @@ This README covers what's specific to the web client. For the repo-wide picture
 
 ## Two halves: `src/` (browser) and `server/` (Node)
 
-| Path | Runs in | Purpose |
-| --- | --- | --- |
-| `src/` | browser | The React SPA — components, hooks, theme, entry (`main.tsx`). |
-| `server/` | Node | The dev/prod backend wiring (never imported by the browser). |
+| Path      | Runs in | Purpose                                                       |
+| --------- | ------- | ------------------------------------------------------------- |
+| `src/`    | browser | The React SPA — components, hooks, theme, entry (`main.tsx`). |
+| `server/` | Node    | The dev/prod backend wiring (never imported by the browser).  |
 
 The `server/` directory holds the Node-only backend:
 
@@ -47,12 +47,12 @@ Two artifacts come out, both of which ship in the published package:
 
 Components live under `src/components/` in four layers, smallest to largest:
 
-| Layer | Count | What it is |
-| --- | --- | --- |
-| `elements/` | ~31 | Leaf presentational pieces (badges, buttons, toggles) over Mantine primitives. |
-| `groups/` | ~63 | Composite pieces (cards, panels, modals, control bars). |
-| `screens/` | ~11 | Full tab screens (Tools, Resources, Servers, monitoring screens…). |
-| `views/` | 1 | `InspectorView` — the top-level layout that composes the screens. |
+| Layer       | Count | What it is                                                                     |
+| ----------- | ----- | ------------------------------------------------------------------------------ |
+| `elements/` | ~31   | Leaf presentational pieces (badges, buttons, toggles) over Mantine primitives. |
+| `groups/`   | ~63   | Composite pieces (cards, panels, modals, control bars).                        |
+| `screens/`  | ~11   | Full tab screens (Tools, Resources, Servers, monitoring screens…).             |
+| `views/`    | 1     | `InspectorView` — the top-level layout that composes the screens.              |
 
 Every screen and element has a `*.stories.tsx` (see [Storybook](#storybook)). Styling follows the Mantine-first rules in [`AGENTS.md`](../../AGENTS.md) — theme variants and component props over CSS, `--inspector-*` tokens over raw colors.
 
@@ -74,23 +74,23 @@ Nothing _enforces_ the boundary — no path alias keys off it, and the coverage
 
 The Apps screen exposes a small, stable set of `data-testid` / `data-*` attributes so an automated driver (deep-link auto-open, CI review harness) can `waitForSelector` on a deterministic signal instead of sleeping. Treat these as a public contract — drivers depend on them staying stable:
 
-| Attribute | Where | Meaning |
-| --- | --- | --- |
-| `data-testid="apps-form"` | Apps content card | The container that carries the status/error attributes below. |
-| `data-app-status` | on `apps-form` | Renderer lifecycle: `idle` (nothing running) → `loading` (bridge building / `ui/initialize` in flight) → `ready` (view fired `notifications/initialized`) → `error` (bridge factory threw/rejected). Poll for `ready`. |
-| `data-app-error` | on `apps-form` | The failure reason string when `data-app-status="error"` (e.g. no connected client); absent otherwise. |
-| `data-testid="apps-error"` | error panel | Rendered below the frame when the app fails to load (factory throw/reject); shows the reason so the failure isn't a silent blank frame. |
-| `data-testid="open-app"` | Open App button | Launches the selected app. |
-| `data-testid="apps-stage"` | Stage-partial button | Snapshots the current form values for progressive-render testing. |
-| `data-testid="apps-messages"` | messages panel | `ui/message` submissions from the running view. |
-| `data-testid="apps-logs"` | app-logs panel | `notifications/message` log entries (default-expanded). |
+| Attribute                     | Where                | Meaning                                                                                                                                                                                                                |
+| ----------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-testid="apps-form"`     | Apps content card    | The container that carries the status/error attributes below.                                                                                                                                                          |
+| `data-app-status`             | on `apps-form`       | Renderer lifecycle: `idle` (nothing running) → `loading` (bridge building / `ui/initialize` in flight) → `ready` (view fired `notifications/initialized`) → `error` (bridge factory threw/rejected). Poll for `ready`. |
+| `data-app-error`              | on `apps-form`       | The failure reason string when `data-app-status="error"` (e.g. no connected client); absent otherwise.                                                                                                                 |
+| `data-testid="apps-error"`    | error panel          | Rendered below the frame when the app fails to load (factory throw/reject); shows the reason so the failure isn't a silent blank frame.                                                                                |
+| `data-testid="open-app"`      | Open App button      | Launches the selected app.                                                                                                                                                                                             |
+| `data-testid="apps-stage"`    | Stage-partial button | Snapshots the current form values for progressive-render testing.                                                                                                                                                      |
+| `data-testid="apps-messages"` | messages panel       | `ui/message` submissions from the running view.                                                                                                                                                                        |
+| `data-testid="apps-logs"`     | app-logs panel       | `notifications/message` log entries (default-expanded).                                                                                                                                                                |
 
 App-rendered **elicitations** (#1854) render through the same `AppRenderer` but outside the Apps screen — one modal per request, from `AppElicitationHost` — and carry their own pair:
 
-| Attribute | Where | Meaning |
-| --- | --- | --- |
+| Attribute                       | Where                 | Meaning                                                                                                                                                                                          |
+| ------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `data-testid="app-elicitation"` | the elicitation modal | One per in-flight app-rendered elicitation. **Absent** means the request was answered by the native elicitation form instead, which is what a driver asserts to prove the negotiation gate held. |
-| `data-app-elicitation-status` | on `app-elicitation` | The same `AppRendererStatus` for that modal's app. `ready` is when the host forwards the `elicitation/create` through its bridge. |
+| `data-app-elicitation-status`   | on `app-elicitation`  | The same `AppRendererStatus` for that modal's app. `ready` is when the host forwards the `elicitation/create` through its bridge.                                                                |
 
 `scripts/smoke-web-elicitation.mjs` drives both halves against the public fixture (`test-servers/configs/app-elicitation-http.json` and its `-native-` sibling).
 
@@ -104,20 +104,20 @@ A driver (launcher, CLI `--print-handoff`, CI review harness) can reach a **conn
 http://127.0.0.1:6274/?serverUrl=<url>&transport=http|sse&autoConnect=<token>
 ```
 
-| Param | Meaning |
-| --- | --- |
-| `serverUrl` | The MCP server URL. Restricted to `http:` / `https:` (a crafted `javascript:` / `data:` / `file:` value is rejected). Canonicalized via `URL.href` so it matches the OAuth store's key form. |
-| `transport` | `http` (streamable-HTTP, the default) or `sse`. Unknown values fall back to `http`. |
+| Param         | Meaning                                                                                                                                                                                                                                                                                                                      |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `serverUrl`   | The MCP server URL. Restricted to `http:` / `https:` (a crafted `javascript:` / `data:` / `file:` value is rejected). Canonicalized via `URL.href` so it matches the OAuth store's key form.                                                                                                                                 |
+| `transport`   | `http` (streamable-HTTP, the default) or `sse`. Unknown values fall back to `http`.                                                                                                                                                                                                                                          |
 | `autoConnect` | **CSRF gate.** Must equal the per-launch `MCP_INSPECTOR_API_TOKEN`. The token is random per launch and only known to whatever started the server, so a third-party-minted link cannot satisfy it — this is the same exposure surface as the existing `?MCP_INSPECTOR_API_TOKEN=` param. Without a match the link is ignored. |
 
 The deep link upserts a stable `deep-link` catalog row (so a reload reconnects to the same row instead of accumulating duplicates) and connects. Connection-level outcomes are surfaced on the `AppShell.Header` as a machine-readable contract, so a driver can `waitForSelector` and read the failure reason without scraping a transient toast:
 
-| Attribute | Where | Meaning |
-| --- | --- | --- |
-| `data-testid="connection-status"` | header | The element carrying the attributes below. |
-| `data-status` | on `connection-status` | The live `ConnectionStatus` (`disconnected` → `connecting` → `connected` / `error`). Poll for `connected`. |
-| `data-error-message` | on `connection-status` | Why the last connect failed (handshake error, OAuth-start failure, deep-link automation failure); absent when there is no error. |
-| `data-deeplink` | on `connection-status` | `parsed` (a valid deep link drove this load), `rejected` (deep-link params present but the token/serverUrl gate failed), or `none`. Lets a driver distinguish "no deep link" from "rejected" — both otherwise leave `data-status` idle. |
+| Attribute                         | Where                  | Meaning                                                                                                                                                                                                                                 |
+| --------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-testid="connection-status"` | header                 | The element carrying the attributes below.                                                                                                                                                                                              |
+| `data-status`                     | on `connection-status` | The live `ConnectionStatus` (`disconnected` → `connecting` → `connected` / `error`). Poll for `connected`.                                                                                                                              |
+| `data-error-message`              | on `connection-status` | Why the last connect failed (handshake error, OAuth-start failure, deep-link automation failure); absent when there is no error.                                                                                                        |
+| `data-deeplink`                   | on `connection-status` | `parsed` (a valid deep link drove this load), `rejected` (deep-link params present but the token/serverUrl gate failed), or `none`. Lets a driver distinguish "no deep link" from "rejected" — both otherwise leave `data-status` idle. |
 
 ### Landing on a rendered app
 
@@ -127,11 +127,11 @@ Three further params extend the deep link to pre-select — and optionally auto-
 …&openApp=<toolName>&appArgs=<base64url(JSON)>&autoOpen=<token>
 ```
 
-| Param | Meaning |
-| --- | --- |
-| `openApp` | The app-tool name. Once the connection is up and the tool appears in the app list, the inspector switches to the Apps tab and pre-selects it. |
-| `appArgs` | `base64url(JSON)` object of form values. Merged **over** the tool's schema defaults (`collectSchemaDefaults`) so a required-with-default field isn't left blank — which would otherwise disable "Open App". Malformed / non-object values fall back to `{}`. |
-| `autoOpen` | **Same CSRF gate as `autoConnect`** — must equal the session token. When set, "Open App" fires automatically (a tool call from a URL), so the token gate is mandatory. Without a match the app is pre-selected but not opened. |
+| Param      | Meaning                                                                                                                                                                                                                                                      |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `openApp`  | The app-tool name. Once the connection is up and the tool appears in the app list, the inspector switches to the Apps tab and pre-selects it.                                                                                                                |
+| `appArgs`  | `base64url(JSON)` object of form values. Merged **over** the tool's schema defaults (`collectSchemaDefaults`) so a required-with-default field isn't left blank — which would otherwise disable "Open App". Malformed / non-object values fall back to `{}`. |
+| `autoOpen` | **Same CSRF gate as `autoConnect`** — must equal the session token. When set, "Open App" fires automatically (a tool call from a URL), so the token gate is mandatory. Without a match the app is pre-selected but not opened.                               |
 
 The app-side render lifecycle is observable through the [MCP Apps screen automation contract](#mcp-apps-screen-automation-contract) above (`data-app-status="ready"`), so a driver can `waitForSelector` the whole `connect → open → ready` chain deterministically.
 
@@ -139,15 +139,29 @@ The app-side render lifecycle is observable through the [MCP Apps screen automat
 
 Each customized Mantine component has a `Theme<Name>.ts` file (`Button.ts`, `Text.ts`, …, ~21 total) exporting a `Theme<Name>` constant; the barrel `index.ts` re-exports them and `theme.ts` assembles the `MantineProvider` theme. Theme files hold app-wide defaults and **variants** (flat CSS-in-JS); only pseudo-selectors, nested child selectors, keyframes, and native-HTML styling belong in `App.css`. Element components import from `@mantine/core` (never from `theme/`) — the theme layer is applied transparently by the provider.
 
+**`cssVariables.ts` is the third piece, beside the component files and `App.css`.** It holds overrides for the CSS variables `MantineProvider` injects at runtime, which `App.css` cannot reach: the provider appends its generated `<style>` after the stylesheet imports, so a `:root` rule there loses on source order at equal specificity. `cssVariablesResolver` is the supported seam. It is passed at **all three** `MantineProvider` sites — the app (`main.tsx`), the Storybook preview, and `renderWithMantine` — so the running app, the stories, and the tests cannot disagree about a token's value. It currently corrects `--mantine-color-error`, whose Mantine defaults fail WCAG AA in both schemes at the size input error text renders.
+
+## Code editing (`JsonObjectInput`)
+
+Payloads whose _values_ may be arbitrary JSON — `_meta` is the case that forced it ([#1910](https://github.com/modelcontextprotocol/inspector/issues/1910)) — are edited with **Ace** (`react-ace` + `ace-builds`, declared in this client because they render React) rather than the key/value rows used for headers and env, which cannot express an object value. Ace brings code folding, brace auto-closing, and per-line error annotation from its JSON worker.
+
+Three integration details are load-bearing:
+
+- **The worker is imported as `?url`** so Vite emits it as an asset. Without it Ace fetches `worker-json.js` from a path that does not exist in a bundled app and silently loses its annotations.
+- **The gutter's colors are overridden in `App.css`**, keyed off Ace's cssClass (`ace-github` / `ace-github-dark` — _not_ the `theme-github_dark` module name). Ace's own themes are 1.89:1 and 4.13:1 there, both under AA, and folding needs the gutter so it cannot simply be hidden.
+- **The label and error are wired to Ace's hidden textarea by hand.** `Input.Wrapper` associates a _Mantine_ input through context; Ace renders its own DOM, so the id, `aria-invalid` and `aria-describedby` are set on the textarea in an effect.
+
+**Testing it is split by necessity.** Ace's input path does not work under happy-dom — `userEvent.type` reaches the textarea and produces no edit — so a keyboard test in the unit project passes while asserting nothing. Unit tests drive the editor instance through `src/test/aceEditor.ts`; real keyboard behaviour lives in the Storybook play functions, which run in Chromium.
+
 ## Testing
 
 Tests run under three Vitest **projects** (configured in `vite.config.ts`), each in the right environment:
 
-| Project | Env | Scope | Script |
-| --- | --- | --- | --- |
-| `unit` | happy-dom | Components, hooks, utils (`*.test.tsx` beside the source) | `npm test` |
-| `integration` | node | `@inspector/core` + transports + auth, spawning the real stdio test server (`src/test/integration/**`) | `npm run test:integration` |
-| `storybook` | real Chromium | Story **play functions** as interaction tests | `npm run test:storybook` |
+| Project       | Env           | Scope                                                                                                  | Script                     |
+| ------------- | ------------- | ------------------------------------------------------------------------------------------------------ | -------------------------- |
+| `unit`        | happy-dom     | Components, hooks, utils (`*.test.tsx` beside the source)                                              | `npm test`                 |
+| `integration` | node          | `@inspector/core` + transports + auth, spawning the real stdio test server (`src/test/integration/**`) | `npm run test:integration` |
+| `storybook`   | real Chromium | Story **play functions** as interaction tests                                                          | `npm run test:storybook`   |
 
 - `npm test` runs the fast **unit** project (happy-dom). `test:watch` for the loop.
 - **Integration** tests run in a real Node env (no happy-dom, 30s timeouts) and spawn `test-servers/build/test-server-stdio.js` as a subprocess, so `pretest`/the coverage script build the test servers first (`test-servers:build`).
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
index e805e8d4..2d72e026 100644
--- a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
@@ -79,11 +79,6 @@ describe("JsonObjectInput", () => {
     const onChange = vi.fn();
     renderWithMantine(<Harness initial={{ keep: "me" }} onChange={onChange} />);
     await setAceText('{"a":');
-    console.log("[dbg] emitted:", screen.getByTestId("emitted").textContent);
-    console.log(
-      "[dbg] body has error?",
-      document.body.textContent?.includes("Not valid JSON"),
-    );
     // Displayed verbatim — not re-escaped back through JSON.stringify.
     expect(getAceText()).toBe('{"a":');
     expect(
@@ -133,6 +128,76 @@ describe("JsonObjectInput", () => {
     expect(JSON.parse(getAceText())).toEqual({ b: 2 });
   });
 
+  it("applies an external value it showed before (A → B → A)", async () => {
+    // Regression: `echoed` used to hold only what this component last emitted,
+    // so returning to a previously-shown value matched the stale entry and was
+    // dismissed as our own echo, stranding the editor on B.
+    function Externally({ value }: { value: JsonObject }) {
+      return (
+        <JsonObjectInput ariaLabel={LABEL} value={value} onChange={() => {}} />
+      );
+    }
+    const { rerender } = renderWithMantine(<Externally value={{ a: 1 }} />);
+    expect(JSON.parse(getAceText())).toEqual({ a: 1 });
+
+    rerender(<Externally value={{ b: 2 }} />);
+    expect(JSON.parse(getAceText())).toEqual({ b: 2 });
+
+    // Back to the first value — a distinct object, same content.
+    rerender(<Externally value={{ a: 1 }} />);
+    expect(JSON.parse(getAceText())).toEqual({ a: 1 });
+  });
+
+  describe("wiring to the Input.Wrapper label and error", () => {
+    /** Ace's hidden textarea — the element the wrapper has to point at. */
+    function textarea(): HTMLTextAreaElement {
+      const el = document.querySelector<HTMLTextAreaElement>(
+        "textarea.ace_text-input",
+      );
+      if (!el) throw new Error("Ace text input not mounted");
+      return el;
+    }
+
+    it("lets the visible label focus the editor", () => {
+      renderWithMantine(
+        <JsonObjectInput
+          label="Request metadata"
+          ariaLabel={LABEL}
+          value={{}}
+          onChange={() => {}}
+        />,
+      );
+      // `Input.Wrapper` renders `<label for={id}>`; the editor is only
+      // reachable from it if Ace's textarea carries that same id.
+      const label = screen.getByText("Request metadata");
+      expect(label.getAttribute("for")).toBe(textarea().id);
+      expect(textarea().id).not.toBe("");
+    });
+
+    it("marks the editor invalid and points it at the error text", async () => {
+      renderWithMantine(<Harness initial={{}} />);
+      expect(textarea().getAttribute("aria-invalid")).toBeNull();
+
+      await setAceText("[1]");
+      expect(textarea().getAttribute("aria-invalid")).toBe("true");
+      const describedBy = textarea().getAttribute("aria-describedby");
+      expect(describedBy).not.toBeNull();
+      // The id must resolve to the message actually on screen.
+      expect(document.getElementById(describedBy!)?.textContent).toMatch(
+        /Must be a JSON object/,
+      );
+    });
+
+    it("clears the invalid marking once the text parses again", async () => {
+      renderWithMantine(<Harness initial={{}} />);
+      await setAceText("[1]");
+      expect(textarea().getAttribute("aria-invalid")).toBe("true");
+      await setAceText('{"a":1}');
+      expect(textarea().getAttribute("aria-invalid")).toBeNull();
+      expect(textarea().getAttribute("aria-describedby")).toBeNull();
+    });
+  });
+
   it("leaves an in-progress edit alone when the parent echoes it back", async () => {
     renderWithMantine(<Harness initial={{}} />);
     // The parent re-renders with the object this text parsed to; the draft must
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
index 8368b291..13056f49 100644
--- a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
@@ -1,5 +1,6 @@
-import { useRef, useState } from "react";
+import { useEffect, useId, useRef, useState } from "react";
 import { Input, useComputedColorScheme } from "@mantine/core";
+import type { Ace } from "ace-builds";
 import AceEditor from "react-ace";
 import ace from "ace-builds/src-noconflict/ace";
 import "ace-builds/src-noconflict/mode-json";
@@ -137,13 +138,47 @@ export function JsonObjectInput({
     });
   };
 
+  const wrapperId = useId();
+  const editorRef = useRef<Ace.Editor | null>(null);
+
   const parsed = parseJsonObjectDraft(draft);
   useValueChange(serialize(value), (next) => {
-    if (next !== echoed) setDraft(next);
+    if (next === echoed) return;
+    setDraft(next);
+    // `echoed` has to advance to the value now on screen, not just to what this
+    // component last emitted. Leaving it behind makes an external A → B → A
+    // sequence stick on B: the second A matches the stale `echoed` from before
+    // B arrived and is dismissed as our own echo.
+    setEchoed(next);
   });
 
+  // `Input.Wrapper` labels and describes a Mantine input through context. Ace
+  // is not one — it renders its own DOM — so the wrapper's label and error node
+  // exist but point at nothing, leaving the control unassociated with the error
+  // a screen reader needs and its visible label inert on click.
+  //
+  // A genuine external-system sync, so an effect rather than `useValueChange`:
+  // it writes to a DOM node React does not own. Giving the textarea the
+  // wrapper's own id is what makes the `<label for>` focus the editor; the
+  // error wiring follows Mantine's `${id}-error` naming.
+  useEffect(() => {
+    const element = editorRef.current?.textInput.getElement();
+    /* v8 ignore next -- the ref is set in `onLoad`, which react-ace calls
+       synchronously on mount, so this effect always sees an element. */
+    if (!element) return;
+    element.id = wrapperId;
+    if (parsed.ok) {
+      element.removeAttribute("aria-invalid");
+      element.removeAttribute("aria-describedby");
+    } else {
+      element.setAttribute("aria-invalid", "true");
+      element.setAttribute("aria-describedby", `${wrapperId}-error`);
+    }
+  }, [wrapperId, parsed.ok]);
+
   return (
     <Input.Wrapper
+      id={wrapperId}
       label={label}
       description={description}
       error={parsed.ok ? undefined : parsed.error}
@@ -162,6 +197,7 @@ export function JsonObjectInput({
         showPrintMargin={false}
         editorProps={{ $blockScrolling: Infinity }}
         onLoad={(editor) => {
+          editorRef.current = editor;
           // `textInputAriaLabel` alone is not enough: Ace composes the hidden
           // textarea's label as "<label>, Cursor at row N" inside
           // `TextInput.setAriaLabel`, and only recomputes it when the cursor
diff --git a/clients/web/src/test/integration/mcp/inspectorClient.test.ts b/clients/web/src/test/integration/mcp/inspectorClient.test.ts
index f0c85846..82e1bcf2 100644
--- a/clients/web/src/test/integration/mcp/inspectorClient.test.ts
+++ b/clients/web/src/test/integration/mcp/inspectorClient.test.ts
@@ -1419,6 +1419,10 @@ describe("InspectorClient", () => {
       ["an array", [1]],
       ["null", null],
       ["a boolean", true],
+      // Past `Number.MAX_SAFE_INTEGER` the float64 value is no longer the
+      // integer it was written as, and zod 4's `.int()` rejects it — so
+      // `Number.isInteger` is too loose a check here.
+      ["an unsafe integer", Number.MAX_SAFE_INTEGER + 1],
     ])(
       "drops a reserved progressToken that is %s rather than sending it",
       async (_label, badToken) => {
@@ -1511,6 +1515,8 @@ describe("InspectorClient", () => {
     it.each([
       ["a string", "tok-1"],
       ["an integer", 7],
+      // The boundary itself is still valid.
+      ["the largest safe integer", Number.MAX_SAFE_INTEGER],
     ])("keeps a valid progressToken that is %s", async (_label, token) => {
       client = new InspectorClient(
         {
diff --git a/core/mcp/inspectorClient.ts b/core/mcp/inspectorClient.ts
index b1d6689f..98290f1e 100644
--- a/core/mcp/inspectorClient.ts
+++ b/core/mcp/inspectorClient.ts
@@ -387,11 +387,17 @@ function describeJsonType(value: unknown): string {
  * a string or an **integer** — a float is as invalid as an object. Everything
  * else in `_meta` may be any JSON (#1910), which is exactly why this one key
  * needs its own check.
+ *
+ * `isSafeInteger`, not `isInteger`: zod 4's `.int()` rejects anything past
+ * `Number.MAX_SAFE_INTEGER`, where the float64 representation is no longer the
+ * integer it was written as. `Number.isInteger(2 ** 53)` is `true`, so the
+ * looser check would pass a token the server then rejects — verified against
+ * the pinned zod.
  */
 function isProgressToken(value: unknown): value is ProgressToken {
   return (
     typeof value === "string" ||
-    (typeof value === "number" && Number.isInteger(value))
+    (typeof value === "number" && Number.isSafeInteger(value))
   );
 }
 

From 167b9b4dab49092f928cc42718a8a21e5fe5e930 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 17:54:26 -0400
Subject: [PATCH 19/35] fix: validate every reserved `_meta` member against the
 SDK's own schema
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`progressToken` was not the only reserved key. The pinned SDK's
`RequestMetaSchema` also constrains `io.modelcontextprotocol/related-task` to
`{ taskId: string }`, and a conforming server rejects the *whole request* over
one bad reserved member rather than ignoring that key. Before #1910 every value
was a string, so only `progressToken` could be wrong; the widening made all of
them reachable.

Replace both hand-rolled checks with the SDK's schemas — `RequestMetaSchema`
for the payload, `ProgressTokenSchema` for the single value. The schema is
loose, so unknown keys pass through untouched, and zod reports the offending
top-level key as `issue.path[0]`, so only that member is dropped and its
siblings survive. A member the SDK constrains in a later release is then
covered without anyone remembering to add it — which is the drift that produced
the `isInteger`/`isSafeInteger` bug one round ago.

`name` was hard-coded, and react-ace uses it as the editor container's DOM id,
so two instances emitted duplicate ids. Derived from the per-instance id, and
deliberately distinct from the id given to the textarea — that one is what the
wrapper's `<label for>` targets, so reusing it would just move the collision.

The docs table, the docs prose and the form hint all claimed "any JSON" without
qualification, presenting a configuration as valid that the client then drops.
All three now name the reserved keys and say what happens to a bad one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../JsonObjectInput/JsonObjectInput.test.tsx  | 20 ++++
 .../JsonObjectInput/JsonObjectInput.tsx       |  6 +-
 .../ServerSettingsForm/ServerSettingsForm.tsx |  7 +-
 .../integration/mcp/inspectorClient.test.ts   | 76 +++++++++++++++
 core/mcp/inspectorClient.ts                   | 92 +++++++++++--------
 docs/mcp-server-configuration.md              | 30 +++---
 6 files changed, 179 insertions(+), 52 deletions(-)

diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
index 2d72e026..85643475 100644
--- a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
@@ -158,6 +158,26 @@ describe("JsonObjectInput", () => {
       return el;
     }
 
+    it("gives two instances distinct DOM ids", () => {
+      // react-ace uses `name` as the container id; a fixed value would put
+      // duplicate ids in the document as soon as a second editor renders.
+      renderWithMantine(
+        <>
+          <JsonObjectInput ariaLabel="First" value={{}} onChange={() => {}} />
+          <JsonObjectInput ariaLabel="Second" value={{}} onChange={() => {}} />
+        </>,
+      );
+      const containerIds = Array.from(
+        document.querySelectorAll(".ace_editor"),
+      ).map((n) => n.id);
+      const inputIds = Array.from(
+        document.querySelectorAll("textarea.ace_text-input"),
+      ).map((n) => n.id);
+      expect(containerIds).toHaveLength(2);
+      expect(new Set([...containerIds, ...inputIds]).size).toBe(4);
+      expect(containerIds.concat(inputIds).every((id) => id !== "")).toBe(true);
+    });
+
     it("lets the visible label focus the editor", () => {
       renderWithMantine(
         <JsonObjectInput
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
index 13056f49..a65b850d 100644
--- a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
@@ -187,7 +187,11 @@ export function JsonObjectInput({
       <AceEditor
         mode="json"
         theme={colorScheme === "dark" ? "github_dark" : "github"}
-        name="json-object-input"
+        // react-ace uses `name` as the editor container's DOM id, so a fixed
+        // value would collide the moment two of these render — and it must also
+        // differ from the id given to the textarea below, which is the one the
+        // wrapper's `<label for>` points at.
+        name={`${wrapperId}-editor`}
         value={draft}
         onChange={handleChange}
         width="100%"
diff --git a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
index 4abb41e7..2e03a93b 100644
--- a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
+++ b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
@@ -732,7 +732,12 @@ export function ServerSettingsForm({
               Metadata merged into the <Code>_meta</Code> field of every MCP
               request to this server, as a JSON object. Values may be any JSON —
               objects, arrays, numbers, booleans, <Code>null</Code> — not just
-              strings. Leave it as <Code>{"{}"}</Code> to send none.
+              strings. Leave it as <Code>{"{}"}</Code> to send none. The keys
+              the protocol reserves keep their own shape:{" "}
+              <Code>progressToken</Code> must be a string or an integer, and{" "}
+              <Code>io.modelcontextprotocol/related-task</Code> an object with a
+              string <Code>taskId</Code>. A reserved key that does not match is
+              dropped from the request rather than sent.
             </HintText>
             <JsonObjectInput
               ariaLabel="Request metadata JSON"
diff --git a/clients/web/src/test/integration/mcp/inspectorClient.test.ts b/clients/web/src/test/integration/mcp/inspectorClient.test.ts
index 82e1bcf2..8bd2a3bf 100644
--- a/clients/web/src/test/integration/mcp/inspectorClient.test.ts
+++ b/clients/web/src/test/integration/mcp/inspectorClient.test.ts
@@ -1469,6 +1469,82 @@ describe("InspectorClient", () => {
       },
     );
 
+    it.each([
+      ["an array", [1]],
+      ["a string", "t1"],
+      ["an object with a non-string taskId", { taskId: 5 }],
+    ])(
+      "drops a related-task member that is %s, keeping its siblings",
+      async (_label, badRelatedTask) => {
+        // `progressToken` is not the only reserved member: the pinned SDK also
+        // constrains `io.modelcontextprotocol/related-task` to
+        // `{ taskId: string }`. A bad one makes a conforming server reject the
+        // whole request, so it is dropped the same way.
+        client = new InspectorClient(
+          {
+            type: "stdio",
+            command: serverCommand.command,
+            args: serverCommand.args,
+          },
+          {
+            environment: { transport: createTransportNode },
+            progress: false,
+            defaultMetadata: {
+              "io.modelcontextprotocol/related-task": badRelatedTask,
+              keep: "me",
+            },
+          },
+        );
+        const messageLogState = new MessageLogState(client);
+        await client.connect();
+        await client.listTools();
+
+        const req = messageLogState
+          .getMessages()
+          .find(
+            (m) =>
+              m.direction === "request" &&
+              (m.message as { method?: string }).method === "tools/list",
+          );
+        const meta = metaOf(req!);
+        expect(meta).not.toHaveProperty("io.modelcontextprotocol/related-task");
+        expect(meta.keep).toBe("me");
+        messageLogState.destroy();
+      },
+    );
+
+    it("keeps a well-formed related-task member", async () => {
+      client = new InspectorClient(
+        {
+          type: "stdio",
+          command: serverCommand.command,
+          args: serverCommand.args,
+        },
+        {
+          environment: { transport: createTransportNode },
+          progress: false,
+          defaultMetadata: {
+            "io.modelcontextprotocol/related-task": { taskId: "task-1" },
+          },
+        },
+      );
+      const messageLogState = new MessageLogState(client);
+      await client.connect();
+      await client.listTools();
+
+      const req = messageLogState
+        .getMessages()
+        .find(
+          (m) =>
+            m.direction === "request" &&
+            (m.message as { method?: string }).method === "tools/list",
+        );
+      expect(metaOf(req!)["io.modelcontextprotocol/related-task"]).toEqual({
+        taskId: "task-1",
+      });
+      messageLogState.destroy();
+    });
+
     it("warns with the rejected progressToken's type, never its value", async () => {
       // This logger is persisted by real clients (the TUI writes it to
       // `~/.mcp-inspector/auth.log`), and an invalid `progressToken` can now be
diff --git a/core/mcp/inspectorClient.ts b/core/mcp/inspectorClient.ts
index 98290f1e..09c8fa89 100644
--- a/core/mcp/inspectorClient.ts
+++ b/core/mcp/inspectorClient.ts
@@ -1,4 +1,10 @@
 import { Client } from "@modelcontextprotocol/client";
+// The protocol's own schemas for the reserved `_meta` members, so the client
+// validates against the SDK rather than a restatement of it that can drift.
+import {
+  ProgressTokenSchema,
+  RequestMetaSchema,
+} from "@modelcontextprotocol/core";
 import type {
   MCPServerConfig,
   StderrLogEntry,
@@ -382,23 +388,53 @@ function describeJsonType(value: unknown): string {
 /**
  * Whether a `_meta.progressToken` value is one the protocol allows.
  *
- * The spec (and the SDK's `ProgressTokenSchema`,
- * `z.union([z.string(), z.number().int()])`) constrains this reserved member to
- * a string or an **integer** — a float is as invalid as an object. Everything
- * else in `_meta` may be any JSON (#1910), which is exactly why this one key
- * needs its own check.
- *
- * `isSafeInteger`, not `isInteger`: zod 4's `.int()` rejects anything past
- * `Number.MAX_SAFE_INTEGER`, where the float64 representation is no longer the
- * integer it was written as. `Number.isInteger(2 ** 53)` is `true`, so the
- * looser check would pass a token the server then rejects — verified against
- * the pinned zod.
+ * Delegates to the SDK's own `ProgressTokenSchema` rather than restating it.
+ * A hand-rolled check drifts: this was `Number.isInteger` until review pointed
+ * out that zod 4's `.int()` rejects anything past `Number.MAX_SAFE_INTEGER`,
+ * so an unsafe integer passed here and was rejected by the server instead.
  */
 function isProgressToken(value: unknown): value is ProgressToken {
-  return (
-    typeof value === "string" ||
-    (typeof value === "number" && Number.isSafeInteger(value))
-  );
+  return ProgressTokenSchema.safeParse(value).success;
+}
+
+/**
+ * Drop the reserved `_meta` members whose value the protocol will not accept.
+ *
+ * Most of `_meta` is arbitrary JSON (#1910), but a few keys are **reserved**
+ * and carry their own schema — `progressToken` (`string | integer`) and
+ * `io.modelcontextprotocol/related-task` (`{ taskId: string }`) in the pinned
+ * SDK. Before the widening every value was a string, so only `progressToken`
+ * could even be wrong; now any of them can, and one bad reserved member makes a
+ * conforming server reject the **whole request** rather than ignore the key.
+ *
+ * Validated with the SDK's `RequestMetaSchema` instead of a hand-maintained
+ * list, which is the point: the schema is loose, so unknown keys pass through
+ * untouched, and a member the SDK constrains in a later release is covered here
+ * without anyone remembering to add it. Zod reports the offending top-level key
+ * as `issue.path[0]`, so only that member is removed — siblings survive, and
+ * the request stays well-formed because every reserved member is optional.
+ */
+function dropInvalidReservedMeta(
+  meta: RequestMetadata,
+  logger: InspectorLogger,
+): RequestMetadata {
+  const result = RequestMetaSchema.safeParse(meta);
+  if (result.success) return meta;
+
+  const cleaned = { ...meta };
+  for (const issue of result.error.issues) {
+    const key = issue.path[0];
+    if (typeof key !== "string" || !(key in cleaned)) continue;
+    // The key and the reason, never the value: `_meta` can carry credentials,
+    // and this logger is persisted by real clients (the TUI writes it to
+    // `~/.mcp-inspector/auth.log`).
+    logger.warn(
+      { key, received: describeJsonType(cleaned[key]) },
+      "Dropping reserved `_meta` member — it does not match the protocol schema.",
+    );
+    delete cleaned[key];
+  }
+  return cleaned;
 }
 
 const MODERN_RECONNECT_BASE_MS = 500;
@@ -1085,27 +1121,11 @@ export class InspectorClient extends InspectorClientEventTarget {
       ...(logMeta ?? {}),
       ...(callMetadata ?? {}),
     };
-    // `_meta` values are arbitrary JSON (#1910), but `progressToken` is a
-    // reserved member the spec constrains to `string | integer`
-    // (`ProgressTokenSchema = z.union([z.string(), z.number().int()])`). Now
-    // that a value can be an object, an array or a float, a bad one would ride
-    // out on the wire and a conforming server would reject the whole request —
-    // so drop the member rather than send something invalid. It is optional, so
-    // the request stays well-formed and simply asks for no progress. Warn,
-    // because a silently dropped key the user typed is worse than a noisy one.
-    if ("progressToken" in merged && !isProgressToken(merged.progressToken)) {
-      // Log the rejected value's *type*, never the value. `_meta` now carries
-      // arbitrary JSON, so an invalid `progressToken` can be an object holding
-      // credentials — and this logger is persisted by real clients (the TUI
-      // writes it to `~/.mcp-inspector/auth.log`). The type is what makes the
-      // warning actionable anyway; the value would only leak.
-      this.logger.warn(
-        { received: describeJsonType(merged.progressToken) },
-        "Dropping `_meta.progressToken` — expected a string or an integer.",
-      );
-      delete merged.progressToken;
-    }
-    return Object.keys(merged).length > 0 ? merged : undefined;
+    // Reserved members carry their own schemas even though the rest of `_meta`
+    // is arbitrary JSON, and one bad reserved value makes a conforming server
+    // reject the whole request. See `dropInvalidReservedMeta`.
+    const sanitized = dropInvalidReservedMeta(merged, this.logger);
+    return Object.keys(sanitized).length > 0 ? sanitized : undefined;
   }
 
   /**
diff --git a/docs/mcp-server-configuration.md b/docs/mcp-server-configuration.md
index 67f98b12..9005411d 100644
--- a/docs/mcp-server-configuration.md
+++ b/docs/mcp-server-configuration.md
@@ -163,21 +163,21 @@ The file is the familiar MCP client-config shape — an `mcpServers` object keye
 
 These have no analog in the broader `mcp.json` ecosystem. Each is **omitted on write when it equals its default**, so a round-trip through the Inspector keeps the file diff minimal.
 
-| Field                                  | Default    | Meaning                                                                                                                                            |
-| -------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `protocolEra`                          | `"legacy"` | `"legacy"` \| `"auto"` \| `"modern"` — which protocol era to negotiate, orthogonal to the transport                                                |
-| `modernLogLevel`                       | `"debug"`  | Per-request log level stamped on modern connections, or `"off"`. Legacy connections ignore it                                                      |
-| `roots`                                | —          | Roots advertised via the `roots` client capability; each is `{ uri, name? }`                                                                       |
-| `metadata`                             | —          | Default `_meta` payload merged into every outgoing request — a JSON object, values may be any JSON. Web and TUI only today; see the CLI note below |
-| `connectionTimeout` / `requestTimeout` | —          | Timeouts in ms                                                                                                                                     |
-| `taskTtl`                              | `60000`    | TTL in ms for tasks created via "Run as task" (`DEFAULT_TASK_TTL_MS`)                                                                              |
-| `autoRefreshOnListChanged`             | `false`    | Refresh lists automatically on `*/list_changed` instead of only flagging the indicator                                                             |
-| `paginatedLists`                       | `false`    | Fetch tools/resources/prompts one page at a time instead of auto-aggregating                                                                       |
-| `advertisedExtensions`                 | —          | Per-extension overrides for what the Inspector declares in `capabilities.extensions`                                                               |
-| `maxFetchRequests`                     | `1000`     | Network-log retention for this server (`DEFAULT_MAX_FETCH_REQUESTS`); `0` means unlimited                                                          |
-| `oauth`                                | —          | `{ clientId, clientSecret, scopes, authorizationParams, authorizationUrl, tokenUrl, enterpriseManaged, onInsufficientScope }`                      |
+| Field                                  | Default    | Meaning                                                                                                                                                                                     |
+| -------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `protocolEra`                          | `"legacy"` | `"legacy"` \| `"auto"` \| `"modern"` — which protocol era to negotiate, orthogonal to the transport                                                                                         |
+| `modernLogLevel`                       | `"debug"`  | Per-request log level stamped on modern connections, or `"off"`. Legacy connections ignore it                                                                                               |
+| `roots`                                | —          | Roots advertised via the `roots` client capability; each is `{ uri, name? }`                                                                                                                |
+| `metadata`                             | —          | Default `_meta` payload merged into every outgoing request — a JSON object; values may be any JSON except for the reserved keys noted below. Web and TUI only today; see the CLI note below |
+| `connectionTimeout` / `requestTimeout` | —          | Timeouts in ms                                                                                                                                                                              |
+| `taskTtl`                              | `60000`    | TTL in ms for tasks created via "Run as task" (`DEFAULT_TASK_TTL_MS`)                                                                                                                       |
+| `autoRefreshOnListChanged`             | `false`    | Refresh lists automatically on `*/list_changed` instead of only flagging the indicator                                                                                                      |
+| `paginatedLists`                       | `false`    | Fetch tools/resources/prompts one page at a time instead of auto-aggregating                                                                                                                |
+| `advertisedExtensions`                 | —          | Per-extension overrides for what the Inspector declares in `capabilities.extensions`                                                                                                        |
+| `maxFetchRequests`                     | `1000`     | Network-log retention for this server (`DEFAULT_MAX_FETCH_REQUESTS`); `0` means unlimited                                                                                                   |
+| `oauth`                                | —          | `{ clientId, clientSecret, scopes, authorizationParams, authorizationUrl, tokenUrl, enterpriseManaged, onInsufficientScope }`                                                               |
 
-`metadata` is a JSON **object**, and its values may be any JSON — an object, an array, a number, a boolean, `null` — not only a string. Nothing in the MCP spec restricts `_meta` value types, and the SDK models the field as a passthrough object, so the Inspector does not narrow it either ([#1910](https://github.com/modelcontextprotocol/inspector/issues/1910)). Edit it in Server Settings → Request Metadata, which is a JSON editor rather than the key/value rows `headers` and `env` use; text that is not a JSON object is flagged inline and not applied.
+`metadata` is a JSON **object**, and its values may be any JSON — an object, an array, a number, a boolean, `null` — not only a string. The MCP spec does not restrict `_meta` value types in general, and the SDK models the field as a passthrough object, so the Inspector does not narrow it either ([#1910](https://github.com/modelcontextprotocol/inspector/issues/1910)). Edit it in Server Settings → Request Metadata, which is a JSON editor rather than the key/value rows `headers` and `env` use; text that is not a JSON object is flagged inline and not applied.
 
 ```jsonc
 "metadata": {
@@ -187,6 +187,8 @@ These have no analog in the broader `mcp.json` ecosystem. Each is **omitted on w
 }
 ```
 
+> **A few keys are reserved and keep their own shape.** "Any JSON" holds for keys you invent, not for the ones the protocol defines. In the current SDK those are `progressToken` (a string or an integer) and `io.modelcontextprotocol/related-task` (`{ "taskId": "<string>" }`). A reserved key whose value does not match is **dropped from the outgoing request**, with a warning naming the key — because a conforming server rejects the _entire_ request over one bad reserved member, rather than ignoring that key. Everything else in the payload is sent unchanged.
+
 > **Not yet applied by the CLI.** The web client and the TUI both send this payload on every request. The CLI does not — it never passes the persisted value to its client, so a `metadata` entry is currently inert for `--cli` runs ([#2093](https://github.com/modelcontextprotocol/inspector/issues/2093)). Use the per-invocation `--metadata` flag there in the meantime.
 
 > **Reading an older file.** Before #1910 this field was a `[{ "key": …, "value": … }]` pair array. That shape is still **read**, so an existing `mcp.json` keeps working unchanged; it is never written back, so the field is rewritten as an object the next time the Inspector saves the entry.

From 1eaebdaf63922610fb76cfabece664e26689b6d9 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 18:06:37 -0400
Subject: [PATCH 20/35] test: assert the dropped-member warning by its binding,
 not its message
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Generalizing the sanitizer changed the warning to one message shared by every
reserved member, moving the offending key into the log's bindings — but this
test still matched on the old message text, so it stopped finding the call at
all. Caught by `npm run ci`.

Asserting `{ key, received }` is the more durable check anyway: the message is
now common to all reserved members, while the binding is what identifies which
one was dropped.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../web/src/test/integration/mcp/inspectorClient.test.ts  | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/clients/web/src/test/integration/mcp/inspectorClient.test.ts b/clients/web/src/test/integration/mcp/inspectorClient.test.ts
index 8bd2a3bf..bcace955 100644
--- a/clients/web/src/test/integration/mcp/inspectorClient.test.ts
+++ b/clients/web/src/test/integration/mcp/inspectorClient.test.ts
@@ -1579,11 +1579,13 @@ describe("InspectorClient", () => {
       await client.connect();
       await client.listTools();
 
-      const call = warn.mock.calls.find((c) =>
-        String(c[1]).includes("progressToken"),
+      // The offending key travels in the log's bindings, not in the message —
+      // the message is shared by every reserved member the sanitizer drops.
+      const call = warn.mock.calls.find(
+        (c) => (c[0] as { key?: string })?.key === "progressToken",
       );
       expect(call).toBeDefined();
-      expect(call![0]).toEqual({ received: "object" });
+      expect(call![0]).toEqual({ key: "progressToken", received: "object" });
       // Belt and braces: the secret must not appear anywhere in the record.
       expect(JSON.stringify(warn.mock.calls)).not.toContain("sk-live");
     });

From 616dd9c196801175ebd4ed2f6b5ce728a8e752a2 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 18:27:28 -0400
Subject: [PATCH 21/35] fix: exclude `undefined` from `_meta` values, and cover
 the JSON worker
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- `JsonValue` admits `undefined`, so `RequestMetadata` accepted values that do
  not survive serialization: `JSON.stringify` drops an `undefined` object
  member and rewrites an `undefined` array element to `null`. The type
  contradicted the one promise this payload makes. Added `StrictJsonValue` /
  `StrictJsonObject` and used them for the metadata path.

  Deliberately not a change to the repo-wide `JsonValue`: for tool *arguments*
  `undefined` legitimately means "not supplied". The narrowing is sound
  wherever it lands here, since every one of these values comes from
  `JSON.parse`, which cannot produce `undefined`. The CLI's `parseKeyValuePair`
  needed the same tightening — caught by `clients/cli`'s typecheck, which the
  web `tsc -b` does not cover.

- Nothing asserted the JSON worker's annotations, and the wrapper's own "Not
  valid JSON" message comes from our parser rather than from Ace — so a broken
  worker URL would have left every test passing while the gutter diagnostics
  silently disappeared. Added a Storybook play function that waits for a real
  `session.getAnnotations()` error entry, and verified it fails when the worker
  module URL is pointed at a bad path.

- `aria-describedby` referenced only the error, so a supplied `description` was
  never announced and would have been dropped entirely once the draft went
  invalid. Both ids are referenced now, with the description surviving the
  error.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/cli/src/cli.ts                        | 15 ++++---
 .../JsonObjectInput.stories.tsx               | 41 +++++++++++++++--
 .../JsonObjectInput/JsonObjectInput.test.tsx  | 44 ++++++++++++++++---
 .../JsonObjectInput/JsonObjectInput.tsx       | 29 +++++++++---
 clients/web/src/utils/jsonObjectDraft.ts      | 14 ++++--
 core/json/jsonUtils.ts                        | 23 ++++++++++
 core/mcp/types.ts                             | 15 +++++--
 7 files changed, 151 insertions(+), 30 deletions(-)

diff --git a/clients/cli/src/cli.ts b/clients/cli/src/cli.ts
index 35ca3dd9..6f9c8550 100644
--- a/clients/cli/src/cli.ts
+++ b/clients/cli/src/cli.ts
@@ -24,6 +24,7 @@ import {
   parseHeaderPair,
 } from "@inspector/core/mcp/node/index.js";
 import type { JsonValue } from "@inspector/core/mcp/index.js";
+import type { StrictJsonValue } from "@inspector/core/json/jsonUtils.js";
 import {
   canonicalUrlHost,
   isAllInterfacesHost,
@@ -473,8 +474,8 @@ function buildHandoff(
 
 function parseKeyValuePair(
   value: string,
-  previous: Record<string, JsonValue> = {},
-): Record<string, JsonValue> {
+  previous: Record<string, StrictJsonValue> = {},
+): Record<string, StrictJsonValue> {
   const parts = value.split("=");
   const key = parts[0];
   const val = parts.slice(1).join("=");
@@ -485,9 +486,11 @@ function parseKeyValuePair(
     );
   }
 
-  let parsedValue: JsonValue;
+  // `StrictJsonValue`: `JSON.parse` cannot produce `undefined`, and these values
+  // become `_meta`, which must reach the wire exactly as written (#1910).
+  let parsedValue: StrictJsonValue;
   try {
-    parsedValue = JSON.parse(val) as JsonValue;
+    parsedValue = JSON.parse(val) as StrictJsonValue;
   } catch {
     parsedValue = val;
   }
@@ -735,8 +738,8 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
     promptName?: string;
     promptArgs?: Record<string, JsonValue>;
     logLevel?: LoggingLevel;
-    metadata?: Record<string, JsonValue>;
-    toolMetadata?: Record<string, JsonValue>;
+    metadata?: Record<string, StrictJsonValue>;
+    toolMetadata?: Record<string, StrictJsonValue>;
     cwd?: string;
     transport?: "sse" | "http" | "stdio";
     serverUrl?: string;
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.stories.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.stories.tsx
index cdbcfc0f..82a6bcc3 100644
--- a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.stories.tsx
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.stories.tsx
@@ -1,7 +1,7 @@
 import { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { expect, userEvent, within } from "storybook/test";
-import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import type { StrictJsonObject } from "@inspector/core/json/jsonUtils.js";
 import { JsonObjectInput } from "./JsonObjectInput";
 
 const LABEL = "Request metadata JSON";
@@ -15,8 +15,8 @@ const LABEL = "Request metadata JSON";
  * place Ace's keyboard behavior can be tested: the unit suite runs in
  * happy-dom, where Ace's hidden-textarea input path does not work at all.
  */
-function ControlledJsonObjectInput({ initial }: { initial: JsonObject }) {
-  const [value, setValue] = useState<JsonObject>(initial);
+function ControlledJsonObjectInput({ initial }: { initial: StrictJsonObject }) {
+  const [value, setValue] = useState<StrictJsonObject>(initial);
   return (
     <JsonObjectInput
       label="Request metadata"
@@ -40,6 +40,7 @@ function aceEditor(canvasElement: HTMLElement): {
   focus(): void;
   selectAll(): void;
   getValue(): string;
+  session: { getAnnotations(): { row: number; type: string }[] };
 } {
   const container = canvasElement.querySelector(".ace_editor");
   const editor = (
@@ -50,6 +51,7 @@ function aceEditor(canvasElement: HTMLElement): {
               focus(): void;
               selectAll(): void;
               getValue(): string;
+              session: { getAnnotations(): { row: number; type: string }[] };
             };
           };
         })
@@ -182,3 +184,34 @@ export const NotAnObject: Story = {
     ).toBeVisible();
   },
 };
+
+/**
+ * The JSON worker marks the offending line in the gutter — the reason this
+ * component registers `worker-json` through `ace.config.setModuleUrl` with a
+ * Vite `?url` asset.
+ *
+ * Asserted because nothing else covers it: the worker runs out-of-process, so
+ * if its URL registration breaks, Ace fails to start it and silently falls back
+ * to no annotations. Every other test here — including the wrapper's own
+ * "Not valid JSON" message, which comes from our parser, not from Ace — would
+ * still pass while the gutter diagnostics quietly disappeared.
+ */
+export const AnnotatesTheOffendingLine: Story = {
+  args: { initial: {} },
+  play: async ({ canvasElement }) => {
+    await focusAndClear(canvasElement);
+    // A trailing comma on line 2: valid-looking until the closing brace, so the
+    // worker has to locate it rather than just reject the document.
+    await userEvent.keyboard('{{"a": 1,{Enter}}');
+    await waitFor(
+      async () => {
+        const annotations = aceEditor(canvasElement).session.getAnnotations();
+        await expect(annotations.length).toBeGreaterThan(0);
+        await expect(annotations.some((a) => a.type === "error")).toBe(true);
+      },
+      // The worker is asynchronous and debounced, so this needs a real wait
+      // rather than a tick.
+      { timeout: 5000 },
+    );
+  },
+};
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
index 85643475..eaf4bb1b 100644
--- a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.test.tsx
@@ -1,7 +1,7 @@
 import { useState } from "react";
 import { describe, it, expect, vi } from "vitest";
 import { act, screen } from "@testing-library/react";
-import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
+import type { StrictJsonObject } from "@inspector/core/json/jsonUtils.js";
 import { renderWithMantine } from "../../../test/renderWithMantine";
 import { aceLabel, getAceText, setAceText } from "../../../test/aceEditor";
 import { JsonObjectInput } from "./JsonObjectInput";
@@ -13,10 +13,10 @@ function Harness({
   initial,
   onChange,
 }: {
-  initial: JsonObject;
-  onChange?: (v: JsonObject) => void;
+  initial: StrictJsonObject;
+  onChange?: (v: StrictJsonObject) => void;
 }) {
-  const [value, setValue] = useState<JsonObject>(initial);
+  const [value, setValue] = useState<StrictJsonObject>(initial);
   return (
     <>
       <JsonObjectInput
@@ -109,7 +109,7 @@ describe("JsonObjectInput", () => {
     // An external reset (switching servers, a reloaded catalog) must reach the
     // editor; an in-progress edit must not be overwritten by what it emitted.
     function Externally() {
-      const [value, setValue] = useState<JsonObject>({ a: 1 });
+      const [value, setValue] = useState<StrictJsonObject>({ a: 1 });
       return (
         <>
           <JsonObjectInput
@@ -132,7 +132,7 @@ describe("JsonObjectInput", () => {
     // Regression: `echoed` used to hold only what this component last emitted,
     // so returning to a previously-shown value matched the stale entry and was
     // dismissed as our own echo, stranding the editor on B.
-    function Externally({ value }: { value: JsonObject }) {
+    function Externally({ value }: { value: StrictJsonObject }) {
       return (
         <JsonObjectInput ariaLabel={LABEL} value={value} onChange={() => {}} />
       );
@@ -208,6 +208,38 @@ describe("JsonObjectInput", () => {
       );
     });
 
+    it("announces a supplied description, and keeps it when the draft breaks", async () => {
+      function WithDescription() {
+        const [value, setValue] = useState<StrictJsonObject>({});
+        return (
+          <JsonObjectInput
+            ariaLabel={LABEL}
+            description="Sent with every request"
+            value={value}
+            onChange={setValue}
+          />
+        );
+      }
+      renderWithMantine(<WithDescription />);
+
+      const described = () =>
+        (textarea().getAttribute("aria-describedby") ?? "")
+          .split(" ")
+          .filter(Boolean)
+          .map((id) => document.getElementById(id)?.textContent);
+
+      // Valid draft: described by the description alone.
+      expect(described()).toEqual(["Sent with every request"]);
+
+      // Invalid draft: the error joins it rather than replacing it — the
+      // description is still true, and dropping it would silently un-describe
+      // the control at the moment it needs explaining most.
+      await setAceText("[1]");
+      expect(described()).toHaveLength(2);
+      expect(described()[0]).toBe("Sent with every request");
+      expect(described()[1]).toMatch(/Must be a JSON object/);
+    });
+
     it("clears the invalid marking once the text parses again", async () => {
       renderWithMantine(<Harness initial={{}} />);
       await setAceText("[1]");
diff --git a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
index a65b850d..9c5842f9 100644
--- a/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
+++ b/clients/web/src/components/elements/JsonObjectInput/JsonObjectInput.tsx
@@ -10,7 +10,7 @@ import "ace-builds/src-noconflict/theme-github_dark";
 // Without it Ace fetches `worker-json.js` from a path that does not exist in a
 // bundled app, silently loses its annotations, and logs a fetch error.
 import jsonWorkerUrl from "ace-builds/src-noconflict/worker-json.js?url";
-import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
+import type { StrictJsonObject } from "@inspector/core/json/jsonUtils.js";
 import { useValueChange } from "../../../hooks/useValueChange";
 import { parseJsonObjectDraft } from "../../../utils/jsonObjectDraft";
 
@@ -19,13 +19,13 @@ import { parseJsonObjectDraft } from "../../../utils/jsonObjectDraft";
 ace.config.setModuleUrl("ace/mode/json_worker", jsonWorkerUrl);
 
 /** Two-space canonical form — the same shape the catalog file is written in. */
-function serialize(value: JsonObject): string {
+function serialize(value: StrictJsonObject): string {
   return JSON.stringify(value, null, 2);
 }
 
 export interface JsonObjectInputProps {
-  value: JsonObject;
-  onChange: (value: JsonObject) => void;
+  value: StrictJsonObject;
+  onChange: (value: StrictJsonObject) => void;
   label?: string;
   description?: string;
   /**
@@ -167,14 +167,29 @@ export function JsonObjectInput({
        synchronously on mount, so this effect always sees an element. */
     if (!element) return;
     element.id = wrapperId;
+
+    // Both the description and the error are rendered by the wrapper and both
+    // describe this control, so both ids belong here — a supplied description
+    // is otherwise never announced, and it must not be dropped just because the
+    // draft went invalid. Mantine renders each only when its prop is set, so
+    // referencing an absent one would point at nothing.
+    const describedBy = [
+      description === undefined ? null : `${wrapperId}-description`,
+      parsed.ok ? null : `${wrapperId}-error`,
+    ].filter((id) => id !== null);
+
+    if (describedBy.length > 0) {
+      element.setAttribute("aria-describedby", describedBy.join(" "));
+    } else {
+      element.removeAttribute("aria-describedby");
+    }
+
     if (parsed.ok) {
       element.removeAttribute("aria-invalid");
-      element.removeAttribute("aria-describedby");
     } else {
       element.setAttribute("aria-invalid", "true");
-      element.setAttribute("aria-describedby", `${wrapperId}-error`);
     }
-  }, [wrapperId, parsed.ok]);
+  }, [wrapperId, parsed.ok, description]);
 
   return (
     <Input.Wrapper
diff --git a/clients/web/src/utils/jsonObjectDraft.ts b/clients/web/src/utils/jsonObjectDraft.ts
index b5397079..16bc545e 100644
--- a/clients/web/src/utils/jsonObjectDraft.ts
+++ b/clients/web/src/utils/jsonObjectDraft.ts
@@ -1,15 +1,21 @@
-import type { JsonObject } from "@inspector/core/json/jsonUtils.js";
+import type { StrictJsonObject } from "@inspector/core/json/jsonUtils.js";
 
 /**
  * What a JSON-object editor's draft text currently means: the object to emit,
  * or why it cannot be emitted.
  */
 export type JsonObjectDraft =
-  | { ok: true; value: JsonObject }
+  | { ok: true; value: StrictJsonObject }
   | { ok: false; error: string };
 
-/** A plain JSON object, i.e. not an array and not a scalar. */
-export function isJsonObject(value: unknown): value is JsonObject {
+/**
+ * A plain JSON object, i.e. not an array and not a scalar.
+ *
+ * The `StrictJsonObject` narrowing is sound because the only caller parses with
+ * `JSON.parse`, whose output cannot contain `undefined` — the value that
+ * separates the strict type from `JsonValue`.
+ */
+export function isJsonObject(value: unknown): value is StrictJsonObject {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
diff --git a/core/json/jsonUtils.ts b/core/json/jsonUtils.ts
index 7366bb9c..a84de8fc 100644
--- a/core/json/jsonUtils.ts
+++ b/core/json/jsonUtils.ts
@@ -14,6 +14,29 @@ export type JsonValue =
 
 export type JsonObject = { [key: string]: JsonValue };
 
+/**
+ * A JSON value that survives serialization unchanged — {@link JsonValue}
+ * without `undefined`.
+ *
+ * `JsonValue` admits `undefined` because it is also used for *arguments*, where
+ * it usefully means "this field was not supplied". That meaning does not carry
+ * to a payload the Inspector promises to transmit verbatim: `JSON.stringify`
+ * drops an `undefined` object member entirely and rewrites an `undefined` array
+ * element to `null`, so a value the type accepted is not the value that arrives.
+ *
+ * Used for `_meta` (#1910), whose whole contract is that any JSON the user
+ * writes reaches the wire as written.
+ */
+export type StrictJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | StrictJsonValue[]
+  | { [key: string]: StrictJsonValue };
+
+export type StrictJsonObject = { [key: string]: StrictJsonValue };
+
 /**
  * Widen a typed object to a generic string-keyed record so its keys can be
  * iterated or read/written generically. Many of the project's config/SDK types
diff --git a/core/mcp/types.ts b/core/mcp/types.ts
index 1b94f9ea..507076de 100644
--- a/core/mcp/types.ts
+++ b/core/mcp/types.ts
@@ -24,7 +24,11 @@ import type { OAuthClientProvider } from "@modelcontextprotocol/client";
 import type { Transport } from "@modelcontextprotocol/client";
 import type { InspectorLogger } from "../logging/logger.js";
 import type { AppElicitationRenderer } from "./appElicitation.js";
-import type { JsonObject, JsonValue } from "../json/jsonUtils.js";
+import type {
+  JsonValue,
+  StrictJsonObject,
+  StrictJsonValue,
+} from "../json/jsonUtils.js";
 import type {
   ClientConfig,
   EnterpriseManagedAuthIdpConfig,
@@ -112,7 +116,7 @@ export type StoredMCPServer = MCPServerConfig & {
    * existing `mcp.json` keeps working, but it is never written back — a
    * round-trip through the Inspector rewrites the field as an object.
    */
-  metadata?: JsonObject;
+  metadata?: StrictJsonObject;
   /**
    * Protocol era to negotiate with this server (`"legacy" | "auto" | "modern"`),
    * orthogonal to the transport `type`. Inspector-specific (no analog in the
@@ -374,6 +378,11 @@ export interface ServerState {
  * A `_meta` payload: a JSON object whose values may be any JSON, not just
  * strings (#1910).
  *
+ * {@link StrictJsonValue}, not `JsonValue`: the latter admits `undefined`,
+ * which `JSON.stringify` drops from an object and turns into `null` inside an
+ * array — so a value the type accepted would not be the value that reaches the
+ * server, contradicting the one promise this payload makes.
+ *
  * The MCP spec places no restriction on `_meta` value types and the SDK models
  * the field as a passthrough object, so the Inspector must be able to send —
  * and to record — nested objects, arrays, numbers, booleans and `null`. Used
@@ -381,7 +390,7 @@ export interface ServerState {
  * `InspectorClientOptions.defaultMetadata`) and the per-call metadata every
  * request verb accepts.
  */
-export type RequestMetadata = Record<string, JsonValue>;
+export type RequestMetadata = Record<string, StrictJsonValue>;
 
 /**
  * Represents a complete resource read invocation, including request parameters,

From 129a435fd4a87d89d27ac6f49bd21b1b0c3fcc76 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 19:31:50 -0400
Subject: [PATCH 22/35] docs: say "safe integer" for progressToken, matching
 what the code enforces
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The copy said `progressToken` may be "an integer" while the implementation
validates with `ProgressTokenSchema` — zod's `.int()`, which rejects anything
past `Number.MAX_SAFE_INTEGER`. This repo's own tests assert that
`MAX_SAFE_INTEGER + 1` is dropped, so the documentation was promising a value
the client discards.

Corrected in all three places, so the code comment, the docs callout and the UI
hint agree: `dropInvalidReservedMeta`'s doc block (which review did not flag),
the `metadata` reserved-keys callout, and the Request Metadata hint.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../groups/ServerSettingsForm/ServerSettingsForm.tsx           | 3 ++-
 core/mcp/inspectorClient.ts                                    | 3 ++-
 docs/mcp-server-configuration.md                               | 2 +-
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
index 2e03a93b..2de2e314 100644
--- a/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
+++ b/clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx
@@ -734,7 +734,8 @@ export function ServerSettingsForm({
               objects, arrays, numbers, booleans, <Code>null</Code> — not just
               strings. Leave it as <Code>{"{}"}</Code> to send none. The keys
               the protocol reserves keep their own shape:{" "}
-              <Code>progressToken</Code> must be a string or an integer, and{" "}
+              <Code>progressToken</Code> must be a string or a safe integer (one
+              JavaScript can represent exactly), and{" "}
               <Code>io.modelcontextprotocol/related-task</Code> an object with a
               string <Code>taskId</Code>. A reserved key that does not match is
               dropped from the request rather than sent.
diff --git a/core/mcp/inspectorClient.ts b/core/mcp/inspectorClient.ts
index 09c8fa89..542ac8ae 100644
--- a/core/mcp/inspectorClient.ts
+++ b/core/mcp/inspectorClient.ts
@@ -401,7 +401,8 @@ function isProgressToken(value: unknown): value is ProgressToken {
  * Drop the reserved `_meta` members whose value the protocol will not accept.
  *
  * Most of `_meta` is arbitrary JSON (#1910), but a few keys are **reserved**
- * and carry their own schema — `progressToken` (`string | integer`) and
+ * and carry their own schema — `progressToken` (a string or a safe integer;
+ * zod's `.int()` rejects anything past `Number.MAX_SAFE_INTEGER`) and
  * `io.modelcontextprotocol/related-task` (`{ taskId: string }`) in the pinned
  * SDK. Before the widening every value was a string, so only `progressToken`
  * could even be wrong; now any of them can, and one bad reserved member makes a
diff --git a/docs/mcp-server-configuration.md b/docs/mcp-server-configuration.md
index 9005411d..b394862a 100644
--- a/docs/mcp-server-configuration.md
+++ b/docs/mcp-server-configuration.md
@@ -187,7 +187,7 @@ These have no analog in the broader `mcp.json` ecosystem. Each is **omitted on w
 }
 ```
 
-> **A few keys are reserved and keep their own shape.** "Any JSON" holds for keys you invent, not for the ones the protocol defines. In the current SDK those are `progressToken` (a string or an integer) and `io.modelcontextprotocol/related-task` (`{ "taskId": "<string>" }`). A reserved key whose value does not match is **dropped from the outgoing request**, with a warning naming the key — because a conforming server rejects the _entire_ request over one bad reserved member, rather than ignoring that key. Everything else in the payload is sent unchanged.
+> **A few keys are reserved and keep their own shape.** "Any JSON" holds for keys you invent, not for the ones the protocol defines. In the current SDK those are `progressToken` (a string or a **safe** integer — one JavaScript represents exactly, so nothing past `Number.MAX_SAFE_INTEGER`) and `io.modelcontextprotocol/related-task` (`{ "taskId": "<string>" }`). A reserved key whose value does not match is **dropped from the outgoing request**, with a warning naming the key — because a conforming server rejects the _entire_ request over one bad reserved member, rather than ignoring that key. Everything else in the payload is sent unchanged.
 
 > **Not yet applied by the CLI.** The web client and the TUI both send this payload on every request. The CLI does not — it never passes the persisted value to its client, so a `metadata` entry is currently inert for `--cli` runs ([#2093](https://github.com/modelcontextprotocol/inspector/issues/2093)). Use the per-invocation `--metadata` flag there in the meantime.
 

From 7f5992081e807157d8dc42e2064ba138439be2a2 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 19:43:39 -0400
Subject: [PATCH 23/35] fix: reject non-finite numbers before they reach
 `_meta`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`StrictJsonValue` removed `undefined`, but the type cannot express the rest of
the gap: TypeScript has one `number`, and JSON has no encoding for `NaN` or
`±Infinity`, so `JSON.stringify` rewrites them to `null`.

This is reachable from ordinary input, not a careless caller.
`JSON.parse('{"a":1e400}')` returns `Infinity` on overflow — so text a user
types parses cleanly, satisfies the type, and reaches the server as `null`
while the editor still shows `1e400`.

`isSerializableJson` in `core/json` is the runtime half of `StrictJsonValue`,
applied at both boundaries that turn text into metadata:

- the editor's draft parser, which now reports "Numbers must be finite" inline
  and withholds the value rather than emitting one it cannot send;
- the CLI's `--metadata` / `--tool-metadata` parser, which throws. Silently
  sending `null` would be wrong, and so would falling back to the literal
  string — neither is what was asked for.

Tests cover the validator directly (including that `JSON.stringify` really does
write `null`, which is the reason it matters), the editor parser, and the CLI
flag.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/cli/__tests__/metadata.test.ts        | 31 ++++++++++++
 clients/cli/src/cli.ts                        | 14 ++++++
 .../test/core/json/isSerializableJson.test.ts | 47 +++++++++++++++++++
 clients/web/src/utils/jsonObjectDraft.test.ts | 19 ++++++++
 clients/web/src/utils/jsonObjectDraft.ts      | 11 +++++
 core/json/jsonUtils.ts                        | 34 ++++++++++++++
 6 files changed, 156 insertions(+)
 create mode 100644 clients/web/src/test/core/json/isSerializableJson.test.ts

diff --git a/clients/cli/__tests__/metadata.test.ts b/clients/cli/__tests__/metadata.test.ts
index a4cb05fc..ef8e2b37 100644
--- a/clients/cli/__tests__/metadata.test.ts
+++ b/clients/cli/__tests__/metadata.test.ts
@@ -880,6 +880,37 @@ describe("Metadata Tests", () => {
       }
     });
 
+    it.each([
+      ["an overflowing literal", "n=1e400"],
+      ["a negative overflow", "n=-1e400"],
+      ["one nested in an object", 'o={"a":1e400}'],
+    ])("rejects %s rather than sending null", async (_label, pair) => {
+      // `JSON.parse` accepts these and yields ±Infinity, which
+      // `JSON.stringify` writes as `null` — so accepting the flag would
+      // transmit a value the user did not ask for.
+      const server = createTestServerHttp({
+        serverInfo: createTestServerInfo(),
+        tools: [createEchoTool()],
+      });
+      try {
+        await server.start();
+        const result = await runCli([
+          server.url,
+          "--cli",
+          "--method",
+          "tools/list",
+          "--metadata",
+          pair,
+          "--transport",
+          "http",
+        ]);
+        expect(result.exitCode).not.toBe(0);
+        expect(`${result.stderr}${result.stdout}`).toMatch(/finite/i);
+      } finally {
+        await server.stop();
+      }
+    });
+
     it("should handle metadata parsing validation", async () => {
       const server = createTestServerHttp({
         serverInfo: createTestServerInfo(),
diff --git a/clients/cli/src/cli.ts b/clients/cli/src/cli.ts
index 6f9c8550..c486a725 100644
--- a/clients/cli/src/cli.ts
+++ b/clients/cli/src/cli.ts
@@ -25,6 +25,7 @@ import {
 } from "@inspector/core/mcp/node/index.js";
 import type { JsonValue } from "@inspector/core/mcp/index.js";
 import type { StrictJsonValue } from "@inspector/core/json/jsonUtils.js";
+import { isSerializableJson } from "@inspector/core/json/jsonUtils.js";
 import {
   canonicalUrlHost,
   isAllInterfacesHost,
@@ -492,9 +493,22 @@ function parseKeyValuePair(
   try {
     parsedValue = JSON.parse(val) as StrictJsonValue;
   } catch {
+    // Not JSON at all — a bare word or an unquoted string. Sent as a string,
+    // which is what the user plainly meant.
     parsedValue = val;
   }
 
+  // Valid JSON syntax is not the same as sendable JSON: `1e400` parses to
+  // `Infinity`, which `JSON.stringify` writes as `null`. Rejecting is better
+  // than accepting the flag and silently transmitting a different value —
+  // and better than falling back to the literal string, which would also not
+  // be what was asked for.
+  if (!isSerializableJson(parsedValue)) {
+    throw new Error(
+      `Invalid parameter value: ${value}. Numbers must be finite (a value like 1e400 overflows and cannot be sent).`,
+    );
+  }
+
   return { ...previous, [key as string]: parsedValue };
 }
 
diff --git a/clients/web/src/test/core/json/isSerializableJson.test.ts b/clients/web/src/test/core/json/isSerializableJson.test.ts
new file mode 100644
index 00000000..ea0d91f4
--- /dev/null
+++ b/clients/web/src/test/core/json/isSerializableJson.test.ts
@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { isSerializableJson } from "@inspector/core/json/jsonUtils.js";
+
+describe("isSerializableJson", () => {
+  it.each([
+    ["a string", "a"],
+    ["a finite number", 1.5],
+    ["zero", 0],
+    ["a negative number", -42],
+    ["a boolean", true],
+    ["null", null],
+    ["a nested object", { a: { b: [1, 2, { c: "d" }] } }],
+    ["an empty array", []],
+  ])("accepts %s", (_label, value) => {
+    expect(isSerializableJson(value)).toBe(true);
+  });
+
+  it.each([
+    ["NaN", NaN],
+    ["Infinity", Infinity],
+    ["-Infinity", -Infinity],
+  ])("rejects %s, which JSON.stringify rewrites to null", (_label, value) => {
+    expect(isSerializableJson(value)).toBe(false);
+    // The reason it matters, asserted rather than asserted-about.
+    expect(JSON.stringify({ v: value })).toBe('{"v":null}');
+  });
+
+  it.each([
+    ["undefined", undefined],
+    ["a function", () => {}],
+    ["a symbol", Symbol("s")],
+    ["a bigint", 10n],
+  ])("rejects %s, which is not JSON at all", (_label, value) => {
+    expect(isSerializableJson(value)).toBe(false);
+  });
+
+  it("descends into arrays and objects", () => {
+    expect(isSerializableJson({ a: [1, { b: Infinity }] })).toBe(false);
+    expect(isSerializableJson([[[NaN]]])).toBe(false);
+    expect(isSerializableJson({ a: [1, { b: 2 }] })).toBe(true);
+  });
+
+  it("rejects what `JSON.parse` produces for an overflowing literal", () => {
+    // The reachable path: valid JSON text that parses to an unsendable value.
+    expect(isSerializableJson(JSON.parse('{"n":1e400}'))).toBe(false);
+  });
+});
diff --git a/clients/web/src/utils/jsonObjectDraft.test.ts b/clients/web/src/utils/jsonObjectDraft.test.ts
index 83298caf..51e835a4 100644
--- a/clients/web/src/utils/jsonObjectDraft.test.ts
+++ b/clients/web/src/utils/jsonObjectDraft.test.ts
@@ -24,6 +24,25 @@ describe("parseJsonObjectDraft", () => {
     });
   });
 
+  it.each([
+    ["an overflowing literal", '{"n":1e400}'],
+    ["a negative overflow", '{"n":-1e400}'],
+    ["one nested in an array", '{"a":[1,1e400]}'],
+  ])("rejects %s, which would be sent as null", (_label, text) => {
+    // `JSON.parse` accepts these; `JSON.stringify` then writes `null`, so the
+    // editor would show one value and the wire would carry another.
+    const result = parseJsonObjectDraft(text);
+    expect(result.ok).toBe(false);
+    expect(result.ok === false && result.error).toMatch(/finite/);
+  });
+
+  it("still accepts large-but-finite numbers", () => {
+    expect(parseJsonObjectDraft('{"n":1e308}')).toEqual({
+      ok: true,
+      value: { n: 1e308 },
+    });
+  });
+
   it("rejects text that is not JSON", () => {
     expect(parseJsonObjectDraft('{"a":')).toEqual({
       ok: false,
diff --git a/clients/web/src/utils/jsonObjectDraft.ts b/clients/web/src/utils/jsonObjectDraft.ts
index 16bc545e..731d6b8f 100644
--- a/clients/web/src/utils/jsonObjectDraft.ts
+++ b/clients/web/src/utils/jsonObjectDraft.ts
@@ -1,4 +1,5 @@
 import type { StrictJsonObject } from "@inspector/core/json/jsonUtils.js";
+import { isSerializableJson } from "@inspector/core/json/jsonUtils.js";
 
 /**
  * What a JSON-object editor's draft text currently means: the object to emit,
@@ -49,5 +50,15 @@ export function parseJsonObjectDraft(text: string): JsonObjectDraft {
       error: "Must be a JSON object (`{ … }`) — changes are not applied",
     };
   }
+  // `JSON.parse` accepts numeric literals it cannot represent: `1e400` parses
+  // to `Infinity`, which `JSON.stringify` then writes as `null`. Accepting it
+  // here would show the user one value and send another.
+  if (!isSerializableJson(parsed)) {
+    return {
+      ok: false,
+      error:
+        "Numbers must be finite — a value like `1e400` overflows and would be sent as null",
+    };
+  }
   return { ok: true, value: parsed };
 }
diff --git a/core/json/jsonUtils.ts b/core/json/jsonUtils.ts
index a84de8fc..ba1533e9 100644
--- a/core/json/jsonUtils.ts
+++ b/core/json/jsonUtils.ts
@@ -37,6 +37,40 @@ export type StrictJsonValue =
 
 export type StrictJsonObject = { [key: string]: StrictJsonValue };
 
+/**
+ * Whether a value is JSON that survives `JSON.stringify` unchanged.
+ *
+ * {@link StrictJsonValue} is the *type*-level half of this and cannot express
+ * the rest: TypeScript has one `number`, but JSON has no encoding for `NaN` or
+ * `±Infinity`, so `JSON.stringify` rewrites them to `null`.
+ *
+ * That is reachable from ordinary input, not just from a careless caller —
+ * `JSON.parse("1e400")` returns `Infinity` on overflow, so text a user typed
+ * parses successfully, satisfies the type, and then reaches the wire as `null`
+ * while the editor still shows what they wrote. Checking at the boundary is the
+ * only place the distinction exists.
+ */
+export function isSerializableJson(value: unknown): value is StrictJsonValue {
+  if (value === null) return true;
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return true;
+    case "number":
+      // Rejects NaN and ±Infinity; every other number round-trips.
+      return Number.isFinite(value);
+    case "object":
+      return Array.isArray(value)
+        ? value.every(isSerializableJson)
+        : Object.values(value as Record<string, unknown>).every(
+            isSerializableJson,
+          );
+    default:
+      // `undefined`, functions, symbols and bigints are not JSON at all.
+      return false;
+  }
+}
+
 /**
  * Widen a typed object to a generic string-keyed record so its keys can be
  * iterated or read/written generically. Many of the project's config/SDK types

From 56d86440327a7175d6439fa7c2bf3c7e4940c684 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 20:03:37 -0400
Subject: [PATCH 24/35] fix: stop leaking metadata values into diagnostics, and
 salvage per key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two credential leaks, the same class already fixed for the client logger:
`serverList` printed the malformed entry verbatim — a legacy row missing `key`
still holds whatever the user configured — and the CLI overflow error echoed
the whole `key=value` pair into stderr and CI logs. Both now name the key and
the offending *type*; a test plants a `sk-live-…` and asserts it appears
nowhere while the key still does.

`normalizeStoredMetadata` now also drops a value that parses but cannot be
sent. A hand-edited catalog is the reachable source: it is parsed server-side,
so `1e400` really does become `Infinity` there, and the next write would store
`null`. Filtered per key, matching the per-item salvage this file already does
elsewhere, so one bad value does not cost the user the rest.

Deliberately *not* added to the `/api/servers` guard, which review also
suggested. Writing that test is what showed why: a client's own
`JSON.stringify` turns `Infinity` into `null` before the request is sent, so
the wire cannot carry the bad case at all — and the check made things worse,
rejecting the whole metadata field where the normalizer drops one key. The
guard stays a container check, with a comment recording both points.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/cli/__tests__/metadata.test.ts        | 28 ++++++++++
 clients/cli/src/cli.ts                        |  5 +-
 .../web/src/test/core/mcp/serverList.test.ts  | 38 +++++++++++++
 core/mcp/remote/node/server.ts                | 15 ++++--
 core/mcp/serverList.ts                        | 54 ++++++++++++++++---
 5 files changed, 129 insertions(+), 11 deletions(-)

diff --git a/clients/cli/__tests__/metadata.test.ts b/clients/cli/__tests__/metadata.test.ts
index ef8e2b37..55074dd4 100644
--- a/clients/cli/__tests__/metadata.test.ts
+++ b/clients/cli/__tests__/metadata.test.ts
@@ -911,6 +911,34 @@ describe("Metadata Tests", () => {
       }
     });
 
+    it("names the key but never the value when rejecting", async () => {
+      // The pair can carry a credential, and this message reaches stderr and
+      // CI logs.
+      const server = createTestServerHttp({
+        serverInfo: createTestServerInfo(),
+        tools: [createEchoTool()],
+      });
+      try {
+        await server.start();
+        const result = await runCli([
+          server.url,
+          "--cli",
+          "--method",
+          "tools/list",
+          "--metadata",
+          'credentials={"accessToken":"sk-live-nope","n":1e400}',
+          "--transport",
+          "http",
+        ]);
+        const output = `${result.stderr}${result.stdout}`;
+        expect(result.exitCode).not.toBe(0);
+        expect(output).toContain("credentials");
+        expect(output).not.toContain("sk-live");
+      } finally {
+        await server.stop();
+      }
+    });
+
     it("should handle metadata parsing validation", async () => {
       const server = createTestServerHttp({
         serverInfo: createTestServerInfo(),
diff --git a/clients/cli/src/cli.ts b/clients/cli/src/cli.ts
index c486a725..412fc5dc 100644
--- a/clients/cli/src/cli.ts
+++ b/clients/cli/src/cli.ts
@@ -504,8 +504,11 @@ function parseKeyValuePair(
   // and better than falling back to the literal string, which would also not
   // be what was asked for.
   if (!isSerializableJson(parsedValue)) {
+    // Names the key, never the value: the pair can carry a credential
+    // (`credentials={"accessToken":"…","n":1e400}`) and this message lands in
+    // stderr and CI logs.
     throw new Error(
-      `Invalid parameter value: ${value}. Numbers must be finite (a value like 1e400 overflows and cannot be sent).`,
+      `Invalid value for "${key}": numbers must be finite (a literal like 1e400 overflows to Infinity and cannot be sent).`,
     );
   }
 
diff --git a/clients/web/src/test/core/mcp/serverList.test.ts b/clients/web/src/test/core/mcp/serverList.test.ts
index 2ad70e4c..acca524f 100644
--- a/clients/web/src/test/core/mcp/serverList.test.ts
+++ b/clients/web/src/test/core/mcp/serverList.test.ts
@@ -1477,6 +1477,44 @@ describe("normalizeStoredMetadata (#1910)", () => {
     expect(warn).toHaveBeenCalledTimes(1);
   });
 
+  it("drops a value that parses but cannot be sent, keeping its siblings", () => {
+    // A hand-edited catalog reaches this untouched by any editor, so it is a
+    // real source of `1e400` — which parses to Infinity and serializes to null.
+    const out = normalizeStoredMetadata(
+      JSON.parse('{"good":1,"bad":1e400,"alsoGood":{"n":2}}'),
+    );
+    expect(out).toEqual({ good: 1, alsoGood: { n: 2 } });
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("drops a non-serializable value nested inside an object", () => {
+    const out = normalizeStoredMetadata(JSON.parse('{"a":{"deep":[1e400]}}'));
+    expect(out).toEqual({});
+  });
+
+  it("applies the same check to a legacy pair value", () => {
+    const out = normalizeStoredMetadata([
+      { key: "ok", value: 1 },
+      { key: "bad", value: JSON.parse("1e400") },
+    ]);
+    expect(out).toEqual({ ok: 1 });
+  });
+
+  it("never prints the offending value in a warning", () => {
+    // `_meta` can hold credentials, and these warnings go to ordinary console
+    // output — so a diagnostic may name the key and the type, never the value.
+    normalizeStoredMetadata([
+      { value: { accessToken: "sk-live-nope" } },
+      { key: "leaky", value: JSON.parse('{"token":1e400}') },
+    ]);
+    normalizeStoredMetadata("sk-live-also-nope");
+    const printed = JSON.stringify(warn.mock.calls);
+    expect(printed).not.toContain("sk-live");
+    expect(printed).not.toContain("accessToken");
+    // The key is still named, so the warning stays actionable.
+    expect(printed).toContain("leaky");
+  });
+
   it("migrates a legacy file to the object shape on the next write", () => {
     // Read side accepts the pair array; write side emits only the object, so
     // one round-trip is the migration.
diff --git a/core/mcp/remote/node/server.ts b/core/mcp/remote/node/server.ts
index 0b3bffe5..8ceb79ae 100644
--- a/core/mcp/remote/node/server.ts
+++ b/core/mcp/remote/node/server.ts
@@ -1213,9 +1213,18 @@ export function createRemoteApp(
   // credentials are intentionally lost on first read (hard cutover per
   // #1358 decision 4). Users re-enter via the form or hand-edit into the
   // flat shape.
-  // A plain JSON object — the container `_meta` requires. Values are
-  // deliberately unchecked: `_meta` takes arbitrary JSON (#1910), and anything
-  // that survived `JSON.parse` already is.
+  // The *container* `_meta` requires — a plain JSON object.
+  //
+  // Value-level validity is deliberately not checked here. Values are
+  // arbitrary JSON (#1910), and the one class that survives `JSON.parse` yet
+  // cannot be sent — a non-finite number, from a literal like `1e400` in a
+  // hand-edited catalog — is filtered **per key** by
+  // `normalizeStoredMetadata`, which every read routes through. Rejecting the
+  // whole field here instead would cost a user every other key they had
+  // configured, for one bad value.
+  //
+  // Note the wire cannot carry the bad case at all: a client's own
+  // `JSON.stringify` turns `Infinity` into `null` before the request is sent.
   const isJsonObject = (v: unknown): v is RequestMetadata =>
     v !== null && typeof v === "object" && !Array.isArray(v);
   const isStringRecord = (v: unknown): v is Record<string, string> => {
diff --git a/core/mcp/serverList.ts b/core/mcp/serverList.ts
index 405bbca2..b21d736b 100644
--- a/core/mcp/serverList.ts
+++ b/core/mcp/serverList.ts
@@ -30,6 +30,7 @@ import {
 } from "../auth/secret-fields.js";
 import { toRecord } from "../json/jsonUtils.js";
 import type { JsonValue } from "../json/jsonUtils.js";
+import { isSerializableJson } from "../json/jsonUtils.js";
 
 // The full set of valid `type` discriminator values, used to reject anything
 // else read off disk so unknown strings can't propagate to narrowing sites.
@@ -226,9 +227,12 @@ export function normalizeStoredMetadata(
         entry === null ||
         typeof (entry as { key?: unknown }).key !== "string"
       ) {
+        // Structural message only — never the entry. A malformed legacy row
+        // still holds whatever the user put in it, which for `_meta` can be a
+        // credential, and this goes to the console of every client that reads
+        // the catalog.
         console.warn(
-          "Ignoring malformed legacy metadata entry (expected `{ key, value }`):",
-          entry,
+          "Ignoring malformed legacy metadata entry (expected `{ key, value }`).",
         );
         continue;
       }
@@ -236,13 +240,14 @@ export function normalizeStoredMetadata(
       if (key.trim() === "") continue;
       // `??`, not `||`: `null` is a legal `_meta` value and must survive the
       // migration as `null`. Only a genuinely absent `value` becomes `""`.
-      //
+      const resolved = value === undefined ? "" : value;
+      if (!keepSerializable(key, resolved)) continue;
       // `defineProperty` rather than `out[key] = …` because a legacy key of
       // `__proto__` would otherwise hit the prototype setter — silently
       // dropping the entry (or, for an object value, mutating the prototype)
       // instead of storing an own property under that name.
       Object.defineProperty(out, key, {
-        value: value === undefined ? "" : value,
+        value: resolved,
         writable: true,
         enumerable: true,
         configurable: true,
@@ -252,16 +257,51 @@ export function normalizeStoredMetadata(
   }
 
   if (typeof metadata === "object") {
-    return { ...(metadata as RequestMetadata) };
+    // A hand-edited catalog reaches this untouched by any editor, so it is a
+    // real source of values that parse but cannot be sent — `1e400` becomes
+    // `Infinity`, which the next serialization writes as `null`. Same
+    // invariant the web editor and the CLI enforce, applied per key so one bad
+    // value does not cost the rest.
+    const out: RequestMetadata = {};
+    for (const [key, value] of Object.entries(metadata as RequestMetadata)) {
+      if (keepSerializable(key, value)) out[key] = value;
+    }
+    return out;
   }
 
   console.warn(
-    "Ignoring malformed `metadata` (expected a JSON object):",
-    metadata,
+    `Ignoring malformed \`metadata\` (expected a JSON object, got ${describeJsonType(metadata)}).`,
   );
   return {};
 }
 
+/**
+ * Whether a metadata value can be sent as written, warning by key when it
+ * cannot.
+ *
+ * Names the key and the offending type, never the value: `_meta` carries
+ * whatever the user configured, credentials included, and these warnings reach
+ * ordinary console output.
+ */
+function keepSerializable(key: string, value: unknown): boolean {
+  if (isSerializableJson(value)) return true;
+  console.warn(
+    `Ignoring metadata key "${key}" — its value is not JSON that can be sent ` +
+      `(got ${describeJsonType(value)}; note \`1e400\` parses to Infinity).`,
+  );
+  return false;
+}
+
+/** A one-word type name for a diagnostic that must not disclose the value. */
+function describeJsonType(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    return Number.isNaN(value) ? "NaN" : "a non-finite number";
+  }
+  return typeof value;
+}
+
 /**
  * Validate a server's `oauth.authorizationParams` as it comes off disk, or
  * `undefined` when there is nothing usable. (#2018)

From bc433bbf7205a65534955e88d51c43227d1d7a53 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 20:18:38 -0400
Subject: [PATCH 25/35] fix: keep the object branch's `__proto__` handling when
 filtering per key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A regression from the previous commit. The object branch was a spread, which
*defines* properties and is therefore safe; rewriting it into a per-key loop to
filter unserializable values turned it into `out[key] = value`, which *sets* —
so a persisted `"__proto__"` key vanished on reload and, with an object value,
gave the returned metadata a caller-controlled prototype. The legacy branch had
already been fixed for exactly this.

Fixed at the root rather than the site: both branches now go through one
`defineMetadataKey`, so a change to how one stores a key cannot leave the other
behind. That split is what let the earlier fix fail to protect this path.

The test uses `JSON.parse('{"__proto__":…}')`, not an object literal — a
literal `__proto__:` key sets the prototype at construction and creates no own
property, so a test written that way passes against the broken code. Confirmed
by reverting the line: only the parsed case fails.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../web/src/test/core/mcp/serverList.test.ts  | 17 ++++++++
 core/mcp/serverList.ts                        | 41 ++++++++++++++-----
 2 files changed, 47 insertions(+), 11 deletions(-)

diff --git a/clients/web/src/test/core/mcp/serverList.test.ts b/clients/web/src/test/core/mcp/serverList.test.ts
index acca524f..1a0f79cc 100644
--- a/clients/web/src/test/core/mcp/serverList.test.ts
+++ b/clients/web/src/test/core/mcp/serverList.test.ts
@@ -1432,6 +1432,23 @@ describe("normalizeStoredMetadata (#1910)", () => {
     });
   });
 
+  it.each([
+    ["the object form", { __proto__: { polluted: true } } as unknown],
+    [
+      "a hand-edited file's object form",
+      JSON.parse('{"__proto__":{"polluted":true}}'),
+    ],
+    ["the legacy pair form", [{ key: "__proto__", value: { polluted: true } }]],
+  ])("stores a `__proto__` key from %s as an own property", (_label, input) => {
+    // Plain assignment hits the prototype setter: the entry vanishes and, for
+    // an object value, the result gets a caller-controlled prototype. Both
+    // branches must define rather than set — the object branch regressed once
+    // when it changed from a spread to a per-key loop.
+    const out = normalizeStoredMetadata(input);
+    expect(Object.getPrototypeOf(out)).toBe(Object.prototype);
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+  });
+
   it("stores a legacy `__proto__` key as an own property", () => {
     // Plain assignment would hit the prototype setter: the entry would vanish
     // (and an object value would mutate the prototype) instead of being stored.
diff --git a/core/mcp/serverList.ts b/core/mcp/serverList.ts
index b21d736b..e30a3efd 100644
--- a/core/mcp/serverList.ts
+++ b/core/mcp/serverList.ts
@@ -242,16 +242,7 @@ export function normalizeStoredMetadata(
       // migration as `null`. Only a genuinely absent `value` becomes `""`.
       const resolved = value === undefined ? "" : value;
       if (!keepSerializable(key, resolved)) continue;
-      // `defineProperty` rather than `out[key] = …` because a legacy key of
-      // `__proto__` would otherwise hit the prototype setter — silently
-      // dropping the entry (or, for an object value, mutating the prototype)
-      // instead of storing an own property under that name.
-      Object.defineProperty(out, key, {
-        value: resolved,
-        writable: true,
-        enumerable: true,
-        configurable: true,
-      });
+      defineMetadataKey(out, key, resolved);
     }
     return out;
   }
@@ -264,7 +255,7 @@ export function normalizeStoredMetadata(
     // value does not cost the rest.
     const out: RequestMetadata = {};
     for (const [key, value] of Object.entries(metadata as RequestMetadata)) {
-      if (keepSerializable(key, value)) out[key] = value;
+      if (keepSerializable(key, value)) defineMetadataKey(out, key, value);
     }
     return out;
   }
@@ -275,6 +266,34 @@ export function normalizeStoredMetadata(
   return {};
 }
 
+/**
+ * Store a metadata key as an **own** property.
+ *
+ * `out[key] = value` invokes the prototype setter for the key `"__proto__"`,
+ * so the entry vanishes on reload and — for an object value — the returned
+ * metadata is given a caller-controlled prototype. `_meta` keys come from a
+ * file a user (or something that wrote that file) controls, so `"__proto__"`
+ * is a key that can genuinely arrive.
+ *
+ * Both branches of `normalizeStoredMetadata` go through this rather than each
+ * spelling it out. The object branch was originally a spread — safe, because
+ * spread defines rather than sets — and rewriting it into a per-key loop for
+ * value filtering silently reintroduced the hazard the legacy branch had
+ * already fixed. One mechanism is what stops that recurring.
+ */
+function defineMetadataKey(
+  out: RequestMetadata,
+  key: string,
+  value: JsonValue,
+): void {
+  Object.defineProperty(out, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  });
+}
+
 /**
  * Whether a metadata value can be sent as written, warning by key when it
  * cannot.

From 06c7985d5c0a4fc6f9ebaa29726d83aecc1d5752 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 20:27:58 -0400
Subject: [PATCH 26/35] fix(web): read MCP App UI resource metadata from
 _meta.ui

McpUiResourceMeta describes the value of a `_meta` bag's `ui` key, not
`_meta` itself, so casting `content._meta` to it left `csp` and
`permissions` undefined for every spec-conforming app. The generated
sandbox CSP then fell back to `connect-src 'none'` and the app's declared
connectDomains never took effect.

Unwrap `_meta.ui` (with a result-level fallback, which the spec allows)
through a small type-guarded helper, mirroring the tool side of this file
where `getToolUiResourceUri` already reads `_meta.ui.resourceUri`. The
test fixture now builds the real wire shape, and cases cover the
result-level fallback plus the unnested bag being ignored.

Closes #2055

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../createAppBridgeFactory.test.ts            | 73 ++++++++++++++++++-
 .../AppRenderer/createAppBridgeFactory.ts     | 26 ++++++-
 2 files changed, 96 insertions(+), 3 deletions(-)

diff --git a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
index 7f32c26b..60a5ba85 100644
--- a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
+++ b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
@@ -83,16 +83,27 @@ function makeIframe(hasWindow = true): HTMLIFrameElement {
 
 const fakeClient = { name: "sdk-client" } as unknown as Client;
 
+/**
+ * A UI resource read result. `meta` is the MCP Apps sandbox metadata, which the
+ * spec nests under the `_meta` bag's `ui` key — the helper wraps it so every
+ * test drives the real wire shape. `opts.at` places it on the result instead of
+ * the content block, and `opts.flat` writes it to `_meta` unnested (the
+ * non-conforming shape the host must ignore).
+ */
 function uiResource(
   text: string | undefined,
   meta?: Record<string, unknown>,
+  opts: { at?: "content" | "result"; flat?: boolean } = {},
 ): ReadResourceResult {
+  const bag = meta ? { _meta: opts.flat ? meta : { ui: meta } } : {};
+  const onResult = opts.at === "result";
   return {
+    ...(onResult ? bag : {}),
     contents: [
       {
         uri: "ui://weather/app.html",
         ...(text === undefined ? {} : { text }),
-        ...(meta ? { _meta: meta } : {}),
+        ...(onResult ? {} : bag),
       },
     ],
   } as ReadResourceResult;
@@ -230,6 +241,66 @@ describe("createAppBridgeFactory", () => {
     });
   });
 
+  it("falls back to the result-level _meta.ui when the content block carries none", async () => {
+    // The spec allows the sandbox metadata at either level; a server that only
+    // stamps the result must still get its connectDomains honored.
+    const readResource = vi.fn().mockResolvedValue(
+      uiResource(
+        "<h1>x</h1>",
+        {
+          permissions: { camera: {} },
+          csp: { connectDomains: ["https://api.example.com"] },
+        },
+        { at: "result" },
+      ),
+    );
+    const factory = createAppBridgeFactory({
+      getClient: () => fakeClient,
+      readResource,
+    });
+    await factory(makeIframe(), { kind: "tool", tool });
+    const bridge = bridgeInstances[0];
+    bridge.emit("sandboxready");
+    await flush();
+
+    const call = bridge.sendSandboxResourceReady.mock.calls[0][0] as {
+      html: string;
+      permissions: unknown;
+    };
+    expect(call.permissions).toEqual({ camera: {} });
+    expect(call.html).toContain("connect-src https://api.example.com");
+  });
+
+  it("ignores sandbox metadata written unnested on _meta", async () => {
+    // `McpUiResourceMeta` describes the value of `_meta.ui`, not `_meta`. A bag
+    // whose keys sit at the top level is not the spec shape, so it must not be
+    // read as one — reading it there is what produced #2055 in reverse.
+    const readResource = vi
+      .fn()
+      .mockResolvedValue(
+        uiResource(
+          "<h1>x</h1>",
+          { csp: { connectDomains: ["https://api.example.com"] } },
+          { flat: true },
+        ),
+      );
+    const factory = createAppBridgeFactory({
+      getClient: () => fakeClient,
+      readResource,
+    });
+    await factory(makeIframe(), { kind: "tool", tool });
+    const bridge = bridgeInstances[0];
+    bridge.emit("sandboxready");
+    await flush();
+
+    const call = bridge.sendSandboxResourceReady.mock.calls[0][0] as {
+      html: string;
+    };
+    expect(call.html).not.toContain("api.example.com");
+    // The policy is rendered into an HTML attribute, so quotes arrive escaped.
+    expect(call.html).toContain("connect-src &#39;none&#39;");
+  });
+
   it("does not mutate the shared HOST_CAPABILITIES when echoing the approved sandbox", async () => {
     // The factory builds a per-app copy ({ ...HOST_CAPABILITIES }) so the
     // sandbox echo never leaks across apps/renders. Lock that in: after a
diff --git a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
index 1447d359..3f3e7156 100644
--- a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
+++ b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
@@ -100,7 +100,29 @@ export interface AppBridgeFactoryDeps {
   advertiseElicitation?: boolean;
 }
 
-/** First text content block of a UI resource, plus its `_meta` (sandbox hints). */
+/**
+ * The MCP Apps sandbox hints (`csp`, `permissions`, …) nested under a `_meta`
+ * bag's `ui` key. `McpUiResourceMeta` describes the value of `_meta.ui`, NOT
+ * `_meta` itself — reading `_meta` directly leaves every field `undefined`, so
+ * a spec-conforming app's declared `connectDomains` never reach the generated
+ * CSP and it renders under `connect-src 'none'` (#2055). This mirrors the tool
+ * side, where `getToolUiResourceUri` already reads `_meta.ui.resourceUri`.
+ */
+function uiMeta(meta: object | undefined): McpUiResourceMeta | undefined {
+  // `_meta` is typed with an index signature, which has no properties in common
+  // with a `{ ui?: unknown }` parameter — hence the cast rather than a narrower
+  // parameter type. Reading one key off an untyped bag is safe.
+  const ui = (meta as { ui?: unknown } | undefined)?.ui;
+  return ui !== null && typeof ui === "object"
+    ? (ui as McpUiResourceMeta)
+    : undefined;
+}
+
+/**
+ * First text content block of a UI resource, plus its `_meta.ui` sandbox hints.
+ * The spec allows the metadata at either the content-block or the result level,
+ * so fall back to the result's own `_meta.ui` when the block carries none.
+ */
 function extractHtmlAndMeta(result: ReadResourceResult): {
   html: string;
   meta: McpUiResourceMeta | undefined;
@@ -110,7 +132,7 @@ function extractHtmlAndMeta(result: ReadResourceResult): {
     if (typeof text === "string") {
       return {
         html: text,
-        meta: content._meta as McpUiResourceMeta | undefined,
+        meta: uiMeta(content._meta) ?? uiMeta(result._meta),
       };
     }
   }

From 0c989a0c347e64c3be6dde80167fc70d61252277 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 20:42:06 -0400
Subject: [PATCH 27/35] fix(web): use the resources/list entry as the UI
 metadata fallback

The read RESULT's own `_meta` is not a documented carrier for the sandbox
hints. ext-apps documents the `resources/list` entry's `_meta.ui` as the
static default a host reviews at connection time, with a read content
item's own `_meta.ui` taking precedence (McpUiAppResourceConfig). Swap
the fallback accordingly and thread the listing through a new optional
`getListedResourceMeta` dep, wired in App.tsx from the resources list.

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/App.tsx                       |  21 +++-
 .../createAppBridgeFactory.test.ts            | 100 ++++++++++++++----
 .../AppRenderer/createAppBridgeFactory.ts     |  29 ++++-
 3 files changed, 121 insertions(+), 29 deletions(-)

diff --git a/clients/web/src/App.tsx b/clients/web/src/App.tsx
index 729eb4d2..613ad758 100644
--- a/clients/web/src/App.tsx
+++ b/clients/web/src/App.tsx
@@ -25,6 +25,7 @@ import type {
   LoggingMessageNotification,
   Progress,
   ProgressToken,
+  Resource,
   Task,
   Tool,
 } from "@modelcontextprotocol/client";
@@ -784,10 +785,24 @@ function App() {
       });
   }, [configBaseUrl]);
 
+  // The `resources/list` entries, read lazily by the App bridge factories below.
+  // ext-apps treats a listing entry's `_meta.ui` as the static default for its
+  // UI resource (a read content item's own `_meta.ui` wins), so the sandbox CSP
+  // has to be able to see it. A ref rather than a dependency: `resources` is
+  // derived further down this component, and the factories only read it inside
+  // an async sandboxready handler, long after any render that produced it.
+  const listedResourcesRef = useRef<Resource[]>([]);
+  const getListedResourceMeta = useCallback(
+    (uri: string) =>
+      listedResourcesRef.current.find((r) => r.uri === uri)?._meta,
+    [],
+  );
+
   const sandboxBridgeFactory = useMemo(
     () =>
       createAppBridgeFactory({
         getClient: () => inspectorClient?.getAppRendererClient() ?? null,
+        getListedResourceMeta,
         readResource: async (uri) => {
           if (!inspectorClient) throw new Error("No MCP client connected.");
           const invocation = await inspectorClient.readResource(uri);
@@ -807,7 +822,7 @@ function App() {
           });
         },
       }),
-    [inspectorClient],
+    [inspectorClient, getListedResourceMeta],
   );
 
   // App-rendered form elicitations (#1854). The controller is created once and
@@ -861,6 +876,7 @@ function App() {
       createAppBridgeFactory({
         advertiseElicitation: true,
         getClient: () => inspectorClient?.getAppRendererClient() ?? null,
+        getListedResourceMeta,
         readResource: async (uri) => {
           if (!inspectorClient) throw new Error("No MCP client connected.");
           const invocation = await inspectorClient.readResource(uri);
@@ -877,7 +893,7 @@ function App() {
           });
         },
       }),
-    [inspectorClient],
+    [inspectorClient, getListedResourceMeta],
   );
   /**
    * Close the previous client's session and open one for the client being
@@ -1238,6 +1254,7 @@ function App() {
   const tools = toolsPagination.items;
   const prompts = promptsPagination.items;
   const resources = resourcesPagination.items;
+  listedResourcesRef.current = resources;
   const {
     tasks,
     refresh: refreshTasks,
diff --git a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
index 60a5ba85..6b16d680 100644
--- a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
+++ b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
@@ -86,29 +86,30 @@ const fakeClient = { name: "sdk-client" } as unknown as Client;
 /**
  * A UI resource read result. `meta` is the MCP Apps sandbox metadata, which the
  * spec nests under the `_meta` bag's `ui` key — the helper wraps it so every
- * test drives the real wire shape. `opts.at` places it on the result instead of
- * the content block, and `opts.flat` writes it to `_meta` unnested (the
- * non-conforming shape the host must ignore).
+ * test drives the real wire shape. `opts.flat` writes it to `_meta` unnested
+ * instead (the non-conforming shape the host must ignore).
  */
 function uiResource(
   text: string | undefined,
   meta?: Record<string, unknown>,
-  opts: { at?: "content" | "result"; flat?: boolean } = {},
+  opts: { flat?: boolean } = {},
 ): ReadResourceResult {
-  const bag = meta ? { _meta: opts.flat ? meta : { ui: meta } } : {};
-  const onResult = opts.at === "result";
   return {
-    ...(onResult ? bag : {}),
     contents: [
       {
         uri: "ui://weather/app.html",
         ...(text === undefined ? {} : { text }),
-        ...(onResult ? {} : bag),
+        ...(meta ? { _meta: opts.flat ? meta : { ui: meta } } : {}),
       },
     ],
   } as ReadResourceResult;
 }
 
+/** The `_meta` of a `resources/list` entry, as `getListedResourceMeta` returns it. */
+function listedMeta(meta: Record<string, unknown>): { ui: unknown } {
+  return { ui: meta };
+}
+
 async function flush(): Promise<void> {
   await Promise.resolve();
   await Promise.resolve();
@@ -241,22 +242,54 @@ describe("createAppBridgeFactory", () => {
     });
   });
 
-  it("falls back to the result-level _meta.ui when the content block carries none", async () => {
-    // The spec allows the sandbox metadata at either level; a server that only
-    // stamps the result must still get its connectDomains honored.
-    const readResource = vi.fn().mockResolvedValue(
-      uiResource(
-        "<h1>x</h1>",
-        {
-          permissions: { camera: {} },
-          csp: { connectDomains: ["https://api.example.com"] },
-        },
-        { at: "result" },
-      ),
+  it("falls back to the resources/list entry's _meta.ui when the content block carries none", async () => {
+    // ext-apps documents the listing-level `_meta.ui` as the static default for
+    // a UI resource, so an app declaring its CSP only there must still have it
+    // honored.
+    const readResource = vi.fn().mockResolvedValue(uiResource("<h1>x</h1>"));
+    const getListedResourceMeta = vi.fn().mockReturnValue(
+      listedMeta({
+        permissions: { camera: {} },
+        csp: { connectDomains: ["https://api.example.com"] },
+      }),
     );
     const factory = createAppBridgeFactory({
       getClient: () => fakeClient,
       readResource,
+      getListedResourceMeta,
+    });
+    await factory(makeIframe(), { kind: "tool", tool });
+    const bridge = bridgeInstances[0];
+    bridge.emit("sandboxready");
+    await flush();
+
+    expect(getListedResourceMeta).toHaveBeenCalledWith("ui://weather/app.html");
+    const call = bridge.sendSandboxResourceReady.mock.calls[0][0] as {
+      html: string;
+      permissions: unknown;
+    };
+    expect(call.permissions).toEqual({ camera: {} });
+    expect(call.html).toContain("connect-src https://api.example.com");
+  });
+
+  it("prefers the read content item's _meta.ui over the listing entry's", async () => {
+    // The listing value is only a default: a content item that carries its own
+    // `_meta.ui` wins outright, rather than being merged with it.
+    const readResource = vi.fn().mockResolvedValue(
+      uiResource("<h1>x</h1>", {
+        csp: { connectDomains: ["https://read.example.com"] },
+      }),
+    );
+    const getListedResourceMeta = vi.fn().mockReturnValue(
+      listedMeta({
+        permissions: { camera: {} },
+        csp: { connectDomains: ["https://listed.example.com"] },
+      }),
+    );
+    const factory = createAppBridgeFactory({
+      getClient: () => fakeClient,
+      readResource,
+      getListedResourceMeta,
     });
     await factory(makeIframe(), { kind: "tool", tool });
     const bridge = bridgeInstances[0];
@@ -267,8 +300,31 @@ describe("createAppBridgeFactory", () => {
       html: string;
       permissions: unknown;
     };
-    expect(call.permissions).toEqual({ camera: {} });
-    expect(call.html).toContain("connect-src https://api.example.com");
+    expect(call.html).toContain("connect-src https://read.example.com");
+    expect(call.html).not.toContain("listed.example.com");
+    expect(call.permissions).toBeUndefined();
+  });
+
+  it("renders with no sandbox hints when neither the content item nor the listing has _meta.ui", async () => {
+    // A host with no resource listing (or one not covering this URI) is
+    // unaffected: the optional dep is simply absent.
+    const readResource = vi.fn().mockResolvedValue(uiResource("<h1>x</h1>"));
+    const factory = createAppBridgeFactory({
+      getClient: () => fakeClient,
+      readResource,
+      getListedResourceMeta: () => undefined,
+    });
+    await factory(makeIframe(), { kind: "tool", tool });
+    const bridge = bridgeInstances[0];
+    bridge.emit("sandboxready");
+    await flush();
+
+    const call = bridge.sendSandboxResourceReady.mock.calls[0][0] as {
+      html: string;
+      permissions: unknown;
+    };
+    expect(call.permissions).toBeUndefined();
+    expect(call.html).toContain("connect-src &#39;none&#39;");
   });
 
   it("ignores sandbox metadata written unnested on _meta", async () => {
diff --git a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
index 3f3e7156..6363d14e 100644
--- a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
+++ b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
@@ -88,6 +88,15 @@ export interface AppBridgeFactoryDeps {
    * frame; the error is also always console.error'd.
    */
   onResourceError?: (err: Error) => void;
+  /**
+   * The `_meta` of the `resources/list` entry for `uri`, when the host has that
+   * listing. ext-apps treats the listing-level `_meta.ui` as the static default
+   * for a UI resource, so an app that declares its CSP only there must still
+   * get it honored; a read content item's own `_meta.ui` wins over it. Omitted
+   * (or returning undefined) simply means no default — the host that has no
+   * resource listing, or whose listing does not include this URI, is unaffected.
+   */
+  getListedResourceMeta?: (uri: string) => object | undefined;
   /**
    * Advertise `hostCapabilities.elicitation` — "this host can forward a
    * form-mode `elicitation/create` to the app and return its result to the
@@ -120,10 +129,17 @@ function uiMeta(meta: object | undefined): McpUiResourceMeta | undefined {
 
 /**
  * First text content block of a UI resource, plus its `_meta.ui` sandbox hints.
- * The spec allows the metadata at either the content-block or the result level,
- * so fall back to the result's own `_meta.ui` when the block carries none.
+ *
+ * `listedMeta` is the `_meta` of the matching `resources/list` entry, which
+ * ext-apps documents as the static default a host can review at connection
+ * time; a `resources/read` content item carrying its own `_meta.ui` takes
+ * precedence over it (`McpUiAppResourceConfig`). Nothing else is consulted —
+ * in particular the read RESULT's own `_meta` is not a documented carrier.
  */
-function extractHtmlAndMeta(result: ReadResourceResult): {
+function extractHtmlAndMeta(
+  result: ReadResourceResult,
+  listedMeta?: object,
+): {
   html: string;
   meta: McpUiResourceMeta | undefined;
 } {
@@ -132,7 +148,7 @@ function extractHtmlAndMeta(result: ReadResourceResult): {
     if (typeof text === "string") {
       return {
         html: text,
-        meta: uiMeta(content._meta) ?? uiMeta(result._meta),
+        meta: uiMeta(content._meta) ?? uiMeta(listedMeta),
       };
     }
   }
@@ -293,7 +309,10 @@ export function createAppBridgeFactory(
           const uri = resolveSourceUri(source);
           if (!uri) return;
           const result = await deps.readResource(uri);
-          const { html, meta } = extractHtmlAndMeta(result);
+          const { html, meta } = extractHtmlAndMeta(
+            result,
+            deps.getListedResourceMeta?.(uri),
+          );
           // Build the per-app CSP host-side: filter the requested sources to
           // ones the host accepts, render the policy string, and wrap the
           // app's HTML in a fixed shell whose first <head> child is the CSP

From a1c00e51a87d4c0d87b093f3bd96b67c5c276a0b Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 20:55:35 -0400
Subject: [PATCH 28/35] test(web): cover the App-level listed-resource metadata
 wiring
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The bridge-factory tests inject `getListedResourceMeta` directly, so
nothing caught App.tsx ceasing to supply it — the fallback would go
unused with every test still green. Add a pass-through spy over the
factory in App.test.tsx and assert both factories receive a lookup that
resolves a listed resource's `_meta` and misses on an unknown URI.

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/App.test.tsx | 70 ++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/clients/web/src/App.test.tsx b/clients/web/src/App.test.tsx
index 2561c308..a37ec645 100644
--- a/clients/web/src/App.test.tsx
+++ b/clients/web/src/App.test.tsx
@@ -355,6 +355,29 @@ vi.mock("@inspector/core/react/useSettingsDraft.js", () => ({
   })),
 }));
 
+// --- App bridge factory spy (#2055) -----------------------------------------
+// Passes through to the real factory but records the deps App hands it, so a
+// test can drive `getListedResourceMeta` — the wiring that carries a
+// `resources/list` entry's `_meta.ui` into the sandbox CSP. Without this the
+// bridge-factory unit tests would still pass while App stopped supplying it.
+const appBridgeFactoryDeps: AppBridgeFactoryDeps[] = [];
+vi.mock(
+  "./components/elements/AppRenderer/createAppBridgeFactory",
+  async (importOriginal) => {
+    const actual =
+      await importOriginal<
+        typeof import("./components/elements/AppRenderer/createAppBridgeFactory")
+      >();
+    return {
+      ...actual,
+      createAppBridgeFactory: (deps: AppBridgeFactoryDeps) => {
+        appBridgeFactoryDeps.push(deps);
+        return actual.createAppBridgeFactory(deps);
+      },
+    };
+  },
+);
+
 // --- InspectorView double ---------------------------------------------------
 // Surfaces each piece of session-scoped state under test and exposes buttons
 // that invoke the App's connect / call-tool / get-prompt / read-resource /
@@ -590,6 +613,8 @@ import type {
   MessageEntry,
   ServerEntry,
 } from "@inspector/core/mcp/types.js";
+import type { AppBridgeFactoryDeps } from "./components/elements/AppRenderer/createAppBridgeFactory";
+import { useManagedResources } from "@inspector/core/react/useManagedResources.js";
 
 // Default useInspectorClient return — capabilities empty (no task tool calls).
 // Individual tests override via vi.mocked(...).mockReturnValue(...).
@@ -3117,3 +3142,48 @@ describe("App background command rejections (#2049)", () => {
     }
   });
 });
+
+describe("App MCP App listed-resource metadata wiring (#2055)", () => {
+  beforeEach(() => {
+    appBridgeFactoryDeps.length = 0;
+  });
+
+  afterEach(() => {
+    // The hook mock is module-level and shared, so put the empty-list default
+    // back rather than leaving a populated list for whatever runs next.
+    vi.mocked(useManagedResources).mockReturnValue({
+      resources: [],
+      refresh: vi.fn(),
+      clearListChanged: vi.fn(),
+    } as unknown as ReturnType<typeof useManagedResources>);
+  });
+
+  it("hands the bridge factory a getListedResourceMeta reading the resources/list entries", async () => {
+    // ext-apps treats a listing entry's `_meta.ui` as the static default for a
+    // UI resource, so the App has to surface the listing to the bridge — the
+    // factory's own tests inject the dep and cannot see this wiring break.
+    const listedMeta = {
+      ui: { csp: { connectDomains: ["https://api.example.com"] } },
+    };
+    vi.mocked(useManagedResources).mockReturnValue({
+      resources: [
+        { uri: "ui://weather/app.html", name: "app", _meta: listedMeta },
+      ],
+      refresh: vi.fn(),
+      clearListChanged: vi.fn(),
+    } as unknown as ReturnType<typeof useManagedResources>);
+
+    renderWithMantine(<App />);
+    await waitFor(() => expect(appBridgeFactoryDeps.length).toBeGreaterThan(0));
+
+    // Every factory App builds gets the wiring, not just the Apps-tab one.
+    for (const deps of appBridgeFactoryDeps) {
+      expect(deps.getListedResourceMeta?.("ui://weather/app.html")).toEqual(
+        listedMeta,
+      );
+      expect(
+        deps.getListedResourceMeta?.("ui://other/app.html"),
+      ).toBeUndefined();
+    }
+  });
+});

From 9f8dc82a9abee9775ba6dd121ad2a513bd6858b8 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 21:07:25 -0400
Subject: [PATCH 29/35] test(web): drop the double casts from the resources
 hook mock

`as unknown as ReturnType<typeof useManagedResources>` erased the hook's
contract and hid that the mock omitted its required `error` and
`listChanged` fields, which the repo's TypeScript rules disallow. Build
the complete `UseManagedResourcesResult` through a small helper instead,
so a future change to that interface fails the typecheck here.

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/App.test.tsx | 31 ++++++++++++++++++++-----------
 1 file changed, 20 insertions(+), 11 deletions(-)

diff --git a/clients/web/src/App.test.tsx b/clients/web/src/App.test.tsx
index a37ec645..923a5e1f 100644
--- a/clients/web/src/App.test.tsx
+++ b/clients/web/src/App.test.tsx
@@ -615,6 +615,8 @@ import type {
 } from "@inspector/core/mcp/types.js";
 import type { AppBridgeFactoryDeps } from "./components/elements/AppRenderer/createAppBridgeFactory";
 import { useManagedResources } from "@inspector/core/react/useManagedResources.js";
+import type { UseManagedResourcesResult } from "@inspector/core/react/useManagedResources.js";
+import type { Resource } from "@modelcontextprotocol/client";
 
 // Default useInspectorClient return — capabilities empty (no task tool calls).
 // Individual tests override via vi.mocked(...).mockReturnValue(...).
@@ -3143,6 +3145,19 @@ describe("App background command rejections (#2049)", () => {
   });
 });
 
+/** A complete `useManagedResources` return, so the mock stays type-checked against the hook's contract. */
+function managedResourcesResult(
+  resources: Resource[],
+): UseManagedResourcesResult {
+  return {
+    error: null,
+    resources,
+    listChanged: false,
+    refresh: vi.fn().mockResolvedValue(resources),
+    clearListChanged: vi.fn(),
+  };
+}
+
 describe("App MCP App listed-resource metadata wiring (#2055)", () => {
   beforeEach(() => {
     appBridgeFactoryDeps.length = 0;
@@ -3151,11 +3166,7 @@ describe("App MCP App listed-resource metadata wiring (#2055)", () => {
   afterEach(() => {
     // The hook mock is module-level and shared, so put the empty-list default
     // back rather than leaving a populated list for whatever runs next.
-    vi.mocked(useManagedResources).mockReturnValue({
-      resources: [],
-      refresh: vi.fn(),
-      clearListChanged: vi.fn(),
-    } as unknown as ReturnType<typeof useManagedResources>);
+    vi.mocked(useManagedResources).mockReturnValue(managedResourcesResult([]));
   });
 
   it("hands the bridge factory a getListedResourceMeta reading the resources/list entries", async () => {
@@ -3165,13 +3176,11 @@ describe("App MCP App listed-resource metadata wiring (#2055)", () => {
     const listedMeta = {
       ui: { csp: { connectDomains: ["https://api.example.com"] } },
     };
-    vi.mocked(useManagedResources).mockReturnValue({
-      resources: [
+    vi.mocked(useManagedResources).mockReturnValue(
+      managedResourcesResult([
         { uri: "ui://weather/app.html", name: "app", _meta: listedMeta },
-      ],
-      refresh: vi.fn(),
-      clearListChanged: vi.fn(),
-    } as unknown as ReturnType<typeof useManagedResources>);
+      ]),
+    );
 
     renderWithMantine(<App />);
     await waitFor(() => expect(appBridgeFactoryDeps.length).toBeGreaterThan(0));

From 45785a0aa60e99e893de8264c5df01df3db0226b Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 21:22:14 -0400
Subject: [PATCH 30/35] fix(web): screen app-supplied sandbox permissions
 before granting them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The sandbox proxy's buildAllowAttribute() tests each permission key for
truthiness, so an untrusted `_meta.ui.permissions` bag could stand a
non-boolean in for a grant — `{ camera: "false" }`, a plausible way for a
server to mean "off", reads as on. Nothing screened it, because before
the `_meta.ui` fix no permissions reached the proxy at all.

Add approveSandboxPermissions alongside approveCspSources: keep only the
four keys the proxy knows, and only where the value is the spec's empty-
object marker or `true`; drop anything else (warning on a malformed
value, silently on an explicit `false`) and return undefined when nothing
survives. Both the notification and the hostCapabilities echo now carry
the approved set, so the app sees what was granted.

Also document what the listing lookup can and cannot see under
`paginatedLists`.

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/App.tsx                       |  7 ++
 .../AppRenderer/createAppBridgeFactory.ts     | 27 ++++----
 clients/web/src/utils/sandbox-csp.test.ts     | 48 ++++++++++++++
 clients/web/src/utils/sandbox-csp.ts          | 64 ++++++++++++++++++-
 4 files changed, 133 insertions(+), 13 deletions(-)

diff --git a/clients/web/src/App.tsx b/clients/web/src/App.tsx
index 613ad758..59201890 100644
--- a/clients/web/src/App.tsx
+++ b/clients/web/src/App.tsx
@@ -1254,6 +1254,13 @@ function App() {
   const tools = toolsPagination.items;
   const prompts = promptsPagination.items;
   const resources = resourcesPagination.items;
+  // Whatever the resource list currently holds — every page in the default
+  // aggregate mode, only the pages fetched so far under `paginatedLists`. The
+  // listing is a documented *default* that a read content item overrides, and
+  // an app whose entry sits on an unfetched page simply falls back to no hints
+  // (`connect-src 'none'`), exactly as before this wiring existed. Walking the
+  // whole list to close that would issue the very requests the user opted out
+  // of by turning pagination on, so the setting wins.
   listedResourcesRef.current = resources;
   const {
     tasks,
diff --git a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
index 6363d14e..2480458d 100644
--- a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
+++ b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
@@ -17,6 +17,7 @@ import type {
 } from "@modelcontextprotocol/client";
 import {
   approveCspSources,
+  approveSandboxPermissions,
   buildSandboxCspPolicy,
   wrapSandboxedHtml,
 } from "../../../utils/sandbox-csp";
@@ -324,23 +325,25 @@ export function createAppBridgeFactory(
           // sendSandboxResourceReady: the view only sends ui/initialize once it
           // has the HTML, so the bridge reflects this in the initialize result.
           const approvedCsp = approveCspSources(meta?.csp);
-          // NOTE on the CSP-vs-permissions asymmetry: `csp` is injection-filtered
-          // by approveCspSources because its sources are interpolated into the
-          // CSP <meta> content string. `permissions` is NOT filtered here — it is
-          // a structured object (camera/microphone/geolocation/clipboardWrite
-          // booleans), and its only consumer is the sandbox proxy's
-          // buildAllowAttribute(), which maps each known key to a fixed
-          // Permissions-Policy token and ignores anything else. Untrusted values
-          // therefore can't reach the iframe `sandbox`/`allow` attribute as raw
-          // text (that layer, and the allow-same-origin strip, is owned by the
-          // sandbox-hardening work in #1565), so no source-style allowlist applies.
+          // Both halves of the app-supplied sandbox config are screened, for
+          // different reasons. `csp` is injection-filtered by approveCspSources
+          // because its sources are interpolated into the CSP <meta> content
+          // string. `permissions` can't reach the `sandbox`/`allow` attribute as
+          // raw text — the proxy maps each known key to a fixed Permissions-Policy
+          // token — but it tests those keys for TRUTHINESS, so a non-boolean
+          // (`camera: "false"`) would read as a grant; approveSandboxPermissions
+          // reduces the bag to the keys actually requested. The `allow-same-origin`
+          // strip and the rest of that layer stay owned by #1565.
+          const approvedPermissions = approveSandboxPermissions(
+            meta?.permissions,
+          );
           hostCapabilities.sandbox = {
-            permissions: meta?.permissions,
+            permissions: approvedPermissions,
             csp: approvedCsp,
           };
           await bridge.sendSandboxResourceReady({
             html: wrapSandboxedHtml(html, buildSandboxCspPolicy(approvedCsp)),
-            permissions: meta?.permissions,
+            permissions: approvedPermissions,
           });
         } catch (err) {
           const error = err instanceof Error ? err : new Error(String(err));
diff --git a/clients/web/src/utils/sandbox-csp.test.ts b/clients/web/src/utils/sandbox-csp.test.ts
index de7d6352..899ebd08 100644
--- a/clients/web/src/utils/sandbox-csp.test.ts
+++ b/clients/web/src/utils/sandbox-csp.test.ts
@@ -2,10 +2,12 @@ import { describe, expect, it, vi } from "vitest";
 import {
   SAFE_CSP_SOURCE,
   approveCspSources,
+  approveSandboxPermissions,
   buildSandboxCspPolicy,
   escapeHtmlAttr,
   wrapSandboxedHtml,
 } from "./sandbox-csp";
+import type { McpUiResourcePermissions } from "@modelcontextprotocol/ext-apps/app-bridge";
 
 describe("SAFE_CSP_SOURCE", () => {
   it.each([
@@ -81,6 +83,52 @@ describe("approveCspSources", () => {
   });
 });
 
+describe("approveSandboxPermissions", () => {
+  it("keeps the spec's empty-object marker and `true` as shorthand", () => {
+    expect(
+      approveSandboxPermissions({
+        camera: {},
+        microphone: true as unknown as Record<string, never>,
+      }),
+    ).toEqual({ camera: {}, microphone: {} });
+  });
+
+  it("drops a truthy non-marker value the proxy would have honored", () => {
+    // The proxy's buildAllowAttribute() tests each key for truthiness, so the
+    // string "false" — a plausible way for a server to mean "off" — would
+    // otherwise switch the camera on.
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect(
+      approveSandboxPermissions({
+        camera: "false",
+        geolocation: 1,
+        microphone: null,
+      } as unknown as McpUiResourcePermissions),
+    ).toBeUndefined();
+    expect(warn).toHaveBeenCalledTimes(3);
+    warn.mockRestore();
+  });
+
+  it("drops `false` without warning, and ignores unknown keys", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect(
+      approveSandboxPermissions({
+        camera: false,
+        midi: {},
+        clipboardWrite: {},
+      } as unknown as McpUiResourcePermissions),
+    ).toEqual({ clipboardWrite: {} });
+    // `false` is an explicit refusal, not a malformed value.
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("returns undefined for no permissions at all", () => {
+    expect(approveSandboxPermissions(undefined)).toBeUndefined();
+    expect(approveSandboxPermissions({})).toBeUndefined();
+  });
+});
+
 describe("buildSandboxCspPolicy", () => {
   it("emits locked-down defaults for an empty approved csp", () => {
     const policy = buildSandboxCspPolicy({});
diff --git a/clients/web/src/utils/sandbox-csp.ts b/clients/web/src/utils/sandbox-csp.ts
index b3d44004..b3283335 100644
--- a/clients/web/src/utils/sandbox-csp.ts
+++ b/clients/web/src/utils/sandbox-csp.ts
@@ -1,4 +1,7 @@
-import type { McpUiResourceCsp } from "@modelcontextprotocol/ext-apps/app-bridge";
+import type {
+  McpUiResourceCsp,
+  McpUiResourcePermissions,
+} from "@modelcontextprotocol/ext-apps/app-bridge";
 
 /**
  * Allowed shapes for a CSP source-expression supplied by an app's
@@ -75,6 +78,65 @@ export function approveCspSources(
   return approved;
 }
 
+/** The permission-key analog of {@link exhaustiveCspKeys}; same compile-time completeness proof. */
+function exhaustivePermissionKeys<
+  const T extends readonly (keyof McpUiResourcePermissions)[],
+>(
+  keys: T &
+    (keyof McpUiResourcePermissions extends T[number] ? unknown : never),
+): T {
+  return keys;
+}
+
+const PERMISSION_KEYS = exhaustivePermissionKeys([
+  "camera",
+  "microphone",
+  "geolocation",
+  "clipboardWrite",
+]);
+
+/**
+ * Filter an app-supplied {@link McpUiResourcePermissions} down to the keys the
+ * host will forward to the sandbox proxy, keeping only those the app actually
+ * *requested*.
+ *
+ * The proxy's `buildAllowAttribute()` tests each key for **truthiness**, so an
+ * unvalidated bag lets a non-boolean stand in for a grant: `{ camera: "false" }`
+ * — a plausible way for a server to mean "off" — is truthy and would switch the
+ * `allow` attribute on. `_meta` is untrusted input, so the value is screened
+ * here rather than at the point of use. A key counts as requested when it
+ * carries the spec's empty-object marker (`camera: {}`), or `true` as the
+ * obvious shorthand; everything else — `false`, any string, `null`, a number —
+ * is dropped, as is any key outside the four the proxy knows.
+ *
+ * Returns undefined when nothing survives, so the notification and the
+ * `hostCapabilities.sandbox` echo carry no permissions at all rather than an
+ * empty object.
+ */
+export function approveSandboxPermissions(
+  permissions: McpUiResourcePermissions | undefined,
+): McpUiResourcePermissions | undefined {
+  if (!permissions) return undefined;
+  const approved: McpUiResourcePermissions = {};
+  let granted = false;
+  for (const key of PERMISSION_KEYS) {
+    const requested: unknown = permissions[key];
+    if (
+      requested === true ||
+      (typeof requested === "object" && requested !== null)
+    ) {
+      approved[key] = {};
+      granted = true;
+    } else if (requested !== undefined && requested !== false) {
+      console.warn(
+        `[mcp-app sandbox] dropping unrecognized "${key}" permission value:`,
+        requested,
+      );
+    }
+  }
+  return granted ? approved : undefined;
+}
+
 function joinSources(list: string[] | undefined, fallback: string): string {
   return list && list.length > 0 ? list.join(" ") : fallback;
 }

From 286dd86f6b0294b7fafb0c10b347b1efb7380fc6 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 21:36:06 -0400
Subject: [PATCH 31/35] refactor(web): type the permissions approver as the
 boundary it is
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

approveSandboxPermissions screens untrusted `_meta`, so it takes
`unknown` and decides the shape itself rather than claiming its input is
already an McpUiResourcePermissions — which had forced its own tests to
cast malformed fixtures through `as unknown as`.

Also stop honoring `true` as a permission marker. The spec defines every
permission as an object (`camera: {}`), so `true` was an undocumented
shorthand, and honoring it means a server typo turns an iframe permission
on. Only the object marker grants now; arrays are rejected too.

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/utils/sandbox-csp.test.ts | 32 +++++++++----------
 clients/web/src/utils/sandbox-csp.ts      | 38 ++++++++++++++---------
 2 files changed, 39 insertions(+), 31 deletions(-)

diff --git a/clients/web/src/utils/sandbox-csp.test.ts b/clients/web/src/utils/sandbox-csp.test.ts
index 899ebd08..c6d00ebd 100644
--- a/clients/web/src/utils/sandbox-csp.test.ts
+++ b/clients/web/src/utils/sandbox-csp.test.ts
@@ -7,7 +7,6 @@ import {
   escapeHtmlAttr,
   wrapSandboxedHtml,
 } from "./sandbox-csp";
-import type { McpUiResourcePermissions } from "@modelcontextprotocol/ext-apps/app-bridge";
 
 describe("SAFE_CSP_SOURCE", () => {
   it.each([
@@ -84,28 +83,27 @@ describe("approveCspSources", () => {
 });
 
 describe("approveSandboxPermissions", () => {
-  it("keeps the spec's empty-object marker and `true` as shorthand", () => {
+  it("keeps the spec's empty-object marker for each known key", () => {
     expect(
-      approveSandboxPermissions({
-        camera: {},
-        microphone: true as unknown as Record<string, never>,
-      }),
-    ).toEqual({ camera: {}, microphone: {} });
+      approveSandboxPermissions({ camera: {}, clipboardWrite: {} }),
+    ).toEqual({ camera: {}, clipboardWrite: {} });
   });
 
-  it("drops a truthy non-marker value the proxy would have honored", () => {
-    // The proxy's buildAllowAttribute() tests each key for truthiness, so the
-    // string "false" — a plausible way for a server to mean "off" — would
-    // otherwise switch the camera on.
+  it("drops a truthy non-marker the proxy would have honored", () => {
+    // buildAllowAttribute() tests each key for truthiness, so the string
+    // "false" — a plausible way for a server to mean "off" — would otherwise
+    // switch the camera on. `true` is rejected too: it is not a marker the
+    // spec defines, and guessing in the granting direction is the wrong bet.
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
     expect(
       approveSandboxPermissions({
         camera: "false",
+        microphone: true,
         geolocation: 1,
-        microphone: null,
-      } as unknown as McpUiResourcePermissions),
+        clipboardWrite: [],
+      }),
     ).toBeUndefined();
-    expect(warn).toHaveBeenCalledTimes(3);
+    expect(warn).toHaveBeenCalledTimes(4);
     warn.mockRestore();
   });
 
@@ -116,15 +114,17 @@ describe("approveSandboxPermissions", () => {
         camera: false,
         midi: {},
         clipboardWrite: {},
-      } as unknown as McpUiResourcePermissions),
+      }),
     ).toEqual({ clipboardWrite: {} });
     // `false` is an explicit refusal, not a malformed value.
     expect(warn).not.toHaveBeenCalled();
     warn.mockRestore();
   });
 
-  it("returns undefined for no permissions at all", () => {
+  it("returns undefined when there is nothing to grant", () => {
     expect(approveSandboxPermissions(undefined)).toBeUndefined();
+    expect(approveSandboxPermissions(null)).toBeUndefined();
+    expect(approveSandboxPermissions("camera")).toBeUndefined();
     expect(approveSandboxPermissions({})).toBeUndefined();
   });
 });
diff --git a/clients/web/src/utils/sandbox-csp.ts b/clients/web/src/utils/sandbox-csp.ts
index b3283335..c15ac8be 100644
--- a/clients/web/src/utils/sandbox-csp.ts
+++ b/clients/web/src/utils/sandbox-csp.ts
@@ -96,38 +96,46 @@ const PERMISSION_KEYS = exhaustivePermissionKeys([
 ]);
 
 /**
- * Filter an app-supplied {@link McpUiResourcePermissions} down to the keys the
- * host will forward to the sandbox proxy, keeping only those the app actually
- * *requested*.
+ * Filter an app-supplied permissions bag down to the keys the host will forward
+ * to the sandbox proxy, keeping only those the app actually *requested*.
  *
  * The proxy's `buildAllowAttribute()` tests each key for **truthiness**, so an
- * unvalidated bag lets a non-boolean stand in for a grant: `{ camera: "false" }`
+ * unvalidated bag lets a non-marker stand in for a grant: `{ camera: "false" }`
  * — a plausible way for a server to mean "off" — is truthy and would switch the
- * `allow` attribute on. `_meta` is untrusted input, so the value is screened
- * here rather than at the point of use. A key counts as requested when it
- * carries the spec's empty-object marker (`camera: {}`), or `true` as the
- * obvious shorthand; everything else — `false`, any string, `null`, a number —
- * is dropped, as is any key outside the four the proxy knows.
+ * `allow` attribute on. `_meta` is untrusted input of no declared type, hence
+ * the `unknown` parameter: this is the boundary that decides what the shape is,
+ * not a consumer of an already-validated one.
+ *
+ * A key counts as requested only when it carries the spec's empty-object marker
+ * (`camera: {}` — {@link McpUiResourcePermissions} defines every permission that
+ * way). Everything else fails closed: `true`, `false`, any string, `null`, a
+ * number, an array, and any key outside the four the proxy knows. `true` in
+ * particular looks like a harmless shorthand, but honoring an undocumented one
+ * means a server typo turns an iframe permission ON, which is the wrong
+ * direction to guess in.
  *
  * Returns undefined when nothing survives, so the notification and the
  * `hostCapabilities.sandbox` echo carry no permissions at all rather than an
  * empty object.
  */
 export function approveSandboxPermissions(
-  permissions: McpUiResourcePermissions | undefined,
+  permissions: unknown,
 ): McpUiResourcePermissions | undefined {
-  if (!permissions) return undefined;
+  if (typeof permissions !== "object" || permissions === null) return undefined;
+  const bag: Record<string, unknown> = { ...permissions };
   const approved: McpUiResourcePermissions = {};
   let granted = false;
   for (const key of PERMISSION_KEYS) {
-    const requested: unknown = permissions[key];
+    const requested = bag[key];
+    if (requested === undefined || requested === false) continue;
     if (
-      requested === true ||
-      (typeof requested === "object" && requested !== null)
+      typeof requested === "object" &&
+      requested !== null &&
+      !Array.isArray(requested)
     ) {
       approved[key] = {};
       granted = true;
-    } else if (requested !== undefined && requested !== false) {
+    } else {
       console.warn(
         `[mcp-app sandbox] dropping unrecognized "${key}" permission value:`,
         requested,

From e2a88d49dde99f2f66774ad923fa378f3ae75e3c Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 21:50:36 -0400
Subject: [PATCH 32/35] fix(web): restore the read result envelope as a
 metadata carrier
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`McpUiReadResourceResult` — the return type of a registerAppResource read
callback — types `_meta.ui` at the result level, so the envelope is a
supported carrier after all and dropping it lost the hints for servers
using that shape. Consult all three, most-specific first: content item,
result envelope, listing entry; first found wins outright.

Also make the App wiring test wait for BOTH factories by their
advertiseElicitation flag. Waiting on a count passed as soon as either
was built, so stripping the wiring from one call site left the other's
deps in the array and the assertion loop still passed.

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/App.test.tsx                  | 21 ++++--
 .../createAppBridgeFactory.test.ts            | 73 ++++++++++++++++++-
 .../AppRenderer/createAppBridgeFactory.ts     | 20 +++--
 3 files changed, 99 insertions(+), 15 deletions(-)

diff --git a/clients/web/src/App.test.tsx b/clients/web/src/App.test.tsx
index 923a5e1f..86a505f2 100644
--- a/clients/web/src/App.test.tsx
+++ b/clients/web/src/App.test.tsx
@@ -3183,15 +3183,26 @@ describe("App MCP App listed-resource metadata wiring (#2055)", () => {
     );
 
     renderWithMantine(<App />);
-    await waitFor(() => expect(appBridgeFactoryDeps.length).toBeGreaterThan(0));
 
-    // Every factory App builds gets the wiring, not just the Apps-tab one.
-    for (const deps of appBridgeFactoryDeps) {
-      expect(deps.getListedResourceMeta?.("ui://weather/app.html")).toEqual(
+    // App builds two factories, differing only in `advertiseElicitation`. Wait
+    // for BOTH by that flag rather than for a count: waiting on "at least one"
+    // would still pass with the wiring stripped from either call site, since
+    // the other's deps sit in the same array.
+    const appsFactory = () =>
+      appBridgeFactoryDeps.find((d) => !d.advertiseElicitation);
+    const elicitationFactory = () =>
+      appBridgeFactoryDeps.find((d) => d.advertiseElicitation === true);
+    await waitFor(() => {
+      expect(appsFactory()).toBeDefined();
+      expect(elicitationFactory()).toBeDefined();
+    });
+
+    for (const deps of [appsFactory(), elicitationFactory()]) {
+      expect(deps?.getListedResourceMeta?.("ui://weather/app.html")).toEqual(
         listedMeta,
       );
       expect(
-        deps.getListedResourceMeta?.("ui://other/app.html"),
+        deps?.getListedResourceMeta?.("ui://other/app.html"),
       ).toBeUndefined();
     }
   });
diff --git a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
index 6b16d680..35eeb1cb 100644
--- a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
+++ b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
@@ -86,20 +86,24 @@ const fakeClient = { name: "sdk-client" } as unknown as Client;
 /**
  * A UI resource read result. `meta` is the MCP Apps sandbox metadata, which the
  * spec nests under the `_meta` bag's `ui` key — the helper wraps it so every
- * test drives the real wire shape. `opts.flat` writes it to `_meta` unnested
- * instead (the non-conforming shape the host must ignore).
+ * test drives the real wire shape. `opts.at` places the bag on the result
+ * envelope (`McpUiReadResourceResult`) instead of the content item, and
+ * `opts.flat` writes it unnested (the non-conforming shape the host ignores).
  */
 function uiResource(
   text: string | undefined,
   meta?: Record<string, unknown>,
-  opts: { flat?: boolean } = {},
+  opts: { at?: "content" | "result"; flat?: boolean } = {},
 ): ReadResourceResult {
+  const bag = meta ? { _meta: opts.flat ? meta : { ui: meta } } : {};
+  const onResult = opts.at === "result";
   return {
+    ...(onResult ? bag : {}),
     contents: [
       {
         uri: "ui://weather/app.html",
         ...(text === undefined ? {} : { text }),
-        ...(meta ? { _meta: opts.flat ? meta : { ui: meta } } : {}),
+        ...(onResult ? {} : bag),
       },
     ],
   } as ReadResourceResult;
@@ -242,6 +246,67 @@ describe("createAppBridgeFactory", () => {
     });
   });
 
+  it("falls back to the read result's _meta.ui when the content item carries none", async () => {
+    // `McpUiReadResourceResult` — what a registerAppResource callback returns —
+    // types `_meta.ui` at the envelope level, so a server stamping it there
+    // must have it honored.
+    const readResource = vi.fn().mockResolvedValue(
+      uiResource(
+        "<h1>x</h1>",
+        {
+          permissions: { microphone: {} },
+          csp: { connectDomains: ["https://envelope.example.com"] },
+        },
+        { at: "result" },
+      ),
+    );
+    const factory = createAppBridgeFactory({
+      getClient: () => fakeClient,
+      readResource,
+    });
+    await factory(makeIframe(), { kind: "tool", tool });
+    const bridge = bridgeInstances[0];
+    bridge.emit("sandboxready");
+    await flush();
+
+    const call = bridge.sendSandboxResourceReady.mock.calls[0][0] as {
+      html: string;
+      permissions: unknown;
+    };
+    expect(call.permissions).toEqual({ microphone: {} });
+    expect(call.html).toContain("connect-src https://envelope.example.com");
+  });
+
+  it("prefers the read result's _meta.ui over the listing entry's", async () => {
+    // Precedence runs most-specific first: content item, then the result
+    // envelope, then the listing default.
+    const readResource = vi
+      .fn()
+      .mockResolvedValue(
+        uiResource(
+          "<h1>x</h1>",
+          { csp: { connectDomains: ["https://envelope.example.com"] } },
+          { at: "result" },
+        ),
+      );
+    const factory = createAppBridgeFactory({
+      getClient: () => fakeClient,
+      readResource,
+      getListedResourceMeta: () =>
+        listedMeta({ csp: { connectDomains: ["https://listed.example.com"] } }),
+    });
+    await factory(makeIframe(), { kind: "tool", tool });
+    const bridge = bridgeInstances[0];
+    bridge.emit("sandboxready");
+    await flush();
+
+    const call = bridge.sendSandboxResourceReady.mock.calls[0][0] as {
+      html: string;
+    };
+    expect(call.html).toContain("connect-src https://envelope.example.com");
+    expect(call.html).not.toContain("listed.example.com");
+  });
+
   it("falls back to the resources/list entry's _meta.ui when the content block carries none", async () => {
     // ext-apps documents the listing-level `_meta.ui` as the static default for
     // a UI resource, so an app declaring its CSP only there must still have it
diff --git a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
index 2480458d..e088fee9 100644
--- a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
+++ b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
@@ -131,11 +131,18 @@ function uiMeta(meta: object | undefined): McpUiResourceMeta | undefined {
 /**
  * First text content block of a UI resource, plus its `_meta.ui` sandbox hints.
  *
- * `listedMeta` is the `_meta` of the matching `resources/list` entry, which
- * ext-apps documents as the static default a host can review at connection
- * time; a `resources/read` content item carrying its own `_meta.ui` takes
- * precedence over it (`McpUiAppResourceConfig`). Nothing else is consulted —
- * in particular the read RESULT's own `_meta` is not a documented carrier.
+ * ext-apps exposes three carriers, and they are consulted most-specific first:
+ *
+ * 1. the **read content item**'s own `_meta.ui`;
+ * 2. the **read result envelope**'s — `McpUiReadResourceResult` (what a
+ *    `registerAppResource` callback returns) types `_meta.ui` at that level;
+ * 3. the matching **`resources/list` entry**'s, which `McpUiAppResourceConfig`
+ *    documents as the static default a host reviews at connection time, and
+ *    which a read content item explicitly takes precedence over.
+ *
+ * Whichever is found first wins outright — the levels are not merged, since a
+ * server that restates only `csp` at the more specific level means that to be
+ * the whole grant, not a patch over the broader one.
  */
 function extractHtmlAndMeta(
   result: ReadResourceResult,
@@ -149,7 +156,8 @@ function extractHtmlAndMeta(
     if (typeof text === "string") {
       return {
         html: text,
-        meta: uiMeta(content._meta) ?? uiMeta(listedMeta),
+        meta:
+          uiMeta(content._meta) ?? uiMeta(result._meta) ?? uiMeta(listedMeta),
       };
     }
   }

From 53943c2ef8d9dad195e5fe7e053a1f00fdee0556 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 22:05:23 -0400
Subject: [PATCH 33/35] fix(web): let a malformed _meta.ui stop the carrier
 lookup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

uiMeta returned undefined for both "this bag declares no ui" and "its ui
is unusable", so a content item declaring `ui: null` fell through and was
granted whatever a BROADER carrier asked for — wrong precedence, wrong
direction to fail in. It now distinguishes the two: no `ui` key means
keep looking, a declared-but-malformed one decides for "no hints".

Also pin the full three-way precedence with a case carrying all three
carriers at once (no prior case would have caught the first two operands
being swapped), and state why a permission's object value need not be
empty: `{}` is the spec's extension point, so rejecting a populated one
would drop grants from servers written against a newer spec.

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../createAppBridgeFactory.test.ts            | 61 +++++++++++++++++++
 .../AppRenderer/createAppBridgeFactory.ts     | 54 +++++++++-------
 clients/web/src/utils/sandbox-csp.test.ts     |  9 +++
 clients/web/src/utils/sandbox-csp.ts          | 22 ++++---
 4 files changed, 117 insertions(+), 29 deletions(-)

diff --git a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
index 35eeb1cb..1e97877d 100644
--- a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
+++ b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
@@ -392,6 +392,67 @@ describe("createAppBridgeFactory", () => {
     expect(call.html).toContain("connect-src &#39;none&#39;");
   });
 
+  it("prefers the content item's _meta.ui over both broader carriers", async () => {
+    // Pins the full three-way order — content item > result envelope > listing
+    // — which no single-fallback case can: swapping the first two operands
+    // would still satisfy them.
+    const result = uiResource("<h1>x</h1>", {
+      csp: { connectDomains: ["https://content.example.com"] },
+    });
+    (result as { _meta?: unknown })._meta = {
+      ui: { csp: { connectDomains: ["https://envelope.example.com"] } },
+    };
+    const factory = createAppBridgeFactory({
+      getClient: () => fakeClient,
+      readResource: vi.fn().mockResolvedValue(result),
+      getListedResourceMeta: () =>
+        listedMeta({ csp: { connectDomains: ["https://listed.example.com"] } }),
+    });
+    await factory(makeIframe(), { kind: "tool", tool });
+    const bridge = bridgeInstances[0];
+    bridge.emit("sandboxready");
+    await flush();
+
+    const call = bridge.sendSandboxResourceReady.mock.calls[0][0] as {
+      html: string;
+    };
+    expect(call.html).toContain("connect-src https://content.example.com");
+    expect(call.html).not.toContain("envelope.example.com");
+    expect(call.html).not.toContain("listed.example.com");
+  });
+
+  it("stops at a carrier whose _meta.ui is malformed rather than falling through", async () => {
+    // A declared-but-unusable `ui` is that carrier's answer. Falling through
+    // would grant whatever a BROADER carrier asked for — wrong precedence, and
+    // the wrong direction to fail in.
+    const readResource = vi
+      .fn()
+      .mockResolvedValue(
+        uiResource("<h1>x</h1>", { ui: null }, { flat: true }),
+      );
+    const factory = createAppBridgeFactory({
+      getClient: () => fakeClient,
+      readResource,
+      getListedResourceMeta: () =>
+        listedMeta({
+          permissions: { camera: {} },
+          csp: { connectDomains: ["https://listed.example.com"] },
+        }),
+    });
+    await factory(makeIframe(), { kind: "tool", tool });
+    const bridge = bridgeInstances[0];
+    bridge.emit("sandboxready");
+    await flush();
+
+    const call = bridge.sendSandboxResourceReady.mock.calls[0][0] as {
+      html: string;
+      permissions: unknown;
+    };
+    expect(call.permissions).toBeUndefined();
+    expect(call.html).not.toContain("listed.example.com");
+    expect(call.html).toContain("connect-src &#39;none&#39;");
+  });
+
   it("ignores sandbox metadata written unnested on _meta", async () => {
     // `McpUiResourceMeta` describes the value of `_meta.ui`, not `_meta`. A bag
     // whose keys sit at the top level is not the spec shape, so it must not be
diff --git a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
index e088fee9..e5d3215d 100644
--- a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
+++ b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
@@ -111,21 +111,31 @@ export interface AppBridgeFactoryDeps {
 }
 
 /**
- * The MCP Apps sandbox hints (`csp`, `permissions`, …) nested under a `_meta`
- * bag's `ui` key. `McpUiResourceMeta` describes the value of `_meta.ui`, NOT
- * `_meta` itself — reading `_meta` directly leaves every field `undefined`, so
- * a spec-conforming app's declared `connectDomains` never reach the generated
- * CSP and it renders under `connect-src 'none'` (#2055). This mirrors the tool
- * side, where `getToolUiResourceUri` already reads `_meta.ui.resourceUri`.
+ * The MCP Apps sandbox hints (`csp`, `permissions`, …) a single `_meta` bag
+ * declares under its `ui` key, or undefined when that bag declares none.
+ *
+ * The two "no hints" cases are deliberately distinguished by the return type:
+ * a bag with no `ui` key at all returns undefined (this carrier is silent —
+ * keep looking), while a bag whose `ui` is malformed returns `{ meta:
+ * undefined }` (this carrier spoke, and what it said is unusable — stop). Were
+ * they conflated, a content item declaring `ui: null` would fall through to a
+ * broader carrier and be granted whatever *that* one asked for, which is both
+ * the wrong precedence and the wrong direction to fail in.
+ *
+ * `McpUiResourceMeta` describes the value of `_meta.ui`, NOT `_meta` itself —
+ * reading `_meta` directly leaves every field undefined, so a spec-conforming
+ * app's declared `connectDomains` never reach the generated CSP and it renders
+ * under `connect-src 'none'` (#2055). This mirrors the tool side, where
+ * `getToolUiResourceUri` already reads `_meta.ui.resourceUri`.
  */
-function uiMeta(meta: object | undefined): McpUiResourceMeta | undefined {
-  // `_meta` is typed with an index signature, which has no properties in common
-  // with a `{ ui?: unknown }` parameter — hence the cast rather than a narrower
-  // parameter type. Reading one key off an untyped bag is safe.
-  const ui = (meta as { ui?: unknown } | undefined)?.ui;
-  return ui !== null && typeof ui === "object"
-    ? (ui as McpUiResourceMeta)
-    : undefined;
+function uiMeta(
+  bag: object | undefined,
+): { meta: McpUiResourceMeta | undefined } | undefined {
+  if (bag === undefined || !("ui" in bag)) return undefined;
+  const ui: unknown = (bag as { ui: unknown }).ui;
+  const wellFormed =
+    ui !== null && typeof ui === "object" && !Array.isArray(ui);
+  return { meta: wellFormed ? (ui as McpUiResourceMeta) : undefined };
 }
 
 /**
@@ -140,9 +150,11 @@ function uiMeta(meta: object | undefined): McpUiResourceMeta | undefined {
  *    documents as the static default a host reviews at connection time, and
  *    which a read content item explicitly takes precedence over.
  *
- * Whichever is found first wins outright — the levels are not merged, since a
- * server that restates only `csp` at the more specific level means that to be
- * the whole grant, not a patch over the broader one.
+ * The first carrier that *declares* a `ui` key decides, and its value is used
+ * outright — the levels are not merged, since a server that restates only
+ * `csp` at the more specific level means that to be the whole grant, not a
+ * patch over the broader one. A carrier declaring a malformed `ui` decides
+ * too, for "no hints"; see {@link uiMeta}.
  */
 function extractHtmlAndMeta(
   result: ReadResourceResult,
@@ -154,11 +166,9 @@ function extractHtmlAndMeta(
   for (const content of result.contents) {
     const text = (content as { text?: unknown }).text;
     if (typeof text === "string") {
-      return {
-        html: text,
-        meta:
-          uiMeta(content._meta) ?? uiMeta(result._meta) ?? uiMeta(listedMeta),
-      };
+      const carried =
+        uiMeta(content._meta) ?? uiMeta(result._meta) ?? uiMeta(listedMeta);
+      return { html: text, meta: carried?.meta };
     }
   }
   throw new Error("UI resource has no text (HTML) content");
diff --git a/clients/web/src/utils/sandbox-csp.test.ts b/clients/web/src/utils/sandbox-csp.test.ts
index c6d00ebd..95b2de94 100644
--- a/clients/web/src/utils/sandbox-csp.test.ts
+++ b/clients/web/src/utils/sandbox-csp.test.ts
@@ -107,6 +107,15 @@ describe("approveSandboxPermissions", () => {
     warn.mockRestore();
   });
 
+  it("accepts a non-empty object, since `{}` is the spec's extension point", () => {
+    // The key's presence is the request; a field the host doesn't know can't
+    // narrow it, and rejecting it would drop grants from servers written
+    // against a newer spec. The value is normalized to `{}` on the way out.
+    expect(approveSandboxPermissions({ camera: { enabled: false } })).toEqual({
+      camera: {},
+    });
+  });
+
   it("drops `false` without warning, and ignores unknown keys", () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
     expect(
diff --git a/clients/web/src/utils/sandbox-csp.ts b/clients/web/src/utils/sandbox-csp.ts
index c15ac8be..83c38845 100644
--- a/clients/web/src/utils/sandbox-csp.ts
+++ b/clients/web/src/utils/sandbox-csp.ts
@@ -106,13 +106,21 @@ const PERMISSION_KEYS = exhaustivePermissionKeys([
  * the `unknown` parameter: this is the boundary that decides what the shape is,
  * not a consumer of an already-validated one.
  *
- * A key counts as requested only when it carries the spec's empty-object marker
- * (`camera: {}` — {@link McpUiResourcePermissions} defines every permission that
- * way). Everything else fails closed: `true`, `false`, any string, `null`, a
- * number, an array, and any key outside the four the proxy knows. `true` in
- * particular looks like a harmless shorthand, but honoring an undocumented one
- * means a server typo turns an iframe permission ON, which is the wrong
- * direction to guess in.
+ * A key counts as requested only when its value is an **object** — the marker
+ * {@link McpUiResourcePermissions} defines for every permission is `{}`, and
+ * presence of that object is the request. Everything else fails closed:
+ * `true`, `false`, any string, `null`, a number, an array, and any key outside
+ * the four the proxy knows. `true` in particular looks like a harmless
+ * shorthand, but honoring an undocumented one means a server typo turns an
+ * iframe permission ON, which is the wrong direction to guess in.
+ *
+ * The object is not required to be *empty*. `{}` is a type with no fields yet,
+ * not a promise there will never be any — it is precisely the spec's extension
+ * point, so rejecting `{ camera: { … } }` would fail closed the day a
+ * permission gains an option, silently dropping grants from servers written
+ * against the newer spec. The value is normalized to `{}` on the way out
+ * either way, so an unrecognized field can't reach the proxy; what it cannot
+ * do is *narrow* a grant the key's presence already asked for.
  *
  * Returns undefined when nothing survives, so the notification and the
  * `hostCapabilities.sandbox` echo carry no permissions at all rather than an

From acf9ff94af1828c63f61c2dc383e62a6794e5532 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 22:20:17 -0400
Subject: [PATCH 34/35] docs(web): state that the listing lookup is best-effort

It does not distinguish "no entry for this URI" from "the list has not
arrived yet"; both yield no hints, which is what a host with no listing
carrier gets anyway. Say so at the lookup, with why blocking on list
readiness is worse: for a server advertising no `resources` capability,
or one whose list errored, that request never resolves, so the app would
never render at all.

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/App.tsx | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/clients/web/src/App.tsx b/clients/web/src/App.tsx
index 59201890..4690a650 100644
--- a/clients/web/src/App.tsx
+++ b/clients/web/src/App.tsx
@@ -792,6 +792,13 @@ function App() {
   // derived further down this component, and the factories only read it inside
   // an async sandboxready handler, long after any render that produced it.
   const listedResourcesRef = useRef<Resource[]>([]);
+  // Best-effort by construction: this reads the list as it stands when the app
+  // opens, and does not distinguish "no entry for this URI" from "the list
+  // hasn't arrived yet". Both yield no hints, which is the same outcome as
+  // having no listing carrier at all. Blocking the render on list readiness
+  // instead would mean waiting on a request that, for a server advertising no
+  // `resources` capability or whose list errored, never resolves — trading a
+  // missing default for an app that never renders.
   const getListedResourceMeta = useCallback(
     (uri: string) =>
       listedResourcesRef.current.find((r) => r.uri === uri)?._meta,

From ab92bab5aa5d8c3dec9063ca6142fde8dcb93fa2 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 23:10:12 -0400
Subject: [PATCH 35/35] fix(test): repair the v2/main typecheck break from a
 semantic conflict
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#2094 retyped `RequestMetadata` as `Record<string, StrictJsonValue>` and
#2087, merged minutes later, added a `updateServerSettings` case passing
`metadata: []`. Neither touched the other's lines, so both merged clean
and `tsc -b` has failed on v2/main ever since (TS2322: 'never[]' is not
assignable to 'RequestMetadata').

One occurrence repo-wide; `[]` → `{}`. Carried here rather than on its
own branch because this PR merged v2/main and inherited the break, so its
CI cannot pass without it.

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/test/core/react/useServers.test.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/clients/web/src/test/core/react/useServers.test.tsx b/clients/web/src/test/core/react/useServers.test.tsx
index 4b6b02f9..aa105284 100644
--- a/clients/web/src/test/core/react/useServers.test.tsx
+++ b/clients/web/src/test/core/react/useServers.test.tsx
@@ -1307,7 +1307,7 @@ describe("useServers", () => {
         result.current.updateServerSettings(existing, {
           headers: [],
           env: [],
-          metadata: [],
+          metadata: {},
           roots: [],
           connectionTimeout: 5000,
           requestTimeout: 30000,