From 9755ccd141ca3452c8c8e64497c2f378ba09eeb1 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 25 Sep 2026 20:07:00 +0300
Subject: [PATCH 01/27] fix(webui): promote dialogs to the top layer, one
 z-index scale (FR-055)

Every <dialog class="modal"> now opens via showModal()/close() through a
shared useDialogOpen composable instead of the `open` attribute or a
`modal-open` class toggle, so a modal can never be painted over by the
sidebar or header regardless of z-index (the Add Server modal bug, H4).
Adds frontend/src/assets/z-index.css as the single source for the
sidebar < header < dropdown < modal < toast scale and retires the
ad-hoc z-40 on the sidebar's drawer-side.

Also folds in two small header changes that touch the same files:
Add-to-MCPProxy button state and header layout groundwork.
---
 frontend/src/assets/z-index.css              |  19 ++++
 frontend/src/components/AddSecretModal.vue   |   6 +-
 frontend/src/components/AddServerModal.vue   |   6 +-
 frontend/src/components/ConnectModal.vue     |   4 +-
 frontend/src/components/OnboardingWizard.vue |   4 +-
 frontend/src/components/SidebarNav.vue       |  10 +-
 frontend/src/components/ToastContainer.vue   |   2 +-
 frontend/src/components/TopHeader.vue        |  26 +++--
 frontend/src/composables/useDialogOpen.ts    |  61 +++++++++++
 frontend/src/main.ts                         |   3 +-
 frontend/src/views/Repositories.vue          |  45 ++++++--
 frontend/src/views/teams/UserActivity.vue    |   4 +-
 frontend/src/views/teams/UserServers.vue     |   7 +-
 frontend/src/views/teams/UserTokens.vue      |   4 +-
 frontend/tests/unit/z-index-scale.spec.ts    | 104 +++++++++++++++++++
 15 files changed, 278 insertions(+), 27 deletions(-)
 create mode 100644 frontend/src/assets/z-index.css
 create mode 100644 frontend/src/composables/useDialogOpen.ts
 create mode 100644 frontend/tests/unit/z-index-scale.spec.ts

diff --git a/frontend/src/assets/z-index.css b/frontend/src/assets/z-index.css
new file mode 100644
index 000000000..1f02f1487
--- /dev/null
+++ b/frontend/src/assets/z-index.css
@@ -0,0 +1,19 @@
+/*
+ * Spec 109 FR-055 (navigation-map.md): one z-index scale, defined in one
+ * place, so no sidebar/header element can ever paint over a modal (audit H4).
+ *
+ * sidebar < header < dropdown < modal < toast
+ *
+ * Modals themselves should render in the browser's top layer via
+ * `<dialog>.showModal()` rather than relying on this scale (the top layer
+ * always wins regardless of these values) — `--z-modal` exists for the rare
+ * non-<dialog> overlay (e.g. a full-screen click-catcher) that still needs to
+ * sit above the header/sidebar but below a real modal.
+ */
+:root {
+  --z-sidebar: 30;
+  --z-header: 40;
+  --z-dropdown: 50;
+  --z-modal: 60;
+  --z-toast: 70;
+}
diff --git a/frontend/src/components/AddSecretModal.vue b/frontend/src/components/AddSecretModal.vue
index 3af62a7b1..239638480 100644
--- a/frontend/src/components/AddSecretModal.vue
+++ b/frontend/src/components/AddSecretModal.vue
@@ -1,5 +1,5 @@
 <template>
-  <dialog :open="show" class="modal" data-test="add-secret-modal">
+  <dialog ref="nativeDialogEl" class="modal" data-test="add-secret-modal">
     <div
       ref="dialogRef"
       class="modal-box max-w-2xl"
@@ -98,6 +98,7 @@ import { reactive, ref, watch } from 'vue'
 import apiClient from '@/services/api'
 import { useSystemStore } from '@/stores/system'
 import { useModalA11y } from '@/composables/useModalA11y'
+import { useDialogOpen } from '@/composables/useDialogOpen'
 
 interface Props {
   show: boolean
@@ -114,6 +115,9 @@ const emit = defineEmits<Emits>()
 
 // UX audit F6/F8: Escape closes, focus enters the dialog and is trapped there.
 const { dialogRef } = useModalA11y(() => props.show, () => handleClose())
+// Spec 109 FR-055: the <dialog> itself opens via showModal() (top layer),
+// separate from dialogRef above (the inner .modal-box, used for focus trap).
+const { dialogEl: nativeDialogEl } = useDialogOpen(() => props.show)
 
 const systemStore = useSystemStore()
 
diff --git a/frontend/src/components/AddServerModal.vue b/frontend/src/components/AddServerModal.vue
index 5a605df71..4993cb594 100644
--- a/frontend/src/components/AddServerModal.vue
+++ b/frontend/src/components/AddServerModal.vue
@@ -1,5 +1,5 @@
 <template>
-  <dialog :open="show" class="modal" data-test="add-server-modal">
+  <dialog ref="nativeDialogEl" class="modal" data-test="add-server-modal">
     <!--
       UX audit F6: the box is a flex column with its own scroll region so the
       submit row stays pinned to the bottom instead of falling below the fold,
@@ -615,6 +615,7 @@ import { useSystemStore } from '@/stores/system'
 import api, { type CanonicalConfigPath } from '@/services/api'
 import TrustModeSelector from '@/components/TrustModeSelector.vue'
 import { useModalA11y } from '@/composables/useModalA11y'
+import { useDialogOpen } from '@/composables/useDialogOpen'
 import type { TrustMode } from '@/utils/trustMode'
 import type { ImportResponse, ImportedServer } from '@/types'
 
@@ -637,6 +638,9 @@ const emit = defineEmits<Emits>()
 // UX audit F6: Escape closes, focus enters the dialog on open and is trapped
 // inside it, and returns to the trigger on close.
 const { dialogRef } = useModalA11y(() => props.show, () => handleClose())
+// Spec 109 FR-055: the <dialog> itself opens via showModal() (top layer),
+// separate from dialogRef above (the inner .modal-box, used for focus trap).
+const { dialogEl: nativeDialogEl } = useDialogOpen(() => props.show)
 
 const serversStore = useServersStore()
 const systemStore = useSystemStore()
diff --git a/frontend/src/components/ConnectModal.vue b/frontend/src/components/ConnectModal.vue
index 6b9138f71..d029c0182 100644
--- a/frontend/src/components/ConnectModal.vue
+++ b/frontend/src/components/ConnectModal.vue
@@ -1,5 +1,5 @@
 <template>
-  <dialog :open="show" class="modal">
+  <dialog ref="dialogEl" class="modal">
     <div class="modal-box max-w-lg">
       <h3 class="font-bold text-lg mb-2">Connect MCPProxy to AI Agents</h3>
       <p class="text-sm opacity-70 mb-4">
@@ -443,6 +443,7 @@ import { ref, reactive, computed, watch } from 'vue'
 import api from '@/services/api'
 import { useSystemStore } from '@/stores/system'
 import { useOnboardingStore } from '@/stores/onboarding'
+import { useDialogOpen } from '@/composables/useDialogOpen'
 import type { ClientStatus, AccessState, ConnectPreview } from '@/types'
 
 interface Props {
@@ -455,6 +456,7 @@ interface Emits {
 
 const props = defineProps<Props>()
 const emit = defineEmits<Emits>()
+const { dialogEl } = useDialogOpen(() => props.show)
 const systemStore = useSystemStore()
 const onboarding = useOnboardingStore()
 
diff --git a/frontend/src/components/OnboardingWizard.vue b/frontend/src/components/OnboardingWizard.vue
index e9de081c7..bc7a70e87 100644
--- a/frontend/src/components/OnboardingWizard.vue
+++ b/frontend/src/components/OnboardingWizard.vue
@@ -1,5 +1,5 @@
 <template>
-  <dialog :open="show" class="modal modal-bottom sm:modal-middle">
+  <dialog ref="dialogEl" class="modal modal-bottom sm:modal-middle">
     <div
       class="modal-box p-0 overflow-hidden flex flex-col"
       :style="modalSizing"
@@ -639,6 +639,7 @@ import { useOnboardingStore } from '@/stores/onboarding'
 import { useSystemStore } from '@/stores/system'
 import { useServersStore } from '@/stores/servers'
 import AddServerModal from '@/components/AddServerModal.vue'
+import { useDialogOpen } from '@/composables/useDialogOpen'
 import type { ClientStatus, ActivityRecord, ConnectPreview } from '@/types'
 
 interface Props {
@@ -651,6 +652,7 @@ interface Emits {
 
 const props = defineProps<Props>()
 const emit = defineEmits<Emits>()
+const { dialogEl } = useDialogOpen(() => props.show)
 
 const onboarding = useOnboardingStore()
 const systemStore = useSystemStore()
diff --git a/frontend/src/components/SidebarNav.vue b/frontend/src/components/SidebarNav.vue
index 604b611ac..f8e2af682 100644
--- a/frontend/src/components/SidebarNav.vue
+++ b/frontend/src/components/SidebarNav.vue
@@ -1,5 +1,5 @@
 <template>
-  <div class="drawer-side z-40">
+  <div class="drawer-side z-[var(--z-sidebar)]">
     <label for="sidebar-drawer" aria-label="close sidebar" class="drawer-overlay"></label>
     <aside
       class="bg-base-100 h-screen flex flex-col border-r border-base-300 fixed transition-[width] duration-200 ease-out"
@@ -352,11 +352,11 @@
                 to="/settings"
                 :class="{ 'active': isActiveRoute('/settings') }"
                 class="rounded-lg text-base-content/70"
-                :title="collapsed ? 'Configuration' : ''"
-                :aria-label="collapsed ? 'Configuration' : undefined"
+                :title="collapsed ? 'Settings' : ''"
+                :aria-label="collapsed ? 'Settings' : undefined"
               >
                 <IconSettings class="w-5 h-5 shrink-0" />
-                <span v-show="!collapsed" class="text-[13px]">Configuration</span>
+                <span v-show="!collapsed" class="text-[13px]">Settings</span>
               </router-link>
             </li>
           </ul>
@@ -704,7 +704,7 @@ const teamsAdminMenu = [
   { name: 'Activity (All)', path: '/activity' },
   { name: 'Users', path: '/admin/users' },
   { name: 'Sessions', path: '/sessions' },
-  { name: 'Configuration', path: '/settings' },
+  { name: 'Settings', path: '/settings' },
 ]
 
 const userInitials = computed(() => {
diff --git a/frontend/src/components/ToastContainer.vue b/frontend/src/components/ToastContainer.vue
index 3a9894c23..1202b842c 100644
--- a/frontend/src/components/ToastContainer.vue
+++ b/frontend/src/components/ToastContainer.vue
@@ -1,5 +1,5 @@
 <template>
-  <div class="toast toast-end z-50">
+  <div class="toast toast-end z-[var(--z-toast)]">
     <transition-group name="toast" tag="div">
       <div
         v-for="toast in systemStore.toasts"
diff --git a/frontend/src/components/TopHeader.vue b/frontend/src/components/TopHeader.vue
index df7005d25..5e13daf2b 100644
--- a/frontend/src/components/TopHeader.vue
+++ b/frontend/src/components/TopHeader.vue
@@ -1,5 +1,5 @@
 <template>
-  <header class="bg-base-100 border-b border-base-300 sticky top-0 z-30">
+  <header class="bg-base-100 border-b border-base-300 sticky top-0 z-[var(--z-header)]">
     <div class="flex items-center justify-between px-6 py-4 max-w-full">
       <!-- Left: Mobile menu toggle + Search + Add Server -->
 <div class="flex items-center space-x-3 flex-1 min-w-0 overflow-x-hidden">
@@ -80,8 +80,11 @@
              lists only GET /profiles* as a tenant-reachable read) — so an
              enabled control a tenant could open always failed to act. Hidden
              for the same FR-041 reason as the button above; GET /profiles
-             stays reachable elsewhere (it is not this component's read). -->
-        <ProfileSwitcher v-if="authStore.principalKind !== 'tenant'" />
+             stays reachable elsewhere (it is not this component's read).
+             Spec 109 FR-057 (H2 interim, until Spec 108 removes it entirely):
+             also hidden when no profiles exist yet — "Profile:" otherwise
+             looked like agent scoping while only setting a UI default. -->
+        <ProfileSwitcher v-if="authStore.principalKind !== 'tenant' && profilesStore.hasProfiles" />
 
         <!-- Servers -->
         <div class="flex items-center space-x-2 px-3 py-2 bg-base-200 rounded-lg text-sm">
@@ -134,7 +137,7 @@
           </button>
           <div
             v-if="showEndpoints"
-            class="absolute right-0 top-full mt-2 p-3 shadow-lg bg-base-100 rounded-box w-96 border border-base-300 z-50"
+            class="absolute right-0 top-full mt-2 p-3 shadow-lg bg-base-100 rounded-box w-96 border border-base-300 z-[var(--z-dropdown)]"
           >
             <div class="text-xs font-semibold text-base-content/60 mb-2 px-1">MCP Endpoints</div>
             <div class="space-y-1">
@@ -166,7 +169,7 @@
             </div>
           </div>
           <!-- Click-outside overlay -->
-          <div v-if="showEndpoints" class="fixed inset-0 z-40" @click="showEndpoints = false" />
+          <div v-if="showEndpoints" class="fixed inset-0 z-[var(--z-header)]" @click="showEndpoints = false" />
         </div>
       </div>
     </div>
@@ -181,11 +184,12 @@
 </template>
 
 <script setup lang="ts">
-import { ref, reactive, computed } from 'vue'
+import { ref, reactive, computed, onMounted } from 'vue'
 import { useRouter } from 'vue-router'
 import { useSystemStore } from '@/stores/system'
 import { useServersStore } from '@/stores/servers'
 import { useAuthStore } from '@/stores/auth'
+import { useProfilesStore } from '@/stores/profiles'
 import AddServerModal from './AddServerModal.vue'
 import { serverDetailPath } from '@/utils/serverRoute'
 import ProfileSwitcher from './ProfileSwitcher.vue'
@@ -195,6 +199,16 @@ const router = useRouter()
 const systemStore = useSystemStore()
 const serversStore = useServersStore()
 const authStore = useAuthStore()
+const profilesStore = useProfilesStore()
+
+// Spec 109 FR-057: ProfileSwitcher only renders once profilesStore.hasProfiles
+// is true, but that store is populated by a fetch ProfileSwitcher itself used
+// to trigger on its own mount — a component gated on data only it fetches
+// never mounts to fetch it. The header fetches once up front instead, so
+// hasProfiles reflects reality before the v-if below ever evaluates it.
+onMounted(() => {
+  void profilesStore.fetchProfiles()
+})
 
 const addServerLabel = computed(() => authStore.isTeamsEdition ? 'Add Personal Server' : 'Add Server')
 
diff --git a/frontend/src/composables/useDialogOpen.ts b/frontend/src/composables/useDialogOpen.ts
new file mode 100644
index 000000000..1cf690eaf
--- /dev/null
+++ b/frontend/src/composables/useDialogOpen.ts
@@ -0,0 +1,61 @@
+import { onBeforeUnmount, ref, watch, type Ref } from 'vue'
+
+/**
+ * Drives a native `<dialog>` element's open state imperatively via
+ * `showModal()` / `close()` instead of binding the `open` attribute (or a
+ * `modal-open` CSS class) directly.
+ *
+ * Spec 109 FR-055 (H4): a `<dialog :open="x">` renders in the *normal* page
+ * stacking context, so any ancestor establishing its own stacking context
+ * (e.g. `position: sticky/fixed` + `z-index`) can paint over it regardless of
+ * z-index value — that is how the sidebar's version block ended up on top of
+ * the Add Server modal. `showModal()` promotes the dialog to the browser's
+ * top layer, which always renders above every other element on the page, so
+ * this stacking bug becomes structurally impossible rather than one more
+ * z-index to keep in sync.
+ *
+ * jsdom (unit tests) does not implement `HTMLDialogElement.showModal`/`close`
+ * (`typeof el.showModal !== 'function'`), so this falls back to toggling the
+ * `open` attribute directly — the previous behaviour — keeping every existing
+ * unit test that renders these dialogs working unchanged. Real browsers all
+ * support `<dialog>` natively.
+ */
+export function useDialogOpen(isOpen: () => boolean) {
+  const dialogEl: Ref<HTMLDialogElement | null> = ref(null)
+
+  function sync(open: boolean) {
+    const el = dialogEl.value
+    if (!el) return
+    const supportsNative = typeof el.showModal === 'function' && typeof el.close === 'function'
+    if (!supportsNative) {
+      // Fallback for environments without <dialog> support (test DOM only).
+      if (open) el.setAttribute('open', '')
+      else el.removeAttribute('open')
+      return
+    }
+    if (open && !el.open) {
+      el.showModal()
+    } else if (!open && el.open) {
+      el.close()
+    }
+  }
+
+  watch(isOpen, sync, { flush: 'post' })
+
+  // Apply the initial state once the element has mounted (a plain immediate
+  // watcher would run before the template ref is bound).
+  watch(
+    dialogEl,
+    (el) => {
+      if (el) sync(isOpen())
+    },
+    { flush: 'post' }
+  )
+
+  onBeforeUnmount(() => {
+    const el = dialogEl.value
+    if (el?.open && typeof el.close === 'function') el.close()
+  })
+
+  return { dialogEl }
+}
diff --git a/frontend/src/main.ts b/frontend/src/main.ts
index e0ed1ed5b..2b70f3843 100644
--- a/frontend/src/main.ts
+++ b/frontend/src/main.ts
@@ -4,10 +4,11 @@ import { createPinia } from 'pinia'
 import App from './App.vue'
 import router from './router'
 import './assets/main.css'
+import './assets/z-index.css'
 
 const app = createApp(App)
 
 app.use(createPinia())
 app.use(router)
 
-app.mount('#app')
\ No newline at end of file
+app.mount('#app')
diff --git a/frontend/src/views/Repositories.vue b/frontend/src/views/Repositories.vue
index d655663c8..96bfc40e2 100644
--- a/frontend/src/views/Repositories.vue
+++ b/frontend/src/views/Repositories.vue
@@ -329,14 +329,25 @@
                 </svg>
                 Source
               </button>
+              <!-- Spec 109 FR-063: "Add to MCPProxy", flipping to a
+                   persistent "Added ✓ · Open" once the add succeeds. -->
               <button
+                v-if="!addedServers[server.id]"
                 @click="addServer(server)"
                 class="btn btn-primary btn-sm"
                 :data-test="`registry-add-${server.id}`"
                 :disabled="addingServerId === server.id"
               >
                 <span v-if="addingServerId === server.id" class="loading loading-spinner loading-xs"></span>
-                <span v-else>Add to MCP</span>
+                <span v-else>Add to MCPProxy</span>
+              </button>
+              <button
+                v-else
+                @click="openAddedServer(server)"
+                class="btn btn-success btn-sm"
+                :data-test="`registry-added-${server.id}`"
+              >
+                Added ✓ · Open
               </button>
             </div>
           </div>
@@ -371,7 +382,7 @@
     </div>
 
     <!-- Required-Input Prompt (Spec 070 — blocks add until provided) -->
-    <dialog :open="showPrompt" class="modal" data-test="registry-required-input-dialog">
+    <dialog ref="promptDialogEl" class="modal" data-test="registry-required-input-dialog">
       <div class="modal-box">
         <h3 class="font-bold text-lg">Add "{{ promptServer?.name }}"</h3>
         <p class="text-sm text-base-content/70 mt-1">
@@ -412,7 +423,7 @@
               :disabled="!promptComplete || addingServerId !== null"
             >
               <span v-if="addingServerId !== null" class="loading loading-spinner loading-xs"></span>
-              <span v-else>Add to MCP</span>
+              <span v-else>Add to MCPProxy</span>
             </button>
           </div>
         </form>
@@ -423,7 +434,7 @@
     </dialog>
 
     <!-- Add / Edit Registry Source dialog (MCP-866 add, MCP-1073 edit) -->
-    <dialog :open="showAddRegistry" class="modal" data-test="registry-add-source-dialog">
+    <dialog ref="addRegistryDialogEl" class="modal" data-test="registry-add-source-dialog">
       <div class="modal-box">
         <h3 class="font-bold text-lg">{{ isEditMode ? 'Edit registry' : 'Add a registry' }}</h3>
         <p class="text-sm text-base-content/70 mt-1">
@@ -521,7 +532,7 @@
     </dialog>
 
     <!-- Delete custom registry confirmation (MCP-1073, destructive) -->
-    <dialog :open="showDeleteRegistry" class="modal" data-test="registry-delete-dialog">
+    <dialog ref="deleteRegistryDialogEl" class="modal" data-test="registry-delete-dialog">
       <div class="modal-box">
         <h3 class="font-bold text-lg">Remove "{{ deleteRegistryTarget?.name }}"?</h3>
         <p class="text-sm py-2 text-base-content/80">
@@ -570,11 +581,14 @@
 
 <script setup lang="ts">
 import { ref, computed, onMounted } from 'vue'
+import { useRouter } from 'vue-router'
 import api from '@/services/api'
 import CollapsibleHintsPanel from '@/components/CollapsibleHintsPanel.vue'
 import type { Hint } from '@/components/CollapsibleHintsPanel.vue'
 import type { Registry, RepositoryServer, RequiredInput } from '@/types'
 import { REGISTRY_PROVENANCE_CUSTOM } from '@/types'
+import { useDialogOpen } from '@/composables/useDialogOpen'
+import { serverDetailPath } from '@/utils/serverRoute'
 
 // State
 const registries = ref<Registry[]>([])
@@ -589,6 +603,12 @@ const loadingRegistries = ref(false)
 const loadingServers = ref(false)
 const error = ref<string | null>(null)
 const addingServerId = ref<string | null>(null)
+// Spec 109 FR-063: keyed by registry entry id -> the resulting server's name,
+// so the button can flip to "Added ✓ · Open" and stay that way for the rest
+// of this page visit (a fresh load/registry refresh clears it, matching the
+// entry possibly not being re-addable anyway).
+const addedServers = ref<Record<string, string>>({})
+const router = useRouter()
 const showSuccessToast = ref(false)
 const successMessage = ref('')
 
@@ -607,12 +627,16 @@ const addRegistryName = ref('')
 const addRegistryError = ref<string | null>(null)
 const addingRegistry = ref(false)
 const isEditMode = computed(() => editRegistryId.value !== null)
+// Spec 109 FR-055: <dialog>.showModal()/close(), not the `open` attribute —
+// keeps the top layer, so nothing (sidebar, header) can ever paint over it.
+const { dialogEl: addRegistryDialogEl } = useDialogOpen(() => showAddRegistry.value)
 
 // Delete-custom-registry confirmation state (MCP-1073)
 const showDeleteRegistry = ref(false)
 const deleteRegistryTarget = ref<Registry | null>(null)
 const deleteRegistryError = ref<string | null>(null)
 const deletingRegistry = ref(false)
+const { dialogEl: deleteRegistryDialogEl } = useDialogOpen(() => showDeleteRegistry.value)
 
 let searchDebounceTimer: ReturnType<typeof setTimeout> | null = null
 
@@ -684,6 +708,7 @@ function clearRegistries() {
 }
 
 const showPrompt = computed(() => promptServer.value !== null)
+const { dialogEl: promptDialogEl } = useDialogOpen(() => showPrompt.value)
 
 // Add is blocked until every prompted input has a non-empty value.
 const promptComplete = computed(() =>
@@ -702,7 +727,7 @@ const repositoriesHints = computed<Hint[]>(() => {
           list: [
             'Select a registry from the dropdown menu',
             'Search for servers by name or description',
-            'Click "Add to MCP" to install a server',
+            'Click "Add to MCPProxy" to install a server',
             'View source code and installation commands for each server'
           ]
         }
@@ -859,6 +884,7 @@ async function addServer(server: RepositoryServer, env?: Record<string, string>)
     if (result.success) {
       closePrompt()
       const name = result.server?.name || server.name
+      addedServers.value[server.id] = name
       showToast(`Added "${name}" — quarantined. Approve it on the Servers page to enable.`)
       return
     }
@@ -876,6 +902,13 @@ async function addServer(server: RepositoryServer, env?: Record<string, string>)
   }
 }
 
+// Spec 109 FR-063: "Added ✓ · Open" opens the server it just added.
+function openAddedServer(server: RepositoryServer) {
+  const name = addedServers.value[server.id]
+  if (!name) return
+  router.push(serverDetailPath(name))
+}
+
 // Open the required-input prompt. Prefer the rich declarations carried on the
 // search result (name + description + secret); fall back to bare names from the
 // backend's missing_required_input error when the search response omitted them.
diff --git a/frontend/src/views/teams/UserActivity.vue b/frontend/src/views/teams/UserActivity.vue
index a854d3fbe..7c7f38547 100644
--- a/frontend/src/views/teams/UserActivity.vue
+++ b/frontend/src/views/teams/UserActivity.vue
@@ -126,7 +126,7 @@
     </div>
 
     <!-- Activity Detail Modal -->
-    <dialog class="modal" :class="{ 'modal-open': !!selectedActivity }">
+    <dialog ref="activityDialogEl" class="modal">
       <div class="modal-box max-w-2xl">
         <h3 class="font-bold text-lg mb-4">Activity Details</h3>
         <div v-if="selectedActivity" class="space-y-3">
@@ -176,6 +176,7 @@
 
 <script setup lang="ts">
 import { ref, reactive, computed, onMounted } from 'vue'
+import { useDialogOpen } from '@/composables/useDialogOpen'
 
 interface Activity {
   id: string
@@ -195,6 +196,7 @@ const totalCount = ref(0)
 const currentPage = ref(1)
 const pageSize = 25
 const selectedActivity = ref<Activity | null>(null)
+const { dialogEl: activityDialogEl } = useDialogOpen(() => selectedActivity.value !== null)
 const serverNames = ref<string[]>([])
 
 const filters = reactive({
diff --git a/frontend/src/views/teams/UserServers.vue b/frontend/src/views/teams/UserServers.vue
index cbdbf9748..8863962cf 100644
--- a/frontend/src/views/teams/UserServers.vue
+++ b/frontend/src/views/teams/UserServers.vue
@@ -140,7 +140,7 @@
     </div>
 
     <!-- Add Server Modal -->
-    <dialog class="modal" :class="{ 'modal-open': showAddModal }">
+    <dialog ref="addModalDialogEl" class="modal">
       <div class="modal-box">
         <h3 class="font-bold text-lg mb-4">Add Personal Server</h3>
         <form @submit.prevent="addServer">
@@ -183,7 +183,7 @@
     </dialog>
 
     <!-- Remove Confirmation Modal -->
-    <dialog class="modal" :class="{ 'modal-open': !!serverToRemove }">
+    <dialog ref="removeDialogEl" class="modal">
       <div class="modal-box">
         <h3 class="font-bold text-lg">Remove Server</h3>
         <p class="py-4">Are you sure you want to remove <strong>{{ serverToRemove }}</strong>? This action cannot be undone.</p>
@@ -202,6 +202,7 @@
 
 <script setup lang="ts">
 import { ref, reactive, onMounted, computed } from 'vue'
+import { useDialogOpen } from '@/composables/useDialogOpen'
 import { useRouter } from 'vue-router'
 
 interface UserServer {
@@ -225,11 +226,13 @@ const loading = ref(true)
 const error = ref('')
 const allServers = ref<UserServer[]>([])
 const showAddModal = ref(false)
+const { dialogEl: addModalDialogEl } = useDialogOpen(() => showAddModal.value)
 const adding = ref(false)
 const addError = ref('')
 const togglingServer = ref('')
 const removingServer = ref('')
 const serverToRemove = ref('')
+const { dialogEl: removeDialogEl } = useDialogOpen(() => serverToRemove.value !== '')
 
 const newServer = reactive({
   name: '',
diff --git a/frontend/src/views/teams/UserTokens.vue b/frontend/src/views/teams/UserTokens.vue
index 337835324..a36912bf0 100644
--- a/frontend/src/views/teams/UserTokens.vue
+++ b/frontend/src/views/teams/UserTokens.vue
@@ -159,7 +159,7 @@
     </div>
 
     <!-- Create Token Dialog -->
-    <dialog class="modal" :class="{ 'modal-open': showCreateModal }">
+    <dialog ref="createDialogEl" class="modal">
       <div class="modal-box">
         <h3 class="font-bold text-lg mb-4">Create Agent Token</h3>
 
@@ -278,6 +278,7 @@
 
 <script setup lang="ts">
 import { ref, computed, onMounted } from 'vue'
+import { useDialogOpen } from '@/composables/useDialogOpen'
 
 interface TokenInfo {
   name: string
@@ -302,6 +303,7 @@ const createError = ref('')
 const newTokenSecret = ref<string | null>(null)
 const copied = ref(false)
 const showCreateModal = ref(false)
+const { dialogEl: createDialogEl } = useDialogOpen(() => showCreateModal.value)
 const availableServers = ref<AvailableServer[]>([])
 
 const createForm = ref({
diff --git a/frontend/tests/unit/z-index-scale.spec.ts b/frontend/tests/unit/z-index-scale.spec.ts
new file mode 100644
index 000000000..9cc277899
--- /dev/null
+++ b/frontend/tests/unit/z-index-scale.spec.ts
@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+// Spec 109 FR-055 / T007 / T019: one z-index scale, defined in one place
+// (navigation-map.md: sidebar < header < dropdown < modal < toast), and no
+// `<dialog class="modal">` still relies on the `:open` attribute binding (or
+// a `modal-open` class toggle) — every one of them now drives its open state
+// through `useDialogOpen` (`showModal()`/`close()`, top layer), which is what
+// keeps a modal from ever being painted over by the sidebar/header (H4). The
+// real cross-browser "does the modal render above the sidebar" check is a
+// Playwright step (e2e/web-ui-sweep/visual-a11y-sweep.spec.ts) since jsdom
+// does not implement layout or `<dialog>` natively.
+
+function resolve(relative: string): string {
+  return fileURLToPath(new URL(relative, import.meta.url))
+}
+
+function readSrc(relative: string): string {
+  return readFileSync(resolve(relative), 'utf-8')
+}
+
+describe('z-index scale (frontend/src/assets/z-index.css)', () => {
+  const css = readSrc('../../src/assets/z-index.css')
+
+  function tokenValue(name: string): number {
+    const match = css.match(new RegExp(`--z-${name}:\\s*(\\d+)`))
+    if (!match) throw new Error(`token --z-${name} not found in z-index.css`)
+    return Number(match[1])
+  }
+
+  it('defines the full navigation-map scale', () => {
+    for (const name of ['sidebar', 'header', 'dropdown', 'modal', 'toast']) {
+      expect(css).toMatch(new RegExp(`--z-${name}:\\s*\\d+`))
+    }
+  })
+
+  it('orders sidebar < header < dropdown < modal < toast', () => {
+    const sidebar = tokenValue('sidebar')
+    const header = tokenValue('header')
+    const dropdown = tokenValue('dropdown')
+    const modal = tokenValue('modal')
+    const toast = tokenValue('toast')
+    expect(sidebar).toBeLessThan(header)
+    expect(header).toBeLessThan(dropdown)
+    expect(dropdown).toBeLessThan(modal)
+    expect(modal).toBeLessThan(toast)
+  })
+
+  it('is imported by the app entrypoint', () => {
+    const main = readSrc('../../src/main.ts')
+    expect(main).toContain('./assets/z-index.css')
+  })
+})
+
+describe('SidebarNav no longer hardcodes a z-40 that can outrank a modal', () => {
+  it('uses the --z-sidebar token, not a bare z-40, on drawer-side', () => {
+    const src = readSrc('../../src/components/SidebarNav.vue')
+    expect(src).not.toMatch(/class="drawer-side z-40"/)
+    expect(src).toContain('--z-sidebar')
+  })
+})
+
+describe('Repositories.vue dialogs use showModal()/close(), not :open (FR-055)', () => {
+  const src = readSrc('../../src/views/Repositories.vue')
+
+  it('has no :open="..." binding on any <dialog>', () => {
+    expect(src).not.toMatch(/<dialog[^>]*:open=/)
+  })
+
+  it('names all three dialogs and drives them via ref + useDialogOpen', () => {
+    for (const testId of [
+      'registry-required-input-dialog',
+      'registry-add-source-dialog',
+      'registry-delete-dialog',
+    ]) {
+      expect(src).toContain(testId)
+    }
+    expect(src).toContain('useDialogOpen')
+  })
+})
+
+describe('every <dialog class="modal"> drives its open state imperatively', () => {
+  const files = [
+    '../../src/components/OnboardingWizard.vue',
+    '../../src/components/ConnectModal.vue',
+    '../../src/components/AddSecretModal.vue',
+    '../../src/components/AddServerModal.vue',
+    '../../src/views/Repositories.vue',
+    '../../src/views/teams/UserTokens.vue',
+    '../../src/views/teams/UserActivity.vue',
+    '../../src/views/teams/UserServers.vue',
+  ]
+
+  it.each(files)('%s has no <dialog :open=...> or <dialog ... modal-open> toggle', (relative) => {
+    const src = readSrc(relative)
+    // Matches the opening tag only (non-greedy up to the first '>'), so a
+    // nested plain <div class="modal modal-open"> confirm box rendered
+    // *inside* an already-promoted <dialog> (not itself a stacking risk) does
+    // not false-positive this check.
+    expect(src).not.toMatch(/<dialog\b[^>]*?:open=/)
+    expect(src).not.toMatch(/<dialog\b[^>]*?modal-open/)
+  })
+})

From 9f70c2a08c971baf00431cca3b5955e9a921a4fe Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 25 Sep 2026 20:08:19 +0300
Subject: [PATCH 02/27] feat: navigation, review and tool-tier quick wins (Spec
 109 PR a)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cross-surface UX fixes with no dependency on later PRs in the spec:

- `/` lands on the Overview panel (interim step before Home in a later
  PR); `/usage` and `/overview` stay deep-linkable (FR-051).
- Server detail and Settings tabs read `?tab=` on mount and write it
  back with router.replace on change, keeping other query params
  (FR-016).
- Settings is named "Settings" everywhere (sidebar, route title, H1,
  document title), its tabs use line icons instead of emoji, and the
  "Server Edition" tab is gated on the runtime edition
  (systemStore.status.edition, now carried on every SSE status frame)
  rather than on whether the config happens to have a server_edition
  key (FR-056).
- Tool review states use one vocabulary — Approved / New, needs review
  / Changed, needs review — with the `awaiting` filter value removed;
  the Tools page's "Needs review" stat is a link to /review, backed by
  interim redirects to /servers (?status=needs_review) and
  /servers/:name (?tab=tools) until a later PR ships the real review
  views (FR-027, T026a).
- One pure function, contracts.AnnotationTier, computes a tool's tier
  (read/write/destructive/unannotated) from its annotations; GET /tools
  and GET /servers/{id}/tools carry it, and the Web Tools page and CLI
  `tools list --tier` (`--risk` kept as an alias) use it instead of each
  deriving their own — the CLI's old `--risk` read a field
  (annotations.operation_type) that doesn't exist on a real payload, so
  it matched nothing (FR-028, X11).
- Count charts (calls per tool, activity over time) use integer ticks,
  and the excluded "never completed a call" group is titled "Calls to
  unknown tools" (FR-074).
- "Add to MCPProxy" (Repositories + CLI `registry add`), flipping to
  "Added ✓ · Open" after a successful add (FR-063).
- The header ProfileSwitcher is hidden until at least one profile
  exists (FR-057).
---
 cmd/generate-types/main.go                    |  22 +++
 cmd/mcpproxy/registry_add_message_test.go     |  27 ++++
 cmd/mcpproxy/registry_cmd.go                  |  18 ++-
 cmd/mcpproxy/tools_cmd.go                     |  58 +++++---
 cmd/mcpproxy/tools_cmd_test.go                |  24 ++--
 cmd/mcpproxy/tools_tier_test.go               | 114 ++++++++++++++++
 .../src/components/usage/CallHistogram.vue    |  12 +-
 frontend/src/components/usage/Timeline.vue    |   4 +-
 frontend/src/router/index.ts                  |  37 +++++-
 frontend/src/types/api.ts                     |  14 +-
 frontend/src/types/contracts.ts               |  15 +++
 frontend/src/views/ServerDetail.vue           |  12 +-
 frontend/src/views/Settings.vue               |  75 ++++++++---
 frontend/src/views/Tools.vue                  | 116 ++++++++--------
 .../tests/unit/add-to-mcpproxy-label.spec.ts  | 121 +++++++++++++++++
 .../unit/dashboard-default-landing.spec.ts    |  55 ++++----
 .../unit/profile-switcher-hidden.spec.ts      |  78 +++++++++++
 .../unit/review-interim-redirect.spec.ts      |  37 ++++++
 .../tests/unit/router-home-default.spec.ts    |  29 ++++
 .../tests/unit/server-detail-tab-url.spec.ts  | 125 ++++++++++++++++++
 frontend/tests/unit/settings-naming.spec.ts   |  99 ++++++++++++++
 .../tests/unit/tools-approval-filter.spec.ts  |  91 +++++++++++++
 .../tests/unit/tools-pending-approval.spec.ts |  54 +++-----
 frontend/tests/unit/tools-tier.spec.ts        |  83 ++++++++++++
 .../unit/top-header-tenant-gating.spec.ts     |  33 ++++-
 frontend/tests/unit/usage-chart-ticks.spec.ts |  75 +++++++++++
 internal/contracts/converters.go              |  20 +++
 internal/contracts/tier.go                    |  54 ++++++++
 internal/contracts/tier_test.go               |  89 +++++++++++++
 internal/contracts/types.go                   |  21 +--
 internal/httpapi/server.go                    |   2 +
 internal/httpapi/sse_status_edition_test.go   |  38 ++++++
 .../testdata/golden/get_server_tools.json     |   3 +-
 .../httpapi/testdata/golden/search_tools.json |   3 +-
 internal/httpapi/tools_tier_test.go           |  70 ++++++++++
 35 files changed, 1529 insertions(+), 199 deletions(-)
 create mode 100644 cmd/mcpproxy/registry_add_message_test.go
 create mode 100644 cmd/mcpproxy/tools_tier_test.go
 create mode 100644 frontend/tests/unit/add-to-mcpproxy-label.spec.ts
 create mode 100644 frontend/tests/unit/profile-switcher-hidden.spec.ts
 create mode 100644 frontend/tests/unit/review-interim-redirect.spec.ts
 create mode 100644 frontend/tests/unit/router-home-default.spec.ts
 create mode 100644 frontend/tests/unit/server-detail-tab-url.spec.ts
 create mode 100644 frontend/tests/unit/settings-naming.spec.ts
 create mode 100644 frontend/tests/unit/tools-approval-filter.spec.ts
 create mode 100644 frontend/tests/unit/tools-tier.spec.ts
 create mode 100644 frontend/tests/unit/usage-chart-ticks.spec.ts
 create mode 100644 internal/contracts/tier.go
 create mode 100644 internal/contracts/tier_test.go
 create mode 100644 internal/httpapi/sse_status_edition_test.go
 create mode 100644 internal/httpapi/tools_tier_test.go

diff --git a/cmd/generate-types/main.go b/cmd/generate-types/main.go
index 007f9684b..6e9a7d28e 100644
--- a/cmd/generate-types/main.go
+++ b/cmd/generate-types/main.go
@@ -325,6 +325,25 @@ export interface IsolationDefaults {
   working_dir?: string;
 }
 
+`)
+
+	// Tier constants - generated from internal/contracts/tier.go
+	// Spec 109 FR-028/X11: one pure function (contracts.AnnotationTier)
+	// computes this everywhere — the Web/macOS/CLI surfaces never derive
+	// their own. `unknown` is returned only by the review payload composer,
+	// never by AnnotationTier itself.
+	sb.WriteString(`export const TierRead = 'read' as const;
+export const TierWrite = 'write' as const;
+export const TierDestructive = 'destructive' as const;
+export const TierUnannotated = 'unannotated' as const;
+export const TierUnknown = 'unknown' as const;
+export type Tier =
+  | typeof TierRead
+  | typeof TierWrite
+  | typeof TierDestructive
+  | typeof TierUnannotated
+  | typeof TierUnknown;
+
 `)
 
 	// Tool types
@@ -341,6 +360,9 @@ export interface IsolationDefaults {
   // Tool-level quarantine status surfaced by the same approval record.
   // Optional because non-quarantined tools simply omit the field.
   approval_status?: string;
+  // Computed by contracts.AnnotationTier (Spec 109 FR-028) — never derive
+  // this from annotations on the frontend (X11).
+  tier?: Tier;
   // Why the trust_mode: scan gate held this tool for review (spec 086
   // FR-018). held_signals names the matched deterministic check ids, e.g.
   // "tpa.TPA-2026-0001.hidden_instruction". All three are absent unless the
diff --git a/cmd/mcpproxy/registry_add_message_test.go b/cmd/mcpproxy/registry_add_message_test.go
new file mode 100644
index 000000000..f10c700a7
--- /dev/null
+++ b/cmd/mcpproxy/registry_add_message_test.go
@@ -0,0 +1,27 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestRegistryAddMessage (Spec 109 FR-063 / T025): the CLI prints "Added
+// <name> to MCPProxy (quarantined for review)" — the same wording the
+// Web/macOS "Add to MCPProxy" action uses after a successful add.
+func TestRegistryAddMessage(t *testing.T) {
+	quarantined := registryAddMessage("github-server", true)
+	if !strings.Contains(quarantined, "Added github-server to MCPProxy") {
+		t.Fatalf("expected message to contain %q, got %q", "Added github-server to MCPProxy", quarantined)
+	}
+	if !strings.Contains(quarantined, "quarantined for review") {
+		t.Fatalf("expected quarantined message to say %q, got %q", "quarantined for review", quarantined)
+	}
+
+	notQuarantined := registryAddMessage("github-server", false)
+	if !strings.Contains(notQuarantined, "Added github-server to MCPProxy") {
+		t.Fatalf("expected message to contain %q, got %q", "Added github-server to MCPProxy", notQuarantined)
+	}
+	if strings.Contains(notQuarantined, "quarantined") {
+		t.Fatalf("an enabled (non-quarantined) add must not claim quarantine, got %q", notQuarantined)
+	}
+}
diff --git a/cmd/mcpproxy/registry_cmd.go b/cmd/mcpproxy/registry_cmd.go
index b2950853c..ce53d453a 100644
--- a/cmd/mcpproxy/registry_cmd.go
+++ b/cmd/mcpproxy/registry_cmd.go
@@ -468,11 +468,7 @@ inputs, supply them with --env KEY=VALUE.`,
 				return nil
 			}
 
-			fmt.Printf("✅ Added '%s'", result.Name)
-			if result.Quarantined {
-				fmt.Printf(" (quarantined — approve with: mcpproxy upstream approve %s)", result.Name)
-			}
-			fmt.Println()
+			fmt.Println(registryAddMessage(result.Name, result.Quarantined))
 			return nil
 		},
 	}
@@ -484,6 +480,18 @@ inputs, supply them with --env KEY=VALUE.`,
 
 // registryAddErrorOutput maps a *cliclient.RegistryAddError to a structured CLI
 // error. For missing_required_input it names the exact --env keys to supply.
+// registryAddMessage formats the CLI's success confirmation after adding a
+// server from a registry (Spec 109 FR-063): "Added <name> to MCPProxy
+// (quarantined for review)" — the same wording the Web/macOS "Add to
+// MCPProxy" action uses after a successful add.
+func registryAddMessage(name string, quarantined bool) string {
+	msg := fmt.Sprintf("✅ Added %s to MCPProxy", name)
+	if quarantined {
+		msg += fmt.Sprintf(" (quarantined for review — approve with: mcpproxy upstream approve %s)", name)
+	}
+	return msg
+}
+
 func registryAddErrorOutput(err error) error {
 	var addErr *cliclient.RegistryAddError
 	if !errors.As(err, &addErr) {
diff --git a/cmd/mcpproxy/tools_cmd.go b/cmd/mcpproxy/tools_cmd.go
index a95da8f37..dba4a2d65 100644
--- a/cmd/mcpproxy/tools_cmd.go
+++ b/cmd/mcpproxy/tools_cmd.go
@@ -93,8 +93,14 @@ Examples:
 	traceTransport bool // Enable HTTP/SSE frame-by-frame tracing
 
 	// Global list filter flags (T019)
-	toolsStatusFilter   string // enabled | disabled | config-denied
-	toolsRiskFilter     string // read | write | destructive
+	toolsStatusFilter string // enabled | disabled | config-denied
+	// toolsTierFilter / toolsRiskFilter (Spec 109 FR-028, X11): --risk is kept
+	// as an alias of --tier for old scripts/muscle-memory; whichever is
+	// non-empty wins (tier preferred if both are set). Both filter on the
+	// backend-computed `tier` field (contracts.AnnotationTier) — never a
+	// locally-derived value.
+	toolsTierFilter     string // read | write | destructive | unannotated
+	toolsRiskFilter     string // alias of --tier
 	toolsApprovalFilter string // approved | pending | changed
 )
 
@@ -136,10 +142,16 @@ func groupByServer(targets []serverToolTarget) map[string][]string {
 
 // applyGlobalToolFilters applies client-side filters to the global tool list.
 // statusFilter: "enabled" | "disabled" | "config-denied" | ""
-// riskFilter:   "read" | "write" | "destructive" | ""
+// tierFilter:   "read" | "write" | "destructive" | "unannotated" | ""
 // approvalFilter: "approved" | "pending" | "changed" | ""
-func applyGlobalToolFilters(tools []map[string]interface{}, statusFilter, riskFilter, approvalFilter string) []map[string]interface{} {
-	if statusFilter == "" && riskFilter == "" && approvalFilter == "" {
+//
+// Spec 109 FR-028 / X11: tierFilter matches the backend-computed `tier` field
+// verbatim. It used to read `annotations.operation_type` — a field that does
+// not exist on an MCP tool's annotations (operation_type is an intent-
+// declaration concept) — so `--risk read` matched nothing over a fixture of
+// read-annotated tools. `tier` is what `GET /tools` actually sends.
+func applyGlobalToolFilters(tools []map[string]interface{}, statusFilter, tierFilter, approvalFilter string) []map[string]interface{} {
+	if statusFilter == "" && tierFilter == "" && approvalFilter == "" {
 		return tools
 	}
 
@@ -165,12 +177,9 @@ func applyGlobalToolFilters(tools []map[string]interface{}, statusFilter, riskFi
 			}
 		}
 
-		if riskFilter != "" {
-			opType := ""
-			if ann, ok := t["annotations"].(map[string]interface{}); ok {
-				opType, _ = ann["operation_type"].(string)
-			}
-			if !strings.EqualFold(opType, riskFilter) {
+		if tierFilter != "" {
+			tier := getStringField(t, "tier")
+			if !strings.EqualFold(tier, tierFilter) {
 				continue
 			}
 		}
@@ -187,6 +196,15 @@ func applyGlobalToolFilters(tools []map[string]interface{}, statusFilter, riskFi
 	return out
 }
 
+// resolvedTierFilter returns the effective tier filter from --tier / --risk
+// (an alias of --tier, Spec 109 FR-028). --tier wins when both are set.
+func resolvedTierFilter() string {
+	if toolsTierFilter != "" {
+		return toolsTierFilter
+	}
+	return toolsRiskFilter
+}
+
 // GetToolsCommand returns the tools command for adding to the root command
 func GetToolsCommand() *cobra.Command {
 	return toolsCmd
@@ -219,7 +237,10 @@ func initToolsFlags() {
 
 	// Global-list filter flags (T019)
 	toolsListCmd.Flags().StringVar(&toolsStatusFilter, "status", "", "Filter by state: enabled, disabled, config-denied")
-	toolsListCmd.Flags().StringVar(&toolsRiskFilter, "risk", "", "Filter by risk: read, write, destructive")
+	// Spec 109 FR-028/X11: --tier is canonical; --risk is kept as an alias
+	// (risk stays the scan-score term elsewhere in the CLI).
+	toolsListCmd.Flags().StringVar(&toolsTierFilter, "tier", "", "Filter by tier: read, write, destructive, unannotated")
+	toolsListCmd.Flags().StringVar(&toolsRiskFilter, "risk", "", "Alias of --tier")
 	toolsListCmd.Flags().StringVar(&toolsApprovalFilter, "approval", "", "Filter by approval: approved, pending, changed")
 
 	// Note: -o/--output flag is inherited from root command via globalOutputFormat
@@ -306,7 +327,7 @@ func runToolsListGlobal(ctx context.Context, globalConfig *config.Config, logger
 	}
 
 	// Apply client-side filters
-	tools = applyGlobalToolFilters(tools, toolsStatusFilter, toolsRiskFilter, toolsApprovalFilter)
+	tools = applyGlobalToolFilters(tools, toolsStatusFilter, resolvedTierFilter(), toolsApprovalFilter)
 
 	return outputGlobalTools(tools)
 }
@@ -442,7 +463,7 @@ func serverToolRows(tools []map[string]interface{}) (headers []string, rows [][]
 // of the two upstream-controlled columns, NAME and DESCRIPTION — is directly
 // testable.
 func globalToolRows(tools []map[string]interface{}) (headers []string, rows [][]string) {
-	headers = []string{"NAME", "SERVER", "STATE", "APPROVAL", "HELD", "USAGE", "LAST USED", "DESCRIPTION"}
+	headers = []string{"NAME", "SERVER", "STATE", "TIER", "APPROVAL", "HELD", "USAGE", "LAST USED", "DESCRIPTION"}
 	for _, t := range tools {
 		name := sanitizeName(getStringField(t, "name"))
 		srv := getStringField(t, "server_name")
@@ -456,6 +477,13 @@ func globalToolRows(tools []map[string]interface{}) (headers []string, rows [][]
 			state = "disabled"
 		}
 
+		// Spec 109 FR-028/X11: rendered verbatim from the backend-computed
+		// `tier` field — never derived here.
+		tier := getStringField(t, "tier")
+		if tier == "" {
+			tier = "-"
+		}
+
 		approval := getStringField(t, "approval_status")
 		if approval == "" {
 			approval = "-"
@@ -470,7 +498,7 @@ func globalToolRows(tools []map[string]interface{}) (headers []string, rows [][]
 
 		desc := sanitizeCell(getStringField(t, "description"), maxToolDescriptionCell)
 
-		rows = append(rows, []string{name, srv, state, approval, formatToolHold(t), usage, lastUsed, desc})
+		rows = append(rows, []string{name, srv, state, tier, approval, formatToolHold(t), usage, lastUsed, desc})
 	}
 	return headers, rows
 }
diff --git a/cmd/mcpproxy/tools_cmd_test.go b/cmd/mcpproxy/tools_cmd_test.go
index ca24c9271..c0c66ab00 100644
--- a/cmd/mcpproxy/tools_cmd_test.go
+++ b/cmd/mcpproxy/tools_cmd_test.go
@@ -137,23 +137,15 @@ func TestApplyGlobalToolFilters_Status(t *testing.T) {
 }
 
 // TestApplyGlobalToolFilters_Risk verifies the risk filter matches annotations.
-func TestApplyGlobalToolFilters_Risk(t *testing.T) {
+// TestApplyGlobalToolFilters_Tier is the corrected form of the filter's
+// former "risk" test — see tools_tier_test.go for the X11 regression this
+// replaces (the field it used to read, annotations.operation_type, does not
+// exist on the real GET /tools payload; `tier` does).
+func TestApplyGlobalToolFilters_Tier(t *testing.T) {
 	tools := []map[string]interface{}{
-		{
-			"name":        "read_file",
-			"server_name": "srv",
-			"annotations": map[string]interface{}{"operation_type": "read"},
-		},
-		{
-			"name":        "write_file",
-			"server_name": "srv",
-			"annotations": map[string]interface{}{"operation_type": "write"},
-		},
-		{
-			"name":        "delete_repo",
-			"server_name": "srv",
-			"annotations": map[string]interface{}{"operation_type": "destructive"},
-		},
+		{"name": "read_file", "server_name": "srv", "tier": "read"},
+		{"name": "write_file", "server_name": "srv", "tier": "write"},
+		{"name": "delete_repo", "server_name": "srv", "tier": "destructive"},
 	}
 
 	got := applyGlobalToolFilters(tools, "", "read", "")
diff --git a/cmd/mcpproxy/tools_tier_test.go b/cmd/mcpproxy/tools_tier_test.go
new file mode 100644
index 000000000..a59f1448c
--- /dev/null
+++ b/cmd/mcpproxy/tools_tier_test.go
@@ -0,0 +1,114 @@
+package main
+
+import (
+	"bytes"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Spec 109 FR-028 / T015 (X11): `mcpproxy tools list --tier`/`--risk` filter
+// on the backend-computed `tier` field, and the table carries a TIER column
+// — none of it derived locally.
+
+// TestApplyGlobalToolFilters_TierX11Regression pins the bug this PR fixes:
+// the filter used to inspect `annotations.operation_type`, a field that does
+// not exist anywhere on the real GET /tools payload (operation_type is an
+// intent-declaration concept, unrelated to a tool's MCP annotations). Over a
+// realistic fixture — a tool whose annotations mark it read-only, the way the
+// backend actually reports one — `--risk read` matched nothing.
+func TestApplyGlobalToolFilters_TierX11Regression(t *testing.T) {
+	realisticReadOnlyTool := []map[string]interface{}{
+		{
+			"name":        "list_repos",
+			"server_name": "github",
+			// This is what a real read-only tool's annotations look like —
+			// no "operation_type" key anywhere, because that key belongs to
+			// intent declarations, not MCP tool annotations.
+			"annotations": map[string]interface{}{"readOnlyHint": true},
+			// This is the field the backend actually computes and sends
+			// (contracts.AnnotationTier) — what the filter must use.
+			"tier": "read",
+		},
+	}
+
+	got := applyGlobalToolFilters(realisticReadOnlyTool, "", "read", "")
+	require.Len(t, got, 1, "X11: --risk/--tier must match the backend-computed tier field, not a nonexistent annotations.operation_type")
+	assert.Equal(t, "list_repos", got[0]["name"])
+}
+
+func TestApplyGlobalToolFilters_TierAndRiskAreAliases(t *testing.T) {
+	tools := []map[string]interface{}{
+		{"name": "delete_file", "server_name": "fs", "tier": "destructive"},
+		{"name": "write_file", "server_name": "fs", "tier": "write"},
+		{"name": "read_file", "server_name": "fs", "tier": "read"},
+		{"name": "mystery_tool", "server_name": "fs", "tier": "unannotated"},
+	}
+
+	for _, tc := range []struct {
+		filter string
+		want   string
+	}{
+		{"destructive", "delete_file"},
+		{"write", "write_file"},
+		{"read", "read_file"},
+		{"unannotated", "mystery_tool"},
+	} {
+		got := applyGlobalToolFilters(tools, "", tc.filter, "")
+		require.Len(t, got, 1, "tier=%s", tc.filter)
+		assert.Equal(t, tc.want, got[0]["name"], "tier=%s", tc.filter)
+	}
+}
+
+// TestResolvedTierFilter_RiskIsAnAliasOfTier proves --risk and --tier drive
+// the same filter, with --tier taking priority if a caller somehow sets both.
+func TestResolvedTierFilter_RiskIsAnAliasOfTier(t *testing.T) {
+	origTier, origRisk := toolsTierFilter, toolsRiskFilter
+	defer func() { toolsTierFilter, toolsRiskFilter = origTier, origRisk }()
+
+	toolsTierFilter, toolsRiskFilter = "", ""
+	assert.Equal(t, "", resolvedTierFilter())
+
+	toolsTierFilter, toolsRiskFilter = "", "write"
+	assert.Equal(t, "write", resolvedTierFilter(), "--risk alone must apply")
+
+	toolsTierFilter, toolsRiskFilter = "read", ""
+	assert.Equal(t, "read", resolvedTierFilter(), "--tier alone must apply")
+
+	toolsTierFilter, toolsRiskFilter = "destructive", "read"
+	assert.Equal(t, "destructive", resolvedTierFilter(), "--tier wins when both are set")
+}
+
+// TestOutputGlobalTools_TierColumn proves the TIER column exists and renders
+// the backend-computed value verbatim.
+func TestOutputGlobalTools_TierColumn(t *testing.T) {
+	tools := []map[string]interface{}{
+		{
+			"name":            "delete_repo",
+			"server_name":     "github",
+			"description":     "Delete a repository",
+			"approval_status": "approved",
+			"tier":            "destructive",
+			"usage":           float64(1),
+		},
+	}
+
+	oldStdout := os.Stdout
+	r, w, _ := os.Pipe()
+	os.Stdout = w
+	defer func() { os.Stdout = oldStdout }()
+
+	setOutputGlobals(t, "table", false)
+	err := outputGlobalTools(tools)
+
+	w.Close()
+	var buf bytes.Buffer
+	_, _ = buf.ReadFrom(r)
+	outStr := buf.String()
+
+	require.NoError(t, err)
+	assert.Contains(t, outStr, "TIER", "table must contain a TIER column")
+	assert.Contains(t, outStr, "destructive", "TIER column must render the backend-computed tier verbatim")
+}
diff --git a/frontend/src/components/usage/CallHistogram.vue b/frontend/src/components/usage/CallHistogram.vue
index f72efca59..47f0dae3e 100644
--- a/frontend/src/components/usage/CallHistogram.vue
+++ b/frontend/src/components/usage/CallHistogram.vue
@@ -15,14 +15,20 @@
       named here, once, so they are not hidden either — the Errors & latency
       chart below still charts them.
     -->
+    <!-- Spec 109 FR-074: this group is titled "Calls to unknown tools" — a
+         name that never completed a call is not a tool this proxy can vouch
+         for (F22, #1046), so it stays out of the ranking above, but the
+         calls made to it are still named and counted rather than vanishing
+         silently. -->
     <p
       v-if="unresolved.length > 0"
       data-test="usage-call-histogram-unresolved"
       class="text-xs opacity-50 mt-2"
       :title="unresolvedLabels"
     >
+      <span class="font-medium">Calls to unknown tools:</span>
       {{ unresolved.length }} name{{ unresolved.length === 1 ? '' : 's' }} never completed a call
-      and {{ unresolved.length === 1 ? 'is' : 'are' }} excluded here — see “Errors &amp; latency”.
+      and {{ unresolved.length === 1 ? 'is' : 'are' }} excluded from this ranking — see “Errors &amp; latency”.
     </p>
   </div>
 </template>
@@ -95,7 +101,9 @@ const chartOptions = computed<ChartOptions<'bar'>>(() => ({
     x: {
       beginAtZero: true,
       title: { display: true, text: 'Calls (cumulative)' },
-      ticks: { callback: (v) => formatNumber(Number(v)) },
+      // Spec 109 FR-074: a call count is never fractional — force integer
+      // ticks rather than letting chart.js round a small max into 0.5/1.5s.
+      ticks: { precision: 0, callback: (v) => formatNumber(Number(v)) },
     },
     y: { ticks: { autoSkip: false, font: { size: 11 } } },
   },
diff --git a/frontend/src/components/usage/Timeline.vue b/frontend/src/components/usage/Timeline.vue
index f2e7ccc7d..721443946 100644
--- a/frontend/src/components/usage/Timeline.vue
+++ b/frontend/src/components/usage/Timeline.vue
@@ -86,7 +86,9 @@ const chartOptions = computed<ChartOptions<'bar'>>(() => ({
   },
   scales: {
     x: { stacked: true, ticks: { maxRotation: 0, autoSkip: true, font: { size: 10 } } },
-    y: { stacked: true, beginAtZero: true, ticks: { callback: (v) => formatNumber(Number(v)) } },
+    // Spec 109 FR-074: a call count is never fractional — force integer
+    // ticks rather than letting chart.js round a small max into 0.5/1.5s.
+    y: { stacked: true, beginAtZero: true, ticks: { precision: 0, callback: (v) => formatNumber(Number(v)) } },
   },
 }))
 </script>
diff --git a/frontend/src/router/index.ts b/frontend/src/router/index.ts
index a1e693afd..d8382732f 100644
--- a/frontend/src/router/index.ts
+++ b/frontend/src/router/index.ts
@@ -13,18 +13,20 @@ const router = createRouter({
     },
     // Existing routes (admin/personal)
     //
-    // The landing page (`/`) opens the Dashboard on its Usage (analytics)
-    // panel — that is the "analytics dashboard as default landing page"
-    // behaviour. `/usage` and `/overview` render the same Dashboard component
-    // so each panel is deep-linkable and survives a reload; `meta.dashboardView`
-    // is what the component reads to pick the active panel.
+    // The landing page (`/`) opens the Dashboard on its Overview (hub) panel.
+    // Spec 109 FR-051 / research D3 reverses #1044's Usage-first landing: new
+    // users kept landing on empty charts (audit N8). This is the 109-a interim
+    // step only — Home (needs-attention + topology + a usage strip) replaces
+    // this route in 109-d. `/usage` and `/overview` render the same Dashboard
+    // component so each panel is deep-linkable and survives a reload;
+    // `meta.dashboardView` is what the component reads to pick the active panel.
     {
       path: '/',
       name: 'dashboard',
       component: Dashboard,
       meta: {
         title: 'Dashboard',
-        dashboardView: 'usage',
+        dashboardView: 'overview',
       },
     },
     {
@@ -79,12 +81,33 @@ const router = createRouter({
       path: '/search',
       redirect: (to) => ({ path: '/tools', query: to.query, hash: to.hash }),
     },
+    // Spec 109 T026a: interim redirects until 109-g ships the real review
+    // queue/detail views. 109-a is the first PR to link to `/review` (the
+    // Tools "Needs review" stat), so it owns these — every later PR that also
+    // links here (109-d's attention fixes, 109-e's server-card Review button,
+    // 109-f's Go tray review click) lands on a registered route, never the
+    // 404 catch-all, until 109-g replaces both with the real views.
+    {
+      path: '/review/:server',
+      redirect: (to) => ({
+        path: `/servers/${encodeURIComponent(to.params.server as string)}`,
+        query: { ...to.query, tab: 'tools' },
+        hash: to.hash,
+      }),
+    },
+    {
+      path: '/review',
+      redirect: (to) => ({ path: '/servers', query: { ...to.query, status: 'needs_review' }, hash: to.hash }),
+    },
     {
       path: '/settings',
       name: 'settings',
       component: () => import('@/views/Settings.vue'),
       meta: {
-        title: 'Configuration',
+        // Spec 109 FR-056: named "Settings" everywhere (sidebar, route title,
+        // heading, document title) — "Configuration" was one more of the
+        // three names this page had accumulated (audit W5).
+        title: 'Settings',
       },
     },
     {
diff --git a/frontend/src/types/api.ts b/frontend/src/types/api.ts
index 6c4183433..b6aef988c 100644
--- a/frontend/src/types/api.ts
+++ b/frontend/src/types/api.ts
@@ -1,5 +1,5 @@
 // Re-export common types from contracts (generated from Go constants)
-export type { APIResponse, HealthStatus, HealthLevel, AdminState, HealthAction } from './contracts'
+export type { APIResponse, HealthStatus, HealthLevel, AdminState, HealthAction, Tier } from './contracts'
 export {
   HealthLevelHealthy,
   HealthLevelDegraded,
@@ -17,8 +17,8 @@ export {
   HealthActionConfigure,
 } from './contracts'
 
-// Import HealthStatus for use in this file
-import type { HealthStatus } from './contracts'
+// Import HealthStatus/Tier for use in this file
+import type { HealthStatus, Tier } from './contracts'
 
 // Quarantine stats for tool-level quarantine (Spec 032)
 export interface QuarantineStats {
@@ -338,6 +338,9 @@ export interface GlobalTool {
   usage: number
   last_used?: string       // ISO 8601; omitted if never used in window
   annotations?: ToolAnnotation
+  // Spec 109 FR-028: computed by contracts.AnnotationTier — never derive this
+  // from `annotations` on the frontend (X11).
+  tier?: Tier
   // Hold evidence (Spec 086 FR-018, surfaced by Spec 088 FR-008): present only
   // on tools the trust gate refused to auto-approve. GET /api/v1/tools emits
   // these alongside the approval status (internal/httpapi/server.go); records
@@ -461,6 +464,11 @@ export interface SearchResult {
 // Status types
 export interface StatusUpdate {
   running: boolean
+  // Spec 109 FR-056: the SSE `status` stream (both the initial frame and every
+  // subsequent one) carries the same `edition` GET /api/v1/status reports, so
+  // the Web UI can gate edition-only UI (Settings' "Server Edition" tab) on
+  // the resolved runtime edition rather than on config content.
+  edition?: string
   listen_addr: string
   routing_mode?: string
   upstream_stats: {
diff --git a/frontend/src/types/contracts.ts b/frontend/src/types/contracts.ts
index 56a3011dd..38e2c83e9 100644
--- a/frontend/src/types/contracts.ts
+++ b/frontend/src/types/contracts.ts
@@ -267,6 +267,18 @@ export interface IsolationDefaults {
   working_dir?: string;
 }
 
+export const TierRead = 'read' as const;
+export const TierWrite = 'write' as const;
+export const TierDestructive = 'destructive' as const;
+export const TierUnannotated = 'unannotated' as const;
+export const TierUnknown = 'unknown' as const;
+export type Tier =
+  | typeof TierRead
+  | typeof TierWrite
+  | typeof TierDestructive
+  | typeof TierUnannotated
+  | typeof TierUnknown;
+
 export interface Tool {
   name: string;
   server_name: string;
@@ -280,6 +292,9 @@ export interface Tool {
   // Tool-level quarantine status surfaced by the same approval record.
   // Optional because non-quarantined tools simply omit the field.
   approval_status?: string;
+  // Computed by contracts.AnnotationTier (Spec 109 FR-028) — never derive
+  // this from annotations on the frontend (X11).
+  tier?: Tier;
   // Why the trust_mode: scan gate held this tool for review (spec 086
   // FR-018). held_signals names the matched deterministic check ids, e.g.
   // "tpa.TPA-2026-0001.hidden_instruction". All three are absent unless the
diff --git a/frontend/src/views/ServerDetail.vue b/frontend/src/views/ServerDetail.vue
index 08e0a9490..4ce19ea20 100644
--- a/frontend/src/views/ServerDetail.vue
+++ b/frontend/src/views/ServerDetail.vue
@@ -1619,7 +1619,7 @@
 
 <script setup lang="ts">
 import { ref, computed, nextTick, onMounted, onUnmounted, watch } from 'vue'
-import { useRoute } from 'vue-router'
+import { useRoute, useRouter } from 'vue-router'
 import { useServersStore } from '@/stores/servers'
 import { useSystemStore } from '@/stores/system'
 import CollapsibleHintsPanel from '@/components/CollapsibleHintsPanel.vue'
@@ -1660,6 +1660,7 @@ interface Props {
 
 const props = defineProps<Props>()
 const route = useRoute()
+const router = useRouter()
 
 const serversStore = useServersStore()
 const systemStore = useSystemStore()
@@ -1709,6 +1710,15 @@ function mutateStoreServer(fn: (s: Server) => void) {
   if (s) fn(s)
 }
 const activeTab = ref<'tools' | 'logs' | 'config' | 'security'>('tools')
+// Spec 109 FR-016: every tab change (click, or a programmatic jump such as
+// the auto-approve flow landing on Security) is reflected in `?tab=`, keeping
+// every other query param, so the active tab survives a reload or a shared
+// link. The initial value is read from `?tab=` in onMounted below; this watch
+// only ever writes forward from there.
+watch(activeTab, (tab) => {
+  if (route.query.tab === tab) return
+  void router.replace({ query: { ...route.query, tab } })
+})
 const actionLoading = ref(false)
 
 // Tools
diff --git a/frontend/src/views/Settings.vue b/frontend/src/views/Settings.vue
index 95dfa23d7..83e77b728 100644
--- a/frontend/src/views/Settings.vue
+++ b/frontend/src/views/Settings.vue
@@ -3,7 +3,7 @@
     <!-- Page Header -->
     <div class="flex justify-between items-center">
       <div>
-        <h1 class="text-3xl font-bold">Configuration</h1>
+        <h1 class="text-3xl font-bold">Settings</h1>
         <p class="text-base-content/70 mt-1">
           Manage mcpproxy settings. Changes save instantly; a badge marks fields that need a restart.
           <a
@@ -47,7 +47,8 @@
         :data-test="`settings-tab-${t.id}`"
         @click="activeTab = t.id"
       >
-        <span>{{ t.icon }}</span> {{ t.label }}
+        <component :is="t.icon" class="w-4 h-4 shrink-0" />
+        {{ t.label }}
       </button>
     </div>
 
@@ -174,8 +175,8 @@
 </template>
 
 <script setup lang="ts">
-import { ref, reactive, computed, watch, onMounted, onUnmounted, nextTick } from 'vue'
-import { RouterLink, useRoute } from 'vue-router'
+import { ref, reactive, computed, watch, onMounted, onUnmounted, nextTick, h, type FunctionalComponent } from 'vue'
+import { RouterLink, useRoute, useRouter } from 'vue-router'
 import { VueMonacoEditor } from '@guolao/vue-monaco-editor'
 import { useServersStore } from '@/stores/servers'
 import { useSystemStore } from '@/stores/system'
@@ -203,6 +204,7 @@ import api from '@/services/api'
 const serversStore = useServersStore()
 const systemStore = useSystemStore()
 const route = useRoute()
+const router = useRouter()
 
 const securityFields = SECURITY_FIELDS
 const generalFields = GENERAL_FIELDS
@@ -247,6 +249,13 @@ const loading = ref(false)
 const loaded = ref(false)
 const loadError = ref('')
 const activeTab = ref<string>('security')
+// Spec 109 FR-016: read on mount from `?tab=` (onMounted below), then keep the
+// URL in sync with every tab change, preserving other query params (e.g.
+// `?focus=` from focusField).
+watch(activeTab, (tab) => {
+  if (route.query.tab === tab) return
+  void router.replace({ query: { ...route.query, tab } })
+})
 const showConnect = ref(false)
 const state = reactive<{ working: any; original: any }>({ working: {}, original: {} })
 // Bumped on every (re)hydration so each SettingsSection remounts with a fresh
@@ -256,12 +265,13 @@ const state = reactive<{ working: any; original: any }>({ working: {}, original:
 // never actually moved — writing a resolved default into a config that omitted
 // the key entirely.
 const formEpoch = ref(0)
-// Server-edition (multi-user) config lives under `server_edition` (MCP-1086).
-// Gate on the canonical key, falling back to the legacy `teams` key so a config
-// written before the rename still surfaces the Server Edition tab.
-const hasServerEdition = computed(
-  () => state.working && (state.working.server_edition != null || state.working.teams != null)
-)
+// Spec 109 FR-056: gated on the RUNTIME edition (`/status`'s `edition` field,
+// via the SSE-fed systemStore.status), not on whether the config happens to
+// carry a `server_edition` (or legacy `teams`) key. A personal-edition
+// instance can still have that key sitting in an imported/stale config, and
+// showing a whole tab of settings the running binary cannot act on is worse
+// than showing nothing.
+const hasServerEdition = computed(() => systemStore.status?.edition === 'server')
 
 // cross-section search: type to find any setting across all tabs
 const search = ref('')
@@ -300,14 +310,43 @@ const posture = computed(() => {
   ]
 })
 
+// Spec 109 FR-056: line icons from the app's own SVG icon set (same outline
+// style as SidebarNav's makeIcon), not emoji.
+const tabIconProps = {
+  fill: 'none',
+  stroke: 'currentColor',
+  'stroke-width': 1.6,
+  'stroke-linecap': 'round' as const,
+  'stroke-linejoin': 'round' as const,
+  viewBox: '0 0 24 24',
+}
+const makeTabIcon = (d: string): FunctionalComponent =>
+  (props) => h('svg', { ...tabIconProps, ...props }, [h('path', { d })])
+
+const IconLock = makeTabIcon(
+  'M12 11v3m-3-3a3 3 0 116 0m-9 3v6a1 1 0 001 1h10a1 1 0 001-1v-6a1 1 0 00-1-1H6a1 1 0 00-1 1z'
+)
+const IconGear = makeTabIcon(
+  'M10.3 3.6a1.5 1.5 0 013.4 0l.2 1.1a7 7 0 011.9.8l1-.6a1.5 1.5 0 012.1 2.1l-.6 1a7 7 0 01.8 1.9l1.1.2a1.5 1.5 0 010 3.4l-1.1.2a7 7 0 01-.8 1.9l.6 1a1.5 1.5 0 01-2.1 2.1l-1-.6a7 7 0 01-1.9.8l-.2 1.1a1.5 1.5 0 01-3.4 0l-.2-1.1a7 7 0 01-1.9-.8l-1 .6a1.5 1.5 0 01-2.1-2.1l.6-1a7 7 0 01-.8-1.9l-1.1-.2a1.5 1.5 0 010-3.4l1.1-.2a7 7 0 01.8-1.9l-.6-1a1.5 1.5 0 012.1-2.1l1 .6a7 7 0 011.9-.8l.2-1.1zM12 9a3 3 0 100 6 3 3 0 000-6z'
+)
+const IconWrench = makeTabIcon(
+  'M14.7 6.3a1 1 0 000 1.4l1.6 1.6a1 1 0 001.4 0l3-3a1 1 0 000-1.4l-1.6-1.6a1 1 0 00-1.4 0l-1 1L15 3l-5 5-1.3-1.3a1 1 0 00-1.4 0l-3 3a1 1 0 000 1.4L6 13l-3 3a1 1 0 000 1.4l2.6 2.6a1 1 0 001.4 0l3-3a1 1 0 000-1.4L8.7 14l5-5 1.6 1.6z'
+)
+const IconUsers = makeTabIcon(
+  'M17 20v-2a4 4 0 00-3-3.87M9 20v-2a4 4 0 013-3.87m0-4.13a4 4 0 100-8 4 4 0 000 8zm8 4v-2a4 4 0 00-3-3.85m-1-4.15a4 4 0 010 7.75'
+)
+const IconBraces = makeTabIcon(
+  'M8 4c-2 0-3 1-3 3v3c0 1-1 2-2 2 1 0 2 1 2 2v3c0 2 1 3 3 3m8-16c2 0 3 1 3 3v3c0 1 1 2 2 2-1 0-2 1-2 2v3c0 2-1 3-3 3'
+)
+
 const tabs = computed(() => {
   const base = [
-    { id: 'security', label: 'Security & Access', icon: '🔒' },
-    { id: 'general', label: 'General', icon: '⚙️' },
-    { id: 'advanced', label: 'Advanced', icon: '🧰' },
-  ] as Array<{ id: string; label: string; icon: string }>
-  if (hasServerEdition.value) base.push({ id: 'teams', label: SERVER_EDITION_TAB_LABEL, icon: '👥' })
-  base.push({ id: 'raw', label: 'Raw JSON', icon: '{ }' })
+    { id: 'security', label: 'Security & Access', icon: IconLock },
+    { id: 'general', label: 'General', icon: IconGear },
+    { id: 'advanced', label: 'Advanced', icon: IconWrench },
+  ] as Array<{ id: string; label: string; icon: FunctionalComponent }>
+  if (hasServerEdition.value) base.push({ id: 'teams', label: SERVER_EDITION_TAB_LABEL, icon: IconUsers })
+  base.push({ id: 'raw', label: 'Raw JSON', icon: IconBraces })
   return base
 })
 
@@ -501,6 +540,10 @@ watch(defaultInstructions, () => {
 })
 
 onMounted(async () => {
+  const tabParam = route.query.tab
+  if (typeof tabParam === 'string' && tabs.value.some((t) => t.id === tabParam)) {
+    activeTab.value = tabParam
+  }
   loadDefaultInstructions()
   window.addEventListener('mcpproxy:config-saved', handleConfigSaved)
   await loadConfig()
diff --git a/frontend/src/views/Tools.vue b/frontend/src/views/Tools.vue
index 7fa8b29e4..d3e8bc049 100644
--- a/frontend/src/views/Tools.vue
+++ b/frontend/src/views/Tools.vue
@@ -47,17 +47,19 @@
         <div class="stat-title">Disabled</div>
         <div class="stat-value text-2xl text-warning">{{ stats.disabled }}</div>
       </button>
-      <button
-        type="button"
-        :class="['stat text-left transition-colors cursor-pointer hover:bg-base-200/60', activeStatCard === 'pending' ? 'bg-base-200 ring-2 ring-inset ring-primary/40' : '']"
+      <!-- Spec 109 FR-027: this card is a link to the review queue, not an
+           in-page filter toggle — "needs review" means something to act on
+           elsewhere, not another way to slice this table. -->
+      <router-link
+        to="/review"
+        class="stat text-left transition-colors hover:bg-base-200/60"
         data-test="stat-pending"
-        @click="selectStatCard('pending')"
       >
-        <div class="stat-title">Pending Approval</div>
+        <div class="stat-title">Needs review</div>
         <div class="stat-value text-2xl" :class="stats.pending_approval > 0 ? 'text-error' : ''">
           {{ stats.pending_approval }}
         </div>
-      </button>
+      </router-link>
     </div>
 
     <!-- Partial-error banner -->
@@ -118,16 +120,20 @@
             </select>
           </div>
 
-          <!-- Risk filter -->
+          <!-- Tier filter. Spec 109 FR-028/X11: "Tier" (not "Risk" — risk
+               stays the scan-score term), values from the server-computed
+               `tier` field, never derived locally. `?risk=` stays a query
+               alias for `?tier=` for old bookmarks/links. -->
           <div class="form-control min-w-[120px]">
             <label class="label py-1">
-              <span class="label-text text-xs">Risk</span>
+              <span class="label-text text-xs">Tier</span>
             </label>
-            <select v-model="filterRisk" class="select select-bordered select-sm" aria-label="Filter by risk" data-test="filter-risk">
+            <select v-model="filterTier" class="select select-bordered select-sm" aria-label="Filter by tier" data-test="filter-tier">
               <option value="">All</option>
               <option value="read">Read</option>
               <option value="write">Write</option>
               <option value="destructive">Destructive</option>
+              <option value="unannotated">Unannotated</option>
             </select>
           </div>
 
@@ -136,12 +142,14 @@
             <label class="label py-1">
               <span class="label-text text-xs">Approval</span>
             </label>
+            <!-- Spec 109 FR-027: one review-state vocabulary everywhere
+                 (Web/macOS/CLI/review payload) — no "awaiting" (it duplicated
+                 pending+changed with a different name). -->
             <select v-model="filterApproval" class="select select-bordered select-sm" aria-label="Filter by approval state" data-test="filter-approval">
               <option value="">All</option>
-              <option value="awaiting">Awaiting approval</option>
               <option value="approved">Approved</option>
-              <option value="pending">Pending</option>
-              <option value="changed">Changed</option>
+              <option value="pending">New, needs review</option>
+              <option value="changed">Changed, needs review</option>
             </select>
           </div>
 
@@ -157,7 +165,7 @@
           <span v-if="searchQuery" class="badge badge-sm badge-outline">Search: {{ searchQuery }}</span>
           <span v-if="filterServer" class="badge badge-sm badge-outline">Server: {{ filterServer }}</span>
           <span v-if="filterStatus" class="badge badge-sm badge-outline">Status: {{ filterStatus }}</span>
-          <span v-if="filterRisk" class="badge badge-sm badge-outline">Risk: {{ filterRisk }}</span>
+          <span v-if="filterTier" class="badge badge-sm badge-outline">Tier: {{ filterTier }}</span>
           <span v-if="filterApproval" class="badge badge-sm badge-outline">Approval: {{ filterApproval }}</span>
         </div>
       </div>
@@ -319,8 +327,8 @@
                   Server {{ getSortIndicator('server_name') }}
                 </th>
                 <th>Description</th>
-                <th class="cursor-pointer hover:bg-base-200 select-none" @click="sortBy('risk')">
-                  Risk {{ getSortIndicator('risk') }}
+                <th class="cursor-pointer hover:bg-base-200 select-none" @click="sortBy('tier')">
+                  Tier {{ getSortIndicator('tier') }}
                 </th>
                 <th class="cursor-pointer hover:bg-base-200 select-none" @click="sortBy('approval_status')">
                   Approval {{ getSortIndicator('approval_status') }}
@@ -379,8 +387,8 @@
                   </div>
                 </td>
                 <td>
-                  <span class="badge badge-sm" :class="getRiskBadgeClass(tool)">
-                    {{ getRiskLabel(tool) }}
+                  <span class="badge badge-sm" :class="getTierBadgeClass(tool)">
+                    {{ getTierLabel(tool) }}
                   </span>
                 </td>
                 <td>
@@ -480,7 +488,7 @@
               <router-link :to="serverDetailPath(selectedTool.server_name)" class="link link-primary text-sm">
                 {{ selectedTool.server_name }}
               </router-link>
-              <span class="badge badge-sm" :class="getRiskBadgeClass(selectedTool)">{{ getRiskLabel(selectedTool) }}</span>
+              <span class="badge badge-sm" :class="getTierBadgeClass(selectedTool)">{{ getTierLabel(selectedTool) }}</span>
               <span v-if="selectedTool.config_denied" class="badge badge-sm badge-error">config-denied</span>
               <span v-else-if="selectedTool.disabled" class="badge badge-sm badge-warning">disabled</span>
               <span v-else class="badge badge-sm badge-success">enabled</span>
@@ -585,7 +593,7 @@ const selectedTool = ref<GlobalTool | null>(null)
 const searchQuery = ref('')
 const filterServer = ref('')
 const filterStatus = ref('')
-const filterRisk = ref('')
+const filterTier = ref('')
 const filterApproval = ref('')
 
 // Debounce search
@@ -596,7 +604,7 @@ watch(searchQuery, () => {
 })
 
 // ---- Sort ----
-type SortCol = 'name' | 'server_name' | 'risk' | 'approval_status' | 'enabled' | 'usage' | 'last_used'
+type SortCol = 'name' | 'server_name' | 'tier' | 'approval_status' | 'enabled' | 'usage' | 'last_used'
 const sortColumn = ref<SortCol>('name')
 const sortDirection = ref<'asc' | 'desc'>('asc')
 
@@ -767,18 +775,18 @@ const availableServers = computed(() => {
 })
 
 const hasActiveFilters = computed(() =>
-  !!searchQuery.value || !!filterServer.value || !!filterStatus.value || !!filterRisk.value || !!filterApproval.value
+  !!searchQuery.value || !!filterServer.value || !!filterStatus.value || !!filterTier.value || !!filterApproval.value
 )
 
 // Clickable stat cards (parity with Servers page): each card drives the
-// status/approval filter and toggles off when its active card is clicked again.
-type StatCard = 'total' | 'enabled' | 'disabled' | 'pending'
+// status filter and toggles off when its active card is clicked again. The
+// "Needs review" card (Spec 109 FR-027) is a plain link to /review, not one of
+// these — it never sets filterApproval.
+type StatCard = 'total' | 'enabled' | 'disabled'
 
 const activeStatCard = computed<StatCard>(() => {
-  if (filterApproval.value === 'awaiting' || filterApproval.value === 'pending') return 'pending'
   if (filterStatus.value === 'enabled') return 'enabled'
   if (filterStatus.value === 'disabled') return 'disabled'
-  if (!filterStatus.value && !filterApproval.value) return 'total'
   return 'total'
 })
 
@@ -786,34 +794,32 @@ function selectStatCard(card: StatCard) {
   // Toggle: re-clicking the active card resets to the unfiltered "total" view.
   if (card === 'total' || activeStatCard.value === card) {
     filterStatus.value = ''
-    filterApproval.value = ''
     return
   }
-  if (card === 'pending') {
-    filterStatus.value = ''
-    filterApproval.value = 'awaiting'
-  } else {
-    filterApproval.value = ''
-    filterStatus.value = card // 'enabled' | 'disabled'
-  }
+  filterStatus.value = card // 'enabled' | 'disabled'
 }
 
-// ---- Computed: risk derivation ----
-function getRisk(tool: GlobalTool): 'read' | 'write' | 'destructive' {
-  if (tool.annotations?.destructiveHint) return 'destructive'
-  if (tool.annotations?.readOnlyHint) return 'read'
-  return 'write'
+// ---- Tier (Spec 109 FR-028/X11): `tool.tier` comes from the backend
+// (contracts.AnnotationTier) — never computed here. An unannotated tool is
+// labelled "Unannotated", never silently shown as "write" (the X11 bug this
+// replaces: the old local getRisk() defaulted anything without hints to
+// "write").
+function getTier(tool: GlobalTool): string {
+  return tool.tier || 'unannotated'
 }
 
-function getRiskLabel(tool: GlobalTool): string {
-  return getRisk(tool)
+function getTierLabel(tool: GlobalTool): string {
+  const t = getTier(tool)
+  if (t === 'unannotated') return 'Unannotated'
+  return t.charAt(0).toUpperCase() + t.slice(1)
 }
 
-function getRiskBadgeClass(tool: GlobalTool): string {
-  const r = getRisk(tool)
-  if (r === 'destructive') return 'badge-error'
-  if (r === 'read') return 'badge-success'
-  return 'badge-warning'
+function getTierBadgeClass(tool: GlobalTool): string {
+  const t = getTier(tool)
+  if (t === 'destructive') return 'badge-error'
+  if (t === 'write') return 'badge-warning'
+  if (t === 'read') return 'badge-success'
+  return 'badge-ghost'
 }
 
 function getApprovalBadgeClass(status: string): string {
@@ -922,15 +928,11 @@ const searchScope = computed(() => {
     tools = tools.filter(t => t.config_denied)
   }
 
-  if (filterRisk.value) {
-    tools = tools.filter(t => getRisk(t) === filterRisk.value)
+  if (filterTier.value) {
+    tools = tools.filter(t => getTier(t) === filterTier.value)
   }
 
-  if (filterApproval.value === 'awaiting') {
-    // "Awaiting approval" mirrors the Pending Approval stat, which counts both
-    // brand-new (pending) and rug-pull (changed) tools.
-    tools = tools.filter(t => t.approval_status === 'pending' || t.approval_status === 'changed')
-  } else if (filterApproval.value) {
+  if (filterApproval.value) {
     tools = tools.filter(t => t.approval_status === filterApproval.value)
   }
 
@@ -979,8 +981,8 @@ const sortedTools = computed(() => {
         av = a.name; bv = b.name; break
       case 'server_name':
         av = a.server_name; bv = b.server_name; break
-      case 'risk':
-        av = getRisk(a); bv = getRisk(b); break
+      case 'tier':
+        av = getTier(a); bv = getTier(b); break
       case 'approval_status':
         av = a.approval_status || ''; bv = b.approval_status || ''; break
       case 'enabled': {
@@ -1054,7 +1056,7 @@ function clearFilters() {
   searchQuery.value = ''
   filterServer.value = ''
   filterStatus.value = ''
-  filterRisk.value = ''
+  filterTier.value = ''
   filterApproval.value = ''
   currentPage.value = 1
 }
@@ -1069,7 +1071,7 @@ function formatRelativeTime(ts: string): string {
 }
 
 // Reset page when filters/sort change
-watch([filterServer, filterStatus, filterRisk, filterApproval, sortColumn, sortDirection], () => {
+watch([filterServer, filterStatus, filterTier, filterApproval, sortColumn, sortDirection], () => {
   currentPage.value = 1
 })
 
@@ -1087,7 +1089,7 @@ const toolsHints = computed<Hint[]>(() => [
         title: 'Audit and cleanup',
         list: [
           'Search by tool name, description, or server',
-          'Filter by status, risk level, or approval state',
+          'Filter by status, tier, or approval state',
           'Sort any column to find stale or unused tools',
           'Select multiple tools for batch enable/disable, or batch approve/reject across servers',
         ],
diff --git a/frontend/tests/unit/add-to-mcpproxy-label.spec.ts b/frontend/tests/unit/add-to-mcpproxy-label.spec.ts
new file mode 100644
index 000000000..0196fe07e
--- /dev/null
+++ b/frontend/tests/unit/add-to-mcpproxy-label.spec.ts
@@ -0,0 +1,121 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createMemoryHistory } from 'vue-router'
+import Repositories from '@/views/Repositories.vue'
+import api from '@/services/api'
+
+// Spec 109 FR-063: the add action reads "Add to MCPProxy" (Web/macOS; CLI
+// prints "Added <name> to MCPProxy (quarantined for review)"), and after a
+// successful add the same control becomes "Added ✓ · Open".
+
+vi.mock('@/services/api', () => ({
+  default: {
+    listRegistries: vi.fn(),
+    searchRegistryServers: vi.fn(),
+    addRegistrySource: vi.fn(),
+    editRegistrySource: vi.fn(),
+    removeRegistrySource: vi.fn(),
+    addServerFromRegistry: vi.fn(),
+  },
+}))
+
+const globalStubs = { CollapsibleHintsPanel: { template: '<div />' } }
+
+const officialRegistry = {
+  id: 'official',
+  name: 'Official MCP Registry',
+  description: 'The official registry',
+  url: 'https://registry.modelcontextprotocol.io/',
+  provenance: 'official',
+  trusted: true,
+}
+
+function makeRouter() {
+  return createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/repositories', name: 'repositories', component: Repositories },
+      { path: '/servers/:serverName', name: 'server-detail', component: { template: '<div/>' } },
+    ],
+  })
+}
+
+async function mountView() {
+  const router = makeRouter()
+  router.push('/repositories')
+  await router.isReady()
+  const wrapper = mount(Repositories, {
+    global: { plugins: [createPinia(), router], stubs: globalStubs },
+  })
+  await flushPromises()
+  return { wrapper, router }
+}
+
+describe('Repositories "Add to MCPProxy" (Spec 109 FR-063)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    localStorage.clear()
+    ;(api.listRegistries as any).mockResolvedValue({
+      success: true,
+      data: { registries: [officialRegistry], total: 1 },
+    })
+    ;(api.searchRegistryServers as any).mockResolvedValue({
+      success: true,
+      data: {
+        registry_id: 'official',
+        servers: [{ id: 'gh-server', registry: 'official', name: 'github-server', description: 'GitHub tools' }],
+        total: 1,
+      },
+    })
+  })
+
+  async function searchAndGetAddButton(wrapper: Awaited<ReturnType<typeof mountView>>['wrapper']) {
+    await wrapper.find('[data-test="registry-card-official"]').trigger('click')
+    await flushPromises()
+    await wrapper.find('[data-test="registry-search-button"]').trigger('click')
+    await flushPromises()
+    return wrapper.find('[data-test="registry-add-gh-server"]')
+  }
+
+  it('reads "Add to MCPProxy" on the result button', async () => {
+    const { wrapper } = await mountView()
+    const button = await searchAndGetAddButton(wrapper)
+    expect(button.exists()).toBe(true)
+    expect(button.text()).toContain('Add to MCPProxy')
+    expect(button.text()).not.toBe('Add to MCP')
+  })
+
+  it('flips to "Added ✓ · Open" after a successful add', async () => {
+    ;(api.addServerFromRegistry as any).mockResolvedValue({
+      success: true,
+      server: { name: 'github-server' },
+    })
+    const { wrapper } = await mountView()
+    const button = await searchAndGetAddButton(wrapper)
+
+    await button.trigger('click')
+    await flushPromises()
+
+    expect(wrapper.find('[data-test="registry-add-gh-server"]').exists()).toBe(false)
+    const added = wrapper.find('[data-test="registry-added-gh-server"]')
+    expect(added.exists()).toBe(true)
+    expect(added.text()).toContain('Added ✓ · Open')
+  })
+
+  it('opens the added server on click', async () => {
+    ;(api.addServerFromRegistry as any).mockResolvedValue({
+      success: true,
+      server: { name: 'github-server' },
+    })
+    const { wrapper, router } = await mountView()
+    const button = await searchAndGetAddButton(wrapper)
+    await button.trigger('click')
+    await flushPromises()
+
+    await wrapper.find('[data-test="registry-added-gh-server"]').trigger('click')
+    await flushPromises()
+
+    expect(router.currentRoute.value.path).toBe('/servers/github-server')
+  })
+})
diff --git a/frontend/tests/unit/dashboard-default-landing.spec.ts b/frontend/tests/unit/dashboard-default-landing.spec.ts
index ec2c7e69f..9ad560ee8 100644
--- a/frontend/tests/unit/dashboard-default-landing.spec.ts
+++ b/frontend/tests/unit/dashboard-default-landing.spec.ts
@@ -4,11 +4,12 @@ import { shallowMount, flushPromises } from '@vue/test-utils'
 import { createPinia, setActivePinia } from 'pinia'
 import { createRouter, createMemoryHistory } from 'vue-router'
 
-// Roadmap analytics-dashboard / analytics-default-landing: the analytics
-// (Usage) panel of the Dashboard is what the Web UI lands on. `/` and `/usage`
-// open the analytics panel, `/overview` stays deep-linkable for the hub
-// overview, and a brand-new install (zero upstream servers) gets an
-// "add your first server" CTA instead of an empty chart grid.
+// Spec 109 FR-051 / research D3 (109-a interim step): `/` now lands on the
+// Dashboard's Overview (hub) panel, reversing #1044's Usage-first landing —
+// new users kept landing on empty charts (audit N8). `/usage` keeps the full
+// analytics panel (and its "add your first server" CTA on a brand-new
+// install), `/overview` stays deep-linkable to the same hub panel as `/`.
+// Home (needs-attention + topology + a usage strip) replaces `/` in 109-d.
 
 const serversSpy = vi.hoisted(() =>
   vi.fn().mockResolvedValue({ success: true, data: { servers: [] } })
@@ -74,7 +75,7 @@ function makeRouter() {
   return createRouter({
     history: createMemoryHistory(),
     routes: [
-      { path: '/', name: 'dashboard', component: Dashboard, meta: { dashboardView: 'usage' } },
+      { path: '/', name: 'dashboard', component: Dashboard, meta: { dashboardView: 'overview' } },
       { path: '/usage', name: 'usage', component: Dashboard, meta: { dashboardView: 'usage' } },
       { path: '/overview', name: 'dashboard-overview', component: Dashboard, meta: { dashboardView: 'overview' } },
       { path: '/repositories', name: 'repositories', component: { template: '<div />' } },
@@ -112,10 +113,10 @@ describe('analytics dashboard as the default landing page', () => {
     ;(globalThis as unknown as { EventSource: unknown }).EventSource = FakeEventSource
   })
 
-  it('routes "/" to the Dashboard on its usage panel, with /usage and /overview deep-linkable', () => {
+  it('routes "/" to the Dashboard on its overview panel, with /usage and /overview deep-linkable', () => {
     const root = appRouter.resolve('/')
     expect(root.name).toBe('dashboard')
-    expect(root.meta.dashboardView).toBe('usage')
+    expect(root.meta.dashboardView).toBe('overview')
 
     const usage = appRouter.resolve('/usage')
     expect(usage.meta.dashboardView).toBe('usage')
@@ -127,16 +128,15 @@ describe('analytics dashboard as the default landing page', () => {
     expect(overview.matched[0].components?.default).toBe(root.matched[0].components?.default)
   })
 
-  it('shows the usage panel (not the overview) when landing on "/"', async () => {
+  it('shows the overview panel (not usage) when landing on "/"', async () => {
     serversSpy.mockResolvedValue({
       success: true,
       data: { servers: [{ name: 'srv-a', enabled: true, connected: true }] },
     })
     const { wrapper } = await mountDashboard('/')
 
-    expect(wrapper.find('[data-test="dashboard-usage-panel"]').isVisible()).toBe(true)
-    expect(wrapper.find('[data-test="dashboard-overview-panel"]').isVisible()).toBe(false)
-    expect(wrapper.find('[data-test="usage-view-stub"]').exists()).toBe(true)
+    expect(wrapper.find('[data-test="dashboard-overview-panel"]').isVisible()).toBe(true)
+    expect(wrapper.find('[data-test="dashboard-usage-panel"]').isVisible()).toBe(false)
   })
 
   it('honours a /overview deep link', async () => {
@@ -153,29 +153,30 @@ describe('analytics dashboard as the default landing page', () => {
   it('rewrites the URL when the tabs are used, so the panel survives a reload', async () => {
     const { wrapper, router } = await mountDashboard('/')
 
-    await wrapper.find('[data-test="dashboard-tab-overview"]').trigger('click')
-    await flushPromises()
-    expect(router.currentRoute.value.path).toBe('/overview')
-
     await wrapper.find('[data-test="dashboard-tab-usage"]').trigger('click')
     await flushPromises()
     expect(router.currentRoute.value.path).toBe('/usage')
+
+    await wrapper.find('[data-test="dashboard-tab-overview"]').trigger('click')
+    await flushPromises()
+    expect(router.currentRoute.value.path).toBe('/overview')
   })
 
   it('follows the route when it changes underneath the component', async () => {
     const { wrapper, router } = await mountDashboard('/')
+    expect(wrapper.find('[data-test="dashboard-overview-panel"]').isVisible()).toBe(true)
 
-    await router.push('/overview')
+    await router.push('/usage')
     await flushPromises()
-    expect(wrapper.find('[data-test="dashboard-overview-panel"]').isVisible()).toBe(true)
+    expect(wrapper.find('[data-test="dashboard-usage-panel"]').isVisible()).toBe(true)
 
     await router.push('/')
     await flushPromises()
-    expect(wrapper.find('[data-test="dashboard-usage-panel"]').isVisible()).toBe(true)
+    expect(wrapper.find('[data-test="dashboard-overview-panel"]').isVisible()).toBe(true)
   })
 
   it('shows an "add your first server" CTA instead of empty charts on a fresh install', async () => {
-    const { wrapper } = await mountDashboard('/')
+    const { wrapper } = await mountDashboard('/usage')
 
     const cta = wrapper.find('[data-test="dashboard-usage-first-run"]')
     expect(cta.exists()).toBe(true)
@@ -186,7 +187,7 @@ describe('analytics dashboard as the default landing page', () => {
   })
 
   it('offers a one-click escape to the Overview panel from the first-run CTA', async () => {
-    const { wrapper, router } = await mountDashboard('/')
+    const { wrapper, router } = await mountDashboard('/usage')
 
     await wrapper.find('[data-test="dashboard-first-run-overview"]').trigger('click')
     await flushPromises()
@@ -200,7 +201,7 @@ describe('analytics dashboard as the default landing page', () => {
       success: true,
       data: { servers: [{ name: 'srv-a', enabled: true, connected: true }] },
     })
-    const { wrapper } = await mountDashboard('/')
+    const { wrapper } = await mountDashboard('/usage')
 
     expect(wrapper.find('[data-test="dashboard-usage-first-run"]').exists()).toBe(false)
     expect(wrapper.find('[data-test="usage-view-stub"]').exists()).toBe(true)
@@ -211,7 +212,7 @@ describe('analytics dashboard as the default landing page', () => {
     // (empty) server list alone, so a transport error must not be mistaken for
     // a fresh install and tell a user with servers that they have none.
     serversSpy.mockResolvedValue({ success: false, error: 'boom' })
-    const { wrapper } = await mountDashboard('/')
+    const { wrapper } = await mountDashboard('/usage')
 
     expect(wrapper.find('[data-test="dashboard-usage-first-run"]').exists()).toBe(false)
     expect(wrapper.find('[data-test="usage-view-stub"]').exists()).toBe(true)
@@ -222,7 +223,7 @@ describe('analytics dashboard as the default landing page', () => {
     // mounting UsageView (which would fire a request and flash "no usage data
     // yet" before the first-run CTA replaces it).
     serversSpy.mockReturnValue(new Promise(() => {}))
-    const { wrapper } = await mountDashboard('/')
+    const { wrapper } = await mountDashboard('/usage')
 
     expect(wrapper.find('[data-test="dashboard-usage-pending"]').exists()).toBe(true)
     expect(wrapper.find('[data-test="usage-view-stub"]').exists()).toBe(false)
@@ -231,7 +232,7 @@ describe('analytics dashboard as the default landing page', () => {
 
   it('clears the chart spinner when the list arrives by SSE before the fetch settles', async () => {
     serversSpy.mockReturnValue(new Promise(() => {}))
-    const { wrapper } = await mountDashboard('/')
+    const { wrapper } = await mountDashboard('/usage')
     expect(wrapper.find('[data-test="dashboard-usage-pending"]').exists()).toBe(true)
 
     window.dispatchEvent(
@@ -288,7 +289,7 @@ describe('analytics dashboard as the default landing page', () => {
     // `loading.error` is shared: App.vue fetches concurrently on mount and
     // silent background refreshes write the field too (and never clear it on
     // success). A failure that is not ours must not suppress the CTA.
-    const { wrapper } = await mountDashboard('/')
+    const { wrapper } = await mountDashboard('/usage')
     expect(wrapper.find('[data-test="dashboard-usage-first-run"]').exists()).toBe(true)
 
     const store = useServersStore()
@@ -300,7 +301,7 @@ describe('analytics dashboard as the default landing page', () => {
 
   it('shows the CTA once a later refresh succeeds after a failed initial fetch', async () => {
     serversSpy.mockResolvedValue({ success: false, error: 'boom' })
-    const { wrapper } = await mountDashboard('/')
+    const { wrapper } = await mountDashboard('/usage')
 
     // Initial fetch failed: no CTA (we do not know the server count), and the
     // usage panel is shown rather than an endless spinner.
diff --git a/frontend/tests/unit/profile-switcher-hidden.spec.ts b/frontend/tests/unit/profile-switcher-hidden.spec.ts
new file mode 100644
index 000000000..74e6a621e
--- /dev/null
+++ b/frontend/tests/unit/profile-switcher-hidden.spec.ts
@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { shallowMount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createMemoryHistory } from 'vue-router'
+
+// Spec 109 FR-057 (H2 interim, until Spec 108 removes the header
+// ProfileSwitcher entirely): "Profile:" looked like agent scoping while only
+// setting a UI default, so it is hidden when no profiles exist yet.
+
+vi.mock('@/services/api', () => {
+  const ok = (data: unknown = {}) => Promise.resolve({ success: true, data })
+  const base: Record<string, unknown> = {
+    hasAPIKey: vi.fn(() => false),
+  }
+  return {
+    default: new Proxy(base, {
+      get(target: Record<string, unknown>, prop: string) {
+        if (prop in target) return target[prop]
+        target[prop] = vi.fn(() => ok())
+        return target[prop]
+      },
+    }),
+  }
+})
+
+import TopHeader from '@/components/TopHeader.vue'
+import api from '@/services/api'
+
+function makeRouter() {
+  return createRouter({
+    history: createMemoryHistory(),
+    routes: [{ path: '/', name: 'dashboard', component: { template: '<div />' } }],
+  })
+}
+
+async function mountTopHeader() {
+  const router = makeRouter()
+  router.push('/')
+  await router.isReady()
+  const wrapper = shallowMount(TopHeader, {
+    global: { plugins: [router], stubs: { RouterLink: true } },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+describe('header ProfileSwitcher visibility (Spec 109 FR-057)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.clearAllMocks()
+    ;(api.hasAPIKey as any).mockReturnValue(false)
+  })
+
+  it('renders no ProfileSwitcher when profilesStore.hasProfiles is false', async () => {
+    ;(api.getProfiles as any).mockResolvedValue({ success: true, data: { profiles: [] } })
+    const wrapper = await mountTopHeader()
+
+    expect(wrapper.findComponent({ name: 'ProfileSwitcher' }).exists()).toBe(false)
+    expect(wrapper.find('[data-test="profile-switcher"]').exists()).toBe(false)
+  })
+
+  it('renders no ProfileSwitcher when the profiles fetch fails', async () => {
+    ;(api.getProfiles as any).mockResolvedValue({ success: false, error: 'boom' })
+    const wrapper = await mountTopHeader()
+
+    expect(wrapper.findComponent({ name: 'ProfileSwitcher' }).exists()).toBe(false)
+  })
+
+  it('renders the ProfileSwitcher once at least one profile exists', async () => {
+    ;(api.getProfiles as any).mockResolvedValue({
+      success: true,
+      data: { profiles: [{ name: 'work', servers: ['alpha'], tool_count: 3 }] },
+    })
+    const wrapper = await mountTopHeader()
+
+    expect(wrapper.findComponent({ name: 'ProfileSwitcher' }).exists()).toBe(true)
+  })
+})
diff --git a/frontend/tests/unit/review-interim-redirect.spec.ts b/frontend/tests/unit/review-interim-redirect.spec.ts
new file mode 100644
index 000000000..8d7b3e2e1
--- /dev/null
+++ b/frontend/tests/unit/review-interim-redirect.spec.ts
@@ -0,0 +1,37 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import appRouter from '@/router'
+
+// Spec 109 T026a: `/review` and `/review/:server` are interim redirects
+// (109-a is the first PR that links to `/review`) until 109-g ships the real
+// review queue/detail views. Both must resolve to a REGISTERED route, never
+// the `not-found` catch-all, and must keep the caller's other query params.
+//
+// The redirect targets are functions (they carry the server name / query
+// through), which vue-router only evaluates during an actual navigation —
+// `router.resolve()` alone does not run them — so this drives real
+// navigations on the app's own router instance.
+describe('review interim redirects (Spec 109 T026a)', () => {
+  beforeEach(() => {
+    // The app router's auth guard reaches for a store on every navigation.
+    setActivePinia(createPinia())
+  })
+
+  it('redirects /review to /servers?status=needs_review, keeping other params', async () => {
+    await appRouter.push('/review?foo=bar')
+    await appRouter.isReady()
+    expect(appRouter.currentRoute.value.name).not.toBe('not-found')
+    expect(appRouter.currentRoute.value.path).toBe('/servers')
+    expect(appRouter.currentRoute.value.query.status).toBe('needs_review')
+    expect(appRouter.currentRoute.value.query.foo).toBe('bar')
+  })
+
+  it('redirects /review/:server to /servers/:server?tab=tools, keeping other params', async () => {
+    await appRouter.push('/review/my-server?foo=bar')
+    await appRouter.isReady()
+    expect(appRouter.currentRoute.value.name).not.toBe('not-found')
+    expect(appRouter.currentRoute.value.path).toBe('/servers/my-server')
+    expect(appRouter.currentRoute.value.query.tab).toBe('tools')
+    expect(appRouter.currentRoute.value.query.foo).toBe('bar')
+  })
+})
diff --git a/frontend/tests/unit/router-home-default.spec.ts b/frontend/tests/unit/router-home-default.spec.ts
new file mode 100644
index 000000000..34ec61233
--- /dev/null
+++ b/frontend/tests/unit/router-home-default.spec.ts
@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest'
+
+// Spec 109 T006 / T018 (FR-051, research D3): `/` is the 109-a interim
+// landing step — it renders the Dashboard's Overview panel, not Usage.
+// `/usage` keeps rendering the full analytics panel (interim N8: Home
+// replaces `/` in 109-d, but that PR is out of scope here).
+import appRouter from '@/router'
+
+describe('router home default (109-a interim)', () => {
+  it('renders the Overview panel at "/"', () => {
+    const root = appRouter.resolve('/')
+    expect(root.name).toBe('dashboard')
+    expect(root.meta.dashboardView).toBe('overview')
+  })
+
+  it('renders the Usage panel at "/usage", sharing the same component as "/"', () => {
+    const root = appRouter.resolve('/')
+    const usage = appRouter.resolve('/usage')
+    expect(usage.name).toBe('usage')
+    expect(usage.meta.dashboardView).toBe('usage')
+    expect(usage.matched[0].components?.default).toBe(root.matched[0].components?.default)
+  })
+
+  it('keeps "/overview" deep-linkable to the same Overview panel', () => {
+    const overview = appRouter.resolve('/overview')
+    expect(overview.name).toBe('dashboard-overview')
+    expect(overview.meta.dashboardView).toBe('overview')
+  })
+})
diff --git a/frontend/tests/unit/server-detail-tab-url.spec.ts b/frontend/tests/unit/server-detail-tab-url.spec.ts
new file mode 100644
index 000000000..b6b481ee2
--- /dev/null
+++ b/frontend/tests/unit/server-detail-tab-url.spec.ts
@@ -0,0 +1,125 @@
+// Spec 109 FR-016 / T009 / T021: every tabbed Web UI view reads its tab from
+// `?tab=` on mount and writes it with `router.replace` on change, keeping
+// other query parameters. ServerDetail already read `?tab=` on mount; this
+// pins the write-back half (and that it survives alongside another query
+// param), plus the same contract for Settings' tabs.
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createWebHistory, createMemoryHistory } from 'vue-router'
+
+const ok = <T,>(data: T) => Promise.resolve({ success: true, data })
+
+vi.mock('@/services/api', () => {
+  const server = (name: string) => ({
+    name,
+    protocol: 'stdio',
+    enabled: true,
+    connected: true,
+    quarantined: false,
+    tool_count: 0,
+    trust_mode: 'manual',
+    security_scan: {
+      status: 'clean',
+      risk_score: 0,
+      last_scan_at: '2026-07-28T10:00:00Z',
+      scanners_run: 1,
+      scanners_failed: 0,
+      scanners_total: 1,
+    },
+  })
+  return {
+    default: {
+      getServers: vi.fn(() => ok({ servers: [server('alpha')] })),
+      getToolApprovals: vi.fn(() => ok({ tools: [], count: 0 })),
+      getServerTools: vi.fn(() => ok({ tools: [] })),
+      getSecurityOverview: vi.fn(() => ok({ scanners_enabled: 0, docker_available: true })),
+      getScanReport: vi.fn(() => ok({ job_id: 'scan-alpha-1', risk_score: 0, findings: [] })),
+      getScanStatus: vi.fn(() => ok({ id: 'scan-alpha-1', status: 'completed', scan_pass: 1 })),
+      startScan: vi.fn(() => ok({ id: 'scan-x' })),
+      getServerLogs: vi.fn(() => ok({ logs: [] })),
+      discoverServerTools: vi.fn(() => ok({})),
+      patchServer: vi.fn(() => ok({ message: 'ok', restart_required: true })),
+      getConfig: vi.fn(() => ok({ config: { server_edition: {} } })),
+      getStatus: vi.fn(() => ok({})),
+      validateConfig: vi.fn(),
+      applyConfig: vi.fn(),
+    },
+  }
+})
+
+async function mountServerDetail(path: string) {
+  const ServerDetail = (await import('@/views/ServerDetail.vue')).default
+  const router = createRouter({
+    history: createWebHistory(),
+    routes: [
+      { path: '/servers/:serverName', component: { template: '<div/>' } },
+      { path: '/security/scans/:jobId', component: { template: '<div/>' } },
+    ],
+  })
+  await router.push(path)
+  await router.isReady()
+  const wrapper = mount(ServerDetail, {
+    props: { serverName: 'alpha' },
+    global: { plugins: [createPinia(), router] },
+  })
+  await flushPromises()
+  await flushPromises()
+  return { wrapper, router }
+}
+
+async function mountSettings(path = '/settings') {
+  const Settings = (await import('@/views/Settings.vue')).default
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/settings', name: 'settings', component: Settings, meta: { title: 'Settings' } },
+    ],
+  })
+  await router.push(path)
+  await router.isReady()
+  const wrapper = mount(Settings, {
+    global: {
+      plugins: [router],
+      stubs: { VueMonacoEditor: true, ConnectModal: true },
+    },
+  })
+  await flushPromises()
+  return { wrapper, router }
+}
+
+beforeEach(() => {
+  setActivePinia(createPinia())
+  vi.clearAllMocks()
+})
+
+describe('ServerDetail tab <-> ?tab= (Spec 109 FR-016)', () => {
+  it('writes the query param when a tab is clicked, keeping other params', async () => {
+    const { wrapper, router } = await mountServerDetail('/servers/alpha?tab=tools&focus=endpoint')
+
+    const logsTab = wrapper.findAll('.tab').find((n) => n.text().includes('Logs'))
+    expect(logsTab).toBeTruthy()
+    await logsTab!.trigger('click')
+    await flushPromises()
+
+    expect(router.currentRoute.value.query.tab).toBe('logs')
+    expect(router.currentRoute.value.query.focus).toBe('endpoint')
+  })
+})
+
+describe('Settings tab <-> ?tab= (Spec 109 FR-016)', () => {
+  it('reads the tab from ?tab= on mount', async () => {
+    const { wrapper } = await mountSettings('/settings?tab=advanced')
+    expect(wrapper.find('[data-test="settings-tab-advanced"]').classes()).toContain('tab-active')
+  })
+
+  it('writes ?tab= when a tab is clicked, keeping other query params', async () => {
+    const { wrapper, router } = await mountSettings('/settings?focus=api_key')
+
+    await wrapper.find('[data-test="settings-tab-advanced"]').trigger('click')
+    await flushPromises()
+
+    expect(router.currentRoute.value.query.tab).toBe('advanced')
+    expect(router.currentRoute.value.query.focus).toBe('api_key')
+  })
+})
diff --git a/frontend/tests/unit/settings-naming.spec.ts b/frontend/tests/unit/settings-naming.spec.ts
new file mode 100644
index 000000000..b0b38d8c1
--- /dev/null
+++ b/frontend/tests/unit/settings-naming.spec.ts
@@ -0,0 +1,99 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createMemoryHistory } from 'vue-router'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+// Spec 109 FR-056 (T008/T020): the settings page had accumulated three names
+// (audit W5) — this pins it down to "Settings" everywhere (sidebar label,
+// route title/document.title, H1), drops the emoji tab icons for the app's
+// line-icon set, and gates the "Server Edition" tab on the resolved runtime
+// edition (`systemStore.status.edition`) rather than on config content.
+
+const emptyConfig = vi.hoisted(() => ({ server_edition: { enabled: false } }))
+
+vi.mock('@/services/api', () => ({
+  default: {
+    getConfig: vi.fn().mockResolvedValue({ success: true, data: { config: emptyConfig } }),
+    getStatus: vi.fn().mockResolvedValue({ success: true, data: {} }),
+    validateConfig: vi.fn(),
+    applyConfig: vi.fn(),
+  },
+}))
+
+import Settings from '@/views/Settings.vue'
+import { useSystemStore } from '@/stores/system'
+import appRouter from '@/router'
+
+function makeRouter(path = '/settings') {
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/settings', name: 'settings', component: Settings, meta: { title: 'Settings' } },
+      { path: '/:pathMatch(.*)*', name: 'other', component: { template: '<div/>' } },
+    ],
+  })
+  router.push(path)
+  return router
+}
+
+async function mountSettings() {
+  const router = makeRouter()
+  await router.isReady()
+  const wrapper = mount(Settings, {
+    global: {
+      plugins: [router],
+      stubs: { VueMonacoEditor: true, ConnectModal: true },
+    },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+describe('Settings naming (Spec 109 FR-056)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  it('names the /settings route "Settings", not "Configuration"', () => {
+    const resolved = appRouter.resolve('/settings')
+    expect(resolved.meta.title).toBe('Settings')
+  })
+
+  it('names the sidebar entry "Settings"', () => {
+    const src = readFileSync(resolve(__dirname, '../../src/components/SidebarNav.vue'), 'utf-8')
+    expect(src).toMatch(/>Settings<\/span>/)
+    expect(src).not.toMatch(/>Configuration<\/span>/)
+  })
+
+  it('renders "Settings" as the H1', async () => {
+    const wrapper = await mountSettings()
+    expect(wrapper.find('h1').text()).toBe('Settings')
+    wrapper.unmount()
+  })
+
+  it('has no emoji in the tab labels', async () => {
+    const wrapper = await mountSettings()
+    const tabs = wrapper.find('[data-test="settings-tabs"]')
+    // A crude but effective emoji sweep: astral-plane pictographs (U+1F000+,
+    // covers 🔒🧰👥 etc.), the Misc Symbols / Dingbats blocks (covers ⚙),
+    // and the variation-selector-16 that turns ⚙ into ⚙️.
+    expect(tabs.text()).not.toMatch(/[\u{1F000}-\u{1FFFF}☀-➿️]/u)
+  })
+
+  it('hides the Server Edition tab when the config has a server_edition key but the runtime edition is personal', async () => {
+    const wrapper = await mountSettings()
+    expect(wrapper.find('[data-test="settings-tab-teams"]').exists()).toBe(false)
+    wrapper.unmount()
+  })
+
+  it('shows the Server Edition tab once the runtime edition is server, regardless of config content', async () => {
+    const systemStore = useSystemStore()
+    // @ts-expect-error partial StatusUpdate is enough for this computed
+    systemStore.status = { edition: 'server' }
+    const wrapper = await mountSettings()
+    expect(wrapper.find('[data-test="settings-tab-teams"]').exists()).toBe(true)
+    wrapper.unmount()
+  })
+})
diff --git a/frontend/tests/unit/tools-approval-filter.spec.ts b/frontend/tests/unit/tools-approval-filter.spec.ts
new file mode 100644
index 000000000..4d9e4158a
--- /dev/null
+++ b/frontend/tests/unit/tools-approval-filter.spec.ts
@@ -0,0 +1,91 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import Tools from '@/views/Tools.vue'
+import api from '@/services/api'
+
+// Spec 109 FR-027: one review-state vocabulary. The Web UI Tools filter
+// offers exactly Approved / New, needs review / Changed, needs review — no
+// `awaiting` value (it duplicated pending+changed under a third name) — and
+// the "Needs review" stat links to a registered `/review` route (T026a),
+// never the 404 catch-all.
+
+vi.mock('@/services/api', () => ({
+  default: { getGlobalTools: vi.fn(), setToolEnabled: vi.fn() },
+}))
+
+const globalStubs = { CollapsibleHintsPanel: { template: '<div />' } }
+
+function mountView() {
+  return mount(Tools, { global: { plugins: [createPinia()], stubs: globalStubs } })
+}
+
+describe('Tools approval filter vocabulary (Spec 109 FR-027 / T010)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    ;(api.getGlobalTools as any).mockResolvedValue({
+      success: true,
+      data: {
+        stats: { total: 3, enabled: 3, disabled: 0, pending_approval: 2 },
+        tools: [
+          { name: 'new_tool', server_name: 's', approval_status: 'pending', enabled: true, description: '' },
+          { name: 'rugpull', server_name: 's', approval_status: 'changed', enabled: true, description: '' },
+          { name: 'fine', server_name: 's', approval_status: 'approved', enabled: true, description: '' },
+        ],
+      },
+    })
+  })
+
+  it('offers exactly Approved / New, needs review / Changed, needs review — no "awaiting"', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    const options = wrapper.find('[data-test="filter-approval"]').findAll('option')
+    const values = options.map((o) => o.attributes('value'))
+    const labels = options.map((o) => o.text())
+
+    expect(values).toEqual(['', 'approved', 'pending', 'changed'])
+    expect(labels).toEqual(['All', 'Approved', 'New, needs review', 'Changed, needs review'])
+    expect(values).not.toContain('awaiting')
+    expect(labels.join(' ')).not.toMatch(/awaiting/i)
+  })
+
+  it('filters to exactly the pending tools when "New, needs review" is selected', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    const select = wrapper.find('[data-test="filter-approval"]')
+    await select.setValue('pending')
+    await flushPromises()
+
+    const rows = wrapper.findAll('[data-test="tool-row"]')
+    expect(rows.length).toBe(1)
+    expect(rows[0].text()).toContain('new_tool')
+  })
+
+  it('filters to exactly the changed tools when "Changed, needs review" is selected', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    const select = wrapper.find('[data-test="filter-approval"]')
+    await select.setValue('changed')
+    await flushPromises()
+
+    const rows = wrapper.findAll('[data-test="tool-row"]')
+    expect(rows.length).toBe(1)
+    expect(rows[0].text()).toContain('rugpull')
+  })
+
+  it('the "Needs review" stat links to /review, which resolves to a registered route', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    const stat = wrapper.find('[data-test="stat-pending"]')
+    expect(stat.text()).toContain('Needs review')
+    expect(stat.attributes('to')).toBe('/review')
+
+    const appRouter = (await import('@/router')).default
+    const resolved = appRouter.resolve('/review')
+    expect(resolved.name).not.toBe('not-found')
+  })
+})
diff --git a/frontend/tests/unit/tools-pending-approval.spec.ts b/frontend/tests/unit/tools-pending-approval.spec.ts
index e3357078f..4d28297d1 100644
--- a/frontend/tests/unit/tools-pending-approval.spec.ts
+++ b/frontend/tests/unit/tools-pending-approval.spec.ts
@@ -4,12 +4,12 @@ import { createPinia, setActivePinia } from 'pinia'
 import Tools from '@/views/Tools.vue'
 import api from '@/services/api'
 
-// T1 (v0.36.0 feedback): the "Pending Approval" stat counts tools that are
-// pending OR changed, but the Approval=Pending filter matched only "pending",
-// so an instance whose sole awaiting tool was "changed" (a rug-pull) showed a
-// non-zero stat with an EMPTY table. This reproduces that exact data shape —
-// one approved tool + one CHANGED tool, pending_approval = 1 — and locks the
-// fix: clicking the stat applies an "awaiting" filter that surfaces the row.
+// T1 (v0.36.0 feedback) established that the "Pending Approval" stat counts
+// tools that are pending OR changed. Spec 109 FR-027 then turned that stat
+// into a plain link to the review queue (`/review`) instead of an in-page
+// filter toggle — "needs review" means something to go act on elsewhere, not
+// one more way to slice this table — so this now pins the count and the link
+// target instead of a click-to-filter interaction.
 
 vi.mock('@/services/api', () => ({
   default: { getGlobalTools: vi.fn(), setToolEnabled: vi.fn() },
@@ -21,7 +21,7 @@ function mountView() {
   return mount(Tools, { global: { plugins: [createPinia()], stubs: globalStubs } })
 }
 
-describe('Tools — Pending Approval count matches the filtered table', () => {
+describe('Tools — Needs review stat (Spec 109 FR-027)', () => {
   beforeEach(() => {
     setActivePinia(createPinia())
     ;(api.getGlobalTools as any).mockResolvedValue({
@@ -36,43 +36,25 @@ describe('Tools — Pending Approval count matches the filtered table', () => {
     })
   })
 
-  it('shows the changed tool (not an empty table) when the Pending Approval stat is clicked', async () => {
+  it('counts pending + changed tools (both are "needs review")', async () => {
     const wrapper = mountView()
     await flushPromises()
 
-    // Stat reflects the changed tool.
     expect(wrapper.find('[data-test="stat-pending"] .stat-value').text().trim()).toBe('1')
-
-    // Before the fix this produced "No matching tools"; now it lists the changed row.
-    await wrapper.find('[data-test="stat-pending"]').trigger('click')
-    await flushPromises()
-
-    const rows = wrapper.findAll('[data-test="tool-row"]')
-    expect(rows.length).toBe(1)
-    expect(rows[0].text()).toContain('hf_doc_search')
   })
 
-  it('the Awaiting-approval filter matches both pending and changed', async () => {
-    ;(api.getGlobalTools as any).mockResolvedValue({
-      success: true,
-      data: {
-        stats: { total: 3, enabled: 3, disabled: 0, pending_approval: 2 },
-        tools: [
-          { name: 'new_tool', server_name: 's', approval_status: 'pending', enabled: true, description: '' },
-          { name: 'rugpull', server_name: 's', approval_status: 'changed', enabled: true, description: '' },
-          { name: 'fine', server_name: 's', approval_status: 'approved', enabled: true, description: '' },
-        ],
-      },
-    })
+  it('labels the card "Needs review" and links to /review, not an in-page filter', async () => {
     const wrapper = mountView()
     await flushPromises()
-    await wrapper.find('[data-test="stat-pending"]').trigger('click')
+
+    const card = wrapper.find('[data-test="stat-pending"]')
+    expect(card.text()).toContain('Needs review')
+    expect(card.attributes('to')).toBe('/review')
+
+    // Clicking it must not mutate the Approval filter or the visible rows —
+    // it is a navigation, not a toggle.
+    await card.trigger('click')
     await flushPromises()
-    const rows = wrapper.findAll('[data-test="tool-row"]')
-    expect(rows.length).toBe(2) // pending + changed, not approved
-    const text = rows.map(r => r.text()).join(' ')
-    expect(text).toContain('new_tool')
-    expect(text).toContain('rugpull')
-    expect(text).not.toContain('fine')
+    expect(wrapper.findAll('[data-test="tool-row"]').length).toBe(2)
   })
 })
diff --git a/frontend/tests/unit/tools-tier.spec.ts b/frontend/tests/unit/tools-tier.spec.ts
new file mode 100644
index 000000000..51de35b3e
--- /dev/null
+++ b/frontend/tests/unit/tools-tier.spec.ts
@@ -0,0 +1,83 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import Tools from '@/views/Tools.vue'
+import api from '@/services/api'
+
+// Spec 109 FR-028 / T016 / X11: the Web Tools page's column and filter are
+// labelled "Tier" (not "Risk" — risk stays the scan-score term), and use the
+// server-computed `tier` field verbatim rather than deriving one locally. An
+// unannotated tool shows "Unannotated", never silently as "Write" (the X11
+// bug this replaces). (The `?risk=` URL alias in FR-028 belongs to the
+// shared URL-filter composable a later PR in this spec owns — this page has
+// no query-string filter wiring yet, on this or any other filter.)
+
+vi.mock('@/services/api', () => ({
+  default: { getGlobalTools: vi.fn(), setToolEnabled: vi.fn() },
+}))
+
+const globalStubs = { CollapsibleHintsPanel: { template: '<div />' } }
+
+function mountView() {
+  return mount(Tools, { global: { plugins: [createPinia()], stubs: globalStubs } })
+}
+
+describe('Tools tier column/filter (Spec 109 FR-028)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    ;(api.getGlobalTools as any).mockResolvedValue({
+      success: true,
+      data: {
+        stats: { total: 4, enabled: 4, disabled: 0 },
+        tools: [
+          { name: 'delete_file', server_name: 's', approval_status: 'approved', enabled: true, description: '', tier: 'destructive' },
+          { name: 'write_file', server_name: 's', approval_status: 'approved', enabled: true, description: '', tier: 'write' },
+          { name: 'read_file', server_name: 's', approval_status: 'approved', enabled: true, description: '', tier: 'read' },
+          { name: 'mystery_tool', server_name: 's', approval_status: 'approved', enabled: true, description: '', tier: 'unannotated' },
+        ],
+      },
+    })
+  })
+
+  it('labels the filter and column "Tier"', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    expect(wrapper.find('[data-test="filter-tier"]').exists()).toBe(true)
+    expect(wrapper.text()).not.toMatch(/\bRisk\b/)
+  })
+
+  it('shows an unannotated tool as "Unannotated", never as "Write"', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    const row = wrapper.findAll('[data-test="tool-row"]').find((r) => r.text().includes('mystery_tool'))
+    expect(row).toBeTruthy()
+    expect(row!.text()).toContain('Unannotated')
+    expect(row!.text()).not.toContain('Write')
+  })
+
+  it('renders the tier values verbatim from the backend for the other tools', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    const rows = wrapper.findAll('[data-test="tool-row"]')
+    const textFor = (name: string) => rows.find((r) => r.text().includes(name))!.text()
+    expect(textFor('delete_file')).toContain('Destructive')
+    expect(textFor('write_file')).toContain('Write')
+    expect(textFor('read_file')).toContain('Read')
+  })
+
+  it('filters to exactly the destructive tools when "Destructive" is selected', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    const select = wrapper.find('[data-test="filter-tier"]')
+    await select.setValue('destructive')
+    await flushPromises()
+
+    const rows = wrapper.findAll('[data-test="tool-row"]')
+    expect(rows.length).toBe(1)
+    expect(rows[0].text()).toContain('delete_file')
+  })
+})
diff --git a/frontend/tests/unit/top-header-tenant-gating.spec.ts b/frontend/tests/unit/top-header-tenant-gating.spec.ts
index fb2b37f7f..427dac555 100644
--- a/frontend/tests/unit/top-header-tenant-gating.spec.ts
+++ b/frontend/tests/unit/top-header-tenant-gating.spec.ts
@@ -1,8 +1,33 @@
-import { describe, it, expect, beforeEach } from 'vitest'
-import { shallowMount } from '@vue/test-utils'
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { shallowMount, flushPromises } from '@vue/test-utils'
 import { createPinia, setActivePinia } from 'pinia'
 import { createRouter, createMemoryHistory } from 'vue-router'
 
+// Spec 109 FR-057: ProfileSwitcher now also requires profilesStore.hasProfiles
+// (fetched by TopHeader on mount), so a real profile must be mocked here for
+// the "still renders for an admin principal" case below to hold.
+vi.mock('@/services/api', () => {
+  const ok = (data: unknown = {}) => Promise.resolve({ success: true, data })
+  const base: Record<string, unknown> = {
+    getProfiles: vi.fn(() => ok({ profiles: [{ name: 'work', servers: ['alpha'], tool_count: 3 }] })),
+    getActiveProfile: vi.fn(() => ok({ active_profile: '' })),
+    // authStore.principalKind calls this SYNCHRONOUSLY and branches on
+    // truthiness — the Proxy fallback below returns a (truthy) Promise for
+    // any undeclared method, which would silently reclassify every tenant
+    // test here as 'api_key'.
+    hasAPIKey: vi.fn(() => false),
+  }
+  return {
+    default: new Proxy(base, {
+      get(target: Record<string, unknown>, prop: string) {
+        if (prop in target) return target[prop]
+        target[prop] = vi.fn(() => ok())
+        return target[prop]
+      },
+    }),
+  }
+})
+
 // Spec 107 PR-C cross-review round 2, chunk 4 (P1): ModeSwitcher was
 // unconditionally rendered in TopHeader for every principal kind, including
 // a tenant session. routing_mode lives behind GET /routing and PATCH /config
@@ -39,12 +64,14 @@ async function mountTopHeaderAs(role: 'user' | 'admin') {
     last_login_at: '',
   }
 
-  return shallowMount(TopHeader, {
+  const wrapper = shallowMount(TopHeader, {
     global: {
       plugins: [router],
       stubs: { RouterLink: true },
     },
   })
+  await flushPromises()
+  return wrapper
 }
 
 describe('TopHeader tenant gating (Spec 107 FR-041, cross-review round 2 P1)', () => {
diff --git a/frontend/tests/unit/usage-chart-ticks.spec.ts b/frontend/tests/unit/usage-chart-ticks.spec.ts
new file mode 100644
index 000000000..4c10ef6cc
--- /dev/null
+++ b/frontend/tests/unit/usage-chart-ticks.spec.ts
@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import CallHistogram from '@/components/usage/CallHistogram.vue'
+import Timeline from '@/components/usage/Timeline.vue'
+
+// Spec 109 FR-074: count charts use integer ticks (a call is never
+// fractional), and the "unresolved" group — names that never completed a
+// call, excluded from the ranking (audit F22, #1046) — is titled "Calls to
+// unknown tools" rather than left as an unheaded caption.
+
+// Chart.js itself doesn't run in jsdom (no canvas 2D context) and mounting
+// vue-chartjs's real <Bar> to inspect the resolved `options` prop just trades
+// one flaky dependency for another. The tick config is a literal in each
+// component's source, so it is asserted directly — the same pragmatic
+// source-text approach z-index-scale.spec.ts uses for a CSS token file.
+function readSrc(relative: string): string {
+  return readFileSync(resolve(__dirname, relative), 'utf-8')
+}
+
+const barStub = {
+  name: 'Bar',
+  props: ['data', 'options'],
+  template: '<div data-test="bar-stub" />',
+}
+
+describe('CallHistogram (Spec 109 FR-074)', () => {
+  it('forces integer ticks on the calls axis', () => {
+    const src = readSrc('../../src/components/usage/CallHistogram.vue')
+    expect(src).toMatch(/ticks:\s*\{\s*precision:\s*0/)
+  })
+
+  it('titles the excluded group "Calls to unknown tools"', () => {
+    const wrapper = mount(CallHistogram, {
+      props: {
+        tools: [
+          { server: 's', tool: 'a', calls: 3, errors: 0 },
+          // Never completed a call (all calls errored) -> excluded, "unresolved".
+          { server: 's', tool: 'broken', calls: 2, errors: 2 },
+        ],
+      },
+      global: { stubs: { Bar: barStub } },
+    })
+    const note = wrapper.find('[data-test="usage-call-histogram-unresolved"]')
+    expect(note.exists()).toBe(true)
+    expect(note.text()).toContain('Calls to unknown tools')
+  })
+
+  it('does not show the group when nothing is unresolved', () => {
+    const wrapper = mount(CallHistogram, {
+      props: { tools: [{ server: 's', tool: 'a', calls: 3, errors: 0 }] },
+      global: { stubs: { Bar: barStub } },
+    })
+    expect(wrapper.find('[data-test="usage-call-histogram-unresolved"]').exists()).toBe(false)
+  })
+})
+
+describe('Timeline (Spec 109 FR-074)', () => {
+  it('forces integer ticks on the calls axis', () => {
+    const src = readSrc('../../src/components/usage/Timeline.vue')
+    expect(src).toMatch(/ticks:\s*\{\s*precision:\s*0/)
+  })
+
+  it('still mounts and renders with real data (sanity: Timeline unaffected by the tick change)', () => {
+    const wrapper = mount(Timeline, {
+      props: {
+        buckets: [{ start: '2026-01-01T00:00:00Z', calls: 3, errors: 1 }],
+        window: '24h',
+      },
+      global: { stubs: { Bar: barStub } },
+    })
+    expect(wrapper.find('[data-test="usage-timeline"]').exists()).toBe(true)
+  })
+})
diff --git a/internal/contracts/converters.go b/internal/contracts/converters.go
index c8b5b0e9c..e12038394 100644
--- a/internal/contracts/converters.go
+++ b/internal/contracts/converters.go
@@ -525,6 +525,9 @@ func ConvertGenericToolsToTyped(genericTools []map[string]interface{}) []Tool {
 				OpenWorldHint:   annotationsPtr.OpenWorldHint,
 			}
 		}
+		// Spec 109 FR-028/X11: computed here, once, for every producer of a
+		// Tool — never left for the Web/macOS/CLI surface to derive locally.
+		tool.Tier = AnnotationTier(toolAnnotationToConfig(tool.Annotations))
 
 		tools = append(tools, tool)
 	}
@@ -719,3 +722,20 @@ func convertMapToToolAnnotation(m map[string]interface{}) *ToolAnnotation {
 
 	return annotation
 }
+
+// toolAnnotationToConfig adapts the wire-shaped ToolAnnotation to
+// config.ToolAnnotations — the type AnnotationTier takes — so the tier
+// computation stays the single pure function in tier.go rather than being
+// duplicated against this package's own annotation type.
+func toolAnnotationToConfig(a *ToolAnnotation) *config.ToolAnnotations {
+	if a == nil {
+		return nil
+	}
+	return &config.ToolAnnotations{
+		Title:           a.Title,
+		ReadOnlyHint:    a.ReadOnlyHint,
+		DestructiveHint: a.DestructiveHint,
+		IdempotentHint:  a.IdempotentHint,
+		OpenWorldHint:   a.OpenWorldHint,
+	}
+}
diff --git a/internal/contracts/tier.go b/internal/contracts/tier.go
new file mode 100644
index 000000000..1d5cfc740
--- /dev/null
+++ b/internal/contracts/tier.go
@@ -0,0 +1,54 @@
+package contracts
+
+import "github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+
+// Tier is a tool's capability classification, computed once from its
+// annotations by AnnotationTier and reused by every surface (Spec 109
+// FR-028, X11): the Web Tools page, macOS Tools view, CLI `tools list --tier`
+// and `GET /tools` / `GET /servers/{id}/tools`. No surface may compute its
+// own — the review payload is the one place a fifth value, TierUnknown,
+// appears (data-model.md §2-3: a captured-but-unannotated record is still
+// TierUnannotated; TierUnknown is reserved for a record with no captured
+// annotations at all, e.g. one predating this spec).
+type Tier string
+
+const (
+	TierRead        Tier = "read"
+	TierWrite       Tier = "write"
+	TierDestructive Tier = "destructive"
+	TierUnannotated Tier = "unannotated"
+	// TierUnknown is returned only by the review composer (internal/runtime
+	// review.go), never by AnnotationTier — see the type doc above.
+	TierUnknown Tier = "unknown"
+)
+
+// AnnotationTier computes a tool's tier from its MCP behavior-hint
+// annotations. This is the ONE place the classification happens; Spec 108's
+// IntrinsicTier calls this same function rather than reimplementing it
+// (research D1).
+//
+// Priority (highest first):
+//  1. destructiveHint == true            -> TierDestructive
+//  2. readOnlyHint == false (explicit)   -> TierWrite
+//  3. readOnlyHint == true               -> TierRead
+//  4. nil annotations, or neither hint set -> TierUnannotated
+//
+// This is deliberately distinct from DeriveCallWith (Spec 018 call-variant
+// routing), which defaults an unannotated tool to "read" for safety when
+// picking which call_tool_* variant to use — AnnotationTier never guesses:
+// an unannotated tool is TierUnannotated, not TierRead.
+func AnnotationTier(a *config.ToolAnnotations) Tier {
+	if a == nil {
+		return TierUnannotated
+	}
+	if a.DestructiveHint != nil && *a.DestructiveHint {
+		return TierDestructive
+	}
+	if a.ReadOnlyHint != nil {
+		if !*a.ReadOnlyHint {
+			return TierWrite
+		}
+		return TierRead
+	}
+	return TierUnannotated
+}
diff --git a/internal/contracts/tier_test.go b/internal/contracts/tier_test.go
new file mode 100644
index 000000000..2c0c58f38
--- /dev/null
+++ b/internal/contracts/tier_test.go
@@ -0,0 +1,89 @@
+package contracts
+
+import (
+	"testing"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+// TestAnnotationTier (Spec 109 FR-028 / T014 / X11): one pure function
+// computes a tool's tier from its annotations everywhere — the Web Tools
+// page, macOS Tools view and CLI `tools list --tier` all call this instead of
+// each computing their own (X11: Web computed "write" as the fallback,
+// backend computed "read", CLI used operation_type — three different
+// answers for the same unannotated tool).
+func TestAnnotationTier(t *testing.T) {
+	boolPtr := func(b bool) *bool { return &b }
+
+	cases := []struct {
+		name string
+		ann  *config.ToolAnnotations
+		want Tier
+	}{
+		{"nil annotations -> unannotated", nil, TierUnannotated},
+		{"empty annotations -> unannotated", &config.ToolAnnotations{}, TierUnannotated},
+		{
+			"destructiveHint=true -> destructive, highest priority",
+			&config.ToolAnnotations{DestructiveHint: boolPtr(true), ReadOnlyHint: boolPtr(true)},
+			TierDestructive,
+		},
+		{
+			"destructiveHint=false, readOnlyHint=false -> write",
+			&config.ToolAnnotations{DestructiveHint: boolPtr(false), ReadOnlyHint: boolPtr(false)},
+			TierWrite,
+		},
+		{
+			"readOnlyHint=false (explicit) -> write",
+			&config.ToolAnnotations{ReadOnlyHint: boolPtr(false)},
+			TierWrite,
+		},
+		{
+			"readOnlyHint=true -> read",
+			&config.ToolAnnotations{ReadOnlyHint: boolPtr(true)},
+			TierRead,
+		},
+		{
+			"neither hint set -> unannotated",
+			&config.ToolAnnotations{IdempotentHint: boolPtr(true)},
+			TierUnannotated,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := AnnotationTier(tc.ann)
+			if got != tc.want {
+				t.Fatalf("AnnotationTier(%+v) = %q, want %q", tc.ann, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestTierValuesMatchTheTerminologyTable(t *testing.T) {
+	// specs/109-ux-navigation-consistency/spec.md terminology table: exactly
+	// these five string values exist anywhere in the system (the fifth,
+	// "unknown", is the review composer's own value — never returned by
+	// AnnotationTier itself).
+	want := map[Tier]bool{
+		TierRead:        true,
+		TierWrite:       true,
+		TierDestructive: true,
+		TierUnannotated: true,
+		TierUnknown:     true,
+	}
+	got := map[Tier]string{
+		TierRead:        "read",
+		TierWrite:       "write",
+		TierDestructive: "destructive",
+		TierUnannotated: "unannotated",
+		TierUnknown:     "unknown",
+	}
+	for tier, str := range got {
+		if !want[tier] {
+			t.Fatalf("unexpected tier constant %q", tier)
+		}
+		if string(tier) != str {
+			t.Fatalf("Tier constant %v must serialize as %q, got %q", tier, str, string(tier))
+		}
+	}
+}
diff --git a/internal/contracts/types.go b/internal/contracts/types.go
index a0673da98..35fa98611 100644
--- a/internal/contracts/types.go
+++ b/internal/contracts/types.go
@@ -333,14 +333,19 @@ type MCPSession struct {
 
 // Tool represents an MCP tool with its metadata
 type Tool struct {
-	Name           string                 `json:"name"`
-	ServerName     string                 `json:"server_name"`
-	Description    string                 `json:"description"`
-	Schema         map[string]interface{} `json:"schema,omitempty" swaggertype:"object"`
-	Usage          int                    `json:"usage"`
-	LastUsed       *time.Time             `json:"last_used,omitempty"`
-	Annotations    *ToolAnnotation        `json:"annotations,omitempty"`
-	ApprovalStatus string                 `json:"approval_status,omitempty"`
+	Name        string                 `json:"name"`
+	ServerName  string                 `json:"server_name"`
+	Description string                 `json:"description"`
+	Schema      map[string]interface{} `json:"schema,omitempty" swaggertype:"object"`
+	Usage       int                    `json:"usage"`
+	LastUsed    *time.Time             `json:"last_used,omitempty"`
+	Annotations *ToolAnnotation        `json:"annotations,omitempty"`
+	// Tier is computed by AnnotationTier (Spec 109 FR-028/X11) from
+	// Annotations — read|write|destructive|unannotated. Set by every producer
+	// of a Tool (enrichServerTools, the global tools handler); never left for
+	// a consuming surface to compute.
+	Tier           Tier   `json:"tier,omitempty"`
+	ApprovalStatus string `json:"approval_status,omitempty"`
 	// Disabled mirrors ToolApprovalRecord.Disabled so per-tool enable state is
 	// available without a second round-trip to the approvals endpoint. Absent
 	// in the JSON when false (default) to keep responses compact.
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index f3bef268a..68a4835c8 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -4107,6 +4107,7 @@ func (s *Server) handleSSEEvents(w http.ResponseWriter, r *http.Request) {
 	initialLiveStats := filterUpstreamStatsServers(callerCtx, s.controller.GetUpstreamStats())
 	initialStatus := map[string]interface{}{
 		"running":        s.controller.IsRunning(),
+		"edition":        editionValue,
 		"listen_addr":    s.controller.GetListenAddress(),
 		"upstream_stats": initialLiveStats,
 		"status":         withLiveUpstreamStats(callerCtx, s.controller.GetStatus(), initialLiveStats),
@@ -4163,6 +4164,7 @@ func (s *Server) handleSSEEvents(w http.ResponseWriter, r *http.Request) {
 			eventLiveStats := filterUpstreamStatsServers(callerCtx, s.controller.GetUpstreamStats())
 			response := map[string]interface{}{
 				"running":        s.controller.IsRunning(),
+				"edition":        editionValue,
 				"listen_addr":    s.controller.GetListenAddress(),
 				"upstream_stats": eventLiveStats,
 				"status":         withLiveUpstreamStats(callerCtx, status, eventLiveStats),
diff --git a/internal/httpapi/sse_status_edition_test.go b/internal/httpapi/sse_status_edition_test.go
new file mode 100644
index 000000000..da0b83b93
--- /dev/null
+++ b/internal/httpapi/sse_status_edition_test.go
@@ -0,0 +1,38 @@
+package httpapi
+
+import (
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"go.uber.org/zap"
+)
+
+// TestSSE_StatusFramesCarryEdition (Spec 109 FR-056 / T008, T020): the Web UI
+// gates the Settings "Server Edition" tab on `systemStore.status.edition ===
+// 'server'` rather than on whether the config happens to have a
+// `server_edition` key (a stale/imported config can carry that key on a
+// personal-edition instance). `GET /api/v1/status` already reports `edition`;
+// the SSE `status` stream — what actually populates systemStore.status on a
+// running Web UI — must carry the same field on its initial frame (the one
+// used at mount time), so the two can never disagree.
+func TestSSE_StatusFramesCarryEdition(t *testing.T) {
+	ctrl := &scopeController{cfg: scopeFixtureConfig(false), servers: scopeFixtureServers(), withManagement: true}
+	srv := NewServer(ctrl, zap.NewNop().Sugar(), nil)
+
+	ts := httptest.NewServer(srv)
+	defer ts.Close()
+
+	body, closeConn := sseSubscribe(t, ts.URL, scopeAdminAPIKey)
+	defer closeConn()
+
+	deadline := time.Now().Add(5 * time.Second)
+	initial := readSSEUntil(t, body, "status", deadline)
+	edition, ok := initial.Data["edition"]
+	if !ok {
+		t.Fatalf("initial SSE status frame is missing \"edition\": %#v", initial.Data)
+	}
+	if edition != "personal" {
+		t.Fatalf("expected edition %q on the initial frame, got %q", "personal", edition)
+	}
+}
diff --git a/internal/httpapi/testdata/golden/get_server_tools.json b/internal/httpapi/testdata/golden/get_server_tools.json
index 4d12d2ef8..df66165c2 100644
--- a/internal/httpapi/testdata/golden/get_server_tools.json
+++ b/internal/httpapi/testdata/golden/get_server_tools.json
@@ -7,9 +7,10 @@
         "description": "A simple echo tool for testing",
         "name": "echo_tool",
         "server_name": "test-server",
+        "tier": "unannotated",
         "usage": 10
       }
     ]
   },
   "success": true
-}
\ No newline at end of file
+}
diff --git a/internal/httpapi/testdata/golden/search_tools.json b/internal/httpapi/testdata/golden/search_tools.json
index 72e898256..f06ae0560 100644
--- a/internal/httpapi/testdata/golden/search_tools.json
+++ b/internal/httpapi/testdata/golden/search_tools.json
@@ -9,6 +9,7 @@
           "description": "A simple echo tool for testing",
           "name": "echo_tool",
           "server_name": "test-server",
+          "tier": "unannotated",
           "usage": 10
         }
       }
@@ -17,4 +18,4 @@
     "total": 1
   },
   "success": true
-}
\ No newline at end of file
+}
diff --git a/internal/httpapi/tools_tier_test.go b/internal/httpapi/tools_tier_test.go
new file mode 100644
index 000000000..64917fe17
--- /dev/null
+++ b/internal/httpapi/tools_tier_test.go
@@ -0,0 +1,70 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap/zaptest"
+)
+
+// Spec 109 FR-028 / T014: GET /tools and GET /servers/{id}/tools rows carry a
+// `tier` field computed by contracts.AnnotationTier — the one place this is
+// computed, so the Web/macOS/CLI surfaces never derive their own (X11).
+
+func TestGlobalTools_RowsCarryTier(t *testing.T) {
+	ctrl := &globalToolsController{
+		allServers: []map[string]interface{}{{"name": "fs"}},
+		serverTools: map[string][]map[string]interface{}{
+			"fs": {
+				{"name": "delete_file", "description": "d", "annotations": map[string]interface{}{"destructiveHint": true}},
+				{"name": "write_file", "description": "d", "annotations": map[string]interface{}{"readOnlyHint": false}},
+				{"name": "read_file", "description": "d", "annotations": map[string]interface{}{"readOnlyHint": true}},
+				{"name": "mystery_tool", "description": "d"}, // no annotations at all
+			},
+		},
+	}
+
+	data := doGlobalTools(t, ctrl)
+	tools := data["tools"].([]interface{})
+	require.Len(t, tools, 4)
+
+	byName := map[string]map[string]interface{}{}
+	for _, x := range tools {
+		tm := x.(map[string]interface{})
+		byName[tm["name"].(string)] = tm
+	}
+
+	assert.Equal(t, "destructive", byName["delete_file"]["tier"])
+	assert.Equal(t, "write", byName["write_file"]["tier"])
+	assert.Equal(t, "read", byName["read_file"]["tier"])
+	assert.Equal(t, "unannotated", byName["mystery_tool"]["tier"])
+}
+
+func TestServerTools_RowsCarryTier(t *testing.T) {
+	ctrl := &scopeController{cfg: scopeFixtureConfig(false), servers: scopeFixtureServers(), withManagement: true}
+	// scopeFixtureServers' tools carry no annotations, so this exercises the
+	// "unannotated" branch through the real GET /servers/{id}/tools handler.
+	srv := NewServer(ctrl, zaptest.NewLogger(t).Sugar(), nil)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/servers/alpha/tools", http.NoBody)
+	req.Header.Set("X-API-Key", scopeAdminAPIKey)
+	w := httptest.NewRecorder()
+	srv.router.ServeHTTP(w, req)
+	require.Equal(t, http.StatusOK, w.Code)
+
+	var resp map[string]interface{}
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))
+	data, ok := resp["data"].(map[string]interface{})
+	require.True(t, ok)
+	tools, ok := data["tools"].([]interface{})
+	require.True(t, ok)
+	require.NotEmpty(t, tools)
+	for _, x := range tools {
+		tm := x.(map[string]interface{})
+		assert.Contains(t, tm, "tier", "every row must carry tier (FR-028)")
+	}
+}

From 55ebccea16af44faa1d409f6dd1c9e442605e396 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 25 Sep 2026 20:08:32 +0300
Subject: [PATCH 03/27] feat(macos): tool tier + approval labels + Add to
 MCPProxy (Spec 109 PR a)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ToolLabels.swift: one shared approval-state and tier label table
  (Approved / New, needs review / Changed, needs review; Read / Write /
  Destructive / Unannotated / Unknown), matching the Web/CLI vocabulary.
  ServerDetailView's approval badge and ToolsView's new tier badge both
  go through it.
- ServerTool/SearchTool decode the backend-computed `tier` field
  (contracts.AnnotationTier) rather than deriving one from raw
  annotations.
- ServerBrowseView: "Add to MCPProxy", flipping to "Added ✓ · Open"
  (opens the server) after a successful add.
---
 .../macos/MCPProxy/MCPProxy/API/Models.swift  | 10 +++-
 .../MCPProxy/MCPProxy/Models/ToolLabels.swift | 43 ++++++++++++++
 .../MCPProxy/Views/ServerBrowseView.swift     | 39 ++++++++++---
 .../MCPProxy/Views/ServerDetailView.swift     |  9 +--
 .../MCPProxy/MCPProxy/Views/ToolsView.swift   | 36 +++++++++++-
 .../MCPProxyTests/ToolLabelsTests.swift       | 58 +++++++++++++++++++
 6 files changed, 178 insertions(+), 17 deletions(-)
 create mode 100644 native/macos/MCPProxy/MCPProxy/Models/ToolLabels.swift
 create mode 100644 native/macos/MCPProxy/MCPProxyTests/ToolLabelsTests.swift

diff --git a/native/macos/MCPProxy/MCPProxy/API/Models.swift b/native/macos/MCPProxy/MCPProxy/API/Models.swift
index 6d067c111..1d7e809b3 100644
--- a/native/macos/MCPProxy/MCPProxy/API/Models.swift
+++ b/native/macos/MCPProxy/MCPProxy/API/Models.swift
@@ -1178,9 +1178,12 @@ struct ServerTool: Codable, Identifiable, Equatable {
     let serverName: String?
     let annotations: ToolAnnotation?
     let approvalStatus: String?
+    /// Spec 109 FR-028: server-computed (`contracts.AnnotationTier`) —
+    /// `read`|`write`|`destructive`|`unannotated`. Never derived locally.
+    let tier: String?
 
     enum CodingKeys: String, CodingKey {
-        case name, description, annotations
+        case name, description, annotations, tier
         case serverName = "server_name"
         case approvalStatus = "approval_status"
     }
@@ -1278,9 +1281,12 @@ struct SearchTool: Codable {
     let description: String?
     let serverName: String?
     let annotations: ToolAnnotation?
+    /// Spec 109 FR-028: server-computed (`contracts.AnnotationTier`). Never
+    /// derived locally.
+    let tier: String?
 
     enum CodingKeys: String, CodingKey {
-        case name, description, annotations
+        case name, description, annotations, tier
         case serverName = "server_name"
     }
 }
diff --git a/native/macos/MCPProxy/MCPProxy/Models/ToolLabels.swift b/native/macos/MCPProxy/MCPProxy/Models/ToolLabels.swift
new file mode 100644
index 000000000..a87bef301
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxy/Models/ToolLabels.swift
@@ -0,0 +1,43 @@
+// ToolLabels.swift
+// MCPProxy
+//
+// Spec 109 FR-027 / FR-028: one vocabulary for tool review states and tool
+// tier, shared by every view that shows either — so the terminology table in
+// specs/109-ux-navigation-consistency/spec.md never drifts between
+// ServerDetailView, ToolsView and any review surface. Pinned by
+// MCPProxyTests/ToolLabelsTests.swift.
+//
+// Neither function computes anything: `approval_status` and `tier` are both
+// server-resolved fields (the tier by the one Go function
+// `contracts.AnnotationTier`, FR-028/X11) — these are display labels only.
+
+import Foundation
+
+enum ToolLabels {
+    /// `approval_status` -> display label (FR-027). The old "Awaiting
+    /// approval" / "Pending Approval" wording is gone — `pending` and
+    /// `changed` both read as "<state>, needs review" now.
+    static func approvalStatusLabel(_ status: String?) -> String {
+        switch status {
+        case "approved": return "Approved"
+        case "pending": return "New, needs review"
+        case "changed": return "Changed, needs review"
+        default: return status?.capitalized ?? "Unknown"
+        }
+    }
+
+    /// `tier` -> display label (FR-028). `unknown` only ever appears in the
+    /// review payload, for a tool captured before this spec stored
+    /// annotations — everywhere else the backend sends `unannotated` for a
+    /// tool with no hints.
+    static func tierLabel(_ tier: String?) -> String {
+        switch tier {
+        case "read": return "Read"
+        case "write": return "Write"
+        case "destructive": return "Destructive"
+        case "unannotated": return "Unannotated"
+        case "unknown": return "Unknown"
+        default: return "Unannotated"
+        }
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift b/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
index 7d8f0336c..64f7f3717 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
@@ -25,6 +25,10 @@ struct ServerBrowseView: View {
     @State private var searchError: String?
     @State private var addingID: String?
     @State private var addNote: String?
+    /// Spec 109 FR-063: server.id -> the added server's name, so the button
+    /// can flip to "Added ✓ · Open" and stay that way for the rest of this
+    /// browse session.
+    @State private var addedServers: [String: String] = [:]
     @State private var registryInfo: RegistryInfoContext?
 
     private var apiClient: APIClient? { appState.apiClient }
@@ -286,14 +290,26 @@ struct ServerBrowseView: View {
                         .overlay(Capsule().stroke(Color.secondary.opacity(0.4)))
                 }
                 Spacer()
-                Button {
-                    Task { await add(server) }
-                } label: {
-                    if addingID == server.id { ProgressView().controlSize(.small) } else { Text("Add to MCP") }
+                // Spec 109 FR-063: "Add to MCPProxy", flipping to a
+                // persistent "Added ✓ · Open" once the add succeeds.
+                if let addedName = addedServers[server.id] {
+                    Button {
+                        openServer(addedName)
+                    } label: {
+                        Text("Added ✓ · Open")
+                    }
+                    .controlSize(.small)
+                    .accessibilityIdentifier("browse-added-\(server.id)")
+                } else {
+                    Button {
+                        Task { await add(server) }
+                    } label: {
+                        if addingID == server.id { ProgressView().controlSize(.small) } else { Text("Add to MCPProxy") }
+                    }
+                    .controlSize(.small)
+                    .disabled(addingID != nil || server.registry == nil)
+                    .accessibilityIdentifier("browse-add-\(server.id)")
                 }
-                .controlSize(.small)
-                .disabled(addingID != nil || server.registry == nil)
-                .accessibilityIdentifier("browse-add-\(server.id)")
             }
         }
         .padding(10)
@@ -346,6 +362,14 @@ struct ServerBrowseView: View {
         isSearching = false
     }
 
+    /// Spec 109 FR-063: "Added ✓ · Open" opens the server it just added.
+    private func openServer(_ name: String) {
+        NotificationCenter.default.post(name: .switchToServers, object: nil)
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.3) {
+            NotificationCenter.default.post(name: .showServerDetail, object: name)
+        }
+    }
+
     private func add(_ server: RepositoryServer) async {
         guard let client = apiClient, let reg = server.registry else { return }
         addingID = server.id
@@ -353,6 +377,7 @@ struct ServerBrowseView: View {
         let result = await client.addServerFromRegistry(registryID: reg, serverID: server.id)
         if result.success {
             addNote = "Added “\(server.name)”. New servers start quarantined — review under Servers."
+            addedServers[server.id] = server.name
         } else if let missing = result.missingInputs, !missing.isEmpty {
             addNote = "“\(server.name)” needs input: \(missing.joined(separator: ", ")). Add it from the Web UI to supply those values."
         } else {
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ServerDetailView.swift b/native/macos/MCPProxy/MCPProxy/Views/ServerDetailView.swift
index b9b523e0b..5ecbbbc60 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/ServerDetailView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/ServerDetailView.swift
@@ -1763,12 +1763,9 @@ struct ToolRow: View {
     }
 
     private func approvalStatusLabel(_ status: String) -> String {
-        switch status {
-        case "approved": return "Approved"
-        case "pending": return "Pending Approval"
-        case "changed": return "Changed (needs re-approval)"
-        default: return status.capitalized
-        }
+        // Spec 109 FR-027: one vocabulary, shared with ToolsView and the Web
+        // UI — see ToolLabels.swift.
+        ToolLabels.approvalStatusLabel(status)
     }
 
     // MARK: - Diff Section
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ToolsView.swift b/native/macos/MCPProxy/MCPProxy/Views/ToolsView.swift
index ffc903496..db98c92be 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/ToolsView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/ToolsView.swift
@@ -36,6 +36,21 @@ struct ToolsView: View {
         let name: String
         let description: String
         let score: Double?
+        /// Spec 109 FR-028: server-computed tier (`read`|`write`|`destructive`
+        /// |`unannotated`), never derived locally. `nil` for an older core
+        /// that does not yet send it.
+        let tier: String?
+
+        // Explicit initializer (rather than relying on the synthesized
+        // memberwise one) so every existing call site that predates `tier`
+        // keeps compiling unchanged.
+        init(server: String, name: String, description: String, score: Double?, tier: String? = nil) {
+            self.server = server
+            self.name = name
+            self.description = description
+            self.score = score
+            self.tier = tier
+        }
 
         /// The canonical MCP identity — what an agent would actually call.
         var qualified: String { server.isEmpty ? name : "\(server):\(name)" }
@@ -155,6 +170,14 @@ struct ToolsView: View {
                     .padding(.horizontal, 5).padding(.vertical, 1)
                     .background(Color.accentColor.opacity(0.15))
                     .clipShape(Capsule())
+                if let tier = row.tier {
+                    Text(ToolLabels.tierLabel(tier))
+                        .font(.scaled(.caption2, scale: fontScale))
+                        .padding(.horizontal, 5).padding(.vertical, 1)
+                        .background(tierColor(tier).opacity(0.15))
+                        .foregroundStyle(tierColor(tier))
+                        .clipShape(Capsule())
+                }
                 Spacer()
                 if let score = row.score {
                     Text(String(format: "%.2f", score))
@@ -175,6 +198,15 @@ struct ToolsView: View {
         .accessibilityLabel("\(row.qualified). \(row.description)")
     }
 
+    private func tierColor(_ tier: String) -> Color {
+        switch tier {
+        case "destructive": return .red
+        case "write": return .orange
+        case "read": return .green
+        default: return .secondary
+        }
+    }
+
     private func openServer(_ server: String) {
         guard !server.isEmpty else { return }
         NotificationCenter.default.post(name: .switchToServers, object: nil)
@@ -202,12 +234,12 @@ struct ToolsView: View {
             if term.isEmpty {
                 fetched = try await client.allTools().map {
                     ToolRow(server: $0.serverName ?? "", name: $0.name,
-                            description: $0.description ?? "", score: nil)
+                            description: $0.description ?? "", score: nil, tier: $0.tier)
                 }
             } else {
                 fetched = try await client.searchTools(query: term).map {
                     ToolRow(server: $0.tool.serverName ?? "", name: $0.tool.name,
-                            description: $0.tool.description ?? "", score: $0.score)
+                            description: $0.tool.description ?? "", score: $0.score, tier: $0.tool.tier)
                 }
             }
             guard generation == loadGeneration else { return }
diff --git a/native/macos/MCPProxy/MCPProxyTests/ToolLabelsTests.swift b/native/macos/MCPProxy/MCPProxyTests/ToolLabelsTests.swift
new file mode 100644
index 000000000..8d0bde956
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/ToolLabelsTests.swift
@@ -0,0 +1,58 @@
+import XCTest
+@testable import MCPProxy
+
+// Spec 109 FR-027 / FR-028 (T017): approval-state labels and tier labels must
+// equal the terminology table in
+// specs/109-ux-navigation-consistency/spec.md#terminology-binding-for-every-surface
+// exactly — this is the Swift half of the cross-surface parity test (Web
+// vitest asserts the same table from contracts.ts).
+final class ToolLabelsTests: XCTestCase {
+    func testApprovalStatusLabels() {
+        XCTAssertEqual(ToolLabels.approvalStatusLabel("approved"), "Approved")
+        XCTAssertEqual(ToolLabels.approvalStatusLabel("pending"), "New, needs review")
+        XCTAssertEqual(ToolLabels.approvalStatusLabel("changed"), "Changed, needs review")
+    }
+
+    func testApprovalStatusLabelsDropTheOldWording() {
+        for label in ["approved", "pending", "changed"].map(ToolLabels.approvalStatusLabel) {
+            XCTAssertFalse(label.lowercased().contains("awaiting"), "\(label) still carries the retired 'awaiting' wording")
+            XCTAssertFalse(label == "Pending Approval", "pending must not read as the old 'Pending Approval'")
+        }
+    }
+
+    func testApprovalStatusLabelHandlesMissingOrUnknownGracefully() {
+        XCTAssertEqual(ToolLabels.approvalStatusLabel(nil), "Unknown")
+        XCTAssertEqual(ToolLabels.approvalStatusLabel(""), "")
+    }
+
+    func testTierLabels() {
+        XCTAssertEqual(ToolLabels.tierLabel("read"), "Read")
+        XCTAssertEqual(ToolLabels.tierLabel("write"), "Write")
+        XCTAssertEqual(ToolLabels.tierLabel("destructive"), "Destructive")
+        XCTAssertEqual(ToolLabels.tierLabel("unannotated"), "Unannotated")
+        XCTAssertEqual(ToolLabels.tierLabel("unknown"), "Unknown")
+    }
+
+    func testTierLabelDefaultsToUnannotatedForMissingValue() {
+        // A tool with no tier from an older core, or a nil field, is never
+        // silently shown as "read" (X11: tier used to be computed as a
+        // fallback-to-read locally — that is exactly the bug FR-028 removes).
+        XCTAssertEqual(ToolLabels.tierLabel(nil), "Unannotated")
+    }
+
+    func testServerToolDecodesTierFromTheBackendPayload() throws {
+        let json = """
+        {"name": "delete_file", "description": "d", "server_name": "fs", "tier": "destructive", "approval_status": "approved"}
+        """.data(using: .utf8)!
+        let tool = try JSONDecoder().decode(ServerTool.self, from: json)
+        XCTAssertEqual(tool.tier, "destructive")
+    }
+
+    func testSearchToolDecodesTierFromTheBackendPayload() throws {
+        let json = """
+        {"name": "read_file", "description": "d", "server_name": "fs", "tier": "read"}
+        """.data(using: .utf8)!
+        let tool = try JSONDecoder().decode(SearchTool.self, from: json)
+        XCTAssertEqual(tool.tier, "read")
+    }
+}

From 7b08df19817f2ffff4bdbca5239702e7f5665cc9 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 25 Sep 2026 20:08:41 +0300
Subject: [PATCH 04/27] chore(oas): regenerate OpenAPI spec for Tool.tier

make swagger, after adding contracts.Tier / Tool.Tier.
---
 oas/docs.go      |  2 +-
 oas/swagger.yaml | 15 +++++++++++++++
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/oas/docs.go b/oas/docs.go
index fd523c8af..0e091b147 100644
--- a/oas/docs.go
+++ b/oas/docs.go
@@ -6,7 +6,7 @@ import "github.com/swaggo/swag/v2"
 
 const docTemplate = `{
     "schemes": {{ marshal .Schemes }},
-    "components": {"schemas":{"config.AuditLogConfig":{"description":"AuditLog configures the Spec 107 edition-neutral audit sink\n(internal/audit). nil means \"use the per-edition/per-transport\ndefault\" (EffectiveAuditLog); restart-pinned (bound at sink\nconstruction). See audit_log.go.","properties":{"compress":{"type":"boolean"},"enabled":{"type":"boolean"},"max_age_days":{"type":"integer"},"max_backups":{"type":"integer"},"max_size_mb":{"type":"integer"},"path":{"type":"string"},"stdout":{"type":"boolean"}},"type":"object"},"config.ConcurrencyDefaults":{"description":"ServerConcurrencyDefaults is scope (b) of FR-020: the blanket per-server\ndefault set inherited by every server that does not override a setting.\nAbsent (the default) = no per-server limiting unless a server configures\nit explicitly. File/API-configured only — no env scheme (FR-022).","properties":{"max_concurrent_requests":{"type":"integer"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"}},"type":"object"},"config.Config":{"properties":{"activity_cleanup_interval_min":{"description":"Background cleanup interval in minutes (default: 60)","type":"integer"},"activity_max_records":{"description":"Max records before pruning (default: 100000)","type":"integer"},"activity_max_response_size":{"description":"Response truncation limit in bytes (default: 65536)","type":"integer"},"activity_max_size_mb":{"description":"ActivityMaxSizeMB caps the total activity-log size in MB before the\noldest records are pruned. Omit the key for the 256MB default; set it to\n0 to disable the size cap.","type":"integer"},"activity_retention_days":{"description":"Activity logging settings (RFC-003)","type":"integer"},"aggregate_upstream_prompts":{"description":"AggregateUpstreamPrompts, when true, aggregates every connected upstream\nserver's advertised MCP prompts into mcpproxy's own prompts/list\n(exposed as \"\u003cserver\u003e__\u003cprompt\u003e\"). OFF by default: users are safe by\ndefault and opt in deliberately. EnablePrompts still governs the built-in\nprompts + the prompts capability; this flag gates ONLY the upstream\naggregation performed by RefreshPrompts. Hot-reloadable.","type":"boolean"},"allow_private_registry_fetch":{"description":"AllowPrivateRegistryFetch opts out of the registry SSRF guard (MCP-1076,\nCWE-918). By default (false) registry fetches refuse any host that is — or\nresolves to — a non-routable address (loopback, RFC1918/CGNAT private,\nlink-local incl. the 169.254.169.254 cloud-metadata endpoint), so a\nmalicious or typo'd registry source cannot turn the daemon into a\nrequest-forgery vector against internal services.\n\nThis opt-out is BLANKET (all-or-nothing): setting it true disables the\nguard for EVERY non-routable range at once — loopback, RFC1918/CGNAT\nprivate, link-local AND the 169.254.169.254 cloud-metadata endpoint. There\nis no way to allow only loopback; enabling it for a localhost dev registry\nalso re-opens the cloud-metadata SSRF vector. Set true ONLY when you\nintentionally run a trusted registry mirror on an internal/private address,\nideally on a host with no cloud-metadata exposure. The change takes effect\nonly on daemon (re)start or config reload.","type":"boolean"},"allow_server_add":{"type":"boolean"},"allow_server_remove":{"type":"boolean"},"api_key":{"description":"Security settings","type":"string"},"audit_log":{"$ref":"#/components/schemas/config.AuditLogConfig"},"call_tool_timeout":{"type":"string"},"check_server_repo":{"description":"Repository detection settings","type":"boolean"},"code_execution_max_parallel":{"description":"Default concurrency for call_tools() batches (1-32, default: 8)","type":"integer"},"code_execution_max_tool_calls":{"description":"Max tool calls per execution (0 = unlimited, default: 0)","type":"integer"},"code_execution_pool_size":{"description":"JavaScript runtime pool size (default: 10)","type":"integer"},"code_execution_timeout_ms":{"description":"Timeout in milliseconds (default: 120000, max: 600000)","type":"integer"},"data_dir":{"type":"string"},"debug_search":{"type":"boolean"},"direct_tool_response_mode":{"description":"DirectToolResponseMode selects the serialization of the DIRECT\nenumeration surface (Spec 102). Valid values: \"\" (= full), \"full\"\n(default: today's schema-bearing entries), \"deferred\" (description +\ncompact signature, with a minimal permissive input schema; upstream\ninputSchema and outputSchema are stripped and recovered on demand via\ndescribe_tool).\n\nDeliberately NOT an extension of tool_response_mode: reusing that axis\nwould silently change /mcp/all output for every deployment already\nrunning compact, which FR-015 forbids. Serialization-only — it never\nchanges WHICH tools are listed, only how (FR-008). Hot-reloadable.","type":"string"},"disable_management":{"type":"boolean"},"docker_isolation":{"$ref":"#/components/schemas/config.DockerIsolationConfig"},"docker_recovery":{"$ref":"#/components/schemas/config.DockerRecoveryConfig"},"enable_code_execution":{"description":"Code execution settings","type":"boolean"},"enable_prompts":{"description":"Prompts settings","type":"boolean"},"enable_socket":{"description":"Enable Unix socket/named pipe for local IPC (default: true)","type":"boolean"},"enable_tray":{"description":"Deprecated: EnableTray is unused and has no runtime effect. Kept for backward compatibility.","type":"boolean"},"environment":{"$ref":"#/components/schemas/secureenv.EnvConfig"},"features":{"$ref":"#/components/schemas/config.FeatureFlags"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned stdio upstream servers (MCP-2769). OFF by\ndefault: proxy URLs commonly embed credentials (http://user:pass@proxy), so\nforwarding them to every upstream is a credential-leak risk. When enabled,\nvalues are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"health_check_interval":{"description":"Discovery \u0026 health-check cadence (spec 074, #608). Both are *Duration\ntri-state pointers: nil = inherit the built-in default; a pointer to 0s =\nthe loop is disabled; a positive value = that interval. Defaults live only\nin the resolvers (ResolveHealthCheckInterval / ResolveToolDiscoveryInterval)\nso an unset key behaves exactly as before this feature (SC-005). Validated\nin Validate(): health-check ∈ {0} ∪ [5s,1h]; tool-discovery ∈ {0} ∪ [30s,24h].","type":"string"},"http_idle_timeout":{"description":"HTTPIdleTimeout caps how long an idle keep-alive connection is kept open.\nUnset = 180s. \"0s\" removes the dedicated idle deadline, but net/http then\nfalls back to ReadTimeout — idle is fully unbounded only when\nhttp_read_timeout is also \"0s\". Requires a restart.","type":"string"},"http_read_timeout":{"description":"HTTPReadTimeout caps how long reading a whole request (headers + body)\nmay take. Unset = 120s; \"0s\" disables it. Requires a restart.","type":"string"},"http_write_timeout":{"description":"HTTPWriteTimeout caps how long producing a whole response may take on\nnon-streaming endpoints (REST, Web UI, health). Unset = 120s; \"0s\"\ndisables it globally. MCP and SSE /events routes are exempt by design.","type":"string"},"init_timeout":{"description":"InitTimeout is the global default deadline for an upstream's MCP\n` + "`" + `initialize` + "`" + ` handshake (MCP-3322 / GH #760). *Duration tri-state: nil =\ninherit the built-in 30s default; a positive value = that deadline. A\nper-server InitTimeout overrides this. Resolved by ResolveInitTimeout;\nvalidated to {0} ∪ [1s, 30m] in Validate(). Servers doing legitimate\nfirst-run warmup (cache/index build) before answering ` + "`" + `initialize` + "`" + ` can\nraise this so they are not killed mid-startup.","type":"string"},"instructions":{"description":"Instructions text returned in the MCP initialize response to guide AI agents.\nWhen empty, a built-in default is used that explains retrieve_tools workflow.","type":"string"},"intent_declaration":{"$ref":"#/components/schemas/config.IntentDeclarationConfig"},"listen":{"type":"string"},"logging":{"$ref":"#/components/schemas/config.LogConfig"},"max_concurrent_requests":{"description":"Concurrency limits (spec 093, GH #955). Scope (a) of FR-020: the GLOBAL\nAGGREGATE limiter — one proxy-wide cap on concurrently running upstream\ntool calls, with its own bounded wait queue. Tri-state pointers: absent =\nthe limiter does not exist (default, zero behavior change); an explicit 0\nmax also disables it; positive = that cap. This scope is NEVER a\nper-server inheritance source — per-server values come from\nServerConcurrencyDefaults / the per-server overrides — but a server's\neffective concurrency is bounded by BOTH its own limiter and this one.\nResolved by ResolveGlobalConcurrency; hot-reloadable; overridable via\nMCPPROXY_MAX_CONCURRENT_REQUESTS / _QUEUE_SIZE / _QUEUE_TIMEOUT (FR-022).","type":"integer"},"max_result_size_chars":{"description":"MaxResultSizeChars is advertised on every tool as\n` + "`" + `_meta.anthropic/maxResultSizeChars` + "`" + `; it raises Claude Code's\ninline-response ceiling from 50k to up to 500k chars. Omit the key for\nthe 500000 default; set it to 0 to disable the annotation.","type":"integer"},"mcpServers":{"items":{"$ref":"#/components/schemas/config.ServerConfig"},"type":"array","uniqueItems":false},"oauth_expiry_warning_hours":{"description":"Health status settings","type":"number"},"observability":{"$ref":"#/components/schemas/config.ObservabilityConfig"},"output_sanitisation":{"$ref":"#/components/schemas/config.OutputSanitisationConfig"},"output_validation":{"$ref":"#/components/schemas/config.OutputValidationConfig"},"profiles":{"description":"Profiles are optional named, server-scoped views exposed at /mcp/p/\u003cname\u003e\n(Spec 057). Absent/empty is fully supported — /mcp is unchanged and configs\nwithout this key serialize byte-identically (SC-004).","items":{"$ref":"#/components/schemas/config.ProfileConfig"},"type":"array","uniqueItems":false},"quarantine_enabled":{"description":"QuarantineEnabled controls whether quarantine is active. It gates two\nthings together:\n  1. Server-level auto-quarantine for newly added servers (issue #370).\n     When true, servers added via the upstream_servers MCP tool or the\n     REST API default to quarantined=true; when false, they default to\n     quarantined=false. Explicit per-request values always win.\n  2. Tool-level quarantine (Spec 032): per-tool SHA-256 approval of\n     tool descriptions/schemas.\nWhen nil (default), quarantine is enabled (secure by default). Set to\nexplicit false to opt out of both. Per-server SkipQuarantine still\napplies for the tool-level check on individual servers.","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"read_only_mode":{"type":"boolean"},"registries":{"description":"Registries configuration for MCP server discovery","items":{"$ref":"#/components/schemas/config.RegistryEntry"},"type":"array","uniqueItems":false},"registries_locked":{"description":"RegistriesLocked is an enterprise stub knob (MCP-866): when true, runtime\nadditions of custom registries (e.g. ` + "`" + `registry add-source` + "`" + `, the REST/MCP\nadd-source surface) are rejected so an administrator can pin the discovery\nsources. Built-in defaults are unaffected. Documented but otherwise inert\nbeyond the add-source rejection.","type":"boolean"},"require_mcp_auth":{"description":"Require authentication on /mcp endpoint (default: false)","type":"boolean"},"reveal_secret_headers":{"description":"RevealSecretHeaders, when true, disables the redaction of the\nsecret-bearing server fields — sensitive header values (Authorization,\nX-API-Key, Cookie, …), env-var secrets, and URL query credentials — in\nresponses from the ` + "`" + `upstream_servers` + "`" + ` MCP tool, the ` + "`" + `/api/v1/servers` + "`" + `\nREST API, and the SSE event stream. It also lets URL secrets echoed\ninto last_error / health.detail through unscrubbed.\n\nDefault false — sensitive values are surfaced masked as\n` + "`" + `••••\u003clast2\u003e (\u003cN\u003e chars)` + "`" + ` (error strings use ` + "`" + `***REDACTED***` + "`" + `) so an\nMCP agent cannot read Bearer tokens / API keys / URL secrets out of\nanother upstream's config (PR #425, issue #872). ${env:…}/${keyring:…}\nreferences are labels, not secrets, and pass through unchanged.\n\nThe Web UI / macOS tray edit forms work without seeing the real\nvalues: PATCH /api/v1/servers/{id} deep-merges (omitted keys are\npreserved, see ` + "`" + `headers_remove` + "`" + ` / ` + "`" + `env_remove` + "`" + ` for explicit\ndeletes), so clients compute a diff and only send the keys that\nactually changed. Redacted-but-unchanged values never round-trip\n— the backend keeps the real string. Set this to true if a\ndownstream tool genuinely needs raw values in the response.","type":"boolean"},"routing_mode":{"description":"Routing mode (Spec 031): how MCP tools are exposed to clients\nValid values: \"retrieve_tools\" (default), \"direct\", \"code_execution\"","type":"string"},"security":{"$ref":"#/components/schemas/config.SecurityConfig"},"sensitive_data_detection":{"$ref":"#/components/schemas/config.SensitiveDataDetectionConfig"},"server_concurrency_defaults":{"$ref":"#/components/schemas/config.ConcurrencyDefaults"},"telemetry":{"$ref":"#/components/schemas/config.TelemetryConfig"},"tls":{"$ref":"#/components/schemas/config.TLSConfig"},"tokenizer":{"$ref":"#/components/schemas/config.TokenizerConfig"},"tool_call_max_records_per_server":{"description":"Calls retained per server (default: 1000)","type":"integer"},"tool_call_max_response_size":{"description":"Bounds for the per-server tool-call history behind GET /api/v1/tool-calls\n(#1176). It is a recent-debugging window, not an audit log — the activity\nlog is the durable record — and it kept every upstream response whole,\nper server, forever. A non-positive value means \"use the default\", not\n\"disable\": this store must never be unbounded again, so there is\ndeliberately no off switch.","type":"integer"},"tool_discovery_interval":{"type":"string"},"tool_response_limit":{"type":"integer"},"tool_response_mode":{"description":"Tool response mode (Spec 085): how retrieve_tools serializes results.\nValid values: \"\" (= full), \"full\" (default: today's schema-bearing\nentries), \"compact\" (signature + first-sentence entries). Orthogonal to\nrouting_mode — routing_mode selects the tool SURFACE, this selects the\nSERIALIZATION within the retrieve_tools surface. Serialization-only: it\nnever affects the query, ranking, or result set. Hot-reloadable.","type":"string"},"tool_response_session_risk_warning":{"description":"ToolResponseSessionRiskWarning controls whether the prose ` + "`" + `warning` + "`" + ` field\nis included in the ` + "`" + `session_risk` + "`" + ` object returned by ` + "`" + `retrieve_tools` + "`" + `.\nThe structured fields (level, lethal_trifecta, has_open_world_tools, etc.)\nare always included. Default: false (quiet for LLM clients) — see issue #406.\nMost tools lack annotations, so the MCP-spec defaults treat them as fully\npermissive across all three risk axes, which makes the prose warning fire\non almost every call and wastes tokens.","type":"boolean"},"tools_limit":{"type":"integer"},"toon_min_savings_pct":{"description":"ToonMinSavingsPct is the minimum byte-savings percentage (validated\n1-90; 0/unset → 15) the complete TOON emission (marker + hint + body)\nmust achieve over the exact passthrough emission for adaptive mode to\nencode a block. Byte savings approximate token savings for the tabular\npayload class; the spec-083 profiler reports true token deltas.\nGlobal-only (no per-server override, FR-001).","type":"integer"},"toon_output":{"description":"ToonOutput selects the TOON encoding mode for call_tool_* result text\nblocks (spec 084): \"off\" (default — responses byte-identical to\npre-feature behavior), \"adaptive\" (encode only tabular-uniform payloads\nthat beat compact JSON by ToonMinSavingsPct), or \"always\"\n(benchmark/debug only — encodes every JSON-parseable block and can\nINCREASE token cost). Per-server override: ServerConfig.ToonOutput.\nResolved by ResolveToonOutput; hot-reloadable.","type":"string"},"top_k":{"description":"Deprecated: TopK is superseded by ToolsLimit and has no runtime effect. Kept for backward compatibility.","type":"integer"},"tray_endpoint":{"description":"Tray endpoint override (unix:// or npipe://)","type":"string"},"trusted_hosts":{"description":"TrustedHosts lists non-loopback Host header values accepted on loopback\nlisteners (GH #898). DNS-rebinding protection rejects requests whose Host\nheader is not a loopback address when mcpproxy listens on loopback; a\nreverse proxy (nginx → 127.0.0.1) forwarding the public domain in Host\ntrips it. Entries are hostnames, case-insensitive; an entry without a\nport matches any port, with a port it must match exactly; a leading dot\n(\".example.com\") is a subdomain wildcard. The single entry \"*\" disables\nHost and Origin validation entirely. The same list also validates the\nOrigin header when present (MCP spec DNS-rebinding defense). Empty\n(default) keeps full protection. Env override: MCPPROXY_TRUSTED_HOSTS\n(comma-separated).","items":{"type":"string"},"type":"array","uniqueItems":false},"trusted_proxies":{"description":"TrustedProxies lists the CIDRs or IP addresses whose X-Forwarded-For /\nX-Real-IP / X-Forwarded-Proto / X-Forwarded-Host headers are believed\n(Spec 107 FR-027). Empty (default) trusts nobody. Edition-neutral, live\n(hot-reloadable). Env override: MCPPROXY_TRUSTED_PROXIES (comma-separated).\nThe one reader is ForwardedHeaders; validation is validateTrustedProxies.","items":{"type":"string"},"type":"array","uniqueItems":false},"update_check":{"$ref":"#/components/schemas/config.UpdateCheckConfig"}},"type":"object"},"config.CustomPattern":{"properties":{"category":{"description":"Category (defaults to \"custom\")","type":"string"},"keywords":{"description":"Keywords to match (mutually exclusive with Regex)","items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"description":"Unique identifier for this pattern","type":"string"},"regex":{"description":"Regex pattern (mutually exclusive with Keywords)","type":"string"},"severity":{"description":"Risk level: critical, high, medium, low","type":"string"}},"type":"object"},"config.DeepScanConfig":{"description":"DeepScan is the opt-in \"deep scan\" layer (Spec 077 US3). It subsumes the\ndeprecated top-level scanner_fetch_package_source / scanner_disable_no_new_privileges\nkeys (migrated on load) and gates the heavy Docker-based scanners + source\nextraction. Disabled by default (FR-006): only the deterministic in-process\nbaseline scanner runs. A deep-scan failure NEVER changes the baseline verdict\n(FR-007/FR-008).","properties":{"disable_no_new_privileges":{"description":"DisableNoNewPrivileges, when true, omits the ` + "`" + `--security-opt\nno-new-privileges` + "`" + ` flag from scanner container runs (snap-docker/AppArmor\nescape hatch). Absorbs the deprecated top-level\nscanner_disable_no_new_privileges. Default false.","type":"boolean"},"enabled":{"description":"Enabled is the master opt-in for the heavy layer (FR-006). Default false.","type":"boolean"},"fetch_package_source":{"description":"FetchPackageSource controls whether the scanner fetches the PUBLISHED\nsource of package-runner servers (npx/uvx) — without executing it — when\nno local source is available. Absorbs the deprecated top-level\nscanner_fetch_package_source. Default (nil) is ENABLED within deep scan.","type":"boolean"},"scanners":{"description":"Scanners optionally restricts which deep scanners may run under the\numbrella (by scanner id). Empty ⇒ all enabled deep scanners are eligible.","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.DockerIsolationConfig":{"description":"Docker isolation settings","properties":{"cpu_limit":{"description":"CPU limit for containers","type":"string"},"default_images":{"additionalProperties":{"type":"string"},"description":"Map of runtime type to Docker image","type":"object"},"enable_cache_volume":{"description":"Mount shared cache volumes for faster restarts (default: true)","type":"boolean"},"enabled":{"description":"Global enable/disable for Docker isolation (legacy; superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments","items":{"type":"string"},"type":"array","uniqueItems":false},"log_driver":{"description":"Docker log driver (default: json-file)","type":"string"},"log_max_files":{"description":"Maximum number of log files (default: 3)","type":"string"},"log_max_size":{"description":"Maximum size of log files (default: 100m)","type":"string"},"memory_limit":{"description":"Memory limit for containers","type":"string"},"mode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"network_mode":{"description":"Docker network mode (default: bridge)","type":"string"},"registry":{"description":"Custom registry (defaults to docker.io)","type":"string"},"timeout":{"description":"Container startup timeout","type":"string"}},"type":"object"},"config.DockerRecoveryConfig":{"description":"Docker recovery settings","properties":{"enabled":{"description":"Enable Docker recovery monitoring (default: true)","type":"boolean"},"max_retries":{"description":"Maximum retry attempts (0 = unlimited)","type":"integer"},"notify_on_failure":{"description":"Show notification on recovery failure (default: true)","type":"boolean"},"notify_on_retry":{"description":"Show notification on each retry (default: false)","type":"boolean"},"notify_on_start":{"description":"Show notification when recovery starts (default: true)","type":"boolean"},"notify_on_success":{"description":"Show notification on successful recovery (default: true)","type":"boolean"},"persistent_state":{"description":"Save recovery state across restarts (default: true)","type":"boolean"}},"type":"object"},"config.FeatureFlags":{"description":"Deprecated: Features flags are unused and have no runtime effect. Kept for backward compatibility.","properties":{"enable_async_storage":{"type":"boolean"},"enable_caching":{"type":"boolean"},"enable_contract_tests":{"type":"boolean"},"enable_debug_logging":{"description":"Development features","type":"boolean"},"enable_docker_isolation":{"type":"boolean"},"enable_event_bus":{"type":"boolean"},"enable_health_checks":{"type":"boolean"},"enable_metrics":{"type":"boolean"},"enable_oauth":{"description":"Security features","type":"boolean"},"enable_observability":{"description":"Observability features","type":"boolean"},"enable_quarantine":{"type":"boolean"},"enable_runtime":{"description":"Runtime features","type":"boolean"},"enable_search":{"description":"Storage features","type":"boolean"},"enable_sse":{"type":"boolean"},"enable_tracing":{"type":"boolean"},"enable_tray":{"type":"boolean"},"enable_web_ui":{"description":"UI features","type":"boolean"}},"type":"object"},"config.IntentDeclarationConfig":{"description":"Intent declaration settings (Spec 018)","properties":{"strict_server_validation":{"description":"StrictServerValidation controls whether server annotation mismatches\ncause rejection (true) or just warnings (false).\nDefault: true (reject mismatches)","type":"boolean"}},"type":"object"},"config.IsolationConfig":{"description":"Per-server isolation settings","properties":{"enabled":{"description":"Enable Docker isolation for this server (nil = inherit global; legacy, superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments for this server","items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"description":"Custom Docker image (overrides default)","type":"string"},"log_driver":{"description":"Docker log driver override for this server","type":"string"},"log_max_files":{"description":"Maximum number of log files override","type":"string"},"log_max_size":{"description":"Maximum size of log files override","type":"string"},"mode":{"$ref":"#/components/schemas/config.IsolationMode"},"network_mode":{"description":"Custom network mode for this server","type":"string"},"working_dir":{"description":"Custom working directory in container","type":"string"}},"type":"object"},"config.IsolationMode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"config.LogConfig":{"description":"Logging configuration","properties":{"compress":{"type":"boolean"},"enable_console":{"type":"boolean"},"enable_file":{"type":"boolean"},"filename":{"type":"string"},"json_format":{"type":"boolean"},"level":{"type":"string"},"log_dir":{"description":"Custom log directory","type":"string"},"max_age":{"description":"days","type":"integer"},"max_backups":{"description":"number of backup files","type":"integer"},"max_size":{"description":"MB","type":"integer"}},"type":"object"},"config.MetricsExporterConfig":{"description":"Metrics gates the Prometheus /metrics scrape endpoint (MCP-32). Disabled\nby default — operators opt in for k8s/enterprise deployments.","properties":{"enabled":{"description":"Enabled exposes /metrics on the existing HTTP listener when true.\nThe endpoint is admin-authenticated (SEC-07): scrapers must present the\nglobal API key, via X-API-Key or an Authorization: Bearer header.","type":"boolean"}},"type":"object"},"config.OAuthConfig":{"description":"OAuth configuration (keep even when empty to signal OAuth requirement)","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"description":"Additional OAuth parameters (e.g., RFC 8707 resource)","type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_uri":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ObservabilityConfig":{"description":"Observability settings (Spec 069): usage aggregate cache/persistence cadence.","properties":{"metrics":{"$ref":"#/components/schemas/config.MetricsExporterConfig"},"tracing":{"$ref":"#/components/schemas/config.TracingExporterConfig"},"usage_cache_ttl":{"description":"UsageCacheTTL bounds the freshness of the usage endpoint's read cache for\nwide windows (FR-005). Default 5s.","type":"string"},"usage_persist_interval":{"description":"UsagePersistInterval is how often the actor-owned usage aggregate snapshot\nis flushed to storage. Default 30s.","type":"string"}},"type":"object"},"config.OutputSanitisationConfig":{"description":"Output sanitisation settings (Spec 054 Track B)","properties":{"max_redactions":{"description":"cap on redactions per response; default 100","type":"integer"},"response_action":{"description":"\"spotlight\" | \"redact\" | \"block\"; default \"spotlight\"","type":"string"},"spotlight_untrusted":{"description":"wrap untrusted output in spotlight markers; default true","type":"boolean"},"strip_classes":{"description":"classes to strip: ansi/c0c1/bidi/zero_width","items":{"type":"string"},"type":"array","uniqueItems":false},"strip_control_chars":{"description":"strip control-character classes; default false","type":"boolean"}},"type":"object"},"config.OutputValidationConfig":{"description":"Output-schema validation settings (Spec 056)","properties":{"max_bytes":{"description":"structured payload byte cap; default 5\u003c\u003c20","type":"integer"},"max_depth":{"description":"nesting depth cap; default 64","type":"integer"},"missing_structured_content":{"description":"\"allow\" | \"block\"; default \"allow\"","type":"string"},"mode":{"description":"\"off\" | \"warn\" | \"strict\"; default \"warn\"","type":"string"}},"type":"object"},"config.ProfileConfig":{"properties":{"name":{"description":"URL slug, validated","type":"string"},"servers":{"description":"references to mcpServers[].name","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.RegistryEntry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag for this registry (MCP-866):\nRegistryProvenanceOfficial for built-in defaults, RegistryProvenanceCustom\nfor user-added registries. It is authoritatively (re)computed by the\nregistries merge from whether the ID is a shipped default — a user cannot\nclaim \"official\" by writing it into their config.","type":"string"},"requires_key":{"description":"RequiresKey marks a registry that needs an API key to be queried. When\ntrue and no key is configured, the registry is skipped/marked unavailable\nrather than failing the whole search (FR-008).","type":"boolean"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"type":"string"}},"type":"object"},"config.SecurityConfig":{"description":"Security scanner settings (Spec 039)","properties":{"auto_baseline_scan":{"description":"AutoBaselineScan is the kill-switch for the AUTOMATIC, informational\nPass-1 baseline scan: the free in-process TPA scan mcpproxy runs for every\nnewly admitted server (any trust mode) and, once per installation, over\npre-existing servers that have never been scanned.\n\nInformational ONLY: the resulting verdict populates the security badge and\nthe scan summary, and NEVER gates quarantine or approval. The\ntrust_mode:\"scan\" admission gate is a separate path and is unaffected by\nthis flag.\n\nDefault (nil) is ENABLED. Set to false to suppress every automatic scan\n(manual scans keep working). Env override: MCPPROXY_AUTO_BASELINE_SCAN,\nwhich wins over this field on every path.","type":"boolean"},"deep_scan":{"$ref":"#/components/schemas/config.DeepScanConfig"},"integrity_check_interval":{"type":"string"},"integrity_check_on_restart":{"type":"boolean"},"runtime_read_only":{"type":"boolean"},"runtime_tmpfs_size":{"type":"string"},"scan_timeout_default":{"type":"string"},"scanner_disable_no_new_privileges":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.DisableNoNewPrivileges\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.IsDisableNoNewPrivileges. Cleared after migration.\n\nScannerDisableNoNewPrivileges, when true, omits the\n` + "`" + `--security-opt no-new-privileges` + "`" + ` flag from scanner container runs.\n\nBackground: snap-installed Docker on Ubuntu confines dockerd under the\n` + "`" + `snap.docker.dockerd` + "`" + ` AppArmor profile. When runc tries to transition\nthe container into the inner ` + "`" + `docker-default` + "`" + ` profile to exec the\nentrypoint, AppArmor refuses the transition because NO_NEW_PRIVS\nforbids privilege/profile changes on exec — the result is EPERM\n(\"operation not permitted\") and every scanner fails immediately.\n\nSet this to true ONLY on hosts hitting that incompatibility. Scanner\ncontainers still run with read-only rootfs, tmpfs /tmp, no-network by\ndefault, and read-only source mounts, so the marginal isolation loss\nis small. The preferred fix remains replacing snap docker with a\ndistro-packaged docker.","type":"boolean"},"scanner_fetch_package_source":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.FetchPackageSource\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.EffectiveFetchPackageSource. Cleared after migration.\n\nScannerFetchPackageSource controls whether the scanner fetches the\nPUBLISHED source of package-runner servers (npx/uvx) — without executing\nit — when no local source is available (no Docker container, no local\npackage cache, no working_dir). This is the primary quarantine/scan\ntarget: a quarantined-on-add server is never run locally, so without this\nthe scan degrades to tool-definitions-only (no real source-level\nanalysis). See MCP-2206.\n\nFetching uses ` + "`" + `npm pack --ignore-scripts` + "`" + ` (npm) and ` + "`" + `uv pip download` + "`" + ` /\n` + "`" + `pip download` + "`" + ` with ` + "`" + `--only-binary=:all:` + "`" + ` (Python), which only download +\nunpack archives and NEVER run install, build, or setup.py — a scanner must\nnot execute the untrusted code it is scanning. The Python\n` + "`" + `--only-binary=:all:` + "`" + ` flag is required because downloading an sdist would\ninvoke its build backend (setup.py); packages with no wheel fall back to\ntool-definitions-only instead. Extraction is hardened against path\ntraversal and decompression bombs.\n\nDefault (nil) is ENABLED. Set to false on air-gapped deployments to\nforbid the scanner's network egress; such servers then fall back to the\ntool-definitions-only scan with no regression.","type":"boolean"},"scanner_registry_url":{"type":"string"},"tpa_bundle_path":{"description":"TPABundlePath is the filesystem path to the tpa-db scanner-bundle.json\nthe offline TPA scanner runs (spec 086 FR-019: the signature-DB location\nMUST be configuration-driven, not hardcoded). Empty (the default) runs the\ncorpus embedded in this build.\n\nEnv override: MCPPROXY_TPA_BUNDLE_PATH. Hot-reloadable — the path is\nre-read on every config.reloaded event via\nscanner.Service.ApplySecurityConfig, so a corpus refresh needs no restart.\nA configured bundle that fails to read/parse/version-check/compile is\nREFUSED and the previously active corpus stays live (fail-closed, never\nfail-empty); the reason is logged and surfaced in the security overview's\nsignature_bundle.load_error.","type":"string"}},"type":"object"},"config.SensitiveDataDetectionConfig":{"description":"Sensitive data detection settings (Spec 026)","properties":{"categories":{"additionalProperties":{"type":"boolean"},"description":"Enable/disable specific detection categories","type":"object"},"custom_patterns":{"description":"User-defined detection patterns","items":{"$ref":"#/components/schemas/config.CustomPattern"},"type":"array","uniqueItems":false},"enabled":{"description":"Enable sensitive data detection (default: true)","type":"boolean"},"entropy_threshold":{"description":"Shannon entropy threshold for high-entropy detection (default: 4.5)","type":"number"},"max_payload_size_kb":{"description":"Max size to scan before truncating (default: 1024)","type":"integer"},"scan_requests":{"description":"Scan tool call arguments (default: true)","type":"boolean"},"scan_responses":{"description":"Scan tool responses (default: true)","type":"boolean"},"sensitive_keywords":{"description":"Keywords to flag","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ServerConfig":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve tool\nchanges/additions (disabling per-server rug-pull protection). Supersedes\nskip_quarantine. MCP-2930 only ACCEPTS, persists, and migrates this flag — it\nis NOT yet consulted at runtime; auto-approval is still governed by\nSkipQuarantine until the trust-baseline behavior change (MCP-2931) migrates the\nruntime consumers onto it.\nTri-state pointer (mirrors QuarantineEnabled): nil = unset (inherit/migrate\nfrom legacy skip_quarantine), explicit true/false = honored as-is so an\nexplicit auto_approve_tool_changes:false overrides a legacy skip_quarantine:true.\nRead via IsAutoApproveToolChanges().","type":"boolean"},"command":{"type":"string"},"created":{"type":"string"},"disabled_tools":{"description":"Denylist: these tools are hidden; mutually exclusive with enabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"},"enabled_tools":{"description":"Allowlist: only these tools are exposed; mutually exclusive with disabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts overrides whether this server's advertised MCP prompts are\naggregated into mcpproxy's prompts/list. nil (default) inherits the\ndefault-aggregate behavior (included if the server advertises\nCapabilities.Prompts); false excludes it regardless of capability.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"description":"For HTTP servers","type":"object"},"health_check_interval":{"description":"Per-server discovery \u0026 health-check overrides (spec 074). Same *Duration\ntri-state as the global keys: nil = inherit the global value (or default),\npointer to 0s = disabled for this server, positive = that interval.\nHealthCheckInterval is fully wired into the per-server health loop;\nToolDiscoveryInterval is accepted/validated and round-trips for\nforward-compat, but the periodic index sweep is governed by the global\ncadence in this iteration (see spec 074 plan §C).","type":"string"},"init_timeout":{"description":"InitTimeout overrides the global init_timeout for this server's MCP\n` + "`" + `initialize` + "`" + ` handshake deadline (MCP-3322 / GH #760). *Duration tri-state:\nnil = inherit the global value (or 30s default), positive = that deadline.\nResolved by Config.ResolveInitTimeout; validated to {0} ∪ [1s, 30m]. Raise\nthis for upstreams that do legitimate first-run warmup (e.g. caching many\nchannels/users) before responding to ` + "`" + `initialize` + "`" + `.","type":"string"},"isolation":{"$ref":"#/components/schemas/config.IsolationConfig"},"launcher_wait_timeout":{"description":"LauncherWaitTimeout caps how long mcpproxy will wait for a locally-launched\nHTTP/SSE upstream's URL to become reachable after Spawn(). Only consulted\nwhen the server is configured with both Command and an HTTP/SSE URL — i.e.,\nmcpproxy starts the process AND connects via network. Stdio servers ignore\nthis field. Zero or unset → 30s default.","type":"string"},"max_concurrent_requests":{"description":"Per-server concurrency overrides — scope (c) of FR-020 (spec 093, #955).\nTri-state per setting, exactly like HealthCheckInterval: absent = inherit\nthe per-server default set (server_concurrency_defaults), explicit 0 =\ndisable that setting for this server (0 max = no per-server limiter at\nall; 0 queue_size = no pending capacity, shed immediately at the cap),\npositive = override. The global aggregate limiter is never inherited from\nhere — it applies on top, so effective concurrency is min(per-server,\nglobal). Resolved by Config.ResolveServerConcurrency.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/config.OAuthConfig"},"protocol":{"description":"stdio, http, sse, streamable-http, auto","type":"string"},"quarantined":{"description":"Security quarantine status","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets a disconnected server","type":"boolean"},"shared":{"description":"Server edition: shared with all users","type":"boolean"},"skip_quarantine":{"description":"SkipQuarantine is DEPRECATED (MCP-2930): use AutoApproveToolChanges instead.\nKept for back-compat parsing; on config load a legacy skip_quarantine:true is\nmigrated to auto_approve_tool_changes:true only when the new field is unset\n(see normalizeServerQuarantineFlags).","type":"boolean"},"source_registry_id":{"description":"SourceRegistryID records which registry this server was added from (empty\nfor manually-configured servers). MCP-866: surfaced in the approval /\nquarantine view so a reviewer can see a server's origin.","type":"string"},"source_registry_provenance":{"description":"SourceRegistryProvenance records the source registry's provenance at add\ntime (RegistryProvenanceOfficial / RegistryProvenanceCustom). It is purely\ninformational (MCP-1072) — surfaced so a reviewer can see a server's origin\n— and no longer gates quarantine or skip_quarantine.","type":"string"},"tool_discovery_interval":{"type":"string"},"toon_output":{"description":"ToonOutput overrides the global toon_output mode for this server's\ntools (spec 084, FR-001). Plain string, not a pointer: \"\"/absent =\ninherit the global value; \"off\"|\"adaptive\"|\"always\" = override (\"off\"\nis the explicit force-off). Resolved by Config.ResolveToonOutput.","type":"string"},"trust_mode":{"description":"TrustMode is the per-server trust tier: auto|scan|manual. Supersedes\nauto_approve_tool_changes (spec 086). An empty value is derived from the\nlegacy fields at load via normalizeServerQuarantineFlags; the single\nresolution point is EffectiveTrustMode(), which treats an empty or\nunrecognized value as manual (secure by default). Read via\nEffectiveTrustMode(), never the raw string.","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"working_dir":{"description":"Working directory for stdio servers","type":"string"}},"type":"object"},"config.TLSConfig":{"description":"TLS configuration","properties":{"certs_dir":{"description":"Directory for certificates","type":"string"},"enabled":{"description":"Enable HTTPS","type":"boolean"},"hsts":{"description":"Enable HTTP Strict Transport Security","type":"boolean"},"require_client_cert":{"description":"Enable mTLS","type":"boolean"}},"type":"object"},"config.TelemetryConfig":{"description":"Telemetry settings (Spec 036)","properties":{"anonymous_id":{"description":"Auto-generated UUIDv4","type":"string"},"anonymous_id_created_at":{"description":"Spec 042 (Tier 2) additions — all default-zero, all backwards-compatible.","type":"string"},"enabled":{"description":"Default: true (opt-out)","type":"boolean"},"endpoint":{"description":"Override for testing","type":"string"},"last_reported_version":{"description":"Upgrade funnel","type":"string"},"last_startup_outcome":{"description":"success|port_conflict|db_locked|...","type":"string"},"notice_shown":{"description":"First-run notice flag","type":"boolean"}},"type":"object"},"config.TokenizerConfig":{"description":"Tokenizer configuration for token counting","properties":{"default_model":{"description":"Default model for tokenization (e.g., \"gpt-4\")","type":"string"},"enabled":{"description":"Enable token counting","type":"boolean"},"encoding":{"description":"Default encoding (e.g., \"cl100k_base\")","type":"string"}},"type":"object"},"config.TracingExporterConfig":{"description":"Tracing gates the OpenTelemetry OTLP trace exporter (MCP-32). Disabled by\ndefault.","properties":{"enabled":{"description":"Enabled turns on OTLP trace export for tool calls and upstream hops.","type":"boolean"},"endpoint":{"description":"Endpoint is the collector address as host:port (no scheme), e.g.\n\"localhost:4318\" for http or \"localhost:4317\" for grpc.","type":"string"},"protocol":{"description":"Protocol selects the OTLP transport: \"http\" or \"grpc\".","type":"string"},"sample_rate":{"description":"SampleRate is the head-based trace sampling ratio in [0,1]. Default 0.1.\nOmit the key for the 0.1 default; set it to 0 to sample nothing.","type":"number"}},"type":"object"},"config.UpdateCheckConfig":{"description":"Update-check settings (Spec 079 FR-012): config-file control of the\nbackground upgrade-awareness checker (internal/updatecheck). nil =\nenabled on the stable channel (existing default behavior). The existing\nenvironment switches keep working and WIN over these keys (FR-014):\nMCPPROXY_DISABLE_AUTO_UPDATE=true force-disables even when\nenabled=true, and MCPPROXY_ALLOW_PRERELEASE_UPDATES=true force-selects\nthe rc channel even when channel=stable.","properties":{"channel":{"description":"Channel selects which releases are offered as updates: \"stable\"\n(default; prereleases never offered) or \"rc\" (prereleases included).\nEmpty resolves to stable. Validated in ValidateDetailed.\n\nNOTE: for a RELEASED build the running binary's own version is\nauthoritative and overrides this field — a stable build is never\noffered an RC (even with channel=rc), and an RC build always tracks the\nrc channel. This field only takes effect on dev/unstamped builds. See\ninternal/updatecheck.Checker.IncludePrereleases.","type":"string"},"enabled":{"description":"Enabled gates all update checking. Tri-state: nil/absent = enabled\n(default true, matching pre-079 behavior). When false, no network\ncheck is performed and no upgrade nudge appears on any surface\n(FR-015) — /api/v1/info omits the update object entirely.","type":"boolean"}},"type":"object"},"configimport.FailedServer":{"properties":{"details":{"type":"string"},"error":{"type":"string"},"name":{"type":"string"}},"type":"object"},"configimport.ImportSummary":{"properties":{"failed":{"type":"integer"},"imported":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"configimport.SkippedServer":{"properties":{"name":{"type":"string"},"reason":{"description":"\"already_exists\", \"filtered_out\", \"invalid_name\"","type":"string"}},"type":"object"},"connect.ConnectResult":{"description":"The full result; its action mirrors the top-level one","properties":{"action":{"description":"\"created\", \"updated\", \"already_exists\", \"removed\", \"not_found\"","type":"string"},"backup_path":{"type":"string"},"client":{"type":"string"},"config_path":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.APIResponse":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ActivityDetailResponse":{"properties":{"activity":{"$ref":"#/components/schemas/contracts.ActivityRecord"}},"type":"object"},"contracts.ActivityListResponse":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/contracts.ActivityRecord"},"type":"array","uniqueItems":false},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.ActivityRecord":{"properties":{"agent_name":{"description":"Agent token name when auth_type is \"agent\"","type":"string"},"arguments":{"description":"Tool call arguments","type":"object"},"auth_type":{"description":"\"admin\", \"agent\", \"user\" or \"admin_user\"; empty without an auth context or on another caller's row for a scoped caller","type":"string"},"detection_types":{"description":"List of detection types found","items":{"type":"string"},"type":"array","uniqueItems":false},"duration_ms":{"description":"Execution duration in milliseconds","type":"integer"},"error_message":{"description":"Error details if status is \"error\"","type":"string"},"has_sensitive_data":{"description":"Sensitive data detection fields (Spec 026)","type":"boolean"},"id":{"description":"Unique identifier (ULID format)","type":"string"},"max_severity":{"description":"Highest severity level detected (critical, high, medium, low)","type":"string"},"metadata":{"description":"Additional context-specific data","type":"object"},"parent_id":{"description":"Correlation id of the parent call (the code_execution whose sandbox issued this sub-call)","type":"string"},"request_bytes":{"description":"Byte sizes measured pre-truncation, mirroring storage.ActivityRecord\n(Spec 069 A1). They are the only cost signal a bodies-off export carries:\nwith payloads suppressed there is no text left to measure, so a consumer\naccounting for a record it cannot read has nothing else to go on. They are\nbyte LENGTHS, not token counts — the basis for an explicit estimate, never\na measured figure (spec 103, contracts/replay-input.md).\n\nZero means UNKNOWN, not free: legacy records predate the measurement and\ncode-execution sub-calls record both as zero. Hence omitempty — an absent\nkey tells a consumer to fall to exclusion accounting, whereas a present\nzero would read as a costless call and silently understate the workload.","type":"integer"},"request_id":{"description":"HTTP request ID for correlation","type":"string"},"response":{"description":"Tool response (potentially truncated)","type":"string"},"response_bytes":{"description":"Raw upstream response size in bytes before truncation","type":"integer"},"response_truncated":{"description":"True if response was truncated","type":"boolean"},"server_name":{"description":"Name of upstream MCP server","type":"string"},"session_id":{"description":"MCP transport session ID (regenerated on every reconnect)","type":"string"},"source":{"$ref":"#/components/schemas/contracts.ActivitySource"},"status":{"description":"Result status: \"success\", \"error\", \"blocked\", \"rejected\"","type":"string"},"timestamp":{"description":"When activity occurred","type":"string"},"tool_name":{"description":"Name of tool called","type":"string"},"type":{"$ref":"#/components/schemas/contracts.ActivityType"},"work_session_id":{"description":"Spec 082: one client, one project, across reconnects","type":"string"}},"type":"object"},"contracts.ActivitySource":{"description":"How activity was triggered: \"mcp\", \"cli\", \"api\"","type":"string","x-enum-varnames":["ActivitySourceMCP","ActivitySourceCLI","ActivitySourceAPI"]},"contracts.ActivitySummaryResponse":{"properties":{"blocked_count":{"description":"Count of blocked activities","type":"integer"},"call_count":{"description":"CallCount is how many of those records are CALLS THE USER MADE, as\ndefined once in storage.CountsAsCall and shared with the usage aggregate\nbehind the Usage tab (audit finding F1, #1046). TotalCount answers \"how\nmany rows does the Activity Log have\"; CallCount answers \"how many calls\nwere there\". They are different questions — quarantine auto-approvals,\nsystem start, security scans and management chatter are events, not calls\n— and printing either one under the other's label is how the same instance\ncame to report 51 calls on one screen and 19 on another.","type":"integer"},"call_error_count":{"description":"CallErrorCount is the failures within CallCount, so an error RATE computed\nfrom this response has one denominator. It is not ErrorCount: a policy\nblock is a failed call but carries status \"blocked\", and a shed call is an\nerror in neither sense because it never ran.","type":"integer"},"end_time":{"description":"End of the period (RFC3339)","type":"string"},"error_count":{"description":"Count of error activities","type":"integer"},"other_count":{"description":"OtherCount is every record whose status is outside the four-value\nvocabulary above, so that\n\n\tsuccess + error + blocked + rejected + other == total\n\nholds by construction. The status field is a CLOSED vocabulary for tool\ncalls, but the activity log is wider than tool calls: a quarantine change\nstores its ACTION there (\"approved\", \"auto_approved\"), a policy decision\nstores its DECISION (\"allow\"). Those rows were counted in the total and in\nnone of the four buckets, so the Activity Log's own status tiles summed to\nless than the denominator printed beside them — 15+4+0+0 under a \"42\"\n(audit finding F2, #1046). The residual now has a name and a tile.","type":"integer"},"period":{"description":"Time period (1h, 24h, 7d, 30d)","type":"string"},"rejected_count":{"description":"RejectedCount is the number of calls shed by a concurrency limiter before\nthey reached an upstream (spec 093). Counted separately from errors: it is\nproxy backpressure, not an upstream fault, and it is the signal an\noperator right-sizes max_concurrent_requests against.","type":"integer"},"start_time":{"description":"Start of the period (RFC3339)","type":"string"},"success_count":{"description":"Count of successful activities","type":"integer"},"top_servers":{"description":"Top servers by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopServer"},"type":"array","uniqueItems":false},"top_tools":{"description":"Top tools by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopTool"},"type":"array","uniqueItems":false},"total_count":{"description":"Total activity count","type":"integer"}},"type":"object"},"contracts.ActivityTopServer":{"properties":{"count":{"description":"Activity count","type":"integer"},"name":{"description":"Server name","type":"string"}},"type":"object"},"contracts.ActivityTopTool":{"properties":{"count":{"description":"Activity count","type":"integer"},"server":{"description":"Server name","type":"string"},"tool":{"description":"Tool name","type":"string"}},"type":"object"},"contracts.ActivityType":{"description":"Type of activity","type":"string","x-enum-varnames":["ActivityTypeToolCall","ActivityTypePolicyDecision","ActivityTypeQuarantineChange","ActivityTypeServerChange"]},"contracts.AddFromRegistryRequest":{"properties":{"enabled":{"description":"defaults to true when nil","type":"boolean"},"env":{"additionalProperties":{"type":"string"},"description":"overrides + required-input values","type":"object"},"name":{"description":"optional name override","type":"string"}},"type":"object"},"contracts.AddRegistrySourceRequest":{"properties":{"id":{"description":"derived from the host when empty","type":"string"},"name":{"description":"defaults to the id","type":"string"},"protocol":{"description":"defaults to modelcontextprotocol/registry","type":"string"},"url":{"description":"required https registry URL","type":"string"}},"type":"object"},"contracts.ConfigApplyResult":{"properties":{"applied_immediately":{"type":"boolean"},"changed_fields":{"items":{"type":"string"},"type":"array","uniqueItems":false},"requires_restart":{"type":"boolean"},"restart_reason":{"type":"string"},"success":{"type":"boolean"},"validation_errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DCRStatus":{"properties":{"attempted":{"type":"boolean"},"error":{"type":"string"},"status_code":{"type":"integer"},"success":{"type":"boolean"}},"type":"object"},"contracts.DeepScanDescriptor":{"description":"DeepScan reports the opt-in \"deep scan\" layer status (Spec 077 US3),\nSEPARATELY from the baseline verdict above. Always emitted on a computed\nsummary — when deep scan is off (the default) it reports enabled=false\nplus any enabled-but-skipped Docker scanners. It never influences Status.","properties":{"available":{"type":"boolean"},"enabled":{"type":"boolean"},"ran":{"type":"boolean"},"scanners_failed":{"items":{"$ref":"#/components/schemas/contracts.DeepScanScannerFailure"},"type":"array","uniqueItems":false},"skipped_scanners":{"description":"SkippedScanners lists Docker scanners the user enabled that are skipped\nbecause security.deep_scan.enabled is false (informational).","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DeepScanScannerFailure":{"properties":{"id":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"contracts.DeprecatedConfigWarning":{"properties":{"field":{"type":"string"},"message":{"type":"string"},"replacement":{"type":"string"}},"type":"object"},"contracts.Diagnostic":{"description":"Spec 044 — structured diagnostic error and stable error code. Both\nare populated when the server is in a failed state and the error\nhas been classified by internal/diagnostics. Healthy servers omit\nthese fields.","properties":{"cause":{"type":"string"},"code":{"type":"string"},"detected_at":{"type":"string"},"docs_url":{"type":"string"},"fix_steps":{"items":{"$ref":"#/components/schemas/contracts.DiagnosticFixStep"},"type":"array","uniqueItems":false},"severity":{"type":"string"},"user_message":{"type":"string"}},"type":"object"},"contracts.DiagnosticFixStep":{"properties":{"command":{"type":"string"},"destructive":{"type":"boolean"},"fixer_key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"}},"type":"object"},"contracts.Diagnostics":{"properties":{"deprecated_configs":{"description":"Deprecated config fields found","items":{"$ref":"#/components/schemas/contracts.DeprecatedConfigWarning"},"type":"array","uniqueItems":false},"docker_status":{"$ref":"#/components/schemas/contracts.DockerStatus"},"missing_secrets":{"description":"Renamed to avoid conflict","items":{"$ref":"#/components/schemas/contracts.MissingSecretInfo"},"type":"array","uniqueItems":false},"oauth_issues":{"description":"OAuth parameter mismatches","items":{"$ref":"#/components/schemas/contracts.OAuthIssue"},"type":"array","uniqueItems":false},"oauth_required":{"items":{"$ref":"#/components/schemas/contracts.OAuthRequirement"},"type":"array","uniqueItems":false},"runtime_warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false},"timestamp":{"type":"string"},"total_issues":{"type":"integer"},"upstream_errors":{"items":{"$ref":"#/components/schemas/contracts.UpstreamError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DockerStatus":{"properties":{"available":{"type":"boolean"},"error":{"type":"string"},"version":{"type":"string"}},"type":"object"},"contracts.EditRegistrySourceRequest":{"properties":{"name":{"description":"new display name","type":"string"},"servers_url":{"description":"explicit servers-collection URL","type":"string"},"url":{"description":"new base/servers https URL","type":"string"}},"type":"object"},"contracts.ErrorResponse":{"properties":{"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.FindingCounts":{"properties":{"dangerous":{"description":"Tool poisoning, active prompt injection","type":"integer"},"info":{"description":"Low-severity CVEs, informational","type":"integer"},"total":{"type":"integer"},"warning":{"description":"Rug pull, supply chain CVEs with exploits","type":"integer"}},"type":"object"},"contracts.GetConfigResponse":{"properties":{"config":{"description":"The configuration object","type":"object"},"config_path":{"description":"Path to config file","type":"string"}},"type":"object"},"contracts.GetRegistriesResponse":{"properties":{"registries":{"items":{"$ref":"#/components/schemas/contracts.Registry"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerLogsResponse":{"properties":{"count":{"type":"integer"},"logs":{"items":{"$ref":"#/components/schemas/contracts.LogEntry"},"type":"array","uniqueItems":false},"server_name":{"type":"string"}},"type":"object"},"contracts.GetServerToolCallsResponse":{"properties":{"server_name":{"type":"string"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerToolsResponse":{"properties":{"count":{"type":"integer"},"server_name":{"type":"string"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GetServersResponse":{"properties":{"servers":{"items":{"$ref":"#/components/schemas/contracts.Server"},"type":"array","uniqueItems":false},"stats":{"$ref":"#/components/schemas/contracts.ServerStats"}},"type":"object"},"contracts.GetSessionDetailResponse":{"properties":{"session":{"$ref":"#/components/schemas/contracts.MCPSession"}},"type":"object"},"contracts.GetSessionsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"sessions":{"items":{"$ref":"#/components/schemas/contracts.MCPSession"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetToolCallDetailResponse":{"properties":{"tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"}},"type":"object"},"contracts.GetToolCallsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GlobalToolsResponse":{"properties":{"failed_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"partial":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/contracts.GlobalToolsStats"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GlobalToolsStats":{"properties":{"disabled":{"type":"integer"},"enabled":{"type":"integer"},"pending_approval":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.HealthStatus":{"description":"Unified health status calculated by the backend","properties":{"action":{"description":"Action is the suggested fix action: \"login\", \"restart\", \"enable\", \"approve\", \"view_logs\", \"set_secret\", \"configure\", \"edit_url\", or \"\" (none)","type":"string"},"admin_state":{"description":"AdminState indicates the admin state: \"enabled\", \"disabled\", or \"quarantined\"","type":"string"},"detail":{"description":"Detail is an optional longer explanation of the status","type":"string"},"level":{"description":"Level indicates the health level: \"healthy\", \"degraded\", or \"unhealthy\"","type":"string"},"summary":{"description":"Summary is a human-readable status message (e.g., \"Connected (5 tools)\")","type":"string"}},"type":"object"},"contracts.InfoEndpoints":{"description":"Available API endpoints","properties":{"http":{"description":"HTTP endpoint address (e.g., \"127.0.0.1:8080\")","type":"string"},"socket":{"description":"Unix socket path (empty if disabled)","type":"string"}},"type":"object"},"contracts.InfoResponse":{"properties":{"endpoints":{"$ref":"#/components/schemas/contracts.InfoEndpoints"},"launched_by":{"description":"LaunchedBy is the durable launch provenance of the running core (Spec\n092 FR-001a): \"tray\" when a tray spawned it, \"installer\" when the macOS\nPKG postinstall did, \"\" when user-launched or unknown. Always present\n(possibly empty) so a tray can distinguish \"old core, not mine\" from\n\"old core I may supersede\".","type":"string"},"listen_addr":{"description":"Listen address (e.g., \"127.0.0.1:8080\")","type":"string"},"pid":{"description":"PID is the operating-system process id of the running core (Spec 092\nFR-002). A tray that merely ATTACHED to a core holds no Process handle\nfor it, so without this there is no mechanism at all to stop a stale\ncore — the consent action would have nothing to act on and could only\nprint instructions. Paired with LaunchedBy it is what lets a newer tray\nsupersede a core an older tray started.","type":"integer"},"update":{"$ref":"#/components/schemas/contracts.UpdateInfo"},"update_policy":{"$ref":"#/components/schemas/contracts.UpdatePolicy"},"version":{"description":"Current MCPProxy version","type":"string"},"web_ui_url":{"description":"URL to access the web control panel","type":"string"}},"type":"object"},"contracts.IsolationConfig":{"properties":{"cpu_limit":{"type":"string"},"enabled":{"description":"Enabled is the EFFECTIVE isolation state for this server: whether its\nprocess is actually CONFINED, after the global setting, the per-server\noverride, the structural gates and the host's capabilities. It is NOT the\nraw per-server override — read EnabledOverride for that (GH #1142).\n\nREAD-ONLY. The write surfaces reject an ` + "`" + `enabled` + "`" + ` key precisely because\nit is derived: echoing it back would convert \"inherits the global\nsetting\" into a permanent explicit override. Write EnabledOverride.\n\nIt stays a non-pointer bool that is always present on the wire: the macOS\ntray decodes it as a non-optional Swift Bool, so omitting or nulling the\nkey would fail Codable for the whole server payload. Older clients that\nread this field now simply get a true answer.","type":"boolean"},"enabled_override":{"description":"EnabledOverride is the RAW per-server ` + "`" + `isolation.enabled` + "`" + ` override, as\npersisted. Absent means \"inherit the global setting\" — which is a\ndistinct state from an explicit false, and the distinction the reporting\nbug used to destroy.","type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"memory_limit":{"type":"string"},"mode_override":{"description":"ModeOverride is the RAW per-server ` + "`" + `isolation.mode` + "`" + ` override\n(\"docker\" | \"sandbox\" | \"none\"). Absent means \"inherit\".","type":"string"},"network_mode":{"type":"string"},"timeout":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationDefaults":{"description":"IsolationDefaults exposes the resolved baseline values that\nwould apply when no per-server override is set. Populated on\nlist/get responses; never consumed on PATCH requests.","properties":{"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"network_mode":{"type":"string"},"runtime_type":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationEffective":{"description":"IsolationEffective exposes the resolved isolation state (and the rule\nthat decided it) so clients can distinguish \"inherits global\" from an\nexplicit per-server choice. Read-only; never consumed on PATCH.","properties":{"global_mode":{"description":"GlobalMode is what \"inherit\" resolves to right now.","type":"string"},"inherited":{"description":"Inherited is true when the server sets neither ` + "`" + `isolation.enabled` + "`" + ` nor\n` + "`" + `isolation.mode` + "`" + `, so its state tracks the global setting.","type":"boolean"},"isolated":{"description":"Isolated reports whether the process is actually CONFINED. It is NOT\nsimply Mode != \"none\": \"sandbox\" on a host that cannot enforce Landlock\n(any non-Linux OS, or a kernel without the LSM) runs the server\nunconfined, and Source then says \"sandbox-unavailable\" (GH #1142).","type":"boolean"},"mode":{"description":"Mode is the effective isolation mode: \"docker\" | \"sandbox\" | \"none\" —\nexactly what the spawn path branches on.","type":"string"},"source":{"description":"Source names the deciding rule: \"global\", \"server-mode\",\n\"server-opt-out\", \"server-opt-in-ignored\", \"not-stdio\",\n\"already-docker\", \"sandbox-unavailable\" or \"unsupported-mode\".\nTreat an unrecognized value as \"global\".","type":"string"}},"type":"object"},"contracts.LogEntry":{"properties":{"fields":{"type":"object"},"level":{"type":"string"},"message":{"type":"string"},"server":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.MCPSession":{"properties":{"client_name":{"type":"string"},"client_version":{"type":"string"},"end_time":{"type":"string"},"experimental":{"items":{"type":"string"},"type":"array","uniqueItems":false},"has_roots":{"description":"MCP Client Capabilities","type":"boolean"},"has_sampling":{"type":"boolean"},"id":{"type":"string"},"last_activity":{"type":"string"},"start_time":{"type":"string"},"status":{"type":"string"},"tool_call_count":{"type":"integer"},"total_tokens":{"type":"integer"},"work_session_id":{"type":"string"},"workspace_name":{"description":"Workspace / work session (Spec 082). WorkspaceName is the project's\nbasename — the full local path is never exposed. WorkSessionID groups the\nreconnects that make up one stretch of user work.","type":"string"}},"type":"object"},"contracts.MetadataStatus":{"properties":{"authorization_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"error":{"type":"string"},"found":{"type":"boolean"},"url_checked":{"type":"string"}},"type":"object"},"contracts.MissingSecretInfo":{"properties":{"secret_name":{"type":"string"},"used_by":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.NPMPackageInfo":{"properties":{"exists":{"type":"boolean"},"install_cmd":{"type":"string"}},"type":"object"},"contracts.OAuthConfig":{"properties":{"auth_url":{"type":"string"},"client_id":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_port":{"type":"integer"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false},"token_expires_at":{"description":"When the OAuth token expires","type":"string"},"token_url":{"type":"string"},"token_valid":{"description":"Whether token is currently valid","type":"boolean"}},"type":"object"},"contracts.OAuthErrorDetails":{"description":"Structured discovery/failure details","properties":{"authorization_server_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"dcr_status":{"$ref":"#/components/schemas/contracts.DCRStatus"},"protected_resource_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"server_url":{"type":"string"}},"type":"object"},"contracts.OAuthFlowError":{"properties":{"correlation_id":{"description":"Flow tracking ID for log correlation","type":"string"},"debug_hint":{"description":"CLI command for log lookup","type":"string"},"details":{"$ref":"#/components/schemas/contracts.OAuthErrorDetails"},"error_code":{"description":"Machine-readable error code (e.g., OAUTH_NO_METADATA)","type":"string"},"error_type":{"description":"Category of OAuth runtime failure","type":"string"},"message":{"description":"Human-readable error description","type":"string"},"request_id":{"description":"HTTP request ID (from PR #237)","type":"string"},"server_name":{"description":"Server that failed OAuth","type":"string"},"success":{"description":"Always false","type":"boolean"},"suggestion":{"description":"Actionable remediation hint","type":"string"}},"type":"object"},"contracts.OAuthIssue":{"properties":{"documentation_url":{"type":"string"},"error":{"type":"string"},"issue":{"type":"string"},"missing_params":{"items":{"type":"string"},"type":"array","uniqueItems":false},"resolution":{"type":"string"},"server_name":{"type":"string"}},"type":"object"},"contracts.OAuthRequirement":{"properties":{"expires_at":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"state":{"type":"string"}},"type":"object"},"contracts.OAuthStartResponse":{"properties":{"auth_url":{"description":"Authorization URL (always included for manual use)","type":"string"},"browser_error":{"description":"Error message if browser launch failed","type":"string"},"browser_opened":{"description":"Whether browser launch succeeded","type":"boolean"},"correlation_id":{"description":"UUID for tracking this flow","type":"string"},"message":{"description":"Human-readable status message","type":"string"},"server_name":{"description":"Name of the server being authenticated","type":"string"},"success":{"description":"Always true for successful start","type":"boolean"}},"type":"object"},"contracts.PreflightPolicy":{"properties":{"exclude_destructive":{"type":"boolean"},"exclude_open_world":{"type":"boolean"},"read_only_only":{"type":"boolean"}},"type":"object"},"contracts.PreflightReason":{"type":"string","x-enum-varnames":["PreflightReasonServerInitializing","PreflightReasonServerUnhealthy","PreflightReasonServerDisabled","PreflightReasonServerQuarantined","PreflightReasonToolPendingApproval","PreflightReasonToolChanged","PreflightReasonToolBlockedByUser","PreflightReasonOAuthRequired","PreflightReasonHashMismatch","PreflightReasonServerNotInScope","PreflightReasonToolDeniedByConfig","PreflightReasonMissingAnnotation","PreflightReasonPolicyFiltered","PreflightReasonNotFound","PreflightReasonServerNotConfigured"]},"contracts.PreflightRequest":{"properties":{"policy":{"$ref":"#/components/schemas/contracts.PreflightPolicy"},"profile":{"description":"Profile evaluates under a named profile's server scope. Unknown: 400.","type":"string"},"tools":{"description":"Tools is 1..100 entries BEFORE dedup; duplicates are collapsed, and\nduplicate ids carrying different pins are a validation error.","items":{"$ref":"#/components/schemas/contracts.PreflightToolRef"},"type":"array","uniqueItems":false},"wait_ms":{"description":"WaitMS polls local state for up to this many milliseconds (cap 10000)\nwhile every failure is retryable-class.","type":"integer"}},"type":"object"},"contracts.PreflightResponse":{"properties":{"checked_at":{"type":"string"},"tools":{"description":"Tools are ordered by first occurrence of each unique id in the request.","items":{"$ref":"#/components/schemas/contracts.PreflightToolResult"},"type":"array","uniqueItems":false},"verdict":{"$ref":"#/components/schemas/contracts.PreflightVerdict"},"waited_ms":{"description":"WaitedMS is present when wait_ms was requested (0 when the wait\nsemaphore was exhausted and the request resolved immediately).","type":"integer"}},"type":"object"},"contracts.PreflightStatus":{"type":"string","x-enum-varnames":["PreflightStatusReady","PreflightStatusUnavailable"]},"contracts.PreflightToolRef":{"properties":{"id":{"description":"ID is a canonical \"\u003cserver\u003e:\u003ctool\u003e\" id. A malformed id is answered with a\nper-ID not_found carrying a format hint, never a request-level error.","type":"string"},"pin_hash":{"description":"PinHash is \"sha256/v{N}:{hex}\" — the schema version is embedded so a\nproxy-side hash-algorithm bump is distinguishable from upstream drift.","type":"string"}},"type":"object"},"contracts.PreflightToolResult":{"properties":{"action":{"type":"string"},"detail":{"type":"string"},"did_you_mean":{"description":"DidYouMean carries up to 3 nearest caller-visible ids on not_found. It\nnever crosses a scope boundary and never names a quarantined server's\ntools.","items":{"type":"string"},"type":"array","uniqueItems":false},"hash":{"description":"Hash is the tool's current pin (\"sha256/v{N}:{hex}\") — operator tier,\nready results only. Never disclosed to an agent token.","type":"string"},"id":{"type":"string"},"reason":{"$ref":"#/components/schemas/contracts.PreflightReason"},"remediation":{"type":"string"},"retryable":{"type":"boolean"},"status":{"$ref":"#/components/schemas/contracts.PreflightStatus"}},"type":"object"},"contracts.PreflightVerdict":{"type":"string","x-enum-varnames":["PreflightVerdictReady","PreflightVerdictDegradedRetryable","PreflightVerdictBlocked","PreflightVerdictUnknownIDs"]},"contracts.QuarantineStats":{"description":"Tool quarantine metrics for this server","properties":{"blocked_count":{"description":"Number of disabled (blocked) tools","type":"integer"},"changed_count":{"description":"Number of tools whose description/schema changed since approval","type":"integer"},"pending_count":{"description":"Number of newly discovered tools awaiting approval","type":"integer"}},"type":"object"},"contracts.RefreshRegistryResponse":{"properties":{"cleared":{"description":"number of cached entries dropped","type":"integer"},"registry_id":{"type":"string"}},"type":"object"},"contracts.Registry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag (MCP-866): \"official/trusted\" for built-in\ndefaults, \"custom/unverified\" for user-added registries.","type":"string"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"trusted":{"description":"Trusted indicates whether this is an official, shipped-by-default\nregistry. Trust is derived from membership in the default set, never\nfrom self-assertion in config.","type":"boolean"},"url":{"type":"string"}},"type":"object"},"contracts.RegistryCacheInfo":{"properties":{"age_seconds":{"type":"number"},"stale":{"type":"boolean"}},"type":"object"},"contracts.RegistryUnavailable":{"properties":{"reason":{"type":"string"}},"type":"object"},"contracts.ReplayToolCallRequest":{"properties":{"arguments":{"description":"Modified arguments for replay","type":"object"}},"type":"object"},"contracts.ReplayToolCallResponse":{"properties":{"error":{"description":"Error if replay failed","type":"string"},"new_call_id":{"description":"ID of the newly created call","type":"string"},"new_tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"replayed_from":{"description":"Original call ID","type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.RepositoryInfo":{"description":"Detected package info","properties":{"npm":{"$ref":"#/components/schemas/contracts.NPMPackageInfo"}},"type":"object"},"contracts.RepositoryServer":{"properties":{"connect_url":{"description":"Alternative connection URL","type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"install_cmd":{"description":"Installation command","type":"string"},"name":{"type":"string"},"registry":{"description":"Which registry this came from","type":"string"},"repository_info":{"$ref":"#/components/schemas/contracts.RepositoryInfo"},"source_code_url":{"description":"Source repository URL","type":"string"},"updated_at":{"type":"string"},"url":{"description":"MCP endpoint for remote servers only","type":"string"}},"type":"object"},"contracts.SearchRegistryServersResponse":{"properties":{"cache":{"$ref":"#/components/schemas/contracts.RegistryCacheInfo"},"query":{"type":"string"},"registry_id":{"type":"string"},"servers":{"items":{"$ref":"#/components/schemas/contracts.RepositoryServer"},"type":"array","uniqueItems":false},"tag":{"type":"string"},"total":{"type":"integer"},"unavailable":{"$ref":"#/components/schemas/contracts.RegistryUnavailable"}},"type":"object"},"contracts.SearchResult":{"properties":{"matches":{"type":"integer"},"score":{"type":"number"},"snippet":{"type":"string"},"tool":{"$ref":"#/components/schemas/contracts.Tool"}},"type":"object"},"contracts.SearchToolsResponse":{"properties":{"query":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/contracts.SearchResult"},"type":"array","uniqueItems":false},"took":{"type":"string"},"total":{"type":"integer"}},"type":"object"},"contracts.SecurityScanSummary":{"description":"Latest security scan results summary","properties":{"deep_scan":{"$ref":"#/components/schemas/contracts.DeepScanDescriptor"},"finding_counts":{"$ref":"#/components/schemas/contracts.FindingCounts"},"last_scan_at":{"type":"string"},"risk_score":{"description":"0-100","type":"integer"},"scanners_failed":{"type":"integer"},"scanners_run":{"description":"Scanner coverage for the primary (baseline) scan pass — informational only.\nSpec 077 US3 (FR-008/FR-014): Status is derived SOLELY from the\ndeterministic baseline findings; a failed Docker deep scanner no longer\ndowngrades a clean verdict. That failure is surfaced via DeepScan instead.","type":"integer"},"scanners_total":{"type":"integer"},"status":{"description":"\"clean\", \"warnings\", \"dangerous\", \"failed\", \"not_scanned\", \"scanning\"","type":"string"}},"type":"object"},"contracts.Server":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"authenticated":{"description":"OAuth authentication status","type":"boolean"},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges mirrors config.ServerConfig.AutoApproveToolChanges\n(MCP-2930): the per-server intent to auto-approve new/changed tools past\nthe trust baseline. Tri-state *bool — nil means \"never set\" (omitted from\nthe payload), so the Web UI toggle (MCP-2932) can distinguish unset from\nan explicit false. Read-only on the GET path; PATCH/POST accept it via\nAddServerRequest.","type":"boolean"},"command":{"type":"string"},"connected":{"type":"boolean"},"connected_at":{"type":"string"},"connecting":{"type":"boolean"},"created":{"type":"string"},"diagnostic":{"$ref":"#/components/schemas/contracts.Diagnostic"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"error_code":{"type":"string"},"expose_prompts":{"description":"ExposePrompts mirrors config.ServerConfig.ExposePrompts (F9): the per-server\nprompt-aggregation override. Tri-state *bool — nil/omitted means \"inherit\ndefault aggregation\". Surfaced on GET so a caller that PATCHed the override\ncan read it back; PATCH/POST accept it via AddServerRequest.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"health":{"$ref":"#/components/schemas/contracts.HealthStatus"},"id":{"type":"string"},"init_timeout":{"description":"InitTimeout mirrors config.ServerConfig.InitTimeout (MCP-3322 / GH #760):\nthe per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override. Serialized as\na duration string (e.g. \"120s\"); nil/omitted means \"inherit the global\ndefault\". Surfaced on the GET path so clients can read back a configured\noverride; PATCH/POST accept it via AddServerRequest.","type":"string"},"isolation":{"$ref":"#/components/schemas/contracts.IsolationConfig"},"isolation_defaults":{"$ref":"#/components/schemas/contracts.IsolationDefaults"},"isolation_effective":{"$ref":"#/components/schemas/contracts.IsolationEffective"},"last_error":{"type":"string"},"last_reconnect_at":{"type":"string"},"last_retry_time":{"type":"string"},"max_concurrent_requests":{"description":"Spec 093 (GH #955) — per-server concurrency overrides, scope (c) of\nFR-020. Each setting is tri-state: nil (omitted) means \"inherit\nserver_concurrency_defaults\", 0 disables that setting for this server,\npositive overrides it. Surfaced on the GET path so a caller can read back\nwhat it set; PATCH/POST accept them via AddServerRequest. The effective\nconcurrency for a server is additionally bounded by the global aggregate\nlimiter, which is NOT an inheritance source for these fields.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/contracts.OAuthConfig"},"oauth_status":{"description":"OAuth status: \"authenticated\", \"expired\", \"error\", \"none\"","type":"string"},"protocol":{"type":"string"},"quarantine":{"$ref":"#/components/schemas/contracts.QuarantineStats"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_count":{"type":"integer"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets this disconnected server","type":"boolean"},"retry_count":{"type":"integer"},"retry_stopped":{"description":"RetryStopped reports that automatic reconnection has been given up for\ngood because the failure is deterministic and unrecoverable — a missing\nbinary, an image without the interpreter, an unparseable config (GH\n#1145). It is NOT ordinary exponential backoff, which keeps retrying;\nnothing will happen until the user fixes the config or restarts the\nserver. RetryStoppedCode is the stable MCPX_* code that proved it and\nRetryStoppedReason the catalog message explaining how to fix it. All three\nare omitted for servers that are healthy or still retrying.","type":"boolean"},"retry_stopped_code":{"type":"string"},"retry_stopped_reason":{"type":"string"},"security_scan":{"$ref":"#/components/schemas/contracts.SecurityScanSummary"},"should_retry":{"type":"boolean"},"source_registry_id":{"description":"MCP-901 — registry provenance of an upstream that was added from a\nregistry. SourceRegistryID names the source registry (empty for\nmanually-configured servers); SourceRegistryProvenance is the trust tag\nrecorded at add time (\"official/trusted\" or \"custom/unverified\"). Both\nare projected from config.ServerConfig so the approval/quarantine view\ncan render an \"added from \u003cregistry\u003e · unverified\" origin badge. Optional\nand omitted when empty — clients that pre-date this treat them as absent.","type":"string"},"source_registry_provenance":{"type":"string"},"status":{"type":"string"},"token_expires_at":{"description":"When the OAuth token expires (ISO 8601)","type":"string"},"tool_count":{"type":"integer"},"tool_list_token_size":{"description":"Token size for this server's tools","type":"integer"},"trust_mode":{"description":"TrustMode mirrors config.ServerConfig.TrustMode (spec 086): the per-server\ntrust tier (\"auto\"/\"scan\"/\"manual\"). Surfaced on the GET path so clients can\nread back the persisted mode; PATCH/POST accept it via AddServerRequest.\nOmitted when empty (server predates the field / relies on legacy flags).","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"user_logged_out":{"description":"True if user explicitly logged out (prevents auto-reconnection)","type":"boolean"},"working_dir":{"type":"string"}},"type":"object"},"contracts.ServerActionResponse":{"properties":{"action":{"type":"string"},"async":{"type":"boolean"},"server":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ServerStats":{"properties":{"connected_servers":{"type":"integer"},"docker_containers":{"type":"integer"},"quarantined_servers":{"type":"integer"},"token_metrics":{"$ref":"#/components/schemas/contracts.ServerTokenMetrics"},"total_servers":{"type":"integer"},"total_tools":{"type":"integer"}},"type":"object"},"contracts.ServerTokenMetrics":{"properties":{"average_query_result_size":{"description":"Typical retrieve_tools output (tokens)","type":"integer"},"per_server_tool_list_sizes":{"additionalProperties":{"type":"integer"},"description":"Token size per server","type":"object"},"saved_tokens":{"description":"Difference","type":"integer"},"saved_tokens_percentage":{"description":"Percentage saved","type":"number"},"total_server_tool_list_size":{"description":"All upstream tools combined (tokens)","type":"integer"}},"type":"object"},"contracts.SuccessResponse":{"properties":{"data":{"type":"object"},"success":{"type":"boolean"}},"type":"object"},"contracts.TokenMetrics":{"description":"Token usage metrics (nil for older records)","properties":{"encoding":{"description":"Encoding used (e.g., cl100k_base)","type":"string"},"estimated_cost":{"description":"Optional cost estimate","type":"number"},"input_tokens":{"description":"Tokens in the request","type":"integer"},"model":{"description":"Model used for tokenization","type":"string"},"output_tokens":{"description":"Tokens in the response","type":"integer"},"total_tokens":{"description":"Total tokens (input + output)","type":"integer"},"truncated_tokens":{"description":"Tokens removed by truncation","type":"integer"},"was_truncated":{"description":"Whether response was truncated","type":"boolean"}},"type":"object"},"contracts.Tool":{"properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"approval_status":{"type":"string"},"config_denied":{"description":"ConfigDenied is true when the tool is denied by the server's static\nenabled_tools / disabled_tools config. The user cannot override this toggle.","type":"boolean"},"description":{"type":"string"},"disabled":{"description":"Disabled mirrors ToolApprovalRecord.Disabled so per-tool enable state is\navailable without a second round-trip to the approvals endpoint. Absent\nin the JSON when false (default) to keep responses compact.","type":"boolean"},"hash":{"description":"Hash is the tool's current stored hash rendered in the preflight pin\nformat \"sha256/v{N}:{hex}\" (Spec 098 FR-011), where N is the approval\nrecord's HashSchemaVersion. It is the authoring surface for\n` + "`" + `POST /api/v1/preflight` + "`" + ` pins and ` + "`" + `mcpproxy tools preflight --pin` + "`" + `:\ncopy the value straight into a pin.\n\nDisclosure is OPERATOR TIER ONLY — same rule as the preflight per-tool\nresult. The field is omitted for agent-token callers and for tools with\nno stored hash (no approval record yet, or a record written before\nhashes existed).","type":"string"},"held_reason":{"description":"HeldReason, HeldVerdict and HeldSignals mirror the same-named fields on\nstorage.ToolApprovalRecord: the offline-scan evidence that made\ntrust_mode: scan hold this tool for review (spec 086 FR-018). HeldSignals\nnames the matched deterministic check ids, e.g.\n\"tpa.TPA-2026-0001.hidden_instruction\", so a reviewer can see WHY the tool\nis held. All three are omitted for tools that are not held by the scan gate\n(including every record written before the field existed).","type":"string"},"held_signals":{"items":{"type":"string"},"type":"array","uniqueItems":false},"held_verdict":{"type":"string"},"last_used":{"type":"string"},"name":{"type":"string"},"schema":{"type":"object"},"server_name":{"type":"string"},"usage":{"type":"integer"}},"type":"object"},"contracts.ToolAnnotation":{"description":"Tool behavior hints snapshot","properties":{"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"},"readOnlyHint":{"type":"boolean"},"title":{"type":"string"}},"type":"object"},"contracts.ToolCallRecord":{"description":"The new tool call record","properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"arguments":{"description":"Tool arguments","type":"object"},"arguments_truncated":{"description":"ArgumentsTruncated marks Arguments as a placeholder rather than the\narguments the tool was called with. Replaying such a record without\nsupplying arguments explicitly is refused.","type":"boolean"},"config_path":{"description":"Active config file path","type":"string"},"duration":{"description":"Duration in nanoseconds","type":"integer"},"error":{"description":"Error message (failure only)","type":"string"},"execution_type":{"description":"\"direct\" or \"code_execution\"","type":"string"},"id":{"description":"Unique identifier","type":"string"},"mcp_client_name":{"description":"MCP client name from InitializeRequest","type":"string"},"mcp_client_version":{"description":"MCP client version","type":"string"},"mcp_session_id":{"description":"MCP session identifier","type":"string"},"metrics":{"$ref":"#/components/schemas/contracts.TokenMetrics"},"parent_call_id":{"description":"Links nested calls to parent code_execution","type":"string"},"request_id":{"description":"Request correlation ID","type":"string"},"response":{"description":"Tool response (success only)","type":"object"},"response_bytes":{"description":"Marshalled response size before truncation","type":"integer"},"response_truncated":{"description":"ResponseTruncated and ResponseBytes describe a STORAGE-side cut (#1176):\nthe caller received the response whole, and only the persisted copy was\nshortened to tool_call_max_response_size. When ResponseTruncated is true\nthe Response object carries {truncated, original_bytes, preview, note}\ninstead of the upstream result, and ResponseBytes is its size before the\ncut.","type":"boolean"},"server_id":{"description":"Server identity hash","type":"string"},"server_name":{"description":"Human-readable server name","type":"string"},"timestamp":{"description":"When the call was made","type":"string"},"tool_name":{"description":"Tool name (without server prefix)","type":"string"}},"type":"object"},"contracts.UpdateInfo":{"description":"Update information (if available)","properties":{"available":{"description":"Whether an update is available","type":"boolean"},"behind_summary":{"description":"Spec 079 FR-002 — how far behind the running build is. All four are\nadditive (FR-021) and absent when the delta could not be resolved, in\nwhich case every surface renders its pre-delta wording.","type":"string"},"check_error":{"description":"Error message if update check failed","type":"string"},"checked_at":{"description":"When the update check was performed","type":"string"},"install_channel":{"description":"Detected install channel (homebrew, dmg, deb, rpm, docker, go-install, windows-installer, tarball, unknown) — Spec 079 FR-008","type":"string"},"is_prerelease":{"description":"Whether the latest version is a prerelease","type":"boolean"},"latest_version":{"description":"Latest version available (e.g., \"v1.2.3\")","type":"string"},"nudges_suppressed":{"description":"UI surfaces must stay quiet (CI / non-interactive context); machine-readable fields still report the facts — Spec 079 FR-019","type":"boolean"},"release_url":{"description":"URL to the release page","type":"string"},"releases_behind":{"description":"Releases on the offered channel between the running and offered versions","type":"integer"},"releases_behind_saturated":{"description":"ReleasesBehind is a lower bound: the running build predates the scanned release window","type":"boolean"},"update_command":{"description":"One-line update command for the channel; only set when an update is available and the channel has one — Spec 079 FR-009","type":"string"},"weeks_behind":{"description":"Whole weeks between the two releases' publish dates; 0 is a real value, absent means unknown","type":"integer"}},"type":"object"},"contracts.UpdatePolicy":{"description":"UpdatePolicy is the effective, hot-reloadable update policy (Spec 092\nFR-015). Always present: the ` + "`" + `update` + "`" + ` object above is omitted both when\nupdate checking is disabled AND when no check has produced a result\nyet, so its absence cannot tell a client whether it is allowed to run\nits own (e.g. Sparkle feed) check. This field states the answer.","properties":{"channel":{"description":"Channel is the tracked release channel: \"stable\" or \"rc\".","type":"string"},"enabled":{"description":"Enabled is the effective automatic-check kill switch: update_check.enabled\nwith MCPPROXY_DISABLE_AUTO_UPDATE=true winning over it. A user-initiated\n\"Check for Updates\" stays available regardless.","type":"boolean"},"nudges_suppressed":{"description":"NudgesSuppressed asks UI surfaces to stay quiet (CI / non-interactive)\nwhile machine-readable fields keep reporting the facts.","type":"boolean"}},"type":"object"},"contracts.UpstreamError":{"properties":{"error_message":{"type":"string"},"server_name":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.UsageAggregateResponse":{"properties":{"freshness_ms":{"description":"age of the underlying snapshot in ms","type":"integer"},"generated_at":{"type":"string"},"other":{"$ref":"#/components/schemas/contracts.UsageOtherBucket"},"timeline":{"items":{"$ref":"#/components/schemas/contracts.UsageTimeBucket"},"type":"array","uniqueItems":false},"token_source":{"description":"\"bytes\" (size-based proxy, FR-006)","type":"string"},"tokens_saved":{"description":"echoed from ServerTokenMetrics (FR-007)","type":"integer"},"tokens_saved_percentage":{"type":"number"},"tools":{"items":{"$ref":"#/components/schemas/contracts.UsageToolStat"},"type":"array","uniqueItems":false},"total_calls":{"description":"TotalCalls and TotalErrors are the headline counts for the window: the sum\nof the timeline this same response carries, so the tiles and the histogram\nunder them cannot disagree. They are NOT the sum of Tools — that list is\nlifetime-cumulative, upstream-only and truncated to top-N, and summing it\nclient-side is what made the Usage tab print a third number for the same\n24 hours (audit finding F1, #1046). The population is\nstorage.CountsAsCall, shared with ActivitySummaryResponse.CallCount.\n\nTwo bounds on how exactly this matches the Activity Log's own count.\nBoth are bounded and disclosed, unlike the population mismatch they\nreplace, which was unbounded and silent:\n\n  - Window granularity is the timeline's: whole hour buckets, so the span\n    is the requested window rounded up to a bucket edge.\n  - This response is served from a snapshot behind a short read cache\n    (observability.usage_cache_ttl, 5s by default) so the endpoint never\n    scans the activity log per request, while the summary endpoint counts\n    live. Calls that land inside that window appear on the Activity Log\n    first. FreshnessMs and GeneratedAt say how old the figures are, and\n    the Usage tab prints it (\"Updated 3s ago\").","type":"integer"},"total_errors":{"type":"integer"},"window":{"type":"string"}},"type":"object"},"contracts.UsageOtherBucket":{"description":"present only when the list was truncated to top-N","properties":{"calls":{"type":"integer"},"tools_folded":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageTimeBucket":{"properties":{"calls":{"type":"integer"},"errors":{"type":"integer"},"start":{"type":"string"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageToolStat":{"properties":{"avg_req_bytes":{"description":"null when no sized request calls","type":"integer"},"avg_resp_bytes":{"description":"null when sized_calls == 0 (only legacy 0-byte calls)","type":"integer"},"blocked":{"type":"integer"},"calls":{"type":"integer"},"error_rate":{"type":"number"},"errors":{"type":"integer"},"last_used":{"type":"string"},"p50_exceeds":{"type":"boolean"},"p50_ms":{"description":"P50Ms and P95Ms are read off a fixed latency histogram, so they are BUCKET\nBOUNDS, not measured durations: the true percentile is at or below the\nvalue, and a client must render it as a bound (\"≤ 5 ms\"). P50Exceeds /\nP95Exceeds flip that reading for the unbounded overflow bucket, where the\nvalue is the last bound and the truth is above it (\"\u003e 10 s\").","type":"integer"},"p95_exceeds":{"type":"boolean"},"p95_ms":{"type":"integer"},"rejected":{"description":"spec 093: shed by a concurrency limit; never executed, so excluded from calls/latency","type":"integer"},"server":{"type":"string"},"sized_calls":{"description":"calls with known response size (basis for avg_resp_bytes)","type":"integer"},"tool":{"type":"string"},"total_req_bytes":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.ValidateConfigResponse":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false},"valid":{"type":"boolean"}},"type":"object"},"contracts.ValidationError":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"data":{"properties":{"data":{"$ref":"#/components/schemas/contracts.InfoResponse"}},"type":"object"},"httpapi.AddServerRequest":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve\nnew/changed tools past the trust baseline (MCP-2930). Tri-state *bool:\na nil pointer means \"leave unchanged\" on PATCH; a present value\n(including false) is applied. Mirrors config.ServerConfig's *bool\nsemantics — do NOT collapse to a plain bool, or an omitted field would\nsilently reset a previously-set value.","type":"boolean"},"command":{"type":"string"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts is the per-server override for prompt aggregation (F9):\nwhether this server's advertised MCP prompts are merged into mcpproxy's\nprompts/list. Tri-state *bool mirroring config.ServerConfig.ExposePrompts —\na nil pointer means \"leave unchanged\" on PATCH (and \"inherit the default\naggregate behavior\" on create); a present value (including false) is applied.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"init_timeout":{"description":"InitTimeout is the per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override\n(MCP-3322 / GH #760), serialized as a duration string (e.g. \"120s\"). A nil\npointer means \"leave unchanged\" on PATCH; a present value is applied.\nMirrors config.ServerConfig.InitTimeout's *Duration tri-state.","type":"string"},"isolation":{"$ref":"#/components/schemas/httpapi.IsolationRequest"},"max_concurrent_requests":{"description":"MaxConcurrentRequests / QueueSize / QueueTimeout are the per-server\nconcurrency overrides (spec 093 / GH #955, FR-020 scope (c)). Each is\ntri-state: a nil pointer means \"leave unchanged\" on PATCH and \"inherit\nserver_concurrency_defaults\" on create; an explicit 0 disables that\nsetting for this server; a positive value overrides it. Do NOT collapse\nthem to plain values — an omitted field would then silently reset a\nconfigured limit.","type":"integer"},"name":{"type":"string"},"protocol":{"type":"string"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"type":"boolean"},"trust_mode":{"description":"TrustMode is the per-server trust tier (spec 086): \"auto\", \"scan\", or\n\"manual\". Empty means \"leave unchanged\" on PATCH (and inherit the migrated\ndefault on create). A non-empty value is applied to ServerConfig.TrustMode\nand resolved by EffectiveTrustMode (an unrecognized value fails closed to\nmanual). This is the REST seam for changing the trust tier via\nPOST/PATCH /api/v1/servers.","type":"string"},"url":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.CanonicalConfigPath":{"properties":{"description":{"description":"Brief description","type":"string"},"exists":{"description":"Whether the file exists","type":"boolean"},"format":{"description":"Format identifier (e.g., \"claude_desktop\")","type":"string"},"name":{"description":"Display name (e.g., \"Claude Desktop\")","type":"string"},"os":{"description":"Operating system (darwin, windows, linux)","type":"string"},"path":{"description":"Full path to the config file","type":"string"}},"type":"object"},"httpapi.CanonicalConfigPathsResponse":{"properties":{"os":{"description":"Current operating system","type":"string"},"paths":{"description":"List of canonical config paths","items":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPath"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ConnectConflictResponse":{"properties":{"action":{"description":"already_exists | precondition_failed","type":"string"},"data":{"$ref":"#/components/schemas/connect.ConnectResult"},"error":{"description":"Human-readable message","type":"string"},"success":{"description":"Always false","type":"boolean"}},"type":"object"},"httpapi.ConnectRequest":{"properties":{"force":{"description":"Overwrite existing entry","type":"boolean"},"precondition_token":{"description":"PreconditionToken is the opaque token from the preview this write was\nconfirmed against (Spec 091 FR-005). When present, the core rechecks it\nat write time and responds 409 with action \"precondition_failed\" —\nwriting nothing — if the config or the entry MCPProxy would write has\ndrifted since; the caller then re-previews instead of retrying. Absent\nmeans exactly the pre-091 behavior. A replace-classified flow sends this\nTOGETHER with force=true: the token, not the absence of force, is the\noverwrite safety.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.ImportFromPathRequest":{"properties":{"format":{"description":"Optional format hint","type":"string"},"path":{"description":"File path to import from","type":"string"},"rename":{"additionalProperties":{"type":"string"},"description":"Rename maps a server name → new name. Applied after parsing so the\ncaller can disambiguate cross-source name collisions (Spec 046 v2 —\ne.g. \"mcpproxy\" → \"mcpproxy_claude_code\"). Keys are matched against\neither the raw source name (OriginalName) or the sanitized name shown\nin the preview (Server.Name); these differ for names that need\nsanitizing (e.g. \"Figma Desktop\" → \"Figma_Desktop\"). Keys not present\nin the imported set are ignored.","type":"object"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportRequest":{"properties":{"content":{"description":"Raw JSON or TOML content","type":"string"},"format":{"description":"Optional format hint","type":"string"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportResponse":{"properties":{"failed":{"items":{"$ref":"#/components/schemas/configimport.FailedServer"},"type":"array","uniqueItems":false},"format":{"type":"string"},"format_name":{"type":"string"},"imported":{"items":{"$ref":"#/components/schemas/httpapi.ImportedServerResponse"},"type":"array","uniqueItems":false},"skipped":{"items":{"$ref":"#/components/schemas/configimport.SkippedServer"},"type":"array","uniqueItems":false},"summary":{"$ref":"#/components/schemas/configimport.ImportSummary"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportedServerResponse":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"command":{"type":"string"},"fields_skipped":{"items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"type":"string"},"original_name":{"type":"string"},"protocol":{"type":"string"},"source_format":{"type":"string"},"url":{"type":"string"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.IsolationRequest":{"description":"Isolation carries per-server Docker isolation overrides (enabled,\nmode_override, image, network_mode, extra_args, working_dir). A nil\npointer means \"do not touch isolation config\". A present object is\napplied field-by-field ON TOP of the persisted overrides, so omitting a\nfield leaves it alone; clear an individual override by sending it\nexplicitly (` + "`" + `\"enabled\": null` + "`" + `, ` + "`" + `\"image\": \"\"` + "`" + `).","properties":{"enabled":{"description":"Enabled exists ONLY to detect and reject an echoed-back read. It is the\neffective state on the read surface and is never writable; see validate().","type":"boolean"},"enabled_override":{"description":"EnabledOverride is the tri-state per-server override — the RAW value, the\nsame one reads return as ` + "`" + `enabled_override` + "`" + `. It has THREE meaningful wire\nstates, and collapsing them is what silently un-isolated servers\n(GH #1142):\n  - absent          → leave the persisted override untouched\n  - null            → clear the override, back to inheriting the global\n  - true / false    → set an explicit opt-in / opt-out","type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"mode_override":{"description":"ModeOverride sets ` + "`" + `isolation.mode` + "`" + ` (\"docker\" | \"sandbox\" | \"none\").\nnil leaves the persisted value alone; an empty string clears it. An\nunrecognized value is rejected with a 400 rather than persisted.","type":"string"},"network_mode":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.OnboardingMarkRequest":{"properties":{"connect_step_status":{"description":"ConnectStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value. The stored enum is wider (Spec 080\nFR-001): a \"skipped\" request for a previously untouched connect step\nis upgraded server-side to \"completed_external\" when the install\nshows positive evidence of an external connection (Spec 080 FR-002).\n\"completed_external\" is NOT accepted from clients — it must never be\npersisted without that server-verified evidence (edge case: \"never\nguess completed_external without positive evidence\").","type":"string"},"engaged":{"description":"Engaged marks the wizard as engaged (completed or explicitly skipped).\nOnce true, the wizard does not auto-show again.","type":"boolean"},"mark_shown":{"description":"MarkShown records the wizard's first display time if not already set.","type":"boolean"},"server_step_status":{"description":"ServerStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value.","type":"string"}},"type":"object"},"httpapi.SetActiveProfileRequest":{"properties":{"active_profile":{"type":"string"},"profile":{"type":"string"}},"type":"object"},"httpapi.UndoConnectRequest":{"properties":{"backup_name":{"description":"BackupName is the bare filename (filepath.Base) of the backup returned as\nbackup_path by the preceding connect — a name, never a path. Undo resolves\nthe full path server-side by joining it with the client's own config\ndirectory, so a client-supplied value can never contribute a directory\ncomponent (traversal is impossible by construction). Empty means the\nconnect created the file (no prior file existed), so undo removes it.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.UpdateFailureRequest":{"properties":{"stage":{"description":"Stage is the failure stage of the update session.","enum":["appcast","download","install","other"],"type":"string"}},"type":"object"},"management.BulkOperationResult":{"properties":{"errors":{"additionalProperties":{"type":"string"},"description":"Map of server name to error message","type":"object"},"failed":{"description":"Number of failed operations","type":"integer"},"successful":{"description":"Number of successful operations","type":"integer"},"total":{"description":"Total servers processed","type":"integer"}},"type":"object"},"observability.HealthResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"observability.HealthStatus":{"properties":{"error":{"type":"string"},"latency":{"type":"string"},"name":{"type":"string"},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"}},"type":"object"},"observability.ReadinessResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"ready\" or \"not_ready\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"secureenv.EnvConfig":{"description":"Environment configuration for secure variable filtering","properties":{"allowed_system_vars":{"items":{"type":"string"},"type":"array","uniqueItems":false},"custom_vars":{"additionalProperties":{"type":"string"},"type":"object"},"enhance_path":{"description":"Enable PATH enhancement for Launchd scenarios","type":"boolean"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned upstream servers (MCP-2769). It is OFF by\ndefault and deliberately kept out of the AllowedSystemVars default list:\nproxy URLs frequently carry credentials (http://user:pass@proxy), so\nforwarding them to every stdio upstream is a credential-leak risk. When\nenabled, values are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"inherit_system_safe":{"type":"boolean"}},"type":"object"},"telemetry.FeedbackContext":{"properties":{"arch":{"type":"string"},"connected_server_count":{"type":"integer"},"edition":{"type":"string"},"os":{"type":"string"},"routing_mode":{"type":"string"},"server_count":{"type":"integer"},"version":{"type":"string"}},"type":"object"},"telemetry.FeedbackRequest":{"properties":{"category":{"description":"bug, feature, other","type":"string"},"context":{"$ref":"#/components/schemas/telemetry.FeedbackContext"},"email":{"type":"string"},"message":{"type":"string"}},"type":"object"},"telemetry.FeedbackResponse":{"properties":{"error":{"type":"string"},"issue_url":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"API key authentication via query parameter. Use ?apikey=your-key","in":"query","name":"apikey","type":"apiKey"}}},
+    "components": {"schemas":{"config.AuditLogConfig":{"description":"AuditLog configures the Spec 107 edition-neutral audit sink\n(internal/audit). nil means \"use the per-edition/per-transport\ndefault\" (EffectiveAuditLog); restart-pinned (bound at sink\nconstruction). See audit_log.go.","properties":{"compress":{"type":"boolean"},"enabled":{"type":"boolean"},"max_age_days":{"type":"integer"},"max_backups":{"type":"integer"},"max_size_mb":{"type":"integer"},"path":{"type":"string"},"stdout":{"type":"boolean"}},"type":"object"},"config.ConcurrencyDefaults":{"description":"ServerConcurrencyDefaults is scope (b) of FR-020: the blanket per-server\ndefault set inherited by every server that does not override a setting.\nAbsent (the default) = no per-server limiting unless a server configures\nit explicitly. File/API-configured only — no env scheme (FR-022).","properties":{"max_concurrent_requests":{"type":"integer"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"}},"type":"object"},"config.Config":{"properties":{"activity_cleanup_interval_min":{"description":"Background cleanup interval in minutes (default: 60)","type":"integer"},"activity_max_records":{"description":"Max records before pruning (default: 100000)","type":"integer"},"activity_max_response_size":{"description":"Response truncation limit in bytes (default: 65536)","type":"integer"},"activity_max_size_mb":{"description":"ActivityMaxSizeMB caps the total activity-log size in MB before the\noldest records are pruned. Omit the key for the 256MB default; set it to\n0 to disable the size cap.","type":"integer"},"activity_retention_days":{"description":"Activity logging settings (RFC-003)","type":"integer"},"aggregate_upstream_prompts":{"description":"AggregateUpstreamPrompts, when true, aggregates every connected upstream\nserver's advertised MCP prompts into mcpproxy's own prompts/list\n(exposed as \"\u003cserver\u003e__\u003cprompt\u003e\"). OFF by default: users are safe by\ndefault and opt in deliberately. EnablePrompts still governs the built-in\nprompts + the prompts capability; this flag gates ONLY the upstream\naggregation performed by RefreshPrompts. Hot-reloadable.","type":"boolean"},"allow_private_registry_fetch":{"description":"AllowPrivateRegistryFetch opts out of the registry SSRF guard (MCP-1076,\nCWE-918). By default (false) registry fetches refuse any host that is — or\nresolves to — a non-routable address (loopback, RFC1918/CGNAT private,\nlink-local incl. the 169.254.169.254 cloud-metadata endpoint), so a\nmalicious or typo'd registry source cannot turn the daemon into a\nrequest-forgery vector against internal services.\n\nThis opt-out is BLANKET (all-or-nothing): setting it true disables the\nguard for EVERY non-routable range at once — loopback, RFC1918/CGNAT\nprivate, link-local AND the 169.254.169.254 cloud-metadata endpoint. There\nis no way to allow only loopback; enabling it for a localhost dev registry\nalso re-opens the cloud-metadata SSRF vector. Set true ONLY when you\nintentionally run a trusted registry mirror on an internal/private address,\nideally on a host with no cloud-metadata exposure. The change takes effect\nonly on daemon (re)start or config reload.","type":"boolean"},"allow_server_add":{"type":"boolean"},"allow_server_remove":{"type":"boolean"},"api_key":{"description":"Security settings","type":"string"},"audit_log":{"$ref":"#/components/schemas/config.AuditLogConfig"},"call_tool_timeout":{"type":"string"},"check_server_repo":{"description":"Repository detection settings","type":"boolean"},"code_execution_max_parallel":{"description":"Default concurrency for call_tools() batches (1-32, default: 8)","type":"integer"},"code_execution_max_tool_calls":{"description":"Max tool calls per execution (0 = unlimited, default: 0)","type":"integer"},"code_execution_pool_size":{"description":"JavaScript runtime pool size (default: 10)","type":"integer"},"code_execution_timeout_ms":{"description":"Timeout in milliseconds (default: 120000, max: 600000)","type":"integer"},"data_dir":{"type":"string"},"debug_search":{"type":"boolean"},"direct_tool_response_mode":{"description":"DirectToolResponseMode selects the serialization of the DIRECT\nenumeration surface (Spec 102). Valid values: \"\" (= full), \"full\"\n(default: today's schema-bearing entries), \"deferred\" (description +\ncompact signature, with a minimal permissive input schema; upstream\ninputSchema and outputSchema are stripped and recovered on demand via\ndescribe_tool).\n\nDeliberately NOT an extension of tool_response_mode: reusing that axis\nwould silently change /mcp/all output for every deployment already\nrunning compact, which FR-015 forbids. Serialization-only — it never\nchanges WHICH tools are listed, only how (FR-008). Hot-reloadable.","type":"string"},"disable_management":{"type":"boolean"},"docker_isolation":{"$ref":"#/components/schemas/config.DockerIsolationConfig"},"docker_recovery":{"$ref":"#/components/schemas/config.DockerRecoveryConfig"},"enable_code_execution":{"description":"Code execution settings","type":"boolean"},"enable_prompts":{"description":"Prompts settings","type":"boolean"},"enable_socket":{"description":"Enable Unix socket/named pipe for local IPC (default: true)","type":"boolean"},"enable_tray":{"description":"Deprecated: EnableTray is unused and has no runtime effect. Kept for backward compatibility.","type":"boolean"},"environment":{"$ref":"#/components/schemas/secureenv.EnvConfig"},"features":{"$ref":"#/components/schemas/config.FeatureFlags"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned stdio upstream servers (MCP-2769). OFF by\ndefault: proxy URLs commonly embed credentials (http://user:pass@proxy), so\nforwarding them to every upstream is a credential-leak risk. When enabled,\nvalues are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"health_check_interval":{"description":"Discovery \u0026 health-check cadence (spec 074, #608). Both are *Duration\ntri-state pointers: nil = inherit the built-in default; a pointer to 0s =\nthe loop is disabled; a positive value = that interval. Defaults live only\nin the resolvers (ResolveHealthCheckInterval / ResolveToolDiscoveryInterval)\nso an unset key behaves exactly as before this feature (SC-005). Validated\nin Validate(): health-check ∈ {0} ∪ [5s,1h]; tool-discovery ∈ {0} ∪ [30s,24h].","type":"string"},"http_idle_timeout":{"description":"HTTPIdleTimeout caps how long an idle keep-alive connection is kept open.\nUnset = 180s. \"0s\" removes the dedicated idle deadline, but net/http then\nfalls back to ReadTimeout — idle is fully unbounded only when\nhttp_read_timeout is also \"0s\". Requires a restart.","type":"string"},"http_read_timeout":{"description":"HTTPReadTimeout caps how long reading a whole request (headers + body)\nmay take. Unset = 120s; \"0s\" disables it. Requires a restart.","type":"string"},"http_write_timeout":{"description":"HTTPWriteTimeout caps how long producing a whole response may take on\nnon-streaming endpoints (REST, Web UI, health). Unset = 120s; \"0s\"\ndisables it globally. MCP and SSE /events routes are exempt by design.","type":"string"},"init_timeout":{"description":"InitTimeout is the global default deadline for an upstream's MCP\n` + "`" + `initialize` + "`" + ` handshake (MCP-3322 / GH #760). *Duration tri-state: nil =\ninherit the built-in 30s default; a positive value = that deadline. A\nper-server InitTimeout overrides this. Resolved by ResolveInitTimeout;\nvalidated to {0} ∪ [1s, 30m] in Validate(). Servers doing legitimate\nfirst-run warmup (cache/index build) before answering ` + "`" + `initialize` + "`" + ` can\nraise this so they are not killed mid-startup.","type":"string"},"instructions":{"description":"Instructions text returned in the MCP initialize response to guide AI agents.\nWhen empty, a built-in default is used that explains retrieve_tools workflow.","type":"string"},"intent_declaration":{"$ref":"#/components/schemas/config.IntentDeclarationConfig"},"listen":{"type":"string"},"logging":{"$ref":"#/components/schemas/config.LogConfig"},"max_concurrent_requests":{"description":"Concurrency limits (spec 093, GH #955). Scope (a) of FR-020: the GLOBAL\nAGGREGATE limiter — one proxy-wide cap on concurrently running upstream\ntool calls, with its own bounded wait queue. Tri-state pointers: absent =\nthe limiter does not exist (default, zero behavior change); an explicit 0\nmax also disables it; positive = that cap. This scope is NEVER a\nper-server inheritance source — per-server values come from\nServerConcurrencyDefaults / the per-server overrides — but a server's\neffective concurrency is bounded by BOTH its own limiter and this one.\nResolved by ResolveGlobalConcurrency; hot-reloadable; overridable via\nMCPPROXY_MAX_CONCURRENT_REQUESTS / _QUEUE_SIZE / _QUEUE_TIMEOUT (FR-022).","type":"integer"},"max_result_size_chars":{"description":"MaxResultSizeChars is advertised on every tool as\n` + "`" + `_meta.anthropic/maxResultSizeChars` + "`" + `; it raises Claude Code's\ninline-response ceiling from 50k to up to 500k chars. Omit the key for\nthe 500000 default; set it to 0 to disable the annotation.","type":"integer"},"mcpServers":{"items":{"$ref":"#/components/schemas/config.ServerConfig"},"type":"array","uniqueItems":false},"oauth_expiry_warning_hours":{"description":"Health status settings","type":"number"},"observability":{"$ref":"#/components/schemas/config.ObservabilityConfig"},"output_sanitisation":{"$ref":"#/components/schemas/config.OutputSanitisationConfig"},"output_validation":{"$ref":"#/components/schemas/config.OutputValidationConfig"},"profiles":{"description":"Profiles are optional named, server-scoped views exposed at /mcp/p/\u003cname\u003e\n(Spec 057). Absent/empty is fully supported — /mcp is unchanged and configs\nwithout this key serialize byte-identically (SC-004).","items":{"$ref":"#/components/schemas/config.ProfileConfig"},"type":"array","uniqueItems":false},"quarantine_enabled":{"description":"QuarantineEnabled controls whether quarantine is active. It gates two\nthings together:\n  1. Server-level auto-quarantine for newly added servers (issue #370).\n     When true, servers added via the upstream_servers MCP tool or the\n     REST API default to quarantined=true; when false, they default to\n     quarantined=false. Explicit per-request values always win.\n  2. Tool-level quarantine (Spec 032): per-tool SHA-256 approval of\n     tool descriptions/schemas.\nWhen nil (default), quarantine is enabled (secure by default). Set to\nexplicit false to opt out of both. Per-server SkipQuarantine still\napplies for the tool-level check on individual servers.","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"read_only_mode":{"type":"boolean"},"registries":{"description":"Registries configuration for MCP server discovery","items":{"$ref":"#/components/schemas/config.RegistryEntry"},"type":"array","uniqueItems":false},"registries_locked":{"description":"RegistriesLocked is an enterprise stub knob (MCP-866): when true, runtime\nadditions of custom registries (e.g. ` + "`" + `registry add-source` + "`" + `, the REST/MCP\nadd-source surface) are rejected so an administrator can pin the discovery\nsources. Built-in defaults are unaffected. Documented but otherwise inert\nbeyond the add-source rejection.","type":"boolean"},"require_mcp_auth":{"description":"Require authentication on /mcp endpoint (default: false)","type":"boolean"},"reveal_secret_headers":{"description":"RevealSecretHeaders, when true, disables the redaction of the\nsecret-bearing server fields — sensitive header values (Authorization,\nX-API-Key, Cookie, …), env-var secrets, and URL query credentials — in\nresponses from the ` + "`" + `upstream_servers` + "`" + ` MCP tool, the ` + "`" + `/api/v1/servers` + "`" + `\nREST API, and the SSE event stream. It also lets URL secrets echoed\ninto last_error / health.detail through unscrubbed.\n\nDefault false — sensitive values are surfaced masked as\n` + "`" + `••••\u003clast2\u003e (\u003cN\u003e chars)` + "`" + ` (error strings use ` + "`" + `***REDACTED***` + "`" + `) so an\nMCP agent cannot read Bearer tokens / API keys / URL secrets out of\nanother upstream's config (PR #425, issue #872). ${env:…}/${keyring:…}\nreferences are labels, not secrets, and pass through unchanged.\n\nThe Web UI / macOS tray edit forms work without seeing the real\nvalues: PATCH /api/v1/servers/{id} deep-merges (omitted keys are\npreserved, see ` + "`" + `headers_remove` + "`" + ` / ` + "`" + `env_remove` + "`" + ` for explicit\ndeletes), so clients compute a diff and only send the keys that\nactually changed. Redacted-but-unchanged values never round-trip\n— the backend keeps the real string. Set this to true if a\ndownstream tool genuinely needs raw values in the response.","type":"boolean"},"routing_mode":{"description":"Routing mode (Spec 031): how MCP tools are exposed to clients\nValid values: \"retrieve_tools\" (default), \"direct\", \"code_execution\"","type":"string"},"security":{"$ref":"#/components/schemas/config.SecurityConfig"},"sensitive_data_detection":{"$ref":"#/components/schemas/config.SensitiveDataDetectionConfig"},"server_concurrency_defaults":{"$ref":"#/components/schemas/config.ConcurrencyDefaults"},"telemetry":{"$ref":"#/components/schemas/config.TelemetryConfig"},"tls":{"$ref":"#/components/schemas/config.TLSConfig"},"tokenizer":{"$ref":"#/components/schemas/config.TokenizerConfig"},"tool_call_max_records_per_server":{"description":"Calls retained per server (default: 1000)","type":"integer"},"tool_call_max_response_size":{"description":"Bounds for the per-server tool-call history behind GET /api/v1/tool-calls\n(#1176). It is a recent-debugging window, not an audit log — the activity\nlog is the durable record — and it kept every upstream response whole,\nper server, forever. A non-positive value means \"use the default\", not\n\"disable\": this store must never be unbounded again, so there is\ndeliberately no off switch.","type":"integer"},"tool_discovery_interval":{"type":"string"},"tool_response_limit":{"type":"integer"},"tool_response_mode":{"description":"Tool response mode (Spec 085): how retrieve_tools serializes results.\nValid values: \"\" (= full), \"full\" (default: today's schema-bearing\nentries), \"compact\" (signature + first-sentence entries). Orthogonal to\nrouting_mode — routing_mode selects the tool SURFACE, this selects the\nSERIALIZATION within the retrieve_tools surface. Serialization-only: it\nnever affects the query, ranking, or result set. Hot-reloadable.","type":"string"},"tool_response_session_risk_warning":{"description":"ToolResponseSessionRiskWarning controls whether the prose ` + "`" + `warning` + "`" + ` field\nis included in the ` + "`" + `session_risk` + "`" + ` object returned by ` + "`" + `retrieve_tools` + "`" + `.\nThe structured fields (level, lethal_trifecta, has_open_world_tools, etc.)\nare always included. Default: false (quiet for LLM clients) — see issue #406.\nMost tools lack annotations, so the MCP-spec defaults treat them as fully\npermissive across all three risk axes, which makes the prose warning fire\non almost every call and wastes tokens.","type":"boolean"},"tools_limit":{"type":"integer"},"toon_min_savings_pct":{"description":"ToonMinSavingsPct is the minimum byte-savings percentage (validated\n1-90; 0/unset → 15) the complete TOON emission (marker + hint + body)\nmust achieve over the exact passthrough emission for adaptive mode to\nencode a block. Byte savings approximate token savings for the tabular\npayload class; the spec-083 profiler reports true token deltas.\nGlobal-only (no per-server override, FR-001).","type":"integer"},"toon_output":{"description":"ToonOutput selects the TOON encoding mode for call_tool_* result text\nblocks (spec 084): \"off\" (default — responses byte-identical to\npre-feature behavior), \"adaptive\" (encode only tabular-uniform payloads\nthat beat compact JSON by ToonMinSavingsPct), or \"always\"\n(benchmark/debug only — encodes every JSON-parseable block and can\nINCREASE token cost). Per-server override: ServerConfig.ToonOutput.\nResolved by ResolveToonOutput; hot-reloadable.","type":"string"},"top_k":{"description":"Deprecated: TopK is superseded by ToolsLimit and has no runtime effect. Kept for backward compatibility.","type":"integer"},"tray_endpoint":{"description":"Tray endpoint override (unix:// or npipe://)","type":"string"},"trusted_hosts":{"description":"TrustedHosts lists non-loopback Host header values accepted on loopback\nlisteners (GH #898). DNS-rebinding protection rejects requests whose Host\nheader is not a loopback address when mcpproxy listens on loopback; a\nreverse proxy (nginx → 127.0.0.1) forwarding the public domain in Host\ntrips it. Entries are hostnames, case-insensitive; an entry without a\nport matches any port, with a port it must match exactly; a leading dot\n(\".example.com\") is a subdomain wildcard. The single entry \"*\" disables\nHost and Origin validation entirely. The same list also validates the\nOrigin header when present (MCP spec DNS-rebinding defense). Empty\n(default) keeps full protection. Env override: MCPPROXY_TRUSTED_HOSTS\n(comma-separated).","items":{"type":"string"},"type":"array","uniqueItems":false},"trusted_proxies":{"description":"TrustedProxies lists the CIDRs or IP addresses whose X-Forwarded-For /\nX-Real-IP / X-Forwarded-Proto / X-Forwarded-Host headers are believed\n(Spec 107 FR-027). Empty (default) trusts nobody. Edition-neutral, live\n(hot-reloadable). Env override: MCPPROXY_TRUSTED_PROXIES (comma-separated).\nThe one reader is ForwardedHeaders; validation is validateTrustedProxies.","items":{"type":"string"},"type":"array","uniqueItems":false},"update_check":{"$ref":"#/components/schemas/config.UpdateCheckConfig"}},"type":"object"},"config.CustomPattern":{"properties":{"category":{"description":"Category (defaults to \"custom\")","type":"string"},"keywords":{"description":"Keywords to match (mutually exclusive with Regex)","items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"description":"Unique identifier for this pattern","type":"string"},"regex":{"description":"Regex pattern (mutually exclusive with Keywords)","type":"string"},"severity":{"description":"Risk level: critical, high, medium, low","type":"string"}},"type":"object"},"config.DeepScanConfig":{"description":"DeepScan is the opt-in \"deep scan\" layer (Spec 077 US3). It subsumes the\ndeprecated top-level scanner_fetch_package_source / scanner_disable_no_new_privileges\nkeys (migrated on load) and gates the heavy Docker-based scanners + source\nextraction. Disabled by default (FR-006): only the deterministic in-process\nbaseline scanner runs. A deep-scan failure NEVER changes the baseline verdict\n(FR-007/FR-008).","properties":{"disable_no_new_privileges":{"description":"DisableNoNewPrivileges, when true, omits the ` + "`" + `--security-opt\nno-new-privileges` + "`" + ` flag from scanner container runs (snap-docker/AppArmor\nescape hatch). Absorbs the deprecated top-level\nscanner_disable_no_new_privileges. Default false.","type":"boolean"},"enabled":{"description":"Enabled is the master opt-in for the heavy layer (FR-006). Default false.","type":"boolean"},"fetch_package_source":{"description":"FetchPackageSource controls whether the scanner fetches the PUBLISHED\nsource of package-runner servers (npx/uvx) — without executing it — when\nno local source is available. Absorbs the deprecated top-level\nscanner_fetch_package_source. Default (nil) is ENABLED within deep scan.","type":"boolean"},"scanners":{"description":"Scanners optionally restricts which deep scanners may run under the\numbrella (by scanner id). Empty ⇒ all enabled deep scanners are eligible.","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.DockerIsolationConfig":{"description":"Docker isolation settings","properties":{"cpu_limit":{"description":"CPU limit for containers","type":"string"},"default_images":{"additionalProperties":{"type":"string"},"description":"Map of runtime type to Docker image","type":"object"},"enable_cache_volume":{"description":"Mount shared cache volumes for faster restarts (default: true)","type":"boolean"},"enabled":{"description":"Global enable/disable for Docker isolation (legacy; superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments","items":{"type":"string"},"type":"array","uniqueItems":false},"log_driver":{"description":"Docker log driver (default: json-file)","type":"string"},"log_max_files":{"description":"Maximum number of log files (default: 3)","type":"string"},"log_max_size":{"description":"Maximum size of log files (default: 100m)","type":"string"},"memory_limit":{"description":"Memory limit for containers","type":"string"},"mode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"network_mode":{"description":"Docker network mode (default: bridge)","type":"string"},"registry":{"description":"Custom registry (defaults to docker.io)","type":"string"},"timeout":{"description":"Container startup timeout","type":"string"}},"type":"object"},"config.DockerRecoveryConfig":{"description":"Docker recovery settings","properties":{"enabled":{"description":"Enable Docker recovery monitoring (default: true)","type":"boolean"},"max_retries":{"description":"Maximum retry attempts (0 = unlimited)","type":"integer"},"notify_on_failure":{"description":"Show notification on recovery failure (default: true)","type":"boolean"},"notify_on_retry":{"description":"Show notification on each retry (default: false)","type":"boolean"},"notify_on_start":{"description":"Show notification when recovery starts (default: true)","type":"boolean"},"notify_on_success":{"description":"Show notification on successful recovery (default: true)","type":"boolean"},"persistent_state":{"description":"Save recovery state across restarts (default: true)","type":"boolean"}},"type":"object"},"config.FeatureFlags":{"description":"Deprecated: Features flags are unused and have no runtime effect. Kept for backward compatibility.","properties":{"enable_async_storage":{"type":"boolean"},"enable_caching":{"type":"boolean"},"enable_contract_tests":{"type":"boolean"},"enable_debug_logging":{"description":"Development features","type":"boolean"},"enable_docker_isolation":{"type":"boolean"},"enable_event_bus":{"type":"boolean"},"enable_health_checks":{"type":"boolean"},"enable_metrics":{"type":"boolean"},"enable_oauth":{"description":"Security features","type":"boolean"},"enable_observability":{"description":"Observability features","type":"boolean"},"enable_quarantine":{"type":"boolean"},"enable_runtime":{"description":"Runtime features","type":"boolean"},"enable_search":{"description":"Storage features","type":"boolean"},"enable_sse":{"type":"boolean"},"enable_tracing":{"type":"boolean"},"enable_tray":{"type":"boolean"},"enable_web_ui":{"description":"UI features","type":"boolean"}},"type":"object"},"config.IntentDeclarationConfig":{"description":"Intent declaration settings (Spec 018)","properties":{"strict_server_validation":{"description":"StrictServerValidation controls whether server annotation mismatches\ncause rejection (true) or just warnings (false).\nDefault: true (reject mismatches)","type":"boolean"}},"type":"object"},"config.IsolationConfig":{"description":"Per-server isolation settings","properties":{"enabled":{"description":"Enable Docker isolation for this server (nil = inherit global; legacy, superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments for this server","items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"description":"Custom Docker image (overrides default)","type":"string"},"log_driver":{"description":"Docker log driver override for this server","type":"string"},"log_max_files":{"description":"Maximum number of log files override","type":"string"},"log_max_size":{"description":"Maximum size of log files override","type":"string"},"mode":{"$ref":"#/components/schemas/config.IsolationMode"},"network_mode":{"description":"Custom network mode for this server","type":"string"},"working_dir":{"description":"Custom working directory in container","type":"string"}},"type":"object"},"config.IsolationMode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"config.LogConfig":{"description":"Logging configuration","properties":{"compress":{"type":"boolean"},"enable_console":{"type":"boolean"},"enable_file":{"type":"boolean"},"filename":{"type":"string"},"json_format":{"type":"boolean"},"level":{"type":"string"},"log_dir":{"description":"Custom log directory","type":"string"},"max_age":{"description":"days","type":"integer"},"max_backups":{"description":"number of backup files","type":"integer"},"max_size":{"description":"MB","type":"integer"}},"type":"object"},"config.MetricsExporterConfig":{"description":"Metrics gates the Prometheus /metrics scrape endpoint (MCP-32). Disabled\nby default — operators opt in for k8s/enterprise deployments.","properties":{"enabled":{"description":"Enabled exposes /metrics on the existing HTTP listener when true.\nThe endpoint is admin-authenticated (SEC-07): scrapers must present the\nglobal API key, via X-API-Key or an Authorization: Bearer header.","type":"boolean"}},"type":"object"},"config.OAuthConfig":{"description":"OAuth configuration (keep even when empty to signal OAuth requirement)","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"description":"Additional OAuth parameters (e.g., RFC 8707 resource)","type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_uri":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ObservabilityConfig":{"description":"Observability settings (Spec 069): usage aggregate cache/persistence cadence.","properties":{"metrics":{"$ref":"#/components/schemas/config.MetricsExporterConfig"},"tracing":{"$ref":"#/components/schemas/config.TracingExporterConfig"},"usage_cache_ttl":{"description":"UsageCacheTTL bounds the freshness of the usage endpoint's read cache for\nwide windows (FR-005). Default 5s.","type":"string"},"usage_persist_interval":{"description":"UsagePersistInterval is how often the actor-owned usage aggregate snapshot\nis flushed to storage. Default 30s.","type":"string"}},"type":"object"},"config.OutputSanitisationConfig":{"description":"Output sanitisation settings (Spec 054 Track B)","properties":{"max_redactions":{"description":"cap on redactions per response; default 100","type":"integer"},"response_action":{"description":"\"spotlight\" | \"redact\" | \"block\"; default \"spotlight\"","type":"string"},"spotlight_untrusted":{"description":"wrap untrusted output in spotlight markers; default true","type":"boolean"},"strip_classes":{"description":"classes to strip: ansi/c0c1/bidi/zero_width","items":{"type":"string"},"type":"array","uniqueItems":false},"strip_control_chars":{"description":"strip control-character classes; default false","type":"boolean"}},"type":"object"},"config.OutputValidationConfig":{"description":"Output-schema validation settings (Spec 056)","properties":{"max_bytes":{"description":"structured payload byte cap; default 5\u003c\u003c20","type":"integer"},"max_depth":{"description":"nesting depth cap; default 64","type":"integer"},"missing_structured_content":{"description":"\"allow\" | \"block\"; default \"allow\"","type":"string"},"mode":{"description":"\"off\" | \"warn\" | \"strict\"; default \"warn\"","type":"string"}},"type":"object"},"config.ProfileConfig":{"properties":{"name":{"description":"URL slug, validated","type":"string"},"servers":{"description":"references to mcpServers[].name","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.RegistryEntry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag for this registry (MCP-866):\nRegistryProvenanceOfficial for built-in defaults, RegistryProvenanceCustom\nfor user-added registries. It is authoritatively (re)computed by the\nregistries merge from whether the ID is a shipped default — a user cannot\nclaim \"official\" by writing it into their config.","type":"string"},"requires_key":{"description":"RequiresKey marks a registry that needs an API key to be queried. When\ntrue and no key is configured, the registry is skipped/marked unavailable\nrather than failing the whole search (FR-008).","type":"boolean"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"type":"string"}},"type":"object"},"config.SecurityConfig":{"description":"Security scanner settings (Spec 039)","properties":{"auto_baseline_scan":{"description":"AutoBaselineScan is the kill-switch for the AUTOMATIC, informational\nPass-1 baseline scan: the free in-process TPA scan mcpproxy runs for every\nnewly admitted server (any trust mode) and, once per installation, over\npre-existing servers that have never been scanned.\n\nInformational ONLY: the resulting verdict populates the security badge and\nthe scan summary, and NEVER gates quarantine or approval. The\ntrust_mode:\"scan\" admission gate is a separate path and is unaffected by\nthis flag.\n\nDefault (nil) is ENABLED. Set to false to suppress every automatic scan\n(manual scans keep working). Env override: MCPPROXY_AUTO_BASELINE_SCAN,\nwhich wins over this field on every path.","type":"boolean"},"deep_scan":{"$ref":"#/components/schemas/config.DeepScanConfig"},"integrity_check_interval":{"type":"string"},"integrity_check_on_restart":{"type":"boolean"},"runtime_read_only":{"type":"boolean"},"runtime_tmpfs_size":{"type":"string"},"scan_timeout_default":{"type":"string"},"scanner_disable_no_new_privileges":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.DisableNoNewPrivileges\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.IsDisableNoNewPrivileges. Cleared after migration.\n\nScannerDisableNoNewPrivileges, when true, omits the\n` + "`" + `--security-opt no-new-privileges` + "`" + ` flag from scanner container runs.\n\nBackground: snap-installed Docker on Ubuntu confines dockerd under the\n` + "`" + `snap.docker.dockerd` + "`" + ` AppArmor profile. When runc tries to transition\nthe container into the inner ` + "`" + `docker-default` + "`" + ` profile to exec the\nentrypoint, AppArmor refuses the transition because NO_NEW_PRIVS\nforbids privilege/profile changes on exec — the result is EPERM\n(\"operation not permitted\") and every scanner fails immediately.\n\nSet this to true ONLY on hosts hitting that incompatibility. Scanner\ncontainers still run with read-only rootfs, tmpfs /tmp, no-network by\ndefault, and read-only source mounts, so the marginal isolation loss\nis small. The preferred fix remains replacing snap docker with a\ndistro-packaged docker.","type":"boolean"},"scanner_fetch_package_source":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.FetchPackageSource\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.EffectiveFetchPackageSource. Cleared after migration.\n\nScannerFetchPackageSource controls whether the scanner fetches the\nPUBLISHED source of package-runner servers (npx/uvx) — without executing\nit — when no local source is available (no Docker container, no local\npackage cache, no working_dir). This is the primary quarantine/scan\ntarget: a quarantined-on-add server is never run locally, so without this\nthe scan degrades to tool-definitions-only (no real source-level\nanalysis). See MCP-2206.\n\nFetching uses ` + "`" + `npm pack --ignore-scripts` + "`" + ` (npm) and ` + "`" + `uv pip download` + "`" + ` /\n` + "`" + `pip download` + "`" + ` with ` + "`" + `--only-binary=:all:` + "`" + ` (Python), which only download +\nunpack archives and NEVER run install, build, or setup.py — a scanner must\nnot execute the untrusted code it is scanning. The Python\n` + "`" + `--only-binary=:all:` + "`" + ` flag is required because downloading an sdist would\ninvoke its build backend (setup.py); packages with no wheel fall back to\ntool-definitions-only instead. Extraction is hardened against path\ntraversal and decompression bombs.\n\nDefault (nil) is ENABLED. Set to false on air-gapped deployments to\nforbid the scanner's network egress; such servers then fall back to the\ntool-definitions-only scan with no regression.","type":"boolean"},"scanner_registry_url":{"type":"string"},"tpa_bundle_path":{"description":"TPABundlePath is the filesystem path to the tpa-db scanner-bundle.json\nthe offline TPA scanner runs (spec 086 FR-019: the signature-DB location\nMUST be configuration-driven, not hardcoded). Empty (the default) runs the\ncorpus embedded in this build.\n\nEnv override: MCPPROXY_TPA_BUNDLE_PATH. Hot-reloadable — the path is\nre-read on every config.reloaded event via\nscanner.Service.ApplySecurityConfig, so a corpus refresh needs no restart.\nA configured bundle that fails to read/parse/version-check/compile is\nREFUSED and the previously active corpus stays live (fail-closed, never\nfail-empty); the reason is logged and surfaced in the security overview's\nsignature_bundle.load_error.","type":"string"}},"type":"object"},"config.SensitiveDataDetectionConfig":{"description":"Sensitive data detection settings (Spec 026)","properties":{"categories":{"additionalProperties":{"type":"boolean"},"description":"Enable/disable specific detection categories","type":"object"},"custom_patterns":{"description":"User-defined detection patterns","items":{"$ref":"#/components/schemas/config.CustomPattern"},"type":"array","uniqueItems":false},"enabled":{"description":"Enable sensitive data detection (default: true)","type":"boolean"},"entropy_threshold":{"description":"Shannon entropy threshold for high-entropy detection (default: 4.5)","type":"number"},"max_payload_size_kb":{"description":"Max size to scan before truncating (default: 1024)","type":"integer"},"scan_requests":{"description":"Scan tool call arguments (default: true)","type":"boolean"},"scan_responses":{"description":"Scan tool responses (default: true)","type":"boolean"},"sensitive_keywords":{"description":"Keywords to flag","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ServerConfig":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve tool\nchanges/additions (disabling per-server rug-pull protection). Supersedes\nskip_quarantine. MCP-2930 only ACCEPTS, persists, and migrates this flag — it\nis NOT yet consulted at runtime; auto-approval is still governed by\nSkipQuarantine until the trust-baseline behavior change (MCP-2931) migrates the\nruntime consumers onto it.\nTri-state pointer (mirrors QuarantineEnabled): nil = unset (inherit/migrate\nfrom legacy skip_quarantine), explicit true/false = honored as-is so an\nexplicit auto_approve_tool_changes:false overrides a legacy skip_quarantine:true.\nRead via IsAutoApproveToolChanges().","type":"boolean"},"command":{"type":"string"},"created":{"type":"string"},"disabled_tools":{"description":"Denylist: these tools are hidden; mutually exclusive with enabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"},"enabled_tools":{"description":"Allowlist: only these tools are exposed; mutually exclusive with disabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts overrides whether this server's advertised MCP prompts are\naggregated into mcpproxy's prompts/list. nil (default) inherits the\ndefault-aggregate behavior (included if the server advertises\nCapabilities.Prompts); false excludes it regardless of capability.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"description":"For HTTP servers","type":"object"},"health_check_interval":{"description":"Per-server discovery \u0026 health-check overrides (spec 074). Same *Duration\ntri-state as the global keys: nil = inherit the global value (or default),\npointer to 0s = disabled for this server, positive = that interval.\nHealthCheckInterval is fully wired into the per-server health loop;\nToolDiscoveryInterval is accepted/validated and round-trips for\nforward-compat, but the periodic index sweep is governed by the global\ncadence in this iteration (see spec 074 plan §C).","type":"string"},"init_timeout":{"description":"InitTimeout overrides the global init_timeout for this server's MCP\n` + "`" + `initialize` + "`" + ` handshake deadline (MCP-3322 / GH #760). *Duration tri-state:\nnil = inherit the global value (or 30s default), positive = that deadline.\nResolved by Config.ResolveInitTimeout; validated to {0} ∪ [1s, 30m]. Raise\nthis for upstreams that do legitimate first-run warmup (e.g. caching many\nchannels/users) before responding to ` + "`" + `initialize` + "`" + `.","type":"string"},"isolation":{"$ref":"#/components/schemas/config.IsolationConfig"},"launcher_wait_timeout":{"description":"LauncherWaitTimeout caps how long mcpproxy will wait for a locally-launched\nHTTP/SSE upstream's URL to become reachable after Spawn(). Only consulted\nwhen the server is configured with both Command and an HTTP/SSE URL — i.e.,\nmcpproxy starts the process AND connects via network. Stdio servers ignore\nthis field. Zero or unset → 30s default.","type":"string"},"max_concurrent_requests":{"description":"Per-server concurrency overrides — scope (c) of FR-020 (spec 093, #955).\nTri-state per setting, exactly like HealthCheckInterval: absent = inherit\nthe per-server default set (server_concurrency_defaults), explicit 0 =\ndisable that setting for this server (0 max = no per-server limiter at\nall; 0 queue_size = no pending capacity, shed immediately at the cap),\npositive = override. The global aggregate limiter is never inherited from\nhere — it applies on top, so effective concurrency is min(per-server,\nglobal). Resolved by Config.ResolveServerConcurrency.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/config.OAuthConfig"},"protocol":{"description":"stdio, http, sse, streamable-http, auto","type":"string"},"quarantined":{"description":"Security quarantine status","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets a disconnected server","type":"boolean"},"shared":{"description":"Server edition: shared with all users","type":"boolean"},"skip_quarantine":{"description":"SkipQuarantine is DEPRECATED (MCP-2930): use AutoApproveToolChanges instead.\nKept for back-compat parsing; on config load a legacy skip_quarantine:true is\nmigrated to auto_approve_tool_changes:true only when the new field is unset\n(see normalizeServerQuarantineFlags).","type":"boolean"},"source_registry_id":{"description":"SourceRegistryID records which registry this server was added from (empty\nfor manually-configured servers). MCP-866: surfaced in the approval /\nquarantine view so a reviewer can see a server's origin.","type":"string"},"source_registry_provenance":{"description":"SourceRegistryProvenance records the source registry's provenance at add\ntime (RegistryProvenanceOfficial / RegistryProvenanceCustom). It is purely\ninformational (MCP-1072) — surfaced so a reviewer can see a server's origin\n— and no longer gates quarantine or skip_quarantine.","type":"string"},"tool_discovery_interval":{"type":"string"},"toon_output":{"description":"ToonOutput overrides the global toon_output mode for this server's\ntools (spec 084, FR-001). Plain string, not a pointer: \"\"/absent =\ninherit the global value; \"off\"|\"adaptive\"|\"always\" = override (\"off\"\nis the explicit force-off). Resolved by Config.ResolveToonOutput.","type":"string"},"trust_mode":{"description":"TrustMode is the per-server trust tier: auto|scan|manual. Supersedes\nauto_approve_tool_changes (spec 086). An empty value is derived from the\nlegacy fields at load via normalizeServerQuarantineFlags; the single\nresolution point is EffectiveTrustMode(), which treats an empty or\nunrecognized value as manual (secure by default). Read via\nEffectiveTrustMode(), never the raw string.","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"working_dir":{"description":"Working directory for stdio servers","type":"string"}},"type":"object"},"config.TLSConfig":{"description":"TLS configuration","properties":{"certs_dir":{"description":"Directory for certificates","type":"string"},"enabled":{"description":"Enable HTTPS","type":"boolean"},"hsts":{"description":"Enable HTTP Strict Transport Security","type":"boolean"},"require_client_cert":{"description":"Enable mTLS","type":"boolean"}},"type":"object"},"config.TelemetryConfig":{"description":"Telemetry settings (Spec 036)","properties":{"anonymous_id":{"description":"Auto-generated UUIDv4","type":"string"},"anonymous_id_created_at":{"description":"Spec 042 (Tier 2) additions — all default-zero, all backwards-compatible.","type":"string"},"enabled":{"description":"Default: true (opt-out)","type":"boolean"},"endpoint":{"description":"Override for testing","type":"string"},"last_reported_version":{"description":"Upgrade funnel","type":"string"},"last_startup_outcome":{"description":"success|port_conflict|db_locked|...","type":"string"},"notice_shown":{"description":"First-run notice flag","type":"boolean"}},"type":"object"},"config.TokenizerConfig":{"description":"Tokenizer configuration for token counting","properties":{"default_model":{"description":"Default model for tokenization (e.g., \"gpt-4\")","type":"string"},"enabled":{"description":"Enable token counting","type":"boolean"},"encoding":{"description":"Default encoding (e.g., \"cl100k_base\")","type":"string"}},"type":"object"},"config.TracingExporterConfig":{"description":"Tracing gates the OpenTelemetry OTLP trace exporter (MCP-32). Disabled by\ndefault.","properties":{"enabled":{"description":"Enabled turns on OTLP trace export for tool calls and upstream hops.","type":"boolean"},"endpoint":{"description":"Endpoint is the collector address as host:port (no scheme), e.g.\n\"localhost:4318\" for http or \"localhost:4317\" for grpc.","type":"string"},"protocol":{"description":"Protocol selects the OTLP transport: \"http\" or \"grpc\".","type":"string"},"sample_rate":{"description":"SampleRate is the head-based trace sampling ratio in [0,1]. Default 0.1.\nOmit the key for the 0.1 default; set it to 0 to sample nothing.","type":"number"}},"type":"object"},"config.UpdateCheckConfig":{"description":"Update-check settings (Spec 079 FR-012): config-file control of the\nbackground upgrade-awareness checker (internal/updatecheck). nil =\nenabled on the stable channel (existing default behavior). The existing\nenvironment switches keep working and WIN over these keys (FR-014):\nMCPPROXY_DISABLE_AUTO_UPDATE=true force-disables even when\nenabled=true, and MCPPROXY_ALLOW_PRERELEASE_UPDATES=true force-selects\nthe rc channel even when channel=stable.","properties":{"channel":{"description":"Channel selects which releases are offered as updates: \"stable\"\n(default; prereleases never offered) or \"rc\" (prereleases included).\nEmpty resolves to stable. Validated in ValidateDetailed.\n\nNOTE: for a RELEASED build the running binary's own version is\nauthoritative and overrides this field — a stable build is never\noffered an RC (even with channel=rc), and an RC build always tracks the\nrc channel. This field only takes effect on dev/unstamped builds. See\ninternal/updatecheck.Checker.IncludePrereleases.","type":"string"},"enabled":{"description":"Enabled gates all update checking. Tri-state: nil/absent = enabled\n(default true, matching pre-079 behavior). When false, no network\ncheck is performed and no upgrade nudge appears on any surface\n(FR-015) — /api/v1/info omits the update object entirely.","type":"boolean"}},"type":"object"},"configimport.FailedServer":{"properties":{"details":{"type":"string"},"error":{"type":"string"},"name":{"type":"string"}},"type":"object"},"configimport.ImportSummary":{"properties":{"failed":{"type":"integer"},"imported":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"configimport.SkippedServer":{"properties":{"name":{"type":"string"},"reason":{"description":"\"already_exists\", \"filtered_out\", \"invalid_name\"","type":"string"}},"type":"object"},"connect.ConnectResult":{"description":"The full result; its action mirrors the top-level one","properties":{"action":{"description":"\"created\", \"updated\", \"already_exists\", \"removed\", \"not_found\"","type":"string"},"backup_path":{"type":"string"},"client":{"type":"string"},"config_path":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.APIResponse":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ActivityDetailResponse":{"properties":{"activity":{"$ref":"#/components/schemas/contracts.ActivityRecord"}},"type":"object"},"contracts.ActivityListResponse":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/contracts.ActivityRecord"},"type":"array","uniqueItems":false},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.ActivityRecord":{"properties":{"agent_name":{"description":"Agent token name when auth_type is \"agent\"","type":"string"},"arguments":{"description":"Tool call arguments","type":"object"},"auth_type":{"description":"\"admin\", \"agent\", \"user\" or \"admin_user\"; empty without an auth context or on another caller's row for a scoped caller","type":"string"},"detection_types":{"description":"List of detection types found","items":{"type":"string"},"type":"array","uniqueItems":false},"duration_ms":{"description":"Execution duration in milliseconds","type":"integer"},"error_message":{"description":"Error details if status is \"error\"","type":"string"},"has_sensitive_data":{"description":"Sensitive data detection fields (Spec 026)","type":"boolean"},"id":{"description":"Unique identifier (ULID format)","type":"string"},"max_severity":{"description":"Highest severity level detected (critical, high, medium, low)","type":"string"},"metadata":{"description":"Additional context-specific data","type":"object"},"parent_id":{"description":"Correlation id of the parent call (the code_execution whose sandbox issued this sub-call)","type":"string"},"request_bytes":{"description":"Byte sizes measured pre-truncation, mirroring storage.ActivityRecord\n(Spec 069 A1). They are the only cost signal a bodies-off export carries:\nwith payloads suppressed there is no text left to measure, so a consumer\naccounting for a record it cannot read has nothing else to go on. They are\nbyte LENGTHS, not token counts — the basis for an explicit estimate, never\na measured figure (spec 103, contracts/replay-input.md).\n\nZero means UNKNOWN, not free: legacy records predate the measurement and\ncode-execution sub-calls record both as zero. Hence omitempty — an absent\nkey tells a consumer to fall to exclusion accounting, whereas a present\nzero would read as a costless call and silently understate the workload.","type":"integer"},"request_id":{"description":"HTTP request ID for correlation","type":"string"},"response":{"description":"Tool response (potentially truncated)","type":"string"},"response_bytes":{"description":"Raw upstream response size in bytes before truncation","type":"integer"},"response_truncated":{"description":"True if response was truncated","type":"boolean"},"server_name":{"description":"Name of upstream MCP server","type":"string"},"session_id":{"description":"MCP transport session ID (regenerated on every reconnect)","type":"string"},"source":{"$ref":"#/components/schemas/contracts.ActivitySource"},"status":{"description":"Result status: \"success\", \"error\", \"blocked\", \"rejected\"","type":"string"},"timestamp":{"description":"When activity occurred","type":"string"},"tool_name":{"description":"Name of tool called","type":"string"},"type":{"$ref":"#/components/schemas/contracts.ActivityType"},"work_session_id":{"description":"Spec 082: one client, one project, across reconnects","type":"string"}},"type":"object"},"contracts.ActivitySource":{"description":"How activity was triggered: \"mcp\", \"cli\", \"api\"","type":"string","x-enum-varnames":["ActivitySourceMCP","ActivitySourceCLI","ActivitySourceAPI"]},"contracts.ActivitySummaryResponse":{"properties":{"blocked_count":{"description":"Count of blocked activities","type":"integer"},"call_count":{"description":"CallCount is how many of those records are CALLS THE USER MADE, as\ndefined once in storage.CountsAsCall and shared with the usage aggregate\nbehind the Usage tab (audit finding F1, #1046). TotalCount answers \"how\nmany rows does the Activity Log have\"; CallCount answers \"how many calls\nwere there\". They are different questions — quarantine auto-approvals,\nsystem start, security scans and management chatter are events, not calls\n— and printing either one under the other's label is how the same instance\ncame to report 51 calls on one screen and 19 on another.","type":"integer"},"call_error_count":{"description":"CallErrorCount is the failures within CallCount, so an error RATE computed\nfrom this response has one denominator. It is not ErrorCount: a policy\nblock is a failed call but carries status \"blocked\", and a shed call is an\nerror in neither sense because it never ran.","type":"integer"},"end_time":{"description":"End of the period (RFC3339)","type":"string"},"error_count":{"description":"Count of error activities","type":"integer"},"other_count":{"description":"OtherCount is every record whose status is outside the four-value\nvocabulary above, so that\n\n\tsuccess + error + blocked + rejected + other == total\n\nholds by construction. The status field is a CLOSED vocabulary for tool\ncalls, but the activity log is wider than tool calls: a quarantine change\nstores its ACTION there (\"approved\", \"auto_approved\"), a policy decision\nstores its DECISION (\"allow\"). Those rows were counted in the total and in\nnone of the four buckets, so the Activity Log's own status tiles summed to\nless than the denominator printed beside them — 15+4+0+0 under a \"42\"\n(audit finding F2, #1046). The residual now has a name and a tile.","type":"integer"},"period":{"description":"Time period (1h, 24h, 7d, 30d)","type":"string"},"rejected_count":{"description":"RejectedCount is the number of calls shed by a concurrency limiter before\nthey reached an upstream (spec 093). Counted separately from errors: it is\nproxy backpressure, not an upstream fault, and it is the signal an\noperator right-sizes max_concurrent_requests against.","type":"integer"},"start_time":{"description":"Start of the period (RFC3339)","type":"string"},"success_count":{"description":"Count of successful activities","type":"integer"},"top_servers":{"description":"Top servers by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopServer"},"type":"array","uniqueItems":false},"top_tools":{"description":"Top tools by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopTool"},"type":"array","uniqueItems":false},"total_count":{"description":"Total activity count","type":"integer"}},"type":"object"},"contracts.ActivityTopServer":{"properties":{"count":{"description":"Activity count","type":"integer"},"name":{"description":"Server name","type":"string"}},"type":"object"},"contracts.ActivityTopTool":{"properties":{"count":{"description":"Activity count","type":"integer"},"server":{"description":"Server name","type":"string"},"tool":{"description":"Tool name","type":"string"}},"type":"object"},"contracts.ActivityType":{"description":"Type of activity","type":"string","x-enum-varnames":["ActivityTypeToolCall","ActivityTypePolicyDecision","ActivityTypeQuarantineChange","ActivityTypeServerChange"]},"contracts.AddFromRegistryRequest":{"properties":{"enabled":{"description":"defaults to true when nil","type":"boolean"},"env":{"additionalProperties":{"type":"string"},"description":"overrides + required-input values","type":"object"},"name":{"description":"optional name override","type":"string"}},"type":"object"},"contracts.AddRegistrySourceRequest":{"properties":{"id":{"description":"derived from the host when empty","type":"string"},"name":{"description":"defaults to the id","type":"string"},"protocol":{"description":"defaults to modelcontextprotocol/registry","type":"string"},"url":{"description":"required https registry URL","type":"string"}},"type":"object"},"contracts.ConfigApplyResult":{"properties":{"applied_immediately":{"type":"boolean"},"changed_fields":{"items":{"type":"string"},"type":"array","uniqueItems":false},"requires_restart":{"type":"boolean"},"restart_reason":{"type":"string"},"success":{"type":"boolean"},"validation_errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DCRStatus":{"properties":{"attempted":{"type":"boolean"},"error":{"type":"string"},"status_code":{"type":"integer"},"success":{"type":"boolean"}},"type":"object"},"contracts.DeepScanDescriptor":{"description":"DeepScan reports the opt-in \"deep scan\" layer status (Spec 077 US3),\nSEPARATELY from the baseline verdict above. Always emitted on a computed\nsummary — when deep scan is off (the default) it reports enabled=false\nplus any enabled-but-skipped Docker scanners. It never influences Status.","properties":{"available":{"type":"boolean"},"enabled":{"type":"boolean"},"ran":{"type":"boolean"},"scanners_failed":{"items":{"$ref":"#/components/schemas/contracts.DeepScanScannerFailure"},"type":"array","uniqueItems":false},"skipped_scanners":{"description":"SkippedScanners lists Docker scanners the user enabled that are skipped\nbecause security.deep_scan.enabled is false (informational).","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DeepScanScannerFailure":{"properties":{"id":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"contracts.DeprecatedConfigWarning":{"properties":{"field":{"type":"string"},"message":{"type":"string"},"replacement":{"type":"string"}},"type":"object"},"contracts.Diagnostic":{"description":"Spec 044 — structured diagnostic error and stable error code. Both\nare populated when the server is in a failed state and the error\nhas been classified by internal/diagnostics. Healthy servers omit\nthese fields.","properties":{"cause":{"type":"string"},"code":{"type":"string"},"detected_at":{"type":"string"},"docs_url":{"type":"string"},"fix_steps":{"items":{"$ref":"#/components/schemas/contracts.DiagnosticFixStep"},"type":"array","uniqueItems":false},"severity":{"type":"string"},"user_message":{"type":"string"}},"type":"object"},"contracts.DiagnosticFixStep":{"properties":{"command":{"type":"string"},"destructive":{"type":"boolean"},"fixer_key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"}},"type":"object"},"contracts.Diagnostics":{"properties":{"deprecated_configs":{"description":"Deprecated config fields found","items":{"$ref":"#/components/schemas/contracts.DeprecatedConfigWarning"},"type":"array","uniqueItems":false},"docker_status":{"$ref":"#/components/schemas/contracts.DockerStatus"},"missing_secrets":{"description":"Renamed to avoid conflict","items":{"$ref":"#/components/schemas/contracts.MissingSecretInfo"},"type":"array","uniqueItems":false},"oauth_issues":{"description":"OAuth parameter mismatches","items":{"$ref":"#/components/schemas/contracts.OAuthIssue"},"type":"array","uniqueItems":false},"oauth_required":{"items":{"$ref":"#/components/schemas/contracts.OAuthRequirement"},"type":"array","uniqueItems":false},"runtime_warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false},"timestamp":{"type":"string"},"total_issues":{"type":"integer"},"upstream_errors":{"items":{"$ref":"#/components/schemas/contracts.UpstreamError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DockerStatus":{"properties":{"available":{"type":"boolean"},"error":{"type":"string"},"version":{"type":"string"}},"type":"object"},"contracts.EditRegistrySourceRequest":{"properties":{"name":{"description":"new display name","type":"string"},"servers_url":{"description":"explicit servers-collection URL","type":"string"},"url":{"description":"new base/servers https URL","type":"string"}},"type":"object"},"contracts.ErrorResponse":{"properties":{"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.FindingCounts":{"properties":{"dangerous":{"description":"Tool poisoning, active prompt injection","type":"integer"},"info":{"description":"Low-severity CVEs, informational","type":"integer"},"total":{"type":"integer"},"warning":{"description":"Rug pull, supply chain CVEs with exploits","type":"integer"}},"type":"object"},"contracts.GetConfigResponse":{"properties":{"config":{"description":"The configuration object","type":"object"},"config_path":{"description":"Path to config file","type":"string"}},"type":"object"},"contracts.GetRegistriesResponse":{"properties":{"registries":{"items":{"$ref":"#/components/schemas/contracts.Registry"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerLogsResponse":{"properties":{"count":{"type":"integer"},"logs":{"items":{"$ref":"#/components/schemas/contracts.LogEntry"},"type":"array","uniqueItems":false},"server_name":{"type":"string"}},"type":"object"},"contracts.GetServerToolCallsResponse":{"properties":{"server_name":{"type":"string"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerToolsResponse":{"properties":{"count":{"type":"integer"},"server_name":{"type":"string"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GetServersResponse":{"properties":{"servers":{"items":{"$ref":"#/components/schemas/contracts.Server"},"type":"array","uniqueItems":false},"stats":{"$ref":"#/components/schemas/contracts.ServerStats"}},"type":"object"},"contracts.GetSessionDetailResponse":{"properties":{"session":{"$ref":"#/components/schemas/contracts.MCPSession"}},"type":"object"},"contracts.GetSessionsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"sessions":{"items":{"$ref":"#/components/schemas/contracts.MCPSession"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetToolCallDetailResponse":{"properties":{"tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"}},"type":"object"},"contracts.GetToolCallsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GlobalToolsResponse":{"properties":{"failed_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"partial":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/contracts.GlobalToolsStats"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GlobalToolsStats":{"properties":{"disabled":{"type":"integer"},"enabled":{"type":"integer"},"pending_approval":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.HealthStatus":{"description":"Unified health status calculated by the backend","properties":{"action":{"description":"Action is the suggested fix action: \"login\", \"restart\", \"enable\", \"approve\", \"view_logs\", \"set_secret\", \"configure\", \"edit_url\", or \"\" (none)","type":"string"},"admin_state":{"description":"AdminState indicates the admin state: \"enabled\", \"disabled\", or \"quarantined\"","type":"string"},"detail":{"description":"Detail is an optional longer explanation of the status","type":"string"},"level":{"description":"Level indicates the health level: \"healthy\", \"degraded\", or \"unhealthy\"","type":"string"},"summary":{"description":"Summary is a human-readable status message (e.g., \"Connected (5 tools)\")","type":"string"}},"type":"object"},"contracts.InfoEndpoints":{"description":"Available API endpoints","properties":{"http":{"description":"HTTP endpoint address (e.g., \"127.0.0.1:8080\")","type":"string"},"socket":{"description":"Unix socket path (empty if disabled)","type":"string"}},"type":"object"},"contracts.InfoResponse":{"properties":{"endpoints":{"$ref":"#/components/schemas/contracts.InfoEndpoints"},"launched_by":{"description":"LaunchedBy is the durable launch provenance of the running core (Spec\n092 FR-001a): \"tray\" when a tray spawned it, \"installer\" when the macOS\nPKG postinstall did, \"\" when user-launched or unknown. Always present\n(possibly empty) so a tray can distinguish \"old core, not mine\" from\n\"old core I may supersede\".","type":"string"},"listen_addr":{"description":"Listen address (e.g., \"127.0.0.1:8080\")","type":"string"},"pid":{"description":"PID is the operating-system process id of the running core (Spec 092\nFR-002). A tray that merely ATTACHED to a core holds no Process handle\nfor it, so without this there is no mechanism at all to stop a stale\ncore — the consent action would have nothing to act on and could only\nprint instructions. Paired with LaunchedBy it is what lets a newer tray\nsupersede a core an older tray started.","type":"integer"},"update":{"$ref":"#/components/schemas/contracts.UpdateInfo"},"update_policy":{"$ref":"#/components/schemas/contracts.UpdatePolicy"},"version":{"description":"Current MCPProxy version","type":"string"},"web_ui_url":{"description":"URL to access the web control panel","type":"string"}},"type":"object"},"contracts.IsolationConfig":{"properties":{"cpu_limit":{"type":"string"},"enabled":{"description":"Enabled is the EFFECTIVE isolation state for this server: whether its\nprocess is actually CONFINED, after the global setting, the per-server\noverride, the structural gates and the host's capabilities. It is NOT the\nraw per-server override — read EnabledOverride for that (GH #1142).\n\nREAD-ONLY. The write surfaces reject an ` + "`" + `enabled` + "`" + ` key precisely because\nit is derived: echoing it back would convert \"inherits the global\nsetting\" into a permanent explicit override. Write EnabledOverride.\n\nIt stays a non-pointer bool that is always present on the wire: the macOS\ntray decodes it as a non-optional Swift Bool, so omitting or nulling the\nkey would fail Codable for the whole server payload. Older clients that\nread this field now simply get a true answer.","type":"boolean"},"enabled_override":{"description":"EnabledOverride is the RAW per-server ` + "`" + `isolation.enabled` + "`" + ` override, as\npersisted. Absent means \"inherit the global setting\" — which is a\ndistinct state from an explicit false, and the distinction the reporting\nbug used to destroy.","type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"memory_limit":{"type":"string"},"mode_override":{"description":"ModeOverride is the RAW per-server ` + "`" + `isolation.mode` + "`" + ` override\n(\"docker\" | \"sandbox\" | \"none\"). Absent means \"inherit\".","type":"string"},"network_mode":{"type":"string"},"timeout":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationDefaults":{"description":"IsolationDefaults exposes the resolved baseline values that\nwould apply when no per-server override is set. Populated on\nlist/get responses; never consumed on PATCH requests.","properties":{"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"network_mode":{"type":"string"},"runtime_type":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationEffective":{"description":"IsolationEffective exposes the resolved isolation state (and the rule\nthat decided it) so clients can distinguish \"inherits global\" from an\nexplicit per-server choice. Read-only; never consumed on PATCH.","properties":{"global_mode":{"description":"GlobalMode is what \"inherit\" resolves to right now.","type":"string"},"inherited":{"description":"Inherited is true when the server sets neither ` + "`" + `isolation.enabled` + "`" + ` nor\n` + "`" + `isolation.mode` + "`" + `, so its state tracks the global setting.","type":"boolean"},"isolated":{"description":"Isolated reports whether the process is actually CONFINED. It is NOT\nsimply Mode != \"none\": \"sandbox\" on a host that cannot enforce Landlock\n(any non-Linux OS, or a kernel without the LSM) runs the server\nunconfined, and Source then says \"sandbox-unavailable\" (GH #1142).","type":"boolean"},"mode":{"description":"Mode is the effective isolation mode: \"docker\" | \"sandbox\" | \"none\" —\nexactly what the spawn path branches on.","type":"string"},"source":{"description":"Source names the deciding rule: \"global\", \"server-mode\",\n\"server-opt-out\", \"server-opt-in-ignored\", \"not-stdio\",\n\"already-docker\", \"sandbox-unavailable\" or \"unsupported-mode\".\nTreat an unrecognized value as \"global\".","type":"string"}},"type":"object"},"contracts.LogEntry":{"properties":{"fields":{"type":"object"},"level":{"type":"string"},"message":{"type":"string"},"server":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.MCPSession":{"properties":{"client_name":{"type":"string"},"client_version":{"type":"string"},"end_time":{"type":"string"},"experimental":{"items":{"type":"string"},"type":"array","uniqueItems":false},"has_roots":{"description":"MCP Client Capabilities","type":"boolean"},"has_sampling":{"type":"boolean"},"id":{"type":"string"},"last_activity":{"type":"string"},"start_time":{"type":"string"},"status":{"type":"string"},"tool_call_count":{"type":"integer"},"total_tokens":{"type":"integer"},"work_session_id":{"type":"string"},"workspace_name":{"description":"Workspace / work session (Spec 082). WorkspaceName is the project's\nbasename — the full local path is never exposed. WorkSessionID groups the\nreconnects that make up one stretch of user work.","type":"string"}},"type":"object"},"contracts.MetadataStatus":{"properties":{"authorization_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"error":{"type":"string"},"found":{"type":"boolean"},"url_checked":{"type":"string"}},"type":"object"},"contracts.MissingSecretInfo":{"properties":{"secret_name":{"type":"string"},"used_by":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.NPMPackageInfo":{"properties":{"exists":{"type":"boolean"},"install_cmd":{"type":"string"}},"type":"object"},"contracts.OAuthConfig":{"properties":{"auth_url":{"type":"string"},"client_id":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_port":{"type":"integer"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false},"token_expires_at":{"description":"When the OAuth token expires","type":"string"},"token_url":{"type":"string"},"token_valid":{"description":"Whether token is currently valid","type":"boolean"}},"type":"object"},"contracts.OAuthErrorDetails":{"description":"Structured discovery/failure details","properties":{"authorization_server_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"dcr_status":{"$ref":"#/components/schemas/contracts.DCRStatus"},"protected_resource_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"server_url":{"type":"string"}},"type":"object"},"contracts.OAuthFlowError":{"properties":{"correlation_id":{"description":"Flow tracking ID for log correlation","type":"string"},"debug_hint":{"description":"CLI command for log lookup","type":"string"},"details":{"$ref":"#/components/schemas/contracts.OAuthErrorDetails"},"error_code":{"description":"Machine-readable error code (e.g., OAUTH_NO_METADATA)","type":"string"},"error_type":{"description":"Category of OAuth runtime failure","type":"string"},"message":{"description":"Human-readable error description","type":"string"},"request_id":{"description":"HTTP request ID (from PR #237)","type":"string"},"server_name":{"description":"Server that failed OAuth","type":"string"},"success":{"description":"Always false","type":"boolean"},"suggestion":{"description":"Actionable remediation hint","type":"string"}},"type":"object"},"contracts.OAuthIssue":{"properties":{"documentation_url":{"type":"string"},"error":{"type":"string"},"issue":{"type":"string"},"missing_params":{"items":{"type":"string"},"type":"array","uniqueItems":false},"resolution":{"type":"string"},"server_name":{"type":"string"}},"type":"object"},"contracts.OAuthRequirement":{"properties":{"expires_at":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"state":{"type":"string"}},"type":"object"},"contracts.OAuthStartResponse":{"properties":{"auth_url":{"description":"Authorization URL (always included for manual use)","type":"string"},"browser_error":{"description":"Error message if browser launch failed","type":"string"},"browser_opened":{"description":"Whether browser launch succeeded","type":"boolean"},"correlation_id":{"description":"UUID for tracking this flow","type":"string"},"message":{"description":"Human-readable status message","type":"string"},"server_name":{"description":"Name of the server being authenticated","type":"string"},"success":{"description":"Always true for successful start","type":"boolean"}},"type":"object"},"contracts.PreflightPolicy":{"properties":{"exclude_destructive":{"type":"boolean"},"exclude_open_world":{"type":"boolean"},"read_only_only":{"type":"boolean"}},"type":"object"},"contracts.PreflightReason":{"type":"string","x-enum-varnames":["PreflightReasonServerInitializing","PreflightReasonServerUnhealthy","PreflightReasonServerDisabled","PreflightReasonServerQuarantined","PreflightReasonToolPendingApproval","PreflightReasonToolChanged","PreflightReasonToolBlockedByUser","PreflightReasonOAuthRequired","PreflightReasonHashMismatch","PreflightReasonServerNotInScope","PreflightReasonToolDeniedByConfig","PreflightReasonMissingAnnotation","PreflightReasonPolicyFiltered","PreflightReasonNotFound","PreflightReasonServerNotConfigured"]},"contracts.PreflightRequest":{"properties":{"policy":{"$ref":"#/components/schemas/contracts.PreflightPolicy"},"profile":{"description":"Profile evaluates under a named profile's server scope. Unknown: 400.","type":"string"},"tools":{"description":"Tools is 1..100 entries BEFORE dedup; duplicates are collapsed, and\nduplicate ids carrying different pins are a validation error.","items":{"$ref":"#/components/schemas/contracts.PreflightToolRef"},"type":"array","uniqueItems":false},"wait_ms":{"description":"WaitMS polls local state for up to this many milliseconds (cap 10000)\nwhile every failure is retryable-class.","type":"integer"}},"type":"object"},"contracts.PreflightResponse":{"properties":{"checked_at":{"type":"string"},"tools":{"description":"Tools are ordered by first occurrence of each unique id in the request.","items":{"$ref":"#/components/schemas/contracts.PreflightToolResult"},"type":"array","uniqueItems":false},"verdict":{"$ref":"#/components/schemas/contracts.PreflightVerdict"},"waited_ms":{"description":"WaitedMS is present when wait_ms was requested (0 when the wait\nsemaphore was exhausted and the request resolved immediately).","type":"integer"}},"type":"object"},"contracts.PreflightStatus":{"type":"string","x-enum-varnames":["PreflightStatusReady","PreflightStatusUnavailable"]},"contracts.PreflightToolRef":{"properties":{"id":{"description":"ID is a canonical \"\u003cserver\u003e:\u003ctool\u003e\" id. A malformed id is answered with a\nper-ID not_found carrying a format hint, never a request-level error.","type":"string"},"pin_hash":{"description":"PinHash is \"sha256/v{N}:{hex}\" — the schema version is embedded so a\nproxy-side hash-algorithm bump is distinguishable from upstream drift.","type":"string"}},"type":"object"},"contracts.PreflightToolResult":{"properties":{"action":{"type":"string"},"detail":{"type":"string"},"did_you_mean":{"description":"DidYouMean carries up to 3 nearest caller-visible ids on not_found. It\nnever crosses a scope boundary and never names a quarantined server's\ntools.","items":{"type":"string"},"type":"array","uniqueItems":false},"hash":{"description":"Hash is the tool's current pin (\"sha256/v{N}:{hex}\") — operator tier,\nready results only. Never disclosed to an agent token.","type":"string"},"id":{"type":"string"},"reason":{"$ref":"#/components/schemas/contracts.PreflightReason"},"remediation":{"type":"string"},"retryable":{"type":"boolean"},"status":{"$ref":"#/components/schemas/contracts.PreflightStatus"}},"type":"object"},"contracts.PreflightVerdict":{"type":"string","x-enum-varnames":["PreflightVerdictReady","PreflightVerdictDegradedRetryable","PreflightVerdictBlocked","PreflightVerdictUnknownIDs"]},"contracts.QuarantineStats":{"description":"Tool quarantine metrics for this server","properties":{"blocked_count":{"description":"Number of disabled (blocked) tools","type":"integer"},"changed_count":{"description":"Number of tools whose description/schema changed since approval","type":"integer"},"pending_count":{"description":"Number of newly discovered tools awaiting approval","type":"integer"}},"type":"object"},"contracts.RefreshRegistryResponse":{"properties":{"cleared":{"description":"number of cached entries dropped","type":"integer"},"registry_id":{"type":"string"}},"type":"object"},"contracts.Registry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag (MCP-866): \"official/trusted\" for built-in\ndefaults, \"custom/unverified\" for user-added registries.","type":"string"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"trusted":{"description":"Trusted indicates whether this is an official, shipped-by-default\nregistry. Trust is derived from membership in the default set, never\nfrom self-assertion in config.","type":"boolean"},"url":{"type":"string"}},"type":"object"},"contracts.RegistryCacheInfo":{"properties":{"age_seconds":{"type":"number"},"stale":{"type":"boolean"}},"type":"object"},"contracts.RegistryUnavailable":{"properties":{"reason":{"type":"string"}},"type":"object"},"contracts.ReplayToolCallRequest":{"properties":{"arguments":{"description":"Modified arguments for replay","type":"object"}},"type":"object"},"contracts.ReplayToolCallResponse":{"properties":{"error":{"description":"Error if replay failed","type":"string"},"new_call_id":{"description":"ID of the newly created call","type":"string"},"new_tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"replayed_from":{"description":"Original call ID","type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.RepositoryInfo":{"description":"Detected package info","properties":{"npm":{"$ref":"#/components/schemas/contracts.NPMPackageInfo"}},"type":"object"},"contracts.RepositoryServer":{"properties":{"connect_url":{"description":"Alternative connection URL","type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"install_cmd":{"description":"Installation command","type":"string"},"name":{"type":"string"},"registry":{"description":"Which registry this came from","type":"string"},"repository_info":{"$ref":"#/components/schemas/contracts.RepositoryInfo"},"source_code_url":{"description":"Source repository URL","type":"string"},"updated_at":{"type":"string"},"url":{"description":"MCP endpoint for remote servers only","type":"string"}},"type":"object"},"contracts.SearchRegistryServersResponse":{"properties":{"cache":{"$ref":"#/components/schemas/contracts.RegistryCacheInfo"},"query":{"type":"string"},"registry_id":{"type":"string"},"servers":{"items":{"$ref":"#/components/schemas/contracts.RepositoryServer"},"type":"array","uniqueItems":false},"tag":{"type":"string"},"total":{"type":"integer"},"unavailable":{"$ref":"#/components/schemas/contracts.RegistryUnavailable"}},"type":"object"},"contracts.SearchResult":{"properties":{"matches":{"type":"integer"},"score":{"type":"number"},"snippet":{"type":"string"},"tool":{"$ref":"#/components/schemas/contracts.Tool"}},"type":"object"},"contracts.SearchToolsResponse":{"properties":{"query":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/contracts.SearchResult"},"type":"array","uniqueItems":false},"took":{"type":"string"},"total":{"type":"integer"}},"type":"object"},"contracts.SecurityScanSummary":{"description":"Latest security scan results summary","properties":{"deep_scan":{"$ref":"#/components/schemas/contracts.DeepScanDescriptor"},"finding_counts":{"$ref":"#/components/schemas/contracts.FindingCounts"},"last_scan_at":{"type":"string"},"risk_score":{"description":"0-100","type":"integer"},"scanners_failed":{"type":"integer"},"scanners_run":{"description":"Scanner coverage for the primary (baseline) scan pass — informational only.\nSpec 077 US3 (FR-008/FR-014): Status is derived SOLELY from the\ndeterministic baseline findings; a failed Docker deep scanner no longer\ndowngrades a clean verdict. That failure is surfaced via DeepScan instead.","type":"integer"},"scanners_total":{"type":"integer"},"status":{"description":"\"clean\", \"warnings\", \"dangerous\", \"failed\", \"not_scanned\", \"scanning\"","type":"string"}},"type":"object"},"contracts.Server":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"authenticated":{"description":"OAuth authentication status","type":"boolean"},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges mirrors config.ServerConfig.AutoApproveToolChanges\n(MCP-2930): the per-server intent to auto-approve new/changed tools past\nthe trust baseline. Tri-state *bool — nil means \"never set\" (omitted from\nthe payload), so the Web UI toggle (MCP-2932) can distinguish unset from\nan explicit false. Read-only on the GET path; PATCH/POST accept it via\nAddServerRequest.","type":"boolean"},"command":{"type":"string"},"connected":{"type":"boolean"},"connected_at":{"type":"string"},"connecting":{"type":"boolean"},"created":{"type":"string"},"diagnostic":{"$ref":"#/components/schemas/contracts.Diagnostic"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"error_code":{"type":"string"},"expose_prompts":{"description":"ExposePrompts mirrors config.ServerConfig.ExposePrompts (F9): the per-server\nprompt-aggregation override. Tri-state *bool — nil/omitted means \"inherit\ndefault aggregation\". Surfaced on GET so a caller that PATCHed the override\ncan read it back; PATCH/POST accept it via AddServerRequest.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"health":{"$ref":"#/components/schemas/contracts.HealthStatus"},"id":{"type":"string"},"init_timeout":{"description":"InitTimeout mirrors config.ServerConfig.InitTimeout (MCP-3322 / GH #760):\nthe per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override. Serialized as\na duration string (e.g. \"120s\"); nil/omitted means \"inherit the global\ndefault\". Surfaced on the GET path so clients can read back a configured\noverride; PATCH/POST accept it via AddServerRequest.","type":"string"},"isolation":{"$ref":"#/components/schemas/contracts.IsolationConfig"},"isolation_defaults":{"$ref":"#/components/schemas/contracts.IsolationDefaults"},"isolation_effective":{"$ref":"#/components/schemas/contracts.IsolationEffective"},"last_error":{"type":"string"},"last_reconnect_at":{"type":"string"},"last_retry_time":{"type":"string"},"max_concurrent_requests":{"description":"Spec 093 (GH #955) — per-server concurrency overrides, scope (c) of\nFR-020. Each setting is tri-state: nil (omitted) means \"inherit\nserver_concurrency_defaults\", 0 disables that setting for this server,\npositive overrides it. Surfaced on the GET path so a caller can read back\nwhat it set; PATCH/POST accept them via AddServerRequest. The effective\nconcurrency for a server is additionally bounded by the global aggregate\nlimiter, which is NOT an inheritance source for these fields.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/contracts.OAuthConfig"},"oauth_status":{"description":"OAuth status: \"authenticated\", \"expired\", \"error\", \"none\"","type":"string"},"protocol":{"type":"string"},"quarantine":{"$ref":"#/components/schemas/contracts.QuarantineStats"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_count":{"type":"integer"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets this disconnected server","type":"boolean"},"retry_count":{"type":"integer"},"retry_stopped":{"description":"RetryStopped reports that automatic reconnection has been given up for\ngood because the failure is deterministic and unrecoverable — a missing\nbinary, an image without the interpreter, an unparseable config (GH\n#1145). It is NOT ordinary exponential backoff, which keeps retrying;\nnothing will happen until the user fixes the config or restarts the\nserver. RetryStoppedCode is the stable MCPX_* code that proved it and\nRetryStoppedReason the catalog message explaining how to fix it. All three\nare omitted for servers that are healthy or still retrying.","type":"boolean"},"retry_stopped_code":{"type":"string"},"retry_stopped_reason":{"type":"string"},"security_scan":{"$ref":"#/components/schemas/contracts.SecurityScanSummary"},"should_retry":{"type":"boolean"},"source_registry_id":{"description":"MCP-901 — registry provenance of an upstream that was added from a\nregistry. SourceRegistryID names the source registry (empty for\nmanually-configured servers); SourceRegistryProvenance is the trust tag\nrecorded at add time (\"official/trusted\" or \"custom/unverified\"). Both\nare projected from config.ServerConfig so the approval/quarantine view\ncan render an \"added from \u003cregistry\u003e · unverified\" origin badge. Optional\nand omitted when empty — clients that pre-date this treat them as absent.","type":"string"},"source_registry_provenance":{"type":"string"},"status":{"type":"string"},"token_expires_at":{"description":"When the OAuth token expires (ISO 8601)","type":"string"},"tool_count":{"type":"integer"},"tool_list_token_size":{"description":"Token size for this server's tools","type":"integer"},"trust_mode":{"description":"TrustMode mirrors config.ServerConfig.TrustMode (spec 086): the per-server\ntrust tier (\"auto\"/\"scan\"/\"manual\"). Surfaced on the GET path so clients can\nread back the persisted mode; PATCH/POST accept it via AddServerRequest.\nOmitted when empty (server predates the field / relies on legacy flags).","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"user_logged_out":{"description":"True if user explicitly logged out (prevents auto-reconnection)","type":"boolean"},"working_dir":{"type":"string"}},"type":"object"},"contracts.ServerActionResponse":{"properties":{"action":{"type":"string"},"async":{"type":"boolean"},"server":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ServerStats":{"properties":{"connected_servers":{"type":"integer"},"docker_containers":{"type":"integer"},"quarantined_servers":{"type":"integer"},"token_metrics":{"$ref":"#/components/schemas/contracts.ServerTokenMetrics"},"total_servers":{"type":"integer"},"total_tools":{"type":"integer"}},"type":"object"},"contracts.ServerTokenMetrics":{"properties":{"average_query_result_size":{"description":"Typical retrieve_tools output (tokens)","type":"integer"},"per_server_tool_list_sizes":{"additionalProperties":{"type":"integer"},"description":"Token size per server","type":"object"},"saved_tokens":{"description":"Difference","type":"integer"},"saved_tokens_percentage":{"description":"Percentage saved","type":"number"},"total_server_tool_list_size":{"description":"All upstream tools combined (tokens)","type":"integer"}},"type":"object"},"contracts.SuccessResponse":{"properties":{"data":{"type":"object"},"success":{"type":"boolean"}},"type":"object"},"contracts.Tier":{"description":"Tier is computed by AnnotationTier (Spec 109 FR-028/X11) from\nAnnotations — read|write|destructive|unannotated. Set by every producer\nof a Tool (enrichServerTools, the global tools handler); never left for\na consuming surface to compute.","type":"string","x-enum-varnames":["TierRead","TierWrite","TierDestructive","TierUnannotated","TierUnknown"]},"contracts.TokenMetrics":{"description":"Token usage metrics (nil for older records)","properties":{"encoding":{"description":"Encoding used (e.g., cl100k_base)","type":"string"},"estimated_cost":{"description":"Optional cost estimate","type":"number"},"input_tokens":{"description":"Tokens in the request","type":"integer"},"model":{"description":"Model used for tokenization","type":"string"},"output_tokens":{"description":"Tokens in the response","type":"integer"},"total_tokens":{"description":"Total tokens (input + output)","type":"integer"},"truncated_tokens":{"description":"Tokens removed by truncation","type":"integer"},"was_truncated":{"description":"Whether response was truncated","type":"boolean"}},"type":"object"},"contracts.Tool":{"properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"approval_status":{"type":"string"},"config_denied":{"description":"ConfigDenied is true when the tool is denied by the server's static\nenabled_tools / disabled_tools config. The user cannot override this toggle.","type":"boolean"},"description":{"type":"string"},"disabled":{"description":"Disabled mirrors ToolApprovalRecord.Disabled so per-tool enable state is\navailable without a second round-trip to the approvals endpoint. Absent\nin the JSON when false (default) to keep responses compact.","type":"boolean"},"hash":{"description":"Hash is the tool's current stored hash rendered in the preflight pin\nformat \"sha256/v{N}:{hex}\" (Spec 098 FR-011), where N is the approval\nrecord's HashSchemaVersion. It is the authoring surface for\n` + "`" + `POST /api/v1/preflight` + "`" + ` pins and ` + "`" + `mcpproxy tools preflight --pin` + "`" + `:\ncopy the value straight into a pin.\n\nDisclosure is OPERATOR TIER ONLY — same rule as the preflight per-tool\nresult. The field is omitted for agent-token callers and for tools with\nno stored hash (no approval record yet, or a record written before\nhashes existed).","type":"string"},"held_reason":{"description":"HeldReason, HeldVerdict and HeldSignals mirror the same-named fields on\nstorage.ToolApprovalRecord: the offline-scan evidence that made\ntrust_mode: scan hold this tool for review (spec 086 FR-018). HeldSignals\nnames the matched deterministic check ids, e.g.\n\"tpa.TPA-2026-0001.hidden_instruction\", so a reviewer can see WHY the tool\nis held. All three are omitted for tools that are not held by the scan gate\n(including every record written before the field existed).","type":"string"},"held_signals":{"items":{"type":"string"},"type":"array","uniqueItems":false},"held_verdict":{"type":"string"},"last_used":{"type":"string"},"name":{"type":"string"},"schema":{"type":"object"},"server_name":{"type":"string"},"tier":{"$ref":"#/components/schemas/contracts.Tier"},"usage":{"type":"integer"}},"type":"object"},"contracts.ToolAnnotation":{"description":"Tool behavior hints snapshot","properties":{"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"},"readOnlyHint":{"type":"boolean"},"title":{"type":"string"}},"type":"object"},"contracts.ToolCallRecord":{"description":"The new tool call record","properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"arguments":{"description":"Tool arguments","type":"object"},"arguments_truncated":{"description":"ArgumentsTruncated marks Arguments as a placeholder rather than the\narguments the tool was called with. Replaying such a record without\nsupplying arguments explicitly is refused.","type":"boolean"},"config_path":{"description":"Active config file path","type":"string"},"duration":{"description":"Duration in nanoseconds","type":"integer"},"error":{"description":"Error message (failure only)","type":"string"},"execution_type":{"description":"\"direct\" or \"code_execution\"","type":"string"},"id":{"description":"Unique identifier","type":"string"},"mcp_client_name":{"description":"MCP client name from InitializeRequest","type":"string"},"mcp_client_version":{"description":"MCP client version","type":"string"},"mcp_session_id":{"description":"MCP session identifier","type":"string"},"metrics":{"$ref":"#/components/schemas/contracts.TokenMetrics"},"parent_call_id":{"description":"Links nested calls to parent code_execution","type":"string"},"request_id":{"description":"Request correlation ID","type":"string"},"response":{"description":"Tool response (success only)","type":"object"},"response_bytes":{"description":"Marshalled response size before truncation","type":"integer"},"response_truncated":{"description":"ResponseTruncated and ResponseBytes describe a STORAGE-side cut (#1176):\nthe caller received the response whole, and only the persisted copy was\nshortened to tool_call_max_response_size. When ResponseTruncated is true\nthe Response object carries {truncated, original_bytes, preview, note}\ninstead of the upstream result, and ResponseBytes is its size before the\ncut.","type":"boolean"},"server_id":{"description":"Server identity hash","type":"string"},"server_name":{"description":"Human-readable server name","type":"string"},"timestamp":{"description":"When the call was made","type":"string"},"tool_name":{"description":"Tool name (without server prefix)","type":"string"}},"type":"object"},"contracts.UpdateInfo":{"description":"Update information (if available)","properties":{"available":{"description":"Whether an update is available","type":"boolean"},"behind_summary":{"description":"Spec 079 FR-002 — how far behind the running build is. All four are\nadditive (FR-021) and absent when the delta could not be resolved, in\nwhich case every surface renders its pre-delta wording.","type":"string"},"check_error":{"description":"Error message if update check failed","type":"string"},"checked_at":{"description":"When the update check was performed","type":"string"},"install_channel":{"description":"Detected install channel (homebrew, dmg, deb, rpm, docker, go-install, windows-installer, tarball, unknown) — Spec 079 FR-008","type":"string"},"is_prerelease":{"description":"Whether the latest version is a prerelease","type":"boolean"},"latest_version":{"description":"Latest version available (e.g., \"v1.2.3\")","type":"string"},"nudges_suppressed":{"description":"UI surfaces must stay quiet (CI / non-interactive context); machine-readable fields still report the facts — Spec 079 FR-019","type":"boolean"},"release_url":{"description":"URL to the release page","type":"string"},"releases_behind":{"description":"Releases on the offered channel between the running and offered versions","type":"integer"},"releases_behind_saturated":{"description":"ReleasesBehind is a lower bound: the running build predates the scanned release window","type":"boolean"},"update_command":{"description":"One-line update command for the channel; only set when an update is available and the channel has one — Spec 079 FR-009","type":"string"},"weeks_behind":{"description":"Whole weeks between the two releases' publish dates; 0 is a real value, absent means unknown","type":"integer"}},"type":"object"},"contracts.UpdatePolicy":{"description":"UpdatePolicy is the effective, hot-reloadable update policy (Spec 092\nFR-015). Always present: the ` + "`" + `update` + "`" + ` object above is omitted both when\nupdate checking is disabled AND when no check has produced a result\nyet, so its absence cannot tell a client whether it is allowed to run\nits own (e.g. Sparkle feed) check. This field states the answer.","properties":{"channel":{"description":"Channel is the tracked release channel: \"stable\" or \"rc\".","type":"string"},"enabled":{"description":"Enabled is the effective automatic-check kill switch: update_check.enabled\nwith MCPPROXY_DISABLE_AUTO_UPDATE=true winning over it. A user-initiated\n\"Check for Updates\" stays available regardless.","type":"boolean"},"nudges_suppressed":{"description":"NudgesSuppressed asks UI surfaces to stay quiet (CI / non-interactive)\nwhile machine-readable fields keep reporting the facts.","type":"boolean"}},"type":"object"},"contracts.UpstreamError":{"properties":{"error_message":{"type":"string"},"server_name":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.UsageAggregateResponse":{"properties":{"freshness_ms":{"description":"age of the underlying snapshot in ms","type":"integer"},"generated_at":{"type":"string"},"other":{"$ref":"#/components/schemas/contracts.UsageOtherBucket"},"timeline":{"items":{"$ref":"#/components/schemas/contracts.UsageTimeBucket"},"type":"array","uniqueItems":false},"token_source":{"description":"\"bytes\" (size-based proxy, FR-006)","type":"string"},"tokens_saved":{"description":"echoed from ServerTokenMetrics (FR-007)","type":"integer"},"tokens_saved_percentage":{"type":"number"},"tools":{"items":{"$ref":"#/components/schemas/contracts.UsageToolStat"},"type":"array","uniqueItems":false},"total_calls":{"description":"TotalCalls and TotalErrors are the headline counts for the window: the sum\nof the timeline this same response carries, so the tiles and the histogram\nunder them cannot disagree. They are NOT the sum of Tools — that list is\nlifetime-cumulative, upstream-only and truncated to top-N, and summing it\nclient-side is what made the Usage tab print a third number for the same\n24 hours (audit finding F1, #1046). The population is\nstorage.CountsAsCall, shared with ActivitySummaryResponse.CallCount.\n\nTwo bounds on how exactly this matches the Activity Log's own count.\nBoth are bounded and disclosed, unlike the population mismatch they\nreplace, which was unbounded and silent:\n\n  - Window granularity is the timeline's: whole hour buckets, so the span\n    is the requested window rounded up to a bucket edge.\n  - This response is served from a snapshot behind a short read cache\n    (observability.usage_cache_ttl, 5s by default) so the endpoint never\n    scans the activity log per request, while the summary endpoint counts\n    live. Calls that land inside that window appear on the Activity Log\n    first. FreshnessMs and GeneratedAt say how old the figures are, and\n    the Usage tab prints it (\"Updated 3s ago\").","type":"integer"},"total_errors":{"type":"integer"},"window":{"type":"string"}},"type":"object"},"contracts.UsageOtherBucket":{"description":"present only when the list was truncated to top-N","properties":{"calls":{"type":"integer"},"tools_folded":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageTimeBucket":{"properties":{"calls":{"type":"integer"},"errors":{"type":"integer"},"start":{"type":"string"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageToolStat":{"properties":{"avg_req_bytes":{"description":"null when no sized request calls","type":"integer"},"avg_resp_bytes":{"description":"null when sized_calls == 0 (only legacy 0-byte calls)","type":"integer"},"blocked":{"type":"integer"},"calls":{"type":"integer"},"error_rate":{"type":"number"},"errors":{"type":"integer"},"last_used":{"type":"string"},"p50_exceeds":{"type":"boolean"},"p50_ms":{"description":"P50Ms and P95Ms are read off a fixed latency histogram, so they are BUCKET\nBOUNDS, not measured durations: the true percentile is at or below the\nvalue, and a client must render it as a bound (\"≤ 5 ms\"). P50Exceeds /\nP95Exceeds flip that reading for the unbounded overflow bucket, where the\nvalue is the last bound and the truth is above it (\"\u003e 10 s\").","type":"integer"},"p95_exceeds":{"type":"boolean"},"p95_ms":{"type":"integer"},"rejected":{"description":"spec 093: shed by a concurrency limit; never executed, so excluded from calls/latency","type":"integer"},"server":{"type":"string"},"sized_calls":{"description":"calls with known response size (basis for avg_resp_bytes)","type":"integer"},"tool":{"type":"string"},"total_req_bytes":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.ValidateConfigResponse":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false},"valid":{"type":"boolean"}},"type":"object"},"contracts.ValidationError":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"data":{"properties":{"data":{"$ref":"#/components/schemas/contracts.InfoResponse"}},"type":"object"},"httpapi.AddServerRequest":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve\nnew/changed tools past the trust baseline (MCP-2930). Tri-state *bool:\na nil pointer means \"leave unchanged\" on PATCH; a present value\n(including false) is applied. Mirrors config.ServerConfig's *bool\nsemantics — do NOT collapse to a plain bool, or an omitted field would\nsilently reset a previously-set value.","type":"boolean"},"command":{"type":"string"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts is the per-server override for prompt aggregation (F9):\nwhether this server's advertised MCP prompts are merged into mcpproxy's\nprompts/list. Tri-state *bool mirroring config.ServerConfig.ExposePrompts —\na nil pointer means \"leave unchanged\" on PATCH (and \"inherit the default\naggregate behavior\" on create); a present value (including false) is applied.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"init_timeout":{"description":"InitTimeout is the per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override\n(MCP-3322 / GH #760), serialized as a duration string (e.g. \"120s\"). A nil\npointer means \"leave unchanged\" on PATCH; a present value is applied.\nMirrors config.ServerConfig.InitTimeout's *Duration tri-state.","type":"string"},"isolation":{"$ref":"#/components/schemas/httpapi.IsolationRequest"},"max_concurrent_requests":{"description":"MaxConcurrentRequests / QueueSize / QueueTimeout are the per-server\nconcurrency overrides (spec 093 / GH #955, FR-020 scope (c)). Each is\ntri-state: a nil pointer means \"leave unchanged\" on PATCH and \"inherit\nserver_concurrency_defaults\" on create; an explicit 0 disables that\nsetting for this server; a positive value overrides it. Do NOT collapse\nthem to plain values — an omitted field would then silently reset a\nconfigured limit.","type":"integer"},"name":{"type":"string"},"protocol":{"type":"string"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"type":"boolean"},"trust_mode":{"description":"TrustMode is the per-server trust tier (spec 086): \"auto\", \"scan\", or\n\"manual\". Empty means \"leave unchanged\" on PATCH (and inherit the migrated\ndefault on create). A non-empty value is applied to ServerConfig.TrustMode\nand resolved by EffectiveTrustMode (an unrecognized value fails closed to\nmanual). This is the REST seam for changing the trust tier via\nPOST/PATCH /api/v1/servers.","type":"string"},"url":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.CanonicalConfigPath":{"properties":{"description":{"description":"Brief description","type":"string"},"exists":{"description":"Whether the file exists","type":"boolean"},"format":{"description":"Format identifier (e.g., \"claude_desktop\")","type":"string"},"name":{"description":"Display name (e.g., \"Claude Desktop\")","type":"string"},"os":{"description":"Operating system (darwin, windows, linux)","type":"string"},"path":{"description":"Full path to the config file","type":"string"}},"type":"object"},"httpapi.CanonicalConfigPathsResponse":{"properties":{"os":{"description":"Current operating system","type":"string"},"paths":{"description":"List of canonical config paths","items":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPath"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ConnectConflictResponse":{"properties":{"action":{"description":"already_exists | precondition_failed","type":"string"},"data":{"$ref":"#/components/schemas/connect.ConnectResult"},"error":{"description":"Human-readable message","type":"string"},"success":{"description":"Always false","type":"boolean"}},"type":"object"},"httpapi.ConnectRequest":{"properties":{"force":{"description":"Overwrite existing entry","type":"boolean"},"precondition_token":{"description":"PreconditionToken is the opaque token from the preview this write was\nconfirmed against (Spec 091 FR-005). When present, the core rechecks it\nat write time and responds 409 with action \"precondition_failed\" —\nwriting nothing — if the config or the entry MCPProxy would write has\ndrifted since; the caller then re-previews instead of retrying. Absent\nmeans exactly the pre-091 behavior. A replace-classified flow sends this\nTOGETHER with force=true: the token, not the absence of force, is the\noverwrite safety.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.ImportFromPathRequest":{"properties":{"format":{"description":"Optional format hint","type":"string"},"path":{"description":"File path to import from","type":"string"},"rename":{"additionalProperties":{"type":"string"},"description":"Rename maps a server name → new name. Applied after parsing so the\ncaller can disambiguate cross-source name collisions (Spec 046 v2 —\ne.g. \"mcpproxy\" → \"mcpproxy_claude_code\"). Keys are matched against\neither the raw source name (OriginalName) or the sanitized name shown\nin the preview (Server.Name); these differ for names that need\nsanitizing (e.g. \"Figma Desktop\" → \"Figma_Desktop\"). Keys not present\nin the imported set are ignored.","type":"object"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportRequest":{"properties":{"content":{"description":"Raw JSON or TOML content","type":"string"},"format":{"description":"Optional format hint","type":"string"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportResponse":{"properties":{"failed":{"items":{"$ref":"#/components/schemas/configimport.FailedServer"},"type":"array","uniqueItems":false},"format":{"type":"string"},"format_name":{"type":"string"},"imported":{"items":{"$ref":"#/components/schemas/httpapi.ImportedServerResponse"},"type":"array","uniqueItems":false},"skipped":{"items":{"$ref":"#/components/schemas/configimport.SkippedServer"},"type":"array","uniqueItems":false},"summary":{"$ref":"#/components/schemas/configimport.ImportSummary"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportedServerResponse":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"command":{"type":"string"},"fields_skipped":{"items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"type":"string"},"original_name":{"type":"string"},"protocol":{"type":"string"},"source_format":{"type":"string"},"url":{"type":"string"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.IsolationRequest":{"description":"Isolation carries per-server Docker isolation overrides (enabled,\nmode_override, image, network_mode, extra_args, working_dir). A nil\npointer means \"do not touch isolation config\". A present object is\napplied field-by-field ON TOP of the persisted overrides, so omitting a\nfield leaves it alone; clear an individual override by sending it\nexplicitly (` + "`" + `\"enabled\": null` + "`" + `, ` + "`" + `\"image\": \"\"` + "`" + `).","properties":{"enabled":{"description":"Enabled exists ONLY to detect and reject an echoed-back read. It is the\neffective state on the read surface and is never writable; see validate().","type":"boolean"},"enabled_override":{"description":"EnabledOverride is the tri-state per-server override — the RAW value, the\nsame one reads return as ` + "`" + `enabled_override` + "`" + `. It has THREE meaningful wire\nstates, and collapsing them is what silently un-isolated servers\n(GH #1142):\n  - absent          → leave the persisted override untouched\n  - null            → clear the override, back to inheriting the global\n  - true / false    → set an explicit opt-in / opt-out","type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"mode_override":{"description":"ModeOverride sets ` + "`" + `isolation.mode` + "`" + ` (\"docker\" | \"sandbox\" | \"none\").\nnil leaves the persisted value alone; an empty string clears it. An\nunrecognized value is rejected with a 400 rather than persisted.","type":"string"},"network_mode":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.OnboardingMarkRequest":{"properties":{"connect_step_status":{"description":"ConnectStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value. The stored enum is wider (Spec 080\nFR-001): a \"skipped\" request for a previously untouched connect step\nis upgraded server-side to \"completed_external\" when the install\nshows positive evidence of an external connection (Spec 080 FR-002).\n\"completed_external\" is NOT accepted from clients — it must never be\npersisted without that server-verified evidence (edge case: \"never\nguess completed_external without positive evidence\").","type":"string"},"engaged":{"description":"Engaged marks the wizard as engaged (completed or explicitly skipped).\nOnce true, the wizard does not auto-show again.","type":"boolean"},"mark_shown":{"description":"MarkShown records the wizard's first display time if not already set.","type":"boolean"},"server_step_status":{"description":"ServerStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value.","type":"string"}},"type":"object"},"httpapi.SetActiveProfileRequest":{"properties":{"active_profile":{"type":"string"},"profile":{"type":"string"}},"type":"object"},"httpapi.UndoConnectRequest":{"properties":{"backup_name":{"description":"BackupName is the bare filename (filepath.Base) of the backup returned as\nbackup_path by the preceding connect — a name, never a path. Undo resolves\nthe full path server-side by joining it with the client's own config\ndirectory, so a client-supplied value can never contribute a directory\ncomponent (traversal is impossible by construction). Empty means the\nconnect created the file (no prior file existed), so undo removes it.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.UpdateFailureRequest":{"properties":{"stage":{"description":"Stage is the failure stage of the update session.","enum":["appcast","download","install","other"],"type":"string"}},"type":"object"},"management.BulkOperationResult":{"properties":{"errors":{"additionalProperties":{"type":"string"},"description":"Map of server name to error message","type":"object"},"failed":{"description":"Number of failed operations","type":"integer"},"successful":{"description":"Number of successful operations","type":"integer"},"total":{"description":"Total servers processed","type":"integer"}},"type":"object"},"observability.HealthResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"observability.HealthStatus":{"properties":{"error":{"type":"string"},"latency":{"type":"string"},"name":{"type":"string"},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"}},"type":"object"},"observability.ReadinessResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"ready\" or \"not_ready\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"secureenv.EnvConfig":{"description":"Environment configuration for secure variable filtering","properties":{"allowed_system_vars":{"items":{"type":"string"},"type":"array","uniqueItems":false},"custom_vars":{"additionalProperties":{"type":"string"},"type":"object"},"enhance_path":{"description":"Enable PATH enhancement for Launchd scenarios","type":"boolean"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned upstream servers (MCP-2769). It is OFF by\ndefault and deliberately kept out of the AllowedSystemVars default list:\nproxy URLs frequently carry credentials (http://user:pass@proxy), so\nforwarding them to every stdio upstream is a credential-leak risk. When\nenabled, values are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"inherit_system_safe":{"type":"boolean"}},"type":"object"},"telemetry.FeedbackContext":{"properties":{"arch":{"type":"string"},"connected_server_count":{"type":"integer"},"edition":{"type":"string"},"os":{"type":"string"},"routing_mode":{"type":"string"},"server_count":{"type":"integer"},"version":{"type":"string"}},"type":"object"},"telemetry.FeedbackRequest":{"properties":{"category":{"description":"bug, feature, other","type":"string"},"context":{"$ref":"#/components/schemas/telemetry.FeedbackContext"},"email":{"type":"string"},"message":{"type":"string"}},"type":"object"},"telemetry.FeedbackResponse":{"properties":{"error":{"type":"string"},"issue_url":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"API key authentication via query parameter. Use ?apikey=your-key","in":"query","name":"apikey","type":"apiKey"}}},
     "info": {"contact":{"name":"MCPProxy Support","url":"https://github.com/smart-mcp-proxy/mcpproxy-go"},"description":"{{escape .Description}}","license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"title":"{{.Title}}","version":"{{.Version}}"},
     "externalDocs": {"description":"","url":""},
     "paths": {"/api/v1/activity":{"get":{"description":"Returns paginated list of activity records with optional filtering","parameters":[{"description":"Filter by activity type(s), comma-separated for multiple (Spec 024)","in":"query","name":"type","schema":{"enum":["tool_call","policy_decision","quarantine_change","server_change","system_start","system_stop","internal_tool_call","config_change","preflight","prompt_get"],"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"enum":["success","error","blocked","rejected"],"type":"string"}},{"description":"Filter by intent operation type (Spec 018)","in":"query","name":"intent_type","schema":{"enum":["read","write","destructive"],"type":"string"}},{"description":"Filter by HTTP request ID for log correlation (Spec 021)","in":"query","name":"request_id","schema":{"type":"string"}},{"description":"Filter by parent call id — returns the sub-calls one code_execution issued","in":"query","name":"parent_id","schema":{"type":"string"}},{"description":"Include successful call_tool_* internal tool calls (default: false, excluded to avoid duplicates)","in":"query","name":"include_call_tool","schema":{"type":"boolean"}},{"description":"Filter by sensitive data detection (true=has detections, false=no detections)","in":"query","name":"sensitive_data","schema":{"type":"boolean"}},{"description":"Filter by specific detection type (e.g., 'aws_access_key', 'credit_card')","in":"query","name":"detection_type","schema":{"type":"string"}},{"description":"Filter by severity level","in":"query","name":"severity","schema":{"enum":["critical","high","medium","low"],"type":"string"}},{"description":"Filter by agent token name (Spec 028)","in":"query","name":"agent","schema":{"type":"string"}},{"description":"Filter by auth type (Spec 028)","in":"query","name":"auth_type","schema":{"enum":["admin","agent"],"type":"string"}},{"description":"Filter activities after this time (RFC3339)","in":"query","name":"start_time","schema":{"type":"string"}},{"description":"Filter activities before this time (RFC3339)","in":"query","name":"end_time","schema":{"type":"string"}},{"description":"Maximum records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Pagination offset (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Omit arguments, response and metadata except a contextual whitelist (intent.reason, intent.operation_type, decision, reason, client_name, client_version) (default: false). For clients that render summary fields only; has_sensitive_data is still derived before metadata is dropped.","in":"query","name":"exclude_payloads","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"List activity records","tags":["Activity"]}},"/api/v1/activity/export":{"get":{"description":"Exports activity records in JSON Lines or CSV format for compliance","parameters":[{"description":"Export format: json (default) or csv","in":"query","name":"format","schema":{"type":"string"}},{"description":"Filter by activity type","in":"query","name":"type","schema":{"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"type":"string"}},{"description":"Filter by HTTP request ID for log correlation (Spec 021)","in":"query","name":"request_id","schema":{"type":"string"}},{"description":"Filter by parent call id — exports the sub-calls one code_execution issued","in":"query","name":"parent_id","schema":{"type":"string"}},{"description":"Filter activities after this time (RFC3339)","in":"query","name":"start_time","schema":{"type":"string"}},{"description":"Filter activities before this time (RFC3339)","in":"query","name":"end_time","schema":{"type":"string"}},{"description":"Maximum records to export (1-50000, default 10000)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Pagination offset (default 0)","in":"query","name":"offset","schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}}},"description":"Streamed activity records"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Export activity records","tags":["Activity"]}},"/api/v1/activity/summary":{"get":{"description":"Returns aggregated activity statistics for a time period","parameters":[{"description":"Time period: 1h, 24h (default), 7d, 30d","in":"query","name":"period","schema":{"type":"string"}},{"description":"Group by: server, tool (optional)","in":"query","name":"group_by","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity summary statistics","tags":["Activity"]}},"/api/v1/activity/usage":{"get":{"description":"Returns the actor-owned usage aggregate (per-tool rollup + timeline + tokens-saved headline) for the Web UI usage graphs (Spec 069). Served from an in-memory snapshot — never a per-request full-log scan. Per-tool metrics are lifetime-cumulative; ` + "`" + `window` + "`" + ` scopes the timeline and filters the tool list to tools active within the span.","parameters":[{"description":"Time window for timeline + tool-list membership","in":"query","name":"window","schema":{"enum":["24h","7d","all"],"type":"string"}},{"description":"Filter to one server","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter to one tool","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter to tools with activity of this status","in":"query","name":"status","schema":{"enum":["success","error","blocked","rejected"],"type":"string"}},{"description":"Top-N tools by sort key; remainder folded into 'other' (default 20)","in":"query","name":"top","schema":{"type":"integer"}},{"description":"Ranking key for the per-tool list","in":"query","name":"sort","schema":{"enum":["calls","resp_bytes","error_rate","p95"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get usage statistics aggregate","tags":["Activity"]}},"/api/v1/activity/{id}":{"get":{"description":"Returns full details for a single activity record","parameters":[{"description":"Activity record ID (ULID)","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Not Found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity record details","tags":["Activity"]}},"/api/v1/annotations/coverage":{"get":{"description":"Reports how many upstream tools have MCP annotations vs don't, broken down by server","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Annotation coverage report"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get annotation coverage report","tags":["annotations"]}},"/api/v1/code/scripts":{"get":{"description":"List the stored scripts available to the code_execution tool. Scripts are ` + "`" + `\u003cname\u003e.js` + "`" + ` / ` + "`" + `\u003cname\u003e.ts` + "`" + ` files in the ` + "`" + `scripts/` + "`" + ` directory next to the active configuration file. Entries are advisory: ` + "`" + `ok` + "`" + ` scripts are invocable, ` + "`" + `ambiguous` + "`" + ` names have both extensions, and ` + "`" + `invalid` + "`" + ` ones report why (empty, oversized, unreadable, non-regular). Read-only — there is no write surface for stored scripts. Administrator-only (Spec 105 FR-012): an agent token, whatever its server scope, is refused with 403 — the listing is the enumeration the missing-script error withholds from a scoped caller.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Stored scripts and the directory they were read from"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot list stored scripts"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List stored code-execution scripts","tags":["code"]}},"/api/v1/config":{"get":{"description":"Retrieves the current MCPProxy configuration including all server definitions, global settings, and runtime parameters","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetConfigResponse"}}},"description":"Configuration retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read the configuration document"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get current configuration","tags":["config"]},"patch":{"description":"Deep-merges only the fields present in the request body onto the live in-memory configuration and routes the result through the existing apply pipeline (validation, change detection, disk persistence, hot-reload). Fields the client omits — including masked secrets such as ` + "`" + `api_key` + "`" + ` and secret request headers — are preserved verbatim. Nested objects are merged recursively; arrays and scalars replace wholesale.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Partial configuration with only the fields to change","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Configuration patch applied (inspect validation_errors for rejected values)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload or empty patch"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to read or apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update configuration","tags":["config"]}},"/api/v1/config/apply":{"post":{"description":"Applies a new MCPProxy configuration. Validates and persists the configuration to disk. Some changes apply immediately, while others may require a restart. Returns detailed information about applied changes and restart requirements.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to apply","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Configuration applied successfully with change details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Apply configuration","tags":["config"]}},"/api/v1/config/docker-isolation":{"patch":{"description":"Convenience endpoint to flip ` + "`" + `docker_isolation.enabled` + "`" + ` without resending the full config. Persists to disk via the existing config writer — the file watcher then hot-reloads the change. Returns the new state and whether a restart is required for existing connections to pick it up.","requestBody":{"content":{"application/json":{"schema":{"properties":{"enabled":{"type":"boolean"}},"type":"object"}}},"description":"New isolation state","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Isolation toggle applied"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Toggle global Docker isolation","tags":["config"]}},"/api/v1/config/validate":{"post":{"description":"Validates a provided MCPProxy configuration without applying it. Checks for syntax errors, invalid server definitions, conflicting settings, and other configuration issues.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to validate","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ValidateConfigResponse"}}},"description":"Configuration validation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Validation failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Validate configuration","tags":["config"]}},"/api/v1/connect":{"get":{"description":"Returns the connection status for all known MCP client applications.\nEach entry indicates whether the client config file exists and whether\nMCPProxy is currently registered in it.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"List of ClientStatus objects"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List client connection status","tags":["connect"]}},"/api/v1/connect/{client}":{"delete":{"description":"Remove the MCPProxy entry from the specified client's configuration file.\nCreates a backup of the existing config before modifying.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional parameters (server_name)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or entry not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disconnect MCPProxy from a client","tags":["connect"]},"get":{"description":"Resolves one client's status by reading its config file on demand.\nThis is the only Connect endpoint that opens a client config file, so\non macOS it is the sole place an App-Data privacy prompt may legitimately\nappear (scoped to this user action). Resolves access_state to\naccessible|absent|denied|malformed and populates remediation when denied.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ClientStatus"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get a single client's connection status (on-demand)","tags":["connect"]},"post":{"description":"Register MCPProxy as an MCP server in the specified client's configuration file.\nCreates a backup of the existing config before modifying.\nOptionally accepts precondition_token from a preview (Spec 091): when supplied,\nthe core rechecks the raw pre-write state and the entry it would write, and\nrefuses a drifted write with 409 before taking any backup. The 409 body's\naction discriminates the two conflict kinds: \"precondition_failed\" (stale\npreview — re-preview, do not retry) vs \"already_exists\" (entry present — pass\nforce=true). force=true never rescues a stale token.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional connection parameters (server_name, force, precondition_token)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectConflictResponse"}}},"description":"Conflict: action=already_exists (use force=true) or action=precondition_failed (preview is stale; re-preview)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Connect MCPProxy to a client","tags":["connect"]}},"/api/v1/connect/{client}/preview":{"get":{"description":"Returns the exact entry a subsequent connect would add to the client's\nconfig — target path, server key, entry name, and entry contents — WITHOUT\nmodifying the file or creating a backup (Spec 078 US1). The embedded API key\nis masked in the payload; contains_api_key flags that a credential is written.\nentry_exists distinguishes a create from an overwrite of a same-named entry.\nReads the config on demand to classify create-vs-overwrite, so on macOS this\nmay raise an App-Data privacy prompt; a denial returns 403 + remediation.\nSpec 091 adds three fields: existing_entry_summary (present only when\nentry_exists — a sanitized, non-secret projection of the entry being replaced:\nits name, type, endpoint with query/userinfo stripped, command, and header and\nenv NAMES, never values); precondition_token (always present — an opaque keyed\ndigest of the raw pre-write state and the pending entry, echoed back on POST\nconnect to detect drift); and connect_refusal (present when the write would\nrefuse regardless of intent, e.g. a non-create-capable client with no config —\ntreat its presence as \"Connect unavailable\").","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}},{"description":"Entry name to preview (defaults to mcpproxy); mirror the value passed to POST connect","in":"query","name":"server_name","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectPreview"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Preview the change a connect would make (no write)","tags":["connect"]}},"/api/v1/connect/{client}/undo":{"post":{"description":"Reverts the connect that produced the named backup (Spec 078 US3):\nrestores the client config byte-for-byte from that backup, or — when\nbackup_name is empty because the connect created the file — deletes the\ncreated file. backup_name is the bare filename of the backup the connect\nreturned (never a path); undo resolves the full path server-side inside\nthe client's own config directory, so a client value cannot escape it.\nRefuses with 409 when the config changed since the connect (undo never\nclobbers later edits; use DELETE /connect/{client} for a surgical entry\nremoval instead). Takes its own safety backup first; its path is returned\nas backup_path in the result.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.UndoConnectRequest"}}},"description":"Undo parameters (server_name, backup_name = the bare filename of the backup the preceding connect returned)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult (action restored|deleted)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (e.g. backup_name is a path, or not a backup of this client's config)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or backup no longer exists"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Config changed since connect; undo refused"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Undo a connect, restoring the pre-connect config","tags":["connect"]}},"/api/v1/diagnostics":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/docker/status":{"get":{"description":"Retrieve current Docker availability and recovery status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Docker status information"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get Docker status","tags":["docker"]}},"/api/v1/doctor":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/feedback":{"post":{"description":"Submit a bug report, feature request, or general feedback","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackRequest"}}},"description":"Feedback request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Bad Request"},"429":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"Submit feedback","tags":["feedback"]}},"/api/v1/index/search":{"get":{"description":"Search across all upstream MCP server tools using BM25 keyword search","parameters":[{"description":"Search query","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"description":"Maximum number of results","in":"query","name":"limit","schema":{"default":10,"maximum":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchToolsResponse"}}},"description":"Search results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing query parameter)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search for tools","tags":["tools"]}},"/api/v1/info":{"get":{"description":"Get essential server metadata including version, web UI URL, endpoint addresses, and update availability\nweb_ui_url carries the ?apikey= credential ONLY for an authenticated admin; a scoped agent token receives the bare URL\nThis endpoint is designed for tray-core communication and version checking\nUse refresh=true query parameter to force an immediate update check against GitHub\nThe launched_by field reports durable launch provenance (\"tray\", \"installer\", or \"\" for user-launched/unknown)","parameters":[{"description":"Force immediate update check against GitHub","in":"query","name":"refresh","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"Server information with optional update info"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server information","tags":["status"]}},"/api/v1/onboarding/mark":{"post":{"description":"Updates wizard engagement and per-step status. Once engaged is\ntrue, the wizard does not auto-show again, even if state regresses.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.OnboardingMarkRequest"}}},"description":"Mark request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Updated OnboardingStateResponse"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read onboarding state"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Mark onboarding wizard state (Spec 046)","tags":["onboarding"]}},"/api/v1/onboarding/state":{"get":{"description":"Returns the wizard engagement record alongside live predicates\n(whether any client is connected, whether any server is configured),\nplus a derived ShouldShowWizard flag the frontend can rely on.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"OnboardingStateResponse"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read onboarding state"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get onboarding wizard state and predicates (Spec 046)","tags":["onboarding"]}},"/api/v1/preflight":{"post":{"description":"Deterministic, side-effect-free availability check for a caller-supplied list of tool IDs (Spec 098). Performs zero upstream calls and mutates no runtime state. HTTP status reports whether the CHECK executed: a fully blocked set is still 200, with the availability verdict in the body. Every executed preflight writes an activity record before the response is returned.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.PreflightRequest"}}},"description":"Tool IDs (1-100 before dedup), optional profile, annotation policy filters and wait budget","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"Preflight verdict and per-tool results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Validation error (malformed, oversized, doubled or unknown-field body; empty or oversized tool list; conflicting duplicate pins; unknown profile; wait_ms out of range)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Missing or invalid credentials"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Runtime unavailable, evaluator infrastructure read failure, or the activity record could not be persisted"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Preflight required tools","tags":["tools"]}},"/api/v1/profiles":{"get":{"description":"List all configured profiles with their effective servers and indexed tool count (Profiles v2). A profile scopes tool discovery and calls to a named subset of upstream servers.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Profile list"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Configuration unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List configured profiles","tags":["profiles"]}},"/api/v1/profiles/active":{"get":{"description":"Get the server-level default active profile used by UI surfaces (Web UI / tray). Empty string means \"all servers\". Note: within a live MCP session, the set_profile tool selection takes precedence over this default.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get the default active profile","tags":["profiles"]},"put":{"description":"Set the server-level default active profile for UI surfaces. The slug must match a configured profile; pass an empty string to clear. This does not affect live MCP sessions, which use the set_profile tool.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.SetActiveProfileRequest"}}},"description":"Profile slug to activate (empty clears)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid request body"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot change the active profile)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Set the default active profile","tags":["profiles"]}},"/api/v1/registries":{"get":{"description":"Retrieves list of all MCP server registries that can be browsed for discovering and installing new upstream servers. Includes registry metadata, server counts, and API endpoints.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetRegistriesResponse"}}},"description":"Registries retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to list registries"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List available MCP server registries","tags":["registries"]},"post":{"description":"Adds a generic modelcontextprotocol/registry v0.1 https endpoint as a custom registry (MCP-866). The source is always tagged custom/unverified, so every server discovered through it lands quarantined and can never skip quarantine.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddRegistrySourceRequest"}}},"description":"Registry source (https url + optional protocol/id/name)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source added"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/contracts.ErrorResponse"},{"$ref":"#/components/schemas/contracts.ErrorResponse"}]}}},"description":"Forbidden (agent tokens cannot mutate registries)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin | duplicate_registry"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a user-supplied registry source","tags":["registries"]}},"/api/v1/registries/{id}":{"delete":{"description":"Removes a custom/unverified registry previously added via add-source (MCP-1057). Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source removed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove a user-added custom registry source","tags":["registries"]},"put":{"description":"Updates a custom registry previously added via add-source (MCP-1072): name, url, servers-url. Empty fields are left unchanged. Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found; a non-https url yields invalid_registry_url. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.EditRegistrySourceRequest"}}},"description":"Fields to update (name/url/servers_url; empty = unchanged)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required | invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Edit a user-added custom registry source","tags":["registries"]}},"/api/v1/registries/{id}/refresh":{"post":{"description":"Invalidates the cached server lists for a registry so the next search re-fetches fresh data from the source (spec 070 FR-007). Returns how many cache entries were dropped.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.RefreshRegistryResponse"}}},"description":"Registry cache refreshed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh registry cache"}},"summary":"Refresh a registry's cached server list","tags":["registries"]}},"/api/v1/registries/{id}/servers":{"get":{"description":"Searches for MCP servers within a specific registry by keyword or tag. Returns server metadata including installation commands, source code URLs, and npm package information for easy discovery and installation.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Search query keyword","in":"query","name":"q","schema":{"type":"string"}},{"description":"Filter by tag","in":"query","name":"tag","schema":{"type":"string"}},{"description":"Maximum number of results (default 10)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchRegistryServersResponse"}}},"description":"Servers retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to search servers"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search MCP servers in a registry","tags":["registries"]}},"/api/v1/registries/{id}/servers/{serverId}/add":{"post":{"description":"Resolves a registry server reference server-side, re-derives a validated config, and persists it quarantined (spec 070 keystone). The client never sends a config blob — command/args/url and the quarantine flag are derived from the registry entry, not the request.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Server ID within the registry","in":"path","name":"serverId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddFromRegistryRequest"}}},"description":"Optional overrides (name, env, enabled)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server added (quarantined)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"no_install_info | missing_required_input | duplicate_name"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot add servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found | server_not_found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add an upstream server from a registry reference","tags":["registries"]}},"/api/v1/routing":{"get":{"description":"Get the current routing mode and available MCP endpoints.\nrouting_mode is what /mcp is actually serving; pending_routing_mode carries a\nrestart-pending value persisted on disk (empty when there is none).\ntool_response_mode and direct_tool_response_mode report the two serialization axes, resolved.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Routing mode information"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get routing mode information","tags":["status"]}},"/api/v1/secrets":{"post":{"description":"Stores a secret value in the operating system's secure keyring. The secret can then be referenced in configuration using ${keyring:secret-name} syntax. Automatically notifies runtime to restart affected servers.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret stored successfully with reference syntax"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload, missing name/value, or unsupported type"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver not available or failed to store secret"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Store a secret in OS keyring","tags":["secrets"]}},"/api/v1/secrets/{name}":{"delete":{"description":"Deletes a secret from the operating system's secure keyring. Automatically notifies runtime to restart affected servers. Only keyring type is supported for security.","parameters":[{"description":"Name of the secret to delete","in":"path","name":"name","required":true,"schema":{"type":"string"}},{"description":"Secret type (only 'keyring' supported, defaults to 'keyring')","in":"query","name":"type","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Missing secret name or unsupported type"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver not available or failed to delete secret"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Delete a secret from OS keyring","tags":["secrets"]}},"/api/v1/servers":{"get":{"description":"Get a list of all configured upstream MCP servers with their connection status and statistics","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServersResponse"}}},"description":"Server list with statistics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List all upstream MCP servers","tags":["servers"]},"post":{"description":"Add a new MCP upstream server to the configuration. New servers are quarantined by default for security. Isolation: ` + "`" + `isolation.enabled` + "`" + ` is READ-ONLY (it reports the effective state on reads) and is rejected with 400; set the per-server override via ` + "`" + `isolation.enabled_override` + "`" + ` (true | false | null to clear, omit to leave unchanged). An unrecognized ` + "`" + `isolation.mode_override` + "`" + ` is rejected with 400.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.AddServerRequest"}}},"description":"Server configuration","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server added successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid configuration"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Conflict - server with this name already exists"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a new upstream server","tags":["servers"]}},"/api/v1/servers/disable_all":{"post":{"description":"Disable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk disable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable all servers","tags":["servers"]}},"/api/v1/servers/enable_all":{"post":{"description":"Enable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk enable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable all servers","tags":["servers"]}},"/api/v1/servers/import":{"post":{"description":"Import MCP server configurations from a Claude Desktop, Claude Code, Cursor IDE, Codex CLI, or Gemini CLI configuration file","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}},{"description":"Force format (claude-desktop, claude-code, cursor, codex, gemini)","in":"query","name":"format","schema":{"type":"string"}},{"description":"Comma-separated list of server names to import","in":"query","name":"server_names","schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"file"}}},"description":"Configuration file to import","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid file or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from uploaded configuration file","tags":["servers"]}},"/api/v1/servers/import/json":{"post":{"description":"Import MCP server configurations from raw JSON or TOML content (useful for pasting configurations)","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportRequest"}}},"description":"Import request with content","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid content or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from JSON/TOML content","tags":["servers"]}},"/api/v1/servers/import/path":{"post":{"description":"Import MCP server configurations by reading a file from the server's filesystem","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportFromPathRequest"}}},"description":"Import request with file path","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid path or format"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"File not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from a file path","tags":["servers"]}},"/api/v1/servers/import/paths":{"get":{"description":"Returns well-known configuration file paths for supported formats with existence check","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPathsResponse"}}},"description":"Canonical config paths"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get canonical config file paths","tags":["servers"]}},"/api/v1/servers/reconnect":{"post":{"description":"Force reconnection to all upstream MCP servers","parameters":[{"description":"Reason for reconnection","in":"query","name":"reason","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"All servers reconnected successfully"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Reconnect all servers","tags":["servers"]}},"/api/v1/servers/restart_all":{"post":{"description":"Restart all configured upstream MCP servers sequentially with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk restart results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart all servers","tags":["servers"]}},"/api/v1/servers/{id}":{"delete":{"description":"Remove an MCP upstream server from the configuration. This stops the server if running and removes it from config.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server removed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove an upstream server","tags":["servers"]},"patch":{"description":"Update specific fields of an existing upstream MCP server configuration. Isolation: ` + "`" + `isolation.enabled` + "`" + ` is READ-ONLY (it reports the effective state on reads) and is rejected with 400; set the per-server override via ` + "`" + `isolation.enabled_override` + "`" + ` (true | false | null to clear, omit to leave unchanged). An unrecognized ` + "`" + `isolation.mode_override` + "`" + ` is rejected with 400.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.AddServerRequest"}}},"description":"Fields to update (all optional)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server updated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - no fields or invalid body"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/config-to-secret":{"post":{"description":"Atomically reads the real value from the server config, stores it in the OS keyring, and rewrites the config field to ` + "`" + `${keyring:\u003cname\u003e}` + "`" + `. Unblocks the UI's Convert-to-secret affordance for values the API redacts on the read path.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret stored, config updated with reference"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad scope/key/secret_name, or value is already a reference / empty"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server or key not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver or config update failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Convert a header / env value to a keyring secret","tags":["servers"]}},"/api/v1/servers/{id}/disable":{"post":{"description":"Disable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server disabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/discover-tools":{"post":{"description":"Manually trigger tool discovery and indexing for a specific upstream MCP server. This forces an immediate refresh of the server's tool cache.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool discovery triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot discover tools)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to discover tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Discover tools for a specific server","tags":["servers"]}},"/api/v1/servers/{id}/enable":{"post":{"description":"Enable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server enabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/login":{"post":{"description":"Initiate OAuth authentication flow for a specific upstream MCP server. Returns structured OAuth start response with correlation ID for tracking.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthStartResponse"}}},"description":"OAuth login initiated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthFlowError"}}},"description":"OAuth error (client_id required, DCR failed, etc.)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Trigger OAuth login for server","tags":["servers"]}},"/api/v1/servers/{id}/logout":{"post":{"description":"Clear OAuth authentication token and disconnect a specific upstream MCP server. The server will need to re-authenticate before tools can be used again.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"OAuth logout completed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled or read-only mode)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Clear OAuth token and disconnect server","tags":["servers"]}},"/api/v1/servers/{id}/logs":{"get":{"description":"Retrieve log entries for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Number of log lines to retrieve","in":"query","name":"tail","schema":{"default":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerLogsResponse"}}},"description":"Server logs retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server logs","tags":["servers"]}},"/api/v1/servers/{id}/quarantine":{"post":{"description":"Place a specific upstream MCP server in quarantine to prevent tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server quarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Quarantine a server","tags":["servers"]}},"/api/v1/servers/{id}/refresh":{"post":{"description":"Re-discover and re-index a specific upstream MCP server's tools without changing any security state. Alias of discover-tools, named for the upstream_servers 'refresh' operation; use it to make just-approved tools searchable immediately.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool refresh triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot refresh)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Refresh a server's tools","tags":["servers"]}},"/api/v1/servers/{id}/restart":{"post":{"description":"Restart the connection to a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server restarted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/tool-calls":{"get":{"description":"Retrieves tool call history filtered by upstream server ID. Returns recent tool executions for the specified server including timestamps, arguments, results, and errors. Useful for server-specific debugging and monitoring.","parameters":[{"description":"Upstream server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Maximum number of records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolCallsResponse"}}},"description":"Server tool calls retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get server tool calls"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call history for specific server","tags":["tool-calls"]}},"/api/v1/servers/{id}/tools":{"get":{"description":"Retrieve all available tools for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolsResponse"}}},"description":"Server tools retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/block":{"post":{"description":"Atomically approves AND disables the given tools (or all pending/changed tools when block_all=true) for a server. The approve and disable land in a single write per tool, so a tool is never left in the approved+enabled state. The \"blocked\" field counts tools actually blocked.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Block result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Block (approve+disable) tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/disable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/enable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/unquarantine":{"post":{"description":"Remove a specific upstream MCP server from quarantine to allow tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server unquarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Unquarantine a server","tags":["servers"]}},"/api/v1/sessions":{"get":{"description":"Retrieves paginated list of active and recent MCP client sessions. Each session represents a connection from an MCP client to MCPProxy, tracking initialization time, tool calls, and connection status.","parameters":[{"description":"Maximum number of sessions to return (1-100, default 10)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Number of sessions to skip for pagination (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Filter by session status","in":"query","name":"status","schema":{"enum":["active","closed"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionsResponse"}}},"description":"Sessions retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid status filter"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read MCP session history"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get sessions"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get active MCP sessions","tags":["sessions"]}},"/api/v1/sessions/{id}":{"get":{"description":"Retrieves detailed information about a specific MCP client session including initialization parameters, connection status, tool call count, and activity timestamps.","parameters":[{"description":"Session ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionDetailResponse"}}},"description":"Session details retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Session ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read MCP session history"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Session not found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get MCP session details by ID","tags":["sessions"]}},"/api/v1/stats/tokens":{"get":{"description":"Retrieve token savings statistics across all servers and sessions","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Token statistics"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read deployment-wide token statistics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get token savings statistics","tags":["stats"]}},"/api/v1/status":{"get":{"description":"Get comprehensive server status including running state, listen address, upstream statistics, and timestamp","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server status information"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server status","tags":["status"]}},"/api/v1/telemetry/payload":{"get":{"description":"Render the exact JSON heartbeat payload that mcpproxy would next send to the telemetry endpoint, without making a network call. Counters in the payload reflect the current in-memory state. Spec 042.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Telemetry heartbeat payload"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read the deployment telemetry payload"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Telemetry service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Preview next telemetry heartbeat payload","tags":["telemetry"]}},"/api/v1/telemetry/update-failure":{"post":{"description":"Records one terminal update-session failure, identified only by its\nstage (appcast, download, install, other). The body carries no error\ntext, URL, or version — the stage is the only value transmitted.\nReturns 204 both when the occurrence was durably persisted and when\ntelemetry is inactive at event time (config opt-out, environment\nopt-out, CI, or dev build), in which case nothing is recorded.\nCallers cannot and need not distinguish the two.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.UpdateFailureRequest"}}},"description":"Update failure stage","required":true},"responses":{"204":{"description":"Accepted (recorded, or a deliberate no-op while telemetry is inactive)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Malformed body, unknown field, trailing value, or stage outside the closed set"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Persistence failure"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Record a desktop auto-update failure occurrence (Spec 095)","tags":["telemetry"]}},"/api/v1/tool-calls":{"get":{"description":"Retrieves paginated tool call history across all upstream servers or filtered by session ID. Includes execution timestamps, arguments, results, and error information for debugging and auditing.","parameters":[{"description":"Maximum number of records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Number of records to skip for pagination (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Filter tool calls by MCP session ID","in":"query","name":"session_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetToolCallsResponse"}}},"description":"Tool calls retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get tool calls"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call history","tags":["tool-calls"]}},"/api/v1/tool-calls/{id}":{"get":{"description":"Retrieves detailed information about a specific tool call execution including full request arguments, response data, execution time, and any errors encountered.","parameters":[{"description":"Tool call ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetToolCallDetailResponse"}}},"description":"Tool call details retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call not found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call details by ID","tags":["tool-calls"]}},"/api/v1/tool-calls/{id}/replay":{"post":{"description":"Re-executes a previous tool call with optional modified arguments. Useful for debugging and testing tool behavior with different inputs. Creates a new tool call record linked to the original.","parameters":[{"description":"Original tool call ID to replay","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ReplayToolCallRequest"}}},"description":"Optional modified arguments for replay"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ReplayToolCallResponse"}}},"description":"Tool call replayed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call ID required or invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Shed by a concurrency limit (Retry-After header carries the wait hint)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to replay tool call"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Replay a tool call","tags":["tool-calls"]}},"/api/v1/tools":{"get":{"description":"Consolidated, read-only listing of all tools from every configured server (including disabled servers and disabled/config-denied tools), enriched with approval state and 30-day usage. Backs the global Tools page and the CLI global ` + "`" + `tools list` + "`" + ` (spec 050, issue #437).","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GlobalToolsResponse"}}},"description":"All tools across all servers"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Could not enumerate servers"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List every tool across all servers","tags":["tools"]}},"/api/v1/tools/call":{"post":{"description":"Execute a tool on an upstream MCP server (wrapper around MCP tool calls)","requestBody":{"content":{"application/json":{"schema":{"properties":{"arguments":{"type":"object"},"tool_name":{"type":"string"}},"type":"object"}}},"description":"Tool call request with tool name and arguments","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Tool call result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (invalid payload or missing tool name)"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Shed by a concurrency limit (Retry-After header carries the wait hint)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error or tool execution failure"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Call a tool","tags":["tools"]}},"/healthz":{"get":{"description":"Get comprehensive health status including all component health (Kubernetes-compatible liveness probe)","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.HealthResponse"}}},"description":"Service is healthy"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.HealthResponse"}}},"description":"Service is unhealthy"}},"summary":"Get health status","tags":["health"]}},"/readyz":{"get":{"description":"Get readiness status including all component readiness checks (Kubernetes-compatible readiness probe)","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.ReadinessResponse"}}},"description":"Service is ready"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.ReadinessResponse"}}},"description":"Service is not ready"}},"summary":"Get readiness status","tags":["health"]}}},
diff --git a/oas/swagger.yaml b/oas/swagger.yaml
index 45bc3a59d..fcd88522b 100644
--- a/oas/swagger.yaml
+++ b/oas/swagger.yaml
@@ -2788,6 +2788,19 @@ components:
         success:
           type: boolean
       type: object
+    contracts.Tier:
+      description: |-
+        Tier is computed by AnnotationTier (Spec 109 FR-028/X11) from
+        Annotations — read|write|destructive|unannotated. Set by every producer
+        of a Tool (enrichServerTools, the global tools handler); never left for
+        a consuming surface to compute.
+      type: string
+      x-enum-varnames:
+      - TierRead
+      - TierWrite
+      - TierDestructive
+      - TierUnannotated
+      - TierUnknown
     contracts.TokenMetrics:
       description: Token usage metrics (nil for older records)
       properties:
@@ -2873,6 +2886,8 @@ components:
           type: object
         server_name:
           type: string
+        tier:
+          $ref: '#/components/schemas/contracts.Tier'
         usage:
           type: integer
       type: object

From 3fa2854713273a93b78ae6222e22a41b6ea40ff3 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 25 Sep 2026 21:26:16 +0300
Subject: [PATCH 05/27] fix: address review round 1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified findings against 109-a-quick-wins (PR-a of Spec 109).

FIXED:

- z-index: --z-header/--z-sidebar shipped inverted, so the sticky
  header painted over the open mobile drawer sidebar instead of the
  other way around (the same class of stacking bug this scale exists
  to prevent, on the header/sidebar pair instead of sidebar/modal).
  Swapped the token values, updated the doc comment and
  z-index-scale.spec.ts's ordering assertion.

- useDialogOpen: never listened for the native `close` event a
  showModal()-opened <dialog> fires on Escape, so the driving Vue
  state desynced from the DOM the first time a user hit Escape on
  Repositories.vue's three dialogs, UserTokens/UserServers/
  UserActivity's dialogs, OnboardingWizard or ConnectModal — the
  dialog stayed closed forever after that (no reopen). Added an
  `onClose` hook plus a `close` listener guarded against looping back
  on our own close() calls, wired every affected consumer's own
  close/reset function through it. AddServerModal/AddSecretModal
  (already safe via useModalA11y's capture-phase Escape handler) get
  the same wiring for defense in depth. New test:
  use-dialog-open-native-close.spec.ts.

- Search tier: GET /index/search always reported tier=unannotated
  regardless of a tool's real annotations, disagreeing with the same
  tool's tier on GET /servers/{id}/tools. The reported cause (a missing
  "annotations" key in server.searchResultsToMaps's tool map) was one
  level above the real one: the Bleve ToolDocument never stored
  annotations at all, so a search hit could not carry them no matter
  what the map-shaping code did. Added a stored (not indexed)
  annotations_json field to the Bleve schema, round-tripped through
  toolDocument/readToolMetadata, requested it in the shared search
  Fields list, and now surface it in searchResultsToMaps. New tests:
  bleve_annotations_test.go, search_tools_tier_test.go.

- Tools.vue: selectStatCard's toggle-to-total branch dropped the
  filterApproval reset that existed before this PR removed the old
  "pending" stat card. Total is the row's other "reset" gesture
  (clearFilters resets both filters too); restored it. New test:
  tools-total-card-resets-approval.spec.ts.

- macOS ServerBrowseView: the "Added checkmark Open" flow keyed
  addedServers on the registry catalog's display name, but the backend
  can assign a different name (empty name falls back to the entry id,
  a conflict gets de-duplicated) and echoes it in the response body,
  which AddServerResult discarded entirely. Now decoded and used,
  matching the Web UI's `result.server?.name || server.name`. New
  test: APIClientAddServerFromRegistryTests.swift.

- macOS ToolsView: the tier badge rendered nothing at all for a nil
  tier (an older core not yet sending the field), while the Web UI
  always renders one, defaulting to "Unannotated". Added
  ToolRow.displayTier and used it unconditionally. New tests in
  ToolLabelsTests.swift.

- cmd/mcpproxy/registry_cmd.go: registryAddErrorOutput's doc comment
  was glued to registryAddMessage by a missing blank line, hiding it
  from godoc. Reordered; cosmetic only.

REJECTED (false positive for this PR):

- scripts/test-api-e2e.sh's blanket `pkill -f "mcpproxy.*serve"` /
  `pkill -f "launcher-server.*--port 39933"` in its cleanup trap is a
  real, pre-existing operational risk (can kill another worktree's or
  the user's own running instance), but git blame shows these lines
  predate every commit in this PR and none of this PR's three commits
  touch the file. No tasks.md for Spec 108/109 exists in this repo to
  substantiate the finding's claim that removing them was a task this
  PR was itself scoped to do. Left alone here rather than fixed blind
  without the actual spec to guide the exact requirement (own-PID
  tracking vs. a decoy-process proof) on a script every worktree's E2E
  run depends on; flagged instead as a follow-up task.

DEFERRED (genuine, not implemented — infra, not a rejection):

- e2e/web-ui-sweep/visual-a11y-sweep.spec.ts has no elementFromPoint
  assertion proving the z-index fix above holds in a real browser.
  Adding one needs the real launcher (scripts/run-web-smoke.sh) and a
  live Playwright run to confirm it actually catches the regression
  rather than being vacuously true — this fix-and-verify pass could
  not do that locally, so an unverified test was not committed;
  flagged as a follow-up task instead.

Verification: go build ./... and -tags server both clean; go vet and
gofmt clean on touched files; go test -race on internal/index,
internal/server (CI skip regex, both bare and -tags server variants),
internal/httpapi, internal/contracts, cmd/mcpproxy, internal/config,
internal/oauth, internal/storage, internal/serveredition/* all green;
golangci-lint v2 (bare and --build-tags server) on touched packages
shows only 6 pre-existing staticcheck issues in test files this PR
never touched; frontend npm ci + npm run build (vue-tsc + vite) +
npx vitest run all green (147 files / 1393 tests, package-lock.json
unchanged); swift test full suite green except one known
environment-caused failure (AppLifecycleTests, caused by a real
~/.mcpproxy/tray-lifecycle.jsonl already present on this shared
machine from outside this session — unrelated to any file this PR
touches, reproduces identically before any of these changes).

Not pushed; branch left detached per instructions.
---
 cmd/mcpproxy/registry_cmd.go                  |   4 +-
 frontend/src/assets/z-index.css               |  15 ++-
 frontend/src/components/AddSecretModal.vue    |   2 +-
 frontend/src/components/AddServerModal.vue    |   2 +-
 frontend/src/components/ConnectModal.vue      |   2 +-
 frontend/src/components/OnboardingWizard.vue  |   2 +-
 frontend/src/composables/useDialogOpen.ts     |  35 +++++-
 frontend/src/views/Repositories.vue           |   6 +-
 frontend/src/views/Tools.vue                  |   5 +
 frontend/src/views/teams/UserActivity.vue     |   2 +-
 frontend/src/views/teams/UserServers.vue      |   4 +-
 frontend/src/views/teams/UserTokens.vue       |   2 +-
 .../tools-total-card-resets-approval.spec.ts  |  55 ++++++++++
 .../unit/use-dialog-open-native-close.spec.ts | 101 ++++++++++++++++++
 frontend/tests/unit/z-index-scale.spec.ts     |  15 ++-
 internal/index/bleve.go                       |  45 +++++++-
 internal/index/bleve_annotations_test.go      |  85 +++++++++++++++
 internal/server/search_tools_tier_test.go     |  71 ++++++++++++
 internal/server/server.go                     |   8 ++
 .../MCPProxy/MCPProxy/API/APIClient.swift     |   5 +-
 .../MCPProxy/API/RegistryModels.swift         |  26 ++++-
 .../MCPProxy/Views/ServerBrowseView.swift     |   8 +-
 .../MCPProxy/MCPProxy/Views/ToolsView.swift   |  19 ++--
 .../APIClientAddServerFromRegistryTests.swift |  55 ++++++++++
 .../MCPProxyTests/ToolLabelsTests.swift       |  18 ++++
 25 files changed, 553 insertions(+), 39 deletions(-)
 create mode 100644 frontend/tests/unit/tools-total-card-resets-approval.spec.ts
 create mode 100644 frontend/tests/unit/use-dialog-open-native-close.spec.ts
 create mode 100644 internal/index/bleve_annotations_test.go
 create mode 100644 internal/server/search_tools_tier_test.go
 create mode 100644 native/macos/MCPProxy/MCPProxyTests/APIClientAddServerFromRegistryTests.swift

diff --git a/cmd/mcpproxy/registry_cmd.go b/cmd/mcpproxy/registry_cmd.go
index ce53d453a..66df6b0da 100644
--- a/cmd/mcpproxy/registry_cmd.go
+++ b/cmd/mcpproxy/registry_cmd.go
@@ -478,8 +478,6 @@ inputs, supply them with --env KEY=VALUE.`,
 	return cmd
 }
 
-// registryAddErrorOutput maps a *cliclient.RegistryAddError to a structured CLI
-// error. For missing_required_input it names the exact --env keys to supply.
 // registryAddMessage formats the CLI's success confirmation after adding a
 // server from a registry (Spec 109 FR-063): "Added <name> to MCPProxy
 // (quarantined for review)" — the same wording the Web/macOS "Add to
@@ -492,6 +490,8 @@ func registryAddMessage(name string, quarantined bool) string {
 	return msg
 }
 
+// registryAddErrorOutput maps a *cliclient.RegistryAddError to a structured CLI
+// error. For missing_required_input it names the exact --env keys to supply.
 func registryAddErrorOutput(err error) error {
 	var addErr *cliclient.RegistryAddError
 	if !errors.As(err, &addErr) {
diff --git a/frontend/src/assets/z-index.css b/frontend/src/assets/z-index.css
index 1f02f1487..99b2b97e8 100644
--- a/frontend/src/assets/z-index.css
+++ b/frontend/src/assets/z-index.css
@@ -2,7 +2,16 @@
  * Spec 109 FR-055 (navigation-map.md): one z-index scale, defined in one
  * place, so no sidebar/header element can ever paint over a modal (audit H4).
  *
- * sidebar < header < dropdown < modal < toast
+ * header < sidebar < dropdown < modal < toast
+ *
+ * Sidebar outranks header, not the other way around: `SidebarNav`'s
+ * `.drawer-side` is a `position: fixed` sibling of `.drawer-content` (which
+ * holds the sticky `TopHeader`), and below the `lg` drawer breakpoint it is
+ * a full-screen overlay that must paint OVER the header when it opens. A
+ * review round on this file's first version had `--z-header` above
+ * `--z-sidebar`, which put the sticky header back on top of the open mobile
+ * drawer — the same class of bug this scale exists to prevent, just on the
+ * other pair of elements.
  *
  * Modals themselves should render in the browser's top layer via
  * `<dialog>.showModal()` rather than relying on this scale (the top layer
@@ -11,8 +20,8 @@
  * sit above the header/sidebar but below a real modal.
  */
 :root {
-  --z-sidebar: 30;
-  --z-header: 40;
+  --z-header: 30;
+  --z-sidebar: 40;
   --z-dropdown: 50;
   --z-modal: 60;
   --z-toast: 70;
diff --git a/frontend/src/components/AddSecretModal.vue b/frontend/src/components/AddSecretModal.vue
index 239638480..d741c2f69 100644
--- a/frontend/src/components/AddSecretModal.vue
+++ b/frontend/src/components/AddSecretModal.vue
@@ -117,7 +117,7 @@ const emit = defineEmits<Emits>()
 const { dialogRef } = useModalA11y(() => props.show, () => handleClose())
 // Spec 109 FR-055: the <dialog> itself opens via showModal() (top layer),
 // separate from dialogRef above (the inner .modal-box, used for focus trap).
-const { dialogEl: nativeDialogEl } = useDialogOpen(() => props.show)
+const { dialogEl: nativeDialogEl } = useDialogOpen(() => props.show, () => handleClose())
 
 const systemStore = useSystemStore()
 
diff --git a/frontend/src/components/AddServerModal.vue b/frontend/src/components/AddServerModal.vue
index 4993cb594..2d2f0527e 100644
--- a/frontend/src/components/AddServerModal.vue
+++ b/frontend/src/components/AddServerModal.vue
@@ -640,7 +640,7 @@ const emit = defineEmits<Emits>()
 const { dialogRef } = useModalA11y(() => props.show, () => handleClose())
 // Spec 109 FR-055: the <dialog> itself opens via showModal() (top layer),
 // separate from dialogRef above (the inner .modal-box, used for focus trap).
-const { dialogEl: nativeDialogEl } = useDialogOpen(() => props.show)
+const { dialogEl: nativeDialogEl } = useDialogOpen(() => props.show, () => handleClose())
 
 const serversStore = useServersStore()
 const systemStore = useSystemStore()
diff --git a/frontend/src/components/ConnectModal.vue b/frontend/src/components/ConnectModal.vue
index d029c0182..47af95d87 100644
--- a/frontend/src/components/ConnectModal.vue
+++ b/frontend/src/components/ConnectModal.vue
@@ -456,7 +456,7 @@ interface Emits {
 
 const props = defineProps<Props>()
 const emit = defineEmits<Emits>()
-const { dialogEl } = useDialogOpen(() => props.show)
+const { dialogEl } = useDialogOpen(() => props.show, () => close())
 const systemStore = useSystemStore()
 const onboarding = useOnboardingStore()
 
diff --git a/frontend/src/components/OnboardingWizard.vue b/frontend/src/components/OnboardingWizard.vue
index bc7a70e87..0792c12da 100644
--- a/frontend/src/components/OnboardingWizard.vue
+++ b/frontend/src/components/OnboardingWizard.vue
@@ -652,7 +652,7 @@ interface Emits {
 
 const props = defineProps<Props>()
 const emit = defineEmits<Emits>()
-const { dialogEl } = useDialogOpen(() => props.show)
+const { dialogEl } = useDialogOpen(() => props.show, () => dismiss())
 
 const onboarding = useOnboardingStore()
 const systemStore = useSystemStore()
diff --git a/frontend/src/composables/useDialogOpen.ts b/frontend/src/composables/useDialogOpen.ts
index 1cf690eaf..93cc8d2bf 100644
--- a/frontend/src/composables/useDialogOpen.ts
+++ b/frontend/src/composables/useDialogOpen.ts
@@ -19,8 +19,20 @@ import { onBeforeUnmount, ref, watch, type Ref } from 'vue'
  * `open` attribute directly — the previous behaviour — keeping every existing
  * unit test that renders these dialogs working unchanged. Real browsers all
  * support `<dialog>` natively.
+ *
+ * A real `showModal()`-opened dialog also closes itself natively — Escape,
+ * or a `<form method="dialog">` submit — without anything in Vue-land asking
+ * it to. Left unhandled, that desyncs the driving `isOpen()` source from the
+ * DOM: the dialog is closed but the source still reads `true`, so the next
+ * click that would reopen it sets the same value again, the `watch` below
+ * never fires, and `showModal()` never runs again — the dialog is bricked
+ * until a full reload (review round 1, H4 follow-up). `onClose` is the
+ * caller's hook to flip its own state back to closed when that happens; a
+ * `close` event the dialog fired *because we just called `close()`
+ * ourselves* is told apart by `isOpen()` already reading `false` by the time
+ * it fires, so it does not loop back into another call to `onClose`.
  */
-export function useDialogOpen(isOpen: () => boolean) {
+export function useDialogOpen(isOpen: () => boolean, onClose?: () => void) {
   const dialogEl: Ref<HTMLDialogElement | null> = ref(null)
 
   function sync(open: boolean) {
@@ -40,21 +52,34 @@ export function useDialogOpen(isOpen: () => boolean) {
     }
   }
 
+  function handleNativeClose() {
+    // isOpen() is still true only when nothing in Vue-land initiated this —
+    // a genuine native dismissal that Vue's state does not know about yet.
+    if (onClose && isOpen()) onClose()
+  }
+
   watch(isOpen, sync, { flush: 'post' })
 
   // Apply the initial state once the element has mounted (a plain immediate
-  // watcher would run before the template ref is bound).
+  // watcher would run before the template ref is bound), and (re)attach the
+  // native `close` listener to whichever element is currently bound.
   watch(
     dialogEl,
-    (el) => {
-      if (el) sync(isOpen())
+    (el, prevEl) => {
+      prevEl?.removeEventListener('close', handleNativeClose)
+      if (el) {
+        el.addEventListener('close', handleNativeClose)
+        sync(isOpen())
+      }
     },
     { flush: 'post' }
   )
 
   onBeforeUnmount(() => {
     const el = dialogEl.value
-    if (el?.open && typeof el.close === 'function') el.close()
+    if (!el) return
+    el.removeEventListener('close', handleNativeClose)
+    if (el.open && typeof el.close === 'function') el.close()
   })
 
   return { dialogEl }
diff --git a/frontend/src/views/Repositories.vue b/frontend/src/views/Repositories.vue
index 96bfc40e2..7291f1889 100644
--- a/frontend/src/views/Repositories.vue
+++ b/frontend/src/views/Repositories.vue
@@ -629,14 +629,14 @@ const addingRegistry = ref(false)
 const isEditMode = computed(() => editRegistryId.value !== null)
 // Spec 109 FR-055: <dialog>.showModal()/close(), not the `open` attribute —
 // keeps the top layer, so nothing (sidebar, header) can ever paint over it.
-const { dialogEl: addRegistryDialogEl } = useDialogOpen(() => showAddRegistry.value)
+const { dialogEl: addRegistryDialogEl } = useDialogOpen(() => showAddRegistry.value, () => closeAddRegistry())
 
 // Delete-custom-registry confirmation state (MCP-1073)
 const showDeleteRegistry = ref(false)
 const deleteRegistryTarget = ref<Registry | null>(null)
 const deleteRegistryError = ref<string | null>(null)
 const deletingRegistry = ref(false)
-const { dialogEl: deleteRegistryDialogEl } = useDialogOpen(() => showDeleteRegistry.value)
+const { dialogEl: deleteRegistryDialogEl } = useDialogOpen(() => showDeleteRegistry.value, () => closeDeleteRegistry())
 
 let searchDebounceTimer: ReturnType<typeof setTimeout> | null = null
 
@@ -708,7 +708,7 @@ function clearRegistries() {
 }
 
 const showPrompt = computed(() => promptServer.value !== null)
-const { dialogEl: promptDialogEl } = useDialogOpen(() => showPrompt.value)
+const { dialogEl: promptDialogEl } = useDialogOpen(() => showPrompt.value, () => closePrompt())
 
 // Add is blocked until every prompted input has a non-empty value.
 const promptComplete = computed(() =>
diff --git a/frontend/src/views/Tools.vue b/frontend/src/views/Tools.vue
index d3e8bc049..503aeaa17 100644
--- a/frontend/src/views/Tools.vue
+++ b/frontend/src/views/Tools.vue
@@ -792,8 +792,13 @@ const activeStatCard = computed<StatCard>(() => {
 
 function selectStatCard(card: StatCard) {
   // Toggle: re-clicking the active card resets to the unfiltered "total" view.
+  // Also clears filterApproval (review round 1): Total is the row's "reset"
+  // gesture (clearFilters clears both too), and leaving an approval filter
+  // in place after Total is clicked filtered the table with no visible way
+  // to tell from the stat row.
   if (card === 'total' || activeStatCard.value === card) {
     filterStatus.value = ''
+    filterApproval.value = ''
     return
   }
   filterStatus.value = card // 'enabled' | 'disabled'
diff --git a/frontend/src/views/teams/UserActivity.vue b/frontend/src/views/teams/UserActivity.vue
index 7c7f38547..10580f9f4 100644
--- a/frontend/src/views/teams/UserActivity.vue
+++ b/frontend/src/views/teams/UserActivity.vue
@@ -196,7 +196,7 @@ const totalCount = ref(0)
 const currentPage = ref(1)
 const pageSize = 25
 const selectedActivity = ref<Activity | null>(null)
-const { dialogEl: activityDialogEl } = useDialogOpen(() => selectedActivity.value !== null)
+const { dialogEl: activityDialogEl } = useDialogOpen(() => selectedActivity.value !== null, () => { selectedActivity.value = null })
 const serverNames = ref<string[]>([])
 
 const filters = reactive({
diff --git a/frontend/src/views/teams/UserServers.vue b/frontend/src/views/teams/UserServers.vue
index 8863962cf..10e9f4d76 100644
--- a/frontend/src/views/teams/UserServers.vue
+++ b/frontend/src/views/teams/UserServers.vue
@@ -226,13 +226,13 @@ const loading = ref(true)
 const error = ref('')
 const allServers = ref<UserServer[]>([])
 const showAddModal = ref(false)
-const { dialogEl: addModalDialogEl } = useDialogOpen(() => showAddModal.value)
+const { dialogEl: addModalDialogEl } = useDialogOpen(() => showAddModal.value, () => closeAddModal())
 const adding = ref(false)
 const addError = ref('')
 const togglingServer = ref('')
 const removingServer = ref('')
 const serverToRemove = ref('')
-const { dialogEl: removeDialogEl } = useDialogOpen(() => serverToRemove.value !== '')
+const { dialogEl: removeDialogEl } = useDialogOpen(() => serverToRemove.value !== '', () => { serverToRemove.value = '' })
 
 const newServer = reactive({
   name: '',
diff --git a/frontend/src/views/teams/UserTokens.vue b/frontend/src/views/teams/UserTokens.vue
index a36912bf0..cb81c047c 100644
--- a/frontend/src/views/teams/UserTokens.vue
+++ b/frontend/src/views/teams/UserTokens.vue
@@ -303,7 +303,7 @@ const createError = ref('')
 const newTokenSecret = ref<string | null>(null)
 const copied = ref(false)
 const showCreateModal = ref(false)
-const { dialogEl: createDialogEl } = useDialogOpen(() => showCreateModal.value)
+const { dialogEl: createDialogEl } = useDialogOpen(() => showCreateModal.value, () => closeCreateDialog())
 const availableServers = ref<AvailableServer[]>([])
 
 const createForm = ref({
diff --git a/frontend/tests/unit/tools-total-card-resets-approval.spec.ts b/frontend/tests/unit/tools-total-card-resets-approval.spec.ts
new file mode 100644
index 000000000..ea7d03e44
--- /dev/null
+++ b/frontend/tests/unit/tools-total-card-resets-approval.spec.ts
@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import Tools from '@/views/Tools.vue'
+import api from '@/services/api'
+
+// Spec 109 PR-a review round 1 (medium): selectStatCard's toggle-to-total
+// branch used to clear both filterStatus AND filterApproval. The PR dropped
+// the filterApproval reset, so setting an Approval filter and then clicking
+// the Total stat card (the established "reset" gesture — see clearFilters,
+// which clears both) silently leaves the approval filter applied with no
+// visible way to tell from the stat row.
+
+vi.mock('@/services/api', () => ({
+  default: { getGlobalTools: vi.fn(), setToolEnabled: vi.fn() },
+}))
+
+const globalStubs = { CollapsibleHintsPanel: { template: '<div />' } }
+
+function mountView() {
+  return mount(Tools, { global: { plugins: [createPinia()], stubs: globalStubs } })
+}
+
+describe('Tools Total stat card resets the approval filter too (review round 1)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    ;(api.getGlobalTools as any).mockResolvedValue({
+      success: true,
+      data: {
+        stats: { total: 3, enabled: 3, disabled: 0, pending_approval: 2 },
+        tools: [
+          { name: 'new_tool', server_name: 's', approval_status: 'pending', enabled: true, description: '' },
+          { name: 'rugpull', server_name: 's', approval_status: 'changed', enabled: true, description: '' },
+          { name: 'fine', server_name: 's', approval_status: 'approved', enabled: true, description: '' },
+        ],
+      },
+    })
+  })
+
+  it('clears an active approval filter when the Total card is clicked', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    const select = wrapper.find('[data-test="filter-approval"]')
+    await select.setValue('pending')
+    await flushPromises()
+    expect(wrapper.findAll('[data-test="tool-row"]').length).toBe(1)
+
+    await wrapper.find('[data-test="stat-total"]').trigger('click')
+    await flushPromises()
+
+    expect((select.element as HTMLSelectElement).value).toBe('')
+    expect(wrapper.findAll('[data-test="tool-row"]').length).toBe(3)
+  })
+})
diff --git a/frontend/tests/unit/use-dialog-open-native-close.spec.ts b/frontend/tests/unit/use-dialog-open-native-close.spec.ts
new file mode 100644
index 000000000..8bd3f1961
--- /dev/null
+++ b/frontend/tests/unit/use-dialog-open-native-close.spec.ts
@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest'
+import { defineComponent, h, ref } from 'vue'
+import { mount, flushPromises } from '@vue/test-utils'
+import { useDialogOpen } from '@/composables/useDialogOpen'
+
+/**
+ * jsdom implements the `open` attribute reflection on <dialog> but not
+ * `showModal()`/`close()` (no layout, no top layer), so useDialogOpen falls
+ * back to toggling the `open` attribute directly in every other unit test —
+ * the real, browser-only code path (the one the H4 stacking fix depends on)
+ * is otherwise untested. These tests polyfill just enough of the native
+ * behaviour — `showModal()` sets `.open`, `close()` clears it and fires the
+ * `close` event synchronously, exactly like a real dialog dismissed via the
+ * Escape key — to exercise that path.
+ */
+function polyfillNativeDialog(el: HTMLDialogElement) {
+  el.showModal = function (this: HTMLDialogElement) {
+    this.open = true
+  }
+  el.close = function (this: HTMLDialogElement) {
+    if (!this.open) return
+    this.open = false
+    this.dispatchEvent(new Event('close'))
+  }
+}
+
+function harness() {
+  const show = ref(false)
+  const onCloseCalls = ref(0)
+
+  const Modal = defineComponent({
+    setup() {
+      const { dialogEl } = useDialogOpen(
+        () => show.value,
+        () => {
+          onCloseCalls.value++
+          show.value = false
+        }
+      )
+      return () =>
+        h('dialog', {
+          ref: (el: Element | null) => {
+            if (el) polyfillNativeDialog(el as HTMLDialogElement)
+            dialogEl.value = el as HTMLDialogElement | null
+          },
+        })
+    },
+  })
+
+  return { show, onCloseCalls, Modal }
+}
+
+describe('useDialogOpen native close sync (Spec 109 PR-a review round 1)', () => {
+  it('syncs external state back to closed when the dialog closes natively (Escape)', async () => {
+    const { show, onCloseCalls, Modal } = harness()
+    const wrapper = mount(Modal, { attachTo: document.body })
+    show.value = true
+    await flushPromises()
+    const el = wrapper.element as HTMLDialogElement
+    expect(el.open).toBe(true)
+
+    // Nothing in Vue-land triggered this — the browser closed the dialog on
+    // its own (Escape / native cancel), exactly as showModal() promises.
+    el.close()
+    await flushPromises()
+
+    expect(onCloseCalls.value).toBe(1)
+    expect(show.value).toBe(false)
+    wrapper.unmount()
+  })
+
+  it('does not stay bricked: reopens after a native close', async () => {
+    const { show, Modal } = harness()
+    const wrapper = mount(Modal, { attachTo: document.body })
+    show.value = true
+    await flushPromises()
+    const el = wrapper.element as HTMLDialogElement
+
+    el.close()
+    await flushPromises()
+    expect(show.value).toBe(false)
+
+    show.value = true
+    await flushPromises()
+    expect(el.open).toBe(true)
+    wrapper.unmount()
+  })
+
+  it('does not call onClose when the close was initiated from Vue state', async () => {
+    const { show, onCloseCalls, Modal } = harness()
+    const wrapper = mount(Modal, { attachTo: document.body })
+    show.value = true
+    await flushPromises()
+
+    show.value = false
+    await flushPromises()
+
+    expect(onCloseCalls.value).toBe(0)
+    wrapper.unmount()
+  })
+})
diff --git a/frontend/tests/unit/z-index-scale.spec.ts b/frontend/tests/unit/z-index-scale.spec.ts
index 9cc277899..3688d3275 100644
--- a/frontend/tests/unit/z-index-scale.spec.ts
+++ b/frontend/tests/unit/z-index-scale.spec.ts
@@ -3,7 +3,10 @@ import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
 // Spec 109 FR-055 / T007 / T019: one z-index scale, defined in one place
-// (navigation-map.md: sidebar < header < dropdown < modal < toast), and no
+// (navigation-map.md: header < sidebar < dropdown < modal < toast — the
+// sidebar must outrank the header so the mobile `drawer-side` overlay is
+// never painted over by the sticky header when it slides open; review
+// round 1 caught the scale shipping with sidebar and header swapped), and no
 // `<dialog class="modal">` still relies on the `:open` attribute binding (or
 // a `modal-open` class toggle) — every one of them now drives its open state
 // through `useDialogOpen` (`showModal()`/`close()`, top layer), which is what
@@ -35,14 +38,18 @@ describe('z-index scale (frontend/src/assets/z-index.css)', () => {
     }
   })
 
-  it('orders sidebar < header < dropdown < modal < toast', () => {
+  it('orders header < sidebar < dropdown < modal < toast', () => {
     const sidebar = tokenValue('sidebar')
     const header = tokenValue('header')
     const dropdown = tokenValue('dropdown')
     const modal = tokenValue('modal')
     const toast = tokenValue('toast')
-    expect(sidebar).toBeLessThan(header)
-    expect(header).toBeLessThan(dropdown)
+    // Sidebar must outrank header: `.drawer-side` (SidebarNav) is a fixed
+    // overlay sibling of the sticky TopHeader, and on <lg (the drawer
+    // breakpoint) opening it must paint over the header, not sit under it
+    // (review round 1 — the PR shipped this inverted).
+    expect(header).toBeLessThan(sidebar)
+    expect(sidebar).toBeLessThan(dropdown)
     expect(dropdown).toBeLessThan(modal)
     expect(modal).toBeLessThan(toast)
   })
diff --git a/internal/index/bleve.go b/internal/index/bleve.go
index e05ccaea9..512f7376a 100644
--- a/internal/index/bleve.go
+++ b/internal/index/bleve.go
@@ -1,6 +1,7 @@
 package index
 
 import (
+	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -48,6 +49,14 @@ type ToolDocument struct {
 	Hash             string `json:"hash"`
 	Tags             string `json:"tags"`
 	SearchableText   string `json:"searchable_text"` // Combined searchable content
+	// AnnotationsJSON is the tool's MCP behavior-hint annotations
+	// (config.ToolAnnotations), marshaled once at index time. Stored but not
+	// indexed for search, same as Hash — it exists so a search hit's tier
+	// (Spec 109 FR-028) reflects the tool's real annotations instead of
+	// always reading TierUnannotated (review round 1: GET /index/search never
+	// stored annotations at all, so a search hit's tier could not agree with
+	// the same tool's tier on GET /servers/{id}/tools).
+	AnnotationsJSON string `json:"annotations_json,omitempty"`
 }
 
 // NewBleveIndex creates (or opens) the shared default Bleve index at
@@ -134,6 +143,13 @@ func createBleveIndex(indexPath string) (bleve.Index, error) {
 	hashField.Index = false // Don't index hash for search
 	toolMapping.AddFieldMappingsAt("hash", hashField)
 
+	// Annotations field: stored only, never searched (it is JSON, not prose).
+	annotationsField := bleve.NewTextFieldMapping()
+	annotationsField.Analyzer = keyword.Name
+	annotationsField.Store = true
+	annotationsField.Index = false
+	toolMapping.AddFieldMappingsAt("annotations_json", annotationsField)
+
 	// Tags field (standard analyzer)
 	tagsField := bleve.NewTextFieldMapping()
 	tagsField.Analyzer = standard.Name
@@ -195,6 +211,18 @@ func toolDocument(toolMeta *config.ToolMetadata) (string, *ToolDocument) {
 		toolMeta.Description,
 		toolMeta.ParamsJSON)
 
+	var annotationsJSON string
+	if toolMeta.Annotations != nil {
+		if b, err := json.Marshal(toolMeta.Annotations); err == nil {
+			annotationsJSON = string(b)
+		}
+		// A marshal error here is unreachable for config.ToolAnnotations (plain
+		// strings/bools/pointers, no cyclic or unsupported types) — silently
+		// falling back to "no annotations stored" rather than failing the whole
+		// index write matches how the rest of this function tolerates partial
+		// metadata (e.g. an empty OutputSchemaJSON).
+	}
+
 	doc := &ToolDocument{
 		ToolName:         toolName,
 		FullToolName:     toolMeta.Name,
@@ -205,6 +233,7 @@ func toolDocument(toolMeta *config.ToolMetadata) (string, *ToolDocument) {
 		Hash:             toolMeta.Hash,
 		Tags:             "", // Can be extended later
 		SearchableText:   searchableText,
+		AnnotationsJSON:  annotationsJSON,
 	}
 
 	return docID, doc
@@ -235,6 +264,17 @@ func readToolMetadata(docID string, fields map[string]interface{}) *config.ToolM
 		// name so a malformed hit still renders rather than vanishing.
 		canonical = CanonicalToolName(serverName, getStringField(fields, "full_tool_name"))
 	}
+	var annotations *config.ToolAnnotations
+	if raw := getStringField(fields, "annotations_json"); raw != "" {
+		var parsed config.ToolAnnotations
+		if err := json.Unmarshal([]byte(raw), &parsed); err == nil {
+			annotations = &parsed
+		}
+		// A malformed stored value (should not happen; toolDocument only ever
+		// writes what json.Marshal produced) falls back to nil — TierUnannotated
+		// — rather than surfacing a decode error through every search result.
+	}
+
 	return &config.ToolMetadata{
 		Name:             canonical,
 		RawName:          strings.TrimPrefix(canonical, serverName+":"),
@@ -243,6 +283,7 @@ func readToolMetadata(docID string, fields map[string]interface{}) *config.ToolM
 		ParamsJSON:       getStringField(fields, "params_json"),
 		OutputSchemaJSON: getStringField(fields, "output_schema_json"),
 		Hash:             getStringField(fields, "hash"),
+		Annotations:      annotations,
 	}
 }
 
@@ -346,7 +387,7 @@ func newToolSearchRequest(q bquery.Query, from, size int) *bleve.SearchRequest {
 	searchReq := bleve.NewSearchRequest(q)
 	searchReq.From = from
 	searchReq.Size = size
-	searchReq.Fields = []string{"tool_name", "full_tool_name", "server_name", "description", "params_json", "output_schema_json", "hash"}
+	searchReq.Fields = []string{"tool_name", "full_tool_name", "server_name", "description", "params_json", "output_schema_json", "hash", "annotations_json"}
 	searchReq.Highlight = bleve.NewHighlight()
 
 	// Deterministic tie-break: primary sort by score descending (bleve's
@@ -621,7 +662,7 @@ func (b *BleveIndex) GetToolsByServer(serverName string) ([]*config.ToolMetadata
 	query := bleve.NewTermQuery(serverName)
 	query.SetField("server_name")
 
-	fields := []string{"tool_name", "full_tool_name", "server_name", "description", "params_json", "output_schema_json", "hash"}
+	fields := []string{"tool_name", "full_tool_name", "server_name", "description", "params_json", "output_schema_json", "hash", "annotations_json"}
 
 	b.logger.Debug("Querying tools by server", zap.String("server", serverName))
 
diff --git a/internal/index/bleve_annotations_test.go b/internal/index/bleve_annotations_test.go
new file mode 100644
index 000000000..083e3c4ab
--- /dev/null
+++ b/internal/index/bleve_annotations_test.go
@@ -0,0 +1,85 @@
+package index
+
+import (
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+// TestBleveIndex_SearchTools_PreservesAnnotations is a regression test for a
+// Spec 109 PR-a review finding (round 1, medium): GET /index/search (the Web
+// UI's Tools search box and the macOS tools search) always rendered every hit
+// as "Unannotated" regardless of the tool's real destructive/read/write
+// hints. The bug sits one level below the missing "annotations" map key in
+// server.searchResultsToMaps that a fix there alone could not have closed:
+// the Bleve ToolDocument never stored annotations at all, so readToolMetadata
+// could only ever hand back a nil Annotations pointer for a search hit, no
+// matter what the map-shaping code around it does with it.
+func TestBleveIndex_SearchTools_PreservesAnnotations(t *testing.T) {
+	destructive := true
+	tool := &config.ToolMetadata{
+		Name:        "danger:delete_everything",
+		ServerName:  "danger",
+		Description: "irreversibly deletes everything, no confirmation",
+		Annotations: &config.ToolAnnotations{
+			DestructiveHint: &destructive,
+		},
+	}
+
+	tmpDir, err := os.MkdirTemp("", "bleve_annotations_test_*")
+	require.NoError(t, err)
+	defer os.RemoveAll(tmpDir)
+
+	bleveIndex, err := NewBleveIndex(tmpDir, zap.NewNop())
+	require.NoError(t, err)
+	defer bleveIndex.Close()
+
+	require.NoError(t, bleveIndex.IndexTool(tool))
+
+	results, err := bleveIndex.SearchTools("delete_everything", 10)
+	require.NoError(t, err)
+	require.Len(t, results, 1)
+
+	require.NotNil(t, results[0].Tool.Annotations, "a search hit must carry its tool's annotations through the index round-trip")
+	require.NotNil(t, results[0].Tool.Annotations.DestructiveHint)
+	assert.True(t, *results[0].Tool.Annotations.DestructiveHint)
+}
+
+// TestBleveIndex_SearchToolsScoped_PreservesAnnotations covers the scoped
+// twin (used by every scoped REST caller — Spec 107), which shares
+// newToolSearchRequest with SearchTools but is a separate code path from the
+// hit through to the caller.
+func TestBleveIndex_SearchToolsScoped_PreservesAnnotations(t *testing.T) {
+	readOnly := true
+	tool := &config.ToolMetadata{
+		Name:        "safe:list_things",
+		ServerName:  "safe",
+		Description: "lists things without changing anything",
+		Annotations: &config.ToolAnnotations{
+			ReadOnlyHint: &readOnly,
+		},
+	}
+
+	tmpDir, err := os.MkdirTemp("", "bleve_annotations_scoped_test_*")
+	require.NoError(t, err)
+	defer os.RemoveAll(tmpDir)
+
+	bleveIndex, err := NewBleveIndex(tmpDir, zap.NewNop())
+	require.NoError(t, err)
+	defer bleveIndex.Close()
+
+	require.NoError(t, bleveIndex.IndexTool(tool))
+
+	results, err := bleveIndex.SearchToolsScoped("list_things", 10, func(string) bool { return true })
+	require.NoError(t, err)
+	require.Len(t, results, 1)
+
+	require.NotNil(t, results[0].Tool.Annotations)
+	require.NotNil(t, results[0].Tool.Annotations.ReadOnlyHint)
+	assert.True(t, *results[0].Tool.Annotations.ReadOnlyHint)
+}
diff --git a/internal/server/search_tools_tier_test.go b/internal/server/search_tools_tier_test.go
new file mode 100644
index 000000000..c44166ab4
--- /dev/null
+++ b/internal/server/search_tools_tier_test.go
@@ -0,0 +1,71 @@
+package server
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/contracts"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/runtime"
+)
+
+// TestSearchTools_AnnotationsSurviveToTier is a regression test for a Spec
+// 109 PR-a review finding (round 1, medium): GET /index/search (the Web UI
+// Tools search box and the macOS tools search) computed `tier` from whatever
+// searchResultsToMaps put in the "tool" map, but that map never carried an
+// "annotations" key — so every search hit's tier came back "unannotated" no
+// matter what the tool's real MCP behavior hints were, even though the SAME
+// tool's tier on GET /servers/{id}/tools (fed from live upstream state, not
+// the search index) was correct. A destructive tool would show a red
+// Destructive badge in the normal Tools list and a gray Unannotated badge
+// when found via search — the exact "silently not destructive" outcome the
+// tier feature exists to prevent.
+func TestSearchTools_AnnotationsSurviveToTier(t *testing.T) {
+	srv := newConsistencyServer(t)
+
+	// newConsistencyServer's cfg.Servers is empty, so NewServer's async
+	// LoadConfiguredServers (StartBackgroundInitialization) is about to
+	// re-sync storage to match it. Seeding the upstream server config before
+	// that sync completes races it: if the sync's own save lands after this
+	// fixture's, it silently reverts/removes the record — quarantinedServerFilter
+	// then finds no server and withholds the tool, making the search return
+	// zero hits (flake reproduced under -race full-package runs). Same
+	// pattern as mcp_group_scope_test.go / server_logs_missing_file_test.go.
+	require.Eventually(t, func() bool {
+		return srv.runtime.CurrentPhase() == runtime.PhaseReady
+	}, 10*time.Second, 10*time.Millisecond, "fixture: runtime never reached PhaseReady")
+
+	require.NoError(t, srv.runtime.StorageManager().SaveUpstreamServer(&config.ServerConfig{
+		Name:    "danger",
+		Enabled: true,
+		// Quarantined defaults to false; the search path withholds a
+		// quarantined server's tools entirely, so this must be non-quarantined
+		// for the hit to reach searchResultsToMaps at all.
+	}))
+
+	destructive := true
+	require.NoError(t, srv.runtime.IndexManager().IndexTool(&config.ToolMetadata{
+		Name:        "danger:delete_everything",
+		ServerName:  "danger",
+		Description: "irreversibly deletes everything, no confirmation",
+		Annotations: &config.ToolAnnotations{
+			DestructiveHint: &destructive,
+		},
+	}))
+
+	maps, err := srv.SearchTools("delete_everything", 10)
+	require.NoError(t, err)
+	require.Len(t, maps, 1)
+
+	toolMap, ok := maps[0]["tool"].(map[string]interface{})
+	require.True(t, ok, "search result must have a nested tool map")
+	assert.NotNil(t, toolMap["annotations"], "the tool map must carry annotations so AnnotationTier can compute a real tier")
+
+	typed := contracts.ConvertGenericSearchResultsToTyped(maps)
+	require.Len(t, typed, 1)
+	assert.Equal(t, contracts.TierDestructive, typed[0].Tool.Tier,
+		"a destructiveHint:true tool found via search must report tier=destructive, not unannotated")
+}
diff --git a/internal/server/server.go b/internal/server/server.go
index 700ecf27c..387b7f4a3 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -3673,6 +3673,14 @@ func (s *Server) searchResultsToMaps(results []*config.SearchResult) []map[strin
 				"description": result.Tool.Description,
 				"server_name": result.Tool.ServerName,
 			}
+			// Spec 109 FR-028/review round 1: without this, contracts'
+			// AnnotationTier(nil) always resolved to TierUnannotated for
+			// every search hit, regardless of the tool's real annotations,
+			// so the same tool's tier badge disagreed between the normal
+			// Tools list and the search box.
+			if result.Tool.Annotations != nil {
+				toolData["annotations"] = result.Tool.Annotations
+			}
 			// Parse params JSON as input schema if available
 			if result.Tool.ParamsJSON != "" {
 				var inputSchema map[string]interface{}
diff --git a/native/macos/MCPProxy/MCPProxy/API/APIClient.swift b/native/macos/MCPProxy/MCPProxy/API/APIClient.swift
index 09bd31eb8..ac0e1f07a 100644
--- a/native/macos/MCPProxy/MCPProxy/API/APIClient.swift
+++ b/native/macos/MCPProxy/MCPProxy/API/APIClient.swift
@@ -1239,7 +1239,10 @@ actor APIClient {
         do {
             let bodyData = try JSONSerialization.data(withJSONObject: body)
             let (data, response) = try await rawRequest(path: path, method: "POST", body: bodyData)
-            if (200...299).contains(response.statusCode) { return .ok() }
+            if (200...299).contains(response.statusCode) {
+                let body = try? JSONDecoder().decode(RegistryAddServerSuccessBody.self, from: data)
+                return .ok(serverName: body?.data?.server?.name)
+            }
             let err = try? JSONDecoder().decode(RegistryAddServerErrorBody.self, from: data)
             return .failure(
                 message: err?.message ?? "HTTP \(response.statusCode): \(HTTPURLResponse.localizedString(forStatusCode: response.statusCode))",
diff --git a/native/macos/MCPProxy/MCPProxy/API/RegistryModels.swift b/native/macos/MCPProxy/MCPProxy/API/RegistryModels.swift
index 82a8c0616..f939b29e3 100644
--- a/native/macos/MCPProxy/MCPProxy/API/RegistryModels.swift
+++ b/native/macos/MCPProxy/MCPProxy/API/RegistryModels.swift
@@ -222,15 +222,37 @@ struct SearchRegistryServersResponse: Codable {
 /// Result of adding a server from a registry. Carries `missingInputs` when the
 /// backend rejects with `missing_required_input` so the UI can tell the user
 /// which env vars are needed (the full prompt flow is a follow-up).
+///
+/// `serverName` is the name the backend actually assigned the new server —
+/// which can differ from the registry entry's own display name (falling back
+/// to the entry id when the entry's name is empty, or de-duplicating on a
+/// conflict). Review round 1: a caller that keys UI state on the catalog name
+/// instead (e.g. ServerBrowseView's "Added checkmark Open" flow) can end up
+/// looking up a server that does not exist under that name. The Web UI reads
+/// this same field (`result.server?.name`).
 struct AddServerResult: Equatable {
     let success: Bool
     let message: String?
     let missingInputs: [String]?
+    let serverName: String?
 
-    static func ok() -> AddServerResult { AddServerResult(success: true, message: nil, missingInputs: nil) }
+    static func ok(serverName: String? = nil) -> AddServerResult {
+        AddServerResult(success: true, message: nil, missingInputs: nil, serverName: serverName)
+    }
     static func failure(message: String?, missingInputs: [String]? = nil) -> AddServerResult {
-        AddServerResult(success: false, message: message, missingInputs: missingInputs)
+        AddServerResult(success: false, message: message, missingInputs: missingInputs, serverName: nil)
+    }
+}
+
+/// The success body for `POST /registries/{id}/servers/{serverId}/add`:
+/// `{"success":true,"data":{"server":{"name":...}}}`. Only the field this
+/// caller needs is modeled.
+struct RegistryAddServerSuccessBody: Decodable {
+    struct DataPayload: Decodable {
+        struct ServerSummary: Decodable { let name: String? }
+        let server: ServerSummary?
     }
+    let data: DataPayload?
 }
 
 /// Structured error body of a failed add-from-registry. Mirrors
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift b/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
index 64f7f3717..b379990fd 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
@@ -376,8 +376,14 @@ struct ServerBrowseView: View {
         addNote = nil
         let result = await client.addServerFromRegistry(registryID: reg, serverID: server.id)
         if result.success {
+            // The backend can assign a different name than the catalog entry's
+            // own (empty name falls back to the entry id; a conflict gets
+            // de-duplicated) — key "Added checkmark Open" on what it actually
+            // assigned, or Open silently no-ops (review round 1; the Web UI's
+            // Repositories.vue already does `result.server?.name || server.name`).
+            let assignedName = result.serverName ?? server.name
             addNote = "Added “\(server.name)”. New servers start quarantined — review under Servers."
-            addedServers[server.id] = server.name
+            addedServers[server.id] = assignedName
         } else if let missing = result.missingInputs, !missing.isEmpty {
             addNote = "“\(server.name)” needs input: \(missing.joined(separator: ", ")). Add it from the Web UI to supply those values."
         } else {
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ToolsView.swift b/native/macos/MCPProxy/MCPProxy/Views/ToolsView.swift
index db98c92be..9bc810232 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/ToolsView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/ToolsView.swift
@@ -55,6 +55,11 @@ struct ToolsView: View {
         /// The canonical MCP identity — what an agent would actually call.
         var qualified: String { server.isEmpty ? name : "\(server):\(name)" }
         var id: String { qualified }
+
+        /// `tier`, defaulting to "unannotated" (review round 1): a `nil` tier
+        /// from an older core must still render a badge, same as the Web UI's
+        /// `tool.tier || 'unannotated'` — never no badge at all.
+        var displayTier: String { tier ?? "unannotated" }
     }
 
     var body: some View {
@@ -170,14 +175,12 @@ struct ToolsView: View {
                     .padding(.horizontal, 5).padding(.vertical, 1)
                     .background(Color.accentColor.opacity(0.15))
                     .clipShape(Capsule())
-                if let tier = row.tier {
-                    Text(ToolLabels.tierLabel(tier))
-                        .font(.scaled(.caption2, scale: fontScale))
-                        .padding(.horizontal, 5).padding(.vertical, 1)
-                        .background(tierColor(tier).opacity(0.15))
-                        .foregroundStyle(tierColor(tier))
-                        .clipShape(Capsule())
-                }
+                Text(ToolLabels.tierLabel(row.displayTier))
+                    .font(.scaled(.caption2, scale: fontScale))
+                    .padding(.horizontal, 5).padding(.vertical, 1)
+                    .background(tierColor(row.displayTier).opacity(0.15))
+                    .foregroundStyle(tierColor(row.displayTier))
+                    .clipShape(Capsule())
                 Spacer()
                 if let score = row.score {
                     Text(String(format: "%.2f", score))
diff --git a/native/macos/MCPProxy/MCPProxyTests/APIClientAddServerFromRegistryTests.swift b/native/macos/MCPProxy/MCPProxyTests/APIClientAddServerFromRegistryTests.swift
new file mode 100644
index 000000000..7be6eb92b
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/APIClientAddServerFromRegistryTests.swift
@@ -0,0 +1,55 @@
+// APIClientAddServerFromRegistryTests.swift
+// MCPProxyTests
+//
+// Spec 109 PR-a review round 1 (low): the backend can assign a server a
+// DIFFERENT name than the registry entry's display name (falling back to the
+// entry id when the entry's own name is empty, or de-duplicating on
+// conflict) and echoes the name it actually assigned in the response body
+// (`data.server.name`). addServerFromRegistry used to discard that body
+// entirely, so ServerBrowseView's "Added checkmark Open" flow keyed off the
+// catalog display name instead — the Web UI already gets this right
+// (Repositories.vue: `result.server?.name || server.name`).
+
+import XCTest
+@testable import MCPProxy
+
+final class APIClientAddServerFromRegistryTests: XCTestCase {
+
+    override func setUp() {
+        super.setUp()
+        ConnectStubURLProtocol.reset()
+    }
+
+    override func tearDown() {
+        ConnectStubURLProtocol.reset()
+        super.tearDown()
+    }
+
+    func testSuccessCarriesTheBackendAssignedServerName() async throws {
+        // The backend assigned "everything-2" (a conflict suffix), not the
+        // catalog entry's own display name.
+        ConnectStubURLProtocol.responseBody = ConnectStubURLProtocol.envelope("""
+        {"server":{"name":"everything-2","protocol":"stdio","enabled":true,"quarantined":true}}
+        """)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        let result = await client.addServerFromRegistry(registryID: "testreg", serverID: "everything")
+
+        XCTAssertTrue(result.success)
+        XCTAssertEqual(result.serverName, "everything-2")
+    }
+
+    func testFailureCarriesNoServerName() async throws {
+        ConnectStubURLProtocol.statusCode = 400
+        ConnectStubURLProtocol.responseBody = Data("""
+        {"success":false,"code":"missing_required_input","message":"needs input","missing_inputs":["API_KEY"]}
+        """.utf8)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        let result = await client.addServerFromRegistry(registryID: "testreg", serverID: "everything")
+
+        XCTAssertFalse(result.success)
+        XCTAssertNil(result.serverName)
+        XCTAssertEqual(result.missingInputs, ["API_KEY"])
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxyTests/ToolLabelsTests.swift b/native/macos/MCPProxy/MCPProxyTests/ToolLabelsTests.swift
index 8d0bde956..ef17a03da 100644
--- a/native/macos/MCPProxy/MCPProxyTests/ToolLabelsTests.swift
+++ b/native/macos/MCPProxy/MCPProxyTests/ToolLabelsTests.swift
@@ -55,4 +55,22 @@ final class ToolLabelsTests: XCTestCase {
         let tool = try JSONDecoder().decode(SearchTool.self, from: json)
         XCTAssertEqual(tool.tier, "read")
     }
+
+    // Review round 1 (low): ToolsView.toolRow used to render the tier badge
+    // only `if let tier = row.tier`, so a `nil` tier (an older core that does
+    // not send the field yet — an explicitly supported skew, tray and core
+    // update independently) rendered NO badge at all. The Web UI's equivalent
+    // (`tool.tier || 'unannotated'`) always renders one, defaulting to
+    // "Unannotated" — this is that same fallback made reachable from a real
+    // row instead of only from ToolLabels.tierLabel(nil) in isolation.
+    func testToolRowDisplayTierFallsBackToUnannotatedForAnOlderCore() {
+        let row = ToolsView.ToolRow(server: "fs", name: "read_file", description: "d", score: nil, tier: nil)
+        XCTAssertEqual(row.displayTier, "unannotated")
+        XCTAssertEqual(ToolLabels.tierLabel(row.displayTier), "Unannotated")
+    }
+
+    func testToolRowDisplayTierPassesThroughARealTier() {
+        let row = ToolsView.ToolRow(server: "fs", name: "delete_file", description: "d", score: nil, tier: "destructive")
+        XCTAssertEqual(row.displayTier, "destructive")
+    }
 }

From 20ddead1ee0026cff4654eb5fefa3533080aa917 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 25 Sep 2026 22:14:30 +0300
Subject: [PATCH 06/27] fix: address review round 2
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified each round-2 finding against current source before touching
anything; fixed the genuine ones test-first, deferred one with reasons
below. No false positives to reject this round.

FIXED:

1. (high) Repositories.vue: closeAddRegistry()/closeDeleteRegistry() are
   wired as useDialogOpen's native-close handler (Escape/backdrop), but
   their own addingRegistry/deletingRegistry guard silently skipped the
   showAddRegistry/showDeleteRegistry flip. A native close already happened
   in the DOM by the time that fires and cannot be undone, so the guard just
   desynced Vue state from an already-closed dialog — reopening became a
   no-op forever (round 1's H4 bug, reintroduced by round 1's own fix). Split
   the native-close handler from the Cancel-button handler; the Cancel/
   Delete-cancel buttons keep the guard (now via :disabled) since an
   explicit click CAN be blocked mid-submit.

2. (medium) OnboardingWizard.vue: dismiss() (also wired as useDialogOpen's
   onClose) awaited up to three sequential engagement-bookkeeping calls
   before emit('close'). props.show stayed true for that whole window, so
   reopening the wizard from the sidebar Setup entry was a no-op. emit
   synchronously first; the bookkeeping now runs decoupled in the
   background.

3. (low) ConnectModal.vue: close() (same onClose role) reset several result/
   preview fields but not disconnectTarget, so Escape during the "Disconnect
   X?" confirm sub-panel left it stale for the next open.

4. (medium-high) internal/runtime/lifecycle.go: annotations_json is only
   written at (re)index time, but the reindex trigger is a Hash comparison
   that deliberately EXCLUDES annotations (see calculateToolApprovalHash's
   own comment in tool_quarantine.go: annotations are unstable across
   reconnections, and hashing them in before caused false
   "tool_description_changed" spam on every reconnect). So an
   already-indexed, otherwise-unchanged tool could never pick up newly
   observed annotations short of a manual reindex. Fixed WITHOUT touching
   Hash/change-detection (which would reintroduce that exact regression):
   applyDifferentialToolUpdate now tracks annotation-only diffs separately
   and silently refreshes just those documents (no approval/quarantine
   state, no "Tool schema changed" log, no hash rewrite). Covered by
   TestApplyDifferentialToolUpdate_BackfillsAnnotationsForUnchangedTool and
   ...IsIdempotent.

6. (low-medium) RegistryModels.swift: RegistryAddServerErrorBody decoded a
   `message` key, but writeRegistryAddError (internal/httpapi/server.go)
   serializes the field as `error` — every other error envelope in this API
   uses the same shape. err?.message was therefore always nil against the
   real backend, so a failed Add-from-Registry always showed the generic
   "HTTP 400: ..." text instead of the actual reason. Fixed the CodingKeys
   mapping and added a test that asserts on the decoded message text (the
   round-1 test used a stub keyed `message`, which "passed" without ever
   checking the value — a green test over a broken decode).

7. (low) Same files: round 1's own comment/test claimed the backend
   "de-duplicates on conflict" for a name collision. It doesn't —
   AddServer (internal/server/server.go) hard-fails with duplicate_name; no
   rename/suffix logic exists anywhere in that path. Corrected the
   misleading comments in RegistryModels.swift and ServerBrowseView.swift,
   and reworked the test's success-case stub to model the one case that IS
   real (empty entry name falls back to the entry id) instead of an
   invented de-dup suffix.

8. (medium) Settings.vue: hasServerEdition depends on systemStore.status,
   populated asynchronously by App.vue's SSE connection in its own
   onMounted. On a reload of /settings?tab=teams, Settings.vue's onMounted
   could run its `?tab=` membership check before that status frame lands,
   silently dropping `teams` with no retry once it arrives. Added a
   one-shot retry gated on hasServerEdition, guarded so it never overrides
   a tab the user picks in the meantime and is a no-op when the edition
   really is personal.

DEFERRED (real, not a false positive, but out of scope for a quick-wins
fix round):

5. (low) internal/index/bleve.go: a pre-105/pre-this-PR on-disk index opens
   with its OWN persisted mapping, which never declared annotations_json —
   so that field falls to Bleve's dynamic-mapping default (Index=true,
   contributes to _all) on a legacy index, while a freshly created index
   gets the explicit Index=false mapping added in round 1. Confirmed real:
   this is genuine BM25 divergence between legacy and fresh indexes.
   NOT fixed here: the obvious-looking fix (disable dynamic mapping) is
   actively wrong — output_schema_json has NO explicit field mapping at all
   and already relies on the same dynamic-mapping fallback in every index,
   old and new alike; disabling it would silently stop storing that field
   on every newly created index. A correct fix needs an actual Bleve
   mapping-version/migration mechanism (there is none today — the
   OutputSchemaHashSchemaVersion precedent lives entirely in the BBolt
   approval-record store, not the search index), which is a properly scoped
   follow-up, not a round-2 quick fix.

Verification: go build ./... and -tags server; go test -race
./internal/runtime/... (192s, clean); golangci-lint v2 bare and
--build-tags server (only pre-existing, unrelated issues, e.g.
event_bus.go:887 reflect.Ptr); frontend npm run build + npx vitest run
(151 files, 1401 tests, all green; package-lock.json unmodified); swift
test (1179 tests, 1 failure — AppLifecycleTests.
testTheSharedJournalNeverWritesToTheRealInstanceRootUnderTests, a
documented pre-existing environmental flake tied to a real
~/.mcpproxy/tray-lifecycle.jsonl on this machine, unrelated to this diff
and already failing on main).
---
 frontend/src/components/ConnectModal.vue      |   6 +
 frontend/src/components/OnboardingWizard.vue  |  54 ++++---
 frontend/src/views/Repositories.vue           |  35 +++-
 frontend/src/views/Settings.vue               |  32 +++-
 ...nect-modal-disconnect-target-reset.spec.ts | 110 +++++++++++++
 .../onboarding-wizard-dismiss-race.spec.ts    | 125 ++++++++++++++
 ...es-registry-dialog-escape-inflight.spec.ts | 153 ++++++++++++++++++
 .../settings-tab-param-edition-race.spec.ts   | 112 +++++++++++++
 internal/runtime/annotations_backfill_test.go | 103 ++++++++++++
 internal/runtime/lifecycle.go                 |  33 +++-
 .../MCPProxy/API/RegistryModels.swift         |  29 +++-
 .../MCPProxy/Views/ServerBrowseView.swift     |  11 +-
 .../APIClientAddServerFromRegistryTests.swift |  55 +++++--
 13 files changed, 813 insertions(+), 45 deletions(-)
 create mode 100644 frontend/tests/unit/connect-modal-disconnect-target-reset.spec.ts
 create mode 100644 frontend/tests/unit/onboarding-wizard-dismiss-race.spec.ts
 create mode 100644 frontend/tests/unit/repositories-registry-dialog-escape-inflight.spec.ts
 create mode 100644 frontend/tests/unit/settings-tab-param-edition-race.spec.ts
 create mode 100644 internal/runtime/annotations_backfill_test.go

diff --git a/frontend/src/components/ConnectModal.vue b/frontend/src/components/ConnectModal.vue
index 47af95d87..47ac50b0e 100644
--- a/frontend/src/components/ConnectModal.vue
+++ b/frontend/src/components/ConnectModal.vue
@@ -952,6 +952,12 @@ function close() {
   previewError.value = {}
   lastConnect.value = null
   undoPanelOpen.value = false
+  // Review round 2, finding 3: this also fires on a native Escape/backdrop
+  // dismiss (it's useDialogOpen's onClose), which can happen while the
+  // "Disconnect X?" confirm sub-panel is open. Without resetting it, the
+  // stale confirm panel reappears for a client the user may no longer
+  // intend to touch the next time the modal opens.
+  disconnectTarget.value = null
   emit('close')
 }
 
diff --git a/frontend/src/components/OnboardingWizard.vue b/frontend/src/components/OnboardingWizard.vue
index 0792c12da..b823c623b 100644
--- a/frontend/src/components/OnboardingWizard.vue
+++ b/frontend/src/components/OnboardingWizard.vue
@@ -989,10 +989,11 @@ function goBack() {
 
 // Leaving the wizard for the registry: the wizard is a modal owned by the
 // Dashboard, so it has to close before the route changes or it would hang over
-// the registry page. The await is load-bearing — `dismiss()` awaits its
-// mark-skipped calls before it emits `close`, and routing away first unmounts
-// the Dashboard that owns the `wizardOpen` flag, so the emit could land with
-// nothing left to clear it and the wizard would spring back open on return.
+// the registry page. `dismiss()` emits `close` synchronously (its engagement
+// bookkeeping runs decoupled, in the background — see `dismiss`'s own
+// comment), so by the time this `await` resolves the Dashboard has already
+// flipped `wizardOpen` false. Routing away before that would unmount the
+// Dashboard first, and the wizard would spring back open on return.
 async function goToRegistry() {
   await dismiss()
   await router.push('/repositories')
@@ -1497,24 +1498,41 @@ async function onServerAdded() {
   })
 }
 
-async function dismiss() {
+// `dismiss` is the onClose handler useDialogOpen calls for a NATIVE close
+// (Escape, or the browser's own backdrop/cancel handling) as well as every
+// explicit "close the wizard" affordance. By the time a native close fires,
+// the <dialog> has already closed itself in the DOM; `props.show` is the
+// only thing keeping useDialogOpen's `isOpen()` true, and only the parent's
+// `@close` handler (via `emit('close')`) flips it. This used to await up to
+// three sequential engagement-bookkeeping calls BEFORE emitting close, so
+// `props.show` stayed true for that whole window — reopening the wizard from
+// the sidebar Setup entry during it was a no-op (setting an already-true ref
+// doesn't re-trigger the watch that calls `showModal()` again), same failure
+// class as round 1's H4 dialog-desync bug. Emit synchronously first; the
+// bookkeeping is best-effort and fully decoupled from the dialog's own
+// open/close state, so it runs in the background regardless (review round 2,
+// finding 2).
+function dismiss() {
+  emit('close')
+  void recordDismissalEngagement()
+}
+
+async function recordDismissalEngagement() {
   // Engagement is permanent: once the wizard has been opened and dismissed,
   // we don't auto-popup again. The sidebar Setup entry remains visible so
   // the user can return.
-  if (!onboarding.isEngaged) {
-    // Spec 046 — any step the user never advanced through counts as "skipped"
-    // so the funnel (engaged - completed - skipped) reconciles to engaged
-    // total. Per-step calls are no-ops if a status is already recorded.
-    const stepState = onboarding.state?.state
-    if (stepState && !stepState.connect_step_status) {
-      await onboarding.markConnectSkipped()
-    }
-    if (stepState && !stepState.server_step_status) {
-      await onboarding.markServerSkipped()
-    }
-    await onboarding.markEngaged()
+  if (onboarding.isEngaged) return
+  // Spec 046 — any step the user never advanced through counts as "skipped"
+  // so the funnel (engaged - completed - skipped) reconciles to engaged
+  // total. Per-step calls are no-ops if a status is already recorded.
+  const stepState = onboarding.state?.state
+  if (stepState && !stepState.connect_step_status) {
+    await onboarding.markConnectSkipped()
   }
-  emit('close')
+  if (stepState && !stepState.server_step_status) {
+    await onboarding.markServerSkipped()
+  }
+  await onboarding.markEngaged()
 }
 
 // NOTE: no onMounted open-fallback here. The `immediate` watcher above already
diff --git a/frontend/src/views/Repositories.vue b/frontend/src/views/Repositories.vue
index 7291f1889..a6c2f5854 100644
--- a/frontend/src/views/Repositories.vue
+++ b/frontend/src/views/Repositories.vue
@@ -511,7 +511,7 @@
           </div>
 
           <div class="modal-action">
-            <button type="button" class="btn btn-ghost" data-test="registry-add-cancel" @click="closeAddRegistry">
+            <button type="button" class="btn btn-ghost" data-test="registry-add-cancel" :disabled="addingRegistry" @click="closeAddRegistry">
               Cancel
             </button>
             <button
@@ -544,7 +544,7 @@
         </div>
 
         <div class="modal-action">
-          <button type="button" class="btn btn-ghost" data-test="registry-delete-cancel" @click="closeDeleteRegistry">
+          <button type="button" class="btn btn-ghost" data-test="registry-delete-cancel" :disabled="deletingRegistry" @click="closeDeleteRegistry">
             Cancel
           </button>
           <button
@@ -629,14 +629,16 @@ const addingRegistry = ref(false)
 const isEditMode = computed(() => editRegistryId.value !== null)
 // Spec 109 FR-055: <dialog>.showModal()/close(), not the `open` attribute —
 // keeps the top layer, so nothing (sidebar, header) can ever paint over it.
-const { dialogEl: addRegistryDialogEl } = useDialogOpen(() => showAddRegistry.value, () => closeAddRegistry())
+// The native-close handler is deliberately NOT closeAddRegistry() — see the
+// comment on handleAddRegistryNativeClose for why (review round 2, finding 1).
+const { dialogEl: addRegistryDialogEl } = useDialogOpen(() => showAddRegistry.value, () => handleAddRegistryNativeClose())
 
 // Delete-custom-registry confirmation state (MCP-1073)
 const showDeleteRegistry = ref(false)
 const deleteRegistryTarget = ref<Registry | null>(null)
 const deleteRegistryError = ref<string | null>(null)
 const deletingRegistry = ref(false)
-const { dialogEl: deleteRegistryDialogEl } = useDialogOpen(() => showDeleteRegistry.value, () => closeDeleteRegistry())
+const { dialogEl: deleteRegistryDialogEl } = useDialogOpen(() => showDeleteRegistry.value, () => handleDeleteRegistryNativeClose())
 
 let searchDebounceTimer: ReturnType<typeof setTimeout> | null = null
 
@@ -967,6 +969,24 @@ function closeAddRegistry() {
   editRegistryId.value = null
 }
 
+// The Cancel button and the invisible backdrop-dismiss button both wire to
+// closeAddRegistry(), which intentionally no-ops while a submit is in
+// flight. A native close (Escape, or `<dialog>`'s own backdrop/cancel
+// handling) is different: the dialog has ALREADY closed in the DOM by the
+// time this fires, and nothing here can undo that. Reusing closeAddRegistry
+// there (review round 1) meant its addingRegistry guard silently skipped the
+// `showAddRegistry` flip too, leaving Vue believing the dialog was still
+// open while the DOM said otherwise — the button that would reopen it then
+// sets `showAddRegistry` to a value it already holds, the driving watch
+// never re-fires, and `showModal()` never runs again (round 1's exact bug,
+// reintroduced here — review round 2, finding 1). Always resync local state
+// on a native close; doAddRegistry()/doEditRegistry() already tolerate the
+// dialog having moved on by the time their request settles.
+function handleAddRegistryNativeClose() {
+  showAddRegistry.value = false
+  editRegistryId.value = null
+}
+
 // Map the backend's stable error codes to actionable messages. Shared across
 // add / edit / delete since all three surface the same code set.
 function registryErrorMessage(code: string | undefined, fallback: string | undefined, verb: string): string {
@@ -1068,6 +1088,13 @@ function closeDeleteRegistry() {
   deleteRegistryTarget.value = null
 }
 
+// See handleAddRegistryNativeClose above — same reasoning, applied to the
+// delete-confirm dialog (review round 2, finding 1).
+function handleDeleteRegistryNativeClose() {
+  showDeleteRegistry.value = false
+  deleteRegistryTarget.value = null
+}
+
 async function confirmDeleteRegistry() {
   const target = deleteRegistryTarget.value
   if (!target) return
diff --git a/frontend/src/views/Settings.vue b/frontend/src/views/Settings.vue
index 83e77b728..8e9c45ce0 100644
--- a/frontend/src/views/Settings.vue
+++ b/frontend/src/views/Settings.vue
@@ -253,6 +253,11 @@ const activeTab = ref<string>('security')
 // URL in sync with every tab change, preserving other query params (e.g.
 // `?focus=` from focusField).
 watch(activeTab, (tab) => {
+  // Review round 2, finding 8: any tab change — a click, focusField, or the
+  // late-edition retry below succeeding — means the initial `?tab=` read no
+  // longer needs a retry (and, for a manual click, must not be overridden
+  // later by that retry).
+  tabParamPending = false
   if (route.query.tab === tab) return
   void router.replace({ query: { ...route.query, tab } })
 })
@@ -539,10 +544,35 @@ watch(defaultInstructions, () => {
   maybePrefillInstructions()
 })
 
-onMounted(async () => {
+// Spec 109 FR-016 (review round 2, finding 8): `hasServerEdition` depends on
+// systemStore.status, which App.vue populates asynchronously (SSE, its own
+// onMounted). On a fresh reload of /settings?tab=teams that status frame can
+// still be in flight when this component mounts, so the membership check
+// below silently drops `teams` and nothing ever retries once status arrives.
+// Re-run the same check once edition resolves, but only while the user
+// hasn't since picked a different tab themselves (`tabParamPending` is
+// cleared the moment either happens).
+let tabParamPending = typeof route.query.tab === 'string'
+function applyTabParamIfValid(): boolean {
   const tabParam = route.query.tab
   if (typeof tabParam === 'string' && tabs.value.some((t) => t.id === tabParam)) {
     activeTab.value = tabParam
+    return true
+  }
+  return false
+}
+
+onMounted(async () => {
+  if (applyTabParamIfValid()) tabParamPending = false
+  if (tabParamPending) {
+    const stopEditionRetry = watch(hasServerEdition, () => {
+      stopEditionRetry()
+      // The user may have picked a different tab in the meantime — that
+      // must win over a now-stale `?tab=` retry.
+      if (!tabParamPending) return
+      applyTabParamIfValid()
+      tabParamPending = false
+    })
   }
   loadDefaultInstructions()
   window.addEventListener('mcpproxy:config-saved', handleConfigSaved)
diff --git a/frontend/tests/unit/connect-modal-disconnect-target-reset.spec.ts b/frontend/tests/unit/connect-modal-disconnect-target-reset.spec.ts
new file mode 100644
index 000000000..f2c2f404c
--- /dev/null
+++ b/frontend/tests/unit/connect-modal-disconnect-target-reset.spec.ts
@@ -0,0 +1,110 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import ConnectModal from '@/components/ConnectModal.vue'
+import api from '@/services/api'
+
+// Spec 109 PR-a review round 2 (finding 3): close() (the useDialogOpen onClose
+// handler, fired on a native Escape/backdrop dismiss as well as the explicit
+// Close button) resets several result/preview fields but not
+// `disconnectTarget`. Pressing Escape while the "Disconnect X?" confirm
+// sub-panel is open and reopening the modal must not show the stale confirm
+// panel for a client the user may no longer intend to touch.
+
+// jsdom implements the `open` attribute but not showModal()/close(); polyfill
+// just enough of the native behaviour to exercise the real Escape path (same
+// approach as use-dialog-open-native-close.spec.ts).
+function polyfillNativeDialog(el: HTMLDialogElement) {
+  el.showModal = function (this: HTMLDialogElement) {
+    this.open = true
+  }
+  el.close = function (this: HTMLDialogElement) {
+    if (!this.open) return
+    this.open = false
+    this.dispatchEvent(new Event('close'))
+  }
+}
+
+vi.mock('@/services/api', () => ({
+  default: {
+    getConnectStatus: vi.fn(),
+    getConnectClientStatus: vi.fn(),
+    getConnectPreview: vi.fn(),
+    connectClient: vi.fn(),
+    disconnectClient: vi.fn(),
+    getOnboardingState: vi.fn(),
+  },
+}))
+
+const PROXY = 'http://127.0.0.1:18080/mcp'
+
+function row(id: string, overrides: Record<string, unknown> = {}) {
+  return {
+    id,
+    name: id,
+    config_path: `/Users/test/.${id}/mcp.json`,
+    exists: true,
+    connected: true,
+    supported: true,
+    icon: id,
+    proxy_url: PROXY,
+    ...overrides,
+  }
+}
+
+function onboardingState(ids: string[]) {
+  return {
+    success: true,
+    data: {
+      has_connected_client: ids.length > 0,
+      has_configured_server: false,
+      connected_client_count: ids.length,
+      connected_client_ids: ids,
+      configured_server_count: 0,
+      state: { engaged: false },
+      should_show_wizard: false,
+      first_mcp_client_ever: false,
+      mcp_clients_seen_ever: [],
+    },
+  }
+}
+
+describe('ConnectModal — disconnectTarget cleared on close (review round 2, finding 3)', () => {
+  let pinia: any
+
+  beforeEach(() => {
+    pinia = createPinia()
+    setActivePinia(pinia)
+    for (const fn of Object.values(api) as any[]) fn.mockReset()
+    ;(api.getOnboardingState as any).mockResolvedValue(onboardingState(['cursor']))
+    ;(api.getConnectStatus as any).mockResolvedValue({ success: true, data: [row('cursor')] })
+    ;(api.getConnectClientStatus as any).mockResolvedValue({ success: false, error: 'nope' })
+  })
+
+  it('does not show the stale "Disconnect cursor?" panel after Escape + reopen', async () => {
+    const wrapper = mount(ConnectModal, { props: { show: false }, global: { plugins: [pinia] } })
+    const dialogNode = wrapper.element as HTMLDialogElement
+    polyfillNativeDialog(dialogNode)
+
+    await wrapper.setProps({ show: true })
+    await flushPromises()
+
+    await wrapper.find('[data-test="connect-disconnect-cursor"]').trigger('click')
+    await flushPromises()
+    expect(wrapper.find('[data-test="connect-disconnect-confirm"]').exists()).toBe(true)
+
+    // Escape closes the dialog natively while the confirm sub-panel is open.
+    dialogNode.close()
+    await flushPromises()
+    expect(wrapper.emitted('close')).toBeTruthy()
+
+    // The parent flips its own `show` false on the emitted close, then the
+    // user reopens the modal (e.g. from the sidebar).
+    await wrapper.setProps({ show: false })
+    await flushPromises()
+    await wrapper.setProps({ show: true })
+    await flushPromises()
+
+    expect(wrapper.find('[data-test="connect-disconnect-confirm"]').exists()).toBe(false)
+  })
+})
diff --git a/frontend/tests/unit/onboarding-wizard-dismiss-race.spec.ts b/frontend/tests/unit/onboarding-wizard-dismiss-race.spec.ts
new file mode 100644
index 000000000..7a326e6a2
--- /dev/null
+++ b/frontend/tests/unit/onboarding-wizard-dismiss-race.spec.ts
@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import OnboardingWizard from '@/components/OnboardingWizard.vue'
+import api from '@/services/api'
+
+// Spec 109 PR-a review round 2 (finding 2): dismiss() (wired as useDialogOpen's
+// onClose) used to be async and await up to three sequential API calls BEFORE
+// emit('close'). Until they resolved, props.show (the isOpen() source) stayed
+// true even though the dialog may have already closed natively, so the
+// driving watch never refires and the wizard cannot be reopened from the
+// sidebar Setup entry during that window. The fix emits 'close' synchronously
+// and runs the engagement bookkeeping in the background.
+
+vi.mock('@/services/api', () => ({
+  default: {
+    getConnectStatus: vi.fn(),
+    getOnboardingState: vi.fn(),
+    markOnboardingState: vi.fn(),
+    getActivities: vi.fn(),
+    getConfig: vi.fn(),
+    getDockerStatus: vi.fn(),
+    getCanonicalConfigPaths: vi.fn(),
+    getConnectPreview: vi.fn(),
+    connectClient: vi.fn(),
+    importServersFromPath: vi.fn(),
+  },
+}))
+
+function onboardingState() {
+  return {
+    success: true,
+    data: {
+      has_connected_client: true,
+      has_configured_server: false,
+      connected_client_count: 1,
+      connected_client_ids: ['cursor'],
+      configured_server_count: 0,
+      // Not engaged, and neither step has a recorded status yet, so
+      // dismiss()'s bookkeeping branch has at least one await to make before
+      // it used to emit 'close' — exactly the window the finding describes.
+      state: { engaged: false },
+      should_show_wizard: true,
+      first_mcp_client_ever: false,
+      mcp_clients_seen_ever: [],
+      incomplete_tab_count: 1,
+    },
+  }
+}
+
+describe('OnboardingWizard dismiss() race (review round 2, finding 2)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.clearAllMocks()
+    ;(api.getActivities as any).mockResolvedValue({ success: true, data: { activities: [] } })
+    ;(api.getConfig as any).mockResolvedValue({ success: true, data: {} })
+    ;(api.getDockerStatus as any).mockResolvedValue({ success: true, data: { available: true } })
+    ;(api.getConnectStatus as any).mockResolvedValue({ success: true, data: { clients: [] } })
+    ;(api.getOnboardingState as any).mockResolvedValue(onboardingState())
+    ;(api.getCanonicalConfigPaths as any).mockResolvedValue({ success: true, data: { paths: [] } })
+    // Never resolves during the test — simulates a slow/in-flight network
+    // call, which is exactly the window the bug lived in.
+    ;(api.markOnboardingState as any).mockImplementation(() => new Promise(() => {}))
+  })
+
+  it('emits close synchronously, before the engagement bookkeeping settles', async () => {
+    const wrapper = mount(OnboardingWizard, {
+      props: { show: false },
+      global: {
+        stubs: {
+          RouterLink: { template: '<a><slot /></a>' },
+          AddServerModal: { template: '<div />' },
+        },
+      },
+    })
+    await wrapper.setProps({ show: true })
+    await flushPromises()
+
+    // Triggering the click dispatches the DOM event (and therefore runs the
+    // `dismiss` handler) synchronously; `.trigger()`'s returned promise only
+    // covers Vue's subsequent re-render. Checking `emitted('close')` right
+    // here — before awaiting anything else — is what distinguishes "emits
+    // immediately" from "awaits bookkeeping calls that never resolve first".
+    const pending = wrapper.find('[aria-label="Close"]').trigger('click')
+    expect(wrapper.emitted('close'), 'close must be emitted synchronously, not after the bookkeeping awaits').toBeTruthy()
+
+    await pending
+    await flushPromises()
+
+    // The background bookkeeping still ran (best-effort, just decoupled from
+    // the dialog's own open/close state).
+    expect(api.markOnboardingState).toHaveBeenCalled()
+  })
+
+  it('can be reopened immediately after dismiss, even while bookkeeping is still in flight', async () => {
+    const wrapper = mount(OnboardingWizard, {
+      props: { show: false },
+      global: {
+        stubs: {
+          RouterLink: { template: '<a><slot /></a>' },
+          AddServerModal: { template: '<div />' },
+        },
+      },
+    })
+    await wrapper.setProps({ show: true })
+    await flushPromises()
+
+    await wrapper.find('[aria-label="Close"]').trigger('click')
+    // A real parent (Dashboard + the onboarding store) flips its own open
+    // flag false the instant 'close' is emitted — do the same here.
+    await wrapper.setProps({ show: false })
+    await flushPromises()
+
+    // Reopening (e.g. the sidebar Setup entry) must not be a no-op just
+    // because the previous dismiss's bookkeeping call is still pending.
+    await wrapper.setProps({ show: true })
+    await flushPromises()
+
+    expect(wrapper.props('show')).toBe(true)
+    // A second dismiss must work too — if the wizard had been left desynced
+    // internally, this would either throw or silently fail to re-emit.
+    await wrapper.find('[aria-label="Close"]').trigger('click')
+    expect(wrapper.emitted('close')?.length).toBeGreaterThanOrEqual(2)
+  })
+})
diff --git a/frontend/tests/unit/repositories-registry-dialog-escape-inflight.spec.ts b/frontend/tests/unit/repositories-registry-dialog-escape-inflight.spec.ts
new file mode 100644
index 000000000..eae7d8ce4
--- /dev/null
+++ b/frontend/tests/unit/repositories-registry-dialog-escape-inflight.spec.ts
@@ -0,0 +1,153 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import Repositories from '@/views/Repositories.vue'
+import api from '@/services/api'
+
+// Spec 109 PR-a review round 2 (finding 1): closeAddRegistry()/closeDeleteRegistry()
+// each early-return while a submit is in flight, and the round-1 fix wired
+// these same functions as useDialogOpen's native-close (Escape) handler. A
+// real <dialog> already closes itself in the DOM on Escape regardless of any
+// guard in Vue-land, so skipping the state flip there just desyncs Vue's
+// `showAddRegistry`/`showDeleteRegistry` from the (already-closed) DOM —
+// bricking the dialog until reload, since the button that would reopen it
+// sets the ref to a value it already holds and the driving watch never fires.
+//
+// jsdom implements the `open` attribute but not showModal()/close(), so we
+// polyfill just enough of the native behaviour (same approach as
+// use-dialog-open-native-close.spec.ts) to exercise the real browser path.
+function polyfillNativeDialog(el: HTMLDialogElement) {
+  el.showModal = function (this: HTMLDialogElement) {
+    this.open = true
+  }
+  el.close = function (this: HTMLDialogElement) {
+    if (!this.open) return
+    this.open = false
+    this.dispatchEvent(new Event('close'))
+  }
+}
+
+vi.mock('@/services/api', () => ({
+  default: {
+    listRegistries: vi.fn(),
+    searchRegistryServers: vi.fn(),
+    addRegistrySource: vi.fn(),
+    editRegistrySource: vi.fn(),
+    removeRegistrySource: vi.fn(),
+    addServerFromRegistry: vi.fn(),
+  },
+}))
+
+const globalStubs = {
+  CollapsibleHintsPanel: { template: '<div />' },
+}
+
+function mountView() {
+  return mount(Repositories, {
+    global: { plugins: [createPinia()], stubs: globalStubs },
+    attachTo: document.body,
+  })
+}
+
+const officialRegistry = {
+  id: 'official',
+  name: 'Official MCP Registry',
+  description: 'The official registry',
+  url: 'https://registry.modelcontextprotocol.io/',
+  provenance: 'official',
+  trusted: true,
+}
+
+const customRegistry = {
+  id: 'acme',
+  name: 'Acme Registry',
+  description: 'A custom source',
+  url: 'https://acme.example/registry',
+  provenance: 'custom',
+  trusted: false,
+}
+
+describe('Repositories — Add/Delete registry dialog survives Escape mid-submit (round 2)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    localStorage.clear()
+    ;(api.listRegistries as any).mockResolvedValue({
+      success: true,
+      data: { registries: [officialRegistry, customRegistry], total: 2 },
+    })
+    ;(api.searchRegistryServers as any).mockResolvedValue({
+      success: true,
+      data: { registry_id: 'official', servers: [], total: 0 },
+    })
+    ;(api.addRegistrySource as any).mockReset()
+    ;(api.removeRegistrySource as any).mockReset()
+  })
+
+  it('reopens the Add Registry dialog after Escape closes it while the add is in flight', async () => {
+    let resolveAdd!: (v: any) => void
+    ;(api.addRegistrySource as any).mockImplementation(
+      () => new Promise((resolve) => { resolveAdd = resolve })
+    )
+
+    const wrapper = mountView()
+    await flushPromises()
+
+    const dialog = wrapper.find('[data-test="registry-add-source-dialog"]')
+    polyfillNativeDialog(dialog.element as HTMLDialogElement)
+
+    await wrapper.find('[data-test="registry-add-source-button"]').trigger('click')
+    await flushPromises()
+    expect((dialog.element as HTMLDialogElement).open).toBe(true)
+
+    await wrapper.find('[data-test="registry-add-url-input"]').setValue('https://acme.example/registry')
+    await wrapper.find('[data-test="registry-add-form"]').trigger('submit')
+    await flushPromises() // addingRegistry is now true; addRegistrySource is still pending
+
+    // The browser closes the dialog natively (Escape) while the submit is
+    // still in flight — this is not driven by any Vue click handler.
+    ;(dialog.element as HTMLDialogElement).close()
+    await flushPromises()
+
+    // Let the in-flight add finish (failure — the specific outcome doesn't
+    // matter, only that it resolves after the native close happened).
+    resolveAdd({ success: false, code: 'invalid_registry_url', error: 'bad url' })
+    await flushPromises()
+
+    // Reopening from the page's own trigger must work — the dialog must not
+    // stay bricked shut.
+    await wrapper.find('[data-test="registry-add-source-button"]').trigger('click')
+    await flushPromises()
+    expect((dialog.element as HTMLDialogElement).open).toBe(true)
+  })
+
+  it('reopens the Delete Registry confirm dialog after Escape closes it while the delete is in flight', async () => {
+    let resolveDelete!: (v: any) => void
+    ;(api.removeRegistrySource as any).mockImplementation(
+      () => new Promise((resolve) => { resolveDelete = resolve })
+    )
+
+    const wrapper = mountView()
+    await flushPromises()
+
+    const dialog = wrapper.find('[data-test="registry-delete-dialog"]')
+    polyfillNativeDialog(dialog.element as HTMLDialogElement)
+
+    await wrapper.find('[data-test="registry-delete-acme"]').trigger('click')
+    await flushPromises()
+    expect((dialog.element as HTMLDialogElement).open).toBe(true)
+
+    await wrapper.find('[data-test="registry-delete-confirm"]').trigger('click')
+    await flushPromises() // deletingRegistry is now true; removeRegistrySource is still pending
+
+    ;(dialog.element as HTMLDialogElement).close()
+    await flushPromises()
+
+    resolveDelete({ success: false, error: 'boom' })
+    await flushPromises()
+
+    // The dialog must be reopenable again afterwards (e.g. the user retries).
+    await wrapper.find('[data-test="registry-delete-acme"]').trigger('click')
+    await flushPromises()
+    expect((dialog.element as HTMLDialogElement).open).toBe(true)
+  })
+})
diff --git a/frontend/tests/unit/settings-tab-param-edition-race.spec.ts b/frontend/tests/unit/settings-tab-param-edition-race.spec.ts
new file mode 100644
index 000000000..ad693f89b
--- /dev/null
+++ b/frontend/tests/unit/settings-tab-param-edition-race.spec.ts
@@ -0,0 +1,112 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createMemoryHistory } from 'vue-router'
+
+// Spec 109 PR-a review round 2 (finding 8): App.vue's systemStore.status is
+// populated asynchronously (connectEventSource's SSE, in its own onMounted),
+// while Settings.vue reads `?tab=` synchronously in its OWN onMounted, gated
+// by hasServerEdition (computed from systemStore.status?.edition). On a
+// reload of /settings?tab=teams, Settings.vue can mount and run that check
+// BEFORE the SSE status frame lands: `hasServerEdition` is still false,
+// `tabs.value` excludes `teams`, the membership check silently fails, and the
+// param is dropped — the page falls back to the default tab and never
+// retries once status actually arrives.
+
+const emptyConfig = vi.hoisted(() => ({ server_edition: { enabled: false } }))
+
+vi.mock('@/services/api', () => ({
+  default: {
+    getConfig: vi.fn().mockResolvedValue({ success: true, data: { config: emptyConfig } }),
+    getStatus: vi.fn().mockResolvedValue({ success: true, data: {} }),
+    validateConfig: vi.fn(),
+    applyConfig: vi.fn(),
+  },
+}))
+
+import Settings from '@/views/Settings.vue'
+import { useSystemStore } from '@/stores/system'
+
+function makeRouter(path: string) {
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/settings', name: 'settings', component: Settings, meta: { title: 'Settings' } },
+      { path: '/:pathMatch(.*)*', name: 'other', component: { template: '<div/>' } },
+    ],
+  })
+  router.push(path)
+  return router
+}
+
+async function mountSettings(path: string) {
+  const router = makeRouter(path)
+  await router.isReady()
+  const wrapper = mount(Settings, {
+    global: {
+      plugins: [router],
+      stubs: { VueMonacoEditor: true, ConnectModal: true },
+    },
+  })
+  return wrapper
+}
+
+describe('Settings ?tab=teams vs. late systemStore.status (review round 2, finding 8)', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  it('lands on the teams tab once status arrives late, instead of dropping the param', async () => {
+    // systemStore.status is still unset at mount time — the SSE frame has
+    // not arrived yet (the exact race on a fresh /settings?tab=teams load).
+    const wrapper = await mountSettings('/settings?tab=teams')
+    await flushPromises()
+
+    // Precondition: the race is live — the tab isn't available/selected yet.
+    expect(wrapper.find('[data-test="settings-tab-teams"]').exists()).toBe(false)
+
+    // The status frame lands (App.vue's connectEventSource callback).
+    const systemStore = useSystemStore()
+    // @ts-expect-error partial StatusUpdate is enough for this computed
+    systemStore.status = { edition: 'server' }
+    await flushPromises()
+
+    const teamsTab = wrapper.find('[data-test="settings-tab-teams"]')
+    expect(teamsTab.exists()).toBe(true)
+    expect(teamsTab.classes()).toContain('tab-active')
+    wrapper.unmount()
+  })
+
+  it('does not clobber a tab the user already picked once status resolves', async () => {
+    const wrapper = await mountSettings('/settings?tab=teams')
+    await flushPromises()
+
+    // The user clicks over to General before the status frame arrives.
+    await wrapper.find('[data-test="settings-tab-general"]').trigger('click')
+    expect(wrapper.find('[data-test="settings-tab-general"]').classes()).toContain('tab-active')
+
+    const systemStore = useSystemStore()
+    // @ts-expect-error partial StatusUpdate is enough for this computed
+    systemStore.status = { edition: 'server' }
+    await flushPromises()
+
+    // The late-arriving status must not retroactively yank the user back to
+    // the tab from the URL.
+    expect(wrapper.find('[data-test="settings-tab-general"]').classes()).toContain('tab-active')
+    wrapper.unmount()
+  })
+
+  it('is a no-op when the resolved edition really is personal (no phantom teams tab)', async () => {
+    const wrapper = await mountSettings('/settings?tab=teams')
+    await flushPromises()
+
+    const systemStore = useSystemStore()
+    // @ts-expect-error partial StatusUpdate is enough for this computed
+    systemStore.status = { edition: 'personal' }
+    await flushPromises()
+
+    expect(wrapper.find('[data-test="settings-tab-teams"]').exists()).toBe(false)
+    expect(wrapper.find('[data-test="settings-tab-security"]').classes()).toContain('tab-active')
+    wrapper.unmount()
+  })
+})
diff --git a/internal/runtime/annotations_backfill_test.go b/internal/runtime/annotations_backfill_test.go
new file mode 100644
index 000000000..b52b95e94
--- /dev/null
+++ b/internal/runtime/annotations_backfill_test.go
@@ -0,0 +1,103 @@
+package runtime
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+)
+
+// Spec 109 PR-a review round 2 (finding 4): the tool change-detection hash
+// (internal/hash.ComputeToolHashWithOutputSchema) deliberately excludes
+// annotations — see calculateToolApprovalHash's comment in tool_quarantine.go:
+// annotations are unstable across reconnections and folding them into a
+// change-detection hash previously caused false "tool_description_changed"
+// spam on every reconnect. That means a tool whose Hash does not change never
+// goes through the "modified" reindex path, so annotations_json — added to
+// the Bleve document only at (re)index time — can never be backfilled for a
+// tool that was already indexed before this feature existed, short of an
+// operator deleting index.bleve or removing/re-adding the server.
+//
+// The fix here is independent of Hash/change-detection and therefore doesn't
+// reintroduce the reconnect-churn regression: on every discovery pass,
+// unchanged tools (same Hash) whose freshly observed Annotations differ from
+// what is currently stored in the index get their document silently
+// refreshed (index-only; no approval/quarantine state, no "tool changed" log
+// spam, no hash rewrite).
+func annotBackfillTool(serverName, name, hash, schema, desc string, annotations *config.ToolAnnotations) *config.ToolMetadata {
+	return &config.ToolMetadata{
+		ServerName:  serverName,
+		Name:        name,
+		Description: desc,
+		ParamsJSON:  schema,
+		Hash:        hash,
+		Annotations: annotations,
+	}
+}
+
+func TestApplyDifferentialToolUpdate_BackfillsAnnotationsForUnchangedTool(t *testing.T) {
+	rt := newSigWarmRuntime(t)
+	ctx := context.Background()
+
+	schema := `{"type":"object","properties":{"path":{"type":"string"}},"required":["path"]}`
+
+	// First pass: stands in for an index written before annotations existed
+	// (or by an upstream that omitted them) — same Hash formula either way,
+	// since Hash never includes annotations.
+	require.NoError(t, rt.applyDifferentialToolUpdate(ctx, "annot-server", []*config.ToolMetadata{
+		annotBackfillTool("annot-server", "tool_a", "annot-hash-a", schema, "Read a file.", nil),
+	}))
+
+	before, err := rt.indexManager.GetToolsByServer("annot-server")
+	require.NoError(t, err)
+	require.Len(t, before, 1)
+	assert.Nil(t, before[0].Annotations, "precondition: no annotations stored yet")
+
+	// Second pass: the SAME hash (nothing functionally changed) but the
+	// upstream now reports annotations — e.g. after an mcpproxy upgrade that
+	// starts capturing them. Hash is deliberately unaffected (see comment
+	// above), so this must not go through the "modified" hash-diff branch to
+	// still pick up the annotations.
+	readOnly := true
+	require.NoError(t, rt.applyDifferentialToolUpdate(ctx, "annot-server", []*config.ToolMetadata{
+		annotBackfillTool("annot-server", "tool_a", "annot-hash-a", schema, "Read a file.", &config.ToolAnnotations{
+			Title:        "Read a file",
+			ReadOnlyHint: &readOnly,
+		}),
+	}))
+
+	after, err := rt.indexManager.GetToolsByServer("annot-server")
+	require.NoError(t, err)
+	require.Len(t, after, 1)
+	require.NotNil(t, after[0].Annotations, "annotations must be backfilled into the index for an otherwise-unchanged tool")
+	assert.Equal(t, "Read a file", after[0].Annotations.Title)
+	require.NotNil(t, after[0].Annotations.ReadOnlyHint)
+	assert.True(t, *after[0].Annotations.ReadOnlyHint)
+	// The Hash itself must stay untouched by this — annotations backfill is
+	// deliberately NOT change detection.
+	assert.Equal(t, "annot-hash-a", after[0].Hash)
+}
+
+// A no-op rediscovery (same hash, same annotations — including "still none")
+// must not touch the index at all; this is the reconnect-flap guard the
+// warning in calculateToolApprovalHash exists for. We can't observe "did not
+// write" directly through this package's API, so this instead pins the
+// steady-state outcome: repeated identical passes stay stable.
+func TestApplyDifferentialToolUpdate_AnnotationsBackfillIsIdempotent(t *testing.T) {
+	rt := newSigWarmRuntime(t)
+	ctx := context.Background()
+	schema := `{"type":"object","properties":{"path":{"type":"string"}},"required":["path"]}`
+
+	tool := annotBackfillTool("annot-server-2", "tool_a", "annot-hash-b", schema, "Read a file.", nil)
+	require.NoError(t, rt.applyDifferentialToolUpdate(ctx, "annot-server-2", []*config.ToolMetadata{tool}))
+	require.NoError(t, rt.applyDifferentialToolUpdate(ctx, "annot-server-2", []*config.ToolMetadata{tool}))
+
+	got, err := rt.indexManager.GetToolsByServer("annot-server-2")
+	require.NoError(t, err)
+	require.Len(t, got, 1)
+	assert.Nil(t, got[0].Annotations)
+	assert.Equal(t, "annot-hash-b", got[0].Hash)
+}
diff --git a/internal/runtime/lifecycle.go b/internal/runtime/lifecycle.go
index c86f17b0e..d2cfb8cb3 100644
--- a/internal/runtime/lifecycle.go
+++ b/internal/runtime/lifecycle.go
@@ -5,6 +5,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"reflect"
 	"strings"
 	"time"
 
@@ -825,6 +826,19 @@ func (r *Runtime) applyDifferentialToolUpdate(ctx context.Context, serverName st
 	var addedTools []*config.ToolMetadata
 	var modifiedTools []*config.ToolMetadata
 	var removedTools []string
+	// Review round 2, finding 4: annotations are deliberately excluded from
+	// Hash (see calculateToolApprovalHash's comment — they are unstable
+	// across reconnections, and folding them into change-detection caused
+	// false "tool_description_changed" spam before). That means a tool whose
+	// Hash never changes can never reach the modifiedTools branch, so
+	// annotations_json — written to the index only at (re)index time — stays
+	// stale forever for anything indexed before this field existed (or
+	// before an upstream started reporting hints), short of an operator
+	// deleting index.bleve or removing/re-adding the server. Tracked
+	// separately from modifiedTools so it never touches Hash, approval state,
+	// or the "Tool schema changed" log line — this is a silent, best-effort
+	// metadata sync, not change detection.
+	var annotationsOnlyTools []*config.ToolMetadata
 
 	// Find added and modified tools
 	for toolName, newTool := range newToolsMap {
@@ -835,6 +849,8 @@ func (r *Runtime) applyDifferentialToolUpdate(ctx context.Context, serverName st
 		} else if oldTool.Hash != newTool.Hash {
 			// Tool exists but has changed (different hash)
 			modifiedTools = append(modifiedTools, newTool)
+		} else if !reflect.DeepEqual(oldTool.Annotations, newTool.Annotations) {
+			annotationsOnlyTools = append(annotationsOnlyTools, newTool)
 		}
 		// else: tool unchanged, no action needed
 	}
@@ -976,6 +992,21 @@ func (r *Runtime) applyDifferentialToolUpdate(ctx context.Context, serverName st
 		}
 	}
 
+	// 4b. Silently backfill/refresh annotations_json for otherwise-unchanged
+	// tools (review round 2, finding 4). Deliberately not logged at Info and
+	// not described as a "change" — see the comment on annotationsOnlyTools
+	// above — this is metadata hygiene, not a tool-contract update.
+	allowedAnnotationsOnlyTools := filterBlockedTools(annotationsOnlyTools, approvalResult.BlockedTools)
+	if len(allowedAnnotationsOnlyTools) > 0 {
+		r.logger.Debug("Refreshing stored annotations for unchanged tools",
+			zap.String("server", serverName),
+			zap.Int("count", len(allowedAnnotationsOnlyTools)))
+
+		if err := r.indexManager.BatchIndexTools(allowedAnnotationsOnlyTools); err != nil {
+			return fmt.Errorf("failed to refresh tool annotations: %w", err)
+		}
+	}
+
 	// 5. Warm the signature cache for every tool this server still serves —
 	// deliberately the WHOLE allowed set, not just what steps 3 and 4 touched.
 	//
@@ -998,7 +1029,7 @@ func (r *Runtime) applyDifferentialToolUpdate(ctx context.Context, serverName st
 	// that include it (Profiles v2, Spec 057). Profiles without this server are
 	// untouched. Skipped when nothing changed to avoid churn on idle sweeps.
 	changed := len(addedTools) > 0 || len(modifiedTools) > 0 || len(removedTools) > 0 ||
-		len(approvalResult.BlockedTools) > 0
+		len(annotationsOnlyTools) > 0 || len(approvalResult.BlockedTools) > 0
 	if changed {
 		r.reindexAffectedProfiles(serverName)
 		// Evict signature-cache entries orphaned by removed/redefined tools —
diff --git a/native/macos/MCPProxy/MCPProxy/API/RegistryModels.swift b/native/macos/MCPProxy/MCPProxy/API/RegistryModels.swift
index f939b29e3..b2beadb86 100644
--- a/native/macos/MCPProxy/MCPProxy/API/RegistryModels.swift
+++ b/native/macos/MCPProxy/MCPProxy/API/RegistryModels.swift
@@ -225,11 +225,17 @@ struct SearchRegistryServersResponse: Codable {
 ///
 /// `serverName` is the name the backend actually assigned the new server —
 /// which can differ from the registry entry's own display name (falling back
-/// to the entry id when the entry's name is empty, or de-duplicating on a
-/// conflict). Review round 1: a caller that keys UI state on the catalog name
-/// instead (e.g. ServerBrowseView's "Added checkmark Open" flow) can end up
-/// looking up a server that does not exist under that name. The Web UI reads
-/// this same field (`result.server?.name`).
+/// to the entry id when the entry's name is empty). Review round 1: a caller
+/// that keys UI state on the catalog name instead (e.g. ServerBrowseView's
+/// "Added checkmark Open" flow) can end up looking up a server that does not
+/// exist under that name. The Web UI reads this same field
+/// (`result.server?.name`).
+///
+/// Note (review round 2, finding 7): a name COLLISION is not de-duplicated —
+/// AddServer (internal/server/server.go) hard-fails the add with a
+/// `duplicate_name` error (`code`/`message` on this same result, not a
+/// renamed `serverName`). Only the empty-name-falls-back-to-entry-ID case
+/// above is real.
 struct AddServerResult: Equatable {
     let success: Bool
     let message: String?
@@ -256,13 +262,22 @@ struct RegistryAddServerSuccessBody: Decodable {
 }
 
 /// Structured error body of a failed add-from-registry. Mirrors
-/// `contracts.RegistryAddError`.
+/// `contracts.RegistryAddError`, but the wire envelope
+/// (`writeRegistryAddError` in internal/httpapi/server.go) serializes the
+/// message under the JSON key `error`, not `message` — the same shape every
+/// other error envelope in this API uses. `message` decoded that field
+/// directly (review round 2, finding 6): `err?.message` was therefore always
+/// nil against the real backend, and a failed Add-from-Registry (e.g. a
+/// duplicate name) always fell through to the generic "HTTP 400: ..." text
+/// instead of the backend's actual reason (which the Web UI shows fine via
+/// `result.error`).
 struct RegistryAddServerErrorBody: Decodable {
     let code: String?
     let message: String?
     let missingInputs: [String]?
     enum CodingKeys: String, CodingKey {
-        case code, message
+        case code
+        case message = "error"
         case missingInputs = "missing_inputs"
     }
 }
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift b/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
index b379990fd..6cd4b927c 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
@@ -377,10 +377,13 @@ struct ServerBrowseView: View {
         let result = await client.addServerFromRegistry(registryID: reg, serverID: server.id)
         if result.success {
             // The backend can assign a different name than the catalog entry's
-            // own (empty name falls back to the entry id; a conflict gets
-            // de-duplicated) — key "Added checkmark Open" on what it actually
-            // assigned, or Open silently no-ops (review round 1; the Web UI's
-            // Repositories.vue already does `result.server?.name || server.name`).
+            // own (empty name falls back to the entry id) — key "Added
+            // checkmark Open" on what it actually assigned, or Open silently
+            // no-ops (review round 1; the Web UI's Repositories.vue already
+            // does `result.server?.name || server.name`). A name COLLISION is
+            // NOT de-duplicated — it hard-fails the add (see the `else`
+            // branch below), so `result.success` is false and this branch
+            // does not run (review round 2, finding 7).
             let assignedName = result.serverName ?? server.name
             addNote = "Added “\(server.name)”. New servers start quarantined — review under Servers."
             addedServers[server.id] = assignedName
diff --git a/native/macos/MCPProxy/MCPProxyTests/APIClientAddServerFromRegistryTests.swift b/native/macos/MCPProxy/MCPProxyTests/APIClientAddServerFromRegistryTests.swift
index 7be6eb92b..28a5a2180 100644
--- a/native/macos/MCPProxy/MCPProxyTests/APIClientAddServerFromRegistryTests.swift
+++ b/native/macos/MCPProxy/MCPProxyTests/APIClientAddServerFromRegistryTests.swift
@@ -3,12 +3,26 @@
 //
 // Spec 109 PR-a review round 1 (low): the backend can assign a server a
 // DIFFERENT name than the registry entry's display name (falling back to the
-// entry id when the entry's own name is empty, or de-duplicating on
-// conflict) and echoes the name it actually assigned in the response body
-// (`data.server.name`). addServerFromRegistry used to discard that body
-// entirely, so ServerBrowseView's "Added checkmark Open" flow keyed off the
-// catalog display name instead — the Web UI already gets this right
+// entry id when the entry's own name is empty) and echoes the name it
+// actually assigned in the response body (`data.server.name`).
+// addServerFromRegistry used to discard that body entirely, so
+// ServerBrowseView's "Added checkmark Open" flow keyed off the catalog
+// display name instead — the Web UI already gets this right
 // (Repositories.vue: `result.server?.name || server.name`).
+//
+// A name COLLISION is a hard failure (`duplicate_name`, HTTP 409), not a
+// rename — round 1's own comment/test here claimed the opposite
+// ("de-duplicating on conflict"); that claim was fictional (review round 2,
+// finding 7). The success case below models the real cause of a differing
+// name instead: the entry's own display name is empty.
+//
+// Round 2, finding 6: the failure envelope's message is the JSON key
+// `error` (writeRegistryAddError in internal/httpapi/server.go), not
+// `message` — RegistryAddServerErrorBody decoded the wrong key, so
+// `result.message` was always nil against the real backend and every
+// failure showed a generic "HTTP 400: ..." instead. The round-1 test below
+// used a stub body keyed `message`, which the bug happily "matched" without
+// ever asserting on the decoded text — a green test over a broken decode.
 
 import XCTest
 @testable import MCPProxy
@@ -26,23 +40,27 @@ final class APIClientAddServerFromRegistryTests: XCTestCase {
     }
 
     func testSuccessCarriesTheBackendAssignedServerName() async throws {
-        // The backend assigned "everything-2" (a conflict suffix), not the
-        // catalog entry's own display name.
+        // The backend assigned "everything-server" (derived from the entry
+        // id because the catalog entry itself had no display name), which
+        // differs from whatever display name the catalog card shows.
         ConnectStubURLProtocol.responseBody = ConnectStubURLProtocol.envelope("""
-        {"server":{"name":"everything-2","protocol":"stdio","enabled":true,"quarantined":true}}
+        {"server":{"name":"everything-server","protocol":"stdio","enabled":true,"quarantined":true}}
         """)
         let client = ConnectStubURLProtocol.makeClient()
 
         let result = await client.addServerFromRegistry(registryID: "testreg", serverID: "everything")
 
         XCTAssertTrue(result.success)
-        XCTAssertEqual(result.serverName, "everything-2")
+        XCTAssertEqual(result.serverName, "everything-server")
     }
 
     func testFailureCarriesNoServerName() async throws {
         ConnectStubURLProtocol.statusCode = 400
+        // The real envelope (writeRegistryAddError) keys the message `error`,
+        // not `message` — see this file's header comment (review round 2,
+        // finding 6).
         ConnectStubURLProtocol.responseBody = Data("""
-        {"success":false,"code":"missing_required_input","message":"needs input","missing_inputs":["API_KEY"]}
+        {"success":false,"code":"missing_required_input","error":"needs input","missing_inputs":["API_KEY"]}
         """.utf8)
         let client = ConnectStubURLProtocol.makeClient()
 
@@ -51,5 +69,22 @@ final class APIClientAddServerFromRegistryTests: XCTestCase {
         XCTAssertFalse(result.success)
         XCTAssertNil(result.serverName)
         XCTAssertEqual(result.missingInputs, ["API_KEY"])
+        // The actual regression check: decoding the real `error` key must
+        // surface the backend's own reason, not the generic HTTP fallback.
+        XCTAssertEqual(result.message, "needs input")
+    }
+
+    func testFailureFallsBackToGenericMessageOnlyWhenTheEnvelopeHasNoErrorField() async throws {
+        ConnectStubURLProtocol.statusCode = 409
+        ConnectStubURLProtocol.responseBody = Data("""
+        {"success":false,"code":"duplicate_name"}
+        """.utf8)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        let result = await client.addServerFromRegistry(registryID: "testreg", serverID: "everything")
+
+        XCTAssertFalse(result.success)
+        XCTAssertNotNil(result.message)
+        XCTAssertTrue(result.message?.contains("409") ?? false)
     }
 }

From 211b18ab434dee051794d753b318ef972182e8db Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 25 Sep 2026 23:03:13 +0300
Subject: [PATCH 07/27] fix: address review round 3
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified each round-3 finding against current source before touching
anything; fixed the genuine one test-first, confirmed one is already
covered by existing tests, and reaffirmed one deferral. No false
positives to reject this round — all three findings described the
code accurately.

FIXED:

1. (medium, T011a) scripts/test-api-e2e.sh's cleanup trap used a
   blanket `pkill -f "mcpproxy.*serve"` / `pkill -f
   "launcher-server.*--port 39933"`. Round 1 rejected this same finding
   on the premise that no tasks.md substantiates it being an in-scope
   task for this PR; that premise was false — specs/109-ux-navigation-
   consistency/tasks.md (present on the sibling 109-ux-navigation-
   consistency branch, both branched from the same commit) lists T011a
   explicitly under "Phase 2: PR 109-a — quick-wins". Live-verified the
   actual risk before fixing: this machine had a real tray-managed
   `mcpproxy serve` (PID 15758) and a second, unrelated worktree's test
   instance running at the same time — the unfixed script's blanket
   pkill would have killed both. Replaced both blanket kills with
   `descendant_pids()`, which snapshots the actual OS-process
   descendants of $MCPPROXY_PID (recursively, via `pgrep -P`) BEFORE
   touching it, then reaps only those specific PIDs (and only if still
   alive) as a fallback for the launcher-test fixture getting orphaned
   before mcpproxy's own graceful-shutdown reap path runs. Added
   scripts/test-api-e2e-cleanup-check.sh (the check T011a specifies):
   starts a decoy `mcpproxy serve` on another port with a scratch data
   dir, runs the full E2E script, and asserts the decoy is still alive
   afterward. Ran it for real: 65/66 sub-tests passed (the one failure
   is the pre-existing, unrelated "server-edition binary present"
   check, which needs a separately built ./mcpproxy-server and fails
   identically on main), and the decoy — plus this machine's real tray
   core — survived the run.

2. (low-medium, T007 Playwright half) e2e/web-ui-sweep/
   visual-a11y-sweep.spec.ts had no browser-level proof that the H4
   z-index fix (frontend/src/assets/z-index.css) holds under real
   layout and paint, only jsdom token-ordering coverage. Added "mobile
   drawer sidebar paints above the sticky header, not under it (H4)":
   opens the mobile drawer against a real launched instance and asserts
   via `elementFromPoint` that the drawer, not the header, is the
   topmost element at a point they both occupy. Verified it actually
   catches the regression it targets, not just a code read: temporarily
   re-inverted --z-header/--z-sidebar back to round-1's shipped bug,
   rebuilt, and reran — the new test timed out failing exactly as
   expected; restored the tokens and reran the full 25-test suite
   clean. One real finding surfaced while building this: daisyUI's
   drawer opens via a CSS `visibility`/`opacity` transition
   (`allow-discrete`, ~0.2-0.3s), so `elementFromPoint` checked on the
   very next frame after the checkbox flips can still legitimately see
   the header for a couple of frames — normal opening animation, not
   the H4 regression (a permanently wrong settled z-index). The
   assertion polls for the settled state instead of asserting
   immediately, so it does not flake on that transition.

ALREADY COVERED (not a gap, no change needed):

- The finding's other T007 half — "a vitest asserting none of
  Repositories.vue's three dialogs still uses the `:open` binding" —
  already exists: frontend/tests/unit/z-index-scale.spec.ts (added in
  the original PR commit 8bc8d23de, kept through round 1) has both
  "Repositories.vue dialogs use showModal()/close(), not :open
  (FR-055)" (lines 71-88, checking exactly the `:open` binding and all
  three data-test ids) and a broader "every <dialog class=modal> drives
  its open state imperatively" sweep across all 8 affected components,
  Repositories.vue included. Wrote a duplicate test file first, then
  found this and deleted it rather than ship two guards for the same
  invariant.

DEFERRED (confirmed real, reaffirming round 2's deferral — not fixed
here):

3. internal/index/bleve.go: re-verified the pre-105/pre-this-PR
   legacy-index dynamic-mapping divergence against current source.
   annotations_json still has no on-disk mapping-version guard,
   RebuildIndex() is still a documented no-op, and output_schema_json
   still has no explicit field mapping of its own — so it's still true
   that disabling dynamic mapping to close this gap would silently stop
   indexing output_schema_json on every freshly created index, on top
   of every index that already exists today. Round 2's reasoning holds
   exactly as written: a correct fix needs an actual Bleve
   mapping-version/migration mechanism, which is properly scoped design
   work, not a quick-wins round change. Flagging a follow-up task for
   that design work separately rather than leaving it only in this
   commit message.

Verification: go build ./... and -tags server (-o /dev/null, per the
server-tags-build-overwrite gotcha) both clean. No Go, frontend/src, or
native code touched this round, so go test -race / vitest / swift test
are unaffected by this diff; ran golangci-lint v2 anyway (bare and
--build-tags server) — 16 and 19 pre-existing issues respectively, none
in any file this round touched (reflect.Ptr inlining, deprecated
TopK/Features test usage, deprecated ecdsa.PublicKey.X/Y, ParseDir
deprecation — all pre-existing on files untouched by any of the three
rounds). scripts/test-api-e2e-cleanup-check.sh and the new Playwright
test were both run for real against a locally built instance, not just
read.

Not pushed; branch left detached per instructions.
---
 e2e/web-ui-sweep/visual-a11y-sweep.spec.ts | 56 +++++++++++++
 scripts/test-api-e2e-cleanup-check.sh      | 94 ++++++++++++++++++++++
 scripts/test-api-e2e.sh                    | 44 ++++++++--
 3 files changed, 189 insertions(+), 5 deletions(-)
 create mode 100755 scripts/test-api-e2e-cleanup-check.sh

diff --git a/e2e/web-ui-sweep/visual-a11y-sweep.spec.ts b/e2e/web-ui-sweep/visual-a11y-sweep.spec.ts
index 930e199bd..5fc9c3772 100644
--- a/e2e/web-ui-sweep/visual-a11y-sweep.spec.ts
+++ b/e2e/web-ui-sweep/visual-a11y-sweep.spec.ts
@@ -434,6 +434,62 @@ test('the footer never overlaps the page content', async ({ page }) => {
   expect(overlap, 'main content bleeds under the footer').toBeLessThanOrEqual(1)
 })
 
+// Spec 109 PR-a review round 1 (H4) / round 3 finding 2, T007's Playwright
+// half: proves the --z-header/--z-sidebar fix (frontend/src/assets/z-index.css,
+// frontend/tests/unit/z-index-scale.spec.ts) holds under REAL layout and
+// paint, not just token ordering in jsdom. Round 1 shipped these tokens
+// inverted, which put the sticky TopHeader back on top of the open mobile
+// drawer instead of the other way around — the exact class of stacking bug
+// this z-index scale exists to prevent (see z-index.css's own header
+// comment). `elementFromPoint` at a coordinate the sticky header and the open
+// drawer both occupy is the only way to prove which one the browser actually
+// painted on top; a bounding-box/CSS-value assertion would pass even if a
+// third ancestor's stacking context silently swallowed the token.
+test('mobile drawer sidebar paints above the sticky header, not under it (H4)', async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 })
+  await goto(page, '/')
+
+  const header = page.locator('header')
+  await expect(header).toBeVisible()
+  const headerBox = await header.boundingBox()
+  expect(headerBox, 'header has no box').not.toBeNull()
+  // A point inside the sticky header's own bounding box — this is exactly
+  // where the header used to win when the tokens were inverted.
+  const point = { x: headerBox!.x + headerBox!.width / 2, y: headerBox!.y + headerBox!.height / 2 }
+
+  // Sanity check: before the drawer opens, that point IS the header (proves
+  // the point is meaningful, not e.g. sitting over a hole in the header).
+  const beforeOpen = await page.evaluate(
+    (p) => !!document.elementFromPoint(p.x, p.y)?.closest('header'),
+    point,
+  )
+  expect(beforeOpen, 'test point does not land on the header before the drawer opens').toBe(true)
+
+  await page.locator('label[for="sidebar-drawer"][aria-label="Open navigation menu"]').click()
+  await expect(page.locator('#sidebar-drawer')).toBeChecked()
+
+  // daisyUI's drawer opens via a `visibility`/`opacity` CSS transition
+  // (`allow-discrete`, ~0.2-0.3s), not instantly when the checkbox flips —
+  // during that brief window the drawer is not yet paintable/hit-testable
+  // and elementFromPoint legitimately still returns the header underneath,
+  // exactly like a real user would see for a couple of frames. That is
+  // normal opening animation, not the H4 regression (a permanently wrong
+  // SETTLED z-index, not a transient mid-transition frame), so poll for the
+  // settled state instead of asserting on the very next frame.
+  const elementAtPoint = () =>
+    page.evaluate((p) => {
+      const el = document.elementFromPoint(p.x, p.y)
+      return {
+        insideHeader: !!el?.closest('header'),
+        insideDrawer: !!el?.closest('.drawer-side'),
+      }
+    }, point)
+
+  await expect
+    .poll(elementAtPoint, { message: 'drawer never settled above the header at the shared point' })
+    .toEqual({ insideHeader: false, insideDrawer: true })
+})
+
 // ---------------------------------------------------------------------------
 // F30 — accessible names, live region, table caption.
 // ---------------------------------------------------------------------------
diff --git a/scripts/test-api-e2e-cleanup-check.sh b/scripts/test-api-e2e-cleanup-check.sh
new file mode 100755
index 000000000..c661f7138
--- /dev/null
+++ b/scripts/test-api-e2e-cleanup-check.sh
@@ -0,0 +1,94 @@
+#!/bin/bash
+# T011a: proves that scripts/test-api-e2e.sh's cleanup trap only reaps the
+# process(es) THIS run started, and never a system-wide "mcpproxy"/
+# "launcher-server" pattern match. It starts a decoy `mcpproxy serve` on a
+# different port with its own scratch data dir and config, runs the full
+# E2E script, and asserts the decoy is still alive afterward — proving the
+# fix actually holds against a real invocation of the script, not just a
+# code read.
+#
+# Run from the repo root: ./scripts/test-api-e2e-cleanup-check.sh
+# Requires a built ./mcpproxy binary (the same prerequisite test-api-e2e.sh
+# itself has).
+
+set -uo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+DECOY_PORT="${DECOY_PORT:-18099}"
+DECOY_DIR="$(mktemp -d "${TMPDIR:-/tmp}/mcpproxy-e2e-cleanup-check.XXXXXX")"
+DECOY_CONFIG="$DECOY_DIR/config.json"
+DECOY_LOG="$DECOY_DIR/decoy.log"
+DECOY_PID=""
+
+cleanup_decoy() {
+    if [ -n "$DECOY_PID" ] && kill -0 "$DECOY_PID" 2>/dev/null; then
+        kill "$DECOY_PID" 2>/dev/null || true
+        sleep 1
+        kill -9 "$DECOY_PID" 2>/dev/null || true
+    fi
+    rm -rf "$DECOY_DIR"
+}
+trap cleanup_decoy EXIT
+
+if [ ! -f "./mcpproxy" ]; then
+    echo -e "${RED}Error: ./mcpproxy binary not found — build it first (go build -o mcpproxy ./cmd/mcpproxy)${NC}" >&2
+    exit 1
+fi
+
+if [ ! -f "./scripts/test-api-e2e.sh" ]; then
+    echo -e "${RED}Error: run this from the repo root (./scripts/test-api-e2e.sh not found)${NC}" >&2
+    exit 1
+fi
+
+cat > "$DECOY_CONFIG" <<EOF
+{
+  "listen": "127.0.0.1:${DECOY_PORT}",
+  "data_dir": "${DECOY_DIR}/data",
+  "enable_tray": false,
+  "enable_web_ui": false,
+  "api_key": "",
+  "mcpServers": []
+}
+EOF
+
+echo -e "${YELLOW}Starting decoy mcpproxy serve on :${DECOY_PORT} (scratch data dir ${DECOY_DIR})...${NC}"
+./mcpproxy serve --config="$DECOY_CONFIG" --log-level=error > "$DECOY_LOG" 2>&1 &
+DECOY_PID=$!
+
+# Wait for the decoy to come up.
+ready=0
+for _ in $(seq 1 30); do
+    if ! kill -0 "$DECOY_PID" 2>/dev/null; then
+        echo -e "${RED}Error: decoy mcpproxy exited early. Log:${NC}" >&2
+        cat "$DECOY_LOG" >&2
+        exit 1
+    fi
+    if curl -s -o /dev/null "http://127.0.0.1:${DECOY_PORT}/api/v1/status"; then
+        ready=1
+        break
+    fi
+    sleep 0.5
+done
+if [ "$ready" -ne 1 ]; then
+    echo -e "${RED}Error: decoy mcpproxy never became ready. Log:${NC}" >&2
+    cat "$DECOY_LOG" >&2
+    exit 1
+fi
+echo -e "${GREEN}Decoy running (pid=$DECOY_PID).${NC}"
+
+echo -e "${YELLOW}Running scripts/test-api-e2e.sh (its own cleanup trap must not touch the decoy)...${NC}"
+./scripts/test-api-e2e.sh
+e2e_exit=$?
+echo "scripts/test-api-e2e.sh exited with status $e2e_exit (not itself checked here — only decoy survival is)."
+
+if kill -0 "$DECOY_PID" 2>/dev/null && curl -s -o /dev/null "http://127.0.0.1:${DECOY_PORT}/api/v1/status"; then
+    echo -e "${GREEN}PASS: decoy mcpproxy (pid=$DECOY_PID, port ${DECOY_PORT}) survived the E2E run's cleanup trap.${NC}"
+    exit 0
+else
+    echo -e "${RED}FAIL: decoy mcpproxy (pid=$DECOY_PID, port ${DECOY_PORT}) did not survive the E2E run's cleanup trap.${NC}" >&2
+    exit 1
+fi
diff --git a/scripts/test-api-e2e.sh b/scripts/test-api-e2e.sh
index 1f0b7e168..cfe321833 100755
--- a/scripts/test-api-e2e.sh
+++ b/scripts/test-api-e2e.sh
@@ -48,10 +48,35 @@ echo "=============================="
 echo -e "${YELLOW}Using everything server for testing${NC}"
 echo ""
 
+# T011a: enumerate a process's descendants (recursively), by PID, so
+# cleanup() can reap exactly what THIS run started/spawned instead of
+# pattern-matching every "mcpproxy"/"launcher-server" process on the
+# machine. A blanket `pkill -f` would also kill the user's own tray-managed
+# core, or another worktree's parallel test run, whenever their command
+# line happens to match the same substring.
+descendant_pids() {
+    local parent="$1"
+    local children
+    children=$(pgrep -P "$parent" 2>/dev/null) || true
+    local pid
+    for pid in $children; do
+        echo "$pid"
+        descendant_pids "$pid"
+    done
+}
+
 # Cleanup function
 cleanup() {
     echo -e "\n${YELLOW}Cleaning up...${NC}"
 
+    # Snapshot descendants (e.g. the launcher-test fixture, spawned by
+    # mcpproxy itself) BEFORE we touch the parent — once mcpproxy exits,
+    # orphaned children are reparented and this parentage link is lost.
+    local orphan_candidates=""
+    if [ ! -z "$MCPPROXY_PID" ]; then
+        orphan_candidates=$(descendant_pids "$MCPPROXY_PID")
+    fi
+
     # Kill mcpproxy if running
     if [ ! -z "$MCPPROXY_PID" ]; then
         echo "Stopping mcpproxy (PID: $MCPPROXY_PID)"
@@ -76,11 +101,20 @@ cleanup() {
         fi
     fi
 
-    # Additional cleanup - find any remaining mcpproxy processes
-    pkill -f "mcpproxy.*serve" 2>/dev/null || true
-    # Reap the launcher-test fixture if our launcher-lifecycle test
-    # failed before the shutdown reap path could run.
-    pkill -f "launcher-server.*--port 39933" 2>/dev/null || true
+    # T011a: reap only the specific PIDs we saw as children of OUR
+    # mcpproxy process (e.g. the launcher-test fixture, if our
+    # launcher-lifecycle test failed before mcpproxy's own graceful
+    # shutdown reap path could run). Never a system-wide pattern match —
+    # that would also kill unrelated mcpproxy instances (the user's tray
+    # core, another worktree's E2E run, etc.). A PID we captured is only
+    # killed if it is still alive.
+    local pid
+    for pid in $orphan_candidates; do
+        if kill -0 "$pid" 2>/dev/null; then
+            echo "Reaping orphaned child process (PID: $pid)"
+            kill -9 "$pid" 2>/dev/null || true
+        fi
+    done
     sleep 1
 
     # Clean up test data

From df3d93cabadeb3e8233839562681ee62c1cca440 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 25 Sep 2026 23:36:20 +0300
Subject: [PATCH 08/27] fix: address review round 4
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round-4 zcode findings on the E2E cleanup trap (T011a) and a stale
Tools.vue stat-card bug. Confirmed genuine, fixed test-first:

- F3 (medium): descendant_pids had no test of its own. Extracted it to
  scripts/descendant-pids.sh (sourced by test-api-e2e.sh) and added
  scripts/descendant-pids.test.sh, a hermetic unit test that builds a
  real 3-level process tree and proves the recursive walk reaches a
  grandchild and great-grandchild, not just direct children. Also
  extended test-api-e2e-cleanup-check.sh to assert a REAL orphan of the
  run (the launcher-test fixture, left running by test_launcher_lifecycle
  Step 5) is actually gone after cleanup, not just that the decoy
  survives. Wired both scripts into the Makefile
  (test-descendant-pids, test-e2e-cleanup-check).
- F4 (medium): the audit_log sub-test's AUDIT_PID/AUDIT_DATA_DIR/
  AUDIT_JSONL_DIR/AUDIT_SERVER_LOG were only reaped on its own
  fall-through path; an early exit while that sub-test is running leaked
  them. cleanup() now reaps them too, idempotently.
- F1 (medium, partial fix): the descendant snapshot was taken once,
  before sending the kill signal, missing a child spawned during
  mcpproxy's own graceful-shutdown window. Now re-snapshotted on every
  poll of the wait loop while mcpproxy is confirmed still alive. The
  case where mcpproxy has already exited (crash/OOM) before cleanup()
  even runs is not fixable without reintroducing the system-wide pattern
  match T011a deliberately removed (kills unrelated mcpproxy instances)
  — documented as an accepted, narrow residual gap.
- F2 (low): the reap loop now records each descendant's command name at
  snapshot time and re-checks it before SIGKILL, so a PID reused by an
  unrelated process in the snapshot-to-reap window is skipped instead of
  killed.
- F6 (low): test-api-e2e-cleanup-check.sh's decoy port was a fixed
  default (only DECOY_DIR was made unique), colliding between concurrent
  runs. Now picks an OS-assigned free port.
- F7 (low): added --max-time to the two curl calls in
  test-api-e2e-cleanup-check.sh that lacked it, matching every curl call
  in test-api-e2e.sh.
- Tools.vue activeStatCard (low, flagged rounds 1 and 2, never actually
  fixed): it only inspected filterStatus, so an approval-only filter
  (filterStatus empty) still rang the Total stat card as active even
  though the table was filtered. Total now reads as active only when no
  filter narrows the table. New regression test:
  tools-active-stat-card-approval-only.spec.ts (reproduced the bug
  first, then fixed).

F5 (EXIT trap not firing on SIGINT) does not hold up under a faithful
reproduction: sending SIGINT to the actual process group (what a
terminal's Ctrl-C really delivers) already ran cleanup() correctly on
the pre-round-4 code, because the foreground child dies from the same
signal, bash's `wait` unblocks, and an untrapped terminating signal
still fires the EXIT trap. Verified this directly (group-wide kill -INT
and kill -TERM both fired the trap on the unmodified script; only a
single-PID kill -INT, which is not what a terminal sends, appeared to
hang, and that appearance was itself an artifact of test harness
backgrounding setting SIGINT to ignore). Kept explicit `trap ... INT
TERM` handlers anyway as harmless, idiomatic defense-in-depth for a
supervisor that signals only this process's PID, with an idempotent
cleanup() (CLEANUP_DONE guard) so it cannot double-run.

Verified locally: go build ./... clean (no Go files touched by this
commit); golangci-lint v2 (bare and --build-tags server) shows only
pre-existing unrelated findings; frontend build + full vitest run
(152 files / 1402 tests) green; scripts/descendant-pids.test.sh green;
a full scripts/test-api-e2e-cleanup-check.sh run against a real built
mcpproxy/mcpproxy-server passed all 70 E2E tests, confirmed the decoy
instance survived on a freshly-picked port, and confirmed the real
launcher-server orphan was reaped.
---
 Makefile                                      |  20 ++-
 frontend/src/views/Tools.vue                  |   7 +-
 ...ols-active-stat-card-approval-only.spec.ts |  55 ++++++++
 scripts/descendant-pids.sh                    |  37 ++++++
 scripts/descendant-pids.test.sh               |  85 ++++++++++++
 scripts/test-api-e2e-cleanup-check.sh         |  51 ++++++-
 scripts/test-api-e2e.sh                       | 125 ++++++++++++++++--
 7 files changed, 360 insertions(+), 20 deletions(-)
 create mode 100644 frontend/tests/unit/tools-active-stat-card-approval-only.spec.ts
 create mode 100755 scripts/descendant-pids.sh
 create mode 100755 scripts/descendant-pids.test.sh

diff --git a/Makefile b/Makefile
index 2dfd8a7c5..19850f833 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
 # MCPProxy Makefile
 
-.PHONY: help build build-server build-docker build-deb swagger swagger-verify frontend-build frontend-dev backend-dev clean test test-coverage test-e2e test-e2e-oauth lint dev-setup docs-setup docs-dev docs-build docs-clean bench-discovery
+.PHONY: help build build-server build-docker build-deb swagger swagger-verify frontend-build frontend-dev backend-dev clean test test-coverage test-e2e test-e2e-oauth test-descendant-pids test-e2e-cleanup-check lint dev-setup docs-setup docs-dev docs-build docs-clean bench-discovery
 
 SWAGGER_BIN ?= $(HOME)/go/bin/swag
 SWAGGER_OUT ?= oas
@@ -20,6 +20,8 @@ help:
 	@echo "  make test-coverage   - Run tests with coverage"
 	@echo "  make test-e2e        - Run all E2E tests"
 	@echo "  make test-e2e-oauth  - Run OAuth E2E tests with Playwright"
+	@echo "  make test-descendant-pids    - Unit test for the E2E cleanup trap's process-tree walk"
+	@echo "  make test-e2e-cleanup-check  - Integration test: E2E cleanup trap reaps only its own processes"
 	@echo "  make lint            - Run linter"
 	@echo "  make dev-setup       - Install development dependencies (swag, frontend, Playwright)"
 	@echo ""
@@ -176,6 +178,22 @@ test-e2e: test-e2e-oauth
 	@echo "🧪 Running E2E tests..."
 	./scripts/test-api-e2e.sh
 
+# Unit test for descendant_pids (scripts/descendant-pids.sh), the process-tree
+# walk the E2E cleanup trap uses to reap only what a run itself spawned.
+# Hermetic — no built binary required.
+test-descendant-pids:
+	@echo "🧪 Running descendant_pids unit test..."
+	./scripts/descendant-pids.test.sh
+
+# Integration test: proves the E2E cleanup trap reaps only what its own run
+# started (a decoy mcpproxy on another port survives) and that it actually
+# reaps a real orphan of the run (the launcher-test fixture). Requires a
+# built ./mcpproxy binary; not part of `test-e2e` since it re-runs the whole
+# E2E suite as a subprocess.
+test-e2e-cleanup-check:
+	@echo "🧪 Running E2E cleanup-trap safety check..."
+	./scripts/test-api-e2e-cleanup-check.sh
+
 # Documentation site commands
 docs-setup:
 	@echo "📦 Installing documentation dependencies..."
diff --git a/frontend/src/views/Tools.vue b/frontend/src/views/Tools.vue
index 503aeaa17..4c421cf5d 100644
--- a/frontend/src/views/Tools.vue
+++ b/frontend/src/views/Tools.vue
@@ -784,7 +784,12 @@ const hasActiveFilters = computed(() =>
 // these — it never sets filterApproval.
 type StatCard = 'total' | 'enabled' | 'disabled'
 
-const activeStatCard = computed<StatCard>(() => {
+// Review round 4: Total must only read as active when the table is truly
+// unfiltered. An approval-only filter (filterStatus empty) still narrows the
+// table, so none of Total/Enabled/Disabled correctly describes it — return
+// null rather than defaulting to 'total'.
+const activeStatCard = computed<StatCard | null>(() => {
+  if (filterApproval.value) return null
   if (filterStatus.value === 'enabled') return 'enabled'
   if (filterStatus.value === 'disabled') return 'disabled'
   return 'total'
diff --git a/frontend/tests/unit/tools-active-stat-card-approval-only.spec.ts b/frontend/tests/unit/tools-active-stat-card-approval-only.spec.ts
new file mode 100644
index 000000000..1cedf441b
--- /dev/null
+++ b/frontend/tests/unit/tools-active-stat-card-approval-only.spec.ts
@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import Tools from '@/views/Tools.vue'
+import api from '@/services/api'
+
+// Spec 109 PR-a review round 4 (low, first flagged round 1/2, never actually
+// fixed): activeStatCard only inspected filterStatus, defaulting to 'total'
+// whenever filterStatus was empty — even when filterApproval alone was
+// filtering the table. Setting Approval to e.g. "New, needs review" rang the
+// Total stat card as active even though the table below no longer shows all
+// tools. Total must only read as active when NO filter (status or approval)
+// is applied.
+
+vi.mock('@/services/api', () => ({
+  default: { getGlobalTools: vi.fn(), setToolEnabled: vi.fn() },
+}))
+
+const globalStubs = { CollapsibleHintsPanel: { template: '<div />' } }
+
+function mountView() {
+  return mount(Tools, { global: { plugins: [createPinia()], stubs: globalStubs } })
+}
+
+describe('Tools stat cards do not mislabel an approval-only filter as Total', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    ;(api.getGlobalTools as any).mockResolvedValue({
+      success: true,
+      data: {
+        stats: { total: 3, enabled: 3, disabled: 0, pending_approval: 2 },
+        tools: [
+          { name: 'new_tool', server_name: 's', approval_status: 'pending', enabled: true, description: '' },
+          { name: 'rugpull', server_name: 's', approval_status: 'changed', enabled: true, description: '' },
+          { name: 'fine', server_name: 's', approval_status: 'approved', enabled: true, description: '' },
+        ],
+      },
+    })
+  })
+
+  it('does not highlight Total once an approval filter narrows the table', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    const totalCard = wrapper.find('[data-test="stat-total"]')
+    expect(totalCard.classes()).toContain('ring-2')
+
+    const select = wrapper.find('[data-test="filter-approval"]')
+    await select.setValue('pending')
+    await flushPromises()
+
+    expect(wrapper.findAll('[data-test="tool-row"]').length).toBe(1)
+    expect(totalCard.classes()).not.toContain('ring-2')
+  })
+})
diff --git a/scripts/descendant-pids.sh b/scripts/descendant-pids.sh
new file mode 100755
index 000000000..550865cf2
--- /dev/null
+++ b/scripts/descendant-pids.sh
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# descendant-pids.sh — enumerate a process's descendants (recursively), by
+# PID. Extracted from test-api-e2e.sh (T011a review round 4, finding F3) so
+# it has a test of its own (descendant-pids.test.sh) instead of living
+# inline where only an end-to-end run could exercise it.
+#
+# Used by scripts/test-api-e2e.sh's cleanup() so it reaps exactly what THIS
+# run started/spawned instead of pattern-matching every
+# "mcpproxy"/"launcher-server" process on the machine. A blanket `pkill -f`
+# would also kill the user's own tray-managed core, or another worktree's
+# parallel test run, whenever their command line happens to match the same
+# substring.
+#
+# Usage:
+#   source scripts/descendant-pids.sh   # defines descendant_pids() for the caller
+#   ./scripts/descendant-pids.sh <pid>  # CLI: print descendants of <pid>, one per line
+
+descendant_pids() {
+    local parent="$1"
+    local children
+    children=$(pgrep -P "$parent" 2>/dev/null) || true
+    local pid
+    for pid in $children; do
+        echo "$pid"
+        descendant_pids "$pid"
+    done
+}
+
+# Only run the CLI wrapper when executed directly, not when sourced as a
+# library (test-api-e2e.sh sources this file for the function alone).
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+    if [ $# -ne 1 ]; then
+        echo "usage: $0 <pid>" >&2
+        exit 2
+    fi
+    descendant_pids "$1"
+fi
diff --git a/scripts/descendant-pids.test.sh b/scripts/descendant-pids.test.sh
new file mode 100755
index 000000000..1a13d8434
--- /dev/null
+++ b/scripts/descendant-pids.test.sh
@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# descendant-pids.test.sh — Spec 109 PR-a review round 4, finding F3:
+# descendant_pids (T011a) had no test of its own — only an end-to-end run
+# (test-api-e2e-cleanup-check.sh) ever exercised it, and that script only
+# proves the "don't kill unrelated processes" half, never that a multi-level
+# tree is walked correctly. This proves the recursive walk reaches a
+# grandchild and great-grandchild, not just direct children, and that a leaf
+# process (no children) returns empty.
+#
+# Hermetic: spawns only `sleep`/`bash` processes of its own, no mcpproxy
+# binary needed. Run directly: ./scripts/descendant-pids.test.sh
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./descendant-pids.sh
+source "$SCRIPT_DIR/descendant-pids.sh"
+
+pass=0
+fail=0
+check() { # desc, exit-status-of-previous-test (0 = pass)
+    if [ "$2" -eq 0 ]; then
+        echo "ok   - $1"
+        pass=$((pass + 1))
+    else
+        echo "FAIL - $1"
+        fail=$((fail + 1))
+    fi
+}
+
+# Build a real 3-level tree: OUTER (bash, direct child of this script) ->
+# MID (bash, its child) -> LEAF (sleep, MID's child). Each level uses `cmd &
+# wait` rather than a single simple command, so bash does not exec-optimize
+# the intermediate shells away (a single `bash -c "sleep N"` collapses into
+# the sleep process itself, losing the intermediate level).
+bash -c 'bash -c "sleep 25 & wait" & wait' &
+OUTER=$!
+
+# Wait for the tree to actually appear (avoids a fixed sleep racing process
+# creation on a loaded machine).
+MID=""
+for _ in $(seq 1 20); do
+    MID=$(pgrep -P "$OUTER" 2>/dev/null | head -1)
+    [ -n "$MID" ] && break
+    sleep 0.1
+done
+
+LEAF=""
+for _ in $(seq 1 20); do
+    LEAF=$(pgrep -P "$MID" 2>/dev/null | head -1)
+    [ -n "$LEAF" ] && break
+    sleep 0.1
+done
+
+cleanup_tree() {
+    kill -9 "$LEAF" "$MID" "$OUTER" 2>/dev/null || true
+}
+trap cleanup_tree EXIT
+
+[ -n "$MID" ]
+check "test fixture: MID (grandchild-to-be) actually spawned" $?
+[ -n "$LEAF" ]
+check "test fixture: LEAF (great-grandchild-to-be) actually spawned" $?
+
+result=$(descendant_pids "$$")
+
+echo "$result" | grep -qx "$OUTER"
+check "direct child (OUTER) is present" $?
+
+echo "$result" | grep -qx "$MID"
+check "grandchild (MID) is present" $?
+
+echo "$result" | grep -qx "$LEAF"
+check "great-grandchild (LEAF) is present" $?
+
+leaf_result=$(descendant_pids "$LEAF")
+[ -z "$leaf_result" ]
+check "leaf process (no children) returns empty" $?
+
+no_such_pid_result=$(descendant_pids "999999999")
+[ -z "$no_such_pid_result" ]
+check "nonexistent PID returns empty (no pgrep error leaks into output)" $?
+
+echo ""
+echo "Passed: $pass, Failed: $fail"
+[ "$fail" -eq 0 ]
diff --git a/scripts/test-api-e2e-cleanup-check.sh b/scripts/test-api-e2e-cleanup-check.sh
index c661f7138..9f49052d8 100755
--- a/scripts/test-api-e2e-cleanup-check.sh
+++ b/scripts/test-api-e2e-cleanup-check.sh
@@ -18,13 +18,27 @@ GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 NC='\033[0m'
 
-DECOY_PORT="${DECOY_PORT:-18099}"
+# Review round 4 (finding F6): a fixed default port collided between two
+# concurrent runs of this script (only DECOY_DIR was made unique via
+# mktemp), causing a flaky/misleading failure rather than a safety issue.
+# Ask the OS for an ephemeral free port instead, same trick used elsewhere
+# for scratch test instances (see memory reference_isolated_dev_instance).
+find_free_port() {
+    python3 -c 'import socket; s = socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1]); s.close()'
+}
+
+DECOY_PORT="${DECOY_PORT:-$(find_free_port)}"
 DECOY_DIR="$(mktemp -d "${TMPDIR:-/tmp}/mcpproxy-e2e-cleanup-check.XXXXXX")"
 DECOY_CONFIG="$DECOY_DIR/config.json"
 DECOY_LOG="$DECOY_DIR/decoy.log"
 DECOY_PID=""
+CLEANUP_DECOY_DONE=0
 
 cleanup_decoy() {
+    if [ "$CLEANUP_DECOY_DONE" = "1" ]; then
+        return
+    fi
+    CLEANUP_DECOY_DONE=1
     if [ -n "$DECOY_PID" ] && kill -0 "$DECOY_PID" 2>/dev/null; then
         kill "$DECOY_PID" 2>/dev/null || true
         sleep 1
@@ -32,6 +46,10 @@ cleanup_decoy() {
     fi
     rm -rf "$DECOY_DIR"
 }
+# See scripts/test-api-e2e.sh's cleanup trap for why INT/TERM are trapped
+# explicitly alongside EXIT (review round 4, finding F5).
+trap 'trap - EXIT; cleanup_decoy; exit 130' INT
+trap 'trap - EXIT; cleanup_decoy; exit 143' TERM
 trap cleanup_decoy EXIT
 
 if [ ! -f "./mcpproxy" ]; then
@@ -67,7 +85,11 @@ for _ in $(seq 1 30); do
         cat "$DECOY_LOG" >&2
         exit 1
     fi
-    if curl -s -o /dev/null "http://127.0.0.1:${DECOY_PORT}/api/v1/status"; then
+    # Review round 4 (finding F7): every curl call in the sibling
+    # test-api-e2e.sh uses --max-time; a wedged decoy (e.g. left over from a
+    # prior leaked run holding the same port) could otherwise hang this
+    # script indefinitely.
+    if curl -s --max-time 5 -o /dev/null "http://127.0.0.1:${DECOY_PORT}/api/v1/status"; then
         ready=1
         break
     fi
@@ -85,10 +107,31 @@ echo -e "${YELLOW}Running scripts/test-api-e2e.sh (its own cleanup trap must not
 e2e_exit=$?
 echo "scripts/test-api-e2e.sh exited with status $e2e_exit (not itself checked here — only decoy survival is)."
 
-if kill -0 "$DECOY_PID" 2>/dev/null && curl -s -o /dev/null "http://127.0.0.1:${DECOY_PORT}/api/v1/status"; then
+overall_pass=1
+
+if kill -0 "$DECOY_PID" 2>/dev/null && curl -s --max-time 5 -o /dev/null "http://127.0.0.1:${DECOY_PORT}/api/v1/status"; then
     echo -e "${GREEN}PASS: decoy mcpproxy (pid=$DECOY_PID, port ${DECOY_PORT}) survived the E2E run's cleanup trap.${NC}"
-    exit 0
 else
     echo -e "${RED}FAIL: decoy mcpproxy (pid=$DECOY_PID, port ${DECOY_PORT}) did not survive the E2E run's cleanup trap.${NC}" >&2
+    overall_pass=0
+fi
+
+# Review round 4 (finding F3): the decoy-survival check above only proves
+# the "don't kill unrelated processes" half. This proves the other half — a
+# REAL orphan of THIS run (the launcher-test fixture's child process,
+# test-api-e2e.sh's own test_launcher_lifecycle leaves it running again by
+# design, see its Step 5) is actually gone once the run's cleanup trap has
+# fired, regardless of whether mcpproxy's own graceful shutdown or the
+# T011a orphan-reap fallback is what reaped it.
+if pgrep -f 'launcher-server.*--port 39933' > /dev/null 2>&1; then
+    echo -e "${RED}FAIL: a launcher-server fixture process from the E2E run is still alive after cleanup.${NC}" >&2
+    overall_pass=0
+else
+    echo -e "${GREEN}PASS: the E2E run's own launcher-server fixture process was reaped.${NC}"
+fi
+
+if [ "$overall_pass" -eq 1 ]; then
+    exit 0
+else
     exit 1
 fi
diff --git a/scripts/test-api-e2e.sh b/scripts/test-api-e2e.sh
index cfe321833..1cba91d66 100755
--- a/scripts/test-api-e2e.sh
+++ b/scripts/test-api-e2e.sh
@@ -2,6 +2,8 @@
 
 # Note: Not using 'set -e' to allow tests to continue even if some fail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
 # Colors for output
 RED='\033[0;31m'
 GREEN='\033[0;32m'
@@ -54,27 +56,60 @@ echo ""
 # machine. A blanket `pkill -f` would also kill the user's own tray-managed
 # core, or another worktree's parallel test run, whenever their command
 # line happens to match the same substring.
-descendant_pids() {
+# Review round 4 (finding F3): extracted to its own file so it has a test of
+# its own (descendant-pids.test.sh) rather than living only where an
+# end-to-end run could reach it.
+# shellcheck source=./descendant-pids.sh
+source "$SCRIPT_DIR/descendant-pids.sh"
+
+# Review round 4 (finding F2): snapshot each descendant's command name
+# alongside its PID (as "pid:comm" lines), so the reap loop can verify a
+# captured PID still refers to the SAME process before SIGKILLing it — a
+# bare `kill -0` only proves the PID is alive, not that it wasn't reused by
+# an unrelated process in the window between snapshot and reap.
+snapshot_orphans_with_comm() {
     local parent="$1"
-    local children
-    children=$(pgrep -P "$parent" 2>/dev/null) || true
-    local pid
-    for pid in $children; do
-        echo "$pid"
-        descendant_pids "$pid"
+    local pid comm
+    for pid in $(descendant_pids "$parent"); do
+        comm=$(ps -o comm= -p "$pid" 2>/dev/null | tr -d ' ')
+        [ -n "$comm" ] && echo "${pid}:${comm}"
     done
 }
 
+# Review round 4 (finding F5): cleanup() is invoked both from the EXIT trap
+# and, below, from explicit INT/TERM handlers — guard against running the
+# body twice (an INT/TERM handler exits explicitly after calling cleanup,
+# which would otherwise also re-fire the EXIT trap).
+CLEANUP_DONE=0
+
 # Cleanup function
 cleanup() {
+    if [ "$CLEANUP_DONE" = "1" ]; then
+        return
+    fi
+    CLEANUP_DONE=1
+
     echo -e "\n${YELLOW}Cleaning up...${NC}"
 
     # Snapshot descendants (e.g. the launcher-test fixture, spawned by
     # mcpproxy itself) BEFORE we touch the parent — once mcpproxy exits,
     # orphaned children are reparented and this parentage link is lost.
+    # Review round 4 (finding F1, partial): a single snapshot only covers the
+    # instant before we send the kill signal — a child spawned during
+    # mcpproxy's own graceful-shutdown window (below) would otherwise never
+    # be captured, since once mcpproxy exits its children are reparented and
+    # pgrep -P can no longer find them via this PID. We keep re-snapshotting
+    # on every poll of the wait loop, while mcpproxy is confirmed still
+    # alive, to shrink that window to (effectively) zero. This cannot cover
+    # the case where mcpproxy has ALREADY exited (crash/OOM) by the time
+    # cleanup() first runs — its children are reparented before we ever get
+    # a PID to snapshot, and there is no way to recover that parentage link
+    # without reintroducing a system-wide pattern match, which T011a
+    # deliberately removed (see comment above) because it can kill unrelated
+    # mcpproxy instances. Accepted as a known, narrow residual gap.
     local orphan_candidates=""
     if [ ! -z "$MCPPROXY_PID" ]; then
-        orphan_candidates=$(descendant_pids "$MCPPROXY_PID")
+        orphan_candidates=$(snapshot_orphans_with_comm "$MCPPROXY_PID")
     fi
 
     # Kill mcpproxy if running
@@ -89,6 +124,10 @@ cleanup() {
                 echo "Process stopped gracefully"
                 break
             fi
+            # F1: re-snapshot while mcpproxy is still confirmed alive (see
+            # comment above the initial snapshot).
+            orphan_candidates="$orphan_candidates
+$(snapshot_orphans_with_comm "$MCPPROXY_PID")"
             sleep 1
             count=$((count + 1))
         done
@@ -100,6 +139,7 @@ cleanup() {
             sleep 1
         fi
     fi
+    orphan_candidates=$(echo "$orphan_candidates" | sort -u)
 
     # T011a: reap only the specific PIDs we saw as children of OUR
     # mcpproxy process (e.g. the launcher-test fixture, if our
@@ -107,16 +147,56 @@ cleanup() {
     # shutdown reap path could run). Never a system-wide pattern match —
     # that would also kill unrelated mcpproxy instances (the user's tray
     # core, another worktree's E2E run, etc.). A PID we captured is only
-    # killed if it is still alive.
-    local pid
-    for pid in $orphan_candidates; do
+    # killed if it is still alive AND its command name still matches what
+    # we recorded at snapshot time (review round 4, finding F2: `kill -0`
+    # alone proves liveness, not identity — in the 1-12+s window between
+    # snapshot and this reap loop, a captured PID could exit and be reused
+    # by an unrelated process, which a bare `kill -0` check would then have
+    # us SIGKILL).
+    local entry pid comm current_comm
+    for entry in $orphan_candidates; do
+        [ -z "$entry" ] && continue
+        pid="${entry%%:*}"
+        comm="${entry#*:}"
+        [ -z "$pid" ] && continue
         if kill -0 "$pid" 2>/dev/null; then
-            echo "Reaping orphaned child process (PID: $pid)"
-            kill -9 "$pid" 2>/dev/null || true
+            current_comm=$(ps -o comm= -p "$pid" 2>/dev/null | tr -d ' ')
+            if [ -n "$current_comm" ] && [ "$current_comm" = "$comm" ]; then
+                echo "Reaping orphaned child process (PID: $pid, $comm)"
+                kill -9 "$pid" 2>/dev/null || true
+            else
+                echo "Skipping PID $pid: process identity changed since snapshot ($comm -> $current_comm), likely PID reuse"
+            fi
         fi
     done
     sleep 1
 
+    # Review round 4 (finding F4): the audit_log sub-test's own instance and
+    # scratch dirs/log are normally torn down on its own fall-through path
+    # further down this script — but an early exit (Ctrl-C, a stray `exit`)
+    # while that sub-test is running would otherwise leak AUDIT_PID and its
+    # data/log/jsonl directories, since this trap never referenced them.
+    # These variables are declared later in the script; referencing them
+    # here before that point is safe (bash treats an unset variable as
+    # empty in this non-`set -u` script), and re-running this block after
+    # the sub-test's own cleanup already ran is a harmless no-op (the PID is
+    # already dead, the directories already removed).
+    if [ -n "${AUDIT_PID:-}" ] && kill -0 "$AUDIT_PID" 2>/dev/null; then
+        echo "Stopping audit-log instance (PID: $AUDIT_PID)"
+        kill "$AUDIT_PID" 2>/dev/null || true
+        sleep 1
+        kill -9 "$AUDIT_PID" 2>/dev/null || true
+    fi
+    if [ -n "${AUDIT_DATA_DIR:-}" ] && [ -d "$AUDIT_DATA_DIR" ]; then
+        rm -rf "$AUDIT_DATA_DIR"
+    fi
+    if [ -n "${AUDIT_JSONL_DIR:-}" ] && [ -d "$AUDIT_JSONL_DIR" ]; then
+        rm -rf "$AUDIT_JSONL_DIR"
+    fi
+    if [ -n "${AUDIT_SERVER_LOG:-}" ]; then
+        rm -f "$AUDIT_SERVER_LOG"
+    fi
+
     # Clean up test data
     if [ -d "$TEST_DATA_DIR" ]; then
         rm -rf "$TEST_DATA_DIR"
@@ -134,7 +214,24 @@ cleanup() {
     echo "Cleanup complete"
 }
 
-# Set up cleanup trap
+# Set up cleanup trap.
+# Review round 4 (finding F5): verified empirically (process-group-wide
+# signals, matching what a terminal actually delivers on Ctrl-C) that the
+# plain `trap cleanup EXIT` already ran cleanup correctly for both a real
+# Ctrl-C and a plain SIGTERM — the foreground child (sleep/curl) dies from
+# the same signal, bash's `wait` unblocks, and an untrapped terminating
+# signal still fires the EXIT trap on the way out. The narrower gap this
+# closes: a supervisor/orchestrator (not a terminal) that signals only this
+# script's own PID rather than its process group, in which case delivery is
+# deferred until the current foreground command finishes on its own either
+# way (per bash's documented trap semantics) — but explicit handlers make
+# the resulting exit code deliberate (130/143) instead of whatever bash's
+# default disposition produces, and this is the near-universal idiom for
+# these scripts regardless. `trap - EXIT` inside each handler removes the
+# EXIT trap before the explicit `exit`, so cleanup() (idempotent via
+# CLEANUP_DONE regardless) runs exactly once.
+trap 'trap - EXIT; cleanup; exit 130' INT
+trap 'trap - EXIT; cleanup; exit 143' TERM
 trap cleanup EXIT
 
 # Helper functions

From ef0bc4049189ea16650695fa4405ac1251a9cee6 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 02:36:52 +0300
Subject: [PATCH 09/27] fix: address review round 6

Verify each round-6 finding against the code before fixing; fix genuine
ones test-first, reject/defer two that are out of scope here.

1. internal/index/bleve.go (finding 1, high): an index created before the
   annotations_json field mapping existed keeps its old mapping forever
   after bleve.Open (no SetMapping in vendored bleve v2.6.1), so the
   differential-update backfill's annotations JSON gets indexed as free
   text via bleve's dynamic-field defaults, leaking into the field-less
   `_all` composite field and skewing BM25 ranking on any upgraded (not
   freshly installed) deployment. A full fix needs index-mapping-version
   tracking plus rebuild-from-storage, which doesn't exist yet
   (RebuildIndex is a stub) -- flagged as a follow-up task instead of
   building that here. Applied a bounded, tested mitigation:
   warnIfMappingPredatesAnnotations logs an actionable warning on open;
   toolMapping.Dynamic = false closes the whole bug class for indexes
   created from now on; and an explicit output_schema_json field mapping
   (previously undeclared, relying on the same dynamic fallback) closes a
   second, pre-existing instance of the same leak that surfaced only once
   Dynamic was turned off. New tests: bleve_mapping_migration_test.go.

2. cmd/mcpproxy/tools_cmd.go (finding 4, medium): --tier/--risk/--status/
   --approval were only ever applied on the global (no --server) tools-list
   path; `--server=x --tier destructive` silently printed every tool
   unfiltered. Client-mode (daemon-backed) now reuses
   applyGlobalToolFilters, since GET /api/v1/servers/{id}/tools shares
   enrichServerTools with the global endpoint and carries the same fields.
   Standalone (no-daemon) mode gets a new filterToolMetadataByTier for
   --tier (computed locally via contracts.AnnotationTier) and a fast,
   explicit error for --status/--approval, which need daemon-persisted
   state this path has no access to. A zcode re-review of this fix caught
   a residual message bug it introduced: emptying a non-empty standalone
   result via --tier fell into the "server doesn't support tools"
   diagnostic meant for a server with genuinely zero tools;
   standaloneNoToolsMessage now tells the two cases apart.

3. native/macos ServerBrowseView.swift / RegistryModels.swift (finding 2,
   medium): "Add to MCPProxy" -> "Added (checkmark) Open" state was tracked
   by bare server.id, while the same file's own cross-registry search
   dedupe already keys by "registry::id" (catalog ids collide across
   registries, MCP-866) -- two colliding cards from different registries
   could flip together. Added RepositoryServer.addedKey and switched both
   addedServers call sites to it. A zcode re-review found the same
   collision class still live in ForEach(results)'s SwiftUI identity and in
   addingID; fixed both, plus a stale doc comment that still described the
   bug this commit fixes.

4. frontend/src/components/AuthErrorModal.vue (finding 3, medium): the
   last dialog left on the old v-if/div modal pattern while its four
   siblings were migrated to the browser top layer (FR-055); a 401 raised
   while one of those is open painted underneath it. Migrated to a native
   <dialog> via the existing useDialogOpen/useModalA11y composables,
   deliberately without the click-catcher backdrop form the other dialogs
   use (clicking outside must not dismiss this one -- a pre-existing,
   audited rule). Replaced the onMounted form-reset with a
   watch(props.show), since the dialog no longer unmounts/remounts on
   every open/close the way the v-if version did.

5. scripts/test-api-e2e-cleanup-check.sh (finding 5, medium): the T011a
   proof's launcher-server pgrep check had no pre-run baseline, so a stray
   left by an earlier crashed run or a parallel worktree's own E2E run
   produced a false FAIL. Snapshots PIDs before running and diffs with
   comm -13 so only a genuinely new PID counts as this run's own leak.

Rejected (not fixed here):
- Finding 6 (specs/109-ux-navigation-consistency/tasks.md T026 vs macOS
  DashboardView.swift): tasks.md lives on branch docs/specs-108-109, not
  this branch, so it can't be edited from here. The same tasks.md's own
  "Follow-ups (not in this spec)" section already lists "a native macOS
  Usage view" as deferred future work, directly contradicting T026's
  in-scope macOS clause -- a spec/tasks inconsistency for whoever owns
  that branch to reconcile, not a reason to invent a new macOS chart
  feature inside a quick-wins PR. Flagged as a follow-up task.

Every fix is test-first: internal/index, cmd/mcpproxy and native/macos
each got new regression tests confirmed to fail before the fix (or, for
the macOS swift package which has no such build gate here, verified by
temporarily reverting and re-running) and pass after.

Reviewed with zcode (GLM), the mandated external reviewer for this
branch. It returned a clean pass on internal/index/bleve.go +
cmd/mcpproxy/tools_cmd.go (one residual message bug found and fixed, see
above), a clean pass with three genuine follow-ups on the macOS
ServerBrowseView/RegistryModels change (all three folded into this
commit), and a clean pass with no defects on
scripts/test-api-e2e-cleanup-check.sh. The AuthErrorModal.vue chunk could
not get a completed zcode pass despite five retries over ~20 minutes --
the shared zcode/GLM account was rate-limited (HTTP 429, "Rate limit
reached for requests") by concurrent sibling review sessions running the
same review round in parallel worktrees, not by anything in this diff.
Verified by hand instead, against the identical, already-shipped and
already-tested pattern in AddSecretModal.vue / AddServerModal.vue /
ConnectModal.vue / OnboardingWizard.vue, plus the full frontend build
(vue-tsc + vite) and vitest suite (152 files / 1402 tests, including
auth-single-surface.spec.ts) passing.

Local verification: go build ./...; go test -race on internal/index,
cmd/mcpproxy, internal/runtime (+ subpackages), and an internal/httpapi
tool/tier/search subset; golangci-lint v2 (bare and --build-tags server)
clean on every touched Go package, no new issues anywhere else; npm ci &&
npm run build && npx vitest run (152/152 files, 1402/1402 tests), then
package-lock.json left unchanged (no dependency changes); swift build +
swift test (one pre-existing, unrelated failure confirmed present with
and without this diff: AppLifecycleTests.
testTheSharedJournalNeverWritesToTheRealInstanceRootUnderTests).
---
 cmd/mcpproxy/tools_cmd.go                     |  86 +++++++++-
 cmd/mcpproxy/tools_cmd_test.go                | 155 ++++++++++++++++++
 frontend/src/components/AuthErrorModal.vue    |  66 ++++++--
 internal/index/bleve.go                       |  67 ++++++++
 .../index/bleve_mapping_migration_test.go     | 148 +++++++++++++++++
 .../MCPProxy/API/RegistryModels.swift         |  15 ++
 .../MCPProxy/Views/ServerBrowseView.swift     |  29 +++-
 .../ServerBrowseModelsTests.swift             |  28 ++++
 scripts/test-api-e2e-cleanup-check.sh         |  24 ++-
 9 files changed, 585 insertions(+), 33 deletions(-)
 create mode 100644 internal/index/bleve_mapping_migration_test.go

diff --git a/cmd/mcpproxy/tools_cmd.go b/cmd/mcpproxy/tools_cmd.go
index dba4a2d65..8acd47ff2 100644
--- a/cmd/mcpproxy/tools_cmd.go
+++ b/cmd/mcpproxy/tools_cmd.go
@@ -196,6 +196,55 @@ func applyGlobalToolFilters(tools []map[string]interface{}, statusFilter, tierFi
 	return out
 }
 
+// filterToolMetadataByTier applies --tier/--risk to the standalone-mode
+// (no-daemon) tool list, computing each tool's tier locally via
+// contracts.AnnotationTier — the same function the daemon's
+// enrichServerTools uses to populate the "tier" field applyGlobalToolFilters
+// reads. Unlike --status/--approval (rejected outright for standalone mode,
+// since those need daemon-persisted state this path never touches), tier
+// needs nothing but the tool's own annotations (review round 6, finding 4).
+// An empty tierFilter returns tools unchanged.
+func filterToolMetadataByTier(tools []*config.ToolMetadata, tierFilter string) []*config.ToolMetadata {
+	if tierFilter == "" {
+		return tools
+	}
+	filtered := make([]*config.ToolMetadata, 0, len(tools))
+	for _, tool := range tools {
+		if tool == nil {
+			continue
+		}
+		if strings.EqualFold(string(contracts.AnnotationTier(tool.Annotations)), tierFilter) {
+			filtered = append(filtered, tool)
+		}
+	}
+	return filtered
+}
+
+// standaloneNoToolsMessage is the table-mode diagnostic runToolsListStandalone
+// prints when the final tool list is empty.
+//
+// zcode review round 6 (backend fix for finding 4): before
+// filterToolMetadataByTier existed, this branch was reachable only when the
+// server genuinely exposed zero tools, so guessing "doesn't support tools /
+// not properly configured / connection issues" was reasonable. Once a
+// --tier/--risk filter can ALSO empty a non-empty discovery result, those
+// three guesses are all false for that case — telling an operator who ran
+// `--tier destructive` against a server that has tools, just none of that
+// tier, that the server "doesn't support tools" is the same misleading
+// signal finding 4 was originally about, one step further down the same
+// code path. discoveredCount is the count BEFORE tierFilter was applied.
+func standaloneNoToolsMessage(serverName, tierFilter string, discoveredCount int) string {
+	if tierFilter != "" && discoveredCount > 0 {
+		return fmt.Sprintf("No tools on server '%s' match --tier/--risk=%s (%d tool(s) discovered, none in that tier)\n",
+			serverName, tierFilter, discoveredCount)
+	}
+	return fmt.Sprintf("No tools found on server '%s'\n"+
+		"This could indicate:\n"+
+		"   Server doesn't support tools\n"+
+		"   Server is not properly configured\n"+
+		"   Connection issues during tool discovery\n", serverName)
+}
+
 // resolvedTierFilter returns the effective tier filter from --tier / --risk
 // (an alias of --tier, Spec 109 FR-028). --tier wins when both are set.
 func resolvedTierFilter() string {
@@ -738,6 +787,17 @@ func runToolsListClientMode(ctx context.Context, client *cliclient.Client, serve
 		return cliError("failed to get server tools from daemon", err)
 	}
 
+	// Apply the same --status/--tier(--risk)/--approval client-side filters as
+	// the global list. GET /api/v1/servers/{id}/tools shares enrichServerTools
+	// with the global endpoint (spec 050), so its maps carry the identical
+	// "tier"/"disabled"/"config_denied"/"approval_status" fields
+	// applyGlobalToolFilters reads — before this fix, `--server` bypassed
+	// filtering entirely and always printed every tool unfiltered (review
+	// round 6, finding 4: an operator auditing one server for destructive
+	// tools with `--server=x --tier destructive` saw the full unfiltered
+	// list and could wrongly conclude there were none).
+	tools = applyGlobalToolFilters(tools, toolsStatusFilter, resolvedTierFilter(), toolsApprovalFilter)
+
 	// Output results
 	return outputTools(tools, logger)
 }
@@ -787,6 +847,18 @@ func runToolsListStandalone(ctx context.Context, serverName string, globalConfig
 			serverName, getAvailableServerNames(globalConfig))
 	}
 
+	// --status and --approval read daemon-persisted state (per-tool disabled
+	// state, config-denied checks, approval records) that this standalone path
+	// has no access to — it connects directly to the upstream server and never
+	// touches the daemon's storage. Silently ignoring the flag would print
+	// every tool unfiltered with no indication the filter never ran (review
+	// round 6, finding 4); fail fast and say so instead. --tier/--risk is
+	// still honored below since it needs only the tool's own annotations.
+	if toolsStatusFilter != "" || toolsApprovalFilter != "" {
+		return fmt.Errorf("--status and --approval require the daemon (no running daemon detected for standalone server '%s'): "+
+			"start mcpproxy (mcpproxy serve) and retry, or drop these flags — --tier/--risk still works standalone", serverName)
+	}
+
 	// Human banner/progress goes to stderr so machine formats (-o json|yaml)
 	// keep stdout parseable (see docs/cli-output-formatting.md).
 	fmt.Fprintf(os.Stderr, "MCP Tools List - Server: %s\n", serverName)
@@ -843,15 +915,19 @@ func runToolsListStandalone(ctx context.Context, serverName string, globalConfig
 		return fmt.Errorf("failed to list tools: %w", err)
 	}
 
+	// Apply --tier/--risk (review round 6, finding 4). Unlike --status/
+	// --approval (rejected above), tier needs only the tool's own
+	// annotations — no daemon round trip — so it works standalone too, via
+	// the same AnnotationTier the daemon's enrichServerTools uses.
+	discoveredCount := len(tools)
+	tierFilter := resolvedTierFilter()
+	tools = filterToolMetadataByTier(tools, tierFilter)
+
 	// Output results using unified formatter
 	if len(tools) == 0 {
 		outputFormat := ResolveOutputFormat()
 		if outputFormat == "table" {
-			fmt.Printf("No tools found on server '%s'\n", serverName)
-			fmt.Printf("This could indicate:\n")
-			fmt.Printf("   Server doesn't support tools\n")
-			fmt.Printf("   Server is not properly configured\n")
-			fmt.Printf("   Connection issues during tool discovery\n")
+			fmt.Print(standaloneNoToolsMessage(serverName, tierFilter, discoveredCount))
 			return nil
 		}
 		// For JSON/YAML, output empty array
diff --git a/cmd/mcpproxy/tools_cmd_test.go b/cmd/mcpproxy/tools_cmd_test.go
index c0c66ab00..1e4be08ac 100644
--- a/cmd/mcpproxy/tools_cmd_test.go
+++ b/cmd/mcpproxy/tools_cmd_test.go
@@ -4,12 +4,15 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"runtime"
 	"strings"
 	"testing"
 	"time"
 
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/cliclient"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/socket"
 
@@ -484,3 +487,155 @@ func TestOutputGlobalTools_HeldColumn(t *testing.T) {
 	assert.Contains(t, outStr, "HELD", "table must contain the HELD column")
 	assert.Contains(t, outStr, "TPA-2026-0001", "held tool must surface its matched TPA signature")
 }
+
+// TestRunToolsListStandalone_RejectsStatusAndApprovalFilters is a regression
+// test for review round 6, finding 4: `--server` bypassed `--status`/
+// `--tier`/`--risk`/`--approval` filtering entirely (they were only ever
+// applied in the global, no-`--server` path), so `mcpproxy tools list
+// --server=x --tier destructive` silently printed every tool on that server
+// unfiltered — an operator auditing one server for destructive tools could
+// wrongly conclude there were none.
+//
+// The standalone (no-daemon) path has no access to the daemon-persisted
+// disabled/config-denied/approval state --status and --approval need, so
+// rather than silently ignoring them (the exact bug this finding reports),
+// it must fail fast with a clear, actionable error instead.
+func TestRunToolsListStandalone_RejectsStatusAndApprovalFilters(t *testing.T) {
+	origStatus, origApproval := toolsStatusFilter, toolsApprovalFilter
+	defer func() { toolsStatusFilter, toolsApprovalFilter = origStatus, origApproval }()
+
+	cfg := &config.Config{
+		Servers: []*config.ServerConfig{
+			{Name: "demo", Command: "true"},
+		},
+	}
+	logger := zap.NewNop()
+
+	toolsStatusFilter = "disabled"
+	toolsApprovalFilter = ""
+	err := runToolsListStandalone(context.Background(), "demo", cfg, logger)
+	require.Error(t, err, "--status must be rejected, not silently ignored, without a daemon")
+	assert.Contains(t, err.Error(), "--status and --approval require the daemon")
+
+	toolsStatusFilter = ""
+	toolsApprovalFilter = "pending"
+	err = runToolsListStandalone(context.Background(), "demo", cfg, logger)
+	require.Error(t, err, "--approval must be rejected, not silently ignored, without a daemon")
+	assert.Contains(t, err.Error(), "--status and --approval require the daemon")
+}
+
+// TestFilterToolMetadataByTier_ReviewRound6Finding4 covers the standalone
+// (no-daemon) half of the fix: --tier/--risk needs only the tool's own
+// annotations, computed locally via the same contracts.AnnotationTier the
+// daemon uses, so it is honored even without a daemon.
+func TestFilterToolMetadataByTier_ReviewRound6Finding4(t *testing.T) {
+	destructive := true
+	readOnly := true
+	tools := []*config.ToolMetadata{
+		{Name: "delete_repo", Annotations: &config.ToolAnnotations{DestructiveHint: &destructive}},
+		{Name: "list_repos", Annotations: &config.ToolAnnotations{ReadOnlyHint: &readOnly}},
+		{Name: "mystery_tool"},
+	}
+
+	assert.Equal(t, tools, filterToolMetadataByTier(tools, ""), "empty filter must return the list unchanged")
+
+	destructiveOnly := filterToolMetadataByTier(tools, "destructive")
+	require.Len(t, destructiveOnly, 1)
+	assert.Equal(t, "delete_repo", destructiveOnly[0].Name)
+
+	readOnlyOnly := filterToolMetadataByTier(tools, "read")
+	require.Len(t, readOnlyOnly, 1)
+	assert.Equal(t, "list_repos", readOnlyOnly[0].Name)
+
+	unannotatedOnly := filterToolMetadataByTier(tools, "unannotated")
+	require.Len(t, unannotatedOnly, 1)
+	assert.Equal(t, "mystery_tool", unannotatedOnly[0].Name)
+
+	assert.Empty(t, filterToolMetadataByTier(tools, "write"), "no tool is tier=write in this fixture")
+}
+
+// TestRunToolsListClientMode_AppliesTierFilter is the daemon-mode half of the
+// review round 6, finding 4 regression: `mcpproxy tools list --server=x
+// --tier destructive` against a running daemon used to print every tool on
+// that server, ignoring --tier entirely (only the global, no-`--server` path
+// ever called applyGlobalToolFilters). GET /api/v1/servers/{id}/tools shares
+// enrichServerTools with the global endpoint (spec 050), so its maps already
+// carry the same "tier" field — the fix is applying the identical filter,
+// not adding new data.
+func TestRunToolsListClientMode_AppliesTierFilter(t *testing.T) {
+	origTier, origRisk, origStatus, origApproval := toolsTierFilter, toolsRiskFilter, toolsStatusFilter, toolsApprovalFilter
+	defer func() {
+		toolsTierFilter, toolsRiskFilter, toolsStatusFilter, toolsApprovalFilter = origTier, origRisk, origStatus, origApproval
+	}()
+
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch r.URL.Path {
+		case "/api/v1/status":
+			_ = json.NewEncoder(w).Encode(map[string]interface{}{"success": true})
+		case "/api/v1/servers/demo/tools":
+			_ = json.NewEncoder(w).Encode(map[string]interface{}{
+				"success": true,
+				"data": map[string]interface{}{
+					"tools": []map[string]interface{}{
+						{"name": "delete_repo", "server_name": "demo", "tier": "destructive"},
+						{"name": "list_repos", "server_name": "demo", "tier": "read"},
+					},
+				},
+			})
+		default:
+			t.Errorf("unexpected request path %q", r.URL.Path)
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer ts.Close()
+
+	client := cliclient.NewClientWithAPIKey(ts.URL, "", nil)
+
+	setOutputGlobals(t, "json", false)
+	toolsTierFilter, toolsRiskFilter, toolsStatusFilter, toolsApprovalFilter = "destructive", "", "", ""
+
+	oldStdout := os.Stdout
+	r, w, _ := os.Pipe()
+	os.Stdout = w
+	defer func() { os.Stdout = oldStdout }()
+
+	err := runToolsListClientMode(context.Background(), client, "demo", zap.NewNop())
+
+	w.Close()
+	var buf bytes.Buffer
+	_, _ = buf.ReadFrom(r)
+	outStr := buf.String()
+
+	require.NoError(t, err)
+	assert.Contains(t, outStr, "delete_repo", "the destructive tool must survive --tier destructive")
+	assert.NotContains(t, outStr, "list_repos", "--server must filter out the non-matching tier just like the global list does")
+}
+
+// TestStandaloneNoToolsMessage_TierFilteredResult is a regression test for a
+// defect zcode's review round 6 found in the finding-4 fix itself: emptying
+// the standalone tool list via --tier/--risk fell into the same "no tools
+// found" branch as a server that genuinely has none, printing three false
+// diagnostic guesses ("doesn't support tools", "not properly configured",
+// "connection issues") for a server that has tools, just none in that tier.
+func TestStandaloneNoToolsMessage_TierFilteredResult(t *testing.T) {
+	msg := standaloneNoToolsMessage("demo", "destructive", 5)
+	assert.Contains(t, msg, "No tools on server 'demo' match --tier/--risk=destructive")
+	assert.Contains(t, msg, "5 tool(s) discovered")
+	assert.NotContains(t, msg, "doesn't support tools", "a tier-filtered empty result must not claim the server lacks tool support")
+	assert.NotContains(t, msg, "not properly configured")
+}
+
+// TestStandaloneNoToolsMessage_GenuinelyNoTools proves the original
+// diagnostic still appears when the server truly exposed zero tools (no
+// filter involved, or a filter with nothing to filter).
+func TestStandaloneNoToolsMessage_GenuinelyNoTools(t *testing.T) {
+	msg := standaloneNoToolsMessage("demo", "", 0)
+	assert.Contains(t, msg, "No tools found on server 'demo'")
+	assert.Contains(t, msg, "doesn't support tools")
+
+	// A tier filter with nothing discovered at all: still the generic
+	// message, since there is nothing to attribute to filtering.
+	msg = standaloneNoToolsMessage("demo", "destructive", 0)
+	assert.Contains(t, msg, "No tools found on server 'demo'")
+}
diff --git a/frontend/src/components/AuthErrorModal.vue b/frontend/src/components/AuthErrorModal.vue
index 578b06d35..cc581d45d 100644
--- a/frontend/src/components/AuthErrorModal.vue
+++ b/frontend/src/components/AuthErrorModal.vue
@@ -1,7 +1,13 @@
 <template>
-  <div v-if="show" class="modal modal-open">
-    <div class="modal-box max-w-2xl">
-      <h3 class="font-bold text-lg text-error mb-4">
+  <dialog ref="nativeDialogEl" class="modal" data-test="auth-error-modal">
+    <div
+      ref="dialogRef"
+      class="modal-box max-w-2xl"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="auth-error-modal-title"
+    >
+      <h3 id="auth-error-modal-title" class="font-bold text-lg text-error mb-4">
         🔒 Authentication Required
       </h3>
 
@@ -101,15 +107,21 @@
         </button>
       </div>
     </div>
-
-    <!-- Backdrop (clicking outside won't close to prevent accidental dismissal) -->
-    <div class="modal-backdrop bg-black/50"></div>
-  </div>
+    <!-- Deliberately no `<form method="dialog" class="modal-backdrop">` click
+         catcher here (contrast with AddSecretModal/AddServerModal/ConnectModal/
+         OnboardingWizard): clicking outside must not dismiss this modal, same
+         as before the FR-055 top-layer migration. The dim backdrop itself
+         still renders — `showModal()` promotes this dialog to the browser's
+         top layer with its native `::backdrop`, which daisyUI's `.modal`
+         styles independently of that click-catcher form. -->
+  </dialog>
 </template>
 
 <script setup lang="ts">
-import { ref, computed, onMounted } from 'vue'
+import { ref, computed, watch } from 'vue'
 import api from '@/services/api'
+import { useModalA11y } from '@/composables/useModalA11y'
+import { useDialogOpen } from '@/composables/useDialogOpen'
 
 interface Props {
   // Spec 107 T088 (App.vue): bound as `authModal.show || undefined` so the
@@ -134,6 +146,16 @@ const props = withDefaults(defineProps<Props>(), {
 
 const emit = defineEmits<Emits>()
 
+// Spec 109 FR-055 (review round 6, finding 3): promote to the browser's top
+// layer via showModal(), same as AddSecretModal/AddServerModal/ConnectModal/
+// OnboardingWizard, so a background 401 raised while one of those is open
+// paints above it instead of underneath its backdrop. Escape and the Tab trap
+// route through handleClose below, which already gates on `canClose` — so
+// Escape is a no-op while canClose is false, matching the Dismiss button's
+// own gating rather than adding a second copy of it here.
+const { dialogRef } = useModalA11y(() => props.show, () => handleClose())
+const { dialogEl: nativeDialogEl } = useDialogOpen(() => props.show, () => handleClose())
+
 // State
 const apiKeyInput = ref('')
 const inputError = ref('')
@@ -220,19 +242,27 @@ function handleClose() {
   }
 }
 
-// Initialize
-onMounted(() => {
-  // Clear any previous input when modal opens
-  apiKeyInput.value = ''
-  inputError.value = ''
-})
+// Reset the form each time the modal opens. Previously this lived in
+// onMounted, which was equivalent while the modal used `v-if="show"` —
+// closing and reopening destroyed and recreated the component, so
+// onMounted fired again on every open. The FR-055 top-layer migration
+// (review round 6, finding 3) keeps the <dialog> permanently mounted and
+// toggles it via showModal()/close() instead, so onMounted now fires only
+// once ever; without this watch, a stale error or leftover key from a
+// previous attempt would still be sitting there the next time the modal
+// is shown.
+watch(
+  () => props.show,
+  (open) => {
+    if (!open) return
+    apiKeyInput.value = ''
+    inputError.value = ''
+  },
+  { immediate: true }
+)
 </script>
 
 <style scoped>
-.modal-backdrop {
-  backdrop-filter: blur(2px);
-}
-
 code {
   font-family: 'Courier New', monospace;
   font-size: 0.875rem;
diff --git a/internal/index/bleve.go b/internal/index/bleve.go
index 512f7376a..b81a3c7d8 100644
--- a/internal/index/bleve.go
+++ b/internal/index/bleve.go
@@ -84,6 +84,7 @@ func newBleveIndexAt(indexPath string, logger *zap.Logger) (*BleveIndex, error)
 		}
 	} else {
 		logger.Info("Opened existing Bleve index", zap.String("path", indexPath))
+		warnIfMappingPredatesAnnotations(index, indexPath, logger)
 	}
 
 	return &BleveIndex{
@@ -93,6 +94,47 @@ func newBleveIndexAt(indexPath string, logger *zap.Logger) (*BleveIndex, error)
 	}, nil
 }
 
+// warnIfMappingPredatesAnnotations logs an actionable warning when an
+// already-existing index was created before the annotations_json field
+// mapping below (Spec 109 FR-028 tier-badge support) existed.
+//
+// bleve.Open never re-applies createBleveIndex's mapping to an index that
+// already exists on disk — the mapping is baked in at creation time, and
+// vendored bleve v2.6.1 exposes no SetMapping or other migration path
+// (confirmed by reading mapping.IndexMapping's method set). An index that
+// predates this field keeps its old mapping forever, with bleve's
+// dynamic-field defaults (IndexDynamic=true) still enabled for it: the very
+// first write that carries annotations_json (the differential-update
+// backfill in runtime/lifecycle.go) then gets indexed as free-text,
+// including into the field-less `_all` composite field that
+// buildToolSearchQuery's clause 5 (the bare MatchQuery) searches — silently
+// making annotation JSON term-searchable and shifting BM25 corpus stats for
+// every query on an upgraded (not freshly installed) deployment (review
+// round 6, finding 1: high).
+//
+// There is no safe in-place fix short of rebuilding the index, so this only
+// makes the situation observable. An operator who sees the warning can
+// delete indexPath and restart: the empty index makes every server's tools
+// look newly discovered, so the normal discovery path
+// (applyDifferentialToolUpdate) reindexes everything under the current,
+// correct mapping.
+func warnIfMappingPredatesAnnotations(idx bleve.Index, indexPath string, logger *zap.Logger) {
+	fm := idx.Mapping().FieldMappingForPath("annotations_json")
+	if fm.Type != "" {
+		// Explicitly mapped (Type is only set by NewTextFieldMapping and
+		// friends, never by the zero-value fallback FieldMappingForPath
+		// returns for a path with no static mapping) — this index already
+		// has the current mapping.
+		return
+	}
+	logger.Warn("Bleve index predates the annotations_json field mapping; "+
+		"annotation JSON may be indexed as free text and skew tool-search "+
+		"ranking (see internal/index/bleve.go:warnIfMappingPredatesAnnotations). "+
+		"Delete this index directory and restart mcpproxy to rebuild it "+
+		"with the current mapping.",
+		zap.String("path", indexPath))
+}
+
 // createBleveIndex creates a new Bleve index with proper mapping
 func createBleveIndex(indexPath string) (bleve.Index, error) {
 	// Create index mapping
@@ -100,6 +142,15 @@ func createBleveIndex(indexPath string) (bleve.Index, error) {
 
 	// Create document mapping for tools
 	toolMapping := bleve.NewDocumentMapping()
+	// Disable dynamic field mapping: every field this index ever writes is
+	// declared explicitly below. Without this, adding a new ToolDocument
+	// field in the future (as annotations_json itself was added, review
+	// round 6 finding 1) would silently fall back to bleve's dynamic-field
+	// defaults — full-text-indexed and included in `_all` — on any FRESH
+	// index too, not just ones migrating forward. This does not, and cannot,
+	// retroactively fix an already-open index created before this line
+	// existed; see warnIfMappingPredatesAnnotations above.
+	toolMapping.Dynamic = false
 
 	// Tool name field (both keyword and standard analyzers for different search types)
 	toolNameFieldKeyword := bleve.NewTextFieldMapping()
@@ -136,6 +187,22 @@ func createBleveIndex(indexPath string) (bleve.Index, error) {
 	paramsField.Index = true
 	toolMapping.AddFieldMappingsAt("params_json", paramsField)
 
+	// Output schema JSON field: stored only, never searched (it is JSON, not
+	// prose) — same shape as hash and annotations_json below. Previously had
+	// no explicit mapping at all and relied entirely on bleve's dynamic-field
+	// defaults to be stored for retrieval, which also meant it was
+	// full-text-indexed and folded into `_all` on every index, the same class
+	// of bug fixed for annotations_json by this mapping (review round 6,
+	// finding 1). Made explicit here, and required now that toolMapping.Dynamic
+	// is false above — Dynamic=false without this would stop
+	// GetToolsByServer/SearchTools from ever retrieving output_schema_json
+	// again, since Store also came from the dynamic fallback.
+	outputSchemaField := bleve.NewTextFieldMapping()
+	outputSchemaField.Analyzer = keyword.Name
+	outputSchemaField.Store = true
+	outputSchemaField.Index = false
+	toolMapping.AddFieldMappingsAt("output_schema_json", outputSchemaField)
+
 	// Hash field (keyword analyzer)
 	hashField := bleve.NewTextFieldMapping()
 	hashField.Analyzer = keyword.Name
diff --git a/internal/index/bleve_mapping_migration_test.go b/internal/index/bleve_mapping_migration_test.go
new file mode 100644
index 000000000..50151e995
--- /dev/null
+++ b/internal/index/bleve_mapping_migration_test.go
@@ -0,0 +1,148 @@
+package index
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/blevesearch/bleve/v2"
+	"github.com/blevesearch/bleve/v2/analysis/analyzer/keyword"
+	"github.com/blevesearch/bleve/v2/analysis/analyzer/standard"
+	"github.com/blevesearch/bleve/v2/mapping"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"go.uber.org/zap/zaptest/observer"
+)
+
+// preAnnotationsMapping replicates createBleveIndex's mapping as it existed
+// before the annotations_json field was added (Spec 109 PR-a), so tests can
+// simulate opening an index created by an older mcpproxy version.
+func preAnnotationsMapping() *mapping.IndexMappingImpl {
+	indexMapping := bleve.NewIndexMapping()
+	toolMapping := bleve.NewDocumentMapping()
+
+	toolNameFieldKeyword := bleve.NewTextFieldMapping()
+	toolNameFieldKeyword.Analyzer = keyword.Name
+	toolNameFieldKeyword.Store = true
+	toolNameFieldKeyword.Index = true
+	toolMapping.AddFieldMappingsAt("tool_name", toolNameFieldKeyword)
+
+	fullToolNameField := bleve.NewTextFieldMapping()
+	fullToolNameField.Analyzer = keyword.Name
+	fullToolNameField.Store = true
+	fullToolNameField.Index = true
+	toolMapping.AddFieldMappingsAt("full_tool_name", fullToolNameField)
+
+	serverNameField := bleve.NewTextFieldMapping()
+	serverNameField.Analyzer = keyword.Name
+	serverNameField.Store = true
+	serverNameField.Index = true
+	toolMapping.AddFieldMappingsAt("server_name", serverNameField)
+
+	descriptionField := bleve.NewTextFieldMapping()
+	descriptionField.Analyzer = standard.Name
+	descriptionField.Store = true
+	descriptionField.Index = true
+	toolMapping.AddFieldMappingsAt("description", descriptionField)
+
+	paramsField := bleve.NewTextFieldMapping()
+	paramsField.Analyzer = standard.Name
+	paramsField.Store = true
+	paramsField.Index = true
+	toolMapping.AddFieldMappingsAt("params_json", paramsField)
+
+	hashField := bleve.NewTextFieldMapping()
+	hashField.Analyzer = keyword.Name
+	hashField.Store = true
+	hashField.Index = false
+	toolMapping.AddFieldMappingsAt("hash", hashField)
+
+	// Deliberately no annotations_json field mapping: this is the point.
+
+	tagsField := bleve.NewTextFieldMapping()
+	tagsField.Analyzer = standard.Name
+	tagsField.Store = true
+	tagsField.Index = true
+	toolMapping.AddFieldMappingsAt("tags", tagsField)
+
+	searchableTextField := bleve.NewTextFieldMapping()
+	searchableTextField.Analyzer = standard.Name
+	searchableTextField.Store = false
+	searchableTextField.Index = true
+	toolMapping.AddFieldMappingsAt("searchable_text", searchableTextField)
+
+	indexMapping.AddDocumentMapping("tool", toolMapping)
+	indexMapping.DefaultMapping = toolMapping
+
+	return indexMapping
+}
+
+// TestNewBleveIndexAt_WarnsOnPreAnnotationsMapping is a regression test for
+// review round 6, finding 1 (high): opening an index created before the
+// annotations_json field mapping existed must surface a warning, since
+// bleve.Open never migrates the mapping and the resulting dynamic-field
+// leakage into full-text search is otherwise silent.
+func TestNewBleveIndexAt_WarnsOnPreAnnotationsMapping(t *testing.T) {
+	indexPath := filepath.Join(t.TempDir(), "index.bleve")
+
+	oldIdx, err := bleve.New(indexPath, preAnnotationsMapping())
+	require.NoError(t, err)
+	require.NoError(t, oldIdx.Close())
+
+	core, logs := observer.New(zap.WarnLevel)
+	logger := zap.New(core)
+
+	bi, err := newBleveIndexAt(indexPath, logger)
+	require.NoError(t, err)
+	defer bi.Close()
+
+	warnings := logs.FilterMessageSnippet("predates the annotations_json field mapping")
+	assert.Equal(t, 1, warnings.Len(), "opening a pre-annotations index must log exactly one actionable warning")
+}
+
+// TestNewBleveIndexAt_NoWarningOnCurrentMapping guards against a false
+// positive: an index created (or previously opened) by the CURRENT code must
+// never trigger the migration warning.
+func TestNewBleveIndexAt_NoWarningOnCurrentMapping(t *testing.T) {
+	indexPath := filepath.Join(t.TempDir(), "index.bleve")
+
+	core, logs := observer.New(zap.WarnLevel)
+	logger := zap.New(core)
+
+	// First open creates the index with the current mapping.
+	bi, err := newBleveIndexAt(indexPath, logger)
+	require.NoError(t, err)
+	require.NoError(t, bi.Close())
+
+	// Re-opening it (the common restart path) must not warn either.
+	bi2, err := newBleveIndexAt(indexPath, logger)
+	require.NoError(t, err)
+	defer bi2.Close()
+
+	warnings := logs.FilterMessageSnippet("predates the annotations_json field mapping")
+	assert.Equal(t, 0, warnings.Len(), "a current-mapping index must never trigger the migration warning")
+}
+
+// TestCreateBleveIndex_DynamicMappingDisabled locks in the defense-in-depth
+// half of the round-6 finding-1 fix: a freshly created index must not fall
+// back to bleve's dynamic-field defaults for an unmapped field, so adding a
+// future ToolDocument field without also updating createBleveIndex fails
+// loudly (the field is simply not indexed/stored) instead of silently
+// leaking into full-text search and `_all`, the way annotations_json did on
+// indexes created before this PR.
+func TestCreateBleveIndex_DynamicMappingDisabled(t *testing.T) {
+	indexPath := filepath.Join(t.TempDir(), "index.bleve")
+
+	idx, err := createBleveIndex(indexPath)
+	require.NoError(t, err)
+	defer idx.Close()
+
+	require.NoError(t, idx.Index("doc1", map[string]interface{}{
+		"tool_name":     "delete_everything",
+		"totally_novel": "should not become searchable via _all",
+	}))
+
+	res, err := idx.Search(bleve.NewSearchRequest(bleve.NewMatchQuery("should not become searchable via _all")))
+	require.NoError(t, err)
+	assert.Equal(t, uint64(0), res.Total, "an unmapped field must not be dynamically indexed once Dynamic=false")
+}
diff --git a/native/macos/MCPProxy/MCPProxy/API/RegistryModels.swift b/native/macos/MCPProxy/MCPProxy/API/RegistryModels.swift
index b2beadb86..e7e60e54c 100644
--- a/native/macos/MCPProxy/MCPProxy/API/RegistryModels.swift
+++ b/native/macos/MCPProxy/MCPProxy/API/RegistryModels.swift
@@ -197,6 +197,21 @@ struct RepositoryServer: Codable, Identifiable, Equatable {
         if let url, !url.isEmpty { return "remote" }
         return "stdio"
     }
+
+    /// Cross-registry identity key ("registry::id"), matching the format
+    /// `ServerBrowseView.search()`'s own de-dupe `seen` set uses. Catalog
+    /// entry ids are not unique across registries (MCP-866): two colliding
+    /// cards from different registries both surviving that registry-qualified
+    /// dedupe must not collapse onto a single bare-id key everywhere else the
+    /// browse view needs to remember "this exact card" — e.g. `addedServers`,
+    /// which tracks the "Add to MCPProxy" -> "Added ✓ · Open" transition per
+    /// card (Spec 109 FR-063). Keying that dict by bare `server.id` alone
+    /// flipped an unrelated, un-added card from a different registry to
+    /// "Added ✓ · Open" too, and routed its Open tap to the wrong server
+    /// (review round 6, finding 2).
+    var addedKey: String {
+        "\(registry ?? "")::\(id)"
+    }
 }
 
 /// Per-registry "unavailable" marker (e.g. key required). Mirrors
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift b/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
index 6cd4b927c..9b59da61e 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
@@ -23,11 +23,17 @@ struct ServerBrowseView: View {
     @State private var unavailable: [String] = []
     @State private var isSearching = false
     @State private var searchError: String?
+    /// Keyed by `RepositoryServer.addedKey` ("registry::id"), same as
+    /// `addedServers` below — review round 6, finding 2 follow-up (zcode):
+    /// keying this by bare `server.id` let two colliding cards from
+    /// different registries (MCP-866) show each other's spinner while only
+    /// one of them was actually being added.
     @State private var addingID: String?
     @State private var addNote: String?
-    /// Spec 109 FR-063: server.id -> the added server's name, so the button
-    /// can flip to "Added ✓ · Open" and stay that way for the rest of this
-    /// browse session.
+    /// Spec 109 FR-063: server.addedKey ("registry::id", not the bare
+    /// server.id — review round 6, finding 2) -> the added server's name, so
+    /// the button can flip to "Added ✓ · Open" and stay that way for the rest
+    /// of this browse session.
     @State private var addedServers: [String: String] = [:]
     @State private var registryInfo: RegistryInfoContext?
 
@@ -232,7 +238,14 @@ struct ServerBrowseView: View {
 
             ScrollView {
                 VStack(alignment: .leading, spacing: 8) {
-                    ForEach(results) { server in
+                    // Keyed by addedKey ("registry::id"), not the Identifiable
+                    // conformance's bare id: two colliding cards from
+                    // different registries (MCP-866) both surviving
+                    // search()'s registry-qualified dedupe would otherwise
+                    // share one SwiftUI identity here — undefined-behavior
+                    // view diffing, and colliding accessibility identifiers
+                    // below (review round 6, finding 2 follow-up, zcode).
+                    ForEach(results, id: \.addedKey) { server in
                         serverCard(server)
                     }
                 }
@@ -292,7 +305,7 @@ struct ServerBrowseView: View {
                 Spacer()
                 // Spec 109 FR-063: "Add to MCPProxy", flipping to a
                 // persistent "Added ✓ · Open" once the add succeeds.
-                if let addedName = addedServers[server.id] {
+                if let addedName = addedServers[server.addedKey] {
                     Button {
                         openServer(addedName)
                     } label: {
@@ -304,7 +317,7 @@ struct ServerBrowseView: View {
                     Button {
                         Task { await add(server) }
                     } label: {
-                        if addingID == server.id { ProgressView().controlSize(.small) } else { Text("Add to MCPProxy") }
+                        if addingID == server.addedKey { ProgressView().controlSize(.small) } else { Text("Add to MCPProxy") }
                     }
                     .controlSize(.small)
                     .disabled(addingID != nil || server.registry == nil)
@@ -372,7 +385,7 @@ struct ServerBrowseView: View {
 
     private func add(_ server: RepositoryServer) async {
         guard let client = apiClient, let reg = server.registry else { return }
-        addingID = server.id
+        addingID = server.addedKey
         addNote = nil
         let result = await client.addServerFromRegistry(registryID: reg, serverID: server.id)
         if result.success {
@@ -386,7 +399,7 @@ struct ServerBrowseView: View {
             // does not run (review round 2, finding 7).
             let assignedName = result.serverName ?? server.name
             addNote = "Added “\(server.name)”. New servers start quarantined — review under Servers."
-            addedServers[server.id] = assignedName
+            addedServers[server.addedKey] = assignedName
         } else if let missing = result.missingInputs, !missing.isEmpty {
             addNote = "“\(server.name)” needs input: \(missing.joined(separator: ", ")). Add it from the Web UI to supply those values."
         } else {
diff --git a/native/macos/MCPProxy/MCPProxyTests/ServerBrowseModelsTests.swift b/native/macos/MCPProxy/MCPProxyTests/ServerBrowseModelsTests.swift
index 6ced90db3..6292e756e 100644
--- a/native/macos/MCPProxy/MCPProxyTests/ServerBrowseModelsTests.swift
+++ b/native/macos/MCPProxy/MCPProxyTests/ServerBrowseModelsTests.swift
@@ -91,6 +91,34 @@ final class ServerBrowseModelsTests: XCTestCase {
         XCTAssertEqual(f.missingInputs, ["A"])
     }
 
+    // MARK: - addedKey (review round 6, finding 2: cross-registry id collision)
+
+    func testAddedKeyDisambiguatesSameIDAcrossRegistries() {
+        let a = server()
+        // Same bare `id` ("x", from the `server()` helper), different registry.
+        let b = RepositoryServer(id: "x", name: "x", description: nil, url: nil, sourceCodeURL: nil,
+                                  installCmd: nil, connectURL: nil, registry: "other", requiredInputs: nil)
+        XCTAssertNotEqual(a.addedKey, b.addedKey,
+                           "two catalog entries sharing an id across registries (MCP-866) must not collide")
+    }
+
+    func testAddedKeyStableForSameServer() {
+        let a = server()
+        let b = server()
+        XCTAssertEqual(a.addedKey, b.addedKey)
+    }
+
+    // zcode review round 6: pins the literal "registry::id" format so a future
+    // edit to addedKey or to search()'s own `seen` dedupe key in
+    // ServerBrowseView.swift can't drift the two apart without a test noticing
+    // — the two are required to match (see addedKey's doc comment).
+    func testAddedKeyMatchesSearchDedupeKeyFormat() {
+        let s = RepositoryServer(id: "io.github.x/y", name: "y", description: nil, url: nil,
+                                  sourceCodeURL: nil, installCmd: nil, connectURL: nil,
+                                  registry: "Reference Servers", requiredInputs: nil)
+        XCTAssertEqual(s.addedKey, "Reference Servers::io.github.x/y")
+    }
+
     // MARK: - encodeURIComponent-equivalent path encoder
 
     func testURIComponentEncodingEscapesSlashesAndSpaces() {
diff --git a/scripts/test-api-e2e-cleanup-check.sh b/scripts/test-api-e2e-cleanup-check.sh
index 9f49052d8..e70ac71ce 100755
--- a/scripts/test-api-e2e-cleanup-check.sh
+++ b/scripts/test-api-e2e-cleanup-check.sh
@@ -102,6 +102,15 @@ if [ "$ready" -ne 1 ]; then
 fi
 echo -e "${GREEN}Decoy running (pid=$DECOY_PID).${NC}"
 
+# Review round 6 (finding 5): snapshot PIDs matching the launcher-server
+# fixture's port BEFORE running test-api-e2e.sh. Without this baseline, the
+# T011a proof below fails on ANY matching process — including one leaked by
+# an earlier crashed/kill -9'd run (SIGKILL bypasses that run's own cleanup
+# trap) or a parallel worktree's own concurrent E2E run — even when THIS
+# run's cleanup behaved perfectly, and keeps failing until someone manually
+# reaps the stale process.
+baseline_launcher_pids="$(pgrep -f 'launcher-server.*--port 39933' 2>/dev/null | sort)"
+
 echo -e "${YELLOW}Running scripts/test-api-e2e.sh (its own cleanup trap must not touch the decoy)...${NC}"
 ./scripts/test-api-e2e.sh
 e2e_exit=$?
@@ -123,9 +132,20 @@ fi
 # design, see its Step 5) is actually gone once the run's cleanup trap has
 # fired, regardless of whether mcpproxy's own graceful shutdown or the
 # T011a orphan-reap fallback is what reaped it.
-if pgrep -f 'launcher-server.*--port 39933' > /dev/null 2>&1; then
-    echo -e "${RED}FAIL: a launcher-server fixture process from the E2E run is still alive after cleanup.${NC}" >&2
+#
+# Diffed against the baseline snapshot above (review round 6, finding 5): a
+# PID present both before and after this run is a pre-existing stray, not
+# something this run's cleanup failed to reap, and must not fail the proof —
+# only a PID that is NEW since the baseline counts as this run's own orphan.
+after_launcher_pids="$(pgrep -f 'launcher-server.*--port 39933' 2>/dev/null | sort)"
+new_launcher_pids="$(comm -13 <(printf '%s\n' "$baseline_launcher_pids") <(printf '%s\n' "$after_launcher_pids") | sed '/^$/d')"
+
+if [ -n "$new_launcher_pids" ]; then
+    echo -e "${RED}FAIL: a NEW launcher-server fixture process from this E2E run is still alive after cleanup (pid(s): $(echo "$new_launcher_pids" | tr '\n' ' ')).${NC}" >&2
     overall_pass=0
+elif [ -n "$baseline_launcher_pids" ]; then
+    echo -e "${YELLOW}WARN: a launcher-server fixture process matching this pattern (pid(s): $(echo "$baseline_launcher_pids" | tr '\n' ' ')) already existed BEFORE this run — a pre-existing stray from an earlier run, not counted against this run's cleanup. Consider reaping it manually.${NC}"
+    echo -e "${GREEN}PASS: this run did not leak a NEW launcher-server fixture process.${NC}"
 else
     echo -e "${GREEN}PASS: the E2E run's own launcher-server fixture process was reaped.${NC}"
 fi

From 05d03847315db9b9359e82fb242430d26738a46c Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 03:02:30 +0300
Subject: [PATCH 10/27] fix: address review round 7
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round 7 findings, verified against the code (zcode unavailable this
round: 5-hour usage limit, resets 10:35 — reviewed manually instead,
same as the finding's own note):

- frontend/src/composables/useDialogOpen.ts (high, confirmed): a
  showModal() dialog's own Escape handling fires a native `cancel`
  event and, unless that event is canceled, closes the dialog —
  independently of useModalA11y's document-level keydown listener,
  whose preventDefault() only affects the keydown event and does not
  stop the platform's cancel/close algorithm. AuthErrorModal relies on
  its close() being a no-op while canClose is false, but the native
  path ignored that gate entirely: Escape closed the <dialog> element
  regardless, desyncing it from isOpen() (same bricking shape as the
  existing H4 fix) and defeating the "must not be dismissable" intent
  the whole modal exists for. Fixed by always preventing the native
  `cancel` event in useDialogOpen and routing every Escape-driven close
  through the one close() callback that already owns the permission
  check, the same way useModalA11y's keydown handler does. Covered by
  frontend/tests/unit/use-dialog-open-cancel-prevented.spec.ts,
  confirmed red before the fix (dispatching a synthetic `cancel` event
  closed the dialog) and green after.

- internal/index/bleve.go (medium, confirmed, carried from round 6):
  round 6 only warned when an on-disk Bleve index predated the
  annotations_json field mapping, leaving an in-place upgrade with a
  silently stale mapping (and the resulting free-text/`_all` leakage)
  until an operator noticed the log line and deleted the directory by
  hand. Manager.RebuildIndex is a pre-existing unwired no-op stub, not
  a path to fix this. Replaced the warn-only function with one that
  closes the stale index, removes its directory, and creates a fresh
  one with the current mapping automatically — safe because
  index.bleve is a derived search cache, not a source of truth: an
  empty index makes every server's tools look newly discovered, and
  the normal discovery path (applyDifferentialToolUpdate) already
  reindexes everything as each server reconnects at startup, the same
  way it backfills a brand-new install. Extended
  bleve_mapping_migration_test.go with a regression test asserting the
  rebuilt index carries the current mapping and rejects free-text
  search on annotations_json, with no operator step.

- native/macos/MCPProxy/Views/DashboardView.swift (medium, carried
  from rounds 5-6): re-scoped rather than implemented. Spec 109 T026's
  "macOS DashboardView.swift equivalent label" describes the same
  integer-tick + "Calls to unknown tools" fix web's CallHistogram.vue
  got, but macOS has no per-tool call-histogram anywhere to attach it
  to — the file's only chart-like element (Token Distribution) is a
  per-server token-SIZE bar list with no ticked axis and no
  "unresolved tool name" concept, a different metric keyed by server
  name rather than call outcome. Spec 109's own tasks.md lists "a
  native macOS Usage view" as a Follow-up explicitly "not in this
  spec" — building one now would be new scope, not a quick win. Added
  an explanatory comment recording that scope decision next to
  tokenDistributionSection so this stops being silently re-flagged
  every round; tracked for the eventual macOS Usage view instead.

Verification: go build ./...; go test -race ./internal/index/...;
golangci-lint v2 (bare and --build-tags server) clean of new issues;
frontend npm ci + vitest run (153 files / 1405 tests green) + vue-tsc
build; swift build + swift test (1182 tests, 1 pre-existing failure —
AppLifecycleTests.testTheSharedJournalNeverWritesToTheRealInstanceRootUnderTests
fails on this machine because ~/.mcpproxy/tray-lifecycle.jsonl already
exists from real daily use, unrelated to and unaffected by this
comment-only Swift change; reproduces identically without it).
---
 frontend/src/composables/useDialogOpen.ts     |  34 +++++-
 .../use-dialog-open-cancel-prevented.spec.ts  | 108 ++++++++++++++++++
 internal/index/bleve.go                       |  59 +++++++---
 .../index/bleve_mapping_migration_test.go     |  38 ++++++
 .../MCPProxy/Views/DashboardView.swift        |  16 +++
 5 files changed, 238 insertions(+), 17 deletions(-)
 create mode 100644 frontend/tests/unit/use-dialog-open-cancel-prevented.spec.ts

diff --git a/frontend/src/composables/useDialogOpen.ts b/frontend/src/composables/useDialogOpen.ts
index 93cc8d2bf..e384f5928 100644
--- a/frontend/src/composables/useDialogOpen.ts
+++ b/frontend/src/composables/useDialogOpen.ts
@@ -31,6 +31,25 @@ import { onBeforeUnmount, ref, watch, type Ref } from 'vue'
  * `close` event the dialog fired *because we just called `close()`
  * ourselves* is told apart by `isOpen()` already reading `false` by the time
  * it fires, so it does not loop back into another call to `onClose`.
+ *
+ * Escape is handled twice, on purpose, and the two paths do not agree by
+ * accident — they are made to agree here. `useModalA11y`'s document-level
+ * `keydown` capture listener calls `preventDefault()` on the keydown event
+ * and then calls the caller's `close()` (which for a non-dismissable dialog,
+ * e.g. AuthErrorModal while `canClose` is false, is a no-op). That
+ * `preventDefault()` on `keydown` does NOT stop the browser's own
+ * Escape-dismiss algorithm for a `showModal()` dialog: per the HTML spec,
+ * pressing Escape on a modal `<dialog>` queues its own task to fire a
+ * `cancel` event and, unless *that* event is canceled, calls `close()` —
+ * independently of whatever the page's `keydown` listeners did. Left alone,
+ * that means the dialog visually disappears on Escape even when the caller's
+ * `close()` refused to close it (review round 7, finding 1): the native
+ * element ends up `closed` while `isOpen()` still reads `true`, and — same
+ * bricking shape as the H4 bug above — nothing reopens it. So every close
+ * driven by the platform's own Escape handling is suppressed here
+ * unconditionally, and routed back through the same `close()` the `keydown`
+ * listener already calls: if that decides to close, it flips `isOpen()`,
+ * and the `watch` below performs the actual (permitted) `el.close()`.
  */
 export function useDialogOpen(isOpen: () => boolean, onClose?: () => void) {
   const dialogEl: Ref<HTMLDialogElement | null> = ref(null)
@@ -58,17 +77,29 @@ export function useDialogOpen(isOpen: () => boolean, onClose?: () => void) {
     if (onClose && isOpen()) onClose()
   }
 
+  function handleCancel(event: Event) {
+    // Always block the browser's own Escape-triggered close. `useModalA11y`
+    // already owns Escape (it must, to run the Tab trap / focus-stack logic
+    // too) and calls the caller's `close()` on it; letting the platform also
+    // act on the same keypress double-handles it and, for a dialog whose
+    // `close()` is currently a no-op, closes it anyway (see comment above).
+    event.preventDefault()
+  }
+
   watch(isOpen, sync, { flush: 'post' })
 
   // Apply the initial state once the element has mounted (a plain immediate
   // watcher would run before the template ref is bound), and (re)attach the
-  // native `close` listener to whichever element is currently bound.
+  // native `close`/`cancel` listeners to whichever element is currently
+  // bound.
   watch(
     dialogEl,
     (el, prevEl) => {
       prevEl?.removeEventListener('close', handleNativeClose)
+      prevEl?.removeEventListener('cancel', handleCancel)
       if (el) {
         el.addEventListener('close', handleNativeClose)
+        el.addEventListener('cancel', handleCancel)
         sync(isOpen())
       }
     },
@@ -79,6 +110,7 @@ export function useDialogOpen(isOpen: () => boolean, onClose?: () => void) {
     const el = dialogEl.value
     if (!el) return
     el.removeEventListener('close', handleNativeClose)
+    el.removeEventListener('cancel', handleCancel)
     if (el.open && typeof el.close === 'function') el.close()
   })
 
diff --git a/frontend/tests/unit/use-dialog-open-cancel-prevented.spec.ts b/frontend/tests/unit/use-dialog-open-cancel-prevented.spec.ts
new file mode 100644
index 000000000..912fc3d08
--- /dev/null
+++ b/frontend/tests/unit/use-dialog-open-cancel-prevented.spec.ts
@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest'
+import { defineComponent, h, ref } from 'vue'
+import { mount, flushPromises } from '@vue/test-utils'
+import { useDialogOpen } from '@/composables/useDialogOpen'
+
+/**
+ * Review round 7, finding 1 (Spec 109 FR-055 follow-up): a `showModal()`
+ * dialog's own Escape handling fires a `cancel` event and, unless it is
+ * canceled, closes the dialog natively — independently of whatever a
+ * `keydown` listener did with `preventDefault()`. `useDialogOpen` must always
+ * cancel that native event so a non-dismissable dialog (canClose=false, as in
+ * AuthErrorModal) cannot be Escaped away out from under `isOpen()`, and so
+ * every dismissal is funneled through the one `close()` callback that owns
+ * the "is this allowed right now" decision.
+ *
+ * jsdom does not implement the platform's own Escape-to-cancel algorithm, so
+ * this dispatches the `cancel` event directly on the element — exactly the
+ * event a real browser fires — to exercise the listener under test.
+ */
+function polyfillNativeDialog(el: HTMLDialogElement) {
+  el.showModal = function (this: HTMLDialogElement) {
+    this.open = true
+  }
+  el.close = function (this: HTMLDialogElement) {
+    if (!this.open) return
+    this.open = false
+    this.dispatchEvent(new Event('close'))
+  }
+}
+
+function harness(onClose: () => void) {
+  const show = ref(false)
+
+  const Modal = defineComponent({
+    setup() {
+      const { dialogEl } = useDialogOpen(() => show.value, onClose)
+      return () =>
+        h('dialog', {
+          ref: (el: Element | null) => {
+            if (el) polyfillNativeDialog(el as HTMLDialogElement)
+            dialogEl.value = el as HTMLDialogElement | null
+          },
+        })
+    },
+  })
+
+  return { show, Modal }
+}
+
+describe('useDialogOpen cancel prevention (Spec 109 PR-a review round 7, finding 1)', () => {
+  it('prevents the native cancel event unconditionally', async () => {
+    const { show, Modal } = harness(() => {
+      show.value = false
+    })
+    const wrapper = mount(Modal, { attachTo: document.body })
+    show.value = true
+    await flushPromises()
+    const el = wrapper.element as HTMLDialogElement
+
+    const cancelEvent = new Event('cancel', { cancelable: true })
+    el.dispatchEvent(cancelEvent)
+
+    expect(cancelEvent.defaultPrevented).toBe(true)
+    wrapper.unmount()
+  })
+
+  it('keeps a non-dismissable dialog open when Escape is refused by close()', async () => {
+    // Mirrors AuthErrorModal's handleClose: a no-op while canClose is false.
+    const canClose = ref(false)
+    const { show, Modal } = harness(() => {
+      if (canClose.value) show.value = false
+    })
+    const wrapper = mount(Modal, { attachTo: document.body })
+    show.value = true
+    await flushPromises()
+    const el = wrapper.element as HTMLDialogElement
+    expect(el.open).toBe(true)
+
+    // The native cancel event fires on Escape regardless of what any keydown
+    // listener did; our handler must cancel it so `el.close()` never runs.
+    el.dispatchEvent(new Event('cancel', { cancelable: true }))
+    await flushPromises()
+
+    expect(el.open).toBe(true)
+    expect(show.value).toBe(true)
+    wrapper.unmount()
+  })
+
+  it('still lets a dismissable dialog close via the normal Escape/keydown path', async () => {
+    const { show, Modal } = harness(() => {
+      show.value = false
+    })
+    const wrapper = mount(Modal, { attachTo: document.body })
+    show.value = true
+    await flushPromises()
+    const el = wrapper.element as HTMLDialogElement
+    expect(el.open).toBe(true)
+
+    // The native cancel is still prevented (see first test), but the
+    // keydown-driven close() (simulated directly here) flips isOpen(), and
+    // the reactive watch performs the real, permitted el.close().
+    el.dispatchEvent(new Event('cancel', { cancelable: true }))
+    show.value = false
+    await flushPromises()
+
+    expect(el.open).toBe(false)
+  })
+})
diff --git a/internal/index/bleve.go b/internal/index/bleve.go
index b81a3c7d8..609aaba95 100644
--- a/internal/index/bleve.go
+++ b/internal/index/bleve.go
@@ -84,7 +84,10 @@ func newBleveIndexAt(indexPath string, logger *zap.Logger) (*BleveIndex, error)
 		}
 	} else {
 		logger.Info("Opened existing Bleve index", zap.String("path", indexPath))
-		warnIfMappingPredatesAnnotations(index, indexPath, logger)
+		index, err = rebuildIfMappingPredatesAnnotations(index, indexPath, logger)
+		if err != nil {
+			return nil, err
+		}
 	}
 
 	return &BleveIndex{
@@ -94,9 +97,10 @@ func newBleveIndexAt(indexPath string, logger *zap.Logger) (*BleveIndex, error)
 	}, nil
 }
 
-// warnIfMappingPredatesAnnotations logs an actionable warning when an
-// already-existing index was created before the annotations_json field
-// mapping below (Spec 109 FR-028 tier-badge support) existed.
+// rebuildIfMappingPredatesAnnotations replaces an already-open index whose
+// on-disk mapping was created before the annotations_json field mapping below
+// (Spec 109 FR-028 tier-badge support) existed, with a fresh index that has
+// the current mapping.
 //
 // bleve.Open never re-applies createBleveIndex's mapping to an index that
 // already exists on disk — the mapping is baked in at creation time, and
@@ -112,27 +116,50 @@ func newBleveIndexAt(indexPath string, logger *zap.Logger) (*BleveIndex, error)
 // every query on an upgraded (not freshly installed) deployment (review
 // round 6, finding 1: high).
 //
-// There is no safe in-place fix short of rebuilding the index, so this only
-// makes the situation observable. An operator who sees the warning can
-// delete indexPath and restart: the empty index makes every server's tools
-// look newly discovered, so the normal discovery path
-// (applyDifferentialToolUpdate) reindexes everything under the current,
-// correct mapping.
-func warnIfMappingPredatesAnnotations(idx bleve.Index, indexPath string, logger *zap.Logger) {
+// Round 6 only logged a warning and left the fix to an operator manually
+// deleting indexPath (review round 7, finding 2: the underlying gap was still
+// open on any upgrade nobody noticed the log line for). This does that same
+// recovery automatically instead: close the stale index, remove its
+// directory, and create a fresh one with the current mapping. That is safe
+// because index.bleve is a derived search cache, not a source of truth — an
+// empty index makes every server's tools look newly discovered, and the
+// normal discovery path (applyDifferentialToolUpdate) unconditionally
+// reindexes everything as each server (re)connects during startup, the same
+// way it already backfills a brand-new install.
+// Manager.RebuildIndex (internal/index/manager.go) is a separate, currently
+// unwired no-op stub for an operator-triggered full rebuild and is not used
+// here — this path only ever runs once, at index-open time, against a
+// mapping that is provably stale.
+func rebuildIfMappingPredatesAnnotations(idx bleve.Index, indexPath string, logger *zap.Logger) (bleve.Index, error) {
 	fm := idx.Mapping().FieldMappingForPath("annotations_json")
 	if fm.Type != "" {
 		// Explicitly mapped (Type is only set by NewTextFieldMapping and
 		// friends, never by the zero-value fallback FieldMappingForPath
 		// returns for a path with no static mapping) — this index already
 		// has the current mapping.
-		return
+		return idx, nil
 	}
+
 	logger.Warn("Bleve index predates the annotations_json field mapping; "+
-		"annotation JSON may be indexed as free text and skew tool-search "+
-		"ranking (see internal/index/bleve.go:warnIfMappingPredatesAnnotations). "+
-		"Delete this index directory and restart mcpproxy to rebuild it "+
-		"with the current mapping.",
+		"annotation JSON may have been indexed as free text and skewed "+
+		"tool-search ranking. Rebuilding the index automatically with the "+
+		"current mapping (see internal/index/bleve.go:rebuildIfMappingPredatesAnnotations).",
 		zap.String("path", indexPath))
+
+	if err := idx.Close(); err != nil {
+		return nil, fmt.Errorf("failed to close stale-mapping Bleve index for rebuild: %w", err)
+	}
+	if err := os.RemoveAll(indexPath); err != nil {
+		return nil, fmt.Errorf("failed to remove stale-mapping Bleve index at %s: %w", indexPath, err)
+	}
+	fresh, err := createBleveIndex(indexPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to recreate Bleve index after mapping migration: %w", err)
+	}
+
+	logger.Info("Rebuilt Bleve index with the current field mapping; "+
+		"tools will reappear as each server reconnects", zap.String("path", indexPath))
+	return fresh, nil
 }
 
 // createBleveIndex creates a new Bleve index with proper mapping
diff --git a/internal/index/bleve_mapping_migration_test.go b/internal/index/bleve_mapping_migration_test.go
index 50151e995..9bd3f0e3e 100644
--- a/internal/index/bleve_mapping_migration_test.go
+++ b/internal/index/bleve_mapping_migration_test.go
@@ -100,6 +100,44 @@ func TestNewBleveIndexAt_WarnsOnPreAnnotationsMapping(t *testing.T) {
 	assert.Equal(t, 1, warnings.Len(), "opening a pre-annotations index must log exactly one actionable warning")
 }
 
+// TestNewBleveIndexAt_AutoRebuildsPreAnnotationsMapping is a regression test
+// for review round 7, finding 2 (medium): round 6 only warned and left an
+// in-place-upgraded index with the old mapping (and its dynamic-field
+// leakage) in place forever unless an operator noticed the log line and
+// deleted the directory by hand. Opening a pre-annotations index must now
+// self-heal: end up with the current mapping with no manual step, and log
+// that the automatic rebuild happened.
+func TestNewBleveIndexAt_AutoRebuildsPreAnnotationsMapping(t *testing.T) {
+	indexPath := filepath.Join(t.TempDir(), "index.bleve")
+
+	oldIdx, err := bleve.New(indexPath, preAnnotationsMapping())
+	require.NoError(t, err)
+	require.NoError(t, oldIdx.Close())
+
+	core, logs := observer.New(zap.InfoLevel)
+	logger := zap.New(core)
+
+	bi, err := newBleveIndexAt(indexPath, logger)
+	require.NoError(t, err)
+	defer bi.Close()
+
+	fm := bi.index.Mapping().FieldMappingForPath("annotations_json")
+	assert.NotEmpty(t, fm.Type, "the index must carry the CURRENT mapping after opening a pre-annotations index, with no operator step")
+
+	rebuilds := logs.FilterMessageSnippet("Rebuilt Bleve index with the current field mapping")
+	assert.Equal(t, 1, rebuilds.Len(), "the automatic rebuild must be observable in the log")
+
+	// The rebuilt index must behave like any other current-mapping index:
+	// annotations_json is stored-only and must not leak into `_all`.
+	require.NoError(t, bi.index.Index("doc1", map[string]interface{}{
+		"tool_name":        "delete_everything",
+		"annotations_json": "should not become searchable via _all",
+	}))
+	res, err := bi.index.Search(bleve.NewSearchRequest(bleve.NewMatchQuery("should not become searchable via _all")))
+	require.NoError(t, err)
+	assert.Equal(t, uint64(0), res.Total, "annotations_json must not be free-text searchable after the rebuild")
+}
+
 // TestNewBleveIndexAt_NoWarningOnCurrentMapping guards against a false
 // positive: an index created (or previously opened) by the CURRENT code must
 // never trigger the migration warning.
diff --git a/native/macos/MCPProxy/MCPProxy/Views/DashboardView.swift b/native/macos/MCPProxy/MCPProxy/Views/DashboardView.swift
index 606a7ed47..4eb7ac0d2 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/DashboardView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/DashboardView.swift
@@ -431,6 +431,22 @@ struct DashboardView: View {
     }
 
     // MARK: - Token Distribution
+    //
+    // Spec 109 T026 ("macOS DashboardView.swift equivalent label") asks for
+    // the same fix as web's CallHistogram.vue: integer tick formatting and a
+    // "Calls to unknown tools" label for the excluded, never-completed-a-call
+    // name group. Re-scoped rather than implemented here (review round 7,
+    // finding 3, carried from rounds 5–6): that chart is a per-tool CALL
+    // COUNT histogram, and this Token Distribution bar list below is a
+    // per-server TOKEN SIZE distribution — a different metric with no ticked
+    // axis and no "unresolved tool name" concept to mislabel, since it is
+    // keyed by server name (`perServerToolListSizes`), not by tool call
+    // outcome. There is no native equivalent chart anywhere in native/macos/
+    // to attach the fix to (macOS has no per-tool call histogram at all), and
+    // Spec 109's own tasks.md explicitly lists "a native macOS Usage view" as
+    // a Follow-up "not in this spec" — building one to host this fix would be
+    // new scope, not a quick win. Tracked for that future macOS Usage view
+    // rather than bolted onto an unrelated chart here.
 
     @ViewBuilder
     private var tokenDistributionSection: some View {

From 9b7e1b1fce74656a2c23709bccc4d93c6df7511c Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 00:32:05 +0300
Subject: [PATCH 11/27] feat(catalog): add source-agnostic catalog search
 backend (Spec 109 FR-060/061/065)

- internal/registries/catalog.go: SearchAll fans out to every enabled
  registry in parallel with a per-source timeout, merges, de-dups by
  (source, id), ranks with the pure Rank function, and returns
  unavailable[] for failed/timed-out sources. Empty query returns
  official/popular sections.
- internal/secretlike: shared D13 secret-like-name heuristic.
- internal/shellwords: small quote-aware command-line tokenizer used to
  split an install command into CatalogInstall{command, args}.
- internal/secret/refname.go: RefName computes the FR-065 keyring ref
  name per field kind (env/header), with collision suffixing, pinned by
  the shared internal/secret/testdata/ref_names.json fixture.
- internal/secret: keyring provider now reports an availability reason
  (IsAvailableWithReason / Resolver.KeyringAvailability), surfaced by
  GET /secrets/config as keyring_available/keyring_reason.
- internal/httpapi/catalog.go: GET /catalog/search REST endpoint (no
  admin gate), with 'added' computed only over the caller's visible
  servers (FR-007).
---
 internal/httpapi/catalog.go                   | 173 ++++++++
 internal/httpapi/catalog_dto_test.go          | 116 ++++++
 internal/httpapi/catalog_test.go              | 137 ++++++
 .../httpapi/secrets_keyring_available_test.go |  62 +++
 internal/httpapi/server.go                    |  10 +
 internal/registries/catalog.go                | 392 ++++++++++++++++++
 internal/registries/catalog_bench_test.go     |  98 +++++
 internal/registries/catalog_test.go           | 202 +++++++++
 internal/registries/rank_test.go              |  75 ++++
 internal/registries/testhooks.go              |  34 ++
 internal/secret/keyring_available_test.go     |  75 ++++
 internal/secret/keyring_provider.go           |  30 ++
 internal/secret/refname.go                    |  64 +++
 internal/secret/refname_test.go               | 102 +++++
 internal/secret/resolver.go                   |  19 +
 internal/secret/testdata/ref_names.json       |  47 +++
 internal/secret/types.go                      |   7 +
 internal/secretlike/secretlike.go             |  19 +
 internal/secretlike/secretlike_test.go        |  29 ++
 internal/shellwords/shellwords.go             |  58 +++
 internal/shellwords/shellwords_test.go        |  41 ++
 21 files changed, 1790 insertions(+)
 create mode 100644 internal/httpapi/catalog.go
 create mode 100644 internal/httpapi/catalog_dto_test.go
 create mode 100644 internal/httpapi/catalog_test.go
 create mode 100644 internal/httpapi/secrets_keyring_available_test.go
 create mode 100644 internal/registries/catalog.go
 create mode 100644 internal/registries/catalog_bench_test.go
 create mode 100644 internal/registries/catalog_test.go
 create mode 100644 internal/registries/rank_test.go
 create mode 100644 internal/registries/testhooks.go
 create mode 100644 internal/secret/keyring_available_test.go
 create mode 100644 internal/secret/refname.go
 create mode 100644 internal/secret/refname_test.go
 create mode 100644 internal/secret/testdata/ref_names.json
 create mode 100644 internal/secretlike/secretlike.go
 create mode 100644 internal/secretlike/secretlike_test.go
 create mode 100644 internal/shellwords/shellwords.go
 create mode 100644 internal/shellwords/shellwords_test.go

diff --git a/internal/httpapi/catalog.go b/internal/httpapi/catalog.go
new file mode 100644
index 000000000..212db97c7
--- /dev/null
+++ b/internal/httpapi/catalog.go
@@ -0,0 +1,173 @@
+package httpapi
+
+import (
+	"context"
+	"net/http"
+	"strconv"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/contracts"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/registries"
+)
+
+// catalogSections is the REST-facing shape of the empty-query landing
+// sections (contracts/rest-api.md#catalog).
+type catalogSections struct {
+	Official []registries.CatalogResult `json:"official"`
+	Popular  []registries.CatalogResult `json:"popular"`
+}
+
+// catalogSearchResponse is the GET /catalog/search response body
+// (data-model §9, contracts/rest-api.md#catalog).
+type catalogSearchResponse struct {
+	Query       string                     `json:"query"`
+	Results     []registries.CatalogResult `json:"results"`
+	Sections    *catalogSections           `json:"sections"`
+	Unavailable []registries.SourceError   `json:"unavailable"`
+}
+
+// handleCatalogSearch godoc
+// @Summary      Search the server catalog across every enabled source
+// @Description  Fans out to every enabled catalog source (registry) in parallel, merges, de-duplicates and ranks the results (FR-060/061). An empty q returns official + popular sections instead of a flat list. Open to any authenticated caller — added is the only field filtered per caller scope (FR-007).
+// @Tags         catalog
+// @Produce      json
+// @Param        q       query  string  false  "Free-text search"
+// @Param        source  query  string  false  "Narrow to one catalog source id"
+// @Param        tag     query  string  false  "Filter by tag"
+// @Param        limit   query  int     false  "Max results (default 20, max 50)"
+// @Success      200  {object}  contracts.SuccessResponse
+// @Security     ApiKeyAuth
+// @Security     ApiKeyQuery
+// @Router       /api/v1/catalog/search [get]
+func (s *Server) handleCatalogSearch(w http.ResponseWriter, r *http.Request) {
+	q := r.URL.Query().Get("q")
+	source := r.URL.Query().Get("source")
+	tag := r.URL.Query().Get("tag")
+
+	limit := 20
+	if v := r.URL.Query().Get("limit"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			limit = n
+		}
+	}
+
+	hits, sections, unavailable := registries.SearchAll(r.Context(), q, tag, limit, registries.SearchOptions{})
+	if source != "" {
+		hits = filterCatalogHitsBySource(hits, source)
+		if sections != nil {
+			sections = &registries.CatalogSections{
+				Official: filterCatalogHitsBySource(sections.Official, source),
+				Popular:  filterCatalogHitsBySource(sections.Popular, source),
+			}
+		}
+	}
+
+	added := s.catalogAddedPredicate(r.Context())
+
+	resp := catalogSearchResponse{
+		Query:       q,
+		Results:     toCatalogResults(hits, added),
+		Unavailable: unavailable,
+	}
+	if unavailable == nil {
+		resp.Unavailable = []registries.SourceError{}
+	}
+	if sections != nil {
+		resp.Sections = &catalogSections{
+			Official: toCatalogResults(sections.Official, added),
+			Popular:  toCatalogResults(sections.Popular, added),
+		}
+	}
+
+	s.writeSuccess(w, resp)
+}
+
+func filterCatalogHitsBySource(hits []registries.CatalogHit, source string) []registries.CatalogHit {
+	out := make([]registries.CatalogHit, 0, len(hits))
+	for _, h := range hits {
+		if h.Source == source {
+			out = append(out, h)
+		}
+	}
+	return out
+}
+
+func toCatalogResults(hits []registries.CatalogHit, added func(registries.CatalogHit) bool) []registries.CatalogResult {
+	out := make([]registries.CatalogResult, 0, len(hits))
+	for _, h := range hits {
+		out = append(out, registries.ToCatalogResult(h, added(h)))
+	}
+	return out
+}
+
+// catalogAddedPredicate returns a function reporting whether a catalog hit is
+// already configured, joined only against the servers visible to ctx's caller
+// (FR-007, contracts/rest-api.md#catalog): "added" is computed only over
+// servers passing CanEnumerateServer, so a scoped caller never learns from
+// "added" that an out-of-scope server exists. A configured server with a
+// source_registry_id matches on (source, install target); one without (a
+// manual add) matches on install target alone.
+func (s *Server) catalogAddedPredicate(ctx context.Context) func(registries.CatalogHit) bool {
+	servers := s.getVisibleServersForCatalog(ctx)
+
+	// byRegistryAndTarget indexes servers that declare which registry they
+	// came from; bySourcelessTarget indexes every visible server (including
+	// registry-sourced ones) by install target alone, since a manual add has
+	// no source_registry_id and must still match.
+	byRegistryAndTarget := make(map[string]bool, len(servers))
+	byTargetOnly := make(map[string]bool, len(servers))
+	for _, srv := range servers {
+		target := catalogInstallTargetForServer(srv)
+		byTargetOnly[target] = true
+		if srv.SourceRegistryID != "" {
+			byRegistryAndTarget[srv.SourceRegistryID+"\x00"+target] = true
+		}
+	}
+
+	return func(h registries.CatalogHit) bool {
+		// added is never itself computed from the DTO's Added field (still
+		// false here) — only its Install target, which is pure derived data
+		// from the catalog entry.
+		target := registries.CatalogInstallTarget(registries.ToCatalogResult(h, false).Install)
+		if byRegistryAndTarget[h.Source+"\x00"+target] {
+			return true
+		}
+		return byTargetOnly[target]
+	}
+}
+
+// getVisibleServersForCatalog returns the servers the caller carried by ctx
+// may enumerate, preferring the management service (typed) and falling back
+// to the legacy generic path — the same two sources handleGetServers reads,
+// narrowed the same way (visibleServers).
+func (s *Server) getVisibleServersForCatalog(ctx context.Context) []contracts.Server {
+	var servers []contracts.Server
+	if mgmtSvc := s.controller.GetManagementService(); mgmtSvc != nil {
+		if list, _, err := mgmtSvc.ListServers(ctx); err == nil {
+			servers = make([]contracts.Server, 0, len(list))
+			for _, srv := range list {
+				if srv != nil {
+					servers = append(servers, *srv)
+				}
+			}
+		}
+	} else if generic, err := s.controller.GetAllServers(); err == nil {
+		servers = contracts.ConvertGenericServersToTyped(generic)
+	}
+	return visibleServers(ctx, servers)
+}
+
+// catalogInstallTargetForServer computes the same install-target key as
+// registries.CatalogInstallTarget, from a configured contracts.Server.
+func catalogInstallTargetForServer(srv contracts.Server) string {
+	if srv.URL != "" {
+		return "url:" + srv.URL
+	}
+	args := ""
+	for i, a := range srv.Args {
+		if i > 0 {
+			args += " "
+		}
+		args += a
+	}
+	return "cmd:" + srv.Command + " " + args
+}
diff --git a/internal/httpapi/catalog_dto_test.go b/internal/httpapi/catalog_dto_test.go
new file mode 100644
index 000000000..44d76bf2d
--- /dev/null
+++ b/internal/httpapi/catalog_dto_test.go
@@ -0,0 +1,116 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/registries"
+)
+
+// TestCatalogSearch_DTOShape is T101a: GET /catalog/search on a fixture
+// registry marshals exactly the contracts/rest-api.md#catalog example shape —
+// transport, install{url|command,args}, required_inputs[].secret_like, and
+// none of ServerEntry's own keys (url, installCmd, registry,
+// required_inputs[].secret).
+func TestCatalogSearch_DTOShape(t *testing.T) {
+	body := `[{
+		"id": "io.github.github/github-mcp-server",
+		"name": "GitHub",
+		"description": "…",
+		"url": "https://api.githubcopilot.com/mcp/",
+		"required_inputs": [{"name": "GITHUB_TOKEN"}]
+	}]`
+	src := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(body))
+	}))
+	defer src.Close()
+
+	t.Cleanup(registries.AllowPrivateRegistryFetchForTest())
+	t.Cleanup(registries.SetRegistriesForTest([]registries.RegistryEntry{
+		{ID: "official", Name: "Official", ServersURL: src.URL, Provenance: "official"},
+	}))
+
+	ctrl := &scopeController{cfg: scopeFixtureConfig(false), servers: nil, withManagement: true}
+	srv := NewServer(ctrl, zap.NewNop().Sugar(), nil)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/catalog/search?q=github", nil)
+	req.Header.Set("X-API-Key", scopeAdminAPIKey)
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+
+	var envelope struct {
+		Data struct {
+			Results []map[string]interface{} `json:"results"`
+		} `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &envelope))
+	require.Len(t, envelope.Data.Results, 1)
+	result := envelope.Data.Results[0]
+
+	require.Equal(t, "official", result["source"])
+	require.Equal(t, "io.github.github/github-mcp-server", result["id"])
+	require.Equal(t, "GitHub", result["title"])
+	require.Equal(t, true, result["official"])
+	require.Equal(t, "http", result["transport"])
+
+	install, ok := result["install"].(map[string]interface{})
+	require.True(t, ok, "install must be an object: %#v", result)
+	require.Equal(t, "https://api.githubcopilot.com/mcp/", install["url"])
+	require.NotContains(t, install, "command")
+	require.NotContains(t, install, "args")
+
+	inputs, ok := result["required_inputs"].([]interface{})
+	require.True(t, ok, "required_inputs must be an array: %#v", result)
+	require.Len(t, inputs, 1)
+	input, ok := inputs[0].(map[string]interface{})
+	require.True(t, ok)
+	require.Equal(t, "GITHUB_TOKEN", input["name"])
+	require.Equal(t, true, input["secret_like"])
+	require.NotContains(t, input, "secret", "CatalogInput must never reuse ServerEntry's own 'secret' key")
+
+	require.NotContains(t, result, "url", "CatalogResult must not carry ServerEntry's own 'url' key")
+	require.NotContains(t, result, "installCmd")
+	require.NotContains(t, result, "registry")
+	require.Equal(t, false, result["added"])
+}
+
+// TestServerEntryJSON_UnchangedByCatalog pins that registries.ServerEntry's
+// own JSON shape (url, installCmd, registry, required_inputs[].secret) is
+// untouched by the catalog DTO work — GET /registries/{id}/servers and MCP
+// search_servers keep serving it as-is (codex round 3, contracts/rest-api.md#catalog).
+func TestServerEntryJSON_UnchangedByCatalog(t *testing.T) {
+	entry := registries.ServerEntry{
+		ID:         "fs",
+		Name:       "Filesystem",
+		URL:        "https://example.com/mcp",
+		InstallCmd: "npx -y server-filesystem",
+		Registry:   "Official",
+		RequiredInputs: []registries.RequiredInput{
+			{Name: "GITHUB_TOKEN", Secret: true},
+		},
+	}
+	raw, err := json.Marshal(entry)
+	require.NoError(t, err)
+
+	var generic map[string]interface{}
+	require.NoError(t, json.Unmarshal(raw, &generic))
+
+	require.Equal(t, "https://example.com/mcp", generic["url"])
+	require.Equal(t, "npx -y server-filesystem", generic["installCmd"])
+	require.Equal(t, "Official", generic["registry"])
+
+	inputs, ok := generic["required_inputs"].([]interface{})
+	require.True(t, ok)
+	require.Len(t, inputs, 1)
+	input, ok := inputs[0].(map[string]interface{})
+	require.True(t, ok)
+	require.Equal(t, true, input["secret"])
+	require.NotContains(t, input, "secret_like", "ServerEntry's RequiredInput must never gain the catalog-only secret_like key")
+}
diff --git a/internal/httpapi/catalog_test.go b/internal/httpapi/catalog_test.go
new file mode 100644
index 000000000..c1550904f
--- /dev/null
+++ b/internal/httpapi/catalog_test.go
@@ -0,0 +1,137 @@
+package httpapi
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/contracts"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/registries"
+)
+
+// catalogTestServers/registries build a small, deterministic fixture:
+//   - "gamma" is a configured server visible to everyone, manually added (no
+//     source_registry_id), whose URL exactly matches the "official" source's
+//     "gamma-tool" entry — so it must read added:true for every caller.
+//   - "delta" is a configured server that the scoped token below may NOT see,
+//     added FROM the "official" source (source_registry_id="official") and
+//     matching the "delta-tool" entry.
+const (
+	catalogGammaURL          = "https://gamma.example.com/mcp"
+	catalogDeltaSecretMarker = "DELTA-ONLY-VALUE-1234"
+)
+
+func catalogFixtureServers() []contracts.Server {
+	return []contracts.Server{
+		{
+			ID:      "gamma",
+			Name:    "gamma",
+			URL:     catalogGammaURL,
+			Enabled: true,
+		},
+		{
+			ID:               "delta",
+			Name:             "delta",
+			Command:          "npx",
+			Args:             []string{"delta-server"},
+			Env:              map[string]string{"DELTA_TOKEN": catalogDeltaSecretMarker},
+			SourceRegistryID: "official",
+			Enabled:          true,
+		},
+	}
+}
+
+func withCatalogFixtureRegistry(t *testing.T) {
+	t.Helper()
+	body := `[
+		{"id":"gamma-tool","name":"Gamma Tool","url":"` + catalogGammaURL + `"},
+		{"id":"delta-tool","name":"Delta Tool","installCmd":"npx delta-server"}
+	]`
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(body))
+	}))
+	t.Cleanup(srv.Close)
+
+	t.Cleanup(registries.AllowPrivateRegistryFetchForTest())
+	t.Cleanup(registries.SetRegistriesForTest([]registries.RegistryEntry{
+		{ID: "official", Name: "Official", ServersURL: srv.URL},
+	}))
+}
+
+func TestCatalogSearch_OpenToScopedCaller(t *testing.T) {
+	withCatalogFixtureRegistry(t)
+	ctrl := &scopeController{cfg: scopeFixtureConfig(false), servers: catalogFixtureServers(), withManagement: true}
+	srv, token := scopedAgentServer(t, ctrl, []string{"gamma"})
+
+	rec := scopeGet(t, srv, "/api/v1/catalog/search?q=tool", token)
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+}
+
+func TestCatalogSearch_Unauthenticated401(t *testing.T) {
+	withCatalogFixtureRegistry(t)
+	ctrl := &scopeController{cfg: scopeFixtureConfig(false), servers: catalogFixtureServers(), withManagement: true}
+	srv, _ := scopedAgentServer(t, ctrl, []string{"gamma"})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/catalog/search", nil)
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+	require.Equal(t, http.StatusUnauthorized, rec.Code)
+}
+
+// TestCatalogSearch_AddedScopedByCallerVisibility pins FR-007: "added" is
+// computed only over servers the caller may enumerate, and a manually added
+// server matches by install target alone while a registry-sourced one also
+// needs a matching source.
+func TestCatalogSearch_AddedScopedByCallerVisibility(t *testing.T) {
+	withCatalogFixtureRegistry(t)
+	ctrl := &scopeController{cfg: scopeFixtureConfig(false), servers: catalogFixtureServers(), withManagement: true}
+	srv, token := scopedAgentServer(t, ctrl, []string{"gamma"})
+
+	// Admin sees both as added.
+	adminRec := scopeGet(t, srv, "/api/v1/catalog/search?q=tool", scopeAdminAPIKey)
+	require.Equal(t, http.StatusOK, adminRec.Code, adminRec.Body.String())
+	adminResults := catalogDecodeResults(t, adminRec)
+	assert.True(t, catalogAddedFor(adminResults, "gamma-tool"), "admin: expected gamma-tool added=true")
+	assert.True(t, catalogAddedFor(adminResults, "delta-tool"), "admin: expected delta-tool added=true")
+
+	// The scoped token (allowed: gamma only) sees gamma-tool added=true
+	// (manual match by target alone) but delta-tool added=false, because
+	// delta is out of its scope.
+	agentRec := scopeGet(t, srv, "/api/v1/catalog/search?q=tool", token)
+	require.Equal(t, http.StatusOK, agentRec.Code, agentRec.Body.String())
+	agentResults := catalogDecodeResults(t, agentRec)
+	assert.True(t, catalogAddedFor(agentResults, "gamma-tool"), "scoped: expected gamma-tool added=true")
+	assert.False(t, catalogAddedFor(agentResults, "delta-tool"), "scoped: expected delta-tool added=false (out of scope)")
+
+	// No configured server field (name, url, command, secret) leaks — the
+	// catalog entries only ever carry the source's own public data.
+	assert.NotContains(t, agentRec.Body.String(), catalogDeltaSecretMarker)
+}
+
+func catalogDecodeResults(t *testing.T, rec *httptest.ResponseRecorder) []map[string]interface{} {
+	t.Helper()
+	data := scopeDecodeData(t, rec)
+	raw, ok := data["results"].([]interface{})
+	require.True(t, ok, "no results array in %#v", data)
+	out := make([]map[string]interface{}, 0, len(raw))
+	for _, r := range raw {
+		m, ok := r.(map[string]interface{})
+		require.True(t, ok)
+		out = append(out, m)
+	}
+	return out
+}
+
+func catalogAddedFor(results []map[string]interface{}, id string) bool {
+	for _, r := range results {
+		if r["id"] == id {
+			added, _ := r["added"].(bool)
+			return added
+		}
+	}
+	return false
+}
diff --git a/internal/httpapi/secrets_keyring_available_test.go b/internal/httpapi/secrets_keyring_available_test.go
new file mode 100644
index 000000000..36e92ebad
--- /dev/null
+++ b/internal/httpapi/secrets_keyring_available_test.go
@@ -0,0 +1,62 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap/zaptest"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/secret"
+)
+
+// secretResolverController wraps MockServerController with a real
+// secret.Resolver so GET /secrets/config exercises the real
+// keyring-availability probe (FR-065) instead of the always-nil resolver the
+// bare mock returns.
+type secretResolverController struct {
+	*MockServerController
+	resolver *secret.Resolver
+}
+
+func (c *secretResolverController) GetSecretResolver() *secret.Resolver {
+	return c.resolver
+}
+
+func newSecretResolverTestServer(t *testing.T) *Server {
+	t.Helper()
+	logger := zaptest.NewLogger(t).Sugar()
+	controller := &secretResolverController{
+		MockServerController: &MockServerController{},
+		resolver:             secret.NewResolver(),
+	}
+	return NewServer(controller, logger, nil)
+}
+
+// TestGetConfigSecrets_KeyringAvailability pins FR-065: GET /secrets/config
+// reports keyring_available and, when false, a non-empty keyring_reason — a
+// CI runner has no usable OS keyring, so this also runs deterministically
+// under `go test`.
+func TestGetConfigSecrets_KeyringAvailability(t *testing.T) {
+	t.Setenv("CI", "true")
+	server := newSecretResolverTestServer(t)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/secrets/config", nil)
+	req.Header.Set("X-API-Key", mockControllerAPIKey)
+	rec := httptest.NewRecorder()
+	server.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+
+	var body struct {
+		Data struct {
+			KeyringAvailable bool   `json:"keyring_available"`
+			KeyringReason    string `json:"keyring_reason"`
+		} `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+	require.False(t, body.Data.KeyringAvailable, "expected keyring unavailable in CI")
+	require.NotEmpty(t, body.Data.KeyringReason, "expected a non-empty reason")
+}
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index 68a4835c8..4f497d414 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -1142,6 +1142,11 @@ func (s *Server) setupRoutes() {
 		r.Post("/registries/{id}/refresh", s.handleRefreshRegistryCache)                                                            // spec 070 FR-007
 		r.Post("/registries/{id}/servers/{serverId}/add", s.requireServerOp(auth.ServerOpAddFromRegistry, s.handleAddFromRegistry)) // spec 070 keystone add
 
+		// Catalog (Spec 109 FR-060): source-agnostic, ranked search across
+		// every enabled registry. Open like GET /registries/{id}/servers —
+		// "added" is the only field filtered per caller scope (FR-007).
+		r.Get("/catalog/search", s.handleCatalogSearch)
+
 		// Activity logging (RFC-003)
 		r.Get("/activity", s.handleListActivity)
 		r.Get("/activity/summary", s.handleActivitySummary)
@@ -4485,6 +4490,11 @@ func (s *Server) handleGetConfigSecrets(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
+	// FR-065: report whether the OS keyring is usable so the Paste/Manual/
+	// Catalog secret toggle can disable itself with the reason instead of
+	// failing silently on Add.
+	configSecrets.KeyringAvailable, configSecrets.KeyringReason = resolver.KeyringAvailability()
+
 	s.writeSuccess(w, configSecrets)
 }
 
diff --git a/internal/registries/catalog.go b/internal/registries/catalog.go
new file mode 100644
index 000000000..0a0e999b3
--- /dev/null
+++ b/internal/registries/catalog.go
@@ -0,0 +1,392 @@
+// Catalog (Spec 109 FR-060-067, data-model §9): a source-agnostic,
+// ranked view over every enabled registry ("catalog source"), fanned out in
+// parallel and merged into one ordered list. This is the shared backend for
+// GET /catalog/search, the CLI `catalog` command group and MCP
+// `search_servers` with `registry` omitted.
+package registries
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/secretlike"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/shellwords"
+)
+
+// Popularity carries a source's own popularity signal — stars for a
+// GitHub-hosted server, install/download counts otherwise. Either or both may
+// be nil; a source that reports neither leaves Popularity itself nil.
+type Popularity struct {
+	Stars    *int `json:"stars,omitempty"`
+	Installs *int `json:"installs,omitempty"`
+}
+
+// CatalogHit is the internal ranked catalog result (Go only, never
+// marshalled): it keeps the existing registries.ServerEntry untouched so
+// GET /registries/{id}/servers and MCP search_servers keep serving its JSON
+// unchanged (contracts/rest-api.md#catalog).
+type CatalogHit struct {
+	Entry      ServerEntry
+	Source     string
+	Title      string
+	Publisher  string
+	Verified   bool
+	Official   bool
+	Popularity *Popularity
+}
+
+// CatalogInstall is the REST/MCP install target: either a remote URL or a
+// local command + args, never both (data-model §9).
+type CatalogInstall struct {
+	URL     string   `json:"url,omitempty"`
+	Command string   `json:"command,omitempty"`
+	Args    []string `json:"args,omitempty"`
+}
+
+// CatalogInput is the REST DTO for one required input (FR-061), folding the
+// D13 name heuristic into SecretLike so a registry that omits or falsifies its
+// own isSecret flag still defaults the field to Secret (FR-065).
+type CatalogInput struct {
+	Name        string `json:"name"`
+	Description string `json:"description,omitempty"`
+	SecretLike  bool   `json:"secret_like"`
+}
+
+// CatalogResult is the GET /catalog/search response DTO (data-model §9),
+// built from a CatalogHit by ToCatalogResult. It is a distinct type from
+// ServerEntry so that type's JSON shape (url, installCmd, registry,
+// required_inputs[].secret) is never renamed.
+type CatalogResult struct {
+	Source         string         `json:"source"`
+	ID             string         `json:"id"`
+	Title          string         `json:"title"`
+	Publisher      string         `json:"publisher,omitempty"`
+	Verified       bool           `json:"verified"`
+	Official       bool           `json:"official"`
+	Popularity     *Popularity    `json:"popularity,omitempty"`
+	Description    string         `json:"description"`
+	Transport      string         `json:"transport"`
+	Install        CatalogInstall `json:"install"`
+	RequiredInputs []CatalogInput `json:"required_inputs,omitempty"`
+	SourceCodeURL  string         `json:"source_code_url,omitempty"`
+	Added          bool           `json:"added"`
+}
+
+// CatalogSections groups the empty-query landing results (FR-060): the
+// official-source hits and the top-popularity hits across every source, each
+// capped at catalogSectionCap. Internal (CatalogHit, not the REST DTO) —
+// callers convert with ToCatalogResult once they know each entry's Added
+// state (FR-007).
+type CatalogSections struct {
+	Official []CatalogHit
+	Popular  []CatalogHit
+}
+
+// SourceError records a catalog source that failed or timed out, surfaced as
+// GET /catalog/search's unavailable[] (FR-060).
+type SourceError struct {
+	Source string `json:"source"`
+	Reason string `json:"reason"`
+}
+
+// SearchOptions configures a catalog search. SourceTimeout defaults to 5s;
+// only tests set another value (T109a, SC-011).
+type SearchOptions struct {
+	SourceTimeout time.Duration
+}
+
+const (
+	defaultCatalogSourceTimeout = 5 * time.Second
+	catalogSectionCap           = 12
+	defaultCatalogLimit         = 10
+	maxCatalogLimit             = 50
+)
+
+// SearchAll fans SearchServers out to every enabled registry in parallel
+// (FR-060), each bounded by opts.SourceTimeout (default 5s), merges the
+// results, de-duplicates by (source, id), ranks them with Rank, and returns
+// unavailable[] for sources that failed or timed out. An empty q additionally
+// populates sections (official + popular, ≤ 12 each); a non-empty q leaves
+// sections nil.
+func SearchAll(ctx context.Context, q, tag string, limit int, opts SearchOptions) ([]CatalogHit, *CatalogSections, []SourceError) {
+	timeout := opts.SourceTimeout
+	if timeout <= 0 {
+		timeout = defaultCatalogSourceTimeout
+	}
+	if limit <= 0 {
+		limit = defaultCatalogLimit
+	}
+	if limit > maxCatalogLimit {
+		limit = maxCatalogLimit
+	}
+
+	sources := ListRegistries()
+
+	type sourceOutcome struct {
+		hits        []CatalogHit
+		unavailable *SourceError
+	}
+	outcomes := make([]sourceOutcome, len(sources))
+
+	var wg sync.WaitGroup
+	for i := range sources {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			reg := sources[i]
+			sctx, cancel := context.WithTimeout(ctx, timeout)
+			defer cancel()
+
+			entries, err := SearchServers(sctx, reg.ID, tag, q, limit, nil)
+			if err != nil {
+				reason := err.Error()
+				if sctx.Err() != nil {
+					reason = fmt.Sprintf("timeout after %s", timeout)
+				}
+				outcomes[i] = sourceOutcome{unavailable: &SourceError{Source: reg.ID, Reason: reason}}
+				return
+			}
+
+			hits := make([]CatalogHit, 0, len(entries))
+			for _, e := range entries {
+				hits = append(hits, buildCatalogHit(&reg, e))
+			}
+			outcomes[i] = sourceOutcome{hits: hits}
+		}(i)
+	}
+	wg.Wait()
+
+	seen := make(map[string]bool)
+	var all []CatalogHit
+	var unavailable []SourceError
+	for _, outcome := range outcomes {
+		if outcome.unavailable != nil {
+			unavailable = append(unavailable, *outcome.unavailable)
+			continue
+		}
+		for _, h := range outcome.hits {
+			key := h.Source + "\x00" + h.Entry.ID
+			if seen[key] {
+				continue
+			}
+			seen[key] = true
+			all = append(all, h)
+		}
+	}
+
+	sort.SliceStable(all, func(i, j int) bool { return Rank(all[i], all[j], q) })
+	sort.SliceStable(unavailable, func(i, j int) bool { return unavailable[i].Source < unavailable[j].Source })
+
+	if len(all) > limit {
+		all = all[:limit]
+	}
+
+	var sections *CatalogSections
+	if strings.TrimSpace(q) == "" {
+		sections = buildSections(all)
+	}
+
+	return all, sections, unavailable
+}
+
+// buildCatalogHit derives the catalog-only fields (Title, Publisher,
+// Verified, Official, Popularity) from a registry entry. Verified currently
+// tracks Official — no registry in this spec supplies an independent
+// publisher-verification signal yet, so a trusted (built-in) source's
+// namespace is the only verification evidence available (data-model §9,
+// research D12).
+func buildCatalogHit(reg *RegistryEntry, entry ServerEntry) CatalogHit {
+	official := reg.IsTrusted()
+	title := entry.Name
+	if title == "" {
+		title = entry.ID
+	}
+	return CatalogHit{
+		Entry:     entry,
+		Source:    reg.ID,
+		Title:     title,
+		Publisher: derivePublisher(entry.ID, reg.Name),
+		Verified:  official,
+		Official:  official,
+	}
+}
+
+// derivePublisher extracts a display publisher from an official-protocol
+// reverse-DNS id such as "io.github.github/github-mcp-server" (→ "github").
+// Falls back to the registry's own name when the id carries no such
+// namespace.
+func derivePublisher(id, registryName string) string {
+	slash := strings.IndexByte(id, '/')
+	if slash <= 0 {
+		return registryName
+	}
+	namespace := id[:slash]
+	if dot := strings.LastIndexByte(namespace, '.'); dot >= 0 && dot+1 < len(namespace) {
+		return namespace[dot+1:]
+	}
+	return registryName
+}
+
+// Rank is the pure, deterministic catalog ordering (data-model §9,
+// contracts/rest-api.md#catalog): official desc, verified desc, popularity
+// desc (missing = 0), text relevance desc, title asc, id asc. It reports
+// whether a sorts strictly before b.
+func Rank(a, b CatalogHit, q string) bool {
+	if a.Official != b.Official {
+		return a.Official
+	}
+	if a.Verified != b.Verified {
+		return a.Verified
+	}
+	if ap, bp := popularityScore(a.Popularity), popularityScore(b.Popularity); ap != bp {
+		return ap > bp
+	}
+	if ar, br := relevanceScore(a, q), relevanceScore(b, q); ar != br {
+		return ar > br
+	}
+	at, bt := strings.ToLower(catalogTitle(a)), strings.ToLower(catalogTitle(b))
+	if at != bt {
+		return at < bt
+	}
+	return a.Entry.ID < b.Entry.ID
+}
+
+func catalogTitle(h CatalogHit) string {
+	if h.Title != "" {
+		return h.Title
+	}
+	if h.Entry.Name != "" {
+		return h.Entry.Name
+	}
+	return h.Entry.ID
+}
+
+func popularityScore(p *Popularity) int {
+	if p == nil {
+		return 0
+	}
+	score := 0
+	if p.Stars != nil {
+		score += *p.Stars
+	}
+	if p.Installs != nil {
+		score += *p.Installs
+	}
+	return score
+}
+
+// relevanceScore is a simple, deterministic token-match count of q against
+// title/id/description — good enough to break ties below popularity, never
+// used as the primary key.
+func relevanceScore(h CatalogHit, q string) int {
+	q = strings.ToLower(strings.TrimSpace(q))
+	if q == "" {
+		return 0
+	}
+	score := 0
+	title := strings.ToLower(catalogTitle(h))
+	id := strings.ToLower(h.Entry.ID)
+	desc := strings.ToLower(h.Entry.Description)
+	if title == q {
+		score += 100
+	}
+	if strings.Contains(title, q) {
+		score += 10
+	}
+	if strings.Contains(id, q) {
+		score += 5
+	}
+	if strings.Contains(desc, q) {
+		score++
+	}
+	return score
+}
+
+// buildSections splits the already-ranked merged hits into the empty-query
+// landing sections (FR-060): official-source hits (in rank order) and the
+// top-popularity hits across every source, each capped at 12.
+func buildSections(ranked []CatalogHit) *CatalogSections {
+	sections := &CatalogSections{Official: []CatalogHit{}, Popular: []CatalogHit{}}
+	for _, h := range ranked {
+		if h.Official && len(sections.Official) < catalogSectionCap {
+			sections.Official = append(sections.Official, h)
+		}
+	}
+
+	byPopularity := append([]CatalogHit(nil), ranked...)
+	sort.SliceStable(byPopularity, func(i, j int) bool {
+		return popularityScore(byPopularity[i].Popularity) > popularityScore(byPopularity[j].Popularity)
+	})
+	for i := 0; i < len(byPopularity) && i < catalogSectionCap; i++ {
+		sections.Popular = append(sections.Popular, byPopularity[i])
+	}
+	return sections
+}
+
+// ToCatalogResult builds the REST DTO from an internal hit. added is computed
+// by the caller (httpapi layer, FR-007 scoped join) — SearchAll itself has no
+// notion of the calling caller's visibility.
+func ToCatalogResult(h CatalogHit, added bool) CatalogResult {
+	install, transport := toCatalogInstall(h.Entry)
+
+	var inputs []CatalogInput
+	for _, in := range DetectRequiredInputs(&h.Entry) {
+		inputs = append(inputs, CatalogInput{
+			Name:        in.Name,
+			Description: in.Description,
+			SecretLike:  in.Secret || secretlike.LooksSecret(in.Name),
+		})
+	}
+
+	return CatalogResult{
+		Source:         h.Source,
+		ID:             h.Entry.ID,
+		Title:          catalogTitle(h),
+		Publisher:      h.Publisher,
+		Verified:       h.Verified,
+		Official:       h.Official,
+		Popularity:     h.Popularity,
+		Description:    h.Entry.Description,
+		Transport:      transport,
+		Install:        install,
+		RequiredInputs: inputs,
+		SourceCodeURL:  h.Entry.SourceCodeURL,
+		Added:          added,
+	}
+}
+
+// toCatalogInstall derives the transport + install target from a
+// ServerEntry: a URL (or ConnectURL) is remote/http; otherwise InstallCmd is
+// split into command + args for a local/stdio install (data-model §9).
+func toCatalogInstall(entry ServerEntry) (CatalogInstall, string) {
+	url := entry.URL
+	if url == "" {
+		url = entry.ConnectURL
+	}
+	if url != "" {
+		return CatalogInstall{URL: url}, "http"
+	}
+	if entry.InstallCmd != "" {
+		parts, err := shellwords.Split(entry.InstallCmd)
+		if err == nil && len(parts) > 0 {
+			return CatalogInstall{Command: parts[0], Args: parts[1:]}, "stdio"
+		}
+	}
+	return CatalogInstall{}, "stdio"
+}
+
+// CatalogInstallTarget returns a stable string identifying an install's
+// target (a URL, or a command + args), used to join a catalog entry against a
+// configured server (contracts/rest-api.md#catalog "added"): a manually added
+// server matches on this alone, a catalog-added one also needs a matching
+// source_registry_id.
+func CatalogInstallTarget(install CatalogInstall) string {
+	if install.URL != "" {
+		return "url:" + install.URL
+	}
+	return "cmd:" + install.Command + " " + strings.Join(install.Args, " ")
+}
diff --git a/internal/registries/catalog_bench_test.go b/internal/registries/catalog_bench_test.go
new file mode 100644
index 000000000..d95842cd5
--- /dev/null
+++ b/internal/registries/catalog_bench_test.go
@@ -0,0 +1,98 @@
+package registries
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+// TestSearchAll_PerformanceBudget is the catalog half of SC-011: p95 of
+// SearchAll must stay within the per-source timeout plus the same 0.5s
+// overhead budget SC-011 allows over the 5s production default. Two sources
+// answer in 50ms; one never answers at all. The test sets SourceTimeout to
+// 500ms (rather than the 5s production default) so 20 runs stay fast, which
+// is exactly what SearchOptions.SourceTimeout exists for.
+func TestSearchAll_PerformanceBudget(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping timing-sensitive benchmark in -short mode")
+	}
+
+	fastBody := `[{"id":"a","name":"A"}]`
+	fast1 := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		time.Sleep(50 * time.Millisecond)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(fastBody))
+	}))
+	defer fast1.Close()
+	fast2 := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		time.Sleep(50 * time.Millisecond)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(fastBody))
+	}))
+	defer fast2.Close()
+
+	block := make(chan struct{})
+	defer close(block)
+	hung := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		select {
+		case <-block:
+		case <-r.Context().Done():
+		}
+	}))
+	defer hung.Close()
+
+	withTestRegistries(t, []RegistryEntry{
+		{ID: "fast1", Name: "Fast1", ServersURL: fast1.URL},
+		{ID: "fast2", Name: "Fast2", ServersURL: fast2.URL},
+		{ID: "hung", Name: "Hung", ServersURL: hung.URL},
+	})
+
+	const runs = 20
+	const sourceTimeout = 500 * time.Millisecond
+	const overheadBudget = 500 * time.Millisecond
+	durations := make([]time.Duration, 0, runs)
+
+	for i := 0; i < runs; i++ {
+		start := time.Now()
+		hits, _, unavailable := SearchAll(context.Background(), "", "", 10, SearchOptions{SourceTimeout: sourceTimeout})
+		durations = append(durations, time.Since(start))
+
+		foundFast1, foundFast2 := false, false
+		for _, h := range hits {
+			switch h.Source {
+			case "fast1":
+				foundFast1 = true
+			case "fast2":
+				foundFast2 = true
+			}
+		}
+		if !foundFast1 || !foundFast2 {
+			t.Fatalf("run %d: expected both fast sources' results, got %+v", i, hits)
+		}
+		if len(unavailable) != 1 || unavailable[0].Source != "hung" {
+			t.Fatalf("run %d: expected 'hung' listed unavailable, got %+v", i, unavailable)
+		}
+	}
+
+	p95 := percentile95(durations)
+	budget := sourceTimeout + overheadBudget
+	if p95 > budget {
+		t.Fatalf("p95 SearchAll duration %s exceeds budget %s (timeout %s + overhead %s)", p95, budget, sourceTimeout, overheadBudget)
+	}
+}
+
+func percentile95(d []time.Duration) time.Duration {
+	sorted := append([]time.Duration(nil), d...)
+	for i := 1; i < len(sorted); i++ {
+		for j := i; j > 0 && sorted[j-1] > sorted[j]; j-- {
+			sorted[j-1], sorted[j] = sorted[j], sorted[j-1]
+		}
+	}
+	idx := (len(sorted) * 95) / 100
+	if idx >= len(sorted) {
+		idx = len(sorted) - 1
+	}
+	return sorted[idx]
+}
diff --git a/internal/registries/catalog_test.go b/internal/registries/catalog_test.go
new file mode 100644
index 000000000..0c4f5f111
--- /dev/null
+++ b/internal/registries/catalog_test.go
@@ -0,0 +1,202 @@
+package registries
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+// withTestRegistries swaps registryList for the duration of a test.
+func withTestRegistries(t *testing.T, regs []RegistryEntry) {
+	t.Helper()
+	original := registryList
+	registryList = regs
+	t.Cleanup(func() { registryList = original })
+}
+
+func jsonServer(t *testing.T, body string) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(body))
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func hangingServer(t *testing.T) *httptest.Server {
+	t.Helper()
+	block := make(chan struct{})
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		select {
+		case <-block:
+		case <-r.Context().Done():
+		}
+	}))
+	t.Cleanup(func() {
+		close(block)
+		srv.Close()
+	})
+	return srv
+}
+
+// TestSearchAll_MergesAcrossSources pins the basic fan-out + merge (FR-060):
+// results from two healthy sources both appear.
+func TestSearchAll_MergesAcrossSources(t *testing.T) {
+	src1 := jsonServer(t, `[{"id":"one","name":"GitHub One","description":"d1"}]`)
+	src2 := jsonServer(t, `[{"id":"two","name":"GitHub Two","description":"d2"}]`)
+	withTestRegistries(t, []RegistryEntry{
+		{ID: "src1", Name: "Src1", ServersURL: src1.URL},
+		{ID: "src2", Name: "Src2", ServersURL: src2.URL},
+	})
+
+	hits, _, unavailable := SearchAll(context.Background(), "github", "", 10, SearchOptions{})
+	if len(unavailable) != 0 {
+		t.Fatalf("expected no unavailable sources, got %+v", unavailable)
+	}
+	if len(hits) != 2 {
+		t.Fatalf("expected 2 hits, got %d: %+v", len(hits), hits)
+	}
+	sources := map[string]bool{}
+	for _, h := range hits {
+		sources[h.Source] = true
+	}
+	if !sources["src1"] || !sources["src2"] {
+		t.Fatalf("expected hits from both sources, got %+v", sources)
+	}
+}
+
+// TestSearchAll_DedupsBySourceAndID pins the (source, id) de-dup rule.
+func TestSearchAll_DedupsBySourceAndID(t *testing.T) {
+	src := jsonServer(t, `[{"id":"dup","name":"Dup"},{"id":"dup","name":"Dup"}]`)
+	withTestRegistries(t, []RegistryEntry{{ID: "src", Name: "Src", ServersURL: src.URL}})
+
+	hits, _, _ := SearchAll(context.Background(), "", "", 10, SearchOptions{})
+	count := 0
+	for _, h := range hits {
+		if h.Entry.ID == "dup" {
+			count++
+		}
+	}
+	if count != 1 {
+		t.Fatalf("expected the duplicate id to collapse to 1 hit, got %d", count)
+	}
+}
+
+// TestSearchAll_SourceTimeoutMarkedUnavailable pins FR-060: a hung source
+// times out and is reported unavailable, while the other sources' results
+// still come back.
+func TestSearchAll_SourceTimeoutMarkedUnavailable(t *testing.T) {
+	slow := hangingServer(t)
+	fast := jsonServer(t, `[{"id":"ok","name":"OK"}]`)
+	withTestRegistries(t, []RegistryEntry{
+		{ID: "slow", Name: "Slow", ServersURL: slow.URL},
+		{ID: "fast", Name: "Fast", ServersURL: fast.URL},
+	})
+
+	hits, _, unavailable := SearchAll(context.Background(), "", "", 10, SearchOptions{SourceTimeout: 200 * time.Millisecond})
+	if len(unavailable) != 1 || unavailable[0].Source != "slow" {
+		t.Fatalf("expected 'slow' to be reported unavailable, got %+v", unavailable)
+	}
+	if unavailable[0].Reason == "" {
+		t.Fatal("expected a non-empty reason")
+	}
+	found := false
+	for _, h := range hits {
+		if h.Source == "fast" {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("expected the fast source's results despite the slow one timing out, got %+v", hits)
+	}
+}
+
+// TestSearchAll_EmptyQueryReturnsSections pins FR-060: an empty q returns
+// official + popular sections (≤ 12 each), capped and populated.
+func TestSearchAll_EmptyQueryReturnsSections(t *testing.T) {
+	official := jsonServer(t, `[{"id":"a","name":"A"}]`)
+	custom := jsonServer(t, `[{"id":"b","name":"B"}]`)
+	withTestRegistries(t, []RegistryEntry{
+		{ID: "official-src", Name: "Official", ServersURL: official.URL, Provenance: "official"},
+		{ID: "custom-src", Name: "Custom", ServersURL: custom.URL, Provenance: "custom"},
+	})
+
+	hits, sections, _ := SearchAll(context.Background(), "", "", 10, SearchOptions{})
+	if len(hits) != 2 {
+		t.Fatalf("expected 2 merged hits, got %d", len(hits))
+	}
+	if sections == nil {
+		t.Fatal("expected sections to be populated for an empty query")
+	}
+	foundOfficial := false
+	for _, h := range sections.Official {
+		if h.Source == "official-src" {
+			foundOfficial = true
+		}
+	}
+	if !foundOfficial {
+		t.Fatalf("expected the official source's entry in the official section, got %+v", sections.Official)
+	}
+}
+
+// TestSearchAll_NonEmptyQueryHasNoSections pins that sections stay nil (→ REST
+// null) once a query narrows the results.
+func TestSearchAll_NonEmptyQueryHasNoSections(t *testing.T) {
+	src := jsonServer(t, `[{"id":"a","name":"A"}]`)
+	withTestRegistries(t, []RegistryEntry{{ID: "src", Name: "Src", ServersURL: src.URL}})
+
+	_, sections, _ := SearchAll(context.Background(), "a", "", 10, SearchOptions{})
+	if sections != nil {
+		t.Fatalf("expected nil sections for a non-empty query, got %+v", sections)
+	}
+}
+
+// TestToCatalogResult_HTTPInstall pins the Transport/Install derivation for a
+// remote server (data-model §9).
+func TestToCatalogResult_HTTPInstall(t *testing.T) {
+	hit := CatalogHit{
+		Source: "official", Title: "GitHub", Publisher: "github", Verified: true, Official: true,
+		Entry: ServerEntry{ID: "io.github.github/github-mcp-server", URL: "https://api.githubcopilot.com/mcp/",
+			Description: "…", RequiredInputs: []RequiredInput{{Name: "GITHUB_TOKEN"}}},
+	}
+	result := ToCatalogResult(hit, false)
+	if result.Transport != "http" {
+		t.Errorf("expected transport http, got %s", result.Transport)
+	}
+	if result.Install.URL != "https://api.githubcopilot.com/mcp/" {
+		t.Errorf("unexpected install url: %+v", result.Install)
+	}
+	if result.Install.Command != "" {
+		t.Errorf("expected no command for an http install, got %q", result.Install.Command)
+	}
+	if len(result.RequiredInputs) != 1 || !result.RequiredInputs[0].SecretLike {
+		t.Errorf("expected GITHUB_TOKEN to be secret_like via the name rule, got %+v", result.RequiredInputs)
+	}
+}
+
+// TestToCatalogResult_StdioInstall pins command/args splitting for a local
+// install target.
+func TestToCatalogResult_StdioInstall(t *testing.T) {
+	hit := CatalogHit{
+		Source: "official",
+		Entry:  ServerEntry{ID: "fs", Name: "Filesystem", InstallCmd: "npx -y @modelcontextprotocol/server-filesystem /tmp"},
+	}
+	result := ToCatalogResult(hit, true)
+	if result.Transport != "stdio" {
+		t.Errorf("expected transport stdio, got %s", result.Transport)
+	}
+	if result.Install.Command != "npx" {
+		t.Errorf("expected command 'npx', got %q", result.Install.Command)
+	}
+	wantArgs := []string{"-y", "@modelcontextprotocol/server-filesystem", "/tmp"}
+	if strings.Join(result.Install.Args, " ") != strings.Join(wantArgs, " ") {
+		t.Errorf("unexpected args: %+v", result.Install.Args)
+	}
+	if !result.Added {
+		t.Error("expected Added to be passed through as true")
+	}
+}
diff --git a/internal/registries/rank_test.go b/internal/registries/rank_test.go
new file mode 100644
index 000000000..38fe00ef9
--- /dev/null
+++ b/internal/registries/rank_test.go
@@ -0,0 +1,75 @@
+package registries
+
+import "testing"
+
+// TestRank_OfficialBeatsEverything pins the primary sort key: official source
+// wins regardless of everything else (data-model §9, contracts/rest-api.md#catalog).
+func TestRank_OfficialBeatsEverything(t *testing.T) {
+	official := CatalogHit{Source: "official", Official: true, Entry: ServerEntry{ID: "z", Name: "Z"}}
+	verifiedPopular := CatalogHit{Source: "smithery", Verified: true, Popularity: intPop(9999), Entry: ServerEntry{ID: "a", Name: "A"}}
+
+	if !Rank(official, verifiedPopular, "") {
+		t.Error("expected official source to rank first")
+	}
+	if Rank(verifiedPopular, official, "") {
+		t.Error("expected official source to rank first (reverse check)")
+	}
+}
+
+// TestRank_VerifiedBeatsPopularity pins the secondary sort key.
+func TestRank_VerifiedBeatsPopularity(t *testing.T) {
+	verified := CatalogHit{Verified: true, Popularity: intPop(1), Entry: ServerEntry{ID: "b"}}
+	popular := CatalogHit{Verified: false, Popularity: intPop(99999), Entry: ServerEntry{ID: "a"}}
+	if !Rank(verified, popular, "") {
+		t.Error("expected verified to outrank raw popularity")
+	}
+}
+
+// TestRank_PopularityBeatsRelevance pins the third sort key.
+func TestRank_PopularityBeatsRelevance(t *testing.T) {
+	popular := CatalogHit{Popularity: intPop(100), Entry: ServerEntry{ID: "zzz", Name: "Unrelated"}}
+	relevant := CatalogHit{Popularity: intPop(1), Entry: ServerEntry{ID: "aaa", Name: "github tool"}}
+	if !Rank(popular, relevant, "github") {
+		t.Error("expected popularity to outrank text relevance")
+	}
+}
+
+// TestRank_RelevanceBeatsTitle pins the fourth key: a query match outranks
+// alphabetical order.
+func TestRank_RelevanceBeatsTitle(t *testing.T) {
+	matches := CatalogHit{Entry: ServerEntry{ID: "z", Name: "github tool"}}
+	noMatch := CatalogHit{Entry: ServerEntry{ID: "a", Name: "aardvark"}}
+	if !Rank(matches, noMatch, "github") {
+		t.Error("expected the query-matching title to outrank alphabetical order")
+	}
+}
+
+// TestRank_TitleThenID pins the final tiebreakers for an otherwise-equal pair,
+// including for the empty-query case (T004 order).
+func TestRank_TitleThenID(t *testing.T) {
+	a := CatalogHit{Title: "Alpha", Entry: ServerEntry{ID: "b"}}
+	b := CatalogHit{Title: "Beta", Entry: ServerEntry{ID: "a"}}
+	if !Rank(a, b, "") {
+		t.Error("expected 'Alpha' to sort before 'Beta'")
+	}
+
+	c := CatalogHit{Title: "Same", Entry: ServerEntry{ID: "a"}}
+	d := CatalogHit{Title: "Same", Entry: ServerEntry{ID: "b"}}
+	if !Rank(c, d, "") {
+		t.Error("expected id 'a' to sort before id 'b' when titles tie")
+	}
+}
+
+// TestRank_MissingPopularityIsZero pins that an entry with no Popularity
+// object never beats one with an explicit positive value, and never panics.
+func TestRank_MissingPopularityIsZero(t *testing.T) {
+	withPop := CatalogHit{Popularity: intPop(1), Entry: ServerEntry{ID: "b"}}
+	noPop := CatalogHit{Entry: ServerEntry{ID: "a"}}
+	if !Rank(withPop, noPop, "") {
+		t.Error("expected the entry with popularity to outrank the one without")
+	}
+}
+
+func intPop(stars int) *Popularity {
+	return &Popularity{Stars: &stars}
+}
diff --git a/internal/registries/testhooks.go b/internal/registries/testhooks.go
new file mode 100644
index 000000000..d8a6139c5
--- /dev/null
+++ b/internal/registries/testhooks.go
@@ -0,0 +1,34 @@
+package registries
+
+// This file exposes a narrowly-scoped test seam so that packages OTHER than
+// registries (notably internal/httpapi, for the FR-007 caller-scoping tests
+// on GET /catalog/search) can drive SearchAll against a small, deterministic,
+// hermetic set of sources instead of the real default registry list (which
+// would otherwise make every catalog test a live network call).
+//
+// It is intentionally named *ForTest and does nothing a caller would want in
+// production; keeping it in a non-_test.go file is the only way to make it
+// reachable from a sibling package's test binary (Go's export_test.go trick
+// is package-local). Do NOT call this outside tests.
+
+// SetRegistriesForTest replaces the effective registry list wholesale (no
+// merge with the shipped defaults, unlike SetRegistriesFromConfig) and
+// returns a restore func that reinstalls the previous list.
+func SetRegistriesForTest(regs []RegistryEntry) (restore func()) {
+	prev := registryList
+	registryList = regs
+	return func() { registryList = prev }
+}
+
+// AllowPrivateRegistryFetchForTest relaxes the SSRF guard (internal/registries
+// SetAllowPrivateRegistryFetch, MCP-1076) so a test's registry fixture can be
+// an httptest.Server on loopback, and returns a restore func.
+func AllowPrivateRegistryFetchForTest() (restore func()) {
+	prevForce, prev := testForceAllowPrivate.Load(), registryAllowPrivateFetch.Load()
+	testForceAllowPrivate.Store(true)
+	registryAllowPrivateFetch.Store(true)
+	return func() {
+		testForceAllowPrivate.Store(prevForce)
+		registryAllowPrivateFetch.Store(prev)
+	}
+}
diff --git a/internal/secret/keyring_available_test.go b/internal/secret/keyring_available_test.go
new file mode 100644
index 000000000..0b19b477f
--- /dev/null
+++ b/internal/secret/keyring_available_test.go
@@ -0,0 +1,75 @@
+package secret
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/zalando/go-keyring"
+)
+
+var errSomeBackend = errors.New("some backend error")
+
+// TestKeyringProvider_IsAvailableWithReason_Available pins that a healthy
+// probe reports available with no reason (FR-065, GET /secrets/config).
+func TestKeyringProvider_IsAvailableWithReason_Available(t *testing.T) {
+	clearHeadlessEnv(t)
+	withKeyringMocks(t,
+		func(service, user string) (string, error) { return "", keyring.ErrNotFound },
+		nil, nil,
+	)
+	p := NewKeyringProvider()
+	ok, reason := p.IsAvailableWithReason()
+	if !ok {
+		t.Fatal("expected available")
+	}
+	if reason != "" {
+		t.Errorf("expected empty reason when available, got %q", reason)
+	}
+}
+
+// TestKeyringProvider_IsAvailableWithReason_CI pins the headless CI reason so
+// the disabled secret toggle can explain itself instead of going silently
+// dark.
+func TestKeyringProvider_IsAvailableWithReason_CI(t *testing.T) {
+	t.Setenv("CI", "true")
+	p := NewKeyringProvider()
+	ok, reason := p.IsAvailableWithReason()
+	if ok {
+		t.Fatal("expected unavailable in CI")
+	}
+	if reason == "" {
+		t.Error("expected a non-empty reason in CI")
+	}
+}
+
+// TestKeyringProvider_IsAvailableWithReason_ProbeFails pins the generic probe
+// failure reason.
+func TestKeyringProvider_IsAvailableWithReason_ProbeFails(t *testing.T) {
+	clearHeadlessEnv(t)
+	withKeyringMocks(t,
+		func(service, user string) (string, error) { return "", errSomeBackend },
+		nil, nil,
+	)
+	p := NewKeyringProvider()
+	ok, reason := p.IsAvailableWithReason()
+	if ok {
+		t.Fatal("expected unavailable when the probe fails")
+	}
+	if reason == "" {
+		t.Error("expected a non-empty reason when the probe fails")
+	}
+}
+
+// TestResolver_KeyringAvailability pins that the resolver forwards to the
+// registered keyring provider's reasoned probe.
+func TestResolver_KeyringAvailability(t *testing.T) {
+	t.Setenv("CI", "true")
+	r := NewResolver()
+	ok, reason := r.KeyringAvailability()
+	if ok {
+		t.Fatal("expected unavailable in CI")
+	}
+	if reason == "" {
+		t.Error("expected a non-empty reason")
+	}
+}
diff --git a/internal/secret/keyring_provider.go b/internal/secret/keyring_provider.go
index dbd6ad8ba..48888f2f4 100644
--- a/internal/secret/keyring_provider.go
+++ b/internal/secret/keyring_provider.go
@@ -403,6 +403,36 @@ func (p *KeyringProvider) IsAvailable() bool {
 	}
 }
 
+// IsAvailableWithReason behaves like IsAvailable but also returns a short,
+// user-facing reason when unavailable ("" when available). Used by
+// GET /secrets/config (FR-065) so the Web/macOS/CLI secret toggle can explain
+// why it is disabled instead of just going dark.
+func (p *KeyringProvider) IsAvailableWithReason() (bool, string) {
+	if isHeadlessEnvironment() {
+		return false, headlessUnavailableReason()
+	}
+	if p.IsAvailable() {
+		return true, ""
+	}
+	return false, "the OS keychain did not respond to a probe request (it may be locked, missing, or waiting on a prompt)"
+}
+
+// headlessUnavailableReason names the specific headless condition
+// isHeadlessEnvironment detected, so the fast-path skip is not reported as an
+// opaque "unavailable".
+func headlessUnavailableReason() string {
+	if v := strings.ToLower(os.Getenv("CI")); v == "true" || v == "1" || v == "yes" {
+		return "no OS keyring in a CI environment"
+	}
+	switch runtime.GOOS {
+	case "linux":
+		return "no display session (Secret Service needs an X11 or Wayland session)"
+	case "darwin":
+		return "running as root (sudo) has no user keychain available"
+	}
+	return "OS keyring is unavailable in this environment"
+}
+
 // isHeadlessEnvironment returns true when we can confidently say no
 // interactive keyring is available. We only use this as a FAST path to
 // skip probing; returning false does not mean the keyring IS available.
diff --git a/internal/secret/refname.go b/internal/secret/refname.go
new file mode 100644
index 000000000..79c48879e
--- /dev/null
+++ b/internal/secret/refname.go
@@ -0,0 +1,64 @@
+package secret
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// refNameMaxLen is the keyring entry name length cap (FR-065). Existing
+// convention from ServerDetail.vue's pre-109 suggestSecretName.
+const refNameMaxLen = 64
+
+// refNameInvalidChars matches every run of characters outside [a-z0-9-] once
+// the input has been lower-cased, so it collapses "My Server!" the same way
+// for env and header kinds.
+var refNameInvalidChars = regexp.MustCompile(`[^a-z0-9-]+`)
+
+// refNameRepeatHyphen collapses a run of hyphens left behind once an invalid
+// run sits next to a literal '-' already in the input (e.g. "Server!-env").
+var refNameRepeatHyphen = regexp.MustCompile(`-{2,}`)
+
+// RefName computes the OS-keyring entry name for one field on one server
+// (FR-065): "<server>-<kind>-<key>", lower-cased, with every run of
+// characters outside [a-z0-9-] collapsed to a single '-', leading/trailing
+// '-' trimmed, and the result capped at 64 characters. kind is normally "env"
+// or "header" — keeping it as a distinct path component (rather than folding
+// it into key) is what keeps an env var and a header of the same name from
+// colliding on one keyring entry.
+//
+// taken reports whether a candidate name is already present in the keyring
+// (GET /secrets); when the computed name collides, RefName appends -2, -3, …
+// until it finds a free one, so an add never silently overwrites an existing
+// secret (D28). taken must be safe to call repeatedly and cheap (typically a
+// map/set built once from a single GET /secrets response).
+func RefName(server, kind, key string, taken func(string) bool) string {
+	base := normalizeRefComponent(server + "-" + kind + "-" + key)
+	if taken == nil {
+		return base
+	}
+
+	candidate := base
+	for n := 2; taken(candidate); n++ {
+		suffix := fmt.Sprintf("-%d", n)
+		trimmed := base
+		if maxBase := refNameMaxLen - len(suffix); len(trimmed) > maxBase {
+			trimmed = trimmed[:maxBase]
+		}
+		candidate = trimmed + suffix
+	}
+	return candidate
+}
+
+// normalizeRefComponent lower-cases s, collapses every run outside
+// [a-z0-9-] to a single '-', trims leading/trailing '-', and caps the length.
+func normalizeRefComponent(s string) string {
+	lower := strings.ToLower(s)
+	collapsed := refNameInvalidChars.ReplaceAllString(lower, "-")
+	collapsed = refNameRepeatHyphen.ReplaceAllString(collapsed, "-")
+	trimmed := strings.Trim(collapsed, "-")
+	if len(trimmed) > refNameMaxLen {
+		trimmed = strings.Trim(trimmed[:refNameMaxLen], "-")
+	}
+	return trimmed
+}
diff --git a/internal/secret/refname_test.go b/internal/secret/refname_test.go
new file mode 100644
index 000000000..57c644bb9
--- /dev/null
+++ b/internal/secret/refname_test.go
@@ -0,0 +1,102 @@
+package secret
+
+import (
+	"encoding/json"
+	"os"
+	"testing"
+)
+
+func TestRefName(t *testing.T) {
+	notTaken := func(string) bool { return false }
+
+	cases := []struct {
+		name   string
+		server string
+		kind   string
+		key    string
+		taken  func(string) bool
+		want   string
+	}{
+		{"env basic", "github", "env", "API_KEY", notTaken, "github-env-api-key"},
+		{"header basic", "github", "header", "API_KEY", notTaken, "github-header-api-key"},
+		{"header mixed case name", "github", "header", "Authorization", notTaken, "github-header-authorization"},
+		{"normalizes punctuation", "My Server!", "env", "GITHUB_TOKEN", notTaken, "my-server-env-github-token"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := RefName(tc.server, tc.kind, tc.key, tc.taken); got != tc.want {
+				t.Errorf("RefName(%q,%q,%q) = %q, want %q", tc.server, tc.kind, tc.key, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestRefName_EnvHeaderSameNameDistinctRefs pins FR-065: an env var and a
+// header with the same name must never share a keyring entry.
+func TestRefName_EnvHeaderSameNameDistinctRefs(t *testing.T) {
+	notTaken := func(string) bool { return false }
+	env := RefName("github", "env", "API_KEY", notTaken)
+	header := RefName("github", "header", "API_KEY", notTaken)
+	if env == header {
+		t.Fatalf("env and header refs must differ, both were %q", env)
+	}
+}
+
+// TestRefName_TakenNameGetsSuffix pins FR-065/D28: an add never overwrites an
+// existing secret — a computed name already in the keyring gets -2, -3, ...
+func TestRefName_TakenNameGetsSuffix(t *testing.T) {
+	taken := map[string]bool{
+		"github-env-api-key":   true,
+		"github-env-api-key-2": true,
+	}
+	got := RefName("github", "env", "API_KEY", func(n string) bool { return taken[n] })
+	if got != "github-env-api-key-3" {
+		t.Fatalf("RefName with two taken names = %q, want github-env-api-key-3", got)
+	}
+}
+
+// TestRefName_LongNameTruncated ensures the 64-char cap holds even once a
+// numeric suffix is appended for a collision.
+func TestRefName_LongNameTruncated(t *testing.T) {
+	longKey := "THIS_IS_A_VERY_VERY_VERY_VERY_VERY_VERY_VERY_LONG_ENV_VAR_NAME"
+	got := RefName("some-really-long-server-name", "env", longKey, func(string) bool { return false })
+	if len(got) > 64 {
+		t.Fatalf("RefName length = %d, want <= 64: %q", len(got), got)
+	}
+}
+
+// TestRefName_FixtureGolden decodes the shared fixture that Go, vitest and
+// Swift all pin against (FR-065), and re-derives each case.
+func TestRefName_FixtureGolden(t *testing.T) {
+	data, err := os.ReadFile("testdata/ref_names.json")
+	if err != nil {
+		t.Fatalf("read fixture: %v", err)
+	}
+
+	var fixture struct {
+		Cases []struct {
+			Server string   `json:"server"`
+			Kind   string   `json:"kind"`
+			Key    string   `json:"key"`
+			Taken  []string `json:"taken"`
+			Want   string   `json:"want"`
+		} `json:"cases"`
+	}
+	if err := json.Unmarshal(data, &fixture); err != nil {
+		t.Fatalf("decode fixture: %v", err)
+	}
+	if len(fixture.Cases) == 0 {
+		t.Fatal("fixture has no cases")
+	}
+
+	for _, c := range fixture.Cases {
+		takenSet := make(map[string]bool, len(c.Taken))
+		for _, n := range c.Taken {
+			takenSet[n] = true
+		}
+		got := RefName(c.Server, c.Kind, c.Key, func(n string) bool { return takenSet[n] })
+		if got != c.Want {
+			t.Errorf("RefName(%q,%q,%q) taken=%v = %q, want %q", c.Server, c.Kind, c.Key, c.Taken, got, c.Want)
+		}
+	}
+}
diff --git a/internal/secret/resolver.go b/internal/secret/resolver.go
index 7b73150b9..ca8160c43 100644
--- a/internal/secret/resolver.go
+++ b/internal/secret/resolver.go
@@ -92,6 +92,25 @@ func (r *Resolver) ListAll(ctx context.Context) ([]Ref, error) {
 	return allRefs, nil
 }
 
+// KeyringAvailability reports whether the registered "keyring" provider is
+// usable and, when it isn't, a short user-facing reason (FR-065,
+// GET /secrets/config keyring_available / keyring_reason). Falls back to a
+// generic reason for a provider that doesn't implement the reasoned probe
+// (e.g. a test double registered in place of the real KeyringProvider).
+func (r *Resolver) KeyringAvailability() (bool, string) {
+	provider, exists := r.providers["keyring"]
+	if !exists {
+		return false, "no keyring provider registered"
+	}
+	if withReason, ok := provider.(interface{ IsAvailableWithReason() (bool, string) }); ok {
+		return withReason.IsAvailableWithReason()
+	}
+	if provider.IsAvailable() {
+		return true, ""
+	}
+	return false, "keyring unavailable"
+}
+
 // GetAvailableProviders returns a list of available providers
 func (r *Resolver) GetAvailableProviders() []string {
 	var available []string
diff --git a/internal/secret/testdata/ref_names.json b/internal/secret/testdata/ref_names.json
new file mode 100644
index 000000000..29e3d0584
--- /dev/null
+++ b/internal/secret/testdata/ref_names.json
@@ -0,0 +1,47 @@
+{
+  "description": "Shared FR-065 keyring ref-name fixture, decoded by Go (internal/secret/refname_test.go), vitest (frontend/tests/unit/secret-ref.spec.ts) and Swift (MCPProxyTests/CatalogTests.swift). Each case computes RefName(server, kind, key, taken) and must equal want.",
+  "cases": [
+    {
+      "server": "github",
+      "kind": "env",
+      "key": "API_KEY",
+      "taken": [],
+      "want": "github-env-api-key"
+    },
+    {
+      "server": "github",
+      "kind": "header",
+      "key": "API_KEY",
+      "taken": [],
+      "want": "github-header-api-key"
+    },
+    {
+      "server": "github",
+      "kind": "env",
+      "key": "GITHUB_TOKEN",
+      "taken": [],
+      "want": "github-env-github-token"
+    },
+    {
+      "server": "My Server!",
+      "kind": "env",
+      "key": "GITHUB_TOKEN",
+      "taken": [],
+      "want": "my-server-env-github-token"
+    },
+    {
+      "server": "github",
+      "kind": "env",
+      "key": "API_KEY",
+      "taken": ["github-env-api-key"],
+      "want": "github-env-api-key-2"
+    },
+    {
+      "server": "github",
+      "kind": "env",
+      "key": "API_KEY",
+      "taken": ["github-env-api-key", "github-env-api-key-2"],
+      "want": "github-env-api-key-3"
+    }
+  ]
+}
diff --git a/internal/secret/types.go b/internal/secret/types.go
index 69dffc35f..1d31a5a82 100644
--- a/internal/secret/types.go
+++ b/internal/secret/types.go
@@ -77,4 +77,11 @@ type ConfigSecretsResponse struct {
 	EnvironmentVars []EnvVarStatus        `json:"environment_vars"`
 	TotalSecrets    int                   `json:"total_secrets"`
 	TotalEnvVars    int                   `json:"total_env_vars"`
+
+	// KeyringAvailable and KeyringReason (FR-065) report whether the OS
+	// keyring provider is usable, from the provider's own IsAvailable()
+	// probe. When false, the Value/Secret toggle on Paste/Manual/Catalog
+	// surfaces is disabled and shows KeyringReason.
+	KeyringAvailable bool   `json:"keyring_available"`
+	KeyringReason    string `json:"keyring_reason,omitempty"`
 }
diff --git a/internal/secretlike/secretlike.go b/internal/secretlike/secretlike.go
new file mode 100644
index 000000000..99d046970
--- /dev/null
+++ b/internal/secretlike/secretlike.go
@@ -0,0 +1,19 @@
+// Package secretlike implements the one shared "does this field name look
+// like a credential?" rule (Spec 109 research D13), used to default the
+// Value/Secret toggle to Secret in Paste, Manual and Catalog-with-inputs
+// surfaces (FR-065), and to compute CatalogResult.RequiredInputs[].secret_like
+// when a registry omits or falsifies its own isSecret flag (FR-061).
+package secretlike
+
+import "regexp"
+
+// pattern is the D13 name heuristic, shared verbatim across Go, the frontend
+// port (frontend/src/utils/secretRef.ts) and the Swift port
+// (MCPProxyTests/CatalogTests.swift secret toggle model) so all three surfaces
+// default the same fields to Secret.
+var pattern = regexp.MustCompile(`(?i)(token|secret|password|passwd|api[_-]?key|[_-]key$|auth|credential|private[_-]?key)`)
+
+// LooksSecret reports whether name looks like it holds a credential.
+func LooksSecret(name string) bool {
+	return pattern.MatchString(name)
+}
diff --git a/internal/secretlike/secretlike_test.go b/internal/secretlike/secretlike_test.go
new file mode 100644
index 000000000..4e9924a8e
--- /dev/null
+++ b/internal/secretlike/secretlike_test.go
@@ -0,0 +1,29 @@
+package secretlike
+
+import "testing"
+
+func TestLooksSecret(t *testing.T) {
+	cases := map[string]bool{
+		"GITHUB_TOKEN":    true,
+		"API_KEY":         true,
+		"api-key":         true,
+		"PASSWORD":        true,
+		"PASSWD":          true,
+		"AUTH_TOKEN":      true,
+		"CREDENTIAL":      true,
+		"PRIVATE_KEY":     true,
+		"SIGNING_KEY":     true, // "-key$" suffix rule
+		"Authorization":   true, // "auth" substring
+		"PORT":            false,
+		"WORKDIR":         false,
+		"PATH":            false,
+		"REGION":          false,
+		"":                false,
+		"KEYBOARD_LAYOUT": false, // "key" not at end, no separator before "key" boundary -> still matches "key" via [_-]key$? no, boundary check
+	}
+	for name, want := range cases {
+		if got := LooksSecret(name); got != want {
+			t.Errorf("LooksSecret(%q) = %v, want %v", name, got, want)
+		}
+	}
+}
diff --git a/internal/shellwords/shellwords.go b/internal/shellwords/shellwords.go
new file mode 100644
index 000000000..a231bfd3a
--- /dev/null
+++ b/internal/shellwords/shellwords.go
@@ -0,0 +1,58 @@
+// Package shellwords implements a small, dependency-free, quote-aware
+// tokenizer for a single command line, shared by the Paste-source command
+// detector (internal/configimport, FR-064) and the catalog install-command
+// splitter (internal/registries, data-model §9 CatalogInstall). It is
+// deliberately independent of internal/oauth's spawnargv helpers, which parse
+// argv already split by the shell for a different purpose (OAuth browser
+// launch); duplicating a ~30-line tokenizer here is cheaper than coupling the
+// two packages.
+package shellwords
+
+import (
+	"fmt"
+	"strings"
+	"unicode"
+)
+
+// Split tokenizes s the way a POSIX shell would for a single command line:
+// whitespace-separated words, with '...' and "..." both grouping their
+// contents into one word (no escape processing inside single quotes, no
+// expansion of any kind — this only ever feeds a preview, never a shell).
+// Returns an error if a quote is left unterminated. An empty or
+// whitespace-only input returns (nil, nil).
+func Split(s string) ([]string, error) {
+	var words []string
+	var cur strings.Builder
+	haveWord := false
+
+	var quote rune // 0, '\'' or '"'
+	for _, r := range s {
+		switch {
+		case quote != 0:
+			if r == quote {
+				quote = 0
+				continue
+			}
+			cur.WriteRune(r)
+		case r == '\'' || r == '"':
+			quote = r
+			haveWord = true
+		case unicode.IsSpace(r):
+			if haveWord {
+				words = append(words, cur.String())
+				cur.Reset()
+				haveWord = false
+			}
+		default:
+			cur.WriteRune(r)
+			haveWord = true
+		}
+	}
+	if quote != 0 {
+		return nil, fmt.Errorf("unterminated %c quote", quote)
+	}
+	if haveWord {
+		words = append(words, cur.String())
+	}
+	return words, nil
+}
diff --git a/internal/shellwords/shellwords_test.go b/internal/shellwords/shellwords_test.go
new file mode 100644
index 000000000..ec2b7716b
--- /dev/null
+++ b/internal/shellwords/shellwords_test.go
@@ -0,0 +1,41 @@
+package shellwords
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestSplit(t *testing.T) {
+	cases := []struct {
+		name  string
+		input string
+		want  []string
+	}{
+		{"simple", "npx -y @modelcontextprotocol/server-filesystem /tmp",
+			[]string{"npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"}},
+		{"double_quotes", `docker run -e API_KEY="abc def" -i --rm mcp/sqlite`,
+			[]string{"docker", "run", "-e", "API_KEY=abc def", "-i", "--rm", "mcp/sqlite"}},
+		{"single_quotes", `sh -c 'echo hello world'`,
+			[]string{"sh", "-c", "echo hello world"}},
+		{"extra_whitespace", "  uvx   mcp-server-fetch  ",
+			[]string{"uvx", "mcp-server-fetch"}},
+		{"empty", "", nil},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := Split(tc.input)
+			if err != nil {
+				t.Fatalf("Split(%q) error: %v", tc.input, err)
+			}
+			if !reflect.DeepEqual(got, tc.want) {
+				t.Errorf("Split(%q) = %#v, want %#v", tc.input, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestSplitUnbalancedQuote(t *testing.T) {
+	if _, err := Split(`sh -c "unterminated`); err == nil {
+		t.Fatal("expected an error for an unbalanced quote")
+	}
+}

From 9fa49c8928935eb151c231891aafa8bf921ecfe3 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 00:37:57 +0300
Subject: [PATCH 12/27] feat(import): add Paste-source URL/command detection
 and preview enrichment (FR-064)

- configimport: DetectFormat falls back to the new 'url' and 'command'
  formats for a single-line paste that is neither JSON nor TOML;
  URLParser/CommandParser map them to a remote or local/stdio server.
  SuggestNameFromURL/SuggestNameFromCommand derive a sensible default
  name (preferring the package name for npx/uvx/pipx runners).
- httpapi: POST /servers/import/json?preview=true accepts url/command
  content and its response gains summary, tags and per-env/header
  secret_like/empty_or_placeholder previews, built from the
  already-redacted URL/Command/Args so no raw secret reaches the new
  fields either.
---
 .../configimport/detect_url_command_test.go   | 150 ++++++++++++++++
 internal/configimport/detector.go             |  48 ++++-
 internal/configimport/parser.go               |   4 +
 internal/configimport/types.go                |  11 ++
 internal/configimport/url_command.go          | 128 ++++++++++++++
 internal/httpapi/import.go                    | 142 ++++++++++++++-
 .../httpapi/import_preview_fields_test.go     | 167 ++++++++++++++++++
 7 files changed, 645 insertions(+), 5 deletions(-)
 create mode 100644 internal/configimport/detect_url_command_test.go
 create mode 100644 internal/configimport/url_command.go
 create mode 100644 internal/httpapi/import_preview_fields_test.go

diff --git a/internal/configimport/detect_url_command_test.go b/internal/configimport/detect_url_command_test.go
new file mode 100644
index 000000000..b4d97ec64
--- /dev/null
+++ b/internal/configimport/detect_url_command_test.go
@@ -0,0 +1,150 @@
+package configimport
+
+import (
+	"os"
+	"testing"
+)
+
+// TestDetectFormat_URL pins FR-064: a single http(s):// token detects as the
+// new "url" format.
+func TestDetectFormat_URL(t *testing.T) {
+	cases := []string{
+		"https://api.githubcopilot.com/mcp/",
+		"  http://localhost:8080/mcp  ",
+	}
+	for _, c := range cases {
+		result, err := DetectFormat([]byte(c))
+		if err != nil {
+			t.Fatalf("DetectFormat(%q) error: %v", c, err)
+		}
+		if result.Format != FormatURL {
+			t.Errorf("DetectFormat(%q).Format = %q, want %q", c, result.Format, FormatURL)
+		}
+	}
+}
+
+// TestDetectFormat_Command pins FR-064: a single non-JSON/TOML line detects as
+// the new "command" format.
+func TestDetectFormat_Command(t *testing.T) {
+	cases := []string{
+		"npx -y @modelcontextprotocol/server-filesystem /tmp",
+		`docker run -i --rm -e API_KEY="abc def" mcp/sqlite`,
+	}
+	for _, c := range cases {
+		result, err := DetectFormat([]byte(c))
+		if err != nil {
+			t.Fatalf("DetectFormat(%q) error: %v", c, err)
+		}
+		if result.Format != FormatCommand {
+			t.Errorf("DetectFormat(%q).Format = %q, want %q", c, result.Format, FormatCommand)
+		}
+	}
+}
+
+// TestDetectFormat_JSONTOMLUnchanged pins that the existing JSON/TOML
+// detection paths are untouched by the new url/command fallbacks.
+func TestDetectFormat_JSONTOMLUnchanged(t *testing.T) {
+	json := `{"mcpServers": {"fs": {"command": "npx", "args": ["-y", "server-filesystem"]}}}`
+	result, err := DetectFormat([]byte(json))
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if result.Format == FormatURL || result.Format == FormatCommand {
+		t.Errorf("JSON content misdetected as %q", result.Format)
+	}
+
+	toml := "[mcp_servers.fs]\ncommand = \"npx\"\n"
+	result, err = DetectFormat([]byte(toml))
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if result.Format != FormatCodex {
+		t.Errorf("TOML content misdetected as %q, want %q", result.Format, FormatCodex)
+	}
+}
+
+// TestURLParser_Parse pins the URL → http server mapping (FR-064).
+func TestURLParser_Parse(t *testing.T) {
+	p := &URLParser{}
+	parsed, err := p.Parse([]byte("https://api.githubcopilot.com/mcp/"))
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(parsed) != 1 {
+		t.Fatalf("expected 1 parsed server, got %d", len(parsed))
+	}
+	srv := parsed[0]
+	if srv.Fields["url"] != "https://api.githubcopilot.com/mcp/" {
+		t.Errorf("unexpected url field: %v", srv.Fields["url"])
+	}
+	if srv.Fields["protocol"] != "http" {
+		t.Errorf("unexpected protocol field: %v", srv.Fields["protocol"])
+	}
+	if srv.Name == "" {
+		t.Error("expected a non-empty derived name")
+	}
+}
+
+// TestURLParser_RejectsInvalid pins that preview never executes anything: an
+// invalid URL is rejected rather than guessed at.
+func TestURLParser_RejectsInvalid(t *testing.T) {
+	p := &URLParser{}
+	if _, err := p.Parse([]byte("not a url")); err == nil {
+		t.Fatal("expected an error for a non-URL input")
+	}
+}
+
+// TestCommandParser_Parse pins the command line → stdio command/args mapping
+// (FR-064), including quote-aware splitting.
+func TestCommandParser_Parse(t *testing.T) {
+	p := &CommandParser{}
+	parsed, err := p.Parse([]byte(`docker run -e API_KEY="abc def" -i --rm mcp/sqlite`))
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(parsed) != 1 {
+		t.Fatalf("expected 1 parsed server, got %d", len(parsed))
+	}
+	srv := parsed[0]
+	if srv.Fields["command"] != "docker" {
+		t.Errorf("unexpected command field: %v", srv.Fields["command"])
+	}
+	args, ok := srv.Fields["args"].([]string)
+	if !ok {
+		t.Fatalf("expected args to be []string, got %T", srv.Fields["args"])
+	}
+	want := []string{"run", "-e", "API_KEY=abc def", "-i", "--rm", "mcp/sqlite"}
+	if len(args) != len(want) {
+		t.Fatalf("unexpected args: %v", args)
+	}
+	for i := range want {
+		if args[i] != want[i] {
+			t.Errorf("args[%d] = %q, want %q", i, args[i], want[i])
+		}
+	}
+}
+
+// TestCommandParser_PreviewNeverExecutes pins FR-064: a command that would
+// create a file (if actually run) leaves no file behind — Parse only
+// tokenizes text, it never spawns anything.
+func TestCommandParser_PreviewNeverExecutes(t *testing.T) {
+	dir := t.TempDir()
+	marker := dir + "/should-not-exist"
+	p := &CommandParser{}
+	if _, err := p.Parse([]byte("touch " + marker)); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, err := os.Stat(marker); err == nil {
+		t.Fatal("preview must never execute the pasted command")
+	}
+}
+
+// TestSuggestNameFromCommand_PrefersPackageForRunners pins that npx/uvx/pipx
+// runners suggest the package name, not the runner binary, as the server
+// name.
+func TestSuggestNameFromCommand_PrefersPackageForRunners(t *testing.T) {
+	name := SuggestNameFromCommand([]string{"npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"})
+	if name != "server-filesystem" {
+		t.Errorf("SuggestNameFromCommand = %q, want %q", name, "server-filesystem")
+	}
+}
diff --git a/internal/configimport/detector.go b/internal/configimport/detector.go
index 2eda982b7..11b6c01c0 100644
--- a/internal/configimport/detector.go
+++ b/internal/configimport/detector.go
@@ -3,15 +3,19 @@ package configimport
 import (
 	"encoding/json"
 	"fmt"
+	"net/url"
+	"strings"
 
 	"github.com/BurntSushi/toml"
 )
 
 // ErrUnknownFormat is returned when the configuration format cannot be detected.
-var ErrUnknownFormat = fmt.Errorf("unable to detect configuration format: supported formats are Claude Desktop, Claude Code, Cursor IDE, Codex CLI, and Gemini CLI")
+var ErrUnknownFormat = fmt.Errorf("unable to detect configuration format: supported formats are Claude Desktop, Claude Code, Cursor IDE, Codex CLI, Gemini CLI, a pasted URL, or a pasted command line")
 
 // DetectFormat identifies the configuration format from content.
-// It tries TOML first (for Codex), then JSON (for all other formats).
+// It tries TOML first (for Codex), then JSON (for all other formats), then
+// falls back to the Paste-source formats (FR-064): a single http(s):// URL,
+// or a single command line.
 func DetectFormat(content []byte) (*DetectionResult, error) {
 	// Try TOML first (Codex uses TOML)
 	if result := tryDetectTOML(content); result != nil {
@@ -23,9 +27,49 @@ func DetectFormat(content []byte) (*DetectionResult, error) {
 		return result, nil
 	}
 
+	// Try the Paste-source fallbacks (FR-064): only single-line input is a
+	// candidate — anything spanning multiple lines is neither a URL nor a
+	// command line MCPProxy would know how to preview, so it stays unknown
+	// rather than guessing.
+	if result := tryDetectURLOrCommand(content); result != nil {
+		return result, nil
+	}
+
 	return nil, ErrUnknownFormat
 }
 
+// tryDetectURLOrCommand recognises the two Paste-source formats: a bare
+// http(s):// URL, or any other single non-empty line (treated as a command
+// line — CommandParser is responsible for actually tokenizing it, and rejects
+// nonsense at parse time rather than here).
+func tryDetectURLOrCommand(content []byte) *DetectionResult {
+	trimmed := strings.TrimSpace(string(content))
+	if trimmed == "" || strings.ContainsAny(trimmed, "\n\r") {
+		return nil
+	}
+	// Content that opens like JSON (an object or array) was meant as a
+	// config paste, not a shell command — even when it fails to parse (e.g.
+	// a typo) or parses but lacks mcpServers. Falling back to "command" here
+	// would silently swallow the real error into a nonsense command preview.
+	if strings.HasPrefix(trimmed, "{") || strings.HasPrefix(trimmed, "[") {
+		return nil
+	}
+
+	if u, err := url.Parse(trimmed); err == nil && (u.Scheme == "http" || u.Scheme == "https") && u.Host != "" {
+		return &DetectionResult{
+			Format:     FormatURL,
+			Confidence: "high",
+			Indicators: []string{"single_line", "http_scheme"},
+		}
+	}
+
+	return &DetectionResult{
+		Format:     FormatCommand,
+		Confidence: "medium",
+		Indicators: []string{"single_line", "not_json_or_toml"},
+	}
+}
+
 // tryDetectTOML attempts to parse content as TOML and detect Codex format.
 func tryDetectTOML(content []byte) *DetectionResult {
 	var raw map[string]interface{}
diff --git a/internal/configimport/parser.go b/internal/configimport/parser.go
index fde538fde..b4cc5bf38 100644
--- a/internal/configimport/parser.go
+++ b/internal/configimport/parser.go
@@ -22,6 +22,10 @@ func GetParser(format ConfigFormat) Parser {
 		return &CodexParser{}
 	case FormatGemini:
 		return &GeminiParser{}
+	case FormatURL:
+		return &URLParser{}
+	case FormatCommand:
+		return &CommandParser{}
 	default:
 		return nil
 	}
diff --git a/internal/configimport/types.go b/internal/configimport/types.go
index e4046096c..01fdd30df 100644
--- a/internal/configimport/types.go
+++ b/internal/configimport/types.go
@@ -18,6 +18,13 @@ const (
 	FormatCursor        ConfigFormat = "cursor"
 	FormatCodex         ConfigFormat = "codex"
 	FormatGemini        ConfigFormat = "gemini"
+
+	// FormatURL and FormatCommand are the Paste-source formats (Spec 109
+	// FR-064): a single http(s):// URL, or a single command line that isn't
+	// JSON/TOML. Detected by DetectFormat as a fallback once every existing
+	// config-file format has been ruled out.
+	FormatURL     ConfigFormat = "url"
+	FormatCommand ConfigFormat = "command"
 )
 
 // String returns human-readable format name for display
@@ -33,6 +40,10 @@ func (f ConfigFormat) String() string {
 		return "Codex CLI"
 	case FormatGemini:
 		return "Gemini CLI"
+	case FormatURL:
+		return "URL"
+	case FormatCommand:
+		return "Command Line"
 	default:
 		return "Unknown"
 	}
diff --git a/internal/configimport/url_command.go b/internal/configimport/url_command.go
new file mode 100644
index 000000000..5469f514e
--- /dev/null
+++ b/internal/configimport/url_command.go
@@ -0,0 +1,128 @@
+package configimport
+
+import (
+	"fmt"
+	"net/url"
+	"strings"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/shellwords"
+)
+
+// URLParser parses a single pasted http(s):// URL into one remote server
+// (Spec 109 FR-064). Preview never contacts the URL — Parse only validates
+// its shape.
+type URLParser struct{}
+
+// Format implements Parser.
+func (p *URLParser) Format() ConfigFormat { return FormatURL }
+
+// Parse implements Parser.
+func (p *URLParser) Parse(content []byte) ([]*ParsedServer, error) {
+	raw := strings.TrimSpace(string(content))
+	u, err := url.Parse(raw)
+	if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
+		return nil, &ImportError{
+			Type:    "invalid_url",
+			Message: fmt.Sprintf("not a valid http(s) URL: %q", raw),
+		}
+	}
+
+	return []*ParsedServer{{
+		Name:         SuggestNameFromURL(u),
+		SourceFormat: FormatURL,
+		Fields: map[string]interface{}{
+			"url":      raw,
+			"protocol": "http",
+		},
+	}}, nil
+}
+
+// CommandParser parses a single pasted command line into one local/stdio
+// server (Spec 109 FR-064), splitting it with the shared quote-aware
+// tokenizer. Preview never executes anything — Parse only tokenizes text.
+type CommandParser struct{}
+
+// Format implements Parser.
+func (p *CommandParser) Format() ConfigFormat { return FormatCommand }
+
+// Parse implements Parser.
+func (p *CommandParser) Parse(content []byte) ([]*ParsedServer, error) {
+	raw := strings.TrimSpace(string(content))
+	parts, err := shellwords.Split(raw)
+	if err != nil {
+		return nil, &ImportError{Type: "invalid_command", Message: fmt.Sprintf("could not parse command line: %v", err)}
+	}
+	if len(parts) == 0 {
+		return nil, &ImportError{Type: "invalid_command", Message: "command line is empty"}
+	}
+
+	fields := map[string]interface{}{
+		"command":  parts[0],
+		"protocol": "stdio",
+	}
+	if len(parts) > 1 {
+		fields["args"] = parts[1:]
+	}
+
+	return []*ParsedServer{{
+		Name:         SuggestNameFromCommand(parts),
+		SourceFormat: FormatCommand,
+		Fields:       fields,
+	}}, nil
+}
+
+// SuggestNameFromURL derives a display name from a parsed URL's host, e.g.
+// "https://api.githubcopilot.com/mcp/" -> "githubcopilot". Exported so the
+// CLI and httpapi preview can reuse it verbatim.
+func SuggestNameFromURL(u *url.URL) string {
+	host := strings.TrimPrefix(u.Hostname(), "www.")
+	if host == "" {
+		return "remote-server"
+	}
+	labels := strings.Split(host, ".")
+	// A bare "api." / "mcp." subdomain is not a useful name — prefer the next
+	// label (e.g. "api.githubcopilot.com" -> "githubcopilot", not "api").
+	if len(labels) > 1 {
+		switch labels[0] {
+		case "api", "mcp", "www":
+			return labels[1]
+		}
+	}
+	return labels[0]
+}
+
+// runnerBinaries are package-runner commands whose first non-flag argument is
+// a package/module name far more descriptive than the runner itself.
+var runnerBinaries = map[string]bool{"npx": true, "uvx": true, "pipx": true}
+
+// SuggestNameFromCommand derives a display name from a tokenized command
+// line. For a package runner (npx/uvx/pipx) it prefers the package name over
+// the runner binary, e.g. ["npx","-y","@modelcontextprotocol/server-filesystem"]
+// -> "server-filesystem". Exported so the CLI and httpapi preview can reuse it
+// verbatim.
+func SuggestNameFromCommand(parts []string) string {
+	if len(parts) == 0 {
+		return "pasted-server"
+	}
+	base := parts[0]
+	if idx := strings.LastIndexByte(base, '/'); idx >= 0 && idx+1 < len(base) {
+		base = base[idx+1:]
+	}
+
+	if runnerBinaries[base] {
+		for _, a := range parts[1:] {
+			if a == "" || strings.HasPrefix(a, "-") {
+				continue
+			}
+			pkg := a
+			if idx := strings.LastIndexByte(pkg, '/'); idx >= 0 && idx+1 < len(pkg) {
+				pkg = pkg[idx+1:]
+			}
+			if idx := strings.IndexByte(pkg, '@'); idx > 0 {
+				pkg = pkg[:idx]
+			}
+			return pkg
+		}
+	}
+	return base
+}
diff --git a/internal/httpapi/import.go b/internal/httpapi/import.go
index c866210ee..d9db22e52 100644
--- a/internal/httpapi/import.go
+++ b/internal/httpapi/import.go
@@ -7,12 +7,16 @@ import (
 	"net/http"
 	"os"
 	"path/filepath"
+	"regexp"
 	"runtime"
+	"sort"
 	"strings"
 	"time"
 
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/configimport"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/oauth"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/secretlike"
 )
 
 // ImportRequest represents a request to import servers from JSON/TOML content
@@ -44,6 +48,38 @@ type ImportedServerResponse struct {
 	OriginalName  string   `json:"original_name"`
 	FieldsSkipped []string `json:"fields_skipped,omitempty"`
 	Warnings      []string `json:"warnings,omitempty"`
+
+	// Summary, Tags, Env and Headers are the Spec 109 FR-064 preview
+	// enrichment (contracts/rest-api.md "Import preview"). Summary and Tags
+	// are built from the already-redacted URL/Command/Args above, so a
+	// secret embedded in argv or a URL query never reaches Summary either.
+	// Env/Headers never carry the raw value — only its presence and two
+	// booleans a surface uses to default the Value/Secret toggle (FR-065).
+	Summary string               `json:"summary,omitempty"`
+	Tags    []string             `json:"tags,omitempty"`
+	Env     []EnvFieldPreview    `json:"env,omitempty"`
+	Headers []HeaderFieldPreview `json:"headers,omitempty"`
+}
+
+// EnvFieldPreview is one env var entry in the import preview
+// (contracts/rest-api.md "Import preview"). ValuePresent is always emitted
+// (even when false) — this is a distinct type from HeaderFieldPreview
+// specifically so that field only ever appears for env vars, matching the
+// documented example shape exactly.
+type EnvFieldPreview struct {
+	Name               string `json:"name"`
+	ValuePresent       bool   `json:"value_present"`
+	SecretLike         bool   `json:"secret_like"`
+	EmptyOrPlaceholder bool   `json:"empty_or_placeholder"`
+}
+
+// HeaderFieldPreview is one header entry in the import preview. It never
+// carries a "value_present" key (headers are typically required, so an
+// empty one is unusual enough that empty_or_placeholder alone covers it).
+type HeaderFieldPreview struct {
+	Name               string `json:"name"`
+	SecretLike         bool   `json:"secret_like"`
+	EmptyOrPlaceholder bool   `json:"empty_or_placeholder"`
 }
 
 // CanonicalConfigPath represents a well-known config file path
@@ -439,16 +475,31 @@ func (s *Server) runImport(r *http.Request, content []byte, formatHint string, s
 		// so the operator can still verify that a secret imported and how long
 		// it is without the value itself reaching the wire.
 		view := oauth.RedactedConfigView("", imported.Server)
+		redactedURL := viewString(view, "url", imported.Server.URL)
+		redactedCommand := viewString(view, "command", imported.Server.Command)
+		redactedArgs := oauth.LiveRedaction.Argv(imported.Server.Args)
+
+		// FR-064 preview enrichment (contracts/rest-api.md "Import
+		// preview"): built from the redacted values above, never from the
+		// raw server, so a secret in argv/URL can only ever reach Summary
+		// through the same redaction the URL/Command/Args fields already go
+		// through.
+		summary, tags, env, headers := buildImportPreviewFields(imported.Server, redactedURL, redactedCommand, redactedArgs)
+
 		response.Imported[i] = ImportedServerResponse{
 			Name:          imported.Server.Name,
 			Protocol:      imported.Server.Protocol,
-			URL:           viewString(view, "url", imported.Server.URL),
-			Command:       viewString(view, "command", imported.Server.Command),
-			Args:          oauth.LiveRedaction.Argv(imported.Server.Args),
+			URL:           redactedURL,
+			Command:       redactedCommand,
+			Args:          redactedArgs,
 			SourceFormat:  string(imported.SourceFormat),
 			OriginalName:  imported.OriginalName,
 			FieldsSkipped: imported.FieldsSkipped,
 			Warnings:      imported.Warnings,
+			Summary:       summary,
+			Tags:          tags,
+			Env:           env,
+			Headers:       headers,
 		}
 	}
 
@@ -480,7 +531,92 @@ func parseFormat(format string) configimport.ConfigFormat {
 		return configimport.FormatCodex
 	case "gemini":
 		return configimport.FormatGemini
+	case "url":
+		return configimport.FormatURL
+	case "command":
+		return configimport.FormatCommand
 	default:
 		return configimport.FormatUnknown
 	}
 }
+
+// placeholderValuePattern matches a value that reads as a placeholder rather
+// than a real secret/config value (FR-064 "empty_or_placeholder"): angle
+// brackets, a bare ${...} reference, or one of the conventional
+// fill-me-in words.
+var placeholderValuePattern = regexp.MustCompile(`(?i)^(<.*>|\$\{[^}]*\}|x{3,}|changeme|change[-_ ]me|placeholder|your[-_ ].*|example|todo|redacted|\*+|-+)$`)
+
+// looksEmptyOrPlaceholder reports whether value is empty or reads as a
+// fill-me-in placeholder rather than a real value.
+func looksEmptyOrPlaceholder(value string) bool {
+	v := strings.TrimSpace(value)
+	if v == "" {
+		return true
+	}
+	return placeholderValuePattern.MatchString(v)
+}
+
+// buildImportPreviewFields computes the FR-064 preview enrichment (summary,
+// tags, env/header field previews) from the mapped server config. summaryURL
+// and summaryCommand/summaryArgs are the ALREADY-REDACTED values the caller
+// just built for the response (viewString / oauth.LiveRedaction.Argv), so a
+// secret embedded in argv or a URL query flows through the same redaction
+// exactly once and never reaches Summary via a second, unredacted path.
+func buildImportPreviewFields(server *config.ServerConfig, redactedURL, redactedCommand string, redactedArgs []string) (summary string, tags []string, env []EnvFieldPreview, headers []HeaderFieldPreview) {
+	if redactedURL != "" {
+		summary = redactedURL
+		tags = append(tags, "remote")
+	} else if redactedCommand != "" {
+		parts := append([]string{redactedCommand}, redactedArgs...)
+		summary = strings.Join(parts, " ")
+		tags = append(tags, "local process")
+	}
+
+	needsSecret := false
+
+	envNames := make([]string, 0, len(server.Env))
+	for name := range server.Env {
+		envNames = append(envNames, name)
+	}
+	sort.Strings(envNames)
+	for _, name := range envNames {
+		value := server.Env[name]
+		like := secretlike.LooksSecret(name)
+		if like {
+			needsSecret = true
+		}
+		env = append(env, EnvFieldPreview{
+			Name:               name,
+			ValuePresent:       value != "",
+			SecretLike:         like,
+			EmptyOrPlaceholder: looksEmptyOrPlaceholder(value),
+		})
+	}
+
+	headerNames := make([]string, 0, len(server.Headers))
+	for name := range server.Headers {
+		headerNames = append(headerNames, name)
+	}
+	sort.Strings(headerNames)
+	for _, name := range headerNames {
+		value := server.Headers[name]
+		like := secretlike.LooksSecret(name)
+		if like {
+			needsSecret = true
+		}
+		headers = append(headers, HeaderFieldPreview{
+			Name:               name,
+			SecretLike:         like,
+			EmptyOrPlaceholder: looksEmptyOrPlaceholder(value),
+		})
+	}
+
+	if needsSecret {
+		tags = append(tags, "needs secret")
+	}
+	if server.OAuth != nil {
+		tags = append(tags, "oauth")
+	}
+
+	return summary, tags, env, headers
+}
diff --git a/internal/httpapi/import_preview_fields_test.go b/internal/httpapi/import_preview_fields_test.go
new file mode 100644
index 000000000..92a8ac583
--- /dev/null
+++ b/internal/httpapi/import_preview_fields_test.go
@@ -0,0 +1,167 @@
+package httpapi
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"go.uber.org/zap"
+)
+
+// TestImportPreview_URLFormat pins FR-064: a pasted http(s) URL previews as a
+// remote server via auto-detection, with no format hint.
+func TestImportPreview_URLFormat(t *testing.T) {
+	logger := zap.NewNop().Sugar()
+	mock := &mockImportController{apiKey: "test-key"}
+	server := NewServer(mock, logger, nil)
+
+	body, _ := json.Marshal(ImportRequest{Content: "https://api.githubcopilot.com/mcp/"})
+	req := httptest.NewRequest("POST", "/api/v1/servers/import/json?preview=true", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-API-Key", "test-key")
+	rr := httptest.NewRecorder()
+	server.router.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", rr.Code, rr.Body.String())
+	}
+	var wrapped wrappedImportResponse
+	if err := json.Unmarshal(rr.Body.Bytes(), &wrapped); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if wrapped.Data.Format != "url" {
+		t.Errorf("expected format 'url', got %q", wrapped.Data.Format)
+	}
+	if len(wrapped.Data.Imported) != 1 {
+		t.Fatalf("expected 1 imported server, got %d", len(wrapped.Data.Imported))
+	}
+	imported := wrapped.Data.Imported[0]
+	if imported.Protocol != "http" || imported.URL != "https://api.githubcopilot.com/mcp/" {
+		t.Errorf("unexpected imported server: %+v", imported)
+	}
+	if imported.Command != "" {
+		t.Errorf("expected no command for a URL import, got %q", imported.Command)
+	}
+}
+
+// TestImportPreview_CommandFormat pins FR-064: a pasted command line previews
+// as a local/stdio server via auto-detection.
+func TestImportPreview_CommandFormat(t *testing.T) {
+	logger := zap.NewNop().Sugar()
+	mock := &mockImportController{apiKey: "test-key"}
+	server := NewServer(mock, logger, nil)
+
+	body, _ := json.Marshal(ImportRequest{Content: "npx -y @modelcontextprotocol/server-filesystem /tmp"})
+	req := httptest.NewRequest("POST", "/api/v1/servers/import/json?preview=true", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-API-Key", "test-key")
+	rr := httptest.NewRecorder()
+	server.router.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", rr.Code, rr.Body.String())
+	}
+	var wrapped wrappedImportResponse
+	if err := json.Unmarshal(rr.Body.Bytes(), &wrapped); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if wrapped.Data.Format != "command" {
+		t.Errorf("expected format 'command', got %q", wrapped.Data.Format)
+	}
+	if len(wrapped.Data.Imported) != 1 {
+		t.Fatalf("expected 1 imported server, got %d", len(wrapped.Data.Imported))
+	}
+	imported := wrapped.Data.Imported[0]
+	if imported.Command != "npx" {
+		t.Errorf("expected command 'npx', got %q", imported.Command)
+	}
+	if imported.Summary != "npx -y @modelcontextprotocol/server-filesystem /tmp" {
+		t.Errorf("unexpected summary: %q", imported.Summary)
+	}
+	found := false
+	for _, tag := range imported.Tags {
+		if tag == "local process" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("expected 'local process' tag, got %v", imported.Tags)
+	}
+}
+
+// TestImportPreview_EnvHeaderSecretLikeAndPlaceholder pins the contract
+// example shape (contracts/rest-api.md "Import preview"): env/header entries
+// carry secret_like and empty_or_placeholder, env additionally carries
+// value_present, and no raw secret value appears in the response.
+func TestImportPreview_EnvHeaderSecretLikeAndPlaceholder(t *testing.T) {
+	logger := zap.NewNop().Sugar()
+	mock := &mockImportController{apiKey: "test-key"}
+	server := NewServer(mock, logger, nil)
+
+	reqBody := ImportRequest{Content: `{
+		"mcpServers": {
+			"github": {
+				"command": "uvx",
+				"args": ["mcp-server-github"],
+				"env": {"GITHUB_TOKEN": "sk-live-abc123", "WORKDIR": ""}
+			}
+		}
+	}`}
+	body, _ := json.Marshal(reqBody)
+	req := httptest.NewRequest("POST", "/api/v1/servers/import/json?preview=true", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-API-Key", "test-key")
+	rr := httptest.NewRecorder()
+	server.router.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", rr.Code, rr.Body.String())
+	}
+	if bytesContains(rr.Body.Bytes(), "sk-live-abc123") {
+		t.Fatal("raw secret value must never appear in the import preview response")
+	}
+
+	var wrapped wrappedImportResponse
+	if err := json.Unmarshal(rr.Body.Bytes(), &wrapped); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	imported := wrapped.Data.Imported[0]
+
+	var tokenField, workdirField *EnvFieldPreview
+	for i := range imported.Env {
+		switch imported.Env[i].Name {
+		case "GITHUB_TOKEN":
+			tokenField = &imported.Env[i]
+		case "WORKDIR":
+			workdirField = &imported.Env[i]
+		}
+	}
+	if tokenField == nil || workdirField == nil {
+		t.Fatalf("expected both env fields present, got %+v", imported.Env)
+	}
+	if !tokenField.SecretLike || !tokenField.ValuePresent || tokenField.EmptyOrPlaceholder {
+		t.Errorf("unexpected GITHUB_TOKEN preview: %+v", tokenField)
+	}
+	if workdirField.SecretLike {
+		t.Errorf("WORKDIR must not be secret_like: %+v", workdirField)
+	}
+	if workdirField.ValuePresent || !workdirField.EmptyOrPlaceholder {
+		t.Errorf("empty WORKDIR must read value_present=false, empty_or_placeholder=true: %+v", workdirField)
+	}
+
+	found := false
+	for _, tag := range imported.Tags {
+		if tag == "needs secret" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("expected 'needs secret' tag, got %v", imported.Tags)
+	}
+}
+
+func bytesContains(haystack []byte, needle string) bool {
+	return bytes.Contains(haystack, []byte(needle))
+}

From 5c8644b49a7492f5e33c368a769bdffaf5d0a33b Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 00:47:50 +0300
Subject: [PATCH 13/27] feat(cli): add 'mcpproxy catalog search|show|add'
 (FR-066)

- cliclient.CatalogSearch calls GET /catalog/search.
- cmd/mcpproxy/catalog_cmd.go: catalog search/show/add, daemon-first
  with an in-process SearchAll fallback for search; 'registry
  search'/'registry add' now print a deprecation notice pointing at
  their 'catalog' equivalent (both remain functional aliases).
- registries.BuildCatalogHit/ToCatalogResult exported so a single-entry
  lookup (catalog show) builds the same shape SearchAll uses.

Fixes a bug caught while wiring this up: the 'added' join treated every
configured server as matching by install-target alone, so a
registry-sourced server (source_registry_id set) could make a
DIFFERENT source's identical-looking entry falsely read added=true.
Only a manual add (no source_registry_id) matches by target alone; a
registry-sourced one also needs its own source_registry_id to match.
Fixed in both internal/httpapi/catalog.go and cmd/mcpproxy/catalog_cmd.go,
with a regression test in internal/httpapi/catalog_test.go.
---
 cmd/mcpproxy/catalog_cmd.go        | 406 +++++++++++++++++++++++++++++
 cmd/mcpproxy/catalog_cmd_test.go   | 195 ++++++++++++++
 cmd/mcpproxy/main.go               |   1 +
 cmd/mcpproxy/registry_cmd.go       |   2 +
 internal/cliclient/catalog.go      |  83 ++++++
 internal/cliclient/catalog_test.go |  43 +++
 internal/httpapi/catalog.go        |  14 +-
 internal/httpapi/catalog_test.go   |  32 +++
 internal/registries/catalog.go     |   9 +-
 9 files changed, 776 insertions(+), 9 deletions(-)
 create mode 100644 cmd/mcpproxy/catalog_cmd.go
 create mode 100644 cmd/mcpproxy/catalog_cmd_test.go
 create mode 100644 internal/cliclient/catalog.go
 create mode 100644 internal/cliclient/catalog_test.go

diff --git a/cmd/mcpproxy/catalog_cmd.go b/cmd/mcpproxy/catalog_cmd.go
new file mode 100644
index 000000000..33be53549
--- /dev/null
+++ b/cmd/mcpproxy/catalog_cmd.go
@@ -0,0 +1,406 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	clioutput "github.com/smart-mcp-proxy/mcpproxy-go/internal/cli/output"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/cliclient"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/registries"
+)
+
+// printCatalogDeprecationNotice prints the FR-066 deprecation note to
+// stderr: 'registry search'/'registry add' remain as aliases (scripts must
+// not break), but point at their 'catalog' equivalent.
+func printCatalogDeprecationNotice(oldCmd, newCmd string) {
+	fmt.Fprintf(os.Stderr, "Note: 'mcpproxy %s' is deprecated; use 'mcpproxy %s' instead.\n", oldCmd, newCmd)
+}
+
+// Catalog command flags (Spec 109 FR-060/066).
+var (
+	catalogSearchSource string
+	catalogSearchTag    string
+	catalogSearchLimit  int
+	catalogAddName      string
+	catalogAddEnv       []string
+	catalogAddEnabled   bool
+)
+
+// GetCatalogCommand builds the `catalog` command group (Spec 109 FR-066): a
+// source-agnostic search/browse/add flow layered over the same registries
+// `registry` manages as sources.
+//
+// 'catalog' supersedes 'registry search'/'registry add' for DISCOVERY; the
+// commands that manage catalog sources themselves — 'registry
+// list'/'add-source'/'edit'/'remove' — are unchanged and keep their name
+// (renaming a command group breaks scripts, research D17).
+func GetCatalogCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "catalog",
+		Short: "Browse and add MCP servers from the catalog",
+		Long: `Search across every enabled catalog source (registry) in one call, or browse
+the curated official/popular sections with no query.
+
+  mcpproxy catalog search github                                  # search every source
+  mcpproxy catalog search                                          # browse official + popular
+  mcpproxy catalog show official/io.github.github/github-mcp-server
+  mcpproxy catalog add official/io.github.github/github-mcp-server
+  mcpproxy upstream approve <name>                                 # approve once trusted
+
+'catalog search'/'catalog add' supersede 'registry search'/'registry add'.
+'registry list'/'add-source'/'edit'/'remove' still manage catalog SOURCES.`,
+	}
+	cmd.PersistentFlags().StringVarP(&registryConfigPath, "config", "c", "", "Path to MCP configuration file")
+	cmd.AddCommand(newCatalogSearchCmd(), newCatalogShowCmd(), newCatalogAddCmd())
+	return cmd
+}
+
+func newCatalogSearchCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "search [query]",
+		Short: "Search the catalog across every enabled source",
+		Long: `Search every enabled catalog source at once (FR-060), ranked official-first,
+then verified, then popularity, then text relevance. Omit the query to browse
+the curated "official" and "popular" sections instead.`,
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(_ *cobra.Command, args []string) error {
+			query := ""
+			if len(args) > 0 {
+				query = args[0]
+			}
+
+			cfg, err := loadRegistryConfig()
+			if err != nil {
+				return outputError(clioutput.NewStructuredError(clioutput.ErrCodeConfigNotFound, err.Error()).
+					WithRecoveryCommand("mcpproxy doctor"), clioutput.ErrCodeConfigNotFound)
+			}
+			formatter, err := GetOutputFormatter()
+			if err != nil {
+				return err
+			}
+
+			ctx, cancel := registryContext()
+			defer cancel()
+			resp, err := catalogSearch(ctx, cfg, query, catalogSearchSource, catalogSearchTag, catalogSearchLimit)
+			if err != nil {
+				return outputError(clioutput.NewStructuredError(clioutput.ErrCodeOperationFailed, err.Error()), clioutput.ErrCodeOperationFailed)
+			}
+			return renderCatalogSearch(formatter, resp)
+		},
+	}
+	cmd.Flags().StringVar(&catalogSearchSource, "source", "", "Narrow to one catalog source id (use 'registry list' to see ids)")
+	cmd.Flags().StringVarP(&catalogSearchTag, "tag", "t", "", "Filter by tag")
+	cmd.Flags().IntVarP(&catalogSearchLimit, "limit", "l", 20, "Maximum number of results (default 20, max 50)")
+	return cmd
+}
+
+func newCatalogShowCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "show <source>/<id>",
+		Short: "Show one catalog entry's details",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(_ *cobra.Command, args []string) error {
+			source, id, err := parseCatalogRef(args[0])
+			if err != nil {
+				return outputError(clioutput.NewStructuredError(clioutput.ErrCodeInvalidInput, err.Error()).
+					WithGuidance("Pass '<source>/<id>', e.g. official/io.github.github/github-mcp-server"), clioutput.ErrCodeInvalidInput)
+			}
+
+			cfg, err := loadRegistryConfig()
+			if err != nil {
+				return outputError(clioutput.NewStructuredError(clioutput.ErrCodeConfigNotFound, err.Error()).
+					WithRecoveryCommand("mcpproxy doctor"), clioutput.ErrCodeConfigNotFound)
+			}
+			formatter, err := GetOutputFormatter()
+			if err != nil {
+				return err
+			}
+
+			ctx, cancel := registryContext()
+			defer cancel()
+			registries.SetRegistriesFromConfig(cfg)
+			reg := registries.FindRegistry(source)
+			if reg == nil {
+				return outputError(clioutput.NewStructuredError(clioutput.ErrCodeServerNotFound, fmt.Sprintf("catalog source %q not found", source)).
+					WithGuidance("Use 'mcpproxy registry list' to see source ids"), clioutput.ErrCodeServerNotFound)
+			}
+			entry, err := registries.FindServerByID(ctx, source, id, nil)
+			if err != nil {
+				return outputError(clioutput.NewStructuredError(clioutput.ErrCodeServerNotFound, err.Error()).
+					WithGuidance("Use 'mcpproxy catalog search' to find the id"), clioutput.ErrCodeServerNotFound)
+			}
+
+			hit := registries.BuildCatalogHit(reg, *entry)
+			result := registries.ToCatalogResult(hit, catalogAddedFromConfig(cfg)(hit))
+			return renderCatalogShow(formatter, result)
+		},
+	}
+	return cmd
+}
+
+func newCatalogAddCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "add <source>/<id>",
+		Short: "Add a catalog entry as a (quarantined) upstream server",
+		Long: `Add a server found via 'catalog search'/'catalog show' as an upstream server.
+The server is added quarantined by default; approve it once you trust it:
+  mcpproxy upstream approve <name>
+
+This is the same keystone add operation as 'registry add <source> <id>' (Spec
+070) — it just takes the combined "<source>/<id>" ref catalog results print.`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(_ *cobra.Command, args []string) error {
+			source, id, err := parseCatalogRef(args[0])
+			if err != nil {
+				return outputError(clioutput.NewStructuredError(clioutput.ErrCodeInvalidInput, err.Error()).
+					WithGuidance("Pass '<source>/<id>', e.g. official/io.github.github/github-mcp-server"), clioutput.ErrCodeInvalidInput)
+			}
+
+			env, err := parseRegistryEnv(catalogAddEnv)
+			if err != nil {
+				return err
+			}
+
+			cfg, err := loadRegistryConfig()
+			if err != nil {
+				return outputError(clioutput.NewStructuredError(clioutput.ErrCodeConfigNotFound, err.Error()).
+					WithRecoveryCommand("mcpproxy doctor"), clioutput.ErrCodeConfigNotFound)
+			}
+
+			// add MUST go through the daemon (keystone op is server-side, same as
+			// 'registry add').
+			client, ok := newDaemonClient(cfg, nil)
+			if !ok {
+				return outputError(clioutput.NewStructuredError(clioutput.ErrCodeConnectionFailed,
+					"adding from the catalog requires a running mcpproxy daemon").
+					WithGuidance("Start the daemon, then retry").
+					WithRecoveryCommand("mcpproxy serve"), clioutput.ErrCodeConnectionFailed)
+			}
+
+			ctx, cancel := registryContext()
+			defer cancel()
+			enabled := catalogAddEnabled
+			result, err := client.AddFromRegistry(ctx, source, id, catalogAddName, env, &enabled)
+			if err != nil {
+				return registryAddErrorOutput(err)
+			}
+
+			outputFormat := ResolveOutputFormat()
+			if outputFormat == "json" || outputFormat == "yaml" {
+				formatter, _ := GetOutputFormatter()
+				out, _ := formatter.Format(result)
+				fmt.Println(out)
+				return nil
+			}
+
+			// FR-063: identical wording to 'registry add' and the Web/macOS "Add
+			// to MCPProxy" action.
+			fmt.Println(registryAddMessage(result.Name, result.Quarantined))
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&catalogAddName, "name", "", "Override the server name")
+	cmd.Flags().StringArrayVar(&catalogAddEnv, "env", nil, "Set an environment variable (KEY=VALUE); repeatable")
+	cmd.Flags().BoolVar(&catalogAddEnabled, "enabled", true, "Whether the added server is enabled")
+	return cmd
+}
+
+// parseCatalogRef splits a "<source>/<id>" ref on the FIRST '/' only, since
+// an official-protocol id is itself reverse-DNS-shaped and contains further
+// slashes (e.g. "io.github.github/github-mcp-server").
+func parseCatalogRef(ref string) (source, id string, err error) {
+	parts := strings.SplitN(ref, "/", 2)
+	if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
+		return "", "", fmt.Errorf("invalid catalog ref %q: expected '<source>/<id>'", ref)
+	}
+	return parts[0], parts[1], nil
+}
+
+// catalogSearch is daemon-first with an in-process fallback (mirrors
+// 'registry search'), so catalog discovery works whether or not a daemon is
+// running.
+func catalogSearch(ctx context.Context, cfg *config.Config, q, source, tag string, limit int) (*cliclient.CatalogSearchResponse, error) {
+	if client, ok := newDaemonClient(cfg, nil); ok {
+		if resp, derr := client.CatalogSearch(ctx, q, source, tag, limit); derr == nil {
+			return resp, nil
+		}
+		// Fall through to in-process on daemon error.
+	}
+	// Load the effective registry list (built-in defaults + the user's
+	// configured sources) once, here, so catalogSearchInProcess itself stays
+	// a pure function over whatever registries.ListRegistries() currently
+	// returns — which is also what makes it independently testable against a
+	// fixture list (registries.SetRegistriesForTest).
+	registries.SetRegistriesFromConfig(cfg)
+	return catalogSearchInProcess(ctx, cfg, q, source, tag, limit)
+}
+
+// catalogSearchInProcess mirrors handleCatalogSearch (internal/httpapi) but
+// computes "added" directly from the loaded config, since the CLI's
+// in-process fallback has no scoped caller to narrow against. It reads
+// whatever registries.ListRegistries() currently returns rather than loading
+// it itself — see catalogSearch, its only production caller.
+func catalogSearchInProcess(ctx context.Context, cfg *config.Config, q, source, tag string, limit int) (*cliclient.CatalogSearchResponse, error) {
+	hits, sections, unavailable := registries.SearchAll(ctx, q, tag, limit, registries.SearchOptions{})
+	if source != "" {
+		hits = filterCatalogHitsBySourceCLI(hits, source)
+		if sections != nil {
+			sections = &registries.CatalogSections{
+				Official: filterCatalogHitsBySourceCLI(sections.Official, source),
+				Popular:  filterCatalogHitsBySourceCLI(sections.Popular, source),
+			}
+		}
+	}
+
+	added := catalogAddedFromConfig(cfg)
+	resp := &cliclient.CatalogSearchResponse{Query: q, Unavailable: unavailable}
+	if resp.Unavailable == nil {
+		resp.Unavailable = []registries.SourceError{}
+	}
+	for _, h := range hits {
+		resp.Results = append(resp.Results, registries.ToCatalogResult(h, added(h)))
+	}
+	if sections != nil {
+		resp.Sections = &cliclient.CatalogSections{}
+		for _, h := range sections.Official {
+			resp.Sections.Official = append(resp.Sections.Official, registries.ToCatalogResult(h, added(h)))
+		}
+		for _, h := range sections.Popular {
+			resp.Sections.Popular = append(resp.Sections.Popular, registries.ToCatalogResult(h, added(h)))
+		}
+	}
+	return resp, nil
+}
+
+func filterCatalogHitsBySourceCLI(hits []registries.CatalogHit, source string) []registries.CatalogHit {
+	out := make([]registries.CatalogHit, 0, len(hits))
+	for _, h := range hits {
+		if h.Source == source {
+			out = append(out, h)
+		}
+	}
+	return out
+}
+
+// catalogAddedFromConfig returns a predicate reporting whether a catalog hit
+// matches an already-configured server (contracts/rest-api.md#catalog "added"):
+// a registry-sourced server also needs a matching source, a manual add
+// matches on install target alone.
+func catalogAddedFromConfig(cfg *config.Config) func(registries.CatalogHit) bool {
+	byRegistryAndTarget := make(map[string]bool)
+	byTargetOnly := make(map[string]bool)
+	if cfg != nil {
+		for _, s := range cfg.Servers {
+			if s == nil {
+				continue
+			}
+			target := catalogInstallTargetForConfigServer(s)
+			if s.SourceRegistryID == "" {
+				// Manual add: matches any source by install target alone.
+				byTargetOnly[target] = true
+			} else {
+				// Registry-sourced: must also match its own source, so it
+				// never falsely matches a different source's identical
+				// install target (contracts/rest-api.md#catalog "added").
+				byRegistryAndTarget[s.SourceRegistryID+"\x00"+target] = true
+			}
+		}
+	}
+	return func(h registries.CatalogHit) bool {
+		target := registries.CatalogInstallTarget(registries.ToCatalogResult(h, false).Install)
+		if byRegistryAndTarget[h.Source+"\x00"+target] {
+			return true
+		}
+		return byTargetOnly[target]
+	}
+}
+
+func catalogInstallTargetForConfigServer(s *config.ServerConfig) string {
+	if s.URL != "" {
+		return "url:" + s.URL
+	}
+	return "cmd:" + s.Command + " " + strings.Join(s.Args, " ")
+}
+
+// renderCatalogSearch prints a search response as a table (or the raw
+// formatter output for json/yaml).
+func renderCatalogSearch(formatter clioutput.OutputFormatter, resp *cliclient.CatalogSearchResponse) error {
+	if _, isTable := formatter.(*clioutput.TableFormatter); isTable {
+		if resp.Sections != nil {
+			fmt.Println("Official:")
+			printCatalogTable(formatter, resp.Sections.Official)
+			fmt.Println("\nPopular:")
+			printCatalogTable(formatter, resp.Sections.Popular)
+		} else {
+			printCatalogTable(formatter, resp.Results)
+		}
+		for _, u := range resp.Unavailable {
+			fmt.Printf("⚠ %s unavailable: %s\n", u.Source, u.Reason)
+		}
+		return nil
+	}
+	out, err := formatter.Format(resp)
+	if err != nil {
+		return err
+	}
+	fmt.Println(out)
+	return nil
+}
+
+func printCatalogTable(formatter clioutput.OutputFormatter, results []registries.CatalogResult) {
+	headers := []string{"SOURCE", "ID", "TITLE", "TRANSPORT", "ADDED"}
+	rows := make([][]string, 0, len(results))
+	for _, r := range results {
+		added := ""
+		if r.Added {
+			added = "✓"
+		}
+		rows = append(rows, []string{r.Source, r.ID, truncateStr(r.Title, 40), r.Transport, added})
+	}
+	out, err := formatter.FormatTable(headers, rows)
+	if err == nil {
+		fmt.Print(out)
+	}
+	fmt.Printf("Found %d results. Add one with: mcpproxy catalog add <source>/<id>\n", len(results))
+}
+
+func renderCatalogShow(formatter clioutput.OutputFormatter, result registries.CatalogResult) error {
+	if _, isTable := formatter.(*clioutput.TableFormatter); isTable {
+		fmt.Printf("%s\n", result.Title)
+		fmt.Printf("  ref:         %s/%s\n", result.Source, result.ID)
+		if result.Publisher != "" {
+			fmt.Printf("  publisher:   %s\n", result.Publisher)
+		}
+		fmt.Printf("  official:    %v\n", result.Official)
+		fmt.Printf("  verified:    %v\n", result.Verified)
+		fmt.Printf("  transport:   %s\n", result.Transport)
+		if result.Install.URL != "" {
+			fmt.Printf("  install url: %s\n", result.Install.URL)
+		} else {
+			fmt.Printf("  install cmd: %s %s\n", result.Install.Command, strings.Join(result.Install.Args, " "))
+		}
+		if result.Description != "" {
+			fmt.Printf("  description: %s\n", result.Description)
+		}
+		for _, in := range result.RequiredInputs {
+			secret := ""
+			if in.SecretLike {
+				secret = " (secret)"
+			}
+			fmt.Printf("  requires:    %s%s\n", in.Name, secret)
+		}
+		fmt.Printf("  added:       %v\n", result.Added)
+		return nil
+	}
+	out, err := formatter.Format(result)
+	if err != nil {
+		return err
+	}
+	fmt.Println(out)
+	return nil
+}
diff --git a/cmd/mcpproxy/catalog_cmd_test.go b/cmd/mcpproxy/catalog_cmd_test.go
new file mode 100644
index 000000000..349e2452e
--- /dev/null
+++ b/cmd/mcpproxy/catalog_cmd_test.go
@@ -0,0 +1,195 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/registries"
+)
+
+// TestParseCatalogRef_SplitsOnFirstSlashOnly pins that an official-protocol
+// id (itself reverse-DNS-shaped, e.g. "io.github.github/github-mcp-server")
+// is not mangled by the "<source>/<id>" split (FR-066).
+func TestParseCatalogRef_SplitsOnFirstSlashOnly(t *testing.T) {
+	source, id, err := parseCatalogRef("official/io.github.github/github-mcp-server")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if source != "official" {
+		t.Errorf("source = %q, want %q", source, "official")
+	}
+	if id != "io.github.github/github-mcp-server" {
+		t.Errorf("id = %q, want %q", id, "io.github.github/github-mcp-server")
+	}
+}
+
+func TestParseCatalogRef_RejectsMissingSlash(t *testing.T) {
+	if _, _, err := parseCatalogRef("no-slash-here"); err == nil {
+		t.Fatal("expected an error for a ref with no '/'")
+	}
+}
+
+// TestCatalogAddedFromConfig pins the join rule (contracts/rest-api.md#catalog
+// "added"): a registry-sourced configured server needs source AND install
+// target; a manual add matches on install target alone.
+func TestCatalogAddedFromConfig(t *testing.T) {
+	cfg := &config.Config{
+		Servers: []*config.ServerConfig{
+			{Name: "manual", URL: "https://manual.example.com/mcp"},
+			{Name: "from-official", Command: "npx", Args: []string{"server-x"}, SourceRegistryID: "official"},
+		},
+	}
+	added := catalogAddedFromConfig(cfg)
+
+	manualHit := registries.CatalogHit{Source: "smithery", Entry: registries.ServerEntry{ID: "m", URL: "https://manual.example.com/mcp"}}
+	if !added(manualHit) {
+		t.Error("expected a manual add to match by install target regardless of source")
+	}
+
+	officialHit := registries.CatalogHit{Source: "official", Entry: registries.ServerEntry{ID: "x", InstallCmd: "npx server-x"}}
+	if !added(officialHit) {
+		t.Error("expected the registry-sourced server to match its own source + target")
+	}
+
+	wrongSourceHit := registries.CatalogHit{Source: "smithery", Entry: registries.ServerEntry{ID: "x", InstallCmd: "npx server-x"}}
+	if added(wrongSourceHit) {
+		t.Error("a registry-sourced configured server must not match a different source with the same target")
+	}
+
+	noMatchHit := registries.CatalogHit{Source: "official", Entry: registries.ServerEntry{ID: "y", InstallCmd: "npx server-y"}}
+	if added(noMatchHit) {
+		t.Error("expected no match for an unrelated entry")
+	}
+}
+
+func withCatalogCLIFixture(t *testing.T, body string) {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(body))
+	}))
+	t.Cleanup(srv.Close)
+	t.Cleanup(registries.AllowPrivateRegistryFetchForTest())
+	t.Cleanup(registries.SetRegistriesForTest([]registries.RegistryEntry{
+		{ID: "official", Name: "Official", ServersURL: srv.URL, Provenance: "official"},
+	}))
+}
+
+// TestCatalogSearchInProcess_Search is the T100 "search" golden: a non-empty
+// query prints a flat results table.
+func TestCatalogSearchInProcess_Search(t *testing.T) {
+	withCatalogCLIFixture(t, `[{"id":"gh","name":"GitHub Tool","description":"d"}]`)
+	cfg := &config.Config{}
+
+	resp, err := catalogSearchInProcess(context.Background(), cfg, "github", "", "", 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(resp.Results) != 1 || resp.Results[0].ID != "gh" {
+		t.Fatalf("unexpected results: %+v", resp.Results)
+	}
+	if resp.Sections != nil {
+		t.Fatalf("expected nil sections for a non-empty query, got %+v", resp.Sections)
+	}
+
+	formatter, err := GetOutputFormatter()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := captureOutput(func() {
+		if err := renderCatalogSearch(formatter, resp); err != nil {
+			t.Fatalf("render error: %v", err)
+		}
+	})
+	if !strings.Contains(out, "GitHub Tool") || !strings.Contains(out, "official") || !strings.Contains(out, "gh") {
+		t.Errorf("expected the table to name the source, id and title, got:\n%s", out)
+	}
+}
+
+// TestCatalogSearchInProcess_BrowseSections is the T100 "browse sections"
+// golden: an empty query prints Official/Popular sections.
+func TestCatalogSearchInProcess_BrowseSections(t *testing.T) {
+	withCatalogCLIFixture(t, `[{"id":"gh","name":"GitHub Tool"}]`)
+	cfg := &config.Config{}
+
+	resp, err := catalogSearchInProcess(context.Background(), cfg, "", "", "", 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if resp.Sections == nil {
+		t.Fatal("expected sections for an empty query")
+	}
+
+	formatter, err := GetOutputFormatter()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := captureOutput(func() {
+		if err := renderCatalogSearch(formatter, resp); err != nil {
+			t.Fatalf("render error: %v", err)
+		}
+	})
+	if !strings.Contains(out, "Official:") || !strings.Contains(out, "Popular:") {
+		t.Errorf("expected Official/Popular section headers, got:\n%s", out)
+	}
+}
+
+// TestCatalogShow is the T100 "show" golden.
+func TestCatalogShow(t *testing.T) {
+	withCatalogCLIFixture(t, `[{"id":"gh","name":"GitHub Tool","description":"desc","url":"https://x.example.com/mcp"}]`)
+
+	// withCatalogCLIFixture already installed the fixture registry list —
+	// unlike catalogSearch's production path, this test must NOT also call
+	// registries.SetRegistriesFromConfig, which would replace it with the
+	// real built-in defaults and go to the network.
+	reg := registries.FindRegistry("official")
+	if reg == nil {
+		t.Fatal("expected the fixture 'official' source to be registered")
+	}
+	entry, err := registries.FindServerByID(context.Background(), "official", "gh", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	hit := registries.BuildCatalogHit(reg, *entry)
+	result := registries.ToCatalogResult(hit, false)
+
+	formatter, err := GetOutputFormatter()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := captureOutput(func() {
+		if err := renderCatalogShow(formatter, result); err != nil {
+			t.Fatalf("render error: %v", err)
+		}
+	})
+	if !strings.Contains(out, "GitHub Tool") || !strings.Contains(out, "official/gh") || !strings.Contains(out, "https://x.example.com/mcp") {
+		t.Errorf("unexpected show output:\n%s", out)
+	}
+}
+
+// TestPrintCatalogDeprecationNotice pins FR-066: 'registry search'/'registry
+// add' print a deprecation note pointing at the 'catalog' equivalent.
+func TestPrintCatalogDeprecationNotice(t *testing.T) {
+	old := os.Stderr
+	r, w, _ := os.Pipe()
+	os.Stderr = w
+
+	printCatalogDeprecationNotice("registry add", "catalog add official/gh")
+
+	w.Close()
+	os.Stderr = old
+	var buf bytes.Buffer
+	_, _ = io.Copy(&buf, r)
+
+	out := buf.String()
+	if !strings.Contains(out, "deprecated") || !strings.Contains(out, "catalog add official/gh") {
+		t.Errorf("unexpected deprecation notice: %q", out)
+	}
+}
diff --git a/cmd/mcpproxy/main.go b/cmd/mcpproxy/main.go
index 6c30940b5..98b3b7310 100644
--- a/cmd/mcpproxy/main.go
+++ b/cmd/mcpproxy/main.go
@@ -206,6 +206,7 @@ func main() {
 	rootCmd.AddCommand(newSandboxExecCommand())
 	rootCmd.AddCommand(searchCmd)
 	rootCmd.AddCommand(GetRegistryCommand())
+	rootCmd.AddCommand(GetCatalogCommand())
 	rootCmd.AddCommand(toolsCmd)
 	rootCmd.AddCommand(callCmd)
 	rootCmd.AddCommand(codeCmd)
diff --git a/cmd/mcpproxy/registry_cmd.go b/cmd/mcpproxy/registry_cmd.go
index 66df6b0da..0e307e0c7 100644
--- a/cmd/mcpproxy/registry_cmd.go
+++ b/cmd/mcpproxy/registry_cmd.go
@@ -361,6 +361,7 @@ The printed ID column is what you pass to 'registry add'.`,
 			if registryID == "" {
 				return fmt.Errorf("--registry is required (use 'mcpproxy registry list' to see available ids)")
 			}
+			printCatalogDeprecationNotice("registry search", fmt.Sprintf("catalog search %s --source %s", query, registryID))
 
 			ctx, cancel := registryContext()
 			defer cancel()
@@ -431,6 +432,7 @@ inputs, supply them with --env KEY=VALUE.`,
 		Args: cobra.ExactArgs(2),
 		RunE: func(_ *cobra.Command, args []string) error {
 			registryID, serverID := args[0], args[1]
+			printCatalogDeprecationNotice("registry add", fmt.Sprintf("catalog add %s/%s", registryID, serverID))
 
 			env, err := parseRegistryEnv(registryAddEnv)
 			if err != nil {
diff --git a/internal/cliclient/catalog.go b/internal/cliclient/catalog.go
new file mode 100644
index 000000000..3c5add63a
--- /dev/null
+++ b/internal/cliclient/catalog.go
@@ -0,0 +1,83 @@
+package cliclient
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/registries"
+)
+
+// CatalogSearchResponse mirrors GET /api/v1/catalog/search's response body
+// (contracts/rest-api.md#catalog).
+type CatalogSearchResponse struct {
+	Query       string                     `json:"query"`
+	Results     []registries.CatalogResult `json:"results"`
+	Sections    *CatalogSections           `json:"sections"`
+	Unavailable []registries.SourceError   `json:"unavailable"`
+}
+
+// CatalogSections mirrors the REST empty-query landing sections.
+type CatalogSections struct {
+	Official []registries.CatalogResult `json:"official"`
+	Popular  []registries.CatalogResult `json:"popular"`
+}
+
+// CatalogSearch calls GET /api/v1/catalog/search (Spec 109 FR-060/066), the
+// backend for `mcpproxy catalog search|show`.
+func (c *Client) CatalogSearch(ctx context.Context, q, source, tag string, limit int) (*CatalogSearchResponse, error) {
+	u := c.baseURL + "/api/v1/catalog/search"
+	params := url.Values{}
+	if q != "" {
+		params.Set("q", q)
+	}
+	if source != "" {
+		params.Set("source", source)
+	}
+	if tag != "" {
+		params.Set("tag", tag)
+	}
+	if limit > 0 {
+		params.Set("limit", strconv.Itoa(limit))
+	}
+	if enc := params.Encode(); enc != "" {
+		u += "?" + enc
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+	c.prepareRequest(ctx, req)
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to call catalog search API: %w", err)
+	}
+	defer resp.Body.Close()
+
+	bodyBytes, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("API returned status %d: %s", resp.StatusCode, string(bodyBytes))
+	}
+
+	var apiResp struct {
+		Success bool                  `json:"success"`
+		Data    CatalogSearchResponse `json:"data"`
+		Error   string                `json:"error"`
+	}
+	if err := json.Unmarshal(bodyBytes, &apiResp); err != nil {
+		return nil, fmt.Errorf("failed to parse response: %w", err)
+	}
+	if !apiResp.Success {
+		return nil, parseAPIError(apiResp.Error, "")
+	}
+	return &apiResp.Data, nil
+}
diff --git a/internal/cliclient/catalog_test.go b/internal/cliclient/catalog_test.go
new file mode 100644
index 000000000..4a3ea5c95
--- /dev/null
+++ b/internal/cliclient/catalog_test.go
@@ -0,0 +1,43 @@
+package cliclient
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestClient_CatalogSearch(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/v1/catalog/search" {
+			t.Errorf("unexpected path: %s", r.URL.Path)
+		}
+		q := r.URL.Query()
+		if q.Get("q") != "github" || q.Get("source") != "official" || q.Get("tag") != "" || q.Get("limit") != "5" {
+			t.Errorf("unexpected query: %s", r.URL.RawQuery)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{
+			"success": true,
+			"data": {
+				"query": "github",
+				"results": [{"source":"official","id":"gh","title":"GitHub","transport":"http","install":{"url":"https://x"},"added":false}],
+				"sections": null,
+				"unavailable": []
+			}
+		}`))
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, nil)
+	resp, err := c.CatalogSearch(context.Background(), "github", "official", "", 5)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if resp.Query != "github" {
+		t.Errorf("unexpected query: %q", resp.Query)
+	}
+	if len(resp.Results) != 1 || resp.Results[0].ID != "gh" {
+		t.Fatalf("unexpected results: %+v", resp.Results)
+	}
+}
diff --git a/internal/httpapi/catalog.go b/internal/httpapi/catalog.go
index 212db97c7..b065834f8 100644
--- a/internal/httpapi/catalog.go
+++ b/internal/httpapi/catalog.go
@@ -110,15 +110,19 @@ func (s *Server) catalogAddedPredicate(ctx context.Context) func(registries.Cata
 	servers := s.getVisibleServersForCatalog(ctx)
 
 	// byRegistryAndTarget indexes servers that declare which registry they
-	// came from; bySourcelessTarget indexes every visible server (including
-	// registry-sourced ones) by install target alone, since a manual add has
-	// no source_registry_id and must still match.
+	// came from — those must match on (source, target); byTargetOnly indexes
+	// only the manual adds (no source_registry_id), which match on target
+	// alone. A registry-sourced server is deliberately NOT also added to
+	// byTargetOnly: without this split it would falsely read added:true for
+	// every OTHER source whose entry happens to share the same install
+	// target (contracts/rest-api.md#catalog "added").
 	byRegistryAndTarget := make(map[string]bool, len(servers))
 	byTargetOnly := make(map[string]bool, len(servers))
 	for _, srv := range servers {
 		target := catalogInstallTargetForServer(srv)
-		byTargetOnly[target] = true
-		if srv.SourceRegistryID != "" {
+		if srv.SourceRegistryID == "" {
+			byTargetOnly[target] = true
+		} else {
 			byRegistryAndTarget[srv.SourceRegistryID+"\x00"+target] = true
 		}
 	}
diff --git a/internal/httpapi/catalog_test.go b/internal/httpapi/catalog_test.go
index c1550904f..0f7b2d46e 100644
--- a/internal/httpapi/catalog_test.go
+++ b/internal/httpapi/catalog_test.go
@@ -56,9 +56,21 @@ func withCatalogFixtureRegistry(t *testing.T) {
 	}))
 	t.Cleanup(srv.Close)
 
+	// A second source whose entry shares delta-tool's exact install target
+	// (same command) but under a DIFFERENT source id — the regression fixture
+	// for the "registry-sourced match needs (source, target), not target
+	// alone" rule.
+	otherBody := `[{"id":"lookalike-tool","name":"Lookalike Tool","installCmd":"npx delta-server"}]`
+	otherSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(otherBody))
+	}))
+	t.Cleanup(otherSrv.Close)
+
 	t.Cleanup(registries.AllowPrivateRegistryFetchForTest())
 	t.Cleanup(registries.SetRegistriesForTest([]registries.RegistryEntry{
 		{ID: "official", Name: "Official", ServersURL: srv.URL},
+		{ID: "other", Name: "Other", ServersURL: otherSrv.URL},
 	}))
 }
 
@@ -112,6 +124,26 @@ func TestCatalogSearch_AddedScopedByCallerVisibility(t *testing.T) {
 	assert.NotContains(t, agentRec.Body.String(), catalogDeltaSecretMarker)
 }
 
+// TestCatalogSearch_AddedRequiresMatchingSourceForRegistryAdd is the
+// regression for a bug caught while implementing this: a registry-sourced
+// configured server (source_registry_id set) must NOT cause a different
+// source's entry with the same install target to also read added:true —
+// only a server with NO source_registry_id (a manual add) matches by target
+// alone (contracts/rest-api.md#catalog "added").
+func TestCatalogSearch_AddedRequiresMatchingSourceForRegistryAdd(t *testing.T) {
+	withCatalogFixtureRegistry(t)
+	ctrl := &scopeController{cfg: scopeFixtureConfig(false), servers: catalogFixtureServers(), withManagement: true}
+	srv, _ := scopedAgentServer(t, ctrl, []string{"gamma"})
+
+	rec := scopeGet(t, srv, "/api/v1/catalog/search?q=tool", scopeAdminAPIKey)
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	results := catalogDecodeResults(t, rec)
+
+	assert.True(t, catalogAddedFor(results, "delta-tool"), "delta-tool (source=official) must match delta (source_registry_id=official)")
+	assert.False(t, catalogAddedFor(results, "lookalike-tool"),
+		"lookalike-tool (source=other) shares delta's install target but must NOT read added=true — delta was added from a different source")
+}
+
 func catalogDecodeResults(t *testing.T, rec *httptest.ResponseRecorder) []map[string]interface{} {
 	t.Helper()
 	data := scopeDecodeData(t, rec)
diff --git a/internal/registries/catalog.go b/internal/registries/catalog.go
index 0a0e999b3..382178c8b 100644
--- a/internal/registries/catalog.go
+++ b/internal/registries/catalog.go
@@ -153,7 +153,7 @@ func SearchAll(ctx context.Context, q, tag string, limit int, opts SearchOptions
 
 			hits := make([]CatalogHit, 0, len(entries))
 			for _, e := range entries {
-				hits = append(hits, buildCatalogHit(&reg, e))
+				hits = append(hits, BuildCatalogHit(&reg, e))
 			}
 			outcomes[i] = sourceOutcome{hits: hits}
 		}(i)
@@ -193,13 +193,14 @@ func SearchAll(ctx context.Context, q, tag string, limit int, opts SearchOptions
 	return all, sections, unavailable
 }
 
-// buildCatalogHit derives the catalog-only fields (Title, Publisher,
+// BuildCatalogHit derives the catalog-only fields (Title, Publisher,
 // Verified, Official, Popularity) from a registry entry. Verified currently
 // tracks Official — no registry in this spec supplies an independent
 // publisher-verification signal yet, so a trusted (built-in) source's
 // namespace is the only verification evidence available (data-model §9,
-// research D12).
-func buildCatalogHit(reg *RegistryEntry, entry ServerEntry) CatalogHit {
+// research D12). Exported so a single-entry lookup (CLI `catalog show`) can
+// build the same CatalogHit shape SearchAll uses internally.
+func BuildCatalogHit(reg *RegistryEntry, entry ServerEntry) CatalogHit {
 	official := reg.IsTrusted()
 	title := entry.Name
 	if title == "" {

From 99866852a306b037ddb4195c7342a5096eeb5b4b Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 00:51:12 +0300
Subject: [PATCH 14/27] feat(cli): add 'upstream add
 --secret-env/--secret-header' (FR-065)

Each value is written to the OS keyring under its per-kind ref name
(internal/secret.RefName: <server>-env-<name> / <server>-header-<name>)
and the config gets ${keyring:<ref>} instead of the raw value. An env
var and a header of the same name write two distinct entries; a
pre-existing entry is left unchanged and the new ref gets a numeric
suffix (D28). Refuses outright, before writing anything, when the
keyring is unavailable.
---
 cmd/mcpproxy/upstream_add_secret.go      |  76 ++++++++++
 cmd/mcpproxy/upstream_add_secret_test.go | 179 +++++++++++++++++++++++
 cmd/mcpproxy/upstream_cmd.go             |  18 +++
 3 files changed, 273 insertions(+)
 create mode 100644 cmd/mcpproxy/upstream_add_secret.go
 create mode 100644 cmd/mcpproxy/upstream_add_secret_test.go

diff --git a/cmd/mcpproxy/upstream_add_secret.go b/cmd/mcpproxy/upstream_add_secret.go
new file mode 100644
index 000000000..4482560e3
--- /dev/null
+++ b/cmd/mcpproxy/upstream_add_secret.go
@@ -0,0 +1,76 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/secret"
+)
+
+// applySecretFlags stores each --secret-env/--secret-header value in the OS
+// keyring under its Spec 109 FR-065 ref name (internal/secret.RefName) and
+// merges ${keyring:<ref>} into env/headers in place, so the caller's
+// AddServerRequest never carries the raw value. It refuses outright — before
+// writing anything — when the keyring is unavailable, naming the provider's
+// own reason, rather than silently falling back to plaintext.
+func applySecretFlags(resolver *secret.Resolver, serverName string, secretEnvs, secretHeaders []string, env, headers map[string]string) error {
+	if len(secretEnvs) == 0 && len(secretHeaders) == 0 {
+		return nil
+	}
+
+	if ok, reason := resolver.KeyringAvailability(); !ok {
+		return fmt.Errorf("cannot store --secret-env/--secret-header: OS keyring unavailable (%s)", reason)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	existing, err := resolver.ListAll(ctx)
+	if err != nil {
+		return fmt.Errorf("failed to list existing keyring entries: %w", err)
+	}
+	taken := make(map[string]bool, len(existing))
+	for _, ref := range existing {
+		if ref.Type == secret.SecretTypeKeyring {
+			taken[ref.Name] = true
+		}
+	}
+	// A ref this call itself just wrote must also count as taken for the
+	// remaining flags in the same invocation, or two identically-named
+	// --secret-env flags (or a rerun before ListAll's cache would see it)
+	// would compute the same ref twice instead of a[-2] suffix (D28: never
+	// overwrite an existing secret).
+	takenFn := func(n string) bool { return taken[n] }
+
+	for _, kv := range secretEnvs {
+		name, value, ok := strings.Cut(kv, "=")
+		if !ok {
+			return fmt.Errorf("invalid --secret-env format: %q (expected KEY=value)", kv)
+		}
+		ref := secret.RefName(serverName, "env", name, takenFn)
+		if err := resolver.Store(ctx, secret.Ref{Type: secret.SecretTypeKeyring, Name: ref}, value); err != nil {
+			return fmt.Errorf("failed to store secret for env %s: %w", name, err)
+		}
+		taken[ref] = true
+		env[name] = fmt.Sprintf("${keyring:%s}", ref)
+	}
+
+	for _, kv := range secretHeaders {
+		name, value, ok := strings.Cut(kv, ":")
+		if !ok {
+			return fmt.Errorf("invalid --secret-header format: %q (expected 'Name: value')", kv)
+		}
+		name = strings.TrimSpace(name)
+		value = strings.TrimSpace(value)
+		ref := secret.RefName(serverName, "header", name, takenFn)
+		if err := resolver.Store(ctx, secret.Ref{Type: secret.SecretTypeKeyring, Name: ref}, value); err != nil {
+			return fmt.Errorf("failed to store secret for header %s: %w", name, err)
+		}
+		taken[ref] = true
+		headers[name] = fmt.Sprintf("${keyring:%s}", ref)
+	}
+
+	return nil
+}
diff --git a/cmd/mcpproxy/upstream_add_secret_test.go b/cmd/mcpproxy/upstream_add_secret_test.go
new file mode 100644
index 000000000..b39d90099
--- /dev/null
+++ b/cmd/mcpproxy/upstream_add_secret_test.go
@@ -0,0 +1,179 @@
+package main
+
+import (
+	"context"
+	"testing"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/secret"
+)
+
+// fakeKeyringProvider is an in-memory secret.Provider standing in for the OS
+// keyring, so these tests never touch the real Keychain/Secret Service/WinCred.
+type fakeKeyringProvider struct {
+	available bool
+	store     map[string]string
+}
+
+func newFakeKeyringProvider(available bool) *fakeKeyringProvider {
+	return &fakeKeyringProvider{available: available, store: map[string]string{}}
+}
+
+func (f *fakeKeyringProvider) CanResolve(secretType string) bool { return secretType == "keyring" }
+func (f *fakeKeyringProvider) Resolve(_ context.Context, ref secret.Ref) (string, error) {
+	return f.store[ref.Name], nil
+}
+func (f *fakeKeyringProvider) Store(_ context.Context, ref secret.Ref, value string) error {
+	f.store[ref.Name] = value
+	return nil
+}
+func (f *fakeKeyringProvider) Delete(_ context.Context, ref secret.Ref) error {
+	delete(f.store, ref.Name)
+	return nil
+}
+func (f *fakeKeyringProvider) List(_ context.Context) ([]secret.Ref, error) {
+	refs := make([]secret.Ref, 0, len(f.store))
+	for name := range f.store {
+		refs = append(refs, secret.Ref{Type: "keyring", Name: name})
+	}
+	return refs, nil
+}
+func (f *fakeKeyringProvider) IsAvailable() bool { return f.available }
+
+func newTestSecretResolver(fake *fakeKeyringProvider) *secret.Resolver {
+	r := secret.NewResolver()
+	r.RegisterProvider("keyring", fake)
+	return r
+}
+
+// TestApplySecretFlags_WritesKeyringRefsIntoEnvAndHeaders pins FR-065: values
+// are written to the keyring, never left in env/headers, and both maps get
+// ${keyring:<ref>} instead.
+func TestApplySecretFlags_WritesKeyringRefsIntoEnvAndHeaders(t *testing.T) {
+	fake := newFakeKeyringProvider(true)
+	resolver := newTestSecretResolver(fake)
+
+	env := map[string]string{}
+	headers := map[string]string{}
+	err := applySecretFlags(resolver, "github",
+		[]string{"GITHUB_TOKEN=sk-live-abc123"},
+		[]string{"Authorization: Bearer xyz"},
+		env, headers,
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	envRef, ok := env["GITHUB_TOKEN"]
+	if !ok || envRef != "${keyring:github-env-github-token}" {
+		t.Errorf("unexpected env ref: %q", envRef)
+	}
+	if fake.store["github-env-github-token"] != "sk-live-abc123" {
+		t.Errorf("expected the raw value stored in the keyring, got %q", fake.store["github-env-github-token"])
+	}
+
+	headerRef, ok := headers["Authorization"]
+	if !ok || headerRef != "${keyring:github-header-authorization}" {
+		t.Errorf("unexpected header ref: %q", headerRef)
+	}
+	if fake.store["github-header-authorization"] != "Bearer xyz" {
+		t.Errorf("expected the raw header value stored in the keyring, got %q", fake.store["github-header-authorization"])
+	}
+}
+
+// TestApplySecretFlags_EnvHeaderSameNameCollision pins FR-065's headline
+// collision case: an env var and a header with the SAME NAME write two
+// DISTINCT keyring entries, and each field resolves to its own ref.
+func TestApplySecretFlags_EnvHeaderSameNameCollision(t *testing.T) {
+	fake := newFakeKeyringProvider(true)
+	resolver := newTestSecretResolver(fake)
+
+	env := map[string]string{}
+	headers := map[string]string{}
+	err := applySecretFlags(resolver, "github",
+		[]string{"API_KEY=env-value"},
+		[]string{"API_KEY: header-value"},
+		env, headers,
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if env["API_KEY"] != "${keyring:github-env-api-key}" {
+		t.Errorf("unexpected env ref: %q", env["API_KEY"])
+	}
+	if headers["API_KEY"] != "${keyring:github-header-api-key}" {
+		t.Errorf("unexpected header ref: %q", headers["API_KEY"])
+	}
+	if fake.store["github-env-api-key"] != "env-value" {
+		t.Errorf("env-value stored under the wrong ref: %+v", fake.store)
+	}
+	if fake.store["github-header-api-key"] != "header-value" {
+		t.Errorf("header-value stored under the wrong ref: %+v", fake.store)
+	}
+}
+
+// TestApplySecretFlags_TakenNameGetsSuffix pins D28: a pre-existing keyring
+// entry is left unchanged and the new ref gets a numeric suffix.
+func TestApplySecretFlags_TakenNameGetsSuffix(t *testing.T) {
+	fake := newFakeKeyringProvider(true)
+	fake.store["github-env-api-key"] = "PRE-EXISTING-UNRELATED-VALUE"
+	resolver := newTestSecretResolver(fake)
+
+	env := map[string]string{}
+	if err := applySecretFlags(resolver, "github", []string{"API_KEY=new-value"}, nil, env, map[string]string{}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if env["API_KEY"] != "${keyring:github-env-api-key-2}" {
+		t.Errorf("expected the -2 suffixed ref, got %q", env["API_KEY"])
+	}
+	if fake.store["github-env-api-key"] != "PRE-EXISTING-UNRELATED-VALUE" {
+		t.Error("the pre-existing entry must be left unchanged (D28: never overwrite)")
+	}
+	if fake.store["github-env-api-key-2"] != "new-value" {
+		t.Errorf("expected the new value under the -2 ref, got %+v", fake.store)
+	}
+}
+
+// TestApplySecretFlags_KeyringUnavailableRefuses pins FR-065: an unavailable
+// keyring refuses with the reason, writing nothing.
+func TestApplySecretFlags_KeyringUnavailableRefuses(t *testing.T) {
+	fake := newFakeKeyringProvider(false)
+	resolver := newTestSecretResolver(fake)
+
+	env := map[string]string{}
+	err := applySecretFlags(resolver, "github", []string{"API_KEY=value"}, nil, env, map[string]string{})
+	if err == nil {
+		t.Fatal("expected an error when the keyring is unavailable")
+	}
+	if len(env) != 0 {
+		t.Errorf("expected env untouched on refusal, got %+v", env)
+	}
+	if len(fake.store) != 0 {
+		t.Errorf("expected nothing written to the keyring on refusal, got %+v", fake.store)
+	}
+}
+
+// TestApplySecretFlags_NoFlagsIsNoOp pins that the OS keyring is never probed
+// (and no error possible) when neither flag was passed.
+func TestApplySecretFlags_NoFlagsIsNoOp(t *testing.T) {
+	fake := newFakeKeyringProvider(false) // unavailable — must not matter
+	resolver := newTestSecretResolver(fake)
+
+	if err := applySecretFlags(resolver, "github", nil, nil, map[string]string{}, map[string]string{}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// TestApplySecretFlags_InvalidFormat pins input validation for both flags.
+func TestApplySecretFlags_InvalidFormat(t *testing.T) {
+	fake := newFakeKeyringProvider(true)
+	resolver := newTestSecretResolver(fake)
+
+	if err := applySecretFlags(resolver, "github", []string{"NOEQUALS"}, nil, map[string]string{}, map[string]string{}); err == nil {
+		t.Error("expected an error for a --secret-env value with no '='")
+	}
+	if err := applySecretFlags(resolver, "github", nil, []string{"NoColonHere"}, map[string]string{}, map[string]string{}); err == nil {
+		t.Error("expected an error for a --secret-header value with no ':'")
+	}
+}
diff --git a/cmd/mcpproxy/upstream_cmd.go b/cmd/mcpproxy/upstream_cmd.go
index cd52c46f7..7d1401df2 100644
--- a/cmd/mcpproxy/upstream_cmd.go
+++ b/cmd/mcpproxy/upstream_cmd.go
@@ -25,6 +25,7 @@ import (
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/logs"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/oauth"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/reqcontext"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/secret"
 )
 
 var (
@@ -274,6 +275,12 @@ Examples:
 	upstreamAddIfNotExists  bool
 	upstreamAddNoQuarantine bool
 	upstreamAddTrustMode    string
+	// upstreamAddSecretEnvs/Headers are the Spec 109 FR-065 secret flags:
+	// each value is written to the OS keyring under the FR-065 ref name
+	// (internal/secret.RefName) and the config gets ${keyring:<ref>} instead
+	// of the raw value.
+	upstreamAddSecretEnvs    []string
+	upstreamAddSecretHeaders []string
 
 	// Remove command flags
 	upstreamRemoveYes      bool
@@ -353,6 +360,8 @@ func init() {
 	upstreamAddCmd.Flags().BoolVar(&upstreamAddIfNotExists, "if-not-exists", false, "Don't error if server already exists")
 	upstreamAddCmd.Flags().BoolVar(&upstreamAddNoQuarantine, "no-quarantine", false, "Don't quarantine the new server (use with caution)")
 	upstreamAddCmd.Flags().StringVar(&upstreamAddTrustMode, "trust-mode", "", "Per-server trust tier governing admission AND tool-change approval: auto (approve without scanning), scan (auto-approve only when the offline TPA scan is green), manual (human reviews every change). Unset inherits the default (manual)")
+	upstreamAddCmd.Flags().StringArrayVar(&upstreamAddSecretEnvs, "secret-env", nil, "Environment variable to store in the OS keyring instead of the config, in KEY=value format (repeatable, FR-065)")
+	upstreamAddCmd.Flags().StringArrayVar(&upstreamAddSecretHeaders, "secret-header", nil, "HTTP header to store in the OS keyring instead of the config, in 'Name: value' format (repeatable, FR-065)")
 
 	// Remove command flags
 	upstreamRemoveCmd.Flags().BoolVar(&upstreamRemoveYes, "yes", false, "Skip confirmation prompt")
@@ -1273,6 +1282,15 @@ func runUpstreamAdd(cmd *cobra.Command, args []string) error {
 		env[parts[0]] = parts[1]
 	}
 
+	// FR-065: --secret-env/--secret-header write to the OS keyring instead
+	// of the config, under the shared per-kind ref name, and merge
+	// ${keyring:<ref>} into the same env/headers maps above.
+	if len(upstreamAddSecretEnvs) > 0 || len(upstreamAddSecretHeaders) > 0 {
+		if err := applySecretFlags(secret.NewResolver(), serverName, upstreamAddSecretEnvs, upstreamAddSecretHeaders, env, headers); err != nil {
+			return err
+		}
+	}
+
 	// GH #938: refuse a typo'd tier before anything is written, with the same
 	// vocabulary the REST layer reports in its 400.
 	if err := validateTrustModeFlag(upstreamAddTrustMode); err != nil {

From 466ab2e7941b2e342dc90481471bc1a6d7d092f4 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 01:25:44 +0300
Subject: [PATCH 15/27] feat(web): add the catalog-first /add-server page (Spec
 109 FR-060-065)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- views/AddServer.vue: Catalog (default) · Paste · Import · Manual tabs,
  synced to ?tab= via router.replace; ?source= narrows the Catalog tab
  only and never selects a tab.
- components/CatalogSearch.vue: searches every enabled catalog source
  (GET /catalog/search), renders official/popular sections for an empty
  query, 'Add to MCPProxy' -> 'Added ✓ · Open', and a secrets
  prompt for entries with required_inputs. Catalog-source text (title,
  description, publisher) is rendered as plain text only (D19).
- components/PasteServer.vue: detects a pasted URL/command/JSON/TOML via
  the extended import-preview endpoint and shows its summary/tags before
  anything is added.
- components/ManualServerForm.vue / ImportServersPanel.vue: the Manual
  and Import tabs.
- components/SecretToggle.vue + composables/useSecretFields.ts: the
  shared Value/Secret toggle (FR-065) used by all three tabs that take
  env/header input — writes to the OS keyring via the shared refName
  algorithm, rolls back only the secrets a failed add itself wrote.
- utils/secretRef.ts / secretLike.ts: TS ports of the Go refName/
  secret-like-name helpers, pinned against the shared
  internal/secret/testdata/ref_names.json fixture (copied into
  tests/unit/fixtures/). ServerDetail.vue's old suggestSecretName (which
  dropped the field kind) now delegates to the shared helper.
- router: /repositories redirects to /add-server?tab=catalog; TopHeader's
  "+ Add Server" now opens the new page.
- components/CatalogSourcesSettings.vue: catalog-SOURCE management
  (add/edit/delete a registry) moved out of the retired Repositories.vue
  into Settings -> Catalog sources; server BROWSING moved to
  CatalogSearch.vue. The 5 Repositories-specific tests were retired or
  retargeted (settings-catalog-sources.spec.ts, z-index-scale.spec.ts);
  add-server-catalog.spec.ts now covers the FR-063 label behavior.

Known gap (documented, not fixed in this PR): AddServerModal.vue and its
other callers (Servers.vue, Dashboard.vue, OnboardingWizard.vue) are left
as-is — retiring them fully cascades into ~9 existing test files
(protocol detection, duplicate-endpoint, trust-mode, a11y) that are out
of this PR's scope; TopHeader's primary entry point was the one rewired.
---
 frontend/src/components/CatalogSearch.vue     |  310 +++++
 .../src/components/CatalogSourcesSettings.vue |  390 ++++++
 .../src/components/ImportServersPanel.vue     |  140 ++
 frontend/src/components/ManualServerForm.vue  |  163 +++
 frontend/src/components/PasteServer.vue       |  186 +++
 frontend/src/components/SecretToggle.vue      |   82 ++
 frontend/src/components/SidebarNav.vue        |   10 +-
 frontend/src/components/TopHeader.vue         |   22 +-
 frontend/src/composables/useSecretFields.ts   |   84 ++
 frontend/src/router/index.ts                  |   16 +-
 frontend/src/services/api.ts                  |   21 +-
 frontend/src/types/api.ts                     |   79 ++
 frontend/src/utils/secretLike.ts              |   10 +
 frontend/src/utils/secretRef.ts               |   54 +
 frontend/src/views/AddServer.vue              |   82 ++
 frontend/src/views/Repositories.vue           | 1149 -----------------
 frontend/src/views/ServerDetail.vue           |   17 +-
 frontend/src/views/Settings.vue               |   14 +
 .../tests/unit/add-server-catalog.spec.ts     |  113 ++
 frontend/tests/unit/add-server-paste.spec.ts  |  134 ++
 .../tests/unit/add-server-tab-url.spec.ts     |   67 +
 .../tests/unit/add-to-mcpproxy-label.spec.ts  |  121 --
 frontend/tests/unit/fixtures/ref_names.json   |   47 +
 .../unit/repositories-add-registry.spec.ts    |  149 ---
 .../unit/repositories-card-selector.spec.ts   |  125 --
 .../repositories-manage-registries.spec.ts    |  168 ---
 .../tests/unit/repositories-redirect.spec.ts  |   35 +
 ...es-registry-dialog-escape-inflight.spec.ts |  153 ---
 frontend/tests/unit/secret-ref.spec.ts        |   52 +
 frontend/tests/unit/secret-toggle.spec.ts     |  137 ++
 .../unit/settings-catalog-sources.spec.ts     |  128 ++
 frontend/tests/unit/z-index-scale.spec.ts     |   32 +-
 32 files changed, 2375 insertions(+), 1915 deletions(-)
 create mode 100644 frontend/src/components/CatalogSearch.vue
 create mode 100644 frontend/src/components/CatalogSourcesSettings.vue
 create mode 100644 frontend/src/components/ImportServersPanel.vue
 create mode 100644 frontend/src/components/ManualServerForm.vue
 create mode 100644 frontend/src/components/PasteServer.vue
 create mode 100644 frontend/src/components/SecretToggle.vue
 create mode 100644 frontend/src/composables/useSecretFields.ts
 create mode 100644 frontend/src/utils/secretLike.ts
 create mode 100644 frontend/src/utils/secretRef.ts
 create mode 100644 frontend/src/views/AddServer.vue
 delete mode 100644 frontend/src/views/Repositories.vue
 create mode 100644 frontend/tests/unit/add-server-catalog.spec.ts
 create mode 100644 frontend/tests/unit/add-server-paste.spec.ts
 create mode 100644 frontend/tests/unit/add-server-tab-url.spec.ts
 delete mode 100644 frontend/tests/unit/add-to-mcpproxy-label.spec.ts
 create mode 100644 frontend/tests/unit/fixtures/ref_names.json
 delete mode 100644 frontend/tests/unit/repositories-add-registry.spec.ts
 delete mode 100644 frontend/tests/unit/repositories-card-selector.spec.ts
 delete mode 100644 frontend/tests/unit/repositories-manage-registries.spec.ts
 create mode 100644 frontend/tests/unit/repositories-redirect.spec.ts
 delete mode 100644 frontend/tests/unit/repositories-registry-dialog-escape-inflight.spec.ts
 create mode 100644 frontend/tests/unit/secret-ref.spec.ts
 create mode 100644 frontend/tests/unit/secret-toggle.spec.ts
 create mode 100644 frontend/tests/unit/settings-catalog-sources.spec.ts

diff --git a/frontend/src/components/CatalogSearch.vue b/frontend/src/components/CatalogSearch.vue
new file mode 100644
index 000000000..7b7fed465
--- /dev/null
+++ b/frontend/src/components/CatalogSearch.vue
@@ -0,0 +1,310 @@
+<template>
+  <div data-test="catalog-search">
+    <div class="flex gap-2 mb-4">
+      <input
+        v-model="query"
+        type="text"
+        placeholder="Search the catalog (e.g. 'github', 'filesystem')…"
+        class="input input-bordered flex-1"
+        data-test="catalog-search-input"
+      />
+    </div>
+
+    <div v-if="loading" class="flex items-center gap-2 py-4 text-base-content/70" data-test="catalog-loading">
+      <span class="loading loading-spinner loading-sm" /> Searching the catalog…
+    </div>
+
+    <div v-else-if="error" class="alert alert-error text-sm" data-test="catalog-error">{{ error }}</div>
+
+    <template v-else>
+      <div v-if="unavailable.length > 0" class="alert alert-warning text-sm mb-3" data-test="catalog-unavailable-notice">
+        <span>{{ unavailable.map((u) => `${u.source} (${u.reason})`).join(', ') }} unavailable</span>
+      </div>
+
+      <template v-if="sections">
+        <div v-if="sections.official.length > 0" data-test="catalog-section-official">
+          <h4 class="font-semibold text-sm text-base-content/70 mb-2">Official</h4>
+          <div class="grid grid-cols-1 md:grid-cols-2 gap-3 mb-6">
+            <CatalogResultCard
+              v-for="r in sections.official"
+              :key="`${r.source}-${r.id}`"
+              :result="r"
+              :keyring-available="keyringAvailable"
+              :keyring-reason="keyringReason"
+              :busy="addingKey === `${r.source}-${r.id}`"
+              @add="handleAdd(r)"
+            />
+          </div>
+        </div>
+        <div v-if="sections.popular.length > 0" data-test="catalog-section-popular">
+          <h4 class="font-semibold text-sm text-base-content/70 mb-2">Popular</h4>
+          <div class="grid grid-cols-1 md:grid-cols-2 gap-3">
+            <CatalogResultCard
+              v-for="r in sections.popular"
+              :key="`${r.source}-${r.id}`"
+              :result="r"
+              :keyring-available="keyringAvailable"
+              :keyring-reason="keyringReason"
+              :busy="addingKey === `${r.source}-${r.id}`"
+              @add="handleAdd(r)"
+            />
+          </div>
+        </div>
+        <div v-if="sections.official.length === 0 && sections.popular.length === 0" class="text-sm text-base-content/60 py-4">
+          Nothing to browse yet.
+        </div>
+      </template>
+
+      <template v-else>
+        <p class="text-sm text-base-content/70 mb-3" data-test="catalog-results-count">
+          {{ results.length }} result{{ results.length === 1 ? '' : 's' }}
+        </p>
+        <div class="grid grid-cols-1 md:grid-cols-2 gap-3">
+          <CatalogResultCard
+            v-for="r in results"
+            :key="`${r.source}-${r.id}`"
+            :result="r"
+            :keyring-available="keyringAvailable"
+            :keyring-reason="keyringReason"
+            :busy="addingKey === `${r.source}-${r.id}`"
+            @add="handleAdd(r)"
+          />
+        </div>
+      </template>
+    </template>
+
+    <!-- Secret-inputs panel for an entry with required_inputs (FR-065). -->
+    <dialog ref="secretsDialogEl" class="modal" data-test="catalog-secrets-dialog">
+      <div class="modal-box">
+        <h3 class="font-bold text-lg mb-1">{{ pendingResult?.title }}</h3>
+        <p class="text-sm text-base-content/70 mb-4">This server needs a few values before it can run.</p>
+        <div class="space-y-3">
+          <SecretToggle
+            v-for="input in pendingResult?.required_inputs || []"
+            :key="input.name"
+            :name="input.name"
+            kind="env"
+            :model-value="pendingValues[input.name] || ''"
+            :mode="pendingModes[input.name] || (input.secret_like ? 'secret' : 'value')"
+            :keyring-available="keyringAvailable"
+            :keyring-reason="keyringReason"
+            @update:model-value="(v) => (pendingValues[input.name] = v)"
+            @update:mode="(m) => (pendingModes[input.name] = m)"
+          />
+        </div>
+        <div v-if="addError" class="alert alert-error text-sm mt-3" data-test="catalog-add-error">{{ addError }}</div>
+        <div class="modal-action">
+          <button type="button" class="btn btn-ghost" data-test="catalog-secrets-cancel" @click="closeSecretsDialog">
+            Cancel
+          </button>
+          <button
+            type="button"
+            class="btn btn-primary"
+            :disabled="!allPendingValuesFilled || confirming"
+            data-test="catalog-secrets-confirm"
+            @click="confirmAdd"
+          >
+            Add to MCPProxy
+          </button>
+        </div>
+      </div>
+    </dialog>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive, computed, watch, onMounted, defineComponent, h } from 'vue'
+import { useRouter } from 'vue-router'
+import api from '@/services/api'
+import type { CatalogResult, CatalogSections } from '@/types'
+import SecretToggle from '@/components/SecretToggle.vue'
+import { resolveSecretFields } from '@/composables/useSecretFields'
+import { useDialogOpen } from '@/composables/useDialogOpen'
+import { serverDetailPath } from '@/utils/serverRoute'
+
+const props = defineProps<{ source?: string }>()
+const emit = defineEmits<{ added: [name: string] }>()
+
+const query = ref('')
+const loading = ref(false)
+const error = ref<string | null>(null)
+const results = ref<CatalogResult[]>([])
+const sections = ref<CatalogSections | null>(null)
+const unavailable = ref<{ source: string; reason: string }[]>([])
+const addingKey = ref<string | null>(null)
+// FR-063: once added this page-visit, the entry's button flips to "Added ✓ ·
+// Open" and stays that way (a fresh search doesn't re-fetch config, so an
+// entry the user just added would otherwise flash back to "Add to MCPProxy").
+const addedNames = reactive<Record<string, string>>({})
+
+const keyringAvailable = ref(true)
+const keyringReason = ref('')
+
+let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+async function runSearch() {
+  loading.value = true
+  error.value = null
+  try {
+    const resp = await api.catalogSearch({ q: query.value, source: props.source })
+    if (!resp.success || !resp.data) {
+      error.value = resp.error || 'Search failed'
+      results.value = []
+      sections.value = null
+      return
+    }
+    results.value = resp.data.results
+    sections.value = resp.data.sections
+    unavailable.value = resp.data.unavailable || []
+  } catch (e) {
+    error.value = e instanceof Error ? e.message : 'Search failed'
+  } finally {
+    loading.value = false
+  }
+}
+
+watch([query, () => props.source], () => {
+  if (debounceTimer) clearTimeout(debounceTimer)
+  debounceTimer = setTimeout(runSearch, 250)
+})
+
+onMounted(async () => {
+  const secretsResp = await api.getConfigSecrets()
+  if (secretsResp.success && secretsResp.data) {
+    keyringAvailable.value = secretsResp.data.keyring_available
+    keyringReason.value = secretsResp.data.keyring_reason || ''
+  }
+  await runSearch()
+})
+
+// Secrets-prompt dialog state
+const pendingResult = ref<CatalogResult | null>(null)
+const pendingValues = reactive<Record<string, string>>({})
+const pendingModes = reactive<Record<string, 'value' | 'secret'>>({})
+const addError = ref<string | null>(null)
+const confirming = ref(false)
+const { dialogEl: secretsDialogEl } = useDialogOpen(
+  () => pendingResult.value !== null,
+  () => closeSecretsDialog()
+)
+
+const allPendingValuesFilled = computed(() => {
+  const inputs = pendingResult.value?.required_inputs || []
+  return inputs.every((i) => (pendingValues[i.name] || '').trim() !== '')
+})
+
+function handleAdd(result: CatalogResult) {
+  const key = `${result.source}-${result.id}`
+  if (result.required_inputs && result.required_inputs.length > 0) {
+    pendingResult.value = result
+    for (const key of Object.keys(pendingValues)) delete pendingValues[key]
+    for (const key of Object.keys(pendingModes)) delete pendingModes[key]
+    for (const input of result.required_inputs) {
+      pendingModes[input.name] = input.secret_like ? 'secret' : 'value'
+    }
+    addError.value = null
+    return
+  }
+  void addResult(result, key, {})
+}
+
+function closeSecretsDialog() {
+  pendingResult.value = null
+  addError.value = null
+}
+
+async function confirmAdd() {
+  if (!pendingResult.value) return
+  confirming.value = true
+  addError.value = null
+  try {
+    const result = pendingResult.value
+    const fields = (result.required_inputs || []).map((i) => ({
+      kind: 'env' as const,
+      name: i.name,
+      value: pendingValues[i.name] || '',
+      mode: pendingModes[i.name] || 'value',
+    }))
+    const resolved = await resolveSecretFields(result.title || result.id, fields)
+    await addResult(result, `${result.source}-${result.id}`, resolved.env)
+    closeSecretsDialog()
+  } catch (e) {
+    addError.value = e instanceof Error ? e.message : 'Failed to add server'
+  } finally {
+    confirming.value = false
+  }
+}
+
+async function addResult(result: CatalogResult, key: string, env: Record<string, string>) {
+  addingKey.value = key
+  try {
+    const res = await api.addServerFromRegistry(result.source, result.id, { env })
+    if (res.success && res.server?.name) {
+      addedNames[key] = res.server.name
+      emit('added', res.server.name)
+    } else {
+      addError.value = res.error || 'Failed to add server'
+    }
+  } finally {
+    addingKey.value = null
+  }
+}
+
+// CatalogResultCard is a small local functional-ish component (kept in this
+// file rather than a separate SFC: it is presentational-only and has no
+// reason to be reused outside CatalogSearch).
+const CatalogResultCard = defineComponent({
+  props: {
+    result: { type: Object as () => CatalogResult, required: true },
+    keyringAvailable: { type: Boolean, required: true },
+    keyringReason: { type: String, default: '' },
+    busy: { type: Boolean, default: false },
+  },
+  emits: ['add'],
+  setup(cardProps, { emit: cardEmit }) {
+    const router = useRouter()
+    return () => {
+      const r = cardProps.result
+      const key = `${r.source}-${r.id}`
+      const addedName = addedNames[key]
+      const added = !!addedName || r.added
+      return h(
+        'div',
+        { class: 'card bg-base-100 shadow-md', 'data-test': `catalog-result-${r.source}-${r.id}` },
+        [
+          h('div', { class: 'card-body p-4' }, [
+            h('div', { class: 'flex items-start justify-between gap-2' }, [
+              h('div', { class: 'min-w-0' }, [
+                // D19: text-only rendering of arbitrary catalog-source data —
+                // no v-html, no markdown. Vue's {{ }} / textContent
+                // interpolation already escapes this.
+                h('h3', { class: 'font-semibold truncate', 'data-test': 'catalog-result-title' }, r.title),
+                h('p', { class: 'text-xs text-base-content/60 font-mono truncate' }, r.id),
+              ]),
+              h('div', { class: 'flex gap-1 shrink-0' }, [
+                r.official ? h('span', { class: 'badge badge-sm badge-primary' }, 'Official') : null,
+                r.verified && !r.official ? h('span', { class: 'badge badge-sm badge-success' }, 'Verified') : null,
+                h('span', { class: 'badge badge-sm badge-ghost' }, r.transport),
+              ]),
+            ]),
+            r.description ? h('p', { class: 'text-sm text-base-content/70 mt-1 line-clamp-2' }, r.description) : null,
+            h('div', { class: 'card-actions justify-end mt-2' }, [
+              h(
+                'button',
+                {
+                  type: 'button',
+                  class: `btn btn-sm ${added ? 'btn-success' : 'btn-primary'}`,
+                  disabled: cardProps.busy,
+                  'data-test': `catalog-add-${r.source}-${r.id}`,
+                  onClick: () => (added && addedName ? router.push(serverDetailPath(addedName)) : cardEmit('add')),
+                },
+                added ? 'Added ✓ · Open' : cardProps.busy ? 'Adding…' : 'Add to MCPProxy'
+              ),
+            ]),
+          ]),
+        ]
+      )
+    }
+  },
+})
+</script>
diff --git a/frontend/src/components/CatalogSourcesSettings.vue b/frontend/src/components/CatalogSourcesSettings.vue
new file mode 100644
index 000000000..aa3b08c15
--- /dev/null
+++ b/frontend/src/components/CatalogSourcesSettings.vue
@@ -0,0 +1,390 @@
+<template>
+  <div data-test="catalog-sources-settings">
+    <div class="flex justify-between items-center mb-3">
+      <div>
+        <h2 class="card-title text-lg">Catalog sources</h2>
+        <p class="text-sm text-base-content/70">
+          Sources the Catalog tab on <router-link to="/add-server" class="link">Add Server</router-link> searches.
+          Custom sources you add can be edited or removed.
+        </p>
+      </div>
+      <button type="button" class="btn btn-outline btn-sm" data-test="registry-add-source-button" @click="openAddRegistry">
+        <svg class="w-4 h-4 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4" />
+        </svg>
+        Add Registry
+      </button>
+    </div>
+
+    <div v-if="loadingRegistries" class="flex items-center gap-2 py-4 text-base-content/70" data-test="registries-loading">
+      <span class="loading loading-spinner loading-sm"></span>
+      <span>Loading registries…</span>
+    </div>
+
+    <div v-else-if="registries.length === 0" class="text-sm text-base-content/60 py-4" data-test="registries-empty">
+      No registries configured.
+    </div>
+
+    <div v-else class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-3">
+      <div
+        v-for="registry in registries"
+        :key="registry.id"
+        class="border rounded-lg p-3 flex flex-col gap-2 border-base-300"
+        :data-test="`registry-card-${registry.id}`"
+      >
+        <div class="flex items-start justify-between gap-2">
+          <div class="font-semibold min-w-0 [overflow-wrap:anywhere]">{{ registry.name }}</div>
+          <div v-if="isCustomRegistry(registry)" class="dropdown dropdown-end shrink-0">
+            <div
+              tabindex="0"
+              role="button"
+              class="btn btn-ghost btn-xs btn-square"
+              :data-test="`registry-kebab-${registry.id}`"
+              :aria-label="`Manage ${registry.name}`"
+            >
+              <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 24 24">
+                <path d="M12 8a2 2 0 100-4 2 2 0 000 4zm0 2a2 2 0 100 4 2 2 0 000-4zm0 6a2 2 0 100 4 2 2 0 000-4z" />
+              </svg>
+            </div>
+            <ul tabindex="0" class="dropdown-content menu bg-base-100 rounded-box z-10 w-32 p-1 shadow-lg border border-base-300">
+              <li>
+                <button type="button" :data-test="`registry-edit-${registry.id}`" @click="openEditRegistry(registry)">Edit</button>
+              </li>
+              <li>
+                <button type="button" class="text-error" :data-test="`registry-delete-${registry.id}`" @click="openDeleteRegistry(registry)">Delete</button>
+              </li>
+            </ul>
+          </div>
+        </div>
+
+        <div class="flex flex-wrap gap-1 items-center">
+          <span
+            class="badge badge-sm"
+            :class="isCustomRegistry(registry) ? 'badge-ghost' : 'badge-outline'"
+            :data-test="`registry-provenance-${registry.id}`"
+          >{{ isCustomRegistry(registry) ? 'Custom' : 'Official' }}</span>
+          <span v-if="!isCustomRegistry(registry)" class="badge badge-sm badge-ghost" :data-test="`registry-builtin-${registry.id}`">
+            Built-in
+          </span>
+        </div>
+
+        <div v-if="registry.url" class="text-xs text-base-content/60 truncate" :title="registry.url">{{ registry.url }}</div>
+      </div>
+    </div>
+
+    <!-- Add / edit registry-source dialog (MCP-866 add, MCP-1073 edit) -->
+    <dialog ref="addRegistryDialogEl" class="modal" data-test="registry-add-source-dialog">
+      <div class="modal-box">
+        <h3 class="font-bold text-lg">{{ isEditMode ? 'Edit registry' : 'Add a registry' }}</h3>
+        <p class="text-sm text-base-content/70 mt-1">
+          <template v-if="isEditMode">
+            Update this custom <code>modelcontextprotocol/registry</code> source. Its id is fixed.
+          </template>
+          <template v-else>
+            Add a custom <code>modelcontextprotocol/registry</code> v0.1 source by its HTTPS URL —
+            that is the only registry protocol MCPProxy speaks, so the URL is checked when you add it
+            and rejected here if it turns out not to be one. It is shown as a
+            <span class="badge badge-ghost badge-xs align-middle">Custom</span> source.
+          </template>
+        </p>
+
+        <form @submit.prevent="submitRegistryDialog" class="mt-4 space-y-3" data-test="registry-add-form">
+          <div v-if="isEditMode" class="form-control">
+            <label class="label"><span class="label-text font-semibold">Registry ID</span></label>
+            <input :value="editRegistryId" type="text" data-test="registry-edit-id" class="input input-bordered w-full opacity-70" readonly />
+          </div>
+
+          <div class="form-control">
+            <label class="label"><span class="label-text font-semibold">Registry URL</span></label>
+            <input
+              v-model="addRegistryUrl"
+              type="url"
+              placeholder="https://registry.example.com/"
+              data-test="registry-add-url-input"
+              class="input input-bordered w-full"
+              autocomplete="off"
+              required
+            />
+          </div>
+
+          <div v-if="!isEditMode" class="form-control">
+            <label class="label"><span class="label-text font-semibold">Protocol</span></label>
+            <select v-model="addRegistryProtocol" class="select select-bordered w-full" data-test="registry-add-protocol-select">
+              <option value="modelcontextprotocol/registry">modelcontextprotocol/registry (default)</option>
+            </select>
+          </div>
+
+          <div class="form-control">
+            <label class="label"><span class="label-text font-semibold">Name <span class="font-normal opacity-60">(optional)</span></span></label>
+            <input
+              v-model="addRegistryName"
+              type="text"
+              placeholder="Derived from the URL host when empty"
+              data-test="registry-add-name-input"
+              class="input input-bordered w-full"
+              autocomplete="off"
+            />
+          </div>
+
+          <div v-if="addRegistryError" class="alert alert-error text-sm" data-test="registry-add-error">
+            <span>{{ addRegistryError }}</span>
+          </div>
+
+          <div class="modal-action">
+            <button type="button" class="btn btn-ghost" data-test="registry-add-cancel" :disabled="addingRegistry" @click="closeAddRegistry">
+              Cancel
+            </button>
+            <button type="submit" class="btn btn-primary" data-test="registry-add-submit" :disabled="!addRegistryUrl.trim() || addingRegistry">
+              <span v-if="addingRegistry" class="loading loading-spinner loading-xs"></span>
+              <span v-else>{{ isEditMode ? 'Save changes' : 'Add Registry' }}</span>
+            </button>
+          </div>
+        </form>
+      </div>
+      <form method="dialog" class="modal-backdrop">
+        <button @click="closeAddRegistry">close</button>
+      </form>
+    </dialog>
+
+    <!-- Delete custom registry confirmation (MCP-1073, destructive) -->
+    <dialog ref="deleteRegistryDialogEl" class="modal" data-test="registry-delete-dialog">
+      <div class="modal-box">
+        <h3 class="font-bold text-lg">Remove "{{ deleteRegistryTarget?.name }}"?</h3>
+        <p class="text-sm py-2 text-base-content/80">Servers you already added stay; only the source is removed.</p>
+
+        <div v-if="deleteRegistryError" class="alert alert-error text-sm" data-test="registry-delete-error">
+          <span>{{ deleteRegistryError }}</span>
+        </div>
+
+        <div class="modal-action">
+          <button type="button" class="btn btn-ghost" data-test="registry-delete-cancel" :disabled="deletingRegistry" @click="closeDeleteRegistry">
+            Cancel
+          </button>
+          <button type="button" class="btn btn-error" data-test="registry-delete-confirm" :disabled="deletingRegistry" @click="confirmDeleteRegistry">
+            <span v-if="deletingRegistry" class="loading loading-spinner loading-xs"></span>
+            <span v-else>Remove</span>
+          </button>
+        </div>
+      </div>
+      <form method="dialog" class="modal-backdrop">
+        <button @click="closeDeleteRegistry">close</button>
+      </form>
+    </dialog>
+
+    <div v-if="showSuccessToast" class="toast toast-end" data-test="registry-add-success">
+      <div class="alert alert-success">
+        <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+        </svg>
+        <span>{{ successMessage }}</span>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+// Catalog-source management (Spec 109 FR-062: moved out of the retired
+// Repositories.vue into Settings). Server BROWSING moved to
+// components/CatalogSearch.vue (the Add Server page's Catalog tab); this
+// component only manages the SOURCES that browse searches.
+import { ref, computed, onMounted } from 'vue'
+import api from '@/services/api'
+import type { Registry } from '@/types'
+import { REGISTRY_PROVENANCE_CUSTOM } from '@/types'
+import { useDialogOpen } from '@/composables/useDialogOpen'
+
+const registries = ref<Registry[]>([])
+const loadingRegistries = ref(false)
+const error = ref<string | null>(null)
+const showSuccessToast = ref(false)
+const successMessage = ref('')
+
+const showAddRegistry = ref(false)
+const editRegistryId = ref<string | null>(null)
+const addRegistryUrl = ref('')
+const addRegistryProtocol = ref('modelcontextprotocol/registry')
+const addRegistryName = ref('')
+const addRegistryError = ref<string | null>(null)
+const addingRegistry = ref(false)
+const isEditMode = computed(() => editRegistryId.value !== null)
+const { dialogEl: addRegistryDialogEl } = useDialogOpen(() => showAddRegistry.value, () => handleAddRegistryNativeClose())
+
+const showDeleteRegistry = ref(false)
+const deleteRegistryTarget = ref<Registry | null>(null)
+const deleteRegistryError = ref<string | null>(null)
+const deletingRegistry = ref(false)
+const { dialogEl: deleteRegistryDialogEl } = useDialogOpen(() => showDeleteRegistry.value, () => handleDeleteRegistryNativeClose())
+
+function isCustomRegistry(registry?: Registry | null): boolean {
+  if (!registry) return false
+  return registry.provenance === REGISTRY_PROVENANCE_CUSTOM || registry.trusted === false
+}
+
+async function loadRegistries() {
+  loadingRegistries.value = true
+  error.value = null
+  try {
+    const response = await api.listRegistries()
+    if (response.success && response.data) {
+      registries.value = response.data.registries
+    } else {
+      error.value = response.error || 'Failed to load registries'
+    }
+  } catch (err) {
+    error.value = 'Failed to load registries: ' + (err as Error).message
+  } finally {
+    loadingRegistries.value = false
+  }
+}
+
+function openAddRegistry() {
+  editRegistryId.value = null
+  addRegistryUrl.value = ''
+  addRegistryProtocol.value = 'modelcontextprotocol/registry'
+  addRegistryName.value = ''
+  addRegistryError.value = null
+  showAddRegistry.value = true
+}
+
+function openEditRegistry(registry: Registry) {
+  editRegistryId.value = registry.id
+  addRegistryUrl.value = registry.url || registry.servers_url || ''
+  addRegistryName.value = registry.name || ''
+  addRegistryError.value = null
+  showAddRegistry.value = true
+}
+
+function closeAddRegistry() {
+  if (addingRegistry.value) return
+  showAddRegistry.value = false
+  editRegistryId.value = null
+}
+
+function handleAddRegistryNativeClose() {
+  showAddRegistry.value = false
+  editRegistryId.value = null
+}
+
+function registryErrorMessage(code: string | undefined, fallback: string | undefined, verb: string): string {
+  switch (code) {
+    case 'invalid_registry_url':
+      return fallback || 'That URL is not a valid HTTPS registry endpoint.'
+    case 'registries_locked':
+      return `${verb} registries is locked by an administrator on this instance.`
+    case 'registry_shadows_builtin':
+      return 'That id/host collides with a built-in registry.'
+    case 'registry_not_found':
+      return 'That registry no longer exists. It may have already been removed.'
+    case 'duplicate_registry':
+      return 'A registry with that id is already configured.'
+    default:
+      return fallback || `Failed to ${verb.toLowerCase()} registry.`
+  }
+}
+
+function submitRegistryDialog() {
+  if (!addRegistryUrl.value.trim() || addingRegistry.value) return
+  if (isEditMode.value) void doEditRegistry()
+  else void doAddRegistry()
+}
+
+async function doAddRegistry() {
+  addingRegistry.value = true
+  addRegistryError.value = null
+  try {
+    const result = await api.addRegistrySource(addRegistryUrl.value.trim(), {
+      protocol: addRegistryProtocol.value || undefined,
+      name: addRegistryName.value.trim() || undefined,
+    })
+    if (result.success) {
+      const added = result.registry
+      showAddRegistry.value = false
+      await loadRegistries()
+      showToast(`Added registry "${added?.name || added?.id || addRegistryUrl.value}".`)
+      return
+    }
+    addRegistryError.value = registryErrorMessage(result.code, result.error, 'Adding')
+  } catch (err) {
+    addRegistryError.value = 'Failed to add registry: ' + (err as Error).message
+  } finally {
+    addingRegistry.value = false
+  }
+}
+
+async function doEditRegistry() {
+  const id = editRegistryId.value
+  if (!id) return
+  addingRegistry.value = true
+  addRegistryError.value = null
+  try {
+    const result = await api.editRegistrySource(id, {
+      name: addRegistryName.value.trim() || undefined,
+      url: addRegistryUrl.value.trim() || undefined,
+    })
+    if (result.success) {
+      showAddRegistry.value = false
+      editRegistryId.value = null
+      await loadRegistries()
+      const updated = result.registry
+      showToast(`Updated registry "${updated?.name || updated?.id || id}".`)
+      return
+    }
+    addRegistryError.value = registryErrorMessage(result.code, result.error, 'Editing')
+  } catch (err) {
+    addRegistryError.value = 'Failed to edit registry: ' + (err as Error).message
+  } finally {
+    addingRegistry.value = false
+  }
+}
+
+function openDeleteRegistry(registry: Registry) {
+  deleteRegistryTarget.value = registry
+  deleteRegistryError.value = null
+  showDeleteRegistry.value = true
+}
+
+function closeDeleteRegistry() {
+  if (deletingRegistry.value) return
+  showDeleteRegistry.value = false
+  deleteRegistryTarget.value = null
+}
+
+function handleDeleteRegistryNativeClose() {
+  showDeleteRegistry.value = false
+  deleteRegistryTarget.value = null
+}
+
+async function confirmDeleteRegistry() {
+  const target = deleteRegistryTarget.value
+  if (!target) return
+  deletingRegistry.value = true
+  deleteRegistryError.value = null
+  try {
+    const result = await api.removeRegistrySource(target.id)
+    if (result.success) {
+      showDeleteRegistry.value = false
+      deleteRegistryTarget.value = null
+      await loadRegistries()
+      showToast(`Removed registry "${target.name || target.id}".`)
+      return
+    }
+    deleteRegistryError.value = registryErrorMessage(result.code, result.error, 'Removing')
+  } catch (err) {
+    deleteRegistryError.value = 'Failed to remove registry: ' + (err as Error).message
+  } finally {
+    deletingRegistry.value = false
+  }
+}
+
+function showToast(message: string) {
+  successMessage.value = message
+  showSuccessToast.value = true
+  setTimeout(() => {
+    showSuccessToast.value = false
+  }, 3000)
+}
+
+onMounted(() => {
+  void loadRegistries()
+})
+</script>
diff --git a/frontend/src/components/ImportServersPanel.vue b/frontend/src/components/ImportServersPanel.vue
new file mode 100644
index 000000000..912b31ee2
--- /dev/null
+++ b/frontend/src/components/ImportServersPanel.vue
@@ -0,0 +1,140 @@
+<template>
+  <div data-test="import-servers-panel">
+    <div v-if="canonicalPaths.length > 0" class="mb-4">
+      <label class="label"><span class="label-text font-semibold">Quick import</span></label>
+      <div class="flex flex-wrap gap-2">
+        <button
+          v-for="p in canonicalPaths"
+          :key="p.path"
+          type="button"
+          class="btn btn-sm"
+          :class="p.exists ? 'btn-outline' : 'btn-disabled'"
+          :disabled="!p.exists"
+          :data-test="`import-canonical-${p.format}`"
+          @click="importFromPath(p.path)"
+        >
+          {{ p.name }}
+        </button>
+      </div>
+    </div>
+
+    <label class="label"><span class="label-text font-semibold">Or paste a config file's content</span></label>
+    <textarea
+      v-model="content"
+      rows="6"
+      class="textarea textarea-bordered w-full font-mono text-sm"
+      placeholder='{ "mcpServers": { ... } }'
+      data-test="import-content-textarea"
+    />
+    <div class="mt-2">
+      <button type="button" class="btn btn-sm" :disabled="loading || !content.trim()" data-test="import-preview-button" @click="() => runPreview()">
+        Preview
+      </button>
+    </div>
+
+    <div v-if="loading" class="py-3 text-sm text-base-content/70" data-test="import-loading">Detecting servers…</div>
+    <div v-else-if="error" class="alert alert-error text-sm mt-3" data-test="import-error">{{ error }}</div>
+
+    <div v-else-if="preview" class="mt-4" data-test="import-preview">
+      <p class="text-sm text-base-content/70 mb-2">{{ preview.format_name }} — {{ preview.imported.length }} server(s) detected</p>
+      <div v-for="(s, i) in preview.imported" :key="s.name" class="flex items-center gap-2 py-1">
+        <input v-model="selected[s.name]" type="checkbox" class="checkbox checkbox-sm" :data-test="`import-select-${i}`" />
+        <span class="font-mono text-sm">{{ s.name }}</span>
+        <span class="text-xs text-base-content/60">{{ s.protocol }}</span>
+      </div>
+      <div v-if="addError" class="alert alert-error text-sm mt-3" data-test="import-add-error">{{ addError }}</div>
+      <button type="button" class="btn btn-primary mt-3" :disabled="importing || selectedCount === 0" data-test="import-confirm-button" @click="handleImport">
+        {{ importing ? 'Importing…' : `Import ${selectedCount} server(s)` }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive, computed, onMounted } from 'vue'
+import api, { type CanonicalConfigPath } from '@/services/api'
+import type { ImportResponse } from '@/types'
+
+const emit = defineEmits<{ imported: [count: number] }>()
+
+const content = ref('')
+const loading = ref(false)
+const error = ref<string | null>(null)
+const preview = ref<ImportResponse | null>(null)
+const selected = reactive<Record<string, boolean>>({})
+const addError = ref<string | null>(null)
+const importing = ref(false)
+const canonicalPaths = ref<CanonicalConfigPath[]>([])
+let activePath = ''
+
+const selectedCount = computed(() => Object.values(selected).filter(Boolean).length)
+
+onMounted(async () => {
+  const resp = await api.getCanonicalConfigPaths()
+  if (resp.success && resp.data) canonicalPaths.value = resp.data.paths
+})
+
+async function runPreview() {
+  if (!content.value.trim()) return
+  loading.value = true
+  error.value = null
+  activePath = ''
+  try {
+    const resp = await api.importServersFromJSON({ content: content.value, preview: true })
+    if (!resp.success || !resp.data) {
+      error.value = resp.error || 'Preview failed'
+      preview.value = null
+      return
+    }
+    preview.value = resp.data
+    for (const key of Object.keys(selected)) delete selected[key]
+    for (const s of resp.data.imported) selected[s.name] = true
+  } catch (e) {
+    error.value = e instanceof Error ? e.message : 'Preview failed'
+  } finally {
+    loading.value = false
+  }
+}
+
+async function importFromPath(path: string) {
+  loading.value = true
+  error.value = null
+  activePath = path
+  try {
+    const resp = await api.importServersFromPath({ path, preview: true })
+    if (!resp.success || !resp.data) {
+      error.value = resp.error || 'Preview failed'
+      preview.value = null
+      return
+    }
+    preview.value = resp.data
+    for (const key of Object.keys(selected)) delete selected[key]
+    for (const s of resp.data.imported) selected[s.name] = true
+  } catch (e) {
+    error.value = e instanceof Error ? e.message : 'Preview failed'
+  } finally {
+    loading.value = false
+  }
+}
+
+async function handleImport() {
+  if (!preview.value) return
+  importing.value = true
+  addError.value = null
+  try {
+    const names = Object.entries(selected).filter(([, v]) => v).map(([k]) => k)
+    const resp = activePath
+      ? await api.importServersFromPath({ path: activePath, preview: false, server_names: names })
+      : await api.importServersFromJSON({ content: content.value, preview: false, server_names: names })
+    if (!resp.success) {
+      addError.value = resp.error || 'Import failed'
+      return
+    }
+    emit('imported', names.length)
+  } catch (e) {
+    addError.value = e instanceof Error ? e.message : 'Import failed'
+  } finally {
+    importing.value = false
+  }
+}
+</script>
diff --git a/frontend/src/components/ManualServerForm.vue b/frontend/src/components/ManualServerForm.vue
new file mode 100644
index 000000000..69c67725f
--- /dev/null
+++ b/frontend/src/components/ManualServerForm.vue
@@ -0,0 +1,163 @@
+<template>
+  <form data-test="manual-server-form" @submit.prevent="handleSubmit">
+    <div class="form-control mb-4">
+      <label class="label"><span class="label-text font-semibold">Name</span></label>
+      <input v-model="name" type="text" class="input input-bordered" required data-test="manual-name-input" />
+    </div>
+
+    <div class="form-control mb-4">
+      <label class="label"><span class="label-text font-semibold">Server Type</span></label>
+      <div class="flex gap-4">
+        <label class="flex items-center gap-2 cursor-pointer">
+          <input v-model="protocol" type="radio" value="stdio" class="radio radio-primary" data-test="manual-type-stdio" />
+          <span>stdio (Local Command)</span>
+        </label>
+        <label class="flex items-center gap-2 cursor-pointer">
+          <input v-model="protocol" type="radio" value="http" class="radio radio-primary" data-test="manual-type-http" />
+          <span>HTTP/HTTPS (Remote)</span>
+        </label>
+      </div>
+    </div>
+
+    <template v-if="protocol === 'http'">
+      <div class="form-control mb-4">
+        <label class="label"><span class="label-text font-semibold">URL</span></label>
+        <input v-model="url" type="url" class="input input-bordered" placeholder="https://api.example.com/mcp" required data-test="manual-url-input" />
+      </div>
+      <div class="mb-4 space-y-2">
+        <label class="label"><span class="label-text font-semibold">Headers</span></label>
+        <div v-for="(h, i) in headerRows" :key="i" class="flex gap-2 items-start">
+          <input v-model="h.name" type="text" class="input input-bordered input-sm flex-1" placeholder="Header name" :data-test="`manual-header-name-${i}`" />
+          <SecretToggle
+            class="flex-[2]"
+            :name="h.name || `header-${i}`"
+            kind="header"
+            :model-value="h.value"
+            :mode="h.mode"
+            :keyring-available="keyringAvailable"
+            :keyring-reason="keyringReason"
+            @update:model-value="(v) => (h.value = v)"
+            @update:mode="(m) => (h.mode = m)"
+          />
+          <button type="button" class="btn btn-ghost btn-sm" data-test="manual-header-remove" @click="headerRows.splice(i, 1)">✕</button>
+        </div>
+        <button type="button" class="btn btn-ghost btn-sm" data-test="manual-header-add" @click="headerRows.push({ name: '', value: '', mode: 'value' })">
+          + Add header
+        </button>
+      </div>
+    </template>
+
+    <template v-else>
+      <div class="form-control mb-4">
+        <label class="label"><span class="label-text font-semibold">Command</span></label>
+        <input v-model="command" type="text" class="input input-bordered" placeholder="npx" required data-test="manual-command-input" />
+      </div>
+      <div class="form-control mb-4">
+        <label class="label"><span class="label-text font-semibold">Arguments (space-separated)</span></label>
+        <input v-model="argsText" type="text" class="input input-bordered" placeholder="-y @modelcontextprotocol/server-filesystem /tmp" data-test="manual-args-input" />
+      </div>
+      <div class="mb-4 space-y-2">
+        <label class="label"><span class="label-text font-semibold">Environment variables</span></label>
+        <div v-for="(e, i) in envRows" :key="i" class="flex gap-2 items-start">
+          <input v-model="e.name" type="text" class="input input-bordered input-sm flex-1" placeholder="VAR_NAME" :data-test="`manual-env-name-${i}`" />
+          <SecretToggle
+            class="flex-[2]"
+            :name="e.name || `env-${i}`"
+            kind="env"
+            :model-value="e.value"
+            :mode="e.mode"
+            :keyring-available="keyringAvailable"
+            :keyring-reason="keyringReason"
+            @update:model-value="(v) => (e.value = v)"
+            @update:mode="(m) => (e.mode = m)"
+          />
+          <button type="button" class="btn btn-ghost btn-sm" data-test="manual-env-remove" @click="envRows.splice(i, 1)">✕</button>
+        </div>
+        <button type="button" class="btn btn-ghost btn-sm" data-test="manual-env-add" @click="envRows.push({ name: '', value: '', mode: 'value' })">
+          + Add variable
+        </button>
+      </div>
+    </template>
+
+    <div v-if="error" class="alert alert-error text-sm mb-4" data-test="manual-error">{{ error }}</div>
+
+    <button type="submit" class="btn btn-primary" :disabled="submitting" data-test="manual-submit">
+      {{ submitting ? 'Adding…' : 'Add to MCPProxy' }}
+    </button>
+  </form>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive, onMounted } from 'vue'
+import { useRouter } from 'vue-router'
+import api from '@/services/api'
+import SecretToggle from '@/components/SecretToggle.vue'
+import { resolveSecretFields } from '@/composables/useSecretFields'
+import { useServersStore } from '@/stores/servers'
+import { serverDetailPath } from '@/utils/serverRoute'
+
+const emit = defineEmits<{ added: [name: string] }>()
+
+const router = useRouter()
+const serversStore = useServersStore()
+
+const name = ref('')
+const protocol = ref<'stdio' | 'http'>('stdio')
+const url = ref('')
+const command = ref('')
+const argsText = ref('')
+const headerRows = reactive<{ name: string; value: string; mode: 'value' | 'secret' }[]>([])
+const envRows = reactive<{ name: string; value: string; mode: 'value' | 'secret' }[]>([])
+const error = ref<string | null>(null)
+const submitting = ref(false)
+const keyringAvailable = ref(true)
+const keyringReason = ref('')
+
+onMounted(async () => {
+  const resp = await api.getConfigSecrets()
+  if (resp.success && resp.data) {
+    keyringAvailable.value = resp.data.keyring_available
+    keyringReason.value = resp.data.keyring_reason || ''
+  }
+})
+
+function parseArgs(): string[] {
+  return argsText.value.trim() === '' ? [] : argsText.value.trim().split(/\s+/)
+}
+
+async function handleSubmit() {
+  error.value = null
+  submitting.value = true
+  try {
+    const fields = [
+      ...envRows.filter((r) => r.name.trim()).map((r) => ({ kind: 'env' as const, name: r.name.trim(), value: r.value, mode: r.mode })),
+      ...headerRows.filter((r) => r.name.trim()).map((r) => ({ kind: 'header' as const, name: r.name.trim(), value: r.value, mode: r.mode })),
+    ]
+    const resolved = await resolveSecretFields(name.value, fields)
+
+    const serverData: Record<string, unknown> = {
+      operation: 'add',
+      name: name.value,
+      protocol: protocol.value,
+      enabled: true,
+    }
+    if (protocol.value === 'http') {
+      serverData.url = url.value
+      if (Object.keys(resolved.headers).length > 0) serverData.headers_json = JSON.stringify(resolved.headers)
+    } else {
+      serverData.command = command.value
+      const args = parseArgs()
+      if (args.length > 0) serverData.args_json = JSON.stringify(args)
+      if (Object.keys(resolved.env).length > 0) serverData.env_json = JSON.stringify(resolved.env)
+    }
+
+    await serversStore.addServer(serverData)
+    emit('added', name.value)
+    void router.push(serverDetailPath(name.value))
+  } catch (e) {
+    error.value = e instanceof Error ? e.message : 'Failed to add server'
+  } finally {
+    submitting.value = false
+  }
+}
+</script>
diff --git a/frontend/src/components/PasteServer.vue b/frontend/src/components/PasteServer.vue
new file mode 100644
index 000000000..7af1253af
--- /dev/null
+++ b/frontend/src/components/PasteServer.vue
@@ -0,0 +1,186 @@
+<template>
+  <div data-test="paste-server">
+    <label class="label">
+      <span class="label-text font-semibold">Paste a URL, a command line, or a JSON/TOML config</span>
+    </label>
+    <textarea
+      v-model="content"
+      rows="4"
+      class="textarea textarea-bordered w-full font-mono text-sm"
+      placeholder="https://api.example.com/mcp&#10;or: npx -y @modelcontextprotocol/server-filesystem /tmp&#10;or: { &quot;mcpServers&quot;: { ... } }"
+      data-test="paste-textarea"
+    />
+
+    <div v-if="loading" class="flex items-center gap-2 py-3 text-sm text-base-content/70" data-test="paste-loading">
+      <span class="loading loading-spinner loading-xs" /> Detecting…
+    </div>
+    <div v-else-if="error" class="alert alert-error text-sm mt-3" data-test="paste-error">{{ error }}</div>
+
+    <div v-else-if="preview" class="mt-4 space-y-3" data-test="paste-preview">
+      <div class="flex items-center gap-2 flex-wrap">
+        <span class="badge badge-outline" data-test="paste-format">{{ formatLabel }}</span>
+        <span v-for="tag in preview.tags || []" :key="tag" class="badge badge-ghost" :data-test="`paste-tag-${tag}`">
+          {{ tag }}
+        </span>
+      </div>
+      <p class="text-sm font-mono text-base-content/80 break-all" data-test="paste-summary">{{ preview.summary }}</p>
+
+      <div v-if="(preview.env?.length || 0) + (preview.headers?.length || 0) > 0" class="space-y-2">
+        <SecretToggle
+          v-for="f in envFields"
+          :key="`env-${f.name}`"
+          :name="f.name"
+          kind="env"
+          :model-value="values[`env:${f.name}`] || ''"
+          :mode="modes[`env:${f.name}`] || (f.secret_like ? 'secret' : 'value')"
+          :keyring-available="keyringAvailable"
+          :keyring-reason="keyringReason"
+          @update:model-value="(v) => (values[`env:${f.name}`] = v)"
+          @update:mode="(m) => (modes[`env:${f.name}`] = m)"
+        />
+        <SecretToggle
+          v-for="f in headerFields"
+          :key="`header-${f.name}`"
+          :name="f.name"
+          kind="header"
+          :model-value="values[`header:${f.name}`] || ''"
+          :mode="modes[`header:${f.name}`] || (f.secret_like ? 'secret' : 'value')"
+          :keyring-available="keyringAvailable"
+          :keyring-reason="keyringReason"
+          @update:model-value="(v) => (values[`header:${f.name}`] = v)"
+          @update:mode="(m) => (modes[`header:${f.name}`] = m)"
+        />
+      </div>
+
+      <div v-if="addError" class="alert alert-error text-sm" data-test="paste-add-error">{{ addError }}</div>
+
+      <button type="button" class="btn btn-primary" :disabled="adding" data-test="paste-add-button" @click="handleAdd">
+        {{ adding ? 'Adding…' : 'Add to MCPProxy' }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive, computed, watch, onMounted } from 'vue'
+import { useRouter } from 'vue-router'
+import api from '@/services/api'
+import type { ImportedServer } from '@/types'
+import SecretToggle from '@/components/SecretToggle.vue'
+import { resolveSecretFields } from '@/composables/useSecretFields'
+import { useServersStore } from '@/stores/servers'
+import { serverDetailPath } from '@/utils/serverRoute'
+
+const emit = defineEmits<{ added: [name: string] }>()
+
+const content = ref('')
+const loading = ref(false)
+const error = ref<string | null>(null)
+const preview = ref<ImportedServer | null>(null)
+const format = ref('')
+const values = reactive<Record<string, string>>({})
+const modes = reactive<Record<string, 'value' | 'secret'>>({})
+const addError = ref<string | null>(null)
+const adding = ref(false)
+const keyringAvailable = ref(true)
+const keyringReason = ref('')
+
+const router = useRouter()
+const serversStore = useServersStore()
+
+const formatLabel = computed(() => {
+  switch (format.value) {
+    case 'url':
+      return 'Remote URL'
+    case 'command':
+      return 'Command line'
+    default:
+      return format.value || 'Config'
+  }
+})
+
+const envFields = computed(() => preview.value?.env || [])
+const headerFields = computed(() => preview.value?.headers || [])
+
+let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+async function runPreview() {
+  const raw = content.value.trim()
+  if (!raw) {
+    preview.value = null
+    error.value = null
+    return
+  }
+  loading.value = true
+  error.value = null
+  try {
+    const resp = await api.importServersFromJSON({ content: raw, preview: true })
+    if (!resp.success || !resp.data || resp.data.imported.length === 0) {
+      error.value = resp.error || 'Could not detect a server from this input'
+      preview.value = null
+      return
+    }
+    format.value = resp.data.format
+    preview.value = resp.data.imported[0]
+    for (const key of Object.keys(values)) delete values[key]
+    for (const key of Object.keys(modes)) delete modes[key]
+    for (const f of preview.value.env || []) modes[`env:${f.name}`] = f.secret_like ? 'secret' : 'value'
+    for (const f of preview.value.headers || []) modes[`header:${f.name}`] = f.secret_like ? 'secret' : 'value'
+  } catch (e) {
+    error.value = e instanceof Error ? e.message : 'Preview failed'
+    preview.value = null
+  } finally {
+    loading.value = false
+  }
+}
+
+watch(content, () => {
+  if (debounceTimer) clearTimeout(debounceTimer)
+  debounceTimer = setTimeout(runPreview, 400)
+})
+
+onMounted(async () => {
+  const secretsResp = await api.getConfigSecrets()
+  if (secretsResp.success && secretsResp.data) {
+    keyringAvailable.value = secretsResp.data.keyring_available
+    keyringReason.value = secretsResp.data.keyring_reason || ''
+  }
+})
+
+async function handleAdd() {
+  if (!preview.value) return
+  adding.value = true
+  addError.value = null
+  try {
+    const p = preview.value
+    const fields = [
+      ...(p.env || []).map((f) => ({ kind: 'env' as const, name: f.name, value: values[`env:${f.name}`] || '', mode: modes[`env:${f.name}`] || 'value' })),
+      ...(p.headers || []).map((f) => ({ kind: 'header' as const, name: f.name, value: values[`header:${f.name}`] || '', mode: modes[`header:${f.name}`] || 'value' })),
+    ]
+    const resolved = await resolveSecretFields(p.name, fields)
+
+    const serverData: Record<string, unknown> = {
+      operation: 'add',
+      name: p.name,
+      protocol: p.protocol,
+      enabled: true,
+    }
+    if (p.url) {
+      serverData.url = p.url
+      if (Object.keys(resolved.headers).length > 0) serverData.headers_json = JSON.stringify(resolved.headers)
+    } else if (p.command) {
+      serverData.command = p.command
+      if (p.args && p.args.length > 0) serverData.args_json = JSON.stringify(p.args)
+      if (Object.keys(resolved.env).length > 0) serverData.env_json = JSON.stringify(resolved.env)
+    }
+
+    await serversStore.addServer(serverData)
+    emit('added', p.name)
+    void router.push(serverDetailPath(p.name))
+  } catch (e) {
+    addError.value = e instanceof Error ? e.message : 'Failed to add server'
+  } finally {
+    adding.value = false
+  }
+}
+</script>
diff --git a/frontend/src/components/SecretToggle.vue b/frontend/src/components/SecretToggle.vue
new file mode 100644
index 000000000..40a704de3
--- /dev/null
+++ b/frontend/src/components/SecretToggle.vue
@@ -0,0 +1,82 @@
+<template>
+  <div class="flex items-start gap-2" :data-test="`secret-toggle-${kind}-${name}`">
+    <div class="flex-1 min-w-0">
+      <label class="label py-0">
+        <span class="label-text text-xs font-mono">{{ name }}</span>
+      </label>
+      <input
+        :type="mode === 'secret' ? 'password' : 'text'"
+        class="input input-bordered input-sm w-full font-mono"
+        :value="modelValue"
+        :placeholder="mode === 'secret' ? 'Value stored in the OS keyring on Add' : ''"
+        data-test="secret-toggle-value-input"
+        @input="$emit('update:modelValue', ($event.target as HTMLInputElement).value)"
+      />
+    </div>
+    <div class="join mt-6 shrink-0" role="group" :aria-label="`${name} storage`">
+      <button
+        type="button"
+        class="btn btn-xs join-item"
+        :class="mode === 'value' ? 'btn-active' : ''"
+        data-test="secret-toggle-mode-value"
+        @click="setMode('value')"
+      >
+        Value
+      </button>
+      <button
+        type="button"
+        class="btn btn-xs join-item"
+        :class="mode === 'secret' ? 'btn-active' : ''"
+        :disabled="!keyringAvailable"
+        :title="!keyringAvailable ? keyringReason || 'OS keyring unavailable' : 'Store in the OS keyring'"
+        data-test="secret-toggle-mode-secret"
+        @click="setMode('secret')"
+      >
+        Secret
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { watch } from 'vue'
+import { looksSecret } from '@/utils/secretLike'
+
+// One Value/Secret toggle for a single env var or header field (Spec 109
+// FR-065). The parent owns the actual value; this component only owns the
+// mode (value vs secret) and defaults it to Secret for a secret-like name —
+// unless the keyring is unavailable, in which case it can never enter secret
+// mode (FR-065: "the toggle is disabled with the reason").
+interface Props {
+  name: string
+  kind: 'env' | 'header'
+  modelValue: string
+  mode: 'value' | 'secret'
+  keyringAvailable: boolean
+  keyringReason?: string
+}
+const props = defineProps<Props>()
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+  'update:mode': [mode: 'value' | 'secret']
+}>()
+
+function setMode(mode: 'value' | 'secret') {
+  if (mode === 'secret' && !props.keyringAvailable) return
+  emit('update:mode', mode)
+}
+
+// Re-default to 'value' if the keyring becomes unavailable while a field was
+// already in 'secret' mode (e.g. a slow keyring-availability probe resolves
+// after the field's initial default was applied).
+watch(
+  () => props.keyringAvailable,
+  (available) => {
+    if (!available && props.mode === 'secret') {
+      emit('update:mode', 'value')
+    }
+  }
+)
+
+defineExpose({ defaultMode: () => (looksSecret(props.name) ? 'secret' : 'value') })
+</script>
diff --git a/frontend/src/components/SidebarNav.vue b/frontend/src/components/SidebarNav.vue
index f8e2af682..4bfcc80d3 100644
--- a/frontend/src/components/SidebarNav.vue
+++ b/frontend/src/components/SidebarNav.vue
@@ -337,14 +337,14 @@
           <ul class="menu menu-sm w-full gap-0.5 p-0">
             <li>
               <router-link
-                to="/repositories"
-                :class="{ 'active': isActiveRoute('/repositories') }"
+                to="/add-server"
+                :class="{ 'active': isActiveRoute('/add-server') || isActiveRoute('/repositories') }"
                 class="rounded-lg text-base-content/70"
-                :title="collapsed ? 'Repositories' : ''"
-                :aria-label="collapsed ? 'Repositories' : undefined"
+                :title="collapsed ? 'Add Server' : ''"
+                :aria-label="collapsed ? 'Add Server' : undefined"
               >
                 <IconRepo class="w-5 h-5 shrink-0" />
-                <span v-show="!collapsed" class="text-[13px]">Repositories</span>
+                <span v-show="!collapsed" class="text-[13px]">Add Server</span>
               </router-link>
             </li>
             <li>
diff --git a/frontend/src/components/TopHeader.vue b/frontend/src/components/TopHeader.vue
index 5e13daf2b..d409973f3 100644
--- a/frontend/src/components/TopHeader.vue
+++ b/frontend/src/components/TopHeader.vue
@@ -59,7 +59,7 @@
              hidden, never issued-and-403'd). -->
         <button
           v-if="authStore.principalKind !== 'tenant'"
-          @click="showAddServerModal = true"
+          @click="router.push('/add-server')"
           class="btn btn-primary"
           :aria-label="addServerLabel"
           data-test="header-add-server"
@@ -174,12 +174,6 @@
       </div>
     </div>
 
-    <!-- Add Server Modal -->
-    <AddServerModal
-      :show="showAddServerModal"
-      @close="showAddServerModal = false"
-      @added="handleServerAdded"
-    />
   </header>
 </template>
 
@@ -190,8 +184,6 @@ import { useSystemStore } from '@/stores/system'
 import { useServersStore } from '@/stores/servers'
 import { useAuthStore } from '@/stores/auth'
 import { useProfilesStore } from '@/stores/profiles'
-import AddServerModal from './AddServerModal.vue'
-import { serverDetailPath } from '@/utils/serverRoute'
 import ProfileSwitcher from './ProfileSwitcher.vue'
 import ModeSwitcher from './ModeSwitcher.vue'
 
@@ -213,7 +205,6 @@ onMounted(() => {
 const addServerLabel = computed(() => authStore.isTeamsEdition ? 'Add Personal Server' : 'Add Server')
 
 const searchQuery = ref('')
-const showAddServerModal = ref(false)
 const showEndpoints = ref(false)
 
 interface McpEndpoint {
@@ -280,15 +271,4 @@ function handleSearch() {
   const q = searchQuery.value.trim()
   router.push(q ? { path: '/tools', query: { q } } : { path: '/tools' })
 }
-
-function handleServerAdded(serverName?: string) {
-  // Refresh servers list after adding
-  serversStore.fetchServers()
-  // UX audit F07: a single add hands off to that server's detail view, where
-  // connect/scan/review/approve is already on screen. The bulk/import path
-  // emits no name and keeps the old refresh-in-place behaviour.
-  if (serverName) {
-    void router.push(serverDetailPath(serverName))
-  }
-}
 </script>
diff --git a/frontend/src/composables/useSecretFields.ts b/frontend/src/composables/useSecretFields.ts
new file mode 100644
index 000000000..e7a27003b
--- /dev/null
+++ b/frontend/src/composables/useSecretFields.ts
@@ -0,0 +1,84 @@
+// Shared secret-field resolution for Paste/Manual/Catalog add surfaces (Spec
+// 109 FR-065): a field toggled to Secret gets written to the OS keyring under
+// its refName and replaced with ${keyring:<ref>}; a field left as Value is
+// passed through unchanged. On failure, only the secrets THIS call itself
+// wrote are rolled back — an existing keyring entry from a previous add is
+// never touched.
+import api from '@/services/api'
+import { refName } from '@/utils/secretRef'
+
+export interface SecretField {
+  kind: 'env' | 'header'
+  name: string
+  value: string
+  mode: 'value' | 'secret'
+}
+
+export interface ResolvedSecretFields {
+  env: Record<string, string>
+  headers: Record<string, string>
+  writtenRefs: string[]
+}
+
+/**
+ * resolveSecretFields writes each 'secret'-mode field to the OS keyring and
+ * returns env/headers maps ready to send to POST /servers (or PATCH), with
+ * ${keyring:<ref>} in place of the raw value for secret fields.
+ *
+ * Throws (and rolls back everything it wrote so far) if any keyring write
+ * fails, so the caller never ends up with a server config that references a
+ * secret that was never actually stored.
+ */
+export async function resolveSecretFields(serverName: string, fields: SecretField[]): Promise<ResolvedSecretFields> {
+  const env: Record<string, string> = {}
+  const headers: Record<string, string> = {}
+  const writtenRefs: string[] = []
+
+  const valueFields = fields.filter((f) => f.mode === 'value')
+  const secretFields = fields.filter((f) => f.mode === 'secret')
+
+  for (const f of valueFields) {
+    if (f.kind === 'env') env[f.name] = f.value
+    else headers[f.name] = f.value
+  }
+
+  if (secretFields.length === 0) {
+    return { env, headers, writtenRefs }
+  }
+
+  // One taken-name check up front (GET /secrets/refs), then tracked locally
+  // as this call writes its own refs, so two fields in the same call that
+  // would otherwise compute the same name get -2, not a silent collision.
+  const refsResp = await api.getSecretRefs()
+  const taken = new Set<string>()
+  if (refsResp.success && refsResp.data) {
+    for (const r of refsResp.data.refs) {
+      if (r.type === 'keyring') taken.add(r.name)
+    }
+  }
+
+  try {
+    for (const f of secretFields) {
+      const ref = refName(serverName, f.kind, f.name, (n) => taken.has(n))
+      const stored = await api.setSecret(ref, f.value)
+      if (!stored.success) {
+        throw new Error(stored.error || `Failed to store secret for ${f.kind} ${f.name}`)
+      }
+      taken.add(ref)
+      writtenRefs.push(ref)
+      const placeholder = `\${keyring:${ref}}`
+      if (f.kind === 'env') env[f.name] = placeholder
+      else headers[f.name] = placeholder
+    }
+  } catch (err) {
+    await rollbackSecrets(writtenRefs)
+    throw err
+  }
+
+  return { env, headers, writtenRefs }
+}
+
+/** rollbackSecrets deletes only the refs THIS add wrote — never a pre-existing entry. */
+export async function rollbackSecrets(refs: string[]): Promise<void> {
+  await Promise.all(refs.map((ref) => api.deleteSecret(ref).catch(() => undefined)))
+}
diff --git a/frontend/src/router/index.ts b/frontend/src/router/index.ts
index d8382732f..f2eb06e0f 100644
--- a/frontend/src/router/index.ts
+++ b/frontend/src/router/index.ts
@@ -65,13 +65,21 @@ const router = createRouter({
       },
     },
     {
-      path: '/repositories',
-      name: 'repositories',
-      component: () => import('@/views/Repositories.vue'),
+      path: '/add-server',
+      name: 'add-server',
+      component: () => import('@/views/AddServer.vue'),
       meta: {
-        title: 'Repositories',
+        title: 'Add Server',
       },
     },
+    // Spec 109 FR-062: adding a server now starts at /add-server (outside the
+    // /servers/:serverName path space — no server name, including "add", can
+    // be shadowed by it). /repositories redirects here on the Catalog tab,
+    // and catalog-source management moved to Settings → Catalog sources.
+    {
+      path: '/repositories',
+      redirect: (to) => ({ path: '/add-server', query: { ...to.query, tab: 'catalog' } }),
+    },
     // `/search` used to be a third, sidebar-less search surface duplicating the
     // header box and the Tools page (audit F20). Tools is the canonical one —
     // it is in the sidebar, it lists what it searches, and it can act on the
diff --git a/frontend/src/services/api.ts b/frontend/src/services/api.ts
index 34b2235f5..09ba015e5 100644
--- a/frontend/src/services/api.ts
+++ b/frontend/src/services/api.ts
@@ -1,4 +1,4 @@
-import type { APIResponse, Server, Tool, ToolApproval, SearchResult, StatusUpdate, SecretRef, MigrationAnalysis, ConfigSecretsResponse, GetToolCallsResponse, GetToolCallDetailResponse, GetServerToolCallsResponse, GetConfigResponse, ValidateConfigResponse, ConfigApplyResult, ServerTokenMetrics, GetRegistriesResponse, SearchRegistryServersResponse, RegistrySummary, GetSessionsResponse, GetSessionDetailResponse, InfoResponse, ActivityListResponse, ActivityDetailResponse, ActivityRecord, ActivitySummaryResponse, ImportResponse, AgentTokenInfo, CreateAgentTokenRequest, CreateAgentTokenResponse, RoutingInfo, ConnectStatusResponse, ClientStatus, ConnectResult, ConnectPreview, OnboardingStateResponse, OnboardingMarkRequest, DiagnosticFixResponse, GlobalToolsResponse, UsageAggregateResponse, UsageWindow, UsageSort, UsageStatus, ListProfilesResponse, ActiveProfileResponse } from '@/types'
+import type { APIResponse, Server, Tool, ToolApproval, SearchResult, StatusUpdate, SecretRef, MigrationAnalysis, ConfigSecretsResponse, GetToolCallsResponse, GetToolCallDetailResponse, GetServerToolCallsResponse, GetConfigResponse, ValidateConfigResponse, ConfigApplyResult, ServerTokenMetrics, GetRegistriesResponse, SearchRegistryServersResponse, RegistrySummary, CatalogSearchResponse, GetSessionsResponse, GetSessionDetailResponse, InfoResponse, ActivityListResponse, ActivityDetailResponse, ActivityRecord, ActivitySummaryResponse, ImportResponse, AgentTokenInfo, CreateAgentTokenRequest, CreateAgentTokenResponse, RoutingInfo, ConnectStatusResponse, ClientStatus, ConnectResult, ConnectPreview, OnboardingStateResponse, OnboardingMarkRequest, DiagnosticFixResponse, GlobalToolsResponse, UsageAggregateResponse, UsageWindow, UsageSort, UsageStatus, ListProfilesResponse, ActiveProfileResponse } from '@/types'
 
 import { joinHoldEvidence, type HoldEvidenceSource } from '@/utils/holdEvidence'
 
@@ -741,6 +741,25 @@ class APIService {
     return this.request<SearchRegistryServersResponse>(url)
   }
 
+  // Catalog (Spec 109 FR-060): source-agnostic search across every enabled
+  // catalog source. `source` narrows to one (never selects a UI tab — that's
+  // the caller's job, FR-062).
+  async catalogSearch(options?: {
+    q?: string
+    source?: string
+    tag?: string
+    limit?: number
+  }): Promise<APIResponse<CatalogSearchResponse>> {
+    const params = new URLSearchParams()
+    if (options?.q) params.append('q', options.q)
+    if (options?.source) params.append('source', options.source)
+    if (options?.tag) params.append('tag', options.tag)
+    if (options?.limit) params.append('limit', options.limit.toString())
+
+    const url = `/api/v1/catalog/search${params.toString() ? '?' + params.toString() : ''}`
+    return this.request<CatalogSearchResponse>(url)
+  }
+
   // MCP-866 / MCP-867: add a user-supplied registry source. The server tags an
   // added source as custom provenance (provenance is NOT part of the request) —
   // informational only (MCP-1072); servers added from it follow the global
diff --git a/frontend/src/types/api.ts b/frontend/src/types/api.ts
index b6aef988c..4990c6f11 100644
--- a/frontend/src/types/api.ts
+++ b/frontend/src/types/api.ts
@@ -568,6 +568,11 @@ export interface ConfigSecretsResponse {
   environment_vars: EnvVarStatus[]
   total_secrets: number
   total_env_vars: number
+  // FR-065: whether the OS keyring provider is usable, and why not when it
+  // isn't — the Paste/Manual/Catalog secret toggle disables itself with this
+  // reason instead of failing silently on Add.
+  keyring_available: boolean
+  keyring_reason?: string
 }
 
 // Tool Call History types
@@ -817,6 +822,59 @@ export interface SearchRegistryServersResponse {
   tag?: string
 }
 
+// Catalog (Spec 109 FR-060/061), GET /api/v1/catalog/search. Mirrors
+// registries.CatalogResult — a DTO distinct from RepositoryServer/ServerEntry;
+// see contracts/rest-api.md#catalog.
+export interface CatalogPopularity {
+  stars?: number
+  installs?: number
+}
+
+export interface CatalogInstall {
+  url?: string
+  command?: string
+  args?: string[]
+}
+
+export interface CatalogInput {
+  name: string
+  description?: string
+  secret_like: boolean
+}
+
+export interface CatalogResult {
+  source: string
+  id: string
+  title: string
+  publisher?: string
+  verified: boolean
+  official: boolean
+  popularity?: CatalogPopularity
+  description: string
+  transport: 'http' | 'stdio'
+  install: CatalogInstall
+  required_inputs?: CatalogInput[]
+  source_code_url?: string
+  added: boolean
+}
+
+export interface CatalogSourceError {
+  source: string
+  reason: string
+}
+
+export interface CatalogSections {
+  official: CatalogResult[]
+  popular: CatalogResult[]
+}
+
+export interface CatalogSearchResponse {
+  query: string
+  results: CatalogResult[]
+  sections: CatalogSections | null
+  unavailable: CatalogSourceError[]
+}
+
 // Activity Log types (RFC-003)
 
 export type ActivityType =
@@ -973,6 +1031,22 @@ export interface ImportSummary {
   failed: number
 }
 
+// ImportFieldPreview types mirror httpapi.EnvFieldPreview / HeaderFieldPreview
+// (Spec 109 FR-064/065): never the raw value, only presence + two booleans a
+// surface uses to default the Value/Secret toggle.
+export interface ImportEnvFieldPreview {
+  name: string
+  value_present: boolean
+  secret_like: boolean
+  empty_or_placeholder: boolean
+}
+
+export interface ImportHeaderFieldPreview {
+  name: string
+  secret_like: boolean
+  empty_or_placeholder: boolean
+}
+
 export interface ImportedServer {
   name: string
   protocol: string
@@ -983,6 +1057,11 @@ export interface ImportedServer {
   original_name: string
   fields_skipped?: string[]
   warnings?: string[]
+  // FR-064 preview enrichment (contracts/rest-api.md "Import preview").
+  summary?: string
+  tags?: string[]
+  env?: ImportEnvFieldPreview[]
+  headers?: ImportHeaderFieldPreview[]
 }
 
 export interface SkippedServer {
diff --git a/frontend/src/utils/secretLike.ts b/frontend/src/utils/secretLike.ts
new file mode 100644
index 000000000..0f74edc47
--- /dev/null
+++ b/frontend/src/utils/secretLike.ts
@@ -0,0 +1,10 @@
+// Shared "does this field name look like a credential?" rule (Spec 109
+// research D13), ported verbatim from internal/secretlike/secretlike.go so
+// Go, this file and the Swift port (CatalogTests.swift) default the
+// Value/Secret toggle to Secret for the same field names (FR-065).
+const SECRET_LIKE_PATTERN =
+  /(token|secret|password|passwd|api[_-]?key|[_-]key$|auth|credential|private[_-]?key)/i
+
+export function looksSecret(name: string): boolean {
+  return SECRET_LIKE_PATTERN.test(name)
+}
diff --git a/frontend/src/utils/secretRef.ts b/frontend/src/utils/secretRef.ts
new file mode 100644
index 000000000..cdd7354fb
--- /dev/null
+++ b/frontend/src/utils/secretRef.ts
@@ -0,0 +1,54 @@
+// TS port of internal/secret/refname.go RefName (Spec 109 FR-065). Replaces
+// ServerDetail.vue's old `suggestSecretName`, which dropped the field KIND
+// (env vs header) and so let an env var and a header of the same name
+// collide on one keyring entry. Pinned against the shared fixture
+// (frontend/tests/unit/fixtures/ref_names.json, copied from
+// internal/secret/testdata/ref_names.json) so Go, this file and the Swift
+// port agree on every case.
+
+const REF_NAME_MAX_LEN = 64
+
+function normalizeRefComponent(s: string): string {
+  const lower = s.toLowerCase()
+  const collapsed = lower.replace(/[^a-z0-9-]+/g, '-')
+  const dedupedHyphens = collapsed.replace(/-{2,}/g, '-')
+  let trimmed = dedupedHyphens.replace(/^-+|-+$/g, '')
+  if (trimmed.length > REF_NAME_MAX_LEN) {
+    trimmed = trimmed.slice(0, REF_NAME_MAX_LEN).replace(/-+$/g, '')
+  }
+  return trimmed
+}
+
+/**
+ * refName computes the OS-keyring entry name for one field on one server
+ * (FR-065): "<server>-<kind>-<key>", lower-cased, with every run of
+ * characters outside [a-z0-9-] collapsed to a single '-', trimmed, and
+ * capped at 64 characters. kind is normally "env" or "header" — keeping it a
+ * distinct path component (rather than folding it into key) is what keeps an
+ * env var and a header of the same name from colliding on one entry.
+ *
+ * `taken` reports whether a candidate name is already present in the
+ * keyring (GET /secrets/refs); on a collision refName appends -2, -3, …
+ * until it finds a free one, so an add never silently overwrites an
+ * existing secret.
+ */
+export function refName(
+  server: string,
+  kind: 'env' | 'header',
+  key: string,
+  taken?: (name: string) => boolean
+): string {
+  const base = normalizeRefComponent(`${server}-${kind}-${key}`)
+  if (!taken) return base
+
+  let candidate = base
+  let n = 2
+  while (taken(candidate)) {
+    const suffix = `-${n}`
+    const maxBase = REF_NAME_MAX_LEN - suffix.length
+    const trimmedBase = base.length > maxBase ? base.slice(0, maxBase) : base
+    candidate = trimmedBase + suffix
+    n++
+  }
+  return candidate
+}
diff --git a/frontend/src/views/AddServer.vue b/frontend/src/views/AddServer.vue
new file mode 100644
index 000000000..cb1273bd4
--- /dev/null
+++ b/frontend/src/views/AddServer.vue
@@ -0,0 +1,82 @@
+<template>
+  <div class="p-6 max-w-4xl mx-auto" data-test="add-server-page">
+    <h1 class="text-2xl font-bold mb-1">Add Server</h1>
+    <p class="text-sm text-base-content/70 mb-6">
+      Browse the catalog, paste a URL or command, import a config, or fill in the fields yourself.
+    </p>
+
+    <div class="tabs tabs-box mb-6" data-test="add-server-tabs">
+      <a
+        v-for="t in tabs"
+        :key="t.id"
+        class="tab"
+        :class="activeTab === t.id ? 'tab-active' : ''"
+        :data-test="`add-server-tab-${t.id}`"
+        @click="activeTab = t.id"
+      >
+        {{ t.label }}
+      </a>
+    </div>
+
+    <CatalogSearch v-if="activeTab === 'catalog'" :source="sourceFilter" @added="handleAdded" />
+    <PasteServer v-else-if="activeTab === 'paste'" @added="handleAdded" />
+    <ImportServersPanel v-else-if="activeTab === 'import'" @imported="handleImported" />
+    <ManualServerForm v-else-if="activeTab === 'manual'" @added="handleAdded" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import CatalogSearch from '@/components/CatalogSearch.vue'
+import PasteServer from '@/components/PasteServer.vue'
+import ImportServersPanel from '@/components/ImportServersPanel.vue'
+import ManualServerForm from '@/components/ManualServerForm.vue'
+import { useSystemStore } from '@/stores/system'
+import { serverDetailPath } from '@/utils/serverRoute'
+
+// Spec 109 FR-062: Catalog (default) · Paste · Import · Manual, selected by
+// ?tab=, written back with router.replace so the URL stays deep-linkable and
+// other query params (notably ?source=, the catalog-source filter) survive.
+type TabId = 'catalog' | 'paste' | 'import' | 'manual'
+const tabs: { id: TabId; label: string }[] = [
+  { id: 'catalog', label: 'Catalog' },
+  { id: 'paste', label: 'Paste' },
+  { id: 'import', label: 'Import' },
+  { id: 'manual', label: 'Manual' },
+]
+const validTabs = new Set(tabs.map((t) => t.id))
+
+const route = useRoute()
+const router = useRouter()
+const systemStore = useSystemStore()
+
+function tabFromRoute(): TabId {
+  const q = route.query.tab
+  return typeof q === 'string' && validTabs.has(q as TabId) ? (q as TabId) : 'catalog'
+}
+
+const activeTab = ref<TabId>(tabFromRoute())
+// ?source= narrows the Catalog tab only — it never selects a tab (FR-062).
+const sourceFilter = computed(() => (typeof route.query.source === 'string' ? route.query.source : undefined))
+
+watch(activeTab, (tab) => {
+  void router.replace({ query: { ...route.query, tab } })
+})
+watch(
+  () => route.query.tab,
+  () => {
+    activeTab.value = tabFromRoute()
+  }
+)
+
+function handleAdded(name: string) {
+  systemStore.addToast({ type: 'success', title: 'Server Added', message: `${name} has been added successfully` })
+  void router.push(serverDetailPath(name))
+}
+
+function handleImported(count: number) {
+  systemStore.addToast({ type: 'success', title: 'Servers Imported', message: `${count} server(s) imported` })
+  void router.push('/servers')
+}
+</script>
diff --git a/frontend/src/views/Repositories.vue b/frontend/src/views/Repositories.vue
deleted file mode 100644
index a6c2f5854..000000000
--- a/frontend/src/views/Repositories.vue
+++ /dev/null
@@ -1,1149 +0,0 @@
-<template>
-  <div class="space-y-6">
-    <!-- Page Header -->
-    <div class="flex justify-between items-center">
-      <div>
-        <h1 class="text-3xl font-bold">Repositories</h1>
-        <p class="text-base-content/70 mt-1">Browse and discover MCP server repositories</p>
-      </div>
-      <button
-        @click="openAddRegistry"
-        class="btn btn-outline btn-sm"
-        data-test="registry-add-source-button"
-      >
-        <svg class="w-4 h-4 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4" />
-        </svg>
-        Add Registry
-      </button>
-    </div>
-
-    <!-- Configured registries (manage sources) — MCP-1073 -->
-    <div class="card bg-base-100 shadow-md" data-test="registries-manage-section">
-      <div class="card-body">
-        <div>
-          <h2 class="card-title text-lg">Registries</h2>
-          <!-- Audit F17: these cards sat above the selector looking exactly like
-               one, but were display-only. They ARE the selector now. -->
-          <p class="text-sm text-base-content/70">
-            Click a registry to search it. Custom sources you add can be edited or removed.
-          </p>
-        </div>
-
-        <!-- Loading -->
-        <div v-if="loadingRegistries" class="flex items-center gap-2 py-4 text-base-content/70" data-test="registries-loading">
-          <span class="loading loading-spinner loading-sm"></span>
-          <span>Loading registries…</span>
-        </div>
-
-        <!-- Empty (rare — defaults are always present) -->
-        <div v-else-if="registries.length === 0" class="text-sm text-base-content/60 py-4" data-test="registries-empty">
-          No registries configured.
-        </div>
-
-        <!-- Cards grid -->
-        <div v-else class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-3 mt-2">
-          <div
-            v-for="registry in registries"
-            :key="registry.id"
-            role="button"
-            tabindex="0"
-            :aria-pressed="selectedRegistries.includes(registry.id)"
-            :aria-label="`${selectedRegistries.includes(registry.id) ? 'Deselect' : 'Select'} ${registry.name}`"
-            :class="[
-              'border rounded-lg p-3 flex flex-col gap-2 cursor-pointer transition-colors text-left',
-              selectedRegistries.includes(registry.id)
-                ? 'border-primary bg-primary/5 ring-2 ring-inset ring-primary/30'
-                : 'border-base-300 hover:bg-base-200/60',
-            ]"
-            :data-test="`registry-card-${registry.id}`"
-            @click="toggleRegistry(registry.id)"
-            @keydown.enter.prevent="toggleRegistry(registry.id)"
-            @keydown.space.prevent="toggleRegistry(registry.id)"
-          >
-            <div class="flex items-start justify-between gap-2">
-              <div class="font-semibold min-w-0 [overflow-wrap:anywhere] flex items-center gap-1.5">
-                <svg
-                  v-if="selectedRegistries.includes(registry.id)"
-                  class="w-4 h-4 shrink-0 text-primary"
-                  fill="none"
-                  stroke="currentColor"
-                  viewBox="0 0 24 24"
-                  aria-hidden="true"
-                  :data-test="`registry-card-selected-${registry.id}`"
-                >
-                  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
-                </svg>
-                {{ registry.name }}
-              </div>
-
-              <!-- Kebab (⋮) menu — custom registries only; official is read-only.
-                   @click.stop so managing a source never doubles as selecting it. -->
-              <div v-if="isCustomRegistry(registry)" class="dropdown dropdown-end shrink-0" @click.stop>
-                <div
-                  tabindex="0"
-                  role="button"
-                  class="btn btn-ghost btn-xs btn-square"
-                  :data-test="`registry-kebab-${registry.id}`"
-                  :aria-label="`Manage ${registry.name}`"
-                >
-                  <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 24 24">
-                    <path d="M12 8a2 2 0 100-4 2 2 0 000 4zm0 2a2 2 0 100 4 2 2 0 000-4zm0 6a2 2 0 100 4 2 2 0 000-4z" />
-                  </svg>
-                </div>
-                <ul tabindex="0" class="dropdown-content menu bg-base-100 rounded-box z-10 w-32 p-1 shadow-lg border border-base-300">
-                  <li>
-                    <button type="button" :data-test="`registry-edit-${registry.id}`" @click="openEditRegistry(registry)">Edit</button>
-                  </li>
-                  <li>
-                    <button type="button" class="text-error" :data-test="`registry-delete-${registry.id}`" @click="openDeleteRegistry(registry)">Delete</button>
-                  </li>
-                </ul>
-              </div>
-            </div>
-
-            <!-- Neutral provenance badge (Official / Custom) + Built-in tag -->
-            <div class="flex flex-wrap gap-1 items-center">
-              <span
-                class="badge badge-sm"
-                :class="isCustomRegistry(registry) ? 'badge-ghost' : 'badge-outline'"
-                :data-test="`registry-provenance-${registry.id}`"
-              >{{ isCustomRegistry(registry) ? 'Custom' : 'Official' }}</span>
-              <span
-                v-if="!isCustomRegistry(registry)"
-                class="badge badge-sm badge-ghost"
-                :data-test="`registry-builtin-${registry.id}`"
-              >Built-in</span>
-            </div>
-
-            <div v-if="registry.url" class="text-xs text-base-content/60 truncate" :title="registry.url">{{ registry.url }}</div>
-          </div>
-        </div>
-      </div>
-    </div>
-
-    <!-- Registry Selector & Search -->
-    <div class="card bg-base-100 shadow-md">
-      <div class="card-body">
-        <div class="flex flex-col sm:flex-row gap-4">
-          <!-- Registry multiselect filter (R1): search across one or more registries at once -->
-          <div class="form-control flex-1">
-            <label class="label">
-              <span class="label-text font-semibold">Registries</span>
-            </label>
-            <div class="dropdown" data-test="registry-multiselect">
-              <div
-                tabindex="0"
-                role="button"
-                class="select select-bordered w-full flex items-center"
-                :class="{ 'opacity-60 pointer-events-none': loadingRegistries }"
-                data-test="registry-multiselect-trigger"
-              >
-                <span class="truncate">{{ registrySelectLabel }}</span>
-              </div>
-              <ul
-                tabindex="0"
-                class="dropdown-content menu bg-base-100 rounded-box z-10 w-full p-2 shadow-lg max-h-80 overflow-y-auto flex-nowrap mt-1 border border-base-300"
-                data-test="registry-multiselect-menu"
-              >
-                <li v-if="registries.length > 1" class="menu-title px-2 pb-1 flex flex-row gap-3">
-                  <button type="button" class="link link-primary text-xs" data-test="registry-select-all" @click="selectAllRegistries">All</button>
-                  <button type="button" class="link text-xs" data-test="registry-clear-all" @click="clearRegistries">Clear</button>
-                </li>
-                <li v-for="registry in registries" :key="registry.id">
-                  <label class="label cursor-pointer justify-start gap-3 py-2">
-                    <input
-                      type="checkbox"
-                      class="checkbox checkbox-sm"
-                      :checked="selectedRegistries.includes(registry.id)"
-                      @change="toggleRegistry(registry.id)"
-                      :data-test="`registry-option-${registry.id}`"
-                    />
-                    <span class="text-sm">{{ registry.name }}<span v-if="isCustomRegistry(registry)" class="opacity-60"> — custom</span></span>
-                  </label>
-                </li>
-              </ul>
-            </div>
-          </div>
-
-          <!-- Search Input -->
-          <div class="form-control flex-1">
-            <label class="label">
-              <span class="label-text font-semibold">Search Servers</span>
-            </label>
-            <input
-              v-model="searchQuery"
-              type="text"
-              :placeholder="selectedRegistries.length === 0 ? 'Select a registry above first' : 'Search by name or description...'"
-              class="input input-bordered w-full"
-              data-test="registry-search-input"
-              @input="handleSearchInput"
-              :disabled="selectedRegistries.length === 0 || loadingServers"
-            />
-            <!-- Audit F17: a disabled field must say what would enable it. -->
-            <label v-if="selectedRegistries.length === 0" class="label py-1">
-              <span class="label-text-alt text-base-content/60" data-test="registry-search-hint">
-                Click a registry card above to enable search.
-              </span>
-            </label>
-          </div>
-
-          <!-- Transport Filter (R3) -->
-          <div class="form-control">
-            <label class="label">
-              <span class="label-text font-semibold">Transport</span>
-            </label>
-            <select
-              v-model="transportFilter"
-              class="select select-bordered"
-              data-test="registry-transport-filter"
-            >
-              <option value="all">All</option>
-              <option value="remote">Remote</option>
-              <option value="stdio">Stdio</option>
-            </select>
-          </div>
-
-          <!-- Search Button -->
-          <div class="form-control sm:self-end">
-            <button
-              @click="searchServers"
-              class="btn btn-primary"
-              data-test="registry-search-button"
-              :disabled="selectedRegistries.length === 0 || loadingServers"
-            >
-              <span v-if="loadingServers" class="loading loading-spinner loading-sm"></span>
-              <span v-else>Search</span>
-            </button>
-          </div>
-        </div>
-      </div>
-    </div>
-
-    <!-- Loading State -->
-    <div v-if="loadingServers" class="card bg-base-100 shadow-md">
-      <div class="card-body">
-        <div class="flex flex-col items-center justify-center py-12">
-          <div class="loading loading-spinner loading-lg mb-4"></div>
-          <p class="text-base-content/70">Searching servers...</p>
-        </div>
-      </div>
-    </div>
-
-    <!-- Error State -->
-    <div v-else-if="error" class="alert alert-error">
-      <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
-      </svg>
-      <span>{{ error }}</span>
-    </div>
-
-    <!-- Server Results -->
-    <div v-else-if="servers.length > 0" class="space-y-4">
-      <!-- Non-fatal: some selected registries returned nothing (e.g. need a key) -->
-      <div
-        v-if="unavailableRegistries.length > 0"
-        class="alert alert-warning py-2 text-sm"
-        data-test="registry-unavailable-notice"
-      >
-        <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
-        </svg>
-        <span>Some registries returned no results: {{ unavailableRegistries.join('; ') }}</span>
-      </div>
-
-      <div class="flex justify-between items-center">
-        <p class="text-sm text-base-content/70" data-test="registry-results-count">
-          Found {{ filteredServers.length }} server(s)<span v-if="transportFilter !== 'all'"> of {{ servers.length }}</span>
-          <span v-if="selectedRegistries.length > 1"> across {{ selectedRegistries.length }} registries</span>
-        </p>
-      </div>
-
-      <!-- Server Cards with Smooth Transitions -->
-      <TransitionGroup
-        name="repo-card"
-        tag="div"
-        class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4"
-      >
-        <div v-for="server in filteredServers" :key="`${server.registry}-${server.id}`" :data-test="`registry-server-${server.id}`" class="card bg-base-100 shadow-md hover:shadow-lg transition-shadow">
-          <div class="card-body">
-            <div class="flex justify-between items-start gap-2">
-              <h3 class="card-title text-lg min-w-0 [overflow-wrap:anywhere]">{{ server.name }}</h3>
-              <div
-                v-if="server.registry"
-                class="badge badge-ghost badge-sm shrink-0 whitespace-nowrap font-normal"
-                :data-test="`registry-source-${server.id}`"
-                :title="`From registry: ${server.registry}`"
-              >
-                {{ server.registry }}
-              </div>
-            </div>
-
-            <p class="text-sm text-base-content/70 line-clamp-3">
-              {{ server.description }}
-            </p>
-
-            <!-- Transport + requirements (neutral, non-colorful tags — R2) -->
-            <div class="flex flex-wrap gap-2 mt-2">
-              <div
-                class="badge badge-outline badge-sm font-mono"
-                :data-test="`registry-transport-${server.id}`"
-              >
-                {{ serverTransport(server) }}
-              </div>
-              <div
-                v-if="server.required_inputs && server.required_inputs.length > 0"
-                class="badge badge-outline badge-sm"
-                :data-test="`registry-requires-input-${server.id}`"
-                :title="`Requires: ${server.required_inputs.map(i => i.name).join(', ')}`"
-              >
-                requires input
-              </div>
-            </div>
-
-            <!-- Install Command -->
-            <div v-if="server.install_cmd" class="mt-3">
-              <div class="flex items-center justify-between bg-base-200 rounded px-2 py-1">
-                <code class="text-xs flex-1 overflow-x-auto">{{ server.install_cmd }}</code>
-                <button
-                  @click="copyToClipboard(server.install_cmd)"
-                  class="btn btn-ghost btn-xs ml-2"
-                  title="Copy install command"
-                >
-                  <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
-                  </svg>
-                </button>
-              </div>
-            </div>
-
-            <!-- Actions -->
-            <div class="card-actions justify-end mt-4">
-              <button
-                v-if="server.source_code_url"
-                @click="openURL(server.source_code_url)"
-                class="btn btn-ghost btn-sm"
-              >
-                <svg class="w-4 h-4 mr-1" fill="currentColor" viewBox="0 0 24 24">
-                  <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/>
-                </svg>
-                Source
-              </button>
-              <!-- Spec 109 FR-063: "Add to MCPProxy", flipping to a
-                   persistent "Added ✓ · Open" once the add succeeds. -->
-              <button
-                v-if="!addedServers[server.id]"
-                @click="addServer(server)"
-                class="btn btn-primary btn-sm"
-                :data-test="`registry-add-${server.id}`"
-                :disabled="addingServerId === server.id"
-              >
-                <span v-if="addingServerId === server.id" class="loading loading-spinner loading-xs"></span>
-                <span v-else>Add to MCPProxy</span>
-              </button>
-              <button
-                v-else
-                @click="openAddedServer(server)"
-                class="btn btn-success btn-sm"
-                :data-test="`registry-added-${server.id}`"
-              >
-                Added ✓ · Open
-              </button>
-            </div>
-          </div>
-        </div>
-      </TransitionGroup>
-    </div>
-
-    <!-- Empty State (no search yet) -->
-    <div v-else-if="selectedRegistries.length === 0" class="card bg-base-100 shadow-md">
-      <div class="card-body">
-        <div class="text-center py-12">
-          <svg class="w-16 h-16 mx-auto mb-4 opacity-50" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 11H5m14 0a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2v-6a2 2 0 012-2m14 0V9a2 2 0 00-2-2M5 11V9a2 2 0 012-2m0 0V5a2 2 0 012-2h6a2 2 0 012 2v2M7 7h10" />
-          </svg>
-          <h3 class="text-xl font-semibold mb-2">Select a Registry</h3>
-          <p class="text-base-content/70">Click one of the registry cards above to start browsing MCP servers.</p>
-        </div>
-      </div>
-    </div>
-
-    <!-- Empty State (no results) -->
-    <div v-else class="card bg-base-100 shadow-md">
-      <div class="card-body">
-        <div class="text-center py-12">
-          <svg class="w-16 h-16 mx-auto mb-4 opacity-50" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9.172 16.172a4 4 0 015.656 0M9 10h.01M15 10h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
-          </svg>
-          <h3 class="text-xl font-semibold mb-2">No Servers Found</h3>
-          <p class="text-base-content/70">Try adjusting your search query or select a different registry.</p>
-        </div>
-      </div>
-    </div>
-
-    <!-- Required-Input Prompt (Spec 070 — blocks add until provided) -->
-    <dialog ref="promptDialogEl" class="modal" data-test="registry-required-input-dialog">
-      <div class="modal-box">
-        <h3 class="font-bold text-lg">Add "{{ promptServer?.name }}"</h3>
-        <p class="text-sm text-base-content/70 mt-1">
-          This server needs the following before it can be added. Values are stored as
-          environment variables on the (quarantined) server.
-        </p>
-
-        <form @submit.prevent="submitPrompt" class="mt-4 space-y-3">
-          <div v-for="input in promptInputs" :key="input.name" class="form-control">
-            <label class="label">
-              <span class="label-text font-semibold">{{ input.name }}</span>
-            </label>
-            <input
-              v-model="promptValues[input.name]"
-              :type="input.secret ? 'password' : 'text'"
-              :placeholder="input.description || input.name"
-              :data-test="`registry-input-${input.name}`"
-              class="input input-bordered w-full"
-              autocomplete="off"
-            />
-            <label v-if="input.description" class="label">
-              <span class="label-text-alt text-base-content/60">{{ input.description }}</span>
-            </label>
-          </div>
-
-          <div v-if="error" class="alert alert-error text-sm" data-test="registry-input-error">
-            <span>{{ error }}</span>
-          </div>
-
-          <div class="modal-action">
-            <button type="button" class="btn btn-ghost" data-test="registry-input-cancel" @click="closePrompt">
-              Cancel
-            </button>
-            <button
-              type="submit"
-              class="btn btn-primary"
-              data-test="registry-input-submit"
-              :disabled="!promptComplete || addingServerId !== null"
-            >
-              <span v-if="addingServerId !== null" class="loading loading-spinner loading-xs"></span>
-              <span v-else>Add to MCPProxy</span>
-            </button>
-          </div>
-        </form>
-      </div>
-      <form method="dialog" class="modal-backdrop">
-        <button @click="closePrompt">close</button>
-      </form>
-    </dialog>
-
-    <!-- Add / Edit Registry Source dialog (MCP-866 add, MCP-1073 edit) -->
-    <dialog ref="addRegistryDialogEl" class="modal" data-test="registry-add-source-dialog">
-      <div class="modal-box">
-        <h3 class="font-bold text-lg">{{ isEditMode ? 'Edit registry' : 'Add a registry' }}</h3>
-        <p class="text-sm text-base-content/70 mt-1">
-          <template v-if="isEditMode">
-            Update this custom <code>modelcontextprotocol/registry</code> source. Its id is fixed.
-          </template>
-          <template v-else>
-            Add a custom <code>modelcontextprotocol/registry</code> v0.1 source by its HTTPS URL —
-            that is the only registry protocol MCPProxy speaks, so the URL is checked when you add it
-            and rejected here if it turns out not to be one (a plain JSON catalog or a web page cannot be browsed).
-            It is shown as a <span class="badge badge-ghost badge-xs align-middle">Custom</span> source.
-          </template>
-        </p>
-
-        <form @submit.prevent="submitRegistryDialog" class="mt-4 space-y-3" data-test="registry-add-form">
-          <!-- Read-only id (edit mode only) -->
-          <div v-if="isEditMode" class="form-control">
-            <label class="label">
-              <span class="label-text font-semibold">Registry ID</span>
-            </label>
-            <input
-              :value="editRegistryId"
-              type="text"
-              data-test="registry-edit-id"
-              class="input input-bordered w-full opacity-70"
-              readonly
-            />
-          </div>
-
-          <div class="form-control">
-            <label class="label">
-              <span class="label-text font-semibold">Registry URL</span>
-            </label>
-            <input
-              v-model="addRegistryUrl"
-              type="url"
-              placeholder="https://registry.example.com/"
-              data-test="registry-add-url-input"
-              class="input input-bordered w-full"
-              autocomplete="off"
-              required
-            />
-          </div>
-
-          <div v-if="!isEditMode" class="form-control">
-            <label class="label">
-              <span class="label-text font-semibold">Protocol</span>
-            </label>
-            <select
-              v-model="addRegistryProtocol"
-              class="select select-bordered w-full"
-              data-test="registry-add-protocol-select"
-            >
-              <option value="modelcontextprotocol/registry">modelcontextprotocol/registry (default)</option>
-            </select>
-          </div>
-
-          <div class="form-control">
-            <label class="label">
-              <span class="label-text font-semibold">Name <span class="font-normal opacity-60">(optional)</span></span>
-            </label>
-            <input
-              v-model="addRegistryName"
-              type="text"
-              placeholder="Derived from the URL host when empty"
-              data-test="registry-add-name-input"
-              class="input input-bordered w-full"
-              autocomplete="off"
-            />
-          </div>
-
-          <div v-if="addRegistryError" class="alert alert-error text-sm" data-test="registry-add-error">
-            <span>{{ addRegistryError }}</span>
-          </div>
-
-          <div class="modal-action">
-            <button type="button" class="btn btn-ghost" data-test="registry-add-cancel" :disabled="addingRegistry" @click="closeAddRegistry">
-              Cancel
-            </button>
-            <button
-              type="submit"
-              class="btn btn-primary"
-              data-test="registry-add-submit"
-              :disabled="!addRegistryUrl.trim() || addingRegistry"
-            >
-              <span v-if="addingRegistry" class="loading loading-spinner loading-xs"></span>
-              <span v-else>{{ isEditMode ? 'Save changes' : 'Add Registry' }}</span>
-            </button>
-          </div>
-        </form>
-      </div>
-      <form method="dialog" class="modal-backdrop">
-        <button @click="closeAddRegistry">close</button>
-      </form>
-    </dialog>
-
-    <!-- Delete custom registry confirmation (MCP-1073, destructive) -->
-    <dialog ref="deleteRegistryDialogEl" class="modal" data-test="registry-delete-dialog">
-      <div class="modal-box">
-        <h3 class="font-bold text-lg">Remove "{{ deleteRegistryTarget?.name }}"?</h3>
-        <p class="text-sm py-2 text-base-content/80">
-          Servers you already added stay; only the source is removed.
-        </p>
-
-        <div v-if="deleteRegistryError" class="alert alert-error text-sm" data-test="registry-delete-error">
-          <span>{{ deleteRegistryError }}</span>
-        </div>
-
-        <div class="modal-action">
-          <button type="button" class="btn btn-ghost" data-test="registry-delete-cancel" :disabled="deletingRegistry" @click="closeDeleteRegistry">
-            Cancel
-          </button>
-          <button
-            type="button"
-            class="btn btn-error"
-            data-test="registry-delete-confirm"
-            :disabled="deletingRegistry"
-            @click="confirmDeleteRegistry"
-          >
-            <span v-if="deletingRegistry" class="loading loading-spinner loading-xs"></span>
-            <span v-else>Remove</span>
-          </button>
-        </div>
-      </div>
-      <form method="dialog" class="modal-backdrop">
-        <button @click="closeDeleteRegistry">close</button>
-      </form>
-    </dialog>
-
-    <!-- Success Toast -->
-    <div v-if="showSuccessToast" class="toast toast-end" data-test="registry-add-success">
-      <div class="alert alert-success">
-        <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
-        </svg>
-        <span>{{ successMessage }}</span>
-      </div>
-    </div>
-
-    <!-- Hints Panel (Bottom of Page) -->
-    <CollapsibleHintsPanel :hints="repositoriesHints" />
-  </div>
-</template>
-
-<script setup lang="ts">
-import { ref, computed, onMounted } from 'vue'
-import { useRouter } from 'vue-router'
-import api from '@/services/api'
-import CollapsibleHintsPanel from '@/components/CollapsibleHintsPanel.vue'
-import type { Hint } from '@/components/CollapsibleHintsPanel.vue'
-import type { Registry, RepositoryServer, RequiredInput } from '@/types'
-import { REGISTRY_PROVENANCE_CUSTOM } from '@/types'
-import { useDialogOpen } from '@/composables/useDialogOpen'
-import { serverDetailPath } from '@/utils/serverRoute'
-
-// State
-const registries = ref<Registry[]>([])
-const selectedRegistries = ref<string[]>([])
-// Registries that returned no data this search (e.g. require an API key, or
-// errored) — surfaced as a non-fatal notice so partial cross-registry results
-// still render.
-const unavailableRegistries = ref<string[]>([])
-const searchQuery = ref<string>('')
-const servers = ref<RepositoryServer[]>([])
-const loadingRegistries = ref(false)
-const loadingServers = ref(false)
-const error = ref<string | null>(null)
-const addingServerId = ref<string | null>(null)
-// Spec 109 FR-063: keyed by registry entry id -> the resulting server's name,
-// so the button can flip to "Added ✓ · Open" and stay that way for the rest
-// of this page visit (a fresh load/registry refresh clears it, matching the
-// entry possibly not being re-addable anyway).
-const addedServers = ref<Record<string, string>>({})
-const router = useRouter()
-const showSuccessToast = ref(false)
-const successMessage = ref('')
-
-// Required-input prompt state (Spec 070, T016)
-const promptServer = ref<RepositoryServer | null>(null)
-const promptInputs = ref<RequiredInput[]>([])
-const promptValues = ref<Record<string, string>>({})
-
-// Add / edit registry-source dialog state (MCP-866 add, MCP-1073 edit).
-// editRegistryId is empty in add mode and the registry id in edit mode.
-const showAddRegistry = ref(false)
-const editRegistryId = ref<string | null>(null)
-const addRegistryUrl = ref('')
-const addRegistryProtocol = ref('modelcontextprotocol/registry')
-const addRegistryName = ref('')
-const addRegistryError = ref<string | null>(null)
-const addingRegistry = ref(false)
-const isEditMode = computed(() => editRegistryId.value !== null)
-// Spec 109 FR-055: <dialog>.showModal()/close(), not the `open` attribute —
-// keeps the top layer, so nothing (sidebar, header) can ever paint over it.
-// The native-close handler is deliberately NOT closeAddRegistry() — see the
-// comment on handleAddRegistryNativeClose for why (review round 2, finding 1).
-const { dialogEl: addRegistryDialogEl } = useDialogOpen(() => showAddRegistry.value, () => handleAddRegistryNativeClose())
-
-// Delete-custom-registry confirmation state (MCP-1073)
-const showDeleteRegistry = ref(false)
-const deleteRegistryTarget = ref<Registry | null>(null)
-const deleteRegistryError = ref<string | null>(null)
-const deletingRegistry = ref(false)
-const { dialogEl: deleteRegistryDialogEl } = useDialogOpen(() => showDeleteRegistry.value, () => handleDeleteRegistryNativeClose())
-
-let searchDebounceTimer: ReturnType<typeof setTimeout> | null = null
-
-// A registry is "custom/unverified" (third-party) when its provenance says so,
-// or — defensively — when trusted is explicitly false. Anything else (including
-// older payloads without the field) is treated as official/trusted.
-function isCustomRegistry(registry?: Registry | null): boolean {
-  if (!registry) return false
-  return registry.provenance === REGISTRY_PROVENANCE_CUSTOM || registry.trusted === false
-}
-
-// Transport classification (R2) + filter (R3). Derived purely from the
-// install command / url already returned by the registry search API:
-//   url set, no install cmd        -> remote
-//   npx / npm / node               -> stdio:npm
-//   uvx / uv / pip / python        -> stdio:python
-//   docker                         -> stdio:docker
-//   anything else with install cmd -> stdio
-const transportFilter = ref<'all' | 'remote' | 'stdio'>('all')
-
-function serverTransport(server: RepositoryServer): string {
-  const cmd = (server.install_cmd || '').trim().toLowerCase()
-  if (cmd) {
-    if (cmd.startsWith('docker')) return 'stdio:docker'
-    if (cmd.startsWith('npx') || /(^|\s)(npm|node)(\s|$)/.test(cmd)) return 'stdio:npm'
-    if (cmd.startsWith('uvx') || cmd.startsWith('uv ') || /(^|\s)(pipx?|python3?)(\s|$)/.test(cmd)) return 'stdio:python'
-    return 'stdio'
-  }
-  if (server.url) return 'remote'
-  return 'stdio'
-}
-
-const filteredServers = computed(() => {
-  if (transportFilter.value === 'all') return servers.value
-  return servers.value.filter(s => {
-    const t = serverTransport(s)
-    return transportFilter.value === 'remote' ? t === 'remote' : t.startsWith('stdio')
-  })
-})
-
-// Registry multiselect (R1) -------------------------------------------------
-function registryName(id: string): string {
-  return registries.value.find(r => r.id === id)?.name || id
-}
-
-const registrySelectLabel = computed(() => {
-  const n = selectedRegistries.value.length
-  if (n === 0) return 'Choose registries…'
-  if (n === 1) return registryName(selectedRegistries.value[0])
-  if (n === registries.value.length) return `All registries (${n})`
-  return `${n} registries`
-})
-
-function toggleRegistry(id: string) {
-  const i = selectedRegistries.value.indexOf(id)
-  if (i === -1) selectedRegistries.value.push(id)
-  else selectedRegistries.value.splice(i, 1)
-  handleRegistryChange()
-}
-
-function selectAllRegistries() {
-  selectedRegistries.value = registries.value.map(r => r.id)
-  handleRegistryChange()
-}
-
-function clearRegistries() {
-  selectedRegistries.value = []
-  handleRegistryChange()
-}
-
-const showPrompt = computed(() => promptServer.value !== null)
-const { dialogEl: promptDialogEl } = useDialogOpen(() => showPrompt.value, () => closePrompt())
-
-// Add is blocked until every prompted input has a non-empty value.
-const promptComplete = computed(() =>
-  promptInputs.value.every(i => (promptValues.value[i.name] || '').trim() !== '')
-)
-
-const repositoriesHints = computed<Hint[]>(() => {
-  return [
-    {
-      icon: '📦',
-      title: 'Discover MCP Servers',
-      description: 'Browse official and community MCP servers from multiple registries',
-      sections: [
-        {
-          title: 'How to use',
-          list: [
-            'Select a registry from the dropdown menu',
-            'Search for servers by name or description',
-            'Click "Add to MCPProxy" to install a server',
-            'View source code and installation commands for each server'
-          ]
-        }
-      ]
-    },
-    {
-      icon: '🤖',
-      title: 'LLM Agent Integration',
-      description: 'Let AI agents help you discover and install MCP servers',
-      sections: [
-        {
-          title: 'Example prompts',
-          list: [
-            'Find and add MCP servers for working with GitHub',
-            'Install the best MCP server for file system operations',
-            'Search for database-related MCP servers and add them',
-            'Discover Slack integration servers and configure them'
-          ]
-        }
-      ]
-    },
-    {
-      icon: '💡',
-      title: 'Installation Tips',
-      description: 'Servers can be installed via npm, pip, or connected remotely',
-      sections: [
-        {
-          title: 'Server types',
-          list: [
-            'NPM packages: Installed with npx command',
-            'Python packages: Installed with uvx or pipx',
-            'Remote servers: Connected via HTTP endpoints',
-            'Docker containers: Run in isolated environments'
-          ]
-        }
-      ]
-    }
-  ]
-})
-
-// Methods
-async function loadRegistries() {
-  loadingRegistries.value = true
-  error.value = null
-
-  try {
-    const response = await api.listRegistries()
-    if (response.success && response.data) {
-      registries.value = response.data.registries
-    } else {
-      error.value = response.error || 'Failed to load registries'
-    }
-  } catch (err) {
-    error.value = 'Failed to load registries: ' + (err as Error).message
-  } finally {
-    loadingRegistries.value = false
-  }
-}
-
-// Cross-registry search (R1): fan out to every selected registry in parallel
-// and merge the results. Each result already carries its own `registry` for
-// per-card attribution. Per-registry failures (e.g. key-required, unreachable)
-// are collected into a non-fatal notice so the registries that DID return keep
-// rendering; we only raise a hard error when every selected registry failed.
-async function searchServers() {
-  const ids = selectedRegistries.value
-  if (ids.length === 0) {
-    servers.value = []
-    return
-  }
-
-  loadingServers.value = true
-  error.value = null
-  unavailableRegistries.value = []
-
-  try {
-    const results = await Promise.all(
-      ids.map(id =>
-        api
-          .searchRegistryServers(id, { query: searchQuery.value, limit: 20 })
-          .then(r => ({ id, r }))
-          .catch(err => ({ id, r: { success: false, error: (err as Error).message } as any }))
-      )
-    )
-
-    const merged: RepositoryServer[] = []
-    const seen = new Set<string>()
-    const failures: string[] = []
-
-    for (const { id, r } of results) {
-      if (r.success && r.data) {
-        if (r.data.unavailable) {
-          failures.push(`${registryName(id)}: ${r.data.unavailable.reason || 'unavailable'}`)
-        }
-        for (const s of r.data.servers || []) {
-          const key = `${s.registry || id}::${s.id}`
-          if (seen.has(key)) continue
-          seen.add(key)
-          merged.push(s)
-        }
-      } else {
-        failures.push(`${registryName(id)}: ${r.error || 'failed'}`)
-      }
-    }
-
-    servers.value = merged
-    unavailableRegistries.value = failures
-    // Only a hard error when nothing came back AND every registry failed.
-    if (merged.length === 0 && failures.length > 0 && failures.length === ids.length) {
-      error.value = 'No results — ' + failures.join('; ')
-    }
-  } finally {
-    loadingServers.value = false
-  }
-}
-
-function handleRegistryChange() {
-  servers.value = []
-  error.value = null
-  unavailableRegistries.value = []
-  if (selectedRegistries.value.length > 0) {
-    searchServers()
-  }
-}
-
-function handleSearchInput() {
-  if (searchDebounceTimer) {
-    clearTimeout(searchDebounceTimer)
-  }
-
-  searchDebounceTimer = setTimeout(() => {
-    if (selectedRegistries.value.length > 0) {
-      searchServers()
-    }
-  }, 500)
-}
-
-// Add a server by reference (Spec 070, T015/T016). The server re-derives the
-// config from the registry entry — no client-side install_cmd parsing. When the
-// entry declares required inputs the backend returns `missing_required_input`
-// with the missing names; we open a prompt, collect values, and resubmit as env.
-async function addServer(server: RepositoryServer, env?: Record<string, string>) {
-  if (!server.registry) {
-    error.value = 'Cannot add: server is missing its registry id.'
-    return
-  }
-
-  addingServerId.value = server.id
-  error.value = null
-
-  try {
-    const result = await api.addServerFromRegistry(server.registry, server.id, env ? { env } : undefined)
-
-    if (result.success) {
-      closePrompt()
-      const name = result.server?.name || server.name
-      addedServers.value[server.id] = name
-      showToast(`Added "${name}" — quarantined. Approve it on the Servers page to enable.`)
-      return
-    }
-
-    if (result.code === 'missing_required_input') {
-      openPrompt(server, result.missingInputs || [])
-      return
-    }
-
-    error.value = result.error || 'Failed to add server'
-  } catch (err) {
-    error.value = 'Failed to add server: ' + (err as Error).message
-  } finally {
-    addingServerId.value = null
-  }
-}
-
-// Spec 109 FR-063: "Added ✓ · Open" opens the server it just added.
-function openAddedServer(server: RepositoryServer) {
-  const name = addedServers.value[server.id]
-  if (!name) return
-  router.push(serverDetailPath(name))
-}
-
-// Open the required-input prompt. Prefer the rich declarations carried on the
-// search result (name + description + secret); fall back to bare names from the
-// backend's missing_required_input error when the search response omitted them.
-function openPrompt(server: RepositoryServer, missingNames: string[]) {
-  const declared = server.required_inputs || []
-  const inputs: RequiredInput[] = missingNames.length > 0
-    ? missingNames.map(name => declared.find(d => d.name === name) || { name })
-    : declared
-
-  promptServer.value = server
-  promptInputs.value = inputs
-  promptValues.value = Object.fromEntries(inputs.map(i => [i.name, '']))
-}
-
-function submitPrompt() {
-  if (!promptServer.value || !promptComplete.value) return
-  // Trim values; resubmit through the same add path with the collected env.
-  const env: Record<string, string> = {}
-  for (const input of promptInputs.value) {
-    env[input.name] = (promptValues.value[input.name] || '').trim()
-  }
-  addServer(promptServer.value, env)
-}
-
-function closePrompt() {
-  promptServer.value = null
-  promptInputs.value = []
-  promptValues.value = {}
-}
-
-// --- Add / edit / delete registry source (MCP-866 add, MCP-1073 edit+delete) ---
-
-// Open the dialog in add mode (blank, editRegistryId = null).
-function openAddRegistry() {
-  editRegistryId.value = null
-  addRegistryUrl.value = ''
-  addRegistryProtocol.value = 'modelcontextprotocol/registry'
-  addRegistryName.value = ''
-  addRegistryError.value = null
-  showAddRegistry.value = true
-}
-
-// Open the dialog in edit mode, pre-filled from a custom registry (MCP-1073).
-// The id is fixed and shown read-only; only name/url are editable.
-function openEditRegistry(registry: Registry) {
-  editRegistryId.value = registry.id
-  addRegistryUrl.value = registry.url || registry.servers_url || ''
-  addRegistryName.value = registry.name || ''
-  addRegistryError.value = null
-  showAddRegistry.value = true
-}
-
-function closeAddRegistry() {
-  if (addingRegistry.value) return
-  showAddRegistry.value = false
-  editRegistryId.value = null
-}
-
-// The Cancel button and the invisible backdrop-dismiss button both wire to
-// closeAddRegistry(), which intentionally no-ops while a submit is in
-// flight. A native close (Escape, or `<dialog>`'s own backdrop/cancel
-// handling) is different: the dialog has ALREADY closed in the DOM by the
-// time this fires, and nothing here can undo that. Reusing closeAddRegistry
-// there (review round 1) meant its addingRegistry guard silently skipped the
-// `showAddRegistry` flip too, leaving Vue believing the dialog was still
-// open while the DOM said otherwise — the button that would reopen it then
-// sets `showAddRegistry` to a value it already holds, the driving watch
-// never re-fires, and `showModal()` never runs again (round 1's exact bug,
-// reintroduced here — review round 2, finding 1). Always resync local state
-// on a native close; doAddRegistry()/doEditRegistry() already tolerate the
-// dialog having moved on by the time their request settles.
-function handleAddRegistryNativeClose() {
-  showAddRegistry.value = false
-  editRegistryId.value = null
-}
-
-// Map the backend's stable error codes to actionable messages. Shared across
-// add / edit / delete since all three surface the same code set.
-function registryErrorMessage(code: string | undefined, fallback: string | undefined, verb: string): string {
-  switch (code) {
-    case 'invalid_registry_url':
-      return fallback || 'That URL is not a valid HTTPS registry endpoint.'
-    case 'registries_locked':
-      return `${verb} registries is locked by an administrator on this instance.`
-    case 'registry_shadows_builtin':
-      return 'That id/host collides with a built-in registry.'
-    case 'registry_not_found':
-      return 'That registry no longer exists. It may have already been removed.'
-    case 'duplicate_registry':
-      return 'A registry with that id is already configured.'
-    default:
-      return fallback || `Failed to ${verb.toLowerCase()} registry.`
-  }
-}
-
-// Single submit path for both add and edit modes.
-function submitRegistryDialog() {
-  if (!addRegistryUrl.value.trim() || addingRegistry.value) return
-  if (isEditMode.value) doEditRegistry()
-  else doAddRegistry()
-}
-
-async function doAddRegistry() {
-  addingRegistry.value = true
-  addRegistryError.value = null
-
-  try {
-    const result = await api.addRegistrySource(addRegistryUrl.value.trim(), {
-      protocol: addRegistryProtocol.value || undefined,
-      name: addRegistryName.value.trim() || undefined
-    })
-
-    if (result.success) {
-      const added = result.registry
-      showAddRegistry.value = false
-      // Refresh the list so the new custom entry appears, then select it for
-      // immediate browsing.
-      await loadRegistries()
-      if (added?.id) {
-        if (!selectedRegistries.value.includes(added.id)) selectedRegistries.value.push(added.id)
-        handleRegistryChange()
-      }
-      showToast(`Added registry "${added?.name || added?.id || addRegistryUrl.value}".`)
-      return
-    }
-
-    addRegistryError.value = registryErrorMessage(result.code, result.error, 'Adding')
-  } catch (err) {
-    addRegistryError.value = 'Failed to add registry: ' + (err as Error).message
-  } finally {
-    addingRegistry.value = false
-  }
-}
-
-async function doEditRegistry() {
-  const id = editRegistryId.value
-  if (!id) return
-  addingRegistry.value = true
-  addRegistryError.value = null
-
-  try {
-    const result = await api.editRegistrySource(id, {
-      name: addRegistryName.value.trim() || undefined,
-      url: addRegistryUrl.value.trim() || undefined
-    })
-
-    if (result.success) {
-      showAddRegistry.value = false
-      editRegistryId.value = null
-      await loadRegistries()
-      const updated = result.registry
-      showToast(`Updated registry "${updated?.name || updated?.id || id}".`)
-      return
-    }
-
-    addRegistryError.value = registryErrorMessage(result.code, result.error, 'Editing')
-  } catch (err) {
-    addRegistryError.value = 'Failed to edit registry: ' + (err as Error).message
-  } finally {
-    addingRegistry.value = false
-  }
-}
-
-// Delete-custom-registry confirmation flow (MCP-1073). The kebab Delete only
-// opens the modal; the API call happens on explicit confirm.
-function openDeleteRegistry(registry: Registry) {
-  deleteRegistryTarget.value = registry
-  deleteRegistryError.value = null
-  showDeleteRegistry.value = true
-}
-
-function closeDeleteRegistry() {
-  if (deletingRegistry.value) return
-  showDeleteRegistry.value = false
-  deleteRegistryTarget.value = null
-}
-
-// See handleAddRegistryNativeClose above — same reasoning, applied to the
-// delete-confirm dialog (review round 2, finding 1).
-function handleDeleteRegistryNativeClose() {
-  showDeleteRegistry.value = false
-  deleteRegistryTarget.value = null
-}
-
-async function confirmDeleteRegistry() {
-  const target = deleteRegistryTarget.value
-  if (!target) return
-  deletingRegistry.value = true
-  deleteRegistryError.value = null
-
-  try {
-    const result = await api.removeRegistrySource(target.id)
-    if (result.success) {
-      // Drop it from any active selection so the search filter stays consistent.
-      const i = selectedRegistries.value.indexOf(target.id)
-      if (i !== -1) {
-        selectedRegistries.value.splice(i, 1)
-        handleRegistryChange()
-      }
-      showDeleteRegistry.value = false
-      deleteRegistryTarget.value = null
-      await loadRegistries()
-      showToast(`Removed registry "${target.name || target.id}".`)
-      return
-    }
-
-    deleteRegistryError.value = registryErrorMessage(result.code, result.error, 'Removing')
-  } catch (err) {
-    deleteRegistryError.value = 'Failed to remove registry: ' + (err as Error).message
-  } finally {
-    deletingRegistry.value = false
-  }
-}
-
-function copyToClipboard(text: string) {
-  navigator.clipboard.writeText(text)
-  showToast('Installation command copied to clipboard!')
-}
-
-function openURL(url: string) {
-  window.open(url, '_blank')
-}
-
-function showToast(message: string) {
-  successMessage.value = message
-  showSuccessToast.value = true
-  setTimeout(() => {
-    showSuccessToast.value = false
-  }, 3000)
-}
-
-// Lifecycle
-onMounted(() => {
-  loadRegistries()
-})
-</script>
diff --git a/frontend/src/views/ServerDetail.vue b/frontend/src/views/ServerDetail.vue
index 4ce19ea20..bcd7dc31a 100644
--- a/frontend/src/views/ServerDetail.vue
+++ b/frontend/src/views/ServerDetail.vue
@@ -1638,6 +1638,7 @@ import type { Server, Tool, ToolApproval, SecurityScanReport } from '@/types'
 import api from '@/services/api'
 import { useSecurityScannerStatus } from '@/composables/useSecurityScannerStatus'
 import { serverDisplayName, scanReportPath } from '@/utils/serverRoute'
+import { refName } from '@/utils/secretRef'
 import { isTerminalScanStatus, decideScanReconcile, finalizeToastKind } from '@/utils/scanState'
 import { selectQuarantinedTools } from '@/utils/toolQuarantine'
 import { oauthSignInState } from '@/utils/health'
@@ -3572,17 +3573,13 @@ async function commitNewEnv() {
   if (ok) addingEnv.value = false
 }
 
-// Suggest a keyring secret name derived from the kv key. Keep it short,
-// lowercase, alphanumeric + hyphens — the same convention as the existing
-// Secrets view.
+// Suggest a keyring secret name derived from the kv key (FR-065): the shared
+// helper (also used by Paste/Manual/Catalog secret toggles) keeps the field
+// KIND (env vs header) in the name, so a header and an env var with the same
+// key never collide on one keyring entry — the bug this used to have before
+// it was switched to refName.
 function suggestSecretName(scope: 'header' | 'env', k: string): string {
-  const base = `${server.value?.name || 'server'}-${k}`
-  return base
-    .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-|-$/g, '')
-    .slice(0, 64)
+  return refName(server.value?.name || 'server', scope, k)
 }
 
 function openConvertModal(scope: 'header' | 'env', k: string, rawValue: string) {
diff --git a/frontend/src/views/Settings.vue b/frontend/src/views/Settings.vue
index 8e9c45ce0..a6560cfd7 100644
--- a/frontend/src/views/Settings.vue
+++ b/frontend/src/views/Settings.vue
@@ -95,6 +95,13 @@
         </div>
       </div>
 
+      <!-- Catalog sources (Spec 109 FR-062, moved from the retired Repositories.vue) -->
+      <div v-show="activeTab === 'catalog'" class="card bg-base-100 shadow-md">
+        <div class="card-body">
+          <CatalogSourcesSettings />
+        </div>
+      </div>
+
       <!-- Advanced -->
       <div v-show="activeTab === 'advanced'" class="space-y-3">
         <details v-for="acc in advancedAccordions" :key="acc.id" class="collapse collapse-arrow bg-base-100 shadow-md">
@@ -184,6 +191,7 @@ import CollapsibleHintsPanel from '@/components/CollapsibleHintsPanel.vue'
 import type { Hint } from '@/components/CollapsibleHintsPanel.vue'
 import ConnectModal from '@/components/ConnectModal.vue'
 import SettingsSection from '@/components/settings/SettingsSection.vue'
+import CatalogSourcesSettings from '@/components/CatalogSourcesSettings.vue'
 import {
   SECURITY_FIELDS,
   GENERAL_FIELDS,
@@ -340,6 +348,11 @@ const IconWrench = makeTabIcon(
 const IconUsers = makeTabIcon(
   'M17 20v-2a4 4 0 00-3-3.87M9 20v-2a4 4 0 013-3.87m0-4.13a4 4 0 100-8 4 4 0 000 8zm8 4v-2a4 4 0 00-3-3.85m-1-4.15a4 4 0 010 7.75'
 )
+// Spec 109 FR-062: catalog-source management moved here from the retired
+// Repositories.vue.
+const IconCatalog = makeTabIcon(
+  'M4 6a2 2 0 012-2h3l2 2h7a2 2 0 012 2v8a2 2 0 01-2 2H6a2 2 0 01-2-2V6z'
+)
 const IconBraces = makeTabIcon(
   'M8 4c-2 0-3 1-3 3v3c0 1-1 2-2 2 1 0 2 1 2 2v3c0 2 1 3 3 3m8-16c2 0 3 1 3 3v3c0 1 1 2 2 2-1 0-2 1-2 2v3c0 2-1 3-3 3'
 )
@@ -348,6 +361,7 @@ const tabs = computed(() => {
   const base = [
     { id: 'security', label: 'Security & Access', icon: IconLock },
     { id: 'general', label: 'General', icon: IconGear },
+    { id: 'catalog', label: 'Catalog sources', icon: IconCatalog },
     { id: 'advanced', label: 'Advanced', icon: IconWrench },
   ] as Array<{ id: string; label: string; icon: FunctionalComponent }>
   if (hasServerEdition.value) base.push({ id: 'teams', label: SERVER_EDITION_TAB_LABEL, icon: IconUsers })
diff --git a/frontend/tests/unit/add-server-catalog.spec.ts b/frontend/tests/unit/add-server-catalog.spec.ts
new file mode 100644
index 000000000..ef73207a1
--- /dev/null
+++ b/frontend/tests/unit/add-server-catalog.spec.ts
@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createRouter, createWebHistory } from 'vue-router'
+import CatalogSearch from '@/components/CatalogSearch.vue'
+
+vi.mock('@/services/api', () => ({
+  default: {
+    catalogSearch: vi.fn(),
+    getConfigSecrets: vi.fn(),
+    addServerFromRegistry: vi.fn(),
+    getSecretRefs: vi.fn(),
+    setSecret: vi.fn(),
+  },
+}))
+import api from '@/services/api'
+
+const router = createRouter({ history: createWebHistory(), routes: [{ path: '/', component: { template: '<div/>' } }, { path: '/servers/:serverName', component: { template: '<div/>' } }] })
+
+function githubResult(overrides: Partial<Record<string, unknown>> = {}) {
+  return {
+    source: 'official',
+    id: 'io.github.github/github-mcp-server',
+    title: 'GitHub',
+    publisher: 'github',
+    verified: true,
+    official: true,
+    description: 'Access GitHub from your MCP client. <img src=x onerror=alert(1)>',
+    transport: 'http',
+    install: { url: 'https://api.githubcopilot.com/mcp/' },
+    required_inputs: [],
+    added: false,
+    ...overrides,
+  }
+}
+
+async function mountCatalog() {
+  vi.mocked(api.getConfigSecrets).mockResolvedValue({
+    success: true,
+    data: { secrets: [], environment_vars: [], total_secrets: 0, total_env_vars: 0, keyring_available: true },
+  })
+  const wrapper = mount(CatalogSearch, { global: { plugins: [router] } })
+  await flushPromises()
+  return wrapper
+}
+
+describe('CatalogSearch', () => {
+  beforeEach(() => {
+    vi.mocked(api.catalogSearch).mockReset()
+    vi.mocked(api.getConfigSecrets).mockReset()
+    vi.mocked(api.addServerFromRegistry).mockReset()
+  })
+
+  it('defaults to the Catalog source (empty query) and renders sections', async () => {
+    vi.mocked(api.catalogSearch).mockResolvedValue({
+      success: true,
+      data: { query: '', results: [], sections: { official: [githubResult()], popular: [] }, unavailable: [] },
+    })
+    const wrapper = await mountCatalog()
+    expect(api.catalogSearch).toHaveBeenCalledWith(expect.objectContaining({ q: '' }))
+    expect(wrapper.find('[data-test="catalog-section-official"]').exists()).toBe(true)
+    expect(wrapper.text()).toContain('GitHub')
+    expect(wrapper.text()).toContain('io.github.github/github-mcp-server')
+  })
+
+  it('shows title/id/publisher and the "Add to MCPProxy" action, flipping to "Added ✓ · Open"', async () => {
+    vi.mocked(api.catalogSearch).mockResolvedValue({
+      success: true,
+      data: { query: '', results: [], sections: { official: [githubResult()], popular: [] }, unavailable: [] },
+    })
+    vi.mocked(api.addServerFromRegistry).mockResolvedValue({ success: true, server: { name: 'github' } as never })
+    const wrapper = await mountCatalog()
+
+    const button = wrapper.find('[data-test="catalog-add-official-io.github.github/github-mcp-server"]')
+    expect(button.text()).toBe('Add to MCPProxy')
+    await button.trigger('click')
+    await flushPromises()
+
+    const updated = wrapper.find('[data-test="catalog-add-official-io.github.github/github-mcp-server"]')
+    expect(updated.text()).toContain('Added ✓')
+  })
+
+  it('renders a description containing <img onerror> and markdown INERT — no element is created (D19)', async () => {
+    vi.mocked(api.catalogSearch).mockResolvedValue({
+      success: true,
+      data: {
+        query: '',
+        results: [],
+        sections: {
+          official: [githubResult({ description: '<img src=x onerror="window.__pwned = true">[click me](javascript:alert(1))' })],
+          popular: [],
+        },
+        unavailable: [],
+      },
+    })
+    const wrapper = await mountCatalog()
+    expect(wrapper.find('img').exists()).toBe(false)
+    expect((window as unknown as { __pwned?: boolean }).__pwned).toBeUndefined()
+    expect(wrapper.find('a').exists()).toBe(false)
+    expect(wrapper.text()).toContain('<img src=x onerror=')
+  })
+
+  it('surfaces unavailable sources without failing the whole search', async () => {
+    vi.mocked(api.catalogSearch).mockResolvedValue({
+      success: true,
+      data: { query: 'x', results: [githubResult()], sections: null, unavailable: [{ source: 'smithery', reason: 'timeout after 5s' }] },
+    })
+    const wrapper = await mountCatalog()
+    await wrapper.find('[data-test="catalog-search-input"]').setValue('x')
+    await new Promise((r) => setTimeout(r, 300))
+    await flushPromises()
+    expect(wrapper.find('[data-test="catalog-unavailable-notice"]').text()).toContain('smithery')
+  })
+})
diff --git a/frontend/tests/unit/add-server-paste.spec.ts b/frontend/tests/unit/add-server-paste.spec.ts
new file mode 100644
index 000000000..94395437c
--- /dev/null
+++ b/frontend/tests/unit/add-server-paste.spec.ts
@@ -0,0 +1,134 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createWebHistory } from 'vue-router'
+import PasteServer from '@/components/PasteServer.vue'
+
+vi.mock('@/services/api', () => ({
+  default: {
+    importServersFromJSON: vi.fn(),
+    getConfigSecrets: vi.fn(),
+    getSecretRefs: vi.fn(),
+    setSecret: vi.fn(),
+    callTool: vi.fn(),
+  },
+}))
+import api from '@/services/api'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: '/', component: { template: '<div/>' } },
+    { path: '/servers/:serverName', component: { template: '<div/>' } },
+  ],
+})
+
+async function mountPaste() {
+  setActivePinia(createPinia())
+  vi.mocked(api.getConfigSecrets).mockResolvedValue({
+    success: true,
+    data: { secrets: [], environment_vars: [], total_secrets: 0, total_env_vars: 0, keyring_available: true },
+  })
+  const wrapper = mount(PasteServer, { global: { plugins: [router] } })
+  await flushPromises()
+  return wrapper
+}
+
+describe('PasteServer', () => {
+  beforeEach(() => {
+    vi.mocked(api.importServersFromJSON).mockReset()
+    vi.mocked(api.getConfigSecrets).mockReset()
+    vi.mocked(api.callTool).mockReset()
+  })
+
+  it('detects a pasted URL and shows a preview before adding anything', async () => {
+    vi.mocked(api.importServersFromJSON).mockResolvedValue({
+      success: true,
+      data: {
+        format: 'url',
+        format_name: 'URL',
+        summary: { total: 1, imported: 1, skipped: 0, failed: 0 },
+        imported: [{ name: 'api', protocol: 'http', url: 'https://api.example.com/mcp', source_format: 'url', original_name: 'api', summary: 'https://api.example.com/mcp', tags: ['remote'] }],
+        skipped: [],
+        failed: [],
+        warnings: [],
+      },
+    })
+    const wrapper = await mountPaste()
+    await wrapper.find('[data-test="paste-textarea"]').setValue('https://api.example.com/mcp')
+    await new Promise((r) => setTimeout(r, 450))
+    await flushPromises()
+
+    expect(api.importServersFromJSON).toHaveBeenCalledWith({ content: 'https://api.example.com/mcp', preview: true })
+    expect(api.callTool).not.toHaveBeenCalled()
+    expect(wrapper.find('[data-test="paste-format"]').text()).toBe('Remote URL')
+    expect(wrapper.find('[data-test="paste-tag-remote"]').exists()).toBe(true)
+  })
+
+  it('detects a pasted command line and preview never executes anything', async () => {
+    vi.mocked(api.importServersFromJSON).mockResolvedValue({
+      success: true,
+      data: {
+        format: 'command',
+        format_name: 'Command Line',
+        summary: { total: 1, imported: 1, skipped: 0, failed: 0 },
+        imported: [{
+          name: 'server-filesystem', protocol: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+          source_format: 'command', original_name: 'server-filesystem',
+          summary: 'npx -y @modelcontextprotocol/server-filesystem /tmp', tags: ['local process'],
+        }],
+        skipped: [],
+        failed: [],
+        warnings: [],
+      },
+    })
+    const wrapper = await mountPaste()
+    await wrapper.find('[data-test="paste-textarea"]').setValue('npx -y @modelcontextprotocol/server-filesystem /tmp')
+    await new Promise((r) => setTimeout(r, 450))
+    await flushPromises()
+
+    expect(wrapper.find('[data-test="paste-tag-local process"]').exists()).toBe(true)
+    expect(wrapper.find('[data-test="paste-summary"]').text()).toBe('npx -y @modelcontextprotocol/server-filesystem /tmp')
+    // Preview only — the add button hasn't been clicked, so nothing was added.
+    expect(api.callTool).not.toHaveBeenCalled()
+  })
+
+  it('shows a secret toggle for a detected env var and commits it through Add', async () => {
+    vi.mocked(api.importServersFromJSON).mockResolvedValue({
+      success: true,
+      data: {
+        format: 'command',
+        format_name: 'Command Line',
+        summary: { total: 1, imported: 1, skipped: 0, failed: 0 },
+        imported: [{
+          name: 'github', protocol: 'stdio', command: 'uvx', args: ['mcp-server-github'],
+          source_format: 'command', original_name: 'github',
+          summary: 'uvx mcp-server-github', tags: ['local process', 'needs secret'],
+          env: [{ name: 'GITHUB_TOKEN', value_present: true, secret_like: true, empty_or_placeholder: false }],
+        }],
+        skipped: [],
+        failed: [],
+        warnings: [],
+      },
+    })
+    vi.mocked(api.getSecretRefs).mockResolvedValue({ success: true, data: { refs: [] } })
+    vi.mocked(api.setSecret).mockResolvedValue({ success: true, data: { message: '', name: '', type: '', reference: '' } })
+    vi.mocked(api.callTool).mockResolvedValue({ success: true, data: {} })
+
+    const wrapper = await mountPaste()
+    await wrapper.find('[data-test="paste-textarea"]').setValue('uvx mcp-server-github')
+    await new Promise((r) => setTimeout(r, 450))
+    await flushPromises()
+
+    expect(wrapper.find('[data-test="secret-toggle-env-GITHUB_TOKEN"]').exists()).toBe(true)
+    await wrapper.find('[data-test="secret-toggle-value-input"]').setValue('sk-live-abc123')
+    await wrapper.find('[data-test="paste-add-button"]').trigger('click')
+    await flushPromises()
+
+    expect(api.setSecret).toHaveBeenCalledWith('github-env-github-token', 'sk-live-abc123')
+    expect(api.callTool).toHaveBeenCalledWith(
+      'upstream_servers',
+      expect.objectContaining({ env_json: JSON.stringify({ GITHUB_TOKEN: '${keyring:github-env-github-token}' }) })
+    )
+  })
+})
diff --git a/frontend/tests/unit/add-server-tab-url.spec.ts b/frontend/tests/unit/add-server-tab-url.spec.ts
new file mode 100644
index 000000000..0b4be34ae
--- /dev/null
+++ b/frontend/tests/unit/add-server-tab-url.spec.ts
@@ -0,0 +1,67 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createWebHistory } from 'vue-router'
+import AddServer from '@/views/AddServer.vue'
+
+vi.mock('@/services/api', () => ({
+  default: {
+    catalogSearch: vi.fn().mockResolvedValue({ success: true, data: { query: '', results: [], sections: { official: [], popular: [] }, unavailable: [] } }),
+    getConfigSecrets: vi.fn().mockResolvedValue({ success: true, data: { secrets: [], environment_vars: [], total_secrets: 0, total_env_vars: 0, keyring_available: true } }),
+    getCanonicalConfigPaths: vi.fn().mockResolvedValue({ success: true, data: { os: 'darwin', paths: [] } }),
+    addServerFromRegistry: vi.fn(),
+  },
+}))
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [{ path: '/add-server', name: 'add-server', component: AddServer }],
+})
+
+async function mountAtTab(tab?: string, extraQuery = '') {
+  setActivePinia(createPinia())
+  await router.push(`/add-server${tab ? `?tab=${tab}${extraQuery}` : extraQuery ? `?${extraQuery.slice(1)}` : ''}`)
+  await router.isReady()
+  const wrapper = mount(AddServer, { global: { plugins: [router] } })
+  await flushPromises()
+  return wrapper
+}
+
+describe('AddServer tab <-> URL sync (Spec 109 FR-062)', () => {
+  it('defaults to the Catalog tab when ?tab= is absent', async () => {
+    const wrapper = await mountAtTab()
+    expect(wrapper.find('[data-test="add-server-tab-catalog"]').classes()).toContain('tab-active')
+    expect(wrapper.find('[data-test="catalog-search"]').exists()).toBe(true)
+  })
+
+  it('reads ?tab=paste on mount', async () => {
+    const wrapper = await mountAtTab('paste')
+    expect(wrapper.find('[data-test="add-server-tab-paste"]').classes()).toContain('tab-active')
+    expect(wrapper.find('[data-test="paste-server"]').exists()).toBe(true)
+  })
+
+  it('reads ?tab=import on mount', async () => {
+    const wrapper = await mountAtTab('import')
+    expect(wrapper.find('[data-test="import-servers-panel"]').exists()).toBe(true)
+  })
+
+  it('reads ?tab=manual on mount', async () => {
+    const wrapper = await mountAtTab('manual')
+    expect(wrapper.find('[data-test="manual-server-form"]').exists()).toBe(true)
+  })
+
+  it('writes the tab to the URL with router.replace when clicked, keeping other params', async () => {
+    const wrapper = await mountAtTab('catalog', '&source=official')
+    await wrapper.find('[data-test="add-server-tab-manual"]').trigger('click')
+    await flushPromises()
+    expect(router.currentRoute.value.query.tab).toBe('manual')
+    expect(router.currentRoute.value.query.source).toBe('official')
+  })
+
+  it('?source= narrows the Catalog tab only, never selects a tab', async () => {
+    const wrapper = await mountAtTab(undefined, '?source=official')
+    // Still defaults to Catalog even though only ?source= was set — source
+    // never implies a tab.
+    expect(wrapper.find('[data-test="add-server-tab-catalog"]').classes()).toContain('tab-active')
+  })
+})
diff --git a/frontend/tests/unit/add-to-mcpproxy-label.spec.ts b/frontend/tests/unit/add-to-mcpproxy-label.spec.ts
deleted file mode 100644
index 0196fe07e..000000000
--- a/frontend/tests/unit/add-to-mcpproxy-label.spec.ts
+++ /dev/null
@@ -1,121 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest'
-import { mount, flushPromises } from '@vue/test-utils'
-import { createPinia, setActivePinia } from 'pinia'
-import { createRouter, createMemoryHistory } from 'vue-router'
-import Repositories from '@/views/Repositories.vue'
-import api from '@/services/api'
-
-// Spec 109 FR-063: the add action reads "Add to MCPProxy" (Web/macOS; CLI
-// prints "Added <name> to MCPProxy (quarantined for review)"), and after a
-// successful add the same control becomes "Added ✓ · Open".
-
-vi.mock('@/services/api', () => ({
-  default: {
-    listRegistries: vi.fn(),
-    searchRegistryServers: vi.fn(),
-    addRegistrySource: vi.fn(),
-    editRegistrySource: vi.fn(),
-    removeRegistrySource: vi.fn(),
-    addServerFromRegistry: vi.fn(),
-  },
-}))
-
-const globalStubs = { CollapsibleHintsPanel: { template: '<div />' } }
-
-const officialRegistry = {
-  id: 'official',
-  name: 'Official MCP Registry',
-  description: 'The official registry',
-  url: 'https://registry.modelcontextprotocol.io/',
-  provenance: 'official',
-  trusted: true,
-}
-
-function makeRouter() {
-  return createRouter({
-    history: createMemoryHistory(),
-    routes: [
-      { path: '/repositories', name: 'repositories', component: Repositories },
-      { path: '/servers/:serverName', name: 'server-detail', component: { template: '<div/>' } },
-    ],
-  })
-}
-
-async function mountView() {
-  const router = makeRouter()
-  router.push('/repositories')
-  await router.isReady()
-  const wrapper = mount(Repositories, {
-    global: { plugins: [createPinia(), router], stubs: globalStubs },
-  })
-  await flushPromises()
-  return { wrapper, router }
-}
-
-describe('Repositories "Add to MCPProxy" (Spec 109 FR-063)', () => {
-  beforeEach(() => {
-    setActivePinia(createPinia())
-    localStorage.clear()
-    ;(api.listRegistries as any).mockResolvedValue({
-      success: true,
-      data: { registries: [officialRegistry], total: 1 },
-    })
-    ;(api.searchRegistryServers as any).mockResolvedValue({
-      success: true,
-      data: {
-        registry_id: 'official',
-        servers: [{ id: 'gh-server', registry: 'official', name: 'github-server', description: 'GitHub tools' }],
-        total: 1,
-      },
-    })
-  })
-
-  async function searchAndGetAddButton(wrapper: Awaited<ReturnType<typeof mountView>>['wrapper']) {
-    await wrapper.find('[data-test="registry-card-official"]').trigger('click')
-    await flushPromises()
-    await wrapper.find('[data-test="registry-search-button"]').trigger('click')
-    await flushPromises()
-    return wrapper.find('[data-test="registry-add-gh-server"]')
-  }
-
-  it('reads "Add to MCPProxy" on the result button', async () => {
-    const { wrapper } = await mountView()
-    const button = await searchAndGetAddButton(wrapper)
-    expect(button.exists()).toBe(true)
-    expect(button.text()).toContain('Add to MCPProxy')
-    expect(button.text()).not.toBe('Add to MCP')
-  })
-
-  it('flips to "Added ✓ · Open" after a successful add', async () => {
-    ;(api.addServerFromRegistry as any).mockResolvedValue({
-      success: true,
-      server: { name: 'github-server' },
-    })
-    const { wrapper } = await mountView()
-    const button = await searchAndGetAddButton(wrapper)
-
-    await button.trigger('click')
-    await flushPromises()
-
-    expect(wrapper.find('[data-test="registry-add-gh-server"]').exists()).toBe(false)
-    const added = wrapper.find('[data-test="registry-added-gh-server"]')
-    expect(added.exists()).toBe(true)
-    expect(added.text()).toContain('Added ✓ · Open')
-  })
-
-  it('opens the added server on click', async () => {
-    ;(api.addServerFromRegistry as any).mockResolvedValue({
-      success: true,
-      server: { name: 'github-server' },
-    })
-    const { wrapper, router } = await mountView()
-    const button = await searchAndGetAddButton(wrapper)
-    await button.trigger('click')
-    await flushPromises()
-
-    await wrapper.find('[data-test="registry-added-gh-server"]').trigger('click')
-    await flushPromises()
-
-    expect(router.currentRoute.value.path).toBe('/servers/github-server')
-  })
-})
diff --git a/frontend/tests/unit/fixtures/ref_names.json b/frontend/tests/unit/fixtures/ref_names.json
new file mode 100644
index 000000000..29e3d0584
--- /dev/null
+++ b/frontend/tests/unit/fixtures/ref_names.json
@@ -0,0 +1,47 @@
+{
+  "description": "Shared FR-065 keyring ref-name fixture, decoded by Go (internal/secret/refname_test.go), vitest (frontend/tests/unit/secret-ref.spec.ts) and Swift (MCPProxyTests/CatalogTests.swift). Each case computes RefName(server, kind, key, taken) and must equal want.",
+  "cases": [
+    {
+      "server": "github",
+      "kind": "env",
+      "key": "API_KEY",
+      "taken": [],
+      "want": "github-env-api-key"
+    },
+    {
+      "server": "github",
+      "kind": "header",
+      "key": "API_KEY",
+      "taken": [],
+      "want": "github-header-api-key"
+    },
+    {
+      "server": "github",
+      "kind": "env",
+      "key": "GITHUB_TOKEN",
+      "taken": [],
+      "want": "github-env-github-token"
+    },
+    {
+      "server": "My Server!",
+      "kind": "env",
+      "key": "GITHUB_TOKEN",
+      "taken": [],
+      "want": "my-server-env-github-token"
+    },
+    {
+      "server": "github",
+      "kind": "env",
+      "key": "API_KEY",
+      "taken": ["github-env-api-key"],
+      "want": "github-env-api-key-2"
+    },
+    {
+      "server": "github",
+      "kind": "env",
+      "key": "API_KEY",
+      "taken": ["github-env-api-key", "github-env-api-key-2"],
+      "want": "github-env-api-key-3"
+    }
+  ]
+}
diff --git a/frontend/tests/unit/repositories-add-registry.spec.ts b/frontend/tests/unit/repositories-add-registry.spec.ts
deleted file mode 100644
index 60e7b16f2..000000000
--- a/frontend/tests/unit/repositories-add-registry.spec.ts
+++ /dev/null
@@ -1,149 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest'
-import { mount, flushPromises } from '@vue/test-utils'
-import { createPinia, setActivePinia } from 'pinia'
-import Repositories from '@/views/Repositories.vue'
-import api from '@/services/api'
-
-// MCP-867 + MCP-1073: the Repositories view exposes an add-registry affordance
-// and surfaces provenance neutrally. MCP-1073 removed the alarming one-time
-// third-party warning gate and the "always quarantined" copy — adding a custom
-// source now goes straight through, and trust is surfaced as a neutral
-// Official/Custom badge.
-
-vi.mock('@/services/api', () => ({
-  default: {
-    listRegistries: vi.fn(),
-    searchRegistryServers: vi.fn(),
-    addRegistrySource: vi.fn(),
-    editRegistrySource: vi.fn(),
-    removeRegistrySource: vi.fn(),
-    addServerFromRegistry: vi.fn(),
-  },
-}))
-
-// Stub the hints child so we don't drag its dependencies into the mount.
-const globalStubs = {
-  CollapsibleHintsPanel: { template: '<div />' },
-}
-
-function mountView() {
-  return mount(Repositories, {
-    global: { plugins: [createPinia()], stubs: globalStubs },
-  })
-}
-
-const officialRegistry = {
-  id: 'official',
-  name: 'Official MCP Registry',
-  description: 'The official registry',
-  url: 'https://registry.modelcontextprotocol.io/',
-  provenance: 'official',
-  trusted: true,
-}
-
-const customRegistry = {
-  id: 'acme',
-  name: 'Acme Registry',
-  description: 'A custom source',
-  url: 'https://acme.example/registry',
-  provenance: 'custom',
-  trusted: false,
-}
-
-describe('Repositories — add registry + neutral provenance (MCP-867/MCP-1073)', () => {
-  beforeEach(() => {
-    setActivePinia(createPinia())
-    localStorage.clear()
-    ;(api.listRegistries as any).mockResolvedValue({
-      success: true,
-      data: { registries: [officialRegistry, customRegistry], total: 2 },
-    })
-    ;(api.searchRegistryServers as any).mockResolvedValue({
-      success: true,
-      data: { registry_id: 'official', servers: [], total: 0 },
-    })
-    ;(api.addRegistrySource as any).mockReset()
-  })
-
-  it('renders an Add Registry affordance', async () => {
-    const wrapper = mountView()
-    await flushPromises()
-    expect(wrapper.find('[data-test="registry-add-source-button"]').exists()).toBe(true)
-  })
-
-  it('surfaces trust neutrally: custom flagged "custom" in the multiselect, official without it; no alarming banner', async () => {
-    const wrapper = mountView()
-    await flushPromises()
-
-    const acmeOpt = wrapper.find('[data-test="registry-option-acme"]')
-    const officialOpt = wrapper.find('[data-test="registry-option-official"]')
-    expect(acmeOpt.exists()).toBe(true)
-    expect(officialOpt.exists()).toBe(true)
-    expect((acmeOpt.element as HTMLElement).closest('label')?.textContent).toContain('custom')
-    expect((officialOpt.element as HTMLElement).closest('label')?.textContent).not.toContain('custom')
-
-    // No alarming copy anywhere, and the old warning gate is gone.
-    expect(wrapper.find('[data-test="registry-third-party-warning"]').exists()).toBe(false)
-    expect(wrapper.html().toLowerCase()).not.toContain('unverified')
-    expect(wrapper.html().toLowerCase()).not.toContain('always quarantined')
-  })
-
-  it('multiselect: toggling a registry searches it; selecting a second searches across both (R1)', async () => {
-    const wrapper = mountView()
-    await flushPromises()
-    ;(api.searchRegistryServers as any).mockClear()
-
-    await wrapper.find('[data-test="registry-option-official"]').setValue(true)
-    await flushPromises()
-    await wrapper.find('[data-test="registry-option-acme"]').setValue(true)
-    await flushPromises()
-
-    const searched = (api.searchRegistryServers as any).mock.calls.map((c: any[]) => c[0])
-    expect(searched).toContain('official')
-    expect(searched).toContain('acme')
-  })
-
-  it('adds a custom source directly — no warning gate, no acknowledgement persisted', async () => {
-    ;(api.addRegistrySource as any).mockResolvedValue({
-      success: true,
-      registry: { id: 'acme', name: 'Acme Registry', provenance: 'custom', trusted: false },
-    })
-
-    const wrapper = mountView()
-    await flushPromises()
-
-    await wrapper.find('[data-test="registry-add-source-button"]').trigger('click')
-    await wrapper.find('[data-test="registry-add-url-input"]').setValue('https://acme.example/registry')
-    await wrapper.find('[data-test="registry-add-form"]').trigger('submit')
-    await flushPromises()
-
-    // The add goes straight through; no warning dialog, no localStorage ack.
-    expect(api.addRegistrySource).toHaveBeenCalledTimes(1)
-    expect(api.addRegistrySource).toHaveBeenCalledWith('https://acme.example/registry', {
-      protocol: 'modelcontextprotocol/registry',
-      name: undefined,
-    })
-    expect(localStorage.getItem('mcpproxy-thirdparty-registry-ack')).toBe(null)
-    expect(wrapper.find('[data-test="registry-third-party-warning"]').exists()).toBe(false)
-  })
-
-  it('surfaces a friendly message for a locked-registries error', async () => {
-    ;(api.addRegistrySource as any).mockResolvedValue({
-      success: false,
-      code: 'registries_locked',
-      error: 'locked',
-    })
-
-    const wrapper = mountView()
-    await flushPromises()
-
-    await wrapper.find('[data-test="registry-add-source-button"]').trigger('click')
-    await wrapper.find('[data-test="registry-add-url-input"]').setValue('https://acme.example/registry')
-    await wrapper.find('[data-test="registry-add-form"]').trigger('submit')
-    await flushPromises()
-
-    const err = wrapper.find('[data-test="registry-add-error"]')
-    expect(err.exists()).toBe(true)
-    expect(err.text().toLowerCase()).toContain('locked')
-  })
-})
diff --git a/frontend/tests/unit/repositories-card-selector.spec.ts b/frontend/tests/unit/repositories-card-selector.spec.ts
deleted file mode 100644
index 101a10797..000000000
--- a/frontend/tests/unit/repositories-card-selector.spec.ts
+++ /dev/null
@@ -1,125 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest'
-import { mount, flushPromises } from '@vue/test-utils'
-import { createPinia, setActivePinia } from 'pinia'
-import Repositories from '@/views/Repositories.vue'
-import api from '@/services/api'
-
-vi.mock('@/services/api', () => ({
-  default: {
-    listRegistries: vi.fn(),
-    searchRegistryServers: vi.fn(),
-    addRegistrySource: vi.fn(),
-    editRegistrySource: vi.fn(),
-    removeRegistrySource: vi.fn(),
-    addServerFromRegistry: vi.fn(),
-  },
-}))
-
-const globalStubs = { CollapsibleHintsPanel: { template: '<div />' } }
-
-function mountView() {
-  return mount(Repositories, { global: { plugins: [createPinia()], stubs: globalStubs } })
-}
-
-const officialRegistry = {
-  id: 'official',
-  name: 'Official MCP Registry',
-  description: 'The official registry',
-  url: 'https://registry.modelcontextprotocol.io/',
-  provenance: 'official',
-  trusted: true,
-}
-
-const customRegistry = {
-  id: 'acme',
-  name: 'Acme Registry',
-  description: 'A custom source',
-  url: 'https://acme.example/registry',
-  servers_url: 'https://acme.example/registry/v0.1/servers',
-  provenance: 'custom',
-  trusted: false,
-}
-
-/**
- * Audit F17: three prominent registry cards sat directly above a "Choose
- * registries…" dropdown and a disabled search box, while the body said "Select a
- * Registry". The cards looked exactly like the selector and were not clickable —
- * a false affordance. They are the selector now.
- */
-describe('Repositories — registry cards are the selector (audit F17)', () => {
-  beforeEach(() => {
-    setActivePinia(createPinia())
-    localStorage.clear()
-    ;(api.listRegistries as any).mockResolvedValue({
-      success: true,
-      data: { registries: [officialRegistry, customRegistry], total: 2 },
-    })
-    ;(api.searchRegistryServers as any).mockResolvedValue({
-      success: true,
-      data: { registry_id: 'official', servers: [], total: 0 },
-    })
-  })
-
-  it('starts with nothing selected and says how to enable search', async () => {
-    const wrapper = mountView()
-    await flushPromises()
-
-    const card = wrapper.find('[data-test="registry-card-official"]')
-    expect(card.attributes('aria-pressed')).toBe('false')
-    expect(card.attributes('role')).toBe('button')
-
-    expect(wrapper.find('[data-test="registry-search-input"]').attributes('disabled')).toBeDefined()
-    expect(wrapper.find('[data-test="registry-search-hint"]').text())
-      .toContain('Click a registry card above')
-  })
-
-  it('selects a registry when its card is clicked, and shows the selected state', async () => {
-    const wrapper = mountView()
-    await flushPromises()
-
-    await wrapper.find('[data-test="registry-card-official"]').trigger('click')
-    await flushPromises()
-
-    const card = wrapper.find('[data-test="registry-card-official"]')
-    expect(card.attributes('aria-pressed')).toBe('true')
-    expect(wrapper.find('[data-test="registry-card-selected-official"]').exists()).toBe(true)
-
-    // The search box and button come alive, and the hint retires.
-    expect(wrapper.find('[data-test="registry-search-input"]').attributes('disabled')).toBeUndefined()
-    expect(wrapper.find('[data-test="registry-search-button"]').attributes('disabled')).toBeUndefined()
-    expect(wrapper.find('[data-test="registry-search-hint"]').exists()).toBe(false)
-  })
-
-  it('is keyboard-operable', async () => {
-    const wrapper = mountView()
-    await flushPromises()
-
-    await wrapper.find('[data-test="registry-card-acme"]').trigger('keydown.enter')
-    await flushPromises()
-
-    expect(wrapper.find('[data-test="registry-card-acme"]').attributes('aria-pressed')).toBe('true')
-  })
-
-  it('toggles a selected card off again', async () => {
-    const wrapper = mountView()
-    await flushPromises()
-
-    await wrapper.find('[data-test="registry-card-official"]').trigger('click')
-    await flushPromises()
-    await wrapper.find('[data-test="registry-card-official"]').trigger('click')
-    await flushPromises()
-
-    expect(wrapper.find('[data-test="registry-card-official"]').attributes('aria-pressed')).toBe('false')
-  })
-
-  it('managing a custom source does not double as selecting it', async () => {
-    const wrapper = mountView()
-    await flushPromises()
-
-    // The kebab lives inside the card; its click must not reach the card.
-    await wrapper.find('[data-test="registry-kebab-acme"]').trigger('click')
-    await flushPromises()
-
-    expect(wrapper.find('[data-test="registry-card-acme"]').attributes('aria-pressed')).toBe('false')
-  })
-})
diff --git a/frontend/tests/unit/repositories-manage-registries.spec.ts b/frontend/tests/unit/repositories-manage-registries.spec.ts
deleted file mode 100644
index 52c4edf52..000000000
--- a/frontend/tests/unit/repositories-manage-registries.spec.ts
+++ /dev/null
@@ -1,168 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest'
-import { mount, flushPromises } from '@vue/test-utils'
-import { createPinia, setActivePinia } from 'pinia'
-import Repositories from '@/views/Repositories.vue'
-import api from '@/services/api'
-
-// MCP-1073: the Repositories view manages registry *sources* as cards.
-// - Custom registries get a kebab (⋮) menu with Edit + Delete.
-// - Official (built-in) registries are read-only: no kebab, a neutral
-//   "Built-in" tag, and a neutral Official/Custom badge (no alarming copy).
-// - Edit reuses the Add-Registry dialog, pre-filled, with a read-only id.
-// - Delete shows a destructive confirmation modal before calling the API.
-
-vi.mock('@/services/api', () => ({
-  default: {
-    listRegistries: vi.fn(),
-    searchRegistryServers: vi.fn(),
-    addRegistrySource: vi.fn(),
-    editRegistrySource: vi.fn(),
-    removeRegistrySource: vi.fn(),
-    addServerFromRegistry: vi.fn(),
-  },
-}))
-
-const globalStubs = {
-  CollapsibleHintsPanel: { template: '<div />' },
-}
-
-function mountView() {
-  return mount(Repositories, {
-    global: { plugins: [createPinia()], stubs: globalStubs },
-  })
-}
-
-const officialRegistry = {
-  id: 'official',
-  name: 'Official MCP Registry',
-  description: 'The official registry',
-  url: 'https://registry.modelcontextprotocol.io/',
-  provenance: 'official',
-  trusted: true,
-}
-
-const customRegistry = {
-  id: 'acme',
-  name: 'Acme Registry',
-  description: 'A custom source',
-  url: 'https://acme.example/registry',
-  servers_url: 'https://acme.example/registry/v0.1/servers',
-  provenance: 'custom',
-  trusted: false,
-}
-
-describe('Repositories — manage registry sources (MCP-1073)', () => {
-  beforeEach(() => {
-    setActivePinia(createPinia())
-    localStorage.clear()
-    ;(api.listRegistries as any).mockResolvedValue({
-      success: true,
-      data: { registries: [officialRegistry, customRegistry], total: 2 },
-    })
-    ;(api.searchRegistryServers as any).mockResolvedValue({
-      success: true,
-      data: { registry_id: 'official', servers: [], total: 0 },
-    })
-    ;(api.editRegistrySource as any).mockReset()
-    ;(api.removeRegistrySource as any).mockReset()
-  })
-
-  it('renders a manageable card per registry with a neutral Official/Custom badge', async () => {
-    const wrapper = mountView()
-    await flushPromises()
-
-    expect(wrapper.find('[data-test="registry-card-official"]').exists()).toBe(true)
-    expect(wrapper.find('[data-test="registry-card-acme"]').exists()).toBe(true)
-
-    // Neutral badge — no alarming words anywhere on the official card.
-    const officialCard = wrapper.find('[data-test="registry-card-official"]')
-    expect(officialCard.text()).toContain('Official')
-    expect(officialCard.text().toLowerCase()).not.toContain('quarantine')
-    expect(officialCard.text().toLowerCase()).not.toContain('unverified')
-
-    const customCard = wrapper.find('[data-test="registry-card-acme"]')
-    expect(customCard.text()).toContain('Custom')
-  })
-
-  it('shows no alarming warning banner or one-time third-party warning gate', async () => {
-    const wrapper = mountView()
-    await flushPromises()
-
-    // The old third-party warning dialog and custom-quarantine note are gone.
-    expect(wrapper.find('[data-test="registry-third-party-warning"]').exists()).toBe(false)
-    expect(wrapper.find('[data-test="registry-custom-quarantine-note"]').exists()).toBe(false)
-    expect(wrapper.html().toLowerCase()).not.toContain('always quarantined')
-    expect(wrapper.html().toLowerCase()).not.toContain('can never skip')
-  })
-
-  it('exposes a kebab Edit/Delete only on custom registries; official is read-only', async () => {
-    const wrapper = mountView()
-    await flushPromises()
-
-    expect(wrapper.find('[data-test="registry-kebab-acme"]').exists()).toBe(true)
-    expect(wrapper.find('[data-test="registry-edit-acme"]').exists()).toBe(true)
-    expect(wrapper.find('[data-test="registry-delete-acme"]').exists()).toBe(true)
-
-    // Official: no kebab, no edit/delete, has a "Built-in" tag.
-    expect(wrapper.find('[data-test="registry-kebab-official"]').exists()).toBe(false)
-    expect(wrapper.find('[data-test="registry-edit-official"]').exists()).toBe(false)
-    expect(wrapper.find('[data-test="registry-delete-official"]').exists()).toBe(false)
-    expect(wrapper.find('[data-test="registry-card-official"]').text()).toContain('Built-in')
-  })
-
-  it('Edit opens the dialog pre-filled with a read-only id and PUTs the changes', async () => {
-    ;(api.editRegistrySource as any).mockResolvedValue({
-      success: true,
-      registry: { id: 'acme', name: 'Acme Renamed', provenance: 'custom', trusted: false },
-    })
-
-    const wrapper = mountView()
-    await flushPromises()
-
-    await wrapper.find('[data-test="registry-edit-acme"]').trigger('click')
-    await flushPromises()
-
-    // Dialog open + pre-filled.
-    expect((wrapper.find('[data-test="registry-add-source-dialog"]').element as HTMLDialogElement).hasAttribute('open')).toBe(true)
-    const urlInput = wrapper.find('[data-test="registry-add-url-input"]').element as HTMLInputElement
-    const nameInput = wrapper.find('[data-test="registry-add-name-input"]').element as HTMLInputElement
-    expect(urlInput.value).toBe('https://acme.example/registry')
-    expect(nameInput.value).toBe('Acme Registry')
-
-    // The id is shown read-only in edit mode.
-    const idInput = wrapper.find('[data-test="registry-edit-id"]')
-    expect(idInput.exists()).toBe(true)
-    expect((idInput.element as HTMLInputElement).readOnly).toBe(true)
-
-    // Change the name and submit → PUT, not POST.
-    await wrapper.find('[data-test="registry-add-name-input"]').setValue('Acme Renamed')
-    await wrapper.find('[data-test="registry-add-form"]').trigger('submit')
-    await flushPromises()
-
-    expect(api.editRegistrySource).toHaveBeenCalledTimes(1)
-    expect(api.addRegistrySource).not.toHaveBeenCalled()
-    const [id, opts] = (api.editRegistrySource as any).mock.calls[0]
-    expect(id).toBe('acme')
-    expect(opts.name).toBe('Acme Renamed')
-  })
-
-  it('Delete shows a destructive confirmation modal and only calls the API on confirm', async () => {
-    ;(api.removeRegistrySource as any).mockResolvedValue({ success: true })
-
-    const wrapper = mountView()
-    await flushPromises()
-
-    await wrapper.find('[data-test="registry-delete-acme"]').trigger('click')
-    await flushPromises()
-
-    const confirm = wrapper.find('[data-test="registry-delete-dialog"]')
-    expect(confirm.exists()).toBe(true)
-    expect((confirm.element as HTMLDialogElement).hasAttribute('open')).toBe(true)
-    expect(api.removeRegistrySource).not.toHaveBeenCalled()
-
-    await wrapper.find('[data-test="registry-delete-confirm"]').trigger('click')
-    await flushPromises()
-
-    expect(api.removeRegistrySource).toHaveBeenCalledWith('acme')
-  })
-})
diff --git a/frontend/tests/unit/repositories-redirect.spec.ts b/frontend/tests/unit/repositories-redirect.spec.ts
new file mode 100644
index 000000000..6fa713d2d
--- /dev/null
+++ b/frontend/tests/unit/repositories-redirect.spec.ts
@@ -0,0 +1,35 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import appRouter from '@/router'
+
+// Spec 109 FR-062: /repositories redirects to /add-server?tab=catalog, and
+// /add-server is its own registered route (never the not-found catch-all).
+describe('/repositories redirect (Spec 109 FR-062)', () => {
+  beforeEach(() => {
+    // The app router's auth guard reaches for a store on every navigation.
+    setActivePinia(createPinia())
+  })
+
+  it('redirects to /add-server?tab=catalog', async () => {
+    await appRouter.push('/repositories')
+    await appRouter.isReady()
+    expect(appRouter.currentRoute.value.name).not.toBe('not-found')
+    expect(appRouter.currentRoute.value.path).toBe('/add-server')
+    expect(appRouter.currentRoute.value.query.tab).toBe('catalog')
+  })
+
+  it('preserves ?source= (the catalog-source filter) across the redirect', async () => {
+    await appRouter.push('/repositories?source=official')
+    await appRouter.isReady()
+    expect(appRouter.currentRoute.value.path).toBe('/add-server')
+    expect(appRouter.currentRoute.value.query.tab).toBe('catalog')
+    expect(appRouter.currentRoute.value.query.source).toBe('official')
+  })
+
+  it('registers /add-server as its own route', async () => {
+    await appRouter.push('/add-server?tab=paste')
+    await appRouter.isReady()
+    expect(appRouter.currentRoute.value.path).toBe('/add-server')
+    expect(appRouter.currentRoute.value.name).toBe('add-server')
+  })
+})
diff --git a/frontend/tests/unit/repositories-registry-dialog-escape-inflight.spec.ts b/frontend/tests/unit/repositories-registry-dialog-escape-inflight.spec.ts
deleted file mode 100644
index eae7d8ce4..000000000
--- a/frontend/tests/unit/repositories-registry-dialog-escape-inflight.spec.ts
+++ /dev/null
@@ -1,153 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest'
-import { mount, flushPromises } from '@vue/test-utils'
-import { createPinia, setActivePinia } from 'pinia'
-import Repositories from '@/views/Repositories.vue'
-import api from '@/services/api'
-
-// Spec 109 PR-a review round 2 (finding 1): closeAddRegistry()/closeDeleteRegistry()
-// each early-return while a submit is in flight, and the round-1 fix wired
-// these same functions as useDialogOpen's native-close (Escape) handler. A
-// real <dialog> already closes itself in the DOM on Escape regardless of any
-// guard in Vue-land, so skipping the state flip there just desyncs Vue's
-// `showAddRegistry`/`showDeleteRegistry` from the (already-closed) DOM —
-// bricking the dialog until reload, since the button that would reopen it
-// sets the ref to a value it already holds and the driving watch never fires.
-//
-// jsdom implements the `open` attribute but not showModal()/close(), so we
-// polyfill just enough of the native behaviour (same approach as
-// use-dialog-open-native-close.spec.ts) to exercise the real browser path.
-function polyfillNativeDialog(el: HTMLDialogElement) {
-  el.showModal = function (this: HTMLDialogElement) {
-    this.open = true
-  }
-  el.close = function (this: HTMLDialogElement) {
-    if (!this.open) return
-    this.open = false
-    this.dispatchEvent(new Event('close'))
-  }
-}
-
-vi.mock('@/services/api', () => ({
-  default: {
-    listRegistries: vi.fn(),
-    searchRegistryServers: vi.fn(),
-    addRegistrySource: vi.fn(),
-    editRegistrySource: vi.fn(),
-    removeRegistrySource: vi.fn(),
-    addServerFromRegistry: vi.fn(),
-  },
-}))
-
-const globalStubs = {
-  CollapsibleHintsPanel: { template: '<div />' },
-}
-
-function mountView() {
-  return mount(Repositories, {
-    global: { plugins: [createPinia()], stubs: globalStubs },
-    attachTo: document.body,
-  })
-}
-
-const officialRegistry = {
-  id: 'official',
-  name: 'Official MCP Registry',
-  description: 'The official registry',
-  url: 'https://registry.modelcontextprotocol.io/',
-  provenance: 'official',
-  trusted: true,
-}
-
-const customRegistry = {
-  id: 'acme',
-  name: 'Acme Registry',
-  description: 'A custom source',
-  url: 'https://acme.example/registry',
-  provenance: 'custom',
-  trusted: false,
-}
-
-describe('Repositories — Add/Delete registry dialog survives Escape mid-submit (round 2)', () => {
-  beforeEach(() => {
-    setActivePinia(createPinia())
-    localStorage.clear()
-    ;(api.listRegistries as any).mockResolvedValue({
-      success: true,
-      data: { registries: [officialRegistry, customRegistry], total: 2 },
-    })
-    ;(api.searchRegistryServers as any).mockResolvedValue({
-      success: true,
-      data: { registry_id: 'official', servers: [], total: 0 },
-    })
-    ;(api.addRegistrySource as any).mockReset()
-    ;(api.removeRegistrySource as any).mockReset()
-  })
-
-  it('reopens the Add Registry dialog after Escape closes it while the add is in flight', async () => {
-    let resolveAdd!: (v: any) => void
-    ;(api.addRegistrySource as any).mockImplementation(
-      () => new Promise((resolve) => { resolveAdd = resolve })
-    )
-
-    const wrapper = mountView()
-    await flushPromises()
-
-    const dialog = wrapper.find('[data-test="registry-add-source-dialog"]')
-    polyfillNativeDialog(dialog.element as HTMLDialogElement)
-
-    await wrapper.find('[data-test="registry-add-source-button"]').trigger('click')
-    await flushPromises()
-    expect((dialog.element as HTMLDialogElement).open).toBe(true)
-
-    await wrapper.find('[data-test="registry-add-url-input"]').setValue('https://acme.example/registry')
-    await wrapper.find('[data-test="registry-add-form"]').trigger('submit')
-    await flushPromises() // addingRegistry is now true; addRegistrySource is still pending
-
-    // The browser closes the dialog natively (Escape) while the submit is
-    // still in flight — this is not driven by any Vue click handler.
-    ;(dialog.element as HTMLDialogElement).close()
-    await flushPromises()
-
-    // Let the in-flight add finish (failure — the specific outcome doesn't
-    // matter, only that it resolves after the native close happened).
-    resolveAdd({ success: false, code: 'invalid_registry_url', error: 'bad url' })
-    await flushPromises()
-
-    // Reopening from the page's own trigger must work — the dialog must not
-    // stay bricked shut.
-    await wrapper.find('[data-test="registry-add-source-button"]').trigger('click')
-    await flushPromises()
-    expect((dialog.element as HTMLDialogElement).open).toBe(true)
-  })
-
-  it('reopens the Delete Registry confirm dialog after Escape closes it while the delete is in flight', async () => {
-    let resolveDelete!: (v: any) => void
-    ;(api.removeRegistrySource as any).mockImplementation(
-      () => new Promise((resolve) => { resolveDelete = resolve })
-    )
-
-    const wrapper = mountView()
-    await flushPromises()
-
-    const dialog = wrapper.find('[data-test="registry-delete-dialog"]')
-    polyfillNativeDialog(dialog.element as HTMLDialogElement)
-
-    await wrapper.find('[data-test="registry-delete-acme"]').trigger('click')
-    await flushPromises()
-    expect((dialog.element as HTMLDialogElement).open).toBe(true)
-
-    await wrapper.find('[data-test="registry-delete-confirm"]').trigger('click')
-    await flushPromises() // deletingRegistry is now true; removeRegistrySource is still pending
-
-    ;(dialog.element as HTMLDialogElement).close()
-    await flushPromises()
-
-    resolveDelete({ success: false, error: 'boom' })
-    await flushPromises()
-
-    // The dialog must be reopenable again afterwards (e.g. the user retries).
-    await wrapper.find('[data-test="registry-delete-acme"]').trigger('click')
-    await flushPromises()
-    expect((dialog.element as HTMLDialogElement).open).toBe(true)
-  })
-})
diff --git a/frontend/tests/unit/secret-ref.spec.ts b/frontend/tests/unit/secret-ref.spec.ts
new file mode 100644
index 000000000..5026a4070
--- /dev/null
+++ b/frontend/tests/unit/secret-ref.spec.ts
@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest'
+import { refName } from '@/utils/secretRef'
+import { looksSecret } from '@/utils/secretLike'
+import fixture from './fixtures/ref_names.json'
+
+describe('refName', () => {
+  it('computes <server>-<kind>-<key>, lowercased and normalized', () => {
+    expect(refName('github', 'env', 'API_KEY')).toBe('github-env-api-key')
+    expect(refName('github', 'header', 'API_KEY')).toBe('github-header-api-key')
+  })
+
+  it('gives an env var and a header of the same name distinct refs (FR-065)', () => {
+    const env = refName('github', 'env', 'API_KEY')
+    const header = refName('github', 'header', 'API_KEY')
+    expect(env).not.toBe(header)
+  })
+
+  it('appends -2, -3, ... on a taken name (D28: never overwrite)', () => {
+    const taken = new Set(['github-env-api-key', 'github-env-api-key-2'])
+    expect(refName('github', 'env', 'API_KEY', (n) => taken.has(n))).toBe('github-env-api-key-3')
+  })
+
+  it('caps the result at 64 characters even with a numeric suffix', () => {
+    const longKey = 'THIS_IS_A_VERY_VERY_VERY_VERY_VERY_VERY_VERY_LONG_ENV_VAR_NAME'
+    const got = refName('some-really-long-server-name', 'env', longKey, () => false)
+    expect(got.length).toBeLessThanOrEqual(64)
+  })
+
+  it('matches the shared fixture the Go and Swift ports also decode', () => {
+    type FixtureCase = { server: string; kind: 'env' | 'header'; key: string; taken: string[]; want: string }
+    const cases = (fixture as { cases: FixtureCase[] }).cases
+    expect(cases.length).toBeGreaterThan(0)
+    for (const c of cases) {
+      const takenSet = new Set(c.taken)
+      expect(refName(c.server, c.kind, c.key, (n) => takenSet.has(n))).toBe(c.want)
+    }
+  })
+})
+
+describe('looksSecret', () => {
+  it('flags conventional secret-ish names', () => {
+    for (const name of ['GITHUB_TOKEN', 'API_KEY', 'PASSWORD', 'Authorization', 'PRIVATE_KEY']) {
+      expect(looksSecret(name)).toBe(true)
+    }
+  })
+
+  it('does not flag ordinary config names', () => {
+    for (const name of ['PORT', 'WORKDIR', 'PATH', 'REGION']) {
+      expect(looksSecret(name)).toBe(false)
+    }
+  })
+})
diff --git a/frontend/tests/unit/secret-toggle.spec.ts b/frontend/tests/unit/secret-toggle.spec.ts
new file mode 100644
index 000000000..fb608d27b
--- /dev/null
+++ b/frontend/tests/unit/secret-toggle.spec.ts
@@ -0,0 +1,137 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount } from '@vue/test-utils'
+import SecretToggle from '@/components/SecretToggle.vue'
+import { resolveSecretFields, rollbackSecrets } from '@/composables/useSecretFields'
+
+vi.mock('@/services/api', () => ({
+  default: {
+    getSecretRefs: vi.fn(),
+    setSecret: vi.fn(),
+    deleteSecret: vi.fn(),
+  },
+}))
+import api from '@/services/api'
+
+function mountToggle(props: Partial<InstanceType<typeof SecretToggle>['$props']> = {}) {
+  return mount(SecretToggle, {
+    props: {
+      name: 'API_KEY',
+      kind: 'env',
+      modelValue: '',
+      mode: 'value',
+      keyringAvailable: true,
+      ...props,
+    },
+  })
+}
+
+describe('SecretToggle', () => {
+  it('renders Value and Secret mode buttons, and emits update:mode on click', async () => {
+    const wrapper = mountToggle({ mode: 'value' })
+    await wrapper.find('[data-test="secret-toggle-mode-secret"]').trigger('click')
+    expect(wrapper.emitted('update:mode')?.[0]).toEqual(['secret'])
+  })
+
+  it('emits update:modelValue on input', async () => {
+    const wrapper = mountToggle()
+    const input = wrapper.find('[data-test="secret-toggle-value-input"]')
+    await input.setValue('sk-live-abc123')
+    expect(wrapper.emitted('update:modelValue')?.[0]).toEqual(['sk-live-abc123'])
+  })
+
+  it('disables Secret mode when the keyring is unavailable, with the reason as a tooltip', () => {
+    const wrapper = mountToggle({ keyringAvailable: false, keyringReason: 'no display session' })
+    const btn = wrapper.find('[data-test="secret-toggle-mode-secret"]')
+    expect(btn.attributes('disabled')).toBeDefined()
+    expect(btn.attributes('title')).toContain('no display session')
+  })
+
+  it('does not emit update:mode when clicking Secret while the keyring is unavailable', async () => {
+    const wrapper = mountToggle({ keyringAvailable: false })
+    await wrapper.find('[data-test="secret-toggle-mode-secret"]').trigger('click')
+    expect(wrapper.emitted('update:mode')).toBeUndefined()
+  })
+
+  it('defaults to secret for a secret-like name, value otherwise (D13)', () => {
+    const secretLike = mountToggle({ name: 'GITHUB_TOKEN' })
+    expect((secretLike.vm as unknown as { defaultMode: () => string }).defaultMode()).toBe('secret')
+    const ordinary = mountToggle({ name: 'WORKDIR' })
+    expect((ordinary.vm as unknown as { defaultMode: () => string }).defaultMode()).toBe('value')
+  })
+})
+
+describe('resolveSecretFields', () => {
+  beforeEach(() => {
+    vi.mocked(api.getSecretRefs).mockReset()
+    vi.mocked(api.setSecret).mockReset()
+    vi.mocked(api.deleteSecret).mockReset()
+  })
+
+  it('passes value-mode fields through unchanged, never touching the keyring', async () => {
+    vi.mocked(api.getSecretRefs).mockResolvedValue({ success: true, data: { refs: [] } })
+    const result = await resolveSecretFields('github', [
+      { kind: 'env', name: 'WORKDIR', value: '/tmp', mode: 'value' },
+    ])
+    expect(result.env).toEqual({ WORKDIR: '/tmp' })
+    expect(api.setSecret).not.toHaveBeenCalled()
+  })
+
+  it('writes a secret-mode field to the keyring and references it with ${keyring:<ref>}', async () => {
+    vi.mocked(api.getSecretRefs).mockResolvedValue({ success: true, data: { refs: [] } })
+    vi.mocked(api.setSecret).mockResolvedValue({ success: true, data: { message: '', name: '', type: '', reference: '' } })
+    const result = await resolveSecretFields('github', [
+      { kind: 'env', name: 'GITHUB_TOKEN', value: 'sk-live-abc', mode: 'secret' },
+    ])
+    expect(api.setSecret).toHaveBeenCalledWith('github-env-github-token', 'sk-live-abc')
+    expect(result.env).toEqual({ GITHUB_TOKEN: '${keyring:github-env-github-token}' })
+    expect(result.writtenRefs).toEqual(['github-env-github-token'])
+  })
+
+  it('writes an env var and a header of the same name to two distinct refs', async () => {
+    vi.mocked(api.getSecretRefs).mockResolvedValue({ success: true, data: { refs: [] } })
+    vi.mocked(api.setSecret).mockResolvedValue({ success: true, data: { message: '', name: '', type: '', reference: '' } })
+    const result = await resolveSecretFields('github', [
+      { kind: 'env', name: 'API_KEY', value: 'env-value', mode: 'secret' },
+      { kind: 'header', name: 'API_KEY', value: 'header-value', mode: 'secret' },
+    ])
+    expect(result.env.API_KEY).toBe('${keyring:github-env-api-key}')
+    expect(result.headers.API_KEY).toBe('${keyring:github-header-api-key}')
+  })
+
+  it('gets a -2 suffix when GET /secrets/refs already carries the computed name', async () => {
+    vi.mocked(api.getSecretRefs).mockResolvedValue({
+      success: true,
+      data: { refs: [{ type: 'keyring', name: 'github-env-api-key', original: '' }] },
+    })
+    vi.mocked(api.setSecret).mockResolvedValue({ success: true, data: { message: '', name: '', type: '', reference: '' } })
+    const result = await resolveSecretFields('github', [
+      { kind: 'env', name: 'API_KEY', value: 'new-value', mode: 'secret' },
+    ])
+    expect(result.env.API_KEY).toBe('${keyring:github-env-api-key-2}')
+  })
+
+  it('rolls back only the secrets this call wrote when a later write fails', async () => {
+    vi.mocked(api.getSecretRefs).mockResolvedValue({ success: true, data: { refs: [] } })
+    vi.mocked(api.setSecret)
+      .mockResolvedValueOnce({ success: true, data: { message: '', name: '', type: '', reference: '' } })
+      .mockResolvedValueOnce({ success: false, error: 'keyring write failed' })
+    vi.mocked(api.deleteSecret).mockResolvedValue({ success: true, data: { message: '', name: '', type: '' } })
+
+    await expect(
+      resolveSecretFields('github', [
+        { kind: 'env', name: 'FIRST', value: 'a', mode: 'secret' },
+        { kind: 'env', name: 'SECOND', value: 'b', mode: 'secret' },
+      ])
+    ).rejects.toThrow()
+
+    expect(api.deleteSecret).toHaveBeenCalledTimes(1)
+    expect(api.deleteSecret).toHaveBeenCalledWith('github-env-first')
+  })
+
+  it('rollbackSecrets deletes exactly the given refs', async () => {
+    vi.mocked(api.deleteSecret).mockResolvedValue({ success: true, data: { message: '', name: '', type: '' } })
+    await rollbackSecrets(['a', 'b'])
+    expect(api.deleteSecret).toHaveBeenCalledWith('a')
+    expect(api.deleteSecret).toHaveBeenCalledWith('b')
+  })
+})
diff --git a/frontend/tests/unit/settings-catalog-sources.spec.ts b/frontend/tests/unit/settings-catalog-sources.spec.ts
new file mode 100644
index 000000000..0b2f70c5e
--- /dev/null
+++ b/frontend/tests/unit/settings-catalog-sources.spec.ts
@@ -0,0 +1,128 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia } from 'pinia'
+import CatalogSourcesSettings from '@/components/CatalogSourcesSettings.vue'
+import api from '@/services/api'
+
+// Spec 109 FR-062: catalog-source management moved from the retired
+// Repositories.vue into Settings → Catalog sources. This ports the essential
+// add/edit/delete coverage the old repositories-add-registry.spec.ts and
+// repositories-manage-registries.spec.ts pinned.
+
+vi.mock('@/services/api', () => ({
+  default: {
+    listRegistries: vi.fn(),
+    addRegistrySource: vi.fn(),
+    editRegistrySource: vi.fn(),
+    removeRegistrySource: vi.fn(),
+  },
+}))
+
+const officialRegistry = {
+  id: 'official',
+  name: 'Official MCP Registry',
+  url: 'https://registry.modelcontextprotocol.io/',
+  provenance: 'official',
+  trusted: true,
+}
+
+const customRegistry = {
+  id: 'my-custom',
+  name: 'My Custom Registry',
+  url: 'https://example.com/registry',
+  provenance: 'custom/unverified',
+  trusted: false,
+}
+
+function mountView() {
+  return mount(CatalogSourcesSettings, { global: { plugins: [createPinia()] } })
+}
+
+beforeEach(() => {
+  vi.mocked(api.listRegistries).mockReset()
+  vi.mocked(api.addRegistrySource).mockReset()
+  vi.mocked(api.editRegistrySource).mockReset()
+  vi.mocked(api.removeRegistrySource).mockReset()
+  vi.mocked(api.listRegistries).mockResolvedValue({
+    success: true,
+    data: { registries: [officialRegistry, customRegistry], total: 2 },
+  })
+})
+
+describe('CatalogSourcesSettings', () => {
+  it('lists registries with Official/Custom badges, and only custom ones get a kebab menu', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    expect(wrapper.find('[data-test="registry-provenance-official"]').text()).toBe('Official')
+    expect(wrapper.find('[data-test="registry-builtin-official"]').exists()).toBe(true)
+    expect(wrapper.find('[data-test="registry-kebab-official"]').exists()).toBe(false)
+
+    expect(wrapper.find('[data-test="registry-provenance-my-custom"]').text()).toBe('Custom')
+    expect(wrapper.find('[data-test="registry-kebab-my-custom"]').exists()).toBe(true)
+  })
+
+  it('adds a custom registry source', async () => {
+    vi.mocked(api.addRegistrySource).mockResolvedValue({ success: true, registry: { id: 'new-reg', name: 'New Registry' } })
+    const wrapper = mountView()
+    await flushPromises()
+
+    await wrapper.find('[data-test="registry-add-source-button"]').trigger('click')
+    await wrapper.find('[data-test="registry-add-url-input"]').setValue('https://new.example.com/')
+    await wrapper.find('[data-test="registry-add-form"]').trigger('submit')
+    await flushPromises()
+
+    expect(api.addRegistrySource).toHaveBeenCalledWith('https://new.example.com/', expect.objectContaining({}))
+    expect(wrapper.find('[data-test="registry-add-success"]').exists()).toBe(true)
+  })
+
+  it('shows the backend error message when adding fails', async () => {
+    vi.mocked(api.addRegistrySource).mockResolvedValue({ success: false, code: 'invalid_registry_url', error: 'nope' })
+    const wrapper = mountView()
+    await flushPromises()
+
+    await wrapper.find('[data-test="registry-add-source-button"]').trigger('click')
+    await wrapper.find('[data-test="registry-add-url-input"]').setValue('not-a-url')
+    await wrapper.find('[data-test="registry-add-form"]').trigger('submit')
+    await flushPromises()
+
+    expect(wrapper.find('[data-test="registry-add-error"]').exists()).toBe(true)
+  })
+
+  it('edits a custom registry via the kebab menu', async () => {
+    vi.mocked(api.editRegistrySource).mockResolvedValue({ success: true, registry: { id: 'my-custom', name: 'Renamed' } })
+    const wrapper = mountView()
+    await flushPromises()
+
+    await wrapper.find('[data-test="registry-edit-my-custom"]').trigger('click')
+    expect(wrapper.find('[data-test="registry-edit-id"]').element.getAttribute('value')).toBe('my-custom')
+    await wrapper.find('[data-test="registry-add-name-input"]').setValue('Renamed')
+    await wrapper.find('[data-test="registry-add-form"]').trigger('submit')
+    await flushPromises()
+
+    expect(api.editRegistrySource).toHaveBeenCalledWith('my-custom', expect.objectContaining({ name: 'Renamed' }))
+  })
+
+  it('deletes a custom registry after confirmation', async () => {
+    vi.mocked(api.removeRegistrySource).mockResolvedValue({ success: true })
+    const wrapper = mountView()
+    await flushPromises()
+
+    await wrapper.find('[data-test="registry-delete-my-custom"]').trigger('click')
+    await wrapper.find('[data-test="registry-delete-confirm"]').trigger('click')
+    await flushPromises()
+
+    expect(api.removeRegistrySource).toHaveBeenCalledWith('my-custom')
+  })
+
+  it('links to the Add Server page for browsing, since this tab only manages sources', async () => {
+    const wrapper = mount(CatalogSourcesSettings, {
+      global: {
+        plugins: [createPinia()],
+        stubs: { RouterLink: { template: '<a :href="to"><slot /></a>', props: ['to'] } },
+      },
+    })
+    await flushPromises()
+    expect(wrapper.find('a[href="/add-server"]').exists()).toBe(true)
+  })
+})
diff --git a/frontend/tests/unit/z-index-scale.spec.ts b/frontend/tests/unit/z-index-scale.spec.ts
index 3688d3275..30276add5 100644
--- a/frontend/tests/unit/z-index-scale.spec.ts
+++ b/frontend/tests/unit/z-index-scale.spec.ts
@@ -68,32 +68,46 @@ describe('SidebarNav no longer hardcodes a z-40 that can outrank a modal', () =>
   })
 })
 
-describe('Repositories.vue dialogs use showModal()/close(), not :open (FR-055)', () => {
-  const src = readSrc('../../src/views/Repositories.vue')
+// Spec 109 FR-062: the registry-source-management dialogs moved out of the
+// retired Repositories.vue into CatalogSourcesSettings.vue (Settings →
+// Catalog sources); the required-input secrets prompt moved into
+// CatalogSearch.vue's own dialog (the Add Server page's Catalog tab).
+describe('CatalogSourcesSettings.vue dialogs use showModal()/close(), not :open (FR-055)', () => {
+  const src = readSrc('../../src/components/CatalogSourcesSettings.vue')
 
   it('has no :open="..." binding on any <dialog>', () => {
     expect(src).not.toMatch(/<dialog[^>]*:open=/)
   })
 
-  it('names all three dialogs and drives them via ref + useDialogOpen', () => {
-    for (const testId of [
-      'registry-required-input-dialog',
-      'registry-add-source-dialog',
-      'registry-delete-dialog',
-    ]) {
+  it('names both dialogs and drives them via ref + useDialogOpen', () => {
+    for (const testId of ['registry-add-source-dialog', 'registry-delete-dialog']) {
       expect(src).toContain(testId)
     }
     expect(src).toContain('useDialogOpen')
   })
 })
 
+describe('CatalogSearch.vue secrets-prompt dialog uses showModal()/close(), not :open (FR-055)', () => {
+  const src = readSrc('../../src/components/CatalogSearch.vue')
+
+  it('has no :open="..." binding on any <dialog>', () => {
+    expect(src).not.toMatch(/<dialog[^>]*:open=/)
+  })
+
+  it('names the dialog and drives it via ref + useDialogOpen', () => {
+    expect(src).toContain('catalog-secrets-dialog')
+    expect(src).toContain('useDialogOpen')
+  })
+})
+
 describe('every <dialog class="modal"> drives its open state imperatively', () => {
   const files = [
     '../../src/components/OnboardingWizard.vue',
     '../../src/components/ConnectModal.vue',
     '../../src/components/AddSecretModal.vue',
     '../../src/components/AddServerModal.vue',
-    '../../src/views/Repositories.vue',
+    '../../src/components/CatalogSourcesSettings.vue',
+    '../../src/components/CatalogSearch.vue',
     '../../src/views/teams/UserTokens.vue',
     '../../src/views/teams/UserActivity.vue',
     '../../src/views/teams/UserServers.vue',

From b3192d6a046f5b04ec1916b4b35962ab9a544d90 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 01:26:24 +0300
Subject: [PATCH 16/27] feat(mcp): make search_servers' registry optional (Spec
 109 FR-067)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Omitted, it searches every enabled catalog source via registries.SearchAll
(FR-060) and returns the merged, ranked ServerEntry list in the same JSON
shape a single-registry search already returns — no 'added' field (that's
REST-only, contracts/rest-api.md#catalog). list_registries' wording moves to
'catalog source' terminology; both tools' descriptions point at the new
all-sources default.

Updates the frozen toolslist goldens deliberately (search_servers/
list_registries added to both the pre-099 and pre-105 enumerated-delta
gates, plus TestMenuSurface_ExactDeltaFromPreFeature's per-field
assertSearchServersDelta/assertListRegistriesDelta) since this changes a
built-in MCP tool's schema (registry: required -> optional).
---
 internal/server/mcp.go                        |  75 +++++++++--
 internal/server/mcp_menu_surface_test.go      |  63 ++++++++++
 .../server/search_servers_all_sources_test.go | 117 ++++++++++++++++++
 .../code_execution_mode.json                  |  10 +-
 .../toolslist_goldens/default_server.json     |  10 +-
 .../retrieve_tools_mode.json                  |  10 +-
 internal/server/toolslist_snapshot_test.go    |  25 +++-
 7 files changed, 275 insertions(+), 35 deletions(-)
 create mode 100644 internal/server/search_servers_all_sources_test.go

diff --git a/internal/server/mcp.go b/internal/server/mcp.go
index 303cbc61d..8bf8bffd4 100644
--- a/internal/server/mcp.go
+++ b/internal/server/mcp.go
@@ -1401,17 +1401,16 @@ func (p *MCPProxyServer) buildManagementTools() []mcpserver.ServerTool {
 		tools = append(tools, mcpserver.ServerTool{Tool: quarantineSecurityTool, Handler: p.handleQuarantineSecurity})
 	}
 
-	// search_servers - Registry search and discovery
+	// search_servers - Catalog search and discovery (Spec 109 FR-060/067)
 	{
 		searchServersTool := mcp.NewTool("search_servers",
-			mcp.WithDescription("🔍 Discover MCP servers from known registries with repository type detection. Search and filter servers from embedded registry list to find new MCP servers that can be added as upstreams. Features npm/PyPI package detection for enhanced install commands. WORKFLOW: 1) Call 'list_registries' first to see available registries, 2) Use this tool with a registry ID to search servers. Results include server URLs and repository information ready for direct use with upstream_servers add command."),
+			mcp.WithDescription("🔍 Discover MCP servers from the catalog, with repository type detection. Omit 'registry' to search every enabled catalog source at once, ranked official-first then by relevance (FR-060) — this is the recommended way to search. Pass 'registry' to narrow to one catalog source (e.g., 'smithery', 'mcprun', 'pulse'); use 'list_registries' to see source ids. Features npm/PyPI package detection for enhanced install commands. Results include server URLs and repository information ready for direct use with upstream_servers add command."),
 			mcp.WithTitleAnnotation("Search Servers"),
 			mcp.WithReadOnlyHintAnnotation(true),
 			mcp.WithDestructiveHintAnnotation(false),
 			mcp.WithOpenWorldHintAnnotation(true),
 			mcp.WithString("registry",
-				mcp.Required(),
-				mcp.Description("Registry ID or name to search (e.g., 'smithery', 'mcprun', 'pulse'). Use 'list_registries' tool first to see available registries."),
+				mcp.Description("Optional: a catalog source id or name to narrow the search to (e.g., 'smithery', 'mcprun', 'pulse'). Omit to search every enabled catalog source at once. Use 'list_registries' to see source ids."),
 			),
 			mcp.WithString("search",
 				mcp.Description("Search term to filter servers by name or description (case-insensitive)"),
@@ -1429,7 +1428,7 @@ func (p *MCPProxyServer) buildManagementTools() []mcpserver.ServerTool {
 	// list_registries - Explicit registry discovery tool
 	{
 		listRegistriesTool := mcp.NewTool("list_registries",
-			mcp.WithDescription("📋 List all available MCP registries. Use this FIRST to discover which registries you can search with the 'search_servers' tool. Each registry contains different collections of MCP servers that can be added as upstreams."),
+			mcp.WithDescription("📋 List all available catalog sources (registries). 'search_servers' already searches every enabled source when 'registry' is omitted (FR-060) — call this to see source ids, e.g. to narrow a search with 'registry', or to check what's enabled. Each source contains different collections of MCP servers that can be added as upstreams."),
 			mcp.WithTitleAnnotation("List Registries"),
 			mcp.WithReadOnlyHintAnnotation(true),
 			mcp.WithDestructiveHintAnnotation(false),
@@ -1575,11 +1574,10 @@ func (p *MCPProxyServer) handleSearchServers(ctx context.Context, request mcp.Ca
 	}
 	requestID := mintCorrelationID("search_servers")
 
-	registry, err := request.RequireString("registry")
-	if err != nil {
-		p.emitActivityInternalToolCall("search_servers", "", "", "", sessionID, requestID, "error", err.Error(), time.Since(startTime).Milliseconds(), nil, nil, nil, "")
-		return mcp.NewToolResultError(fmt.Sprintf("Missing required parameter 'registry': %v", err)), nil
-	}
+	// FR-067: 'registry' is optional — omitted means "every enabled catalog
+	// source" via registries.SearchAll (FR-060). Empty/whitespace is treated
+	// as omitted so a caller passing "" gets the same all-sources search.
+	registry := strings.TrimSpace(request.GetString("registry", ""))
 
 	// Get optional parameters
 	search := request.GetString("search", "")
@@ -1588,8 +1586,10 @@ func (p *MCPProxyServer) handleSearchServers(ctx context.Context, request mcp.Ca
 
 	// Build arguments map for activity logging (Spec 024)
 	args := map[string]interface{}{
-		"registry": registry,
-		"limit":    limit,
+		"limit": limit,
+	}
+	if registry != "" {
+		args["registry"] = registry
 	}
 	if search != "" {
 		args["search"] = search
@@ -1598,6 +1598,10 @@ func (p *MCPProxyServer) handleSearchServers(ctx context.Context, request mcp.Ca
 		args["tag"] = tag
 	}
 
+	if registry == "" {
+		return p.handleSearchServersAllSources(ctx, sessionID, requestID, startTime, args, search, tag, limit)
+	}
+
 	// Create experiments guesser if repository checking is enabled
 	var guesser *experiments.Guesser
 	if p.config != nil && p.config.CheckServerRepo {
@@ -1663,6 +1667,51 @@ func (p *MCPProxyServer) handleSearchServers(ctx context.Context, request mcp.Ca
 	return mcp.NewToolResultText(string(jsonResult)), nil
 }
 
+// handleSearchServersAllSources implements search_servers with 'registry'
+// omitted (Spec 109 FR-060/067): fans out across every enabled catalog
+// source via registries.SearchAll and returns the merged, ranked
+// ServerEntry list — the SAME JSON shape (url, installCmd, registry,
+// required_inputs[].secret) a single-registry search already returns, in
+// FR-060 rank order, with no "added" field (contracts/rest-api.md#catalog:
+// that field is REST-only, since it depends on caller scope MCP callers
+// don't carry the same way).
+func (p *MCPProxyServer) handleSearchServersAllSources(ctx context.Context, sessionID, requestID string, startTime time.Time, args map[string]interface{}, search, tag string, limit int) (*mcp.CallToolResult, error) {
+	hits, _, unavailable := registries.SearchAll(ctx, search, tag, limit, registries.SearchOptions{})
+
+	servers := make([]registries.ServerEntry, 0, len(hits))
+	for _, h := range hits {
+		servers = append(servers, h.Entry)
+	}
+
+	response := map[string]interface{}{
+		"servers": servers,
+		"total":   len(servers),
+		"query":   search,
+		"tag":     tag,
+	}
+	if len(unavailable) > 0 {
+		response["unavailable"] = unavailable
+	}
+
+	switch {
+	case len(servers) == 0 && search != "":
+		response["message"] = fmt.Sprintf("No servers found across any catalog source matching '%s'", search)
+	case len(servers) == 0:
+		response["message"] = "No servers found across any catalog source"
+	default:
+		response["message"] = fmt.Sprintf("Found %d server(s) across every enabled catalog source. Use 'upstream_servers add' with the URL to add one.", len(servers))
+	}
+
+	jsonResult, err := json.Marshal(response)
+	if err != nil {
+		p.emitActivityInternalToolCall("search_servers", "", "", "", sessionID, requestID, "error", err.Error(), time.Since(startTime).Milliseconds(), args, nil, nil, "")
+		return mcp.NewToolResultError(fmt.Sprintf("Failed to serialize results: %v", err)), nil
+	}
+
+	p.emitActivityInternalToolCall("search_servers", "", "", "", sessionID, requestID, "success", "", time.Since(startTime).Milliseconds(), args, response, nil, "")
+	return mcp.NewToolResultText(string(jsonResult)), nil
+}
+
 // handleListRegistries implements the list_registries functionality
 func (p *MCPProxyServer) handleListRegistries(ctx context.Context, _ mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 	startTime := time.Now()
@@ -1696,7 +1745,7 @@ func (p *MCPProxyServer) handleListRegistries(ctx context.Context, _ mcp.CallToo
 	response := map[string]interface{}{
 		"registries": registriesList,
 		"total":      len(registriesList),
-		"message":    "Available MCP registries. Use 'search_servers' tool with a registry ID to find servers. Newly added servers are quarantined by default until you approve them.",
+		"message":    "Available catalog sources (registries). Call 'search_servers' with no 'registry' to search all of them at once, or pass one of these ids to narrow it. Newly added servers are quarantined by default until you approve them.",
 	}
 
 	jsonResult, err := json.Marshal(response)
diff --git a/internal/server/mcp_menu_surface_test.go b/internal/server/mcp_menu_surface_test.go
index fa16ba31a..fda3f8ff1 100644
--- a/internal/server/mcp_menu_surface_test.go
+++ b/internal/server/mcp_menu_surface_test.go
@@ -185,6 +185,10 @@ func TestMenuSurface_ExactDeltaFromPreFeature(t *testing.T) {
 					assertUpstreamServersDelta(t, surface, preM, curM)
 				case name == "code_execution":
 					assertCodeExecutionLive(t, surface, preM, curM)
+				case name == "search_servers":
+					assertSearchServersDelta(t, surface, preM, curM)
+				case name == "list_registries":
+					assertListRegistriesDelta(t, surface, preM, curM)
 				default:
 					assert.Equal(t, preM, curM,
 						"surface %s: tool %q must be byte-identical to the pre-feature snapshot (SC-003)", surface, name)
@@ -335,6 +339,65 @@ func assertUpstreamServersDelta(t *testing.T, surface string, preM, curM map[str
 		"surface %s: the redaction note is APPENDED — no pre-feature prose may be rewritten", surface)
 }
 
+// assertSearchServersDelta: Spec 109 FR-067 makes 'registry' OPTIONAL (was
+// required) and updates its description, plus the tool's own description,
+// to the "search every catalog source" wording. No parameter is added or
+// removed, and every parameter OTHER than 'registry' is byte-identical.
+func assertSearchServersDelta(t *testing.T, surface string, preM, curM map[string]interface{}) {
+	t.Helper()
+
+	preDesc, _ := preM["description"].(string)
+	curDesc, _ := curM["description"].(string)
+	assert.NotEqual(t, preDesc, curDesc,
+		"surface %s: search_servers.description must be regenerated with the FR-067 catalog wording", surface)
+
+	preProps := schemaProps(preM)
+	curProps := schemaProps(curM)
+	assert.ElementsMatch(t, keysOf(preProps), keysOf(curProps),
+		"surface %s: search_servers must keep the same parameter set — FR-067 changes registry's requiredness/description only", surface)
+
+	for name, preProp := range preProps {
+		if name == "registry" {
+			continue
+		}
+		assert.Equal(t, preProp, curProps[name],
+			"surface %s: search_servers.%s must be unchanged (only 'registry' may move, FR-067)", surface, name)
+	}
+
+	preRequired := requiredParams(preM)
+	curRequired := requiredParams(curM)
+	assert.Contains(t, preRequired, "registry",
+		"surface %s: precondition — pre-feature search_servers required 'registry'", surface)
+	assert.NotContains(t, curRequired, "registry",
+		"surface %s: 'registry' must become optional (FR-067)", surface)
+}
+
+// assertListRegistriesDelta: Spec 109 FR-067 changes ONLY list_registries'
+// description (pointing at search_servers' all-sources default and using
+// "catalog source" wording). The tool takes no parameters, so its schema
+// must otherwise be byte-identical.
+func assertListRegistriesDelta(t *testing.T, surface string, preM, curM map[string]interface{}) {
+	t.Helper()
+
+	assert.Equal(t, schemaWithout(preM, "description"), schemaWithout(curM, "description"),
+		"surface %s: only list_registries' description may move (FR-067)", surface)
+
+	preDesc, _ := preM["description"].(string)
+	curDesc, _ := curM["description"].(string)
+	assert.NotEqual(t, preDesc, curDesc,
+		"surface %s: list_registries.description must be regenerated with the FR-067 catalog wording", surface)
+}
+
+// keysOf returns m's top-level keys, order-independent (paired with
+// assert.ElementsMatch).
+func keysOf(m map[string]interface{}) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}
+
 // assertQuarantineSecurityDelta: quarantine_security may grow the two scan
 // operations and the prose that documents them, and NOTHING else. In
 // particular it takes no new parameter — both operations reuse `name` — so the
diff --git a/internal/server/search_servers_all_sources_test.go b/internal/server/search_servers_all_sources_test.go
new file mode 100644
index 000000000..39f27b6d6
--- /dev/null
+++ b/internal/server/search_servers_all_sources_test.go
@@ -0,0 +1,117 @@
+package server
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/registries"
+)
+
+func withMCPCatalogFixture(t *testing.T) {
+	t.Helper()
+	fast := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{"id":"one","name":"Alpha Tool","description":"d1"}]`))
+	}))
+	t.Cleanup(fast.Close)
+	slow := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		<-r.Context().Done()
+	}))
+	t.Cleanup(slow.Close)
+
+	t.Cleanup(registries.AllowPrivateRegistryFetchForTest())
+	t.Cleanup(registries.SetRegistriesForTest([]registries.RegistryEntry{
+		{ID: "fast", Name: "Fast", ServersURL: fast.URL},
+	}))
+}
+
+// TestSearchServers_RegistryOptional_SearchesAllSources pins FR-067: omitting
+// 'registry' fans out across every enabled catalog source via
+// registries.SearchAll (FR-060) and returns the merged ServerEntry list,
+// carrying no "added" field (contracts/rest-api.md#catalog: REST-only).
+func TestSearchServers_RegistryOptional_SearchesAllSources(t *testing.T) {
+	withMCPCatalogFixture(t)
+	proxy := createTestMCPProxyServer(t)
+
+	req := mcp.CallToolRequest{Params: mcp.CallToolParams{
+		Name:      "search_servers",
+		Arguments: map[string]interface{}{"search": "Alpha"},
+	}}
+	result, err := proxy.handleSearchServers(context.Background(), req)
+	require.NoError(t, err)
+	require.False(t, result.IsError, "unexpected tool error: %+v", result.Content)
+
+	text := toolResultText(t, result)
+	var payload map[string]interface{}
+	require.NoError(t, json.Unmarshal([]byte(text), &payload))
+
+	servers, ok := payload["servers"].([]interface{})
+	require.True(t, ok, "expected a servers array, got %#v", payload)
+	require.Len(t, servers, 1)
+	entry, ok := servers[0].(map[string]interface{})
+	require.True(t, ok)
+	assert.Equal(t, "one", entry["id"])
+	assert.Equal(t, "Alpha Tool", entry["name"])
+	assert.NotContains(t, entry, "added", "the MCP surface must never carry the REST-only 'added' field")
+	if _, hasRegistryArg := payload["registry"]; hasRegistryArg {
+		t.Errorf("expected no 'registry' field echoed back when omitted, got %#v", payload["registry"])
+	}
+}
+
+// TestSearchServers_RegistryOptional_UnavailableSourceReported pins that a
+// failed source is listed unavailable rather than failing the whole search.
+func TestSearchServers_RegistryOptional_UnavailableSourceReported(t *testing.T) {
+	failing := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer failing.Close()
+
+	restoreAllow := registries.AllowPrivateRegistryFetchForTest()
+	defer restoreAllow()
+	restore := registries.SetRegistriesForTest([]registries.RegistryEntry{
+		{ID: "broken", Name: "Broken", ServersURL: failing.URL},
+	})
+	defer restore()
+
+	proxy := createTestMCPProxyServer(t)
+	req := mcp.CallToolRequest{Params: mcp.CallToolParams{Name: "search_servers", Arguments: map[string]interface{}{}}}
+	result, err := proxy.handleSearchServers(context.Background(), req)
+	require.NoError(t, err)
+	require.False(t, result.IsError)
+
+	var payload map[string]interface{}
+	require.NoError(t, json.Unmarshal([]byte(toolResultText(t, result)), &payload))
+	unavailable, ok := payload["unavailable"].([]interface{})
+	require.True(t, ok, "expected unavailable[] in the response, got %#v", payload)
+	require.Len(t, unavailable, 1)
+}
+
+// TestSearchServers_RegistrySpecified_UnchangedBehavior pins that passing
+// 'registry' still uses the single-source path unchanged (FR-067's ONLY
+// requirement is making it optional).
+func TestSearchServers_RegistrySpecified_UnchangedBehavior(t *testing.T) {
+	withMCPCatalogFixture(t)
+	proxy := createTestMCPProxyServer(t)
+
+	req := mcp.CallToolRequest{Params: mcp.CallToolParams{
+		Name:      "search_servers",
+		Arguments: map[string]interface{}{"registry": "fast"},
+	}}
+	result, err := proxy.handleSearchServers(context.Background(), req)
+	require.NoError(t, err)
+	require.False(t, result.IsError, "unexpected tool error: %+v", result.Content)
+
+	var payload map[string]interface{}
+	require.NoError(t, json.Unmarshal([]byte(toolResultText(t, result)), &payload))
+	assert.Equal(t, "fast", payload["registry"])
+	servers, ok := payload["servers"].([]interface{})
+	require.True(t, ok)
+	require.Len(t, servers, 1)
+}
diff --git a/internal/server/testdata/toolslist_goldens/code_execution_mode.json b/internal/server/testdata/toolslist_goldens/code_execution_mode.json
index 3dc25c486..9df56e78e 100644
--- a/internal/server/testdata/toolslist_goldens/code_execution_mode.json
+++ b/internal/server/testdata/toolslist_goldens/code_execution_mode.json
@@ -50,7 +50,7 @@
       "idempotentHint": false,
       "openWorldHint": false
     },
-    "description": "📋 List all available MCP registries. Use this FIRST to discover which registries you can search with the 'search_servers' tool. Each registry contains different collections of MCP servers that can be added as upstreams.",
+    "description": "📋 List all available catalog sources (registries). 'search_servers' already searches every enabled source when 'registry' is omitted (FR-060) — call this to see source ids, e.g. to narrow a search with 'registry', or to check what's enabled. Each source contains different collections of MCP servers that can be added as upstreams.",
     "inputSchema": {
       "properties": {},
       "required": [],
@@ -161,7 +161,7 @@
       "idempotentHint": false,
       "openWorldHint": true
     },
-    "description": "🔍 Discover MCP servers from known registries with repository type detection. Search and filter servers from embedded registry list to find new MCP servers that can be added as upstreams. Features npm/PyPI package detection for enhanced install commands. WORKFLOW: 1) Call 'list_registries' first to see available registries, 2) Use this tool with a registry ID to search servers. Results include server URLs and repository information ready for direct use with upstream_servers add command.",
+    "description": "🔍 Discover MCP servers from the catalog, with repository type detection. Omit 'registry' to search every enabled catalog source at once, ranked official-first then by relevance (FR-060) — this is the recommended way to search. Pass 'registry' to narrow to one catalog source (e.g., 'smithery', 'mcprun', 'pulse'); use 'list_registries' to see source ids. Features npm/PyPI package detection for enhanced install commands. Results include server URLs and repository information ready for direct use with upstream_servers add command.",
     "inputSchema": {
       "properties": {
         "limit": {
@@ -169,7 +169,7 @@
           "type": "number"
         },
         "registry": {
-          "description": "Registry ID or name to search (e.g., 'smithery', 'mcprun', 'pulse'). Use 'list_registries' tool first to see available registries.",
+          "description": "Optional: a catalog source id or name to narrow the search to (e.g., 'smithery', 'mcprun', 'pulse'). Omit to search every enabled catalog source at once. Use 'list_registries' to see source ids.",
           "type": "string"
         },
         "search": {
@@ -181,9 +181,7 @@
           "type": "string"
         }
       },
-      "required": [
-        "registry"
-      ],
+      "required": [],
       "type": "object"
     },
     "name": "search_servers"
diff --git a/internal/server/testdata/toolslist_goldens/default_server.json b/internal/server/testdata/toolslist_goldens/default_server.json
index 8083efeb1..6e258e09a 100644
--- a/internal/server/testdata/toolslist_goldens/default_server.json
+++ b/internal/server/testdata/toolslist_goldens/default_server.json
@@ -215,7 +215,7 @@
       "idempotentHint": false,
       "openWorldHint": false
     },
-    "description": "📋 List all available MCP registries. Use this FIRST to discover which registries you can search with the 'search_servers' tool. Each registry contains different collections of MCP servers that can be added as upstreams.",
+    "description": "📋 List all available catalog sources (registries). 'search_servers' already searches every enabled source when 'registry' is omitted (FR-060) — call this to see source ids, e.g. to narrow a search with 'registry', or to check what's enabled. Each source contains different collections of MCP servers that can be added as upstreams.",
     "inputSchema": {
       "properties": {},
       "required": [],
@@ -381,7 +381,7 @@
       "idempotentHint": false,
       "openWorldHint": true
     },
-    "description": "🔍 Discover MCP servers from known registries with repository type detection. Search and filter servers from embedded registry list to find new MCP servers that can be added as upstreams. Features npm/PyPI package detection for enhanced install commands. WORKFLOW: 1) Call 'list_registries' first to see available registries, 2) Use this tool with a registry ID to search servers. Results include server URLs and repository information ready for direct use with upstream_servers add command.",
+    "description": "🔍 Discover MCP servers from the catalog, with repository type detection. Omit 'registry' to search every enabled catalog source at once, ranked official-first then by relevance (FR-060) — this is the recommended way to search. Pass 'registry' to narrow to one catalog source (e.g., 'smithery', 'mcprun', 'pulse'); use 'list_registries' to see source ids. Features npm/PyPI package detection for enhanced install commands. Results include server URLs and repository information ready for direct use with upstream_servers add command.",
     "inputSchema": {
       "properties": {
         "limit": {
@@ -389,7 +389,7 @@
           "type": "number"
         },
         "registry": {
-          "description": "Registry ID or name to search (e.g., 'smithery', 'mcprun', 'pulse'). Use 'list_registries' tool first to see available registries.",
+          "description": "Optional: a catalog source id or name to narrow the search to (e.g., 'smithery', 'mcprun', 'pulse'). Omit to search every enabled catalog source at once. Use 'list_registries' to see source ids.",
           "type": "string"
         },
         "search": {
@@ -401,9 +401,7 @@
           "type": "string"
         }
       },
-      "required": [
-        "registry"
-      ],
+      "required": [],
       "type": "object"
     },
     "name": "search_servers"
diff --git a/internal/server/testdata/toolslist_goldens/retrieve_tools_mode.json b/internal/server/testdata/toolslist_goldens/retrieve_tools_mode.json
index 846578bd1..543bf6c19 100644
--- a/internal/server/testdata/toolslist_goldens/retrieve_tools_mode.json
+++ b/internal/server/testdata/toolslist_goldens/retrieve_tools_mode.json
@@ -215,7 +215,7 @@
       "idempotentHint": false,
       "openWorldHint": false
     },
-    "description": "📋 List all available MCP registries. Use this FIRST to discover which registries you can search with the 'search_servers' tool. Each registry contains different collections of MCP servers that can be added as upstreams.",
+    "description": "📋 List all available catalog sources (registries). 'search_servers' already searches every enabled source when 'registry' is omitted (FR-060) — call this to see source ids, e.g. to narrow a search with 'registry', or to check what's enabled. Each source contains different collections of MCP servers that can be added as upstreams.",
     "inputSchema": {
       "properties": {},
       "required": [],
@@ -377,7 +377,7 @@
       "idempotentHint": false,
       "openWorldHint": true
     },
-    "description": "🔍 Discover MCP servers from known registries with repository type detection. Search and filter servers from embedded registry list to find new MCP servers that can be added as upstreams. Features npm/PyPI package detection for enhanced install commands. WORKFLOW: 1) Call 'list_registries' first to see available registries, 2) Use this tool with a registry ID to search servers. Results include server URLs and repository information ready for direct use with upstream_servers add command.",
+    "description": "🔍 Discover MCP servers from the catalog, with repository type detection. Omit 'registry' to search every enabled catalog source at once, ranked official-first then by relevance (FR-060) — this is the recommended way to search. Pass 'registry' to narrow to one catalog source (e.g., 'smithery', 'mcprun', 'pulse'); use 'list_registries' to see source ids. Features npm/PyPI package detection for enhanced install commands. Results include server URLs and repository information ready for direct use with upstream_servers add command.",
     "inputSchema": {
       "properties": {
         "limit": {
@@ -385,7 +385,7 @@
           "type": "number"
         },
         "registry": {
-          "description": "Registry ID or name to search (e.g., 'smithery', 'mcprun', 'pulse'). Use 'list_registries' tool first to see available registries.",
+          "description": "Optional: a catalog source id or name to narrow the search to (e.g., 'smithery', 'mcprun', 'pulse'). Omit to search every enabled catalog source at once. Use 'list_registries' to see source ids.",
           "type": "string"
         },
         "search": {
@@ -397,9 +397,7 @@
           "type": "string"
         }
       },
-      "required": [
-        "registry"
-      ],
+      "required": [],
       "type": "object"
     },
     "name": "search_servers"
diff --git a/internal/server/toolslist_snapshot_test.go b/internal/server/toolslist_snapshot_test.go
index eb8c84d92..c15d85893 100644
--- a/internal/server/toolslist_snapshot_test.go
+++ b/internal/server/toolslist_snapshot_test.go
@@ -197,10 +197,16 @@ func TestToolsListSnapshot_MatchesMergeBaseGoldens(t *testing.T) {
 //     by issue #1236), so on those surfaces the entry CHANGES from the stub to
 //     the live tool; mcp_menu_surface_test.go pins that transition field by
 //     field (assertCodeExecutionLive).
+//   - search_servers / list_registries — Spec 109 FR-060/067: 'registry'
+//     becomes optional on search_servers (was required) so it searches every
+//     enabled catalog source when omitted, and both tools' descriptions gained
+//     "catalog source" wording. Pinned field by field by
+//     TestMenuSurface_ExactDeltaFromPreFeature's assertSearchServersDelta /
+//     assertListRegistriesDelta.
 var toolsListAllowedDelta = map[string][]string{
-	"default_server":      {"describe_tool", "quarantine_security", "upstream_servers"},
-	"retrieve_tools_mode": {"code_execution", "describe_tool", "quarantine_security", "upstream_servers"},
-	"code_execution_mode": {"code_execution", "quarantine_security", "upstream_servers"},
+	"default_server":      {"describe_tool", "quarantine_security", "upstream_servers", "search_servers", "list_registries"},
+	"retrieve_tools_mode": {"code_execution", "describe_tool", "quarantine_security", "upstream_servers", "search_servers", "list_registries"},
+	"code_execution_mode": {"code_execution", "quarantine_security", "upstream_servers", "search_servers", "list_registries"},
 }
 
 // toolsListAllowedAdditions enumerates the tool entries a shipped change was
@@ -346,6 +352,17 @@ const (
 	spec105CodeExecutionTool = "code_execution"
 )
 
+// spec109CatalogTools are the two entries Spec 109 (FR-060/067) allowed to
+// move relative to the pre-105 baseline: search_servers' 'registry'
+// parameter becomes optional (was required) and both tools' descriptions
+// gained "catalog source" wording. Skipped in the pre-105 byte-comparison
+// loop below the same way code_execution is; their delta is pinned field by
+// field against the newer pre-099 baseline instead
+// (TestToolsListSnapshot_DeltaIsEnumerated / toolsListAllowedDelta) and by
+// TestMenuSurface_ExactDeltaFromPreFeature's assertSearchServersDelta /
+// assertListRegistriesDelta.
+var spec109CatalogTools = map[string]bool{"search_servers": true, "list_registries": true}
+
 // spec105EnumerationPhrases are the pre-105 fragments that advertised
 // discovery-by-failed-call. Neither may survive in the live strings.
 var spec105EnumerationPhrases = []string{
@@ -389,7 +406,7 @@ func TestCodeExecutionDescriptions_EnumerationIsAdminOnly(t *testing.T) {
 
 			// Every other entry is byte-equal to the frozen capture.
 			for name, pre := range before {
-				if name == spec105CodeExecutionTool {
+				if name == spec105CodeExecutionTool || spec109CatalogTools[name] {
 					continue
 				}
 				assert.True(t, bytes.Equal(pre, after[name]),

From f89476b7f3ff0bf9e01f9542a4c99b1fc9c1050a Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 01:32:54 +0300
Subject: [PATCH 17/27] feat(macos): add catalog models + shared secret
 ref-name helper (Spec 109 FR-060/065)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- API/CatalogModels.swift: Codable mirrors of GET /api/v1/catalog/search's
  DTOs (CatalogResult, CatalogInstall, CatalogInput, CatalogSections),
  distinct from RegistryModels' RepositoryServer (that JSON stays
  unchanged).
- API/APIClient.swift: searchCatalog(query:source:tag:limit:) calling the
  new endpoint.
- Models/SecretRefName.swift: Swift port of internal/secret/refname.go's
  RefName (FR-065), pinned against the shared ref_names.json fixture in
  MCPProxyTests/CatalogTests.swift. ServerDetailView's old
  suggestedSecretName (which dropped the field kind) now delegates to it.
- Models/SecretLikeName.swift: Swift port of the D13 secret-like-name
  heuristic.

Known gap (documented, not fixed in this PR): the Add Server sheet's
Catalog/Paste tabs and the Registries-sidebar-item removal are NOT
implemented — this PR lands the shared, contract-critical data
layer (verified via swift test) that a follow-up UI PR builds on, mirroring
the same scoped-down decision made on the Web side for AddServerModal's
other callers.
---
 .../MCPProxy/MCPProxy/API/APIClient.swift     |  12 ++
 .../MCPProxy/MCPProxy/API/CatalogModels.swift |  84 ++++++++++
 .../MCPProxy/Models/SecretLikeName.swift      |  17 ++
 .../MCPProxy/Models/SecretRefName.swift       |  69 ++++++++
 .../MCPProxy/Views/ServerDetailView.swift     |  22 +--
 .../MCPProxy/MCPProxyTests/CatalogTests.swift | 155 ++++++++++++++++++
 6 files changed, 345 insertions(+), 14 deletions(-)
 create mode 100644 native/macos/MCPProxy/MCPProxy/API/CatalogModels.swift
 create mode 100644 native/macos/MCPProxy/MCPProxy/Models/SecretLikeName.swift
 create mode 100644 native/macos/MCPProxy/MCPProxy/Models/SecretRefName.swift
 create mode 100644 native/macos/MCPProxy/MCPProxyTests/CatalogTests.swift

diff --git a/native/macos/MCPProxy/MCPProxy/API/APIClient.swift b/native/macos/MCPProxy/MCPProxy/API/APIClient.swift
index ac0e1f07a..03f171ce4 100644
--- a/native/macos/MCPProxy/MCPProxy/API/APIClient.swift
+++ b/native/macos/MCPProxy/MCPProxy/API/APIClient.swift
@@ -1252,4 +1252,16 @@ actor APIClient {
             return .failure(message: error.localizedDescription)
         }
     }
+
+    /// Search the catalog across every enabled source (Spec 109 FR-060) via
+    /// `GET /api/v1/catalog/search?q=&source=&tag=&limit=`. `source` narrows
+    /// to one catalog source id; omit for "every enabled source at once".
+    func searchCatalog(query: String = "", source: String? = nil, tag: String? = nil, limit: Int = 20) async throws -> CatalogSearchResponse {
+        var params: [String] = ["limit=\(limit)"]
+        if !query.isEmpty { params.append("q=\(query.uriComponentEncoded)") }
+        if let source, !source.isEmpty { params.append("source=\(source.uriComponentEncoded)") }
+        if let tag, !tag.isEmpty { params.append("tag=\(tag.uriComponentEncoded)") }
+        let path = "/api/v1/catalog/search?\(params.joined(separator: "&"))"
+        return try await fetchWrapped(path: path)
+    }
 }
diff --git a/native/macos/MCPProxy/MCPProxy/API/CatalogModels.swift b/native/macos/MCPProxy/MCPProxy/API/CatalogModels.swift
new file mode 100644
index 000000000..5138d9b08
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxy/API/CatalogModels.swift
@@ -0,0 +1,84 @@
+import Foundation
+
+// MARK: - Catalog (Spec 109 FR-060/061)
+//
+// macOS-tray mirror of `GET /api/v1/catalog/search` — a source-agnostic,
+// ranked view over every enabled registry ("catalog source"), fanned out in
+// parallel server-side (`registries.SearchAll`). This is a distinct DTO from
+// `RepositoryServer` (RegistryModels.swift): the existing
+// `GET /api/v1/registries/{id}/servers` and MCP `search_servers` keep
+// serving that shape unchanged (contracts/rest-api.md#catalog).
+
+/// A source's own popularity signal — stars for a GitHub-hosted server,
+/// install/download counts otherwise. Either field may be absent.
+struct CatalogPopularity: Codable, Equatable {
+    let stars: Int?
+    let installs: Int?
+}
+
+/// The install target: either a remote URL or a local command + args, never
+/// both.
+struct CatalogInstall: Codable, Equatable {
+    let url: String?
+    let command: String?
+    let args: [String]?
+}
+
+/// One required input (FR-061/065). `secretLike` already folds in the D13
+/// name heuristic server-side, so the toggle default needs no client-side
+/// re-derivation.
+struct CatalogInput: Codable, Equatable {
+    let name: String
+    let description: String?
+    let secretLike: Bool
+
+    enum CodingKeys: String, CodingKey {
+        case name, description
+        case secretLike = "secret_like"
+    }
+}
+
+/// One `GET /api/v1/catalog/search` result. Mirrors `registries.CatalogResult`.
+struct CatalogResult: Codable, Identifiable, Equatable {
+    let source: String
+    let id: String
+    let title: String
+    let publisher: String?
+    let verified: Bool
+    let official: Bool
+    let popularity: CatalogPopularity?
+    let description: String
+    let transport: String
+    let install: CatalogInstall
+    let requiredInputs: [CatalogInput]?
+    let sourceCodeURL: String?
+    let added: Bool
+
+    enum CodingKeys: String, CodingKey {
+        case source, id, title, publisher, verified, official, popularity, description, transport, install, added
+        case requiredInputs = "required_inputs"
+        case sourceCodeURL = "source_code_url"
+    }
+}
+
+/// A catalog source that failed or timed out. Mirrors `registries.SourceError`.
+struct CatalogSourceError: Codable, Equatable {
+    let source: String
+    let reason: String
+}
+
+/// The empty-query landing sections (FR-060), each capped at 12 server-side.
+struct CatalogSections: Codable, Equatable {
+    let official: [CatalogResult]
+    let popular: [CatalogResult]
+}
+
+/// Response of `GET /api/v1/catalog/search`. Mirrors the REST DTO
+/// (contracts/rest-api.md#catalog): `sections` is `null` for a non-empty
+/// query.
+struct CatalogSearchResponse: Codable {
+    let query: String
+    let results: [CatalogResult]
+    let sections: CatalogSections?
+    let unavailable: [CatalogSourceError]?
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Models/SecretLikeName.swift b/native/macos/MCPProxy/MCPProxy/Models/SecretLikeName.swift
new file mode 100644
index 000000000..8ef562255
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxy/Models/SecretLikeName.swift
@@ -0,0 +1,17 @@
+import Foundation
+
+/// Shared "does this field name look like a credential?" rule (Spec 109
+/// research D13), ported verbatim from `internal/secretlike/secretlike.go` /
+/// `frontend/src/utils/secretLike.ts` so all three surfaces default the
+/// Value/Secret toggle to Secret for the same field names (FR-065).
+enum SecretLikeName {
+    private static let pattern = try! NSRegularExpression(
+        pattern: "(token|secret|password|passwd|api[_-]?key|[_-]key$|auth|credential|private[_-]?key)",
+        options: [.caseInsensitive]
+    )
+
+    static func looksSecret(_ name: String) -> Bool {
+        let range = NSRange(name.startIndex..<name.endIndex, in: name)
+        return pattern.firstMatch(in: name, options: [], range: range) != nil
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Models/SecretRefName.swift b/native/macos/MCPProxy/MCPProxy/Models/SecretRefName.swift
new file mode 100644
index 000000000..f9f0e11a8
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxy/Models/SecretRefName.swift
@@ -0,0 +1,69 @@
+import Foundation
+
+/// Swift port of `internal/secret/refname.go` `RefName` (Spec 109 FR-065),
+/// shared verbatim with the Go implementation and the TS port
+/// (`frontend/src/utils/secretRef.ts`) via `internal/secret/testdata/ref_names.json`
+/// (see `MCPProxyTests/CatalogTests.swift`). Replaces `ServerDetailView`'s old
+/// `suggestedSecretName`, which dropped the field KIND (env vs header) and so
+/// let an env var and a header of the same name collide on one keyring entry.
+enum SecretRefName {
+    /// Kind of field a secret name is computed for. Kept as a distinct path
+    /// component (rather than folded into the key) so an env var and a
+    /// header of the same name never share one keyring entry.
+    enum Kind: String {
+        case env
+        case header
+    }
+
+    private static let maxLength = 64
+
+    /// Computes the OS-keyring entry name for one field on one server:
+    /// "<server>-<kind>-<key>", lower-cased, with every run of characters
+    /// outside [a-z0-9-] collapsed to a single '-', trimmed, and capped at 64
+    /// characters.
+    ///
+    /// `taken` reports whether a candidate name is already present in the
+    /// keyring (`GET /secrets/refs`); on a collision this appends -2, -3, …
+    /// until it finds a free one, so an add never silently overwrites an
+    /// existing secret (D28).
+    static func compute(server: String, kind: Kind, key: String, taken: ((String) -> Bool)? = nil) -> String {
+        let base = normalize("\(server)-\(kind.rawValue)-\(key)")
+        guard let taken else { return base }
+
+        var candidate = base
+        var n = 2
+        while taken(candidate) {
+            let suffix = "-\(n)"
+            let maxBase = maxLength - suffix.count
+            let trimmedBase = base.count > maxBase ? String(base.prefix(maxBase)) : base
+            candidate = trimmedBase + suffix
+            n += 1
+        }
+        return candidate
+    }
+
+    private static let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyz0123456789-")
+
+    private static func normalize(_ s: String) -> String {
+        let scrubbed = s.lowercased().unicodeScalars.map { allowed.contains($0) ? Character($0) : "-" }
+        var collapsed = ""
+        var lastWasDash = false
+        for ch in scrubbed {
+            if ch == "-" {
+                if !lastWasDash { collapsed.append(ch) }
+                lastWasDash = true
+            } else {
+                collapsed.append(ch)
+                lastWasDash = false
+            }
+        }
+        var trimmed = collapsed
+        while trimmed.hasPrefix("-") { trimmed.removeFirst() }
+        while trimmed.hasSuffix("-") { trimmed.removeLast() }
+        if trimmed.count > maxLength {
+            trimmed = String(trimmed.prefix(maxLength))
+            while trimmed.hasSuffix("-") { trimmed.removeLast() }
+        }
+        return trimmed
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ServerDetailView.swift b/native/macos/MCPProxy/MCPProxy/Views/ServerDetailView.swift
index 5ecbbbc60..15f351a21 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/ServerDetailView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/ServerDetailView.swift
@@ -1292,23 +1292,17 @@ struct ServerDetailView: View {
         enum Scope: String { case header, env }
     }
 
-    /// Suggest a keyring secret name derived from server.name + key.
-    /// Lowercased, alphanumeric + hyphens, capped at 64 chars — same
-    /// convention as the Web UI / Secrets view.
-    private func suggestedSecretName(for key: String) -> String {
-        let base = "\(server.name)-\(key)"
-        let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyz0123456789-")
-        let scrubbed = base.lowercased().unicodeScalars
-            .map { allowed.contains($0) ? Character($0) : "-" }
-        var out = String(scrubbed)
-            .split(separator: "-", omittingEmptySubsequences: true)
-            .joined(separator: "-")
-        if out.count > 64 { out = String(out.prefix(64)) }
-        return out
+    /// Suggest a keyring secret name derived from server.name + key (FR-065):
+    /// the shared SecretRefName helper (also used by the Add Server sheet)
+    /// keeps the field KIND (env vs header) in the name, so a header and an
+    /// env var with the same key never collide on one keyring entry.
+    private func suggestedSecretName(scope: ConvertToSecretContext.Scope, key: String) -> String {
+        let kind: SecretRefName.Kind = scope == .header ? .header : .env
+        return SecretRefName.compute(server: server.name, kind: kind, key: key)
     }
 
     private func openConvertSheet(scope: ConvertToSecretContext.Scope, key: String, value: String) {
-        convertSheetSecretName = suggestedSecretName(for: key)
+        convertSheetSecretName = suggestedSecretName(scope: scope, key: key)
         convertSheetBusy = false
         convertSheetError = nil
         convertSheet = ConvertToSecretContext(scope: scope, key: key, value: value)
diff --git a/native/macos/MCPProxy/MCPProxyTests/CatalogTests.swift b/native/macos/MCPProxy/MCPProxyTests/CatalogTests.swift
new file mode 100644
index 000000000..42e60734c
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/CatalogTests.swift
@@ -0,0 +1,155 @@
+import XCTest
+@testable import MCPProxy
+
+/// Spec 109 (FR-060/061/065) — macOS mirror of the Web UI catalog surface.
+/// Covers the pure, testable units the Add Server sheet's Catalog tab and
+/// secret toggle rely on: `GET /api/v1/catalog/search` JSON decode, the
+/// FR-065 keyring ref-name algorithm (pinned against the same shared fixture
+/// Go and vitest decode), and the D13 secret-like-name heuristic.
+final class CatalogTests: XCTestCase {
+
+    private func decode<T: Decodable>(_ type: T.Type, from jsonString: String) throws -> T {
+        let data = jsonString.data(using: .utf8)!
+        return try JSONDecoder().decode(T.self, from: data)
+    }
+
+    // MARK: - CatalogResult decode (contracts/rest-api.md#catalog example)
+
+    func testDecodesTheContractExampleShape() throws {
+        let json = """
+        {"source": "official", "id": "io.github.github/github-mcp-server", "title": "GitHub",
+         "publisher": "github", "verified": true, "official": true, "popularity": {"stars": 21000},
+         "description": "…", "transport": "http", "install": {"url": "https://api.githubcopilot.com/mcp/"},
+         "required_inputs": [{"name": "GITHUB_TOKEN", "secret_like": true}], "added": false}
+        """
+        let result = try decode(CatalogResult.self, from: json)
+        XCTAssertEqual(result.source, "official")
+        XCTAssertEqual(result.id, "io.github.github/github-mcp-server")
+        XCTAssertEqual(result.title, "GitHub")
+        XCTAssertTrue(result.official)
+        XCTAssertTrue(result.verified)
+        XCTAssertEqual(result.popularity?.stars, 21000)
+        XCTAssertEqual(result.transport, "http")
+        XCTAssertEqual(result.install.url, "https://api.githubcopilot.com/mcp/")
+        XCTAssertNil(result.install.command)
+        XCTAssertEqual(result.requiredInputs?.first?.name, "GITHUB_TOKEN")
+        XCTAssertEqual(result.requiredInputs?.first?.secretLike, true)
+        XCTAssertFalse(result.added)
+    }
+
+    func testDecodesAStdioInstallTarget() throws {
+        let json = """
+        {"source": "official", "id": "fs", "title": "Filesystem", "verified": false, "official": true,
+         "description": "d", "transport": "stdio",
+         "install": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]},
+         "added": true}
+        """
+        let result = try decode(CatalogResult.self, from: json)
+        XCTAssertEqual(result.install.command, "npx")
+        XCTAssertEqual(result.install.args, ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])
+        XCTAssertNil(result.install.url)
+        XCTAssertTrue(result.added)
+    }
+
+    func testDecodesSearchResponseWithNullSections() throws {
+        let json = """
+        {"query": "github", "results": [], "sections": null,
+         "unavailable": [{"source": "smithery", "reason": "timeout after 5s"}]}
+        """
+        let resp = try decode(CatalogSearchResponse.self, from: json)
+        XCTAssertEqual(resp.query, "github")
+        XCTAssertNil(resp.sections)
+        XCTAssertEqual(resp.unavailable?.first?.source, "smithery")
+    }
+
+    func testDecodesEmptyQuerySections() throws {
+        let json = """
+        {"query": "", "results": [], "sections": {"official": [], "popular": []}, "unavailable": []}
+        """
+        let resp = try decode(CatalogSearchResponse.self, from: json)
+        XCTAssertNotNil(resp.sections)
+        XCTAssertEqual(resp.sections?.official.count, 0)
+    }
+
+    // MARK: - SecretRefName (FR-065), pinned against the shared fixture
+
+    func testRefNameBasic() {
+        XCTAssertEqual(SecretRefName.compute(server: "github", kind: .env, key: "API_KEY"), "github-env-api-key")
+        XCTAssertEqual(SecretRefName.compute(server: "github", kind: .header, key: "API_KEY"), "github-header-api-key")
+    }
+
+    func testRefNameEnvHeaderSameNameDistinctRefs() {
+        let env = SecretRefName.compute(server: "github", kind: .env, key: "API_KEY")
+        let header = SecretRefName.compute(server: "github", kind: .header, key: "API_KEY")
+        XCTAssertNotEqual(env, header)
+    }
+
+    func testRefNameTakenNameGetsSuffix() {
+        let taken: Set<String> = ["github-env-api-key", "github-env-api-key-2"]
+        let got = SecretRefName.compute(server: "github", kind: .env, key: "API_KEY", taken: { taken.contains($0) })
+        XCTAssertEqual(got, "github-env-api-key-3")
+    }
+
+    func testRefNameLongNameTruncated() {
+        let longKey = "THIS_IS_A_VERY_VERY_VERY_VERY_VERY_VERY_VERY_LONG_ENV_VAR_NAME"
+        let got = SecretRefName.compute(server: "some-really-long-server-name", kind: .env, key: longKey)
+        XCTAssertLessThanOrEqual(got.count, 64)
+    }
+
+    /// Decodes the same fixture Go (`internal/secret/refname_test.go`) and
+    /// vitest (`frontend/tests/unit/secret-ref.spec.ts`) decode, so all three
+    /// ports agree on every case (FR-065).
+    func testRefNameMatchesSharedFixture() throws {
+        struct FixtureCase: Decodable {
+            let server: String
+            let kind: String
+            let key: String
+            let taken: [String]
+            let want: String
+        }
+        struct Fixture: Decodable {
+            let cases: [FixtureCase]
+        }
+        // Kept in sync with internal/secret/testdata/ref_names.json /
+        // frontend/tests/unit/fixtures/ref_names.json by hand (no shared
+        // fixture-loading mechanism between the Go module and this SPM
+        // package's test target).
+        let fixtureJSON = """
+        {
+          "cases": [
+            {"server": "github", "kind": "env", "key": "API_KEY", "taken": [], "want": "github-env-api-key"},
+            {"server": "github", "kind": "header", "key": "API_KEY", "taken": [], "want": "github-header-api-key"},
+            {"server": "github", "kind": "env", "key": "GITHUB_TOKEN", "taken": [], "want": "github-env-github-token"},
+            {"server": "My Server!", "kind": "env", "key": "GITHUB_TOKEN", "taken": [], "want": "my-server-env-github-token"},
+            {"server": "github", "kind": "env", "key": "API_KEY", "taken": ["github-env-api-key"], "want": "github-env-api-key-2"},
+            {"server": "github", "kind": "env", "key": "API_KEY", "taken": ["github-env-api-key", "github-env-api-key-2"], "want": "github-env-api-key-3"}
+          ]
+        }
+        """
+        let fixture = try decode(Fixture.self, from: fixtureJSON)
+        XCTAssertFalse(fixture.cases.isEmpty)
+        for c in fixture.cases {
+            let takenSet = Set(c.taken)
+            guard let kind = SecretRefName.Kind(rawValue: c.kind) else {
+                XCTFail("unknown kind \(c.kind)")
+                continue
+            }
+            let got = SecretRefName.compute(server: c.server, kind: kind, key: c.key, taken: { takenSet.contains($0) })
+            XCTAssertEqual(got, c.want, "server=\(c.server) kind=\(c.kind) key=\(c.key)")
+        }
+    }
+
+    // MARK: - SecretLikeName (D13)
+
+    func testLooksSecretFlagsConventionalNames() {
+        for name in ["GITHUB_TOKEN", "API_KEY", "PASSWORD", "Authorization", "PRIVATE_KEY"] {
+            XCTAssertTrue(SecretLikeName.looksSecret(name), name)
+        }
+    }
+
+    func testLooksSecretDoesNotFlagOrdinaryNames() {
+        for name in ["PORT", "WORKDIR", "PATH", "REGION"] {
+            XCTAssertFalse(SecretLikeName.looksSecret(name), name)
+        }
+    }
+}

From 28706d7b376b66e1d508d6cefe51b6ea487aad93 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 01:37:53 +0300
Subject: [PATCH 18/27] chore(oas): regenerate OpenAPI spec for GET
 /catalog/search

---
 oas/docs.go      |  4 +--
 oas/swagger.yaml | 84 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+), 2 deletions(-)

diff --git a/oas/docs.go b/oas/docs.go
index 0e091b147..59f8fa04e 100644
--- a/oas/docs.go
+++ b/oas/docs.go
@@ -6,10 +6,10 @@ import "github.com/swaggo/swag/v2"
 
 const docTemplate = `{
     "schemes": {{ marshal .Schemes }},
-    "components": {"schemas":{"config.AuditLogConfig":{"description":"AuditLog configures the Spec 107 edition-neutral audit sink\n(internal/audit). nil means \"use the per-edition/per-transport\ndefault\" (EffectiveAuditLog); restart-pinned (bound at sink\nconstruction). See audit_log.go.","properties":{"compress":{"type":"boolean"},"enabled":{"type":"boolean"},"max_age_days":{"type":"integer"},"max_backups":{"type":"integer"},"max_size_mb":{"type":"integer"},"path":{"type":"string"},"stdout":{"type":"boolean"}},"type":"object"},"config.ConcurrencyDefaults":{"description":"ServerConcurrencyDefaults is scope (b) of FR-020: the blanket per-server\ndefault set inherited by every server that does not override a setting.\nAbsent (the default) = no per-server limiting unless a server configures\nit explicitly. File/API-configured only — no env scheme (FR-022).","properties":{"max_concurrent_requests":{"type":"integer"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"}},"type":"object"},"config.Config":{"properties":{"activity_cleanup_interval_min":{"description":"Background cleanup interval in minutes (default: 60)","type":"integer"},"activity_max_records":{"description":"Max records before pruning (default: 100000)","type":"integer"},"activity_max_response_size":{"description":"Response truncation limit in bytes (default: 65536)","type":"integer"},"activity_max_size_mb":{"description":"ActivityMaxSizeMB caps the total activity-log size in MB before the\noldest records are pruned. Omit the key for the 256MB default; set it to\n0 to disable the size cap.","type":"integer"},"activity_retention_days":{"description":"Activity logging settings (RFC-003)","type":"integer"},"aggregate_upstream_prompts":{"description":"AggregateUpstreamPrompts, when true, aggregates every connected upstream\nserver's advertised MCP prompts into mcpproxy's own prompts/list\n(exposed as \"\u003cserver\u003e__\u003cprompt\u003e\"). OFF by default: users are safe by\ndefault and opt in deliberately. EnablePrompts still governs the built-in\nprompts + the prompts capability; this flag gates ONLY the upstream\naggregation performed by RefreshPrompts. Hot-reloadable.","type":"boolean"},"allow_private_registry_fetch":{"description":"AllowPrivateRegistryFetch opts out of the registry SSRF guard (MCP-1076,\nCWE-918). By default (false) registry fetches refuse any host that is — or\nresolves to — a non-routable address (loopback, RFC1918/CGNAT private,\nlink-local incl. the 169.254.169.254 cloud-metadata endpoint), so a\nmalicious or typo'd registry source cannot turn the daemon into a\nrequest-forgery vector against internal services.\n\nThis opt-out is BLANKET (all-or-nothing): setting it true disables the\nguard for EVERY non-routable range at once — loopback, RFC1918/CGNAT\nprivate, link-local AND the 169.254.169.254 cloud-metadata endpoint. There\nis no way to allow only loopback; enabling it for a localhost dev registry\nalso re-opens the cloud-metadata SSRF vector. Set true ONLY when you\nintentionally run a trusted registry mirror on an internal/private address,\nideally on a host with no cloud-metadata exposure. The change takes effect\nonly on daemon (re)start or config reload.","type":"boolean"},"allow_server_add":{"type":"boolean"},"allow_server_remove":{"type":"boolean"},"api_key":{"description":"Security settings","type":"string"},"audit_log":{"$ref":"#/components/schemas/config.AuditLogConfig"},"call_tool_timeout":{"type":"string"},"check_server_repo":{"description":"Repository detection settings","type":"boolean"},"code_execution_max_parallel":{"description":"Default concurrency for call_tools() batches (1-32, default: 8)","type":"integer"},"code_execution_max_tool_calls":{"description":"Max tool calls per execution (0 = unlimited, default: 0)","type":"integer"},"code_execution_pool_size":{"description":"JavaScript runtime pool size (default: 10)","type":"integer"},"code_execution_timeout_ms":{"description":"Timeout in milliseconds (default: 120000, max: 600000)","type":"integer"},"data_dir":{"type":"string"},"debug_search":{"type":"boolean"},"direct_tool_response_mode":{"description":"DirectToolResponseMode selects the serialization of the DIRECT\nenumeration surface (Spec 102). Valid values: \"\" (= full), \"full\"\n(default: today's schema-bearing entries), \"deferred\" (description +\ncompact signature, with a minimal permissive input schema; upstream\ninputSchema and outputSchema are stripped and recovered on demand via\ndescribe_tool).\n\nDeliberately NOT an extension of tool_response_mode: reusing that axis\nwould silently change /mcp/all output for every deployment already\nrunning compact, which FR-015 forbids. Serialization-only — it never\nchanges WHICH tools are listed, only how (FR-008). Hot-reloadable.","type":"string"},"disable_management":{"type":"boolean"},"docker_isolation":{"$ref":"#/components/schemas/config.DockerIsolationConfig"},"docker_recovery":{"$ref":"#/components/schemas/config.DockerRecoveryConfig"},"enable_code_execution":{"description":"Code execution settings","type":"boolean"},"enable_prompts":{"description":"Prompts settings","type":"boolean"},"enable_socket":{"description":"Enable Unix socket/named pipe for local IPC (default: true)","type":"boolean"},"enable_tray":{"description":"Deprecated: EnableTray is unused and has no runtime effect. Kept for backward compatibility.","type":"boolean"},"environment":{"$ref":"#/components/schemas/secureenv.EnvConfig"},"features":{"$ref":"#/components/schemas/config.FeatureFlags"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned stdio upstream servers (MCP-2769). OFF by\ndefault: proxy URLs commonly embed credentials (http://user:pass@proxy), so\nforwarding them to every upstream is a credential-leak risk. When enabled,\nvalues are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"health_check_interval":{"description":"Discovery \u0026 health-check cadence (spec 074, #608). Both are *Duration\ntri-state pointers: nil = inherit the built-in default; a pointer to 0s =\nthe loop is disabled; a positive value = that interval. Defaults live only\nin the resolvers (ResolveHealthCheckInterval / ResolveToolDiscoveryInterval)\nso an unset key behaves exactly as before this feature (SC-005). Validated\nin Validate(): health-check ∈ {0} ∪ [5s,1h]; tool-discovery ∈ {0} ∪ [30s,24h].","type":"string"},"http_idle_timeout":{"description":"HTTPIdleTimeout caps how long an idle keep-alive connection is kept open.\nUnset = 180s. \"0s\" removes the dedicated idle deadline, but net/http then\nfalls back to ReadTimeout — idle is fully unbounded only when\nhttp_read_timeout is also \"0s\". Requires a restart.","type":"string"},"http_read_timeout":{"description":"HTTPReadTimeout caps how long reading a whole request (headers + body)\nmay take. Unset = 120s; \"0s\" disables it. Requires a restart.","type":"string"},"http_write_timeout":{"description":"HTTPWriteTimeout caps how long producing a whole response may take on\nnon-streaming endpoints (REST, Web UI, health). Unset = 120s; \"0s\"\ndisables it globally. MCP and SSE /events routes are exempt by design.","type":"string"},"init_timeout":{"description":"InitTimeout is the global default deadline for an upstream's MCP\n` + "`" + `initialize` + "`" + ` handshake (MCP-3322 / GH #760). *Duration tri-state: nil =\ninherit the built-in 30s default; a positive value = that deadline. A\nper-server InitTimeout overrides this. Resolved by ResolveInitTimeout;\nvalidated to {0} ∪ [1s, 30m] in Validate(). Servers doing legitimate\nfirst-run warmup (cache/index build) before answering ` + "`" + `initialize` + "`" + ` can\nraise this so they are not killed mid-startup.","type":"string"},"instructions":{"description":"Instructions text returned in the MCP initialize response to guide AI agents.\nWhen empty, a built-in default is used that explains retrieve_tools workflow.","type":"string"},"intent_declaration":{"$ref":"#/components/schemas/config.IntentDeclarationConfig"},"listen":{"type":"string"},"logging":{"$ref":"#/components/schemas/config.LogConfig"},"max_concurrent_requests":{"description":"Concurrency limits (spec 093, GH #955). Scope (a) of FR-020: the GLOBAL\nAGGREGATE limiter — one proxy-wide cap on concurrently running upstream\ntool calls, with its own bounded wait queue. Tri-state pointers: absent =\nthe limiter does not exist (default, zero behavior change); an explicit 0\nmax also disables it; positive = that cap. This scope is NEVER a\nper-server inheritance source — per-server values come from\nServerConcurrencyDefaults / the per-server overrides — but a server's\neffective concurrency is bounded by BOTH its own limiter and this one.\nResolved by ResolveGlobalConcurrency; hot-reloadable; overridable via\nMCPPROXY_MAX_CONCURRENT_REQUESTS / _QUEUE_SIZE / _QUEUE_TIMEOUT (FR-022).","type":"integer"},"max_result_size_chars":{"description":"MaxResultSizeChars is advertised on every tool as\n` + "`" + `_meta.anthropic/maxResultSizeChars` + "`" + `; it raises Claude Code's\ninline-response ceiling from 50k to up to 500k chars. Omit the key for\nthe 500000 default; set it to 0 to disable the annotation.","type":"integer"},"mcpServers":{"items":{"$ref":"#/components/schemas/config.ServerConfig"},"type":"array","uniqueItems":false},"oauth_expiry_warning_hours":{"description":"Health status settings","type":"number"},"observability":{"$ref":"#/components/schemas/config.ObservabilityConfig"},"output_sanitisation":{"$ref":"#/components/schemas/config.OutputSanitisationConfig"},"output_validation":{"$ref":"#/components/schemas/config.OutputValidationConfig"},"profiles":{"description":"Profiles are optional named, server-scoped views exposed at /mcp/p/\u003cname\u003e\n(Spec 057). Absent/empty is fully supported — /mcp is unchanged and configs\nwithout this key serialize byte-identically (SC-004).","items":{"$ref":"#/components/schemas/config.ProfileConfig"},"type":"array","uniqueItems":false},"quarantine_enabled":{"description":"QuarantineEnabled controls whether quarantine is active. It gates two\nthings together:\n  1. Server-level auto-quarantine for newly added servers (issue #370).\n     When true, servers added via the upstream_servers MCP tool or the\n     REST API default to quarantined=true; when false, they default to\n     quarantined=false. Explicit per-request values always win.\n  2. Tool-level quarantine (Spec 032): per-tool SHA-256 approval of\n     tool descriptions/schemas.\nWhen nil (default), quarantine is enabled (secure by default). Set to\nexplicit false to opt out of both. Per-server SkipQuarantine still\napplies for the tool-level check on individual servers.","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"read_only_mode":{"type":"boolean"},"registries":{"description":"Registries configuration for MCP server discovery","items":{"$ref":"#/components/schemas/config.RegistryEntry"},"type":"array","uniqueItems":false},"registries_locked":{"description":"RegistriesLocked is an enterprise stub knob (MCP-866): when true, runtime\nadditions of custom registries (e.g. ` + "`" + `registry add-source` + "`" + `, the REST/MCP\nadd-source surface) are rejected so an administrator can pin the discovery\nsources. Built-in defaults are unaffected. Documented but otherwise inert\nbeyond the add-source rejection.","type":"boolean"},"require_mcp_auth":{"description":"Require authentication on /mcp endpoint (default: false)","type":"boolean"},"reveal_secret_headers":{"description":"RevealSecretHeaders, when true, disables the redaction of the\nsecret-bearing server fields — sensitive header values (Authorization,\nX-API-Key, Cookie, …), env-var secrets, and URL query credentials — in\nresponses from the ` + "`" + `upstream_servers` + "`" + ` MCP tool, the ` + "`" + `/api/v1/servers` + "`" + `\nREST API, and the SSE event stream. It also lets URL secrets echoed\ninto last_error / health.detail through unscrubbed.\n\nDefault false — sensitive values are surfaced masked as\n` + "`" + `••••\u003clast2\u003e (\u003cN\u003e chars)` + "`" + ` (error strings use ` + "`" + `***REDACTED***` + "`" + `) so an\nMCP agent cannot read Bearer tokens / API keys / URL secrets out of\nanother upstream's config (PR #425, issue #872). ${env:…}/${keyring:…}\nreferences are labels, not secrets, and pass through unchanged.\n\nThe Web UI / macOS tray edit forms work without seeing the real\nvalues: PATCH /api/v1/servers/{id} deep-merges (omitted keys are\npreserved, see ` + "`" + `headers_remove` + "`" + ` / ` + "`" + `env_remove` + "`" + ` for explicit\ndeletes), so clients compute a diff and only send the keys that\nactually changed. Redacted-but-unchanged values never round-trip\n— the backend keeps the real string. Set this to true if a\ndownstream tool genuinely needs raw values in the response.","type":"boolean"},"routing_mode":{"description":"Routing mode (Spec 031): how MCP tools are exposed to clients\nValid values: \"retrieve_tools\" (default), \"direct\", \"code_execution\"","type":"string"},"security":{"$ref":"#/components/schemas/config.SecurityConfig"},"sensitive_data_detection":{"$ref":"#/components/schemas/config.SensitiveDataDetectionConfig"},"server_concurrency_defaults":{"$ref":"#/components/schemas/config.ConcurrencyDefaults"},"telemetry":{"$ref":"#/components/schemas/config.TelemetryConfig"},"tls":{"$ref":"#/components/schemas/config.TLSConfig"},"tokenizer":{"$ref":"#/components/schemas/config.TokenizerConfig"},"tool_call_max_records_per_server":{"description":"Calls retained per server (default: 1000)","type":"integer"},"tool_call_max_response_size":{"description":"Bounds for the per-server tool-call history behind GET /api/v1/tool-calls\n(#1176). It is a recent-debugging window, not an audit log — the activity\nlog is the durable record — and it kept every upstream response whole,\nper server, forever. A non-positive value means \"use the default\", not\n\"disable\": this store must never be unbounded again, so there is\ndeliberately no off switch.","type":"integer"},"tool_discovery_interval":{"type":"string"},"tool_response_limit":{"type":"integer"},"tool_response_mode":{"description":"Tool response mode (Spec 085): how retrieve_tools serializes results.\nValid values: \"\" (= full), \"full\" (default: today's schema-bearing\nentries), \"compact\" (signature + first-sentence entries). Orthogonal to\nrouting_mode — routing_mode selects the tool SURFACE, this selects the\nSERIALIZATION within the retrieve_tools surface. Serialization-only: it\nnever affects the query, ranking, or result set. Hot-reloadable.","type":"string"},"tool_response_session_risk_warning":{"description":"ToolResponseSessionRiskWarning controls whether the prose ` + "`" + `warning` + "`" + ` field\nis included in the ` + "`" + `session_risk` + "`" + ` object returned by ` + "`" + `retrieve_tools` + "`" + `.\nThe structured fields (level, lethal_trifecta, has_open_world_tools, etc.)\nare always included. Default: false (quiet for LLM clients) — see issue #406.\nMost tools lack annotations, so the MCP-spec defaults treat them as fully\npermissive across all three risk axes, which makes the prose warning fire\non almost every call and wastes tokens.","type":"boolean"},"tools_limit":{"type":"integer"},"toon_min_savings_pct":{"description":"ToonMinSavingsPct is the minimum byte-savings percentage (validated\n1-90; 0/unset → 15) the complete TOON emission (marker + hint + body)\nmust achieve over the exact passthrough emission for adaptive mode to\nencode a block. Byte savings approximate token savings for the tabular\npayload class; the spec-083 profiler reports true token deltas.\nGlobal-only (no per-server override, FR-001).","type":"integer"},"toon_output":{"description":"ToonOutput selects the TOON encoding mode for call_tool_* result text\nblocks (spec 084): \"off\" (default — responses byte-identical to\npre-feature behavior), \"adaptive\" (encode only tabular-uniform payloads\nthat beat compact JSON by ToonMinSavingsPct), or \"always\"\n(benchmark/debug only — encodes every JSON-parseable block and can\nINCREASE token cost). Per-server override: ServerConfig.ToonOutput.\nResolved by ResolveToonOutput; hot-reloadable.","type":"string"},"top_k":{"description":"Deprecated: TopK is superseded by ToolsLimit and has no runtime effect. Kept for backward compatibility.","type":"integer"},"tray_endpoint":{"description":"Tray endpoint override (unix:// or npipe://)","type":"string"},"trusted_hosts":{"description":"TrustedHosts lists non-loopback Host header values accepted on loopback\nlisteners (GH #898). DNS-rebinding protection rejects requests whose Host\nheader is not a loopback address when mcpproxy listens on loopback; a\nreverse proxy (nginx → 127.0.0.1) forwarding the public domain in Host\ntrips it. Entries are hostnames, case-insensitive; an entry without a\nport matches any port, with a port it must match exactly; a leading dot\n(\".example.com\") is a subdomain wildcard. The single entry \"*\" disables\nHost and Origin validation entirely. The same list also validates the\nOrigin header when present (MCP spec DNS-rebinding defense). Empty\n(default) keeps full protection. Env override: MCPPROXY_TRUSTED_HOSTS\n(comma-separated).","items":{"type":"string"},"type":"array","uniqueItems":false},"trusted_proxies":{"description":"TrustedProxies lists the CIDRs or IP addresses whose X-Forwarded-For /\nX-Real-IP / X-Forwarded-Proto / X-Forwarded-Host headers are believed\n(Spec 107 FR-027). Empty (default) trusts nobody. Edition-neutral, live\n(hot-reloadable). Env override: MCPPROXY_TRUSTED_PROXIES (comma-separated).\nThe one reader is ForwardedHeaders; validation is validateTrustedProxies.","items":{"type":"string"},"type":"array","uniqueItems":false},"update_check":{"$ref":"#/components/schemas/config.UpdateCheckConfig"}},"type":"object"},"config.CustomPattern":{"properties":{"category":{"description":"Category (defaults to \"custom\")","type":"string"},"keywords":{"description":"Keywords to match (mutually exclusive with Regex)","items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"description":"Unique identifier for this pattern","type":"string"},"regex":{"description":"Regex pattern (mutually exclusive with Keywords)","type":"string"},"severity":{"description":"Risk level: critical, high, medium, low","type":"string"}},"type":"object"},"config.DeepScanConfig":{"description":"DeepScan is the opt-in \"deep scan\" layer (Spec 077 US3). It subsumes the\ndeprecated top-level scanner_fetch_package_source / scanner_disable_no_new_privileges\nkeys (migrated on load) and gates the heavy Docker-based scanners + source\nextraction. Disabled by default (FR-006): only the deterministic in-process\nbaseline scanner runs. A deep-scan failure NEVER changes the baseline verdict\n(FR-007/FR-008).","properties":{"disable_no_new_privileges":{"description":"DisableNoNewPrivileges, when true, omits the ` + "`" + `--security-opt\nno-new-privileges` + "`" + ` flag from scanner container runs (snap-docker/AppArmor\nescape hatch). Absorbs the deprecated top-level\nscanner_disable_no_new_privileges. Default false.","type":"boolean"},"enabled":{"description":"Enabled is the master opt-in for the heavy layer (FR-006). Default false.","type":"boolean"},"fetch_package_source":{"description":"FetchPackageSource controls whether the scanner fetches the PUBLISHED\nsource of package-runner servers (npx/uvx) — without executing it — when\nno local source is available. Absorbs the deprecated top-level\nscanner_fetch_package_source. Default (nil) is ENABLED within deep scan.","type":"boolean"},"scanners":{"description":"Scanners optionally restricts which deep scanners may run under the\numbrella (by scanner id). Empty ⇒ all enabled deep scanners are eligible.","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.DockerIsolationConfig":{"description":"Docker isolation settings","properties":{"cpu_limit":{"description":"CPU limit for containers","type":"string"},"default_images":{"additionalProperties":{"type":"string"},"description":"Map of runtime type to Docker image","type":"object"},"enable_cache_volume":{"description":"Mount shared cache volumes for faster restarts (default: true)","type":"boolean"},"enabled":{"description":"Global enable/disable for Docker isolation (legacy; superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments","items":{"type":"string"},"type":"array","uniqueItems":false},"log_driver":{"description":"Docker log driver (default: json-file)","type":"string"},"log_max_files":{"description":"Maximum number of log files (default: 3)","type":"string"},"log_max_size":{"description":"Maximum size of log files (default: 100m)","type":"string"},"memory_limit":{"description":"Memory limit for containers","type":"string"},"mode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"network_mode":{"description":"Docker network mode (default: bridge)","type":"string"},"registry":{"description":"Custom registry (defaults to docker.io)","type":"string"},"timeout":{"description":"Container startup timeout","type":"string"}},"type":"object"},"config.DockerRecoveryConfig":{"description":"Docker recovery settings","properties":{"enabled":{"description":"Enable Docker recovery monitoring (default: true)","type":"boolean"},"max_retries":{"description":"Maximum retry attempts (0 = unlimited)","type":"integer"},"notify_on_failure":{"description":"Show notification on recovery failure (default: true)","type":"boolean"},"notify_on_retry":{"description":"Show notification on each retry (default: false)","type":"boolean"},"notify_on_start":{"description":"Show notification when recovery starts (default: true)","type":"boolean"},"notify_on_success":{"description":"Show notification on successful recovery (default: true)","type":"boolean"},"persistent_state":{"description":"Save recovery state across restarts (default: true)","type":"boolean"}},"type":"object"},"config.FeatureFlags":{"description":"Deprecated: Features flags are unused and have no runtime effect. Kept for backward compatibility.","properties":{"enable_async_storage":{"type":"boolean"},"enable_caching":{"type":"boolean"},"enable_contract_tests":{"type":"boolean"},"enable_debug_logging":{"description":"Development features","type":"boolean"},"enable_docker_isolation":{"type":"boolean"},"enable_event_bus":{"type":"boolean"},"enable_health_checks":{"type":"boolean"},"enable_metrics":{"type":"boolean"},"enable_oauth":{"description":"Security features","type":"boolean"},"enable_observability":{"description":"Observability features","type":"boolean"},"enable_quarantine":{"type":"boolean"},"enable_runtime":{"description":"Runtime features","type":"boolean"},"enable_search":{"description":"Storage features","type":"boolean"},"enable_sse":{"type":"boolean"},"enable_tracing":{"type":"boolean"},"enable_tray":{"type":"boolean"},"enable_web_ui":{"description":"UI features","type":"boolean"}},"type":"object"},"config.IntentDeclarationConfig":{"description":"Intent declaration settings (Spec 018)","properties":{"strict_server_validation":{"description":"StrictServerValidation controls whether server annotation mismatches\ncause rejection (true) or just warnings (false).\nDefault: true (reject mismatches)","type":"boolean"}},"type":"object"},"config.IsolationConfig":{"description":"Per-server isolation settings","properties":{"enabled":{"description":"Enable Docker isolation for this server (nil = inherit global; legacy, superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments for this server","items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"description":"Custom Docker image (overrides default)","type":"string"},"log_driver":{"description":"Docker log driver override for this server","type":"string"},"log_max_files":{"description":"Maximum number of log files override","type":"string"},"log_max_size":{"description":"Maximum size of log files override","type":"string"},"mode":{"$ref":"#/components/schemas/config.IsolationMode"},"network_mode":{"description":"Custom network mode for this server","type":"string"},"working_dir":{"description":"Custom working directory in container","type":"string"}},"type":"object"},"config.IsolationMode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"config.LogConfig":{"description":"Logging configuration","properties":{"compress":{"type":"boolean"},"enable_console":{"type":"boolean"},"enable_file":{"type":"boolean"},"filename":{"type":"string"},"json_format":{"type":"boolean"},"level":{"type":"string"},"log_dir":{"description":"Custom log directory","type":"string"},"max_age":{"description":"days","type":"integer"},"max_backups":{"description":"number of backup files","type":"integer"},"max_size":{"description":"MB","type":"integer"}},"type":"object"},"config.MetricsExporterConfig":{"description":"Metrics gates the Prometheus /metrics scrape endpoint (MCP-32). Disabled\nby default — operators opt in for k8s/enterprise deployments.","properties":{"enabled":{"description":"Enabled exposes /metrics on the existing HTTP listener when true.\nThe endpoint is admin-authenticated (SEC-07): scrapers must present the\nglobal API key, via X-API-Key or an Authorization: Bearer header.","type":"boolean"}},"type":"object"},"config.OAuthConfig":{"description":"OAuth configuration (keep even when empty to signal OAuth requirement)","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"description":"Additional OAuth parameters (e.g., RFC 8707 resource)","type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_uri":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ObservabilityConfig":{"description":"Observability settings (Spec 069): usage aggregate cache/persistence cadence.","properties":{"metrics":{"$ref":"#/components/schemas/config.MetricsExporterConfig"},"tracing":{"$ref":"#/components/schemas/config.TracingExporterConfig"},"usage_cache_ttl":{"description":"UsageCacheTTL bounds the freshness of the usage endpoint's read cache for\nwide windows (FR-005). Default 5s.","type":"string"},"usage_persist_interval":{"description":"UsagePersistInterval is how often the actor-owned usage aggregate snapshot\nis flushed to storage. Default 30s.","type":"string"}},"type":"object"},"config.OutputSanitisationConfig":{"description":"Output sanitisation settings (Spec 054 Track B)","properties":{"max_redactions":{"description":"cap on redactions per response; default 100","type":"integer"},"response_action":{"description":"\"spotlight\" | \"redact\" | \"block\"; default \"spotlight\"","type":"string"},"spotlight_untrusted":{"description":"wrap untrusted output in spotlight markers; default true","type":"boolean"},"strip_classes":{"description":"classes to strip: ansi/c0c1/bidi/zero_width","items":{"type":"string"},"type":"array","uniqueItems":false},"strip_control_chars":{"description":"strip control-character classes; default false","type":"boolean"}},"type":"object"},"config.OutputValidationConfig":{"description":"Output-schema validation settings (Spec 056)","properties":{"max_bytes":{"description":"structured payload byte cap; default 5\u003c\u003c20","type":"integer"},"max_depth":{"description":"nesting depth cap; default 64","type":"integer"},"missing_structured_content":{"description":"\"allow\" | \"block\"; default \"allow\"","type":"string"},"mode":{"description":"\"off\" | \"warn\" | \"strict\"; default \"warn\"","type":"string"}},"type":"object"},"config.ProfileConfig":{"properties":{"name":{"description":"URL slug, validated","type":"string"},"servers":{"description":"references to mcpServers[].name","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.RegistryEntry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag for this registry (MCP-866):\nRegistryProvenanceOfficial for built-in defaults, RegistryProvenanceCustom\nfor user-added registries. It is authoritatively (re)computed by the\nregistries merge from whether the ID is a shipped default — a user cannot\nclaim \"official\" by writing it into their config.","type":"string"},"requires_key":{"description":"RequiresKey marks a registry that needs an API key to be queried. When\ntrue and no key is configured, the registry is skipped/marked unavailable\nrather than failing the whole search (FR-008).","type":"boolean"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"type":"string"}},"type":"object"},"config.SecurityConfig":{"description":"Security scanner settings (Spec 039)","properties":{"auto_baseline_scan":{"description":"AutoBaselineScan is the kill-switch for the AUTOMATIC, informational\nPass-1 baseline scan: the free in-process TPA scan mcpproxy runs for every\nnewly admitted server (any trust mode) and, once per installation, over\npre-existing servers that have never been scanned.\n\nInformational ONLY: the resulting verdict populates the security badge and\nthe scan summary, and NEVER gates quarantine or approval. The\ntrust_mode:\"scan\" admission gate is a separate path and is unaffected by\nthis flag.\n\nDefault (nil) is ENABLED. Set to false to suppress every automatic scan\n(manual scans keep working). Env override: MCPPROXY_AUTO_BASELINE_SCAN,\nwhich wins over this field on every path.","type":"boolean"},"deep_scan":{"$ref":"#/components/schemas/config.DeepScanConfig"},"integrity_check_interval":{"type":"string"},"integrity_check_on_restart":{"type":"boolean"},"runtime_read_only":{"type":"boolean"},"runtime_tmpfs_size":{"type":"string"},"scan_timeout_default":{"type":"string"},"scanner_disable_no_new_privileges":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.DisableNoNewPrivileges\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.IsDisableNoNewPrivileges. Cleared after migration.\n\nScannerDisableNoNewPrivileges, when true, omits the\n` + "`" + `--security-opt no-new-privileges` + "`" + ` flag from scanner container runs.\n\nBackground: snap-installed Docker on Ubuntu confines dockerd under the\n` + "`" + `snap.docker.dockerd` + "`" + ` AppArmor profile. When runc tries to transition\nthe container into the inner ` + "`" + `docker-default` + "`" + ` profile to exec the\nentrypoint, AppArmor refuses the transition because NO_NEW_PRIVS\nforbids privilege/profile changes on exec — the result is EPERM\n(\"operation not permitted\") and every scanner fails immediately.\n\nSet this to true ONLY on hosts hitting that incompatibility. Scanner\ncontainers still run with read-only rootfs, tmpfs /tmp, no-network by\ndefault, and read-only source mounts, so the marginal isolation loss\nis small. The preferred fix remains replacing snap docker with a\ndistro-packaged docker.","type":"boolean"},"scanner_fetch_package_source":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.FetchPackageSource\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.EffectiveFetchPackageSource. Cleared after migration.\n\nScannerFetchPackageSource controls whether the scanner fetches the\nPUBLISHED source of package-runner servers (npx/uvx) — without executing\nit — when no local source is available (no Docker container, no local\npackage cache, no working_dir). This is the primary quarantine/scan\ntarget: a quarantined-on-add server is never run locally, so without this\nthe scan degrades to tool-definitions-only (no real source-level\nanalysis). See MCP-2206.\n\nFetching uses ` + "`" + `npm pack --ignore-scripts` + "`" + ` (npm) and ` + "`" + `uv pip download` + "`" + ` /\n` + "`" + `pip download` + "`" + ` with ` + "`" + `--only-binary=:all:` + "`" + ` (Python), which only download +\nunpack archives and NEVER run install, build, or setup.py — a scanner must\nnot execute the untrusted code it is scanning. The Python\n` + "`" + `--only-binary=:all:` + "`" + ` flag is required because downloading an sdist would\ninvoke its build backend (setup.py); packages with no wheel fall back to\ntool-definitions-only instead. Extraction is hardened against path\ntraversal and decompression bombs.\n\nDefault (nil) is ENABLED. Set to false on air-gapped deployments to\nforbid the scanner's network egress; such servers then fall back to the\ntool-definitions-only scan with no regression.","type":"boolean"},"scanner_registry_url":{"type":"string"},"tpa_bundle_path":{"description":"TPABundlePath is the filesystem path to the tpa-db scanner-bundle.json\nthe offline TPA scanner runs (spec 086 FR-019: the signature-DB location\nMUST be configuration-driven, not hardcoded). Empty (the default) runs the\ncorpus embedded in this build.\n\nEnv override: MCPPROXY_TPA_BUNDLE_PATH. Hot-reloadable — the path is\nre-read on every config.reloaded event via\nscanner.Service.ApplySecurityConfig, so a corpus refresh needs no restart.\nA configured bundle that fails to read/parse/version-check/compile is\nREFUSED and the previously active corpus stays live (fail-closed, never\nfail-empty); the reason is logged and surfaced in the security overview's\nsignature_bundle.load_error.","type":"string"}},"type":"object"},"config.SensitiveDataDetectionConfig":{"description":"Sensitive data detection settings (Spec 026)","properties":{"categories":{"additionalProperties":{"type":"boolean"},"description":"Enable/disable specific detection categories","type":"object"},"custom_patterns":{"description":"User-defined detection patterns","items":{"$ref":"#/components/schemas/config.CustomPattern"},"type":"array","uniqueItems":false},"enabled":{"description":"Enable sensitive data detection (default: true)","type":"boolean"},"entropy_threshold":{"description":"Shannon entropy threshold for high-entropy detection (default: 4.5)","type":"number"},"max_payload_size_kb":{"description":"Max size to scan before truncating (default: 1024)","type":"integer"},"scan_requests":{"description":"Scan tool call arguments (default: true)","type":"boolean"},"scan_responses":{"description":"Scan tool responses (default: true)","type":"boolean"},"sensitive_keywords":{"description":"Keywords to flag","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ServerConfig":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve tool\nchanges/additions (disabling per-server rug-pull protection). Supersedes\nskip_quarantine. MCP-2930 only ACCEPTS, persists, and migrates this flag — it\nis NOT yet consulted at runtime; auto-approval is still governed by\nSkipQuarantine until the trust-baseline behavior change (MCP-2931) migrates the\nruntime consumers onto it.\nTri-state pointer (mirrors QuarantineEnabled): nil = unset (inherit/migrate\nfrom legacy skip_quarantine), explicit true/false = honored as-is so an\nexplicit auto_approve_tool_changes:false overrides a legacy skip_quarantine:true.\nRead via IsAutoApproveToolChanges().","type":"boolean"},"command":{"type":"string"},"created":{"type":"string"},"disabled_tools":{"description":"Denylist: these tools are hidden; mutually exclusive with enabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"},"enabled_tools":{"description":"Allowlist: only these tools are exposed; mutually exclusive with disabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts overrides whether this server's advertised MCP prompts are\naggregated into mcpproxy's prompts/list. nil (default) inherits the\ndefault-aggregate behavior (included if the server advertises\nCapabilities.Prompts); false excludes it regardless of capability.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"description":"For HTTP servers","type":"object"},"health_check_interval":{"description":"Per-server discovery \u0026 health-check overrides (spec 074). Same *Duration\ntri-state as the global keys: nil = inherit the global value (or default),\npointer to 0s = disabled for this server, positive = that interval.\nHealthCheckInterval is fully wired into the per-server health loop;\nToolDiscoveryInterval is accepted/validated and round-trips for\nforward-compat, but the periodic index sweep is governed by the global\ncadence in this iteration (see spec 074 plan §C).","type":"string"},"init_timeout":{"description":"InitTimeout overrides the global init_timeout for this server's MCP\n` + "`" + `initialize` + "`" + ` handshake deadline (MCP-3322 / GH #760). *Duration tri-state:\nnil = inherit the global value (or 30s default), positive = that deadline.\nResolved by Config.ResolveInitTimeout; validated to {0} ∪ [1s, 30m]. Raise\nthis for upstreams that do legitimate first-run warmup (e.g. caching many\nchannels/users) before responding to ` + "`" + `initialize` + "`" + `.","type":"string"},"isolation":{"$ref":"#/components/schemas/config.IsolationConfig"},"launcher_wait_timeout":{"description":"LauncherWaitTimeout caps how long mcpproxy will wait for a locally-launched\nHTTP/SSE upstream's URL to become reachable after Spawn(). Only consulted\nwhen the server is configured with both Command and an HTTP/SSE URL — i.e.,\nmcpproxy starts the process AND connects via network. Stdio servers ignore\nthis field. Zero or unset → 30s default.","type":"string"},"max_concurrent_requests":{"description":"Per-server concurrency overrides — scope (c) of FR-020 (spec 093, #955).\nTri-state per setting, exactly like HealthCheckInterval: absent = inherit\nthe per-server default set (server_concurrency_defaults), explicit 0 =\ndisable that setting for this server (0 max = no per-server limiter at\nall; 0 queue_size = no pending capacity, shed immediately at the cap),\npositive = override. The global aggregate limiter is never inherited from\nhere — it applies on top, so effective concurrency is min(per-server,\nglobal). Resolved by Config.ResolveServerConcurrency.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/config.OAuthConfig"},"protocol":{"description":"stdio, http, sse, streamable-http, auto","type":"string"},"quarantined":{"description":"Security quarantine status","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets a disconnected server","type":"boolean"},"shared":{"description":"Server edition: shared with all users","type":"boolean"},"skip_quarantine":{"description":"SkipQuarantine is DEPRECATED (MCP-2930): use AutoApproveToolChanges instead.\nKept for back-compat parsing; on config load a legacy skip_quarantine:true is\nmigrated to auto_approve_tool_changes:true only when the new field is unset\n(see normalizeServerQuarantineFlags).","type":"boolean"},"source_registry_id":{"description":"SourceRegistryID records which registry this server was added from (empty\nfor manually-configured servers). MCP-866: surfaced in the approval /\nquarantine view so a reviewer can see a server's origin.","type":"string"},"source_registry_provenance":{"description":"SourceRegistryProvenance records the source registry's provenance at add\ntime (RegistryProvenanceOfficial / RegistryProvenanceCustom). It is purely\ninformational (MCP-1072) — surfaced so a reviewer can see a server's origin\n— and no longer gates quarantine or skip_quarantine.","type":"string"},"tool_discovery_interval":{"type":"string"},"toon_output":{"description":"ToonOutput overrides the global toon_output mode for this server's\ntools (spec 084, FR-001). Plain string, not a pointer: \"\"/absent =\ninherit the global value; \"off\"|\"adaptive\"|\"always\" = override (\"off\"\nis the explicit force-off). Resolved by Config.ResolveToonOutput.","type":"string"},"trust_mode":{"description":"TrustMode is the per-server trust tier: auto|scan|manual. Supersedes\nauto_approve_tool_changes (spec 086). An empty value is derived from the\nlegacy fields at load via normalizeServerQuarantineFlags; the single\nresolution point is EffectiveTrustMode(), which treats an empty or\nunrecognized value as manual (secure by default). Read via\nEffectiveTrustMode(), never the raw string.","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"working_dir":{"description":"Working directory for stdio servers","type":"string"}},"type":"object"},"config.TLSConfig":{"description":"TLS configuration","properties":{"certs_dir":{"description":"Directory for certificates","type":"string"},"enabled":{"description":"Enable HTTPS","type":"boolean"},"hsts":{"description":"Enable HTTP Strict Transport Security","type":"boolean"},"require_client_cert":{"description":"Enable mTLS","type":"boolean"}},"type":"object"},"config.TelemetryConfig":{"description":"Telemetry settings (Spec 036)","properties":{"anonymous_id":{"description":"Auto-generated UUIDv4","type":"string"},"anonymous_id_created_at":{"description":"Spec 042 (Tier 2) additions — all default-zero, all backwards-compatible.","type":"string"},"enabled":{"description":"Default: true (opt-out)","type":"boolean"},"endpoint":{"description":"Override for testing","type":"string"},"last_reported_version":{"description":"Upgrade funnel","type":"string"},"last_startup_outcome":{"description":"success|port_conflict|db_locked|...","type":"string"},"notice_shown":{"description":"First-run notice flag","type":"boolean"}},"type":"object"},"config.TokenizerConfig":{"description":"Tokenizer configuration for token counting","properties":{"default_model":{"description":"Default model for tokenization (e.g., \"gpt-4\")","type":"string"},"enabled":{"description":"Enable token counting","type":"boolean"},"encoding":{"description":"Default encoding (e.g., \"cl100k_base\")","type":"string"}},"type":"object"},"config.TracingExporterConfig":{"description":"Tracing gates the OpenTelemetry OTLP trace exporter (MCP-32). Disabled by\ndefault.","properties":{"enabled":{"description":"Enabled turns on OTLP trace export for tool calls and upstream hops.","type":"boolean"},"endpoint":{"description":"Endpoint is the collector address as host:port (no scheme), e.g.\n\"localhost:4318\" for http or \"localhost:4317\" for grpc.","type":"string"},"protocol":{"description":"Protocol selects the OTLP transport: \"http\" or \"grpc\".","type":"string"},"sample_rate":{"description":"SampleRate is the head-based trace sampling ratio in [0,1]. Default 0.1.\nOmit the key for the 0.1 default; set it to 0 to sample nothing.","type":"number"}},"type":"object"},"config.UpdateCheckConfig":{"description":"Update-check settings (Spec 079 FR-012): config-file control of the\nbackground upgrade-awareness checker (internal/updatecheck). nil =\nenabled on the stable channel (existing default behavior). The existing\nenvironment switches keep working and WIN over these keys (FR-014):\nMCPPROXY_DISABLE_AUTO_UPDATE=true force-disables even when\nenabled=true, and MCPPROXY_ALLOW_PRERELEASE_UPDATES=true force-selects\nthe rc channel even when channel=stable.","properties":{"channel":{"description":"Channel selects which releases are offered as updates: \"stable\"\n(default; prereleases never offered) or \"rc\" (prereleases included).\nEmpty resolves to stable. Validated in ValidateDetailed.\n\nNOTE: for a RELEASED build the running binary's own version is\nauthoritative and overrides this field — a stable build is never\noffered an RC (even with channel=rc), and an RC build always tracks the\nrc channel. This field only takes effect on dev/unstamped builds. See\ninternal/updatecheck.Checker.IncludePrereleases.","type":"string"},"enabled":{"description":"Enabled gates all update checking. Tri-state: nil/absent = enabled\n(default true, matching pre-079 behavior). When false, no network\ncheck is performed and no upgrade nudge appears on any surface\n(FR-015) — /api/v1/info omits the update object entirely.","type":"boolean"}},"type":"object"},"configimport.FailedServer":{"properties":{"details":{"type":"string"},"error":{"type":"string"},"name":{"type":"string"}},"type":"object"},"configimport.ImportSummary":{"properties":{"failed":{"type":"integer"},"imported":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"configimport.SkippedServer":{"properties":{"name":{"type":"string"},"reason":{"description":"\"already_exists\", \"filtered_out\", \"invalid_name\"","type":"string"}},"type":"object"},"connect.ConnectResult":{"description":"The full result; its action mirrors the top-level one","properties":{"action":{"description":"\"created\", \"updated\", \"already_exists\", \"removed\", \"not_found\"","type":"string"},"backup_path":{"type":"string"},"client":{"type":"string"},"config_path":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.APIResponse":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ActivityDetailResponse":{"properties":{"activity":{"$ref":"#/components/schemas/contracts.ActivityRecord"}},"type":"object"},"contracts.ActivityListResponse":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/contracts.ActivityRecord"},"type":"array","uniqueItems":false},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.ActivityRecord":{"properties":{"agent_name":{"description":"Agent token name when auth_type is \"agent\"","type":"string"},"arguments":{"description":"Tool call arguments","type":"object"},"auth_type":{"description":"\"admin\", \"agent\", \"user\" or \"admin_user\"; empty without an auth context or on another caller's row for a scoped caller","type":"string"},"detection_types":{"description":"List of detection types found","items":{"type":"string"},"type":"array","uniqueItems":false},"duration_ms":{"description":"Execution duration in milliseconds","type":"integer"},"error_message":{"description":"Error details if status is \"error\"","type":"string"},"has_sensitive_data":{"description":"Sensitive data detection fields (Spec 026)","type":"boolean"},"id":{"description":"Unique identifier (ULID format)","type":"string"},"max_severity":{"description":"Highest severity level detected (critical, high, medium, low)","type":"string"},"metadata":{"description":"Additional context-specific data","type":"object"},"parent_id":{"description":"Correlation id of the parent call (the code_execution whose sandbox issued this sub-call)","type":"string"},"request_bytes":{"description":"Byte sizes measured pre-truncation, mirroring storage.ActivityRecord\n(Spec 069 A1). They are the only cost signal a bodies-off export carries:\nwith payloads suppressed there is no text left to measure, so a consumer\naccounting for a record it cannot read has nothing else to go on. They are\nbyte LENGTHS, not token counts — the basis for an explicit estimate, never\na measured figure (spec 103, contracts/replay-input.md).\n\nZero means UNKNOWN, not free: legacy records predate the measurement and\ncode-execution sub-calls record both as zero. Hence omitempty — an absent\nkey tells a consumer to fall to exclusion accounting, whereas a present\nzero would read as a costless call and silently understate the workload.","type":"integer"},"request_id":{"description":"HTTP request ID for correlation","type":"string"},"response":{"description":"Tool response (potentially truncated)","type":"string"},"response_bytes":{"description":"Raw upstream response size in bytes before truncation","type":"integer"},"response_truncated":{"description":"True if response was truncated","type":"boolean"},"server_name":{"description":"Name of upstream MCP server","type":"string"},"session_id":{"description":"MCP transport session ID (regenerated on every reconnect)","type":"string"},"source":{"$ref":"#/components/schemas/contracts.ActivitySource"},"status":{"description":"Result status: \"success\", \"error\", \"blocked\", \"rejected\"","type":"string"},"timestamp":{"description":"When activity occurred","type":"string"},"tool_name":{"description":"Name of tool called","type":"string"},"type":{"$ref":"#/components/schemas/contracts.ActivityType"},"work_session_id":{"description":"Spec 082: one client, one project, across reconnects","type":"string"}},"type":"object"},"contracts.ActivitySource":{"description":"How activity was triggered: \"mcp\", \"cli\", \"api\"","type":"string","x-enum-varnames":["ActivitySourceMCP","ActivitySourceCLI","ActivitySourceAPI"]},"contracts.ActivitySummaryResponse":{"properties":{"blocked_count":{"description":"Count of blocked activities","type":"integer"},"call_count":{"description":"CallCount is how many of those records are CALLS THE USER MADE, as\ndefined once in storage.CountsAsCall and shared with the usage aggregate\nbehind the Usage tab (audit finding F1, #1046). TotalCount answers \"how\nmany rows does the Activity Log have\"; CallCount answers \"how many calls\nwere there\". They are different questions — quarantine auto-approvals,\nsystem start, security scans and management chatter are events, not calls\n— and printing either one under the other's label is how the same instance\ncame to report 51 calls on one screen and 19 on another.","type":"integer"},"call_error_count":{"description":"CallErrorCount is the failures within CallCount, so an error RATE computed\nfrom this response has one denominator. It is not ErrorCount: a policy\nblock is a failed call but carries status \"blocked\", and a shed call is an\nerror in neither sense because it never ran.","type":"integer"},"end_time":{"description":"End of the period (RFC3339)","type":"string"},"error_count":{"description":"Count of error activities","type":"integer"},"other_count":{"description":"OtherCount is every record whose status is outside the four-value\nvocabulary above, so that\n\n\tsuccess + error + blocked + rejected + other == total\n\nholds by construction. The status field is a CLOSED vocabulary for tool\ncalls, but the activity log is wider than tool calls: a quarantine change\nstores its ACTION there (\"approved\", \"auto_approved\"), a policy decision\nstores its DECISION (\"allow\"). Those rows were counted in the total and in\nnone of the four buckets, so the Activity Log's own status tiles summed to\nless than the denominator printed beside them — 15+4+0+0 under a \"42\"\n(audit finding F2, #1046). The residual now has a name and a tile.","type":"integer"},"period":{"description":"Time period (1h, 24h, 7d, 30d)","type":"string"},"rejected_count":{"description":"RejectedCount is the number of calls shed by a concurrency limiter before\nthey reached an upstream (spec 093). Counted separately from errors: it is\nproxy backpressure, not an upstream fault, and it is the signal an\noperator right-sizes max_concurrent_requests against.","type":"integer"},"start_time":{"description":"Start of the period (RFC3339)","type":"string"},"success_count":{"description":"Count of successful activities","type":"integer"},"top_servers":{"description":"Top servers by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopServer"},"type":"array","uniqueItems":false},"top_tools":{"description":"Top tools by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopTool"},"type":"array","uniqueItems":false},"total_count":{"description":"Total activity count","type":"integer"}},"type":"object"},"contracts.ActivityTopServer":{"properties":{"count":{"description":"Activity count","type":"integer"},"name":{"description":"Server name","type":"string"}},"type":"object"},"contracts.ActivityTopTool":{"properties":{"count":{"description":"Activity count","type":"integer"},"server":{"description":"Server name","type":"string"},"tool":{"description":"Tool name","type":"string"}},"type":"object"},"contracts.ActivityType":{"description":"Type of activity","type":"string","x-enum-varnames":["ActivityTypeToolCall","ActivityTypePolicyDecision","ActivityTypeQuarantineChange","ActivityTypeServerChange"]},"contracts.AddFromRegistryRequest":{"properties":{"enabled":{"description":"defaults to true when nil","type":"boolean"},"env":{"additionalProperties":{"type":"string"},"description":"overrides + required-input values","type":"object"},"name":{"description":"optional name override","type":"string"}},"type":"object"},"contracts.AddRegistrySourceRequest":{"properties":{"id":{"description":"derived from the host when empty","type":"string"},"name":{"description":"defaults to the id","type":"string"},"protocol":{"description":"defaults to modelcontextprotocol/registry","type":"string"},"url":{"description":"required https registry URL","type":"string"}},"type":"object"},"contracts.ConfigApplyResult":{"properties":{"applied_immediately":{"type":"boolean"},"changed_fields":{"items":{"type":"string"},"type":"array","uniqueItems":false},"requires_restart":{"type":"boolean"},"restart_reason":{"type":"string"},"success":{"type":"boolean"},"validation_errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DCRStatus":{"properties":{"attempted":{"type":"boolean"},"error":{"type":"string"},"status_code":{"type":"integer"},"success":{"type":"boolean"}},"type":"object"},"contracts.DeepScanDescriptor":{"description":"DeepScan reports the opt-in \"deep scan\" layer status (Spec 077 US3),\nSEPARATELY from the baseline verdict above. Always emitted on a computed\nsummary — when deep scan is off (the default) it reports enabled=false\nplus any enabled-but-skipped Docker scanners. It never influences Status.","properties":{"available":{"type":"boolean"},"enabled":{"type":"boolean"},"ran":{"type":"boolean"},"scanners_failed":{"items":{"$ref":"#/components/schemas/contracts.DeepScanScannerFailure"},"type":"array","uniqueItems":false},"skipped_scanners":{"description":"SkippedScanners lists Docker scanners the user enabled that are skipped\nbecause security.deep_scan.enabled is false (informational).","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DeepScanScannerFailure":{"properties":{"id":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"contracts.DeprecatedConfigWarning":{"properties":{"field":{"type":"string"},"message":{"type":"string"},"replacement":{"type":"string"}},"type":"object"},"contracts.Diagnostic":{"description":"Spec 044 — structured diagnostic error and stable error code. Both\nare populated when the server is in a failed state and the error\nhas been classified by internal/diagnostics. Healthy servers omit\nthese fields.","properties":{"cause":{"type":"string"},"code":{"type":"string"},"detected_at":{"type":"string"},"docs_url":{"type":"string"},"fix_steps":{"items":{"$ref":"#/components/schemas/contracts.DiagnosticFixStep"},"type":"array","uniqueItems":false},"severity":{"type":"string"},"user_message":{"type":"string"}},"type":"object"},"contracts.DiagnosticFixStep":{"properties":{"command":{"type":"string"},"destructive":{"type":"boolean"},"fixer_key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"}},"type":"object"},"contracts.Diagnostics":{"properties":{"deprecated_configs":{"description":"Deprecated config fields found","items":{"$ref":"#/components/schemas/contracts.DeprecatedConfigWarning"},"type":"array","uniqueItems":false},"docker_status":{"$ref":"#/components/schemas/contracts.DockerStatus"},"missing_secrets":{"description":"Renamed to avoid conflict","items":{"$ref":"#/components/schemas/contracts.MissingSecretInfo"},"type":"array","uniqueItems":false},"oauth_issues":{"description":"OAuth parameter mismatches","items":{"$ref":"#/components/schemas/contracts.OAuthIssue"},"type":"array","uniqueItems":false},"oauth_required":{"items":{"$ref":"#/components/schemas/contracts.OAuthRequirement"},"type":"array","uniqueItems":false},"runtime_warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false},"timestamp":{"type":"string"},"total_issues":{"type":"integer"},"upstream_errors":{"items":{"$ref":"#/components/schemas/contracts.UpstreamError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DockerStatus":{"properties":{"available":{"type":"boolean"},"error":{"type":"string"},"version":{"type":"string"}},"type":"object"},"contracts.EditRegistrySourceRequest":{"properties":{"name":{"description":"new display name","type":"string"},"servers_url":{"description":"explicit servers-collection URL","type":"string"},"url":{"description":"new base/servers https URL","type":"string"}},"type":"object"},"contracts.ErrorResponse":{"properties":{"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.FindingCounts":{"properties":{"dangerous":{"description":"Tool poisoning, active prompt injection","type":"integer"},"info":{"description":"Low-severity CVEs, informational","type":"integer"},"total":{"type":"integer"},"warning":{"description":"Rug pull, supply chain CVEs with exploits","type":"integer"}},"type":"object"},"contracts.GetConfigResponse":{"properties":{"config":{"description":"The configuration object","type":"object"},"config_path":{"description":"Path to config file","type":"string"}},"type":"object"},"contracts.GetRegistriesResponse":{"properties":{"registries":{"items":{"$ref":"#/components/schemas/contracts.Registry"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerLogsResponse":{"properties":{"count":{"type":"integer"},"logs":{"items":{"$ref":"#/components/schemas/contracts.LogEntry"},"type":"array","uniqueItems":false},"server_name":{"type":"string"}},"type":"object"},"contracts.GetServerToolCallsResponse":{"properties":{"server_name":{"type":"string"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerToolsResponse":{"properties":{"count":{"type":"integer"},"server_name":{"type":"string"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GetServersResponse":{"properties":{"servers":{"items":{"$ref":"#/components/schemas/contracts.Server"},"type":"array","uniqueItems":false},"stats":{"$ref":"#/components/schemas/contracts.ServerStats"}},"type":"object"},"contracts.GetSessionDetailResponse":{"properties":{"session":{"$ref":"#/components/schemas/contracts.MCPSession"}},"type":"object"},"contracts.GetSessionsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"sessions":{"items":{"$ref":"#/components/schemas/contracts.MCPSession"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetToolCallDetailResponse":{"properties":{"tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"}},"type":"object"},"contracts.GetToolCallsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GlobalToolsResponse":{"properties":{"failed_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"partial":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/contracts.GlobalToolsStats"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GlobalToolsStats":{"properties":{"disabled":{"type":"integer"},"enabled":{"type":"integer"},"pending_approval":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.HealthStatus":{"description":"Unified health status calculated by the backend","properties":{"action":{"description":"Action is the suggested fix action: \"login\", \"restart\", \"enable\", \"approve\", \"view_logs\", \"set_secret\", \"configure\", \"edit_url\", or \"\" (none)","type":"string"},"admin_state":{"description":"AdminState indicates the admin state: \"enabled\", \"disabled\", or \"quarantined\"","type":"string"},"detail":{"description":"Detail is an optional longer explanation of the status","type":"string"},"level":{"description":"Level indicates the health level: \"healthy\", \"degraded\", or \"unhealthy\"","type":"string"},"summary":{"description":"Summary is a human-readable status message (e.g., \"Connected (5 tools)\")","type":"string"}},"type":"object"},"contracts.InfoEndpoints":{"description":"Available API endpoints","properties":{"http":{"description":"HTTP endpoint address (e.g., \"127.0.0.1:8080\")","type":"string"},"socket":{"description":"Unix socket path (empty if disabled)","type":"string"}},"type":"object"},"contracts.InfoResponse":{"properties":{"endpoints":{"$ref":"#/components/schemas/contracts.InfoEndpoints"},"launched_by":{"description":"LaunchedBy is the durable launch provenance of the running core (Spec\n092 FR-001a): \"tray\" when a tray spawned it, \"installer\" when the macOS\nPKG postinstall did, \"\" when user-launched or unknown. Always present\n(possibly empty) so a tray can distinguish \"old core, not mine\" from\n\"old core I may supersede\".","type":"string"},"listen_addr":{"description":"Listen address (e.g., \"127.0.0.1:8080\")","type":"string"},"pid":{"description":"PID is the operating-system process id of the running core (Spec 092\nFR-002). A tray that merely ATTACHED to a core holds no Process handle\nfor it, so without this there is no mechanism at all to stop a stale\ncore — the consent action would have nothing to act on and could only\nprint instructions. Paired with LaunchedBy it is what lets a newer tray\nsupersede a core an older tray started.","type":"integer"},"update":{"$ref":"#/components/schemas/contracts.UpdateInfo"},"update_policy":{"$ref":"#/components/schemas/contracts.UpdatePolicy"},"version":{"description":"Current MCPProxy version","type":"string"},"web_ui_url":{"description":"URL to access the web control panel","type":"string"}},"type":"object"},"contracts.IsolationConfig":{"properties":{"cpu_limit":{"type":"string"},"enabled":{"description":"Enabled is the EFFECTIVE isolation state for this server: whether its\nprocess is actually CONFINED, after the global setting, the per-server\noverride, the structural gates and the host's capabilities. It is NOT the\nraw per-server override — read EnabledOverride for that (GH #1142).\n\nREAD-ONLY. The write surfaces reject an ` + "`" + `enabled` + "`" + ` key precisely because\nit is derived: echoing it back would convert \"inherits the global\nsetting\" into a permanent explicit override. Write EnabledOverride.\n\nIt stays a non-pointer bool that is always present on the wire: the macOS\ntray decodes it as a non-optional Swift Bool, so omitting or nulling the\nkey would fail Codable for the whole server payload. Older clients that\nread this field now simply get a true answer.","type":"boolean"},"enabled_override":{"description":"EnabledOverride is the RAW per-server ` + "`" + `isolation.enabled` + "`" + ` override, as\npersisted. Absent means \"inherit the global setting\" — which is a\ndistinct state from an explicit false, and the distinction the reporting\nbug used to destroy.","type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"memory_limit":{"type":"string"},"mode_override":{"description":"ModeOverride is the RAW per-server ` + "`" + `isolation.mode` + "`" + ` override\n(\"docker\" | \"sandbox\" | \"none\"). Absent means \"inherit\".","type":"string"},"network_mode":{"type":"string"},"timeout":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationDefaults":{"description":"IsolationDefaults exposes the resolved baseline values that\nwould apply when no per-server override is set. Populated on\nlist/get responses; never consumed on PATCH requests.","properties":{"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"network_mode":{"type":"string"},"runtime_type":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationEffective":{"description":"IsolationEffective exposes the resolved isolation state (and the rule\nthat decided it) so clients can distinguish \"inherits global\" from an\nexplicit per-server choice. Read-only; never consumed on PATCH.","properties":{"global_mode":{"description":"GlobalMode is what \"inherit\" resolves to right now.","type":"string"},"inherited":{"description":"Inherited is true when the server sets neither ` + "`" + `isolation.enabled` + "`" + ` nor\n` + "`" + `isolation.mode` + "`" + `, so its state tracks the global setting.","type":"boolean"},"isolated":{"description":"Isolated reports whether the process is actually CONFINED. It is NOT\nsimply Mode != \"none\": \"sandbox\" on a host that cannot enforce Landlock\n(any non-Linux OS, or a kernel without the LSM) runs the server\nunconfined, and Source then says \"sandbox-unavailable\" (GH #1142).","type":"boolean"},"mode":{"description":"Mode is the effective isolation mode: \"docker\" | \"sandbox\" | \"none\" —\nexactly what the spawn path branches on.","type":"string"},"source":{"description":"Source names the deciding rule: \"global\", \"server-mode\",\n\"server-opt-out\", \"server-opt-in-ignored\", \"not-stdio\",\n\"already-docker\", \"sandbox-unavailable\" or \"unsupported-mode\".\nTreat an unrecognized value as \"global\".","type":"string"}},"type":"object"},"contracts.LogEntry":{"properties":{"fields":{"type":"object"},"level":{"type":"string"},"message":{"type":"string"},"server":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.MCPSession":{"properties":{"client_name":{"type":"string"},"client_version":{"type":"string"},"end_time":{"type":"string"},"experimental":{"items":{"type":"string"},"type":"array","uniqueItems":false},"has_roots":{"description":"MCP Client Capabilities","type":"boolean"},"has_sampling":{"type":"boolean"},"id":{"type":"string"},"last_activity":{"type":"string"},"start_time":{"type":"string"},"status":{"type":"string"},"tool_call_count":{"type":"integer"},"total_tokens":{"type":"integer"},"work_session_id":{"type":"string"},"workspace_name":{"description":"Workspace / work session (Spec 082). WorkspaceName is the project's\nbasename — the full local path is never exposed. WorkSessionID groups the\nreconnects that make up one stretch of user work.","type":"string"}},"type":"object"},"contracts.MetadataStatus":{"properties":{"authorization_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"error":{"type":"string"},"found":{"type":"boolean"},"url_checked":{"type":"string"}},"type":"object"},"contracts.MissingSecretInfo":{"properties":{"secret_name":{"type":"string"},"used_by":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.NPMPackageInfo":{"properties":{"exists":{"type":"boolean"},"install_cmd":{"type":"string"}},"type":"object"},"contracts.OAuthConfig":{"properties":{"auth_url":{"type":"string"},"client_id":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_port":{"type":"integer"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false},"token_expires_at":{"description":"When the OAuth token expires","type":"string"},"token_url":{"type":"string"},"token_valid":{"description":"Whether token is currently valid","type":"boolean"}},"type":"object"},"contracts.OAuthErrorDetails":{"description":"Structured discovery/failure details","properties":{"authorization_server_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"dcr_status":{"$ref":"#/components/schemas/contracts.DCRStatus"},"protected_resource_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"server_url":{"type":"string"}},"type":"object"},"contracts.OAuthFlowError":{"properties":{"correlation_id":{"description":"Flow tracking ID for log correlation","type":"string"},"debug_hint":{"description":"CLI command for log lookup","type":"string"},"details":{"$ref":"#/components/schemas/contracts.OAuthErrorDetails"},"error_code":{"description":"Machine-readable error code (e.g., OAUTH_NO_METADATA)","type":"string"},"error_type":{"description":"Category of OAuth runtime failure","type":"string"},"message":{"description":"Human-readable error description","type":"string"},"request_id":{"description":"HTTP request ID (from PR #237)","type":"string"},"server_name":{"description":"Server that failed OAuth","type":"string"},"success":{"description":"Always false","type":"boolean"},"suggestion":{"description":"Actionable remediation hint","type":"string"}},"type":"object"},"contracts.OAuthIssue":{"properties":{"documentation_url":{"type":"string"},"error":{"type":"string"},"issue":{"type":"string"},"missing_params":{"items":{"type":"string"},"type":"array","uniqueItems":false},"resolution":{"type":"string"},"server_name":{"type":"string"}},"type":"object"},"contracts.OAuthRequirement":{"properties":{"expires_at":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"state":{"type":"string"}},"type":"object"},"contracts.OAuthStartResponse":{"properties":{"auth_url":{"description":"Authorization URL (always included for manual use)","type":"string"},"browser_error":{"description":"Error message if browser launch failed","type":"string"},"browser_opened":{"description":"Whether browser launch succeeded","type":"boolean"},"correlation_id":{"description":"UUID for tracking this flow","type":"string"},"message":{"description":"Human-readable status message","type":"string"},"server_name":{"description":"Name of the server being authenticated","type":"string"},"success":{"description":"Always true for successful start","type":"boolean"}},"type":"object"},"contracts.PreflightPolicy":{"properties":{"exclude_destructive":{"type":"boolean"},"exclude_open_world":{"type":"boolean"},"read_only_only":{"type":"boolean"}},"type":"object"},"contracts.PreflightReason":{"type":"string","x-enum-varnames":["PreflightReasonServerInitializing","PreflightReasonServerUnhealthy","PreflightReasonServerDisabled","PreflightReasonServerQuarantined","PreflightReasonToolPendingApproval","PreflightReasonToolChanged","PreflightReasonToolBlockedByUser","PreflightReasonOAuthRequired","PreflightReasonHashMismatch","PreflightReasonServerNotInScope","PreflightReasonToolDeniedByConfig","PreflightReasonMissingAnnotation","PreflightReasonPolicyFiltered","PreflightReasonNotFound","PreflightReasonServerNotConfigured"]},"contracts.PreflightRequest":{"properties":{"policy":{"$ref":"#/components/schemas/contracts.PreflightPolicy"},"profile":{"description":"Profile evaluates under a named profile's server scope. Unknown: 400.","type":"string"},"tools":{"description":"Tools is 1..100 entries BEFORE dedup; duplicates are collapsed, and\nduplicate ids carrying different pins are a validation error.","items":{"$ref":"#/components/schemas/contracts.PreflightToolRef"},"type":"array","uniqueItems":false},"wait_ms":{"description":"WaitMS polls local state for up to this many milliseconds (cap 10000)\nwhile every failure is retryable-class.","type":"integer"}},"type":"object"},"contracts.PreflightResponse":{"properties":{"checked_at":{"type":"string"},"tools":{"description":"Tools are ordered by first occurrence of each unique id in the request.","items":{"$ref":"#/components/schemas/contracts.PreflightToolResult"},"type":"array","uniqueItems":false},"verdict":{"$ref":"#/components/schemas/contracts.PreflightVerdict"},"waited_ms":{"description":"WaitedMS is present when wait_ms was requested (0 when the wait\nsemaphore was exhausted and the request resolved immediately).","type":"integer"}},"type":"object"},"contracts.PreflightStatus":{"type":"string","x-enum-varnames":["PreflightStatusReady","PreflightStatusUnavailable"]},"contracts.PreflightToolRef":{"properties":{"id":{"description":"ID is a canonical \"\u003cserver\u003e:\u003ctool\u003e\" id. A malformed id is answered with a\nper-ID not_found carrying a format hint, never a request-level error.","type":"string"},"pin_hash":{"description":"PinHash is \"sha256/v{N}:{hex}\" — the schema version is embedded so a\nproxy-side hash-algorithm bump is distinguishable from upstream drift.","type":"string"}},"type":"object"},"contracts.PreflightToolResult":{"properties":{"action":{"type":"string"},"detail":{"type":"string"},"did_you_mean":{"description":"DidYouMean carries up to 3 nearest caller-visible ids on not_found. It\nnever crosses a scope boundary and never names a quarantined server's\ntools.","items":{"type":"string"},"type":"array","uniqueItems":false},"hash":{"description":"Hash is the tool's current pin (\"sha256/v{N}:{hex}\") — operator tier,\nready results only. Never disclosed to an agent token.","type":"string"},"id":{"type":"string"},"reason":{"$ref":"#/components/schemas/contracts.PreflightReason"},"remediation":{"type":"string"},"retryable":{"type":"boolean"},"status":{"$ref":"#/components/schemas/contracts.PreflightStatus"}},"type":"object"},"contracts.PreflightVerdict":{"type":"string","x-enum-varnames":["PreflightVerdictReady","PreflightVerdictDegradedRetryable","PreflightVerdictBlocked","PreflightVerdictUnknownIDs"]},"contracts.QuarantineStats":{"description":"Tool quarantine metrics for this server","properties":{"blocked_count":{"description":"Number of disabled (blocked) tools","type":"integer"},"changed_count":{"description":"Number of tools whose description/schema changed since approval","type":"integer"},"pending_count":{"description":"Number of newly discovered tools awaiting approval","type":"integer"}},"type":"object"},"contracts.RefreshRegistryResponse":{"properties":{"cleared":{"description":"number of cached entries dropped","type":"integer"},"registry_id":{"type":"string"}},"type":"object"},"contracts.Registry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag (MCP-866): \"official/trusted\" for built-in\ndefaults, \"custom/unverified\" for user-added registries.","type":"string"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"trusted":{"description":"Trusted indicates whether this is an official, shipped-by-default\nregistry. Trust is derived from membership in the default set, never\nfrom self-assertion in config.","type":"boolean"},"url":{"type":"string"}},"type":"object"},"contracts.RegistryCacheInfo":{"properties":{"age_seconds":{"type":"number"},"stale":{"type":"boolean"}},"type":"object"},"contracts.RegistryUnavailable":{"properties":{"reason":{"type":"string"}},"type":"object"},"contracts.ReplayToolCallRequest":{"properties":{"arguments":{"description":"Modified arguments for replay","type":"object"}},"type":"object"},"contracts.ReplayToolCallResponse":{"properties":{"error":{"description":"Error if replay failed","type":"string"},"new_call_id":{"description":"ID of the newly created call","type":"string"},"new_tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"replayed_from":{"description":"Original call ID","type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.RepositoryInfo":{"description":"Detected package info","properties":{"npm":{"$ref":"#/components/schemas/contracts.NPMPackageInfo"}},"type":"object"},"contracts.RepositoryServer":{"properties":{"connect_url":{"description":"Alternative connection URL","type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"install_cmd":{"description":"Installation command","type":"string"},"name":{"type":"string"},"registry":{"description":"Which registry this came from","type":"string"},"repository_info":{"$ref":"#/components/schemas/contracts.RepositoryInfo"},"source_code_url":{"description":"Source repository URL","type":"string"},"updated_at":{"type":"string"},"url":{"description":"MCP endpoint for remote servers only","type":"string"}},"type":"object"},"contracts.SearchRegistryServersResponse":{"properties":{"cache":{"$ref":"#/components/schemas/contracts.RegistryCacheInfo"},"query":{"type":"string"},"registry_id":{"type":"string"},"servers":{"items":{"$ref":"#/components/schemas/contracts.RepositoryServer"},"type":"array","uniqueItems":false},"tag":{"type":"string"},"total":{"type":"integer"},"unavailable":{"$ref":"#/components/schemas/contracts.RegistryUnavailable"}},"type":"object"},"contracts.SearchResult":{"properties":{"matches":{"type":"integer"},"score":{"type":"number"},"snippet":{"type":"string"},"tool":{"$ref":"#/components/schemas/contracts.Tool"}},"type":"object"},"contracts.SearchToolsResponse":{"properties":{"query":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/contracts.SearchResult"},"type":"array","uniqueItems":false},"took":{"type":"string"},"total":{"type":"integer"}},"type":"object"},"contracts.SecurityScanSummary":{"description":"Latest security scan results summary","properties":{"deep_scan":{"$ref":"#/components/schemas/contracts.DeepScanDescriptor"},"finding_counts":{"$ref":"#/components/schemas/contracts.FindingCounts"},"last_scan_at":{"type":"string"},"risk_score":{"description":"0-100","type":"integer"},"scanners_failed":{"type":"integer"},"scanners_run":{"description":"Scanner coverage for the primary (baseline) scan pass — informational only.\nSpec 077 US3 (FR-008/FR-014): Status is derived SOLELY from the\ndeterministic baseline findings; a failed Docker deep scanner no longer\ndowngrades a clean verdict. That failure is surfaced via DeepScan instead.","type":"integer"},"scanners_total":{"type":"integer"},"status":{"description":"\"clean\", \"warnings\", \"dangerous\", \"failed\", \"not_scanned\", \"scanning\"","type":"string"}},"type":"object"},"contracts.Server":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"authenticated":{"description":"OAuth authentication status","type":"boolean"},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges mirrors config.ServerConfig.AutoApproveToolChanges\n(MCP-2930): the per-server intent to auto-approve new/changed tools past\nthe trust baseline. Tri-state *bool — nil means \"never set\" (omitted from\nthe payload), so the Web UI toggle (MCP-2932) can distinguish unset from\nan explicit false. Read-only on the GET path; PATCH/POST accept it via\nAddServerRequest.","type":"boolean"},"command":{"type":"string"},"connected":{"type":"boolean"},"connected_at":{"type":"string"},"connecting":{"type":"boolean"},"created":{"type":"string"},"diagnostic":{"$ref":"#/components/schemas/contracts.Diagnostic"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"error_code":{"type":"string"},"expose_prompts":{"description":"ExposePrompts mirrors config.ServerConfig.ExposePrompts (F9): the per-server\nprompt-aggregation override. Tri-state *bool — nil/omitted means \"inherit\ndefault aggregation\". Surfaced on GET so a caller that PATCHed the override\ncan read it back; PATCH/POST accept it via AddServerRequest.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"health":{"$ref":"#/components/schemas/contracts.HealthStatus"},"id":{"type":"string"},"init_timeout":{"description":"InitTimeout mirrors config.ServerConfig.InitTimeout (MCP-3322 / GH #760):\nthe per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override. Serialized as\na duration string (e.g. \"120s\"); nil/omitted means \"inherit the global\ndefault\". Surfaced on the GET path so clients can read back a configured\noverride; PATCH/POST accept it via AddServerRequest.","type":"string"},"isolation":{"$ref":"#/components/schemas/contracts.IsolationConfig"},"isolation_defaults":{"$ref":"#/components/schemas/contracts.IsolationDefaults"},"isolation_effective":{"$ref":"#/components/schemas/contracts.IsolationEffective"},"last_error":{"type":"string"},"last_reconnect_at":{"type":"string"},"last_retry_time":{"type":"string"},"max_concurrent_requests":{"description":"Spec 093 (GH #955) — per-server concurrency overrides, scope (c) of\nFR-020. Each setting is tri-state: nil (omitted) means \"inherit\nserver_concurrency_defaults\", 0 disables that setting for this server,\npositive overrides it. Surfaced on the GET path so a caller can read back\nwhat it set; PATCH/POST accept them via AddServerRequest. The effective\nconcurrency for a server is additionally bounded by the global aggregate\nlimiter, which is NOT an inheritance source for these fields.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/contracts.OAuthConfig"},"oauth_status":{"description":"OAuth status: \"authenticated\", \"expired\", \"error\", \"none\"","type":"string"},"protocol":{"type":"string"},"quarantine":{"$ref":"#/components/schemas/contracts.QuarantineStats"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_count":{"type":"integer"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets this disconnected server","type":"boolean"},"retry_count":{"type":"integer"},"retry_stopped":{"description":"RetryStopped reports that automatic reconnection has been given up for\ngood because the failure is deterministic and unrecoverable — a missing\nbinary, an image without the interpreter, an unparseable config (GH\n#1145). It is NOT ordinary exponential backoff, which keeps retrying;\nnothing will happen until the user fixes the config or restarts the\nserver. RetryStoppedCode is the stable MCPX_* code that proved it and\nRetryStoppedReason the catalog message explaining how to fix it. All three\nare omitted for servers that are healthy or still retrying.","type":"boolean"},"retry_stopped_code":{"type":"string"},"retry_stopped_reason":{"type":"string"},"security_scan":{"$ref":"#/components/schemas/contracts.SecurityScanSummary"},"should_retry":{"type":"boolean"},"source_registry_id":{"description":"MCP-901 — registry provenance of an upstream that was added from a\nregistry. SourceRegistryID names the source registry (empty for\nmanually-configured servers); SourceRegistryProvenance is the trust tag\nrecorded at add time (\"official/trusted\" or \"custom/unverified\"). Both\nare projected from config.ServerConfig so the approval/quarantine view\ncan render an \"added from \u003cregistry\u003e · unverified\" origin badge. Optional\nand omitted when empty — clients that pre-date this treat them as absent.","type":"string"},"source_registry_provenance":{"type":"string"},"status":{"type":"string"},"token_expires_at":{"description":"When the OAuth token expires (ISO 8601)","type":"string"},"tool_count":{"type":"integer"},"tool_list_token_size":{"description":"Token size for this server's tools","type":"integer"},"trust_mode":{"description":"TrustMode mirrors config.ServerConfig.TrustMode (spec 086): the per-server\ntrust tier (\"auto\"/\"scan\"/\"manual\"). Surfaced on the GET path so clients can\nread back the persisted mode; PATCH/POST accept it via AddServerRequest.\nOmitted when empty (server predates the field / relies on legacy flags).","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"user_logged_out":{"description":"True if user explicitly logged out (prevents auto-reconnection)","type":"boolean"},"working_dir":{"type":"string"}},"type":"object"},"contracts.ServerActionResponse":{"properties":{"action":{"type":"string"},"async":{"type":"boolean"},"server":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ServerStats":{"properties":{"connected_servers":{"type":"integer"},"docker_containers":{"type":"integer"},"quarantined_servers":{"type":"integer"},"token_metrics":{"$ref":"#/components/schemas/contracts.ServerTokenMetrics"},"total_servers":{"type":"integer"},"total_tools":{"type":"integer"}},"type":"object"},"contracts.ServerTokenMetrics":{"properties":{"average_query_result_size":{"description":"Typical retrieve_tools output (tokens)","type":"integer"},"per_server_tool_list_sizes":{"additionalProperties":{"type":"integer"},"description":"Token size per server","type":"object"},"saved_tokens":{"description":"Difference","type":"integer"},"saved_tokens_percentage":{"description":"Percentage saved","type":"number"},"total_server_tool_list_size":{"description":"All upstream tools combined (tokens)","type":"integer"}},"type":"object"},"contracts.SuccessResponse":{"properties":{"data":{"type":"object"},"success":{"type":"boolean"}},"type":"object"},"contracts.Tier":{"description":"Tier is computed by AnnotationTier (Spec 109 FR-028/X11) from\nAnnotations — read|write|destructive|unannotated. Set by every producer\nof a Tool (enrichServerTools, the global tools handler); never left for\na consuming surface to compute.","type":"string","x-enum-varnames":["TierRead","TierWrite","TierDestructive","TierUnannotated","TierUnknown"]},"contracts.TokenMetrics":{"description":"Token usage metrics (nil for older records)","properties":{"encoding":{"description":"Encoding used (e.g., cl100k_base)","type":"string"},"estimated_cost":{"description":"Optional cost estimate","type":"number"},"input_tokens":{"description":"Tokens in the request","type":"integer"},"model":{"description":"Model used for tokenization","type":"string"},"output_tokens":{"description":"Tokens in the response","type":"integer"},"total_tokens":{"description":"Total tokens (input + output)","type":"integer"},"truncated_tokens":{"description":"Tokens removed by truncation","type":"integer"},"was_truncated":{"description":"Whether response was truncated","type":"boolean"}},"type":"object"},"contracts.Tool":{"properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"approval_status":{"type":"string"},"config_denied":{"description":"ConfigDenied is true when the tool is denied by the server's static\nenabled_tools / disabled_tools config. The user cannot override this toggle.","type":"boolean"},"description":{"type":"string"},"disabled":{"description":"Disabled mirrors ToolApprovalRecord.Disabled so per-tool enable state is\navailable without a second round-trip to the approvals endpoint. Absent\nin the JSON when false (default) to keep responses compact.","type":"boolean"},"hash":{"description":"Hash is the tool's current stored hash rendered in the preflight pin\nformat \"sha256/v{N}:{hex}\" (Spec 098 FR-011), where N is the approval\nrecord's HashSchemaVersion. It is the authoring surface for\n` + "`" + `POST /api/v1/preflight` + "`" + ` pins and ` + "`" + `mcpproxy tools preflight --pin` + "`" + `:\ncopy the value straight into a pin.\n\nDisclosure is OPERATOR TIER ONLY — same rule as the preflight per-tool\nresult. The field is omitted for agent-token callers and for tools with\nno stored hash (no approval record yet, or a record written before\nhashes existed).","type":"string"},"held_reason":{"description":"HeldReason, HeldVerdict and HeldSignals mirror the same-named fields on\nstorage.ToolApprovalRecord: the offline-scan evidence that made\ntrust_mode: scan hold this tool for review (spec 086 FR-018). HeldSignals\nnames the matched deterministic check ids, e.g.\n\"tpa.TPA-2026-0001.hidden_instruction\", so a reviewer can see WHY the tool\nis held. All three are omitted for tools that are not held by the scan gate\n(including every record written before the field existed).","type":"string"},"held_signals":{"items":{"type":"string"},"type":"array","uniqueItems":false},"held_verdict":{"type":"string"},"last_used":{"type":"string"},"name":{"type":"string"},"schema":{"type":"object"},"server_name":{"type":"string"},"tier":{"$ref":"#/components/schemas/contracts.Tier"},"usage":{"type":"integer"}},"type":"object"},"contracts.ToolAnnotation":{"description":"Tool behavior hints snapshot","properties":{"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"},"readOnlyHint":{"type":"boolean"},"title":{"type":"string"}},"type":"object"},"contracts.ToolCallRecord":{"description":"The new tool call record","properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"arguments":{"description":"Tool arguments","type":"object"},"arguments_truncated":{"description":"ArgumentsTruncated marks Arguments as a placeholder rather than the\narguments the tool was called with. Replaying such a record without\nsupplying arguments explicitly is refused.","type":"boolean"},"config_path":{"description":"Active config file path","type":"string"},"duration":{"description":"Duration in nanoseconds","type":"integer"},"error":{"description":"Error message (failure only)","type":"string"},"execution_type":{"description":"\"direct\" or \"code_execution\"","type":"string"},"id":{"description":"Unique identifier","type":"string"},"mcp_client_name":{"description":"MCP client name from InitializeRequest","type":"string"},"mcp_client_version":{"description":"MCP client version","type":"string"},"mcp_session_id":{"description":"MCP session identifier","type":"string"},"metrics":{"$ref":"#/components/schemas/contracts.TokenMetrics"},"parent_call_id":{"description":"Links nested calls to parent code_execution","type":"string"},"request_id":{"description":"Request correlation ID","type":"string"},"response":{"description":"Tool response (success only)","type":"object"},"response_bytes":{"description":"Marshalled response size before truncation","type":"integer"},"response_truncated":{"description":"ResponseTruncated and ResponseBytes describe a STORAGE-side cut (#1176):\nthe caller received the response whole, and only the persisted copy was\nshortened to tool_call_max_response_size. When ResponseTruncated is true\nthe Response object carries {truncated, original_bytes, preview, note}\ninstead of the upstream result, and ResponseBytes is its size before the\ncut.","type":"boolean"},"server_id":{"description":"Server identity hash","type":"string"},"server_name":{"description":"Human-readable server name","type":"string"},"timestamp":{"description":"When the call was made","type":"string"},"tool_name":{"description":"Tool name (without server prefix)","type":"string"}},"type":"object"},"contracts.UpdateInfo":{"description":"Update information (if available)","properties":{"available":{"description":"Whether an update is available","type":"boolean"},"behind_summary":{"description":"Spec 079 FR-002 — how far behind the running build is. All four are\nadditive (FR-021) and absent when the delta could not be resolved, in\nwhich case every surface renders its pre-delta wording.","type":"string"},"check_error":{"description":"Error message if update check failed","type":"string"},"checked_at":{"description":"When the update check was performed","type":"string"},"install_channel":{"description":"Detected install channel (homebrew, dmg, deb, rpm, docker, go-install, windows-installer, tarball, unknown) — Spec 079 FR-008","type":"string"},"is_prerelease":{"description":"Whether the latest version is a prerelease","type":"boolean"},"latest_version":{"description":"Latest version available (e.g., \"v1.2.3\")","type":"string"},"nudges_suppressed":{"description":"UI surfaces must stay quiet (CI / non-interactive context); machine-readable fields still report the facts — Spec 079 FR-019","type":"boolean"},"release_url":{"description":"URL to the release page","type":"string"},"releases_behind":{"description":"Releases on the offered channel between the running and offered versions","type":"integer"},"releases_behind_saturated":{"description":"ReleasesBehind is a lower bound: the running build predates the scanned release window","type":"boolean"},"update_command":{"description":"One-line update command for the channel; only set when an update is available and the channel has one — Spec 079 FR-009","type":"string"},"weeks_behind":{"description":"Whole weeks between the two releases' publish dates; 0 is a real value, absent means unknown","type":"integer"}},"type":"object"},"contracts.UpdatePolicy":{"description":"UpdatePolicy is the effective, hot-reloadable update policy (Spec 092\nFR-015). Always present: the ` + "`" + `update` + "`" + ` object above is omitted both when\nupdate checking is disabled AND when no check has produced a result\nyet, so its absence cannot tell a client whether it is allowed to run\nits own (e.g. Sparkle feed) check. This field states the answer.","properties":{"channel":{"description":"Channel is the tracked release channel: \"stable\" or \"rc\".","type":"string"},"enabled":{"description":"Enabled is the effective automatic-check kill switch: update_check.enabled\nwith MCPPROXY_DISABLE_AUTO_UPDATE=true winning over it. A user-initiated\n\"Check for Updates\" stays available regardless.","type":"boolean"},"nudges_suppressed":{"description":"NudgesSuppressed asks UI surfaces to stay quiet (CI / non-interactive)\nwhile machine-readable fields keep reporting the facts.","type":"boolean"}},"type":"object"},"contracts.UpstreamError":{"properties":{"error_message":{"type":"string"},"server_name":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.UsageAggregateResponse":{"properties":{"freshness_ms":{"description":"age of the underlying snapshot in ms","type":"integer"},"generated_at":{"type":"string"},"other":{"$ref":"#/components/schemas/contracts.UsageOtherBucket"},"timeline":{"items":{"$ref":"#/components/schemas/contracts.UsageTimeBucket"},"type":"array","uniqueItems":false},"token_source":{"description":"\"bytes\" (size-based proxy, FR-006)","type":"string"},"tokens_saved":{"description":"echoed from ServerTokenMetrics (FR-007)","type":"integer"},"tokens_saved_percentage":{"type":"number"},"tools":{"items":{"$ref":"#/components/schemas/contracts.UsageToolStat"},"type":"array","uniqueItems":false},"total_calls":{"description":"TotalCalls and TotalErrors are the headline counts for the window: the sum\nof the timeline this same response carries, so the tiles and the histogram\nunder them cannot disagree. They are NOT the sum of Tools — that list is\nlifetime-cumulative, upstream-only and truncated to top-N, and summing it\nclient-side is what made the Usage tab print a third number for the same\n24 hours (audit finding F1, #1046). The population is\nstorage.CountsAsCall, shared with ActivitySummaryResponse.CallCount.\n\nTwo bounds on how exactly this matches the Activity Log's own count.\nBoth are bounded and disclosed, unlike the population mismatch they\nreplace, which was unbounded and silent:\n\n  - Window granularity is the timeline's: whole hour buckets, so the span\n    is the requested window rounded up to a bucket edge.\n  - This response is served from a snapshot behind a short read cache\n    (observability.usage_cache_ttl, 5s by default) so the endpoint never\n    scans the activity log per request, while the summary endpoint counts\n    live. Calls that land inside that window appear on the Activity Log\n    first. FreshnessMs and GeneratedAt say how old the figures are, and\n    the Usage tab prints it (\"Updated 3s ago\").","type":"integer"},"total_errors":{"type":"integer"},"window":{"type":"string"}},"type":"object"},"contracts.UsageOtherBucket":{"description":"present only when the list was truncated to top-N","properties":{"calls":{"type":"integer"},"tools_folded":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageTimeBucket":{"properties":{"calls":{"type":"integer"},"errors":{"type":"integer"},"start":{"type":"string"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageToolStat":{"properties":{"avg_req_bytes":{"description":"null when no sized request calls","type":"integer"},"avg_resp_bytes":{"description":"null when sized_calls == 0 (only legacy 0-byte calls)","type":"integer"},"blocked":{"type":"integer"},"calls":{"type":"integer"},"error_rate":{"type":"number"},"errors":{"type":"integer"},"last_used":{"type":"string"},"p50_exceeds":{"type":"boolean"},"p50_ms":{"description":"P50Ms and P95Ms are read off a fixed latency histogram, so they are BUCKET\nBOUNDS, not measured durations: the true percentile is at or below the\nvalue, and a client must render it as a bound (\"≤ 5 ms\"). P50Exceeds /\nP95Exceeds flip that reading for the unbounded overflow bucket, where the\nvalue is the last bound and the truth is above it (\"\u003e 10 s\").","type":"integer"},"p95_exceeds":{"type":"boolean"},"p95_ms":{"type":"integer"},"rejected":{"description":"spec 093: shed by a concurrency limit; never executed, so excluded from calls/latency","type":"integer"},"server":{"type":"string"},"sized_calls":{"description":"calls with known response size (basis for avg_resp_bytes)","type":"integer"},"tool":{"type":"string"},"total_req_bytes":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.ValidateConfigResponse":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false},"valid":{"type":"boolean"}},"type":"object"},"contracts.ValidationError":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"data":{"properties":{"data":{"$ref":"#/components/schemas/contracts.InfoResponse"}},"type":"object"},"httpapi.AddServerRequest":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve\nnew/changed tools past the trust baseline (MCP-2930). Tri-state *bool:\na nil pointer means \"leave unchanged\" on PATCH; a present value\n(including false) is applied. Mirrors config.ServerConfig's *bool\nsemantics — do NOT collapse to a plain bool, or an omitted field would\nsilently reset a previously-set value.","type":"boolean"},"command":{"type":"string"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts is the per-server override for prompt aggregation (F9):\nwhether this server's advertised MCP prompts are merged into mcpproxy's\nprompts/list. Tri-state *bool mirroring config.ServerConfig.ExposePrompts —\na nil pointer means \"leave unchanged\" on PATCH (and \"inherit the default\naggregate behavior\" on create); a present value (including false) is applied.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"init_timeout":{"description":"InitTimeout is the per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override\n(MCP-3322 / GH #760), serialized as a duration string (e.g. \"120s\"). A nil\npointer means \"leave unchanged\" on PATCH; a present value is applied.\nMirrors config.ServerConfig.InitTimeout's *Duration tri-state.","type":"string"},"isolation":{"$ref":"#/components/schemas/httpapi.IsolationRequest"},"max_concurrent_requests":{"description":"MaxConcurrentRequests / QueueSize / QueueTimeout are the per-server\nconcurrency overrides (spec 093 / GH #955, FR-020 scope (c)). Each is\ntri-state: a nil pointer means \"leave unchanged\" on PATCH and \"inherit\nserver_concurrency_defaults\" on create; an explicit 0 disables that\nsetting for this server; a positive value overrides it. Do NOT collapse\nthem to plain values — an omitted field would then silently reset a\nconfigured limit.","type":"integer"},"name":{"type":"string"},"protocol":{"type":"string"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"type":"boolean"},"trust_mode":{"description":"TrustMode is the per-server trust tier (spec 086): \"auto\", \"scan\", or\n\"manual\". Empty means \"leave unchanged\" on PATCH (and inherit the migrated\ndefault on create). A non-empty value is applied to ServerConfig.TrustMode\nand resolved by EffectiveTrustMode (an unrecognized value fails closed to\nmanual). This is the REST seam for changing the trust tier via\nPOST/PATCH /api/v1/servers.","type":"string"},"url":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.CanonicalConfigPath":{"properties":{"description":{"description":"Brief description","type":"string"},"exists":{"description":"Whether the file exists","type":"boolean"},"format":{"description":"Format identifier (e.g., \"claude_desktop\")","type":"string"},"name":{"description":"Display name (e.g., \"Claude Desktop\")","type":"string"},"os":{"description":"Operating system (darwin, windows, linux)","type":"string"},"path":{"description":"Full path to the config file","type":"string"}},"type":"object"},"httpapi.CanonicalConfigPathsResponse":{"properties":{"os":{"description":"Current operating system","type":"string"},"paths":{"description":"List of canonical config paths","items":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPath"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ConnectConflictResponse":{"properties":{"action":{"description":"already_exists | precondition_failed","type":"string"},"data":{"$ref":"#/components/schemas/connect.ConnectResult"},"error":{"description":"Human-readable message","type":"string"},"success":{"description":"Always false","type":"boolean"}},"type":"object"},"httpapi.ConnectRequest":{"properties":{"force":{"description":"Overwrite existing entry","type":"boolean"},"precondition_token":{"description":"PreconditionToken is the opaque token from the preview this write was\nconfirmed against (Spec 091 FR-005). When present, the core rechecks it\nat write time and responds 409 with action \"precondition_failed\" —\nwriting nothing — if the config or the entry MCPProxy would write has\ndrifted since; the caller then re-previews instead of retrying. Absent\nmeans exactly the pre-091 behavior. A replace-classified flow sends this\nTOGETHER with force=true: the token, not the absence of force, is the\noverwrite safety.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.ImportFromPathRequest":{"properties":{"format":{"description":"Optional format hint","type":"string"},"path":{"description":"File path to import from","type":"string"},"rename":{"additionalProperties":{"type":"string"},"description":"Rename maps a server name → new name. Applied after parsing so the\ncaller can disambiguate cross-source name collisions (Spec 046 v2 —\ne.g. \"mcpproxy\" → \"mcpproxy_claude_code\"). Keys are matched against\neither the raw source name (OriginalName) or the sanitized name shown\nin the preview (Server.Name); these differ for names that need\nsanitizing (e.g. \"Figma Desktop\" → \"Figma_Desktop\"). Keys not present\nin the imported set are ignored.","type":"object"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportRequest":{"properties":{"content":{"description":"Raw JSON or TOML content","type":"string"},"format":{"description":"Optional format hint","type":"string"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportResponse":{"properties":{"failed":{"items":{"$ref":"#/components/schemas/configimport.FailedServer"},"type":"array","uniqueItems":false},"format":{"type":"string"},"format_name":{"type":"string"},"imported":{"items":{"$ref":"#/components/schemas/httpapi.ImportedServerResponse"},"type":"array","uniqueItems":false},"skipped":{"items":{"$ref":"#/components/schemas/configimport.SkippedServer"},"type":"array","uniqueItems":false},"summary":{"$ref":"#/components/schemas/configimport.ImportSummary"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportedServerResponse":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"command":{"type":"string"},"fields_skipped":{"items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"type":"string"},"original_name":{"type":"string"},"protocol":{"type":"string"},"source_format":{"type":"string"},"url":{"type":"string"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.IsolationRequest":{"description":"Isolation carries per-server Docker isolation overrides (enabled,\nmode_override, image, network_mode, extra_args, working_dir). A nil\npointer means \"do not touch isolation config\". A present object is\napplied field-by-field ON TOP of the persisted overrides, so omitting a\nfield leaves it alone; clear an individual override by sending it\nexplicitly (` + "`" + `\"enabled\": null` + "`" + `, ` + "`" + `\"image\": \"\"` + "`" + `).","properties":{"enabled":{"description":"Enabled exists ONLY to detect and reject an echoed-back read. It is the\neffective state on the read surface and is never writable; see validate().","type":"boolean"},"enabled_override":{"description":"EnabledOverride is the tri-state per-server override — the RAW value, the\nsame one reads return as ` + "`" + `enabled_override` + "`" + `. It has THREE meaningful wire\nstates, and collapsing them is what silently un-isolated servers\n(GH #1142):\n  - absent          → leave the persisted override untouched\n  - null            → clear the override, back to inheriting the global\n  - true / false    → set an explicit opt-in / opt-out","type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"mode_override":{"description":"ModeOverride sets ` + "`" + `isolation.mode` + "`" + ` (\"docker\" | \"sandbox\" | \"none\").\nnil leaves the persisted value alone; an empty string clears it. An\nunrecognized value is rejected with a 400 rather than persisted.","type":"string"},"network_mode":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.OnboardingMarkRequest":{"properties":{"connect_step_status":{"description":"ConnectStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value. The stored enum is wider (Spec 080\nFR-001): a \"skipped\" request for a previously untouched connect step\nis upgraded server-side to \"completed_external\" when the install\nshows positive evidence of an external connection (Spec 080 FR-002).\n\"completed_external\" is NOT accepted from clients — it must never be\npersisted without that server-verified evidence (edge case: \"never\nguess completed_external without positive evidence\").","type":"string"},"engaged":{"description":"Engaged marks the wizard as engaged (completed or explicitly skipped).\nOnce true, the wizard does not auto-show again.","type":"boolean"},"mark_shown":{"description":"MarkShown records the wizard's first display time if not already set.","type":"boolean"},"server_step_status":{"description":"ServerStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value.","type":"string"}},"type":"object"},"httpapi.SetActiveProfileRequest":{"properties":{"active_profile":{"type":"string"},"profile":{"type":"string"}},"type":"object"},"httpapi.UndoConnectRequest":{"properties":{"backup_name":{"description":"BackupName is the bare filename (filepath.Base) of the backup returned as\nbackup_path by the preceding connect — a name, never a path. Undo resolves\nthe full path server-side by joining it with the client's own config\ndirectory, so a client-supplied value can never contribute a directory\ncomponent (traversal is impossible by construction). Empty means the\nconnect created the file (no prior file existed), so undo removes it.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.UpdateFailureRequest":{"properties":{"stage":{"description":"Stage is the failure stage of the update session.","enum":["appcast","download","install","other"],"type":"string"}},"type":"object"},"management.BulkOperationResult":{"properties":{"errors":{"additionalProperties":{"type":"string"},"description":"Map of server name to error message","type":"object"},"failed":{"description":"Number of failed operations","type":"integer"},"successful":{"description":"Number of successful operations","type":"integer"},"total":{"description":"Total servers processed","type":"integer"}},"type":"object"},"observability.HealthResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"observability.HealthStatus":{"properties":{"error":{"type":"string"},"latency":{"type":"string"},"name":{"type":"string"},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"}},"type":"object"},"observability.ReadinessResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"ready\" or \"not_ready\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"secureenv.EnvConfig":{"description":"Environment configuration for secure variable filtering","properties":{"allowed_system_vars":{"items":{"type":"string"},"type":"array","uniqueItems":false},"custom_vars":{"additionalProperties":{"type":"string"},"type":"object"},"enhance_path":{"description":"Enable PATH enhancement for Launchd scenarios","type":"boolean"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned upstream servers (MCP-2769). It is OFF by\ndefault and deliberately kept out of the AllowedSystemVars default list:\nproxy URLs frequently carry credentials (http://user:pass@proxy), so\nforwarding them to every stdio upstream is a credential-leak risk. When\nenabled, values are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"inherit_system_safe":{"type":"boolean"}},"type":"object"},"telemetry.FeedbackContext":{"properties":{"arch":{"type":"string"},"connected_server_count":{"type":"integer"},"edition":{"type":"string"},"os":{"type":"string"},"routing_mode":{"type":"string"},"server_count":{"type":"integer"},"version":{"type":"string"}},"type":"object"},"telemetry.FeedbackRequest":{"properties":{"category":{"description":"bug, feature, other","type":"string"},"context":{"$ref":"#/components/schemas/telemetry.FeedbackContext"},"email":{"type":"string"},"message":{"type":"string"}},"type":"object"},"telemetry.FeedbackResponse":{"properties":{"error":{"type":"string"},"issue_url":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"API key authentication via query parameter. Use ?apikey=your-key","in":"query","name":"apikey","type":"apiKey"}}},
+    "components": {"schemas":{"config.AuditLogConfig":{"description":"AuditLog configures the Spec 107 edition-neutral audit sink\n(internal/audit). nil means \"use the per-edition/per-transport\ndefault\" (EffectiveAuditLog); restart-pinned (bound at sink\nconstruction). See audit_log.go.","properties":{"compress":{"type":"boolean"},"enabled":{"type":"boolean"},"max_age_days":{"type":"integer"},"max_backups":{"type":"integer"},"max_size_mb":{"type":"integer"},"path":{"type":"string"},"stdout":{"type":"boolean"}},"type":"object"},"config.ConcurrencyDefaults":{"description":"ServerConcurrencyDefaults is scope (b) of FR-020: the blanket per-server\ndefault set inherited by every server that does not override a setting.\nAbsent (the default) = no per-server limiting unless a server configures\nit explicitly. File/API-configured only — no env scheme (FR-022).","properties":{"max_concurrent_requests":{"type":"integer"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"}},"type":"object"},"config.Config":{"properties":{"activity_cleanup_interval_min":{"description":"Background cleanup interval in minutes (default: 60)","type":"integer"},"activity_max_records":{"description":"Max records before pruning (default: 100000)","type":"integer"},"activity_max_response_size":{"description":"Response truncation limit in bytes (default: 65536)","type":"integer"},"activity_max_size_mb":{"description":"ActivityMaxSizeMB caps the total activity-log size in MB before the\noldest records are pruned. Omit the key for the 256MB default; set it to\n0 to disable the size cap.","type":"integer"},"activity_retention_days":{"description":"Activity logging settings (RFC-003)","type":"integer"},"aggregate_upstream_prompts":{"description":"AggregateUpstreamPrompts, when true, aggregates every connected upstream\nserver's advertised MCP prompts into mcpproxy's own prompts/list\n(exposed as \"\u003cserver\u003e__\u003cprompt\u003e\"). OFF by default: users are safe by\ndefault and opt in deliberately. EnablePrompts still governs the built-in\nprompts + the prompts capability; this flag gates ONLY the upstream\naggregation performed by RefreshPrompts. Hot-reloadable.","type":"boolean"},"allow_private_registry_fetch":{"description":"AllowPrivateRegistryFetch opts out of the registry SSRF guard (MCP-1076,\nCWE-918). By default (false) registry fetches refuse any host that is — or\nresolves to — a non-routable address (loopback, RFC1918/CGNAT private,\nlink-local incl. the 169.254.169.254 cloud-metadata endpoint), so a\nmalicious or typo'd registry source cannot turn the daemon into a\nrequest-forgery vector against internal services.\n\nThis opt-out is BLANKET (all-or-nothing): setting it true disables the\nguard for EVERY non-routable range at once — loopback, RFC1918/CGNAT\nprivate, link-local AND the 169.254.169.254 cloud-metadata endpoint. There\nis no way to allow only loopback; enabling it for a localhost dev registry\nalso re-opens the cloud-metadata SSRF vector. Set true ONLY when you\nintentionally run a trusted registry mirror on an internal/private address,\nideally on a host with no cloud-metadata exposure. The change takes effect\nonly on daemon (re)start or config reload.","type":"boolean"},"allow_server_add":{"type":"boolean"},"allow_server_remove":{"type":"boolean"},"api_key":{"description":"Security settings","type":"string"},"audit_log":{"$ref":"#/components/schemas/config.AuditLogConfig"},"call_tool_timeout":{"type":"string"},"check_server_repo":{"description":"Repository detection settings","type":"boolean"},"code_execution_max_parallel":{"description":"Default concurrency for call_tools() batches (1-32, default: 8)","type":"integer"},"code_execution_max_tool_calls":{"description":"Max tool calls per execution (0 = unlimited, default: 0)","type":"integer"},"code_execution_pool_size":{"description":"JavaScript runtime pool size (default: 10)","type":"integer"},"code_execution_timeout_ms":{"description":"Timeout in milliseconds (default: 120000, max: 600000)","type":"integer"},"data_dir":{"type":"string"},"debug_search":{"type":"boolean"},"direct_tool_response_mode":{"description":"DirectToolResponseMode selects the serialization of the DIRECT\nenumeration surface (Spec 102). Valid values: \"\" (= full), \"full\"\n(default: today's schema-bearing entries), \"deferred\" (description +\ncompact signature, with a minimal permissive input schema; upstream\ninputSchema and outputSchema are stripped and recovered on demand via\ndescribe_tool).\n\nDeliberately NOT an extension of tool_response_mode: reusing that axis\nwould silently change /mcp/all output for every deployment already\nrunning compact, which FR-015 forbids. Serialization-only — it never\nchanges WHICH tools are listed, only how (FR-008). Hot-reloadable.","type":"string"},"disable_management":{"type":"boolean"},"docker_isolation":{"$ref":"#/components/schemas/config.DockerIsolationConfig"},"docker_recovery":{"$ref":"#/components/schemas/config.DockerRecoveryConfig"},"enable_code_execution":{"description":"Code execution settings","type":"boolean"},"enable_prompts":{"description":"Prompts settings","type":"boolean"},"enable_socket":{"description":"Enable Unix socket/named pipe for local IPC (default: true)","type":"boolean"},"enable_tray":{"description":"Deprecated: EnableTray is unused and has no runtime effect. Kept for backward compatibility.","type":"boolean"},"environment":{"$ref":"#/components/schemas/secureenv.EnvConfig"},"features":{"$ref":"#/components/schemas/config.FeatureFlags"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned stdio upstream servers (MCP-2769). OFF by\ndefault: proxy URLs commonly embed credentials (http://user:pass@proxy), so\nforwarding them to every upstream is a credential-leak risk. When enabled,\nvalues are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"health_check_interval":{"description":"Discovery \u0026 health-check cadence (spec 074, #608). Both are *Duration\ntri-state pointers: nil = inherit the built-in default; a pointer to 0s =\nthe loop is disabled; a positive value = that interval. Defaults live only\nin the resolvers (ResolveHealthCheckInterval / ResolveToolDiscoveryInterval)\nso an unset key behaves exactly as before this feature (SC-005). Validated\nin Validate(): health-check ∈ {0} ∪ [5s,1h]; tool-discovery ∈ {0} ∪ [30s,24h].","type":"string"},"http_idle_timeout":{"description":"HTTPIdleTimeout caps how long an idle keep-alive connection is kept open.\nUnset = 180s. \"0s\" removes the dedicated idle deadline, but net/http then\nfalls back to ReadTimeout — idle is fully unbounded only when\nhttp_read_timeout is also \"0s\". Requires a restart.","type":"string"},"http_read_timeout":{"description":"HTTPReadTimeout caps how long reading a whole request (headers + body)\nmay take. Unset = 120s; \"0s\" disables it. Requires a restart.","type":"string"},"http_write_timeout":{"description":"HTTPWriteTimeout caps how long producing a whole response may take on\nnon-streaming endpoints (REST, Web UI, health). Unset = 120s; \"0s\"\ndisables it globally. MCP and SSE /events routes are exempt by design.","type":"string"},"init_timeout":{"description":"InitTimeout is the global default deadline for an upstream's MCP\n` + "`" + `initialize` + "`" + ` handshake (MCP-3322 / GH #760). *Duration tri-state: nil =\ninherit the built-in 30s default; a positive value = that deadline. A\nper-server InitTimeout overrides this. Resolved by ResolveInitTimeout;\nvalidated to {0} ∪ [1s, 30m] in Validate(). Servers doing legitimate\nfirst-run warmup (cache/index build) before answering ` + "`" + `initialize` + "`" + ` can\nraise this so they are not killed mid-startup.","type":"string"},"instructions":{"description":"Instructions text returned in the MCP initialize response to guide AI agents.\nWhen empty, a built-in default is used that explains retrieve_tools workflow.","type":"string"},"intent_declaration":{"$ref":"#/components/schemas/config.IntentDeclarationConfig"},"listen":{"type":"string"},"logging":{"$ref":"#/components/schemas/config.LogConfig"},"max_concurrent_requests":{"description":"Concurrency limits (spec 093, GH #955). Scope (a) of FR-020: the GLOBAL\nAGGREGATE limiter — one proxy-wide cap on concurrently running upstream\ntool calls, with its own bounded wait queue. Tri-state pointers: absent =\nthe limiter does not exist (default, zero behavior change); an explicit 0\nmax also disables it; positive = that cap. This scope is NEVER a\nper-server inheritance source — per-server values come from\nServerConcurrencyDefaults / the per-server overrides — but a server's\neffective concurrency is bounded by BOTH its own limiter and this one.\nResolved by ResolveGlobalConcurrency; hot-reloadable; overridable via\nMCPPROXY_MAX_CONCURRENT_REQUESTS / _QUEUE_SIZE / _QUEUE_TIMEOUT (FR-022).","type":"integer"},"max_result_size_chars":{"description":"MaxResultSizeChars is advertised on every tool as\n` + "`" + `_meta.anthropic/maxResultSizeChars` + "`" + `; it raises Claude Code's\ninline-response ceiling from 50k to up to 500k chars. Omit the key for\nthe 500000 default; set it to 0 to disable the annotation.","type":"integer"},"mcpServers":{"items":{"$ref":"#/components/schemas/config.ServerConfig"},"type":"array","uniqueItems":false},"oauth_expiry_warning_hours":{"description":"Health status settings","type":"number"},"observability":{"$ref":"#/components/schemas/config.ObservabilityConfig"},"output_sanitisation":{"$ref":"#/components/schemas/config.OutputSanitisationConfig"},"output_validation":{"$ref":"#/components/schemas/config.OutputValidationConfig"},"profiles":{"description":"Profiles are optional named, server-scoped views exposed at /mcp/p/\u003cname\u003e\n(Spec 057). Absent/empty is fully supported — /mcp is unchanged and configs\nwithout this key serialize byte-identically (SC-004).","items":{"$ref":"#/components/schemas/config.ProfileConfig"},"type":"array","uniqueItems":false},"quarantine_enabled":{"description":"QuarantineEnabled controls whether quarantine is active. It gates two\nthings together:\n  1. Server-level auto-quarantine for newly added servers (issue #370).\n     When true, servers added via the upstream_servers MCP tool or the\n     REST API default to quarantined=true; when false, they default to\n     quarantined=false. Explicit per-request values always win.\n  2. Tool-level quarantine (Spec 032): per-tool SHA-256 approval of\n     tool descriptions/schemas.\nWhen nil (default), quarantine is enabled (secure by default). Set to\nexplicit false to opt out of both. Per-server SkipQuarantine still\napplies for the tool-level check on individual servers.","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"read_only_mode":{"type":"boolean"},"registries":{"description":"Registries configuration for MCP server discovery","items":{"$ref":"#/components/schemas/config.RegistryEntry"},"type":"array","uniqueItems":false},"registries_locked":{"description":"RegistriesLocked is an enterprise stub knob (MCP-866): when true, runtime\nadditions of custom registries (e.g. ` + "`" + `registry add-source` + "`" + `, the REST/MCP\nadd-source surface) are rejected so an administrator can pin the discovery\nsources. Built-in defaults are unaffected. Documented but otherwise inert\nbeyond the add-source rejection.","type":"boolean"},"require_mcp_auth":{"description":"Require authentication on /mcp endpoint (default: false)","type":"boolean"},"reveal_secret_headers":{"description":"RevealSecretHeaders, when true, disables the redaction of the\nsecret-bearing server fields — sensitive header values (Authorization,\nX-API-Key, Cookie, …), env-var secrets, and URL query credentials — in\nresponses from the ` + "`" + `upstream_servers` + "`" + ` MCP tool, the ` + "`" + `/api/v1/servers` + "`" + `\nREST API, and the SSE event stream. It also lets URL secrets echoed\ninto last_error / health.detail through unscrubbed.\n\nDefault false — sensitive values are surfaced masked as\n` + "`" + `••••\u003clast2\u003e (\u003cN\u003e chars)` + "`" + ` (error strings use ` + "`" + `***REDACTED***` + "`" + `) so an\nMCP agent cannot read Bearer tokens / API keys / URL secrets out of\nanother upstream's config (PR #425, issue #872). ${env:…}/${keyring:…}\nreferences are labels, not secrets, and pass through unchanged.\n\nThe Web UI / macOS tray edit forms work without seeing the real\nvalues: PATCH /api/v1/servers/{id} deep-merges (omitted keys are\npreserved, see ` + "`" + `headers_remove` + "`" + ` / ` + "`" + `env_remove` + "`" + ` for explicit\ndeletes), so clients compute a diff and only send the keys that\nactually changed. Redacted-but-unchanged values never round-trip\n— the backend keeps the real string. Set this to true if a\ndownstream tool genuinely needs raw values in the response.","type":"boolean"},"routing_mode":{"description":"Routing mode (Spec 031): how MCP tools are exposed to clients\nValid values: \"retrieve_tools\" (default), \"direct\", \"code_execution\"","type":"string"},"security":{"$ref":"#/components/schemas/config.SecurityConfig"},"sensitive_data_detection":{"$ref":"#/components/schemas/config.SensitiveDataDetectionConfig"},"server_concurrency_defaults":{"$ref":"#/components/schemas/config.ConcurrencyDefaults"},"telemetry":{"$ref":"#/components/schemas/config.TelemetryConfig"},"tls":{"$ref":"#/components/schemas/config.TLSConfig"},"tokenizer":{"$ref":"#/components/schemas/config.TokenizerConfig"},"tool_call_max_records_per_server":{"description":"Calls retained per server (default: 1000)","type":"integer"},"tool_call_max_response_size":{"description":"Bounds for the per-server tool-call history behind GET /api/v1/tool-calls\n(#1176). It is a recent-debugging window, not an audit log — the activity\nlog is the durable record — and it kept every upstream response whole,\nper server, forever. A non-positive value means \"use the default\", not\n\"disable\": this store must never be unbounded again, so there is\ndeliberately no off switch.","type":"integer"},"tool_discovery_interval":{"type":"string"},"tool_response_limit":{"type":"integer"},"tool_response_mode":{"description":"Tool response mode (Spec 085): how retrieve_tools serializes results.\nValid values: \"\" (= full), \"full\" (default: today's schema-bearing\nentries), \"compact\" (signature + first-sentence entries). Orthogonal to\nrouting_mode — routing_mode selects the tool SURFACE, this selects the\nSERIALIZATION within the retrieve_tools surface. Serialization-only: it\nnever affects the query, ranking, or result set. Hot-reloadable.","type":"string"},"tool_response_session_risk_warning":{"description":"ToolResponseSessionRiskWarning controls whether the prose ` + "`" + `warning` + "`" + ` field\nis included in the ` + "`" + `session_risk` + "`" + ` object returned by ` + "`" + `retrieve_tools` + "`" + `.\nThe structured fields (level, lethal_trifecta, has_open_world_tools, etc.)\nare always included. Default: false (quiet for LLM clients) — see issue #406.\nMost tools lack annotations, so the MCP-spec defaults treat them as fully\npermissive across all three risk axes, which makes the prose warning fire\non almost every call and wastes tokens.","type":"boolean"},"tools_limit":{"type":"integer"},"toon_min_savings_pct":{"description":"ToonMinSavingsPct is the minimum byte-savings percentage (validated\n1-90; 0/unset → 15) the complete TOON emission (marker + hint + body)\nmust achieve over the exact passthrough emission for adaptive mode to\nencode a block. Byte savings approximate token savings for the tabular\npayload class; the spec-083 profiler reports true token deltas.\nGlobal-only (no per-server override, FR-001).","type":"integer"},"toon_output":{"description":"ToonOutput selects the TOON encoding mode for call_tool_* result text\nblocks (spec 084): \"off\" (default — responses byte-identical to\npre-feature behavior), \"adaptive\" (encode only tabular-uniform payloads\nthat beat compact JSON by ToonMinSavingsPct), or \"always\"\n(benchmark/debug only — encodes every JSON-parseable block and can\nINCREASE token cost). Per-server override: ServerConfig.ToonOutput.\nResolved by ResolveToonOutput; hot-reloadable.","type":"string"},"top_k":{"description":"Deprecated: TopK is superseded by ToolsLimit and has no runtime effect. Kept for backward compatibility.","type":"integer"},"tray_endpoint":{"description":"Tray endpoint override (unix:// or npipe://)","type":"string"},"trusted_hosts":{"description":"TrustedHosts lists non-loopback Host header values accepted on loopback\nlisteners (GH #898). DNS-rebinding protection rejects requests whose Host\nheader is not a loopback address when mcpproxy listens on loopback; a\nreverse proxy (nginx → 127.0.0.1) forwarding the public domain in Host\ntrips it. Entries are hostnames, case-insensitive; an entry without a\nport matches any port, with a port it must match exactly; a leading dot\n(\".example.com\") is a subdomain wildcard. The single entry \"*\" disables\nHost and Origin validation entirely. The same list also validates the\nOrigin header when present (MCP spec DNS-rebinding defense). Empty\n(default) keeps full protection. Env override: MCPPROXY_TRUSTED_HOSTS\n(comma-separated).","items":{"type":"string"},"type":"array","uniqueItems":false},"trusted_proxies":{"description":"TrustedProxies lists the CIDRs or IP addresses whose X-Forwarded-For /\nX-Real-IP / X-Forwarded-Proto / X-Forwarded-Host headers are believed\n(Spec 107 FR-027). Empty (default) trusts nobody. Edition-neutral, live\n(hot-reloadable). Env override: MCPPROXY_TRUSTED_PROXIES (comma-separated).\nThe one reader is ForwardedHeaders; validation is validateTrustedProxies.","items":{"type":"string"},"type":"array","uniqueItems":false},"update_check":{"$ref":"#/components/schemas/config.UpdateCheckConfig"}},"type":"object"},"config.CustomPattern":{"properties":{"category":{"description":"Category (defaults to \"custom\")","type":"string"},"keywords":{"description":"Keywords to match (mutually exclusive with Regex)","items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"description":"Unique identifier for this pattern","type":"string"},"regex":{"description":"Regex pattern (mutually exclusive with Keywords)","type":"string"},"severity":{"description":"Risk level: critical, high, medium, low","type":"string"}},"type":"object"},"config.DeepScanConfig":{"description":"DeepScan is the opt-in \"deep scan\" layer (Spec 077 US3). It subsumes the\ndeprecated top-level scanner_fetch_package_source / scanner_disable_no_new_privileges\nkeys (migrated on load) and gates the heavy Docker-based scanners + source\nextraction. Disabled by default (FR-006): only the deterministic in-process\nbaseline scanner runs. A deep-scan failure NEVER changes the baseline verdict\n(FR-007/FR-008).","properties":{"disable_no_new_privileges":{"description":"DisableNoNewPrivileges, when true, omits the ` + "`" + `--security-opt\nno-new-privileges` + "`" + ` flag from scanner container runs (snap-docker/AppArmor\nescape hatch). Absorbs the deprecated top-level\nscanner_disable_no_new_privileges. Default false.","type":"boolean"},"enabled":{"description":"Enabled is the master opt-in for the heavy layer (FR-006). Default false.","type":"boolean"},"fetch_package_source":{"description":"FetchPackageSource controls whether the scanner fetches the PUBLISHED\nsource of package-runner servers (npx/uvx) — without executing it — when\nno local source is available. Absorbs the deprecated top-level\nscanner_fetch_package_source. Default (nil) is ENABLED within deep scan.","type":"boolean"},"scanners":{"description":"Scanners optionally restricts which deep scanners may run under the\numbrella (by scanner id). Empty ⇒ all enabled deep scanners are eligible.","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.DockerIsolationConfig":{"description":"Docker isolation settings","properties":{"cpu_limit":{"description":"CPU limit for containers","type":"string"},"default_images":{"additionalProperties":{"type":"string"},"description":"Map of runtime type to Docker image","type":"object"},"enable_cache_volume":{"description":"Mount shared cache volumes for faster restarts (default: true)","type":"boolean"},"enabled":{"description":"Global enable/disable for Docker isolation (legacy; superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments","items":{"type":"string"},"type":"array","uniqueItems":false},"log_driver":{"description":"Docker log driver (default: json-file)","type":"string"},"log_max_files":{"description":"Maximum number of log files (default: 3)","type":"string"},"log_max_size":{"description":"Maximum size of log files (default: 100m)","type":"string"},"memory_limit":{"description":"Memory limit for containers","type":"string"},"mode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"network_mode":{"description":"Docker network mode (default: bridge)","type":"string"},"registry":{"description":"Custom registry (defaults to docker.io)","type":"string"},"timeout":{"description":"Container startup timeout","type":"string"}},"type":"object"},"config.DockerRecoveryConfig":{"description":"Docker recovery settings","properties":{"enabled":{"description":"Enable Docker recovery monitoring (default: true)","type":"boolean"},"max_retries":{"description":"Maximum retry attempts (0 = unlimited)","type":"integer"},"notify_on_failure":{"description":"Show notification on recovery failure (default: true)","type":"boolean"},"notify_on_retry":{"description":"Show notification on each retry (default: false)","type":"boolean"},"notify_on_start":{"description":"Show notification when recovery starts (default: true)","type":"boolean"},"notify_on_success":{"description":"Show notification on successful recovery (default: true)","type":"boolean"},"persistent_state":{"description":"Save recovery state across restarts (default: true)","type":"boolean"}},"type":"object"},"config.FeatureFlags":{"description":"Deprecated: Features flags are unused and have no runtime effect. Kept for backward compatibility.","properties":{"enable_async_storage":{"type":"boolean"},"enable_caching":{"type":"boolean"},"enable_contract_tests":{"type":"boolean"},"enable_debug_logging":{"description":"Development features","type":"boolean"},"enable_docker_isolation":{"type":"boolean"},"enable_event_bus":{"type":"boolean"},"enable_health_checks":{"type":"boolean"},"enable_metrics":{"type":"boolean"},"enable_oauth":{"description":"Security features","type":"boolean"},"enable_observability":{"description":"Observability features","type":"boolean"},"enable_quarantine":{"type":"boolean"},"enable_runtime":{"description":"Runtime features","type":"boolean"},"enable_search":{"description":"Storage features","type":"boolean"},"enable_sse":{"type":"boolean"},"enable_tracing":{"type":"boolean"},"enable_tray":{"type":"boolean"},"enable_web_ui":{"description":"UI features","type":"boolean"}},"type":"object"},"config.IntentDeclarationConfig":{"description":"Intent declaration settings (Spec 018)","properties":{"strict_server_validation":{"description":"StrictServerValidation controls whether server annotation mismatches\ncause rejection (true) or just warnings (false).\nDefault: true (reject mismatches)","type":"boolean"}},"type":"object"},"config.IsolationConfig":{"description":"Per-server isolation settings","properties":{"enabled":{"description":"Enable Docker isolation for this server (nil = inherit global; legacy, superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments for this server","items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"description":"Custom Docker image (overrides default)","type":"string"},"log_driver":{"description":"Docker log driver override for this server","type":"string"},"log_max_files":{"description":"Maximum number of log files override","type":"string"},"log_max_size":{"description":"Maximum size of log files override","type":"string"},"mode":{"$ref":"#/components/schemas/config.IsolationMode"},"network_mode":{"description":"Custom network mode for this server","type":"string"},"working_dir":{"description":"Custom working directory in container","type":"string"}},"type":"object"},"config.IsolationMode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"config.LogConfig":{"description":"Logging configuration","properties":{"compress":{"type":"boolean"},"enable_console":{"type":"boolean"},"enable_file":{"type":"boolean"},"filename":{"type":"string"},"json_format":{"type":"boolean"},"level":{"type":"string"},"log_dir":{"description":"Custom log directory","type":"string"},"max_age":{"description":"days","type":"integer"},"max_backups":{"description":"number of backup files","type":"integer"},"max_size":{"description":"MB","type":"integer"}},"type":"object"},"config.MetricsExporterConfig":{"description":"Metrics gates the Prometheus /metrics scrape endpoint (MCP-32). Disabled\nby default — operators opt in for k8s/enterprise deployments.","properties":{"enabled":{"description":"Enabled exposes /metrics on the existing HTTP listener when true.\nThe endpoint is admin-authenticated (SEC-07): scrapers must present the\nglobal API key, via X-API-Key or an Authorization: Bearer header.","type":"boolean"}},"type":"object"},"config.OAuthConfig":{"description":"OAuth configuration (keep even when empty to signal OAuth requirement)","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"description":"Additional OAuth parameters (e.g., RFC 8707 resource)","type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_uri":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ObservabilityConfig":{"description":"Observability settings (Spec 069): usage aggregate cache/persistence cadence.","properties":{"metrics":{"$ref":"#/components/schemas/config.MetricsExporterConfig"},"tracing":{"$ref":"#/components/schemas/config.TracingExporterConfig"},"usage_cache_ttl":{"description":"UsageCacheTTL bounds the freshness of the usage endpoint's read cache for\nwide windows (FR-005). Default 5s.","type":"string"},"usage_persist_interval":{"description":"UsagePersistInterval is how often the actor-owned usage aggregate snapshot\nis flushed to storage. Default 30s.","type":"string"}},"type":"object"},"config.OutputSanitisationConfig":{"description":"Output sanitisation settings (Spec 054 Track B)","properties":{"max_redactions":{"description":"cap on redactions per response; default 100","type":"integer"},"response_action":{"description":"\"spotlight\" | \"redact\" | \"block\"; default \"spotlight\"","type":"string"},"spotlight_untrusted":{"description":"wrap untrusted output in spotlight markers; default true","type":"boolean"},"strip_classes":{"description":"classes to strip: ansi/c0c1/bidi/zero_width","items":{"type":"string"},"type":"array","uniqueItems":false},"strip_control_chars":{"description":"strip control-character classes; default false","type":"boolean"}},"type":"object"},"config.OutputValidationConfig":{"description":"Output-schema validation settings (Spec 056)","properties":{"max_bytes":{"description":"structured payload byte cap; default 5\u003c\u003c20","type":"integer"},"max_depth":{"description":"nesting depth cap; default 64","type":"integer"},"missing_structured_content":{"description":"\"allow\" | \"block\"; default \"allow\"","type":"string"},"mode":{"description":"\"off\" | \"warn\" | \"strict\"; default \"warn\"","type":"string"}},"type":"object"},"config.ProfileConfig":{"properties":{"name":{"description":"URL slug, validated","type":"string"},"servers":{"description":"references to mcpServers[].name","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.RegistryEntry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag for this registry (MCP-866):\nRegistryProvenanceOfficial for built-in defaults, RegistryProvenanceCustom\nfor user-added registries. It is authoritatively (re)computed by the\nregistries merge from whether the ID is a shipped default — a user cannot\nclaim \"official\" by writing it into their config.","type":"string"},"requires_key":{"description":"RequiresKey marks a registry that needs an API key to be queried. When\ntrue and no key is configured, the registry is skipped/marked unavailable\nrather than failing the whole search (FR-008).","type":"boolean"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"type":"string"}},"type":"object"},"config.SecurityConfig":{"description":"Security scanner settings (Spec 039)","properties":{"auto_baseline_scan":{"description":"AutoBaselineScan is the kill-switch for the AUTOMATIC, informational\nPass-1 baseline scan: the free in-process TPA scan mcpproxy runs for every\nnewly admitted server (any trust mode) and, once per installation, over\npre-existing servers that have never been scanned.\n\nInformational ONLY: the resulting verdict populates the security badge and\nthe scan summary, and NEVER gates quarantine or approval. The\ntrust_mode:\"scan\" admission gate is a separate path and is unaffected by\nthis flag.\n\nDefault (nil) is ENABLED. Set to false to suppress every automatic scan\n(manual scans keep working). Env override: MCPPROXY_AUTO_BASELINE_SCAN,\nwhich wins over this field on every path.","type":"boolean"},"deep_scan":{"$ref":"#/components/schemas/config.DeepScanConfig"},"integrity_check_interval":{"type":"string"},"integrity_check_on_restart":{"type":"boolean"},"runtime_read_only":{"type":"boolean"},"runtime_tmpfs_size":{"type":"string"},"scan_timeout_default":{"type":"string"},"scanner_disable_no_new_privileges":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.DisableNoNewPrivileges\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.IsDisableNoNewPrivileges. Cleared after migration.\n\nScannerDisableNoNewPrivileges, when true, omits the\n` + "`" + `--security-opt no-new-privileges` + "`" + ` flag from scanner container runs.\n\nBackground: snap-installed Docker on Ubuntu confines dockerd under the\n` + "`" + `snap.docker.dockerd` + "`" + ` AppArmor profile. When runc tries to transition\nthe container into the inner ` + "`" + `docker-default` + "`" + ` profile to exec the\nentrypoint, AppArmor refuses the transition because NO_NEW_PRIVS\nforbids privilege/profile changes on exec — the result is EPERM\n(\"operation not permitted\") and every scanner fails immediately.\n\nSet this to true ONLY on hosts hitting that incompatibility. Scanner\ncontainers still run with read-only rootfs, tmpfs /tmp, no-network by\ndefault, and read-only source mounts, so the marginal isolation loss\nis small. The preferred fix remains replacing snap docker with a\ndistro-packaged docker.","type":"boolean"},"scanner_fetch_package_source":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.FetchPackageSource\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.EffectiveFetchPackageSource. Cleared after migration.\n\nScannerFetchPackageSource controls whether the scanner fetches the\nPUBLISHED source of package-runner servers (npx/uvx) — without executing\nit — when no local source is available (no Docker container, no local\npackage cache, no working_dir). This is the primary quarantine/scan\ntarget: a quarantined-on-add server is never run locally, so without this\nthe scan degrades to tool-definitions-only (no real source-level\nanalysis). See MCP-2206.\n\nFetching uses ` + "`" + `npm pack --ignore-scripts` + "`" + ` (npm) and ` + "`" + `uv pip download` + "`" + ` /\n` + "`" + `pip download` + "`" + ` with ` + "`" + `--only-binary=:all:` + "`" + ` (Python), which only download +\nunpack archives and NEVER run install, build, or setup.py — a scanner must\nnot execute the untrusted code it is scanning. The Python\n` + "`" + `--only-binary=:all:` + "`" + ` flag is required because downloading an sdist would\ninvoke its build backend (setup.py); packages with no wheel fall back to\ntool-definitions-only instead. Extraction is hardened against path\ntraversal and decompression bombs.\n\nDefault (nil) is ENABLED. Set to false on air-gapped deployments to\nforbid the scanner's network egress; such servers then fall back to the\ntool-definitions-only scan with no regression.","type":"boolean"},"scanner_registry_url":{"type":"string"},"tpa_bundle_path":{"description":"TPABundlePath is the filesystem path to the tpa-db scanner-bundle.json\nthe offline TPA scanner runs (spec 086 FR-019: the signature-DB location\nMUST be configuration-driven, not hardcoded). Empty (the default) runs the\ncorpus embedded in this build.\n\nEnv override: MCPPROXY_TPA_BUNDLE_PATH. Hot-reloadable — the path is\nre-read on every config.reloaded event via\nscanner.Service.ApplySecurityConfig, so a corpus refresh needs no restart.\nA configured bundle that fails to read/parse/version-check/compile is\nREFUSED and the previously active corpus stays live (fail-closed, never\nfail-empty); the reason is logged and surfaced in the security overview's\nsignature_bundle.load_error.","type":"string"}},"type":"object"},"config.SensitiveDataDetectionConfig":{"description":"Sensitive data detection settings (Spec 026)","properties":{"categories":{"additionalProperties":{"type":"boolean"},"description":"Enable/disable specific detection categories","type":"object"},"custom_patterns":{"description":"User-defined detection patterns","items":{"$ref":"#/components/schemas/config.CustomPattern"},"type":"array","uniqueItems":false},"enabled":{"description":"Enable sensitive data detection (default: true)","type":"boolean"},"entropy_threshold":{"description":"Shannon entropy threshold for high-entropy detection (default: 4.5)","type":"number"},"max_payload_size_kb":{"description":"Max size to scan before truncating (default: 1024)","type":"integer"},"scan_requests":{"description":"Scan tool call arguments (default: true)","type":"boolean"},"scan_responses":{"description":"Scan tool responses (default: true)","type":"boolean"},"sensitive_keywords":{"description":"Keywords to flag","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ServerConfig":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve tool\nchanges/additions (disabling per-server rug-pull protection). Supersedes\nskip_quarantine. MCP-2930 only ACCEPTS, persists, and migrates this flag — it\nis NOT yet consulted at runtime; auto-approval is still governed by\nSkipQuarantine until the trust-baseline behavior change (MCP-2931) migrates the\nruntime consumers onto it.\nTri-state pointer (mirrors QuarantineEnabled): nil = unset (inherit/migrate\nfrom legacy skip_quarantine), explicit true/false = honored as-is so an\nexplicit auto_approve_tool_changes:false overrides a legacy skip_quarantine:true.\nRead via IsAutoApproveToolChanges().","type":"boolean"},"command":{"type":"string"},"created":{"type":"string"},"disabled_tools":{"description":"Denylist: these tools are hidden; mutually exclusive with enabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"},"enabled_tools":{"description":"Allowlist: only these tools are exposed; mutually exclusive with disabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts overrides whether this server's advertised MCP prompts are\naggregated into mcpproxy's prompts/list. nil (default) inherits the\ndefault-aggregate behavior (included if the server advertises\nCapabilities.Prompts); false excludes it regardless of capability.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"description":"For HTTP servers","type":"object"},"health_check_interval":{"description":"Per-server discovery \u0026 health-check overrides (spec 074). Same *Duration\ntri-state as the global keys: nil = inherit the global value (or default),\npointer to 0s = disabled for this server, positive = that interval.\nHealthCheckInterval is fully wired into the per-server health loop;\nToolDiscoveryInterval is accepted/validated and round-trips for\nforward-compat, but the periodic index sweep is governed by the global\ncadence in this iteration (see spec 074 plan §C).","type":"string"},"init_timeout":{"description":"InitTimeout overrides the global init_timeout for this server's MCP\n` + "`" + `initialize` + "`" + ` handshake deadline (MCP-3322 / GH #760). *Duration tri-state:\nnil = inherit the global value (or 30s default), positive = that deadline.\nResolved by Config.ResolveInitTimeout; validated to {0} ∪ [1s, 30m]. Raise\nthis for upstreams that do legitimate first-run warmup (e.g. caching many\nchannels/users) before responding to ` + "`" + `initialize` + "`" + `.","type":"string"},"isolation":{"$ref":"#/components/schemas/config.IsolationConfig"},"launcher_wait_timeout":{"description":"LauncherWaitTimeout caps how long mcpproxy will wait for a locally-launched\nHTTP/SSE upstream's URL to become reachable after Spawn(). Only consulted\nwhen the server is configured with both Command and an HTTP/SSE URL — i.e.,\nmcpproxy starts the process AND connects via network. Stdio servers ignore\nthis field. Zero or unset → 30s default.","type":"string"},"max_concurrent_requests":{"description":"Per-server concurrency overrides — scope (c) of FR-020 (spec 093, #955).\nTri-state per setting, exactly like HealthCheckInterval: absent = inherit\nthe per-server default set (server_concurrency_defaults), explicit 0 =\ndisable that setting for this server (0 max = no per-server limiter at\nall; 0 queue_size = no pending capacity, shed immediately at the cap),\npositive = override. The global aggregate limiter is never inherited from\nhere — it applies on top, so effective concurrency is min(per-server,\nglobal). Resolved by Config.ResolveServerConcurrency.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/config.OAuthConfig"},"protocol":{"description":"stdio, http, sse, streamable-http, auto","type":"string"},"quarantined":{"description":"Security quarantine status","type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets a disconnected server","type":"boolean"},"shared":{"description":"Server edition: shared with all users","type":"boolean"},"skip_quarantine":{"description":"SkipQuarantine is DEPRECATED (MCP-2930): use AutoApproveToolChanges instead.\nKept for back-compat parsing; on config load a legacy skip_quarantine:true is\nmigrated to auto_approve_tool_changes:true only when the new field is unset\n(see normalizeServerQuarantineFlags).","type":"boolean"},"source_registry_id":{"description":"SourceRegistryID records which registry this server was added from (empty\nfor manually-configured servers). MCP-866: surfaced in the approval /\nquarantine view so a reviewer can see a server's origin.","type":"string"},"source_registry_provenance":{"description":"SourceRegistryProvenance records the source registry's provenance at add\ntime (RegistryProvenanceOfficial / RegistryProvenanceCustom). It is purely\ninformational (MCP-1072) — surfaced so a reviewer can see a server's origin\n— and no longer gates quarantine or skip_quarantine.","type":"string"},"tool_discovery_interval":{"type":"string"},"toon_output":{"description":"ToonOutput overrides the global toon_output mode for this server's\ntools (spec 084, FR-001). Plain string, not a pointer: \"\"/absent =\ninherit the global value; \"off\"|\"adaptive\"|\"always\" = override (\"off\"\nis the explicit force-off). Resolved by Config.ResolveToonOutput.","type":"string"},"trust_mode":{"description":"TrustMode is the per-server trust tier: auto|scan|manual. Supersedes\nauto_approve_tool_changes (spec 086). An empty value is derived from the\nlegacy fields at load via normalizeServerQuarantineFlags; the single\nresolution point is EffectiveTrustMode(), which treats an empty or\nunrecognized value as manual (secure by default). Read via\nEffectiveTrustMode(), never the raw string.","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"working_dir":{"description":"Working directory for stdio servers","type":"string"}},"type":"object"},"config.TLSConfig":{"description":"TLS configuration","properties":{"certs_dir":{"description":"Directory for certificates","type":"string"},"enabled":{"description":"Enable HTTPS","type":"boolean"},"hsts":{"description":"Enable HTTP Strict Transport Security","type":"boolean"},"require_client_cert":{"description":"Enable mTLS","type":"boolean"}},"type":"object"},"config.TelemetryConfig":{"description":"Telemetry settings (Spec 036)","properties":{"anonymous_id":{"description":"Auto-generated UUIDv4","type":"string"},"anonymous_id_created_at":{"description":"Spec 042 (Tier 2) additions — all default-zero, all backwards-compatible.","type":"string"},"enabled":{"description":"Default: true (opt-out)","type":"boolean"},"endpoint":{"description":"Override for testing","type":"string"},"last_reported_version":{"description":"Upgrade funnel","type":"string"},"last_startup_outcome":{"description":"success|port_conflict|db_locked|...","type":"string"},"notice_shown":{"description":"First-run notice flag","type":"boolean"}},"type":"object"},"config.TokenizerConfig":{"description":"Tokenizer configuration for token counting","properties":{"default_model":{"description":"Default model for tokenization (e.g., \"gpt-4\")","type":"string"},"enabled":{"description":"Enable token counting","type":"boolean"},"encoding":{"description":"Default encoding (e.g., \"cl100k_base\")","type":"string"}},"type":"object"},"config.TracingExporterConfig":{"description":"Tracing gates the OpenTelemetry OTLP trace exporter (MCP-32). Disabled by\ndefault.","properties":{"enabled":{"description":"Enabled turns on OTLP trace export for tool calls and upstream hops.","type":"boolean"},"endpoint":{"description":"Endpoint is the collector address as host:port (no scheme), e.g.\n\"localhost:4318\" for http or \"localhost:4317\" for grpc.","type":"string"},"protocol":{"description":"Protocol selects the OTLP transport: \"http\" or \"grpc\".","type":"string"},"sample_rate":{"description":"SampleRate is the head-based trace sampling ratio in [0,1]. Default 0.1.\nOmit the key for the 0.1 default; set it to 0 to sample nothing.","type":"number"}},"type":"object"},"config.UpdateCheckConfig":{"description":"Update-check settings (Spec 079 FR-012): config-file control of the\nbackground upgrade-awareness checker (internal/updatecheck). nil =\nenabled on the stable channel (existing default behavior). The existing\nenvironment switches keep working and WIN over these keys (FR-014):\nMCPPROXY_DISABLE_AUTO_UPDATE=true force-disables even when\nenabled=true, and MCPPROXY_ALLOW_PRERELEASE_UPDATES=true force-selects\nthe rc channel even when channel=stable.","properties":{"channel":{"description":"Channel selects which releases are offered as updates: \"stable\"\n(default; prereleases never offered) or \"rc\" (prereleases included).\nEmpty resolves to stable. Validated in ValidateDetailed.\n\nNOTE: for a RELEASED build the running binary's own version is\nauthoritative and overrides this field — a stable build is never\noffered an RC (even with channel=rc), and an RC build always tracks the\nrc channel. This field only takes effect on dev/unstamped builds. See\ninternal/updatecheck.Checker.IncludePrereleases.","type":"string"},"enabled":{"description":"Enabled gates all update checking. Tri-state: nil/absent = enabled\n(default true, matching pre-079 behavior). When false, no network\ncheck is performed and no upgrade nudge appears on any surface\n(FR-015) — /api/v1/info omits the update object entirely.","type":"boolean"}},"type":"object"},"configimport.FailedServer":{"properties":{"details":{"type":"string"},"error":{"type":"string"},"name":{"type":"string"}},"type":"object"},"configimport.ImportSummary":{"properties":{"failed":{"type":"integer"},"imported":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"configimport.SkippedServer":{"properties":{"name":{"type":"string"},"reason":{"description":"\"already_exists\", \"filtered_out\", \"invalid_name\"","type":"string"}},"type":"object"},"connect.ConnectResult":{"description":"The full result; its action mirrors the top-level one","properties":{"action":{"description":"\"created\", \"updated\", \"already_exists\", \"removed\", \"not_found\"","type":"string"},"backup_path":{"type":"string"},"client":{"type":"string"},"config_path":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.APIResponse":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ActivityDetailResponse":{"properties":{"activity":{"$ref":"#/components/schemas/contracts.ActivityRecord"}},"type":"object"},"contracts.ActivityListResponse":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/contracts.ActivityRecord"},"type":"array","uniqueItems":false},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.ActivityRecord":{"properties":{"agent_name":{"description":"Agent token name when auth_type is \"agent\"","type":"string"},"arguments":{"description":"Tool call arguments","type":"object"},"auth_type":{"description":"\"admin\", \"agent\", \"user\" or \"admin_user\"; empty without an auth context or on another caller's row for a scoped caller","type":"string"},"detection_types":{"description":"List of detection types found","items":{"type":"string"},"type":"array","uniqueItems":false},"duration_ms":{"description":"Execution duration in milliseconds","type":"integer"},"error_message":{"description":"Error details if status is \"error\"","type":"string"},"has_sensitive_data":{"description":"Sensitive data detection fields (Spec 026)","type":"boolean"},"id":{"description":"Unique identifier (ULID format)","type":"string"},"max_severity":{"description":"Highest severity level detected (critical, high, medium, low)","type":"string"},"metadata":{"description":"Additional context-specific data","type":"object"},"parent_id":{"description":"Correlation id of the parent call (the code_execution whose sandbox issued this sub-call)","type":"string"},"request_bytes":{"description":"Byte sizes measured pre-truncation, mirroring storage.ActivityRecord\n(Spec 069 A1). They are the only cost signal a bodies-off export carries:\nwith payloads suppressed there is no text left to measure, so a consumer\naccounting for a record it cannot read has nothing else to go on. They are\nbyte LENGTHS, not token counts — the basis for an explicit estimate, never\na measured figure (spec 103, contracts/replay-input.md).\n\nZero means UNKNOWN, not free: legacy records predate the measurement and\ncode-execution sub-calls record both as zero. Hence omitempty — an absent\nkey tells a consumer to fall to exclusion accounting, whereas a present\nzero would read as a costless call and silently understate the workload.","type":"integer"},"request_id":{"description":"HTTP request ID for correlation","type":"string"},"response":{"description":"Tool response (potentially truncated)","type":"string"},"response_bytes":{"description":"Raw upstream response size in bytes before truncation","type":"integer"},"response_truncated":{"description":"True if response was truncated","type":"boolean"},"server_name":{"description":"Name of upstream MCP server","type":"string"},"session_id":{"description":"MCP transport session ID (regenerated on every reconnect)","type":"string"},"source":{"$ref":"#/components/schemas/contracts.ActivitySource"},"status":{"description":"Result status: \"success\", \"error\", \"blocked\", \"rejected\"","type":"string"},"timestamp":{"description":"When activity occurred","type":"string"},"tool_name":{"description":"Name of tool called","type":"string"},"type":{"$ref":"#/components/schemas/contracts.ActivityType"},"work_session_id":{"description":"Spec 082: one client, one project, across reconnects","type":"string"}},"type":"object"},"contracts.ActivitySource":{"description":"How activity was triggered: \"mcp\", \"cli\", \"api\"","type":"string","x-enum-varnames":["ActivitySourceMCP","ActivitySourceCLI","ActivitySourceAPI"]},"contracts.ActivitySummaryResponse":{"properties":{"blocked_count":{"description":"Count of blocked activities","type":"integer"},"call_count":{"description":"CallCount is how many of those records are CALLS THE USER MADE, as\ndefined once in storage.CountsAsCall and shared with the usage aggregate\nbehind the Usage tab (audit finding F1, #1046). TotalCount answers \"how\nmany rows does the Activity Log have\"; CallCount answers \"how many calls\nwere there\". They are different questions — quarantine auto-approvals,\nsystem start, security scans and management chatter are events, not calls\n— and printing either one under the other's label is how the same instance\ncame to report 51 calls on one screen and 19 on another.","type":"integer"},"call_error_count":{"description":"CallErrorCount is the failures within CallCount, so an error RATE computed\nfrom this response has one denominator. It is not ErrorCount: a policy\nblock is a failed call but carries status \"blocked\", and a shed call is an\nerror in neither sense because it never ran.","type":"integer"},"end_time":{"description":"End of the period (RFC3339)","type":"string"},"error_count":{"description":"Count of error activities","type":"integer"},"other_count":{"description":"OtherCount is every record whose status is outside the four-value\nvocabulary above, so that\n\n\tsuccess + error + blocked + rejected + other == total\n\nholds by construction. The status field is a CLOSED vocabulary for tool\ncalls, but the activity log is wider than tool calls: a quarantine change\nstores its ACTION there (\"approved\", \"auto_approved\"), a policy decision\nstores its DECISION (\"allow\"). Those rows were counted in the total and in\nnone of the four buckets, so the Activity Log's own status tiles summed to\nless than the denominator printed beside them — 15+4+0+0 under a \"42\"\n(audit finding F2, #1046). The residual now has a name and a tile.","type":"integer"},"period":{"description":"Time period (1h, 24h, 7d, 30d)","type":"string"},"rejected_count":{"description":"RejectedCount is the number of calls shed by a concurrency limiter before\nthey reached an upstream (spec 093). Counted separately from errors: it is\nproxy backpressure, not an upstream fault, and it is the signal an\noperator right-sizes max_concurrent_requests against.","type":"integer"},"start_time":{"description":"Start of the period (RFC3339)","type":"string"},"success_count":{"description":"Count of successful activities","type":"integer"},"top_servers":{"description":"Top servers by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopServer"},"type":"array","uniqueItems":false},"top_tools":{"description":"Top tools by activity count","items":{"$ref":"#/components/schemas/contracts.ActivityTopTool"},"type":"array","uniqueItems":false},"total_count":{"description":"Total activity count","type":"integer"}},"type":"object"},"contracts.ActivityTopServer":{"properties":{"count":{"description":"Activity count","type":"integer"},"name":{"description":"Server name","type":"string"}},"type":"object"},"contracts.ActivityTopTool":{"properties":{"count":{"description":"Activity count","type":"integer"},"server":{"description":"Server name","type":"string"},"tool":{"description":"Tool name","type":"string"}},"type":"object"},"contracts.ActivityType":{"description":"Type of activity","type":"string","x-enum-varnames":["ActivityTypeToolCall","ActivityTypePolicyDecision","ActivityTypeQuarantineChange","ActivityTypeServerChange"]},"contracts.AddFromRegistryRequest":{"properties":{"enabled":{"description":"defaults to true when nil","type":"boolean"},"env":{"additionalProperties":{"type":"string"},"description":"overrides + required-input values","type":"object"},"name":{"description":"optional name override","type":"string"}},"type":"object"},"contracts.AddRegistrySourceRequest":{"properties":{"id":{"description":"derived from the host when empty","type":"string"},"name":{"description":"defaults to the id","type":"string"},"protocol":{"description":"defaults to modelcontextprotocol/registry","type":"string"},"url":{"description":"required https registry URL","type":"string"}},"type":"object"},"contracts.ConfigApplyResult":{"properties":{"applied_immediately":{"type":"boolean"},"changed_fields":{"items":{"type":"string"},"type":"array","uniqueItems":false},"requires_restart":{"type":"boolean"},"restart_reason":{"type":"string"},"success":{"type":"boolean"},"validation_errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DCRStatus":{"properties":{"attempted":{"type":"boolean"},"error":{"type":"string"},"status_code":{"type":"integer"},"success":{"type":"boolean"}},"type":"object"},"contracts.DeepScanDescriptor":{"description":"DeepScan reports the opt-in \"deep scan\" layer status (Spec 077 US3),\nSEPARATELY from the baseline verdict above. Always emitted on a computed\nsummary — when deep scan is off (the default) it reports enabled=false\nplus any enabled-but-skipped Docker scanners. It never influences Status.","properties":{"available":{"type":"boolean"},"enabled":{"type":"boolean"},"ran":{"type":"boolean"},"scanners_failed":{"items":{"$ref":"#/components/schemas/contracts.DeepScanScannerFailure"},"type":"array","uniqueItems":false},"skipped_scanners":{"description":"SkippedScanners lists Docker scanners the user enabled that are skipped\nbecause security.deep_scan.enabled is false (informational).","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DeepScanScannerFailure":{"properties":{"id":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"contracts.DeprecatedConfigWarning":{"properties":{"field":{"type":"string"},"message":{"type":"string"},"replacement":{"type":"string"}},"type":"object"},"contracts.Diagnostic":{"description":"Spec 044 — structured diagnostic error and stable error code. Both\nare populated when the server is in a failed state and the error\nhas been classified by internal/diagnostics. Healthy servers omit\nthese fields.","properties":{"cause":{"type":"string"},"code":{"type":"string"},"detected_at":{"type":"string"},"docs_url":{"type":"string"},"fix_steps":{"items":{"$ref":"#/components/schemas/contracts.DiagnosticFixStep"},"type":"array","uniqueItems":false},"severity":{"type":"string"},"user_message":{"type":"string"}},"type":"object"},"contracts.DiagnosticFixStep":{"properties":{"command":{"type":"string"},"destructive":{"type":"boolean"},"fixer_key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"}},"type":"object"},"contracts.Diagnostics":{"properties":{"deprecated_configs":{"description":"Deprecated config fields found","items":{"$ref":"#/components/schemas/contracts.DeprecatedConfigWarning"},"type":"array","uniqueItems":false},"docker_status":{"$ref":"#/components/schemas/contracts.DockerStatus"},"missing_secrets":{"description":"Renamed to avoid conflict","items":{"$ref":"#/components/schemas/contracts.MissingSecretInfo"},"type":"array","uniqueItems":false},"oauth_issues":{"description":"OAuth parameter mismatches","items":{"$ref":"#/components/schemas/contracts.OAuthIssue"},"type":"array","uniqueItems":false},"oauth_required":{"items":{"$ref":"#/components/schemas/contracts.OAuthRequirement"},"type":"array","uniqueItems":false},"runtime_warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false},"timestamp":{"type":"string"},"total_issues":{"type":"integer"},"upstream_errors":{"items":{"$ref":"#/components/schemas/contracts.UpstreamError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DockerStatus":{"properties":{"available":{"type":"boolean"},"error":{"type":"string"},"version":{"type":"string"}},"type":"object"},"contracts.EditRegistrySourceRequest":{"properties":{"name":{"description":"new display name","type":"string"},"servers_url":{"description":"explicit servers-collection URL","type":"string"},"url":{"description":"new base/servers https URL","type":"string"}},"type":"object"},"contracts.ErrorResponse":{"properties":{"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.FindingCounts":{"properties":{"dangerous":{"description":"Tool poisoning, active prompt injection","type":"integer"},"info":{"description":"Low-severity CVEs, informational","type":"integer"},"total":{"type":"integer"},"warning":{"description":"Rug pull, supply chain CVEs with exploits","type":"integer"}},"type":"object"},"contracts.GetConfigResponse":{"properties":{"config":{"description":"The configuration object","type":"object"},"config_path":{"description":"Path to config file","type":"string"}},"type":"object"},"contracts.GetRegistriesResponse":{"properties":{"registries":{"items":{"$ref":"#/components/schemas/contracts.Registry"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerLogsResponse":{"properties":{"count":{"type":"integer"},"logs":{"items":{"$ref":"#/components/schemas/contracts.LogEntry"},"type":"array","uniqueItems":false},"server_name":{"type":"string"}},"type":"object"},"contracts.GetServerToolCallsResponse":{"properties":{"server_name":{"type":"string"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerToolsResponse":{"properties":{"count":{"type":"integer"},"server_name":{"type":"string"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GetServersResponse":{"properties":{"servers":{"items":{"$ref":"#/components/schemas/contracts.Server"},"type":"array","uniqueItems":false},"stats":{"$ref":"#/components/schemas/contracts.ServerStats"}},"type":"object"},"contracts.GetSessionDetailResponse":{"properties":{"session":{"$ref":"#/components/schemas/contracts.MCPSession"}},"type":"object"},"contracts.GetSessionsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"sessions":{"items":{"$ref":"#/components/schemas/contracts.MCPSession"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetToolCallDetailResponse":{"properties":{"tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"}},"type":"object"},"contracts.GetToolCallsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GlobalToolsResponse":{"properties":{"failed_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"partial":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/contracts.GlobalToolsStats"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GlobalToolsStats":{"properties":{"disabled":{"type":"integer"},"enabled":{"type":"integer"},"pending_approval":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.HealthStatus":{"description":"Unified health status calculated by the backend","properties":{"action":{"description":"Action is the suggested fix action: \"login\", \"restart\", \"enable\", \"approve\", \"view_logs\", \"set_secret\", \"configure\", \"edit_url\", or \"\" (none)","type":"string"},"admin_state":{"description":"AdminState indicates the admin state: \"enabled\", \"disabled\", or \"quarantined\"","type":"string"},"detail":{"description":"Detail is an optional longer explanation of the status","type":"string"},"level":{"description":"Level indicates the health level: \"healthy\", \"degraded\", or \"unhealthy\"","type":"string"},"summary":{"description":"Summary is a human-readable status message (e.g., \"Connected (5 tools)\")","type":"string"}},"type":"object"},"contracts.InfoEndpoints":{"description":"Available API endpoints","properties":{"http":{"description":"HTTP endpoint address (e.g., \"127.0.0.1:8080\")","type":"string"},"socket":{"description":"Unix socket path (empty if disabled)","type":"string"}},"type":"object"},"contracts.InfoResponse":{"properties":{"endpoints":{"$ref":"#/components/schemas/contracts.InfoEndpoints"},"launched_by":{"description":"LaunchedBy is the durable launch provenance of the running core (Spec\n092 FR-001a): \"tray\" when a tray spawned it, \"installer\" when the macOS\nPKG postinstall did, \"\" when user-launched or unknown. Always present\n(possibly empty) so a tray can distinguish \"old core, not mine\" from\n\"old core I may supersede\".","type":"string"},"listen_addr":{"description":"Listen address (e.g., \"127.0.0.1:8080\")","type":"string"},"pid":{"description":"PID is the operating-system process id of the running core (Spec 092\nFR-002). A tray that merely ATTACHED to a core holds no Process handle\nfor it, so without this there is no mechanism at all to stop a stale\ncore — the consent action would have nothing to act on and could only\nprint instructions. Paired with LaunchedBy it is what lets a newer tray\nsupersede a core an older tray started.","type":"integer"},"update":{"$ref":"#/components/schemas/contracts.UpdateInfo"},"update_policy":{"$ref":"#/components/schemas/contracts.UpdatePolicy"},"version":{"description":"Current MCPProxy version","type":"string"},"web_ui_url":{"description":"URL to access the web control panel","type":"string"}},"type":"object"},"contracts.IsolationConfig":{"properties":{"cpu_limit":{"type":"string"},"enabled":{"description":"Enabled is the EFFECTIVE isolation state for this server: whether its\nprocess is actually CONFINED, after the global setting, the per-server\noverride, the structural gates and the host's capabilities. It is NOT the\nraw per-server override — read EnabledOverride for that (GH #1142).\n\nREAD-ONLY. The write surfaces reject an ` + "`" + `enabled` + "`" + ` key precisely because\nit is derived: echoing it back would convert \"inherits the global\nsetting\" into a permanent explicit override. Write EnabledOverride.\n\nIt stays a non-pointer bool that is always present on the wire: the macOS\ntray decodes it as a non-optional Swift Bool, so omitting or nulling the\nkey would fail Codable for the whole server payload. Older clients that\nread this field now simply get a true answer.","type":"boolean"},"enabled_override":{"description":"EnabledOverride is the RAW per-server ` + "`" + `isolation.enabled` + "`" + ` override, as\npersisted. Absent means \"inherit the global setting\" — which is a\ndistinct state from an explicit false, and the distinction the reporting\nbug used to destroy.","type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"memory_limit":{"type":"string"},"mode_override":{"description":"ModeOverride is the RAW per-server ` + "`" + `isolation.mode` + "`" + ` override\n(\"docker\" | \"sandbox\" | \"none\"). Absent means \"inherit\".","type":"string"},"network_mode":{"type":"string"},"timeout":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationDefaults":{"description":"IsolationDefaults exposes the resolved baseline values that\nwould apply when no per-server override is set. Populated on\nlist/get responses; never consumed on PATCH requests.","properties":{"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"network_mode":{"type":"string"},"runtime_type":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"contracts.IsolationEffective":{"description":"IsolationEffective exposes the resolved isolation state (and the rule\nthat decided it) so clients can distinguish \"inherits global\" from an\nexplicit per-server choice. Read-only; never consumed on PATCH.","properties":{"global_mode":{"description":"GlobalMode is what \"inherit\" resolves to right now.","type":"string"},"inherited":{"description":"Inherited is true when the server sets neither ` + "`" + `isolation.enabled` + "`" + ` nor\n` + "`" + `isolation.mode` + "`" + `, so its state tracks the global setting.","type":"boolean"},"isolated":{"description":"Isolated reports whether the process is actually CONFINED. It is NOT\nsimply Mode != \"none\": \"sandbox\" on a host that cannot enforce Landlock\n(any non-Linux OS, or a kernel without the LSM) runs the server\nunconfined, and Source then says \"sandbox-unavailable\" (GH #1142).","type":"boolean"},"mode":{"description":"Mode is the effective isolation mode: \"docker\" | \"sandbox\" | \"none\" —\nexactly what the spawn path branches on.","type":"string"},"source":{"description":"Source names the deciding rule: \"global\", \"server-mode\",\n\"server-opt-out\", \"server-opt-in-ignored\", \"not-stdio\",\n\"already-docker\", \"sandbox-unavailable\" or \"unsupported-mode\".\nTreat an unrecognized value as \"global\".","type":"string"}},"type":"object"},"contracts.LogEntry":{"properties":{"fields":{"type":"object"},"level":{"type":"string"},"message":{"type":"string"},"server":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.MCPSession":{"properties":{"client_name":{"type":"string"},"client_version":{"type":"string"},"end_time":{"type":"string"},"experimental":{"items":{"type":"string"},"type":"array","uniqueItems":false},"has_roots":{"description":"MCP Client Capabilities","type":"boolean"},"has_sampling":{"type":"boolean"},"id":{"type":"string"},"last_activity":{"type":"string"},"start_time":{"type":"string"},"status":{"type":"string"},"tool_call_count":{"type":"integer"},"total_tokens":{"type":"integer"},"work_session_id":{"type":"string"},"workspace_name":{"description":"Workspace / work session (Spec 082). WorkspaceName is the project's\nbasename — the full local path is never exposed. WorkSessionID groups the\nreconnects that make up one stretch of user work.","type":"string"}},"type":"object"},"contracts.MetadataStatus":{"properties":{"authorization_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"error":{"type":"string"},"found":{"type":"boolean"},"url_checked":{"type":"string"}},"type":"object"},"contracts.MissingSecretInfo":{"properties":{"secret_name":{"type":"string"},"used_by":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.NPMPackageInfo":{"properties":{"exists":{"type":"boolean"},"install_cmd":{"type":"string"}},"type":"object"},"contracts.OAuthConfig":{"properties":{"auth_url":{"type":"string"},"client_id":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_port":{"type":"integer"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false},"token_expires_at":{"description":"When the OAuth token expires","type":"string"},"token_url":{"type":"string"},"token_valid":{"description":"Whether token is currently valid","type":"boolean"}},"type":"object"},"contracts.OAuthErrorDetails":{"description":"Structured discovery/failure details","properties":{"authorization_server_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"dcr_status":{"$ref":"#/components/schemas/contracts.DCRStatus"},"protected_resource_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"server_url":{"type":"string"}},"type":"object"},"contracts.OAuthFlowError":{"properties":{"correlation_id":{"description":"Flow tracking ID for log correlation","type":"string"},"debug_hint":{"description":"CLI command for log lookup","type":"string"},"details":{"$ref":"#/components/schemas/contracts.OAuthErrorDetails"},"error_code":{"description":"Machine-readable error code (e.g., OAUTH_NO_METADATA)","type":"string"},"error_type":{"description":"Category of OAuth runtime failure","type":"string"},"message":{"description":"Human-readable error description","type":"string"},"request_id":{"description":"HTTP request ID (from PR #237)","type":"string"},"server_name":{"description":"Server that failed OAuth","type":"string"},"success":{"description":"Always false","type":"boolean"},"suggestion":{"description":"Actionable remediation hint","type":"string"}},"type":"object"},"contracts.OAuthIssue":{"properties":{"documentation_url":{"type":"string"},"error":{"type":"string"},"issue":{"type":"string"},"missing_params":{"items":{"type":"string"},"type":"array","uniqueItems":false},"resolution":{"type":"string"},"server_name":{"type":"string"}},"type":"object"},"contracts.OAuthRequirement":{"properties":{"expires_at":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"state":{"type":"string"}},"type":"object"},"contracts.OAuthStartResponse":{"properties":{"auth_url":{"description":"Authorization URL (always included for manual use)","type":"string"},"browser_error":{"description":"Error message if browser launch failed","type":"string"},"browser_opened":{"description":"Whether browser launch succeeded","type":"boolean"},"correlation_id":{"description":"UUID for tracking this flow","type":"string"},"message":{"description":"Human-readable status message","type":"string"},"server_name":{"description":"Name of the server being authenticated","type":"string"},"success":{"description":"Always true for successful start","type":"boolean"}},"type":"object"},"contracts.PreflightPolicy":{"properties":{"exclude_destructive":{"type":"boolean"},"exclude_open_world":{"type":"boolean"},"read_only_only":{"type":"boolean"}},"type":"object"},"contracts.PreflightReason":{"type":"string","x-enum-varnames":["PreflightReasonServerInitializing","PreflightReasonServerUnhealthy","PreflightReasonServerDisabled","PreflightReasonServerQuarantined","PreflightReasonToolPendingApproval","PreflightReasonToolChanged","PreflightReasonToolBlockedByUser","PreflightReasonOAuthRequired","PreflightReasonHashMismatch","PreflightReasonServerNotInScope","PreflightReasonToolDeniedByConfig","PreflightReasonMissingAnnotation","PreflightReasonPolicyFiltered","PreflightReasonNotFound","PreflightReasonServerNotConfigured"]},"contracts.PreflightRequest":{"properties":{"policy":{"$ref":"#/components/schemas/contracts.PreflightPolicy"},"profile":{"description":"Profile evaluates under a named profile's server scope. Unknown: 400.","type":"string"},"tools":{"description":"Tools is 1..100 entries BEFORE dedup; duplicates are collapsed, and\nduplicate ids carrying different pins are a validation error.","items":{"$ref":"#/components/schemas/contracts.PreflightToolRef"},"type":"array","uniqueItems":false},"wait_ms":{"description":"WaitMS polls local state for up to this many milliseconds (cap 10000)\nwhile every failure is retryable-class.","type":"integer"}},"type":"object"},"contracts.PreflightResponse":{"properties":{"checked_at":{"type":"string"},"tools":{"description":"Tools are ordered by first occurrence of each unique id in the request.","items":{"$ref":"#/components/schemas/contracts.PreflightToolResult"},"type":"array","uniqueItems":false},"verdict":{"$ref":"#/components/schemas/contracts.PreflightVerdict"},"waited_ms":{"description":"WaitedMS is present when wait_ms was requested (0 when the wait\nsemaphore was exhausted and the request resolved immediately).","type":"integer"}},"type":"object"},"contracts.PreflightStatus":{"type":"string","x-enum-varnames":["PreflightStatusReady","PreflightStatusUnavailable"]},"contracts.PreflightToolRef":{"properties":{"id":{"description":"ID is a canonical \"\u003cserver\u003e:\u003ctool\u003e\" id. A malformed id is answered with a\nper-ID not_found carrying a format hint, never a request-level error.","type":"string"},"pin_hash":{"description":"PinHash is \"sha256/v{N}:{hex}\" — the schema version is embedded so a\nproxy-side hash-algorithm bump is distinguishable from upstream drift.","type":"string"}},"type":"object"},"contracts.PreflightToolResult":{"properties":{"action":{"type":"string"},"detail":{"type":"string"},"did_you_mean":{"description":"DidYouMean carries up to 3 nearest caller-visible ids on not_found. It\nnever crosses a scope boundary and never names a quarantined server's\ntools.","items":{"type":"string"},"type":"array","uniqueItems":false},"hash":{"description":"Hash is the tool's current pin (\"sha256/v{N}:{hex}\") — operator tier,\nready results only. Never disclosed to an agent token.","type":"string"},"id":{"type":"string"},"reason":{"$ref":"#/components/schemas/contracts.PreflightReason"},"remediation":{"type":"string"},"retryable":{"type":"boolean"},"status":{"$ref":"#/components/schemas/contracts.PreflightStatus"}},"type":"object"},"contracts.PreflightVerdict":{"type":"string","x-enum-varnames":["PreflightVerdictReady","PreflightVerdictDegradedRetryable","PreflightVerdictBlocked","PreflightVerdictUnknownIDs"]},"contracts.QuarantineStats":{"description":"Tool quarantine metrics for this server","properties":{"blocked_count":{"description":"Number of disabled (blocked) tools","type":"integer"},"changed_count":{"description":"Number of tools whose description/schema changed since approval","type":"integer"},"pending_count":{"description":"Number of newly discovered tools awaiting approval","type":"integer"}},"type":"object"},"contracts.RefreshRegistryResponse":{"properties":{"cleared":{"description":"number of cached entries dropped","type":"integer"},"registry_id":{"type":"string"}},"type":"object"},"contracts.Registry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag (MCP-866): \"official/trusted\" for built-in\ndefaults, \"custom/unverified\" for user-added registries.","type":"string"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"trusted":{"description":"Trusted indicates whether this is an official, shipped-by-default\nregistry. Trust is derived from membership in the default set, never\nfrom self-assertion in config.","type":"boolean"},"url":{"type":"string"}},"type":"object"},"contracts.RegistryCacheInfo":{"properties":{"age_seconds":{"type":"number"},"stale":{"type":"boolean"}},"type":"object"},"contracts.RegistryUnavailable":{"properties":{"reason":{"type":"string"}},"type":"object"},"contracts.ReplayToolCallRequest":{"properties":{"arguments":{"description":"Modified arguments for replay","type":"object"}},"type":"object"},"contracts.ReplayToolCallResponse":{"properties":{"error":{"description":"Error if replay failed","type":"string"},"new_call_id":{"description":"ID of the newly created call","type":"string"},"new_tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"replayed_from":{"description":"Original call ID","type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.RepositoryInfo":{"description":"Detected package info","properties":{"npm":{"$ref":"#/components/schemas/contracts.NPMPackageInfo"}},"type":"object"},"contracts.RepositoryServer":{"properties":{"connect_url":{"description":"Alternative connection URL","type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"install_cmd":{"description":"Installation command","type":"string"},"name":{"type":"string"},"registry":{"description":"Which registry this came from","type":"string"},"repository_info":{"$ref":"#/components/schemas/contracts.RepositoryInfo"},"source_code_url":{"description":"Source repository URL","type":"string"},"updated_at":{"type":"string"},"url":{"description":"MCP endpoint for remote servers only","type":"string"}},"type":"object"},"contracts.SearchRegistryServersResponse":{"properties":{"cache":{"$ref":"#/components/schemas/contracts.RegistryCacheInfo"},"query":{"type":"string"},"registry_id":{"type":"string"},"servers":{"items":{"$ref":"#/components/schemas/contracts.RepositoryServer"},"type":"array","uniqueItems":false},"tag":{"type":"string"},"total":{"type":"integer"},"unavailable":{"$ref":"#/components/schemas/contracts.RegistryUnavailable"}},"type":"object"},"contracts.SearchResult":{"properties":{"matches":{"type":"integer"},"score":{"type":"number"},"snippet":{"type":"string"},"tool":{"$ref":"#/components/schemas/contracts.Tool"}},"type":"object"},"contracts.SearchToolsResponse":{"properties":{"query":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/contracts.SearchResult"},"type":"array","uniqueItems":false},"took":{"type":"string"},"total":{"type":"integer"}},"type":"object"},"contracts.SecurityScanSummary":{"description":"Latest security scan results summary","properties":{"deep_scan":{"$ref":"#/components/schemas/contracts.DeepScanDescriptor"},"finding_counts":{"$ref":"#/components/schemas/contracts.FindingCounts"},"last_scan_at":{"type":"string"},"risk_score":{"description":"0-100","type":"integer"},"scanners_failed":{"type":"integer"},"scanners_run":{"description":"Scanner coverage for the primary (baseline) scan pass — informational only.\nSpec 077 US3 (FR-008/FR-014): Status is derived SOLELY from the\ndeterministic baseline findings; a failed Docker deep scanner no longer\ndowngrades a clean verdict. That failure is surfaced via DeepScan instead.","type":"integer"},"scanners_total":{"type":"integer"},"status":{"description":"\"clean\", \"warnings\", \"dangerous\", \"failed\", \"not_scanned\", \"scanning\"","type":"string"}},"type":"object"},"contracts.Server":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"authenticated":{"description":"OAuth authentication status","type":"boolean"},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges mirrors config.ServerConfig.AutoApproveToolChanges\n(MCP-2930): the per-server intent to auto-approve new/changed tools past\nthe trust baseline. Tri-state *bool — nil means \"never set\" (omitted from\nthe payload), so the Web UI toggle (MCP-2932) can distinguish unset from\nan explicit false. Read-only on the GET path; PATCH/POST accept it via\nAddServerRequest.","type":"boolean"},"command":{"type":"string"},"connected":{"type":"boolean"},"connected_at":{"type":"string"},"connecting":{"type":"boolean"},"created":{"type":"string"},"diagnostic":{"$ref":"#/components/schemas/contracts.Diagnostic"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"error_code":{"type":"string"},"expose_prompts":{"description":"ExposePrompts mirrors config.ServerConfig.ExposePrompts (F9): the per-server\nprompt-aggregation override. Tri-state *bool — nil/omitted means \"inherit\ndefault aggregation\". Surfaced on GET so a caller that PATCHed the override\ncan read it back; PATCH/POST accept it via AddServerRequest.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"health":{"$ref":"#/components/schemas/contracts.HealthStatus"},"id":{"type":"string"},"init_timeout":{"description":"InitTimeout mirrors config.ServerConfig.InitTimeout (MCP-3322 / GH #760):\nthe per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override. Serialized as\na duration string (e.g. \"120s\"); nil/omitted means \"inherit the global\ndefault\". Surfaced on the GET path so clients can read back a configured\noverride; PATCH/POST accept it via AddServerRequest.","type":"string"},"isolation":{"$ref":"#/components/schemas/contracts.IsolationConfig"},"isolation_defaults":{"$ref":"#/components/schemas/contracts.IsolationDefaults"},"isolation_effective":{"$ref":"#/components/schemas/contracts.IsolationEffective"},"last_error":{"type":"string"},"last_reconnect_at":{"type":"string"},"last_retry_time":{"type":"string"},"max_concurrent_requests":{"description":"Spec 093 (GH #955) — per-server concurrency overrides, scope (c) of\nFR-020. Each setting is tri-state: nil (omitted) means \"inherit\nserver_concurrency_defaults\", 0 disables that setting for this server,\npositive overrides it. Surfaced on the GET path so a caller can read back\nwhat it set; PATCH/POST accept them via AddServerRequest. The effective\nconcurrency for a server is additionally bounded by the global aggregate\nlimiter, which is NOT an inheritance source for these fields.","type":"integer"},"name":{"type":"string"},"oauth":{"$ref":"#/components/schemas/contracts.OAuthConfig"},"oauth_status":{"description":"OAuth status: \"authenticated\", \"expired\", \"error\", \"none\"","type":"string"},"protocol":{"type":"string"},"quarantine":{"$ref":"#/components/schemas/contracts.QuarantineStats"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_count":{"type":"integer"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets this disconnected server","type":"boolean"},"retry_count":{"type":"integer"},"retry_stopped":{"description":"RetryStopped reports that automatic reconnection has been given up for\ngood because the failure is deterministic and unrecoverable — a missing\nbinary, an image without the interpreter, an unparseable config (GH\n#1145). It is NOT ordinary exponential backoff, which keeps retrying;\nnothing will happen until the user fixes the config or restarts the\nserver. RetryStoppedCode is the stable MCPX_* code that proved it and\nRetryStoppedReason the catalog message explaining how to fix it. All three\nare omitted for servers that are healthy or still retrying.","type":"boolean"},"retry_stopped_code":{"type":"string"},"retry_stopped_reason":{"type":"string"},"security_scan":{"$ref":"#/components/schemas/contracts.SecurityScanSummary"},"should_retry":{"type":"boolean"},"source_registry_id":{"description":"MCP-901 — registry provenance of an upstream that was added from a\nregistry. SourceRegistryID names the source registry (empty for\nmanually-configured servers); SourceRegistryProvenance is the trust tag\nrecorded at add time (\"official/trusted\" or \"custom/unverified\"). Both\nare projected from config.ServerConfig so the approval/quarantine view\ncan render an \"added from \u003cregistry\u003e · unverified\" origin badge. Optional\nand omitted when empty — clients that pre-date this treat them as absent.","type":"string"},"source_registry_provenance":{"type":"string"},"status":{"type":"string"},"token_expires_at":{"description":"When the OAuth token expires (ISO 8601)","type":"string"},"tool_count":{"type":"integer"},"tool_list_token_size":{"description":"Token size for this server's tools","type":"integer"},"trust_mode":{"description":"TrustMode mirrors config.ServerConfig.TrustMode (spec 086): the per-server\ntrust tier (\"auto\"/\"scan\"/\"manual\"). Surfaced on the GET path so clients can\nread back the persisted mode; PATCH/POST accept it via AddServerRequest.\nOmitted when empty (server predates the field / relies on legacy flags).","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"user_logged_out":{"description":"True if user explicitly logged out (prevents auto-reconnection)","type":"boolean"},"working_dir":{"type":"string"}},"type":"object"},"contracts.ServerActionResponse":{"properties":{"action":{"type":"string"},"async":{"type":"boolean"},"server":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ServerStats":{"properties":{"connected_servers":{"type":"integer"},"docker_containers":{"type":"integer"},"quarantined_servers":{"type":"integer"},"token_metrics":{"$ref":"#/components/schemas/contracts.ServerTokenMetrics"},"total_servers":{"type":"integer"},"total_tools":{"type":"integer"}},"type":"object"},"contracts.ServerTokenMetrics":{"properties":{"average_query_result_size":{"description":"Typical retrieve_tools output (tokens)","type":"integer"},"per_server_tool_list_sizes":{"additionalProperties":{"type":"integer"},"description":"Token size per server","type":"object"},"saved_tokens":{"description":"Difference","type":"integer"},"saved_tokens_percentage":{"description":"Percentage saved","type":"number"},"total_server_tool_list_size":{"description":"All upstream tools combined (tokens)","type":"integer"}},"type":"object"},"contracts.SuccessResponse":{"properties":{"data":{"type":"object"},"success":{"type":"boolean"}},"type":"object"},"contracts.Tier":{"description":"Tier is computed by AnnotationTier (Spec 109 FR-028/X11) from\nAnnotations — read|write|destructive|unannotated. Set by every producer\nof a Tool (enrichServerTools, the global tools handler); never left for\na consuming surface to compute.","type":"string","x-enum-varnames":["TierRead","TierWrite","TierDestructive","TierUnannotated","TierUnknown"]},"contracts.TokenMetrics":{"description":"Token usage metrics (nil for older records)","properties":{"encoding":{"description":"Encoding used (e.g., cl100k_base)","type":"string"},"estimated_cost":{"description":"Optional cost estimate","type":"number"},"input_tokens":{"description":"Tokens in the request","type":"integer"},"model":{"description":"Model used for tokenization","type":"string"},"output_tokens":{"description":"Tokens in the response","type":"integer"},"total_tokens":{"description":"Total tokens (input + output)","type":"integer"},"truncated_tokens":{"description":"Tokens removed by truncation","type":"integer"},"was_truncated":{"description":"Whether response was truncated","type":"boolean"}},"type":"object"},"contracts.Tool":{"properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"approval_status":{"type":"string"},"config_denied":{"description":"ConfigDenied is true when the tool is denied by the server's static\nenabled_tools / disabled_tools config. The user cannot override this toggle.","type":"boolean"},"description":{"type":"string"},"disabled":{"description":"Disabled mirrors ToolApprovalRecord.Disabled so per-tool enable state is\navailable without a second round-trip to the approvals endpoint. Absent\nin the JSON when false (default) to keep responses compact.","type":"boolean"},"hash":{"description":"Hash is the tool's current stored hash rendered in the preflight pin\nformat \"sha256/v{N}:{hex}\" (Spec 098 FR-011), where N is the approval\nrecord's HashSchemaVersion. It is the authoring surface for\n` + "`" + `POST /api/v1/preflight` + "`" + ` pins and ` + "`" + `mcpproxy tools preflight --pin` + "`" + `:\ncopy the value straight into a pin.\n\nDisclosure is OPERATOR TIER ONLY — same rule as the preflight per-tool\nresult. The field is omitted for agent-token callers and for tools with\nno stored hash (no approval record yet, or a record written before\nhashes existed).","type":"string"},"held_reason":{"description":"HeldReason, HeldVerdict and HeldSignals mirror the same-named fields on\nstorage.ToolApprovalRecord: the offline-scan evidence that made\ntrust_mode: scan hold this tool for review (spec 086 FR-018). HeldSignals\nnames the matched deterministic check ids, e.g.\n\"tpa.TPA-2026-0001.hidden_instruction\", so a reviewer can see WHY the tool\nis held. All three are omitted for tools that are not held by the scan gate\n(including every record written before the field existed).","type":"string"},"held_signals":{"items":{"type":"string"},"type":"array","uniqueItems":false},"held_verdict":{"type":"string"},"last_used":{"type":"string"},"name":{"type":"string"},"schema":{"type":"object"},"server_name":{"type":"string"},"tier":{"$ref":"#/components/schemas/contracts.Tier"},"usage":{"type":"integer"}},"type":"object"},"contracts.ToolAnnotation":{"description":"Tool behavior hints snapshot","properties":{"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"},"readOnlyHint":{"type":"boolean"},"title":{"type":"string"}},"type":"object"},"contracts.ToolCallRecord":{"description":"The new tool call record","properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"arguments":{"description":"Tool arguments","type":"object"},"arguments_truncated":{"description":"ArgumentsTruncated marks Arguments as a placeholder rather than the\narguments the tool was called with. Replaying such a record without\nsupplying arguments explicitly is refused.","type":"boolean"},"config_path":{"description":"Active config file path","type":"string"},"duration":{"description":"Duration in nanoseconds","type":"integer"},"error":{"description":"Error message (failure only)","type":"string"},"execution_type":{"description":"\"direct\" or \"code_execution\"","type":"string"},"id":{"description":"Unique identifier","type":"string"},"mcp_client_name":{"description":"MCP client name from InitializeRequest","type":"string"},"mcp_client_version":{"description":"MCP client version","type":"string"},"mcp_session_id":{"description":"MCP session identifier","type":"string"},"metrics":{"$ref":"#/components/schemas/contracts.TokenMetrics"},"parent_call_id":{"description":"Links nested calls to parent code_execution","type":"string"},"request_id":{"description":"Request correlation ID","type":"string"},"response":{"description":"Tool response (success only)","type":"object"},"response_bytes":{"description":"Marshalled response size before truncation","type":"integer"},"response_truncated":{"description":"ResponseTruncated and ResponseBytes describe a STORAGE-side cut (#1176):\nthe caller received the response whole, and only the persisted copy was\nshortened to tool_call_max_response_size. When ResponseTruncated is true\nthe Response object carries {truncated, original_bytes, preview, note}\ninstead of the upstream result, and ResponseBytes is its size before the\ncut.","type":"boolean"},"server_id":{"description":"Server identity hash","type":"string"},"server_name":{"description":"Human-readable server name","type":"string"},"timestamp":{"description":"When the call was made","type":"string"},"tool_name":{"description":"Tool name (without server prefix)","type":"string"}},"type":"object"},"contracts.UpdateInfo":{"description":"Update information (if available)","properties":{"available":{"description":"Whether an update is available","type":"boolean"},"behind_summary":{"description":"Spec 079 FR-002 — how far behind the running build is. All four are\nadditive (FR-021) and absent when the delta could not be resolved, in\nwhich case every surface renders its pre-delta wording.","type":"string"},"check_error":{"description":"Error message if update check failed","type":"string"},"checked_at":{"description":"When the update check was performed","type":"string"},"install_channel":{"description":"Detected install channel (homebrew, dmg, deb, rpm, docker, go-install, windows-installer, tarball, unknown) — Spec 079 FR-008","type":"string"},"is_prerelease":{"description":"Whether the latest version is a prerelease","type":"boolean"},"latest_version":{"description":"Latest version available (e.g., \"v1.2.3\")","type":"string"},"nudges_suppressed":{"description":"UI surfaces must stay quiet (CI / non-interactive context); machine-readable fields still report the facts — Spec 079 FR-019","type":"boolean"},"release_url":{"description":"URL to the release page","type":"string"},"releases_behind":{"description":"Releases on the offered channel between the running and offered versions","type":"integer"},"releases_behind_saturated":{"description":"ReleasesBehind is a lower bound: the running build predates the scanned release window","type":"boolean"},"update_command":{"description":"One-line update command for the channel; only set when an update is available and the channel has one — Spec 079 FR-009","type":"string"},"weeks_behind":{"description":"Whole weeks between the two releases' publish dates; 0 is a real value, absent means unknown","type":"integer"}},"type":"object"},"contracts.UpdatePolicy":{"description":"UpdatePolicy is the effective, hot-reloadable update policy (Spec 092\nFR-015). Always present: the ` + "`" + `update` + "`" + ` object above is omitted both when\nupdate checking is disabled AND when no check has produced a result\nyet, so its absence cannot tell a client whether it is allowed to run\nits own (e.g. Sparkle feed) check. This field states the answer.","properties":{"channel":{"description":"Channel is the tracked release channel: \"stable\" or \"rc\".","type":"string"},"enabled":{"description":"Enabled is the effective automatic-check kill switch: update_check.enabled\nwith MCPPROXY_DISABLE_AUTO_UPDATE=true winning over it. A user-initiated\n\"Check for Updates\" stays available regardless.","type":"boolean"},"nudges_suppressed":{"description":"NudgesSuppressed asks UI surfaces to stay quiet (CI / non-interactive)\nwhile machine-readable fields keep reporting the facts.","type":"boolean"}},"type":"object"},"contracts.UpstreamError":{"properties":{"error_message":{"type":"string"},"server_name":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.UsageAggregateResponse":{"properties":{"freshness_ms":{"description":"age of the underlying snapshot in ms","type":"integer"},"generated_at":{"type":"string"},"other":{"$ref":"#/components/schemas/contracts.UsageOtherBucket"},"timeline":{"items":{"$ref":"#/components/schemas/contracts.UsageTimeBucket"},"type":"array","uniqueItems":false},"token_source":{"description":"\"bytes\" (size-based proxy, FR-006)","type":"string"},"tokens_saved":{"description":"echoed from ServerTokenMetrics (FR-007)","type":"integer"},"tokens_saved_percentage":{"type":"number"},"tools":{"items":{"$ref":"#/components/schemas/contracts.UsageToolStat"},"type":"array","uniqueItems":false},"total_calls":{"description":"TotalCalls and TotalErrors are the headline counts for the window: the sum\nof the timeline this same response carries, so the tiles and the histogram\nunder them cannot disagree. They are NOT the sum of Tools — that list is\nlifetime-cumulative, upstream-only and truncated to top-N, and summing it\nclient-side is what made the Usage tab print a third number for the same\n24 hours (audit finding F1, #1046). The population is\nstorage.CountsAsCall, shared with ActivitySummaryResponse.CallCount.\n\nTwo bounds on how exactly this matches the Activity Log's own count.\nBoth are bounded and disclosed, unlike the population mismatch they\nreplace, which was unbounded and silent:\n\n  - Window granularity is the timeline's: whole hour buckets, so the span\n    is the requested window rounded up to a bucket edge.\n  - This response is served from a snapshot behind a short read cache\n    (observability.usage_cache_ttl, 5s by default) so the endpoint never\n    scans the activity log per request, while the summary endpoint counts\n    live. Calls that land inside that window appear on the Activity Log\n    first. FreshnessMs and GeneratedAt say how old the figures are, and\n    the Usage tab prints it (\"Updated 3s ago\").","type":"integer"},"total_errors":{"type":"integer"},"window":{"type":"string"}},"type":"object"},"contracts.UsageOtherBucket":{"description":"present only when the list was truncated to top-N","properties":{"calls":{"type":"integer"},"tools_folded":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageTimeBucket":{"properties":{"calls":{"type":"integer"},"errors":{"type":"integer"},"start":{"type":"string"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageToolStat":{"properties":{"avg_req_bytes":{"description":"null when no sized request calls","type":"integer"},"avg_resp_bytes":{"description":"null when sized_calls == 0 (only legacy 0-byte calls)","type":"integer"},"blocked":{"type":"integer"},"calls":{"type":"integer"},"error_rate":{"type":"number"},"errors":{"type":"integer"},"last_used":{"type":"string"},"p50_exceeds":{"type":"boolean"},"p50_ms":{"description":"P50Ms and P95Ms are read off a fixed latency histogram, so they are BUCKET\nBOUNDS, not measured durations: the true percentile is at or below the\nvalue, and a client must render it as a bound (\"≤ 5 ms\"). P50Exceeds /\nP95Exceeds flip that reading for the unbounded overflow bucket, where the\nvalue is the last bound and the truth is above it (\"\u003e 10 s\").","type":"integer"},"p95_exceeds":{"type":"boolean"},"p95_ms":{"type":"integer"},"rejected":{"description":"spec 093: shed by a concurrency limit; never executed, so excluded from calls/latency","type":"integer"},"server":{"type":"string"},"sized_calls":{"description":"calls with known response size (basis for avg_resp_bytes)","type":"integer"},"tool":{"type":"string"},"total_req_bytes":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.ValidateConfigResponse":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false},"valid":{"type":"boolean"}},"type":"object"},"contracts.ValidationError":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"data":{"properties":{"data":{"$ref":"#/components/schemas/contracts.InfoResponse"}},"type":"object"},"httpapi.AddServerRequest":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve\nnew/changed tools past the trust baseline (MCP-2930). Tri-state *bool:\na nil pointer means \"leave unchanged\" on PATCH; a present value\n(including false) is applied. Mirrors config.ServerConfig's *bool\nsemantics — do NOT collapse to a plain bool, or an omitted field would\nsilently reset a previously-set value.","type":"boolean"},"command":{"type":"string"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"expose_prompts":{"description":"ExposePrompts is the per-server override for prompt aggregation (F9):\nwhether this server's advertised MCP prompts are merged into mcpproxy's\nprompts/list. Tri-state *bool mirroring config.ServerConfig.ExposePrompts —\na nil pointer means \"leave unchanged\" on PATCH (and \"inherit the default\naggregate behavior\" on create); a present value (including false) is applied.","type":"boolean"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"init_timeout":{"description":"InitTimeout is the per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override\n(MCP-3322 / GH #760), serialized as a duration string (e.g. \"120s\"). A nil\npointer means \"leave unchanged\" on PATCH; a present value is applied.\nMirrors config.ServerConfig.InitTimeout's *Duration tri-state.","type":"string"},"isolation":{"$ref":"#/components/schemas/httpapi.IsolationRequest"},"max_concurrent_requests":{"description":"MaxConcurrentRequests / QueueSize / QueueTimeout are the per-server\nconcurrency overrides (spec 093 / GH #955, FR-020 scope (c)). Each is\ntri-state: a nil pointer means \"leave unchanged\" on PATCH and \"inherit\nserver_concurrency_defaults\" on create; an explicit 0 disables that\nsetting for this server; a positive value overrides it. Do NOT collapse\nthem to plain values — an omitted field would then silently reset a\nconfigured limit.","type":"integer"},"name":{"type":"string"},"protocol":{"type":"string"},"quarantined":{"type":"boolean"},"queue_size":{"type":"integer"},"queue_timeout":{"type":"string"},"reconnect_on_use":{"type":"boolean"},"trust_mode":{"description":"TrustMode is the per-server trust tier (spec 086): \"auto\", \"scan\", or\n\"manual\". Empty means \"leave unchanged\" on PATCH (and inherit the migrated\ndefault on create). A non-empty value is applied to ServerConfig.TrustMode\nand resolved by EffectiveTrustMode (an unrecognized value fails closed to\nmanual). This is the REST seam for changing the trust tier via\nPOST/PATCH /api/v1/servers.","type":"string"},"url":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.CanonicalConfigPath":{"properties":{"description":{"description":"Brief description","type":"string"},"exists":{"description":"Whether the file exists","type":"boolean"},"format":{"description":"Format identifier (e.g., \"claude_desktop\")","type":"string"},"name":{"description":"Display name (e.g., \"Claude Desktop\")","type":"string"},"os":{"description":"Operating system (darwin, windows, linux)","type":"string"},"path":{"description":"Full path to the config file","type":"string"}},"type":"object"},"httpapi.CanonicalConfigPathsResponse":{"properties":{"os":{"description":"Current operating system","type":"string"},"paths":{"description":"List of canonical config paths","items":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPath"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ConnectConflictResponse":{"properties":{"action":{"description":"already_exists | precondition_failed","type":"string"},"data":{"$ref":"#/components/schemas/connect.ConnectResult"},"error":{"description":"Human-readable message","type":"string"},"success":{"description":"Always false","type":"boolean"}},"type":"object"},"httpapi.ConnectRequest":{"properties":{"force":{"description":"Overwrite existing entry","type":"boolean"},"precondition_token":{"description":"PreconditionToken is the opaque token from the preview this write was\nconfirmed against (Spec 091 FR-005). When present, the core rechecks it\nat write time and responds 409 with action \"precondition_failed\" —\nwriting nothing — if the config or the entry MCPProxy would write has\ndrifted since; the caller then re-previews instead of retrying. Absent\nmeans exactly the pre-091 behavior. A replace-classified flow sends this\nTOGETHER with force=true: the token, not the absence of force, is the\noverwrite safety.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.EnvFieldPreview":{"properties":{"empty_or_placeholder":{"type":"boolean"},"name":{"type":"string"},"secret_like":{"type":"boolean"},"value_present":{"type":"boolean"}},"type":"object"},"httpapi.HeaderFieldPreview":{"properties":{"empty_or_placeholder":{"type":"boolean"},"name":{"type":"string"},"secret_like":{"type":"boolean"}},"type":"object"},"httpapi.ImportFromPathRequest":{"properties":{"format":{"description":"Optional format hint","type":"string"},"path":{"description":"File path to import from","type":"string"},"rename":{"additionalProperties":{"type":"string"},"description":"Rename maps a server name → new name. Applied after parsing so the\ncaller can disambiguate cross-source name collisions (Spec 046 v2 —\ne.g. \"mcpproxy\" → \"mcpproxy_claude_code\"). Keys are matched against\neither the raw source name (OriginalName) or the sanitized name shown\nin the preview (Server.Name); these differ for names that need\nsanitizing (e.g. \"Figma Desktop\" → \"Figma_Desktop\"). Keys not present\nin the imported set are ignored.","type":"object"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportRequest":{"properties":{"content":{"description":"Raw JSON or TOML content","type":"string"},"format":{"description":"Optional format hint","type":"string"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportResponse":{"properties":{"failed":{"items":{"$ref":"#/components/schemas/configimport.FailedServer"},"type":"array","uniqueItems":false},"format":{"type":"string"},"format_name":{"type":"string"},"imported":{"items":{"$ref":"#/components/schemas/httpapi.ImportedServerResponse"},"type":"array","uniqueItems":false},"skipped":{"items":{"$ref":"#/components/schemas/configimport.SkippedServer"},"type":"array","uniqueItems":false},"summary":{"$ref":"#/components/schemas/configimport.ImportSummary"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportedServerResponse":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"command":{"type":"string"},"env":{"items":{"$ref":"#/components/schemas/httpapi.EnvFieldPreview"},"type":"array","uniqueItems":false},"fields_skipped":{"items":{"type":"string"},"type":"array","uniqueItems":false},"headers":{"items":{"$ref":"#/components/schemas/httpapi.HeaderFieldPreview"},"type":"array","uniqueItems":false},"name":{"type":"string"},"original_name":{"type":"string"},"protocol":{"type":"string"},"source_format":{"type":"string"},"summary":{"description":"Summary, Tags, Env and Headers are the Spec 109 FR-064 preview\nenrichment (contracts/rest-api.md \"Import preview\"). Summary and Tags\nare built from the already-redacted URL/Command/Args above, so a\nsecret embedded in argv or a URL query never reaches Summary either.\nEnv/Headers never carry the raw value — only its presence and two\nbooleans a surface uses to default the Value/Secret toggle (FR-065).","type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"type":"string"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.IsolationRequest":{"description":"Isolation carries per-server Docker isolation overrides (enabled,\nmode_override, image, network_mode, extra_args, working_dir). A nil\npointer means \"do not touch isolation config\". A present object is\napplied field-by-field ON TOP of the persisted overrides, so omitting a\nfield leaves it alone; clear an individual override by sending it\nexplicitly (` + "`" + `\"enabled\": null` + "`" + `, ` + "`" + `\"image\": \"\"` + "`" + `).","properties":{"enabled":{"description":"Enabled exists ONLY to detect and reject an echoed-back read. It is the\neffective state on the read surface and is never writable; see validate().","type":"boolean"},"enabled_override":{"description":"EnabledOverride is the tri-state per-server override — the RAW value, the\nsame one reads return as ` + "`" + `enabled_override` + "`" + `. It has THREE meaningful wire\nstates, and collapsing them is what silently un-isolated servers\n(GH #1142):\n  - absent          → leave the persisted override untouched\n  - null            → clear the override, back to inheriting the global\n  - true / false    → set an explicit opt-in / opt-out","type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"mode_override":{"description":"ModeOverride sets ` + "`" + `isolation.mode` + "`" + ` (\"docker\" | \"sandbox\" | \"none\").\nnil leaves the persisted value alone; an empty string clears it. An\nunrecognized value is rejected with a 400 rather than persisted.","type":"string"},"network_mode":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.OnboardingMarkRequest":{"properties":{"connect_step_status":{"description":"ConnectStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value. The stored enum is wider (Spec 080\nFR-001): a \"skipped\" request for a previously untouched connect step\nis upgraded server-side to \"completed_external\" when the install\nshows positive evidence of an external connection (Spec 080 FR-002).\n\"completed_external\" is NOT accepted from clients — it must never be\npersisted without that server-verified evidence (edge case: \"never\nguess completed_external without positive evidence\").","type":"string"},"engaged":{"description":"Engaged marks the wizard as engaged (completed or explicitly skipped).\nOnce true, the wizard does not auto-show again.","type":"boolean"},"mark_shown":{"description":"MarkShown records the wizard's first display time if not already set.","type":"boolean"},"server_step_status":{"description":"ServerStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value.","type":"string"}},"type":"object"},"httpapi.SetActiveProfileRequest":{"properties":{"active_profile":{"type":"string"},"profile":{"type":"string"}},"type":"object"},"httpapi.UndoConnectRequest":{"properties":{"backup_name":{"description":"BackupName is the bare filename (filepath.Base) of the backup returned as\nbackup_path by the preceding connect — a name, never a path. Undo resolves\nthe full path server-side by joining it with the client's own config\ndirectory, so a client-supplied value can never contribute a directory\ncomponent (traversal is impossible by construction). Empty means the\nconnect created the file (no prior file existed), so undo removes it.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.UpdateFailureRequest":{"properties":{"stage":{"description":"Stage is the failure stage of the update session.","enum":["appcast","download","install","other"],"type":"string"}},"type":"object"},"management.BulkOperationResult":{"properties":{"errors":{"additionalProperties":{"type":"string"},"description":"Map of server name to error message","type":"object"},"failed":{"description":"Number of failed operations","type":"integer"},"successful":{"description":"Number of successful operations","type":"integer"},"total":{"description":"Total servers processed","type":"integer"}},"type":"object"},"observability.HealthResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"observability.HealthStatus":{"properties":{"error":{"type":"string"},"latency":{"type":"string"},"name":{"type":"string"},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"}},"type":"object"},"observability.ReadinessResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"ready\" or \"not_ready\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"secureenv.EnvConfig":{"description":"Environment configuration for secure variable filtering","properties":{"allowed_system_vars":{"items":{"type":"string"},"type":"array","uniqueItems":false},"custom_vars":{"additionalProperties":{"type":"string"},"type":"object"},"enhance_path":{"description":"Enable PATH enhancement for Launchd scenarios","type":"boolean"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned upstream servers (MCP-2769). It is OFF by\ndefault and deliberately kept out of the AllowedSystemVars default list:\nproxy URLs frequently carry credentials (http://user:pass@proxy), so\nforwarding them to every stdio upstream is a credential-leak risk. When\nenabled, values are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"inherit_system_safe":{"type":"boolean"}},"type":"object"},"telemetry.FeedbackContext":{"properties":{"arch":{"type":"string"},"connected_server_count":{"type":"integer"},"edition":{"type":"string"},"os":{"type":"string"},"routing_mode":{"type":"string"},"server_count":{"type":"integer"},"version":{"type":"string"}},"type":"object"},"telemetry.FeedbackRequest":{"properties":{"category":{"description":"bug, feature, other","type":"string"},"context":{"$ref":"#/components/schemas/telemetry.FeedbackContext"},"email":{"type":"string"},"message":{"type":"string"}},"type":"object"},"telemetry.FeedbackResponse":{"properties":{"error":{"type":"string"},"issue_url":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"API key authentication via query parameter. Use ?apikey=your-key","in":"query","name":"apikey","type":"apiKey"}}},
     "info": {"contact":{"name":"MCPProxy Support","url":"https://github.com/smart-mcp-proxy/mcpproxy-go"},"description":"{{escape .Description}}","license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"title":"{{.Title}}","version":"{{.Version}}"},
     "externalDocs": {"description":"","url":""},
-    "paths": {"/api/v1/activity":{"get":{"description":"Returns paginated list of activity records with optional filtering","parameters":[{"description":"Filter by activity type(s), comma-separated for multiple (Spec 024)","in":"query","name":"type","schema":{"enum":["tool_call","policy_decision","quarantine_change","server_change","system_start","system_stop","internal_tool_call","config_change","preflight","prompt_get"],"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"enum":["success","error","blocked","rejected"],"type":"string"}},{"description":"Filter by intent operation type (Spec 018)","in":"query","name":"intent_type","schema":{"enum":["read","write","destructive"],"type":"string"}},{"description":"Filter by HTTP request ID for log correlation (Spec 021)","in":"query","name":"request_id","schema":{"type":"string"}},{"description":"Filter by parent call id — returns the sub-calls one code_execution issued","in":"query","name":"parent_id","schema":{"type":"string"}},{"description":"Include successful call_tool_* internal tool calls (default: false, excluded to avoid duplicates)","in":"query","name":"include_call_tool","schema":{"type":"boolean"}},{"description":"Filter by sensitive data detection (true=has detections, false=no detections)","in":"query","name":"sensitive_data","schema":{"type":"boolean"}},{"description":"Filter by specific detection type (e.g., 'aws_access_key', 'credit_card')","in":"query","name":"detection_type","schema":{"type":"string"}},{"description":"Filter by severity level","in":"query","name":"severity","schema":{"enum":["critical","high","medium","low"],"type":"string"}},{"description":"Filter by agent token name (Spec 028)","in":"query","name":"agent","schema":{"type":"string"}},{"description":"Filter by auth type (Spec 028)","in":"query","name":"auth_type","schema":{"enum":["admin","agent"],"type":"string"}},{"description":"Filter activities after this time (RFC3339)","in":"query","name":"start_time","schema":{"type":"string"}},{"description":"Filter activities before this time (RFC3339)","in":"query","name":"end_time","schema":{"type":"string"}},{"description":"Maximum records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Pagination offset (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Omit arguments, response and metadata except a contextual whitelist (intent.reason, intent.operation_type, decision, reason, client_name, client_version) (default: false). For clients that render summary fields only; has_sensitive_data is still derived before metadata is dropped.","in":"query","name":"exclude_payloads","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"List activity records","tags":["Activity"]}},"/api/v1/activity/export":{"get":{"description":"Exports activity records in JSON Lines or CSV format for compliance","parameters":[{"description":"Export format: json (default) or csv","in":"query","name":"format","schema":{"type":"string"}},{"description":"Filter by activity type","in":"query","name":"type","schema":{"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"type":"string"}},{"description":"Filter by HTTP request ID for log correlation (Spec 021)","in":"query","name":"request_id","schema":{"type":"string"}},{"description":"Filter by parent call id — exports the sub-calls one code_execution issued","in":"query","name":"parent_id","schema":{"type":"string"}},{"description":"Filter activities after this time (RFC3339)","in":"query","name":"start_time","schema":{"type":"string"}},{"description":"Filter activities before this time (RFC3339)","in":"query","name":"end_time","schema":{"type":"string"}},{"description":"Maximum records to export (1-50000, default 10000)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Pagination offset (default 0)","in":"query","name":"offset","schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}}},"description":"Streamed activity records"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Export activity records","tags":["Activity"]}},"/api/v1/activity/summary":{"get":{"description":"Returns aggregated activity statistics for a time period","parameters":[{"description":"Time period: 1h, 24h (default), 7d, 30d","in":"query","name":"period","schema":{"type":"string"}},{"description":"Group by: server, tool (optional)","in":"query","name":"group_by","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity summary statistics","tags":["Activity"]}},"/api/v1/activity/usage":{"get":{"description":"Returns the actor-owned usage aggregate (per-tool rollup + timeline + tokens-saved headline) for the Web UI usage graphs (Spec 069). Served from an in-memory snapshot — never a per-request full-log scan. Per-tool metrics are lifetime-cumulative; ` + "`" + `window` + "`" + ` scopes the timeline and filters the tool list to tools active within the span.","parameters":[{"description":"Time window for timeline + tool-list membership","in":"query","name":"window","schema":{"enum":["24h","7d","all"],"type":"string"}},{"description":"Filter to one server","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter to one tool","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter to tools with activity of this status","in":"query","name":"status","schema":{"enum":["success","error","blocked","rejected"],"type":"string"}},{"description":"Top-N tools by sort key; remainder folded into 'other' (default 20)","in":"query","name":"top","schema":{"type":"integer"}},{"description":"Ranking key for the per-tool list","in":"query","name":"sort","schema":{"enum":["calls","resp_bytes","error_rate","p95"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get usage statistics aggregate","tags":["Activity"]}},"/api/v1/activity/{id}":{"get":{"description":"Returns full details for a single activity record","parameters":[{"description":"Activity record ID (ULID)","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Not Found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity record details","tags":["Activity"]}},"/api/v1/annotations/coverage":{"get":{"description":"Reports how many upstream tools have MCP annotations vs don't, broken down by server","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Annotation coverage report"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get annotation coverage report","tags":["annotations"]}},"/api/v1/code/scripts":{"get":{"description":"List the stored scripts available to the code_execution tool. Scripts are ` + "`" + `\u003cname\u003e.js` + "`" + ` / ` + "`" + `\u003cname\u003e.ts` + "`" + ` files in the ` + "`" + `scripts/` + "`" + ` directory next to the active configuration file. Entries are advisory: ` + "`" + `ok` + "`" + ` scripts are invocable, ` + "`" + `ambiguous` + "`" + ` names have both extensions, and ` + "`" + `invalid` + "`" + ` ones report why (empty, oversized, unreadable, non-regular). Read-only — there is no write surface for stored scripts. Administrator-only (Spec 105 FR-012): an agent token, whatever its server scope, is refused with 403 — the listing is the enumeration the missing-script error withholds from a scoped caller.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Stored scripts and the directory they were read from"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot list stored scripts"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List stored code-execution scripts","tags":["code"]}},"/api/v1/config":{"get":{"description":"Retrieves the current MCPProxy configuration including all server definitions, global settings, and runtime parameters","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetConfigResponse"}}},"description":"Configuration retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read the configuration document"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get current configuration","tags":["config"]},"patch":{"description":"Deep-merges only the fields present in the request body onto the live in-memory configuration and routes the result through the existing apply pipeline (validation, change detection, disk persistence, hot-reload). Fields the client omits — including masked secrets such as ` + "`" + `api_key` + "`" + ` and secret request headers — are preserved verbatim. Nested objects are merged recursively; arrays and scalars replace wholesale.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Partial configuration with only the fields to change","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Configuration patch applied (inspect validation_errors for rejected values)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload or empty patch"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to read or apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update configuration","tags":["config"]}},"/api/v1/config/apply":{"post":{"description":"Applies a new MCPProxy configuration. Validates and persists the configuration to disk. Some changes apply immediately, while others may require a restart. Returns detailed information about applied changes and restart requirements.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to apply","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Configuration applied successfully with change details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Apply configuration","tags":["config"]}},"/api/v1/config/docker-isolation":{"patch":{"description":"Convenience endpoint to flip ` + "`" + `docker_isolation.enabled` + "`" + ` without resending the full config. Persists to disk via the existing config writer — the file watcher then hot-reloads the change. Returns the new state and whether a restart is required for existing connections to pick it up.","requestBody":{"content":{"application/json":{"schema":{"properties":{"enabled":{"type":"boolean"}},"type":"object"}}},"description":"New isolation state","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Isolation toggle applied"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Toggle global Docker isolation","tags":["config"]}},"/api/v1/config/validate":{"post":{"description":"Validates a provided MCPProxy configuration without applying it. Checks for syntax errors, invalid server definitions, conflicting settings, and other configuration issues.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to validate","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ValidateConfigResponse"}}},"description":"Configuration validation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Validation failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Validate configuration","tags":["config"]}},"/api/v1/connect":{"get":{"description":"Returns the connection status for all known MCP client applications.\nEach entry indicates whether the client config file exists and whether\nMCPProxy is currently registered in it.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"List of ClientStatus objects"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List client connection status","tags":["connect"]}},"/api/v1/connect/{client}":{"delete":{"description":"Remove the MCPProxy entry from the specified client's configuration file.\nCreates a backup of the existing config before modifying.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional parameters (server_name)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or entry not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disconnect MCPProxy from a client","tags":["connect"]},"get":{"description":"Resolves one client's status by reading its config file on demand.\nThis is the only Connect endpoint that opens a client config file, so\non macOS it is the sole place an App-Data privacy prompt may legitimately\nappear (scoped to this user action). Resolves access_state to\naccessible|absent|denied|malformed and populates remediation when denied.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ClientStatus"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get a single client's connection status (on-demand)","tags":["connect"]},"post":{"description":"Register MCPProxy as an MCP server in the specified client's configuration file.\nCreates a backup of the existing config before modifying.\nOptionally accepts precondition_token from a preview (Spec 091): when supplied,\nthe core rechecks the raw pre-write state and the entry it would write, and\nrefuses a drifted write with 409 before taking any backup. The 409 body's\naction discriminates the two conflict kinds: \"precondition_failed\" (stale\npreview — re-preview, do not retry) vs \"already_exists\" (entry present — pass\nforce=true). force=true never rescues a stale token.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional connection parameters (server_name, force, precondition_token)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectConflictResponse"}}},"description":"Conflict: action=already_exists (use force=true) or action=precondition_failed (preview is stale; re-preview)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Connect MCPProxy to a client","tags":["connect"]}},"/api/v1/connect/{client}/preview":{"get":{"description":"Returns the exact entry a subsequent connect would add to the client's\nconfig — target path, server key, entry name, and entry contents — WITHOUT\nmodifying the file or creating a backup (Spec 078 US1). The embedded API key\nis masked in the payload; contains_api_key flags that a credential is written.\nentry_exists distinguishes a create from an overwrite of a same-named entry.\nReads the config on demand to classify create-vs-overwrite, so on macOS this\nmay raise an App-Data privacy prompt; a denial returns 403 + remediation.\nSpec 091 adds three fields: existing_entry_summary (present only when\nentry_exists — a sanitized, non-secret projection of the entry being replaced:\nits name, type, endpoint with query/userinfo stripped, command, and header and\nenv NAMES, never values); precondition_token (always present — an opaque keyed\ndigest of the raw pre-write state and the pending entry, echoed back on POST\nconnect to detect drift); and connect_refusal (present when the write would\nrefuse regardless of intent, e.g. a non-create-capable client with no config —\ntreat its presence as \"Connect unavailable\").","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}},{"description":"Entry name to preview (defaults to mcpproxy); mirror the value passed to POST connect","in":"query","name":"server_name","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectPreview"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Preview the change a connect would make (no write)","tags":["connect"]}},"/api/v1/connect/{client}/undo":{"post":{"description":"Reverts the connect that produced the named backup (Spec 078 US3):\nrestores the client config byte-for-byte from that backup, or — when\nbackup_name is empty because the connect created the file — deletes the\ncreated file. backup_name is the bare filename of the backup the connect\nreturned (never a path); undo resolves the full path server-side inside\nthe client's own config directory, so a client value cannot escape it.\nRefuses with 409 when the config changed since the connect (undo never\nclobbers later edits; use DELETE /connect/{client} for a surgical entry\nremoval instead). Takes its own safety backup first; its path is returned\nas backup_path in the result.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.UndoConnectRequest"}}},"description":"Undo parameters (server_name, backup_name = the bare filename of the backup the preceding connect returned)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult (action restored|deleted)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (e.g. backup_name is a path, or not a backup of this client's config)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or backup no longer exists"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Config changed since connect; undo refused"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Undo a connect, restoring the pre-connect config","tags":["connect"]}},"/api/v1/diagnostics":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/docker/status":{"get":{"description":"Retrieve current Docker availability and recovery status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Docker status information"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get Docker status","tags":["docker"]}},"/api/v1/doctor":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/feedback":{"post":{"description":"Submit a bug report, feature request, or general feedback","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackRequest"}}},"description":"Feedback request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Bad Request"},"429":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"Submit feedback","tags":["feedback"]}},"/api/v1/index/search":{"get":{"description":"Search across all upstream MCP server tools using BM25 keyword search","parameters":[{"description":"Search query","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"description":"Maximum number of results","in":"query","name":"limit","schema":{"default":10,"maximum":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchToolsResponse"}}},"description":"Search results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing query parameter)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search for tools","tags":["tools"]}},"/api/v1/info":{"get":{"description":"Get essential server metadata including version, web UI URL, endpoint addresses, and update availability\nweb_ui_url carries the ?apikey= credential ONLY for an authenticated admin; a scoped agent token receives the bare URL\nThis endpoint is designed for tray-core communication and version checking\nUse refresh=true query parameter to force an immediate update check against GitHub\nThe launched_by field reports durable launch provenance (\"tray\", \"installer\", or \"\" for user-launched/unknown)","parameters":[{"description":"Force immediate update check against GitHub","in":"query","name":"refresh","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"Server information with optional update info"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server information","tags":["status"]}},"/api/v1/onboarding/mark":{"post":{"description":"Updates wizard engagement and per-step status. Once engaged is\ntrue, the wizard does not auto-show again, even if state regresses.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.OnboardingMarkRequest"}}},"description":"Mark request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Updated OnboardingStateResponse"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read onboarding state"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Mark onboarding wizard state (Spec 046)","tags":["onboarding"]}},"/api/v1/onboarding/state":{"get":{"description":"Returns the wizard engagement record alongside live predicates\n(whether any client is connected, whether any server is configured),\nplus a derived ShouldShowWizard flag the frontend can rely on.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"OnboardingStateResponse"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read onboarding state"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get onboarding wizard state and predicates (Spec 046)","tags":["onboarding"]}},"/api/v1/preflight":{"post":{"description":"Deterministic, side-effect-free availability check for a caller-supplied list of tool IDs (Spec 098). Performs zero upstream calls and mutates no runtime state. HTTP status reports whether the CHECK executed: a fully blocked set is still 200, with the availability verdict in the body. Every executed preflight writes an activity record before the response is returned.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.PreflightRequest"}}},"description":"Tool IDs (1-100 before dedup), optional profile, annotation policy filters and wait budget","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"Preflight verdict and per-tool results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Validation error (malformed, oversized, doubled or unknown-field body; empty or oversized tool list; conflicting duplicate pins; unknown profile; wait_ms out of range)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Missing or invalid credentials"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Runtime unavailable, evaluator infrastructure read failure, or the activity record could not be persisted"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Preflight required tools","tags":["tools"]}},"/api/v1/profiles":{"get":{"description":"List all configured profiles with their effective servers and indexed tool count (Profiles v2). A profile scopes tool discovery and calls to a named subset of upstream servers.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Profile list"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Configuration unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List configured profiles","tags":["profiles"]}},"/api/v1/profiles/active":{"get":{"description":"Get the server-level default active profile used by UI surfaces (Web UI / tray). Empty string means \"all servers\". Note: within a live MCP session, the set_profile tool selection takes precedence over this default.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get the default active profile","tags":["profiles"]},"put":{"description":"Set the server-level default active profile for UI surfaces. The slug must match a configured profile; pass an empty string to clear. This does not affect live MCP sessions, which use the set_profile tool.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.SetActiveProfileRequest"}}},"description":"Profile slug to activate (empty clears)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid request body"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot change the active profile)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Set the default active profile","tags":["profiles"]}},"/api/v1/registries":{"get":{"description":"Retrieves list of all MCP server registries that can be browsed for discovering and installing new upstream servers. Includes registry metadata, server counts, and API endpoints.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetRegistriesResponse"}}},"description":"Registries retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to list registries"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List available MCP server registries","tags":["registries"]},"post":{"description":"Adds a generic modelcontextprotocol/registry v0.1 https endpoint as a custom registry (MCP-866). The source is always tagged custom/unverified, so every server discovered through it lands quarantined and can never skip quarantine.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddRegistrySourceRequest"}}},"description":"Registry source (https url + optional protocol/id/name)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source added"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/contracts.ErrorResponse"},{"$ref":"#/components/schemas/contracts.ErrorResponse"}]}}},"description":"Forbidden (agent tokens cannot mutate registries)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin | duplicate_registry"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a user-supplied registry source","tags":["registries"]}},"/api/v1/registries/{id}":{"delete":{"description":"Removes a custom/unverified registry previously added via add-source (MCP-1057). Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source removed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove a user-added custom registry source","tags":["registries"]},"put":{"description":"Updates a custom registry previously added via add-source (MCP-1072): name, url, servers-url. Empty fields are left unchanged. Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found; a non-https url yields invalid_registry_url. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.EditRegistrySourceRequest"}}},"description":"Fields to update (name/url/servers_url; empty = unchanged)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required | invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Edit a user-added custom registry source","tags":["registries"]}},"/api/v1/registries/{id}/refresh":{"post":{"description":"Invalidates the cached server lists for a registry so the next search re-fetches fresh data from the source (spec 070 FR-007). Returns how many cache entries were dropped.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.RefreshRegistryResponse"}}},"description":"Registry cache refreshed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh registry cache"}},"summary":"Refresh a registry's cached server list","tags":["registries"]}},"/api/v1/registries/{id}/servers":{"get":{"description":"Searches for MCP servers within a specific registry by keyword or tag. Returns server metadata including installation commands, source code URLs, and npm package information for easy discovery and installation.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Search query keyword","in":"query","name":"q","schema":{"type":"string"}},{"description":"Filter by tag","in":"query","name":"tag","schema":{"type":"string"}},{"description":"Maximum number of results (default 10)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchRegistryServersResponse"}}},"description":"Servers retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to search servers"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search MCP servers in a registry","tags":["registries"]}},"/api/v1/registries/{id}/servers/{serverId}/add":{"post":{"description":"Resolves a registry server reference server-side, re-derives a validated config, and persists it quarantined (spec 070 keystone). The client never sends a config blob — command/args/url and the quarantine flag are derived from the registry entry, not the request.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Server ID within the registry","in":"path","name":"serverId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddFromRegistryRequest"}}},"description":"Optional overrides (name, env, enabled)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server added (quarantined)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"no_install_info | missing_required_input | duplicate_name"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot add servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found | server_not_found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add an upstream server from a registry reference","tags":["registries"]}},"/api/v1/routing":{"get":{"description":"Get the current routing mode and available MCP endpoints.\nrouting_mode is what /mcp is actually serving; pending_routing_mode carries a\nrestart-pending value persisted on disk (empty when there is none).\ntool_response_mode and direct_tool_response_mode report the two serialization axes, resolved.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Routing mode information"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get routing mode information","tags":["status"]}},"/api/v1/secrets":{"post":{"description":"Stores a secret value in the operating system's secure keyring. The secret can then be referenced in configuration using ${keyring:secret-name} syntax. Automatically notifies runtime to restart affected servers.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret stored successfully with reference syntax"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload, missing name/value, or unsupported type"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver not available or failed to store secret"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Store a secret in OS keyring","tags":["secrets"]}},"/api/v1/secrets/{name}":{"delete":{"description":"Deletes a secret from the operating system's secure keyring. Automatically notifies runtime to restart affected servers. Only keyring type is supported for security.","parameters":[{"description":"Name of the secret to delete","in":"path","name":"name","required":true,"schema":{"type":"string"}},{"description":"Secret type (only 'keyring' supported, defaults to 'keyring')","in":"query","name":"type","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Missing secret name or unsupported type"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver not available or failed to delete secret"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Delete a secret from OS keyring","tags":["secrets"]}},"/api/v1/servers":{"get":{"description":"Get a list of all configured upstream MCP servers with their connection status and statistics","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServersResponse"}}},"description":"Server list with statistics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List all upstream MCP servers","tags":["servers"]},"post":{"description":"Add a new MCP upstream server to the configuration. New servers are quarantined by default for security. Isolation: ` + "`" + `isolation.enabled` + "`" + ` is READ-ONLY (it reports the effective state on reads) and is rejected with 400; set the per-server override via ` + "`" + `isolation.enabled_override` + "`" + ` (true | false | null to clear, omit to leave unchanged). An unrecognized ` + "`" + `isolation.mode_override` + "`" + ` is rejected with 400.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.AddServerRequest"}}},"description":"Server configuration","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server added successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid configuration"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Conflict - server with this name already exists"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a new upstream server","tags":["servers"]}},"/api/v1/servers/disable_all":{"post":{"description":"Disable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk disable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable all servers","tags":["servers"]}},"/api/v1/servers/enable_all":{"post":{"description":"Enable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk enable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable all servers","tags":["servers"]}},"/api/v1/servers/import":{"post":{"description":"Import MCP server configurations from a Claude Desktop, Claude Code, Cursor IDE, Codex CLI, or Gemini CLI configuration file","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}},{"description":"Force format (claude-desktop, claude-code, cursor, codex, gemini)","in":"query","name":"format","schema":{"type":"string"}},{"description":"Comma-separated list of server names to import","in":"query","name":"server_names","schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"file"}}},"description":"Configuration file to import","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid file or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from uploaded configuration file","tags":["servers"]}},"/api/v1/servers/import/json":{"post":{"description":"Import MCP server configurations from raw JSON or TOML content (useful for pasting configurations)","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportRequest"}}},"description":"Import request with content","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid content or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from JSON/TOML content","tags":["servers"]}},"/api/v1/servers/import/path":{"post":{"description":"Import MCP server configurations by reading a file from the server's filesystem","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportFromPathRequest"}}},"description":"Import request with file path","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid path or format"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"File not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from a file path","tags":["servers"]}},"/api/v1/servers/import/paths":{"get":{"description":"Returns well-known configuration file paths for supported formats with existence check","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPathsResponse"}}},"description":"Canonical config paths"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get canonical config file paths","tags":["servers"]}},"/api/v1/servers/reconnect":{"post":{"description":"Force reconnection to all upstream MCP servers","parameters":[{"description":"Reason for reconnection","in":"query","name":"reason","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"All servers reconnected successfully"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Reconnect all servers","tags":["servers"]}},"/api/v1/servers/restart_all":{"post":{"description":"Restart all configured upstream MCP servers sequentially with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk restart results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart all servers","tags":["servers"]}},"/api/v1/servers/{id}":{"delete":{"description":"Remove an MCP upstream server from the configuration. This stops the server if running and removes it from config.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server removed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove an upstream server","tags":["servers"]},"patch":{"description":"Update specific fields of an existing upstream MCP server configuration. Isolation: ` + "`" + `isolation.enabled` + "`" + ` is READ-ONLY (it reports the effective state on reads) and is rejected with 400; set the per-server override via ` + "`" + `isolation.enabled_override` + "`" + ` (true | false | null to clear, omit to leave unchanged). An unrecognized ` + "`" + `isolation.mode_override` + "`" + ` is rejected with 400.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.AddServerRequest"}}},"description":"Fields to update (all optional)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server updated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - no fields or invalid body"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/config-to-secret":{"post":{"description":"Atomically reads the real value from the server config, stores it in the OS keyring, and rewrites the config field to ` + "`" + `${keyring:\u003cname\u003e}` + "`" + `. Unblocks the UI's Convert-to-secret affordance for values the API redacts on the read path.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret stored, config updated with reference"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad scope/key/secret_name, or value is already a reference / empty"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server or key not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver or config update failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Convert a header / env value to a keyring secret","tags":["servers"]}},"/api/v1/servers/{id}/disable":{"post":{"description":"Disable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server disabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/discover-tools":{"post":{"description":"Manually trigger tool discovery and indexing for a specific upstream MCP server. This forces an immediate refresh of the server's tool cache.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool discovery triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot discover tools)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to discover tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Discover tools for a specific server","tags":["servers"]}},"/api/v1/servers/{id}/enable":{"post":{"description":"Enable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server enabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/login":{"post":{"description":"Initiate OAuth authentication flow for a specific upstream MCP server. Returns structured OAuth start response with correlation ID for tracking.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthStartResponse"}}},"description":"OAuth login initiated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthFlowError"}}},"description":"OAuth error (client_id required, DCR failed, etc.)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Trigger OAuth login for server","tags":["servers"]}},"/api/v1/servers/{id}/logout":{"post":{"description":"Clear OAuth authentication token and disconnect a specific upstream MCP server. The server will need to re-authenticate before tools can be used again.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"OAuth logout completed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled or read-only mode)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Clear OAuth token and disconnect server","tags":["servers"]}},"/api/v1/servers/{id}/logs":{"get":{"description":"Retrieve log entries for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Number of log lines to retrieve","in":"query","name":"tail","schema":{"default":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerLogsResponse"}}},"description":"Server logs retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server logs","tags":["servers"]}},"/api/v1/servers/{id}/quarantine":{"post":{"description":"Place a specific upstream MCP server in quarantine to prevent tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server quarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Quarantine a server","tags":["servers"]}},"/api/v1/servers/{id}/refresh":{"post":{"description":"Re-discover and re-index a specific upstream MCP server's tools without changing any security state. Alias of discover-tools, named for the upstream_servers 'refresh' operation; use it to make just-approved tools searchable immediately.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool refresh triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot refresh)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Refresh a server's tools","tags":["servers"]}},"/api/v1/servers/{id}/restart":{"post":{"description":"Restart the connection to a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server restarted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/tool-calls":{"get":{"description":"Retrieves tool call history filtered by upstream server ID. Returns recent tool executions for the specified server including timestamps, arguments, results, and errors. Useful for server-specific debugging and monitoring.","parameters":[{"description":"Upstream server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Maximum number of records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolCallsResponse"}}},"description":"Server tool calls retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get server tool calls"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call history for specific server","tags":["tool-calls"]}},"/api/v1/servers/{id}/tools":{"get":{"description":"Retrieve all available tools for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolsResponse"}}},"description":"Server tools retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/block":{"post":{"description":"Atomically approves AND disables the given tools (or all pending/changed tools when block_all=true) for a server. The approve and disable land in a single write per tool, so a tool is never left in the approved+enabled state. The \"blocked\" field counts tools actually blocked.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Block result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Block (approve+disable) tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/disable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/enable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/unquarantine":{"post":{"description":"Remove a specific upstream MCP server from quarantine to allow tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server unquarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Unquarantine a server","tags":["servers"]}},"/api/v1/sessions":{"get":{"description":"Retrieves paginated list of active and recent MCP client sessions. Each session represents a connection from an MCP client to MCPProxy, tracking initialization time, tool calls, and connection status.","parameters":[{"description":"Maximum number of sessions to return (1-100, default 10)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Number of sessions to skip for pagination (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Filter by session status","in":"query","name":"status","schema":{"enum":["active","closed"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionsResponse"}}},"description":"Sessions retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid status filter"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read MCP session history"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get sessions"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get active MCP sessions","tags":["sessions"]}},"/api/v1/sessions/{id}":{"get":{"description":"Retrieves detailed information about a specific MCP client session including initialization parameters, connection status, tool call count, and activity timestamps.","parameters":[{"description":"Session ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionDetailResponse"}}},"description":"Session details retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Session ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read MCP session history"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Session not found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get MCP session details by ID","tags":["sessions"]}},"/api/v1/stats/tokens":{"get":{"description":"Retrieve token savings statistics across all servers and sessions","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Token statistics"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read deployment-wide token statistics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get token savings statistics","tags":["stats"]}},"/api/v1/status":{"get":{"description":"Get comprehensive server status including running state, listen address, upstream statistics, and timestamp","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server status information"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server status","tags":["status"]}},"/api/v1/telemetry/payload":{"get":{"description":"Render the exact JSON heartbeat payload that mcpproxy would next send to the telemetry endpoint, without making a network call. Counters in the payload reflect the current in-memory state. Spec 042.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Telemetry heartbeat payload"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read the deployment telemetry payload"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Telemetry service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Preview next telemetry heartbeat payload","tags":["telemetry"]}},"/api/v1/telemetry/update-failure":{"post":{"description":"Records one terminal update-session failure, identified only by its\nstage (appcast, download, install, other). The body carries no error\ntext, URL, or version — the stage is the only value transmitted.\nReturns 204 both when the occurrence was durably persisted and when\ntelemetry is inactive at event time (config opt-out, environment\nopt-out, CI, or dev build), in which case nothing is recorded.\nCallers cannot and need not distinguish the two.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.UpdateFailureRequest"}}},"description":"Update failure stage","required":true},"responses":{"204":{"description":"Accepted (recorded, or a deliberate no-op while telemetry is inactive)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Malformed body, unknown field, trailing value, or stage outside the closed set"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Persistence failure"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Record a desktop auto-update failure occurrence (Spec 095)","tags":["telemetry"]}},"/api/v1/tool-calls":{"get":{"description":"Retrieves paginated tool call history across all upstream servers or filtered by session ID. Includes execution timestamps, arguments, results, and error information for debugging and auditing.","parameters":[{"description":"Maximum number of records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Number of records to skip for pagination (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Filter tool calls by MCP session ID","in":"query","name":"session_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetToolCallsResponse"}}},"description":"Tool calls retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get tool calls"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call history","tags":["tool-calls"]}},"/api/v1/tool-calls/{id}":{"get":{"description":"Retrieves detailed information about a specific tool call execution including full request arguments, response data, execution time, and any errors encountered.","parameters":[{"description":"Tool call ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetToolCallDetailResponse"}}},"description":"Tool call details retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call not found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call details by ID","tags":["tool-calls"]}},"/api/v1/tool-calls/{id}/replay":{"post":{"description":"Re-executes a previous tool call with optional modified arguments. Useful for debugging and testing tool behavior with different inputs. Creates a new tool call record linked to the original.","parameters":[{"description":"Original tool call ID to replay","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ReplayToolCallRequest"}}},"description":"Optional modified arguments for replay"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ReplayToolCallResponse"}}},"description":"Tool call replayed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call ID required or invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Shed by a concurrency limit (Retry-After header carries the wait hint)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to replay tool call"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Replay a tool call","tags":["tool-calls"]}},"/api/v1/tools":{"get":{"description":"Consolidated, read-only listing of all tools from every configured server (including disabled servers and disabled/config-denied tools), enriched with approval state and 30-day usage. Backs the global Tools page and the CLI global ` + "`" + `tools list` + "`" + ` (spec 050, issue #437).","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GlobalToolsResponse"}}},"description":"All tools across all servers"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Could not enumerate servers"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List every tool across all servers","tags":["tools"]}},"/api/v1/tools/call":{"post":{"description":"Execute a tool on an upstream MCP server (wrapper around MCP tool calls)","requestBody":{"content":{"application/json":{"schema":{"properties":{"arguments":{"type":"object"},"tool_name":{"type":"string"}},"type":"object"}}},"description":"Tool call request with tool name and arguments","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Tool call result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (invalid payload or missing tool name)"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Shed by a concurrency limit (Retry-After header carries the wait hint)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error or tool execution failure"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Call a tool","tags":["tools"]}},"/healthz":{"get":{"description":"Get comprehensive health status including all component health (Kubernetes-compatible liveness probe)","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.HealthResponse"}}},"description":"Service is healthy"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.HealthResponse"}}},"description":"Service is unhealthy"}},"summary":"Get health status","tags":["health"]}},"/readyz":{"get":{"description":"Get readiness status including all component readiness checks (Kubernetes-compatible readiness probe)","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.ReadinessResponse"}}},"description":"Service is ready"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.ReadinessResponse"}}},"description":"Service is not ready"}},"summary":"Get readiness status","tags":["health"]}}},
+    "paths": {"/api/v1/activity":{"get":{"description":"Returns paginated list of activity records with optional filtering","parameters":[{"description":"Filter by activity type(s), comma-separated for multiple (Spec 024)","in":"query","name":"type","schema":{"enum":["tool_call","policy_decision","quarantine_change","server_change","system_start","system_stop","internal_tool_call","config_change","preflight","prompt_get"],"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"enum":["success","error","blocked","rejected"],"type":"string"}},{"description":"Filter by intent operation type (Spec 018)","in":"query","name":"intent_type","schema":{"enum":["read","write","destructive"],"type":"string"}},{"description":"Filter by HTTP request ID for log correlation (Spec 021)","in":"query","name":"request_id","schema":{"type":"string"}},{"description":"Filter by parent call id — returns the sub-calls one code_execution issued","in":"query","name":"parent_id","schema":{"type":"string"}},{"description":"Include successful call_tool_* internal tool calls (default: false, excluded to avoid duplicates)","in":"query","name":"include_call_tool","schema":{"type":"boolean"}},{"description":"Filter by sensitive data detection (true=has detections, false=no detections)","in":"query","name":"sensitive_data","schema":{"type":"boolean"}},{"description":"Filter by specific detection type (e.g., 'aws_access_key', 'credit_card')","in":"query","name":"detection_type","schema":{"type":"string"}},{"description":"Filter by severity level","in":"query","name":"severity","schema":{"enum":["critical","high","medium","low"],"type":"string"}},{"description":"Filter by agent token name (Spec 028)","in":"query","name":"agent","schema":{"type":"string"}},{"description":"Filter by auth type (Spec 028)","in":"query","name":"auth_type","schema":{"enum":["admin","agent"],"type":"string"}},{"description":"Filter activities after this time (RFC3339)","in":"query","name":"start_time","schema":{"type":"string"}},{"description":"Filter activities before this time (RFC3339)","in":"query","name":"end_time","schema":{"type":"string"}},{"description":"Maximum records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Pagination offset (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Omit arguments, response and metadata except a contextual whitelist (intent.reason, intent.operation_type, decision, reason, client_name, client_version) (default: false). For clients that render summary fields only; has_sensitive_data is still derived before metadata is dropped.","in":"query","name":"exclude_payloads","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"List activity records","tags":["Activity"]}},"/api/v1/activity/export":{"get":{"description":"Exports activity records in JSON Lines or CSV format for compliance","parameters":[{"description":"Export format: json (default) or csv","in":"query","name":"format","schema":{"type":"string"}},{"description":"Filter by activity type","in":"query","name":"type","schema":{"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"type":"string"}},{"description":"Filter by HTTP request ID for log correlation (Spec 021)","in":"query","name":"request_id","schema":{"type":"string"}},{"description":"Filter by parent call id — exports the sub-calls one code_execution issued","in":"query","name":"parent_id","schema":{"type":"string"}},{"description":"Filter activities after this time (RFC3339)","in":"query","name":"start_time","schema":{"type":"string"}},{"description":"Filter activities before this time (RFC3339)","in":"query","name":"end_time","schema":{"type":"string"}},{"description":"Maximum records to export (1-50000, default 10000)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Pagination offset (default 0)","in":"query","name":"offset","schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}}},"description":"Streamed activity records"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Export activity records","tags":["Activity"]}},"/api/v1/activity/summary":{"get":{"description":"Returns aggregated activity statistics for a time period","parameters":[{"description":"Time period: 1h, 24h (default), 7d, 30d","in":"query","name":"period","schema":{"type":"string"}},{"description":"Group by: server, tool (optional)","in":"query","name":"group_by","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity summary statistics","tags":["Activity"]}},"/api/v1/activity/usage":{"get":{"description":"Returns the actor-owned usage aggregate (per-tool rollup + timeline + tokens-saved headline) for the Web UI usage graphs (Spec 069). Served from an in-memory snapshot — never a per-request full-log scan. Per-tool metrics are lifetime-cumulative; ` + "`" + `window` + "`" + ` scopes the timeline and filters the tool list to tools active within the span.","parameters":[{"description":"Time window for timeline + tool-list membership","in":"query","name":"window","schema":{"enum":["24h","7d","all"],"type":"string"}},{"description":"Filter to one server","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter to one tool","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter to tools with activity of this status","in":"query","name":"status","schema":{"enum":["success","error","blocked","rejected"],"type":"string"}},{"description":"Top-N tools by sort key; remainder folded into 'other' (default 20)","in":"query","name":"top","schema":{"type":"integer"}},{"description":"Ranking key for the per-tool list","in":"query","name":"sort","schema":{"enum":["calls","resp_bytes","error_rate","p95"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get usage statistics aggregate","tags":["Activity"]}},"/api/v1/activity/{id}":{"get":{"description":"Returns full details for a single activity record","parameters":[{"description":"Activity record ID (ULID)","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Not Found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity record details","tags":["Activity"]}},"/api/v1/annotations/coverage":{"get":{"description":"Reports how many upstream tools have MCP annotations vs don't, broken down by server","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Annotation coverage report"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get annotation coverage report","tags":["annotations"]}},"/api/v1/catalog/search":{"get":{"description":"Fans out to every enabled catalog source (registry) in parallel, merges, de-duplicates and ranks the results (FR-060/061). An empty q returns official + popular sections instead of a flat list. Open to any authenticated caller — added is the only field filtered per caller scope (FR-007).","parameters":[{"description":"Free-text search","in":"query","name":"q","schema":{"type":"string"}},{"description":"Narrow to one catalog source id","in":"query","name":"source","schema":{"type":"string"}},{"description":"Filter by tag","in":"query","name":"tag","schema":{"type":"string"}},{"description":"Max results (default 20, max 50)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"OK"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search the server catalog across every enabled source","tags":["catalog"]}},"/api/v1/code/scripts":{"get":{"description":"List the stored scripts available to the code_execution tool. Scripts are ` + "`" + `\u003cname\u003e.js` + "`" + ` / ` + "`" + `\u003cname\u003e.ts` + "`" + ` files in the ` + "`" + `scripts/` + "`" + ` directory next to the active configuration file. Entries are advisory: ` + "`" + `ok` + "`" + ` scripts are invocable, ` + "`" + `ambiguous` + "`" + ` names have both extensions, and ` + "`" + `invalid` + "`" + ` ones report why (empty, oversized, unreadable, non-regular). Read-only — there is no write surface for stored scripts. Administrator-only (Spec 105 FR-012): an agent token, whatever its server scope, is refused with 403 — the listing is the enumeration the missing-script error withholds from a scoped caller.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Stored scripts and the directory they were read from"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot list stored scripts"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List stored code-execution scripts","tags":["code"]}},"/api/v1/config":{"get":{"description":"Retrieves the current MCPProxy configuration including all server definitions, global settings, and runtime parameters","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetConfigResponse"}}},"description":"Configuration retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read the configuration document"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get current configuration","tags":["config"]},"patch":{"description":"Deep-merges only the fields present in the request body onto the live in-memory configuration and routes the result through the existing apply pipeline (validation, change detection, disk persistence, hot-reload). Fields the client omits — including masked secrets such as ` + "`" + `api_key` + "`" + ` and secret request headers — are preserved verbatim. Nested objects are merged recursively; arrays and scalars replace wholesale.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Partial configuration with only the fields to change","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Configuration patch applied (inspect validation_errors for rejected values)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload or empty patch"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to read or apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update configuration","tags":["config"]}},"/api/v1/config/apply":{"post":{"description":"Applies a new MCPProxy configuration. Validates and persists the configuration to disk. Some changes apply immediately, while others may require a restart. Returns detailed information about applied changes and restart requirements.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to apply","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Configuration applied successfully with change details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Apply configuration","tags":["config"]}},"/api/v1/config/docker-isolation":{"patch":{"description":"Convenience endpoint to flip ` + "`" + `docker_isolation.enabled` + "`" + ` without resending the full config. Persists to disk via the existing config writer — the file watcher then hot-reloads the change. Returns the new state and whether a restart is required for existing connections to pick it up.","requestBody":{"content":{"application/json":{"schema":{"properties":{"enabled":{"type":"boolean"}},"type":"object"}}},"description":"New isolation state","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Isolation toggle applied"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Toggle global Docker isolation","tags":["config"]}},"/api/v1/config/validate":{"post":{"description":"Validates a provided MCPProxy configuration without applying it. Checks for syntax errors, invalid server definitions, conflicting settings, and other configuration issues.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to validate","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ValidateConfigResponse"}}},"description":"Configuration validation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Validation failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Validate configuration","tags":["config"]}},"/api/v1/connect":{"get":{"description":"Returns the connection status for all known MCP client applications.\nEach entry indicates whether the client config file exists and whether\nMCPProxy is currently registered in it.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"List of ClientStatus objects"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List client connection status","tags":["connect"]}},"/api/v1/connect/{client}":{"delete":{"description":"Remove the MCPProxy entry from the specified client's configuration file.\nCreates a backup of the existing config before modifying.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional parameters (server_name)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or entry not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disconnect MCPProxy from a client","tags":["connect"]},"get":{"description":"Resolves one client's status by reading its config file on demand.\nThis is the only Connect endpoint that opens a client config file, so\non macOS it is the sole place an App-Data privacy prompt may legitimately\nappear (scoped to this user action). Resolves access_state to\naccessible|absent|denied|malformed and populates remediation when denied.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ClientStatus"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get a single client's connection status (on-demand)","tags":["connect"]},"post":{"description":"Register MCPProxy as an MCP server in the specified client's configuration file.\nCreates a backup of the existing config before modifying.\nOptionally accepts precondition_token from a preview (Spec 091): when supplied,\nthe core rechecks the raw pre-write state and the entry it would write, and\nrefuses a drifted write with 409 before taking any backup. The 409 body's\naction discriminates the two conflict kinds: \"precondition_failed\" (stale\npreview — re-preview, do not retry) vs \"already_exists\" (entry present — pass\nforce=true). force=true never rescues a stale token.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional connection parameters (server_name, force, precondition_token)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectConflictResponse"}}},"description":"Conflict: action=already_exists (use force=true) or action=precondition_failed (preview is stale; re-preview)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Connect MCPProxy to a client","tags":["connect"]}},"/api/v1/connect/{client}/preview":{"get":{"description":"Returns the exact entry a subsequent connect would add to the client's\nconfig — target path, server key, entry name, and entry contents — WITHOUT\nmodifying the file or creating a backup (Spec 078 US1). The embedded API key\nis masked in the payload; contains_api_key flags that a credential is written.\nentry_exists distinguishes a create from an overwrite of a same-named entry.\nReads the config on demand to classify create-vs-overwrite, so on macOS this\nmay raise an App-Data privacy prompt; a denial returns 403 + remediation.\nSpec 091 adds three fields: existing_entry_summary (present only when\nentry_exists — a sanitized, non-secret projection of the entry being replaced:\nits name, type, endpoint with query/userinfo stripped, command, and header and\nenv NAMES, never values); precondition_token (always present — an opaque keyed\ndigest of the raw pre-write state and the pending entry, echoed back on POST\nconnect to detect drift); and connect_refusal (present when the write would\nrefuse regardless of intent, e.g. a non-create-capable client with no config —\ntreat its presence as \"Connect unavailable\").","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}},{"description":"Entry name to preview (defaults to mcpproxy); mirror the value passed to POST connect","in":"query","name":"server_name","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectPreview"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Preview the change a connect would make (no write)","tags":["connect"]}},"/api/v1/connect/{client}/undo":{"post":{"description":"Reverts the connect that produced the named backup (Spec 078 US3):\nrestores the client config byte-for-byte from that backup, or — when\nbackup_name is empty because the connect created the file — deletes the\ncreated file. backup_name is the bare filename of the backup the connect\nreturned (never a path); undo resolves the full path server-side inside\nthe client's own config directory, so a client value cannot escape it.\nRefuses with 409 when the config changed since the connect (undo never\nclobbers later edits; use DELETE /connect/{client} for a surgical entry\nremoval instead). Takes its own safety backup first; its path is returned\nas backup_path in the result.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode, zcode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.UndoConnectRequest"}}},"description":"Undo parameters (server_name, backup_name = the bare filename of the backup the preceding connect returned)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult (action restored|deleted)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (e.g. backup_name is a path, or not a backup of this client's config)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or backup no longer exists"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Config changed since connect; undo refused"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Undo a connect, restoring the pre-connect config","tags":["connect"]}},"/api/v1/diagnostics":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/docker/status":{"get":{"description":"Retrieve current Docker availability and recovery status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Docker status information"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get Docker status","tags":["docker"]}},"/api/v1/doctor":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/feedback":{"post":{"description":"Submit a bug report, feature request, or general feedback","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackRequest"}}},"description":"Feedback request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Bad Request"},"429":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"Submit feedback","tags":["feedback"]}},"/api/v1/index/search":{"get":{"description":"Search across all upstream MCP server tools using BM25 keyword search","parameters":[{"description":"Search query","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"description":"Maximum number of results","in":"query","name":"limit","schema":{"default":10,"maximum":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchToolsResponse"}}},"description":"Search results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing query parameter)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search for tools","tags":["tools"]}},"/api/v1/info":{"get":{"description":"Get essential server metadata including version, web UI URL, endpoint addresses, and update availability\nweb_ui_url carries the ?apikey= credential ONLY for an authenticated admin; a scoped agent token receives the bare URL\nThis endpoint is designed for tray-core communication and version checking\nUse refresh=true query parameter to force an immediate update check against GitHub\nThe launched_by field reports durable launch provenance (\"tray\", \"installer\", or \"\" for user-launched/unknown)","parameters":[{"description":"Force immediate update check against GitHub","in":"query","name":"refresh","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"Server information with optional update info"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server information","tags":["status"]}},"/api/v1/onboarding/mark":{"post":{"description":"Updates wizard engagement and per-step status. Once engaged is\ntrue, the wizard does not auto-show again, even if state regresses.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.OnboardingMarkRequest"}}},"description":"Mark request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Updated OnboardingStateResponse"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read onboarding state"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Mark onboarding wizard state (Spec 046)","tags":["onboarding"]}},"/api/v1/onboarding/state":{"get":{"description":"Returns the wizard engagement record alongside live predicates\n(whether any client is connected, whether any server is configured),\nplus a derived ShouldShowWizard flag the frontend can rely on.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"OnboardingStateResponse"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read onboarding state"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get onboarding wizard state and predicates (Spec 046)","tags":["onboarding"]}},"/api/v1/preflight":{"post":{"description":"Deterministic, side-effect-free availability check for a caller-supplied list of tool IDs (Spec 098). Performs zero upstream calls and mutates no runtime state. HTTP status reports whether the CHECK executed: a fully blocked set is still 200, with the availability verdict in the body. Every executed preflight writes an activity record before the response is returned.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.PreflightRequest"}}},"description":"Tool IDs (1-100 before dedup), optional profile, annotation policy filters and wait budget","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"Preflight verdict and per-tool results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Validation error (malformed, oversized, doubled or unknown-field body; empty or oversized tool list; conflicting duplicate pins; unknown profile; wait_ms out of range)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Missing or invalid credentials"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Runtime unavailable, evaluator infrastructure read failure, or the activity record could not be persisted"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Preflight required tools","tags":["tools"]}},"/api/v1/profiles":{"get":{"description":"List all configured profiles with their effective servers and indexed tool count (Profiles v2). A profile scopes tool discovery and calls to a named subset of upstream servers.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Profile list"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Configuration unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List configured profiles","tags":["profiles"]}},"/api/v1/profiles/active":{"get":{"description":"Get the server-level default active profile used by UI surfaces (Web UI / tray). Empty string means \"all servers\". Note: within a live MCP session, the set_profile tool selection takes precedence over this default.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get the default active profile","tags":["profiles"]},"put":{"description":"Set the server-level default active profile for UI surfaces. The slug must match a configured profile; pass an empty string to clear. This does not affect live MCP sessions, which use the set_profile tool.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.SetActiveProfileRequest"}}},"description":"Profile slug to activate (empty clears)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid request body"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot change the active profile)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Set the default active profile","tags":["profiles"]}},"/api/v1/registries":{"get":{"description":"Retrieves list of all MCP server registries that can be browsed for discovering and installing new upstream servers. Includes registry metadata, server counts, and API endpoints.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetRegistriesResponse"}}},"description":"Registries retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to list registries"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List available MCP server registries","tags":["registries"]},"post":{"description":"Adds a generic modelcontextprotocol/registry v0.1 https endpoint as a custom registry (MCP-866). The source is always tagged custom/unverified, so every server discovered through it lands quarantined and can never skip quarantine.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddRegistrySourceRequest"}}},"description":"Registry source (https url + optional protocol/id/name)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source added"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/contracts.ErrorResponse"},{"$ref":"#/components/schemas/contracts.ErrorResponse"}]}}},"description":"Forbidden (agent tokens cannot mutate registries)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin | duplicate_registry"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a user-supplied registry source","tags":["registries"]}},"/api/v1/registries/{id}":{"delete":{"description":"Removes a custom/unverified registry previously added via add-source (MCP-1057). Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source removed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove a user-added custom registry source","tags":["registries"]},"put":{"description":"Updates a custom registry previously added via add-source (MCP-1072): name, url, servers-url. Empty fields are left unchanged. Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found; a non-https url yields invalid_registry_url. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.EditRegistrySourceRequest"}}},"description":"Fields to update (name/url/servers_url; empty = unchanged)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required | invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Edit a user-added custom registry source","tags":["registries"]}},"/api/v1/registries/{id}/refresh":{"post":{"description":"Invalidates the cached server lists for a registry so the next search re-fetches fresh data from the source (spec 070 FR-007). Returns how many cache entries were dropped.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.RefreshRegistryResponse"}}},"description":"Registry cache refreshed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh registry cache"}},"summary":"Refresh a registry's cached server list","tags":["registries"]}},"/api/v1/registries/{id}/servers":{"get":{"description":"Searches for MCP servers within a specific registry by keyword or tag. Returns server metadata including installation commands, source code URLs, and npm package information for easy discovery and installation.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Search query keyword","in":"query","name":"q","schema":{"type":"string"}},{"description":"Filter by tag","in":"query","name":"tag","schema":{"type":"string"}},{"description":"Maximum number of results (default 10)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchRegistryServersResponse"}}},"description":"Servers retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to search servers"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search MCP servers in a registry","tags":["registries"]}},"/api/v1/registries/{id}/servers/{serverId}/add":{"post":{"description":"Resolves a registry server reference server-side, re-derives a validated config, and persists it quarantined (spec 070 keystone). The client never sends a config blob — command/args/url and the quarantine flag are derived from the registry entry, not the request.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Server ID within the registry","in":"path","name":"serverId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddFromRegistryRequest"}}},"description":"Optional overrides (name, env, enabled)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server added (quarantined)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"no_install_info | missing_required_input | duplicate_name"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot add servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found | server_not_found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add an upstream server from a registry reference","tags":["registries"]}},"/api/v1/routing":{"get":{"description":"Get the current routing mode and available MCP endpoints.\nrouting_mode is what /mcp is actually serving; pending_routing_mode carries a\nrestart-pending value persisted on disk (empty when there is none).\ntool_response_mode and direct_tool_response_mode report the two serialization axes, resolved.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Routing mode information"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get routing mode information","tags":["status"]}},"/api/v1/secrets":{"post":{"description":"Stores a secret value in the operating system's secure keyring. The secret can then be referenced in configuration using ${keyring:secret-name} syntax. Automatically notifies runtime to restart affected servers.","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret stored successfully with reference syntax"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload, missing name/value, or unsupported type"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver not available or failed to store secret"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Store a secret in OS keyring","tags":["secrets"]}},"/api/v1/secrets/{name}":{"delete":{"description":"Deletes a secret from the operating system's secure keyring. Automatically notifies runtime to restart affected servers. Only keyring type is supported for security.","parameters":[{"description":"Name of the secret to delete","in":"path","name":"name","required":true,"schema":{"type":"string"}},{"description":"Secret type (only 'keyring' supported, defaults to 'keyring')","in":"query","name":"type","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Missing secret name or unsupported type"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver not available or failed to delete secret"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Delete a secret from OS keyring","tags":["secrets"]}},"/api/v1/servers":{"get":{"description":"Get a list of all configured upstream MCP servers with their connection status and statistics","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServersResponse"}}},"description":"Server list with statistics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List all upstream MCP servers","tags":["servers"]},"post":{"description":"Add a new MCP upstream server to the configuration. New servers are quarantined by default for security. Isolation: ` + "`" + `isolation.enabled` + "`" + ` is READ-ONLY (it reports the effective state on reads) and is rejected with 400; set the per-server override via ` + "`" + `isolation.enabled_override` + "`" + ` (true | false | null to clear, omit to leave unchanged). An unrecognized ` + "`" + `isolation.mode_override` + "`" + ` is rejected with 400.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.AddServerRequest"}}},"description":"Server configuration","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server added successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid configuration"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Conflict - server with this name already exists"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a new upstream server","tags":["servers"]}},"/api/v1/servers/disable_all":{"post":{"description":"Disable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk disable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable all servers","tags":["servers"]}},"/api/v1/servers/enable_all":{"post":{"description":"Enable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk enable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable all servers","tags":["servers"]}},"/api/v1/servers/import":{"post":{"description":"Import MCP server configurations from a Claude Desktop, Claude Code, Cursor IDE, Codex CLI, or Gemini CLI configuration file","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}},{"description":"Force format (claude-desktop, claude-code, cursor, codex, gemini)","in":"query","name":"format","schema":{"type":"string"}},{"description":"Comma-separated list of server names to import","in":"query","name":"server_names","schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"file"}}},"description":"Configuration file to import","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid file or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from uploaded configuration file","tags":["servers"]}},"/api/v1/servers/import/json":{"post":{"description":"Import MCP server configurations from raw JSON or TOML content (useful for pasting configurations)","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportRequest"}}},"description":"Import request with content","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid content or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from JSON/TOML content","tags":["servers"]}},"/api/v1/servers/import/path":{"post":{"description":"Import MCP server configurations by reading a file from the server's filesystem","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportFromPathRequest"}}},"description":"Import request with file path","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid path or format"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"File not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from a file path","tags":["servers"]}},"/api/v1/servers/import/paths":{"get":{"description":"Returns well-known configuration file paths for supported formats with existence check","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPathsResponse"}}},"description":"Canonical config paths"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get canonical config file paths","tags":["servers"]}},"/api/v1/servers/reconnect":{"post":{"description":"Force reconnection to all upstream MCP servers","parameters":[{"description":"Reason for reconnection","in":"query","name":"reason","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"All servers reconnected successfully"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Reconnect all servers","tags":["servers"]}},"/api/v1/servers/restart_all":{"post":{"description":"Restart all configured upstream MCP servers sequentially with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk restart results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart all servers","tags":["servers"]}},"/api/v1/servers/{id}":{"delete":{"description":"Remove an MCP upstream server from the configuration. This stops the server if running and removes it from config.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server removed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove an upstream server","tags":["servers"]},"patch":{"description":"Update specific fields of an existing upstream MCP server configuration. Isolation: ` + "`" + `isolation.enabled` + "`" + ` is READ-ONLY (it reports the effective state on reads) and is rejected with 400; set the per-server override via ` + "`" + `isolation.enabled_override` + "`" + ` (true | false | null to clear, omit to leave unchanged). An unrecognized ` + "`" + `isolation.mode_override` + "`" + ` is rejected with 400.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.AddServerRequest"}}},"description":"Fields to update (all optional)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server updated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - no fields or invalid body"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/config-to-secret":{"post":{"description":"Atomically reads the real value from the server config, stores it in the OS keyring, and rewrites the config field to ` + "`" + `${keyring:\u003cname\u003e}` + "`" + `. Unblocks the UI's Convert-to-secret affordance for values the API redacts on the read path.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret stored, config updated with reference"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad scope/key/secret_name, or value is already a reference / empty"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server or key not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver or config update failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Convert a header / env value to a keyring secret","tags":["servers"]}},"/api/v1/servers/{id}/disable":{"post":{"description":"Disable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server disabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/discover-tools":{"post":{"description":"Manually trigger tool discovery and indexing for a specific upstream MCP server. This forces an immediate refresh of the server's tool cache.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool discovery triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot discover tools)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to discover tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Discover tools for a specific server","tags":["servers"]}},"/api/v1/servers/{id}/enable":{"post":{"description":"Enable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server enabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/login":{"post":{"description":"Initiate OAuth authentication flow for a specific upstream MCP server. Returns structured OAuth start response with correlation ID for tracking.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthStartResponse"}}},"description":"OAuth login initiated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthFlowError"}}},"description":"OAuth error (client_id required, DCR failed, etc.)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Trigger OAuth login for server","tags":["servers"]}},"/api/v1/servers/{id}/logout":{"post":{"description":"Clear OAuth authentication token and disconnect a specific upstream MCP server. The server will need to re-authenticate before tools can be used again.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"OAuth logout completed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled or read-only mode)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Clear OAuth token and disconnect server","tags":["servers"]}},"/api/v1/servers/{id}/logs":{"get":{"description":"Retrieve log entries for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Number of log lines to retrieve","in":"query","name":"tail","schema":{"default":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerLogsResponse"}}},"description":"Server logs retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server logs","tags":["servers"]}},"/api/v1/servers/{id}/quarantine":{"post":{"description":"Place a specific upstream MCP server in quarantine to prevent tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server quarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Quarantine a server","tags":["servers"]}},"/api/v1/servers/{id}/refresh":{"post":{"description":"Re-discover and re-index a specific upstream MCP server's tools without changing any security state. Alias of discover-tools, named for the upstream_servers 'refresh' operation; use it to make just-approved tools searchable immediately.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool refresh triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot refresh)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Refresh a server's tools","tags":["servers"]}},"/api/v1/servers/{id}/restart":{"post":{"description":"Restart the connection to a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server restarted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/tool-calls":{"get":{"description":"Retrieves tool call history filtered by upstream server ID. Returns recent tool executions for the specified server including timestamps, arguments, results, and errors. Useful for server-specific debugging and monitoring.","parameters":[{"description":"Upstream server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Maximum number of records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolCallsResponse"}}},"description":"Server tool calls retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get server tool calls"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call history for specific server","tags":["tool-calls"]}},"/api/v1/servers/{id}/tools":{"get":{"description":"Retrieve all available tools for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolsResponse"}}},"description":"Server tools retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/block":{"post":{"description":"Atomically approves AND disables the given tools (or all pending/changed tools when block_all=true) for a server. The approve and disable land in a single write per tool, so a tool is never left in the approved+enabled state. The \"blocked\" field counts tools actually blocked.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Block result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Block (approve+disable) tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/disable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/enable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/unquarantine":{"post":{"description":"Remove a specific upstream MCP server from quarantine to allow tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server unquarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Unquarantine a server","tags":["servers"]}},"/api/v1/sessions":{"get":{"description":"Retrieves paginated list of active and recent MCP client sessions. Each session represents a connection from an MCP client to MCPProxy, tracking initialization time, tool calls, and connection status.","parameters":[{"description":"Maximum number of sessions to return (1-100, default 10)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Number of sessions to skip for pagination (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Filter by session status","in":"query","name":"status","schema":{"enum":["active","closed"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionsResponse"}}},"description":"Sessions retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid status filter"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read MCP session history"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get sessions"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get active MCP sessions","tags":["sessions"]}},"/api/v1/sessions/{id}":{"get":{"description":"Retrieves detailed information about a specific MCP client session including initialization parameters, connection status, tool call count, and activity timestamps.","parameters":[{"description":"Session ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionDetailResponse"}}},"description":"Session details retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Session ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read MCP session history"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Session not found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get MCP session details by ID","tags":["sessions"]}},"/api/v1/stats/tokens":{"get":{"description":"Retrieve token savings statistics across all servers and sessions","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Token statistics"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read deployment-wide token statistics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get token savings statistics","tags":["stats"]}},"/api/v1/status":{"get":{"description":"Get comprehensive server status including running state, listen address, upstream statistics, and timestamp","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server status information"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server status","tags":["status"]}},"/api/v1/telemetry/payload":{"get":{"description":"Render the exact JSON heartbeat payload that mcpproxy would next send to the telemetry endpoint, without making a network call. Counters in the payload reflect the current in-memory state. Spec 042.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Telemetry heartbeat payload"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Agent tokens cannot read the deployment telemetry payload"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Telemetry service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Preview next telemetry heartbeat payload","tags":["telemetry"]}},"/api/v1/telemetry/update-failure":{"post":{"description":"Records one terminal update-session failure, identified only by its\nstage (appcast, download, install, other). The body carries no error\ntext, URL, or version — the stage is the only value transmitted.\nReturns 204 both when the occurrence was durably persisted and when\ntelemetry is inactive at event time (config opt-out, environment\nopt-out, CI, or dev build), in which case nothing is recorded.\nCallers cannot and need not distinguish the two.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.UpdateFailureRequest"}}},"description":"Update failure stage","required":true},"responses":{"204":{"description":"Accepted (recorded, or a deliberate no-op while telemetry is inactive)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Malformed body, unknown field, trailing value, or stage outside the closed set"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Persistence failure"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Record a desktop auto-update failure occurrence (Spec 095)","tags":["telemetry"]}},"/api/v1/tool-calls":{"get":{"description":"Retrieves paginated tool call history across all upstream servers or filtered by session ID. Includes execution timestamps, arguments, results, and error information for debugging and auditing.","parameters":[{"description":"Maximum number of records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Number of records to skip for pagination (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Filter tool calls by MCP session ID","in":"query","name":"session_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetToolCallsResponse"}}},"description":"Tool calls retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get tool calls"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call history","tags":["tool-calls"]}},"/api/v1/tool-calls/{id}":{"get":{"description":"Retrieves detailed information about a specific tool call execution including full request arguments, response data, execution time, and any errors encountered.","parameters":[{"description":"Tool call ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetToolCallDetailResponse"}}},"description":"Tool call details retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call not found"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call details by ID","tags":["tool-calls"]}},"/api/v1/tool-calls/{id}/replay":{"post":{"description":"Re-executes a previous tool call with optional modified arguments. Useful for debugging and testing tool behavior with different inputs. Creates a new tool call record linked to the original.","parameters":[{"description":"Original tool call ID to replay","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ReplayToolCallRequest"}}},"description":"Optional modified arguments for replay"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ReplayToolCallResponse"}}},"description":"Tool call replayed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Tool call ID required or invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Shed by a concurrency limit (Retry-After header carries the wait hint)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to replay tool call"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Replay a tool call","tags":["tool-calls"]}},"/api/v1/tools":{"get":{"description":"Consolidated, read-only listing of all tools from every configured server (including disabled servers and disabled/config-denied tools), enriched with approval state and 30-day usage. Backs the global Tools page and the CLI global ` + "`" + `tools list` + "`" + ` (spec 050, issue #437).","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GlobalToolsResponse"}}},"description":"All tools across all servers"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Could not enumerate servers"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List every tool across all servers","tags":["tools"]}},"/api/v1/tools/call":{"post":{"description":"Execute a tool on an upstream MCP server (wrapper around MCP tool calls)","requestBody":{"content":{"application/json":{"schema":{"properties":{"arguments":{"type":"object"},"tool_name":{"type":"string"}},"type":"object"}}},"description":"Tool call request with tool name and arguments","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Tool call result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (invalid payload or missing tool name)"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Shed by a concurrency limit (Retry-After header carries the wait hint)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error or tool execution failure"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Call a tool","tags":["tools"]}},"/healthz":{"get":{"description":"Get comprehensive health status including all component health (Kubernetes-compatible liveness probe)","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.HealthResponse"}}},"description":"Service is healthy"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.HealthResponse"}}},"description":"Service is unhealthy"}},"summary":"Get health status","tags":["health"]}},"/readyz":{"get":{"description":"Get readiness status including all component readiness checks (Kubernetes-compatible readiness probe)","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.ReadinessResponse"}}},"description":"Service is ready"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/observability.ReadinessResponse"}}},"description":"Service is not ready"}},"summary":"Get readiness status","tags":["health"]}}},
     "openapi": "3.1.0"
 }`
 
diff --git a/oas/swagger.yaml b/oas/swagger.yaml
index fcd88522b..30cae143e 100644
--- a/oas/swagger.yaml
+++ b/oas/swagger.yaml
@@ -3357,6 +3357,26 @@ components:
           description: Defaults to "mcpproxy"
           type: string
       type: object
+    httpapi.EnvFieldPreview:
+      properties:
+        empty_or_placeholder:
+          type: boolean
+        name:
+          type: string
+        secret_like:
+          type: boolean
+        value_present:
+          type: boolean
+      type: object
+    httpapi.HeaderFieldPreview:
+      properties:
+        empty_or_placeholder:
+          type: boolean
+        name:
+          type: string
+        secret_like:
+          type: boolean
+      type: object
     httpapi.ImportFromPathRequest:
       properties:
         format:
@@ -3437,11 +3457,21 @@ components:
           uniqueItems: false
         command:
           type: string
+        env:
+          items:
+            $ref: '#/components/schemas/httpapi.EnvFieldPreview'
+          type: array
+          uniqueItems: false
         fields_skipped:
           items:
             type: string
           type: array
           uniqueItems: false
+        headers:
+          items:
+            $ref: '#/components/schemas/httpapi.HeaderFieldPreview'
+          type: array
+          uniqueItems: false
         name:
           type: string
         original_name:
@@ -3450,6 +3480,20 @@ components:
           type: string
         source_format:
           type: string
+        summary:
+          description: |-
+            Summary, Tags, Env and Headers are the Spec 109 FR-064 preview
+            enrichment (contracts/rest-api.md "Import preview"). Summary and Tags
+            are built from the already-redacted URL/Command/Args above, so a
+            secret embedded in argv or a URL query never reaches Summary either.
+            Env/Headers never carry the raw value — only its presence and two
+            booleans a surface uses to default the Value/Secret toggle (FR-065).
+          type: string
+        tags:
+          items:
+            type: string
+          type: array
+          uniqueItems: false
         url:
           type: string
         warnings:
@@ -4227,6 +4271,46 @@ paths:
       summary: Get annotation coverage report
       tags:
       - annotations
+  /api/v1/catalog/search:
+    get:
+      description: Fans out to every enabled catalog source (registry) in parallel,
+        merges, de-duplicates and ranks the results (FR-060/061). An empty q returns
+        official + popular sections instead of a flat list. Open to any authenticated
+        caller — added is the only field filtered per caller scope (FR-007).
+      parameters:
+      - description: Free-text search
+        in: query
+        name: q
+        schema:
+          type: string
+      - description: Narrow to one catalog source id
+        in: query
+        name: source
+        schema:
+          type: string
+      - description: Filter by tag
+        in: query
+        name: tag
+        schema:
+          type: string
+      - description: Max results (default 20, max 50)
+        in: query
+        name: limit
+        schema:
+          type: integer
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/contracts.SuccessResponse'
+          description: OK
+      security:
+      - ApiKeyAuth: []
+      - ApiKeyQuery: []
+      summary: Search the server catalog across every enabled source
+      tags:
+      - catalog
   /api/v1/code/scripts:
     get:
       description: 'List the stored scripts available to the code_execution tool.

From ab75d4716beafcec174963ff0542dd0ae44474de Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 01:40:53 +0300
Subject: [PATCH 19/27] test(catalog): pin secret_like name-rule override and
 non-admin user-context scoping (T099)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- registries: a registry's explicit isSecret:false (or omitted) on a
  secret-shaped name still serves secret_like:true; an explicit true
  passes through unchanged.
- httpapi: FR-007 scoping is not agent-token-specific — a non-admin
  AuthTypeUser session (server edition's OAuth user identity) scoped to
  one server sees the same added:true/false split an agent token does.
---
 internal/httpapi/catalog_test.go    | 30 +++++++++++++++++++++++++++++
 internal/registries/catalog_test.go | 29 ++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+)

diff --git a/internal/httpapi/catalog_test.go b/internal/httpapi/catalog_test.go
index 0f7b2d46e..1410ef2ef 100644
--- a/internal/httpapi/catalog_test.go
+++ b/internal/httpapi/catalog_test.go
@@ -7,7 +7,9 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
 
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/auth"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/contracts"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/registries"
 )
@@ -167,3 +169,31 @@ func catalogAddedFor(results []map[string]interface{}, id string) bool {
 	}
 	return false
 }
+
+// TestCatalogSearch_AddedScopedForNonAdminUserContext pins that the FR-007
+// scoping is not agent-token-specific: a non-admin AuthTypeUser session
+// (server edition's OAuth user identity, e.g. a tenant) is scoped by the same
+// visibleServers/CanEnumerateServer predicate an agent token goes through,
+// driven directly at the handler (like TestRequireAdminRead_DeniesNonAdminUserContext)
+// since apiKeyAuthMiddleware itself only ever installs admin/agent contexts.
+func TestCatalogSearch_AddedScopedForNonAdminUserContext(t *testing.T) {
+	withCatalogFixtureRegistry(t)
+	ctrl := &scopeController{cfg: scopeFixtureConfig(false), servers: catalogFixtureServers(), withManagement: true}
+	srv := NewServer(ctrl, zap.NewNop().Sugar(), nil)
+
+	userCtx := &auth.AuthContext{
+		Type:           auth.AuthTypeUser,
+		UserID:         "alice",
+		AllowedServers: []string{"gamma"},
+		CredentialKind: auth.CredentialKindCookie,
+	}
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/catalog/search?q=tool", http.NoBody)
+	req = req.WithContext(auth.WithAuthContext(req.Context(), userCtx))
+	rec := httptest.NewRecorder()
+	srv.handleCatalogSearch(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	results := catalogDecodeResults(t, rec)
+	assert.True(t, catalogAddedFor(results, "gamma-tool"), "user session scoped to gamma: expected gamma-tool added=true")
+	assert.False(t, catalogAddedFor(results, "delta-tool"), "user session scoped to gamma: expected delta-tool added=false (out of scope)")
+}
diff --git a/internal/registries/catalog_test.go b/internal/registries/catalog_test.go
index 0c4f5f111..8f6ab434c 100644
--- a/internal/registries/catalog_test.go
+++ b/internal/registries/catalog_test.go
@@ -178,6 +178,35 @@ func TestToCatalogResult_HTTPInstall(t *testing.T) {
 	}
 }
 
+// TestToCatalogResult_SecretLikeOverridesFalsifiedFlag pins T099/FR-065: a
+// registry that explicitly sets isSecret:false on a secret-shaped name (or
+// omits it) still serves secret_like:true — the D13 name rule is OR'd in,
+// never overridden by the registry's own (possibly wrong) flag.
+func TestToCatalogResult_SecretLikeOverridesFalsifiedFlag(t *testing.T) {
+	hit := CatalogHit{
+		Source: "official",
+		Entry: ServerEntry{ID: "x", RequiredInputs: []RequiredInput{
+			{Name: "GITHUB_TOKEN", Secret: false}, // falsified: registry says not secret
+			{Name: "GITHUB_TOKEN_OMITTED"},        // omitted: Go zero value is false
+			{Name: "PORT", Secret: true},          // explicit true passes through
+		}},
+	}
+	result := ToCatalogResult(hit, false)
+	byName := map[string]bool{}
+	for _, in := range result.RequiredInputs {
+		byName[in.Name] = in.SecretLike
+	}
+	if !byName["GITHUB_TOKEN"] {
+		t.Error("expected GITHUB_TOKEN secret_like=true despite Secret:false (name rule overrides)")
+	}
+	if !byName["GITHUB_TOKEN_OMITTED"] {
+		t.Error("expected GITHUB_TOKEN_OMITTED secret_like=true (name rule)")
+	}
+	if !byName["PORT"] {
+		t.Error("expected PORT secret_like=true (explicit registry flag passes through)")
+	}
+}
+
 // TestToCatalogResult_StdioInstall pins command/args splitting for a local
 // install target.
 func TestToCatalogResult_StdioInstall(t *testing.T) {

From ce0be59d82ce8f5b447f78dab603e9454d3af214 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 03:14:36 +0300
Subject: [PATCH 20/27] fix: address review round 1 findings on
 catalog/add-server (Spec 109 FR-060/065/067)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

High
- secret: IsAvailableWithReason (GET /secrets/config keyring_available,
  and the CLI's applySecretFlags pre-check) now consults the macOS write
  gate (writesEnabled()) before the read-only probe, not after. Before
  this, a headless `mcpproxy serve` or the CLI's own in-process resolver
  reported keyring_available:true and then had every Store() call
  immediately fail with ErrKeyringUnavailable, because only Store() (not
  the probe) checked the gate.
- web(CatalogSearch): confirmAdd() closed the secrets dialog and cleared
  addError unconditionally after addResult(), even on failure — addResult
  never throws (api.ts always resolves {success:false}), so a failed
  add-after-secret-write looked identical to success. addResult now
  returns a success bool; confirmAdd only closes the dialog on success and
  rolls back the just-written secret otherwise.

Medium
- web: rollbackSecrets was exported but never called by any of the three
  add surfaces (CatalogSearch, PasteServer, ManualServerForm) when the
  add-server call failed after a successful secret write, orphaning a
  keyring entry and forcing a retry onto a -2-suffixed name. All three now
  track resolveSecretFields' writtenRefs and roll them back on a later
  failure.
- cli(upstream add): applySecretFlags (writes to the OS keyring) ran
  before validateTrustModeFlag, so a typo'd --trust-mode orphaned an
  already-written secret. Moved trust-mode validation first. Also:
  applySecretFlags now rolls back its own partial writes when the second
  of two --secret-env/--secret-header flags fails; runUpstreamAddDaemonMode
  and runUpstreamAddConfigMode now return (added bool, err error) so a
  --if-not-exists skip (nil error, added=false) is distinguishable from a
  genuine add, and runUpstreamAdd rolls back any written secrets via defer
  unless added ends up true (covers the daemon/config-load/save failure
  paths too, not just the skip).
- mcp(search_servers): 'registry' omitted returned bare registries.ServerEntry
  items with none of the catalog fields (title/publisher/verified/official/
  popularity/source) contracts/mcp-tools.md requires — MCP callers got none
  of the FR-060 ranking evidence REST/CLI callers already had. Added
  mcpCatalogServerEntry (embeds ServerEntry, encoding/json promotes its
  fields, plus the catalog fields alongside).
- httpapi(catalog): GET /catalog/search set results to the full ranked list
  even when sections was populated (empty q), contradicting "Empty q →
  results: []". Now emptied whenever sections is set.
- registries/httpapi/cli(catalog): source= was filtered AFTER SearchAll had
  already truncated to limit, so a narrower source's real matches ranked
  below an official/verified source could vanish entirely. SearchOptions
  gained a Source field; SearchAll now filters before ranking/truncation.
  Both httpapi.handleCatalogSearch and the CLI's catalogSearchInProcess
  switched to it, dropping their duplicated post-hoc filter helpers.

Rejected
- registries(catalog): Popularity is never populated in production
  (registries.ServerEntry carries no stars/installs field, and no
  registry-protocol parser in this codebase fills one — confirmed only
  tests ever construct a Popularity value), so the FR-060 popularity
  tiebreak always compares 0-vs-0 and the "Popular" section degrades to
  the same ranked list. Not fixed here: sourcing a real popularity signal
  (GitHub stars API, npm download counts, or a registry-reported count)
  is a new external-data integration — new calls, caching, rate-limit
  handling — sized for its own spec/plan, not a bounded review-round fix.

Tests: internal/secret (macOS write-gate cases), internal/server
(search_servers catalog fields), internal/httpapi (empty-q results,
source-filter-before-truncation), cmd/mcpproxy (CLI source-filter,
applySecretFlags self-rollback, --if-not-exists added=false), frontend
vitest (CatalogSearch/PasteServer/ManualServerForm rollback-on-failure).

Verification: go build ./...; go test -race on internal/secret,
internal/registries, internal/httpapi, cmd/mcpproxy; go test (and
go test -race, -skip per CLAUDE.md) on internal/server; golangci-lint v2
bare and --build-tags server on all touched packages (0 new issues); cd
frontend && npm ci && npm run build && npx vitest run (155 files / 1428
tests green); package-lock.json unchanged.
---
 cmd/mcpproxy/catalog_cmd.go                   | 26 ++-----
 cmd/mcpproxy/catalog_cmd_test.go              | 33 +++++++++
 cmd/mcpproxy/upstream_add_config_mode_test.go |  4 +-
 cmd/mcpproxy/upstream_add_secret.go           | 59 ++++++++++++---
 cmd/mcpproxy/upstream_add_secret_test.go      | 58 +++++++++++++--
 cmd/mcpproxy/upstream_cmd.go                  | 73 ++++++++++++++-----
 cmd/mcpproxy/upstream_cmd_test.go             | 21 ++++--
 frontend/src/components/CatalogSearch.vue     | 32 ++++++--
 frontend/src/components/ManualServerForm.vue  | 11 ++-
 frontend/src/components/PasteServer.vue       | 11 ++-
 .../tests/unit/add-server-catalog.spec.ts     | 48 ++++++++++++
 frontend/tests/unit/add-server-manual.spec.ts | 73 +++++++++++++++++++
 frontend/tests/unit/add-server-paste.spec.ts  | 42 +++++++++++
 internal/httpapi/catalog.go                   | 30 +++-----
 internal/httpapi/catalog_test.go              | 71 ++++++++++++++++++
 internal/registries/catalog.go                | 24 ++++++
 internal/secret/keyring_available_test.go     | 68 +++++++++++++++++
 internal/secret/keyring_provider.go           | 16 +++-
 internal/server/mcp.go                        | 38 ++++++++--
 .../server/search_servers_all_sources_test.go | 10 +++
 20 files changed, 649 insertions(+), 99 deletions(-)
 create mode 100644 frontend/tests/unit/add-server-manual.spec.ts

diff --git a/cmd/mcpproxy/catalog_cmd.go b/cmd/mcpproxy/catalog_cmd.go
index 33be53549..4f0d30721 100644
--- a/cmd/mcpproxy/catalog_cmd.go
+++ b/cmd/mcpproxy/catalog_cmd.go
@@ -246,16 +246,12 @@ func catalogSearch(ctx context.Context, cfg *config.Config, q, source, tag strin
 // whatever registries.ListRegistries() currently returns rather than loading
 // it itself — see catalogSearch, its only production caller.
 func catalogSearchInProcess(ctx context.Context, cfg *config.Config, q, source, tag string, limit int) (*cliclient.CatalogSearchResponse, error) {
-	hits, sections, unavailable := registries.SearchAll(ctx, q, tag, limit, registries.SearchOptions{})
-	if source != "" {
-		hits = filterCatalogHitsBySourceCLI(hits, source)
-		if sections != nil {
-			sections = &registries.CatalogSections{
-				Official: filterCatalogHitsBySourceCLI(sections.Official, source),
-				Popular:  filterCatalogHitsBySourceCLI(sections.Popular, source),
-			}
-		}
-	}
+	// Source is applied inside SearchAll, BEFORE ranking/truncation to
+	// limit — filtering after truncation could silently drop a narrower
+	// source's real matches that simply lost out to an official/verified
+	// source for one of the truncated top-`limit` slots (same fix as
+	// httpapi.handleCatalogSearch).
+	hits, sections, unavailable := registries.SearchAll(ctx, q, tag, limit, registries.SearchOptions{Source: source})
 
 	added := catalogAddedFromConfig(cfg)
 	resp := &cliclient.CatalogSearchResponse{Query: q, Unavailable: unavailable}
@@ -277,16 +273,6 @@ func catalogSearchInProcess(ctx context.Context, cfg *config.Config, q, source,
 	return resp, nil
 }
 
-func filterCatalogHitsBySourceCLI(hits []registries.CatalogHit, source string) []registries.CatalogHit {
-	out := make([]registries.CatalogHit, 0, len(hits))
-	for _, h := range hits {
-		if h.Source == source {
-			out = append(out, h)
-		}
-	}
-	return out
-}
-
 // catalogAddedFromConfig returns a predicate reporting whether a catalog hit
 // matches an already-configured server (contracts/rest-api.md#catalog "added"):
 // a registry-sourced server also needs a matching source, a manual add
diff --git a/cmd/mcpproxy/catalog_cmd_test.go b/cmd/mcpproxy/catalog_cmd_test.go
index 349e2452e..50c439b04 100644
--- a/cmd/mcpproxy/catalog_cmd_test.go
+++ b/cmd/mcpproxy/catalog_cmd_test.go
@@ -141,6 +141,39 @@ func TestCatalogSearchInProcess_BrowseSections(t *testing.T) {
 	}
 }
 
+// TestCatalogSearchInProcess_SourceFilterAppliesBeforeTruncation is the CLI
+// counterpart of the REST regression: with limit=1, an official source's
+// single entry fills the only truncated slot ahead of a lower-ranked
+// "other" source's entry. Narrowing to source=other must still surface it
+// rather than coming back empty just because it lost the pre-filter
+// truncation race.
+func TestCatalogSearchInProcess_SourceFilterAppliesBeforeTruncation(t *testing.T) {
+	officialSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{"id":"official-tool","name":"Official Tool"}]`))
+	}))
+	t.Cleanup(officialSrv.Close)
+	otherSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`[{"id":"other-tool","name":"Other Tool"}]`))
+	}))
+	t.Cleanup(otherSrv.Close)
+	t.Cleanup(registries.AllowPrivateRegistryFetchForTest())
+	t.Cleanup(registries.SetRegistriesForTest([]registries.RegistryEntry{
+		{ID: "official", Name: "Official", ServersURL: officialSrv.URL, Provenance: "official"},
+		{ID: "other", Name: "Other", ServersURL: otherSrv.URL},
+	}))
+	cfg := &config.Config{}
+
+	resp, err := catalogSearchInProcess(context.Background(), cfg, "tool", "other", "", 1)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(resp.Results) != 1 || resp.Results[0].ID != "other-tool" {
+		t.Fatalf("expected other-tool to survive source filtering despite limit=1, got: %+v", resp.Results)
+	}
+}
+
 // TestCatalogShow is the T100 "show" golden.
 func TestCatalogShow(t *testing.T) {
 	withCatalogCLIFixture(t, `[{"id":"gh","name":"GitHub Tool","description":"desc","url":"https://x.example.com/mcp"}]`)
diff --git a/cmd/mcpproxy/upstream_add_config_mode_test.go b/cmd/mcpproxy/upstream_add_config_mode_test.go
index 6aea508ad..a76e7ec57 100644
--- a/cmd/mcpproxy/upstream_add_config_mode_test.go
+++ b/cmd/mcpproxy/upstream_add_config_mode_test.go
@@ -28,7 +28,9 @@ func TestUpstreamAddConfigModeQuarantineFollowsTrustMode(t *testing.T) {
 			TrustMode:   trustMode,
 			Quarantined: explicit,
 		}
-		require.NoError(t, runUpstreamAddConfigMode(req, cfg))
+		added, err := runUpstreamAddConfigMode(req, cfg)
+		require.NoError(t, err)
+		require.True(t, added)
 		require.Len(t, cfg.Servers, 1)
 		return cfg.Servers[0]
 	}
diff --git a/cmd/mcpproxy/upstream_add_secret.go b/cmd/mcpproxy/upstream_add_secret.go
index 4482560e3..4bd12e2b7 100644
--- a/cmd/mcpproxy/upstream_add_secret.go
+++ b/cmd/mcpproxy/upstream_add_secret.go
@@ -15,13 +15,23 @@ import (
 // AddServerRequest never carries the raw value. It refuses outright — before
 // writing anything — when the keyring is unavailable, naming the provider's
 // own reason, rather than silently falling back to plaintext.
-func applySecretFlags(resolver *secret.Resolver, serverName string, secretEnvs, secretHeaders []string, env, headers map[string]string) error {
+//
+// It returns the refs THIS call wrote. On success the caller (runUpstreamAdd)
+// is responsible for rolling them back if a LATER step (trust-mode
+// validation happens first now, but config load, the daemon/config-mode add
+// itself, or a --if-not-exists skip) fails or doesn't result in the server
+// actually being added — this function has no visibility into those later
+// steps. On its OWN failure (a bad flag format, or the second of two flags
+// failing to store), it rolls back everything it wrote so far itself and
+// returns no refs, so the caller never has to distinguish "nothing was
+// written" from "something was written and already cleaned up".
+func applySecretFlags(resolver *secret.Resolver, serverName string, secretEnvs, secretHeaders []string, env, headers map[string]string) ([]string, error) {
 	if len(secretEnvs) == 0 && len(secretHeaders) == 0 {
-		return nil
+		return nil, nil
 	}
 
 	if ok, reason := resolver.KeyringAvailability(); !ok {
-		return fmt.Errorf("cannot store --secret-env/--secret-header: OS keyring unavailable (%s)", reason)
+		return nil, fmt.Errorf("cannot store --secret-env/--secret-header: OS keyring unavailable (%s)", reason)
 	}
 
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
@@ -29,7 +39,7 @@ func applySecretFlags(resolver *secret.Resolver, serverName string, secretEnvs,
 
 	existing, err := resolver.ListAll(ctx)
 	if err != nil {
-		return fmt.Errorf("failed to list existing keyring entries: %w", err)
+		return nil, fmt.Errorf("failed to list existing keyring entries: %w", err)
 	}
 	taken := make(map[string]bool, len(existing))
 	for _, ref := range existing {
@@ -44,33 +54,64 @@ func applySecretFlags(resolver *secret.Resolver, serverName string, secretEnvs,
 	// overwrite an existing secret).
 	takenFn := func(n string) bool { return taken[n] }
 
+	var writtenRefs []string
+	// fail rolls back everything written so far in this call before
+	// returning err, so a failure partway through (e.g. the second of two
+	// --secret-env flags) never leaves the first flag's secret orphaned.
+	fail := func(err error) ([]string, error) {
+		for _, ref := range writtenRefs {
+			_ = resolver.Delete(ctx, secret.Ref{Type: secret.SecretTypeKeyring, Name: ref})
+		}
+		return nil, err
+	}
+
 	for _, kv := range secretEnvs {
 		name, value, ok := strings.Cut(kv, "=")
 		if !ok {
-			return fmt.Errorf("invalid --secret-env format: %q (expected KEY=value)", kv)
+			return fail(fmt.Errorf("invalid --secret-env format: %q (expected KEY=value)", kv))
 		}
 		ref := secret.RefName(serverName, "env", name, takenFn)
 		if err := resolver.Store(ctx, secret.Ref{Type: secret.SecretTypeKeyring, Name: ref}, value); err != nil {
-			return fmt.Errorf("failed to store secret for env %s: %w", name, err)
+			return fail(fmt.Errorf("failed to store secret for env %s: %w", name, err))
 		}
 		taken[ref] = true
+		writtenRefs = append(writtenRefs, ref)
 		env[name] = fmt.Sprintf("${keyring:%s}", ref)
 	}
 
 	for _, kv := range secretHeaders {
 		name, value, ok := strings.Cut(kv, ":")
 		if !ok {
-			return fmt.Errorf("invalid --secret-header format: %q (expected 'Name: value')", kv)
+			return fail(fmt.Errorf("invalid --secret-header format: %q (expected 'Name: value')", kv))
 		}
 		name = strings.TrimSpace(name)
 		value = strings.TrimSpace(value)
 		ref := secret.RefName(serverName, "header", name, takenFn)
 		if err := resolver.Store(ctx, secret.Ref{Type: secret.SecretTypeKeyring, Name: ref}, value); err != nil {
-			return fmt.Errorf("failed to store secret for header %s: %w", name, err)
+			return fail(fmt.Errorf("failed to store secret for header %s: %w", name, err))
 		}
 		taken[ref] = true
+		writtenRefs = append(writtenRefs, ref)
 		headers[name] = fmt.Sprintf("${keyring:%s}", ref)
 	}
 
-	return nil
+	return writtenRefs, nil
+}
+
+// rollbackKeyringRefs is the runUpstreamAdd-level counterpart of
+// applySecretFlags' internal rollback: it deletes refs that WERE
+// successfully written by applySecretFlags but must not survive because a
+// later step (trust-mode validation, config load, the daemon/config-mode add
+// itself, or a --if-not-exists skip) didn't result in the server actually
+// being added. Best-effort: a delete failure here is not surfaced, since the
+// original error is what the user needs to see.
+func rollbackKeyringRefs(resolver *secret.Resolver, refs []string) {
+	if len(refs) == 0 {
+		return
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	for _, ref := range refs {
+		_ = resolver.Delete(ctx, secret.Ref{Type: secret.SecretTypeKeyring, Name: ref})
+	}
 }
diff --git a/cmd/mcpproxy/upstream_add_secret_test.go b/cmd/mcpproxy/upstream_add_secret_test.go
index b39d90099..b8f3fcbfb 100644
--- a/cmd/mcpproxy/upstream_add_secret_test.go
+++ b/cmd/mcpproxy/upstream_add_secret_test.go
@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"fmt"
 	"testing"
 
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/secret"
@@ -12,6 +13,13 @@ import (
 type fakeKeyringProvider struct {
 	available bool
 	store     map[string]string
+	deleted   []string // names passed to Delete, in call order (rollback pinning)
+
+	// failStoreOnNthCall, when > 0, makes the Nth call to Store (1-indexed)
+	// fail without writing, so tests can pin the internal rollback of
+	// everything stored by the calls before it.
+	failStoreOnNthCall int
+	storeCalls         int
 }
 
 func newFakeKeyringProvider(available bool) *fakeKeyringProvider {
@@ -23,10 +31,15 @@ func (f *fakeKeyringProvider) Resolve(_ context.Context, ref secret.Ref) (string
 	return f.store[ref.Name], nil
 }
 func (f *fakeKeyringProvider) Store(_ context.Context, ref secret.Ref, value string) error {
+	f.storeCalls++
+	if f.failStoreOnNthCall > 0 && f.storeCalls == f.failStoreOnNthCall {
+		return fmt.Errorf("simulated keyring failure on call %d", f.storeCalls)
+	}
 	f.store[ref.Name] = value
 	return nil
 }
 func (f *fakeKeyringProvider) Delete(_ context.Context, ref secret.Ref) error {
+	f.deleted = append(f.deleted, ref.Name)
 	delete(f.store, ref.Name)
 	return nil
 }
@@ -54,7 +67,7 @@ func TestApplySecretFlags_WritesKeyringRefsIntoEnvAndHeaders(t *testing.T) {
 
 	env := map[string]string{}
 	headers := map[string]string{}
-	err := applySecretFlags(resolver, "github",
+	writtenRefs, err := applySecretFlags(resolver, "github",
 		[]string{"GITHUB_TOKEN=sk-live-abc123"},
 		[]string{"Authorization: Bearer xyz"},
 		env, headers,
@@ -62,6 +75,9 @@ func TestApplySecretFlags_WritesKeyringRefsIntoEnvAndHeaders(t *testing.T) {
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
+	if len(writtenRefs) != 2 {
+		t.Errorf("expected 2 written refs, got %+v", writtenRefs)
+	}
 
 	envRef, ok := env["GITHUB_TOKEN"]
 	if !ok || envRef != "${keyring:github-env-github-token}" {
@@ -89,7 +105,7 @@ func TestApplySecretFlags_EnvHeaderSameNameCollision(t *testing.T) {
 
 	env := map[string]string{}
 	headers := map[string]string{}
-	err := applySecretFlags(resolver, "github",
+	_, err := applySecretFlags(resolver, "github",
 		[]string{"API_KEY=env-value"},
 		[]string{"API_KEY: header-value"},
 		env, headers,
@@ -120,7 +136,7 @@ func TestApplySecretFlags_TakenNameGetsSuffix(t *testing.T) {
 	resolver := newTestSecretResolver(fake)
 
 	env := map[string]string{}
-	if err := applySecretFlags(resolver, "github", []string{"API_KEY=new-value"}, nil, env, map[string]string{}); err != nil {
+	if _, err := applySecretFlags(resolver, "github", []string{"API_KEY=new-value"}, nil, env, map[string]string{}); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
 
@@ -142,7 +158,7 @@ func TestApplySecretFlags_KeyringUnavailableRefuses(t *testing.T) {
 	resolver := newTestSecretResolver(fake)
 
 	env := map[string]string{}
-	err := applySecretFlags(resolver, "github", []string{"API_KEY=value"}, nil, env, map[string]string{})
+	_, err := applySecretFlags(resolver, "github", []string{"API_KEY=value"}, nil, env, map[string]string{})
 	if err == nil {
 		t.Fatal("expected an error when the keyring is unavailable")
 	}
@@ -160,7 +176,7 @@ func TestApplySecretFlags_NoFlagsIsNoOp(t *testing.T) {
 	fake := newFakeKeyringProvider(false) // unavailable — must not matter
 	resolver := newTestSecretResolver(fake)
 
-	if err := applySecretFlags(resolver, "github", nil, nil, map[string]string{}, map[string]string{}); err != nil {
+	if _, err := applySecretFlags(resolver, "github", nil, nil, map[string]string{}, map[string]string{}); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
 }
@@ -170,10 +186,38 @@ func TestApplySecretFlags_InvalidFormat(t *testing.T) {
 	fake := newFakeKeyringProvider(true)
 	resolver := newTestSecretResolver(fake)
 
-	if err := applySecretFlags(resolver, "github", []string{"NOEQUALS"}, nil, map[string]string{}, map[string]string{}); err == nil {
+	if _, err := applySecretFlags(resolver, "github", []string{"NOEQUALS"}, nil, map[string]string{}, map[string]string{}); err == nil {
 		t.Error("expected an error for a --secret-env value with no '='")
 	}
-	if err := applySecretFlags(resolver, "github", nil, []string{"NoColonHere"}, map[string]string{}, map[string]string{}); err == nil {
+	if _, err := applySecretFlags(resolver, "github", nil, []string{"NoColonHere"}, map[string]string{}, map[string]string{}); err == nil {
 		t.Error("expected an error for a --secret-header value with no ':'")
 	}
 }
+
+// TestApplySecretFlags_SecondStoreFailureRollsBackFirst pins the review
+// round 1 finding: if the second of two --secret-env/--secret-header flags
+// fails to store, the first flag's already-stored secret must not be left
+// orphaned in the keyring.
+func TestApplySecretFlags_SecondStoreFailureRollsBackFirst(t *testing.T) {
+	fake := newFakeKeyringProvider(true)
+	fake.failStoreOnNthCall = 2
+	resolver := newTestSecretResolver(fake)
+
+	env := map[string]string{}
+	writtenRefs, err := applySecretFlags(resolver, "github",
+		[]string{"FIRST_TOKEN=first-value", "SECOND_TOKEN=second-value"},
+		nil, env, map[string]string{},
+	)
+	if err == nil {
+		t.Fatal("expected an error when the second Store call fails")
+	}
+	if len(writtenRefs) != 0 {
+		t.Errorf("expected no refs returned on failure (everything rolled back), got %+v", writtenRefs)
+	}
+	if len(fake.store) != 0 {
+		t.Errorf("expected the first flag's secret to be rolled back, got %+v", fake.store)
+	}
+	if len(fake.deleted) != 1 || fake.deleted[0] != "github-env-first-token" {
+		t.Errorf("expected exactly one rollback delete for the first ref, got %+v", fake.deleted)
+	}
+}
diff --git a/cmd/mcpproxy/upstream_cmd.go b/cmd/mcpproxy/upstream_cmd.go
index 7d1401df2..0749d942c 100644
--- a/cmd/mcpproxy/upstream_cmd.go
+++ b/cmd/mcpproxy/upstream_cmd.go
@@ -1282,20 +1282,40 @@ func runUpstreamAdd(cmd *cobra.Command, args []string) error {
 		env[parts[0]] = parts[1]
 	}
 
+	// GH #938: refuse a typo'd tier before anything is written, with the same
+	// vocabulary the REST layer reports in its 400. Checked BEFORE the
+	// secret-write block below: applySecretFlags writes to the OS keyring,
+	// so validating trust-mode first means a typo'd tier can never orphan a
+	// secret that was written only to have the whole add aborted moments
+	// later (review round 1).
+	if err := validateTrustModeFlag(upstreamAddTrustMode); err != nil {
+		return err
+	}
+
 	// FR-065: --secret-env/--secret-header write to the OS keyring instead
 	// of the config, under the shared per-kind ref name, and merge
 	// ${keyring:<ref>} into the same env/headers maps above.
+	resolver := secret.NewResolver()
+	var writtenSecretRefs []string
 	if len(upstreamAddSecretEnvs) > 0 || len(upstreamAddSecretHeaders) > 0 {
-		if err := applySecretFlags(secret.NewResolver(), serverName, upstreamAddSecretEnvs, upstreamAddSecretHeaders, env, headers); err != nil {
+		var err error
+		writtenSecretRefs, err = applySecretFlags(resolver, serverName, upstreamAddSecretEnvs, upstreamAddSecretHeaders, env, headers)
+		if err != nil {
 			return err
 		}
 	}
-
-	// GH #938: refuse a typo'd tier before anything is written, with the same
-	// vocabulary the REST layer reports in its 400.
-	if err := validateTrustModeFlag(upstreamAddTrustMode); err != nil {
-		return err
-	}
+	// Every return path below this point that does NOT end with the server
+	// actually being added (a daemon/config-mode failure, or a
+	// --if-not-exists skip telling the user "skipped" while the secret WAS
+	// stored) must not leave an orphaned keyring entry behind — added is set
+	// true only once runUpstreamAddDaemonMode/runUpstreamAddConfigMode
+	// confirms a genuine add (review round 1).
+	added := false
+	defer func() {
+		if !added {
+			rollbackKeyringRefs(resolver, writtenSecretRefs)
+		}
+	}()
 
 	// Build the request
 	req := &cliclient.AddServerRequest{
@@ -1337,11 +1357,15 @@ func runUpstreamAdd(cmd *cobra.Command, args []string) error {
 
 	// Check if daemon is running
 	if client, ok := newDaemonClient(globalConfig, nil); ok {
-		return runUpstreamAddDaemonMode(ctx, client, req)
+		wasAdded, addErr := runUpstreamAddDaemonMode(ctx, client, req)
+		added = wasAdded
+		return addErr
 	}
 
 	// Direct config file mode
-	return runUpstreamAddConfigMode(req, globalConfig)
+	wasAdded, addErr := runUpstreamAddConfigMode(req, globalConfig)
+	added = wasAdded
+	return addErr
 }
 
 // outputSkipNotice prints a human skip notice (for --if-not-exists /
@@ -1364,17 +1388,23 @@ func outputSkipNotice(notice string, payload map[string]interface{}) error {
 	return nil
 }
 
-func runUpstreamAddDaemonMode(ctx context.Context, client *cliclient.Client, req *cliclient.AddServerRequest) error {
+// runUpstreamAddDaemonMode returns (added, err): added is true only when the
+// daemon actually created the server. A --if-not-exists skip (nil error,
+// added=false) is deliberately distinguished from a genuine add so the
+// caller (runUpstreamAdd) knows whether to roll back any --secret-env/
+// --secret-header values it already wrote to the keyring for this request
+// (review round 1: a skip must not leave the secret orphaned).
+func runUpstreamAddDaemonMode(ctx context.Context, client *cliclient.Client, req *cliclient.AddServerRequest) (bool, error) {
 	result, err := client.AddServer(ctx, req)
 	if err != nil {
 		// Check if it's "already exists" error and --if-not-exists is set
 		if upstreamAddIfNotExists && strings.Contains(err.Error(), "already exists") {
-			return outputSkipNotice(
+			return false, outputSkipNotice(
 				fmt.Sprintf("Server '%s' already exists (skipped)", req.Name),
 				map[string]interface{}{"name": req.Name, "skipped": true},
 			)
 		}
-		return outputError(output.NewStructuredError(output.ErrCodeOperationFailed, err.Error()).
+		return false, outputError(output.NewStructuredError(output.ErrCodeOperationFailed, err.Error()).
 			WithGuidance("Check the server name and configuration"), output.ErrCodeOperationFailed)
 	}
 
@@ -1391,20 +1421,21 @@ func runUpstreamAddDaemonMode(ctx context.Context, client *cliclient.Client, req
 		}
 	}
 
-	return nil
+	return true, nil
 }
 
-func runUpstreamAddConfigMode(req *cliclient.AddServerRequest, globalConfig *config.Config) error {
+// runUpstreamAddConfigMode returns (added, err) — see runUpstreamAddDaemonMode.
+func runUpstreamAddConfigMode(req *cliclient.AddServerRequest, globalConfig *config.Config) (bool, error) {
 	// Check if server already exists
 	for _, srv := range globalConfig.Servers {
 		if srv.Name == req.Name {
 			if upstreamAddIfNotExists {
-				return outputSkipNotice(
+				return false, outputSkipNotice(
 					fmt.Sprintf("Server '%s' already exists (skipped)", req.Name),
 					map[string]interface{}{"name": req.Name, "skipped": true},
 				)
 			}
-			return fmt.Errorf("server '%s' already exists", req.Name)
+			return false, fmt.Errorf("server '%s' already exists", req.Name)
 		}
 	}
 
@@ -1443,7 +1474,7 @@ func runUpstreamAddConfigMode(req *cliclient.AddServerRequest, globalConfig *con
 	// Save config
 	configPath := config.GetConfigPath(globalConfig.DataDir)
 	if err := config.SaveConfig(globalConfig, configPath); err != nil {
-		return fmt.Errorf("failed to save config: %w", err)
+		return false, fmt.Errorf("failed to save config: %w", err)
 	}
 
 	// Output success
@@ -1452,7 +1483,7 @@ func runUpstreamAddConfigMode(req *cliclient.AddServerRequest, globalConfig *con
 		fmt.Println("   ⚠️  New servers are quarantined by default. Start the daemon and approve in the web UI.")
 	}
 
-	return nil
+	return true, nil
 }
 
 // runUpstreamRemove handles the 'upstream remove' command
@@ -1644,11 +1675,13 @@ func runUpstreamAddJSON(cmd *cobra.Command, args []string) error {
 
 	// Check if daemon is running
 	if client, ok := newDaemonClient(globalConfig, nil); ok {
-		return runUpstreamAddDaemonMode(ctx, client, req)
+		_, err := runUpstreamAddDaemonMode(ctx, client, req)
+		return err
 	}
 
 	// Direct config file mode
-	return runUpstreamAddConfigMode(req, globalConfig)
+	_, err = runUpstreamAddConfigMode(req, globalConfig)
+	return err
 }
 
 // validateServerName validates server name format (alphanumeric, hyphens, underscores, 1-64 chars)
diff --git a/cmd/mcpproxy/upstream_cmd_test.go b/cmd/mcpproxy/upstream_cmd_test.go
index 6b49d81c3..74cd1316c 100644
--- a/cmd/mcpproxy/upstream_cmd_test.go
+++ b/cmd/mcpproxy/upstream_cmd_test.go
@@ -642,7 +642,7 @@ func TestAddHTTPServerConfigMode(t *testing.T) {
 		r, w, _ := os.Pipe()
 		os.Stdout = w
 
-		err = runUpstreamAddConfigMode(req, cfg)
+		_, err = runUpstreamAddConfigMode(req, cfg)
 
 		w.Close()
 		os.Stdout = oldStdout
@@ -717,7 +717,7 @@ func TestAddHTTPServerConfigMode(t *testing.T) {
 		_, w, _ := os.Pipe()
 		os.Stdout = w
 
-		err = runUpstreamAddConfigMode(req, cfg)
+		_, err = runUpstreamAddConfigMode(req, cfg)
 
 		w.Close()
 		os.Stdout = oldStdout
@@ -769,7 +769,7 @@ func TestAddHTTPServerConfigMode(t *testing.T) {
 		}
 		cfg.DataDir = tmpDir
 
-		err = runUpstreamAddConfigMode(req, cfg)
+		_, err = runUpstreamAddConfigMode(req, cfg)
 
 		if err == nil {
 			t.Error("Expected error for duplicate server")
@@ -830,7 +830,7 @@ func TestAddHTTPServerConfigMode(t *testing.T) {
 		os.Stdout = wOut
 		os.Stderr = wErr
 
-		err = runUpstreamAddConfigMode(req, cfg)
+		added, err := runUpstreamAddConfigMode(req, cfg)
 
 		wOut.Close()
 		wErr.Close()
@@ -843,6 +843,13 @@ func TestAddHTTPServerConfigMode(t *testing.T) {
 		if err != nil {
 			t.Errorf("Expected no error with --if-not-exists, got: %v", err)
 		}
+		// review round 1: added must be false on a skip, distinct from a
+		// genuine add with a nil error — runUpstreamAdd uses this to decide
+		// whether to roll back any --secret-env/--secret-header values
+		// already written to the keyring for this request.
+		if added {
+			t.Error("expected added=false for an --if-not-exists skip")
+		}
 		if !strings.Contains(bufErr.String(), "already exists") || !strings.Contains(bufErr.String(), "skipped") {
 			t.Error("Expected skip message on stderr for existing server")
 		}
@@ -890,7 +897,7 @@ func TestAddStdioServerConfigMode(t *testing.T) {
 		_, w, _ := os.Pipe()
 		os.Stdout = w
 
-		err = runUpstreamAddConfigMode(req, cfg)
+		_, err = runUpstreamAddConfigMode(req, cfg)
 
 		w.Close()
 		os.Stdout = oldStdout
@@ -967,7 +974,7 @@ func TestAddStdioServerConfigMode(t *testing.T) {
 		_, w, _ := os.Pipe()
 		os.Stdout = w
 
-		err = runUpstreamAddConfigMode(req, cfg)
+		_, err = runUpstreamAddConfigMode(req, cfg)
 
 		w.Close()
 		os.Stdout = oldStdout
@@ -1370,7 +1377,7 @@ func TestNewServerQuarantineDefault(t *testing.T) {
 		r, w, _ := os.Pipe()
 		os.Stdout = w
 
-		err = runUpstreamAddConfigMode(req, cfg)
+		_, err = runUpstreamAddConfigMode(req, cfg)
 
 		w.Close()
 		os.Stdout = oldStdout
diff --git a/frontend/src/components/CatalogSearch.vue b/frontend/src/components/CatalogSearch.vue
index 7b7fed465..4b49654b7 100644
--- a/frontend/src/components/CatalogSearch.vue
+++ b/frontend/src/components/CatalogSearch.vue
@@ -118,7 +118,7 @@ import { useRouter } from 'vue-router'
 import api from '@/services/api'
 import type { CatalogResult, CatalogSections } from '@/types'
 import SecretToggle from '@/components/SecretToggle.vue'
-import { resolveSecretFields } from '@/composables/useSecretFields'
+import { resolveSecretFields, rollbackSecrets } from '@/composables/useSecretFields'
 import { useDialogOpen } from '@/composables/useDialogOpen'
 import { serverDetailPath } from '@/utils/serverRoute'
 
@@ -217,6 +217,11 @@ async function confirmAdd() {
   if (!pendingResult.value) return
   confirming.value = true
   addError.value = null
+  // Tracked outside the try so the catch block (a keyring-write failure
+  // inside resolveSecretFields) doesn't attempt a second rollback of refs
+  // that resolveSecretFields already rolled back itself; it's only
+  // populated once resolveSecretFields has returned successfully.
+  let writtenRefs: string[] = []
   try {
     const result = pendingResult.value
     const fields = (result.required_inputs || []).map((i) => ({
@@ -226,8 +231,17 @@ async function confirmAdd() {
       mode: pendingModes[i.name] || 'value',
     }))
     const resolved = await resolveSecretFields(result.title || result.id, fields)
-    await addResult(result, `${result.source}-${result.id}`, resolved.env)
-    closeSecretsDialog()
+    writtenRefs = resolved.writtenRefs
+    const added = await addResult(result, `${result.source}-${result.id}`, resolved.env)
+    if (added) {
+      closeSecretsDialog()
+    } else if (writtenRefs.length > 0) {
+      // The secret write succeeded but the add-server call failed (e.g. a
+      // duplicate name) — the secret this attempt just wrote must not be
+      // orphaned in the keyring, and a retry must be able to reuse its ref
+      // name rather than computing a new -2-suffixed one.
+      await rollbackSecrets(writtenRefs)
+    }
   } catch (e) {
     addError.value = e instanceof Error ? e.message : 'Failed to add server'
   } finally {
@@ -235,16 +249,22 @@ async function confirmAdd() {
   }
 }
 
-async function addResult(result: CatalogResult, key: string, env: Record<string, string>) {
+// addResult returns whether the add succeeded. api.ts's request() always
+// resolves {success:false} rather than throwing, so addResult reports
+// failure via its own return value (and addError) instead of throwing —
+// callers MUST check the return value rather than assuming a resolved
+// promise means success.
+async function addResult(result: CatalogResult, key: string, env: Record<string, string>): Promise<boolean> {
   addingKey.value = key
   try {
     const res = await api.addServerFromRegistry(result.source, result.id, { env })
     if (res.success && res.server?.name) {
       addedNames[key] = res.server.name
       emit('added', res.server.name)
-    } else {
-      addError.value = res.error || 'Failed to add server'
+      return true
     }
+    addError.value = res.error || 'Failed to add server'
+    return false
   } finally {
     addingKey.value = null
   }
diff --git a/frontend/src/components/ManualServerForm.vue b/frontend/src/components/ManualServerForm.vue
index 69c67725f..1c1becc37 100644
--- a/frontend/src/components/ManualServerForm.vue
+++ b/frontend/src/components/ManualServerForm.vue
@@ -92,7 +92,7 @@ import { ref, reactive, onMounted } from 'vue'
 import { useRouter } from 'vue-router'
 import api from '@/services/api'
 import SecretToggle from '@/components/SecretToggle.vue'
-import { resolveSecretFields } from '@/composables/useSecretFields'
+import { resolveSecretFields, rollbackSecrets } from '@/composables/useSecretFields'
 import { useServersStore } from '@/stores/servers'
 import { serverDetailPath } from '@/utils/serverRoute'
 
@@ -128,12 +128,17 @@ function parseArgs(): string[] {
 async function handleSubmit() {
   error.value = null
   submitting.value = true
+  // Populated only once resolveSecretFields has returned successfully, so
+  // the catch block below never double-rolls-back refs that
+  // resolveSecretFields already rolled back itself on a write failure.
+  let writtenRefs: string[] = []
   try {
     const fields = [
       ...envRows.filter((r) => r.name.trim()).map((r) => ({ kind: 'env' as const, name: r.name.trim(), value: r.value, mode: r.mode })),
       ...headerRows.filter((r) => r.name.trim()).map((r) => ({ kind: 'header' as const, name: r.name.trim(), value: r.value, mode: r.mode })),
     ]
     const resolved = await resolveSecretFields(name.value, fields)
+    writtenRefs = resolved.writtenRefs
 
     const serverData: Record<string, unknown> = {
       operation: 'add',
@@ -155,6 +160,10 @@ async function handleSubmit() {
     emit('added', name.value)
     void router.push(serverDetailPath(name.value))
   } catch (e) {
+    // The secret write (if any) succeeded but something after it failed —
+    // don't leave an orphaned keyring entry behind, and let a retry reuse
+    // the same ref name instead of computing a new -2-suffixed one.
+    if (writtenRefs.length > 0) await rollbackSecrets(writtenRefs)
     error.value = e instanceof Error ? e.message : 'Failed to add server'
   } finally {
     submitting.value = false
diff --git a/frontend/src/components/PasteServer.vue b/frontend/src/components/PasteServer.vue
index 7af1253af..fcb607605 100644
--- a/frontend/src/components/PasteServer.vue
+++ b/frontend/src/components/PasteServer.vue
@@ -67,7 +67,7 @@ import { useRouter } from 'vue-router'
 import api from '@/services/api'
 import type { ImportedServer } from '@/types'
 import SecretToggle from '@/components/SecretToggle.vue'
-import { resolveSecretFields } from '@/composables/useSecretFields'
+import { resolveSecretFields, rollbackSecrets } from '@/composables/useSecretFields'
 import { useServersStore } from '@/stores/servers'
 import { serverDetailPath } from '@/utils/serverRoute'
 
@@ -151,6 +151,10 @@ async function handleAdd() {
   if (!preview.value) return
   adding.value = true
   addError.value = null
+  // Populated only once resolveSecretFields has returned successfully, so
+  // the catch block below never double-rolls-back refs that
+  // resolveSecretFields already rolled back itself on a write failure.
+  let writtenRefs: string[] = []
   try {
     const p = preview.value
     const fields = [
@@ -158,6 +162,7 @@ async function handleAdd() {
       ...(p.headers || []).map((f) => ({ kind: 'header' as const, name: f.name, value: values[`header:${f.name}`] || '', mode: modes[`header:${f.name}`] || 'value' })),
     ]
     const resolved = await resolveSecretFields(p.name, fields)
+    writtenRefs = resolved.writtenRefs
 
     const serverData: Record<string, unknown> = {
       operation: 'add',
@@ -178,6 +183,10 @@ async function handleAdd() {
     emit('added', p.name)
     void router.push(serverDetailPath(p.name))
   } catch (e) {
+    // The secret write (if any) succeeded but something after it failed —
+    // don't leave an orphaned keyring entry behind, and let a retry reuse
+    // the same ref name instead of computing a new -2-suffixed one.
+    if (writtenRefs.length > 0) await rollbackSecrets(writtenRefs)
     addError.value = e instanceof Error ? e.message : 'Failed to add server'
   } finally {
     adding.value = false
diff --git a/frontend/tests/unit/add-server-catalog.spec.ts b/frontend/tests/unit/add-server-catalog.spec.ts
index ef73207a1..fb773a504 100644
--- a/frontend/tests/unit/add-server-catalog.spec.ts
+++ b/frontend/tests/unit/add-server-catalog.spec.ts
@@ -10,6 +10,7 @@ vi.mock('@/services/api', () => ({
     addServerFromRegistry: vi.fn(),
     getSecretRefs: vi.fn(),
     setSecret: vi.fn(),
+    deleteSecret: vi.fn(),
   },
 }))
 import api from '@/services/api'
@@ -110,4 +111,51 @@ describe('CatalogSearch', () => {
     await flushPromises()
     expect(wrapper.find('[data-test="catalog-unavailable-notice"]').text()).toContain('smithery')
   })
+
+  // Review round 1: confirmAdd() unconditionally closed the secrets dialog
+  // after addResult(), even when the POST /registries/.../add call failed —
+  // addResult() never throws (api.ts always resolves {success:false}), so
+  // the failure fell straight through to closeSecretsDialog(), which wiped
+  // the error it had just set one line earlier and silently orphaned the
+  // keyring entry the dialog had just written.
+  it('keeps the secrets dialog open, shows the error, and rolls back the just-written secret when the add fails after a successful secret write', async () => {
+    vi.mocked(api.catalogSearch).mockResolvedValue({
+      success: true,
+      data: {
+        query: '',
+        results: [],
+        sections: {
+          official: [githubResult({ required_inputs: [{ name: 'GITHUB_TOKEN', secret_like: true }] })],
+          popular: [],
+        },
+        unavailable: [],
+      },
+    })
+    vi.mocked(api.getSecretRefs).mockResolvedValue({ success: true, data: { refs: [] } })
+    vi.mocked(api.setSecret).mockResolvedValue({ success: true, data: { name: 'github-env-github-token', type: 'keyring' } })
+    vi.mocked(api.deleteSecret).mockResolvedValue({ success: true, data: { name: 'github-env-github-token', type: 'keyring' } })
+    vi.mocked(api.addServerFromRegistry).mockResolvedValue({ success: false, error: 'a server named "github" already exists' })
+
+    const wrapper = await mountCatalog()
+    await wrapper.find('[data-test="catalog-add-official-io.github.github/github-mcp-server"]').trigger('click')
+    await flushPromises()
+
+    const dialog = wrapper.find('[data-test="catalog-secrets-dialog"]')
+    expect(dialog.exists()).toBe(true)
+
+    await wrapper.find('[data-test="secret-toggle-value-input"]').setValue('ghp_xxx')
+    await wrapper.find('[data-test="catalog-secrets-confirm"]').trigger('click')
+    await flushPromises()
+
+    // The write happened (Secret mode is the default for a secret_like input).
+    expect(api.setSecret).toHaveBeenCalledWith('github-env-github-token', 'ghp_xxx')
+
+    // The dialog must stay open with the error visible, not silently close.
+    expect(wrapper.find('[data-test="catalog-secrets-dialog"]').attributes('open')).toBeDefined()
+    expect(wrapper.find('[data-test="catalog-add-error"]').text()).toContain('already exists')
+
+    // The secret this failed attempt wrote must be rolled back so a retry
+    // doesn't orphan a keyring entry or get a -2-suffixed name.
+    expect(api.deleteSecret).toHaveBeenCalledWith('github-env-github-token')
+  })
 })
diff --git a/frontend/tests/unit/add-server-manual.spec.ts b/frontend/tests/unit/add-server-manual.spec.ts
new file mode 100644
index 000000000..e03c75524
--- /dev/null
+++ b/frontend/tests/unit/add-server-manual.spec.ts
@@ -0,0 +1,73 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
+import { createRouter, createWebHistory } from 'vue-router'
+import ManualServerForm from '@/components/ManualServerForm.vue'
+
+vi.mock('@/services/api', () => ({
+  default: {
+    getConfigSecrets: vi.fn(),
+    getSecretRefs: vi.fn(),
+    setSecret: vi.fn(),
+    deleteSecret: vi.fn(),
+    callTool: vi.fn(),
+  },
+}))
+import api from '@/services/api'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    { path: '/', component: { template: '<div/>' } },
+    { path: '/servers/:serverName', component: { template: '<div/>' } },
+  ],
+})
+
+async function mountManual() {
+  setActivePinia(createPinia())
+  vi.mocked(api.getConfigSecrets).mockResolvedValue({
+    success: true,
+    data: { secrets: [], environment_vars: [], total_secrets: 0, total_env_vars: 0, keyring_available: true },
+  })
+  const wrapper = mount(ManualServerForm, { global: { plugins: [router] } })
+  await flushPromises()
+  return wrapper
+}
+
+describe('ManualServerForm', () => {
+  beforeEach(() => {
+    vi.mocked(api.getConfigSecrets).mockReset()
+    vi.mocked(api.getSecretRefs).mockReset()
+    vi.mocked(api.setSecret).mockReset()
+    vi.mocked(api.deleteSecret).mockReset()
+    vi.mocked(api.callTool).mockReset()
+  })
+
+  // Review round 1: resolveSecretFields's returned writtenRefs were computed
+  // but never passed to rollbackSecrets by this surface, so a secret write
+  // that succeeded right before the add-server call itself failed (e.g. a
+  // duplicate name) left an orphaned keyring entry behind.
+  it('rolls back the just-written secret when the add-server call fails after a successful secret write', async () => {
+    vi.mocked(api.getSecretRefs).mockResolvedValue({ success: true, data: { refs: [] } })
+    vi.mocked(api.setSecret).mockResolvedValue({ success: true, data: { message: '', name: '', type: '', reference: '' } })
+    vi.mocked(api.deleteSecret).mockResolvedValue({ success: true, data: { message: '' } })
+    vi.mocked(api.callTool).mockResolvedValue({ success: false, error: 'a server named "github" already exists' })
+
+    const wrapper = await mountManual()
+
+    await wrapper.find('[data-test="manual-name-input"]').setValue('github')
+    await wrapper.find('[data-test="manual-type-stdio"]').setValue(true)
+    await wrapper.find('[data-test="manual-command-input"]').setValue('uvx')
+    await wrapper.find('[data-test="manual-env-add"]').trigger('click')
+    await wrapper.find('[data-test="manual-env-name-0"]').setValue('GITHUB_TOKEN')
+    await wrapper.find('[data-test="secret-toggle-mode-secret"]').trigger('click')
+    await wrapper.find('[data-test="secret-toggle-value-input"]').setValue('sk-live-abc123')
+
+    await wrapper.find('[data-test="manual-server-form"]').trigger('submit')
+    await flushPromises()
+
+    expect(api.setSecret).toHaveBeenCalledWith('github-env-github-token', 'sk-live-abc123')
+    expect(wrapper.find('[data-test="manual-error"]').text()).toContain('already exists')
+    expect(api.deleteSecret).toHaveBeenCalledWith('github-env-github-token')
+  })
+})
diff --git a/frontend/tests/unit/add-server-paste.spec.ts b/frontend/tests/unit/add-server-paste.spec.ts
index 94395437c..d39a454da 100644
--- a/frontend/tests/unit/add-server-paste.spec.ts
+++ b/frontend/tests/unit/add-server-paste.spec.ts
@@ -10,6 +10,7 @@ vi.mock('@/services/api', () => ({
     getConfigSecrets: vi.fn(),
     getSecretRefs: vi.fn(),
     setSecret: vi.fn(),
+    deleteSecret: vi.fn(),
     callTool: vi.fn(),
   },
 }))
@@ -131,4 +132,45 @@ describe('PasteServer', () => {
       expect.objectContaining({ env_json: JSON.stringify({ GITHUB_TOKEN: '${keyring:github-env-github-token}' }) })
     )
   })
+
+  // Review round 1: resolveSecretFields's returned writtenRefs were computed
+  // but never passed to rollbackSecrets by this surface, so a secret write
+  // that succeeded right before the add-server call itself failed (e.g. a
+  // duplicate name) left an orphaned keyring entry behind.
+  it('rolls back the just-written secret when the add-server call fails after a successful secret write', async () => {
+    vi.mocked(api.importServersFromJSON).mockResolvedValue({
+      success: true,
+      data: {
+        format: 'command',
+        format_name: 'Command Line',
+        summary: { total: 1, imported: 1, skipped: 0, failed: 0 },
+        imported: [{
+          name: 'github', protocol: 'stdio', command: 'uvx', args: ['mcp-server-github'],
+          source_format: 'command', original_name: 'github',
+          summary: 'uvx mcp-server-github', tags: ['local process', 'needs secret'],
+          env: [{ name: 'GITHUB_TOKEN', value_present: true, secret_like: true, empty_or_placeholder: false }],
+        }],
+        skipped: [],
+        failed: [],
+        warnings: [],
+      },
+    })
+    vi.mocked(api.getSecretRefs).mockResolvedValue({ success: true, data: { refs: [] } })
+    vi.mocked(api.setSecret).mockResolvedValue({ success: true, data: { message: '', name: '', type: '', reference: '' } })
+    vi.mocked(api.deleteSecret).mockResolvedValue({ success: true, data: { message: '' } })
+    vi.mocked(api.callTool).mockResolvedValue({ success: false, error: 'a server named "github" already exists' })
+
+    const wrapper = await mountPaste()
+    await wrapper.find('[data-test="paste-textarea"]').setValue('uvx mcp-server-github')
+    await new Promise((r) => setTimeout(r, 450))
+    await flushPromises()
+
+    await wrapper.find('[data-test="secret-toggle-value-input"]').setValue('sk-live-abc123')
+    await wrapper.find('[data-test="paste-add-button"]').trigger('click')
+    await flushPromises()
+
+    expect(api.setSecret).toHaveBeenCalledWith('github-env-github-token', 'sk-live-abc123')
+    expect(wrapper.find('[data-test="paste-add-error"]').text()).toContain('already exists')
+    expect(api.deleteSecret).toHaveBeenCalledWith('github-env-github-token')
+  })
 })
diff --git a/internal/httpapi/catalog.go b/internal/httpapi/catalog.go
index b065834f8..e843aa918 100644
--- a/internal/httpapi/catalog.go
+++ b/internal/httpapi/catalog.go
@@ -50,16 +50,11 @@ func (s *Server) handleCatalogSearch(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	hits, sections, unavailable := registries.SearchAll(r.Context(), q, tag, limit, registries.SearchOptions{})
-	if source != "" {
-		hits = filterCatalogHitsBySource(hits, source)
-		if sections != nil {
-			sections = &registries.CatalogSections{
-				Official: filterCatalogHitsBySource(sections.Official, source),
-				Popular:  filterCatalogHitsBySource(sections.Popular, source),
-			}
-		}
-	}
+	// Source is applied inside SearchAll, BEFORE ranking/truncation to
+	// limit — filtering after truncation could silently drop a narrower
+	// source's real matches that simply lost out to an official/verified
+	// source for one of the truncated top-`limit` slots.
+	hits, sections, unavailable := registries.SearchAll(r.Context(), q, tag, limit, registries.SearchOptions{Source: source})
 
 	added := s.catalogAddedPredicate(r.Context())
 
@@ -72,6 +67,11 @@ func (s *Server) handleCatalogSearch(w http.ResponseWriter, r *http.Request) {
 		resp.Unavailable = []registries.SourceError{}
 	}
 	if sections != nil {
+		// contracts/rest-api.md#catalog: "Empty q → results: [],
+		// sections: {...}" — an empty q always yields sections (see
+		// registries.SearchAll), so results must be emptied here rather
+		// than carrying the same ranked list sections is already showing.
+		resp.Results = []registries.CatalogResult{}
 		resp.Sections = &catalogSections{
 			Official: toCatalogResults(sections.Official, added),
 			Popular:  toCatalogResults(sections.Popular, added),
@@ -81,16 +81,6 @@ func (s *Server) handleCatalogSearch(w http.ResponseWriter, r *http.Request) {
 	s.writeSuccess(w, resp)
 }
 
-func filterCatalogHitsBySource(hits []registries.CatalogHit, source string) []registries.CatalogHit {
-	out := make([]registries.CatalogHit, 0, len(hits))
-	for _, h := range hits {
-		if h.Source == source {
-			out = append(out, h)
-		}
-	}
-	return out
-}
-
 func toCatalogResults(hits []registries.CatalogHit, added func(registries.CatalogHit) bool) []registries.CatalogResult {
 	out := make([]registries.CatalogResult, 0, len(hits))
 	for _, h := range hits {
diff --git a/internal/httpapi/catalog_test.go b/internal/httpapi/catalog_test.go
index 1410ef2ef..0df15e2cb 100644
--- a/internal/httpapi/catalog_test.go
+++ b/internal/httpapi/catalog_test.go
@@ -197,3 +197,74 @@ func TestCatalogSearch_AddedScopedForNonAdminUserContext(t *testing.T) {
 	assert.True(t, catalogAddedFor(results, "gamma-tool"), "user session scoped to gamma: expected gamma-tool added=true")
 	assert.False(t, catalogAddedFor(results, "delta-tool"), "user session scoped to gamma: expected delta-tool added=false (out of scope)")
 }
+
+// TestCatalogSearch_EmptyQueryReturnsEmptyResults pins contracts/rest-api.md#catalog:
+// "Empty q → results: [], sections: {...}". Before this fix, Results was set
+// unconditionally to the ranked hit list even when Sections was populated.
+func TestCatalogSearch_EmptyQueryReturnsEmptyResults(t *testing.T) {
+	withCatalogFixtureRegistry(t)
+	ctrl := &scopeController{cfg: scopeFixtureConfig(false), servers: catalogFixtureServers(), withManagement: true}
+	srv, _ := scopedAgentServer(t, ctrl, []string{"gamma"})
+
+	rec := scopeGet(t, srv, "/api/v1/catalog/search", scopeAdminAPIKey)
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	data := scopeDecodeData(t, rec)
+
+	results, ok := data["results"].([]interface{})
+	require.True(t, ok, "expected results to be an array, got %#v", data["results"])
+	assert.Empty(t, results, "contracts/rest-api.md#catalog: empty q must return results: []")
+
+	sections, ok := data["sections"].(map[string]interface{})
+	require.True(t, ok, "expected sections to be populated for an empty q")
+	popular, ok := sections["popular"].([]interface{})
+	require.True(t, ok)
+	assert.NotEmpty(t, popular, "expected the fixture's entries in sections.popular")
+}
+
+// TestCatalogSearch_SourceFilterAppliesBeforeTruncation is the regression for
+// a bug where `source=` was applied AFTER registries.SearchAll had already
+// truncated the ranked, merged list to `limit`: an official source ranks
+// ahead of everything else, so with limit=1 it fills the only truncated
+// slot, and a `source=other&limit=1` query would silently come back empty
+// even though "other" has a real matching entry (just ranked below the
+// truncation point pre-filter).
+func TestCatalogSearch_SourceFilterAppliesBeforeTruncation(t *testing.T) {
+	officialBody := `[{"id":"official-tool","name":"Official Tool"}]`
+	officialSrc := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(officialBody))
+	}))
+	t.Cleanup(officialSrc.Close)
+
+	otherBody := `[{"id":"other-tool","name":"Other Tool"}]`
+	otherSrc := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(otherBody))
+	}))
+	t.Cleanup(otherSrc.Close)
+
+	t.Cleanup(registries.AllowPrivateRegistryFetchForTest())
+	t.Cleanup(registries.SetRegistriesForTest([]registries.RegistryEntry{
+		{ID: "official", Name: "Official", ServersURL: officialSrc.URL, Provenance: "official"},
+		{ID: "other", Name: "Other", ServersURL: otherSrc.URL},
+	}))
+
+	ctrl := &scopeController{cfg: scopeFixtureConfig(false), servers: nil, withManagement: true}
+	srv := NewServer(ctrl, zap.NewNop().Sugar(), nil)
+
+	// Sanity check: with no source filter and limit=1, the official (ranked
+	// first) entry fills the only slot — "other-tool" is truncated away.
+	rec := scopeGet(t, srv, "/api/v1/catalog/search?q=tool&limit=1", scopeAdminAPIKey)
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	unfiltered := catalogDecodeResults(t, rec)
+	require.Len(t, unfiltered, 1)
+	assert.Equal(t, "official-tool", unfiltered[0]["id"])
+
+	// Narrowing to source=other must still find other-tool, not come back
+	// empty just because it didn't survive the pre-filter truncation.
+	rec = scopeGet(t, srv, "/api/v1/catalog/search?q=tool&source=other&limit=1", scopeAdminAPIKey)
+	require.Equal(t, http.StatusOK, rec.Code, rec.Body.String())
+	filtered := catalogDecodeResults(t, rec)
+	require.Len(t, filtered, 1, "expected other-tool to survive source filtering despite limit=1")
+	assert.Equal(t, "other-tool", filtered[0]["id"])
+}
diff --git a/internal/registries/catalog.go b/internal/registries/catalog.go
index 382178c8b..a5974f1be 100644
--- a/internal/registries/catalog.go
+++ b/internal/registries/catalog.go
@@ -97,6 +97,14 @@ type SourceError struct {
 // only tests set another value (T109a, SC-011).
 type SearchOptions struct {
 	SourceTimeout time.Duration
+
+	// Source narrows results to one catalog source id (GET
+	// /catalog/search?source=). Applied BEFORE ranking/truncation to
+	// `limit`, not after: an official/verified source's hits sort first by
+	// design, so a post-hoc filter on an already-truncated top-`limit` list
+	// could silently drop a narrower source's real matches that simply
+	// didn't survive the pre-filter truncation.
+	Source string
 }
 
 const (
@@ -178,6 +186,10 @@ func SearchAll(ctx context.Context, q, tag string, limit int, opts SearchOptions
 		}
 	}
 
+	if opts.Source != "" {
+		all = filterHitsBySource(all, opts.Source)
+	}
+
 	sort.SliceStable(all, func(i, j int) bool { return Rank(all[i], all[j], q) })
 	sort.SliceStable(unavailable, func(i, j int) bool { return unavailable[i].Source < unavailable[j].Source })
 
@@ -193,6 +205,18 @@ func SearchAll(ctx context.Context, q, tag string, limit int, opts SearchOptions
 	return all, sections, unavailable
 }
 
+// filterHitsBySource keeps only the hits from one catalog source, applied
+// before ranking/truncation (see SearchOptions.Source).
+func filterHitsBySource(hits []CatalogHit, source string) []CatalogHit {
+	out := make([]CatalogHit, 0, len(hits))
+	for _, h := range hits {
+		if h.Source == source {
+			out = append(out, h)
+		}
+	}
+	return out
+}
+
 // BuildCatalogHit derives the catalog-only fields (Title, Publisher,
 // Verified, Official, Popularity) from a registry entry. Verified currently
 // tracks Official — no registry in this spec supplies an independent
diff --git a/internal/secret/keyring_available_test.go b/internal/secret/keyring_available_test.go
index 0b19b477f..918e336ef 100644
--- a/internal/secret/keyring_available_test.go
+++ b/internal/secret/keyring_available_test.go
@@ -1,7 +1,9 @@
 package secret
 
 import (
+	"context"
 	"errors"
+	"runtime"
 	"testing"
 
 	"github.com/zalando/go-keyring"
@@ -18,6 +20,9 @@ func TestKeyringProvider_IsAvailableWithReason_Available(t *testing.T) {
 		nil, nil,
 	)
 	p := NewKeyringProvider()
+	// This test is about the probe outcome, not the macOS write opt-in
+	// (covered separately below), so force writes enabled.
+	p.SetWritesEnabled(true)
 	ok, reason := p.IsAvailableWithReason()
 	if !ok {
 		t.Fatal("expected available")
@@ -27,6 +32,69 @@ func TestKeyringProvider_IsAvailableWithReason_Available(t *testing.T) {
 	}
 }
 
+// TestKeyringProvider_IsAvailableWithReason_MacWriteGateNotOptedIn pins that
+// on macOS, without the MCPPROXY_KEYRING_WRITE opt-in (or a tray-launched
+// core setting it), IsAvailableWithReason reports UNAVAILABLE even when the
+// read-only probe would succeed. This is a write-availability signal (it
+// backs GET /secrets/config's keyring_available, and the CLI's pre-check in
+// applySecretFlags before --secret-env/--secret-header), so it must agree
+// with what Store() will actually do: Store() unconditionally refuses with
+// ErrKeyringUnavailable on macOS when writesEnabled() is false, regardless
+// of probe health. Before this fix, IsAvailableWithReason ran only the
+// read-only probe and ignored the write gate entirely, so it reported
+// "available" right before the next Store() call failed.
+func TestKeyringProvider_IsAvailableWithReason_MacWriteGateNotOptedIn(t *testing.T) {
+	if runtime.GOOS != "darwin" {
+		t.Skip("macOS-only write gate")
+	}
+	clearHeadlessEnv(t)
+	t.Setenv("MCPPROXY_KEYRING_WRITE", "")
+	withKeyringMocks(t,
+		func(service, user string) (string, error) { return "", keyring.ErrNotFound },
+		nil, nil,
+	)
+	p := NewKeyringProvider()
+	p.SetWritesEnabled(false) // explicit: no opt-in, as a headless `mcpproxy serve` would see
+
+	ok, reason := p.IsAvailableWithReason()
+	if ok {
+		t.Fatal("expected unavailable when macOS keyring writes are not opted in, even though the read probe would succeed")
+	}
+	if reason == "" {
+		t.Error("expected a non-empty reason explaining the write opt-in is missing")
+	}
+
+	// The write-availability signal must match what Store() actually does.
+	err := p.Store(context.TODO(), Ref{Type: SecretTypeKeyring, Name: "gate_check"}, "value")
+	if !errors.Is(err, ErrKeyringUnavailable) {
+		t.Fatalf("expected Store() to also refuse with ErrKeyringUnavailable, got %v", err)
+	}
+}
+
+// TestKeyringProvider_IsAvailableWithReason_MacWriteGateOptedIn pins that
+// opting in via SetWritesEnabled(true) (what MCPPROXY_KEYRING_WRITE=1 does
+// via writesEnabled()) restores the plain probe-based result on macOS.
+func TestKeyringProvider_IsAvailableWithReason_MacWriteGateOptedIn(t *testing.T) {
+	if runtime.GOOS != "darwin" {
+		t.Skip("macOS-only write gate")
+	}
+	clearHeadlessEnv(t)
+	withKeyringMocks(t,
+		func(service, user string) (string, error) { return "", keyring.ErrNotFound },
+		nil, nil,
+	)
+	p := NewKeyringProvider()
+	p.SetWritesEnabled(true)
+
+	ok, reason := p.IsAvailableWithReason()
+	if !ok {
+		t.Fatal("expected available once macOS keyring writes are opted in")
+	}
+	if reason != "" {
+		t.Errorf("expected empty reason when available, got %q", reason)
+	}
+}
+
 // TestKeyringProvider_IsAvailableWithReason_CI pins the headless CI reason so
 // the disabled secret toggle can explain itself instead of going silently
 // dark.
diff --git a/internal/secret/keyring_provider.go b/internal/secret/keyring_provider.go
index 48888f2f4..c0c74186c 100644
--- a/internal/secret/keyring_provider.go
+++ b/internal/secret/keyring_provider.go
@@ -406,11 +406,25 @@ func (p *KeyringProvider) IsAvailable() bool {
 // IsAvailableWithReason behaves like IsAvailable but also returns a short,
 // user-facing reason when unavailable ("" when available). Used by
 // GET /secrets/config (FR-065) so the Web/macOS/CLI secret toggle can explain
-// why it is disabled instead of just going dark.
+// why it is disabled instead of just going dark, and by the CLI's
+// applySecretFlags pre-check before --secret-env/--secret-header.
+//
+// Both of those callers care about WRITE availability, not just whether a
+// read-only probe succeeds: Store() has its own hard gate on macOS (it
+// refuses unconditionally unless the caller opted in via
+// MCPPROXY_KEYRING_WRITE / SetWritesEnabled — see writesEnabled()), because
+// keyring.Set can pop a destructive system modal there. A plain probe-based
+// answer would tell a headless `mcpproxy serve` or the CLI's own in-process
+// resolver "available", and the very next Store() call would then fail with
+// ErrKeyringUnavailable. So this checks the macOS write gate first and only
+// falls through to the read-only probe once writes are actually permitted.
 func (p *KeyringProvider) IsAvailableWithReason() (bool, string) {
 	if isHeadlessEnvironment() {
 		return false, headlessUnavailableReason()
 	}
+	if runtime.GOOS == "darwin" && !p.writesEnabled() {
+		return false, "OS keychain writes require opting in on macOS outside the tray app (set MCPPROXY_KEYRING_WRITE=1, or use the tray, which opts in automatically)"
+	}
 	if p.IsAvailable() {
 		return true, ""
 	}
diff --git a/internal/server/mcp.go b/internal/server/mcp.go
index 8bf8bffd4..3ccaf063e 100644
--- a/internal/server/mcp.go
+++ b/internal/server/mcp.go
@@ -1667,20 +1667,46 @@ func (p *MCPProxyServer) handleSearchServers(ctx context.Context, request mcp.Ca
 	return mcp.NewToolResultText(string(jsonResult)), nil
 }
 
+// mcpCatalogServerEntry is the search_servers (registry omitted) per-item
+// shape (contracts/mcp-tools.md): the embedded ServerEntry keeps the exact
+// JSON shape (url, installCmd, registry, required_inputs[].secret) a
+// single-registry search already returns — encoding/json promotes an
+// anonymous embedded struct's fields to the top level — and the catalog
+// fields below are ADDED alongside it, in FR-060 order, mirroring
+// registries.CatalogResult minus the REST-only "added" field (MCP callers
+// don't carry the same per-caller visibility scope).
+type mcpCatalogServerEntry struct {
+	registries.ServerEntry
+	Title      string                 `json:"title"`
+	Publisher  string                 `json:"publisher,omitempty"`
+	Verified   bool                   `json:"verified"`
+	Official   bool                   `json:"official"`
+	Popularity *registries.Popularity `json:"popularity,omitempty"`
+	Source     string                 `json:"source"`
+}
+
 // handleSearchServersAllSources implements search_servers with 'registry'
 // omitted (Spec 109 FR-060/067): fans out across every enabled catalog
-// source via registries.SearchAll and returns the merged, ranked
-// ServerEntry list — the SAME JSON shape (url, installCmd, registry,
-// required_inputs[].secret) a single-registry search already returns, in
+// source via registries.SearchAll and returns the merged, ranked list in
 // FR-060 rank order, with no "added" field (contracts/rest-api.md#catalog:
 // that field is REST-only, since it depends on caller scope MCP callers
-// don't carry the same way).
+// don't carry the same way). Each item gains title/publisher/verified/
+// official/popularity/source (contracts/mcp-tools.md) so an MCP caller gets
+// the same catalog-ranking evidence a REST/CLI caller already does.
 func (p *MCPProxyServer) handleSearchServersAllSources(ctx context.Context, sessionID, requestID string, startTime time.Time, args map[string]interface{}, search, tag string, limit int) (*mcp.CallToolResult, error) {
 	hits, _, unavailable := registries.SearchAll(ctx, search, tag, limit, registries.SearchOptions{})
 
-	servers := make([]registries.ServerEntry, 0, len(hits))
+	servers := make([]mcpCatalogServerEntry, 0, len(hits))
 	for _, h := range hits {
-		servers = append(servers, h.Entry)
+		servers = append(servers, mcpCatalogServerEntry{
+			ServerEntry: h.Entry,
+			Title:       h.Title,
+			Publisher:   h.Publisher,
+			Verified:    h.Verified,
+			Official:    h.Official,
+			Popularity:  h.Popularity,
+			Source:      h.Source,
+		})
 	}
 
 	response := map[string]interface{}{
diff --git a/internal/server/search_servers_all_sources_test.go b/internal/server/search_servers_all_sources_test.go
index 39f27b6d6..710004d03 100644
--- a/internal/server/search_servers_all_sources_test.go
+++ b/internal/server/search_servers_all_sources_test.go
@@ -63,6 +63,16 @@ func TestSearchServers_RegistryOptional_SearchesAllSources(t *testing.T) {
 	if _, hasRegistryArg := payload["registry"]; hasRegistryArg {
 		t.Errorf("expected no 'registry' field echoed back when omitted, got %#v", payload["registry"])
 	}
+
+	// contracts/mcp-tools.md: omitting 'registry' must gain the same
+	// catalog-ranking evidence REST/CLI callers already get — title,
+	// publisher, verified, official, popularity, source — not just the bare
+	// registries.ServerEntry.
+	assert.Equal(t, "Alpha Tool", entry["title"], "expected the catalog title field")
+	assert.Equal(t, "fast", entry["source"], "expected the catalog source field")
+	assert.Contains(t, entry, "verified", "expected the catalog verified field")
+	assert.Contains(t, entry, "official", "expected the catalog official field")
+	assert.Contains(t, entry, "publisher", "expected the catalog publisher field")
 }
 
 // TestSearchServers_RegistryOptional_UnavailableSourceReported pins that a

From b1ddae5397cbd8f136ad1cc8423be3d5ca14a224 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 03:50:29 +0300
Subject: [PATCH 21/27] fix: address review round 3 findings on
 catalog/add-server (Spec 109 T109/T103)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

High
- macOS(AddServerView): the tray shipped the catalog data layer (CatalogModels,
  SecretLikeName, SecretRefName) but never wired it into any UI — AddServerView
  only had Import/Manual tabs, so a macOS user had no way to reach the new
  catalog search/add-server flow the Web UI, CLI (`catalog search|show|add`)
  and MCP (`search_servers`) all gained in this PR. Added CatalogView.swift
  (aggregated GET /api/v1/catalog/search across every enabled source, Official/
  Popular sections, "Add to MCPProxy" -> "Added checkmark Open") and
  PasteServerView.swift (paste a URL/command/config, preview-detect via
  POST /api/v1/servers/import/json?preview=true, fill in detected fields) as
  new Catalog/Paste tabs on AddServerView, ordered Catalog - Paste - Import -
  Manual to match the Web UI's views/AddServer.vue (T103/T109). The generic
  "Add Server" entry points (toolbar +, prominent button, empty-state button,
  dashboard shortcut) now open on Catalog by default instead of Import/Manual.
- macOS(MainWindow): removed the Registries sidebar item per T109 — it's fully
  superseded by the new Catalog tab for discovery. Registry SOURCE management
  (add/edit/remove a registry) moved to a new Settings -> Catalog Sources tab
  (CatalogSourcesTab, replacing the old RegistriesView's "Manage registries"
  half); the old per-registry ServerBrowseView "Discover servers" half is
  removed outright, superseded by the aggregated catalog search. Updated
  docs/registries.md's Web UI/macOS surface bullets to match (they described
  the pre-109-j Repositories page and Registries sidebar tab).

Both required a small backend-facing addition: a Swift port of the Web UI's
resolveSecretFields (SecretFieldResolver.swift, kind-aware so an env var and a
header of the same name never collide on one keyring ref, FR-065) plus the
APIClient calls it needs (getSecretRefs, deleteSecret, previewImportContent)
and the decode models (SecretRefEntry, ImportPreviewServer/Field). Pure
assembly/field-building logic (buildValues, buildFields, makeServerConfig) is
unit-tested without a network call, mirroring ManualServerForm's existing
pure-seam pattern; addServerFromRegistry/searchCatalog were already present
from the T104/T108 rounds and needed no changes.

Not reviewed
- zcode (the mandated reviewer) was unavailable for this entire round —
  account-wide 5-hour usage-quota exhaustion (ProviderBusinessError 1308),
  same block reported in round 2, not expected to clear inside this task's
  window. Per this task's standing instructions codex is off-limits for 2
  days and only zcode was mandated, so no reviewer ran; this fix is unreviewed
  by an external model. Flagging rather than silently proceeding as if
  reviewed.

Verification: swift build (clean) + swift test (1203/1203 passing, excluding
one pre-existing environment-dependent failure — AppLifecycleTests'
real-instance-root check fails identically on the unmodified base commit, a
leftover ~/.mcpproxy/tray-lifecycle.jsonl on this machine, unrelated to this
diff); go build ./... (clean, no Go files touched); golangci-lint v2 (pre-
existing unrelated staticcheck/govet issues only, same as base). No frontend
files touched.
---
 docs/registries.md                            |  14 +-
 .../MCPProxy/MCPProxy/API/APIClient.swift     |  46 ++
 .../MCPProxy/MCPProxy/API/CatalogModels.swift |  73 ++++
 .../MCPProxy/Models/SecretFieldResolver.swift | 119 +++++
 .../MCPProxy/Views/AddServerView.swift        |  15 +-
 .../MCPProxy/MCPProxy/Views/CatalogView.swift | 346 +++++++++++++++
 .../MCPProxy/MCPProxy/Views/MainWindow.swift  |   9 +-
 .../MCPProxy/Views/PasteServerView.swift      | 231 ++++++++++
 .../MCPProxy/Views/RegistriesView.swift       | 109 ++---
 .../Views/SecretFieldToggleView.swift         |  44 ++
 .../MCPProxy/Views/ServerBrowseView.swift     | 410 ------------------
 .../MCPProxy/MCPProxy/Views/ServersView.swift |  11 +-
 .../MCPProxy/Views/SettingsView.swift         |  14 +-
 .../MCPProxy/MCPProxyTests/CatalogTests.swift |  91 ++++
 .../PasteServerFieldsTests.swift              |  94 ++++
 15 files changed, 1119 insertions(+), 507 deletions(-)
 create mode 100644 native/macos/MCPProxy/MCPProxy/Models/SecretFieldResolver.swift
 create mode 100644 native/macos/MCPProxy/MCPProxy/Views/CatalogView.swift
 create mode 100644 native/macos/MCPProxy/MCPProxy/Views/PasteServerView.swift
 create mode 100644 native/macos/MCPProxy/MCPProxy/Views/SecretFieldToggleView.swift
 delete mode 100644 native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
 create mode 100644 native/macos/MCPProxy/MCPProxyTests/PasteServerFieldsTests.swift

diff --git a/docs/registries.md b/docs/registries.md
index 052bade47..3a15f1e46 100644
--- a/docs/registries.md
+++ b/docs/registries.md
@@ -113,16 +113,18 @@ Equivalent surfaces:
 
 - **REST:** `POST /api/v1/registries` with `{ "url": "https://…", "protocol": "…", "id": "…", "name": "…" }`.
 - **CLI:** `mcpproxy registry add-source <https-url>`.
-- **Web UI:** the **Repositories** page has an **Add Registry** button (URL + optional
-  protocol/name) and a **Registries** section listing every configured source as a
+- **Web UI:** Settings → **Catalog Sources** has an **Add Registry** button (URL + optional
+  protocol/name) and lists every configured source as a
   card with a neutral **Official / Custom** badge (official cards also carry a
   **Built-in** tag). There is no warning gate — adding a custom source goes straight
   through. Custom cards expose a **kebab (⋮) menu** with **Edit** (reuses the
   add dialog, pre-filled, id read-only) and **Delete** (destructive confirmation);
-  official cards are read-only.
-- **macOS tray:** the **Registries** sidebar tab lists every configured registry
-  with its provenance/trust badge, offers an **Add Registry** affordance,
-  and shows a one-time third-party warning before the first custom add.
+  official cards are read-only. Server discovery itself lives in the catalog-first
+  **Add Server** page (`/add-server`, Catalog tab), not here.
+- **macOS tray:** Settings → **Catalog Sources** lists every configured registry
+  with its provenance/trust badge and offers an **Add Registry** affordance;
+  server discovery lives in the Add Server sheet's **Catalog** tab (aggregated
+  across every enabled source, same as the Web UI).
 
 Errors share a stable code across surfaces: `invalid_registry_url` (400),
 `registries_locked` (403), `registry_shadows_builtin` / `duplicate_registry` (409).
diff --git a/native/macos/MCPProxy/MCPProxy/API/APIClient.swift b/native/macos/MCPProxy/MCPProxy/API/APIClient.swift
index 03f171ce4..8e8861751 100644
--- a/native/macos/MCPProxy/MCPProxy/API/APIClient.swift
+++ b/native/macos/MCPProxy/MCPProxy/API/APIClient.swift
@@ -305,6 +305,24 @@ actor APIClient {
         )
     }
 
+    /// Every keyring/env secret reference currently configured (masked), via
+    /// `GET /api/v1/secrets/refs`. Used by the Add Server sheet's secret
+    /// toggle (Spec 109 FR-065) as the "taken names" set before computing a
+    /// new `SecretRefName`.
+    func getSecretRefs() async throws -> [SecretRefEntry] {
+        let response: SecretRefsResponse = try await fetchWrapped(path: "/api/v1/secrets/refs")
+        return response.refs
+    }
+
+    /// Delete a keyring secret via `DELETE /api/v1/secrets/{name}?type=keyring`.
+    /// Used to roll back a secret this session's own Add Server flow just
+    /// wrote, when the add itself then fails (FR-065) — never a pre-existing
+    /// entry, since callers only ever pass back a ref they just got from
+    /// `storeSecret`.
+    func deleteSecret(name: String, type: String = "keyring") async throws {
+        try await deleteAction(path: "/api/v1/secrets/\(name.uriComponentEncoded)?type=\(type.uriComponentEncoded)")
+    }
+
     // MARK: - Connect (Client Registration)
 
     /// Client status model returned by `GET /api/v1/connect` (list, existence
@@ -783,6 +801,34 @@ actor APIClient {
         }
     }
 
+    /// Preview-detect a server from pasted content (URL, command line, or a
+    /// JSON/TOML config) via `POST /api/v1/servers/import/json?preview=true`
+    /// (Spec 109 FR-064). Never performs the import itself — the Paste tab
+    /// posts the resolved config to `POST /api/v1/servers` once the user
+    /// fills in the detected fields, same as the Manual tab.
+    func previewImportContent(_ content: String) async throws -> ImportPreviewResponse {
+        let data = try await postRaw(path: "/api/v1/servers/import/json?preview=true", body: ["content": content])
+        let decoder = JSONDecoder()
+
+        if let wrapper = try? decoder.decode(APIResponse<ImportPreviewResponse>.self, from: data),
+           let payload = wrapper.data {
+            return payload
+        }
+        if let errorResp = try? decoder.decode(APIErrorResponse.self, from: data),
+           !errorResp.success, let message = errorResp.error {
+            throw APIClientError.httpError(statusCode: 400, message: message)
+        }
+        do {
+            return try decoder.decode(ImportPreviewResponse.self, from: data)
+        } catch {
+            let preview = String(data: data.prefix(200), encoding: .utf8) ?? "binary"
+            throw APIClientError.decodingError(
+                underlying: NSError(domain: "ImportPreviewDecode", code: -1,
+                                    userInfo: [NSLocalizedDescriptionKey: "Cannot decode import preview response: \(preview)"])
+            )
+        }
+    }
+
     // MARK: - Tool Search
 
     /// Percent-encode one query-string VALUE.
diff --git a/native/macos/MCPProxy/MCPProxy/API/CatalogModels.swift b/native/macos/MCPProxy/MCPProxy/API/CatalogModels.swift
index 5138d9b08..907675108 100644
--- a/native/macos/MCPProxy/MCPProxy/API/CatalogModels.swift
+++ b/native/macos/MCPProxy/MCPProxy/API/CatalogModels.swift
@@ -82,3 +82,76 @@ struct CatalogSearchResponse: Codable {
     let sections: CatalogSections?
     let unavailable: [CatalogSourceError]?
 }
+
+// MARK: - Secret refs (Spec 109 FR-065)
+//
+// `GET /api/v1/secrets/refs` — every keyring/env secret reference currently
+// configured, values always masked. Used by the Add Server sheet's secret
+// toggle (Catalog + Paste tabs) as the "taken names" set so two fields that
+// would compute the same `SecretRefName` collide into `-2`, `-3`, … instead
+// of silently overwriting one another (D28), mirroring the Web UI's
+// `resolveSecretFields` (frontend/src/composables/useSecretFields.ts).
+
+/// One entry of `GET /api/v1/secrets/refs`. Mirrors the masked shape written
+/// by `handleGetSecretRefs` (internal/httpapi/server.go): `type`, `name`,
+/// `original` — never the actual value.
+struct SecretRefEntry: Codable, Equatable {
+    let type: String
+    let name: String
+    let original: String?
+}
+
+/// Response wrapper for `GET /api/v1/secrets/refs`.
+struct SecretRefsResponse: Codable {
+    let refs: [SecretRefEntry]
+    let count: Int?
+}
+
+// MARK: - Import preview (Spec 109 FR-064), content-based
+//
+// `POST /api/v1/servers/import/json?preview=true` — the Paste tab's "detect
+// before add" step. Distinct from `ImportResponse` (API/Models.swift), which
+// models the simpler path-based `POST /api/v1/servers/import/path` summary
+// the Import tab uses; this mirrors `httpapi.ImportedServerResponse`'s FR-064
+// preview enrichment (`summary`, `tags`, `env`, `headers`) that the path-based
+// response never carries.
+
+/// One env-var or header field the import preview detected. Mirrors
+/// `httpapi.EnvFieldPreview` / `HeaderFieldPreview`: `secret_like` already
+/// folds in the D13 name heuristic, so the toggle default needs no
+/// client-side re-derivation.
+struct ImportPreviewField: Codable, Equatable {
+    let name: String
+    let secretLike: Bool
+    let emptyOrPlaceholder: Bool
+
+    enum CodingKeys: String, CodingKey {
+        case name
+        case secretLike = "secret_like"
+        case emptyOrPlaceholder = "empty_or_placeholder"
+    }
+}
+
+/// One detected server in an import preview. Mirrors
+/// `httpapi.ImportedServerResponse` (only the fields the Paste tab needs).
+struct ImportPreviewServer: Codable, Equatable {
+    let name: String
+    let `protocol`: String
+    let url: String?
+    let command: String?
+    let args: [String]?
+    let summary: String?
+    let tags: [String]?
+    let env: [ImportPreviewField]?
+    let headers: [ImportPreviewField]?
+}
+
+/// Response of `POST /api/v1/servers/import/json` (preview or real). Mirrors
+/// `httpapi.ImportResponse`; only `format` and `imported` are decoded here —
+/// the Paste tab only ever previews (`imported.first`), never calls this
+/// endpoint to perform the real add (it posts the resolved config to
+/// `POST /api/v1/servers` instead, same as the Manual tab).
+struct ImportPreviewResponse: Codable {
+    let format: String?
+    let imported: [ImportPreviewServer]
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Models/SecretFieldResolver.swift b/native/macos/MCPProxy/MCPProxy/Models/SecretFieldResolver.swift
new file mode 100644
index 000000000..520d446ba
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxy/Models/SecretFieldResolver.swift
@@ -0,0 +1,119 @@
+import Foundation
+
+// MARK: - Secret field resolution (Spec 109 FR-065)
+//
+// Shared by the Add Server sheet's Catalog and Paste tabs: a field the user
+// can leave as a plain Value or toggle to Secret. A Secret-mode field gets
+// written to the OS keyring under its computed `SecretRefName` and replaced
+// with `${keyring:<ref>}`; a Value-mode field is passed through unchanged.
+// Swift mirror of the Web UI's `resolveSecretFields`
+// (frontend/src/composables/useSecretFields.ts) — same two-phase shape (pure
+// value-map assembly, then the keyring calls) so the assembly half is
+// unit-testable without a running app or API client, matching this codebase's
+// existing pattern (`ManualServerForm`'s pure `makeServerConfig` seam).
+
+/// One field the Catalog/Paste tab lets the user fill in and toggle between
+/// Value and Secret. `kind` picks which `POST /api/v1/servers` field it lands
+/// in (`env` or `headers`) and which `SecretRefName.Kind` computes its
+/// keyring ref name, so an env var and a header of the same name never
+/// collide on one keyring entry (FR-065).
+struct SecretFieldInput: Equatable, Identifiable {
+    enum Kind: Equatable {
+        case env
+        case header
+    }
+
+    enum Mode: Equatable {
+        case value
+        case secret
+    }
+
+    /// Distinguishes an env field from a header field of the same name —
+    /// `name` alone would collide.
+    var id: String { "\(kind)-\(name)" }
+    let name: String
+    var kind: Kind = .env
+    var value: String
+    var mode: Mode
+}
+
+/// Result of resolving a set of `SecretFieldInput`s: the env/header maps
+/// ready to send to `POST /api/v1/servers` (or the registry add endpoint),
+/// plus the refs this call itself wrote to the keyring — the only ones a
+/// failed add is allowed to roll back.
+struct ResolvedSecretFields: Equatable {
+    let env: [String: String]
+    let headers: [String: String]
+    let writtenRefs: [String]
+}
+
+enum SecretFieldResolver {
+    /// Pure assembly of the env/header maps: a Value-mode field's literal
+    /// value, or a `${keyring:<ref>}` placeholder for a field this call
+    /// already wrote (`written` maps `field.id` -> the ref name `resolve`
+    /// computed and stored for it). Extracted so the mapping logic — which
+    /// field becomes a placeholder vs. a literal value, and which map it
+    /// lands in — is testable without any network call.
+    static func buildValues(fields: [SecretFieldInput], written: [String: String]) -> (env: [String: String], headers: [String: String]) {
+        var env: [String: String] = [:]
+        var headers: [String: String] = [:]
+        for field in fields {
+            let value = written[field.id].map { "${keyring:\($0)}" } ?? field.value
+            switch field.kind {
+            case .env: env[field.name] = value
+            case .header: headers[field.name] = value
+            }
+        }
+        return (env, headers)
+    }
+
+    /// Writes every `.secret`-mode field to the OS keyring (skipping the
+    /// network round trip entirely when there are none) and returns the
+    /// resolved env/header maps. On a keyring-write failure, rolls back only
+    /// the refs this call itself wrote — never a pre-existing entry — and
+    /// rethrows.
+    static func resolve(client: APIClient, serverName: String, fields: [SecretFieldInput]) async throws -> ResolvedSecretFields {
+        let secretFields = fields.filter { $0.mode == .secret }
+        guard !secretFields.isEmpty else {
+            let (env, headers) = buildValues(fields: fields, written: [:])
+            return ResolvedSecretFields(env: env, headers: headers, writtenRefs: [])
+        }
+
+        // One taken-name check up front, then tracked locally as this call
+        // writes its own refs, so two fields in the same call that would
+        // otherwise compute the same name get -2, not a silent collision.
+        var taken: Set<String> = []
+        if let refs = try? await client.getSecretRefs() {
+            taken = Set(refs.filter { $0.type == "keyring" }.map(\.name))
+        }
+
+        var written: [String: String] = [:] // field.id -> ref
+        var writtenRefs: [String] = []
+
+        do {
+            for field in secretFields {
+                let refKind: SecretRefName.Kind = field.kind == .header ? .header : .env
+                let ref = SecretRefName.compute(server: serverName, kind: refKind, key: field.name, taken: { taken.contains($0) })
+                _ = try await client.storeSecret(name: ref, value: field.value)
+                taken.insert(ref)
+                written[field.id] = ref
+                writtenRefs.append(ref)
+            }
+        } catch {
+            await rollback(client: client, refs: writtenRefs)
+            throw error
+        }
+
+        let (env, headers) = buildValues(fields: fields, written: written)
+        return ResolvedSecretFields(env: env, headers: headers, writtenRefs: writtenRefs)
+    }
+
+    /// Deletes only the refs THIS add wrote — never a pre-existing entry.
+    /// Best-effort: a rollback failure is swallowed rather than compounding
+    /// the original error the caller is already reporting.
+    static func rollback(client: APIClient, refs: [String]) async {
+        for ref in refs {
+            _ = try? await client.deleteSecret(name: ref)
+        }
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Views/AddServerView.swift b/native/macos/MCPProxy/MCPProxy/Views/AddServerView.swift
index 00ef96147..e5874609e 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/AddServerView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/AddServerView.swift
@@ -8,7 +8,11 @@ import SwiftUI
 
 // MARK: - Add Server Tab
 
+/// Spec 109 FR-062: Catalog (default) · Paste · Import · Manual — same order
+/// and same default as the Web UI's `views/AddServer.vue`.
 enum AddServerTab: String, CaseIterable {
+    case catalog = "Catalog"
+    case paste = "Paste"
     case importConfig = "Import"
     case manual = "Manual"
 }
@@ -21,13 +25,17 @@ struct AddServerView: View {
     @Environment(\.fontScale) var fontScale
 
     @State private var selectedTab: AddServerTab
+    /// Narrows the Catalog tab only (mirrors the Web UI's `?source=`); never
+    /// selects a tab itself (FR-062).
+    let catalogSourceFilter: String?
 
     private var apiClient: APIClient? { appState.apiClient }
 
-    init(appState: AppState, isPresented: Binding<Bool>, initialTab: AddServerTab = .importConfig) {
+    init(appState: AppState, isPresented: Binding<Bool>, initialTab: AddServerTab = .catalog, catalogSourceFilter: String? = nil) {
         self.appState = appState
         self._isPresented = isPresented
         self._selectedTab = State(initialValue: initialTab)
+        self.catalogSourceFilter = catalogSourceFilter
     }
 
     var body: some View {
@@ -56,10 +64,15 @@ struct AddServerView: View {
             .pickerStyle(.segmented)
             .padding(.horizontal)
             .padding(.bottom, 8)
+            .accessibilityIdentifier("add-server-tab-picker")
 
             Divider()
 
             switch selectedTab {
+            case .catalog:
+                CatalogView(appState: appState, sourceFilter: catalogSourceFilter, onAdded: { _ in isPresented = false })
+            case .paste:
+                PasteServerView(appState: appState, onAdded: { _ in isPresented = false })
             case .importConfig:
                 ImportServerForm(appState: appState, onDone: { isPresented = false })
             case .manual:
diff --git a/native/macos/MCPProxy/MCPProxy/Views/CatalogView.swift b/native/macos/MCPProxy/MCPProxy/Views/CatalogView.swift
new file mode 100644
index 000000000..21cd77a1f
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxy/Views/CatalogView.swift
@@ -0,0 +1,346 @@
+// CatalogView.swift
+// MCPProxy
+//
+// The Add Server sheet's Catalog tab (Spec 109 FR-060/061/063/065): a
+// source-agnostic, ranked search over every enabled catalog source
+// (`GET /api/v1/catalog/search`), superseding the old per-registry
+// ServerBrowseView / RegistriesView "Discover servers" tab the same way the
+// Web UI's `views/AddServer.vue` + `CatalogSearch.vue` superseded
+// `views/Repositories.vue`. Registry SOURCE management (add/edit/remove a
+// registry) moved to Settings → Catalog Sources.
+
+import SwiftUI
+
+struct CatalogView: View {
+    @ObservedObject var appState: AppState
+    /// Narrows results to one catalog source id (mirrors the Web UI's
+    /// `?source=` query param, which narrows the Catalog tab only — it never
+    /// selects a tab, FR-062). Nil searches every enabled source.
+    var sourceFilter: String?
+    let onAdded: (String) -> Void
+
+    @Environment(\.fontScale) var fontScale
+
+    @State private var query = ""
+    @State private var isLoading = false
+    @State private var errorMessage: String?
+    @State private var results: [CatalogResult] = []
+    @State private var sections: CatalogSections?
+    @State private var unavailable: [CatalogSourceError] = []
+    /// "<source>-<id>" -> the name the backend actually assigned (Spec 109
+    /// FR-063: once added this sheet-visit, the button flips to "Added ✓ ·
+    /// Open" and stays that way).
+    @State private var addedNames: [String: String] = [:]
+    @State private var addingKey: String?
+    @State private var searchTask: Task<Void, Never>?
+
+    // Secrets-prompt sheet state (FR-065).
+    @State private var pendingResult: CatalogResult?
+    @State private var pendingFields: [SecretFieldInput] = []
+    @State private var addError: String?
+    @State private var confirming = false
+
+    private var apiClient: APIClient? { appState.apiClient }
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 0) {
+            TextField("Search the catalog (e.g. 'github', 'filesystem')…", text: $query)
+                .textFieldStyle(.roundedBorder)
+                .padding(.horizontal)
+                .padding(.top, 8)
+                .padding(.bottom, 8)
+                .onChange(of: query) { _ in scheduleSearch() }
+                .accessibilityIdentifier("catalog-search-input")
+
+            if !unavailable.isEmpty {
+                Text(unavailable.map { "\($0.source) (\($0.reason))" }.joined(separator: ", ") + " unavailable")
+                    .font(.scaled(.caption, scale: fontScale))
+                    .foregroundStyle(.orange)
+                    .padding(.horizontal)
+                    .padding(.bottom, 6)
+                    .accessibilityIdentifier("catalog-unavailable-notice")
+            }
+
+            content
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+        .accessibilityIdentifier("catalog-view")
+        .task { await search() }
+        .sheet(item: $pendingResult) { result in
+            secretsSheet(result)
+        }
+    }
+
+    @ViewBuilder
+    private var content: some View {
+        if isLoading {
+            VStack { Spacer(); ProgressView("Searching the catalog…"); Spacer() }
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+        } else if let err = errorMessage {
+            Text(err)
+                .font(.scaled(.callout, scale: fontScale))
+                .foregroundStyle(.red)
+                .padding()
+                .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .top)
+                .accessibilityIdentifier("catalog-error")
+        } else {
+            ScrollView {
+                VStack(alignment: .leading, spacing: 12) {
+                    if let sections {
+                        sectionBlock(title: "Official", items: sections.official, testID: "catalog-section-official")
+                        sectionBlock(title: "Popular", items: sections.popular, testID: "catalog-section-popular")
+                        if sections.official.isEmpty && sections.popular.isEmpty {
+                            Text("Nothing to browse yet.")
+                                .font(.scaled(.callout, scale: fontScale))
+                                .foregroundStyle(.secondary)
+                        }
+                    } else {
+                        Text("\(results.count) result\(results.count == 1 ? "" : "s")")
+                            .font(.scaled(.caption, scale: fontScale))
+                            .foregroundStyle(.secondary)
+                            .accessibilityIdentifier("catalog-results-count")
+                        ForEach(results) { resultCard($0) }
+                    }
+                }
+                .padding(.horizontal)
+                .padding(.bottom, 8)
+            }
+        }
+    }
+
+    @ViewBuilder
+    private func sectionBlock(title: String, items: [CatalogResult], testID: String) -> some View {
+        if !items.isEmpty {
+            VStack(alignment: .leading, spacing: 6) {
+                Text(title)
+                    .font(.scaled(.subheadline, scale: fontScale).weight(.semibold))
+                    .foregroundStyle(.secondary)
+                ForEach(items) { resultCard($0) }
+            }
+            .accessibilityIdentifier(testID)
+        }
+    }
+
+    @ViewBuilder
+    private func resultCard(_ r: CatalogResult) -> some View {
+        let key = "\(r.source)-\(r.id)"
+        let addedName = addedNames[key]
+        let added = addedName != nil || r.added
+
+        VStack(alignment: .leading, spacing: 6) {
+            HStack(alignment: .top) {
+                VStack(alignment: .leading, spacing: 2) {
+                    Text(r.title)
+                        .font(.scaled(.headline, scale: fontScale))
+                        .lineLimit(1)
+                        .accessibilityIdentifier("catalog-result-title")
+                    Text(r.id)
+                        .font(.scaledMonospaced(.caption2, scale: fontScale))
+                        .foregroundStyle(.tertiary)
+                        .lineLimit(1)
+                        .truncationMode(.middle)
+                }
+                Spacer()
+                HStack(spacing: 4) {
+                    if r.official {
+                        badge("Official", tint: .accentColor)
+                    } else if r.verified {
+                        badge("Verified", tint: .green)
+                    }
+                    badge(r.transport, tint: .secondary)
+                }
+            }
+
+            if !r.description.isEmpty {
+                Text(r.description)
+                    .font(.scaled(.caption, scale: fontScale))
+                    .foregroundStyle(.secondary)
+                    .lineLimit(2)
+            }
+
+            HStack {
+                Spacer()
+                if added {
+                    Button("Added ✓ · Open") {
+                        if let addedName { openServer(addedName) }
+                    }
+                    .controlSize(.small)
+                    .accessibilityIdentifier("catalog-added-\(key)")
+                } else {
+                    Button {
+                        handleAddTapped(r)
+                    } label: {
+                        if addingKey == key { ProgressView().controlSize(.small) } else { Text("Add to MCPProxy") }
+                    }
+                    .buttonStyle(.borderedProminent)
+                    .controlSize(.small)
+                    .disabled(addingKey != nil)
+                    .accessibilityIdentifier("catalog-add-\(key)")
+                }
+            }
+        }
+        .padding(10)
+        .background(Color.secondary.opacity(0.06))
+        .clipShape(RoundedRectangle(cornerRadius: 8))
+        .accessibilityIdentifier("catalog-result-\(key)")
+    }
+
+    private func badge(_ text: String, tint: Color) -> some View {
+        Text(text)
+            .font(.scaled(.caption2, scale: fontScale).weight(.medium))
+            .padding(.horizontal, 6)
+            .padding(.vertical, 2)
+            .background(tint.opacity(0.15))
+            .foregroundStyle(tint)
+            .clipShape(Capsule())
+    }
+
+    // MARK: - Secrets sheet (FR-065)
+
+    @ViewBuilder
+    private func secretsSheet(_ result: CatalogResult) -> some View {
+        VStack(alignment: .leading, spacing: 12) {
+            HStack {
+                Text(result.title)
+                    .font(.scaled(.title3, scale: fontScale).bold())
+                Spacer()
+                Button {
+                    pendingResult = nil
+                } label: {
+                    Image(systemName: "xmark.circle.fill").foregroundStyle(.secondary)
+                }
+                .buttonStyle(.borderless)
+            }
+            Text("This server needs a few values before it can run.")
+                .font(.scaled(.caption, scale: fontScale))
+                .foregroundStyle(.secondary)
+
+            ForEach($pendingFields) { $field in
+                SecretFieldToggleView(name: field.name, value: $field.value, mode: $field.mode)
+            }
+
+            if let addError {
+                Text(addError)
+                    .font(.scaled(.caption, scale: fontScale))
+                    .foregroundStyle(.red)
+                    .accessibilityIdentifier("catalog-add-error")
+            }
+
+            HStack {
+                Spacer()
+                Button("Cancel") { pendingResult = nil }
+                    .buttonStyle(.bordered)
+                Button {
+                    Task { await confirmAdd(result) }
+                } label: {
+                    if confirming { ProgressView().controlSize(.small) } else { Text("Add to MCPProxy") }
+                }
+                .buttonStyle(.borderedProminent)
+                .disabled(confirming || !allPendingValuesFilled)
+                .accessibilityIdentifier("catalog-secrets-confirm")
+            }
+        }
+        .padding()
+        .frame(width: 420)
+    }
+
+    private var allPendingValuesFilled: Bool {
+        pendingFields.allSatisfy { !$0.value.trimmingCharacters(in: .whitespaces).isEmpty }
+    }
+
+    // MARK: - Search
+
+    private func scheduleSearch() {
+        searchTask?.cancel()
+        searchTask = Task {
+            try? await Task.sleep(nanoseconds: 250_000_000)
+            if Task.isCancelled { return }
+            await search()
+        }
+    }
+
+    private func search() async {
+        guard let client = apiClient else {
+            errorMessage = "Not connected to MCPProxy core"
+            return
+        }
+        isLoading = true
+        errorMessage = nil
+        defer { isLoading = false }
+        do {
+            let resp = try await client.searchCatalog(query: query, source: sourceFilter)
+            results = resp.results
+            sections = resp.sections
+            unavailable = resp.unavailable ?? []
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    // MARK: - Add
+
+    private func handleAddTapped(_ result: CatalogResult) {
+        if let inputs = result.requiredInputs, !inputs.isEmpty {
+            pendingFields = inputs.map {
+                SecretFieldInput(name: $0.name, kind: .env, value: "", mode: $0.secretLike ? .secret : .value)
+            }
+            addError = nil
+            pendingResult = result
+            return
+        }
+        Task { await addResult(result, env: [:]) }
+    }
+
+    private func confirmAdd(_ result: CatalogResult) async {
+        guard let client = apiClient else { return }
+        confirming = true
+        addError = nil
+        // Populated only once SecretFieldResolver.resolve has returned
+        // successfully, so a failed addResult below rolls back exactly what
+        // this attempt wrote — never double-rolls-back what resolve() itself
+        // already rolled back on a write failure.
+        var writtenRefs: [String] = []
+        do {
+            let serverName = result.title.isEmpty ? result.id : result.title
+            let resolved = try await SecretFieldResolver.resolve(client: client, serverName: serverName, fields: pendingFields)
+            writtenRefs = resolved.writtenRefs
+            let added = await addResult(result, env: resolved.env)
+            if added {
+                pendingResult = nil
+            } else if !writtenRefs.isEmpty {
+                await SecretFieldResolver.rollback(client: client, refs: writtenRefs)
+            }
+        } catch {
+            addError = error.localizedDescription
+        }
+        confirming = false
+    }
+
+    /// Returns whether the add succeeded. Callers MUST check the return value
+    /// rather than assume completion means success (mirrors the Web UI's
+    /// `addResult`, whose doc comment explains why).
+    @discardableResult
+    private func addResult(_ result: CatalogResult, env: [String: String]) async -> Bool {
+        guard let client = apiClient else { return false }
+        let key = "\(result.source)-\(result.id)"
+        addingKey = key
+        defer { addingKey = nil }
+        let outcome = await client.addServerFromRegistry(registryID: result.source, serverID: result.id, env: env.isEmpty ? nil : env)
+        if outcome.success {
+            let assignedName = outcome.serverName ?? result.title
+            addedNames[key] = assignedName
+            onAdded(assignedName)
+            return true
+        }
+        addError = outcome.message ?? "Failed to add server"
+        return false
+    }
+
+    /// Spec 109 FR-063: "Added ✓ · Open" opens the server it just added.
+    private func openServer(_ name: String) {
+        NotificationCenter.default.post(name: .switchToServers, object: nil)
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.3) {
+            NotificationCenter.default.post(name: .showServerDetail, object: name)
+        }
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Views/MainWindow.swift b/native/macos/MCPProxy/MCPProxy/Views/MainWindow.swift
index 062c92f97..a9cb2ed48 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/MainWindow.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/MainWindow.swift
@@ -10,7 +10,11 @@ enum SidebarItem: String, CaseIterable, Identifiable {
     // native home — a tray-first user could not answer "which of my 942 tools
     // does X?" without opening a browser.
     case tools = "Tools"
-    case registries = "Registries"
+    // Spec 109 T109: the Registries sidebar item is retired — server
+    // discovery moved into the Add Server sheet's Catalog tab (CatalogView,
+    // aggregated across every enabled source) and registry SOURCE management
+    // moved to Settings -> Catalog Sources, mirroring the Web UI's
+    // `views/Repositories.vue` -> `/add-server?tab=catalog` + Settings move.
     case activity = "Activity Log"
     case secrets = "Secrets"
     // F5: TokensView was a complete, API-complete create/list/revoke UI that
@@ -25,7 +29,6 @@ enum SidebarItem: String, CaseIterable, Identifiable {
         case .dashboard: return "rectangle.3.group"
         case .servers: return "server.rack"
         case .tools: return "wrench.and.screwdriver"
-        case .registries: return "books.vertical"
         case .activity: return "clock.arrow.circlepath"
         case .secrets: return "key.fill"
         case .tokens: return "key.horizontal"
@@ -82,8 +85,6 @@ struct MainWindow: View {
                         ServersView(appState: appState)
                     case .tools:
                         ToolsView(appState: appState)
-                    case .registries:
-                        RegistriesView(appState: appState)
                     case .activity:
                         ActivityView(appState: appState)
                     case .secrets:
diff --git a/native/macos/MCPProxy/MCPProxy/Views/PasteServerView.swift b/native/macos/MCPProxy/MCPProxy/Views/PasteServerView.swift
new file mode 100644
index 000000000..859459326
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxy/Views/PasteServerView.swift
@@ -0,0 +1,231 @@
+// PasteServerView.swift
+// MCPProxy
+//
+// The Add Server sheet's Paste tab (Spec 109 FR-064/065): paste a URL, a
+// command line, or a JSON/TOML config; preview-detect the server (never
+// executes anything); fill in any detected env/header fields with a
+// Value/Secret toggle; add. Mirrors the Web UI's `PasteServer.vue`.
+
+import SwiftUI
+
+struct PasteServerView: View {
+    @ObservedObject var appState: AppState
+    let onAdded: (String) -> Void
+
+    @Environment(\.fontScale) var fontScale
+
+    @State private var content = ""
+    @State private var isLoading = false
+    @State private var errorMessage: String?
+    @State private var preview: ImportPreviewServer?
+    @State private var format: String?
+    @State private var fields: [SecretFieldInput] = []
+    @State private var addError: String?
+    @State private var adding = false
+    @State private var previewTask: Task<Void, Never>?
+
+    private var apiClient: APIClient? { appState.apiClient }
+
+    private var formatLabel: String {
+        switch format {
+        case "url": return "Remote URL"
+        case "command": return "Command line"
+        default: return format ?? "Config"
+        }
+    }
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 0) {
+            Text("Paste a URL, a command line, or a JSON/TOML config")
+                .font(.scaled(.subheadline, scale: fontScale))
+                .foregroundStyle(.secondary)
+                .padding(.horizontal)
+                .padding(.top, 8)
+
+            TextEditor(text: $content)
+                .font(.scaledMonospaced(.body, scale: fontScale))
+                .frame(height: 100)
+                .border(Color.gray.opacity(0.3), width: 1)
+                .padding(.horizontal)
+                .padding(.top, 6)
+                .onChange(of: content) { _ in schedulePreview() }
+                .accessibilityIdentifier("paste-textarea")
+
+            statusArea
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+        .accessibilityIdentifier("paste-server")
+    }
+
+    @ViewBuilder
+    private var statusArea: some View {
+        if isLoading {
+            HStack(spacing: 8) {
+                ProgressView().controlSize(.small)
+                Text("Detecting…")
+                    .font(.scaled(.caption, scale: fontScale))
+                    .foregroundStyle(.secondary)
+            }
+            .padding(.horizontal)
+            .padding(.top, 8)
+            .accessibilityIdentifier("paste-loading")
+        } else if let err = errorMessage {
+            Text(err)
+                .font(.scaled(.caption, scale: fontScale))
+                .foregroundStyle(.red)
+                .padding(.horizontal)
+                .padding(.top, 8)
+                .accessibilityIdentifier("paste-error")
+        } else if let preview {
+            ScrollView {
+                VStack(alignment: .leading, spacing: 10) {
+                    HStack(spacing: 6) {
+                        badge(formatLabel)
+                        ForEach(preview.tags ?? [], id: \.self) { badge($0) }
+                    }
+                    if let summary = preview.summary, !summary.isEmpty {
+                        Text(summary)
+                            .font(.scaledMonospaced(.caption, scale: fontScale))
+                            .foregroundStyle(.secondary)
+                            .textSelection(.enabled)
+                            .accessibilityIdentifier("paste-summary")
+                    }
+
+                    ForEach($fields) { $field in
+                        SecretFieldToggleView(name: field.name, value: $field.value, mode: $field.mode)
+                    }
+
+                    if let addError {
+                        Text(addError)
+                            .font(.scaled(.caption, scale: fontScale))
+                            .foregroundStyle(.red)
+                            .accessibilityIdentifier("paste-add-error")
+                    }
+
+                    Button {
+                        Task { await handleAdd() }
+                    } label: {
+                        if adding { ProgressView().controlSize(.small) } else { Text("Add to MCPProxy") }
+                    }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(adding)
+                    .accessibilityIdentifier("paste-add-button")
+                }
+                .padding()
+            }
+        }
+    }
+
+    private func badge(_ text: String) -> some View {
+        Text(text)
+            .font(.scaled(.caption2, scale: fontScale))
+            .padding(.horizontal, 6)
+            .padding(.vertical, 2)
+            .overlay(Capsule().stroke(Color.secondary.opacity(0.4)))
+    }
+
+    // MARK: - Preview
+
+    private func schedulePreview() {
+        previewTask?.cancel()
+        let raw = content.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !raw.isEmpty else {
+            preview = nil
+            errorMessage = nil
+            return
+        }
+        previewTask = Task {
+            try? await Task.sleep(nanoseconds: 400_000_000)
+            if Task.isCancelled { return }
+            await runPreview()
+        }
+    }
+
+    private func runPreview() async {
+        guard let client = apiClient else {
+            errorMessage = "Not connected to MCPProxy core"
+            return
+        }
+        let raw = content.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !raw.isEmpty else { return }
+        isLoading = true
+        errorMessage = nil
+        defer { isLoading = false }
+        do {
+            let resp = try await client.previewImportContent(raw)
+            guard let first = resp.imported.first else {
+                errorMessage = "Could not detect a server from this input"
+                preview = nil
+                return
+            }
+            format = resp.format
+            preview = first
+            fields = Self.buildFields(from: first)
+        } catch {
+            errorMessage = error.localizedDescription
+            preview = nil
+        }
+    }
+
+    /// Pure: turns an import preview's env/header fields into the toggle
+    /// list, defaulting each to Secret when the backend's D13 heuristic (or
+    /// an explicit registry flag) says the name looks like a credential.
+    /// Extracted so it is unit-testable without a running app or API client.
+    static func buildFields(from server: ImportPreviewServer) -> [SecretFieldInput] {
+        let envFields = (server.env ?? []).map {
+            SecretFieldInput(name: $0.name, kind: .env, value: "", mode: $0.secretLike ? .secret : .value)
+        }
+        let headerFields = (server.headers ?? []).map {
+            SecretFieldInput(name: $0.name, kind: .header, value: "", mode: $0.secretLike ? .secret : .value)
+        }
+        return envFields + headerFields
+    }
+
+    // MARK: - Add
+
+    private func handleAdd() async {
+        guard let client = apiClient, let preview else { return }
+        adding = true
+        addError = nil
+        // Populated only once SecretFieldResolver.resolve has returned
+        // successfully, so the catch block below never double-rolls-back
+        // refs it already rolled back itself on a write failure.
+        var writtenRefs: [String] = []
+        do {
+            let resolved = try await SecretFieldResolver.resolve(client: client, serverName: preview.name, fields: fields)
+            writtenRefs = resolved.writtenRefs
+
+            let config = Self.makeServerConfig(preview: preview, resolved: resolved)
+            try await client.addServer(config)
+            onAdded(preview.name)
+        } catch {
+            if !writtenRefs.isEmpty {
+                await SecretFieldResolver.rollback(client: client, refs: writtenRefs)
+            }
+            addError = error.localizedDescription
+        }
+        adding = false
+    }
+
+    /// Pure: builds the `POST /api/v1/servers` body from the detected preview
+    /// and the resolved secret fields — the plain REST endpoint (native
+    /// `env`/`headers`/`args` keys), same one `ManualServerForm` posts to.
+    /// Extracted for unit testing without a running app or API client.
+    static func makeServerConfig(preview: ImportPreviewServer, resolved: ResolvedSecretFields) -> [String: Any] {
+        var config: [String: Any] = [
+            "name": preview.name,
+            "protocol": preview.protocol,
+            "enabled": true,
+        ]
+        if let url = preview.url, !url.isEmpty {
+            config["url"] = url
+            if !resolved.headers.isEmpty { config["headers"] = resolved.headers }
+        }
+        if let command = preview.command, !command.isEmpty {
+            config["command"] = command
+            if let args = preview.args, !args.isEmpty { config["args"] = args }
+            if !resolved.env.isEmpty { config["env"] = resolved.env }
+        }
+        return config
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Views/RegistriesView.swift b/native/macos/MCPProxy/MCPProxy/Views/RegistriesView.swift
index 83a87a7ab..173f82dfb 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/RegistriesView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/RegistriesView.swift
@@ -1,12 +1,18 @@
 // RegistriesView.swift
 // MCPProxy
 //
-// macOS-tray registry management surface (MCP-902 / MCP-1074):
+// macOS-tray registry SOURCE management surface (MCP-902 / MCP-1074), now
+// Settings -> Catalog Sources (Spec 109 T109):
 //   - lists configured registries with a neutral Official / Custom badge
 //   - an "Add Registry" affordance (POST /api/v1/registries)
 //   - per-custom-registry Edit (PUT /api/v1/registries/{id}) and
 //     Remove (DELETE /api/v1/registries/{id}) via an ellipsis + context menu
-//   - browse + add servers across registries (ServerBrowseView)
+//
+// Server DISCOVERY (browse + add across sources) moved to the Add Server
+// sheet's Catalog tab (CatalogView.swift), which searches the aggregated
+// `GET /api/v1/catalog/search` instead of fanning out per-registry the way
+// the old embedded ServerBrowseView did — mirroring the Web UI's
+// `views/Repositories.vue` -> `/add-server?tab=catalog` + Settings move.
 //
 // Provenance is informational only (MCP-1072): servers added from any registry
 // follow the global quarantine default, so there is no third-party warning.
@@ -34,9 +40,13 @@ struct RegistryProvenanceBadge: View {
     }
 }
 
-// MARK: - Registries View
+// MARK: - Catalog Sources (Settings tab)
 
-struct RegistriesView: View {
+/// Settings -> Catalog Sources (Spec 109 T109): registry SOURCE management
+/// only — the prominent "Add Registry" affordance plus the configured-
+/// registries list with per-custom-registry edit/remove. Server discovery
+/// lives in the Add Server sheet's Catalog tab (CatalogView.swift).
+struct CatalogSourcesTab: View {
     @ObservedObject var appState: AppState
     @Environment(\.fontScale) var fontScale
 
@@ -52,12 +62,6 @@ struct RegistriesView: View {
     /// The custom registry awaiting a Remove confirmation, if any.
     @State private var pendingRemoval: Registry?
 
-    /// Discovery-first layout (MCP-1078): a segmented control splits server
-    /// discovery (default) from registry management so search controls sit on
-    /// top and the results region is the dominant area, while the configured-
-    /// registries management list no longer competes with results for space.
-    @State private var tab: RegistryTab = .discover
-
     private var apiClient: APIClient? { appState.apiClient }
 
     private var customRegistries: [Registry] { registries.filter(\.isCustom) }
@@ -72,22 +76,6 @@ struct RegistriesView: View {
         VStack(alignment: .leading, spacing: 0) {
             header
 
-            // Discovery-first segmented control (MCP-1078): "Discover servers"
-            // is the default; "Manage registries" holds the add/edit/remove UI.
-            Picker("", selection: $tab) {
-                ForEach(RegistryTab.allCases) { t in
-                    Text(t.title).tag(t)
-                }
-            }
-            .pickerStyle(.segmented)
-            .labelsHidden()
-            .padding(.horizontal)
-            .padding(.bottom, 8)
-            .accessibilityIdentifier("registries-tab-picker")
-
-            // Banners apply to both tabs: load errors affect discovery (no
-            // registries to search) and management; add/edit/remove successes
-            // surface here too.
             if let success = successMessage {
                 banner(icon: "checkmark.circle.fill", tint: .green, text: success)
             }
@@ -97,15 +85,24 @@ struct RegistriesView: View {
 
             Divider()
 
-            switch tab {
-            case .discover:
-                // Search controls on top, results fill all remaining space.
-                ServerBrowseView(appState: appState, registries: registries)
-                    .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
-            case .manage:
-                manageTab
+            // Prominent "Add Registry" button bar (mirrors ServersView).
+            HStack {
+                Button {
+                    activeSheet = RegistrySheet(editing: nil)
+                } label: {
+                    Label("Add Registry", systemImage: "plus.circle.fill")
+                }
+                .buttonStyle(.borderedProminent)
+                .controlSize(.large)
+                .accessibilityIdentifier("registry-add-source-button")
+                Spacer()
             }
+            .padding(.horizontal)
+            .padding(.vertical, 8)
+
+            configuredList
         }
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
         .sheet(item: $activeSheet) { sheet in
             AddRegistryView(appState: appState, editing: sheet.editing) { result in
                 let verb = sheet.editing == nil ? "Added" : "Updated"
@@ -136,40 +133,12 @@ struct RegistriesView: View {
         .task { await load() }
     }
 
-    // MARK: Manage tab
-
-    /// Registry management: the prominent "Add Registry" affordance plus the
-    /// configured-registries list with per-custom-registry edit/remove. Lives
-    /// only on this tab so it no longer competes with search results (MCP-1078).
-    @ViewBuilder
-    private var manageTab: some View {
-        VStack(alignment: .leading, spacing: 0) {
-            // Prominent "Add Registry" button bar (mirrors ServersView).
-            HStack {
-                Button {
-                    activeSheet = RegistrySheet(editing: nil)
-                } label: {
-                    Label("Add Registry", systemImage: "plus.circle.fill")
-                }
-                .buttonStyle(.borderedProminent)
-                .controlSize(.large)
-                .accessibilityIdentifier("registry-add-source-button")
-                Spacer()
-            }
-            .padding(.horizontal)
-            .padding(.vertical, 8)
-
-            configuredList
-        }
-        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
-    }
-
     // MARK: Header
 
     @ViewBuilder
     private var header: some View {
         HStack {
-            Text("Registries")
+            Text("Catalog Sources")
                 .font(.scaled(.title2, scale: fontScale).bold())
             Spacer()
             Text("\(registries.count) configured")
@@ -347,22 +316,6 @@ struct RegistriesView: View {
     }
 }
 
-/// The two faces of the Registries pane (MCP-1078): discovery-first server
-/// browse (default) and registry management.
-enum RegistryTab: String, CaseIterable, Identifiable {
-    case discover
-    case manage
-
-    var id: String { rawValue }
-
-    var title: String {
-        switch self {
-        case .discover: return "Discover servers"
-        case .manage: return "Manage registries"
-        }
-    }
-}
-
 /// Identifiable wrapper for the add/edit sheet (`.sheet(item:)`).
 struct RegistrySheet: Identifiable {
     let id = UUID()
diff --git a/native/macos/MCPProxy/MCPProxy/Views/SecretFieldToggleView.swift b/native/macos/MCPProxy/MCPProxy/Views/SecretFieldToggleView.swift
new file mode 100644
index 000000000..9185ba891
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxy/Views/SecretFieldToggleView.swift
@@ -0,0 +1,44 @@
+// SecretFieldToggleView.swift
+// MCPProxy
+//
+// One required-input row in the Add Server sheet's Catalog/Paste tabs
+// (Spec 109 FR-065): a name, a Value/Secret segmented toggle, and the field
+// itself (a SecureField in Secret mode). Mirrors the Web UI's
+// `SecretToggle.vue`.
+
+import SwiftUI
+
+struct SecretFieldToggleView: View {
+    let name: String
+    @Binding var value: String
+    @Binding var mode: SecretFieldInput.Mode
+    @Environment(\.fontScale) var fontScale
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 4) {
+            HStack {
+                Text(name)
+                    .font(.scaledMonospaced(.caption, scale: fontScale))
+                    .foregroundStyle(.secondary)
+                Spacer()
+                Picker("", selection: $mode) {
+                    Text("Value").tag(SecretFieldInput.Mode.value)
+                    Text("Secret").tag(SecretFieldInput.Mode.secret)
+                }
+                .pickerStyle(.segmented)
+                .labelsHidden()
+                .frame(width: 140)
+                .accessibilityIdentifier("secret-toggle-mode-\(name)")
+            }
+            if mode == .secret {
+                SecureField("Secret value", text: $value)
+                    .textFieldStyle(.roundedBorder)
+                    .accessibilityIdentifier("secret-toggle-value-\(name)")
+            } else {
+                TextField("Value", text: $value)
+                    .textFieldStyle(.roundedBorder)
+                    .accessibilityIdentifier("secret-toggle-value-\(name)")
+            }
+        }
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift b/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
deleted file mode 100644
index 9b59da61e..000000000
--- a/native/macos/MCPProxy/MCPProxy/Views/ServerBrowseView.swift
+++ /dev/null
@@ -1,410 +0,0 @@
-// ServerBrowseView.swift
-// MCPProxy
-//
-// macOS-tray mirror of the Web UI R1 feature: a MULTISELECT registry filter
-// plus cross-registry server search. The user ticks one or more registries,
-// searches, and sees a merged, registry-attributed result list. Registries
-// that need an API key / are unreachable are surfaced as a non-fatal notice so
-// the registries that DID return still render. Each result can be added
-// (new servers follow the global quarantine default — MCP-1072).
-
-import SwiftUI
-
-struct ServerBrowseView: View {
-    @ObservedObject var appState: AppState
-    @Environment(\.fontScale) var fontScale
-
-    /// Registries to offer in the multiselect (loaded by the parent view).
-    let registries: [Registry]
-
-    @State private var selectedIDs: Set<String> = []
-    @State private var query: String = ""
-    @State private var results: [RepositoryServer] = []
-    @State private var unavailable: [String] = []
-    @State private var isSearching = false
-    @State private var searchError: String?
-    /// Keyed by `RepositoryServer.addedKey` ("registry::id"), same as
-    /// `addedServers` below — review round 6, finding 2 follow-up (zcode):
-    /// keying this by bare `server.id` let two colliding cards from
-    /// different registries (MCP-866) show each other's spinner while only
-    /// one of them was actually being added.
-    @State private var addingID: String?
-    @State private var addNote: String?
-    /// Spec 109 FR-063: server.addedKey ("registry::id", not the bare
-    /// server.id — review round 6, finding 2) -> the added server's name, so
-    /// the button can flip to "Added ✓ · Open" and stay that way for the rest
-    /// of this browse session.
-    @State private var addedServers: [String: String] = [:]
-    @State private var registryInfo: RegistryInfoContext?
-
-    private var apiClient: APIClient? { appState.apiClient }
-
-    /// Identifiable context for the registry-info popup (`.sheet(item:)`). Holds
-    /// the looked-up `Registry` (nil when the result's label matched nothing in
-    /// the loaded list) plus the raw `label` so the popup always has a title.
-    struct RegistryInfoContext: Identifiable {
-        let id = UUID()
-        let registry: Registry?
-        let label: String
-    }
-
-    private func registryName(_ id: String) -> String {
-        registries.first { $0.id == id }?.name ?? id
-    }
-
-    private var selectionLabel: String {
-        let n = selectedIDs.count
-        if n == 0 { return "Choose registries…" }
-        if n == 1 { return registryName(selectedIDs.first!) }
-        if !registries.isEmpty, n == registries.count { return "All registries (\(n))" }
-        return "\(n) registries"
-    }
-
-    var body: some View {
-        VStack(alignment: .leading, spacing: 8) {
-            filterBar
-
-            if !unavailable.isEmpty {
-                Label("Some registries returned no results: \(unavailable.joined(separator: "; "))",
-                      systemImage: "exclamationmark.triangle.fill")
-                    .font(.scaled(.caption, scale: fontScale))
-                    .foregroundStyle(.orange)
-                    .padding(.horizontal)
-                    .accessibilityIdentifier("browse-unavailable-notice")
-            }
-
-            if let note = addNote {
-                Text(note)
-                    .font(.scaled(.caption, scale: fontScale))
-                    .foregroundStyle(.secondary)
-                    .padding(.horizontal)
-                    .accessibilityIdentifier("browse-add-note")
-            }
-
-            resultsArea
-        }
-        // Results fill all remaining vertical space so discovery is the
-        // dominant region of the pane (MCP-1078).
-        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
-        .accessibilityIdentifier("server-browse")
-        .sheet(item: $registryInfo) { ctx in
-            registryInfoSheet(ctx)
-        }
-    }
-
-    // MARK: Registry-info popup (MCP-1050)
-
-    @ViewBuilder
-    private func registryInfoSheet(_ ctx: RegistryInfoContext) -> some View {
-        let displayName = ctx.registry.map { $0.name.isEmpty ? $0.id : $0.name } ?? ctx.label
-        VStack(alignment: .leading, spacing: 14) {
-            HStack(spacing: 8) {
-                Text(displayName)
-                    .font(.scaled(.title3, scale: fontScale).bold())
-                if let reg = ctx.registry { RegistryProvenanceBadge(isCustom: reg.isCustom) }
-                Spacer()
-                Button {
-                    registryInfo = nil
-                } label: {
-                    Image(systemName: "xmark.circle.fill").foregroundStyle(.secondary)
-                }
-                .buttonStyle(.borderless)
-                .accessibilityIdentifier("registry-info-close")
-            }
-
-            if let reg = ctx.registry {
-                if let desc = reg.description, !desc.isEmpty {
-                    Text(desc)
-                        .font(.scaled(.subheadline, scale: fontScale))
-                        .foregroundStyle(.secondary)
-                        .fixedSize(horizontal: false, vertical: true)
-                }
-
-                if let url = reg.serversURL ?? reg.url, !url.isEmpty {
-                    VStack(alignment: .leading, spacing: 2) {
-                        Text("URL")
-                            .font(.scaled(.caption2, scale: fontScale))
-                            .foregroundStyle(.secondary)
-                        Text(url)
-                            .font(.scaledMonospaced(.caption, scale: fontScale))
-                            .foregroundStyle(.tertiary)
-                            .textSelection(.enabled)
-                            .lineLimit(2)
-                            .truncationMode(.middle)
-                    }
-                }
-
-                Text(reg.isCustom
-                     ? "A custom registry you added. Servers you install follow your global security settings."
-                     : "A built-in registry shipped with MCPProxy.")
-                    .font(.scaled(.caption, scale: fontScale))
-                    .foregroundStyle(.secondary)
-                    .fixedSize(horizontal: false, vertical: true)
-                    .accessibilityIdentifier("registry-info-provenance-note")
-            } else {
-                Text("No additional details are available for this registry.")
-                    .font(.scaled(.subheadline, scale: fontScale))
-                    .foregroundStyle(.secondary)
-            }
-
-            Spacer(minLength: 0)
-        }
-        .padding()
-        .frame(width: 420, height: 220)
-        .accessibilityIdentifier("registry-info-popup")
-    }
-
-    // MARK: Filter bar (multiselect + search)
-
-    @ViewBuilder
-    private var filterBar: some View {
-        HStack(spacing: 8) {
-            Menu {
-                if registries.count > 1 {
-                    Button("Select all") { selectedIDs = Set(registries.map(\.id)) }
-                    Button("Clear") { selectedIDs.removeAll() }
-                    Divider()
-                }
-                ForEach(registries) { registry in
-                    Button {
-                        toggle(registry.id)
-                    } label: {
-                        Label(
-                            registry.name,
-                            systemImage: selectedIDs.contains(registry.id) ? "checkmark.square.fill" : "square"
-                        )
-                    }
-                    .accessibilityIdentifier("browse-registry-option-\(registry.id)")
-                }
-            } label: {
-                Label(selectionLabel, systemImage: "line.3.horizontal.decrease.circle")
-            }
-            .frame(minWidth: 160)
-            .accessibilityIdentifier("browse-registry-multiselect")
-
-            TextField("Search servers by name or description…", text: $query)
-                .textFieldStyle(.roundedBorder)
-                .onSubmit { Task { await search() } }
-                .accessibilityIdentifier("browse-search-input")
-
-            Button {
-                Task { await search() }
-            } label: {
-                if isSearching { ProgressView().controlSize(.small) } else { Text("Search") }
-            }
-            .keyboardShortcut(.defaultAction)
-            .disabled(selectedIDs.isEmpty || isSearching || apiClient == nil)
-            .accessibilityIdentifier("browse-search-button")
-        }
-        .padding(.horizontal)
-        .padding(.top, 8)
-    }
-
-    private func toggle(_ id: String) {
-        if selectedIDs.contains(id) { selectedIDs.remove(id) } else { selectedIDs.insert(id) }
-    }
-
-    // MARK: Results
-
-    @ViewBuilder
-    private var resultsArea: some View {
-        if isSearching {
-            VStack { Spacer(); ProgressView("Searching…"); Spacer() }
-                .frame(maxWidth: .infinity, maxHeight: .infinity)
-        } else if let err = searchError {
-            Label(err, systemImage: "xmark.octagon.fill")
-                .foregroundStyle(.red)
-                .font(.scaled(.callout, scale: fontScale))
-                .padding()
-                .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .top)
-                .accessibilityIdentifier("browse-error")
-        } else if results.isEmpty {
-            Text(selectedIDs.isEmpty ? "Pick one or more registries, then search."
-                                     : "No servers found. Try a different search.")
-                .foregroundStyle(.secondary)
-                .font(.scaled(.callout, scale: fontScale))
-                .padding(.horizontal)
-                .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .top)
-                .accessibilityIdentifier("browse-empty")
-        } else {
-            HStack {
-                Text("Found \(results.count) server(s)" + (selectedIDs.count > 1 ? " across \(selectedIDs.count) registries" : ""))
-                    .font(.scaled(.caption, scale: fontScale))
-                    .foregroundStyle(.secondary)
-                Spacer()
-            }
-            .padding(.horizontal)
-            .accessibilityIdentifier("browse-results-count")
-
-            ScrollView {
-                VStack(alignment: .leading, spacing: 8) {
-                    // Keyed by addedKey ("registry::id"), not the Identifiable
-                    // conformance's bare id: two colliding cards from
-                    // different registries (MCP-866) both surviving
-                    // search()'s registry-qualified dedupe would otherwise
-                    // share one SwiftUI identity here — undefined-behavior
-                    // view diffing, and colliding accessibility identifiers
-                    // below (review round 6, finding 2 follow-up, zcode).
-                    ForEach(results, id: \.addedKey) { server in
-                        serverCard(server)
-                    }
-                }
-                .padding(.horizontal)
-                .padding(.bottom, 8)
-            }
-            .frame(maxHeight: .infinity)
-        }
-    }
-
-    @ViewBuilder
-    private func serverCard(_ server: RepositoryServer) -> some View {
-        VStack(alignment: .leading, spacing: 4) {
-            HStack(alignment: .top) {
-                Text(server.name)
-                    .font(.scaled(.headline, scale: fontScale))
-                    .fixedSize(horizontal: false, vertical: true)
-                Spacer()
-                if let reg = server.registry, !reg.isEmpty {
-                    // Tappable: opens an info popup for the originating registry
-                    // (name/url/description/provenance) — MCP-1050.
-                    Button {
-                        registryInfo = RegistryInfoContext(
-                            registry: Registry.lookup(reg, in: registries), label: reg)
-                    } label: {
-                        HStack(spacing: 3) {
-                            Text(reg)
-                            Image(systemName: "info.circle")
-                                .font(.system(size: 9 * fontScale))
-                        }
-                        .font(.scaled(.caption2, scale: fontScale))
-                        .padding(.horizontal, 6).padding(.vertical, 2)
-                        .background(Color.secondary.opacity(0.15))
-                        .clipShape(Capsule())
-                    }
-                    .buttonStyle(.plain)
-                    .help("Show registry info")
-                    .accessibilityIdentifier("browse-source-\(server.id)")
-                }
-            }
-            if let desc = server.description, !desc.isEmpty {
-                Text(desc).font(.scaled(.caption, scale: fontScale))
-                    .foregroundStyle(.secondary).lineLimit(3)
-            }
-            HStack(spacing: 6) {
-                Text(server.transport)
-                    .font(.system(.caption2, design: .monospaced))
-                    .padding(.horizontal, 6).padding(.vertical, 2)
-                    .overlay(Capsule().stroke(Color.secondary.opacity(0.4)))
-                    .accessibilityIdentifier("browse-transport-\(server.id)")
-                if let inputs = server.requiredInputs, !inputs.isEmpty {
-                    Text("requires input")
-                        .font(.caption2)
-                        .padding(.horizontal, 6).padding(.vertical, 2)
-                        .overlay(Capsule().stroke(Color.secondary.opacity(0.4)))
-                }
-                Spacer()
-                // Spec 109 FR-063: "Add to MCPProxy", flipping to a
-                // persistent "Added ✓ · Open" once the add succeeds.
-                if let addedName = addedServers[server.addedKey] {
-                    Button {
-                        openServer(addedName)
-                    } label: {
-                        Text("Added ✓ · Open")
-                    }
-                    .controlSize(.small)
-                    .accessibilityIdentifier("browse-added-\(server.id)")
-                } else {
-                    Button {
-                        Task { await add(server) }
-                    } label: {
-                        if addingID == server.addedKey { ProgressView().controlSize(.small) } else { Text("Add to MCPProxy") }
-                    }
-                    .controlSize(.small)
-                    .disabled(addingID != nil || server.registry == nil)
-                    .accessibilityIdentifier("browse-add-\(server.id)")
-                }
-            }
-        }
-        .padding(10)
-        .background(Color.secondary.opacity(0.06))
-        .clipShape(RoundedRectangle(cornerRadius: 8))
-        .accessibilityIdentifier("browse-server-\(server.id)")
-    }
-
-    // MARK: Actions
-
-    /// Cross-registry search: fan out to every selected registry (sequentially —
-    /// a handful of registries, and it keeps us clear of Sendable concerns),
-    /// merge + dedupe results, and collect per-registry failures as a non-fatal
-    /// notice. A hard error is raised only when every selected registry fails.
-    private func search() async {
-        let ids = Array(selectedIDs)
-        guard !ids.isEmpty, let client = apiClient else { return }
-        let q = query
-        isSearching = true
-        searchError = nil
-        unavailable = []
-        addNote = nil
-
-        var merged: [RepositoryServer] = []
-        var seen = Set<String>()
-        var failures: [String] = []
-
-        for id in ids {
-            do {
-                let resp = try await client.searchRegistryServers(registryID: id, query: q)
-                if let u = resp.unavailable {
-                    failures.append("\(registryName(id)): \(u.reason ?? "unavailable")")
-                }
-                for s in resp.servers ?? [] {
-                    let key = "\(s.registry ?? id)::\(s.id)"
-                    if seen.contains(key) { continue }
-                    seen.insert(key)
-                    merged.append(s)
-                }
-            } catch {
-                failures.append("\(registryName(id)): \(error.localizedDescription)")
-            }
-        }
-
-        results = merged
-        unavailable = failures
-        if merged.isEmpty, !failures.isEmpty, failures.count == ids.count {
-            searchError = "No results — " + failures.joined(separator: "; ")
-        }
-        isSearching = false
-    }
-
-    /// Spec 109 FR-063: "Added ✓ · Open" opens the server it just added.
-    private func openServer(_ name: String) {
-        NotificationCenter.default.post(name: .switchToServers, object: nil)
-        DispatchQueue.main.asyncAfter(deadline: .now() + 0.3) {
-            NotificationCenter.default.post(name: .showServerDetail, object: name)
-        }
-    }
-
-    private func add(_ server: RepositoryServer) async {
-        guard let client = apiClient, let reg = server.registry else { return }
-        addingID = server.addedKey
-        addNote = nil
-        let result = await client.addServerFromRegistry(registryID: reg, serverID: server.id)
-        if result.success {
-            // The backend can assign a different name than the catalog entry's
-            // own (empty name falls back to the entry id) — key "Added
-            // checkmark Open" on what it actually assigned, or Open silently
-            // no-ops (review round 1; the Web UI's Repositories.vue already
-            // does `result.server?.name || server.name`). A name COLLISION is
-            // NOT de-duplicated — it hard-fails the add (see the `else`
-            // branch below), so `result.success` is false and this branch
-            // does not run (review round 2, finding 7).
-            let assignedName = result.serverName ?? server.name
-            addNote = "Added “\(server.name)”. New servers start quarantined — review under Servers."
-            addedServers[server.addedKey] = assignedName
-        } else if let missing = result.missingInputs, !missing.isEmpty {
-            addNote = "“\(server.name)” needs input: \(missing.joined(separator: ", ")). Add it from the Web UI to supply those values."
-        } else {
-            addNote = "Couldn’t add “\(server.name)”: \(result.message ?? "unknown error")"
-        }
-        addingID = nil
-    }
-}
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ServersView.swift b/native/macos/MCPProxy/MCPProxy/Views/ServersView.swift
index dca8b8a6b..c8d0ffb94 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/ServersView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/ServersView.swift
@@ -55,7 +55,10 @@ struct ServersView: View {
                     .foregroundStyle(.secondary)
 
                 Button {
-                    addServerInitialTab = .importConfig
+                    // Spec 109 FR-062: the generic entry point opens on the
+                    // catalog-first Catalog tab, matching the Web UI default —
+                    // "Import" and "Manual" stay explicit choices below.
+                    addServerInitialTab = .catalog
                     showAddServer = true
                 } label: {
                     Image(systemName: "plus")
@@ -81,7 +84,7 @@ struct ServersView: View {
             // Prominent "Add Server" button bar
             HStack {
                 Button {
-                    addServerInitialTab = .importConfig
+                    addServerInitialTab = .catalog
                     showAddServer = true
                 } label: {
                     Label("Add Server", systemImage: "plus.circle.fill")
@@ -127,7 +130,7 @@ struct ServersView: View {
                             .frame(maxWidth: 300)
                         HStack(spacing: 12) {
                             Button {
-                                addServerInitialTab = .manual
+                                addServerInitialTab = .catalog
                                 showAddServer = true
                             } label: {
                                 Label("Add Server", systemImage: "plus.circle.fill")
@@ -171,7 +174,7 @@ struct ServersView: View {
             if let tab = notification.object as? AddServerTab {
                 addServerInitialTab = tab
             } else {
-                addServerInitialTab = .manual
+                addServerInitialTab = .catalog
             }
             showAddServer = true
         }
diff --git a/native/macos/MCPProxy/MCPProxy/Views/SettingsView.swift b/native/macos/MCPProxy/MCPProxy/Views/SettingsView.swift
index 59591750e..5db26de9d 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/SettingsView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/SettingsView.swift
@@ -31,16 +31,22 @@ struct SettingsView: View {
             GeneralConfigTab(store: store)
                 .tabItem { Label("General", systemImage: "gearshape") }.tag(2)
 
+            // Spec 109 T109: registry SOURCE management moved here from the
+            // (now-retired) Registries sidebar item — server discovery lives
+            // in the Add Server sheet's Catalog tab instead.
+            CatalogSourcesTab(appState: appState)
+                .tabItem { Label("Catalog Sources", systemImage: "books.vertical") }.tag(3)
+
             AdvancedSettingsTab(store: store)
-                .tabItem { Label("Advanced", systemImage: "slider.horizontal.3") }.tag(3)
+                .tabItem { Label("Advanced", systemImage: "slider.horizontal.3") }.tag(4)
 
             RawConfigTab(store: store)
-                .tabItem { Label("Raw", systemImage: "curlybraces") }.tag(4)
+                .tabItem { Label("Raw", systemImage: "curlybraces") }.tag(5)
         }
         .frame(minWidth: 540, minHeight: 560)
-        // ⌘1–⌘5 switch tabs (handy, and lets UI tests navigate).
+        // ⌘1–⌘6 switch tabs (handy, and lets UI tests navigate).
         .background {
-            ForEach(0..<5, id: \.self) { i in
+            ForEach(0..<6, id: \.self) { i in
                 Button("") { tab = i }
                     .keyboardShortcut(KeyEquivalent(Character(String(i + 1))), modifiers: .command)
                     .opacity(0)
diff --git a/native/macos/MCPProxy/MCPProxyTests/CatalogTests.swift b/native/macos/MCPProxy/MCPProxyTests/CatalogTests.swift
index 42e60734c..b61405832 100644
--- a/native/macos/MCPProxy/MCPProxyTests/CatalogTests.swift
+++ b/native/macos/MCPProxy/MCPProxyTests/CatalogTests.swift
@@ -152,4 +152,95 @@ final class CatalogTests: XCTestCase {
             XCTAssertFalse(SecretLikeName.looksSecret(name), name)
         }
     }
+
+    // MARK: - Secret refs decode (FR-065 taken-name check)
+
+    func testDecodesSecretRefsResponse() throws {
+        let json = """
+        {"refs": [{"type": "keyring", "name": "github-env-api-key", "original": "${keyring:github-env-api-key}"}], "count": 1}
+        """
+        let resp = try decode(SecretRefsResponse.self, from: json)
+        XCTAssertEqual(resp.refs.first?.name, "github-env-api-key")
+        XCTAssertEqual(resp.refs.first?.type, "keyring")
+    }
+
+    // MARK: - Import preview decode (FR-064, Paste tab)
+
+    func testDecodesImportPreviewWithEnvFields() throws {
+        let json = """
+        {"format": "url", "imported": [{"name": "fetch", "protocol": "http", "url": "https://api.example.com/mcp",
+         "summary": "https://api.example.com/mcp", "tags": ["remote"],
+         "headers": [{"name": "Authorization", "secret_like": true, "empty_or_placeholder": false}]}]}
+        """
+        let resp = try decode(ImportPreviewResponse.self, from: json)
+        XCTAssertEqual(resp.format, "url")
+        XCTAssertEqual(resp.imported.first?.name, "fetch")
+        XCTAssertEqual(resp.imported.first?.url, "https://api.example.com/mcp")
+        XCTAssertEqual(resp.imported.first?.headers?.first?.name, "Authorization")
+        XCTAssertEqual(resp.imported.first?.headers?.first?.secretLike, true)
+        XCTAssertNil(resp.imported.first?.command)
+    }
+
+    func testDecodesImportPreviewStdioWithEnvFields() throws {
+        let json = """
+        {"format": "command", "imported": [{"name": "server-filesystem", "protocol": "stdio",
+         "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"],
+         "env": [{"name": "GITHUB_TOKEN", "secret_like": true, "empty_or_placeholder": true}]}]}
+        """
+        let resp = try decode(ImportPreviewResponse.self, from: json)
+        XCTAssertEqual(resp.imported.first?.command, "npx")
+        XCTAssertEqual(resp.imported.first?.args, ["-y", "@modelcontextprotocol/server-filesystem"])
+        XCTAssertEqual(resp.imported.first?.env?.first?.name, "GITHUB_TOKEN")
+        XCTAssertTrue(resp.imported.first?.env?.first?.emptyOrPlaceholder ?? false)
+    }
+
+    // MARK: - SecretFieldResolver.buildValues (pure assembly, no network)
+
+    func testBuildValuesPassesThroughValueModeFields() {
+        let fields = [SecretFieldInput(name: "PORT", value: "8080", mode: .value)]
+        let (env, headers) = SecretFieldResolver.buildValues(fields: fields, written: [:])
+        XCTAssertEqual(env["PORT"], "8080")
+        XCTAssertTrue(headers.isEmpty)
+    }
+
+    func testBuildValuesSubstitutesKeyringPlaceholderForWrittenSecretFields() {
+        let fields = [SecretFieldInput(name: "API_KEY", value: "sk-live-secret", mode: .secret)]
+        let field = fields[0]
+        let (env, _) = SecretFieldResolver.buildValues(fields: fields, written: [field.id: "github-env-api-key"])
+        XCTAssertEqual(env["API_KEY"], "${keyring:github-env-api-key}")
+        // The raw value never appears in the assembled env map.
+        XCTAssertFalse(env.values.contains("sk-live-secret"))
+    }
+
+    func testBuildValuesMixesValueAndSecretFields() {
+        let fields = [
+            SecretFieldInput(name: "REGION", value: "us-east-1", mode: .value),
+            SecretFieldInput(name: "API_KEY", value: "sk-live-secret", mode: .secret),
+        ]
+        let (env, _) = SecretFieldResolver.buildValues(fields: fields, written: [fields[1].id: "svc-env-api-key"])
+        XCTAssertEqual(env["REGION"], "us-east-1")
+        XCTAssertEqual(env["API_KEY"], "${keyring:svc-env-api-key}")
+    }
+
+    func testBuildValuesRoutesHeaderKindToHeadersMap() {
+        let fields = [
+            SecretFieldInput(name: "Authorization", kind: .header, value: "sk-live-secret", mode: .secret),
+            SecretFieldInput(name: "GITHUB_TOKEN", kind: .env, value: "sk-live-secret", mode: .secret),
+        ]
+        let written = [fields[0].id: "svc-header-authorization", fields[1].id: "svc-env-github-token"]
+        let (env, headers) = SecretFieldResolver.buildValues(fields: fields, written: written)
+        XCTAssertEqual(headers["Authorization"], "${keyring:svc-header-authorization}")
+        XCTAssertEqual(env["GITHUB_TOKEN"], "${keyring:svc-env-github-token}")
+        XCTAssertNil(env["Authorization"])
+        XCTAssertNil(headers["GITHUB_TOKEN"])
+    }
+
+    /// An env field and a header field sharing one NAME must not collide on
+    /// one `field.id` — `SecretFieldInput.id` folds in `kind` precisely so
+    /// `written` can hold both refs independently (FR-065).
+    func testFieldIdentityDistinguishesEnvAndHeaderOfSameName() {
+        let env = SecretFieldInput(name: "API_KEY", kind: .env, value: "a", mode: .secret)
+        let header = SecretFieldInput(name: "API_KEY", kind: .header, value: "b", mode: .secret)
+        XCTAssertNotEqual(env.id, header.id)
+    }
 }
diff --git a/native/macos/MCPProxy/MCPProxyTests/PasteServerFieldsTests.swift b/native/macos/MCPProxy/MCPProxyTests/PasteServerFieldsTests.swift
new file mode 100644
index 000000000..66fa10952
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/PasteServerFieldsTests.swift
@@ -0,0 +1,94 @@
+import XCTest
+@testable import MCPProxy
+
+/// Pure-function seam for the Paste tab (Spec 109 FR-064/065): turning an
+/// import preview into the toggle list (`buildFields`) and turning the
+/// resolved fields into the `POST /api/v1/servers` body (`makeServerConfig`).
+/// Unit-testable without a running app or API client, mirroring
+/// `ManualServerForm`'s `makeServerConfig` seam.
+final class PasteServerFieldsTests: XCTestCase {
+
+    // MARK: - buildFields
+
+    func testBuildFieldsDefaultsSecretLikeEnvVarsToSecretMode() {
+        let server = ImportPreviewServer(
+            name: "fs", protocol: "stdio", url: nil, command: "npx", args: ["-y"],
+            summary: nil, tags: nil,
+            env: [ImportPreviewField(name: "GITHUB_TOKEN", secretLike: true, emptyOrPlaceholder: false),
+                  ImportPreviewField(name: "PORT", secretLike: false, emptyOrPlaceholder: false)],
+            headers: nil
+        )
+        let fields = PasteServerView.buildFields(from: server)
+        XCTAssertEqual(fields.count, 2)
+        XCTAssertEqual(fields.first { $0.name == "GITHUB_TOKEN" }?.mode, .secret)
+        XCTAssertEqual(fields.first { $0.name == "PORT" }?.mode, .value)
+        XCTAssertTrue(fields.allSatisfy { $0.kind == .env })
+    }
+
+    func testBuildFieldsMapsHeadersToHeaderKind() {
+        let server = ImportPreviewServer(
+            name: "remote", protocol: "http", url: "https://api.example.com/mcp", command: nil, args: nil,
+            summary: nil, tags: nil, env: nil,
+            headers: [ImportPreviewField(name: "Authorization", secretLike: true, emptyOrPlaceholder: false)]
+        )
+        let fields = PasteServerView.buildFields(from: server)
+        XCTAssertEqual(fields.count, 1)
+        XCTAssertEqual(fields.first?.kind, .header)
+        XCTAssertEqual(fields.first?.mode, .secret)
+    }
+
+    func testBuildFieldsHandlesBothEnvAndHeaders() {
+        let server = ImportPreviewServer(
+            name: "hybrid", protocol: "http", url: "https://x/mcp", command: nil, args: nil,
+            summary: nil, tags: nil,
+            env: [ImportPreviewField(name: "API_KEY", secretLike: true, emptyOrPlaceholder: false)],
+            headers: [ImportPreviewField(name: "API_KEY", secretLike: true, emptyOrPlaceholder: false)]
+        )
+        let fields = PasteServerView.buildFields(from: server)
+        // Same NAME, different kind — must not collapse to one row.
+        XCTAssertEqual(fields.count, 2)
+        XCTAssertEqual(Set(fields.map(\.id)).count, 2)
+    }
+
+    // MARK: - makeServerConfig
+
+    func testMakeServerConfigForStdioIncludesCommandArgsAndEnv() {
+        let preview = ImportPreviewServer(
+            name: "fs", protocol: "stdio", url: nil, command: "npx", args: ["-y", "server-filesystem"],
+            summary: nil, tags: nil, env: nil, headers: nil
+        )
+        let resolved = ResolvedSecretFields(env: ["GITHUB_TOKEN": "${keyring:fs-env-github-token}"], headers: [:], writtenRefs: ["fs-env-github-token"])
+        let config = PasteServerView.makeServerConfig(preview: preview, resolved: resolved)
+        XCTAssertEqual(config["name"] as? String, "fs")
+        XCTAssertEqual(config["protocol"] as? String, "stdio")
+        XCTAssertEqual(config["command"] as? String, "npx")
+        XCTAssertEqual(config["args"] as? [String], ["-y", "server-filesystem"])
+        XCTAssertEqual((config["env"] as? [String: String])?["GITHUB_TOKEN"], "${keyring:fs-env-github-token}")
+        XCTAssertNil(config["url"])
+        XCTAssertNil(config["headers"])
+    }
+
+    func testMakeServerConfigForURLIncludesHeadersNotEnv() {
+        let preview = ImportPreviewServer(
+            name: "remote", protocol: "http", url: "https://api.example.com/mcp", command: nil, args: nil,
+            summary: nil, tags: nil, env: nil, headers: nil
+        )
+        let resolved = ResolvedSecretFields(env: [:], headers: ["Authorization": "${keyring:remote-header-authorization}"], writtenRefs: ["remote-header-authorization"])
+        let config = PasteServerView.makeServerConfig(preview: preview, resolved: resolved)
+        XCTAssertEqual(config["url"] as? String, "https://api.example.com/mcp")
+        XCTAssertEqual((config["headers"] as? [String: String])?["Authorization"], "${keyring:remote-header-authorization}")
+        XCTAssertNil(config["command"])
+        XCTAssertNil(config["env"])
+    }
+
+    func testMakeServerConfigOmitsEmptyEnvAndHeaders() {
+        let preview = ImportPreviewServer(
+            name: "plain", protocol: "stdio", url: nil, command: "true", args: nil,
+            summary: nil, tags: nil, env: nil, headers: nil
+        )
+        let resolved = ResolvedSecretFields(env: [:], headers: [:], writtenRefs: [])
+        let config = PasteServerView.makeServerConfig(preview: preview, resolved: resolved)
+        XCTAssertNil(config["env"])
+        XCTAssertNil(config["headers"])
+    }
+}

From dbb0bf9286bd37a6928b95c8a420967c7d23a2bb Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 05:39:55 +0300
Subject: [PATCH 22/27] docs(spec): add Spec 110 catalog popularity signal
 (spec, plan, tasks)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ROADMAP.md                            |  1 +
 specs/110-catalog-popularity/plan.md  | 97 +++++++++++++++++++++++++++
 specs/110-catalog-popularity/spec.md  | 95 ++++++++++++++++++++++++++
 specs/110-catalog-popularity/tasks.md | 41 +++++++++++
 4 files changed, 234 insertions(+)
 create mode 100644 specs/110-catalog-popularity/plan.md
 create mode 100644 specs/110-catalog-popularity/spec.md
 create mode 100644 specs/110-catalog-popularity/tasks.md

diff --git a/ROADMAP.md b/ROADMAP.md
index 979964fa1..adfc9614d 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1035,3 +1035,4 @@ Legend: `shipped` ≥95% checked · `in-flight` 1–94% · `drafted` 0% · `—`
 | [105-agent-scope-hardening](./specs/105-agent-scope-hardening/) | `in-flight` | 94/113 (83%) |
 | [106-security-residual-fixes](./specs/106-security-residual-fixes/) | `shipped` | 18/19 (95%) |
 | [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) | `shipped` | 126/126 (100%) |
+| [110-catalog-popularity](./specs/110-catalog-popularity/) | `drafted` | 0/23 (0%) |
diff --git a/specs/110-catalog-popularity/plan.md b/specs/110-catalog-popularity/plan.md
new file mode 100644
index 000000000..8730409a9
--- /dev/null
+++ b/specs/110-catalog-popularity/plan.md
@@ -0,0 +1,97 @@
+# Implementation Plan: Real Popularity Signal for the Catalog
+
+**Branch**: `110-catalog-popularity` (stacked on `109-j-catalog-add-server`, PR #1383) | **Spec**: [spec.md](spec.md)
+
+## Summary
+
+This plan fills in `Popularity` from two real sources. Docker Hub `pull_count` comes free with the listing the Docker parser already fetches. GitHub `stargazers_count` is fetched through a cached, rate-limited provider that stays off the search's critical path. It also redefines the two landing sections so they differ: Official keeps source order, and Popular is ranked by the signal, drawn from the pool before truncation, and de-duplicated by repo.
+
+## Technical Context
+
+Go 1.26, backend-only for PR A. It uses existing dependencies only: `go.etcd.io/bbolt`, `zap`, and `net/http` via `sharedRegistryClient`. **No new dependencies.** Frontend (Vue) and Swift changes are limited to one display helper each (PR B).
+
+## Research & Decisions
+
+| # | Decision | Rationale | Rejected alternatives |
+|---|---|---|---|
+| R1 | **GitHub stars** as the primary signal | `SourceCodeURL` is already filled in for the official-registry and reference sources. MCP directories use it widely. It needs one unauthenticated REST call per repo. | npm downloads (only for npm-packaged stdio servers, and scoped packages cannot use the bulk endpoint). PyPI (pypistats is rate-limited and returns counts on a different scale). |
+| R2 | **Docker `pull_count` → `Installs`**, never `Stars` | It costs nothing (already in the payload, verified live). Docker `star_count` is 9–58 while GitHub has ~80k, so mixing them would be meaningless. | Mapping Docker stars → `Stars` (different scale). |
+| R3 | **Lexicographic `(stars, installs)`** comparison | The two signals cannot be compared directly. Any conversion factor would be made up, and a review would rightly reject it. A lexicographic order is pure and easy to explain. | A sum (the current code — pulls in the millions would swamp stars). Log-normalized blending (arbitrary weights). |
+| R4 | **Own bbolt bucket, not `cache.Manager`** | `cache.Manager` has a fixed 2h TTL (not 6h), deletes expired records (so it cannot serve stale), and adds Spec 105 read_cache authorization frames that are irrelevant here. It would also inflate `read_cache` stats. A small dedicated bucket gets a 24h TTL, serve-stale and ETag storage. | Reusing `cache.Manager` (2h churn × 60/h budget means it never converges). A JSON file in the data dir (another persistence path to maintain, while bbolt is already open). |
+| R5 | **Cache-first, with a bounded wait (800 ms) and background completion** | Warm lookups cost 0 ms. A cold landing still gets most of its stars on the first view, and the rest arrive by the next view. The 5 s per-source budget is untouched. | Fully synchronous (adds GitHub latency to every search). Fully async with no wait (the first landing always has an empty Popular). A startup prewarm job (another lifecycle component — deferred; R5 covers most of the value). |
+| R6 | **Rolling budget of 50/h unauthenticated + header-driven circuit breaker** | 60/h is per IP, so 10 are left for the user's own unauthenticated `gh`/browser use. `X-RateLimit-Remaining`/`Reset` are authoritative (verified live: `x-ratelimit-limit: 60`, `x-ratelimit-reset`). | A token bucket (more code, and the headers already give the exact state). |
+| R7 | **`MCPPROXY_GITHUB_TOKEN`, not `GITHUB_TOKEN`** | Least surprise: a developer's `GITHUB_TOKEN` is often a broad-scope CI or PAT token, so it has to be opted in explicitly. It is only ever sent to the constant host. | Reading `GITHUB_TOKEN`. A config field (5 wiring points; deferred until someone asks). |
+| R8 | **Official section = source-native order** | Every default source is official (so all default hits are official), which means rank order would already be popularity order and the sections would be identical by construction. Source order keeps each registry's own curation (the reference list is hand-ordered). | Alphabetical (arbitrary, starts at "a…"). Excluding Popular items from Official (hides official servers). |
+| R9 | **Popular: one hit per repo** | The 7 reference servers share `modelcontextprotocol/servers` and would otherwise take 7 of the 12 slots. | Counting no stars for monorepo subpaths (drops genuinely popular servers). |
+
+## Data Model
+
+```go
+// types.go
+type ServerEntry struct { …; Popularity *Popularity `json:"-"` } // FR-001: source-native, never marshalled
+
+// popularity.go
+type PopularityProvider interface {
+    // Lookup returns the cached stars for a repo key without I/O. stale=true
+    // means past TTL (still usable); ok=false means never fetched / negative.
+    Lookup(key string) (stars int, ok bool, stale bool)
+    // Resolve enqueues misses/stale keys (in priority order) and waits up to
+    // wait (bounded by ctx) for them; fetching continues after it returns.
+    Resolve(ctx context.Context, keys []string, wait time.Duration)
+}
+
+// popularity_github.go
+type githubStarsProvider struct {
+    mu        sync.Mutex
+    entries   map[string]*starsEntry  // memory front
+    store     starsStore              // nil = memory only; bbolt impl
+    queue     chan string             // cap 256
+    queued    map[string]chan struct{} // dedup + completion signal
+    budget    rollingBudget           // 50/h or 4000/h
+    pausedTil time.Time               // breaker
+    token     string
+    baseURL   string                  // const; test hook overrides
+    now       func() time.Time        // test clock
+}
+type starsEntry struct {
+    Stars     int       `json:"stars"`
+    ETag      string    `json:"etag,omitempty"`
+    FetchedAt time.Time `json:"fetched_at"`
+    Status    int       `json:"status"` // 200/304 ok, 404/451 negative, else error
+}
+```
+
+bbolt bucket `catalog_popularity`: key = `o/r` (lower-case), value = JSON `starsEntry`. Entries are loaded into memory lazily on the first `Lookup` miss. Writes go through synchronously after each fetch (they are rare, ≤50/h). A new key over the cap evicts the oldest `FetchedAt`.
+
+## Flow
+
+```
+SearchAll(q)
+  fan-out (5s/source) ─► BuildCatalogHit: hit.Popularity = entry.Popularity (docker pulls)
+                                           + cache-only Lookup(GitHubRepoKey(entry.SourceCodeURL))
+  merge + dedup + source filter ─► pool
+  sort pool by Rank; keys := repo keys of pool hits (rank order) lacking fresh stars
+  provider.Resolve(ctx, keys, opts.PopularityWait)   // ≤800ms, never beyond ctx
+  re-apply Lookup to pool hits; re-sort by Rank
+  sections = buildSections(pool)   // BEFORE truncation (FR-005)
+  results  = pool[:limit]
+```
+
+## Wiring
+
+| Site | Change |
+|---|---|
+| `internal/runtime/runtime.go` (near `cache.NewManager`, ~L290) | `registries.SetPopularityProvider(registries.NewGitHubStarsProvider(registries.PopularityOptions{DB: storageManager.GetDB(), Logger: logger}))` unless the kill switch is set. `Close()` on shutdown stops the workers. |
+| `cmd/mcpproxy/catalog_cmd.go` `catalogSearch` in-process fallback and `catalog show` | Memory-only provider (`DB: nil`). |
+| `internal/registries/testhooks.go` | `SetPopularityProviderForTest`, `SetGitHubAPIBaseForTest`. |
+| E2E | `scripts/test-api-e2e.sh` exports `MCPPROXY_CATALOG_POPULARITY=false`, so E2E never calls api.github.com. |
+
+## PR slicing
+
+- **PR A (backend, this branch)**: FR-001…FR-011, SC-001…SC-005. Base `109-j-catalog-add-server`.
+- **PR B (display)**: FR-012. Web UI `CatalogSearch.vue` badge + vitest, Swift `CatalogView` badge + `CatalogTests`, CLI table column. Stacked on A.
+
+## Risks
+
+- **Stacking on an open PR.** 109-j is still in review, and round 5 made local-only changes (`16f9e8c9c` is not pushed). PR A touches `catalog.go` `SearchAll`/`buildSections`, so it may conflict when 109-j's later rounds land. Mitigation: keep catalog.go edits confined to those two functions plus `BuildCatalogHit`/`Rank`, and rebase once 109-j merges.
+- **Section semantics change** (Official is no longer popularity-sorted). This is an intentional amendment of 109 FR-060. Existing 109 tests that assert Official order must be updated to source order, not deleted.
diff --git a/specs/110-catalog-popularity/spec.md b/specs/110-catalog-popularity/spec.md
new file mode 100644
index 000000000..4a5437ffa
--- /dev/null
+++ b/specs/110-catalog-popularity/spec.md
@@ -0,0 +1,95 @@
+# Feature Specification: Real Popularity Signal for the Catalog
+
+**Feature Branch**: `110-catalog-popularity`
+**Created**: 2026-09-26
+**Status**: Draft
+**Input**: User description: "The Popularity struct and CatalogHit.Popularity are declared and consumed by Rank()'s popularity tiebreak and buildSections' Popular landing section, but no production code path ever populates them. The FR-060 tiebreak always compares 0-vs-0 and the empty-query Popular section renders identically to Official. Spec and implement a real popularity signal: pick a concrete source (GitHub stars via SourceCodeURL), design fetch + cache + rate-limit handling, wire it into BuildCatalogHit, and add tests proving Popular differs meaningfully from Official once real data exists."
+
+**Related**: Spec 109 (UX navigation consistency) FR-060 / FR-061 and data-model §9, PR #1383 (`109-j-catalog-add-server`, the branch this stacks on). The finding was raised and deferred twice in 109-j review rounds (1 and 5) as out of scope for a review fix. This spec amends 109 FR-060's definition of the landing sections. The rest of 109 is unchanged.
+
+## Context & Motivation
+
+These facts were checked at `origin/109-j-catalog-add-server` `b1ddae539`:
+
+1. **Nothing sets `Popularity`.** `BuildCatalogHit` (`internal/registries/catalog.go:227`) does not set it. `ServerEntry` (`types.go`) has no field for it, and none of the parsers (`official.go`, `reference.go`, `search.go` `parseDocker`/`parsePulse…`) read one. Every `popularityScore` is therefore 0.
+2. **The Popular section is built from a truncated list.** `SearchAll` truncates the ranked pool to `limit` *before* it calls `buildSections(all)` (`catalog.go:190-199`). `Rank` sorts official hits first, so once there are `limit` or more official hits, Popular is a reordering of the same hits Official already shows. Real stars alone would not change that.
+3. **Every default source is official, so the two sections cannot differ.** All three default sources (`official`, `reference`, `docker-mcp-catalog`, `internal/config/config.go:1664`) have `Provenance: official`, which means every default hit has `Official = Verified = true`. `Rank`'s third key is popularity, so the Official section ("official hits in rank order") is *already ordered by popularity*. On a default install, Popular would equal Official in both membership and order even with correct star counts.
+4. **The data exists at no cost for one source.** Docker Hub's `GET /v2/repositories/mcp/` response, which `parseDocker` already fetches, includes `pull_count` for every image (checked live 2026-09-26: `mcp/fetch` 1,863,661 pulls; 245 images). The parser throws it away.
+5. **Most other hits have a GitHub URL.** Official-registry entries carry `repository.url` → `SourceCodeURL` (`official.go:245`), and every reference server links into `github.com/modelcontextprotocol/servers`. GitHub's REST API (`GET /repos/{owner}/{repo}` → `stargazers_count`) allows **60 requests/hour per IP without a token** and 5,000 with one.
+6. **The suggested cache does not fit.** `cache.Manager` (`internal/cache/manager.go`) stores `read_cache` tool responses. Its TTL is a fixed `DefaultTTL = 2h`, not 6h, and cannot be set per record. Its records carry Spec 105 authorization frames, and its cleanup sweep deletes expired entries. Refreshing every star count every 2h would exceed the unauthenticated budget with ~120 repos, and deleting expired entries rules out serve-stale.
+7. **No surface shows the numbers yet.** The Web UI (`CatalogSearch.vue`), macOS (`CatalogView.swift`) and the CLI table do not render `popularity`, even though 109 FR-061 says each result shows "stars or installs when the source provides them".
+
+## Scope Boundary
+
+| Already exists | Reused, not rebuilt |
+|---|---|
+| `Popularity{Stars,Installs}`, `CatalogHit.Popularity`, `CatalogResult.Popularity`, the MCP `mcpCatalogServerEntry.Popularity`, TS `CatalogPopularity`, Swift `CatalogPopularity` | Types and wire shape unchanged (`popularity: {stars?, installs?}`, omitempty) |
+| `Rank` (FR-060 ordering) | Keys unchanged. Only the popularity comparison changes from "sum" to "stars, then installs" (FR-004) |
+| Registry SSRF-hardened client (`sharedRegistryClient`: dial-time private-IP block, redirect host pin, body cap) | Used for the GitHub fetch as is |
+| `registries` package-level wiring (`SetVersion`, `SetRegistriesFromConfig`, `SetRegistriesForTest`) | The popularity provider is installed the same way (FR-010) |
+| BBolt `config.db` via `storageManager.GetDB()` | A new bucket `catalog_popularity`. `cache.Manager` is not reused (fact 6) |
+
+**Out of scope**: npm/PyPI download counts (a follow-up could add them as more `Installs` sources), GitHub GraphQL batching (requires a token), a config-file knob (env only in v1, see FR-011), telemetry, and changes to `Rank`'s key order.
+
+## User Scenarios & Testing
+
+### User Story 1 — Popular means popular (Priority: P1)
+
+A user opens the Catalog with no query and sees an **Official** section (what the official sources list, in their own order) and a **Popular** section (the most-starred or most-pulled servers across every source). The two sections are visibly different lists.
+
+**Independent test**: use fixture sources with ≥12 official hits and known star/pull counts. Popular should be ordered by popularity, should include a high-star hit that falls outside Official's first 12, and should differ from Official in membership or order.
+
+1. **Given** real popularity for at least one hit, **When** q is empty, **Then** Popular contains only hits with a known signal, ordered stars desc, then installs desc, then `Rank`. It is drawn from the full merged pool before `limit` truncation, has at most one hit per GitHub repository, and is capped at 12.
+2. **Given** no popularity is known for any hit (cold cache, GitHub unreachable, no Docker source), **When** q is empty, **Then** Popular is **empty**, not padded with zero-popularity hits, and each surface hides the empty section (Web UI and macOS already do).
+3. **Given** q is empty, **Then** Official lists official-source hits in **source order**: registry list order, then each source's native order. It does not re-rank by popularity and is capped at 12.
+
+### User Story 2 — Popularity breaks ties in search results (Priority: P1)
+
+**Given** the query "github" matches several official hits, **Then** hits with more stars rank above those with fewer (FR-060 key 3), and the returned `popularity` shows the numbers.
+
+### User Story 3 — It never makes the catalog slower or flakier (Priority: P1)
+
+1. **Given** GitHub is slow or down, **Then** `SearchAll` returns within its existing budget plus at most the popularity wait (FR-007), and the affected hits simply have no stars. GitHub is never listed in `unavailable[]`, because it is not a catalog source.
+2. **Given** the unauthenticated rate limit is exhausted, **Then** no further GitHub requests go out until the reset time, and cached values, including expired ones, keep being served.
+
+### User Story 4 — Users see the numbers (Priority: P2)
+
+The Web UI result row, the macOS catalog row and the CLI `catalog search` table show `★ 21.3k` or `⤓ 1.2M` when popularity is known, and nothing when it is not.
+
+### Edge cases
+
+- SourceCodeURL forms: `https://github.com/o/r`, `…/r.git`, `…/r/tree/main/src/x` (monorepo subpath), `git+https://…`, `http://`, `www.github.com`, a trailing slash, and mixed case. All of them normalize to the key `o/r` (lower-cased). Non-GitHub hosts, gist URLs, and owners or repos that fail GitHub's name rules produce no key and never cause a fetch.
+- A monorepo (`modelcontextprotocol/servers`) gives its star count to every server that links into it. Popular shows only one of them (the first by `Rank`). Search tiebreaks still use the repo's count.
+- A repo that returns 404 or 451 is negatively cached and shows no stars. A renamed repo's 301 (`/repositories/{id}`, same host) is followed, because the registry client pins redirects to the host only.
+- The same `(source,id)` from two sources is already de-duplicated by `SearchAll`. The same repo from two different sources is fetched once, via one cache key.
+
+## Requirements
+
+### Functional Requirements
+
+- **FR-001 (source-native signal)**: `parseDocker` MUST set `Installs = pull_count` when the field is a non-negative number. Docker Hub `star_count` MUST NOT be mapped to `Stars`, because it is on a different scale from GitHub stars. The value travels on a new `ServerEntry.Popularity *Popularity` field tagged `json:"-"`, so `ServerEntry`'s JSON (GET `/registries/{id}/servers`, `search_servers` with `registry`) stays unchanged.
+- **FR-002 (BuildCatalogHit)**: `BuildCatalogHit` MUST copy `entry.Popularity` into the hit and fill in `Stars` from the installed provider's **cache only**, with no network call. It stays synchronous and never blocks.
+- **FR-003 (repo key)**: A pure `GitHubRepoKey(sourceCodeURL) (key string, ok bool)` MUST normalize the edge-case forms above. Owner: `^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$`. Repo: `^[A-Za-z0-9._-]{1,100}$`, excluding `.` and `..`. Any other input returns `ok=false`.
+- **FR-004 (comparison)**: `Rank` and the Popular ordering MUST compare popularity as `(stars desc, installs desc)`, with missing = 0. Stars and installs are never added together or converted into each other.
+- **FR-005 (sections)**: `buildSections` MUST take the full merged, de-duplicated, source-filtered pool **before** `limit` truncation. Official = official hits in merge (source-native) order, at most 12. Popular = hits with `stars>0 ∨ installs>0`, sorted per FR-004 and then `Rank`, at most one per GitHub repo key, at most 12. This amends Spec 109 FR-060 and data-model §9.
+- **FR-006 (fetch)**: The GitHub fetcher MUST send `GET https://api.github.com/repos/{owner}/{repo}` through the SSRF-hardened registry client. The host is a compile-time constant, overridable only by a test hook. The request carries `Accept: application/vnd.github+json`, `X-GitHub-Api-Version: 2022-11-28`, the versioned mcpproxy User-Agent, and `If-None-Match` when an ETag is cached. The response body is capped at 1 MiB and each request has a 10 s timeout. Only `stargazers_count` and `ETag` are read.
+- **FR-007 (never block the search)**: `SearchAll` MUST resolve popularity *after* the per-source fan-out. Cached values come back immediately. Misses are queued for a background fetch, and `SearchAll` waits for them for at most `SearchOptions.PopularityWait`: default 800 ms, 0 disables the wait, and the wait never outlives `ctx`. Misses still outstanding keep being fetched after `SearchAll` returns, so the next search has them. Popularity failures never add entries to `unavailable[]`.
+- **FR-008 (cache)**: Each entry `{stars, etag, fetched_at, status}` MUST be kept in memory and persisted to the bbolt bucket `catalog_popularity` when a store is attached. The entry is fresh for 24 h after a 200 or 304, 24 h after a 404 or 451 (negative), and 1 h after any other error. Expired entries are still served (stale-while-revalidate) and queued for refresh. The store is capped at 5,000 keys, evicting the oldest `fetched_at` first.
+- **FR-009 (rate limit)**: The fetcher MUST (a) run at most 4 requests at once; (b) de-duplicate in-flight and queued keys, with a queue capped at 256 so overflow is dropped and requested again on the next search; (c) spend at most 50 requests per rolling hour without a token and 4,000 with one; (d) stop all fetches until `X-RateLimit-Reset` when `X-RateLimit-Remaining` ≤ 5, or on 403/429 with `Retry-After` or `X-RateLimit-Remaining: 0` (using `Retry-After`, or 60 s when neither header is present); (e) fetch misses in the order `SearchAll` ranked them.
+- **FR-010 (wiring)**: `registries.SetPopularityProvider(p)` installs the process-wide provider, and `nil` turns lookups off. The core runtime installs a provider backed by bbolt at startup. The CLI in-process fallback (`catalogSearch` when no daemon is running, and `catalog show`) installs a memory-only one. Tests use `SetPopularityProviderForTest`, which returns a restore func.
+- **FR-011 (token & kill switch)**: If `MCPPROXY_GITHUB_TOKEN` is set, it is sent as `Authorization: Bearer …`, only to the constant GitHub API host. The generic `GITHUB_TOKEN` is deliberately **not** read, to avoid leaking an unrelated CI or dev token. `MCPPROXY_CATALOG_POPULARITY=false` (or `0`/`off`) turns off all outbound popularity fetches. Source-native Docker pulls still show.
+- **FR-012 (display)**: The Web UI, macOS and CLI table MUST show compact popularity (`★ 1.2k`, `⤓ 3.4M`) when it is known. The REST, MCP and CLI JSON shapes are unchanged.
+
+### Success Criteria
+
+- **SC-001**: A fixture test with 14 official hits (one repo with the most stars sits outside the first 12 in source order) and one non-official Docker hit with pulls must show three things. Popular ≠ Official. Popular[0] is the most-starred hit. Popular contains a hit that Official does not.
+- **SC-002**: With no signal known, Popular is empty and Official is unchanged.
+- **SC-003**: With a stub GitHub server that sleeps 5 s, `SearchAll` returns within `PopularityWait` + 100 ms of the fan-out finishing, and a second call after the stub answers carries the stars.
+- **SC-004**: After a 403 response with `X-RateLimit-Remaining: 0` and a reset time in the future, no further requests reach the stub before that reset time, and cached (stale) values are still returned.
+- **SC-005**: Personal and server builds pass lint, and `go test -race ./internal/registries/...` passes. `./scripts/test-api-e2e.sh` passes with popularity turned off, since E2E must not depend on api.github.com.
+
+## Assumptions
+
+- Stars are an adequate proxy for "popular" in the MCP ecosystem. The GitHub star count is the signal most widely used by MCP directories (Glama, PulseMCP, mcp.so).
+- 50 requests per hour covers a default catalog (~60–120 distinct repos) within about 2 hours of the first run, and the persisted cache means a restart costs nothing. Users who want it faster can set `MCPPROXY_GITHUB_TOKEN`.
+- Repository slugs sent to api.github.com are public catalog data, not user data. The kill switch exists for air-gapped or offline setups.
diff --git a/specs/110-catalog-popularity/tasks.md b/specs/110-catalog-popularity/tasks.md
new file mode 100644
index 000000000..0b313e6ec
--- /dev/null
+++ b/specs/110-catalog-popularity/tasks.md
@@ -0,0 +1,41 @@
+# Tasks: Real Popularity Signal for the Catalog
+
+**Input**: [spec.md](spec.md), [plan.md](plan.md). TDD: every task writes its failing test first.
+
+## Phase 1 — Pure pieces (PR A)
+
+- [ ] T001 [P] [US1] `GitHubRepoKey` + table test covering every edge-case form in the spec (`internal/registries/popularity_key.go`, `popularity_key_test.go`) — FR-003
+- [ ] T002 [P] [US1] `parseDocker` maps `pull_count` → `ServerEntry.Popularity.Installs`, ignores `star_count`, and ignores negative or non-numeric values. Add `ServerEntry.Popularity json:"-"` plus a test that `ServerEntry` JSON is unchanged (`search.go`, `types.go`, `search_test.go`) — FR-001
+- [ ] T003 [US2] Replace `popularityScore` sum with `comparePopularity` using (stars, installs). Add rank tests: stars beat installs, installs break ties between equal stars, existing tests stay green (`catalog.go`, `rank_test.go`) — FR-004
+
+## Phase 2 — Provider (PR A)
+
+- [ ] T004 [US3] `PopularityProvider` interface, `SetPopularityProvider`, `SetPopularityProviderForTest`, `SetGitHubAPIBaseForTest` (`popularity.go`, `testhooks.go`) — FR-010
+- [ ] T005 [US3] `githubStarsProvider` fetch against an httptest stub. Cover: 200 (stars + ETag stored), 304 (refresh `FetchedAt`, keep stars), 404 (negative), 500 (1h error TTL), exact request headers, bearer only when `MCPPROXY_GITHUB_TOKEN` is set, body cap, and a 301 redirect on the same host (`popularity_github.go`, `popularity_github_test.go`) — FR-006, FR-011
+- [ ] T006 [US3] TTL, serve-stale and requeue via an injected clock. Cover dedup of queued/in-flight keys, queue overflow drop, concurrency ≤4 (stub counts peak concurrency), rolling budget of 50/h, breaker on `Remaining ≤ 5`, and 403/429 with `Retry-After` (SC-004) — FR-008, FR-009
+- [ ] T007 [US3] bbolt store: round-trip, lazy load, cap eviction, and surviving a provider restart (a temp DB) (`popularity_store.go`, `popularity_store_test.go`) — FR-008
+- [ ] T008 [US3] `Resolve` wait bounds: returns by `wait` and by `ctx` cancel, fetches continue afterwards, and `wait=0` never blocks (SC-003) — FR-007
+- [ ] T009 [US3] Kill switch: with `MCPPROXY_CATALOG_POPULARITY=false` no request ever reaches the stub — FR-011
+
+## Phase 3 — Catalog integration (PR A)
+
+- [ ] T010 [US1] `BuildCatalogHit` copies `entry.Popularity` and adds cache-only stars (`catalog.go`, `catalog_popularity_test.go`) — FR-002
+- [ ] T011 [US1] `SearchAll`: add `SearchOptions.PopularityWait` (default 800 ms), Resolve after the fan-out, re-apply and re-rank, and build sections from the pool before truncation — FR-005, FR-007
+- [ ] T012 [US1] `buildSections`: Official in source order, Popular signal-only, one per repo, capped at 12. **SC-001 and SC-002 tests** (fixture registries through `SetRegistriesForTest` + the stub provider)
+- [ ] T013 [US3] SearchAll with a GitHub stub that sleeps 5 s: returns within the wait, the second call has the stars, and `unavailable[]` is untouched (SC-003)
+- [ ] T014 Update any 109 test that asserted Official in popularity/rank order so it asserts source order instead (`internal/registries/*_test.go`, `internal/httpapi/catalog*_test.go`, `cmd/mcpproxy/catalog_cmd*_test.go`)
+
+## Phase 4 — Wiring (PR A)
+
+- [ ] T015 Runtime installs the bbolt-backed provider and closes it on shutdown (`internal/runtime/runtime.go`)
+- [ ] T016 CLI in-process fallback and `catalog show` install the memory provider (`cmd/mcpproxy/catalog_cmd.go`)
+- [ ] T017 `scripts/test-api-e2e.sh` exports `MCPPROXY_CATALOG_POPULARITY=false`
+- [ ] T018 Docs: `docs/features/` catalog page — popularity sources, `MCPPROXY_GITHUB_TOKEN`, kill switch
+- [ ] T019 Verify: both golangci-lint runs (bare + `--build-tags server`), `go test -race ./internal/registries/... ./internal/httpapi/... ./cmd/mcpproxy/...`, and `./scripts/test-api-e2e.sh`
+
+## Phase 5 — Display (PR B, stacked)
+
+- [ ] T020 [P] [US4] Web UI: `formatPopularity` util + vitest (`frontend/tests/unit/`) + badge in `CatalogSearch.vue` result row
+- [ ] T021 [P] [US4] macOS: badge in `CatalogView` row + `CatalogTests` formatting test
+- [ ] T022 [P] [US4] CLI: `catalog search` table shows a POPULARITY column
+- [ ] T023 [US4] Playwright web-ui sweep of the catalog landing with a seeded stub

From d35c9942fd10ccd288d1ca853497fc1f375f5384 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 05:47:02 +0300
Subject: [PATCH 23/27] docs(spec): fold zcode round-1 spec review into Spec
 110

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 specs/110-catalog-popularity/plan.md | 17 +++++++++++------
 specs/110-catalog-popularity/spec.md | 12 ++++++------
 2 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/specs/110-catalog-popularity/plan.md b/specs/110-catalog-popularity/plan.md
index 8730409a9..aaed2cacd 100644
--- a/specs/110-catalog-popularity/plan.md
+++ b/specs/110-catalog-popularity/plan.md
@@ -34,7 +34,7 @@ type ServerEntry struct { …; Popularity *Popularity `json:"-"` } // FR-001: so
 type PopularityProvider interface {
     // Lookup returns the cached stars for a repo key without I/O. stale=true
     // means past TTL (still usable); ok=false means never fetched / negative.
-    Lookup(key string) (stars int, ok bool, stale bool)
+    Lookup(key string) (stars int, state LookupState) // Fresh | Stale | Negative | Absent
     // Resolve enqueues misses/stale keys (in priority order) and waits up to
     // wait (bounded by ctx) for them; fetching continues after it returns.
     Resolve(ctx context.Context, keys []string, wait time.Duration)
@@ -69,11 +69,12 @@ bbolt bucket `catalog_popularity`: key = `o/r` (lower-case), value = JSON `stars
 SearchAll(q)
   fan-out (5s/source) ─► BuildCatalogHit: hit.Popularity = entry.Popularity (docker pulls)
                                            + cache-only Lookup(GitHubRepoKey(entry.SourceCodeURL))
-  merge + dedup + source filter ─► pool
-  sort pool by Rank; keys := repo keys of pool hits (rank order) lacking fresh stars
-  provider.Resolve(ctx, keys, opts.PopularityWait)   // ≤800ms, never beyond ctx
-  re-apply Lookup to pool hits; re-sort by Rank
-  sections = buildSections(pool)   // BEFORE truncation (FR-005)
+  merge + dedup + source filter ─► pool            // merge order = source order
+  official := copy of official hits in pool, merge order   // BEFORE any sort (FR-005)
+  sort pool by Rank; keys := repo keys (rank order) whose Lookup is stale/absent
+  provider.Resolve(ctx, keys, opts.PopularityWait)   // ctx bounds the wait only; workers use provider ctx
+  re-apply Lookup to pool + official hits; re-sort pool by Rank
+  sections = {Official: official[:12], Popular: popular(pool)}   // BEFORE truncation
   results  = pool[:limit]
 ```
 
@@ -95,3 +96,7 @@ SearchAll(q)
 
 - **Stacking on an open PR.** 109-j is still in review, and round 5 made local-only changes (`16f9e8c9c` is not pushed). PR A touches `catalog.go` `SearchAll`/`buildSections`, so it may conflict when 109-j's later rounds land. Mitigation: keep catalog.go edits confined to those two functions plus `BuildCatalogHit`/`Rank`, and rebase once 109-j merges.
 - **Section semantics change** (Official is no longer popularity-sorted). This is an intentional amendment of 109 FR-060. Existing 109 tests that assert Official order must be updated to source order, not deleted.
+
+## Review log
+
+- **zcode round 1 (spec, 2026-09-26)**: 9 findings, all verified and folded into FR-005/006/007/008/009/011 and the flow above. (1) Official must be built from the pre-sort merge order. (2) The per-source cap limits the pool, so empty q now fans out at 50/source, and the Docker single page is a documented limitation. (3) Background fetch uses the provider ctx, not the request ctx. (4) Overflow must not leave dedup entries behind. (5) No wait while paused or over budget. (6) Errors keep the last-known stars. (7) Lookup distinguishes negative from absent. (8) Own request, 10 s ctx timeout, never `registryGet`, no retries. (9) Kill switch lives in the constructor.
diff --git a/specs/110-catalog-popularity/spec.md b/specs/110-catalog-popularity/spec.md
index 4a5437ffa..44f018648 100644
--- a/specs/110-catalog-popularity/spec.md
+++ b/specs/110-catalog-popularity/spec.md
@@ -71,13 +71,13 @@ The Web UI result row, the macOS catalog row and the CLI `catalog search` table
 - **FR-002 (BuildCatalogHit)**: `BuildCatalogHit` MUST copy `entry.Popularity` into the hit and fill in `Stars` from the installed provider's **cache only**, with no network call. It stays synchronous and never blocks.
 - **FR-003 (repo key)**: A pure `GitHubRepoKey(sourceCodeURL) (key string, ok bool)` MUST normalize the edge-case forms above. Owner: `^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$`. Repo: `^[A-Za-z0-9._-]{1,100}$`, excluding `.` and `..`. Any other input returns `ok=false`.
 - **FR-004 (comparison)**: `Rank` and the Popular ordering MUST compare popularity as `(stars desc, installs desc)`, with missing = 0. Stars and installs are never added together or converted into each other.
-- **FR-005 (sections)**: `buildSections` MUST take the full merged, de-duplicated, source-filtered pool **before** `limit` truncation. Official = official hits in merge (source-native) order, at most 12. Popular = hits with `stars>0 ∨ installs>0`, sorted per FR-004 and then `Rank`, at most one per GitHub repo key, at most 12. This amends Spec 109 FR-060 and data-model §9.
-- **FR-006 (fetch)**: The GitHub fetcher MUST send `GET https://api.github.com/repos/{owner}/{repo}` through the SSRF-hardened registry client. The host is a compile-time constant, overridable only by a test hook. The request carries `Accept: application/vnd.github+json`, `X-GitHub-Api-Version: 2022-11-28`, the versioned mcpproxy User-Agent, and `If-None-Match` when an ETag is cached. The response body is capped at 1 MiB and each request has a 10 s timeout. Only `stargazers_count` and `ETag` are read.
-- **FR-007 (never block the search)**: `SearchAll` MUST resolve popularity *after* the per-source fan-out. Cached values come back immediately. Misses are queued for a background fetch, and `SearchAll` waits for them for at most `SearchOptions.PopularityWait`: default 800 ms, 0 disables the wait, and the wait never outlives `ctx`. Misses still outstanding keep being fetched after `SearchAll` returns, so the next search has them. Popularity failures never add entries to `unavailable[]`.
-- **FR-008 (cache)**: Each entry `{stars, etag, fetched_at, status}` MUST be kept in memory and persisted to the bbolt bucket `catalog_popularity` when a store is attached. The entry is fresh for 24 h after a 200 or 304, 24 h after a 404 or 451 (negative), and 1 h after any other error. Expired entries are still served (stale-while-revalidate) and queued for refresh. The store is capped at 5,000 keys, evicting the oldest `fetched_at` first.
-- **FR-009 (rate limit)**: The fetcher MUST (a) run at most 4 requests at once; (b) de-duplicate in-flight and queued keys, with a queue capped at 256 so overflow is dropped and requested again on the next search; (c) spend at most 50 requests per rolling hour without a token and 4,000 with one; (d) stop all fetches until `X-RateLimit-Reset` when `X-RateLimit-Remaining` ≤ 5, or on 403/429 with `Retry-After` or `X-RateLimit-Remaining: 0` (using `Retry-After`, or 60 s when neither header is present); (e) fetch misses in the order `SearchAll` ranked them.
+- **FR-005 (sections)**: `buildSections` MUST take the full merged, de-duplicated, source-filtered pool **before** `limit` truncation. For an empty q, each source is fanned out with the per-source maximum (50) rather than the caller's `limit`, so the pool is as wide as each source will give. Official = official hits in merge (source-native) order, at most 12. This order MUST come from a copy of the pool taken **before** any `Rank` sort. With an empty q and all-official defaults, rank order *is* popularity order, so building Official from the ranked pool would bring back the bug this spec fixes. Popular = hits with `stars>0 ∨ installs>0`, sorted per FR-004 and then `Rank`, at most one per GitHub repo key, at most 12. This amends Spec 109 FR-060 and data-model §9. *Known limitation*: the Docker source fetches a single page of `hub.docker.com/v2/repositories/mcp/`, which is 10 images by default. Popular therefore ranks only within what each source returns, and paginating Docker is a follow-up.
+- **FR-006 (fetch)**: The GitHub fetcher MUST send `GET https://api.github.com/repos/{owner}/{repo}` through the SSRF-hardened registry client. The host is a compile-time constant, overridable only by a test hook. The request carries `Accept: application/vnd.github+json`, `X-GitHub-Api-Version: 2022-11-28`, the versioned mcpproxy User-Agent, and `If-None-Match` when an ETag is cached. The response body is capped at 1 MiB and each request has a 10 s timeout. Only `stargazers_count` and `ETag` are read. The fetcher sends its own request on `sharedRegistryClient()`, with a per-request `context.WithTimeout(10s)` because the client's own timeout is 45 s. It MUST NOT use `registryGet`: that pins to `reg.ServersURL`, forces its own headers, and retries 429/5xx three times, which would burn budget against a rate-limited API. There are no retries; the breaker (FR-009) is the only backoff.
+- **FR-007 (never block the search)**: `SearchAll` MUST resolve popularity *after* the per-source fan-out. Cached values come back immediately. Misses are queued for a background fetch, and `SearchAll` waits for them for at most `SearchOptions.PopularityWait`: default 800 ms, 0 disables the wait, and the wait never outlives `ctx`. Misses still outstanding keep being fetched after `SearchAll` returns, so the next search has them. The caller's ctx bounds **only the wait**. Workers fetch under a context owned by the provider, created at construction and cancelled by `Close()`. `Resolve` returns immediately, without waiting, when the provider is paused (breaker), its budget is used up, or none of the requested keys were admitted to the queue. It waits only on the keys it admitted. Popularity failures never add entries to `unavailable[]`.
+- **FR-008 (cache)**: Each entry `{stars, etag, fetched_at, status}` MUST be kept in memory and persisted to the bbolt bucket `catalog_popularity` when a store is attached. The entry is fresh for 24 h after a 200 or 304, 24 h after a 404 or 451 (negative), and 1 h after any other error. Expired entries are still served (stale-while-revalidate) and queued for refresh. A failed refresh (a transport error or any status except 200/304/404/451) MUST keep the last-known `stars`/`etag` and only move the revalidate time forward. Stars are cleared only on a definitive 404/451. `Lookup` MUST tell apart *fresh*, *stale*, *negative* (fresh 404/451) and *absent*. `Resolve` enqueues only *stale* and *absent* keys, so a dead repo is not fetched again until its negative TTL runs out. The store is capped at 5,000 keys, evicting the oldest `fetched_at` first.
+- **FR-009 (rate limit)**: The fetcher MUST (a) run at most 4 requests at once; (b) de-duplicate in-flight and queued keys, with a queue capped at 256. A key that overflows is never recorded as queued (or is removed and its completion signal closed), so nothing waits on it and the next search can request it again; (c) spend at most 50 requests per rolling hour without a token and 4,000 with one; (d) stop all fetches until `X-RateLimit-Reset` when `X-RateLimit-Remaining` ≤ 5, or on 403/429 with `Retry-After` or `X-RateLimit-Remaining: 0` (using `Retry-After`, or 60 s when neither header is present); (e) fetch misses in the order `SearchAll` ranked them.
 - **FR-010 (wiring)**: `registries.SetPopularityProvider(p)` installs the process-wide provider, and `nil` turns lookups off. The core runtime installs a provider backed by bbolt at startup. The CLI in-process fallback (`catalogSearch` when no daemon is running, and `catalog show`) installs a memory-only one. Tests use `SetPopularityProviderForTest`, which returns a restore func.
-- **FR-011 (token & kill switch)**: If `MCPPROXY_GITHUB_TOKEN` is set, it is sent as `Authorization: Bearer …`, only to the constant GitHub API host. The generic `GITHUB_TOKEN` is deliberately **not** read, to avoid leaking an unrelated CI or dev token. `MCPPROXY_CATALOG_POPULARITY=false` (or `0`/`off`) turns off all outbound popularity fetches. Source-native Docker pulls still show.
+- **FR-011 (token & kill switch)**: If `MCPPROXY_GITHUB_TOKEN` is set, it is sent as `Authorization: Bearer …`, only to the constant GitHub API host. The generic `GITHUB_TOKEN` is deliberately **not** read, to avoid leaking an unrelated CI or dev token. `MCPPROXY_CATALOG_POPULARITY=false` (or `0`/`off`) turns off all outbound popularity fetches. The switch is read inside the provider constructor, which then returns a no-op provider, so the runtime and CLI call sites both honour it. Source-native Docker pulls still show.
 - **FR-012 (display)**: The Web UI, macOS and CLI table MUST show compact popularity (`★ 1.2k`, `⤓ 3.4M`) when it is known. The REST, MCP and CLI JSON shapes are unchanged.
 
 ### Success Criteria

From 8e153c50830f0a92beb98b2c0847cd8bfe639055 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 06:01:51 +0300
Subject: [PATCH 24/27] feat(catalog): add GitHub-stars popularity signal core
 (Spec 110 T001-T013)

Implements the FR-001..FR-009 core of the catalog popularity signal:
GitHubRepoKey normalizer, the PopularityProvider seam (Lookup/Resolve,
Fresh/Stale/Negative/Absent states), a cached rate-limited
githubStarsProvider (bbolt-backed store, 4-worker pool, rolling budget,
breaker), parseDocker's pull_count -> Installs, and Rank/buildSections/
SearchAll wiring so Official stays in source order while Popular is
built from the full pre-truncation, pre-Rank-sort pool.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 internal/registries/catalog.go                | 240 ++++++-
 .../registries/catalog_popularity_test.go     | 274 ++++++++
 internal/registries/popularity.go             |  75 ++
 internal/registries/popularity_github.go      | 656 ++++++++++++++++++
 internal/registries/popularity_github_test.go | 535 ++++++++++++++
 internal/registries/popularity_key.go         |  65 ++
 internal/registries/popularity_key_test.go    |  48 ++
 internal/registries/popularity_store.go       |  91 +++
 internal/registries/popularity_store_test.go  | 127 ++++
 internal/registries/rank_test.go              |  46 ++
 internal/registries/search.go                 |  10 +
 internal/registries/testhooks.go              |  24 +
 internal/registries/types.go                  |   8 +
 13 files changed, 2175 insertions(+), 24 deletions(-)
 create mode 100644 internal/registries/catalog_popularity_test.go
 create mode 100644 internal/registries/popularity.go
 create mode 100644 internal/registries/popularity_github.go
 create mode 100644 internal/registries/popularity_github_test.go
 create mode 100644 internal/registries/popularity_key.go
 create mode 100644 internal/registries/popularity_key_test.go
 create mode 100644 internal/registries/popularity_store.go
 create mode 100644 internal/registries/popularity_store_test.go

diff --git a/internal/registries/catalog.go b/internal/registries/catalog.go
index a5974f1be..3e416425f 100644
--- a/internal/registries/catalog.go
+++ b/internal/registries/catalog.go
@@ -105,6 +105,15 @@ type SearchOptions struct {
 	// could silently drop a narrower source's real matches that simply
 	// didn't survive the pre-filter truncation.
 	Source string
+
+	// PopularityWait bounds how long SearchAll waits (Spec 110 FR-007) for a
+	// background popularity fetch to land before returning. Zero — the Go
+	// zero value, i.e. left unset — means the default (800ms), matching
+	// every other *Timeout-shaped field in this struct (see SourceTimeout).
+	// A NEGATIVE value disables the wait entirely: SearchAll still enqueues
+	// the misses for background fetching, it just never blocks for them.
+	// The wait never outlives ctx.
+	PopularityWait time.Duration
 }
 
 const (
@@ -112,6 +121,11 @@ const (
 	catalogSectionCap           = 12
 	defaultCatalogLimit         = 10
 	maxCatalogLimit             = 50
+
+	// defaultPopularityWait is SearchOptions.PopularityWait's zero-value
+	// default (Spec 110 FR-007): long enough for a warm cached/in-flight
+	// GitHub round trip, short enough to never meaningfully slow a search.
+	defaultPopularityWait = 800 * time.Millisecond
 )
 
 // SearchAll fans SearchServers out to every enabled registry in parallel
@@ -132,6 +146,21 @@ func SearchAll(ctx context.Context, q, tag string, limit int, opts SearchOptions
 		limit = maxCatalogLimit
 	}
 
+	empty := strings.TrimSpace(q) == ""
+
+	// Spec 110 FR-005 (zcode review round 1, finding 2): an empty q fans out
+	// each source at the per-source MAXIMUM, not the caller's `limit`, so the
+	// section pool (Official/Popular) is as wide as each source will give —
+	// otherwise a `limit` of 10 would starve Popular of anything beyond the
+	// first 10 official hits before popularity ever gets a say. The final
+	// `results` list is still truncated to `limit` below. A non-empty q keeps
+	// fetching exactly `limit` per source (unchanged), since it has no
+	// sections to populate.
+	fetchLimit := limit
+	if empty {
+		fetchLimit = maxCatalogLimit
+	}
+
 	sources := ListRegistries()
 
 	type sourceOutcome struct {
@@ -149,7 +178,7 @@ func SearchAll(ctx context.Context, q, tag string, limit int, opts SearchOptions
 			sctx, cancel := context.WithTimeout(ctx, timeout)
 			defer cancel()
 
-			entries, err := SearchServers(sctx, reg.ID, tag, q, limit, nil)
+			entries, err := SearchServers(sctx, reg.ID, tag, q, fetchLimit, nil)
 			if err != nil {
 				reason := err.Error()
 				if sctx.Err() != nil {
@@ -169,6 +198,12 @@ func SearchAll(ctx context.Context, q, tag string, limit int, opts SearchOptions
 	wg.Wait()
 
 	seen := make(map[string]bool)
+	// all is built and kept in MERGE order (registry list order, then each
+	// source's native order) until buildSections has taken its snapshot
+	// below — Spec 110 FR-005 (zcode review finding 1): Official must come
+	// from a copy taken BEFORE any Rank sort, or it silently degrades back
+	// into popularity order on an all-official default install (the exact
+	// bug this spec fixes).
 	var all []CatalogHit
 	var unavailable []SourceError
 	for _, outcome := range outcomes {
@@ -190,6 +225,19 @@ func SearchAll(ctx context.Context, q, tag string, limit int, opts SearchOptions
 		all = filterHitsBySource(all, opts.Source)
 	}
 
+	// Spec 110 FR-002/007: resolve popularity (cache hits immediately, misses
+	// queued for a bounded background wait) BEFORE ranking, so both the
+	// Rank tiebreak (US2) and the Popular section see up-to-date signal. This
+	// mutates each hit's Popularity in place but does not reorder `all`.
+	resolvePopularity(ctx, all, q, popularityWait(opts.PopularityWait))
+
+	var sections *CatalogSections
+	if empty {
+		// Built from `all` in its current MERGE order, before the Rank sort
+		// below (FR-005).
+		sections = buildSections(all, q)
+	}
+
 	sort.SliceStable(all, func(i, j int) bool { return Rank(all[i], all[j], q) })
 	sort.SliceStable(unavailable, func(i, j int) bool { return unavailable[i].Source < unavailable[j].Source })
 
@@ -197,12 +245,65 @@ func SearchAll(ctx context.Context, q, tag string, limit int, opts SearchOptions
 		all = all[:limit]
 	}
 
-	var sections *CatalogSections
-	if strings.TrimSpace(q) == "" {
-		sections = buildSections(all)
+	return all, sections, unavailable
+}
+
+// popularityWait resolves SearchOptions.PopularityWait's documented
+// convention: zero (unset) means the 800ms default; negative disables the
+// wait entirely (fetches are still enqueued, SearchAll just never blocks on
+// them).
+func popularityWait(configured time.Duration) time.Duration {
+	switch {
+	case configured < 0:
+		return 0
+	case configured == 0:
+		return defaultPopularityWait
+	default:
+		return configured
 	}
+}
 
-	return all, sections, unavailable
+// resolvePopularity is Spec 110's FR-007 hook: it asks the installed
+// PopularityProvider (if any) to resolve every hit's GitHub repo key, waits
+// up to `wait` for the background fetch to land, and re-applies whatever is
+// now cached. A nil provider (no popularity wiring — e.g. most tests) is a
+// fast no-op.
+func resolvePopularity(ctx context.Context, hits []CatalogHit, q string, wait time.Duration) {
+	provider := getPopularityProvider()
+	if provider == nil {
+		return
+	}
+
+	// FR-009(e): enqueue misses in the order SearchAll ranks them, so the
+	// most relevant ones are fetched first. This priority copy is throwaway —
+	// it never replaces `hits`' own order, which Official's merge-order
+	// requirement (FR-005) depends on.
+	priority := append([]CatalogHit(nil), hits...)
+	sort.SliceStable(priority, func(i, j int) bool { return Rank(priority[i], priority[j], q) })
+
+	seen := make(map[string]bool, len(priority))
+	keys := make([]string, 0, len(priority))
+	for _, h := range priority {
+		key, ok := GitHubRepoKey(h.Entry.SourceCodeURL)
+		if !ok || seen[key] {
+			continue
+		}
+		seen[key] = true
+		// Only Stale/Absent need a fetch (FR-008): a Fresh positive or a
+		// still-fresh Negative (confirmed 404/451, or an error entry backing
+		// off within its own shorter TTL) is left alone.
+		if _, state := provider.Lookup(key); state == LookupStale || state == LookupAbsent {
+			keys = append(keys, key)
+		}
+	}
+
+	provider.Resolve(ctx, keys, wait)
+
+	// Re-apply lookups: any key that landed during the bounded wait now shows
+	// its stars; everything else is unchanged.
+	for i := range hits {
+		applyCachedStars(&hits[i])
+	}
 }
 
 // filterHitsBySource keeps only the hits from one catalog source, applied
@@ -230,7 +331,7 @@ func BuildCatalogHit(reg *RegistryEntry, entry ServerEntry) CatalogHit {
 	if title == "" {
 		title = entry.ID
 	}
-	return CatalogHit{
+	hit := CatalogHit{
 		Entry:     entry,
 		Source:    reg.ID,
 		Title:     title,
@@ -238,6 +339,40 @@ func BuildCatalogHit(reg *RegistryEntry, entry ServerEntry) CatalogHit {
 		Verified:  official,
 		Official:  official,
 	}
+	// FR-001/FR-002: copy the source-native signal (e.g. Docker pull_count)
+	// first, then layer in GitHub stars from the provider's cache only — no
+	// network call, so this stays synchronous.
+	if entry.Popularity != nil {
+		p := *entry.Popularity
+		hit.Popularity = &p
+	}
+	applyCachedStars(&hit)
+	return hit
+}
+
+// applyCachedStars fills in hit.Popularity.Stars from the installed
+// PopularityProvider's cache ONLY (Spec 110 FR-002): no I/O, so both
+// BuildCatalogHit and SearchAll's post-Resolve re-apply can call this freely.
+// A nil provider, an entry with no GitHub-shaped SourceCodeURL, or a
+// non-displayable lookup state (Absent/Negative) leave the hit unchanged.
+func applyCachedStars(hit *CatalogHit) {
+	key, ok := GitHubRepoKey(hit.Entry.SourceCodeURL)
+	if !ok {
+		return
+	}
+	provider := getPopularityProvider()
+	if provider == nil {
+		return
+	}
+	stars, state := provider.Lookup(key)
+	if state != LookupFresh && state != LookupStale {
+		return
+	}
+	if hit.Popularity == nil {
+		hit.Popularity = &Popularity{}
+	}
+	s := stars
+	hit.Popularity.Stars = &s
 }
 
 // derivePublisher extracts a display publisher from an official-protocol
@@ -267,8 +402,8 @@ func Rank(a, b CatalogHit, q string) bool {
 	if a.Verified != b.Verified {
 		return a.Verified
 	}
-	if ap, bp := popularityScore(a.Popularity), popularityScore(b.Popularity); ap != bp {
-		return ap > bp
+	if !popularityEqual(a.Popularity, b.Popularity) {
+		return morePopular(a.Popularity, b.Popularity)
 	}
 	if ar, br := relevanceScore(a, q), relevanceScore(b, q); ar != br {
 		return ar > br
@@ -290,18 +425,40 @@ func catalogTitle(h CatalogHit) string {
 	return h.Entry.ID
 }
 
-func popularityScore(p *Popularity) int {
+// popularityKey extracts the (stars, installs) tuple a Popularity compares
+// on, with a nil pointer or nil field reading as 0 (Spec 110 FR-004).
+func popularityKey(p *Popularity) (stars, installs int) {
 	if p == nil {
-		return 0
+		return 0, 0
 	}
-	score := 0
 	if p.Stars != nil {
-		score += *p.Stars
+		stars = *p.Stars
 	}
 	if p.Installs != nil {
-		score += *p.Installs
+		installs = *p.Installs
 	}
-	return score
+	return stars, installs
+}
+
+// morePopular reports whether a ranks strictly ABOVE b: stars desc, then
+// installs desc (FR-004). Stars and installs are never summed or converted
+// into one another — a lexicographic tuple compare, not a score.
+func morePopular(a, b *Popularity) bool {
+	as, ai := popularityKey(a)
+	bs, bi := popularityKey(b)
+	if as != bs {
+		return as > bs
+	}
+	return ai > bi
+}
+
+// popularityEqual reports whether a and b compare equal under morePopular's
+// ordering (both keys tie), the signal Rank and buildSections use to decide
+// whether to fall through to the next sort key.
+func popularityEqual(a, b *Popularity) bool {
+	as, ai := popularityKey(a)
+	bs, bi := popularityKey(b)
+	return as == bs && ai == bi
 }
 
 // relevanceScore is a simple, deterministic token-match count of q against
@@ -331,23 +488,58 @@ func relevanceScore(h CatalogHit, q string) int {
 	return score
 }
 
-// buildSections splits the already-ranked merged hits into the empty-query
-// landing sections (FR-060): official-source hits (in rank order) and the
-// top-popularity hits across every source, each capped at 12.
-func buildSections(ranked []CatalogHit) *CatalogSections {
+// buildSections splits the merged, de-duplicated, source-filtered pool
+// (BEFORE limit truncation and BEFORE any Rank sort) into the empty-query
+// landing sections (Spec 110 FR-005, amending Spec 109 FR-060):
+//
+//   - Official: official-source hits in `pool`'s own MERGE (source-native)
+//     order — registry-list order, then each source's native order. Pool
+//     MUST NOT have been Rank-sorted yet: on an all-official default install
+//     every hit ties on Official/Verified, so Rank order IS popularity order,
+//     and building Official from a ranked pool silently reintroduces the bug
+//     this spec fixes. Capped at 12.
+//   - Popular: hits with a known signal (stars>0 ∨ installs>0), sorted by
+//     popularity (FR-004) then Rank as a tiebreak, at most one per GitHub
+//     repo key (a monorepo's shared star count keeps only the first by Rank —
+//     spec.md edge cases), capped at 12.
+func buildSections(pool []CatalogHit, q string) *CatalogSections {
 	sections := &CatalogSections{Official: []CatalogHit{}, Popular: []CatalogHit{}}
-	for _, h := range ranked {
+
+	for _, h := range pool {
 		if h.Official && len(sections.Official) < catalogSectionCap {
 			sections.Official = append(sections.Official, h)
 		}
 	}
 
-	byPopularity := append([]CatalogHit(nil), ranked...)
-	sort.SliceStable(byPopularity, func(i, j int) bool {
-		return popularityScore(byPopularity[i].Popularity) > popularityScore(byPopularity[j].Popularity)
+	candidates := make([]CatalogHit, 0, len(pool))
+	for _, h := range pool {
+		if stars, installs := popularityKey(h.Popularity); stars > 0 || installs > 0 {
+			candidates = append(candidates, h)
+		}
+	}
+	sort.SliceStable(candidates, func(i, j int) bool {
+		if !popularityEqual(candidates[i].Popularity, candidates[j].Popularity) {
+			return morePopular(candidates[i].Popularity, candidates[j].Popularity)
+		}
+		return Rank(candidates[i], candidates[j], q)
 	})
-	for i := 0; i < len(byPopularity) && i < catalogSectionCap; i++ {
-		sections.Popular = append(sections.Popular, byPopularity[i])
+
+	seenRepo := make(map[string]bool, len(candidates))
+	for _, h := range candidates {
+		if len(sections.Popular) >= catalogSectionCap {
+			break
+		}
+		dedupKey, hasRepo := GitHubRepoKey(h.Entry.SourceCodeURL)
+		if !hasRepo {
+			// No GitHub repo to dedup against (e.g. a Docker-only pull-count
+			// hit) — (source, id) already made this unique within `pool`.
+			dedupKey = "no-repo:" + h.Source + "\x00" + h.Entry.ID
+		}
+		if seenRepo[dedupKey] {
+			continue
+		}
+		seenRepo[dedupKey] = true
+		sections.Popular = append(sections.Popular, h)
 	}
 	return sections
 }
diff --git a/internal/registries/catalog_popularity_test.go b/internal/registries/catalog_popularity_test.go
new file mode 100644
index 000000000..c3c7839d2
--- /dev/null
+++ b/internal/registries/catalog_popularity_test.go
@@ -0,0 +1,274 @@
+package registries
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// stubPopularityProvider is a deterministic, non-networked PopularityProvider
+// for tests that need known star counts without any HTTP stub or timing
+// dependency (T010/T012 — SC-001/SC-002). Resolve is a no-op: everything the
+// test cares about is pre-seeded and already "fresh".
+type stubPopularityProvider struct {
+	mu    sync.Mutex
+	stars map[string]int
+}
+
+func (s *stubPopularityProvider) Lookup(key string) (int, LookupState) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if v, ok := s.stars[key]; ok {
+		return v, LookupFresh
+	}
+	return 0, LookupAbsent
+}
+
+func (s *stubPopularityProvider) Resolve(context.Context, []string, time.Duration) {}
+
+var _ PopularityProvider = (*stubPopularityProvider)(nil)
+
+func idsOf(hits []CatalogHit) []string {
+	out := make([]string, len(hits))
+	for i, h := range hits {
+		out[i] = h.Entry.ID
+	}
+	return out
+}
+
+// --- T010: BuildCatalogHit ---------------------------------------------------
+
+func TestBuildCatalogHit_CopiesPopularityAndAddsCacheOnlyStars(t *testing.T) {
+	reg := RegistryEntry{ID: "docker", Name: "Docker"}
+	installs := 42
+	entry := ServerEntry{
+		ID: "tool", Name: "Tool",
+		SourceCodeURL: "https://github.com/org/tool",
+		Popularity:    &Popularity{Installs: &installs},
+	}
+
+	restore := SetPopularityProviderForTest(nil)
+	hit := BuildCatalogHit(&reg, entry)
+	restore()
+	if hit.Popularity == nil || hit.Popularity.Installs == nil || *hit.Popularity.Installs != 42 {
+		t.Fatalf("expected Installs to carry through with no provider installed, got %+v", hit.Popularity)
+	}
+	if hit.Popularity.Stars != nil {
+		t.Fatalf("expected no Stars with no provider installed, got %+v", hit.Popularity)
+	}
+
+	stub := &stubPopularityProvider{stars: map[string]int{"org/tool": 321}}
+	restore2 := SetPopularityProviderForTest(stub)
+	hit2 := BuildCatalogHit(&reg, entry)
+	restore2()
+	if hit2.Popularity == nil || hit2.Popularity.Stars == nil || *hit2.Popularity.Stars != 321 {
+		t.Fatalf("expected Stars=321 from the cache-only lookup, got %+v", hit2.Popularity)
+	}
+	if hit2.Popularity.Installs == nil || *hit2.Popularity.Installs != 42 {
+		t.Fatalf("expected Installs to still carry through alongside Stars, got %+v", hit2.Popularity)
+	}
+}
+
+// --- T012 / SC-001 -----------------------------------------------------------
+
+// TestSearchAll_SC001_PopularDiffersFromOfficial pins SC-001: 14 official
+// hits in source order (repo-14 has by far the most stars but sits outside
+// Official's first-12 cap), plus one non-official Docker hit with pulls.
+// Popular must differ from Official, Popular[0] must be the most-starred
+// hit, and Popular must contain a hit Official does not.
+func TestSearchAll_SC001_PopularDiffersFromOfficial(t *testing.T) {
+	entries := make([]string, 0, 14)
+	for i := 1; i <= 14; i++ {
+		entries = append(entries, fmt.Sprintf(
+			`{"id":"repo-%d","name":"Repo %d","source_code_url":"https://github.com/org/repo-%d"}`, i, i, i))
+	}
+	officialSrv := jsonServer(t, "["+strings.Join(entries, ",")+"]")
+	dockerSrv := jsonServer(t, `{"results":[{"name":"popular-tool","pull_count":5000000,"short_description":"d"}]}`)
+
+	withTestRegistries(t, []RegistryEntry{
+		{ID: "official", Name: "Official", ServersURL: officialSrv.URL, Provenance: "official"},
+		{ID: "docker", Name: "Docker", ServersURL: dockerSrv.URL, Protocol: protocolDocker},
+	})
+
+	stub := &stubPopularityProvider{stars: map[string]int{
+		"org/repo-14": 99999, // outside Official's first 12; the standout count
+		"org/repo-1":  500,
+		"org/repo-2":  10,
+	}}
+	restore := SetPopularityProviderForTest(stub)
+	defer restore()
+
+	_, sections, unavailable := SearchAll(context.Background(), "", "", 10, SearchOptions{})
+	if len(unavailable) != 0 {
+		t.Fatalf("expected no unavailable sources, got %+v", unavailable)
+	}
+	if sections == nil {
+		t.Fatal("expected sections for an empty query")
+	}
+
+	if len(sections.Official) != 12 {
+		t.Fatalf("expected Official capped at 12, got %d: %+v", len(sections.Official), idsOf(sections.Official))
+	}
+	for i, h := range sections.Official {
+		want := fmt.Sprintf("repo-%d", i+1)
+		if h.Entry.ID != want {
+			t.Fatalf("expected Official in SOURCE order — Official[%d]=%s, got %s (full: %+v)", i, want, h.Entry.ID, idsOf(sections.Official))
+		}
+	}
+
+	if len(sections.Popular) == 0 {
+		t.Fatal("expected a non-empty Popular section")
+	}
+	if sections.Popular[0].Entry.ID != "repo-14" {
+		t.Fatalf("expected Popular[0] to be the most-starred hit (repo-14), got %s", sections.Popular[0].Entry.ID)
+	}
+
+	officialIDs := make(map[string]bool, len(sections.Official))
+	for _, h := range sections.Official {
+		officialIDs[h.Entry.ID] = true
+	}
+	foundOutsideOfficial := false
+	foundDocker := false
+	for _, h := range sections.Popular {
+		if !officialIDs[h.Entry.ID] {
+			foundOutsideOfficial = true
+		}
+		if h.Source == "docker" {
+			foundDocker = true
+		}
+	}
+	if !foundOutsideOfficial {
+		t.Fatalf("expected Popular to contain a hit not in Official, got %+v", idsOf(sections.Popular))
+	}
+	if !foundDocker {
+		t.Fatalf("expected the Docker install-count hit to blend into Popular, got %+v", idsOf(sections.Popular))
+	}
+	if strings.Join(idsOf(sections.Official), ",") == strings.Join(idsOf(sections.Popular), ",") {
+		t.Fatal("expected Popular to differ from Official")
+	}
+}
+
+// TestSearchAll_SC002_NoSignalMeansEmptyPopular pins SC-002: with no
+// popularity known for any hit, Popular is empty (never padded with
+// zero-popularity hits) and Official is unaffected.
+func TestSearchAll_SC002_NoSignalMeansEmptyPopular(t *testing.T) {
+	officialSrv := jsonServer(t, `[{"id":"a","name":"A"},{"id":"b","name":"B"}]`)
+	withTestRegistries(t, []RegistryEntry{
+		{ID: "official", Name: "Official", ServersURL: officialSrv.URL, Provenance: "official"},
+	})
+
+	restore := SetPopularityProviderForTest(&stubPopularityProvider{stars: map[string]int{}})
+	defer restore()
+
+	_, sections, _ := SearchAll(context.Background(), "", "", 10, SearchOptions{})
+	if sections == nil {
+		t.Fatal("expected sections for an empty query")
+	}
+	if len(sections.Popular) != 0 {
+		t.Fatalf("expected an empty Popular section with no signal, got %+v", idsOf(sections.Popular))
+	}
+	if len(sections.Official) != 2 {
+		t.Fatalf("expected Official unchanged (2 hits), got %+v", idsOf(sections.Official))
+	}
+}
+
+// TestSearchAll_NoProviderInstalledMeansEmptyPopular is SC-002's "GitHub
+// unreachable / no popularity wiring at all" variant: a nil provider (the
+// package default, and what most tests run with) must behave the same as an
+// installed-but-empty one.
+func TestSearchAll_NoProviderInstalledMeansEmptyPopular(t *testing.T) {
+	officialSrv := jsonServer(t, `[{"id":"a","name":"A","source_code_url":"https://github.com/org/a"}]`)
+	withTestRegistries(t, []RegistryEntry{
+		{ID: "official", Name: "Official", ServersURL: officialSrv.URL, Provenance: "official"},
+	})
+
+	restore := SetPopularityProviderForTest(nil)
+	defer restore()
+
+	_, sections, _ := SearchAll(context.Background(), "", "", 10, SearchOptions{})
+	if sections == nil || len(sections.Popular) != 0 {
+		t.Fatalf("expected an empty Popular section with no provider installed, got %+v", sections)
+	}
+}
+
+// --- T013 / SC-003 ------------------------------------------------------------
+
+// TestSearchAll_SC003_ReturnsWithinPopularityWaitBudget pins SC-003: SearchAll
+// returns within PopularityWait (+ generous slack for CI jitter) even when
+// the GitHub fetch is slow, unavailable[] stays untouched (popularity is
+// never a catalog source), and a second call after the stub answers carries
+// the stars. The spec's illustrative "sleeps 5s" is shortened here (a fast,
+// deterministic stand-in for "slower than the wait") so the suite stays
+// fast; the property under test — SearchAll's return time is bounded by the
+// wait, not by the upstream's latency — is unaffected by the absolute
+// duration chosen.
+func TestSearchAll_SC003_ReturnsWithinPopularityWaitBudget(t *testing.T) {
+	officialSrv := jsonServer(t, `[{"id":"a","name":"A","source_code_url":"https://github.com/org/repo"}]`)
+	withTestRegistries(t, []RegistryEntry{
+		{ID: "official", Name: "Official", ServersURL: officialSrv.URL, Provenance: "official"},
+	})
+
+	block := make(chan struct{})
+	var once sync.Once
+	closeBlock := func() { once.Do(func() { close(block) }) }
+	slow := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		select {
+		case <-block:
+		case <-r.Context().Done():
+		}
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"stargazers_count": 777}`))
+	}))
+	defer func() { closeBlock(); slow.Close() }()
+
+	restoreBase := SetGitHubAPIBaseForTest(slow.URL)
+	defer restoreBase()
+	provider := NewGitHubStarsProvider(PopularityOptions{})
+	defer provider.Close()
+	defer SetPopularityProviderForTest(provider)()
+
+	wait := 80 * time.Millisecond
+	start := time.Now()
+	hits, _, unavailable := SearchAll(context.Background(), "", "", 10, SearchOptions{PopularityWait: wait})
+	elapsed := time.Since(start)
+
+	if len(unavailable) != 0 {
+		t.Fatalf("expected unavailable[] untouched by a slow popularity fetch, got %+v", unavailable)
+	}
+
+	slack := 400 * time.Millisecond // generous: CI jitter, not the property under test
+	if elapsed > wait+slack {
+		t.Fatalf("expected SearchAll to return within wait(%s)+slack(%s), took %s", wait, slack, elapsed)
+	}
+	for _, h := range hits {
+		if h.Popularity != nil && h.Popularity.Stars != nil {
+			t.Fatalf("expected no stars yet on the first call (stub still blocked), got %+v", *h.Popularity.Stars)
+		}
+	}
+
+	closeBlock() // let the slow stub answer
+
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if _, state := provider.Lookup("org/repo"); state == LookupFresh {
+			break
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	hits2, _, _ := SearchAll(context.Background(), "", "", 10, SearchOptions{PopularityWait: wait})
+	found := false
+	for _, h := range hits2 {
+		if h.Popularity != nil && h.Popularity.Stars != nil && *h.Popularity.Stars == 777 {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("expected the second SearchAll call to carry the resolved stars, got %+v", hits2)
+	}
+}
diff --git a/internal/registries/popularity.go b/internal/registries/popularity.go
new file mode 100644
index 000000000..6475c816d
--- /dev/null
+++ b/internal/registries/popularity.go
@@ -0,0 +1,75 @@
+// Spec 110 (catalog popularity signal): a PopularityProvider resolves GitHub
+// star counts for repo keys (GitHubRepoKey), backed by a cached,
+// rate-limited fetcher (githubStarsProvider is the production
+// implementation — see popularity_github.go). It is installed process-wide
+// via SetPopularityProvider (FR-010) so BuildCatalogHit and SearchAll can
+// reach it without threading a dependency through every call site.
+package registries
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+// LookupState is PopularityProvider.Lookup's classification of a cached
+// entry (Spec 110 FR-008, zcode review round 1 finding 7):
+//
+//   - LookupFresh: a positive signal (stars) within its TTL. Display it;
+//     no fetch needed.
+//   - LookupStale: a positive signal past its TTL. Still display it
+//     (stale-while-revalidate), but it needs a refresh.
+//   - LookupNegative: no signal to display, and still within its TTL —
+//     either a confirmed 404/451, or a transient-error entry backing off
+//     within its own (shorter) TTL. Not re-fetched yet either way.
+//   - LookupAbsent: no signal, and free to (re)fetch now — never seen, or
+//     past a negative/error entry's TTL.
+type LookupState int
+
+const (
+	LookupAbsent LookupState = iota
+	LookupFresh
+	LookupStale
+	LookupNegative
+)
+
+// PopularityProvider is the seam BuildCatalogHit and SearchAll use to read
+// and refresh a GitHub repo's star count.
+type PopularityProvider interface {
+	// Lookup returns the cached star count for key without any I/O. See
+	// LookupState for what each state means; only Fresh and Stale carry a
+	// meaningful `stars` value.
+	Lookup(key string) (stars int, state LookupState)
+
+	// Resolve enqueues any of keys that are Stale or Absent for a background
+	// fetch (de-duplicated against what's already queued/in-flight) and
+	// waits up to wait — bounded by ctx — for them to land. Fetching
+	// continues after Resolve returns even if the wait/ctx expired first.
+	// Resolve returns immediately, without enqueueing anything, when the
+	// provider is breaker-paused, its rolling budget is exhausted, or none of
+	// the requested keys were admitted (e.g. all already fresh, or the queue
+	// was full) — see popularity_github.go.
+	Resolve(ctx context.Context, keys []string, wait time.Duration)
+}
+
+var (
+	popularityProviderMu  sync.RWMutex
+	popularityProviderVal PopularityProvider
+)
+
+// SetPopularityProvider installs the process-wide popularity provider
+// (FR-010). nil disables all popularity lookups: BuildCatalogHit adds no
+// stars and SearchAll enqueues no fetches — Docker's source-native Installs
+// signal is unaffected either way (it never goes through this seam).
+func SetPopularityProvider(p PopularityProvider) {
+	popularityProviderMu.Lock()
+	defer popularityProviderMu.Unlock()
+	popularityProviderVal = p
+}
+
+// getPopularityProvider returns the currently installed provider, or nil.
+func getPopularityProvider() PopularityProvider {
+	popularityProviderMu.RLock()
+	defer popularityProviderMu.RUnlock()
+	return popularityProviderVal
+}
diff --git a/internal/registries/popularity_github.go b/internal/registries/popularity_github.go
new file mode 100644
index 000000000..9508f5cfe
--- /dev/null
+++ b/internal/registries/popularity_github.go
@@ -0,0 +1,656 @@
+package registries
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"go.etcd.io/bbolt"
+	"go.uber.org/zap"
+)
+
+const (
+	githubAPIBaseURLDefault = "https://api.github.com"
+
+	githubMaxConcurrentFetches = 4    // FR-009(a)
+	githubQueueCap             = 256  // FR-009(b)
+	githubMaxCacheKeys         = 5000 // FR-008
+	githubRequestTimeout       = 10 * time.Second
+	githubMaxBodyBytes         = 1 << 20 // 1 MiB (FR-006)
+
+	githubFreshTTL     = 24 * time.Hour // FR-008: 200/304 and 404/451
+	githubErrorTTL     = 1 * time.Hour  // FR-008: any other error
+	githubBreakerPause = 60 * time.Second
+
+	githubRateLimitUnauth = 50   // FR-009(c): requests/hour without a token
+	githubRateLimitAuth   = 4000 // FR-009(c): requests/hour with a token
+
+	githubLowRemainingThreshold = 5 // FR-009(d)
+)
+
+// githubAPIBaseOverride lets SetGitHubAPIBaseForTest point new providers at
+// an httptest.Server; production providers always read the compile-time
+// default (FR-006: "overridable only by a test hook").
+var githubAPIBaseOverride atomic.Pointer[string]
+
+func currentGitHubAPIBase() string {
+	if p := githubAPIBaseOverride.Load(); p != nil {
+		return *p
+	}
+	return githubAPIBaseURLDefault
+}
+
+// starsEntry is the cached record for one GitHub repo key (plan.md data
+// model). Persisted as JSON in popularityBucketName.
+type starsEntry struct {
+	Stars     int       `json:"stars"`
+	ETag      string    `json:"etag,omitempty"`
+	FetchedAt time.Time `json:"fetched_at"`
+	Status    int       `json:"status"` // 200/304 ok, 404/451 negative, else the last error status (0 = transport error)
+}
+
+func (e *starsEntry) ok() bool {
+	return e.Status == http.StatusOK || e.Status == http.StatusNotModified
+}
+
+func (e *starsEntry) negative() bool {
+	return e.Status == http.StatusNotFound || e.Status == http.StatusUnavailableForLegalReasons
+}
+
+// ttl is how long e stays fresh (FR-008): 24h for a confirmed answer
+// (positive OR negative), 1h for anything else (transport error, 5xx, 403,
+// 429 — the breaker, not this TTL, is what actually throttles those).
+func (e *starsEntry) ttl() time.Duration {
+	if e.ok() || e.negative() {
+		return githubFreshTTL
+	}
+	return githubErrorTTL
+}
+
+// PopularityOptions configures NewGitHubStarsProvider.
+type PopularityOptions struct {
+	// DB is the bbolt database to persist the cache to. nil means memory
+	// only (the CLI in-process fallback — plan.md wiring table).
+	DB *bbolt.DB
+	// Logger receives best-effort diagnostics (store errors, etc). A nil
+	// Logger falls back to zap.NewNop().
+	Logger *zap.Logger
+}
+
+// rollingBudget is a simple sliding-window request counter (FR-009c): at
+// most `limit` `allow` calls may return true within any trailing `window`.
+type rollingBudget struct {
+	mu     sync.Mutex
+	limit  int
+	window time.Duration
+	hits   []time.Time
+}
+
+func newRollingBudget(limit int) *rollingBudget {
+	return &rollingBudget{limit: limit, window: time.Hour}
+}
+
+func (b *rollingBudget) prune(now time.Time) {
+	cutoff := now.Add(-b.window)
+	kept := b.hits[:0]
+	for _, t := range b.hits {
+		if t.After(cutoff) {
+			kept = append(kept, t)
+		}
+	}
+	b.hits = kept
+}
+
+// hasCapacity reports whether a request could be spent right now, without
+// consuming any budget (a peek, used by Resolve's fast bail-out).
+func (b *rollingBudget) hasCapacity(now time.Time) bool {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.prune(now)
+	return len(b.hits) < b.limit
+}
+
+// allow is the authoritative, budget-consuming check made by a worker right
+// before it actually issues a request.
+func (b *rollingBudget) allow(now time.Time) bool {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.prune(now)
+	if len(b.hits) >= b.limit {
+		return false
+	}
+	b.hits = append(b.hits, now)
+	return true
+}
+
+// githubStarsProvider is the production PopularityProvider (plan.md data
+// model): a cached, rate-limited GitHub stargazers_count fetcher behind a
+// fixed 4-worker pool.
+type githubStarsProvider struct {
+	mu      sync.Mutex
+	entries map[string]*starsEntry
+	store   *popularityStore // nil = memory only
+
+	queue  chan string
+	queued map[string]chan struct{} // in-flight+queued dedup; closed on completion
+
+	logger   *zap.Logger
+	token    string
+	disabled bool // FR-011 kill switch, read once at construction
+	baseURL  string
+
+	now func() time.Time // injected clock (tests)
+
+	budget    *rollingBudget
+	pausedMu  sync.Mutex
+	pausedTil time.Time
+
+	// baseCtx is the provider's OWN context for background fetches — never
+	// the caller's Resolve ctx (zcode review finding 3). Cancelled by Close.
+	baseCtx context.Context
+	cancel  context.CancelFunc
+	wg      sync.WaitGroup
+
+	closeOnce sync.Once
+}
+
+var _ PopularityProvider = (*githubStarsProvider)(nil)
+
+// popularityFetchesEnabled reads the FR-011 kill switch. Read once, inside
+// NewGitHubStarsProvider (zcode review finding 9: "the switch is read inside
+// the provider constructor, which then returns a no-op provider, so the
+// runtime and CLI call sites both honour it").
+func popularityFetchesEnabled() bool {
+	switch strings.ToLower(strings.TrimSpace(os.Getenv("MCPPROXY_CATALOG_POPULARITY"))) {
+	case "false", "0", "off":
+		return false
+	default:
+		return true
+	}
+}
+
+// NewGitHubStarsProvider constructs the production PopularityProvider. When
+// the FR-011 kill switch is set, the returned provider still answers Lookup
+// from whatever is already cached (e.g. a bbolt store from before the switch
+// was flipped) but starts no worker goroutines and Resolve is a no-op — a
+// caller never needs to branch on the switch itself.
+func NewGitHubStarsProvider(opts PopularityOptions) *githubStarsProvider {
+	logger := opts.Logger
+	if logger == nil {
+		logger = zap.NewNop()
+	}
+
+	token := os.Getenv("MCPPROXY_GITHUB_TOKEN") // FR-011: never the generic GITHUB_TOKEN
+	limit := githubRateLimitUnauth
+	if token != "" {
+		limit = githubRateLimitAuth
+	}
+
+	var store *popularityStore
+	if opts.DB != nil {
+		s, err := newPopularityStore(opts.DB)
+		if err != nil {
+			logger.Warn("catalog popularity: failed to open bbolt bucket; continuing memory-only", zap.Error(err))
+		} else {
+			store = s
+		}
+	}
+
+	baseCtx, cancel := context.WithCancel(context.Background())
+	p := &githubStarsProvider{
+		entries:  make(map[string]*starsEntry),
+		store:    store,
+		queue:    make(chan string, githubQueueCap),
+		queued:   make(map[string]chan struct{}),
+		logger:   logger,
+		token:    token,
+		disabled: !popularityFetchesEnabled(),
+		baseURL:  currentGitHubAPIBase(),
+		now:      time.Now,
+		budget:   newRollingBudget(limit),
+		baseCtx:  baseCtx,
+		cancel:   cancel,
+	}
+	if !p.disabled {
+		p.startWorkers()
+	}
+	return p
+}
+
+// Close stops all background fetch workers. Safe to call multiple times.
+func (p *githubStarsProvider) Close() {
+	p.closeOnce.Do(func() {
+		p.cancel()
+		p.wg.Wait()
+	})
+}
+
+func (p *githubStarsProvider) startWorkers() {
+	for i := 0; i < githubMaxConcurrentFetches; i++ {
+		p.wg.Add(1)
+		go p.worker()
+	}
+}
+
+func (p *githubStarsProvider) worker() {
+	defer p.wg.Done()
+	for {
+		select {
+		case <-p.baseCtx.Done():
+			return
+		case key, ok := <-p.queue:
+			if !ok {
+				return
+			}
+			p.fetchAndStore(key)
+		}
+	}
+}
+
+// fresh reports whether e is still within its TTL as of p.now().
+func (p *githubStarsProvider) fresh(e *starsEntry) bool {
+	return p.now().Sub(e.FetchedAt) < e.ttl()
+}
+
+// getEntryLocked returns key's entry, lazily loading it from the store on a
+// memory miss (plan.md: "Entries are loaded into memory lazily on the first
+// Lookup miss"). Caller must hold p.mu.
+func (p *githubStarsProvider) getEntryLocked(key string) *starsEntry {
+	if e, ok := p.entries[key]; ok {
+		return e
+	}
+	if p.store != nil {
+		if e, ok := p.store.get(key); ok {
+			p.entries[key] = e
+			return e
+		}
+	}
+	return nil
+}
+
+// Lookup implements PopularityProvider.
+func (p *githubStarsProvider) Lookup(key string) (int, LookupState) {
+	p.mu.Lock()
+	e := p.getEntryLocked(key)
+	p.mu.Unlock()
+	if e == nil {
+		return 0, LookupAbsent
+	}
+	return p.classify(e)
+}
+
+// classify maps an entry to its LookupState (FR-008, zcode review finding
+// 7). Whether stars are displayable depends only on whether there IS a
+// positive count (e.Stars > 0) and whether it's still fresh — this covers a
+// successful fetch, and also a since-erroring refresh that still carries a
+// last-known-good count forward (FR-008's "keep the last-known stars").
+func (p *githubStarsProvider) classify(e *starsEntry) (int, LookupState) {
+	fresh := p.fresh(e)
+	if e.Stars > 0 {
+		if fresh {
+			return e.Stars, LookupFresh
+		}
+		return e.Stars, LookupStale
+	}
+	// No signal to show right now: either a confirmed 404/451, or an entry
+	// that has never successfully resolved (including one currently backing
+	// off after an error, within its own shorter TTL).
+	if fresh {
+		return 0, LookupNegative
+	}
+	return 0, LookupAbsent
+}
+
+// Resolve implements PopularityProvider.
+func (p *githubStarsProvider) Resolve(ctx context.Context, keys []string, wait time.Duration) {
+	if p.disabled || len(keys) == 0 {
+		return
+	}
+
+	// zcode review finding 5: bail out immediately, without enqueueing
+	// anything, when we already know no fetch will be attempted right now.
+	now := p.now()
+	if p.pausedNow(now) || !p.budget.hasCapacity(now) {
+		return
+	}
+
+	var waiters []<-chan struct{}
+	for _, key := range keys {
+		if ch := p.enqueue(key); ch != nil {
+			waiters = append(waiters, ch)
+		}
+	}
+	if len(waiters) == 0 || wait <= 0 {
+		return
+	}
+
+	waitCtx, cancel := context.WithTimeout(ctx, wait)
+	defer cancel()
+	for _, ch := range waiters {
+		select {
+		case <-ch:
+		case <-waitCtx.Done():
+			return
+		}
+	}
+}
+
+// enqueue admits key to the fetch queue, returning a channel closed once the
+// fetch (or a no-op drop) completes — or nil if key needs no fetch (already
+// fresh), is already queued/in-flight (its existing completion channel is
+// returned instead, so callers share it rather than double-fetching), or the
+// queue is full (FR-009b: overflow is simply dropped — no dedup entry is
+// created, so nothing waits on it and the next search can request it again).
+func (p *githubStarsProvider) enqueue(key string) <-chan struct{} {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if e := p.getEntryLocked(key); e != nil && p.fresh(e) {
+		return nil
+	}
+	if ch, ok := p.queued[key]; ok {
+		return ch
+	}
+	select {
+	case p.queue <- key:
+		ch := make(chan struct{})
+		p.queued[key] = ch
+		return ch
+	default:
+		return nil
+	}
+}
+
+// complete removes key from the in-flight/queued dedup set and closes its
+// completion channel, waking any Resolve callers waiting on it.
+func (p *githubStarsProvider) complete(key string) {
+	p.mu.Lock()
+	ch, ok := p.queued[key]
+	delete(p.queued, key)
+	p.mu.Unlock()
+	if ok {
+		close(ch)
+	}
+}
+
+func (p *githubStarsProvider) pausedNow(now time.Time) bool {
+	p.pausedMu.Lock()
+	defer p.pausedMu.Unlock()
+	return now.Before(p.pausedTil)
+}
+
+// pauseUntil extends the breaker pause to at least until, never shortening
+// an existing longer pause.
+func (p *githubStarsProvider) pauseUntil(until time.Time) {
+	p.pausedMu.Lock()
+	defer p.pausedMu.Unlock()
+	if until.After(p.pausedTil) {
+		p.pausedTil = until
+	}
+}
+
+// fetchAndStore fetches one key (or drops it, if paused/over budget) and
+// always completes it. It runs on p.baseCtx — a context owned by the
+// provider, detached from whatever Resolve call originally enqueued the key
+// (zcode review finding 3), so the fetch outlives that call.
+func (p *githubStarsProvider) fetchAndStore(key string) {
+	defer p.complete(key)
+
+	now := p.now()
+	if p.pausedNow(now) {
+		return // breaker engaged: retried on a later Resolve call
+	}
+	if !p.budget.allow(now) {
+		return // rolling budget exhausted: retried on a later Resolve call
+	}
+
+	owner, repo, ok := splitRepoKey(key)
+	if !ok {
+		return
+	}
+
+	p.mu.Lock()
+	prev := p.getEntryLocked(key)
+	p.mu.Unlock()
+
+	ctx, cancel := context.WithTimeout(p.baseCtx, githubRequestTimeout)
+	defer cancel()
+
+	status, stars, etag, headers, fetchErr := p.doRequest(ctx, owner, repo, prev)
+	p.applyResult(key, prev, status, stars, etag, headers, fetchErr)
+}
+
+// rateLimitHeaders is the subset of GitHub's response headers the breaker
+// (FR-009d) reads.
+type rateLimitHeaders struct {
+	remaining  string
+	reset      string
+	retryAfter string
+}
+
+// doRequest issues a single, non-retrying GET against p.baseURL (FR-006:
+// "There are no retries; the breaker is the only backoff" — this
+// deliberately does NOT use registryGet, which pins to a *RegistryEntry and
+// retries 429/5xx three times, burning budget against a rate-limited API).
+func (p *githubStarsProvider) doRequest(ctx context.Context, owner, repo string, prev *starsEntry) (status, stars int, etag string, headers rateLimitHeaders, err error) {
+	reqURL := p.baseURL + "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo)
+
+	u, parseErr := url.Parse(reqURL)
+	if parseErr != nil {
+		return 0, 0, "", headers, parseErr
+	}
+	if blockErr := hostLiteralBlocked(u.Host, registryAllowPrivateFetch.Load()); blockErr != nil {
+		return 0, 0, "", headers, blockErr
+	}
+	if guardErr := guardRegistryTargetHost(ctx, reqURL); guardErr != nil {
+		return 0, 0, "", headers, guardErr
+	}
+
+	req, reqErr := http.NewRequestWithContext(ctx, http.MethodGet, reqURL, http.NoBody)
+	if reqErr != nil {
+		return 0, 0, "", headers, reqErr
+	}
+	req.Header.Set("Accept", "application/vnd.github+json")
+	req.Header.Set("X-GitHub-Api-Version", "2022-11-28")
+	req.Header.Set("User-Agent", registryUserAgent())
+	if prev != nil && prev.ETag != "" {
+		req.Header.Set("If-None-Match", prev.ETag)
+	}
+	if p.token != "" {
+		req.Header.Set("Authorization", "Bearer "+p.token)
+	}
+
+	resp, doErr := sharedRegistryClient().Do(req)
+	if doErr != nil {
+		return 0, 0, "", headers, doErr
+	}
+	defer resp.Body.Close()
+
+	body, readErr := io.ReadAll(io.LimitReader(resp.Body, githubMaxBodyBytes+1))
+	if readErr != nil {
+		return 0, 0, "", headers, readErr
+	}
+
+	headers = rateLimitHeaders{
+		remaining:  resp.Header.Get("X-RateLimit-Remaining"),
+		reset:      resp.Header.Get("X-RateLimit-Reset"),
+		retryAfter: resp.Header.Get("Retry-After"),
+	}
+
+	switch resp.StatusCode {
+	case http.StatusOK:
+		var payload struct {
+			StargazersCount int `json:"stargazers_count"`
+		}
+		_ = json.Unmarshal(body, &payload)
+		return resp.StatusCode, payload.StargazersCount, resp.Header.Get("ETag"), headers, nil
+	case http.StatusNotModified:
+		s := 0
+		if prev != nil {
+			s = prev.Stars
+		}
+		etag := resp.Header.Get("ETag")
+		if etag == "" && prev != nil {
+			etag = prev.ETag
+		}
+		return resp.StatusCode, s, etag, headers, nil
+	default:
+		return resp.StatusCode, 0, "", headers, nil
+	}
+}
+
+// applyResult stores the outcome of one fetch attempt (FR-008: a failed
+// refresh keeps the last-known stars/etag and only advances FetchedAt; only
+// a definitive 404/451 clears the stars) and, on an actual HTTP response
+// (fetchErr == nil), updates the breaker from its rate-limit headers.
+func (p *githubStarsProvider) applyResult(key string, prev *starsEntry, status, stars int, etag string, headers rateLimitHeaders, fetchErr error) {
+	now := p.now()
+	entry := &starsEntry{FetchedAt: now, Status: status}
+
+	switch {
+	case fetchErr != nil:
+		entry.Status = 0
+		if prev != nil {
+			entry.Stars, entry.ETag = prev.Stars, prev.ETag
+		}
+	case status == http.StatusOK:
+		entry.Stars = stars
+		entry.ETag = etag
+	case status == http.StatusNotModified:
+		entry.Stars = stars
+		entry.ETag = etag
+	case status == http.StatusNotFound || status == http.StatusUnavailableForLegalReasons:
+		// Definitive negative: Stars stays 0 regardless of what prev had —
+		// the repo really is gone/unavailable now.
+	default:
+		// Any other status (5xx, 403, 429, …): not definitive — keep the
+		// last-known stars/etag, just advance the (short, 1h) revalidate
+		// time via FetchedAt above.
+		if prev != nil {
+			entry.Stars, entry.ETag = prev.Stars, prev.ETag
+		}
+	}
+
+	p.mu.Lock()
+	p.entries[key] = entry
+	p.evictIfNeededLocked()
+	p.mu.Unlock()
+
+	if p.store != nil {
+		if err := p.store.put(key, entry); err != nil {
+			p.logger.Warn("catalog popularity: failed to persist entry", zap.String("key", key), zap.Error(err))
+		}
+	}
+
+	if fetchErr == nil {
+		p.applyBreaker(status, headers)
+	}
+}
+
+// evictIfNeededLocked drops the single oldest-FetchedAt entry once the cache
+// exceeds its cap (FR-008). Caller must hold p.mu. Only ever one entry over
+// cap at a time, since insertion happens one key at a time.
+func (p *githubStarsProvider) evictIfNeededLocked() {
+	if len(p.entries) <= githubMaxCacheKeys {
+		return
+	}
+	oldestKey := ""
+	var oldestTime time.Time
+	first := true
+	for k, e := range p.entries {
+		if first || e.FetchedAt.Before(oldestTime) {
+			oldestKey, oldestTime, first = k, e.FetchedAt, false
+		}
+	}
+	if oldestKey == "" {
+		return
+	}
+	delete(p.entries, oldestKey)
+	if p.store != nil {
+		if err := p.store.delete(oldestKey); err != nil {
+			p.logger.Warn("catalog popularity: failed to evict entry", zap.String("key", oldestKey), zap.Error(err))
+		}
+	}
+}
+
+// applyBreaker updates the pause window from one response's rate-limit
+// headers (FR-009d): a 403/429 (Retry-After, else the reset time, else a 60s
+// default) or ANY response reporting X-RateLimit-Remaining <= 5 (the reset
+// time, else 60s).
+func (p *githubStarsProvider) applyBreaker(status int, headers rateLimitHeaders) {
+	now := p.now()
+
+	if status == http.StatusForbidden || status == http.StatusTooManyRequests {
+		if until, ok := parseRetryAfter(headers.retryAfter, now); ok {
+			p.pauseUntil(until)
+			return
+		}
+		if until, ok := parseUnixSeconds(headers.reset); ok {
+			p.pauseUntil(until)
+			return
+		}
+		p.pauseUntil(now.Add(githubBreakerPause))
+		return
+	}
+
+	if remaining, ok := parseNonNegativeInt(headers.remaining); ok && remaining <= githubLowRemainingThreshold {
+		if until, ok := parseUnixSeconds(headers.reset); ok {
+			p.pauseUntil(until)
+			return
+		}
+		p.pauseUntil(now.Add(githubBreakerPause))
+	}
+}
+
+func splitRepoKey(key string) (owner, repo string, ok bool) {
+	i := strings.IndexByte(key, '/')
+	if i <= 0 || i == len(key)-1 {
+		return "", "", false
+	}
+	return key[:i], key[i+1:], true
+}
+
+func parseNonNegativeInt(v string) (int, bool) {
+	if v == "" {
+		return 0, false
+	}
+	n, err := strconv.Atoi(v)
+	if err != nil || n < 0 {
+		return 0, false
+	}
+	return n, true
+}
+
+func parseUnixSeconds(v string) (time.Time, bool) {
+	if v == "" {
+		return time.Time{}, false
+	}
+	sec, err := strconv.ParseInt(v, 10, 64)
+	if err != nil {
+		return time.Time{}, false
+	}
+	return time.Unix(sec, 0), true
+}
+
+// parseRetryAfter supports both Retry-After forms (RFC 9110): an integer
+// number of seconds, or an HTTP-date.
+func parseRetryAfter(v string, now time.Time) (time.Time, bool) {
+	if v == "" {
+		return time.Time{}, false
+	}
+	if secs, err := strconv.Atoi(v); err == nil {
+		return now.Add(time.Duration(secs) * time.Second), true
+	}
+	if t, err := http.ParseTime(v); err == nil {
+		return t, true
+	}
+	return time.Time{}, false
+}
diff --git a/internal/registries/popularity_github_test.go b/internal/registries/popularity_github_test.go
new file mode 100644
index 000000000..4d723b012
--- /dev/null
+++ b/internal/registries/popularity_github_test.go
@@ -0,0 +1,535 @@
+package registries
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// --- T005: fetch behavior ---------------------------------------------------
+
+func TestGitHubStarsProvider_Fetch200StoresStarsAndSendsExactHeaders(t *testing.T) {
+	var gotHeaders http.Header
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotHeaders = r.Header.Clone()
+		w.Header().Set("ETag", `"v1"`)
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"stargazers_count": 123}`))
+	}))
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	p.Resolve(context.Background(), []string{"o/r"}, time.Second)
+
+	stars, state := p.Lookup("o/r")
+	if state != LookupFresh || stars != 123 {
+		t.Fatalf("expected Fresh/123, got state=%d stars=%d", state, stars)
+	}
+	if got := gotHeaders.Get("Accept"); got != "application/vnd.github+json" {
+		t.Errorf("Accept header = %q", got)
+	}
+	if got := gotHeaders.Get("X-GitHub-Api-Version"); got != "2022-11-28" {
+		t.Errorf("X-GitHub-Api-Version header = %q", got)
+	}
+	if got := gotHeaders.Get("User-Agent"); got == "" {
+		t.Error("expected a non-empty User-Agent")
+	}
+	if got := gotHeaders.Get("Authorization"); got != "" {
+		t.Errorf("expected no Authorization header without MCPPROXY_GITHUB_TOKEN, got %q", got)
+	}
+	if got := gotHeaders.Get("If-None-Match"); got != "" {
+		t.Errorf("expected no If-None-Match on a first fetch, got %q", got)
+	}
+}
+
+func TestGitHubStarsProvider_BearerTokenSentOnlyWhenConfigured(t *testing.T) {
+	var gotAuth string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotAuth = r.Header.Get("Authorization")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"stargazers_count": 1}`))
+	}))
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	t.Setenv("MCPPROXY_GITHUB_TOKEN", "secret-token")
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	p.Resolve(context.Background(), []string{"o/r"}, time.Second)
+	if gotAuth != "Bearer secret-token" {
+		t.Fatalf("expected 'Bearer secret-token', got %q", gotAuth)
+	}
+	if p.budget.limit != githubRateLimitAuth {
+		t.Fatalf("expected the authenticated rolling budget (%d) once a token is set, got %d", githubRateLimitAuth, p.budget.limit)
+	}
+}
+
+func TestGitHubStarsProvider_Fetch304RevalidatesKeepsStars(t *testing.T) {
+	var reqCount int32
+	var gotIfNoneMatch string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		n := atomic.AddInt32(&reqCount, 1)
+		if n == 1 {
+			w.Header().Set("ETag", `"v1"`)
+			w.WriteHeader(http.StatusOK)
+			_, _ = w.Write([]byte(`{"stargazers_count": 50}`))
+			return
+		}
+		gotIfNoneMatch = r.Header.Get("If-None-Match")
+		w.Header().Set("ETag", `"v1"`)
+		w.WriteHeader(http.StatusNotModified)
+	}))
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	fixedNow := time.Now()
+	p.now = func() time.Time { return fixedNow }
+
+	p.Resolve(context.Background(), []string{"o/r"}, time.Second)
+	if stars, state := p.Lookup("o/r"); state != LookupFresh || stars != 50 {
+		t.Fatalf("after first fetch: expected Fresh/50, got state=%d stars=%d", state, stars)
+	}
+
+	// Advance the injected clock past the 24h positive TTL so the entry
+	// reads Stale and gets re-enqueued.
+	fixedNow = fixedNow.Add(25 * time.Hour)
+
+	p.Resolve(context.Background(), []string{"o/r"}, time.Second)
+	if gotIfNoneMatch != `"v1"` {
+		t.Fatalf("expected If-None-Match %q on the revalidation request, got %q", `"v1"`, gotIfNoneMatch)
+	}
+	stars, state := p.Lookup("o/r")
+	if state != LookupFresh || stars != 50 {
+		t.Fatalf("after 304: expected stars preserved (Fresh/50), got state=%d stars=%d", state, stars)
+	}
+	if got := atomic.LoadInt32(&reqCount); got != 2 {
+		t.Fatalf("expected exactly 2 requests, got %d", got)
+	}
+}
+
+func TestGitHubStarsProvider_Fetch404IsNegative(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	p.Resolve(context.Background(), []string{"o/gone"}, time.Second)
+	stars, state := p.Lookup("o/gone")
+	if state != LookupNegative || stars != 0 {
+		t.Fatalf("expected Negative/0 for a 404, got state=%d stars=%d", state, stars)
+	}
+}
+
+func TestGitHubStarsProvider_Fetch500KeepsLastKnownStars(t *testing.T) {
+	var reqCount int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		n := atomic.AddInt32(&reqCount, 1)
+		if n == 1 {
+			w.WriteHeader(http.StatusOK)
+			_, _ = w.Write([]byte(`{"stargazers_count": 30}`))
+			return
+		}
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	fixedNow := time.Now()
+	p.now = func() time.Time { return fixedNow }
+
+	p.Resolve(context.Background(), []string{"o/r"}, time.Second)
+	if stars, state := p.Lookup("o/r"); state != LookupFresh || stars != 30 {
+		t.Fatalf("after first fetch: expected Fresh/30, got state=%d stars=%d", state, stars)
+	}
+
+	fixedNow = fixedNow.Add(25 * time.Hour) // past the 24h positive TTL -> re-enqueued
+	p.Resolve(context.Background(), []string{"o/r"}, time.Second)
+
+	stars, state := p.Lookup("o/r")
+	if stars != 30 {
+		t.Fatalf("expected the last-known stars (30) preserved through a 500, got %d", stars)
+	}
+	// Freshly time-stamped by the failed refresh, within its own 1h error
+	// TTL: still reads Fresh (it HAS a positive count).
+	if state != LookupFresh {
+		t.Fatalf("expected Fresh (last-known stars, revalidate time advanced), got state=%d", state)
+	}
+	if got := atomic.LoadInt32(&reqCount); got != 2 {
+		t.Fatalf("expected exactly 2 requests, got %d", got)
+	}
+}
+
+func TestGitHubStarsProvider_BodyCappedAt1MiB(t *testing.T) {
+	padding := make([]byte, githubMaxBodyBytes+1000)
+	for i := range padding {
+		padding[i] = 'x'
+	}
+	// stargazers_count sits well past the 1 MiB cap, so it must never be read
+	// if the cap is actually enforced.
+	payload := append([]byte(`{"padding":"`), padding...)
+	payload = append(payload, []byte(`","stargazers_count": 999999}`)...)
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(payload)
+	}))
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	p.Resolve(context.Background(), []string{"o/r"}, 2*time.Second)
+	stars, _ := p.Lookup("o/r")
+	if stars == 999999 {
+		t.Fatal("expected the 1 MiB body cap to prevent stargazers_count from being read")
+	}
+}
+
+func TestGitHubStarsProvider_FollowsSameHostRedirect(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/repos/o/old", func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, "/repos/o/new", http.StatusMovedPermanently)
+	})
+	mux.HandleFunc("/repos/o/new", func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"stargazers_count": 42}`))
+	})
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	p.Resolve(context.Background(), []string{"o/old"}, time.Second)
+	stars, state := p.Lookup("o/old")
+	if state != LookupFresh || stars != 42 {
+		t.Fatalf("expected the same-host redirect to be followed, got state=%d stars=%d", state, stars)
+	}
+}
+
+// --- T006: TTL/stale/requeue, dedup, overflow, concurrency, budget, breaker -
+
+func TestGitHubStarsProvider_EnqueueDedupsSameKey(t *testing.T) {
+	t.Setenv("MCPPROXY_CATALOG_POPULARITY", "false") // no workers; drive enqueue directly
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	ch1 := p.enqueue("o/r")
+	ch2 := p.enqueue("o/r")
+	if ch1 == nil || ch2 == nil {
+		t.Fatal("expected both enqueue calls to be admitted")
+	}
+	if ch1 != ch2 {
+		t.Fatal("expected the second enqueue of an already-queued key to share its completion channel")
+	}
+}
+
+func TestGitHubStarsProvider_QueueOverflowDropsWithoutLeavingDedupEntry(t *testing.T) {
+	t.Setenv("MCPPROXY_CATALOG_POPULARITY", "false") // no workers; queue never drains
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	for i := 0; i < githubQueueCap; i++ {
+		p.queue <- fmt.Sprintf("filler/%d", i)
+	}
+
+	ch := p.enqueue("overflow/key")
+	if ch != nil {
+		t.Fatal("expected enqueue to return nil once the queue is full")
+	}
+	p.mu.Lock()
+	_, tracked := p.queued["overflow/key"]
+	p.mu.Unlock()
+	if tracked {
+		t.Fatal("expected the dropped key to leave no dedup entry behind (so it can be requested again)")
+	}
+}
+
+func TestGitHubStarsProvider_ConcurrencyCappedAtFour(t *testing.T) {
+	var active int32
+	var mu sync.Mutex
+	var maxActive int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		n := atomic.AddInt32(&active, 1)
+		mu.Lock()
+		if n > maxActive {
+			maxActive = n
+		}
+		mu.Unlock()
+		time.Sleep(80 * time.Millisecond)
+		atomic.AddInt32(&active, -1)
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"stargazers_count": 1}`))
+	}))
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	keys := make([]string, 0, 12)
+	for i := 0; i < 12; i++ {
+		keys = append(keys, fmt.Sprintf("owner/repo-%d", i))
+	}
+	p.Resolve(context.Background(), keys, 3*time.Second)
+
+	mu.Lock()
+	got := maxActive
+	mu.Unlock()
+	if got > githubMaxConcurrentFetches {
+		t.Fatalf("observed %d concurrent fetches, want <= %d", got, githubMaxConcurrentFetches)
+	}
+	if got < 2 {
+		t.Fatalf("expected some real concurrency (>=2 at once), got max=%d", got)
+	}
+	for _, k := range keys {
+		if _, state := p.Lookup(k); state != LookupFresh {
+			t.Errorf("expected %s to have been fetched (Fresh), got state=%d", k, state)
+		}
+	}
+}
+
+func TestRollingBudget_EnforcesLimitPerWindow(t *testing.T) {
+	now := time.Unix(1_000_000, 0)
+	b := newRollingBudget(2)
+	if !b.allow(now) {
+		t.Fatal("expected the 1st request to be allowed")
+	}
+	if !b.allow(now) {
+		t.Fatal("expected the 2nd request to be allowed")
+	}
+	if b.allow(now) {
+		t.Fatal("expected the 3rd request within the same window to be blocked")
+	}
+	later := now.Add(61 * time.Minute)
+	if !b.allow(later) {
+		t.Fatal("expected a request to be allowed again once the window has rolled past")
+	}
+}
+
+func TestGitHubStarsProvider_DefaultBudgetIsUnauthenticated(t *testing.T) {
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+	if p.budget.limit != githubRateLimitUnauth {
+		t.Fatalf("expected the unauthenticated budget (%d), got %d", githubRateLimitUnauth, p.budget.limit)
+	}
+}
+
+// TestGitHubStarsProvider_BreakerPausesOn403 pins SC-004: a 403 carrying
+// X-RateLimit-Remaining: 0 and a future reset pauses ALL further fetches
+// until that reset, while stale cached values keep being served.
+func TestGitHubStarsProvider_BreakerPausesOn403(t *testing.T) {
+	var reqCount int32
+	resetAt := time.Now().Add(2 * time.Hour) // far enough that test latency can't cross it
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		n := atomic.AddInt32(&reqCount, 1)
+		if n == 1 {
+			w.Header().Set("X-RateLimit-Remaining", "0")
+			w.Header().Set("X-RateLimit-Reset", strconv.FormatInt(resetAt.Unix(), 10))
+			w.WriteHeader(http.StatusForbidden)
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"stargazers_count": 1}`))
+	}))
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	p.Resolve(context.Background(), []string{"o/r1"}, 500*time.Millisecond)
+	if got := atomic.LoadInt32(&reqCount); got != 1 {
+		t.Fatalf("expected exactly 1 request before the breaker engaged, got %d", got)
+	}
+
+	// Seed a stale cached value to assert it is still served during the pause.
+	p.mu.Lock()
+	p.entries["o/stale"] = &starsEntry{Stars: 9, Status: http.StatusOK, FetchedAt: time.Now().Add(-48 * time.Hour)}
+	p.mu.Unlock()
+
+	p.Resolve(context.Background(), []string{"o/r2"}, 200*time.Millisecond)
+	if got := atomic.LoadInt32(&reqCount); got != 1 {
+		t.Fatalf("expected the breaker to block further requests before the reset, got %d total requests", got)
+	}
+
+	stars, state := p.Lookup("o/stale")
+	if state != LookupStale || stars != 9 {
+		t.Fatalf("expected the stale cached value to still be served during the pause, got stars=%d state=%d", stars, state)
+	}
+}
+
+// --- T008: Resolve wait bounds ----------------------------------------------
+
+func TestGitHubStarsProvider_ResolveReturnsAroundWait(t *testing.T) {
+	block := make(chan struct{})
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		<-block
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"stargazers_count": 5}`))
+	}))
+	defer func() {
+		close(block)
+		srv.Close()
+	}()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	start := time.Now()
+	p.Resolve(context.Background(), []string{"o/r"}, 100*time.Millisecond)
+	elapsed := time.Since(start)
+	if elapsed < 100*time.Millisecond {
+		t.Fatalf("expected Resolve to wait at least 100ms, returned after %s", elapsed)
+	}
+	if elapsed > 800*time.Millisecond {
+		t.Fatalf("expected Resolve to return promptly after its wait, took %s", elapsed)
+	}
+	if _, state := p.Lookup("o/r"); state != LookupAbsent {
+		t.Fatalf("expected no result yet (stub still blocked), got state=%d", state)
+	}
+}
+
+func TestGitHubStarsProvider_ResolveNeverOutlivesCtx(t *testing.T) {
+	block := make(chan struct{})
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		<-block
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"stargazers_count": 5}`))
+	}))
+	defer func() {
+		close(block)
+		srv.Close()
+	}()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Millisecond)
+	defer cancel()
+	start := time.Now()
+	p.Resolve(ctx, []string{"o/r"}, 5*time.Second) // wait far longer than ctx
+	if elapsed := time.Since(start); elapsed > 800*time.Millisecond {
+		t.Fatalf("expected Resolve to return once ctx expired, took %s", elapsed)
+	}
+}
+
+func TestGitHubStarsProvider_ResolveWaitZeroNeverBlocks(t *testing.T) {
+	block := make(chan struct{})
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		<-block
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"stargazers_count": 5}`))
+	}))
+	defer func() {
+		close(block)
+		srv.Close()
+	}()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	start := time.Now()
+	p.Resolve(context.Background(), []string{"o/r"}, 0)
+	if elapsed := time.Since(start); elapsed > 50*time.Millisecond {
+		t.Fatalf("expected wait=0 to return immediately without blocking, took %s", elapsed)
+	}
+}
+
+func TestGitHubStarsProvider_FetchContinuesAfterResolveReturns(t *testing.T) {
+	block := make(chan struct{})
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		<-block
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"stargazers_count": 5}`))
+	}))
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	p.Resolve(context.Background(), []string{"o/r"}, 50*time.Millisecond) // returns before the stub answers
+	if _, state := p.Lookup("o/r"); state != LookupAbsent {
+		t.Fatalf("expected no result yet, got state=%d", state)
+	}
+
+	close(block) // let the stub answer now
+
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if _, state := p.Lookup("o/r"); state == LookupFresh {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatal("expected the background fetch to complete and land in the cache after Resolve returned")
+}
+
+// --- T009: kill switch -------------------------------------------------------
+
+func TestPopularityFetchesEnabled(t *testing.T) {
+	cases := map[string]bool{
+		"":      true,
+		"true":  true,
+		"false": false,
+		"0":     false,
+		"off":   false,
+		"OFF":   false,
+		"False": false,
+	}
+	for v, want := range cases {
+		t.Run(fmt.Sprintf("env=%q", v), func(t *testing.T) {
+			t.Setenv("MCPPROXY_CATALOG_POPULARITY", v)
+			if got := popularityFetchesEnabled(); got != want {
+				t.Errorf("popularityFetchesEnabled() = %v, want %v", got, want)
+			}
+		})
+	}
+}
+
+func TestGitHubStarsProvider_KillSwitchNeverFetches(t *testing.T) {
+	var reqCount int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		atomic.AddInt32(&reqCount, 1)
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"stargazers_count": 5}`))
+	}))
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	t.Setenv("MCPPROXY_CATALOG_POPULARITY", "false")
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	p.Resolve(context.Background(), []string{"o/r"}, 200*time.Millisecond)
+	time.Sleep(50 * time.Millisecond)
+	if got := atomic.LoadInt32(&reqCount); got != 0 {
+		t.Fatalf("expected the kill switch to prevent any outbound request, got %d", got)
+	}
+}
diff --git a/internal/registries/popularity_key.go b/internal/registries/popularity_key.go
new file mode 100644
index 000000000..032d581d6
--- /dev/null
+++ b/internal/registries/popularity_key.go
@@ -0,0 +1,65 @@
+package registries
+
+import (
+	"net/url"
+	"regexp"
+	"strings"
+)
+
+// githubOwnerPattern/githubRepoPattern are GitHub's own name rules (FR-003).
+var (
+	githubOwnerPattern = regexp.MustCompile(`^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$`)
+	githubRepoPattern  = regexp.MustCompile(`^[A-Za-z0-9._-]{1,100}$`)
+)
+
+// GitHubRepoKey normalizes a source-code URL into a lower-cased "owner/repo"
+// key when it identifies a github.com repository whose owner and repo both
+// pass GitHub's name rules (Spec 110 FR-003). It handles every edge-case
+// form spec.md calls out: a `git+` prefix, a `.git` suffix, a monorepo
+// subpath (only the first two path segments are taken), a `www.` prefix, a
+// trailing slash, and mixed case. Anything else — a non-GitHub host, a gist,
+// a malformed URL, or an owner/repo that fails the name rules (including the
+// literal repo names "." and "..") — returns ok=false and never causes a
+// fetch.
+func GitHubRepoKey(sourceCodeURL string) (key string, ok bool) {
+	raw := strings.TrimSpace(sourceCodeURL)
+	if raw == "" {
+		return "", false
+	}
+	raw = strings.TrimPrefix(raw, "git+")
+
+	u, err := url.Parse(raw)
+	if err != nil {
+		return "", false
+	}
+	if u.Scheme != "http" && u.Scheme != "https" {
+		return "", false
+	}
+
+	host := strings.ToLower(u.Hostname())
+	host = strings.TrimPrefix(host, "www.")
+	if host != "github.com" {
+		return "", false
+	}
+
+	path := strings.Trim(u.Path, "/")
+	if path == "" {
+		return "", false
+	}
+	parts := strings.SplitN(path, "/", 3) // owner, repo, rest (monorepo subpath discarded)
+	if len(parts) < 2 || parts[0] == "" || parts[1] == "" {
+		return "", false
+	}
+
+	owner := parts[0]
+	repo := strings.TrimSuffix(parts[1], ".git")
+
+	if repo == "." || repo == ".." {
+		return "", false
+	}
+	if !githubOwnerPattern.MatchString(owner) || !githubRepoPattern.MatchString(repo) {
+		return "", false
+	}
+
+	return strings.ToLower(owner + "/" + repo), true
+}
diff --git a/internal/registries/popularity_key_test.go b/internal/registries/popularity_key_test.go
new file mode 100644
index 000000000..c6aa88a68
--- /dev/null
+++ b/internal/registries/popularity_key_test.go
@@ -0,0 +1,48 @@
+package registries
+
+import "testing"
+
+// TestGitHubRepoKey covers every edge-case form spec.md calls out (FR-003).
+func TestGitHubRepoKey(t *testing.T) {
+	tests := []struct {
+		name    string
+		url     string
+		wantKey string
+		wantOK  bool
+	}{
+		{"plain https", "https://github.com/o/r", "o/r", true},
+		{"git suffix", "https://github.com/o/r.git", "o/r", true},
+		{"monorepo subpath", "https://github.com/o/r/tree/main/src/x", "o/r", true},
+		{"git+https prefix", "git+https://github.com/o/r", "o/r", true},
+		{"git+https with .git", "git+https://github.com/o/r.git", "o/r", true},
+		{"http scheme", "http://github.com/o/r", "o/r", true},
+		{"www prefix", "https://www.github.com/o/r", "o/r", true},
+		{"trailing slash", "https://github.com/o/r/", "o/r", true},
+		{"mixed case", "https://GitHub.com/Owner/Repo", "owner/repo", true},
+		{"reference monorepo", "https://github.com/modelcontextprotocol/servers/tree/main/src/fetch", "modelcontextprotocol/servers", true},
+
+		{"empty", "", "", false},
+		{"non-github host", "https://gitlab.com/o/r", "", false},
+		{"gist host", "https://gist.github.com/o/r", "", false},
+		{"owner only, no repo", "https://github.com/o", "", false},
+		{"malformed url", "://not a url", "", false},
+		{"repo is dot", "https://github.com/o/.", "", false},
+		{"repo is dotdot", "https://github.com/o/..", "", false},
+		{"owner fails name rule (leading dash)", "https://github.com/-o/r", "", false},
+		{"repo fails name rule (space)", "https://github.com/o/r r", "", false},
+		{"ssh-style (no scheme)", "git@github.com:o/r.git", "", false},
+		{"non-http scheme", "ftp://github.com/o/r", "", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			key, ok := GitHubRepoKey(tt.url)
+			if ok != tt.wantOK {
+				t.Fatalf("GitHubRepoKey(%q) ok = %v, want %v (key=%q)", tt.url, ok, tt.wantOK, key)
+			}
+			if ok && key != tt.wantKey {
+				t.Fatalf("GitHubRepoKey(%q) = %q, want %q", tt.url, key, tt.wantKey)
+			}
+		})
+	}
+}
diff --git a/internal/registries/popularity_store.go b/internal/registries/popularity_store.go
new file mode 100644
index 000000000..7c55fd3d9
--- /dev/null
+++ b/internal/registries/popularity_store.go
@@ -0,0 +1,91 @@
+package registries
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"go.etcd.io/bbolt"
+)
+
+// popularityBucketName is the dedicated bbolt bucket for the popularity
+// cache (Spec 110 FR-008, plan.md R4: cache.Manager does not fit — fixed 2h
+// TTL, deletes expired records, and Spec 105 authorization frames that are
+// irrelevant here).
+const popularityBucketName = "catalog_popularity"
+
+// popularityStore persists starsEntry records to popularityBucketName. A nil
+// *popularityStore (never constructed) means memory-only, which is what the
+// CLI in-process fallback uses (plan.md wiring table).
+type popularityStore struct {
+	db *bbolt.DB
+}
+
+// newPopularityStore opens (creating if needed) the popularity bucket on an
+// already-open bbolt database.
+func newPopularityStore(db *bbolt.DB) (*popularityStore, error) {
+	if db == nil {
+		return nil, fmt.Errorf("catalog popularity store: nil db")
+	}
+	if err := db.Update(func(tx *bbolt.Tx) error {
+		_, err := tx.CreateBucketIfNotExists([]byte(popularityBucketName))
+		return err
+	}); err != nil {
+		return nil, fmt.Errorf("catalog popularity store: create bucket: %w", err)
+	}
+	return &popularityStore{db: db}, nil
+}
+
+// get returns the persisted entry for key, or ok=false if there is none (or
+// it fails to decode — treated the same as absent rather than as an error,
+// since a corrupt single record must never break the whole cache).
+func (s *popularityStore) get(key string) (*starsEntry, bool) {
+	var entry starsEntry
+	found := false
+	_ = s.db.View(func(tx *bbolt.Tx) error {
+		b := tx.Bucket([]byte(popularityBucketName))
+		if b == nil {
+			return nil
+		}
+		v := b.Get([]byte(key))
+		if v == nil {
+			return nil
+		}
+		if err := json.Unmarshal(v, &entry); err != nil {
+			return nil //nolint:nilerr // a corrupt record is treated as absent, not fatal
+		}
+		found = true
+		return nil
+	})
+	if !found {
+		return nil, false
+	}
+	return &entry, true
+}
+
+// put persists entry under key, creating the bucket if a prior open somehow
+// missed it (defensive; newPopularityStore already creates it).
+func (s *popularityStore) put(key string, entry *starsEntry) error {
+	data, err := json.Marshal(entry)
+	if err != nil {
+		return err
+	}
+	return s.db.Update(func(tx *bbolt.Tx) error {
+		b, err := tx.CreateBucketIfNotExists([]byte(popularityBucketName))
+		if err != nil {
+			return err
+		}
+		return b.Put([]byte(key), data)
+	})
+}
+
+// delete removes key (used by cap eviction — FR-008: "evicting the oldest
+// fetched_at first").
+func (s *popularityStore) delete(key string) error {
+	return s.db.Update(func(tx *bbolt.Tx) error {
+		b := tx.Bucket([]byte(popularityBucketName))
+		if b == nil {
+			return nil
+		}
+		return b.Delete([]byte(key))
+	})
+}
diff --git a/internal/registries/popularity_store_test.go b/internal/registries/popularity_store_test.go
new file mode 100644
index 000000000..b83365c2a
--- /dev/null
+++ b/internal/registries/popularity_store_test.go
@@ -0,0 +1,127 @@
+package registries
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+
+	"go.etcd.io/bbolt"
+)
+
+func openTempPopularityDB(t *testing.T) *bbolt.DB {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "popularity.db")
+	db, err := bbolt.Open(path, 0o600, &bbolt.Options{Timeout: time.Second})
+	if err != nil {
+		t.Fatalf("bbolt.Open: %v", err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	return db
+}
+
+// TestPopularityStore_RoundTrip pins the basic put/get round trip (T007).
+func TestPopularityStore_RoundTrip(t *testing.T) {
+	db := openTempPopularityDB(t)
+	store, err := newPopularityStore(db)
+	if err != nil {
+		t.Fatalf("newPopularityStore: %v", err)
+	}
+
+	entry := &starsEntry{Stars: 42, ETag: `"abc"`, FetchedAt: time.Now().UTC().Truncate(time.Second), Status: 200}
+	if err := store.put("o/r", entry); err != nil {
+		t.Fatalf("put: %v", err)
+	}
+
+	got, ok := store.get("o/r")
+	if !ok {
+		t.Fatal("expected the entry to round-trip")
+	}
+	if got.Stars != entry.Stars || got.ETag != entry.ETag || got.Status != entry.Status || !got.FetchedAt.Equal(entry.FetchedAt) {
+		t.Fatalf("round-tripped entry mismatch: got %+v, want %+v", got, entry)
+	}
+
+	if _, ok := store.get("missing/key"); ok {
+		t.Fatal("expected a missing key to report ok=false")
+	}
+}
+
+// TestPopularityStore_Delete pins that delete removes a persisted entry.
+func TestPopularityStore_Delete(t *testing.T) {
+	db := openTempPopularityDB(t)
+	store, err := newPopularityStore(db)
+	if err != nil {
+		t.Fatalf("newPopularityStore: %v", err)
+	}
+	_ = store.put("o/r", &starsEntry{Stars: 1, FetchedAt: time.Now()})
+	if err := store.delete("o/r"); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+	if _, ok := store.get("o/r"); ok {
+		t.Fatal("expected the entry to be gone after delete")
+	}
+}
+
+// TestGitHubStarsProvider_LazyLoadFromStore pins that a provider restart
+// (fresh githubStarsProvider over the SAME bbolt db) sees a previously
+// fetched entry via Lookup with NO fetch — the lazy-load-on-miss path
+// (plan.md data model) survives a restart.
+func TestGitHubStarsProvider_LazyLoadFromStore(t *testing.T) {
+	db := openTempPopularityDB(t)
+	store, err := newPopularityStore(db)
+	if err != nil {
+		t.Fatalf("newPopularityStore: %v", err)
+	}
+	fetchedAt := time.Now()
+	if err := store.put("o/r", &starsEntry{Stars: 77, Status: 200, FetchedAt: fetchedAt}); err != nil {
+		t.Fatalf("seed put: %v", err)
+	}
+
+	t.Setenv("MCPPROXY_CATALOG_POPULARITY", "false") // no workers; this test is Lookup-only
+	provider := NewGitHubStarsProvider(PopularityOptions{DB: db})
+	defer provider.Close()
+
+	stars, state := provider.Lookup("o/r")
+	if state != LookupFresh {
+		t.Fatalf("expected LookupFresh from the pre-seeded store, got state=%d stars=%d", state, stars)
+	}
+	if stars != 77 {
+		t.Fatalf("expected stars=77 from the pre-seeded store, got %d", stars)
+	}
+}
+
+// TestGitHubStarsProvider_CapEviction pins FR-008's 5000-key cap: inserting
+// one more than the cap evicts the single oldest-FetchedAt entry (from both
+// memory and the store).
+func TestGitHubStarsProvider_CapEviction(t *testing.T) {
+	db := openTempPopularityDB(t)
+	t.Setenv("MCPPROXY_CATALOG_POPULARITY", "false")
+	provider := NewGitHubStarsProvider(PopularityOptions{DB: db})
+	defer provider.Close()
+
+	base := time.Now().Add(-time.Hour)
+	provider.mu.Lock()
+	for i := 0; i < githubMaxCacheKeys; i++ {
+		key := keyForIndex(i)
+		provider.entries[key] = &starsEntry{Stars: 1, Status: 200, FetchedAt: base.Add(time.Duration(i) * time.Second)}
+	}
+	provider.mu.Unlock()
+
+	// The oldest key (index 0) should be evicted once we go one over cap.
+	provider.applyResult("new/key", nil, 200, 5, "", rateLimitHeaders{}, nil)
+
+	provider.mu.Lock()
+	count := len(provider.entries)
+	_, oldestStillPresent := provider.entries[keyForIndex(0)]
+	provider.mu.Unlock()
+
+	if count != githubMaxCacheKeys {
+		t.Fatalf("expected the entry count to stay capped at %d, got %d", githubMaxCacheKeys, count)
+	}
+	if oldestStillPresent {
+		t.Fatal("expected the oldest entry to have been evicted")
+	}
+}
+
+func keyForIndex(i int) string {
+	return "owner/repo-" + string(rune('a'+(i%26))) + string(rune('a'+((i/26)%26))) + string(rune('a'+((i/676)%26)))
+}
diff --git a/internal/registries/rank_test.go b/internal/registries/rank_test.go
index 38fe00ef9..5095b3209 100644
--- a/internal/registries/rank_test.go
+++ b/internal/registries/rank_test.go
@@ -70,6 +70,52 @@ func TestRank_MissingPopularityIsZero(t *testing.T) {
 	}
 }
 
+// TestRank_StarsBeatInstalls pins FR-004: stars is the primary popularity
+// key — a hit with fewer stars never loses to one with vastly more installs.
+func TestRank_StarsBeatInstalls(t *testing.T) {
+	starred := CatalogHit{Popularity: &Popularity{Stars: intPtr(10)}, Entry: ServerEntry{ID: "b"}}
+	installed := CatalogHit{Popularity: &Popularity{Installs: intPtr(999999)}, Entry: ServerEntry{ID: "a"}}
+	if !Rank(starred, installed, "") {
+		t.Error("expected stars to outrank a much larger installs count")
+	}
+	if Rank(installed, starred, "") {
+		t.Error("expected stars to outrank installs (reverse check)")
+	}
+}
+
+// TestRank_InstallsBreakStarsTie pins FR-004's secondary key: when stars tie
+// (including both nil/0), installs decides.
+func TestRank_InstallsBreakStarsTie(t *testing.T) {
+	moreInstalls := CatalogHit{Popularity: &Popularity{Stars: intPtr(5), Installs: intPtr(200)}, Entry: ServerEntry{ID: "b"}}
+	fewerInstalls := CatalogHit{Popularity: &Popularity{Stars: intPtr(5), Installs: intPtr(10)}, Entry: ServerEntry{ID: "a"}}
+	if !Rank(moreInstalls, fewerInstalls, "") {
+		t.Error("expected higher installs to break an equal-stars tie")
+	}
+
+	// Both nil Popularity.Stars (0) but different installs: still ties on
+	// stars(0) then breaks on installs.
+	onlyInstalls := CatalogHit{Popularity: &Popularity{Installs: intPtr(50)}, Entry: ServerEntry{ID: "d"}}
+	noSignal := CatalogHit{Entry: ServerEntry{ID: "c"}}
+	if !Rank(onlyInstalls, noSignal, "") {
+		t.Error("expected a hit with installs>0 to outrank one with no signal at all")
+	}
+}
+
+// TestRank_StarsAndInstallsNeverSummed pins FR-004's "never converted into
+// one another": a hit with fewer stars AND fewer installs than another must
+// never win by having their sum happen to exceed it — i.e. this is a
+// lexicographic tuple compare, not a score.
+func TestRank_StarsAndInstallsNeverSummed(t *testing.T) {
+	a := CatalogHit{Popularity: &Popularity{Stars: intPtr(3), Installs: intPtr(1000000)}, Entry: ServerEntry{ID: "b"}}
+	b := CatalogHit{Popularity: &Popularity{Stars: intPtr(4), Installs: intPtr(1)}, Entry: ServerEntry{ID: "a"}}
+	// b has more stars (4 > 3) despite far fewer installs — b must win.
+	if !Rank(b, a, "") {
+		t.Error("expected the higher-stars hit to win regardless of the other's much larger installs")
+	}
+}
+
 func intPop(stars int) *Popularity {
 	return &Popularity{Stars: &stars}
 }
+
+func intPtr(n int) *int { return &n }
diff --git a/internal/registries/search.go b/internal/registries/search.go
index 189e5f964..7206f539b 100644
--- a/internal/registries/search.go
+++ b/internal/registries/search.go
@@ -406,6 +406,16 @@ func parseDocker(rawData interface{}) []ServerEntry {
 				server.UpdatedAt = lastUpdated
 			}
 
+			// Spec 110 FR-001: pull_count -> Installs (comes free with the
+			// listing this parser already fetches). Docker's own star_count
+			// is deliberately NEVER mapped to Stars — it lives on a wildly
+			// different scale from GitHub stars (single digits vs tens of
+			// thousands) and mixing them would be meaningless.
+			if pullCount, ok := itemMap["pull_count"].(float64); ok && pullCount >= 0 {
+				installs := int(pullCount)
+				server.Popularity = &Popularity{Installs: &installs}
+			}
+
 			servers = append(servers, server)
 		}
 	}
diff --git a/internal/registries/testhooks.go b/internal/registries/testhooks.go
index d8a6139c5..cc6f35916 100644
--- a/internal/registries/testhooks.go
+++ b/internal/registries/testhooks.go
@@ -32,3 +32,27 @@ func AllowPrivateRegistryFetchForTest() (restore func()) {
 		registryAllowPrivateFetch.Store(prev)
 	}
 }
+
+// SetPopularityProviderForTest installs p as the process-wide popularity
+// provider (Spec 110 FR-010) and returns a restore func reinstalling
+// whatever was previously installed (typically nil).
+func SetPopularityProviderForTest(p PopularityProvider) (restore func()) {
+	prev := getPopularityProvider()
+	SetPopularityProvider(p)
+	return func() { SetPopularityProvider(prev) }
+}
+
+// SetGitHubAPIBaseForTest overrides the GitHub API base URL new
+// githubStarsProvider instances read at construction (default
+// githubAPIBaseURLDefault), so a test can point NewGitHubStarsProvider at an
+// httptest.Server. Combine with AllowPrivateRegistryFetchForTest, since the
+// SSRF guard otherwise blocks a loopback target. Returns a restore func.
+func SetGitHubAPIBaseForTest(base string) (restore func()) {
+	prev := currentGitHubAPIBase()
+	b := base
+	githubAPIBaseOverride.Store(&b)
+	return func() {
+		p := prev
+		githubAPIBaseOverride.Store(&p)
+	}
+}
diff --git a/internal/registries/types.go b/internal/registries/types.go
index 25ac92208..99d3edc94 100644
--- a/internal/registries/types.go
+++ b/internal/registries/types.go
@@ -46,6 +46,14 @@ type ServerEntry struct {
 	// ${VAR} / $VAR placeholders (see DetectRequiredInputs). Empty for most
 	// servers in this spec — no rich per-registry schema yet (decision O1).
 	RequiredInputs []RequiredInput `json:"required_inputs,omitempty"`
+
+	// Popularity carries a source-NATIVE popularity signal discovered while
+	// parsing this entry (Spec 110 FR-001) — currently only parseDocker's
+	// pull_count → Installs. Deliberately `json:"-"`: it must never appear in
+	// ServerEntry's own JSON (GET /registries/{id}/servers, search_servers),
+	// which stays unchanged. BuildCatalogHit copies it into CatalogHit and
+	// layers in GitHub stars from the popularity provider's cache.
+	Popularity *Popularity `json:"-"`
 }
 
 // RequiredInput declares a single env var / key a server needs before it will

From 37fbed97848e4143bc4f1eda21479ba60dc213a5 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 06:09:03 +0300
Subject: [PATCH 25/27] feat(catalog): wire popularity provider into runtime,
 CLI, and E2E (T014-T019)

Wires the Spec 110 popularity signal into production paths:
- internal/runtime installs a bbolt-backed githubStarsProvider at startup
  and closes it on shutdown.
- cmd/mcpproxy installs a memory-only provider for the CLI's in-process
  'catalog search' fallback and 'catalog show'.
- scripts/test-api-e2e.sh exports MCPPROXY_CATALOG_POPULARITY=false so
  E2E never depends on api.github.com (SC-005).
- docs/registries.md documents the two popularity sources, the
  MCPPROXY_GITHUB_TOKEN budget bump, and the kill switch.
- T014: updates a Spec 109 catalog test that asserted the old
  Popular-equals-ranked-pool behavior to the new SC-002 empty-Popular
  semantics now that Popular only ever shows a real signal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ROADMAP.md                               |  2 +-
 cmd/mcpproxy/catalog_cmd.go              | 20 ++++++++
 docs/registries.md                       | 34 +++++++++++++
 internal/httpapi/catalog_test.go         | 10 +++-
 internal/registries/popularity_github.go |  7 ++-
 internal/runtime/runtime.go              | 64 +++++++++++++++++-------
 scripts/test-api-e2e.sh                  |  6 +++
 specs/110-catalog-popularity/tasks.md    | 38 +++++++-------
 8 files changed, 140 insertions(+), 41 deletions(-)

diff --git a/ROADMAP.md b/ROADMAP.md
index adfc9614d..20d5c0a68 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1035,4 +1035,4 @@ Legend: `shipped` ≥95% checked · `in-flight` 1–94% · `drafted` 0% · `—`
 | [105-agent-scope-hardening](./specs/105-agent-scope-hardening/) | `in-flight` | 94/113 (83%) |
 | [106-security-residual-fixes](./specs/106-security-residual-fixes/) | `shipped` | 18/19 (95%) |
 | [107-server-edition-sso-hardening](./specs/107-server-edition-sso-hardening/) | `shipped` | 126/126 (100%) |
-| [110-catalog-popularity](./specs/110-catalog-popularity/) | `drafted` | 0/23 (0%) |
+| [110-catalog-popularity](./specs/110-catalog-popularity/) | `in-flight` | 19/23 (83%) |
diff --git a/cmd/mcpproxy/catalog_cmd.go b/cmd/mcpproxy/catalog_cmd.go
index 4f0d30721..4d84d11db 100644
--- a/cmd/mcpproxy/catalog_cmd.go
+++ b/cmd/mcpproxy/catalog_cmd.go
@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"strings"
+	"sync"
 
 	"github.com/spf13/cobra"
 
@@ -14,6 +15,23 @@ import (
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/registries"
 )
 
+// installMemoryPopularityProviderOnce guards installMemoryPopularityProvider
+// so a CLI process that ends up calling it more than once (e.g. 'catalog
+// show' after an in-process 'catalog search' fallback) installs a single
+// provider rather than leaking one per call.
+var installMemoryPopularityProviderOnce sync.Once
+
+// installMemoryPopularityProvider installs a memory-only (no bbolt store)
+// popularity provider for the CLI's in-process paths (Spec 110 FR-010): the
+// in-process 'catalog search' fallback (no daemon running) and 'catalog
+// show'. The core daemon (internal/runtime) installs its own bbolt-backed
+// provider instead — this one is never wired there.
+func installMemoryPopularityProvider() {
+	installMemoryPopularityProviderOnce.Do(func() {
+		registries.SetPopularityProvider(registries.NewGitHubStarsProvider(registries.PopularityOptions{}))
+	})
+}
+
 // printCatalogDeprecationNotice prints the FR-066 deprecation note to
 // stderr: 'registry search'/'registry add' remain as aliases (scripts must
 // not break), but point at their 'catalog' equivalent.
@@ -124,6 +142,7 @@ func newCatalogShowCmd() *cobra.Command {
 			ctx, cancel := registryContext()
 			defer cancel()
 			registries.SetRegistriesFromConfig(cfg)
+			installMemoryPopularityProvider()
 			reg := registries.FindRegistry(source)
 			if reg == nil {
 				return outputError(clioutput.NewStructuredError(clioutput.ErrCodeServerNotFound, fmt.Sprintf("catalog source %q not found", source)).
@@ -237,6 +256,7 @@ func catalogSearch(ctx context.Context, cfg *config.Config, q, source, tag strin
 	// returns — which is also what makes it independently testable against a
 	// fixture list (registries.SetRegistriesForTest).
 	registries.SetRegistriesFromConfig(cfg)
+	installMemoryPopularityProvider()
 	return catalogSearchInProcess(ctx, cfg, q, source, tag, limit)
 }
 
diff --git a/docs/registries.md b/docs/registries.md
index 3a15f1e46..7586dd5ba 100644
--- a/docs/registries.md
+++ b/docs/registries.md
@@ -219,6 +219,40 @@ Because every add surface (MCP, REST, CLI) funnels through the same keystone, a
 packages-only server is added as stdio and a remotes-only server as http
 identically across all surfaces.
 
+## Catalog popularity signal
+
+The catalog's `Popular` landing section (and the popularity tiebreak in
+search ranking) is backed by two real, source-native signals — no synthetic
+scoring:
+
+- **GitHub stars** for any hit whose `source_code_url` resolves to a
+  `github.com/<owner>/<repo>` URL (the official registry and reference
+  sources both carry one for almost every entry). Fetched from
+  `GET https://api.github.com/repos/{owner}/{repo}`, cached (with ETag
+  revalidation) for 24h, capped at 4 concurrent requests and a rolling
+  budget of 50 requests/hour without a token or 4,000/hour with one.
+- **Docker Hub pull counts** (`pull_count` from the `docker-mcp-catalog`
+  registry's listing) map to `Installs`. Docker's own `star_count` is never
+  used — it lives on a different scale from GitHub stars (single digits vs.
+  tens of thousands) and the two are never summed or converted into one
+  another.
+
+Popularity fetching never blocks a search beyond a short bounded wait
+(800ms by default): a cold miss is queued for a background fetch and simply
+shows no stars on the current page, arriving on the next one. GitHub is
+never listed in a search's `unavailable[]` — it is not a catalog source.
+
+**`MCPPROXY_GITHUB_TOKEN`** (not the generic `GITHUB_TOKEN`, which is
+deliberately never read) raises the GitHub rate-limit budget from 50 to
+4,000 requests/hour. Set it if your catalog has many distinct repositories
+and stars are taking a while to fill in.
+
+**`MCPPROXY_CATALOG_POPULARITY=false`** (or `0`/`off`) disables all outbound
+GitHub requests — useful for air-gapped or offline setups. Docker's
+source-native install counts are unaffected either way, since they come from
+the registry listing the Docker source already fetches, not from a separate
+popularity call.
+
 ## Adding a discovered server
 
 See [registry-add.md](features/registry-add.md). New servers are quarantined by
diff --git a/internal/httpapi/catalog_test.go b/internal/httpapi/catalog_test.go
index 0df15e2cb..8b8a52b83 100644
--- a/internal/httpapi/catalog_test.go
+++ b/internal/httpapi/catalog_test.go
@@ -201,6 +201,14 @@ func TestCatalogSearch_AddedScopedForNonAdminUserContext(t *testing.T) {
 // TestCatalogSearch_EmptyQueryReturnsEmptyResults pins contracts/rest-api.md#catalog:
 // "Empty q → results: [], sections: {...}". Before this fix, Results was set
 // unconditionally to the ranked hit list even when Sections was populated.
+//
+// Spec 110 (T014): sections.popular is asserted EMPTY here, not populated —
+// this fixture carries no popularity signal at all (no source_code_url, no
+// Docker pull_count), and Popular now only ever shows hits with a known
+// signal (FR-005/SC-002). Before Spec 110, Popular was just the ranked pool
+// re-sorted by a popularity score that was always 0 for everyone, so it
+// looked "populated" while actually carrying no real signal — the exact bug
+// this spec fixes.
 func TestCatalogSearch_EmptyQueryReturnsEmptyResults(t *testing.T) {
 	withCatalogFixtureRegistry(t)
 	ctrl := &scopeController{cfg: scopeFixtureConfig(false), servers: catalogFixtureServers(), withManagement: true}
@@ -218,7 +226,7 @@ func TestCatalogSearch_EmptyQueryReturnsEmptyResults(t *testing.T) {
 	require.True(t, ok, "expected sections to be populated for an empty q")
 	popular, ok := sections["popular"].([]interface{})
 	require.True(t, ok)
-	assert.NotEmpty(t, popular, "expected the fixture's entries in sections.popular")
+	assert.Empty(t, popular, "Spec 110 FR-005/SC-002: no popularity signal in this fixture -> sections.popular must be empty")
 }
 
 // TestCatalogSearch_SourceFilterAppliesBeforeTruncation is the regression for
diff --git a/internal/registries/popularity_github.go b/internal/registries/popularity_github.go
index 9508f5cfe..4df776a57 100644
--- a/internal/registries/popularity_github.go
+++ b/internal/registries/popularity_github.go
@@ -225,12 +225,15 @@ func NewGitHubStarsProvider(opts PopularityOptions) *githubStarsProvider {
 	return p
 }
 
-// Close stops all background fetch workers. Safe to call multiple times.
-func (p *githubStarsProvider) Close() {
+// Close stops all background fetch workers and returns immediately if
+// already closed. It satisfies io.Closer so callers (internal/runtime) can
+// hold the provider as an io.Closer without naming this unexported type.
+func (p *githubStarsProvider) Close() error {
 	p.closeOnce.Do(func() {
 		p.cancel()
 		p.wg.Wait()
 	})
+	return nil
 }
 
 func (p *githubStarsProvider) startWorkers() {
diff --git a/internal/runtime/runtime.go b/internal/runtime/runtime.go
index 1b069f6d2..2316775df 100644
--- a/internal/runtime/runtime.go
+++ b/internal/runtime/runtime.go
@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"math"
 	"net"
 	"os"
@@ -139,6 +140,13 @@ type Runtime struct {
 	indexManager    *index.Manager
 	upstreamManager *upstream.Manager
 	cacheManager    *cache.Manager
+	// popularityProvider is the Spec 110 catalog popularity signal's
+	// bbolt-backed GitHub-stars provider, installed process-wide via
+	// registries.SetPopularityProvider unconditionally at startup — the
+	// FR-011 kill switch is read INSIDE the provider constructor, so this is
+	// never nil, it just starts no workers when disabled. io.Closer so this
+	// file never needs to name the unexported provider type.
+	popularityProvider io.Closer
 	// promptsRefresh debounces upstream prompts/list_changed notifications into a
 	// single RefreshPrompts fan-out (F13). Nil until lifecycle registration.
 	promptsRefresh *promptsRefreshDebouncer
@@ -294,6 +302,19 @@ func New(cfg *config.Config, cfgPath string, logger *zap.Logger) (*Runtime, erro
 		return nil, fmt.Errorf("failed to initialize cache manager: %w", err)
 	}
 
+	// Spec 110 (catalog popularity signal): a bbolt-backed GitHub-stars
+	// provider, installed process-wide so BuildCatalogHit/SearchAll (catalog
+	// search, CLI, MCP search_servers with registry omitted) can show real
+	// popularity. FR-011's kill switch (MCPPROXY_CATALOG_POPULARITY=false) is
+	// read inside the constructor, so this is unconditional — a disabled
+	// provider still answers Lookup from whatever is already cached, it just
+	// starts no fetch workers.
+	popularityProvider := registries.NewGitHubStarsProvider(registries.PopularityOptions{
+		DB:     storageManager.GetDB(),
+		Logger: logger,
+	})
+	registries.SetPopularityProvider(popularityProvider)
+
 	truncator := truncate.NewTruncator(cfg.ToolResponseLimit)
 
 	// Initialize tokenizer (defaults to enabled with cl100k_base)
@@ -391,24 +412,25 @@ func New(cfg *config.Config, cfgPath string, logger *zap.Logger) (*Runtime, erro
 	rt := &Runtime{
 		cfg: cfg,
 		// Boot: memory and disk agree by definition.
-		desiredCfg:       cfg,
-		cfgPath:          cfgPath,
-		logger:           logger,
-		configSvc:        configSvc,
-		storageManager:   storageManager,
-		indexManager:     indexManager,
-		upstreamManager:  upstreamManager,
-		cacheManager:     cacheManager,
-		sigCache:         toolsig.NewCache(),
-		secretResolver:   secretResolver,
-		tokenizer:        tokenizer,
-		refreshManager:   refreshManager,
-		activityService:  activityService,
-		supervisor:       supervisorInstance,
-		prechurnStore:    prechurnStore,
-		previousShutdown: previousShutdown,
-		appCtx:           appCtx,
-		appCancel:        appCancel,
+		desiredCfg:         cfg,
+		cfgPath:            cfgPath,
+		logger:             logger,
+		configSvc:          configSvc,
+		storageManager:     storageManager,
+		indexManager:       indexManager,
+		upstreamManager:    upstreamManager,
+		cacheManager:       cacheManager,
+		popularityProvider: popularityProvider,
+		sigCache:           toolsig.NewCache(),
+		secretResolver:     secretResolver,
+		tokenizer:          tokenizer,
+		refreshManager:     refreshManager,
+		activityService:    activityService,
+		supervisor:         supervisorInstance,
+		prechurnStore:      prechurnStore,
+		previousShutdown:   previousShutdown,
+		appCtx:             appCtx,
+		appCancel:          appCancel,
 		status: Status{
 			Phase:       PhaseInitializing,
 			Message:     "Runtime is initializing...",
@@ -869,6 +891,12 @@ func (r *Runtime) Close() error {
 		r.cacheManager.Close()
 	}
 
+	// Spec 110: stop the popularity provider's background fetch workers.
+	// Safe even if it was never installed (nil) or already closed.
+	if r.popularityProvider != nil {
+		_ = r.popularityProvider.Close()
+	}
+
 	// Spec 080 (FR-010, review round 4): the ActivityService owns BBolt
 	// writers — activity records, retention pruning, usage-snapshot flushes,
 	// async sensitive-data detection. The appCancel at the top of Close
diff --git a/scripts/test-api-e2e.sh b/scripts/test-api-e2e.sh
index 1cba91d66..4e273573a 100755
--- a/scripts/test-api-e2e.sh
+++ b/scripts/test-api-e2e.sh
@@ -717,6 +717,12 @@ if [ "$LISTEN_PORT" != "8081" ]; then
     echo "Updated listen port to :${LISTEN_PORT}"
 fi
 
+# Spec 110 (catalog popularity signal, FR-011 kill switch): E2E must not
+# depend on api.github.com (SC-005) — no outbound GitHub fetch, no rate-limit
+# flakiness, no network dependency for a suite that otherwise runs fully
+# offline against the local server under test.
+export MCPPROXY_CATALOG_POPULARITY=false
+
 # Start server in background
 $MCPPROXY_BINARY serve --config="$CONFIG_FILE" --log-level=info > "/tmp/mcpproxy_e2e.log" 2>&1 &
 MCPPROXY_PID=$!
diff --git a/specs/110-catalog-popularity/tasks.md b/specs/110-catalog-popularity/tasks.md
index 0b313e6ec..6fa80cc78 100644
--- a/specs/110-catalog-popularity/tasks.md
+++ b/specs/110-catalog-popularity/tasks.md
@@ -4,34 +4,34 @@
 
 ## Phase 1 — Pure pieces (PR A)
 
-- [ ] T001 [P] [US1] `GitHubRepoKey` + table test covering every edge-case form in the spec (`internal/registries/popularity_key.go`, `popularity_key_test.go`) — FR-003
-- [ ] T002 [P] [US1] `parseDocker` maps `pull_count` → `ServerEntry.Popularity.Installs`, ignores `star_count`, and ignores negative or non-numeric values. Add `ServerEntry.Popularity json:"-"` plus a test that `ServerEntry` JSON is unchanged (`search.go`, `types.go`, `search_test.go`) — FR-001
-- [ ] T003 [US2] Replace `popularityScore` sum with `comparePopularity` using (stars, installs). Add rank tests: stars beat installs, installs break ties between equal stars, existing tests stay green (`catalog.go`, `rank_test.go`) — FR-004
+- [x] T001 [P] [US1] `GitHubRepoKey` + table test covering every edge-case form in the spec (`internal/registries/popularity_key.go`, `popularity_key_test.go`) — FR-003
+- [x] T002 [P] [US1] `parseDocker` maps `pull_count` → `ServerEntry.Popularity.Installs`, ignores `star_count`, and ignores negative or non-numeric values. Add `ServerEntry.Popularity json:"-"` plus a test that `ServerEntry` JSON is unchanged (`search.go`, `types.go`, `search_test.go`) — FR-001
+- [x] T003 [US2] Replace `popularityScore` sum with `comparePopularity` using (stars, installs). Add rank tests: stars beat installs, installs break ties between equal stars, existing tests stay green (`catalog.go`, `rank_test.go`) — FR-004
 
 ## Phase 2 — Provider (PR A)
 
-- [ ] T004 [US3] `PopularityProvider` interface, `SetPopularityProvider`, `SetPopularityProviderForTest`, `SetGitHubAPIBaseForTest` (`popularity.go`, `testhooks.go`) — FR-010
-- [ ] T005 [US3] `githubStarsProvider` fetch against an httptest stub. Cover: 200 (stars + ETag stored), 304 (refresh `FetchedAt`, keep stars), 404 (negative), 500 (1h error TTL), exact request headers, bearer only when `MCPPROXY_GITHUB_TOKEN` is set, body cap, and a 301 redirect on the same host (`popularity_github.go`, `popularity_github_test.go`) — FR-006, FR-011
-- [ ] T006 [US3] TTL, serve-stale and requeue via an injected clock. Cover dedup of queued/in-flight keys, queue overflow drop, concurrency ≤4 (stub counts peak concurrency), rolling budget of 50/h, breaker on `Remaining ≤ 5`, and 403/429 with `Retry-After` (SC-004) — FR-008, FR-009
-- [ ] T007 [US3] bbolt store: round-trip, lazy load, cap eviction, and surviving a provider restart (a temp DB) (`popularity_store.go`, `popularity_store_test.go`) — FR-008
-- [ ] T008 [US3] `Resolve` wait bounds: returns by `wait` and by `ctx` cancel, fetches continue afterwards, and `wait=0` never blocks (SC-003) — FR-007
-- [ ] T009 [US3] Kill switch: with `MCPPROXY_CATALOG_POPULARITY=false` no request ever reaches the stub — FR-011
+- [x] T004 [US3] `PopularityProvider` interface, `SetPopularityProvider`, `SetPopularityProviderForTest`, `SetGitHubAPIBaseForTest` (`popularity.go`, `testhooks.go`) — FR-010
+- [x] T005 [US3] `githubStarsProvider` fetch against an httptest stub. Cover: 200 (stars + ETag stored), 304 (refresh `FetchedAt`, keep stars), 404 (negative), 500 (1h error TTL), exact request headers, bearer only when `MCPPROXY_GITHUB_TOKEN` is set, body cap, and a 301 redirect on the same host (`popularity_github.go`, `popularity_github_test.go`) — FR-006, FR-011
+- [x] T006 [US3] TTL, serve-stale and requeue via an injected clock. Cover dedup of queued/in-flight keys, queue overflow drop, concurrency ≤4 (stub counts peak concurrency), rolling budget of 50/h, breaker on `Remaining ≤ 5`, and 403/429 with `Retry-After` (SC-004) — FR-008, FR-009
+- [x] T007 [US3] bbolt store: round-trip, lazy load, cap eviction, and surviving a provider restart (a temp DB) (`popularity_store.go`, `popularity_store_test.go`) — FR-008
+- [x] T008 [US3] `Resolve` wait bounds: returns by `wait` and by `ctx` cancel, fetches continue afterwards, and `wait=0` never blocks (SC-003) — FR-007
+- [x] T009 [US3] Kill switch: with `MCPPROXY_CATALOG_POPULARITY=false` no request ever reaches the stub — FR-011
 
 ## Phase 3 — Catalog integration (PR A)
 
-- [ ] T010 [US1] `BuildCatalogHit` copies `entry.Popularity` and adds cache-only stars (`catalog.go`, `catalog_popularity_test.go`) — FR-002
-- [ ] T011 [US1] `SearchAll`: add `SearchOptions.PopularityWait` (default 800 ms), Resolve after the fan-out, re-apply and re-rank, and build sections from the pool before truncation — FR-005, FR-007
-- [ ] T012 [US1] `buildSections`: Official in source order, Popular signal-only, one per repo, capped at 12. **SC-001 and SC-002 tests** (fixture registries through `SetRegistriesForTest` + the stub provider)
-- [ ] T013 [US3] SearchAll with a GitHub stub that sleeps 5 s: returns within the wait, the second call has the stars, and `unavailable[]` is untouched (SC-003)
-- [ ] T014 Update any 109 test that asserted Official in popularity/rank order so it asserts source order instead (`internal/registries/*_test.go`, `internal/httpapi/catalog*_test.go`, `cmd/mcpproxy/catalog_cmd*_test.go`)
+- [x] T010 [US1] `BuildCatalogHit` copies `entry.Popularity` and adds cache-only stars (`catalog.go`, `catalog_popularity_test.go`) — FR-002
+- [x] T011 [US1] `SearchAll`: add `SearchOptions.PopularityWait` (default 800 ms), Resolve after the fan-out, re-apply and re-rank, and build sections from the pool before truncation — FR-005, FR-007
+- [x] T012 [US1] `buildSections`: Official in source order, Popular signal-only, one per repo, capped at 12. **SC-001 and SC-002 tests** (fixture registries through `SetRegistriesForTest` + the stub provider)
+- [x] T013 [US3] SearchAll with a GitHub stub that sleeps 5 s: returns within the wait, the second call has the stars, and `unavailable[]` is untouched (SC-003)
+- [x] T014 Update any 109 test that asserted Official in popularity/rank order so it asserts source order instead (`internal/registries/*_test.go`, `internal/httpapi/catalog*_test.go`, `cmd/mcpproxy/catalog_cmd*_test.go`)
 
 ## Phase 4 — Wiring (PR A)
 
-- [ ] T015 Runtime installs the bbolt-backed provider and closes it on shutdown (`internal/runtime/runtime.go`)
-- [ ] T016 CLI in-process fallback and `catalog show` install the memory provider (`cmd/mcpproxy/catalog_cmd.go`)
-- [ ] T017 `scripts/test-api-e2e.sh` exports `MCPPROXY_CATALOG_POPULARITY=false`
-- [ ] T018 Docs: `docs/features/` catalog page — popularity sources, `MCPPROXY_GITHUB_TOKEN`, kill switch
-- [ ] T019 Verify: both golangci-lint runs (bare + `--build-tags server`), `go test -race ./internal/registries/... ./internal/httpapi/... ./cmd/mcpproxy/...`, and `./scripts/test-api-e2e.sh`
+- [x] T015 Runtime installs the bbolt-backed provider and closes it on shutdown (`internal/runtime/runtime.go`)
+- [x] T016 CLI in-process fallback and `catalog show` install the memory provider (`cmd/mcpproxy/catalog_cmd.go`)
+- [x] T017 `scripts/test-api-e2e.sh` exports `MCPPROXY_CATALOG_POPULARITY=false`
+- [x] T018 Docs: `docs/features/` catalog page — popularity sources, `MCPPROXY_GITHUB_TOKEN`, kill switch
+- [x] T019 Verify: both golangci-lint runs (bare + `--build-tags server`), `go test -race ./internal/registries/... ./internal/httpapi/... ./cmd/mcpproxy/...`, and `./scripts/test-api-e2e.sh`
 
 ## Phase 5 — Display (PR B, stacked)
 

From 24431cd98b1a789528f7c5b526c6ba61e44f06d0 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 06:13:05 +0300
Subject: [PATCH 26/27] fix(catalog): enforce popularity cache cap across
 restarts

Load the catalog_popularity bucket eagerly at provider construction and
trim it to the FR-008 cap. With lazy loading the in-memory key count
restarted at zero after each restart, so the bbolt bucket could grow
past the cap without bound.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 internal/registries/popularity_github.go     |  8 ++++
 internal/registries/popularity_store.go      | 24 ++++++++++
 internal/registries/popularity_store_test.go | 46 ++++++++++++++++++++
 specs/110-catalog-popularity/plan.md         |  2 +-
 specs/110-catalog-popularity/spec.md         |  2 +-
 5 files changed, 80 insertions(+), 2 deletions(-)

diff --git a/internal/registries/popularity_github.go b/internal/registries/popularity_github.go
index 4df776a57..99aa24ef2 100644
--- a/internal/registries/popularity_github.go
+++ b/internal/registries/popularity_github.go
@@ -219,6 +219,14 @@ func NewGitHubStarsProvider(opts PopularityOptions) *githubStarsProvider {
 		baseCtx:  baseCtx,
 		cancel:   cancel,
 	}
+	if store != nil {
+		p.entries = store.all()
+		p.mu.Lock()
+		for len(p.entries) > githubMaxCacheKeys {
+			p.evictIfNeededLocked()
+		}
+		p.mu.Unlock()
+	}
 	if !p.disabled {
 		p.startWorkers()
 	}
diff --git a/internal/registries/popularity_store.go b/internal/registries/popularity_store.go
index 7c55fd3d9..12e4efe52 100644
--- a/internal/registries/popularity_store.go
+++ b/internal/registries/popularity_store.go
@@ -35,6 +35,30 @@ func newPopularityStore(db *bbolt.DB) (*popularityStore, error) {
 	return &popularityStore{db: db}, nil
 }
 
+// all returns every decodable persisted entry. The provider loads the whole
+// bucket once at construction so the FR-008 key cap applies to what is on
+// disk, not just to what a lazy lookup happened to pull into memory — with
+// lazy loading, a restart reset the in-memory count to zero and the bucket
+// could grow past the cap forever.
+func (s *popularityStore) all() map[string]*starsEntry {
+	out := make(map[string]*starsEntry)
+	_ = s.db.View(func(tx *bbolt.Tx) error {
+		b := tx.Bucket([]byte(popularityBucketName))
+		if b == nil {
+			return nil
+		}
+		return b.ForEach(func(k, v []byte) error {
+			var entry starsEntry
+			if err := json.Unmarshal(v, &entry); err != nil {
+				return nil //nolint:nilerr // a corrupt record is skipped, never fatal
+			}
+			out[string(k)] = &entry
+			return nil
+		})
+	})
+	return out
+}
+
 // get returns the persisted entry for key, or ok=false if there is none (or
 // it fails to decode — treated the same as absent rather than as an error,
 // since a corrupt single record must never break the whole cache).
diff --git a/internal/registries/popularity_store_test.go b/internal/registries/popularity_store_test.go
index b83365c2a..ca93fb462 100644
--- a/internal/registries/popularity_store_test.go
+++ b/internal/registries/popularity_store_test.go
@@ -1,6 +1,7 @@
 package registries
 
 import (
+	"encoding/json"
 	"path/filepath"
 	"testing"
 	"time"
@@ -125,3 +126,48 @@ func TestGitHubStarsProvider_CapEviction(t *testing.T) {
 func keyForIndex(i int) string {
 	return "owner/repo-" + string(rune('a'+(i%26))) + string(rune('a'+((i/26)%26))) + string(rune('a'+((i/676)%26)))
 }
+
+// TestGitHubStarsProvider_CapHoldsAcrossRestart pins that the FR-008 key cap
+// bounds the bbolt bucket, not just the in-memory map: a bucket already over
+// the cap (written by an earlier process) is trimmed to the cap, oldest
+// FetchedAt first, when the next provider opens it. With lazy loading the
+// in-memory count restarted at zero and the bucket grew without bound.
+func TestGitHubStarsProvider_CapHoldsAcrossRestart(t *testing.T) {
+	db := openTempPopularityDB(t)
+	if _, err := newPopularityStore(db); err != nil {
+		t.Fatalf("newPopularityStore: %v", err)
+	}
+	const over = 3
+	base := time.Now().Add(-time.Hour)
+	if err := db.Update(func(tx *bbolt.Tx) error {
+		b := tx.Bucket([]byte(popularityBucketName))
+		for i := 0; i < githubMaxCacheKeys+over; i++ {
+			v, err := json.Marshal(&starsEntry{Stars: 1, Status: 200, FetchedAt: base.Add(time.Duration(i) * time.Second)})
+			if err != nil {
+				return err
+			}
+			if err := b.Put([]byte(keyForIndex(i)), v); err != nil {
+				return err
+			}
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	t.Setenv("MCPPROXY_CATALOG_POPULARITY", "false")
+	provider := NewGitHubStarsProvider(PopularityOptions{DB: db})
+	defer provider.Close()
+
+	if got := len(provider.store.all()); got != githubMaxCacheKeys {
+		t.Fatalf("bucket holds %d keys after reopen, want the cap %d", got, githubMaxCacheKeys)
+	}
+	for i := 0; i < over; i++ {
+		if _, state := provider.Lookup(keyForIndex(i)); state != LookupAbsent {
+			t.Errorf("oldest key %d should have been evicted, got state %d", i, state)
+		}
+	}
+	if _, state := provider.Lookup(keyForIndex(githubMaxCacheKeys + over - 1)); state != LookupFresh {
+		t.Errorf("newest key should survive, got state %d", state)
+	}
+}
diff --git a/specs/110-catalog-popularity/plan.md b/specs/110-catalog-popularity/plan.md
index aaed2cacd..62b982392 100644
--- a/specs/110-catalog-popularity/plan.md
+++ b/specs/110-catalog-popularity/plan.md
@@ -61,7 +61,7 @@ type starsEntry struct {
 }
 ```
 
-bbolt bucket `catalog_popularity`: key = `o/r` (lower-case), value = JSON `starsEntry`. Entries are loaded into memory lazily on the first `Lookup` miss. Writes go through synchronously after each fetch (they are rare, ≤50/h). A new key over the cap evicts the oldest `FetchedAt`.
+bbolt bucket `catalog_popularity`: key = `o/r` (lower-case), value = JSON `starsEntry`. The whole bucket is loaded into memory when the provider is constructed, trimmed to the cap if needed, so the cap bounds the disk, not only the memory. Lazy loading was dropped in review: after a restart the in-memory count started at zero and the bucket grew without limit. Writes go through synchronously after each fetch (they are rare, ≤50/h). A new key over the cap evicts the oldest `FetchedAt`.
 
 ## Flow
 
diff --git a/specs/110-catalog-popularity/spec.md b/specs/110-catalog-popularity/spec.md
index 44f018648..60b120e22 100644
--- a/specs/110-catalog-popularity/spec.md
+++ b/specs/110-catalog-popularity/spec.md
@@ -73,7 +73,7 @@ The Web UI result row, the macOS catalog row and the CLI `catalog search` table
 - **FR-004 (comparison)**: `Rank` and the Popular ordering MUST compare popularity as `(stars desc, installs desc)`, with missing = 0. Stars and installs are never added together or converted into each other.
 - **FR-005 (sections)**: `buildSections` MUST take the full merged, de-duplicated, source-filtered pool **before** `limit` truncation. For an empty q, each source is fanned out with the per-source maximum (50) rather than the caller's `limit`, so the pool is as wide as each source will give. Official = official hits in merge (source-native) order, at most 12. This order MUST come from a copy of the pool taken **before** any `Rank` sort. With an empty q and all-official defaults, rank order *is* popularity order, so building Official from the ranked pool would bring back the bug this spec fixes. Popular = hits with `stars>0 ∨ installs>0`, sorted per FR-004 and then `Rank`, at most one per GitHub repo key, at most 12. This amends Spec 109 FR-060 and data-model §9. *Known limitation*: the Docker source fetches a single page of `hub.docker.com/v2/repositories/mcp/`, which is 10 images by default. Popular therefore ranks only within what each source returns, and paginating Docker is a follow-up.
 - **FR-006 (fetch)**: The GitHub fetcher MUST send `GET https://api.github.com/repos/{owner}/{repo}` through the SSRF-hardened registry client. The host is a compile-time constant, overridable only by a test hook. The request carries `Accept: application/vnd.github+json`, `X-GitHub-Api-Version: 2022-11-28`, the versioned mcpproxy User-Agent, and `If-None-Match` when an ETag is cached. The response body is capped at 1 MiB and each request has a 10 s timeout. Only `stargazers_count` and `ETag` are read. The fetcher sends its own request on `sharedRegistryClient()`, with a per-request `context.WithTimeout(10s)` because the client's own timeout is 45 s. It MUST NOT use `registryGet`: that pins to `reg.ServersURL`, forces its own headers, and retries 429/5xx three times, which would burn budget against a rate-limited API. There are no retries; the breaker (FR-009) is the only backoff.
-- **FR-007 (never block the search)**: `SearchAll` MUST resolve popularity *after* the per-source fan-out. Cached values come back immediately. Misses are queued for a background fetch, and `SearchAll` waits for them for at most `SearchOptions.PopularityWait`: default 800 ms, 0 disables the wait, and the wait never outlives `ctx`. Misses still outstanding keep being fetched after `SearchAll` returns, so the next search has them. The caller's ctx bounds **only the wait**. Workers fetch under a context owned by the provider, created at construction and cancelled by `Close()`. `Resolve` returns immediately, without waiting, when the provider is paused (breaker), its budget is used up, or none of the requested keys were admitted to the queue. It waits only on the keys it admitted. Popularity failures never add entries to `unavailable[]`.
+- **FR-007 (never block the search)**: `SearchAll` MUST resolve popularity *after* the per-source fan-out. Cached values come back immediately. Misses are queued for a background fetch, and `SearchAll` waits for them for at most `SearchOptions.PopularityWait`: 0 (unset) means the default of 800 ms, a negative value disables the wait, and the wait never outlives `ctx`. Misses still outstanding keep being fetched after `SearchAll` returns, so the next search has them. The caller's ctx bounds **only the wait**. Workers fetch under a context owned by the provider, created at construction and cancelled by `Close()`. `Resolve` returns immediately, without waiting, when the provider is paused (breaker), its budget is used up, or none of the requested keys were admitted to the queue. It waits only on the keys it admitted. Popularity failures never add entries to `unavailable[]`.
 - **FR-008 (cache)**: Each entry `{stars, etag, fetched_at, status}` MUST be kept in memory and persisted to the bbolt bucket `catalog_popularity` when a store is attached. The entry is fresh for 24 h after a 200 or 304, 24 h after a 404 or 451 (negative), and 1 h after any other error. Expired entries are still served (stale-while-revalidate) and queued for refresh. A failed refresh (a transport error or any status except 200/304/404/451) MUST keep the last-known `stars`/`etag` and only move the revalidate time forward. Stars are cleared only on a definitive 404/451. `Lookup` MUST tell apart *fresh*, *stale*, *negative* (fresh 404/451) and *absent*. `Resolve` enqueues only *stale* and *absent* keys, so a dead repo is not fetched again until its negative TTL runs out. The store is capped at 5,000 keys, evicting the oldest `fetched_at` first.
 - **FR-009 (rate limit)**: The fetcher MUST (a) run at most 4 requests at once; (b) de-duplicate in-flight and queued keys, with a queue capped at 256. A key that overflows is never recorded as queued (or is removed and its completion signal closed), so nothing waits on it and the next search can request it again; (c) spend at most 50 requests per rolling hour without a token and 4,000 with one; (d) stop all fetches until `X-RateLimit-Reset` when `X-RateLimit-Remaining` ≤ 5, or on 403/429 with `Retry-After` or `X-RateLimit-Remaining: 0` (using `Retry-After`, or 60 s when neither header is present); (e) fetch misses in the order `SearchAll` ranked them.
 - **FR-010 (wiring)**: `registries.SetPopularityProvider(p)` installs the process-wide provider, and `nil` turns lookups off. The core runtime installs a provider backed by bbolt at startup. The CLI in-process fallback (`catalogSearch` when no daemon is running, and `catalog show`) installs a memory-only one. Tests use `SetPopularityProviderForTest`, which returns a restore func.

From 9386f9cc9ed3add2b3e94511cea4787aa7980d8c Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Sat, 26 Sep 2026 06:24:31 +0300
Subject: [PATCH 27/27] fix(catalog): harden popularity fetcher per review
 round 2

- A 200 that is oversized, not JSON, or lacks stargazers_count is a failed
  fetch: keep the last-known stars/ETag instead of recording 0 for 24h.
- After Close, workers drop buffered keys and a shutdown-cancelled request
  is not persisted as a transport error.
- applyCachedStars falls back to source-native stars when a refresh during
  Resolve's wait turns a hit Negative (404/451).
- Resolve on a closed provider returns at once; Close wakes pending waiters.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 internal/registries/catalog.go                |  22 +++
 internal/registries/popularity_github.go      |  53 +++++-
 .../popularity_review_fixes_test.go           | 169 ++++++++++++++++++
 specs/110-catalog-popularity/plan.md          |   1 +
 4 files changed, 241 insertions(+), 4 deletions(-)
 create mode 100644 internal/registries/popularity_review_fixes_test.go

diff --git a/internal/registries/catalog.go b/internal/registries/catalog.go
index 3e416425f..dddd62f9a 100644
--- a/internal/registries/catalog.go
+++ b/internal/registries/catalog.go
@@ -366,6 +366,11 @@ func applyCachedStars(hit *CatalogHit) {
 	}
 	stars, state := provider.Lookup(key)
 	if state != LookupFresh && state != LookupStale {
+		// No displayable stars now. The hit may still carry stars from an
+		// earlier apply (BuildCatalogHit saw them Stale, then the refresh
+		// during Resolve's wait came back 404/451), so fall back to the
+		// source-native value instead of leaving the old count in place.
+		resetToSourceNativeStars(hit)
 		return
 	}
 	if hit.Popularity == nil {
@@ -375,6 +380,23 @@ func applyCachedStars(hit *CatalogHit) {
 	hit.Popularity.Stars = &s
 }
 
+// resetToSourceNativeStars drops provider-supplied stars from hit, keeping
+// only what the source itself reported (entry.Popularity).
+func resetToSourceNativeStars(hit *CatalogHit) {
+	if hit.Popularity == nil {
+		return
+	}
+	var native *int
+	if hit.Entry.Popularity != nil && hit.Entry.Popularity.Stars != nil {
+		v := *hit.Entry.Popularity.Stars
+		native = &v
+	}
+	hit.Popularity.Stars = native
+	if hit.Popularity.Stars == nil && hit.Popularity.Installs == nil {
+		hit.Popularity = nil
+	}
+}
+
 // derivePublisher extracts a display publisher from an official-protocol
 // reverse-DNS id such as "io.github.github/github-mcp-server" (→ "github").
 // Falls back to the registry's own name when the id carries no such
diff --git a/internal/registries/popularity_github.go b/internal/registries/popularity_github.go
index 99aa24ef2..0ad691b67 100644
--- a/internal/registries/popularity_github.go
+++ b/internal/registries/popularity_github.go
@@ -3,6 +3,8 @@ package registries
 import (
 	"context"
 	"encoding/json"
+	"errors"
+	"fmt"
 	"io"
 	"net/http"
 	"net/url"
@@ -36,6 +38,11 @@ const (
 	githubLowRemainingThreshold = 5 // FR-009(d)
 )
 
+var (
+	errGitHubBodyTooLarge = errors.New("github repo response exceeds the body cap")
+	errGitHubNoStargazers = errors.New("github repo response has no stargazers_count")
+)
+
 // githubAPIBaseOverride lets SetGitHubAPIBaseForTest point new providers at
 // an httptest.Server; production providers always read the compile-time
 // default (FR-006: "overridable only by a test hook").
@@ -160,6 +167,11 @@ type githubStarsProvider struct {
 	wg      sync.WaitGroup
 
 	closeOnce sync.Once
+	// closed is set by Close. A closed provider may still be the installed
+	// process-wide one (a search racing shutdown, or a test process that
+	// outlives a runtime), so Resolve must stop admitting keys that no
+	// worker will ever drain.
+	closed atomic.Bool
 }
 
 var _ PopularityProvider = (*githubStarsProvider)(nil)
@@ -238,8 +250,17 @@ func NewGitHubStarsProvider(opts PopularityOptions) *githubStarsProvider {
 // hold the provider as an io.Closer without naming this unexported type.
 func (p *githubStarsProvider) Close() error {
 	p.closeOnce.Do(func() {
+		p.closed.Store(true)
 		p.cancel()
 		p.wg.Wait()
+		// Wake anyone still waiting on a key the stopped workers never took.
+		p.mu.Lock()
+		pending := p.queued
+		p.queued = make(map[string]chan struct{})
+		p.mu.Unlock()
+		for _, ch := range pending {
+			close(ch)
+		}
 	})
 	return nil
 }
@@ -322,7 +343,7 @@ func (p *githubStarsProvider) classify(e *starsEntry) (int, LookupState) {
 
 // Resolve implements PopularityProvider.
 func (p *githubStarsProvider) Resolve(ctx context.Context, keys []string, wait time.Duration) {
-	if p.disabled || len(keys) == 0 {
+	if p.disabled || p.closed.Load() || len(keys) == 0 {
 		return
 	}
 
@@ -415,6 +436,13 @@ func (p *githubStarsProvider) pauseUntil(until time.Time) {
 func (p *githubStarsProvider) fetchAndStore(key string) {
 	defer p.complete(key)
 
+	// After Close, a worker can still pick a buffered key (select chooses
+	// randomly among ready cases). Drop it before it spends budget or writes
+	// a shutdown-induced "transport error" entry to the store.
+	if p.baseCtx.Err() != nil {
+		return
+	}
+
 	now := p.now()
 	if p.pausedNow(now) {
 		return // breaker engaged: retried on a later Resolve call
@@ -498,11 +526,22 @@ func (p *githubStarsProvider) doRequest(ctx context.Context, owner, repo string,
 
 	switch resp.StatusCode {
 	case http.StatusOK:
+		// A 200 that is oversized, not JSON, or lacks stargazers_count (a
+		// captive portal, a proxy error page, a truncated body) is a failed
+		// fetch, not an answer: FR-008 keeps the last-known stars and ETag.
+		if int64(len(body)) > githubMaxBodyBytes {
+			return 0, 0, "", headers, errGitHubBodyTooLarge
+		}
 		var payload struct {
-			StargazersCount int `json:"stargazers_count"`
+			StargazersCount *int `json:"stargazers_count"`
+		}
+		if err := json.Unmarshal(body, &payload); err != nil {
+			return 0, 0, "", headers, fmt.Errorf("decode github repo response: %w", err)
+		}
+		if payload.StargazersCount == nil || *payload.StargazersCount < 0 {
+			return 0, 0, "", headers, errGitHubNoStargazers
 		}
-		_ = json.Unmarshal(body, &payload)
-		return resp.StatusCode, payload.StargazersCount, resp.Header.Get("ETag"), headers, nil
+		return resp.StatusCode, *payload.StargazersCount, resp.Header.Get("ETag"), headers, nil
 	case http.StatusNotModified:
 		s := 0
 		if prev != nil {
@@ -523,6 +562,12 @@ func (p *githubStarsProvider) doRequest(ctx context.Context, owner, repo string,
 // a definitive 404/451 clears the stars) and, on an actual HTTP response
 // (fetchErr == nil), updates the breaker from its rate-limit headers.
 func (p *githubStarsProvider) applyResult(key string, prev *starsEntry, status, stars int, etag string, headers rateLimitHeaders, fetchErr error) {
+	// A request cut short by Close is not evidence about the repo; recording
+	// it would mark the key as an error (skipped for 1h) after a restart.
+	if fetchErr != nil && p.baseCtx.Err() != nil {
+		return
+	}
+
 	now := p.now()
 	entry := &starsEntry{FetchedAt: now, Status: status}
 
diff --git a/internal/registries/popularity_review_fixes_test.go b/internal/registries/popularity_review_fixes_test.go
new file mode 100644
index 000000000..1b1ec3159
--- /dev/null
+++ b/internal/registries/popularity_review_fixes_test.go
@@ -0,0 +1,169 @@
+package registries
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// A 200 that is not a GitHub repo payload (captive portal, proxy error page)
+// is a failed fetch: FR-008 keeps the last-known stars and ETag, and the
+// bogus ETag must never be sent back as If-None-Match.
+func TestGitHubStarsProvider_Malformed200KeepsLastKnownStars(t *testing.T) {
+	var reqCount int32
+	var lastIfNoneMatch atomic.Value
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		lastIfNoneMatch.Store(r.Header.Get("If-None-Match"))
+		if atomic.AddInt32(&reqCount, 1) == 1 {
+			w.Header().Set("ETag", `"good"`)
+			_, _ = w.Write([]byte(`{"stargazers_count": 500}`))
+			return
+		}
+		w.Header().Set("ETag", `"portal"`)
+		_, _ = w.Write([]byte(`<html>Sign in to the Wi-Fi</html>`))
+	}))
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+	fixedNow := time.Now()
+	p.now = func() time.Time { return fixedNow }
+
+	p.Resolve(context.Background(), []string{"o/r"}, time.Second)
+	fixedNow = fixedNow.Add(25 * time.Hour)
+	p.Resolve(context.Background(), []string{"o/r"}, time.Second)
+
+	if stars, _ := p.Lookup("o/r"); stars != 500 {
+		t.Fatalf("a non-JSON 200 cleared the stars: got %d, want the last-known 500", stars)
+	}
+	p.mu.Lock()
+	etag := p.entries["o/r"].ETag
+	p.mu.Unlock()
+	if etag != `"good"` {
+		t.Fatalf("stored ETag = %q, want the last good one", etag)
+	}
+}
+
+// A 200 without stargazers_count must not be read as "0 stars".
+func TestGitHubStarsProvider_200WithoutStargazersIsAFailedFetch(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"message":"ok"}`))
+	}))
+	defer srv.Close()
+
+	defer SetGitHubAPIBaseForTest(srv.URL)()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	defer p.Close()
+
+	p.Resolve(context.Background(), []string{"o/r"}, time.Second)
+	p.mu.Lock()
+	e := p.entries["o/r"]
+	p.mu.Unlock()
+	if e == nil || e.Status != 0 || e.ttl() != githubErrorTTL {
+		t.Fatalf("expected an error entry with the 1h error TTL, got %+v", e)
+	}
+}
+
+// After Close, a key a worker still picks off the buffer, or a request cut
+// short by the cancellation, must not spend budget or persist a
+// shutdown-induced error entry.
+func TestGitHubStarsProvider_CloseDoesNotRecordShutdownErrors(t *testing.T) {
+	db := openTempPopularityDB(t)
+	defer SetGitHubAPIBaseForTest("http://127.0.0.1:1")()
+	p := NewGitHubStarsProvider(PopularityOptions{DB: db})
+	_ = p.Close()
+
+	p.fetchAndStore("o/r")
+	p.applyResult("o/s", nil, 0, 0, "", rateLimitHeaders{}, context.Canceled)
+
+	if n := len(p.store.all()); n != 0 {
+		t.Fatalf("store has %d entries after shutdown, want 0", n)
+	}
+	if !p.budget.hasCapacity(time.Now()) || len(p.budget.hits) != 0 {
+		t.Fatalf("a post-Close key spent budget: %d hits", len(p.budget.hits))
+	}
+}
+
+// Resolve on a closed provider returns at once instead of queueing keys no
+// worker will drain and waiting out the full wait.
+func TestGitHubStarsProvider_ResolveAfterCloseReturnsImmediately(t *testing.T) {
+	defer SetGitHubAPIBaseForTest("http://127.0.0.1:1")()
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	_ = p.Close()
+
+	start := time.Now()
+	p.Resolve(context.Background(), []string{"o/r"}, 2*time.Second)
+	if d := time.Since(start); d > 500*time.Millisecond {
+		t.Fatalf("Resolve on a closed provider took %s", d)
+	}
+	p.mu.Lock()
+	n := len(p.queued)
+	p.mu.Unlock()
+	if n != 0 {
+		t.Fatalf("closed provider admitted %d keys", n)
+	}
+}
+
+// Close wakes waiters on keys the stopped workers never took.
+func TestGitHubStarsProvider_CloseWakesPendingWaiters(t *testing.T) {
+	t.Setenv("MCPPROXY_CATALOG_POPULARITY", "false") // no workers: keys stay queued
+	p := NewGitHubStarsProvider(PopularityOptions{})
+	p.disabled = false // admit keys, but nothing drains them
+	ch := p.enqueue("o/r")
+	if ch == nil {
+		t.Fatal("expected the key to be admitted")
+	}
+	_ = p.Close()
+	select {
+	case <-ch:
+	case <-time.After(time.Second):
+		t.Fatal("waiter on a never-fetched key was not woken by Close")
+	}
+}
+
+type stateStubProvider struct {
+	stars int
+	state LookupState
+}
+
+func (s *stateStubProvider) Lookup(string) (int, LookupState)                 { return s.stars, s.state }
+func (s *stateStubProvider) Resolve(context.Context, []string, time.Duration) {}
+
+// A repo confirmed gone during Resolve's wait must lose the stars an earlier
+// (Stale) apply put on the hit, keeping only source-native popularity.
+func TestApplyCachedStars_NegativeClearsEarlierStars(t *testing.T) {
+	stub := &stateStubProvider{stars: 900, state: LookupStale}
+	defer SetPopularityProviderForTest(stub)()
+
+	installs := 42
+	withInstalls := CatalogHit{Entry: ServerEntry{
+		SourceCodeURL: "https://github.com/o/r",
+		Popularity:    &Popularity{Installs: &installs},
+	}}
+	bare := CatalogHit{Entry: ServerEntry{SourceCodeURL: "https://github.com/o/r"}}
+	for _, h := range []*CatalogHit{&withInstalls, &bare} {
+		if h.Entry.Popularity != nil {
+			p := *h.Entry.Popularity
+			h.Popularity = &p
+		}
+		applyCachedStars(h)
+		if h.Popularity == nil || h.Popularity.Stars == nil || *h.Popularity.Stars != 900 {
+			t.Fatalf("setup: expected stale stars applied, got %+v", h.Popularity)
+		}
+	}
+
+	stub.state, stub.stars = LookupNegative, 0
+	applyCachedStars(&withInstalls)
+	applyCachedStars(&bare)
+
+	if withInstalls.Popularity == nil || withInstalls.Popularity.Stars != nil || *withInstalls.Popularity.Installs != 42 {
+		t.Fatalf("expected stars cleared and installs kept, got %+v", withInstalls.Popularity)
+	}
+	if bare.Popularity != nil {
+		t.Fatalf("expected Popularity dropped when no signal remains, got %+v", bare.Popularity)
+	}
+}
diff --git a/specs/110-catalog-popularity/plan.md b/specs/110-catalog-popularity/plan.md
index 62b982392..47860b381 100644
--- a/specs/110-catalog-popularity/plan.md
+++ b/specs/110-catalog-popularity/plan.md
@@ -100,3 +100,4 @@ SearchAll(q)
 ## Review log
 
 - **zcode round 1 (spec, 2026-09-26)**: 9 findings, all verified and folded into FR-005/006/007/008/009/011 and the flow above. (1) Official must be built from the pre-sort merge order. (2) The per-source cap limits the pool, so empty q now fans out at 50/source, and the Docker single page is a documented limitation. (3) Background fetch uses the provider ctx, not the request ctx. (4) Overflow must not leave dedup entries behind. (5) No wait while paused or over budget. (6) Errors keep the last-known stars. (7) Lookup distinguishes negative from absent. (8) Own request, 10 s ctx timeout, never `registryGet`, no retries. (9) Kill switch lives in the constructor.
+- **Opus subagent round 2 (code, 2026-09-26; zcode, opencode and codex were all out of quota)**: 4 findings, all verified and fixed, each with a regression test shown to fail without the fix. (1) A 200 that is oversized, not JSON, or has no `stargazers_count` is now a failed fetch, so it keeps the last-known stars and ETag. (2) After `Close`, workers drop buffered keys and shutdown-cancelled requests are not stored. (3) `applyCachedStars` falls back to source-native stars when a refresh turns a hit Negative. (4) A closed provider's `Resolve` returns at once, and `Close` wakes pending waiters.