From 391605cf78366e1fc9c81cfc3163225ca2051109 Mon Sep 17 00:00:00 2001
From: Kieran Zhang <oldmeatovo@gmail.com>
Date: Thu, 1 Oct 2026 01:50:56 +0800
Subject: [PATCH 1/3] feat(settings): add an MCP section for global MCP servers

Lists servers from the global mcp.json instantly, probes their state separately, and supports sign-in/out, enable/disable, exposure, add and remove. Changes apply to new sessions.
---
 apps/desktop/src/dev/mock/scenarios.ts        |   8 +
 apps/desktop/src/pages/settings-mcp.test.tsx  | 353 +++++++++
 apps/desktop/src/pages/settings-mcp.tsx       | 730 ++++++++++++++++++
 apps/desktop/src/pages/settings.tsx           |   8 +
 apps/desktop/src/shared/runtime.ts            | 197 ++++-
 .../desktop/src/shared/settings-navigation.ts |   3 +-
 6 files changed, 1297 insertions(+), 2 deletions(-)
 create mode 100644 apps/desktop/src/pages/settings-mcp.test.tsx
 create mode 100644 apps/desktop/src/pages/settings-mcp.tsx

diff --git a/apps/desktop/src/dev/mock/scenarios.ts b/apps/desktop/src/dev/mock/scenarios.ts
index 91cc7e55..6136a103 100644
--- a/apps/desktop/src/dev/mock/scenarios.ts
+++ b/apps/desktop/src/dev/mock/scenarios.ts
@@ -518,6 +518,14 @@ export function createMockApi(): PaceRendererApi {
         case "search_workspace_files":
         case "list_provider_auth_status":
         case "test_provider_connection":
+        case "get_mcp_config":
+        case "probe_mcp_servers":
+        case "set_mcp_server_enabled":
+        case "set_mcp_server_exposure":
+        case "login_mcp_server":
+        case "logout_mcp_server":
+        case "add_mcp_server":
+        case "remove_mcp_server":
         case "update:status":
         case "get_chat_workspace_root":
         case "get_runtime_info":
diff --git a/apps/desktop/src/pages/settings-mcp.test.tsx b/apps/desktop/src/pages/settings-mcp.test.tsx
new file mode 100644
index 00000000..23a05932
--- /dev/null
+++ b/apps/desktop/src/pages/settings-mcp.test.tsx
@@ -0,0 +1,353 @@
+import { act, render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { McpSettingsSection } from "@/pages/settings-mcp";
+import type { PaceRendererApi } from "@/shared/runtime";
+import type {
+  McpActionResult,
+  McpConfigReport,
+  McpProbeReport,
+} from "@pace/core";
+
+const mcpConfig: McpConfigReport = {
+  configPath: "/agent/mcp.json",
+  errors: [],
+  servers: [
+    {
+      name: "filesystem",
+      source: "/agent/mcp.json",
+      enabled: true,
+      exposure: "codemode",
+      kind: "stdio",
+      transport: "npx -y @modelcontextprotocol/server-filesystem .",
+      usesOAuth: false,
+    },
+    {
+      name: "sentry",
+      source: "/agent/mcp.json",
+      enabled: true,
+      exposure: "codemode",
+      kind: "http",
+      transport: "https://mcp.sentry.dev/mcp",
+      usesOAuth: true,
+    },
+    {
+      name: "legacy-db",
+      source: "/agent/mcp.json",
+      enabled: true,
+      exposure: "direct",
+      kind: "stdio",
+      transport: "node db-server.js",
+      usesOAuth: false,
+    },
+    {
+      name: "playwright",
+      source: "/agent/mcp.json",
+      enabled: false,
+      exposure: "codemode",
+      kind: "stdio",
+      transport: "npx -y @playwright/mcp",
+      usesOAuth: false,
+    },
+  ],
+};
+
+const mcpProbe: McpProbeReport = {
+  errors: [],
+  servers: [
+    {
+      name: "filesystem",
+      state: "connected",
+      tools: ["read_file", "write_file", "list_directory"],
+    },
+    { name: "sentry", state: "needs-auth", tools: [] },
+    {
+      name: "legacy-db",
+      state: "failed",
+      tools: [],
+      error: 'MCP server "legacy-db" failed to connect: spawn node ENOENT',
+    },
+    { name: "playwright", state: "disabled", tools: [] },
+  ],
+};
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+type McpRenderOptions = {
+  config?: McpConfigReport;
+  probe?: McpProbeReport;
+  /** When set, probe_mcp_servers returns this promise instead of resolving. */
+  probePromise?: Promise<McpProbeReport>;
+  handlers?: Record<string, (args?: Record<string, unknown>) => unknown>;
+};
+
+function renderMcpSection(options: McpRenderOptions = {}) {
+  const invoke = vi.fn(async (command: string, args?: Record<string, unknown>) => {
+    if (command === "get_mcp_config") {
+      return options.config ?? mcpConfig;
+    }
+
+    const handler = options.handlers?.[command];
+    if (handler) {
+      return handler(args);
+    }
+
+    if (command === "probe_mcp_servers") {
+      return options.probePromise ?? options.probe ?? mcpProbe;
+    }
+
+    throw new Error(`unexpected backend command ${command}`);
+  });
+
+  window.pace = {
+    invoke: invoke as unknown as PaceRendererApi["invoke"],
+    onBackendEvent: vi.fn(() => vi.fn()),
+    onBrowserEvent: vi.fn(() => vi.fn()),
+    onUpdateEvent: vi.fn(() => vi.fn()),
+    onWindowFocusChanged: vi.fn(() => vi.fn()),
+    onNavigateRequest: vi.fn(() => vi.fn()),
+  };
+
+  const queryClient = new QueryClient();
+  const tree = render(
+    <QueryClientProvider client={queryClient}>
+      <McpSettingsSection enabled />
+    </QueryClientProvider>,
+  );
+
+  return {
+    ...tree,
+    invoke,
+    countCalls: (command: string) =>
+      invoke.mock.calls.filter(([called]) => called === command).length,
+  };
+}
+
+async function findMcpSection() {
+  return screen.findByRole("region", { name: "MCP" });
+}
+
+afterEach(() => {
+  delete window.pace;
+});
+
+describe("Settings — MCP servers", () => {
+  it("renders configured rows while the probe is pending, then shows probed states", async () => {
+    const probe = deferred<McpProbeReport>();
+    renderMcpSection({ probePromise: probe.promise });
+
+    const section = await findMcpSection();
+    await within(section).findByText("filesystem");
+    for (const name of ["sentry", "legacy-db", "playwright"]) {
+      expect(within(section).getByText(name)).toBeInTheDocument();
+    }
+    // Enabled rows probe until the result lands; a disabled row knows its state.
+    expect(within(section).getAllByText("Checking…")).toHaveLength(3);
+    expect(within(section).getByText("Disabled")).toBeInTheDocument();
+
+    await act(async () => {
+      probe.resolve(mcpProbe);
+    });
+
+    const sentry = await screen.findByTestId("mcp-server-sentry");
+    expect(within(sentry).getByText("Needs sign-in")).toBeInTheDocument();
+    expect(
+      within(sentry).getByRole("button", { name: "Sign in" }),
+    ).toBeInTheDocument();
+
+    const filesystem = screen.getByTestId("mcp-server-filesystem");
+    expect(within(filesystem).getByText(/3 tools/)).toBeInTheDocument();
+
+    const legacyDb = screen.getByTestId("mcp-server-legacy-db");
+    expect(within(legacyDb).getByText(/ENOENT/)).toBeInTheDocument();
+  });
+
+  it("toggles a server through set_mcp_server_enabled and re-probes", async () => {
+    const user = userEvent.setup();
+    const { invoke, countCalls } = renderMcpSection({
+      handlers: {
+        set_mcp_server_enabled: (args) => ({
+          ...mcpConfig,
+          servers: mcpConfig.servers.map((server) =>
+            server.name === args?.name
+              ? { ...server, enabled: args.enabled === true }
+              : server,
+          ),
+        }),
+      },
+    });
+
+    const section = await findMcpSection();
+    expect(await within(section).findByText(/3 tools/)).toBeInTheDocument();
+    expect(countCalls("probe_mcp_servers")).toBe(1);
+
+    const filesystem = screen.getByTestId("mcp-server-filesystem");
+    await user.click(
+      within(filesystem).getByRole("switch", { name: "Enable filesystem" }),
+    );
+
+    await waitFor(() => {
+      expect(invoke).toHaveBeenCalledWith("set_mcp_server_enabled", {
+        name: "filesystem",
+        enabled: false,
+      });
+    });
+    await waitFor(() => {
+      expect(countCalls("probe_mcp_servers")).toBe(2);
+    });
+  });
+
+  it("shows Checking… while a re-probe is in flight instead of the stale state", async () => {
+    const user = userEvent.setup();
+    const reprobe = deferred<McpProbeReport>();
+    let probeCalls = 0;
+    renderMcpSection({
+      handlers: {
+        probe_mcp_servers: () => {
+          probeCalls += 1;
+          return probeCalls === 1 ? mcpProbe : reprobe.promise;
+        },
+        set_mcp_server_enabled: (args) => ({
+          ...mcpConfig,
+          servers: mcpConfig.servers.map((server) =>
+            server.name === args?.name
+              ? { ...server, enabled: args.enabled === true }
+              : server,
+          ),
+        }),
+      },
+    });
+
+    const playwright = await screen.findByTestId("mcp-server-playwright");
+    expect(await within(playwright).findByText("Disabled")).toBeInTheDocument();
+
+    await user.click(
+      within(playwright).getByRole("switch", { name: "Enable playwright" }),
+    );
+
+    // The toggle wrote enabled:true and invalidated the probe; while the fresh
+    // probe is in flight the row must not keep showing the stale "Disabled".
+    expect(await within(playwright).findByText("Checking…")).toBeInTheDocument();
+    expect(within(playwright).queryByText("Disabled")).not.toBeInTheDocument();
+
+    await act(async () => {
+      reprobe.resolve({
+        errors: [],
+        servers: [
+          ...mcpProbe.servers.filter((server) => server.name !== "playwright"),
+          {
+            name: "playwright",
+            state: "connected",
+            tools: ["browser_navigate"],
+          },
+        ],
+      });
+    });
+
+    expect(await within(playwright).findByText("Connected")).toBeInTheDocument();
+  });
+
+  it("shows the pending state during sign-in and reports a failed result", async () => {
+    const user = userEvent.setup();
+    const login = deferred<McpActionResult>();
+    renderMcpSection({
+      handlers: { login_mcp_server: () => login.promise },
+    });
+
+    const sentry = await screen.findByTestId("mcp-server-sentry");
+    await user.click(within(sentry).getByRole("button", { name: "Sign in" }));
+
+    expect(
+      await within(sentry).findByRole("button", { name: "Waiting for browser…" }),
+    ).toBeDisabled();
+
+    await act(async () => {
+      login.resolve({ ok: false, message: "Sign-in timed out." });
+    });
+
+    expect(await within(sentry).findByRole("alert")).toHaveTextContent(
+      "Sign-in timed out.",
+    );
+  });
+
+  it("keeps the add dialog open on a failed result and splits arguments by line", async () => {
+    const user = userEvent.setup();
+    const add = vi.fn(async () => ({
+      ok: false,
+      message: 'An MCP server named "github" already exists.',
+    }));
+    const { invoke } = renderMcpSection({
+      handlers: { add_mcp_server: add },
+    });
+
+    const section = await findMcpSection();
+    await user.click(within(section).getByRole("button", { name: "Add server" }));
+
+    const dialog = await screen.findByRole("dialog", { name: "Add server" });
+    const submit = within(dialog).getByRole("button", { name: "Add server" });
+    expect(submit).toBeDisabled();
+
+    await user.type(within(dialog).getByLabelText("Name"), "github");
+    await user.type(within(dialog).getByLabelText("Command"), "npx");
+    await user.type(
+      within(dialog).getByLabelText("Arguments"),
+      "-y\n@modelcontextprotocol/server-github\n\n--flag value",
+    );
+    expect(submit).toBeEnabled();
+
+    await user.click(submit);
+
+    await waitFor(() => {
+      expect(invoke).toHaveBeenCalledWith("add_mcp_server", {
+        input: {
+          kind: "stdio",
+          name: "github",
+          command: "npx",
+          args: ["-y", "@modelcontextprotocol/server-github", "--flag value"],
+        },
+      });
+    });
+    expect(
+      await within(dialog).findByRole("alert"),
+    ).toHaveTextContent('already exists');
+    expect(
+      screen.getByRole("dialog", { name: "Add server" }),
+    ).toBeInTheDocument();
+  });
+
+  it("removes a server only after confirmation", async () => {
+    const user = userEvent.setup();
+    const remove = vi.fn(async () => ({ ok: true, message: "" }));
+    const { invoke } = renderMcpSection({
+      handlers: { remove_mcp_server: remove },
+    });
+
+    const filesystem = await screen.findByTestId("mcp-server-filesystem");
+    await user.click(
+      within(filesystem).getByRole("button", { name: "filesystem actions" }),
+    );
+    await user.click(await screen.findByRole("menuitem", { name: /Remove/ }));
+
+    const dialog = await screen.findByRole("dialog", {
+      name: "Remove MCP server",
+    });
+    expect(invoke).not.toHaveBeenCalledWith(
+      "remove_mcp_server",
+      expect.anything(),
+    );
+
+    await user.click(within(dialog).getByRole("button", { name: "Remove" }));
+    await waitFor(() => {
+      expect(invoke).toHaveBeenCalledWith("remove_mcp_server", {
+        name: "filesystem",
+      });
+    });
+  });
+});
diff --git a/apps/desktop/src/pages/settings-mcp.tsx b/apps/desktop/src/pages/settings-mcp.tsx
new file mode 100644
index 00000000..259a23f8
--- /dev/null
+++ b/apps/desktop/src/pages/settings-mcp.tsx
@@ -0,0 +1,730 @@
+// Settings → MCP: manage the global Pi mcp.json through the backend's
+// `pi mcp` bridge. The config list renders instantly; connection states come
+// from a separate probe query that can take as long as a server's timeout.
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Banner } from "@astryxdesign/core/Banner";
+import { Button } from "@astryxdesign/core/Button";
+import { Code } from "@astryxdesign/core/Code";
+import { Collapsible } from "@astryxdesign/core/Collapsible";
+import { Dialog, DialogHeader } from "@astryxdesign/core/Dialog";
+import { EmptyState } from "@astryxdesign/core/EmptyState";
+import { Layout, LayoutContent } from "@astryxdesign/core/Layout";
+import { List, ListItem } from "@astryxdesign/core/List";
+import { MoreMenu } from "@astryxdesign/core/MoreMenu";
+import { Selector, SelectorOption } from "@astryxdesign/core/Selector";
+import {
+  SegmentedControl,
+  SegmentedControlItem,
+} from "@astryxdesign/core/SegmentedControl";
+import { StatusDot, type StatusDotVariant } from "@astryxdesign/core/StatusDot";
+import { HStack, VStack } from "@astryxdesign/core/Stack";
+import { Switch } from "@astryxdesign/core/Switch";
+import { TextArea } from "@astryxdesign/core/TextArea";
+import { TextInput } from "@astryxdesign/core/TextInput";
+import { Heading, Text } from "@astryxdesign/core/Text";
+import { useState } from "react";
+import { MoreHorizontal, RefreshCw } from "@/shared/ui/icons";
+import { invoke } from "@/shared/runtime";
+import type {
+  McpActionResult,
+  McpAddServerInput,
+  McpConfigReport,
+  McpExposure,
+  McpProbeReport,
+  McpServerConfigItem,
+  McpServerProbe,
+} from "@pace/core";
+
+const MCP_CONFIG_KEY = ["mcp-config"] as const;
+const MCP_PROBE_KEY = ["mcp-probe"] as const;
+
+const EXPOSURE_OPTIONS: Array<{ value: McpExposure; description: string }> = [
+  { value: "codemode", description: "Called from codemode scripts, listed in its description" },
+  { value: "codemode-deferred", description: "Called from codemode scripts, found with searchTools()" },
+  { value: "deferred", description: "Loaded by tool_search, then called directly" },
+  { value: "direct", description: "Declared to the model like built-in tools" },
+  { value: "hidden", description: "Registered but unreachable" },
+];
+
+type RowStatus = {
+  variant: StatusDotVariant;
+  label: string;
+  pulsing?: boolean;
+};
+
+function rowStatus(
+  server: McpServerConfigItem,
+  probe: McpServerProbe | undefined,
+  probeFailed: boolean,
+): RowStatus {
+  if (!server.enabled) {
+    return { variant: "neutral", label: "Disabled" };
+  }
+  if (probe) {
+    switch (probe.state) {
+      case "connected":
+        return { variant: "success", label: "Connected" };
+      case "needs-auth":
+        return { variant: "warning", label: "Needs sign-in" };
+      case "failed":
+        return { variant: "error", label: "Failed" };
+      case "disabled":
+        return { variant: "neutral", label: "Disabled" };
+      case "connecting":
+        return { variant: "neutral", label: "Connecting…", pulsing: true };
+      case "disconnected":
+        return { variant: "neutral", label: "Disconnected" };
+    }
+  }
+  if (probeFailed) {
+    return { variant: "neutral", label: "Status unknown" };
+  }
+  return { variant: "neutral", label: "Checking…", pulsing: true };
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function McpServerTools({ tools }: { tools: string[] }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <Collapsible
+      trigger={
+        <Text type="body" size="sm" color="secondary">
+          {`${tools.length} tool${tools.length === 1 ? "" : "s"}`}
+        </Text>
+      }
+      isOpen={open}
+      onOpenChange={setOpen}
+    >
+      {open ? (
+        <Text
+          as="div"
+          type="body"
+          size="sm"
+          style={{ whiteSpace: "pre-wrap", overflowWrap: "anywhere" }}
+        >
+          {tools.join(", ")}
+        </Text>
+      ) : null}
+    </Collapsible>
+  );
+}
+
+function McpExposureSelect({
+  label,
+  value,
+  disabled,
+  isLabelHidden = true,
+  onChange,
+}: {
+  label: string;
+  value: McpExposure;
+  disabled?: boolean;
+  /** Rows hide the label; the add dialog shows it like the other fields. */
+  isLabelHidden?: boolean;
+  onChange: (value: McpExposure) => void;
+}) {
+  return (
+    <Selector
+      isLabelHidden={isLabelHidden}
+      label={label}
+      size="sm"
+      options={EXPOSURE_OPTIONS.map((option) => ({
+        value: option.value,
+        label: option.value,
+      }))}
+      value={value}
+      isDisabled={disabled}
+      onChange={(next) => onChange(next as McpExposure)}
+      renderOption={(option) => {
+        const meta = EXPOSURE_OPTIONS.find((entry) => entry.value === option.value);
+        return (
+          <SelectorOption
+            label={option.label ?? option.value}
+            description={meta?.description}
+          />
+        );
+      }}
+    />
+  );
+}
+
+function McpServerRow({
+  server,
+  probe,
+  probeFailed,
+}: {
+  server: McpServerConfigItem;
+  probe?: McpServerProbe;
+  probeFailed: boolean;
+}) {
+  const queryClient = useQueryClient();
+  const [rowError, setRowError] = useState<string | null>(null);
+  const [removeOpen, setRemoveOpen] = useState(false);
+  const [removeError, setRemoveError] = useState<string | null>(null);
+
+  const applyConfigReport = (report: McpConfigReport) => {
+    queryClient.setQueryData(MCP_CONFIG_KEY, report);
+    void queryClient.invalidateQueries({ queryKey: MCP_PROBE_KEY });
+  };
+
+  const enabledMutation = useMutation({
+    mutationFn: (enabled: boolean) =>
+      invoke<McpConfigReport>("set_mcp_server_enabled", {
+        name: server.name,
+        enabled,
+      }),
+    onMutate: () => setRowError(null),
+    onSuccess: applyConfigReport,
+    onError: (error) => setRowError(errorText(error)),
+  });
+
+  const exposureMutation = useMutation({
+    mutationFn: (exposure: McpExposure) =>
+      invoke<McpConfigReport>("set_mcp_server_exposure", {
+        name: server.name,
+        exposure,
+      }),
+    onMutate: () => setRowError(null),
+    onSuccess: applyConfigReport,
+    onError: (error) => setRowError(errorText(error)),
+  });
+
+  const signInMutation = useMutation({
+    mutationFn: () => invoke<McpActionResult>("login_mcp_server", { name: server.name }),
+    onMutate: () => setRowError(null),
+    onSuccess: (result) => {
+      if (result.ok) {
+        void queryClient.invalidateQueries({ queryKey: MCP_PROBE_KEY });
+      } else {
+        setRowError(result.message || "Sign-in failed.");
+      }
+    },
+    onError: (error) => setRowError(errorText(error)),
+  });
+
+  const signOutMutation = useMutation({
+    mutationFn: () => invoke<McpActionResult>("logout_mcp_server", { name: server.name }),
+    onMutate: () => setRowError(null),
+    onSuccess: (result) => {
+      if (result.ok) {
+        void queryClient.invalidateQueries({ queryKey: MCP_PROBE_KEY });
+      } else {
+        setRowError(result.message || "Sign-out failed.");
+      }
+    },
+    onError: (error) => setRowError(errorText(error)),
+  });
+
+  const removeMutation = useMutation({
+    mutationFn: () => invoke<McpActionResult>("remove_mcp_server", { name: server.name }),
+    onMutate: () => setRemoveError(null),
+    onSuccess: (result) => {
+      if (result.ok) {
+        setRemoveOpen(false);
+        void queryClient.invalidateQueries({ queryKey: MCP_CONFIG_KEY });
+        void queryClient.invalidateQueries({ queryKey: MCP_PROBE_KEY });
+      } else {
+        setRemoveError(result.message || `Could not remove ${server.name}.`);
+      }
+    },
+    onError: (error) => setRemoveError(errorText(error)),
+  });
+
+  const status = rowStatus(server, probe, probeFailed);
+  const controlsBusy = enabledMutation.isPending || exposureMutation.isPending;
+  const oauthBusy = signInMutation.isPending || signOutMutation.isPending;
+  const showSignIn = server.usesOAuth && probe?.state === "needs-auth";
+  const showSignOut = server.usesOAuth && probe?.state === "connected";
+
+  return (
+    <>
+      <ListItem
+        data-testid={`mcp-server-${server.name}`}
+        label={server.name}
+        description={
+          <VStack gap={1}>
+            <HStack gap={1.5} vAlign="center">
+              <StatusDot
+                variant={status.variant}
+                label={status.label}
+                isPulsing={status.pulsing}
+              />
+              <Text type="supporting">{status.label}</Text>
+            </HStack>
+            <span title={server.transport}>
+              <Text type="supporting" maxLines={1}>
+                <Code>{server.transport}</Code>
+              </Text>
+            </span>
+            {probe?.state === "connected" && probe.tools.length > 0 ? (
+              <McpServerTools tools={probe.tools} />
+            ) : null}
+            {probe?.state === "connected" && probe.tools.length === 0 ? (
+              <Text type="supporting">No tools</Text>
+            ) : null}
+            {probe?.state === "failed" && probe.error ? (
+              <span title={probe.error}>
+                <Text
+                  type="supporting"
+                  maxLines={1}
+                  style={{ color: "var(--danger)" }}
+                >
+                  {probe.error}
+                </Text>
+              </span>
+            ) : null}
+            {rowError ? (
+              <Text
+                as="p"
+                type="supporting"
+                role="alert"
+                style={{ color: "var(--danger)" }}
+              >
+                {rowError}
+              </Text>
+            ) : null}
+          </VStack>
+        }
+        endContent={
+          <HStack gap={2} vAlign="center">
+            {showSignIn ? (
+              <Button
+                variant="secondary"
+                size="sm"
+                label={
+                  signInMutation.isPending ? "Waiting for browser…" : "Sign in"
+                }
+                isDisabled={oauthBusy}
+                onClick={() => signInMutation.mutate()}
+              />
+            ) : null}
+            {showSignOut ? (
+              <Button
+                variant="ghost"
+                size="sm"
+                label={signOutMutation.isPending ? "Signing out…" : "Sign out"}
+                isDisabled={oauthBusy}
+                onClick={() => signOutMutation.mutate()}
+              />
+            ) : null}
+            <McpExposureSelect
+              label={`${server.name} tool exposure`}
+              value={server.exposure}
+              disabled={controlsBusy}
+              onChange={(exposure) => exposureMutation.mutate(exposure)}
+            />
+            <Switch
+              label={`Enable ${server.name}`}
+              isLabelHidden
+              value={server.enabled}
+              isDisabled={controlsBusy}
+              onChange={(enabled) => enabledMutation.mutate(enabled)}
+            />
+            <MoreMenu
+              icon={<MoreHorizontal aria-hidden="true" />}
+              label={`${server.name} actions`}
+              size="sm"
+              variant="ghost"
+              isDisabled={removeMutation.isPending}
+              items={[
+                {
+                  label: "Remove…",
+                  onClick: () => {
+                    setRemoveError(null);
+                    setRemoveOpen(true);
+                  },
+                },
+              ]}
+            />
+          </HStack>
+        }
+      />
+      {removeOpen ? (
+        <RemoveMcpServerDialog
+          name={server.name}
+          pending={removeMutation.isPending}
+          error={removeError}
+          onConfirm={() => removeMutation.mutate()}
+          onClose={() => setRemoveOpen(false)}
+        />
+      ) : null}
+    </>
+  );
+}
+
+function RemoveMcpServerDialog({
+  name,
+  pending,
+  error,
+  onConfirm,
+  onClose,
+}: {
+  name: string;
+  pending: boolean;
+  error: string | null;
+  onConfirm: () => void;
+  onClose: () => void;
+}) {
+  return (
+    <Dialog
+      aria-label="Remove MCP server"
+      isOpen
+      onOpenChange={(isOpen) => {
+        if (!isOpen && !pending) onClose();
+      }}
+      purpose="form"
+    >
+      <Layout
+        header={
+          <DialogHeader
+            title="Remove MCP server"
+            onOpenChange={(isOpen) => {
+              if (!isOpen && !pending) onClose();
+            }}
+          />
+        }
+        content={
+          <LayoutContent>
+            <VStack gap={3}>
+              <Text as="p">Remove {name} from mcp.json?</Text>
+              {error ? (
+                <Text
+                  as="p"
+                  type="supporting"
+                  role="alert"
+                  style={{ color: "var(--danger)" }}
+                >
+                  {error}
+                </Text>
+              ) : null}
+              <HStack gap={2} justify="end">
+                <Button
+                  variant="ghost"
+                  label="Cancel"
+                  isDisabled={pending}
+                  onClick={onClose}
+                />
+                <Button
+                  variant="destructive"
+                  label={pending ? "Removing…" : "Remove"}
+                  isDisabled={pending}
+                  onClick={onConfirm}
+                />
+              </HStack>
+            </VStack>
+          </LayoutContent>
+        }
+      />
+    </Dialog>
+  );
+}
+
+function AddMcpServerDialog({ onClose }: { onClose: () => void }) {
+  const queryClient = useQueryClient();
+  const [name, setName] = useState("");
+  const [kind, setKind] = useState<"stdio" | "http">("stdio");
+  const [command, setCommand] = useState("");
+  const [argsText, setArgsText] = useState("");
+  const [url, setUrl] = useState("");
+  const [exposure, setExposure] = useState<McpExposure>("codemode");
+  const [error, setError] = useState<string | null>(null);
+
+  const addMutation = useMutation({
+    mutationFn: (input: McpAddServerInput) =>
+      invoke<McpActionResult>("add_mcp_server", { input }),
+    onSuccess: (result) => {
+      if (result.ok) {
+        void queryClient.invalidateQueries({ queryKey: MCP_CONFIG_KEY });
+        void queryClient.invalidateQueries({ queryKey: MCP_PROBE_KEY });
+        onClose();
+      } else {
+        setError(result.message || "Could not add the server.");
+      }
+    },
+    onError: (err) => setError(errorText(err)),
+  });
+
+  // One argument per line; blank lines dropped, inner spaces preserved.
+  const args = argsText
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  const canSubmit =
+    name.trim().length > 0 &&
+    (kind === "stdio" ? command.trim().length > 0 : url.trim().length > 0) &&
+    !addMutation.isPending;
+
+  const submit = () => {
+    if (!canSubmit) return;
+    setError(null);
+    const exposureInput = exposure === "codemode" ? {} : { exposure };
+    addMutation.mutate(
+      kind === "stdio"
+        ? { kind, name: name.trim(), command: command.trim(), args, ...exposureInput }
+        : { kind, name: name.trim(), url: url.trim(), ...exposureInput },
+    );
+  };
+
+  return (
+    <Dialog
+      aria-label="Add server"
+      isOpen
+      onOpenChange={(isOpen) => {
+        if (!isOpen && !addMutation.isPending) onClose();
+      }}
+      purpose="form"
+    >
+      <Layout
+        header={
+          <DialogHeader
+            title="Add server"
+            onOpenChange={(isOpen) => {
+              if (!isOpen && !addMutation.isPending) onClose();
+            }}
+          />
+        }
+        content={
+          <LayoutContent>
+            <form
+              onSubmit={(event) => {
+                event.preventDefault();
+                submit();
+              }}
+            >
+              <VStack gap={3}>
+                <TextInput
+                  label="Name"
+                  value={name}
+                  onChange={setName}
+                  isDisabled={addMutation.isPending}
+                  placeholder="filesystem"
+                />
+                <SegmentedControl
+                  label="Transport"
+                  value={kind}
+                  onChange={(value) => {
+                    if (value === "stdio" || value === "http") setKind(value);
+                  }}
+                >
+                  <SegmentedControlItem label="Stdio" value="stdio" />
+                  <SegmentedControlItem label="HTTP" value="http" />
+                </SegmentedControl>
+                {kind === "stdio" ? (
+                  <>
+                    <TextInput
+                      label="Command"
+                      value={command}
+                      onChange={setCommand}
+                      isDisabled={addMutation.isPending}
+                      placeholder="npx"
+                    />
+                    <TextArea
+                      label="Arguments"
+                      description="One argument per line."
+                      value={argsText}
+                      onChange={setArgsText}
+                      isDisabled={addMutation.isPending}
+                      placeholder={"-y\n@modelcontextprotocol/server-filesystem"}
+                    />
+                  </>
+                ) : (
+                  <TextInput
+                    label="URL"
+                    value={url}
+                    onChange={setUrl}
+                    isDisabled={addMutation.isPending}
+                    placeholder="https://example.com/mcp"
+                  />
+                )}
+                <McpExposureSelect
+                  label="Exposure"
+                  value={exposure}
+                  disabled={addMutation.isPending}
+                  isLabelHidden={false}
+                  onChange={setExposure}
+                />
+                <Text as="p" type="supporting">
+                  Environment variables, headers, and OAuth client settings still
+                  need editing mcp.json directly.
+                </Text>
+                {error ? (
+                  <Text
+                    as="p"
+                    type="supporting"
+                    role="alert"
+                    style={{ color: "var(--danger)" }}
+                  >
+                    {error}
+                  </Text>
+                ) : null}
+                <HStack gap={2} justify="end">
+                  <Button
+                    type="submit"
+                    variant="primary"
+                    label={addMutation.isPending ? "Adding…" : "Add server"}
+                    isDisabled={!canSubmit}
+                  />
+                </HStack>
+              </VStack>
+            </form>
+          </LayoutContent>
+        }
+      />
+    </Dialog>
+  );
+}
+
+export function McpSettingsSection({ enabled }: { enabled: boolean }) {
+  const queryClient = useQueryClient();
+  const [addOpen, setAddOpen] = useState(false);
+
+  const configQuery = useQuery({
+    queryKey: MCP_CONFIG_KEY,
+    queryFn: () => invoke<McpConfigReport>("get_mcp_config"),
+    enabled,
+    retry: false,
+    refetchOnWindowFocus: false,
+  });
+  const probeQuery = useQuery({
+    queryKey: MCP_PROBE_KEY,
+    queryFn: () => invoke<McpProbeReport>("probe_mcp_servers"),
+    enabled,
+    retry: false,
+    refetchOnWindowFocus: false,
+  });
+
+  const servers = configQuery.data?.servers ?? [];
+  // A probe in flight means the cached report is stale: a toggled or just
+  // signed-in server would flash its old state (e.g. still "Disabled" while
+  // enabled) until the new probe lands. Withhold it so rows show "Checking…".
+  const probes = probeQuery.isFetching
+    ? new Map<string, McpServerProbe>()
+    : new Map(
+        (probeQuery.data?.servers ?? []).map((server) => [server.name, server]),
+      );
+  const configErrors = configQuery.data?.errors ?? [];
+  const probeErrors = probeQuery.data?.errors ?? [];
+
+  const refresh = () => {
+    void configQuery.refetch();
+    void probeQuery.refetch();
+  };
+
+  return (
+    <VStack
+      as="section"
+      aria-labelledby="settings-mcp-heading"
+      gap={3}
+      data-testid="settings-mcp"
+    >
+      <VStack gap={2}>
+        <HStack justify="between" vAlign="center">
+          <Heading level={2} id="settings-mcp-heading">
+            MCP
+          </Heading>
+          <HStack gap={2} vAlign="center">
+            <Button
+              variant="ghost"
+              size="sm"
+              label="Refresh"
+              icon={<RefreshCw aria-hidden="true" />}
+              isDisabled={configQuery.isFetching || probeQuery.isFetching}
+              onClick={refresh}
+            />
+            <Button
+              variant="secondary"
+              size="sm"
+              label="Add server"
+              onClick={() => setAddOpen(true)}
+            />
+          </HStack>
+        </HStack>
+        <Text as="p" type="supporting">
+          MCP servers from the global Pi <Code>mcp.json</Code>. Changes apply to
+          new sessions. Sign-ins reach running sessions on their next turn.
+        </Text>
+        {configQuery.data ? (
+          <Text as="p" type="supporting">
+            <Code style={{ userSelect: "text" }}>
+              {configQuery.data.configPath}
+            </Code>
+          </Text>
+        ) : null}
+      </VStack>
+
+      {configErrors.length > 0 ? (
+        <Banner
+          status="error"
+          title="mcp.json has configuration errors"
+          description={configErrors.join("\n")}
+        />
+      ) : null}
+      {probeErrors.length > 0 ? (
+        <Banner
+          status="error"
+          title="Server check reported errors"
+          description={probeErrors.join("\n")}
+        />
+      ) : null}
+      {configQuery.isError ? (
+        <Banner
+          status="error"
+          title="Could not load MCP configuration"
+          description={errorText(configQuery.error)}
+        />
+      ) : null}
+      {probeQuery.isError ? (
+        <Banner
+          status="error"
+          title="Could not check server status"
+          description={errorText(probeQuery.error)}
+          endContent={
+            <Button
+              variant="secondary"
+              size="sm"
+              label="Retry"
+              onClick={() => void probeQuery.refetch()}
+            />
+          }
+        />
+      ) : null}
+
+      {configQuery.isPending ? (
+        <Text as="p" type="supporting">
+          Loading…
+        </Text>
+      ) : servers.length === 0 ? (
+        <EmptyState
+          isCompact
+          title="No MCP servers configured"
+          description="Add a server to mcp.json to give Pi extra tools."
+          actions={
+            <Button
+              variant="secondary"
+              size="sm"
+              label="Add server"
+              onClick={() => setAddOpen(true)}
+            />
+          }
+        />
+      ) : (
+        <List hasDividers>
+          {servers.map((server) => (
+            <McpServerRow
+              key={server.name}
+              server={server}
+              probe={probes.get(server.name)}
+              probeFailed={probeQuery.isError && !probeQuery.isFetching}
+            />
+          ))}
+        </List>
+      )}
+
+      {addOpen ? <AddMcpServerDialog onClose={() => setAddOpen(false)} /> : null}
+    </VStack>
+  );
+}
diff --git a/apps/desktop/src/pages/settings.tsx b/apps/desktop/src/pages/settings.tsx
index 628671bb..e3bcd787 100644
--- a/apps/desktop/src/pages/settings.tsx
+++ b/apps/desktop/src/pages/settings.tsx
@@ -27,11 +27,13 @@ import {
   AnimatedInformationCircle,
   AnimatedKey,
   AnimatedMessage,
+  AnimatedPuzzle,
   AnimatedRobot,
   MoreHorizontal,
   RefreshCw,
 } from "@/shared/ui/icons";
 import { ChangelogSection } from "@/pages/settings-changelog";
+import { McpSettingsSection } from "@/pages/settings-mcp";
 import paceIcon from "../../../../build/icon-512.png";
 import { ProviderIcon } from "@/entities/provider/provider-icon";
 import { useModelCatalog } from "@/entities/model/use-model-catalog";
@@ -1164,6 +1166,11 @@ function SettingsContent({
               providerLabels={providerLabels}
             />
           </VStack>
+          <VStack
+            style={{ display: section === "mcp" ? undefined : "none" }}
+          >
+            <McpSettingsSection enabled={section === "mcp"} />
+          </VStack>
           <VStack
             style={{ display: section === "chats" ? undefined : "none" }}
           >
@@ -1184,6 +1191,7 @@ function SettingsContent({
 const settingsSections = [
   { id: "providers", label: "Providers", icon: AnimatedKey },
   { id: "models", label: "Models", icon: AnimatedRobot },
+  { id: "mcp", label: "MCP", icon: AnimatedPuzzle },
   { id: "chats", label: "Chats", icon: AnimatedMessage },
   { id: "changelog", label: "Changelog", icon: AnimatedFile },
   { id: "about", label: "About & Updates", icon: AnimatedInformationCircle },
diff --git a/apps/desktop/src/shared/runtime.ts b/apps/desktop/src/shared/runtime.ts
index 8e2b5be1..01886dda 100644
--- a/apps/desktop/src/shared/runtime.ts
+++ b/apps/desktop/src/shared/runtime.ts
@@ -3,7 +3,14 @@ import type { BackendRpcEvent } from "@pace/backend";
 import type { BrowserEvent } from "@/shared/browser-protocol";
 import type { NavigateRequest } from "@/shared/navigate-protocol";
 import type { UpdateStatus } from "@/shared/update-protocol";
-import type { SessionDetail } from "@pace/core";
+import type {
+  McpConfigReport,
+  McpExposure,
+  McpProbeReport,
+  McpServerConfigItem,
+  McpServerState,
+  SessionDetail,
+} from "@pace/core";
 import type { SessionSummary } from "@/entities/session/sessions";
 
 declare global {
@@ -33,6 +40,92 @@ const emptyConfigInventory = {
 };
 const browserSessionSummaryFixture: SessionSummary[] = browserSessionSummaries;
 
+// Browser-dev MCP fixture. One mutable list backs both reads, so Settings
+// mutations (enable, exposure, sign-in, add, remove) stay consistent between
+// the config report and the probe report for the life of the page.
+type BrowserMcpServer = McpServerConfigItem & {
+  /** Probable state once enabled; `enabled: false` always reports "disabled". */
+  state: McpServerState;
+  tools: string[];
+  error?: string;
+};
+
+const browserMcpConfigPath = "/browser-dev/mcp.json";
+
+const browserMcpServers: BrowserMcpServer[] = [
+  {
+    name: "filesystem",
+    source: browserMcpConfigPath,
+    enabled: true,
+    exposure: "codemode",
+    kind: "stdio",
+    transport: "npx -y @modelcontextprotocol/server-filesystem ~/Documents",
+    usesOAuth: false,
+    state: "connected",
+    tools: ["read_file", "write_file", "list_directory", "search_files"],
+  },
+  {
+    name: "sentry",
+    source: browserMcpConfigPath,
+    enabled: true,
+    exposure: "codemode",
+    kind: "http",
+    transport: "https://mcp.sentry.dev/mcp",
+    usesOAuth: true,
+    state: "needs-auth",
+    tools: [],
+  },
+  {
+    name: "legacy-db",
+    source: browserMcpConfigPath,
+    enabled: true,
+    exposure: "direct",
+    kind: "stdio",
+    transport: "node scripts/db-mcp-server.js",
+    usesOAuth: false,
+    state: "failed",
+    tools: [],
+    error: 'MCP server "legacy-db" failed to connect: spawn node ENOENT',
+  },
+  {
+    name: "playwright",
+    source: browserMcpConfigPath,
+    enabled: false,
+    exposure: "deferred",
+    kind: "stdio",
+    transport: "npx -y @playwright/mcp@latest",
+    usesOAuth: false,
+    state: "connected",
+    tools: ["browser_navigate", "browser_click", "browser_snapshot"],
+  },
+];
+
+function browserMcpConfig(): McpConfigReport {
+  return {
+    configPath: browserMcpConfigPath,
+    errors: [],
+    servers: browserMcpServers.map(
+      ({ state: _state, tools: _tools, error: _error, ...item }) => item,
+    ),
+  };
+}
+
+function browserMcpProbe(): McpProbeReport {
+  return {
+    errors: [],
+    servers: browserMcpServers.map((server) => ({
+      name: server.name,
+      state: server.enabled ? server.state : "disabled",
+      tools: server.enabled ? server.tools : [],
+      ...(server.enabled && server.error ? { error: server.error } : {}),
+    })),
+  };
+}
+
+function browserMcpServer(name: unknown): BrowserMcpServer | undefined {
+  return browserMcpServers.find((server) => server.name === name);
+}
+
 export function isElectronRuntime() {
   return typeof window !== "undefined" && window.pace !== undefined;
 }
@@ -323,6 +416,108 @@ export function invokeBrowserFallback<T>(command: string, args?: InvokeArgs): Pr
         message: "Connection tests run in the desktop app",
         detail: "",
       } as T);
+    case "get_mcp_config":
+      return Promise.resolve(browserMcpConfig() as T);
+    case "probe_mcp_servers":
+      return Promise.resolve(browserMcpProbe() as T);
+    case "set_mcp_server_enabled": {
+      const server = browserMcpServer(args?.name);
+      if (server) server.enabled = args?.enabled === true;
+      return Promise.resolve(browserMcpConfig() as T);
+    }
+    case "set_mcp_server_exposure": {
+      const server = browserMcpServer(args?.name);
+      if (server && typeof args?.exposure === "string") {
+        server.exposure = args.exposure as McpExposure;
+      }
+      return Promise.resolve(browserMcpConfig() as T);
+    }
+    case "login_mcp_server": {
+      const server = browserMcpServer(args?.name);
+      if (!server) {
+        return Promise.resolve({
+          ok: false,
+          message: `No MCP server named "${args?.name}".`,
+        } as T);
+      }
+      server.state = "connected";
+      if (server.tools.length === 0) {
+        server.tools = ["search_issues", "get_issue", "list_projects"];
+      }
+      return Promise.resolve({
+        ok: true,
+        message: `Signed in to MCP server "${server.name}".`,
+      } as T);
+    }
+    case "logout_mcp_server": {
+      const server = browserMcpServer(args?.name);
+      if (!server?.usesOAuth) {
+        return Promise.resolve({
+          ok: false,
+          message: `MCP server "${args?.name}" does not use OAuth.`,
+        } as T);
+      }
+      server.state = "needs-auth";
+      server.tools = [];
+      return Promise.resolve({
+        ok: true,
+        message: `Signed out of MCP server "${server.name}".`,
+      } as T);
+    }
+    case "add_mcp_server": {
+      const input = (args?.input ?? {}) as {
+        kind?: string;
+        name?: string;
+        command?: string;
+        url?: string;
+        args?: string[];
+        exposure?: McpExposure;
+      };
+      const name = input.name?.trim();
+      const command = input.command?.trim() ?? "";
+      const transport =
+        input.kind === "http"
+          ? (input.url?.trim() ?? "")
+          : [command, ...(input.args ?? [])].join(" ").trim();
+      if (!name || !transport || (input.kind !== "http" && !command)) {
+        return Promise.resolve({
+          ok: false,
+          message: "Invalid MCP server input.",
+        } as T);
+      }
+      browserMcpServers.push({
+        name,
+        source: browserMcpConfigPath,
+        enabled: true,
+        exposure: input.exposure ?? "codemode",
+        kind: input.kind === "http" ? "http" : "stdio",
+        transport,
+        // No headers can be entered in this form, so HTTP adds are OAuth-able.
+        usesOAuth: input.kind === "http",
+        state: "connected",
+        tools: [],
+      });
+      return Promise.resolve({
+        ok: true,
+        message: `Added global MCP server "${name}".`,
+      } as T);
+    }
+    case "remove_mcp_server": {
+      const index = browserMcpServers.findIndex(
+        (server) => server.name === args?.name,
+      );
+      if (index < 0) {
+        return Promise.resolve({
+          ok: false,
+          message: `No global MCP server named "${args?.name}".`,
+        } as T);
+      }
+      browserMcpServers.splice(index, 1);
+      return Promise.resolve({
+        ok: true,
+        message: `Removed global MCP server "${args?.name}".`,
+      } as T);
+    }
     case "resolve_tool_schemas":
       return Promise.resolve({ schemas: {} } as T);
     case "list_prompt_commands":
diff --git a/apps/desktop/src/shared/settings-navigation.ts b/apps/desktop/src/shared/settings-navigation.ts
index 9239321c..a5c7619d 100644
--- a/apps/desktop/src/shared/settings-navigation.ts
+++ b/apps/desktop/src/shared/settings-navigation.ts
@@ -1,10 +1,11 @@
 import { useRouter, useRouterState } from "@tanstack/react-router";
 
-export type SettingsSection = "providers" | "models" | "chats" | "changelog" | "about";
+export type SettingsSection = "providers" | "models" | "mcp" | "chats" | "changelog" | "about";
 
 export function parseSettingsSection(value: unknown): SettingsSection | null {
   return value === "providers" ||
     value === "models" ||
+    value === "mcp" ||
     value === "chats" ||
     value === "changelog" ||
     value === "about"

From 6bafd921571ae383d549f760e61ae06856bd7875 Mon Sep 17 00:00:00 2001
From: Kieran Zhang <oldmeatovo@gmail.com>
Date: Thu, 1 Oct 2026 18:48:28 +0800
Subject: [PATCH 2/3] fix(settings): let the MCP transport switch fill its row

---
 apps/desktop/src/pages/settings-mcp.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/apps/desktop/src/pages/settings-mcp.tsx b/apps/desktop/src/pages/settings-mcp.tsx
index 259a23f8..3e2cb749 100644
--- a/apps/desktop/src/pages/settings-mcp.tsx
+++ b/apps/desktop/src/pages/settings-mcp.tsx
@@ -505,6 +505,7 @@ function AddMcpServerDialog({ onClose }: { onClose: () => void }) {
                 />
                 <SegmentedControl
                   label="Transport"
+                  layout="fill"
                   value={kind}
                   onChange={(value) => {
                     if (value === "stdio" || value === "http") setKind(value);

From 3bfaae29042d38ec58927894d1d9ae4353c165a8 Mon Sep 17 00:00:00 2001
From: Kieran Zhang <oldmeatovo@gmail.com>
Date: Thu, 1 Oct 2026 19:32:22 +0800
Subject: [PATCH 3/3] fix(settings): offer MCP sign-out only when credentials
 are stored

---
 apps/desktop/src/pages/settings-mcp.test.tsx | 44 ++++++++++++++++++++
 apps/desktop/src/pages/settings-mcp.tsx      | 10 ++++-
 apps/desktop/src/shared/runtime.ts           | 40 ++++++++++++++++++
 3 files changed, 93 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/pages/settings-mcp.test.tsx b/apps/desktop/src/pages/settings-mcp.test.tsx
index 23a05932..8f32baba 100644
--- a/apps/desktop/src/pages/settings-mcp.test.tsx
+++ b/apps/desktop/src/pages/settings-mcp.test.tsx
@@ -22,6 +22,7 @@ const mcpConfig: McpConfigReport = {
       kind: "stdio",
       transport: "npx -y @modelcontextprotocol/server-filesystem .",
       usesOAuth: false,
+      hasStoredCredentials: false,
     },
     {
       name: "sentry",
@@ -31,6 +32,7 @@ const mcpConfig: McpConfigReport = {
       kind: "http",
       transport: "https://mcp.sentry.dev/mcp",
       usesOAuth: true,
+      hasStoredCredentials: false,
     },
     {
       name: "legacy-db",
@@ -40,6 +42,7 @@ const mcpConfig: McpConfigReport = {
       kind: "stdio",
       transport: "node db-server.js",
       usesOAuth: false,
+      hasStoredCredentials: false,
     },
     {
       name: "playwright",
@@ -49,6 +52,7 @@ const mcpConfig: McpConfigReport = {
       kind: "stdio",
       transport: "npx -y @playwright/mcp",
       usesOAuth: false,
+      hasStoredCredentials: false,
     },
   ],
 };
@@ -322,6 +326,46 @@ describe("Settings — MCP servers", () => {
     ).toBeInTheDocument();
   });
 
+  it("offers Sign out only when credentials are stored", async () => {
+    const connectedProbe: McpProbeReport = {
+      errors: [],
+      servers: mcpProbe.servers.map((server) =>
+        server.name === "sentry"
+          ? { ...server, state: "connected" as const }
+          : server,
+      ),
+    };
+    const configWith = (hasStoredCredentials: boolean): McpConfigReport => ({
+      ...mcpConfig,
+      servers: mcpConfig.servers.map((server) =>
+        server.name === "sentry"
+          ? { ...server, hasStoredCredentials }
+          : server,
+      ),
+    });
+
+    // A connected OAuth-shaped server without stored credentials cannot sign out.
+    const first = renderMcpSection({
+      config: configWith(false),
+      probe: connectedProbe,
+    });
+    let sentry = await screen.findByTestId("mcp-server-sentry");
+    await within(sentry).findByText("Connected");
+    expect(
+      within(sentry).queryByRole("button", { name: "Sign out" }),
+    ).not.toBeInTheDocument();
+    first.unmount();
+
+    renderMcpSection({
+      config: configWith(true),
+      probe: connectedProbe,
+    });
+    sentry = await screen.findByTestId("mcp-server-sentry");
+    expect(
+      await within(sentry).findByRole("button", { name: "Sign out" }),
+    ).toBeInTheDocument();
+  });
+
   it("removes a server only after confirmation", async () => {
     const user = userEvent.setup();
     const remove = vi.fn(async () => ({ ok: true, message: "" }));
diff --git a/apps/desktop/src/pages/settings-mcp.tsx b/apps/desktop/src/pages/settings-mcp.tsx
index 3e2cb749..098f058e 100644
--- a/apps/desktop/src/pages/settings-mcp.tsx
+++ b/apps/desktop/src/pages/settings-mcp.tsx
@@ -198,6 +198,9 @@ function McpServerRow({
     onMutate: () => setRowError(null),
     onSuccess: (result) => {
       if (result.ok) {
+        // Stored credentials changed, so the config (not just the probe)
+        // decides which OAuth button the row shows next.
+        void queryClient.invalidateQueries({ queryKey: MCP_CONFIG_KEY });
         void queryClient.invalidateQueries({ queryKey: MCP_PROBE_KEY });
       } else {
         setRowError(result.message || "Sign-in failed.");
@@ -211,6 +214,7 @@ function McpServerRow({
     onMutate: () => setRowError(null),
     onSuccess: (result) => {
       if (result.ok) {
+        void queryClient.invalidateQueries({ queryKey: MCP_CONFIG_KEY });
         void queryClient.invalidateQueries({ queryKey: MCP_PROBE_KEY });
       } else {
         setRowError(result.message || "Sign-out failed.");
@@ -238,7 +242,11 @@ function McpServerRow({
   const controlsBusy = enabledMutation.isPending || exposureMutation.isPending;
   const oauthBusy = signInMutation.isPending || signOutMutation.isPending;
   const showSignIn = server.usesOAuth && probe?.state === "needs-auth";
-  const showSignOut = server.usesOAuth && probe?.state === "connected";
+  // usesOAuth only describes the config shape (HTTP without an Authorization
+  // header); sign-out requires actual stored credentials. When sign-in applies,
+  // it takes precedence over offering sign-out for a stale credential.
+  const showSignOut =
+    server.usesOAuth && server.hasStoredCredentials && !showSignIn;
 
   return (
     <>
diff --git a/apps/desktop/src/shared/runtime.ts b/apps/desktop/src/shared/runtime.ts
index 01886dda..1d5d567a 100644
--- a/apps/desktop/src/shared/runtime.ts
+++ b/apps/desktop/src/shared/runtime.ts
@@ -61,6 +61,7 @@ const browserMcpServers: BrowserMcpServer[] = [
     kind: "stdio",
     transport: "npx -y @modelcontextprotocol/server-filesystem ~/Documents",
     usesOAuth: false,
+    hasStoredCredentials: false,
     state: "connected",
     tools: ["read_file", "write_file", "list_directory", "search_files"],
   },
@@ -72,9 +73,36 @@ const browserMcpServers: BrowserMcpServer[] = [
     kind: "http",
     transport: "https://mcp.sentry.dev/mcp",
     usesOAuth: true,
+    hasStoredCredentials: false,
     state: "needs-auth",
     tools: [],
   },
+  {
+    name: "linear",
+    source: browserMcpConfigPath,
+    enabled: true,
+    exposure: "codemode",
+    kind: "http",
+    transport: "https://mcp.linear.app/mcp",
+    usesOAuth: true,
+    // Signed-in OAuth server: connected and able to sign out.
+    hasStoredCredentials: true,
+    state: "connected",
+    tools: ["search_issues", "get_issue", "list_projects"],
+  },
+  {
+    name: "internal-api",
+    source: browserMcpConfigPath,
+    enabled: true,
+    exposure: "deferred",
+    kind: "http",
+    transport: "http://localhost:8321/mcp",
+    usesOAuth: true,
+    // OAuth-shaped by config but never signed in: connected, no Sign out.
+    hasStoredCredentials: false,
+    state: "connected",
+    tools: ["get_status"],
+  },
   {
     name: "legacy-db",
     source: browserMcpConfigPath,
@@ -83,6 +111,7 @@ const browserMcpServers: BrowserMcpServer[] = [
     kind: "stdio",
     transport: "node scripts/db-mcp-server.js",
     usesOAuth: false,
+    hasStoredCredentials: false,
     state: "failed",
     tools: [],
     error: 'MCP server "legacy-db" failed to connect: spawn node ENOENT',
@@ -95,6 +124,7 @@ const browserMcpServers: BrowserMcpServer[] = [
     kind: "stdio",
     transport: "npx -y @playwright/mcp@latest",
     usesOAuth: false,
+    hasStoredCredentials: false,
     state: "connected",
     tools: ["browser_navigate", "browser_click", "browser_snapshot"],
   },
@@ -441,6 +471,7 @@ export function invokeBrowserFallback<T>(command: string, args?: InvokeArgs): Pr
         } as T);
       }
       server.state = "connected";
+      server.hasStoredCredentials = true;
       if (server.tools.length === 0) {
         server.tools = ["search_issues", "get_issue", "list_projects"];
       }
@@ -457,6 +488,14 @@ export function invokeBrowserFallback<T>(command: string, args?: InvokeArgs): Pr
           message: `MCP server "${args?.name}" does not use OAuth.`,
         } as T);
       }
+      // Pi's logout reports "No stored credentials" when nothing was stored.
+      if (!server.hasStoredCredentials) {
+        return Promise.resolve({
+          ok: false,
+          message: `No stored credentials for MCP server "${server.name}".`,
+        } as T);
+      }
+      server.hasStoredCredentials = false;
       server.state = "needs-auth";
       server.tools = [];
       return Promise.resolve({
@@ -494,6 +533,7 @@ export function invokeBrowserFallback<T>(command: string, args?: InvokeArgs): Pr
         transport,
         // No headers can be entered in this form, so HTTP adds are OAuth-able.
         usesOAuth: input.kind === "http",
+        hasStoredCredentials: false,
         state: "connected",
         tools: [],
       });