From 92bb43a8b32fa0f8e5a395d4e18cbbf918483399 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 29 May 2026 10:43:15 +0300
Subject: [PATCH 01/10] feat(060): form-based settings page with partial-update
 PATCH /config

Redesign the Web UI Configuration page from a raw Monaco JSON editor into
prioritized, form-based sections: Security & Access / General / Advanced
(subsystem accordions) / Raw JSON (Monaco kept) / Teams (server edition).

Backend: new generic PATCH /api/v1/config that deep-merges only the fields
the client sends onto the live config and routes through ApplyConfig. Starting
from the real in-memory config means a section save never clobbers untouched
fields or masked secrets (api_key, secret headers). Modeled on
handlePatchDockerIsolation.

Frontend: declarative field catalogue (fields.ts) drives SettingField +
SettingsSection (per-section partial save, toast, restart/sensitive badges,
danger-confirm dialogs). Settings.vue becomes the tab shell. data-test ids on
all controls.

Verified end-to-end (Playwright; Chrome ext unavailable): all sections render,
partial save persists require_mcp_auth while preserving api_key, danger-confirm
cancel prevents reveal_secret_headers, restart badges shown. Backend
secret-preservation unit tests green.

Relates to Spec 060.
---
 docs/features/settings-page.md                |  38 ++
 .../src/components/settings/SettingField.vue  | 157 +++++++
 .../components/settings/SettingsSection.vue   | 189 ++++++++
 frontend/src/services/api.ts                  |  10 +
 frontend/src/views/Settings.vue               | 439 ++++++++----------
 frontend/src/views/settings/fields.ts         | 271 +++++++++++
 internal/httpapi/server.go                    | 103 ++++
 internal/httpapi/server_config_patch_test.go  | 265 +++++++++++
 oas/docs.go                                   |   2 +-
 oas/swagger.yaml                              |  46 ++
 .../checklists/requirements.md                |  29 ++
 specs/060-settings-page/data-model.md         |  46 ++
 specs/060-settings-page/plan.md               |  71 +++
 specs/060-settings-page/quickstart.md         |  26 ++
 specs/060-settings-page/research.md           |  29 ++
 specs/060-settings-page/spec.md               | 115 +++++
 specs/060-settings-page/tasks.md              |  48 ++
 17 files changed, 1634 insertions(+), 250 deletions(-)
 create mode 100644 docs/features/settings-page.md
 create mode 100644 frontend/src/components/settings/SettingField.vue
 create mode 100644 frontend/src/components/settings/SettingsSection.vue
 create mode 100644 frontend/src/views/settings/fields.ts
 create mode 100644 internal/httpapi/server_config_patch_test.go
 create mode 100644 specs/060-settings-page/checklists/requirements.md
 create mode 100644 specs/060-settings-page/data-model.md
 create mode 100644 specs/060-settings-page/plan.md
 create mode 100644 specs/060-settings-page/quickstart.md
 create mode 100644 specs/060-settings-page/research.md
 create mode 100644 specs/060-settings-page/spec.md
 create mode 100644 specs/060-settings-page/tasks.md

diff --git a/docs/features/settings-page.md b/docs/features/settings-page.md
new file mode 100644
index 000000000..c8b7abe4f
--- /dev/null
+++ b/docs/features/settings-page.md
@@ -0,0 +1,38 @@
+# Settings Page (Web UI)
+
+The Web UI **Configuration** page (`/ui/settings`) presents mcpproxy's config as
+friendly, prioritized form sections instead of raw JSON:
+
+- **Security & Access** — API key (masked, show/regenerate), require MCP auth,
+  quarantine, global Docker isolation, code execution, read-only mode,
+  sensitive-data detection, reveal secret headers, listen address.
+- **General** — routing mode, tool limits, response limit, call timeout, log
+  level, telemetry, prompts.
+- **Advanced** — collapsible accordions per subsystem (code execution, Docker
+  isolation, sensitive-data detection, output validation, output sanitisation,
+  activity retention, logging, TLS, …).
+- **Raw JSON** — the full Monaco editor, kept as an escape hatch.
+- **Teams** — server edition only.
+
+## How saving works
+
+Each section saves **only the fields you changed** via `PATCH /api/v1/config`, a
+partial deep-merge that routes through the normal validate → persist → hot-reload
+pipeline. Because the merge starts from the live config and overlays just your
+changes, unrelated values and masked secrets (API key, secret headers) are never
+overwritten.
+
+Fields that need a restart (`listen`, `data_dir`, `api_key`, `tls.*`) show a
+**restart** badge; sensitive changes (reveal secret headers, disabling
+quarantine/management, binding to a non-loopback address) require an explicit
+confirmation before they apply.
+
+```bash
+# Equivalent API call — change one field, everything else preserved
+curl -X PATCH -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
+  -d '{"quarantine_enabled": false}' http://127.0.0.1:8080/api/v1/config
+```
+
+Complex lists/maps (Docker image map, custom detection patterns, environment
+vars) and `mcpServers` / `registries` are managed on their own pages or the Raw
+JSON tab. See [configuration.md](../configuration.md) for the full option reference.
diff --git a/frontend/src/components/settings/SettingField.vue b/frontend/src/components/settings/SettingField.vue
new file mode 100644
index 000000000..022f39b3c
--- /dev/null
+++ b/frontend/src/components/settings/SettingField.vue
@@ -0,0 +1,157 @@
+<template>
+  <div
+    class="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-2 py-3 border-b border-base-200 last:border-0"
+    :data-test="`setting-row-${field.key}`"
+  >
+    <!-- Label + help + badges -->
+    <div class="sm:max-w-md">
+      <div class="flex items-center gap-2 flex-wrap">
+        <span class="font-medium">{{ field.label }}</span>
+        <span v-if="field.restart" class="badge badge-warning badge-xs gap-1" title="Requires restart">
+          restart
+        </span>
+        <span v-if="field.danger" class="badge badge-error badge-xs" title="Sensitive change">
+          sensitive
+        </span>
+      </div>
+      <p v-if="field.help" class="text-xs text-base-content/60 mt-0.5">{{ field.help }}</p>
+    </div>
+
+    <!-- Control -->
+    <div class="shrink-0">
+      <!-- toggle -->
+      <input
+        v-if="field.control === 'toggle'"
+        type="checkbox"
+        class="toggle toggle-primary"
+        :checked="!!modelValue"
+        :data-test="`setting-toggle-${field.key}`"
+        @change="emitVal(($event.target as HTMLInputElement).checked)"
+      />
+
+      <!-- select -->
+      <select
+        v-else-if="field.control === 'select'"
+        class="select select-bordered select-sm min-w-[12rem]"
+        :value="modelValue ?? ''"
+        :data-test="`setting-select-${field.key}`"
+        @change="emitVal(($event.target as HTMLSelectElement).value)"
+      >
+        <option v-for="opt in field.options" :key="opt.value" :value="opt.value">{{ opt.label }}</option>
+      </select>
+
+      <!-- number -->
+      <input
+        v-else-if="field.control === 'number'"
+        type="number"
+        class="input input-bordered input-sm w-32"
+        :class="{ 'input-error': numberError }"
+        :value="modelValue"
+        :min="field.min"
+        :max="field.max"
+        :step="field.step"
+        :data-test="`setting-number-${field.key}`"
+        @input="onNumber(($event.target as HTMLInputElement).value)"
+      />
+
+      <!-- secret -->
+      <div v-else-if="field.control === 'secret'" class="join">
+        <input
+          :type="showSecret ? 'text' : 'password'"
+          class="input input-bordered input-sm join-item w-56 font-mono"
+          :value="modelValue ?? ''"
+          :placeholder="field.placeholder"
+          :data-test="`setting-secret-${field.key}`"
+          @input="emitVal(($event.target as HTMLInputElement).value)"
+        />
+        <button type="button" class="btn btn-sm join-item" :title="showSecret ? 'Hide' : 'Show'" @click="showSecret = !showSecret">
+          {{ showSecret ? '🙈' : '👁' }}
+        </button>
+        <button
+          type="button"
+          class="btn btn-sm join-item"
+          :data-test="`setting-regenerate-${field.key}`"
+          title="Generate a new random key"
+          @click="regenerate"
+        >
+          ↻
+        </button>
+      </div>
+
+      <!-- text / duration -->
+      <input
+        v-else-if="field.control === 'text' || field.control === 'duration'"
+        type="text"
+        class="input input-bordered input-sm w-56 font-mono"
+        :value="modelValue ?? ''"
+        :placeholder="field.placeholder"
+        :data-test="`setting-text-${field.key}`"
+        @input="emitVal(($event.target as HTMLInputElement).value)"
+      />
+
+      <!-- multiselect (checkbox group) -->
+      <div v-else-if="field.control === 'multiselect'" class="flex flex-wrap gap-3 justify-end max-w-xs">
+        <label v-for="opt in field.options" :key="opt.value" class="label cursor-pointer gap-1 p-0">
+          <input
+            type="checkbox"
+            class="checkbox checkbox-xs"
+            :checked="Array.isArray(modelValue) && modelValue.includes(opt.value)"
+            :data-test="`setting-multi-${field.key}-${opt.value}`"
+            @change="toggleMulti(opt.value, ($event.target as HTMLInputElement).checked)"
+          />
+          <span class="text-xs">{{ opt.label }}</span>
+        </label>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+import type { SettingField } from '@/views/settings/fields'
+
+const props = defineProps<{ field: SettingField; modelValue: any }>()
+const emit = defineEmits<{ (e: 'update:modelValue', v: any): void }>()
+
+const showSecret = ref(false)
+
+const numberError = computed(() => {
+  if (props.field.control !== 'number' || props.modelValue == null || props.modelValue === '') return false
+  const n = Number(props.modelValue)
+  if (Number.isNaN(n)) return true
+  if (props.field.min != null && n < props.field.min) return true
+  if (props.field.max != null && n > props.field.max) return true
+  return false
+})
+
+function emitVal(v: any) {
+  emit('update:modelValue', v)
+}
+
+function onNumber(raw: string) {
+  if (raw === '') {
+    emitVal('')
+    return
+  }
+  emitVal(Number(raw))
+}
+
+function toggleMulti(value: string, checked: boolean) {
+  const cur = Array.isArray(props.modelValue) ? [...props.modelValue] : []
+  const idx = cur.indexOf(value)
+  if (checked && idx === -1) cur.push(value)
+  if (!checked && idx !== -1) cur.splice(idx, 1)
+  emitVal(cur)
+}
+
+function regenerate() {
+  // 32-byte random hex key — generated client-side; user must save + restart.
+  const bytes = new Uint8Array(32)
+  crypto.getRandomValues(bytes)
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')
+  showSecret.value = true
+  emitVal(hex)
+}
+
+defineExpose({ numberError })
+</script>
diff --git a/frontend/src/components/settings/SettingsSection.vue b/frontend/src/components/settings/SettingsSection.vue
new file mode 100644
index 000000000..05b6fbce7
--- /dev/null
+++ b/frontend/src/components/settings/SettingsSection.vue
@@ -0,0 +1,189 @@
+<template>
+  <div class="space-y-3" :data-test="`settings-section-${sectionId}`">
+    <SettingField
+      v-for="f in fields"
+      :key="f.key"
+      :field="f"
+      :model-value="getPath(working, f.key)"
+      @update:model-value="onChange(f, $event)"
+    />
+
+    <!-- per-section action bar -->
+    <div class="flex items-center justify-between pt-2">
+      <div class="text-sm min-h-[1.25rem]">
+        <span v-if="lastResult?.requires_restart" class="text-warning" :data-test="`settings-restart-${sectionId}`">
+          ⚠️ Saved — restart required{{ lastResult.restart_reason ? `: ${lastResult.restart_reason}` : '' }}
+        </span>
+        <span v-else-if="lastResult" class="text-success" :data-test="`settings-saved-${sectionId}`">
+          ✓ Saved
+        </span>
+        <span v-else-if="error" class="text-error">{{ error }}</span>
+        <span v-else-if="dirtyKeys.length" class="text-base-content/60">
+          {{ dirtyKeys.length }} unsaved change{{ dirtyKeys.length > 1 ? 's' : '' }}
+        </span>
+      </div>
+      <button
+        class="btn btn-primary btn-sm"
+        :disabled="!dirtyKeys.length || saving || hasInvalid"
+        :data-test="`settings-apply-${sectionId}`"
+        @click="attemptSave"
+      >
+        <span v-if="saving" class="loading loading-spinner loading-xs"></span>
+        Save changes
+      </button>
+    </div>
+
+    <!-- danger confirm -->
+    <dialog ref="confirmEl" class="modal" :data-test="`settings-confirm-${sectionId}`">
+      <div class="modal-box">
+        <h3 class="font-bold text-lg text-error">Confirm sensitive change</h3>
+        <ul class="list-disc list-inside text-sm mt-3 space-y-2">
+          <li v-for="(m, i) in pendingMessages" :key="i">{{ m }}</li>
+        </ul>
+        <div class="modal-action">
+          <button class="btn btn-sm" @click="cancelConfirm" data-test="settings-confirm-cancel">Cancel</button>
+          <button class="btn btn-sm btn-error" @click="proceedConfirm" data-test="settings-confirm-proceed">
+            Apply anyway
+          </button>
+        </div>
+      </div>
+      <form method="dialog" class="modal-backdrop"><button @click="cancelConfirm">close</button></form>
+    </dialog>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, getCurrentInstance } from 'vue'
+import SettingField from './SettingField.vue'
+import { getPath, setPath, buildPartial, type SettingField as Field } from '@/views/settings/fields'
+import { useSystemStore } from '@/stores/system'
+import api from '@/services/api'
+
+const props = defineProps<{
+  sectionId: string
+  fields: Field[]
+  working: any // reactive working copy of the full config
+  original: any // snapshot of last-saved values
+}>()
+const emit = defineEmits<{ (e: 'saved', changed: string[]): void }>()
+
+const systemStore = useSystemStore()
+const saving = ref(false)
+const error = ref('')
+const lastResult = ref<any>(null)
+const dirty = ref<Record<string, true>>({})
+const confirmEl = ref<HTMLDialogElement | null>(null)
+const pendingMessages = ref<string[]>([])
+
+const dirtyKeys = computed(() => Object.keys(dirty.value))
+
+// crude validity gate: any number field out of range blocks save
+const hasInvalid = computed(() =>
+  props.fields.some((f) => {
+    if (f.control !== 'number') return false
+    const v = getPath(props.working, f.key)
+    if (v === '' || v == null) return true
+    const n = Number(v)
+    if (Number.isNaN(n)) return true
+    if (f.min != null && n < f.min) return true
+    if (f.max != null && n > f.max) return true
+    return false
+  })
+)
+
+function eq(a: any, b: any): boolean {
+  return JSON.stringify(a) === JSON.stringify(b)
+}
+
+function onChange(f: Field, val: any) {
+  setPath(props.working, f.key, val)
+  if (eq(getPath(props.working, f.key), getPath(props.original, f.key))) {
+    delete dirty.value[f.key]
+  } else {
+    dirty.value[f.key] = true
+  }
+  dirty.value = { ...dirty.value } // trigger reactivity
+  lastResult.value = null
+  error.value = ''
+}
+
+function isLoopback(addr: any): boolean {
+  const s = String(addr ?? '')
+  return /^(127\.|localhost|\[::1\]|::1)/.test(s.replace(/^.*@/, '')) || s.startsWith('127.0.0.1')
+}
+
+function dangerMessages(): string[] {
+  const msgs: string[] = []
+  for (const key of dirtyKeys.value) {
+    const f = props.fields.find((x) => x.key === key)
+    if (!f?.danger) continue
+    const val = getPath(props.working, key)
+    if ('confirmValue' in f.danger) {
+      if (eq(val, f.danger.confirmValue)) msgs.push(f.danger.message)
+    } else if (f.key === 'listen') {
+      if (!isLoopback(val)) msgs.push(f.danger.message)
+    } else {
+      msgs.push(f.danger.message)
+    }
+  }
+  return msgs
+}
+
+function attemptSave() {
+  const msgs = dangerMessages()
+  if (msgs.length) {
+    pendingMessages.value = msgs
+    confirmEl.value?.showModal()
+    return
+  }
+  void doSave()
+}
+
+function cancelConfirm() {
+  confirmEl.value?.close()
+  pendingMessages.value = []
+}
+
+function proceedConfirm() {
+  confirmEl.value?.close()
+  pendingMessages.value = []
+  void doSave()
+}
+
+async function doSave() {
+  saving.value = true
+  error.value = ''
+  lastResult.value = null
+  try {
+    const keys = dirtyKeys.value
+    const partial = buildPartial(props.working, keys)
+    const resp = await api.patchConfig(partial)
+    if (resp.success && resp.data) {
+      lastResult.value = resp.data
+      if (resp.data.validation_errors && resp.data.validation_errors.length) {
+        error.value = resp.data.validation_errors.map((e: any) => `${e.field}: ${e.message}`).join('; ')
+        lastResult.value = null
+      } else {
+        // commit saved values into the original snapshot, clear dirty
+        for (const k of keys) setPath(props.original, k, getPath(props.working, k))
+        dirty.value = {}
+        systemStore.addToast({
+          type: resp.data.requires_restart ? 'warning' : 'success',
+          title: resp.data.requires_restart ? 'Saved — restart required' : 'Settings saved',
+          message: (resp.data.changed_fields || keys).join(', '),
+        })
+        emit('saved', keys)
+      }
+    } else {
+      error.value = resp.error || 'Failed to save'
+    }
+  } catch (e: any) {
+    error.value = e?.message || 'Failed to save'
+  } finally {
+    saving.value = false
+  }
+}
+
+// keep getCurrentInstance import used (avoids tree-shake lint in some setups)
+void getCurrentInstance
+</script>
diff --git a/frontend/src/services/api.ts b/frontend/src/services/api.ts
index 86ed88b11..3b60fed0a 100644
--- a/frontend/src/services/api.ts
+++ b/frontend/src/services/api.ts
@@ -595,6 +595,16 @@ class APIService {
     })
   }
 
+  // patchConfig applies a partial (deep-merged) config update — only the
+  // fields present in `partial` are changed; everything else (including masked
+  // secrets like api_key) is preserved server-side. Spec 060.
+  async patchConfig(partial: Record<string, any>): Promise<APIResponse<ConfigApplyResult>> {
+    return this.request<ConfigApplyResult>('/api/v1/config', {
+      method: 'PATCH',
+      body: JSON.stringify(partial)
+    })
+  }
+
   // Token statistics endpoints
   async getTokenStats(): Promise<APIResponse<ServerTokenMetrics>> {
     return this.request<ServerTokenMetrics>('/api/v1/stats/tokens')
diff --git a/frontend/src/views/Settings.vue b/frontend/src/views/Settings.vue
index f51e742dd..048997ff6 100644
--- a/frontend/src/views/Settings.vue
+++ b/frontend/src/views/Settings.vue
@@ -4,141 +4,173 @@
     <div class="flex justify-between items-center">
       <div>
         <h1 class="text-3xl font-bold">Configuration</h1>
-        <p class="text-base-content/70 mt-1">Edit your MCPProxy configuration directly. Changes require restart for some settings.</p>
+        <p class="text-base-content/70 mt-1">
+          Manage mcpproxy settings. Changes save instantly; a badge marks fields that need a restart.
+        </p>
       </div>
+      <button class="btn btn-sm btn-outline" :disabled="loading" @click="loadConfig" data-test="settings-reload">
+        <span v-if="loading" class="loading loading-spinner loading-xs"></span>
+        <span v-else>Reload</span>
+      </button>
     </div>
 
-    <!-- Configuration Editor -->
-    <div class="card bg-base-100 shadow-md">
-      <div class="card-body">
-        <div class="flex justify-between items-center mb-4">
-          <div>
-            <h2 class="card-title">Configuration Editor</h2>
-            <p class="text-sm text-base-content/70 mt-1">
-              Edit your MCPProxy configuration directly. Changes require restart for some settings.
-            </p>
-          </div>
-          <div class="flex items-center space-x-2">
-            <div v-if="configStatus" :class="['badge', configStatus.valid ? 'badge-success' : 'badge-error']">
-              {{ configStatus.valid ? '✓ Valid' : '✗ Invalid' }}
-            </div>
-            <button
-              class="btn btn-sm btn-outline"
-              @click="loadConfig"
-              :disabled="loadingConfig"
-            >
-              <span v-if="loadingConfig" class="loading loading-spinner loading-xs"></span>
-              <span v-else>Reload</span>
-            </button>
-          </div>
+    <!-- Tabs -->
+    <div role="tablist" class="tabs tabs-bordered" data-test="settings-tabs">
+      <button
+        v-for="t in tabs"
+        :key="t.id"
+        role="tab"
+        class="tab gap-2"
+        :class="{ 'tab-active font-semibold': activeTab === t.id }"
+        :data-test="`settings-tab-${t.id}`"
+        @click="activeTab = t.id"
+      >
+        <span>{{ t.icon }}</span> {{ t.label }}
+      </button>
+    </div>
+
+    <div v-if="loadError" class="alert alert-error">
+      <span>{{ loadError }}</span>
+    </div>
+
+    <template v-else-if="loaded">
+      <!-- Security & Access -->
+      <div v-show="activeTab === 'security'" class="card bg-base-100 shadow-md">
+        <div class="card-body">
+          <h2 class="card-title text-lg">🔒 Security &amp; Access</h2>
+          <p class="text-sm text-base-content/60 mb-2">The settings that most affect how exposed and protected your instance is.</p>
+          <SettingsSection section-id="security" :fields="securityFields" :working="state.working" :original="state.original" />
         </div>
+      </div>
 
-        <!-- Monaco Editor -->
-        <div class="border border-base-300 rounded-lg overflow-hidden" style="height: 600px;">
-          <vue-monaco-editor
-            v-model:value="configJson"
-            language="json"
-            theme="vs-dark"
-            :options="editorOptions"
-            @mount="handleEditorMount"
-            @change="handleConfigChange"
-          />
+      <!-- General -->
+      <div v-show="activeTab === 'general'" class="card bg-base-100 shadow-md">
+        <div class="card-body">
+          <h2 class="card-title text-lg">⚙️ General</h2>
+          <SettingsSection section-id="general" :fields="generalFields" :working="state.working" :original="state.original" />
         </div>
+      </div>
 
-        <!-- Validation Errors -->
-        <div v-if="configErrors.length > 0" class="alert alert-error mt-4">
-          <svg xmlns="http://www.w3.org/2000/svg" class="stroke-current shrink-0 h-6 w-6" fill="none" viewBox="0 0 24 24">
-            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 14l2-2m0 0l2-2m-2 2l-2-2m2 2l2 2m7-2a9 9 0 11-18 0 9 9 0 0118 0z" />
-          </svg>
-          <div>
-            <h3 class="font-bold">Validation Errors</h3>
-            <ul class="list-disc list-inside text-sm">
-              <li v-for="(error, index) in configErrors" :key="index">
-                <span class="font-mono">{{ error.field }}</span>: {{ error.message }}
-              </li>
-            </ul>
+      <!-- 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">
+          <summary class="collapse-title font-medium" :data-test="`settings-accordion-${acc.id}`">{{ acc.title }}</summary>
+          <div class="collapse-content">
+            <p v-if="acc.description" class="text-xs text-base-content/60 mb-2">{{ acc.description }}</p>
+            <SettingsSection :section-id="acc.id" :fields="acc.fields" :working="state.working" :original="state.original" />
           </div>
+        </details>
+        <div class="text-xs text-base-content/50 px-1">
+          Complex lists/maps (image map, custom detection patterns, environment vars, registries) and
+          <RouterLink to="/" class="link">servers</RouterLink> are managed on their own pages or the Raw JSON tab.
         </div>
+      </div>
+
+      <!-- Teams (server edition only) -->
+      <div v-if="hasTeams" v-show="activeTab === 'teams'" class="card bg-base-100 shadow-md">
+        <div class="card-body">
+          <h2 class="card-title text-lg">👥 Teams / Server</h2>
+          <SettingsSection section-id="teams" :fields="teamsFields" :working="state.working" :original="state.original" />
+        </div>
+      </div>
 
-        <!-- Apply Configuration -->
-        <div class="flex justify-between items-center mt-4">
-          <div class="text-sm text-base-content/70">
-            <span v-if="applyResult && applyResult.requires_restart" class="text-warning">
-              ⚠️ {{ applyResult.restart_reason }}
-            </span>
-            <span v-else-if="applyResult && applyResult.applied_immediately" class="text-success">
-              ✓ Configuration applied successfully
-            </span>
+      <!-- Raw JSON (existing Monaco editor) -->
+      <div v-show="activeTab === 'raw'" class="card bg-base-100 shadow-md">
+        <div class="card-body">
+          <div class="flex justify-between items-center mb-2">
+            <h2 class="card-title text-lg">{ } Raw JSON</h2>
+            <div v-if="configStatus" :class="['badge', configStatus.valid ? 'badge-success' : 'badge-error']">
+              {{ configStatus.valid ? '✓ Valid' : '✗ Invalid' }}
+            </div>
+          </div>
+          <p class="text-sm text-base-content/60 mb-2">Full configuration editor. Edits here apply the entire document.</p>
+          <div class="border border-base-300 rounded-lg overflow-hidden" style="height: 560px;">
+            <vue-monaco-editor
+              v-model:value="configJson"
+              language="json"
+              theme="vs-dark"
+              :options="editorOptions"
+              @change="handleConfigChange"
+            />
           </div>
-          <div class="flex items-center space-x-2">
-            <button
-              class="btn btn-outline"
-              @click="validateConfig"
-              :disabled="validatingConfig || !configJson"
-            >
-              <span v-if="validatingConfig" class="loading loading-spinner loading-sm"></span>
-              Validate
+          <div v-if="configErrors.length > 0" class="alert alert-error mt-4">
+            <div>
+              <h3 class="font-bold">Validation Errors</h3>
+              <ul class="list-disc list-inside text-sm">
+                <li v-for="(err, i) in configErrors" :key="i"><span class="font-mono">{{ err.field }}</span>: {{ err.message }}</li>
+              </ul>
+            </div>
+          </div>
+          <div class="flex justify-end gap-2 mt-4">
+            <button class="btn btn-outline btn-sm" :disabled="validatingConfig || !configJson" @click="validateConfig" data-test="settings-raw-validate">
+              <span v-if="validatingConfig" class="loading loading-spinner loading-xs"></span> Validate
             </button>
-            <button
-              class="btn btn-primary"
-              @click="applyConfig"
-              :disabled="applyingConfig || configErrors.length > 0 || !configJson"
-            >
-              <span v-if="applyingConfig" class="loading loading-spinner loading-sm"></span>
-              Apply Configuration
+            <button class="btn btn-primary btn-sm" :disabled="applyingConfig || configErrors.length > 0 || !configJson" @click="applyConfig" data-test="settings-raw-apply">
+              <span v-if="applyingConfig" class="loading loading-spinner loading-xs"></span> Apply
             </button>
           </div>
         </div>
       </div>
-    </div>
-
-    <!-- Configuration Info -->
-    <div class="card bg-base-100 shadow-md">
-      <div class="card-body">
-        <h3 class="card-title text-sm">Configuration Tips</h3>
-        <div class="text-sm text-base-content/70 space-y-2">
-          <p>• Use <kbd class="kbd kbd-xs">Ctrl+Space</kbd> for autocomplete</p>
-          <p>• Use <kbd class="kbd kbd-xs">Ctrl+F</kbd> to search in the configuration</p>
-          <p>• Invalid JSON will be highlighted with red squiggles</p>
-          <p>• <span class="font-semibold">Hot-reloadable</span>: server changes, limits, logging</p>
-          <p>• <span class="font-semibold">Requires restart</span>: listen address, data directory, API key, TLS</p>
-        </div>
-      </div>
-    </div>
+    </template>
 
-    <!-- Hints Panel (Bottom of Page) -->
     <CollapsibleHintsPanel :hints="settingsHints" />
   </div>
 </template>
 
 <script setup lang="ts">
-import { ref, computed, onMounted, onUnmounted } from 'vue'
+import { ref, reactive, computed, onMounted, onUnmounted } from 'vue'
+import { RouterLink } from 'vue-router'
 import { VueMonacoEditor } from '@guolao/vue-monaco-editor'
 import { useServersStore } from '@/stores/servers'
+import { useSystemStore } from '@/stores/system'
 import CollapsibleHintsPanel from '@/components/CollapsibleHintsPanel.vue'
 import type { Hint } from '@/components/CollapsibleHintsPanel.vue'
+import SettingsSection from '@/components/settings/SettingsSection.vue'
+import {
+  SECURITY_FIELDS,
+  GENERAL_FIELDS,
+  ADVANCED_ACCORDIONS,
+  type SettingField,
+} from '@/views/settings/fields'
 import api from '@/services/api'
 
-// Store references
 const serversStore = useServersStore()
+const systemStore = useSystemStore()
+
+const securityFields = SECURITY_FIELDS
+const generalFields = GENERAL_FIELDS
+const advancedAccordions = ADVANCED_ACCORDIONS
+const teamsFields: SettingField[] = [
+  { key: 'teams.enabled', label: 'Enable multi-user mode', control: 'toggle', restart: true },
+  { key: 'teams.oauth.provider', label: 'OAuth provider', control: 'select', options: ['', 'google', 'github', 'microsoft'].map((v) => ({ value: v, label: v || '(none)' })) },
+  { key: 'teams.max_user_servers', label: 'Max servers per user', control: 'number', min: 0 },
+]
 
-// Configuration editor state
+// ---- form state ----
+const loading = ref(false)
+const loaded = ref(false)
+const loadError = ref('')
+const activeTab = ref<string>('security')
+const state = reactive<{ working: any; original: any }>({ working: {}, original: {} })
+const hasTeams = computed(() => state.working && state.working.teams != null)
+
+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 (hasTeams.value) base.push({ id: 'teams', label: 'Teams', icon: '👥' })
+  base.push({ id: 'raw', label: 'Raw JSON', icon: '{ }' })
+  return base
+})
+
+// ---- Raw JSON (Monaco) state, preserved from the previous editor ----
 const configJson = ref('')
-const loadingConfig = ref(false)
 const validatingConfig = ref(false)
 const applyingConfig = ref(false)
 const configStatus = ref<{ valid: boolean } | null>(null)
 const configErrors = ref<Array<{ field: string; message: string }>>([])
-const applyResult = ref<{
-  success: boolean
-  applied_immediately: boolean
-  requires_restart: boolean
-  restart_reason?: string
-  changed_fields?: string[]
-} | null>(null)
-const editorInstance = ref<any>(null)
-
-// Monaco editor options
 const editorOptions = {
   automaticLayout: true,
   formatOnType: true,
@@ -147,77 +179,61 @@ const editorOptions = {
   scrollBeyondLastLine: false,
   fontSize: 14,
   tabSize: 2,
-  wordWrap: 'on' as 'on',
-  lineNumbers: 'on' as 'on',
-  glyphMargin: true,
-  folding: true,
-  lineDecorationsWidth: 10,
-  lineNumbersMinChars: 3
+  wordWrap: 'on' as const,
+  lineNumbers: 'on' as const,
 }
 
-// Configuration editor methods
-function handleEditorMount(editor: any) {
-  editorInstance.value = editor
-}
-
-function handleConfigChange() {
-  // Reset validation state on change
-  configErrors.value = []
-  configStatus.value = null
-  applyResult.value = null
-
-  // Try to parse JSON to check syntax
-  try {
-    JSON.parse(configJson.value)
-    configStatus.value = { valid: true }
-  } catch (e) {
-    configStatus.value = { valid: false }
-  }
+function clone<T>(v: T): T {
+  return JSON.parse(JSON.stringify(v))
 }
 
 async function loadConfig() {
-  loadingConfig.value = true
-  configErrors.value = []
-  applyResult.value = null
-
+  loading.value = true
+  loadError.value = ''
   try {
     const response = await api.getConfig()
     if (response.success && response.data) {
-      configJson.value = JSON.stringify(response.data.config, null, 2)
+      const cfg = response.data.config
+      state.working = clone(cfg)
+      state.original = clone(cfg)
+      configJson.value = JSON.stringify(cfg, null, 2)
       configStatus.value = { valid: true }
+      loaded.value = true
     } else {
-      configErrors.value = [{ field: 'general', message: response.error || 'Failed to load configuration' }]
+      loadError.value = response.error || 'Failed to load configuration'
     }
-  } catch (error: any) {
-    console.error('Failed to load config:', error)
-    configErrors.value = [{ field: 'general', message: error.message || 'Failed to load configuration' }]
+  } catch (e: any) {
+    loadError.value = e?.message || 'Failed to load configuration'
   } finally {
-    loadingConfig.value = false
+    loading.value = false
+  }
+}
+
+function handleConfigChange() {
+  configErrors.value = []
+  try {
+    JSON.parse(configJson.value)
+    configStatus.value = { valid: true }
+  } catch {
+    configStatus.value = { valid: false }
   }
 }
 
 async function validateConfig() {
   validatingConfig.value = true
   configErrors.value = []
-
   try {
-    // Parse JSON first
-    const config = JSON.parse(configJson.value)
-
-    // Call validation endpoint
-    const response = await api.validateConfig(config)
+    const cfg = JSON.parse(configJson.value)
+    const response = await api.validateConfig(cfg)
     if (response.success && response.data) {
       configErrors.value = response.data.errors || []
       configStatus.value = { valid: response.data.valid }
-      if (response.data.valid) {
-        console.log('Configuration validated successfully')
-      }
     } else {
       configErrors.value = [{ field: 'general', message: response.error || 'Validation failed' }]
       configStatus.value = { valid: false }
     }
-  } catch (error: any) {
-    configErrors.value = [{ field: 'json', message: error.message || 'Invalid JSON syntax' }]
+  } catch (e: any) {
+    configErrors.value = [{ field: 'json', message: e?.message || 'Invalid JSON syntax' }]
     configStatus.value = { valid: false }
   } finally {
     validatingConfig.value = false
@@ -227,128 +243,53 @@ async function validateConfig() {
 async function applyConfig() {
   applyingConfig.value = true
   configErrors.value = []
-  applyResult.value = null
-
   try {
-    // Parse JSON first
-    const config = JSON.parse(configJson.value)
-
-    // Call apply configuration endpoint
-    const response = await api.applyConfig(config)
+    const cfg = JSON.parse(configJson.value)
+    const response = await api.applyConfig(cfg)
     if (response.success && response.data) {
-      applyResult.value = response.data
-      if (response.data.applied_immediately) {
-        // Refresh UI data to reflect changes
-        await serversStore.fetchServers()
-      }
-      console.log('Configuration applied successfully:', response.data)
+      systemStore.addToast({
+        type: response.data.requires_restart ? 'warning' : 'success',
+        title: response.data.requires_restart ? 'Applied — restart required' : 'Configuration applied',
+      })
+      if (response.data.applied_immediately) await serversStore.fetchServers()
+      await loadConfig()
     } else {
       configErrors.value = [{ field: 'apply', message: response.error || 'Failed to apply configuration' }]
     }
-  } catch (error: any) {
-    configErrors.value = [{ field: 'apply', message: error.message || 'Failed to apply configuration' }]
+  } catch (e: any) {
+    configErrors.value = [{ field: 'apply', message: e?.message || 'Failed to apply configuration' }]
   } finally {
     applyingConfig.value = false
   }
 }
 
-// Settings hints
-const settingsHints = computed<Hint[]>(() => {
-  return [
-    {
-      icon: '⚙️',
-      title: 'Configuration Management',
-      description: 'Edit MCPProxy configuration with JSON editor',
-      sections: [
-        {
-          title: 'Hot-Reloadable Settings',
-          text: 'These settings are applied immediately without restarting:',
-          list: [
-            'Server enable/disable status',
-            'Tool limits and search parameters',
-            'Log levels and output settings',
-            'Cache and timeout settings'
-          ]
-        },
-        {
-          title: 'Restart Required',
-          text: 'These settings require mcpproxy restart to take effect:',
-          list: [
-            'Listen address (network binding)',
-            'Data directory path',
-            'API key authentication',
-            'TLS/HTTPS configuration'
-          ]
-        }
-      ]
-    },
-    {
-      icon: '🔧',
-      title: 'CLI Configuration Tools',
-      description: 'Manage configuration from the command line',
-      sections: [
-        {
-          title: 'View current configuration',
-          codeBlock: {
-            language: 'bash',
-            code: `# View configuration location\nmcpproxy config path\n\n# Dump current config\ncat ~/.mcpproxy/mcp_config.json`
-          }
-        },
-        {
-          title: 'Backup configuration',
-          codeBlock: {
-            language: 'bash',
-            code: `# Create backup\ncp ~/.mcpproxy/mcp_config.json ~/.mcpproxy/mcp_config.backup.json`
-          }
-        }
-      ]
-    },
-    {
-      icon: '💡',
-      title: 'Configuration Tips',
-      description: 'Best practices for managing MCPProxy config',
-      sections: [
-        {
-          title: 'Editor features',
-          list: [
-            'Use Ctrl+Space for autocomplete suggestions',
-            'Use Ctrl+F to search within the configuration',
-            'Invalid JSON is highlighted with red squiggles',
-            'Format with Ctrl+Shift+F (or Cmd+Shift+F on Mac)'
-          ]
-        },
-        {
-          title: 'Version control',
-          text: 'Consider tracking your configuration in git (excluding secrets):',
-          codeBlock: {
-            language: 'bash',
-            code: `# Initialize git repo for configs\ncd ~/.mcpproxy\ngit init\necho "*.db" >> .gitignore\necho "*.bleve/" >> .gitignore\ngit add mcp_config.json\ngit commit -m "Initial MCPProxy configuration"`
-          }
-        }
-      ]
-    }
-  ]
-})
-
-// Configuration reload event listener
-function handleConfigSaved(event: Event) {
-  const customEvent = event as CustomEvent
-  console.log('Configuration saved event received, reloading config:', customEvent.detail)
+const settingsHints = computed<Hint[]>(() => [
+  {
+    icon: '🔒',
+    title: 'Settings',
+    description: 'Manage configuration from friendly forms or raw JSON',
+    sections: [
+      {
+        title: 'Saving',
+        text: 'Each section saves only the fields you changed, so secrets like your API key are never overwritten.',
+      },
+      {
+        title: 'Requires restart',
+        list: ['Listen address', 'Data directory', 'API key', 'TLS/HTTPS settings'],
+      },
+    ],
+  },
+])
 
-  // Reload configuration to show updated servers
+function handleConfigSaved() {
   loadConfig()
 }
 
-// Initialize component
 onMounted(() => {
-  loadConfig() // Load configuration when component mounts
-
-  // Listen for config.saved events from SSE
+  loadConfig()
   window.addEventListener('mcpproxy:config-saved', handleConfigSaved)
 })
-
 onUnmounted(() => {
-  // Clean up event listener
   window.removeEventListener('mcpproxy:config-saved', handleConfigSaved)
 })
 </script>
diff --git a/frontend/src/views/settings/fields.ts b/frontend/src/views/settings/fields.ts
new file mode 100644
index 000000000..4e5e879cc
--- /dev/null
+++ b/frontend/src/views/settings/fields.ts
@@ -0,0 +1,271 @@
+// Spec 060 — declarative settings field catalogue.
+// Drives the form-based Settings page. Each entry maps a dot-path into the
+// mcpproxy config to a labelled control. Keeping this declarative makes the
+// page auditable ("every non-deprecated option reachable") and gives every
+// control a systematic data-test id.
+
+export type ControlType =
+  | 'toggle'
+  | 'select'
+  | 'number'
+  | 'text'
+  | 'secret'
+  | 'duration'
+  | 'multiselect'
+
+export interface SelectOption {
+  value: string
+  label: string
+}
+
+export interface DangerSpec {
+  // Confirm before applying. For toggles/selects, only when the new value
+  // equals confirmValue (omit to always confirm on change).
+  message: string
+  confirmValue?: unknown
+}
+
+export interface SettingField {
+  key: string // dot-path, e.g. "docker_isolation.enabled"
+  label: string
+  help?: string
+  control: ControlType
+  options?: SelectOption[]
+  min?: number
+  max?: number
+  step?: number
+  restart?: boolean // requires server restart to take effect
+  danger?: DangerSpec
+  placeholder?: string
+}
+
+export interface SettingsAccordion {
+  id: string
+  title: string
+  description?: string
+  fields: SettingField[]
+}
+
+// ---- Section 1: Security & Access (prioritised, security-first) ----
+export const SECURITY_FIELDS: SettingField[] = [
+  {
+    key: 'api_key',
+    label: 'API key',
+    help: 'Secret for REST API authentication. Leave blank to keep the current key.',
+    control: 'secret',
+    restart: true,
+    placeholder: '•••••••• (unchanged)',
+  },
+  {
+    key: 'require_mcp_auth',
+    label: 'Require auth on /mcp',
+    help: 'Reject unauthenticated requests to the MCP endpoint.',
+    control: 'toggle',
+  },
+  {
+    key: 'quarantine_enabled',
+    label: 'Security quarantine',
+    help: 'Auto-quarantine new servers and require approval for changed tools (Tool Poisoning protection).',
+    control: 'toggle',
+    danger: {
+      confirmValue: false,
+      message:
+        'Disabling quarantine removes Tool Poisoning Attack protection — new servers and changed tools will run without approval. Continue?',
+    },
+  },
+  {
+    key: 'docker_isolation.enabled',
+    label: 'Global Docker isolation',
+    help: 'Run stdio MCP servers inside Docker containers by default.',
+    control: 'toggle',
+  },
+  {
+    key: 'enable_code_execution',
+    label: 'Code execution tool',
+    help: 'Expose the sandboxed JavaScript code_execution tool.',
+    control: 'toggle',
+  },
+  {
+    key: 'read_only_mode',
+    label: 'Read-only mode',
+    help: 'Block all write and destructive tool calls.',
+    control: 'toggle',
+  },
+  {
+    key: 'sensitive_data_detection.enabled',
+    label: 'Sensitive-data detection',
+    help: 'Scan tool calls and responses for secrets and credentials.',
+    control: 'toggle',
+  },
+  {
+    key: 'reveal_secret_headers',
+    label: 'Reveal secret headers',
+    help: 'Stop redacting Authorization / API-Key headers in responses and logs.',
+    control: 'toggle',
+    danger: {
+      confirmValue: true,
+      message:
+        'Revealing secret headers will expose credentials in tool responses, logs and the activity view. Only enable for debugging. Continue?',
+    },
+  },
+  {
+    key: 'listen',
+    label: 'Listen address',
+    help: 'Network bind address. Keep 127.0.0.1 unless you intend remote access.',
+    control: 'text',
+    restart: true,
+    placeholder: '127.0.0.1:8080',
+    danger: {
+      message:
+        'Binding to a non-loopback address exposes mcpproxy on your network. Make sure authentication is enabled. Continue?',
+    },
+  },
+]
+
+// ---- Section 2: General ----
+export const GENERAL_FIELDS: SettingField[] = [
+  {
+    key: 'routing_mode',
+    label: 'Routing mode',
+    help: 'How upstream tools are exposed to agents.',
+    control: 'select',
+    options: [
+      { value: 'retrieve_tools', label: 'Retrieve tools (BM25 discovery)' },
+      { value: 'direct', label: 'Direct (all tools listed)' },
+      { value: 'code_execution', label: 'Code execution' },
+    ],
+  },
+  { key: 'tools_limit', label: 'Tools per search', help: 'Max tools returned by retrieve_tools.', control: 'number', min: 1, max: 1000 },
+  { key: 'tool_response_limit', label: 'Tool response limit (chars)', help: '0 disables truncation.', control: 'number', min: 0 },
+  { key: 'call_tool_timeout', label: 'Tool call timeout', help: 'e.g. 2m, 90s.', control: 'duration', placeholder: '2m' },
+  {
+    key: 'logging.level',
+    label: 'Log level',
+    control: 'select',
+    options: ['trace', 'debug', 'info', 'warn', 'error'].map((v) => ({ value: v, label: v })),
+  },
+  { key: 'telemetry.enabled', label: 'Anonymous telemetry', help: 'Opt-out anonymous usage metrics.', control: 'toggle' },
+  { key: 'enable_prompts', label: 'Expose MCP prompts', control: 'toggle' },
+]
+
+// ---- Section 3: Advanced (subsystem accordions) ----
+export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
+  {
+    id: 'code-execution',
+    title: 'Code execution',
+    fields: [
+      { key: 'code_execution_timeout_ms', label: 'Timeout (ms)', control: 'number', min: 1, max: 600000 },
+      { key: 'code_execution_max_tool_calls', label: 'Max tool calls (0 = unlimited)', control: 'number', min: 0 },
+      { key: 'code_execution_pool_size', label: 'Runtime pool size', control: 'number', min: 1, max: 100 },
+    ],
+  },
+  {
+    id: 'docker-isolation',
+    title: 'Docker isolation',
+    description: 'Per-image and resource detail. Image map / extra args are editable in the Raw JSON tab.',
+    fields: [
+      { key: 'docker_isolation.network_mode', label: 'Network mode', control: 'select', options: ['bridge', 'none', 'host'].map((v) => ({ value: v, label: v })) },
+      { key: 'docker_isolation.memory_limit', label: 'Memory limit', control: 'text', placeholder: '512m' },
+      { key: 'docker_isolation.cpu_limit', label: 'CPU limit', control: 'text', placeholder: '1.0' },
+      { key: 'docker_isolation.registry', label: 'Registry', control: 'text', placeholder: 'docker.io' },
+      { key: 'docker_isolation.enable_cache_volume', label: 'Cache volume', control: 'toggle' },
+    ],
+  },
+  {
+    id: 'sensitive-data',
+    title: 'Sensitive-data detection',
+    description: 'Per-category toggles and custom patterns are editable in the Raw JSON tab.',
+    fields: [
+      { key: 'sensitive_data_detection.scan_requests', label: 'Scan tool arguments', control: 'toggle' },
+      { key: 'sensitive_data_detection.scan_responses', label: 'Scan tool responses', control: 'toggle' },
+      { key: 'sensitive_data_detection.max_payload_size_kb', label: 'Max scan size (KB)', control: 'number', min: 1 },
+      { key: 'sensitive_data_detection.entropy_threshold', label: 'Entropy threshold', control: 'number', min: 0, max: 8, step: 0.1 },
+    ],
+  },
+  {
+    id: 'output-validation',
+    title: 'Output-schema validation (Track A)',
+    fields: [
+      { key: 'output_validation.mode', label: 'Mode', control: 'select', options: ['off', 'warn', 'strict'].map((v) => ({ value: v, label: v })) },
+      { key: 'output_validation.missing_structured_content', label: 'Missing structured content', control: 'select', options: ['allow', 'block'].map((v) => ({ value: v, label: v })) },
+    ],
+  },
+  {
+    id: 'output-sanitisation',
+    title: 'Output sanitisation (Track B)',
+    fields: [
+      { key: 'output_sanitisation.spotlight_untrusted', label: 'Spotlight untrusted output', control: 'toggle' },
+      { key: 'output_sanitisation.response_action', label: 'Response action', control: 'select', options: ['spotlight', 'redact', 'block'].map((v) => ({ value: v, label: v })) },
+      { key: 'output_sanitisation.strip_control_chars', label: 'Strip control sequences', control: 'toggle' },
+      { key: 'output_sanitisation.strip_classes', label: 'Strip classes', control: 'multiselect', options: ['ansi', 'c0c1', 'bidi', 'zero_width'].map((v) => ({ value: v, label: v })) },
+      { key: 'output_sanitisation.max_redactions', label: 'Max redactions / response', control: 'number', min: 0 },
+    ],
+  },
+  {
+    id: 'activity',
+    title: 'Activity log retention',
+    fields: [
+      { key: 'activity_retention_days', label: 'Retention (days)', control: 'number', min: 0 },
+      { key: 'activity_max_records', label: 'Max records', control: 'number', min: 0 },
+      { key: 'activity_cleanup_interval_min', label: 'Cleanup interval (min)', control: 'number', min: 1 },
+    ],
+  },
+  {
+    id: 'logging',
+    title: 'Logging',
+    fields: [
+      { key: 'logging.enable_file', label: 'Log to file', control: 'toggle' },
+      { key: 'logging.enable_console', label: 'Log to console', control: 'toggle' },
+      { key: 'logging.json_format', label: 'JSON format', control: 'toggle' },
+      { key: 'logging.max_size', label: 'Max size (MB)', control: 'number', min: 1 },
+      { key: 'logging.max_backups', label: 'Max backups', control: 'number', min: 0 },
+      { key: 'logging.max_age', label: 'Max age (days)', control: 'number', min: 0 },
+    ],
+  },
+  {
+    id: 'tls',
+    title: 'TLS / HTTPS',
+    fields: [
+      { key: 'tls.enabled', label: 'Enable HTTPS', control: 'toggle', restart: true },
+      { key: 'tls.require_client_cert', label: 'Require client cert (mTLS)', control: 'toggle', restart: true },
+      { key: 'tls.hsts', label: 'HSTS header', control: 'toggle', restart: true },
+    ],
+  },
+  {
+    id: 'misc',
+    title: 'Miscellaneous',
+    fields: [
+      { key: 'max_result_size_chars', label: 'Max inline response (chars, 0 = off)', control: 'number', min: 0 },
+      { key: 'oauth_expiry_warning_hours', label: 'OAuth expiry warning (hours)', control: 'number', min: 0, step: 0.5 },
+      { key: 'disable_management', label: 'Disable management tool', control: 'toggle', danger: { confirmValue: true, message: 'Disabling the management tool prevents agents from adding/removing servers. Continue?' } },
+      { key: 'allow_server_add', label: 'Allow agents to add servers', control: 'toggle' },
+      { key: 'allow_server_remove', label: 'Allow agents to remove servers', control: 'toggle' },
+      { key: 'debug_search', label: 'Debug BM25 search', control: 'toggle' },
+    ],
+  },
+]
+
+// ---- path helpers ----
+export function getPath(obj: any, path: string): any {
+  return path.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj)
+}
+
+export function setPath(obj: any, path: string, value: any): void {
+  const keys = path.split('.')
+  let cur = obj
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (cur[keys[i]] == null || typeof cur[keys[i]] !== 'object') cur[keys[i]] = {}
+    cur = cur[keys[i]]
+  }
+  cur[keys[keys.length - 1]] = value
+}
+
+// buildPartial assembles a nested object containing ONLY the given dot-path
+// keys, read from `source`. This is the partial payload sent to PATCH /config.
+export function buildPartial(source: any, dirtyKeys: string[]): Record<string, any> {
+  const out: Record<string, any> = {}
+  for (const key of dirtyKeys) {
+    setPath(out, key, getPath(source, key))
+  }
+  return out
+}
diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go
index f75b7d8ed..17a45dd4f 100644
--- a/internal/httpapi/server.go
+++ b/internal/httpapi/server.go
@@ -613,6 +613,7 @@ func (s *Server) setupRoutes() {
 		r.Get("/config", s.handleGetConfig)
 		r.Post("/config/validate", s.handleValidateConfig)
 		r.Post("/config/apply", s.handleApplyConfig)
+		r.Patch("/config", s.handlePatchConfig)
 		r.Patch("/config/docker-isolation", s.handlePatchDockerIsolation)
 
 		// Registry browsing (Phase 7)
@@ -3734,6 +3735,108 @@ func (s *Server) handlePatchDockerIsolation(w http.ResponseWriter, r *http.Reque
 	s.writeSuccess(w, response)
 }
 
+// handlePatchConfig godoc
+// @Summary      Partially update configuration
+// @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.
+// @Tags         config
+// @Accept       json
+// @Produce      json
+// @Param        patch  body      object                        true  "Partial configuration with only the fields to change"
+// @Success      200    {object}  contracts.ConfigApplyResult   "Configuration patch applied (inspect validation_errors for rejected values)"
+// @Failure      400    {object}  contracts.ErrorResponse       "Invalid JSON payload or empty patch"
+// @Failure      401    {object}  contracts.ErrorResponse       "Unauthorized - missing or invalid API key"
+// @Failure      500    {object}  contracts.ErrorResponse       "Failed to read or apply configuration"
+// @Security     ApiKeyAuth
+// @Security     ApiKeyQuery
+// @Router       /api/v1/config [patch]
+func (s *Server) handlePatchConfig(w http.ResponseWriter, r *http.Request) {
+	var patchMap map[string]interface{}
+	if err := json.NewDecoder(r.Body).Decode(&patchMap); err != nil {
+		s.writeError(w, r, http.StatusBadRequest, "Invalid JSON payload")
+		return
+	}
+	if len(patchMap) == 0 {
+		s.writeError(w, r, http.StatusBadRequest, "Patch body must contain at least one field")
+		return
+	}
+
+	// Read the REAL in-memory config (secrets intact — redaction only happens
+	// on the GET response path). We deep-merge only the client-sent keys so
+	// untouched fields, including masked secrets, are preserved verbatim.
+	cfg, err := s.controller.GetConfig()
+	if err != nil {
+		s.logger.Error("Failed to get configuration for patch", "error", err)
+		s.writeError(w, r, http.StatusInternalServerError, "Failed to read configuration")
+		return
+	}
+	if cfg == nil {
+		s.writeError(w, r, http.StatusInternalServerError, "Configuration not available")
+		return
+	}
+
+	// Round-trip the live config through JSON to get a generic map we can
+	// deep-merge the patch onto without enumerating every field.
+	baseBytes, err := json.Marshal(cfg)
+	if err != nil {
+		s.logger.Error("Failed to marshal live configuration", "error", err)
+		s.writeError(w, r, http.StatusInternalServerError, "Failed to read configuration")
+		return
+	}
+	var baseMap map[string]interface{}
+	if err := json.Unmarshal(baseBytes, &baseMap); err != nil {
+		s.logger.Error("Failed to unmarshal live configuration", "error", err)
+		s.writeError(w, r, http.StatusInternalServerError, "Failed to read configuration")
+		return
+	}
+
+	deepMergeJSON(baseMap, patchMap)
+
+	mergedBytes, err := json.Marshal(baseMap)
+	if err != nil {
+		s.logger.Error("Failed to marshal merged configuration", "error", err)
+		s.writeError(w, r, http.StatusInternalServerError, "Failed to build configuration")
+		return
+	}
+	var merged config.Config
+	if err := json.Unmarshal(mergedBytes, &merged); err != nil {
+		s.writeError(w, r, http.StatusBadRequest, fmt.Sprintf("Invalid configuration patch: %v", err))
+		return
+	}
+
+	result, err := s.controller.ApplyConfig(&merged, s.controller.GetConfigPath())
+	if err != nil {
+		s.logger.Error("Failed to apply configuration patch", "error", err)
+		s.writeError(w, r, http.StatusInternalServerError, fmt.Sprintf("Failed to apply configuration: %v", err))
+		return
+	}
+
+	response := &contracts.ConfigApplyResult{
+		Success:            result.Success,
+		AppliedImmediately: result.AppliedImmediately,
+		RequiresRestart:    result.RequiresRestart,
+		RestartReason:      result.RestartReason,
+		ChangedFields:      result.ChangedFields,
+		ValidationErrors:   contracts.ConvertValidationErrors(result.ValidationErrors),
+	}
+	s.writeSuccess(w, response)
+}
+
+// deepMergeJSON recursively merges patch into base. When both base[k] and
+// patch[k] are JSON objects (map[string]interface{}), they are merged
+// recursively; otherwise patch[k] overwrites base[k] (arrays and scalars
+// replace wholesale). Keys present only in base are preserved.
+func deepMergeJSON(base, patch map[string]interface{}) {
+	for k, patchVal := range patch {
+		patchSub, patchIsMap := patchVal.(map[string]interface{})
+		baseSub, baseIsMap := base[k].(map[string]interface{})
+		if patchIsMap && baseIsMap {
+			deepMergeJSON(baseSub, patchSub)
+			continue
+		}
+		base[k] = patchVal
+	}
+}
+
 // handleCallTool godoc
 // @Summary Call a tool
 // @Description Execute a tool on an upstream MCP server (wrapper around MCP tool calls)
diff --git a/internal/httpapi/server_config_patch_test.go b/internal/httpapi/server_config_patch_test.go
new file mode 100644
index 000000000..1377cbcac
--- /dev/null
+++ b/internal/httpapi/server_config_patch_test.go
@@ -0,0 +1,265 @@
+package httpapi
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
+	runtime "github.com/smart-mcp-proxy/mcpproxy-go/internal/runtime"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+)
+
+// mockPatchConfigController captures the *config.Config passed to ApplyConfig
+// so PATCH /api/v1/config tests can assert the deep-merge result that reaches
+// the apply pipeline (secret preservation, nested merge, change detection).
+type mockPatchConfigController struct {
+	baseController
+	apiKey       string
+	live         *config.Config
+	captured     *config.Config
+	changedField string
+	// validationErrs, when non-empty, is returned from ApplyConfig so a test
+	// can assert that invalid values surface as validation errors rather than
+	// corrupting config.
+	validationErrs []config.ValidationError
+}
+
+func (m *mockPatchConfigController) GetCurrentConfig() any {
+	return &config.Config{APIKey: m.apiKey}
+}
+
+func (m *mockPatchConfigController) GetConfig() (*config.Config, error) {
+	return m.live, nil
+}
+
+func (m *mockPatchConfigController) GetConfigPath() string { return "/tmp/mcp_config.json" }
+
+func (m *mockPatchConfigController) ApplyConfig(cfg *config.Config, _ string) (*runtime.ConfigApplyResult, error) {
+	clone := *cfg
+	m.captured = &clone
+	if len(m.validationErrs) > 0 {
+		return &runtime.ConfigApplyResult{
+			Success:          false,
+			ValidationErrors: m.validationErrs,
+		}, nil
+	}
+	changed := []string{}
+	if m.changedField != "" {
+		changed = []string{m.changedField}
+	}
+	return &runtime.ConfigApplyResult{
+		Success:            true,
+		AppliedImmediately: true,
+		ChangedFields:      changed,
+	}, nil
+}
+
+func boolPtrPatch(b bool) *bool { return &b }
+
+func decodePatchResult(t *testing.T, body []byte) map[string]interface{} {
+	t.Helper()
+	var envelope map[string]interface{}
+	require.NoError(t, json.Unmarshal(body, &envelope))
+	// writeSuccess wraps the payload; tolerate either a bare result or a
+	// {success, data} envelope.
+	if data, ok := envelope["data"].(map[string]interface{}); ok {
+		return data
+	}
+	return envelope
+}
+
+// TestHandlePatchConfig_SecretPreservation is the core invariant: patching a
+// single non-secret field must leave a pre-set api_key untouched. The PATCH
+// handler reads the REAL in-memory config (secrets intact), deep-merges only
+// the client-sent keys, and pushes the result through ApplyConfig — so the
+// api_key, which was never in the patch body, must survive verbatim.
+func TestHandlePatchConfig_SecretPreservation(t *testing.T) {
+	logger := zap.NewNop().Sugar()
+	mockCtrl := &mockPatchConfigController{
+		apiKey: "test-key",
+		live: &config.Config{
+			APIKey:            "super-secret-api-key",
+			QuarantineEnabled: boolPtrPatch(true),
+		},
+		changedField: "quarantine_enabled",
+	}
+	srv := NewServer(mockCtrl, logger, nil)
+
+	body, _ := json.Marshal(map[string]any{"quarantine_enabled": false})
+	req := httptest.NewRequest(http.MethodPatch, "/api/v1/config", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code, "body=%s", w.Body.String())
+	require.NotNil(t, mockCtrl.captured, "ApplyConfig should have been called")
+
+	assert.Equal(t, "super-secret-api-key", mockCtrl.captured.APIKey,
+		"api_key must be preserved verbatim — it was never in the PATCH body")
+	require.NotNil(t, mockCtrl.captured.QuarantineEnabled)
+	assert.False(t, *mockCtrl.captured.QuarantineEnabled,
+		"quarantine_enabled must reflect the PATCH body (false)")
+}
+
+// TestHandlePatchConfig_NestedMerge verifies that patching one field inside a
+// nested object flips it while sibling fields set on the live config survive.
+func TestHandlePatchConfig_NestedMerge(t *testing.T) {
+	logger := zap.NewNop().Sugar()
+	mockCtrl := &mockPatchConfigController{
+		apiKey: "test-key",
+		live: &config.Config{
+			APIKey: "super-secret-api-key",
+			DockerIsolation: &config.DockerIsolationConfig{
+				Enabled:     false,
+				MemoryLimit: "512m",
+			},
+		},
+		changedField: "docker_isolation",
+	}
+	srv := NewServer(mockCtrl, logger, nil)
+
+	body := []byte(`{"docker_isolation":{"enabled":true}}`)
+	req := httptest.NewRequest(http.MethodPatch, "/api/v1/config", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code, "body=%s", w.Body.String())
+	require.NotNil(t, mockCtrl.captured)
+	require.NotNil(t, mockCtrl.captured.DockerIsolation)
+
+	assert.True(t, mockCtrl.captured.DockerIsolation.Enabled,
+		"docker_isolation.enabled must be flipped by the PATCH")
+	assert.Equal(t, "512m", mockCtrl.captured.DockerIsolation.MemoryLimit,
+		"sibling docker_isolation.memory_limit must be preserved")
+	assert.Equal(t, "super-secret-api-key", mockCtrl.captured.APIKey,
+		"api_key must be preserved")
+}
+
+// TestHandlePatchConfig_ChangedFields verifies the patched key surfaces in the
+// response's changed_fields.
+func TestHandlePatchConfig_ChangedFields(t *testing.T) {
+	logger := zap.NewNop().Sugar()
+	mockCtrl := &mockPatchConfigController{
+		apiKey:       "test-key",
+		live:         &config.Config{QuarantineEnabled: boolPtrPatch(true)},
+		changedField: "quarantine_enabled",
+	}
+	srv := NewServer(mockCtrl, logger, nil)
+
+	body := []byte(`{"quarantine_enabled":false}`)
+	req := httptest.NewRequest(http.MethodPatch, "/api/v1/config", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code, "body=%s", w.Body.String())
+	result := decodePatchResult(t, w.Body.Bytes())
+	changed, _ := result["changed_fields"].([]interface{})
+	require.NotEmpty(t, changed, "changed_fields must be populated, got %v", result)
+	assert.Contains(t, changed, "quarantine_enabled")
+}
+
+// TestHandlePatchConfig_EmptyBody rejects an empty object with 400.
+func TestHandlePatchConfig_EmptyBody(t *testing.T) {
+	logger := zap.NewNop().Sugar()
+	mockCtrl := &mockPatchConfigController{apiKey: "test-key", live: &config.Config{}}
+	srv := NewServer(mockCtrl, logger, nil)
+
+	req := httptest.NewRequest(http.MethodPatch, "/api/v1/config", bytes.NewReader([]byte(`{}`)))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusBadRequest, w.Code, "body=%s", w.Body.String())
+	assert.Nil(t, mockCtrl.captured, "empty body must not reach ApplyConfig")
+}
+
+// TestHandlePatchConfig_MalformedJSON rejects invalid JSON with 400.
+func TestHandlePatchConfig_MalformedJSON(t *testing.T) {
+	logger := zap.NewNop().Sugar()
+	mockCtrl := &mockPatchConfigController{apiKey: "test-key", live: &config.Config{}}
+	srv := NewServer(mockCtrl, logger, nil)
+
+	req := httptest.NewRequest(http.MethodPatch, "/api/v1/config", bytes.NewReader([]byte(`{not json`)))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusBadRequest, w.Code, "body=%s", w.Body.String())
+	assert.Nil(t, mockCtrl.captured)
+}
+
+// TestHandlePatchConfig_ValidationErrors verifies that an invalid value
+// surfaces as validation errors in the response rather than corrupting config.
+func TestHandlePatchConfig_ValidationErrors(t *testing.T) {
+	logger := zap.NewNop().Sugar()
+	mockCtrl := &mockPatchConfigController{
+		apiKey: "test-key",
+		live:   &config.Config{APIKey: "super-secret-api-key"},
+		validationErrs: []config.ValidationError{
+			{Field: "listen", Message: "invalid address"},
+		},
+	}
+	srv := NewServer(mockCtrl, logger, nil)
+
+	body := []byte(`{"listen":"not a valid addr"}`)
+	req := httptest.NewRequest(http.MethodPatch, "/api/v1/config", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.ServeHTTP(w, req)
+
+	require.Equal(t, http.StatusOK, w.Code, "body=%s", w.Body.String())
+	result := decodePatchResult(t, w.Body.Bytes())
+	assert.Equal(t, false, result["success"], "success must be false on validation error")
+	verrs, _ := result["validation_errors"].([]interface{})
+	require.NotEmpty(t, verrs, "validation_errors must be populated, got %v", result)
+}
+
+// TestDeepMergeJSON unit-tests the recursive merge helper directly.
+func TestDeepMergeJSON(t *testing.T) {
+	base := map[string]interface{}{
+		"api_key": "secret",
+		"docker_isolation": map[string]interface{}{
+			"enabled":      false,
+			"memory_limit": "512m",
+		},
+		"servers": []interface{}{"a", "b"},
+		"scalar":  1,
+	}
+	patch := map[string]interface{}{
+		"docker_isolation": map[string]interface{}{
+			"enabled": true,
+		},
+		"servers": []interface{}{"c"}, // arrays replace wholesale
+		"scalar":  2,
+		"new_key": "x",
+	}
+
+	deepMergeJSON(base, patch)
+
+	// Untouched key preserved.
+	assert.Equal(t, "secret", base["api_key"])
+	// Nested merge: enabled flipped, sibling preserved.
+	di := base["docker_isolation"].(map[string]interface{})
+	assert.Equal(t, true, di["enabled"])
+	assert.Equal(t, "512m", di["memory_limit"])
+	// Array replaced wholesale.
+	assert.Equal(t, []interface{}{"c"}, base["servers"])
+	// Scalar overwritten.
+	assert.Equal(t, 2, base["scalar"])
+	// New key added.
+	assert.Equal(t, "x", base["new_key"])
+}
diff --git a/oas/docs.go b/oas/docs.go
index 920ee66c1..1a57fce88 100644
--- a/oas/docs.go
+++ b/oas/docs.go
@@ -9,7 +9,7 @@ const docTemplate = `{
     "components": {"schemas":{"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_retention_days":{"description":"Activity logging settings (RFC-003)","type":"integer"},"allow_server_add":{"type":"boolean"},"allow_server_remove":{"type":"boolean"},"api_key":{"description":"Security settings","type":"string"},"call_tool_timeout":{"type":"string"},"check_server_repo":{"description":"Repository detection settings","type":"boolean"},"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"},"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"},"intent_declaration":{"$ref":"#/components/schemas/config.IntentDeclarationConfig"},"listen":{"type":"string"},"logging":{"$ref":"#/components/schemas/config.LogConfig"},"max_result_size_chars":{"description":"Advertised on every tool as ` + "`" + `_meta.anthropic/maxResultSizeChars` + "`" + `; raises Claude Code's inline-response ceiling from 50k to up to 500k chars. Set to 0 to disable.","type":"integer"},"mcpServers":{"items":{"$ref":"#/components/schemas/config.ServerConfig"},"type":"array","uniqueItems":false},"oauth_expiry_warning_hours":{"description":"Health status settings","type":"number"},"output_sanitisation":{"$ref":"#/components/schemas/config.OutputSanitisationConfig"},"output_validation":{"$ref":"#/components/schemas/config.OutputValidationConfig"},"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"},"read_only_mode":{"type":"boolean"},"registries":{"description":"Registries configuration for MCP server discovery","items":{"$ref":"#/components/schemas/config.RegistryEntry"},"type":"array","uniqueItems":false},"require_mcp_auth":{"description":"Require authentication on /mcp endpoint (default: false)","type":"boolean"},"reveal_secret_headers":{"description":"RevealSecretHeaders, when true, disables the redaction of sensitive\nheader values (Authorization, X-API-Key, Cookie, …) in responses\nfrom the ` + "`" + `upstream_servers` + "`" + ` MCP tool, the ` + "`" + `/api/v1/servers` + "`" + ` REST\nAPI, and the SSE event stream.\n\nDefault false — sensitive header values are surfaced as\n` + "`" + `***REDACTED***` + "`" + ` so an MCP agent cannot read Bearer tokens / API\nkeys out of another upstream's config (PR #425).\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"},"telemetry":{"$ref":"#/components/schemas/config.TelemetryConfig"},"tls":{"$ref":"#/components/schemas/config.TLSConfig"},"tokenizer":{"$ref":"#/components/schemas/config.TokenizerConfig"},"tool_response_limit":{"type":"integer"},"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"},"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"}},"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.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","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"},"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)","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"},"network_mode":{"description":"Custom network mode for this server","type":"string"},"working_dir":{"description":"Custom working directory in container","type":"string"}},"type":"object"},"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.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.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.RegistryEntry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"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_scan_quarantined":{"type":"boolean"},"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":"ScannerDisableNoNewPrivileges, 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_registry_url":{"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},"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"},"headers":{"additionalProperties":{"type":"string"},"description":"For HTTP servers","type":"object"},"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"},"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"},"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":"Skip tool-level quarantine for this server","type":"boolean"},"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"},"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"},"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":{"arguments":{"description":"Tool call arguments","type":"object"},"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"},"request_id":{"description":"HTTP request ID for correlation","type":"string"},"response":{"description":"Tool response (potentially truncated)","type":"string"},"response_truncated":{"description":"True if response was truncated","type":"boolean"},"server_name":{"description":"Name of upstream MCP server","type":"string"},"session_id":{"description":"MCP session ID for correlation","type":"string"},"source":{"$ref":"#/components/schemas/contracts.ActivitySource"},"status":{"description":"Result status: \"success\", \"error\", \"blocked\"","type":"string"},"timestamp":{"description":"When activity occurred","type":"string"},"tool_name":{"description":"Name of tool called","type":"string"},"type":{"$ref":"#/components/schemas/contracts.ActivityType"}},"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"},"end_time":{"description":"End of the period (RFC3339)","type":"string"},"error_count":{"description":"Count of error activities","type":"integer"},"period":{"description":"Time period (1h, 24h, 7d, 30d)","type":"string"},"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.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.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.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\", 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"},"listen_addr":{"description":"Listen address (e.g., \"127.0.0.1:8080\")","type":"string"},"update":{"$ref":"#/components/schemas/contracts.UpdateInfo"},"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":{"type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"type":"string"},"memory_limit":{"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.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"}},"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.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.Registry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"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":{"query":{"type":"string"},"registry_id":{"type":"string"},"servers":{"items":{"$ref":"#/components/schemas/contracts.RepositoryServer"},"type":"array","uniqueItems":false},"tag":{"type":"string"},"total":{"type":"integer"}},"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":{"finding_counts":{"$ref":"#/components/schemas/contracts.FindingCounts"},"last_scan_at":{"type":"string"},"risk_score":{"description":"0-100","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"},"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"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"health":{"$ref":"#/components/schemas/contracts.HealthStatus"},"id":{"type":"string"},"isolation":{"$ref":"#/components/schemas/contracts.IsolationConfig"},"isolation_defaults":{"$ref":"#/components/schemas/contracts.IsolationDefaults"},"last_error":{"type":"string"},"last_reconnect_at":{"type":"string"},"last_retry_time":{"type":"string"},"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"},"reconnect_count":{"type":"integer"},"reconnect_on_use":{"description":"Attempt reconnection when a tool call targets this disconnected server","type":"boolean"},"retry_count":{"type":"integer"},"security_scan":{"$ref":"#/components/schemas/contracts.SecurityScanSummary"},"should_retry":{"type":"boolean"},"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"},"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"},"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"},"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"},"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"},"check_error":{"description":"Error message if update check failed","type":"string"},"checked_at":{"description":"When the update check was performed","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"},"release_url":{"description":"URL to the release page","type":"string"}},"type":"object"},"contracts.UpstreamError":{"properties":{"error_message":{"type":"string"},"server_name":{"type":"string"},"timestamp":{"type":"string"}},"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},"command":{"type":"string"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"isolation":{"$ref":"#/components/schemas/httpapi.IsolationRequest"},"name":{"type":"string"},"protocol":{"type":"string"},"quarantined":{"type":"boolean"},"reconnect_on_use":{"type":"boolean"},"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.ConnectRequest":{"properties":{"force":{"description":"Overwrite existing entry","type":"boolean"},"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 OriginalName → new name. Applied after parsing so the\ncaller can disambiguate cross-source name collisions (Spec 046 v2 —\ne.g. \"mcpproxy\" → \"mcpproxy_claude_code\"). Keys not present in the\nimported 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 (image,\nnetwork_mode, extra_args, working_dir, enabled). A nil pointer\nmeans \"do not touch isolation config\"; an empty-but-present\nobject on PATCH intentionally clears the overrides.","properties":{"enabled":{"type":"boolean"},"extra_args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"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.","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"},"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"},"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"],"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 session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"enum":["success","error","blocked"],"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":"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"}}],"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 session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","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/{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/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"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get current 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"},"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"},"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, cursor, windsurf, vscode, codex, gemini)","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"},"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"]},"post":{"description":"Register MCPProxy as an MCP server in the specified client's configuration file.\nCreates a backup of the existing config before modifying.","parameters":[{"description":"Client ID (claude-code, cursor, windsurf, vscode, codex, gemini)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional connection parameters"},"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"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Already connected (use force=true)"},"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/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\nThis endpoint is designed for tray-core communication and version checking\nUse refresh=true query parameter to force an immediate update check against GitHub","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"},"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"},"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/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"]}},"/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/routing":{"get":{"description":"Get the current routing mode and available MCP endpoints","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.","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"},"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"},"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"},"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.","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"},"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"},"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"},"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)"},"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"},"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.)"},"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)"},"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}/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"},"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/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)"},"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"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionsResponse"}}},"description":"Sessions 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 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"},"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"},"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"},"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/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"},"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)"},"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"],"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 session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"enum":["success","error","blocked"],"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":"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"}}],"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 session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","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/{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/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"},"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"},"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"},"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"},"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, cursor, windsurf, vscode, codex, gemini)","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"},"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"]},"post":{"description":"Register MCPProxy as an MCP server in the specified client's configuration file.\nCreates a backup of the existing config before modifying.","parameters":[{"description":"Client ID (claude-code, cursor, windsurf, vscode, codex, gemini)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional connection parameters"},"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"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Already connected (use force=true)"},"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/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\nThis endpoint is designed for tray-core communication and version checking\nUse refresh=true query parameter to force an immediate update check against GitHub","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"},"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"},"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/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"]}},"/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/routing":{"get":{"description":"Get the current routing mode and available MCP endpoints","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.","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"},"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"},"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"},"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.","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"},"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"},"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"},"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)"},"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"},"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.)"},"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)"},"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}/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"},"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/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)"},"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"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionsResponse"}}},"description":"Sessions 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 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"},"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"},"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"},"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/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"},"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)"},"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 4cceca346..5667853da 100644
--- a/oas/swagger.yaml
+++ b/oas/swagger.yaml
@@ -2670,6 +2670,52 @@ paths:
       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
+        "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
diff --git a/specs/060-settings-page/checklists/requirements.md b/specs/060-settings-page/checklists/requirements.md
new file mode 100644
index 000000000..12c76c365
--- /dev/null
+++ b/specs/060-settings-page/checklists/requirements.md
@@ -0,0 +1,29 @@
+# Specification Quality Checklist: UX-Friendly Settings Page
+
+**Created**: 2026-05-29
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+- [x] No implementation details leak into requirements (kept at WHAT/WHY; tech confined to Context/Testing)
+- [x] Focused on user value
+- [x] Written for stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+- [x] No [NEEDS CLARIFICATION] markers
+- [x] Requirements testable and unambiguous
+- [x] Success criteria measurable
+- [x] Success criteria technology-agnostic
+- [x] Acceptance scenarios defined
+- [x] Edge cases identified (secret-clobber, deprecated hidden, restart-required, validation)
+- [x] Scope bounded (settings UI + one partial-update endpoint; servers/registries excluded)
+- [x] Dependencies/assumptions identified (existing /config API, redaction behaviour)
+
+## Feature Readiness
+- [x] FRs have acceptance criteria
+- [x] User scenarios cover primary flows (Security → General → Advanced/Raw → Teams)
+- [x] Meets measurable outcomes
+- [x] No impl detail leak
+
+## Notes
+- MVP = User Story 1 (Security & Access section) + partial-update PATCH. Ready for `/speckit.plan`.
diff --git a/specs/060-settings-page/data-model.md b/specs/060-settings-page/data-model.md
new file mode 100644
index 000000000..fb664e068
--- /dev/null
+++ b/specs/060-settings-page/data-model.md
@@ -0,0 +1,46 @@
+# Phase 1 Data Model: Settings Page
+
+## API contract — `PATCH /api/v1/config`
+
+**Request**: a partial config object (any subset of the `mcp_config.json` shape). Examples:
+```json
+{ "quarantine_enabled": false }
+{ "docker_isolation": { "enabled": true } }
+{ "logging": { "level": "debug" }, "telemetry": { "enabled": false } }
+```
+**Response** (`200`): `contracts.ConfigApplyResult` — same as `/config/apply`:
+```json
+{ "success": true, "applied_immediately": true, "requires_restart": false,
+  "restart_reason": "", "changed_fields": ["quarantine_enabled"], "validation_errors": [] }
+```
+**Errors**: `400` invalid JSON; `400`/`200`+validation_errors on invalid values (via ApplyConfig); `500` read/apply failure. Auth: `ApiKeyAuth` / `ApiKeyQuery` (same as other config routes).
+
+**Invariant**: fields absent from the request keep their live values; secrets (api_key, secret headers) are never modified by a request that doesn't include them.
+
+## Frontend — SettingField (TS metadata)
+
+| field | meaning |
+|-------|---------|
+| `key` | dot-path into config (e.g. `docker_isolation.enabled`) |
+| `label` / `help` | human text |
+| `control` | `toggle` \| `select` \| `number` \| `text` \| `secret` \| `duration` \| `list` \| `multiselect` |
+| `section` | `security` \| `general` \| advanced-subsystem id |
+| `options` | for select/multiselect |
+| `min`/`max`/`step` | for number |
+| `danger` | requires confirm dialog |
+| `restart` | badge "requires restart" |
+| `placeholder`/`mask` | for text/secret |
+
+## Frontend — SaveState (per section)
+
+`{ dirtyKeys: Set<string>, saving: bool, lastResult: ConfigApplyResult | null }`. On save: build a nested partial object from `dirtyKeys` only → `api.patchConfig(partial)` → toast + render `requires_restart`/`changed_fields`; clear dirty.
+
+## Components
+
+- `Settings.vue` — tab shell + load `GET /config` once; routes tabs.
+- `SettingsSection.vue` — renders a list of `SettingField`s for a section + a Save button (`data-test="settings-apply-<section>"`).
+- Control atoms: `SettingToggle`, `SettingSelect`, `SettingNumber`, `SettingText` (secret/show), each emitting changes + carrying `data-test="setting-<control>-<key>"`.
+- `ConfirmDialog.vue` — danger confirm.
+- `RestartBadge.vue` — restart-required marker.
+- Raw JSON tab = existing Monaco editor (unchanged behaviour).
+- `TeamsSection.vue` — rendered only when `config.teams` present.
diff --git a/specs/060-settings-page/plan.md b/specs/060-settings-page/plan.md
new file mode 100644
index 000000000..e541f5cea
--- /dev/null
+++ b/specs/060-settings-page/plan.md
@@ -0,0 +1,71 @@
+# Implementation Plan: UX-Friendly Settings Page
+
+**Branch**: `060-settings-page` | **Date**: 2026-05-29 | **Spec**: [spec.md](./spec.md)
+**Input**: `/specs/060-settings-page/spec.md`
+
+## Summary
+
+Redesign the Web UI Settings page from a single raw Monaco JSON editor into a prioritized, form-based experience: **Security & Access** → **General** → **Advanced** (subsystem accordions) → **Raw JSON** (the existing editor, kept) → **Teams** (server edition only). Add one backend endpoint — `PATCH /api/v1/config` — that deep-merges a partial payload onto the live config and routes through the existing `ApplyConfig` pipeline, so saving a section persists only changed fields and never clobbers masked secrets (api_key, secret headers). Everything else reuses the existing `GET /config` (read, redacted) and `POST /config/apply`/`validate`.
+
+## Technical Context
+
+**Language/Version**: Go 1.24 (backend), TypeScript 5.9 / Vue 3.5 (frontend)
+**Primary Dependencies**: Chi router, Zap, existing `Runtime.ApplyConfig` + `Controller.GetConfig`/`GetConfigPath`; Vue 3, Pinia, Tailwind + DaisyUI, Monaco (existing, for Raw JSON tab)
+**Storage**: None new — config in `mcp_config.json` via existing apply pipeline; no DB/schema change
+**Testing**: `go test ./internal/httpapi/... ./internal/runtime/...`; Chrome-extension browser automation for the Web UI (mandatory)
+**Target Platform**: Core server (personal + server editions); Web UI served at `/ui/`
+**Project Type**: Web (Go backend + Vue frontend)
+**Performance Goals**: N/A (config path, not hot path)
+**Constraints**: Partial save MUST preserve secrets (FR-003); restart-only fields flagged (FR-007); personal edition unaffected by Teams (FR-010)
+**Scale/Scope**: 1 new backend handler + ~1 new frontend api method + Settings.vue redesign into sectioned components
+
+## Constitution Check
+
+- **I. Performance at Scale** — N/A (config UI/endpoint).
+- **II. Actor-Based Concurrency** — PASS. Reuses `ApplyConfig`; no new concurrency.
+- **III. Configuration-Driven Architecture** — PASS / core to this feature. All settings remain in `mcp_config.json`; changes go through the existing validate→persist→hot-reload pipeline; the tray/Web-UI remain pure controllers reading/writing core config via REST. Sensible defaults preserved.
+- **IV. Security by Default** — PASS / reinforces. Partial-update PATCH starts from the **real** in-memory config (secrets intact) and overlays only changed fields, so the redaction-on-read can never round-trip a `***REDACTED***` back to disk. Dangerous toggles gated by confirm dialogs.
+- **V. TDD** — PASS. Backend gets a failing test first (partial merge preserves untouched fields incl. secrets; only changed fields in `ChangedFields`; restart-required reported).
+- **VI. Documentation Hygiene** — PASS. Update `docs/` + swagger (auto-regen); CLAUDE.md note only if room (40k gate).
+
+No violations → Complexity Tracking empty.
+
+## Key technical decisions (see research.md)
+
+- **PATCH semantics**: `GetConfig()` → marshal to map → deep-merge incoming partial map (patch wins, objects merged recursively) → unmarshal to `config.Config` → `ApplyConfig`. Starting from the real config is what preserves secrets and unrelated fields. Modeled on `handlePatchDockerIsolation` (server.go:3685) + the per-server PATCH deep-merge precedent.
+- **Secrets**: never sent by the form unless the user explicitly edits them; the deep-merge means an absent key keeps the live value.
+- **Restart classification**: surfaced from the existing `ConfigApplyResult.RequiresRestart`/`RestartReason`/`ChangedFields`; UI also statically badges the known restart-only fields (listen, data_dir, api_key, tls.*).
+- **Edition gating**: Teams section rendered only when the config payload contains a `teams` object (absent in personal-edition binary).
+
+## Project Structure
+
+```text
+specs/060-settings-page/
+├── plan.md, research.md, data-model.md, quickstart.md, tasks.md
+└── checklists/requirements.md
+
+internal/httpapi/
+├── server.go              # NEW handler handlePatchConfig + route PATCH /api/v1/config; helper deepMergeJSON
+└── server_config_patch_test.go  # NEW: partial-merge preserves secrets + untouched fields (TDD)
+
+oas/                       # regenerated (swagger) for the new endpoint
+
+frontend/src/
+├── services/api.ts        # NEW patchConfig(partial) method
+├── views/Settings.vue     # REDESIGN: tabbed shell (Security/General/Advanced/RawJSON/Teams)
+└── components/settings/    # NEW: SettingsSection, SettingToggle, SettingSelect, SettingNumber,
+                            #      SettingText (masked/secret), ConfirmDialog, RestartBadge,
+                            #      SecuritySection, GeneralSection, AdvancedSection (accordions), TeamsSection
+```
+
+**Structure Decision**: Web app. Backend change is one handler + a small deep-merge helper. Frontend keeps the existing `/settings` route and Monaco editor (as the Raw JSON tab) and adds form sections as child components driven by a field-metadata table (label, help, control, bounds, danger, restart) so controls stay declarative and testable.
+
+## Phases
+
+- **Phase 0 (research.md)**: deep-merge approach + secret-preservation proof; restart-field list; field-metadata catalogue (from the config inventory); Chrome-ext verification approach.
+- **Phase 1 (data-model.md, quickstart.md, contracts/)**: PATCH request/response contract; settings field-metadata model; quickstart to enable + verify.
+- **Phase 2 (tasks.md)**: via /speckit.tasks.
+
+## Complexity Tracking
+
+*No constitution violations — section intentionally empty.*
diff --git a/specs/060-settings-page/quickstart.md b/specs/060-settings-page/quickstart.md
new file mode 100644
index 000000000..3cb42cee5
--- /dev/null
+++ b/specs/060-settings-page/quickstart.md
@@ -0,0 +1,26 @@
+# Quickstart: Settings Page
+
+## Use
+
+Open the Web UI → **Configuration** (sidebar). Tabs:
+- **Security & Access** — API key (masked, show/regenerate), MCP auth, quarantine, Docker isolation, code execution, read-only, sensitive-data detection, reveal secret headers (danger), listen.
+- **General** — routing mode, tool limits, response limit, call timeout, log level, telemetry, prompts.
+- **Advanced** — accordions per subsystem.
+- **Raw JSON** — the full editor (unchanged).
+- **Teams** — server edition only.
+
+Change a field → **Save** (saves only that section's changed fields). A toast confirms; a "restart required" badge appears for `listen` / `data_dir` / `api_key` / `tls.*`.
+
+## API
+
+```bash
+# Partial update — only changed fields; secrets untouched
+curl -X PATCH -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
+  -d '{"quarantine_enabled": false}' \
+  http://127.0.0.1:8080/api/v1/config
+# → {"success":true,"applied_immediately":true,"requires_restart":false,"changed_fields":["quarantine_enabled"],...}
+```
+
+## Verify (mandatory — Chrome extension)
+
+Drive the live Web UI: capture Security/General/Advanced/RawJSON; toggle quarantine and save, re-read to confirm persistence; trigger a danger toggle and confirm the dialog. (QA report produced for review, not committed.)
diff --git a/specs/060-settings-page/research.md b/specs/060-settings-page/research.md
new file mode 100644
index 000000000..ed1de0b3d
--- /dev/null
+++ b/specs/060-settings-page/research.md
@@ -0,0 +1,29 @@
+# Phase 0 Research: Settings Page
+
+## D1 — Partial config update that preserves secrets
+
+**Decision**: New `PATCH /api/v1/config` handler. Steps: `cfg := controller.GetConfig()` (the **real** in-memory config, secrets intact — redaction lives only in `handleGetConfig`'s response path, server.go:1126/3552), marshal `cfg`→`map[string]any`, decode the request body→`map[string]any`, `deepMergeJSON(base, patch)` (patch scalar/array values overwrite; nested objects merge recursively), marshal merged→bytes→`json.Unmarshal` into a fresh `config.Config`, then `controller.ApplyConfig(&merged, controller.GetConfigPath())`. Return the existing `ConfigApplyResult`.
+
+**Rationale**: Starting from the real config and overlaying only the keys the client sent means (a) untouched fields keep their live values, and (b) masked secrets (api_key, secret request headers) are never round-tripped from a redacted read back to disk — the FR-003 / Constitution-IV requirement. Reuses the full validate→persist→hot-reload→restart-detection pipeline; zero duplication. Direct copy of the `handlePatchDockerIsolation` shape, generalised.
+
+**Alternatives**: (a) full-config `POST /apply` from the form — rejected: redacted `GET /config` would persist `***REDACTED***` over the real key. (b) per-field endpoints like docker-isolation for every option — rejected: dozens of one-off handlers; the generic deep-merge is one handler.
+
+**Merge edge cases**: arrays replace wholesale (e.g. `strip_classes`, `admin_emails`) — correct for settings. No key-removal semantics needed (settings only set values). Unknown keys: `json.Unmarshal` into typed `config.Config` ignores them, and `ApplyConfig` validates — so a bad patch fails validation rather than corrupting config.
+
+## D2 — Restart-required fields
+
+**Decision**: Trust the server: surface `ConfigApplyResult.RequiresRestart` + `RestartReason` + `ChangedFields` after each save. Additionally, statically badge the known restart-only set in the UI **before** save so users aren't surprised: `listen`, `data_dir`, `api_key`, `tls.*` (authoritative per `internal/runtime/config_hotreload.go`). Everything else hot-reloads (some need upstream reconnect, noted as "applies on reconnect").
+
+## D3 — Field metadata catalogue
+
+**Decision**: Drive the form from a declarative TS catalogue (one entry per setting: `key` (dot-path), `label`, `help`, `control` (toggle|select|number|text|secret|duration|list|multiselect), `section`, `options`/`min`/`max`, `danger?`, `restart?`). Sourced from the config inventory. This keeps Settings.vue declarative, makes `data-test` ids systematic, and makes "every non-deprecated option reachable" auditable. Hidden keys: `top_k`, `enable_tray`, `features`/`enable_web_ui`, telemetry bookkeeping (`anonymous_id`, …), `mcpServers`, `registries`.
+
+**Security section (FR-002, ordered):** `api_key` (secret), `require_mcp_auth`, `quarantine_enabled`, `docker_isolation.enabled`, `enable_code_execution`, `read_only_mode`, `sensitive_data_detection.enabled`, `reveal_secret_headers` (danger), `listen` (restart). Danger set requiring confirm: `reveal_secret_headers`, `disable_management`, `quarantine_enabled→false`, non-loopback `listen`.
+
+**General:** `routing_mode` (select), `tools_limit` (1–1000), `tool_response_limit`, `call_tool_timeout` (duration), `logging.level` (select), `telemetry.enabled`, `enable_prompts`.
+
+**Advanced accordions:** code execution, docker isolation (detail), sensitive-data detection (scan toggles + categories + custom patterns), output validation, output sanitisation, activity retention, logging (file/rotation), TLS (restart), tokenizer, intent declaration, environment, security scanner, misc root.
+
+## D4 — Verification via Chrome extension
+
+**Decision**: Drive the live Web UI through the Chrome extension MCP tools (navigate, read_page/find for `data-test` selectors, computer for clicks/screenshots): capture Security/General/Advanced/RawJSON, exercise a toggle-save (e.g. quarantine) confirming persistence via re-read, and a danger-confirm flow. If the extension is unavailable at run time, fall back to the documented Playwright sweep. QA artifacts are produced for review but **not committed** (project policy).
diff --git a/specs/060-settings-page/spec.md b/specs/060-settings-page/spec.md
new file mode 100644
index 000000000..64054d9a4
--- /dev/null
+++ b/specs/060-settings-page/spec.md
@@ -0,0 +1,115 @@
+# Feature Specification: UX-Friendly Web UI Settings Page
+
+**Feature Branch**: `060-settings-page`
+**Created**: 2026-05-29
+**Status**: Draft
+**Input**: Make mcpproxy's many config options approachable from the Web UI — a sectioned, form-based settings experience instead of raw JSON.
+
+## Context
+
+mcpproxy has grown a large configuration surface (security toggles, Docker isolation, code execution, quarantine, detection, logging, retention, TLS, teams…). Today the Web UI exposes all of it only as a raw Monaco JSON editor — fine for power users, intimidating for everyone else and easy to break. This feature turns the most important options into a friendly, prioritized, form-based settings page while keeping the raw editor as an escape hatch.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Manage security & access settings without editing JSON (Priority: P1)
+
+As an operator, I want a prominent "Security & Access" section where I can see and change the settings that matter most — API key, MCP auth requirement, quarantine, Docker isolation, code execution, read-only mode, sensitive-data detection, secret-header reveal, and the listen address — using plain toggles and inputs, so I can secure my instance confidently without hand-editing config or risking a typo.
+
+**Why this priority**: These are the highest-impact, highest-risk options; making them safe and obvious is the core value and the MVP.
+
+**Independent Test**: Open Settings → Security & Access. Toggle quarantine off and save; confirm the change persists and the running server reflects it. Toggle a dangerous option (reveal secret headers) and confirm a confirmation prompt appears. Confirm the API key field is masked with show/regenerate, and that saving a security change does NOT wipe the API key or other secrets.
+
+**Acceptance Scenarios**:
+
+1. **Given** the Security section, **When** I toggle `quarantine_enabled` off and save, **Then** only that field is sent, a success toast appears, and a re-open shows the new value (persisted + hot-reloaded).
+2. **Given** a dangerous toggle (reveal secret headers, disable management, non-loopback listen), **When** I change it, **Then** I must confirm in a dialog before it is applied.
+3. **Given** the API key field, **When** I view it, **Then** it is masked with a show toggle and a regenerate action; saving an unrelated security change must not overwrite the stored key/secret headers.
+4. **Given** a restart-only field (api_key, listen, data_dir, TLS), **When** I change it, **Then** the UI clearly flags that a restart is required and the apply response's restart indication is surfaced.
+
+### User Story 2 - Adjust common behaviour in a General section (Priority: P2)
+
+As an operator, I want a "General" section for everyday knobs — routing mode, tool limits, response limit, call timeout, log level, telemetry, prompts — with appropriate controls (selects, numbers, toggles), so I can tune normal behaviour quickly.
+
+**Acceptance Scenarios**:
+
+1. **Given** the General section, **When** I change `routing_mode` via a select and save, **Then** only that field is applied and a success toast appears.
+2. **Given** a numeric field with bounds (e.g. tools limit), **When** I enter an out-of-range value, **Then** the UI prevents saving and explains the valid range.
+
+### User Story 3 - Reach every option via Advanced accordions and the raw editor (Priority: P3)
+
+As a power user, I want the remaining subsystems (code execution, Docker isolation detail, sensitive-data detection categories/patterns, output validation, output sanitisation, activity retention, logging, TLS, tokenizer, intent, environment, scanner) grouped into collapsible "Advanced" accordions, plus a "Raw JSON" tab that preserves the full editor, so nothing becomes unreachable and I can still edit anything directly.
+
+**Acceptance Scenarios**:
+
+1. **Given** the Advanced tab, **When** I expand a subsystem accordion and change a field, **Then** I can save just that subsystem's changes.
+2. **Given** the Raw JSON tab, **When** I edit and apply, **Then** behaviour matches today's editor (validate + apply), and validation errors are shown inline.
+3. **Given** the server (multi-user) edition, **When** Teams config is present, **Then** a Teams section is shown; in the personal edition it is absent.
+
+### Edge Cases
+
+- Saving must never clobber secrets: because the config read masks the API key and secret headers, a save sends only the fields the user changed (partial update), not the whole masked config.
+- Deprecated/internal options (`top_k`, `enable_tray`, `features`/`enable_web_ui`, telemetry bookkeeping) are not shown.
+- Options managed elsewhere (upstream servers, registries) are not duplicated; the page links to those pages instead.
+- A change that requires a restart is applied/persisted but clearly marked as taking effect after restart.
+- Invalid input is caught before save with a clear message; a failed apply surfaces the server's validation errors.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The settings page MUST present configuration in prioritized sections: Security & Access (top), General, Advanced (grouped accordions), Raw JSON (full editor), and Teams (server edition only).
+- **FR-002**: The Security & Access section MUST include, at minimum: API key (masked, show, regenerate), require MCP auth, quarantine enabled, global Docker isolation enabled, code execution enabled, read-only mode, sensitive-data detection enabled, reveal secret headers, and listen address.
+- **FR-003**: Saving a section MUST persist only the fields the user changed (partial update), so masked secrets are never overwritten by a save of unrelated fields.
+- **FR-004**: After a save, the system MUST persist the change, apply it live where possible, and clearly indicate when a restart is required (and which fields).
+- **FR-005**: Changing a dangerous option (reveal secret headers, disabling management, binding to a non-loopback address, disabling quarantine) MUST require explicit confirmation.
+- **FR-006**: Each control MUST use the appropriate input type (toggle, select/enum, number with bounds, text, duration, list) and validate input before allowing save.
+- **FR-007**: Restart-only fields (api_key, listen, data_dir, TLS) MUST be visually flagged as requiring a restart.
+- **FR-008**: Deprecated and internal-only fields MUST be hidden; options owned by other pages (servers, registries) MUST NOT be duplicated and SHOULD be cross-linked.
+- **FR-009**: The Raw JSON editor MUST remain available with validate + apply behaviour equivalent to today's.
+- **FR-010**: The Teams/Server section MUST appear only in the server edition and MUST NOT affect the personal edition.
+- **FR-011**: Save outcomes (success, validation error, restart-required) MUST be communicated via clear feedback (toast + inline messaging).
+- **FR-012**: All interactive controls MUST carry stable test identifiers to support automated UI verification.
+
+### Key Entities
+
+- **Settings section**: a grouped set of related options with its own save action; partial save scope.
+- **Setting field**: one configurable option — key, label, help text, control type, value, validation bounds, danger flag, restart-required flag.
+- **Apply result**: outcome of a save — applied-immediately vs requires-restart, the list of changed fields, and any validation errors.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: An operator can change each of the nine Security & Access settings and the General settings entirely through form controls, with zero JSON editing.
+- **SC-002**: Saving any single setting persists only that field; 100% of the time, unrelated secrets (API key, secret headers) are preserved across the save.
+- **SC-003**: 100% of dangerous changes require an explicit confirmation step before taking effect.
+- **SC-004**: Every non-deprecated, non-duplicated config option is reachable from the page (a friendly control in Security/General/Advanced, or via the Raw JSON tab).
+- **SC-005**: After any save, the UI correctly reports whether the change is live or needs a restart, matching the server's response.
+- **SC-006**: The personal edition shows no Teams section and behaves identically to before for users who never open the new sections.
+- **SC-007**: Each section and key control is verifiable via the Chrome extension (stable test identifiers + captured screenshots).
+
+## Commit Message Conventions *(mandatory)*
+
+### Issue References
+
+Reference this spec (060) in commit bodies.
+
+### Co-Authorship
+
+Per repo policy: no Claude/Co-Authored-By attribution in mcpproxy-go commits.
+
+### Example Commit Message
+
+```
+feat(060): form-based settings page with partial-update PATCH /config
+
+Redesign Settings.vue into Security/General/Advanced/Raw-JSON tabs;
+add PATCH /api/v1/config (partial deep-merge) so saving a section
+preserves masked secrets. Verified via Chrome extension.
+```
+
+## Testing
+
+- Backend: unit/integration tests for the partial-merge config update (only changed fields applied; secrets preserved; restart-required reported).
+- Frontend: the page renders sections, validates inputs, confirms dangerous changes, and saves partial updates.
+- Verification (mandatory): drive the Web UI via the Chrome extension — capture Security, General, Advanced, and Raw JSON sections; exercise a toggle save and a dangerous-toggle confirm. (QA report/screenshots are produced for review but NOT committed, per project policy.)
diff --git a/specs/060-settings-page/tasks.md b/specs/060-settings-page/tasks.md
new file mode 100644
index 000000000..d10081102
--- /dev/null
+++ b/specs/060-settings-page/tasks.md
@@ -0,0 +1,48 @@
+# Tasks: UX-Friendly Settings Page
+
+**Feature**: `060-settings-page` | **Spec**: [spec.md](./spec.md) | **Plan**: [plan.md](./plan.md)
+
+TDD on the backend; frontend verified via Chrome extension.
+
+## Phase 1: Setup
+- [x] T001 Baseline green: `go build ./cmd/mcpproxy`, `cd frontend && npm run build` (or `make build`) pass before changes.
+
+## Phase 2: Backend — partial-update endpoint (blocks frontend save)
+- [x] T002 [P] Failing test `internal/httpapi/server_config_patch_test.go`: PATCH /config with `{"quarantine_enabled":false}` applies only that field; an untouched secret (api_key, secret header) is preserved; nested merge (`{"docker_isolation":{"enabled":true}}`) keeps sibling docker fields; invalid value returns validation error; `changed_fields` reflects the patch.
+- [x] T003 Implement `handlePatchConfig` + `deepMergeJSON` helper in `internal/httpapi/server.go` (GetConfig→map→merge patch→unmarshal→ApplyConfig), modeled on `handlePatchDockerIsolation`. Register route `PATCH /api/v1/config`. Make T002 pass.
+- [x] T004 Regenerate swagger (`make swagger`) for the new endpoint; `./scripts/verify-oas-coverage.sh` green.
+
+## Phase 3: Frontend foundation (US1 enablement)
+- [x] T005 [P] Add `patchConfig(partial)` to `frontend/src/services/api.ts` (PATCH /api/v1/config).
+- [x] T006 [P] Field-metadata catalogue `frontend/src/views/settings/fields.ts` (SettingField[] per data-model: key/label/help/control/section/options/min/max/danger/restart; hidden keys excluded).
+- [x] T007 Control atoms in `frontend/src/components/settings/`: `SettingToggle.vue`, `SettingSelect.vue`, `SettingNumber.vue`, `SettingText.vue` (secret/show), `RestartBadge.vue`, `ConfirmDialog.vue` — each with `data-test` ids. (frontend-design skill.)
+- [x] T008 `SettingsSection.vue` — renders fields for a section + per-section Save (builds nested partial from dirty keys → `patchConfig`), toast + restart/changed-fields feedback, danger-confirm gating.
+
+## Phase 4: US1 — Security & Access (P1, MVP) 🎯
+- [x] T009 [US1] Redesign `frontend/src/views/Settings.vue` into a tab shell (Security/General/Advanced/Raw JSON/Teams), loading `GET /config` once; keep existing Monaco editor as the Raw JSON tab.
+- [x] T010 [US1] `SecuritySection.vue` with the 9 ordered fields; api_key masked + regenerate; danger confirms for reveal_secret_headers / disable_management / quarantine-off / non-loopback listen; restart badges. Save persists only changed fields.
+
+## Phase 5: US2 — General (P2)
+- [x] T011 [US2] `GeneralSection.vue`: routing_mode, tools_limit (1–1000), tool_response_limit, call_tool_timeout, logging.level, telemetry.enabled, enable_prompts; number-bound validation before save.
+
+## Phase 6: US3 — Advanced + Raw JSON + Teams (P3)
+- [x] T012 [US3] `AdvancedSection.vue` with DaisyUI accordions per subsystem (code execution, docker isolation detail, sensitive-data detection incl. categories + custom patterns, output validation, output sanitisation, activity retention, logging, TLS, tokenizer, intent, environment, scanner, misc).
+- [x] T013 [US3] Verify Raw JSON tab retains validate+apply behaviour; `TeamsSection.vue` rendered only when `config.teams` present (personal edition shows no Teams tab).
+
+## Phase 7: Polish & Verify
+- [x] T014 [P] `cd frontend && npm run build` clean (TS6/Vite8); `go test ./internal/httpapi/... ./internal/runtime/... -count=1`; `./scripts/test-api-e2e.sh` green.
+- [x] T015 Docs: `docs/` settings page note; cross-link from config docs. (CLAUDE.md only if under 40k.)
+- [x] T016 **Mandatory verification (Chrome extension)**: drive live Web UI — capture Security/General/Advanced/Raw JSON; toggle quarantine + save + re-read to confirm persistence + secret preserved; danger-confirm flow. Build a local QA report (NOT committed, per policy); end with `open <report>`.
+
+## Dependencies
+- T002–T004 (backend) block T008's save path.
+- T005–T008 foundation block US1/US2/US3.
+- US1 is the MVP; US2/US3 extend the same section framework.
+- T010's tab shell (T009) is shared by all sections — build once.
+
+## Parallel opportunities
+- Backend (T002–T004) ∥ frontend foundation (T005–T007) — different stacks. Dispatch backend to a subagent while building the frontend.
+- T005 ∥ T006 (different files).
+
+## MVP scope
+US1 (T009–T010) + backend PATCH (T002–T003) + foundation (T005–T008): a working, secure Security & Access form with partial saves.

From 2c4074f5ba8971a60a2672fe2f511d6f9ce38a22 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 29 May 2026 14:34:03 +0300
Subject: [PATCH 02/10] =?UTF-8?q?feat(060):=20settings=20page=20UX=20?=
 =?UTF-8?q?=E2=80=94=20cross-section=20search,=20posture=20summary,=20dirt?=
 =?UTF-8?q?y/discard?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Make the settings page genuinely useful for finding and reviewing options:
- Cross-section search box: type to surface matching settings from every
  section (Security/General/Advanced/Teams) in one editable list.
- Security posture summary: at-a-glance colour-coded chips (quarantine, MCP
  auth, Docker isolation, secret scan, code exec, read-only, reveal headers),
  flagging anything that warrants review.
- Per-field dirty highlight (left accent + ● badge) and a per-section Discard
  button to revert unsaved changes.

Relates to Spec 060.
---
 .../src/components/settings/SettingField.vue  |  6 +-
 .../components/settings/SettingsSection.vue   | 40 +++++++---
 frontend/src/views/Settings.vue               | 74 +++++++++++++++++--
 3 files changed, 103 insertions(+), 17 deletions(-)

diff --git a/frontend/src/components/settings/SettingField.vue b/frontend/src/components/settings/SettingField.vue
index 022f39b3c..12d95a813 100644
--- a/frontend/src/components/settings/SettingField.vue
+++ b/frontend/src/components/settings/SettingField.vue
@@ -1,12 +1,14 @@
 <template>
   <div
-    class="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-2 py-3 border-b border-base-200 last:border-0"
+    class="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-2 py-3 px-2 -mx-2 border-b border-base-200 last:border-0 rounded transition-colors"
+    :class="dirty ? 'bg-warning/5 border-l-2 border-l-warning' : 'border-l-2 border-l-transparent'"
     :data-test="`setting-row-${field.key}`"
   >
     <!-- Label + help + badges -->
     <div class="sm:max-w-md">
       <div class="flex items-center gap-2 flex-wrap">
         <span class="font-medium">{{ field.label }}</span>
+        <span v-if="dirty" class="badge badge-warning badge-xs" title="Unsaved change">●</span>
         <span v-if="field.restart" class="badge badge-warning badge-xs gap-1" title="Requires restart">
           restart
         </span>
@@ -110,7 +112,7 @@
 import { ref, computed } from 'vue'
 import type { SettingField } from '@/views/settings/fields'
 
-const props = defineProps<{ field: SettingField; modelValue: any }>()
+const props = defineProps<{ field: SettingField; modelValue: any; dirty?: boolean }>()
 const emit = defineEmits<{ (e: 'update:modelValue', v: any): void }>()
 
 const showSecret = ref(false)
diff --git a/frontend/src/components/settings/SettingsSection.vue b/frontend/src/components/settings/SettingsSection.vue
index 05b6fbce7..00be51136 100644
--- a/frontend/src/components/settings/SettingsSection.vue
+++ b/frontend/src/components/settings/SettingsSection.vue
@@ -5,8 +5,10 @@
       :key="f.key"
       :field="f"
       :model-value="getPath(working, f.key)"
+      :dirty="!!dirty[f.key]"
       @update:model-value="onChange(f, $event)"
     />
+    <p v-if="!fields.length" class="text-sm text-base-content/50 py-4">No settings match your search.</p>
 
     <!-- per-section action bar -->
     <div class="flex items-center justify-between pt-2">
@@ -22,15 +24,26 @@
           {{ dirtyKeys.length }} unsaved change{{ dirtyKeys.length > 1 ? 's' : '' }}
         </span>
       </div>
-      <button
-        class="btn btn-primary btn-sm"
-        :disabled="!dirtyKeys.length || saving || hasInvalid"
-        :data-test="`settings-apply-${sectionId}`"
-        @click="attemptSave"
-      >
-        <span v-if="saving" class="loading loading-spinner loading-xs"></span>
-        Save changes
-      </button>
+      <div class="flex items-center gap-2">
+        <button
+          v-if="dirtyKeys.length"
+          class="btn btn-ghost btn-sm"
+          :disabled="saving"
+          :data-test="`settings-discard-${sectionId}`"
+          @click="discard"
+        >
+          Discard
+        </button>
+        <button
+          class="btn btn-primary btn-sm"
+          :disabled="!dirtyKeys.length || saving || hasInvalid"
+          :data-test="`settings-apply-${sectionId}`"
+          @click="attemptSave"
+        >
+          <span v-if="saving" class="loading loading-spinner loading-xs"></span>
+          Save changes
+        </button>
+      </div>
     </div>
 
     <!-- danger confirm -->
@@ -129,6 +142,15 @@ function dangerMessages(): string[] {
   return msgs
 }
 
+function discard() {
+  for (const key of dirtyKeys.value) {
+    setPath(props.working, key, getPath(props.original, key))
+  }
+  dirty.value = {}
+  lastResult.value = null
+  error.value = ''
+}
+
 function attemptSave() {
   const msgs = dangerMessages()
   if (msgs.length) {
diff --git a/frontend/src/views/Settings.vue b/frontend/src/views/Settings.vue
index 048997ff6..1e049f852 100644
--- a/frontend/src/views/Settings.vue
+++ b/frontend/src/views/Settings.vue
@@ -8,14 +8,29 @@
           Manage mcpproxy settings. Changes save instantly; a badge marks fields that need a restart.
         </p>
       </div>
-      <button class="btn btn-sm btn-outline" :disabled="loading" @click="loadConfig" data-test="settings-reload">
-        <span v-if="loading" class="loading loading-spinner loading-xs"></span>
-        <span v-else>Reload</span>
-      </button>
+      <div class="flex items-center gap-2">
+        <label class="input input-bordered input-sm flex items-center gap-2 w-64">
+          <span class="opacity-50">🔍</span>
+          <input v-model="search" type="text" class="grow" placeholder="Search all settings…" data-test="settings-search" />
+          <button v-if="search" class="opacity-50 hover:opacity-100" @click="search = ''" title="Clear">✕</button>
+        </label>
+        <button class="btn btn-sm btn-outline" :disabled="loading" @click="loadConfig" data-test="settings-reload">
+          <span v-if="loading" class="loading loading-spinner loading-xs"></span>
+          <span v-else>Reload</span>
+        </button>
+      </div>
+    </div>
+
+    <!-- Search results (across all sections) -->
+    <div v-if="loaded && search.trim()" class="card bg-base-100 shadow-md" data-test="settings-search-results">
+      <div class="card-body">
+        <h2 class="card-title text-lg">🔍 Search results <span class="text-sm font-normal text-base-content/60">({{ filteredFields.length }})</span></h2>
+        <SettingsSection section-id="search" :fields="filteredFields" :working="state.working" :original="state.original" />
+      </div>
     </div>
 
     <!-- Tabs -->
-    <div role="tablist" class="tabs tabs-bordered" data-test="settings-tabs">
+    <div v-show="!search.trim()" role="tablist" class="tabs tabs-bordered" data-test="settings-tabs">
       <button
         v-for="t in tabs"
         :key="t.id"
@@ -33,12 +48,24 @@
       <span>{{ loadError }}</span>
     </div>
 
-    <template v-else-if="loaded">
+    <template v-else-if="loaded && !search.trim()">
       <!-- Security & Access -->
       <div v-show="activeTab === 'security'" class="card bg-base-100 shadow-md">
         <div class="card-body">
           <h2 class="card-title text-lg">🔒 Security &amp; Access</h2>
           <p class="text-sm text-base-content/60 mb-2">The settings that most affect how exposed and protected your instance is.</p>
+          <!-- posture summary -->
+          <div class="flex flex-wrap gap-2 mb-4" data-test="settings-posture">
+            <span
+              v-for="p in posture"
+              :key="p.label"
+              class="badge gap-1"
+              :class="p.good ? 'badge-success badge-outline' : 'badge-warning'"
+              :title="p.good ? 'OK' : 'Review this'"
+            >
+              {{ p.label }}: {{ p.on ? 'on' : 'off' }}
+            </span>
+          </div>
           <SettingsSection section-id="security" :fields="securityFields" :working="state.working" :original="state.original" />
         </div>
       </div>
@@ -154,6 +181,41 @@ const activeTab = ref<string>('security')
 const state = reactive<{ working: any; original: any }>({ working: {}, original: {} })
 const hasTeams = computed(() => state.working && state.working.teams != null)
 
+// cross-section search: type to find any setting across all tabs
+const search = ref('')
+const allFields = computed<SettingField[]>(() => [
+  ...securityFields,
+  ...generalFields,
+  ...advancedAccordions.flatMap((a) => a.fields),
+  ...(hasTeams.value ? teamsFields : []),
+])
+const filteredFields = computed<SettingField[]>(() => {
+  const q = search.value.trim().toLowerCase()
+  if (!q) return []
+  return allFields.value.filter(
+    (f) =>
+      f.label.toLowerCase().includes(q) ||
+      f.key.toLowerCase().includes(q) ||
+      (f.help?.toLowerCase().includes(q) ?? false)
+  )
+})
+
+// at-a-glance security posture (computed from the working config)
+const posture = computed(() => {
+  const w: any = state.working || {}
+  const sdd = w.sensitive_data_detection?.enabled !== false
+  const quarantine = w.quarantine_enabled !== false // default-on
+  return [
+    { label: 'Quarantine', on: quarantine, good: quarantine },
+    { label: 'MCP auth', on: !!w.require_mcp_auth, good: !!w.require_mcp_auth },
+    { label: 'Docker isolation', on: !!(w.docker_isolation && w.docker_isolation.enabled), good: !!(w.docker_isolation && w.docker_isolation.enabled) },
+    { label: 'Secret scan', on: sdd, good: sdd },
+    { label: 'Code exec', on: !!w.enable_code_execution, good: !w.enable_code_execution },
+    { label: 'Read-only', on: !!w.read_only_mode, good: true },
+    { label: 'Reveal headers', on: !!w.reveal_secret_headers, good: !w.reveal_secret_headers },
+  ]
+})
+
 const tabs = computed(() => {
   const base = [
     { id: 'security', label: 'Security & Access', icon: '🔒' },

From 25693e06697e08c191e61940d8dc3a3571f217fd Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 29 May 2026 14:58:59 +0300
Subject: [PATCH 03/10] feat(060): clearer setting labels + Connect-a-client
 helper + committed verification spec
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rewrote every setting's label and help text from the user's point of view:
  explain what each option does, how to use it, and the consequence (e.g.
  "Require API key for MCP clients" now explains clients send it as a Bearer
  token and points to the connect helper).
- Added a "Connect a client" helper to the Security section that opens the
  shared ConnectModal, so users can register mcpproxy in their AI client's
  config right where they configure auth.
- Committed the reproducible Playwright verification spec + config under
  specs/060/verification (spec only — screenshots/report stay local per policy).

Relates to Spec 060.
---
 frontend/src/views/Settings.vue               |  14 ++
 frontend/src/views/settings/fields.ts         | 146 +++++++++---------
 .../verification/playwright.config.ts         |  20 +++
 .../verification/settings.spec.ts             |  74 +++++++++
 4 files changed, 184 insertions(+), 70 deletions(-)
 create mode 100644 specs/060-settings-page/verification/playwright.config.ts
 create mode 100644 specs/060-settings-page/verification/settings.spec.ts

diff --git a/frontend/src/views/Settings.vue b/frontend/src/views/Settings.vue
index 1e049f852..80b7a8a47 100644
--- a/frontend/src/views/Settings.vue
+++ b/frontend/src/views/Settings.vue
@@ -54,6 +54,15 @@
         <div class="card-body">
           <h2 class="card-title text-lg">🔒 Security &amp; Access</h2>
           <p class="text-sm text-base-content/60 mb-2">The settings that most affect how exposed and protected your instance is.</p>
+          <!-- connect-a-client helper -->
+          <div class="alert bg-base-200 border-base-300 mb-3 flex-col sm:flex-row items-start sm:items-center gap-2">
+            <span class="text-sm grow">
+              🔌 Connecting an AI client (Claude, Cursor, VS Code…)? The helper registers mcpproxy with the right endpoint and API key in the client's config.
+            </span>
+            <button class="btn btn-sm btn-primary" data-test="settings-connect-client" @click="showConnect = true">
+              Connect a client
+            </button>
+          </div>
           <!-- posture summary -->
           <div class="flex flex-wrap gap-2 mb-4" data-test="settings-posture">
             <span
@@ -141,6 +150,9 @@
     </template>
 
     <CollapsibleHintsPanel :hints="settingsHints" />
+
+    <!-- Connect-a-client helper (shared with Dashboard) -->
+    <ConnectModal :show="showConnect" @close="showConnect = false" />
   </div>
 </template>
 
@@ -152,6 +164,7 @@ import { useServersStore } from '@/stores/servers'
 import { useSystemStore } from '@/stores/system'
 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 {
   SECURITY_FIELDS,
@@ -178,6 +191,7 @@ const loading = ref(false)
 const loaded = ref(false)
 const loadError = ref('')
 const activeTab = ref<string>('security')
+const showConnect = ref(false)
 const state = reactive<{ working: any; original: any }>({ working: {}, original: {} })
 const hasTeams = computed(() => state.working && state.working.teams != null)
 
diff --git a/frontend/src/views/settings/fields.ts b/frontend/src/views/settings/fields.ts
index 4e5e879cc..149c0d1cc 100644
--- a/frontend/src/views/settings/fields.ts
+++ b/frontend/src/views/settings/fields.ts
@@ -51,73 +51,73 @@ export const SECURITY_FIELDS: SettingField[] = [
   {
     key: 'api_key',
     label: 'API key',
-    help: 'Secret for REST API authentication. Leave blank to keep the current key.',
+    help: 'Secret that authenticates clients to the REST API and Web UI (sent as the "X-API-Key" header or "?apikey=" in the URL). Leave blank to keep the current key; ↻ generates a new one. Changing it requires a restart and re-connecting clients.',
     control: 'secret',
     restart: true,
-    placeholder: '•••••••• (unchanged)',
+    placeholder: '•••••••• (unchanged — type to replace)',
   },
   {
     key: 'require_mcp_auth',
-    label: 'Require auth on /mcp',
-    help: 'Reject unauthenticated requests to the MCP endpoint.',
+    label: 'Require API key for MCP clients',
+    help: 'When on, AI clients connecting to the /mcp endpoint must send the API key above (as an "Authorization: Bearer <key>" header). Use “Connect a client” to configure this automatically. When off, any local client can connect without a key.',
     control: 'toggle',
   },
   {
     key: 'quarantine_enabled',
-    label: 'Security quarantine',
-    help: 'Auto-quarantine new servers and require approval for changed tools (Tool Poisoning protection).',
+    label: 'Quarantine new servers & changed tools',
+    help: 'Holds newly added servers and tools whose description/schema changed for your approval before agents can call them — protects against Tool Poisoning Attacks. Recommended ON.',
     control: 'toggle',
     danger: {
       confirmValue: false,
       message:
-        'Disabling quarantine removes Tool Poisoning Attack protection — new servers and changed tools will run without approval. Continue?',
+        'Disabling quarantine removes Tool Poisoning Attack protection — new servers and changed tools will run without your approval. Continue?',
     },
   },
   {
     key: 'docker_isolation.enabled',
-    label: 'Global Docker isolation',
-    help: 'Run stdio MCP servers inside Docker containers by default.',
+    label: 'Run stdio servers in Docker',
+    help: 'Runs command-based (stdio) MCP servers inside isolated Docker containers instead of directly on your machine. Requires Docker to be installed and running.',
     control: 'toggle',
   },
   {
     key: 'enable_code_execution',
-    label: 'Code execution tool',
-    help: 'Expose the sandboxed JavaScript code_execution tool.',
+    label: 'Enable code execution tool',
+    help: 'Adds a sandboxed JavaScript tool agents can use to orchestrate several tool calls in one request. Off by default.',
     control: 'toggle',
   },
   {
     key: 'read_only_mode',
     label: 'Read-only mode',
-    help: 'Block all write and destructive tool calls.',
+    help: 'Blocks every write and destructive tool call across all servers — agents can only read. Useful for safe exploration.',
     control: 'toggle',
   },
   {
     key: 'sensitive_data_detection.enabled',
-    label: 'Sensitive-data detection',
-    help: 'Scan tool calls and responses for secrets and credentials.',
+    label: 'Scan for secrets in tool traffic',
+    help: 'Inspects tool arguments and responses for credentials (API keys, tokens, private keys, …) and flags them in the Activity log.',
     control: 'toggle',
   },
   {
     key: 'reveal_secret_headers',
-    label: 'Reveal secret headers',
-    help: 'Stop redacting Authorization / API-Key headers in responses and logs.',
+    label: 'Show secret headers (debug)',
+    help: 'Normally mcpproxy redacts Authorization / API-Key header values in responses and logs. Turning this on shows them in clear text — debugging only.',
     control: 'toggle',
     danger: {
       confirmValue: true,
       message:
-        'Revealing secret headers will expose credentials in tool responses, logs and the activity view. Only enable for debugging. Continue?',
+        'Revealing secret headers will expose credentials in tool responses, logs and the Activity view. Only enable temporarily for debugging. Continue?',
     },
   },
   {
     key: 'listen',
     label: 'Listen address',
-    help: 'Network bind address. Keep 127.0.0.1 unless you intend remote access.',
+    help: 'Where the server accepts connections. Keep 127.0.0.1:8080 for local-only use. To reach mcpproxy from other machines use 0.0.0.0:8080 — turn on “Require API key for MCP clients” first. Takes effect after restart.',
     control: 'text',
     restart: true,
     placeholder: '127.0.0.1:8080',
     danger: {
       message:
-        'Binding to a non-loopback address exposes mcpproxy on your network. Make sure authentication is enabled. Continue?',
+        'Binding to a non-loopback address (e.g. 0.0.0.0) exposes mcpproxy to your network. Make sure “Require API key for MCP clients” is enabled. Continue?',
     },
   },
 ]
@@ -126,26 +126,27 @@ export const SECURITY_FIELDS: SettingField[] = [
 export const GENERAL_FIELDS: SettingField[] = [
   {
     key: 'routing_mode',
-    label: 'Routing mode',
-    help: 'How upstream tools are exposed to agents.',
+    label: 'How agents find tools',
+    help: 'Retrieve = agents search for tools first (best when you have many servers); Direct = every tool is listed to the agent; Code execution = agents call tools from JavaScript.',
     control: 'select',
     options: [
-      { value: 'retrieve_tools', label: 'Retrieve tools (BM25 discovery)' },
-      { value: 'direct', label: 'Direct (all tools listed)' },
+      { value: 'retrieve_tools', label: 'Retrieve — search tools first (recommended)' },
+      { value: 'direct', label: 'Direct — list all tools' },
       { value: 'code_execution', label: 'Code execution' },
     ],
   },
-  { key: 'tools_limit', label: 'Tools per search', help: 'Max tools returned by retrieve_tools.', control: 'number', min: 1, max: 1000 },
-  { key: 'tool_response_limit', label: 'Tool response limit (chars)', help: '0 disables truncation.', control: 'number', min: 0 },
-  { key: 'call_tool_timeout', label: 'Tool call timeout', help: 'e.g. 2m, 90s.', control: 'duration', placeholder: '2m' },
+  { key: 'tools_limit', label: 'Search results limit', help: 'How many tools a single tool-search returns to the agent.', control: 'number', min: 1, max: 1000 },
+  { key: 'tool_response_limit', label: 'Max tool response size (characters)', help: 'Responses larger than this are truncated and cached so the agent can page through them. 0 = never truncate.', control: 'number', min: 0 },
+  { key: 'call_tool_timeout', label: 'Tool call timeout', help: 'How long to wait for a single tool call before giving up. e.g. 2m, 90s, 30s.', control: 'duration', placeholder: '2m' },
   {
     key: 'logging.level',
-    label: 'Log level',
+    label: 'Log verbosity',
+    help: 'How much detail mcpproxy writes to its logs. Use debug/trace when troubleshooting.',
     control: 'select',
     options: ['trace', 'debug', 'info', 'warn', 'error'].map((v) => ({ value: v, label: v })),
   },
-  { key: 'telemetry.enabled', label: 'Anonymous telemetry', help: 'Opt-out anonymous usage metrics.', control: 'toggle' },
-  { key: 'enable_prompts', label: 'Expose MCP prompts', control: 'toggle' },
+  { key: 'telemetry.enabled', label: 'Anonymous usage telemetry', help: 'Sends anonymous usage counts (never tool arguments, content, or identities). Opt-out at any time.', control: 'toggle' },
+  { key: 'enable_prompts', label: 'Expose MCP prompts to clients', help: 'Advertise prompt templates from your upstream servers to connected AI clients.', control: 'toggle' },
 ]
 
 // ---- Section 3: Advanced (subsystem accordions) ----
@@ -153,94 +154,99 @@ export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
   {
     id: 'code-execution',
     title: 'Code execution',
+    description: 'Limits for the sandboxed JavaScript tool (enable it in Security & Access).',
     fields: [
-      { key: 'code_execution_timeout_ms', label: 'Timeout (ms)', control: 'number', min: 1, max: 600000 },
-      { key: 'code_execution_max_tool_calls', label: 'Max tool calls (0 = unlimited)', control: 'number', min: 0 },
-      { key: 'code_execution_pool_size', label: 'Runtime pool size', control: 'number', min: 1, max: 100 },
+      { key: 'code_execution_timeout_ms', label: 'Max run time per execution (ms)', control: 'number', min: 1, max: 600000 },
+      { key: 'code_execution_max_tool_calls', label: 'Max tool calls per execution', help: '0 = unlimited.', control: 'number', min: 0 },
+      { key: 'code_execution_pool_size', label: 'JavaScript runtime pool size', help: 'How many sandboxes run concurrently.', control: 'number', min: 1, max: 100 },
     ],
   },
   {
     id: 'docker-isolation',
     title: 'Docker isolation',
-    description: 'Per-image and resource detail. Image map / extra args are editable in the Raw JSON tab.',
+    description: 'Defaults for containerised stdio servers (turn isolation on in Security & Access). The per-runtime image map and extra docker args are edited in the Raw JSON tab.',
     fields: [
-      { key: 'docker_isolation.network_mode', label: 'Network mode', control: 'select', options: ['bridge', 'none', 'host'].map((v) => ({ value: v, label: v })) },
-      { key: 'docker_isolation.memory_limit', label: 'Memory limit', control: 'text', placeholder: '512m' },
-      { key: 'docker_isolation.cpu_limit', label: 'CPU limit', control: 'text', placeholder: '1.0' },
-      { key: 'docker_isolation.registry', label: 'Registry', control: 'text', placeholder: 'docker.io' },
-      { key: 'docker_isolation.enable_cache_volume', label: 'Cache volume', control: 'toggle' },
+      { key: 'docker_isolation.network_mode', label: 'Container network', help: 'none = no network (most secure), bridge = NAT, host = share host network.', control: 'select', options: ['bridge', 'none', 'host'].map((v) => ({ value: v, label: v })) },
+      { key: 'docker_isolation.memory_limit', label: 'Memory limit per container', control: 'text', placeholder: '512m' },
+      { key: 'docker_isolation.cpu_limit', label: 'CPU limit per container', control: 'text', placeholder: '1.0' },
+      { key: 'docker_isolation.registry', label: 'Container image registry', control: 'text', placeholder: 'docker.io' },
+      { key: 'docker_isolation.enable_cache_volume', label: 'Share a package cache volume', help: 'Speeds up repeated npm/uvx installs by caching across containers.', control: 'toggle' },
     ],
   },
   {
     id: 'sensitive-data',
-    title: 'Sensitive-data detection',
-    description: 'Per-category toggles and custom patterns are editable in the Raw JSON tab.',
+    title: 'Secret detection',
+    description: 'Tuning for the secret scanner (turn it on in Security & Access). Per-category toggles and custom patterns are edited in the Raw JSON tab.',
     fields: [
       { key: 'sensitive_data_detection.scan_requests', label: 'Scan tool arguments', control: 'toggle' },
       { key: 'sensitive_data_detection.scan_responses', label: 'Scan tool responses', control: 'toggle' },
-      { key: 'sensitive_data_detection.max_payload_size_kb', label: 'Max scan size (KB)', control: 'number', min: 1 },
-      { key: 'sensitive_data_detection.entropy_threshold', label: 'Entropy threshold', control: 'number', min: 0, max: 8, step: 0.1 },
+      { key: 'sensitive_data_detection.max_payload_size_kb', label: 'Max payload scanned (KB)', help: 'Larger payloads are scanned only up to this size.', control: 'number', min: 1 },
+      { key: 'sensitive_data_detection.entropy_threshold', label: 'Randomness threshold', help: 'Higher = fewer false positives when flagging random-looking strings (default 4.5).', control: 'number', min: 0, max: 8, step: 0.1 },
     ],
   },
   {
     id: 'output-validation',
-    title: 'Output-schema validation (Track A)',
+    title: 'Output-schema validation',
+    description: 'Checks a tool’s structured response against its declared schema before it reaches the agent (Spec 054 Track A).',
     fields: [
-      { key: 'output_validation.mode', label: 'Mode', control: 'select', options: ['off', 'warn', 'strict'].map((v) => ({ value: v, label: v })) },
-      { key: 'output_validation.missing_structured_content', label: 'Missing structured content', control: 'select', options: ['allow', 'block'].map((v) => ({ value: v, label: v })) },
+      { key: 'output_validation.mode', label: 'Validation mode', help: 'off = no checks; warn = log mismatches; strict = block non-conforming responses.', control: 'select', options: ['off', 'warn', 'strict'].map((v) => ({ value: v, label: v })) },
+      { key: 'output_validation.missing_structured_content', label: 'When structured content is missing', help: 'Whether to allow or block a response that declares a schema but returns none.', control: 'select', options: ['allow', 'block'].map((v) => ({ value: v, label: v })) },
     ],
   },
   {
     id: 'output-sanitisation',
-    title: 'Output sanitisation (Track B)',
+    title: 'Output sanitisation',
+    description: 'Contains untrusted tool output before it reaches the agent (Spec 054 Track B). All opt-in.',
     fields: [
-      { key: 'output_sanitisation.spotlight_untrusted', label: 'Spotlight untrusted output', control: 'toggle' },
-      { key: 'output_sanitisation.response_action', label: 'Response action', control: 'select', options: ['spotlight', 'redact', 'block'].map((v) => ({ value: v, label: v })) },
-      { key: 'output_sanitisation.strip_control_chars', label: 'Strip control sequences', control: 'toggle' },
-      { key: 'output_sanitisation.strip_classes', label: 'Strip classes', control: 'multiselect', options: ['ansi', 'c0c1', 'bidi', 'zero_width'].map((v) => ({ value: v, label: v })) },
-      { key: 'output_sanitisation.max_redactions', label: 'Max redactions / response', control: 'number', min: 0 },
+      { key: 'output_sanitisation.spotlight_untrusted', label: 'Wrap untrusted output in markers', help: 'Surrounds output from open-world tools with «untrusted» delimiters so the agent can tell data from instructions.', control: 'toggle' },
+      { key: 'output_sanitisation.response_action', label: 'On detected secrets', help: 'spotlight = only wrap; redact = mask secrets; block = drop the whole response on a critical detection.', control: 'select', options: ['spotlight', 'redact', 'block'].map((v) => ({ value: v, label: v })) },
+      { key: 'output_sanitisation.strip_control_chars', label: 'Strip control characters', help: 'Remove ANSI/zero-width/bidi sequences that can hide instructions in untrusted text.', control: 'toggle' },
+      { key: 'output_sanitisation.strip_classes', label: 'Which characters to strip', control: 'multiselect', options: ['ansi', 'c0c1', 'bidi', 'zero_width'].map((v) => ({ value: v, label: v })) },
+      { key: 'output_sanitisation.max_redactions', label: 'Max redactions per response', control: 'number', min: 0 },
     ],
   },
   {
     id: 'activity',
     title: 'Activity log retention',
+    description: 'How long the audit log of tool calls is kept.',
     fields: [
-      { key: 'activity_retention_days', label: 'Retention (days)', control: 'number', min: 0 },
-      { key: 'activity_max_records', label: 'Max records', control: 'number', min: 0 },
-      { key: 'activity_cleanup_interval_min', label: 'Cleanup interval (min)', control: 'number', min: 1 },
+      { key: 'activity_retention_days', label: 'Keep records for (days)', help: '0 = keep until the record cap is hit.', control: 'number', min: 0 },
+      { key: 'activity_max_records', label: 'Maximum records kept', control: 'number', min: 0 },
+      { key: 'activity_cleanup_interval_min', label: 'Cleanup runs every (minutes)', control: 'number', min: 1 },
     ],
   },
   {
     id: 'logging',
     title: 'Logging',
     fields: [
-      { key: 'logging.enable_file', label: 'Log to file', control: 'toggle' },
-      { key: 'logging.enable_console', label: 'Log to console', control: 'toggle' },
-      { key: 'logging.json_format', label: 'JSON format', control: 'toggle' },
-      { key: 'logging.max_size', label: 'Max size (MB)', control: 'number', min: 1 },
-      { key: 'logging.max_backups', label: 'Max backups', control: 'number', min: 0 },
-      { key: 'logging.max_age', label: 'Max age (days)', control: 'number', min: 0 },
+      { key: 'logging.enable_file', label: 'Write logs to a file', control: 'toggle' },
+      { key: 'logging.enable_console', label: 'Write logs to the console', control: 'toggle' },
+      { key: 'logging.json_format', label: 'Structured (JSON) log format', control: 'toggle' },
+      { key: 'logging.max_size', label: 'Rotate log after (MB)', control: 'number', min: 1 },
+      { key: 'logging.max_backups', label: 'Rotated files to keep', control: 'number', min: 0 },
+      { key: 'logging.max_age', label: 'Delete rotated logs after (days)', control: 'number', min: 0 },
     ],
   },
   {
     id: 'tls',
     title: 'TLS / HTTPS',
+    description: 'Serve the API and Web UI over HTTPS. Changes take effect after a restart.',
     fields: [
-      { key: 'tls.enabled', label: 'Enable HTTPS', control: 'toggle', restart: true },
-      { key: 'tls.require_client_cert', label: 'Require client cert (mTLS)', control: 'toggle', restart: true },
-      { key: 'tls.hsts', label: 'HSTS header', control: 'toggle', restart: true },
+      { key: 'tls.enabled', label: 'Serve over HTTPS', control: 'toggle', restart: true },
+      { key: 'tls.require_client_cert', label: 'Require client certificate (mTLS)', control: 'toggle', restart: true },
+      { key: 'tls.hsts', label: 'Send HSTS header', help: 'Tells browsers to always use HTTPS for this host.', control: 'toggle', restart: true },
     ],
   },
   {
     id: 'misc',
-    title: 'Miscellaneous',
+    title: 'Other',
     fields: [
-      { key: 'max_result_size_chars', label: 'Max inline response (chars, 0 = off)', control: 'number', min: 0 },
-      { key: 'oauth_expiry_warning_hours', label: 'OAuth expiry warning (hours)', control: 'number', min: 0, step: 0.5 },
-      { key: 'disable_management', label: 'Disable management tool', control: 'toggle', danger: { confirmValue: true, message: 'Disabling the management tool prevents agents from adding/removing servers. Continue?' } },
-      { key: 'allow_server_add', label: 'Allow agents to add servers', control: 'toggle' },
-      { key: 'allow_server_remove', label: 'Allow agents to remove servers', control: 'toggle' },
-      { key: 'debug_search', label: 'Debug BM25 search', control: 'toggle' },
+      { key: 'max_result_size_chars', label: 'Max inline response to the client (characters)', help: 'Hard ceiling on a single response sent inline. 0 = no ceiling.', control: 'number', min: 0 },
+      { key: 'oauth_expiry_warning_hours', label: 'Warn before OAuth token expires (hours)', help: 'How early a server is shown as “degraded” before its OAuth token expires.', control: 'number', min: 0, step: 0.5 },
+      { key: 'disable_management', label: 'Block agents from managing servers', help: 'Prevents agents from using the upstream_servers management tool.', control: 'toggle', danger: { confirmValue: true, message: 'This prevents agents from adding or removing servers via the management tool. Continue?' } },
+      { key: 'allow_server_add', label: 'Let agents add servers', control: 'toggle' },
+      { key: 'allow_server_remove', label: 'Let agents remove servers', control: 'toggle' },
+      { key: 'debug_search', label: 'Verbose tool-search debugging', control: 'toggle' },
     ],
   },
 ]
diff --git a/specs/060-settings-page/verification/playwright.config.ts b/specs/060-settings-page/verification/playwright.config.ts
new file mode 100644
index 000000000..b366638a6
--- /dev/null
+++ b/specs/060-settings-page/verification/playwright.config.ts
@@ -0,0 +1,20 @@
+import { defineConfig } from '@playwright/test'
+
+// Reuse the project's installed Chromium 1217 (e2e/playwright/node_modules).
+// Symlink node_modules here, or run from a dir that has @playwright/test.
+export default defineConfig({
+  testDir: '.',
+  timeout: 40000,
+  fullyParallel: false,
+  workers: 1,
+  retries: 0,
+  use: {
+    headless: true,
+    viewport: { width: 1440, height: 900 },
+    launchOptions: {
+      executablePath:
+        process.env.PW_CHROMIUM ||
+        '/Users/user/Library/Caches/ms-playwright/chromium-1217/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+    },
+  },
+})
diff --git a/specs/060-settings-page/verification/settings.spec.ts b/specs/060-settings-page/verification/settings.spec.ts
new file mode 100644
index 000000000..96a9f51b3
--- /dev/null
+++ b/specs/060-settings-page/verification/settings.spec.ts
@@ -0,0 +1,74 @@
+// Reproducible Web-UI verification for the Spec 060 Settings page.
+//
+// Setup (throwaway instance):
+//   rm -rf /tmp/settings-uitest && mkdir -p /tmp/settings-uitest
+//   cat > /tmp/settings-uitest/config.json <<'EOF'
+//   { "listen":"127.0.0.1:18099","data_dir":"/tmp/settings-uitest","api_key":"settingskey",
+//     "enable_socket":false,"telemetry":{"enabled":false},"mcpServers":[] }
+//   EOF
+//   ./mcpproxy serve --config=/tmp/settings-uitest/config.json --log-level=warn &
+//
+// Run:  BASE_URL=http://127.0.0.1:18099 API_KEY=settingskey \
+//         ./node_modules/.bin/playwright test settings.spec.ts
+//
+// Screenshots are written only when SHOT_DIR is set (kept out of the repo).
+import { test, expect } from '@playwright/test'
+
+const BASE = process.env.BASE_URL || 'http://127.0.0.1:18099'
+const KEY = process.env.API_KEY || 'settingskey'
+const SHOT = process.env.SHOT_DIR // optional; unset in CI
+
+async function shot(page: any, name: string) {
+  if (SHOT) await page.screenshot({ path: `${SHOT}/${name}.png`, fullPage: true })
+}
+
+test('settings page: sections, search, posture, partial save, danger confirm', async ({ page }) => {
+  await page.goto(`${BASE}/ui/settings?apikey=${KEY}`)
+  await page.waitForLoadState('domcontentloaded')
+  await page.waitForSelector('[data-test="settings-tabs"]')
+
+  // Security tab renders with the at-a-glance posture summary + connect helper.
+  await expect(page.locator('[data-test="settings-posture"]')).toBeVisible()
+  await expect(page.locator('[data-test="setting-secret-api_key"]')).toBeVisible()
+  await expect(page.locator('[data-test="settings-connect-client"]')).toBeVisible()
+  await shot(page, 's01-security')
+
+  // Cross-section search surfaces matching fields from any section.
+  await page.locator('[data-test="settings-search"]').fill('docker')
+  await expect(page.locator('[data-test="settings-search-results"]')).toBeVisible()
+  await shot(page, 's00-search')
+  await page.locator('[data-test="settings-search"]').fill('')
+
+  // Partial save: flip a non-dangerous toggle and confirm the saved indicator.
+  await page.locator('[data-test="setting-toggle-require_mcp_auth"]').click()
+  await page.locator('[data-test="settings-apply-security"]').click()
+  await page.waitForSelector(
+    '[data-test="settings-saved-security"], [data-test="settings-restart-security"]',
+    { timeout: 8000 }
+  )
+  await shot(page, 's02-security-saved')
+
+  // Dangerous toggle requires explicit confirmation.
+  await page.locator('[data-test="setting-toggle-reveal_secret_headers"]').click()
+  await page.locator('[data-test="settings-apply-security"]').click()
+  const dialogOpen = await page.evaluate(() => {
+    const d = document.querySelector('[data-test="settings-confirm-security"]') as HTMLDialogElement | null
+    return !!d && d.open
+  })
+  expect(dialogOpen).toBeTruthy()
+  await shot(page, 's03-danger-confirm')
+  await page.locator('[data-test="settings-confirm-security"] [data-test="settings-confirm-cancel"]').click()
+
+  // Other tabs render.
+  await page.locator('[data-test="settings-tab-general"]').click()
+  await expect(page.locator('[data-test="setting-select-routing_mode"]')).toBeVisible()
+  await page.locator('[data-test="settings-tab-advanced"]').click()
+  await expect(page.locator('[data-test="settings-accordion-output-sanitisation"]')).toBeVisible()
+  await page.locator('[data-test="settings-tab-raw"]').click()
+
+  // Connect-a-client helper opens the shared ConnectModal (done last so the
+  // modal doesn't overlay earlier interactions).
+  await page.locator('[data-test="settings-tab-security"]').click()
+  await page.locator('[data-test="settings-connect-client"]').click()
+  await expect(page.getByText('Connect MCPProxy to AI Agents')).toBeVisible()
+})

From 8de63dc8c166458d5e61baf72cc7391fd513e5f9 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 29 May 2026 17:23:57 +0300
Subject: [PATCH 04/10] fix(060): guard setPath against prototype pollution
 (CodeQL)

setPath walked dot-path keys and assigned recursively without rejecting
__proto__/prototype/constructor. Settings keys come from the static
catalogue, but guard the generic helper so a crafted path can never
pollute Object.prototype. Resolves CodeQL js/prototype-polluting-assignment.

Relates to Spec 060.
---
 frontend/src/views/settings/fields.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/frontend/src/views/settings/fields.ts b/frontend/src/views/settings/fields.ts
index 149c0d1cc..3081ad78d 100644
--- a/frontend/src/views/settings/fields.ts
+++ b/frontend/src/views/settings/fields.ts
@@ -252,12 +252,19 @@ export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
 ]
 
 // ---- path helpers ----
+// Keys that would mutate the prototype chain. setPath refuses to traverse or
+// assign these so a crafted dot-path can never pollute Object.prototype
+// (CodeQL js/prototype-polluting-assignment). Settings keys come from the
+// static catalogue above, but we guard the generic helper regardless.
+const UNSAFE_KEYS = new Set(['__proto__', 'prototype', 'constructor'])
+
 export function getPath(obj: any, path: string): any {
   return path.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj)
 }
 
 export function setPath(obj: any, path: string, value: any): void {
   const keys = path.split('.')
+  if (keys.some((k) => UNSAFE_KEYS.has(k))) return // guard against prototype pollution
   let cur = obj
   for (let i = 0; i < keys.length - 1; i++) {
     if (cur[keys[i]] == null || typeof cur[keys[i]] !== 'object') cur[keys[i]] = {}

From 75baf46b329753b96d6aeb493e057015e6def327 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 29 May 2026 17:31:42 +0300
Subject: [PATCH 05/10] feat(060): link settings to docs.mcpproxy.app where it
 helps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add an optional `docs` path to settings fields/accordions and render links:
- per-field "docs ↗" on the options with a dedicated doc page (quarantine,
  Docker isolation, code execution, secret detection, routing mode, telemetry),
- "Learn more ↗" on each Advanced subsystem accordion (incl. output
  validation/sanitisation, activity log),
- "Full configuration reference ↗" in the page header.

All target URLs verified to return 200 on docs.mcpproxy.app (served at root via
the Docusaurus site). Verification spec asserts the field + reference links.

Relates to Spec 060.
---
 .../src/components/settings/SettingField.vue  | 13 ++++++++++-
 frontend/src/views/Settings.vue               | 21 ++++++++++++++++-
 frontend/src/views/settings/fields.ts         | 23 ++++++++++++++++++-
 .../verification/settings.spec.ts             |  3 +++
 4 files changed, 57 insertions(+), 3 deletions(-)

diff --git a/frontend/src/components/settings/SettingField.vue b/frontend/src/components/settings/SettingField.vue
index 12d95a813..91791dc44 100644
--- a/frontend/src/components/settings/SettingField.vue
+++ b/frontend/src/components/settings/SettingField.vue
@@ -9,6 +9,16 @@
       <div class="flex items-center gap-2 flex-wrap">
         <span class="font-medium">{{ field.label }}</span>
         <span v-if="dirty" class="badge badge-warning badge-xs" title="Unsaved change">●</span>
+        <a
+          v-if="docsHref"
+          :href="docsHref"
+          target="_blank"
+          rel="noopener noreferrer"
+          class="link link-primary text-xs font-normal"
+          :data-test="`setting-docs-${field.key}`"
+          title="Open documentation"
+          @click.stop
+        >docs ↗</a>
         <span v-if="field.restart" class="badge badge-warning badge-xs gap-1" title="Requires restart">
           restart
         </span>
@@ -110,12 +120,13 @@
 
 <script setup lang="ts">
 import { ref, computed } from 'vue'
-import type { SettingField } from '@/views/settings/fields'
+import { docsUrl, type SettingField } from '@/views/settings/fields'
 
 const props = defineProps<{ field: SettingField; modelValue: any; dirty?: boolean }>()
 const emit = defineEmits<{ (e: 'update:modelValue', v: any): void }>()
 
 const showSecret = ref(false)
+const docsHref = computed(() => docsUrl(props.field.docs))
 
 const numberError = computed(() => {
   if (props.field.control !== 'number' || props.modelValue == null || props.modelValue === '') return false
diff --git a/frontend/src/views/Settings.vue b/frontend/src/views/Settings.vue
index 80b7a8a47..86e2b18d6 100644
--- a/frontend/src/views/Settings.vue
+++ b/frontend/src/views/Settings.vue
@@ -6,6 +6,13 @@
         <h1 class="text-3xl font-bold">Configuration</h1>
         <p class="text-base-content/70 mt-1">
           Manage mcpproxy settings. Changes save instantly; a badge marks fields that need a restart.
+          <a
+            :href="`${DOCS_BASE}/configuration/config-file`"
+            target="_blank"
+            rel="noopener noreferrer"
+            class="link link-primary"
+            data-test="settings-docs-reference"
+          >Full configuration reference ↗</a>
         </p>
       </div>
       <div class="flex items-center gap-2">
@@ -92,7 +99,17 @@
         <details v-for="acc in advancedAccordions" :key="acc.id" class="collapse collapse-arrow bg-base-100 shadow-md">
           <summary class="collapse-title font-medium" :data-test="`settings-accordion-${acc.id}`">{{ acc.title }}</summary>
           <div class="collapse-content">
-            <p v-if="acc.description" class="text-xs text-base-content/60 mb-2">{{ acc.description }}</p>
+            <p v-if="acc.description || acc.docs" class="text-xs text-base-content/60 mb-2">
+              {{ acc.description }}
+              <a
+                v-if="acc.docs"
+                :href="docsUrl(acc.docs)"
+                target="_blank"
+                rel="noopener noreferrer"
+                class="link link-primary"
+                :data-test="`settings-accordion-docs-${acc.id}`"
+              >Learn more ↗</a>
+            </p>
             <SettingsSection :section-id="acc.id" :fields="acc.fields" :working="state.working" :original="state.original" />
           </div>
         </details>
@@ -170,6 +187,8 @@ import {
   SECURITY_FIELDS,
   GENERAL_FIELDS,
   ADVANCED_ACCORDIONS,
+  DOCS_BASE,
+  docsUrl,
   type SettingField,
 } from '@/views/settings/fields'
 import api from '@/services/api'
diff --git a/frontend/src/views/settings/fields.ts b/frontend/src/views/settings/fields.ts
index 3081ad78d..e71279996 100644
--- a/frontend/src/views/settings/fields.ts
+++ b/frontend/src/views/settings/fields.ts
@@ -37,6 +37,7 @@ export interface SettingField {
   restart?: boolean // requires server restart to take effect
   danger?: DangerSpec
   placeholder?: string
+  docs?: string // doc page path on docs.mcpproxy.app, e.g. "/features/docker-isolation"
 }
 
 export interface SettingsAccordion {
@@ -44,6 +45,15 @@ export interface SettingsAccordion {
   title: string
   description?: string
   fields: SettingField[]
+  docs?: string // doc page path on docs.mcpproxy.app
+}
+
+// Base URL for the hosted documentation; field/accordion `docs` are paths under it.
+export const DOCS_BASE = 'https://docs.mcpproxy.app'
+
+export function docsUrl(path?: string): string | undefined {
+  if (!path) return undefined
+  return path.startsWith('http') ? path : DOCS_BASE + path
 }
 
 // ---- Section 1: Security & Access (prioritised, security-first) ----
@@ -64,6 +74,7 @@ export const SECURITY_FIELDS: SettingField[] = [
   },
   {
     key: 'quarantine_enabled',
+    docs: '/features/security-quarantine',
     label: 'Quarantine new servers & changed tools',
     help: 'Holds newly added servers and tools whose description/schema changed for your approval before agents can call them — protects against Tool Poisoning Attacks. Recommended ON.',
     control: 'toggle',
@@ -75,12 +86,14 @@ export const SECURITY_FIELDS: SettingField[] = [
   },
   {
     key: 'docker_isolation.enabled',
+    docs: '/features/docker-isolation',
     label: 'Run stdio servers in Docker',
     help: 'Runs command-based (stdio) MCP servers inside isolated Docker containers instead of directly on your machine. Requires Docker to be installed and running.',
     control: 'toggle',
   },
   {
     key: 'enable_code_execution',
+    docs: '/features/code-execution',
     label: 'Enable code execution tool',
     help: 'Adds a sandboxed JavaScript tool agents can use to orchestrate several tool calls in one request. Off by default.',
     control: 'toggle',
@@ -93,6 +106,7 @@ export const SECURITY_FIELDS: SettingField[] = [
   },
   {
     key: 'sensitive_data_detection.enabled',
+    docs: '/features/sensitive-data-detection',
     label: 'Scan for secrets in tool traffic',
     help: 'Inspects tool arguments and responses for credentials (API keys, tokens, private keys, …) and flags them in the Activity log.',
     control: 'toggle',
@@ -126,6 +140,7 @@ export const SECURITY_FIELDS: SettingField[] = [
 export const GENERAL_FIELDS: SettingField[] = [
   {
     key: 'routing_mode',
+    docs: '/features/routing-modes',
     label: 'How agents find tools',
     help: 'Retrieve = agents search for tools first (best when you have many servers); Direct = every tool is listed to the agent; Code execution = agents call tools from JavaScript.',
     control: 'select',
@@ -145,7 +160,7 @@ export const GENERAL_FIELDS: SettingField[] = [
     control: 'select',
     options: ['trace', 'debug', 'info', 'warn', 'error'].map((v) => ({ value: v, label: v })),
   },
-  { key: 'telemetry.enabled', label: 'Anonymous usage telemetry', help: 'Sends anonymous usage counts (never tool arguments, content, or identities). Opt-out at any time.', control: 'toggle' },
+  { key: 'telemetry.enabled', docs: '/features/telemetry', label: 'Anonymous usage telemetry', help: 'Sends anonymous usage counts (never tool arguments, content, or identities). Opt-out at any time.', control: 'toggle' },
   { key: 'enable_prompts', label: 'Expose MCP prompts to clients', help: 'Advertise prompt templates from your upstream servers to connected AI clients.', control: 'toggle' },
 ]
 
@@ -153,6 +168,7 @@ export const GENERAL_FIELDS: SettingField[] = [
 export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
   {
     id: 'code-execution',
+    docs: '/features/code-execution',
     title: 'Code execution',
     description: 'Limits for the sandboxed JavaScript tool (enable it in Security & Access).',
     fields: [
@@ -163,6 +179,7 @@ export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
   },
   {
     id: 'docker-isolation',
+    docs: '/features/docker-isolation',
     title: 'Docker isolation',
     description: 'Defaults for containerised stdio servers (turn isolation on in Security & Access). The per-runtime image map and extra docker args are edited in the Raw JSON tab.',
     fields: [
@@ -175,6 +192,7 @@ export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
   },
   {
     id: 'sensitive-data',
+    docs: '/features/sensitive-data-detection',
     title: 'Secret detection',
     description: 'Tuning for the secret scanner (turn it on in Security & Access). Per-category toggles and custom patterns are edited in the Raw JSON tab.',
     fields: [
@@ -186,6 +204,7 @@ export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
   },
   {
     id: 'output-validation',
+    docs: '/features/output-schema-validation',
     title: 'Output-schema validation',
     description: 'Checks a tool’s structured response against its declared schema before it reaches the agent (Spec 054 Track A).',
     fields: [
@@ -195,6 +214,7 @@ export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
   },
   {
     id: 'output-sanitisation',
+    docs: '/features/output-sanitisation',
     title: 'Output sanitisation',
     description: 'Contains untrusted tool output before it reaches the agent (Spec 054 Track B). All opt-in.',
     fields: [
@@ -207,6 +227,7 @@ export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
   },
   {
     id: 'activity',
+    docs: '/features/activity-log',
     title: 'Activity log retention',
     description: 'How long the audit log of tool calls is kept.',
     fields: [
diff --git a/specs/060-settings-page/verification/settings.spec.ts b/specs/060-settings-page/verification/settings.spec.ts
index 96a9f51b3..779306d86 100644
--- a/specs/060-settings-page/verification/settings.spec.ts
+++ b/specs/060-settings-page/verification/settings.spec.ts
@@ -31,6 +31,9 @@ test('settings page: sections, search, posture, partial save, danger confirm', a
   await expect(page.locator('[data-test="settings-posture"]')).toBeVisible()
   await expect(page.locator('[data-test="setting-secret-api_key"]')).toBeVisible()
   await expect(page.locator('[data-test="settings-connect-client"]')).toBeVisible()
+  // doc links: per-field (quarantine) + full config reference in the header
+  await expect(page.locator('[data-test="setting-docs-quarantine_enabled"]')).toHaveAttribute('href', /docs\.mcpproxy\.app\/features\/security-quarantine/)
+  await expect(page.locator('[data-test="settings-docs-reference"]')).toBeVisible()
   await shot(page, 's01-security')
 
   // Cross-section search surfaces matching fields from any section.

From 960f65a971c1781305251d7e1a60f5f795a6082e Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 29 May 2026 17:41:18 +0300
Subject: [PATCH 06/10] =?UTF-8?q?feat(060):=20settings=20UX=20polish=20?=
 =?UTF-8?q?=E2=80=94=20copy=20key,=20confirm=20regen/opt-out,=20validate?=
 =?UTF-8?q?=20duration,=20name=20prompts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

API key field:
- add a copy-to-clipboard button (with a transient ✓ + clipboard fallback);
- regenerating the key now opens a confirmation dialog first (the value only
  changes after you confirm, and nothing persists until Save).

Confirmations:
- turning OFF "Anonymous usage telemetry" now asks for confirmation with an
  informational (non-alarming) tone explaining telemetry helps improve
  mcpproxy — new DangerSpec.tone:'info' (neutral styling, no "sensitive" badge).

Validation:
- duration fields (e.g. Tool call timeout) are validated against Go duration
  syntax; invalid input shows an inline error and blocks Save. Shared
  validateField() now gates both number and duration fields.

Clarity:
- "Expose MCP prompts" now names the built-in prompts (setup-new-mcp-server,
  troubleshoot-mcp-server).

Verification spec extended to cover copy button, regen confirm, telemetry
opt-out confirm, and duration validation.

Relates to Spec 060.
---
 .../src/components/settings/SettingField.vue  | 158 ++++++++++++------
 .../components/settings/SettingsSection.vue   |  53 +++---
 frontend/src/views/settings/fields.ts         |  43 ++++-
 .../verification/settings.spec.ts             |  38 ++++-
 4 files changed, 213 insertions(+), 79 deletions(-)

diff --git a/frontend/src/components/settings/SettingField.vue b/frontend/src/components/settings/SettingField.vue
index 91791dc44..d48f6c1bf 100644
--- a/frontend/src/components/settings/SettingField.vue
+++ b/frontend/src/components/settings/SettingField.vue
@@ -22,7 +22,7 @@
         <span v-if="field.restart" class="badge badge-warning badge-xs gap-1" title="Requires restart">
           restart
         </span>
-        <span v-if="field.danger" class="badge badge-error badge-xs" title="Sensitive change">
+        <span v-if="field.danger && field.danger.tone !== 'info'" class="badge badge-error badge-xs" title="Sensitive change">
           sensitive
         </span>
       </div>
@@ -53,54 +53,88 @@
       </select>
 
       <!-- number -->
-      <input
-        v-else-if="field.control === 'number'"
-        type="number"
-        class="input input-bordered input-sm w-32"
-        :class="{ 'input-error': numberError }"
-        :value="modelValue"
-        :min="field.min"
-        :max="field.max"
-        :step="field.step"
-        :data-test="`setting-number-${field.key}`"
-        @input="onNumber(($event.target as HTMLInputElement).value)"
-      />
+      <div v-else-if="field.control === 'number'" class="flex flex-col items-end">
+        <input
+          type="number"
+          class="input input-bordered input-sm w-32"
+          :class="{ 'input-error': validationError }"
+          :value="modelValue"
+          :min="field.min"
+          :max="field.max"
+          :step="field.step"
+          :data-test="`setting-number-${field.key}`"
+          @input="onNumber(($event.target as HTMLInputElement).value)"
+        />
+        <span v-if="validationError" class="text-error text-xs mt-1" :data-test="`setting-error-${field.key}`">{{ validationError }}</span>
+      </div>
 
       <!-- secret -->
-      <div v-else-if="field.control === 'secret'" class="join">
+      <template v-else-if="field.control === 'secret'">
+        <div class="join">
+          <input
+            :type="showSecret ? 'text' : 'password'"
+            class="input input-bordered input-sm join-item w-56 font-mono"
+            :value="modelValue ?? ''"
+            :placeholder="field.placeholder"
+            :data-test="`setting-secret-${field.key}`"
+            @input="emitVal(($event.target as HTMLInputElement).value)"
+          />
+          <button type="button" class="btn btn-sm join-item" :title="showSecret ? 'Hide' : 'Show'" @click="showSecret = !showSecret">
+            {{ showSecret ? '🙈' : '👁' }}
+          </button>
+          <button
+            type="button"
+            class="btn btn-sm join-item"
+            :class="{ 'btn-success': copied }"
+            :data-test="`setting-copy-${field.key}`"
+            :title="copied ? 'Copied!' : 'Copy to clipboard'"
+            :disabled="!modelValue"
+            @click="copy"
+          >
+            {{ copied ? '✓' : '📋' }}
+          </button>
+          <button
+            type="button"
+            class="btn btn-sm join-item"
+            :data-test="`setting-regenerate-${field.key}`"
+            title="Generate a new random key"
+            @click="regenEl?.showModal()"
+          >
+            ↻
+          </button>
+        </div>
+        <dialog ref="regenEl" class="modal" :data-test="`setting-regenerate-confirm-${field.key}`">
+          <div class="modal-box">
+            <h3 class="font-bold text-lg">Generate a new {{ field.label }}?</h3>
+            <p class="text-sm mt-2">
+              A new random value will replace the current one in the field. Nothing changes until you click
+              <b>Save changes</b> — after saving you'll need to update connected clients and restart.
+            </p>
+            <div class="modal-action">
+              <button class="btn btn-sm" @click="regenEl?.close()" :data-test="`setting-regenerate-cancel-${field.key}`">Cancel</button>
+              <button class="btn btn-sm btn-primary" @click="confirmRegenerate" :data-test="`setting-regenerate-proceed-${field.key}`">
+                Generate
+              </button>
+            </div>
+          </div>
+          <form method="dialog" class="modal-backdrop"><button>close</button></form>
+        </dialog>
+      </template>
+
+      <!-- text / duration -->
+      <div v-else-if="field.control === 'text' || field.control === 'duration'" class="flex flex-col items-end">
         <input
-          :type="showSecret ? 'text' : 'password'"
-          class="input input-bordered input-sm join-item w-56 font-mono"
+          type="text"
+          class="input input-bordered input-sm w-56 font-mono"
+          :class="{ 'input-error': validationError }"
           :value="modelValue ?? ''"
           :placeholder="field.placeholder"
-          :data-test="`setting-secret-${field.key}`"
+          :data-test="`setting-text-${field.key}`"
           @input="emitVal(($event.target as HTMLInputElement).value)"
         />
-        <button type="button" class="btn btn-sm join-item" :title="showSecret ? 'Hide' : 'Show'" @click="showSecret = !showSecret">
-          {{ showSecret ? '🙈' : '👁' }}
-        </button>
-        <button
-          type="button"
-          class="btn btn-sm join-item"
-          :data-test="`setting-regenerate-${field.key}`"
-          title="Generate a new random key"
-          @click="regenerate"
-        >
-          ↻
-        </button>
+        <span v-if="validationError" class="text-error text-xs mt-1" :data-test="`setting-error-${field.key}`">{{ validationError }}</span>
       </div>
 
-      <!-- text / duration -->
-      <input
-        v-else-if="field.control === 'text' || field.control === 'duration'"
-        type="text"
-        class="input input-bordered input-sm w-56 font-mono"
-        :value="modelValue ?? ''"
-        :placeholder="field.placeholder"
-        :data-test="`setting-text-${field.key}`"
-        @input="emitVal(($event.target as HTMLInputElement).value)"
-      />
-
       <!-- multiselect (checkbox group) -->
       <div v-else-if="field.control === 'multiselect'" class="flex flex-wrap gap-3 justify-end max-w-xs">
         <label v-for="opt in field.options" :key="opt.value" class="label cursor-pointer gap-1 p-0">
@@ -120,22 +154,46 @@
 
 <script setup lang="ts">
 import { ref, computed } from 'vue'
-import { docsUrl, type SettingField } from '@/views/settings/fields'
+import { docsUrl, validateField, type SettingField } from '@/views/settings/fields'
 
 const props = defineProps<{ field: SettingField; modelValue: any; dirty?: boolean }>()
 const emit = defineEmits<{ (e: 'update:modelValue', v: any): void }>()
 
 const showSecret = ref(false)
+const copied = ref(false)
+const regenEl = ref<HTMLDialogElement | null>(null)
 const docsHref = computed(() => docsUrl(props.field.docs))
 
-const numberError = computed(() => {
-  if (props.field.control !== 'number' || props.modelValue == null || props.modelValue === '') return false
-  const n = Number(props.modelValue)
-  if (Number.isNaN(n)) return true
-  if (props.field.min != null && n < props.field.min) return true
-  if (props.field.max != null && n > props.field.max) return true
-  return false
-})
+async function copy() {
+  const val = props.modelValue
+  if (!val) return
+  try {
+    await navigator.clipboard.writeText(String(val))
+  } catch {
+    // clipboard API unavailable (e.g. non-secure context) — fall back
+    const ta = document.createElement('textarea')
+    ta.value = String(val)
+    document.body.appendChild(ta)
+    ta.select()
+    try {
+      document.execCommand('copy')
+    } catch {
+      /* ignore */
+    }
+    document.body.removeChild(ta)
+  }
+  copied.value = true
+  setTimeout(() => {
+    copied.value = false
+  }, 1500)
+}
+
+function confirmRegenerate() {
+  regenEl.value?.close()
+  regenerate()
+}
+
+const validationError = computed(() => validateField(props.field, props.modelValue))
 
 function emitVal(v: any) {
   emit('update:modelValue', v)
@@ -166,5 +224,5 @@ function regenerate() {
   emitVal(hex)
 }
 
-defineExpose({ numberError })
+defineExpose({ validationError })
 </script>
diff --git a/frontend/src/components/settings/SettingsSection.vue b/frontend/src/components/settings/SettingsSection.vue
index 00be51136..be1e45fb0 100644
--- a/frontend/src/components/settings/SettingsSection.vue
+++ b/frontend/src/components/settings/SettingsSection.vue
@@ -49,14 +49,23 @@
     <!-- danger confirm -->
     <dialog ref="confirmEl" class="modal" :data-test="`settings-confirm-${sectionId}`">
       <div class="modal-box">
-        <h3 class="font-bold text-lg text-error">Confirm sensitive change</h3>
+        <h3 class="font-bold text-lg" :class="pendingInfoOnly ? '' : 'text-error'">
+          {{ pendingInfoOnly ? 'Are you sure?' : 'Confirm sensitive change' }}
+        </h3>
         <ul class="list-disc list-inside text-sm mt-3 space-y-2">
           <li v-for="(m, i) in pendingMessages" :key="i">{{ m }}</li>
         </ul>
         <div class="modal-action">
-          <button class="btn btn-sm" @click="cancelConfirm" data-test="settings-confirm-cancel">Cancel</button>
-          <button class="btn btn-sm btn-error" @click="proceedConfirm" data-test="settings-confirm-proceed">
-            Apply anyway
+          <button class="btn btn-sm" @click="cancelConfirm" data-test="settings-confirm-cancel">
+            {{ pendingInfoOnly ? 'Keep it on' : 'Cancel' }}
+          </button>
+          <button
+            class="btn btn-sm"
+            :class="pendingInfoOnly ? 'btn-primary' : 'btn-error'"
+            @click="proceedConfirm"
+            data-test="settings-confirm-proceed"
+          >
+            {{ pendingInfoOnly ? 'Turn off anyway' : 'Apply anyway' }}
           </button>
         </div>
       </div>
@@ -68,7 +77,7 @@
 <script setup lang="ts">
 import { ref, computed, getCurrentInstance } from 'vue'
 import SettingField from './SettingField.vue'
-import { getPath, setPath, buildPartial, type SettingField as Field } from '@/views/settings/fields'
+import { getPath, setPath, buildPartial, validateField, type SettingField as Field } from '@/views/settings/fields'
 import { useSystemStore } from '@/stores/system'
 import api from '@/services/api'
 
@@ -87,21 +96,13 @@ const lastResult = ref<any>(null)
 const dirty = ref<Record<string, true>>({})
 const confirmEl = ref<HTMLDialogElement | null>(null)
 const pendingMessages = ref<string[]>([])
+const pendingInfoOnly = ref(false)
 
 const dirtyKeys = computed(() => Object.keys(dirty.value))
 
-// crude validity gate: any number field out of range blocks save
+// Block Save when any field (number/duration) is invalid.
 const hasInvalid = computed(() =>
-  props.fields.some((f) => {
-    if (f.control !== 'number') return false
-    const v = getPath(props.working, f.key)
-    if (v === '' || v == null) return true
-    const n = Number(v)
-    if (Number.isNaN(n)) return true
-    if (f.min != null && n < f.min) return true
-    if (f.max != null && n > f.max) return true
-    return false
-  })
+  props.fields.some((f) => validateField(f, getPath(props.working, f.key)) != null)
 )
 
 function eq(a: any, b: any): boolean {
@@ -125,21 +126,22 @@ function isLoopback(addr: any): boolean {
   return /^(127\.|localhost|\[::1\]|::1)/.test(s.replace(/^.*@/, '')) || s.startsWith('127.0.0.1')
 }
 
-function dangerMessages(): string[] {
-  const msgs: string[] = []
+function dangerMessages(): Array<{ message: string; tone: 'danger' | 'info' }> {
+  const out: Array<{ message: string; tone: 'danger' | 'info' }> = []
   for (const key of dirtyKeys.value) {
     const f = props.fields.find((x) => x.key === key)
     if (!f?.danger) continue
     const val = getPath(props.working, key)
+    const entry = { message: f.danger.message, tone: f.danger.tone ?? 'danger' }
     if ('confirmValue' in f.danger) {
-      if (eq(val, f.danger.confirmValue)) msgs.push(f.danger.message)
+      if (eq(val, f.danger.confirmValue)) out.push(entry)
     } else if (f.key === 'listen') {
-      if (!isLoopback(val)) msgs.push(f.danger.message)
+      if (!isLoopback(val)) out.push(entry)
     } else {
-      msgs.push(f.danger.message)
+      out.push(entry)
     }
   }
-  return msgs
+  return out
 }
 
 function discard() {
@@ -152,9 +154,10 @@ function discard() {
 }
 
 function attemptSave() {
-  const msgs = dangerMessages()
-  if (msgs.length) {
-    pendingMessages.value = msgs
+  const items = dangerMessages()
+  if (items.length) {
+    pendingMessages.value = items.map((i) => i.message)
+    pendingInfoOnly.value = items.every((i) => i.tone === 'info')
     confirmEl.value?.showModal()
     return
   }
diff --git a/frontend/src/views/settings/fields.ts b/frontend/src/views/settings/fields.ts
index e71279996..02ecda6df 100644
--- a/frontend/src/views/settings/fields.ts
+++ b/frontend/src/views/settings/fields.ts
@@ -23,6 +23,10 @@ export interface DangerSpec {
   // equals confirmValue (omit to always confirm on change).
   message: string
   confirmValue?: unknown
+  // 'danger' (default) = security-risky change, shown red + "sensitive" badge.
+  // 'info' = a gentle "are you sure?" (e.g. opting out of telemetry) — neutral
+  // styling, no sensitive badge.
+  tone?: 'danger' | 'info'
 }
 
 export interface SettingField {
@@ -56,6 +60,29 @@ export function docsUrl(path?: string): string | undefined {
   return path.startsWith('http') ? path : DOCS_BASE + path
 }
 
+// Matches Go time.Duration syntax: one or more <number><unit> segments,
+// e.g. "2m", "90s", "1h30m", "500ms". Used to validate duration fields.
+const DURATION_RE = /^(\d+(\.\d+)?(ns|us|µs|ms|s|m|h))+$/
+
+// validateField returns a human-readable error string for an invalid value,
+// or null when the value is acceptable. Shared by the field control (to show
+// the error) and the section (to block Save).
+export function validateField(field: SettingField, value: unknown): string | null {
+  if (field.control === 'number') {
+    if (value === '' || value == null) return 'Enter a number'
+    const n = Number(value)
+    if (Number.isNaN(n)) return 'Must be a number'
+    if (field.min != null && n < field.min) return `Must be ≥ ${field.min}`
+    if (field.max != null && n > field.max) return `Must be ≤ ${field.max}`
+  }
+  if (field.control === 'duration') {
+    const s = String(value ?? '').trim()
+    if (s === '') return 'Enter a duration, e.g. 2m'
+    if (!DURATION_RE.test(s)) return 'Use a duration like 2m, 90s, or 1h30m'
+  }
+  return null
+}
+
 // ---- Section 1: Security & Access (prioritised, security-first) ----
 export const SECURITY_FIELDS: SettingField[] = [
   {
@@ -160,8 +187,20 @@ export const GENERAL_FIELDS: SettingField[] = [
     control: 'select',
     options: ['trace', 'debug', 'info', 'warn', 'error'].map((v) => ({ value: v, label: v })),
   },
-  { key: 'telemetry.enabled', docs: '/features/telemetry', label: 'Anonymous usage telemetry', help: 'Sends anonymous usage counts (never tool arguments, content, or identities). Opt-out at any time.', control: 'toggle' },
-  { key: 'enable_prompts', label: 'Expose MCP prompts to clients', help: 'Advertise prompt templates from your upstream servers to connected AI clients.', control: 'toggle' },
+  {
+    key: 'telemetry.enabled',
+    docs: '/features/telemetry',
+    label: 'Anonymous usage telemetry',
+    help: 'Sends anonymous usage counts (never tool arguments, content, or identities). Opt-out at any time.',
+    control: 'toggle',
+    danger: {
+      confirmValue: false,
+      tone: 'info',
+      message:
+        'Anonymous telemetry is how we see which features matter and catch problems — it never includes your tool arguments, content, or any identifying info. Turning it off removes that signal. Turn it off anyway?',
+    },
+  },
+  { key: 'enable_prompts', label: 'Expose MCP prompts to clients', help: 'Advertises mcpproxy’s built-in guided prompts to connected AI clients: “setup-new-mcp-server” (add a server) and “troubleshoot-mcp-server” (diagnose connection issues).', control: 'toggle' },
 ]
 
 // ---- Section 3: Advanced (subsystem accordions) ----
diff --git a/specs/060-settings-page/verification/settings.spec.ts b/specs/060-settings-page/verification/settings.spec.ts
index 779306d86..66d6748fd 100644
--- a/specs/060-settings-page/verification/settings.spec.ts
+++ b/specs/060-settings-page/verification/settings.spec.ts
@@ -4,7 +4,11 @@
 //   rm -rf /tmp/settings-uitest && mkdir -p /tmp/settings-uitest
 //   cat > /tmp/settings-uitest/config.json <<'EOF'
 //   { "listen":"127.0.0.1:18099","data_dir":"/tmp/settings-uitest","api_key":"settingskey",
-//     "enable_socket":false,"telemetry":{"enabled":false},"mcpServers":[] }
+//     "enable_socket":false,
+//     "telemetry":{"enabled":true,"endpoint":"http://127.0.0.1:1/none"},
+//     "mcpServers":[] }
+//   (telemetry on — with a dead endpoint so nothing is sent — so the opt-out
+//    confirmation can be exercised.)
 //   EOF
 //   ./mcpproxy serve --config=/tmp/settings-uitest/config.json --log-level=warn &
 //
@@ -30,7 +34,20 @@ test('settings page: sections, search, posture, partial save, danger confirm', a
   // Security tab renders with the at-a-glance posture summary + connect helper.
   await expect(page.locator('[data-test="settings-posture"]')).toBeVisible()
   await expect(page.locator('[data-test="setting-secret-api_key"]')).toBeVisible()
+  await expect(page.locator('[data-test="setting-copy-api_key"]')).toBeVisible()
   await expect(page.locator('[data-test="settings-connect-client"]')).toBeVisible()
+
+  // Regenerating the API key asks for confirmation before changing the value.
+  const apiKeyVal = await page.locator('[data-test="setting-secret-api_key"]').inputValue()
+  await page.locator('[data-test="setting-regenerate-api_key"]').click()
+  const regenOpen = await page.evaluate(() => {
+    const d = document.querySelector('[data-test="setting-regenerate-confirm-api_key"]') as HTMLDialogElement | null
+    return !!d && d.open
+  })
+  expect(regenOpen).toBeTruthy()
+  await page.locator('[data-test="setting-regenerate-cancel-api_key"]').click()
+  // value unchanged after cancelling
+  expect(await page.locator('[data-test="setting-secret-api_key"]').inputValue()).toBe(apiKeyVal)
   // doc links: per-field (quarantine) + full config reference in the header
   await expect(page.locator('[data-test="setting-docs-quarantine_enabled"]')).toHaveAttribute('href', /docs\.mcpproxy\.app\/features\/security-quarantine/)
   await expect(page.locator('[data-test="settings-docs-reference"]')).toBeVisible()
@@ -62,9 +79,26 @@ test('settings page: sections, search, posture, partial save, danger confirm', a
   await shot(page, 's03-danger-confirm')
   await page.locator('[data-test="settings-confirm-security"] [data-test="settings-confirm-cancel"]').click()
 
-  // Other tabs render.
+  // General tab: duration validation + telemetry opt-out confirmation.
   await page.locator('[data-test="settings-tab-general"]').click()
   await expect(page.locator('[data-test="setting-select-routing_mode"]')).toBeVisible()
+
+  // Invalid duration is rejected (error shown, Save blocked).
+  await page.locator('[data-test="setting-text-call_tool_timeout"]').fill('not-a-duration')
+  await expect(page.locator('[data-test="setting-error-call_tool_timeout"]')).toBeVisible()
+  await expect(page.locator('[data-test="settings-apply-general"]')).toBeDisabled()
+  await page.locator('[data-test="setting-text-call_tool_timeout"]').fill('90s')
+  await expect(page.locator('[data-test="setting-error-call_tool_timeout"]')).toHaveCount(0)
+
+  // Turning telemetry OFF asks for confirmation (info tone).
+  await page.locator('[data-test="setting-toggle-telemetry.enabled"]').click()
+  await page.locator('[data-test="settings-apply-general"]').click()
+  const telemetryConfirm = await page.evaluate(() => {
+    const d = document.querySelector('[data-test="settings-confirm-general"]') as HTMLDialogElement | null
+    return !!d && d.open
+  })
+  expect(telemetryConfirm).toBeTruthy()
+  await page.locator('[data-test="settings-confirm-general"] [data-test="settings-confirm-cancel"]').click()
   await page.locator('[data-test="settings-tab-advanced"]').click()
   await expect(page.locator('[data-test="settings-accordion-output-sanitisation"]')).toBeVisible()
   await page.locator('[data-test="settings-tab-raw"]').click()

From 1964911873a6f601b5e19dfe42ab43093aa47e38 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 29 May 2026 17:51:11 +0300
Subject: [PATCH 07/10] feat(060): validate text settings (listen address,
 sizes, registry, key)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add format validation so users can't save values that break mcpproxy:
- Listen address: must be a valid host:port (IPv4/hostname/[IPv6]:port,
  port 1–65535) — the critical field that previously accepted any string.
- Docker memory_limit (bytesize), cpu_limit (positive number), registry
  (hostname) — validated, blank falls back to the Docker default.
- API key: a non-empty key must be ≥16 chars (empty still = keep current).

Shared validateField() drives a new `valueKind` (hostport/bytesize/cpu/
hostname/url/secretkey). Errors only surface — and only block Save — for
fields the user has actually edited, so a pre-existing value never blocks
saving unrelated changes. Verification spec covers the listen + duration cases.

Relates to Spec 060.
---
 .../src/components/settings/SettingField.vue  |  5 +-
 .../components/settings/SettingsSection.vue   |  8 ++-
 frontend/src/views/settings/fields.ts         | 62 ++++++++++++++++++-
 .../verification/settings.spec.ts             |  8 +++
 4 files changed, 77 insertions(+), 6 deletions(-)

diff --git a/frontend/src/components/settings/SettingField.vue b/frontend/src/components/settings/SettingField.vue
index d48f6c1bf..0799d1cd2 100644
--- a/frontend/src/components/settings/SettingField.vue
+++ b/frontend/src/components/settings/SettingField.vue
@@ -193,7 +193,10 @@ function confirmRegenerate() {
   regenerate()
 }
 
-const validationError = computed(() => validateField(props.field, props.modelValue))
+// Only surface validation errors for fields the user has actually edited, so a
+// pre-existing value (e.g. a short legacy API key) never alarms or blocks
+// saving unrelated fields.
+const validationError = computed(() => (props.dirty ? validateField(props.field, props.modelValue) : null))
 
 function emitVal(v: any) {
   emit('update:modelValue', v)
diff --git a/frontend/src/components/settings/SettingsSection.vue b/frontend/src/components/settings/SettingsSection.vue
index be1e45fb0..724c780f2 100644
--- a/frontend/src/components/settings/SettingsSection.vue
+++ b/frontend/src/components/settings/SettingsSection.vue
@@ -100,9 +100,13 @@ const pendingInfoOnly = ref(false)
 
 const dirtyKeys = computed(() => Object.keys(dirty.value))
 
-// Block Save when any field (number/duration) is invalid.
+// Block Save only when a CHANGED field is invalid — a pre-existing value the
+// user hasn't touched must never block saving unrelated edits.
 const hasInvalid = computed(() =>
-  props.fields.some((f) => validateField(f, getPath(props.working, f.key)) != null)
+  dirtyKeys.value.some((k) => {
+    const f = props.fields.find((x) => x.key === k)
+    return f != null && validateField(f, getPath(props.working, k)) != null
+  })
 )
 
 function eq(a: any, b: any): boolean {
diff --git a/frontend/src/views/settings/fields.ts b/frontend/src/views/settings/fields.ts
index 02ecda6df..67b50d4aa 100644
--- a/frontend/src/views/settings/fields.ts
+++ b/frontend/src/views/settings/fields.ts
@@ -29,6 +29,10 @@ export interface DangerSpec {
   tone?: 'danger' | 'info'
 }
 
+// Extra validation applied to text/secret fields (beyond number/duration,
+// which are validated from the control type). Centralised in validateField.
+export type ValueKind = 'hostport' | 'bytesize' | 'cpu' | 'hostname' | 'url' | 'secretkey'
+
 export interface SettingField {
   key: string // dot-path, e.g. "docker_isolation.enabled"
   label: string
@@ -42,6 +46,8 @@ export interface SettingField {
   danger?: DangerSpec
   placeholder?: string
   docs?: string // doc page path on docs.mcpproxy.app, e.g. "/features/docker-isolation"
+  valueKind?: ValueKind // extra format validation for text/secret fields
+  optional?: boolean // when true, an empty value is valid (skips kind validation)
 }
 
 export interface SettingsAccordion {
@@ -64,6 +70,32 @@ export function docsUrl(path?: string): string | undefined {
 // e.g. "2m", "90s", "1h30m", "500ms". Used to validate duration fields.
 const DURATION_RE = /^(\d+(\.\d+)?(ns|us|µs|ms|s|m|h))+$/
 
+// validateHostPort checks a Go-style listen address: "[host]:port" where the
+// host part may be empty (all interfaces), an IPv4/hostname, or a bracketed
+// IPv6 literal. Port must be 1–65535.
+function validateHostPort(s: string): string | null {
+  let host: string
+  let portStr: string
+  if (s.startsWith('[')) {
+    const close = s.indexOf(']')
+    if (close === -1) return 'Unclosed “[” in IPv6 address'
+    host = s.slice(1, close)
+    const rest = s.slice(close + 1)
+    if (!rest.startsWith(':')) return 'Expected [ipv6]:port, e.g. [::1]:8080'
+    portStr = rest.slice(1)
+  } else {
+    const i = s.lastIndexOf(':')
+    if (i === -1) return 'Must include a port, e.g. 127.0.0.1:8080'
+    host = s.slice(0, i)
+    portStr = s.slice(i + 1)
+  }
+  if (!/^\d+$/.test(portStr)) return 'Port must be a number, e.g. 8080'
+  const port = Number(portStr)
+  if (port < 1 || port > 65535) return 'Port must be between 1 and 65535'
+  if (host && !/^[A-Za-z0-9.\-:]+$/.test(host)) return 'Invalid host in address'
+  return null
+}
+
 // validateField returns a human-readable error string for an invalid value,
 // or null when the value is acceptable. Shared by the field control (to show
 // the error) and the section (to block Save).
@@ -80,6 +112,27 @@ export function validateField(field: SettingField, value: unknown): string | nul
     if (s === '') return 'Enter a duration, e.g. 2m'
     if (!DURATION_RE.test(s)) return 'Use a duration like 2m, 90s, or 1h30m'
   }
+  if (field.valueKind && (field.control === 'text' || field.control === 'secret')) {
+    const s = String(value ?? '').trim()
+    if (s === '') return field.optional ? null : 'This field is required'
+    switch (field.valueKind) {
+      case 'hostport':
+        return validateHostPort(s)
+      case 'bytesize':
+        // Docker-style size: 512m, 1g, 256k, 1073741824 (bytes), optional unit
+        return /^\d+(\.\d+)?\s*([bkmgtBKMGT]i?b?)?$/.test(s) ? null : 'Use a size like 512m, 1g, or 256k'
+      case 'cpu':
+        return /^\d+(\.\d+)?$/.test(s) && Number(s) > 0 ? null : 'Use a positive number of CPUs, e.g. 1.0 or 0.5'
+      case 'hostname':
+        return /^[A-Za-z0-9.\-]+(:\d+)?(\/[^\s]*)?$/.test(s) ? null : 'Use a registry host like docker.io or ghcr.io'
+      case 'url':
+        return /^https?:\/\/[^\s]+$/.test(s) ? null : 'Use a URL starting with http:// or https://'
+      case 'secretkey':
+        // A non-empty key must be reasonably strong. Empty is handled above
+        // (api_key uses optional:true → blank keeps the current key).
+        return s.length >= 16 ? null : 'API key must be at least 16 characters'
+    }
+  }
   return null
 }
 
@@ -90,6 +143,8 @@ export const SECURITY_FIELDS: SettingField[] = [
     label: 'API key',
     help: 'Secret that authenticates clients to the REST API and Web UI (sent as the "X-API-Key" header or "?apikey=" in the URL). Leave blank to keep the current key; ↻ generates a new one. Changing it requires a restart and re-connecting clients.',
     control: 'secret',
+    valueKind: 'secretkey',
+    optional: true,
     restart: true,
     placeholder: '•••••••• (unchanged — type to replace)',
   },
@@ -154,6 +209,7 @@ export const SECURITY_FIELDS: SettingField[] = [
     label: 'Listen address',
     help: 'Where the server accepts connections. Keep 127.0.0.1:8080 for local-only use. To reach mcpproxy from other machines use 0.0.0.0:8080 — turn on “Require API key for MCP clients” first. Takes effect after restart.',
     control: 'text',
+    valueKind: 'hostport',
     restart: true,
     placeholder: '127.0.0.1:8080',
     danger: {
@@ -223,9 +279,9 @@ export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
     description: 'Defaults for containerised stdio servers (turn isolation on in Security & Access). The per-runtime image map and extra docker args are edited in the Raw JSON tab.',
     fields: [
       { key: 'docker_isolation.network_mode', label: 'Container network', help: 'none = no network (most secure), bridge = NAT, host = share host network.', control: 'select', options: ['bridge', 'none', 'host'].map((v) => ({ value: v, label: v })) },
-      { key: 'docker_isolation.memory_limit', label: 'Memory limit per container', control: 'text', placeholder: '512m' },
-      { key: 'docker_isolation.cpu_limit', label: 'CPU limit per container', control: 'text', placeholder: '1.0' },
-      { key: 'docker_isolation.registry', label: 'Container image registry', control: 'text', placeholder: 'docker.io' },
+      { key: 'docker_isolation.memory_limit', label: 'Memory limit per container', control: 'text', placeholder: '512m', valueKind: 'bytesize', optional: true },
+      { key: 'docker_isolation.cpu_limit', label: 'CPU limit per container', control: 'text', placeholder: '1.0', valueKind: 'cpu', optional: true },
+      { key: 'docker_isolation.registry', label: 'Container image registry', control: 'text', placeholder: 'docker.io', valueKind: 'hostname', optional: true },
       { key: 'docker_isolation.enable_cache_volume', label: 'Share a package cache volume', help: 'Speeds up repeated npm/uvx installs by caching across containers.', control: 'toggle' },
     ],
   },
diff --git a/specs/060-settings-page/verification/settings.spec.ts b/specs/060-settings-page/verification/settings.spec.ts
index 66d6748fd..bad515200 100644
--- a/specs/060-settings-page/verification/settings.spec.ts
+++ b/specs/060-settings-page/verification/settings.spec.ts
@@ -48,6 +48,14 @@ test('settings page: sections, search, posture, partial save, danger confirm', a
   await page.locator('[data-test="setting-regenerate-cancel-api_key"]').click()
   // value unchanged after cancelling
   expect(await page.locator('[data-test="setting-secret-api_key"]').inputValue()).toBe(apiKeyVal)
+  // Listen address validation: a malformed host:port shows an error and blocks Save.
+  const origListen = await page.locator('[data-test="setting-text-listen"]').inputValue()
+  await page.locator('[data-test="setting-text-listen"]').fill('not-an-address')
+  await expect(page.locator('[data-test="setting-error-listen"]')).toBeVisible()
+  await expect(page.locator('[data-test="settings-apply-security"]')).toBeDisabled()
+  await page.locator('[data-test="setting-text-listen"]').fill(origListen) // restore (clears dirty)
+  await expect(page.locator('[data-test="setting-error-listen"]')).toHaveCount(0)
+
   // doc links: per-field (quarantine) + full config reference in the header
   await expect(page.locator('[data-test="setting-docs-quarantine_enabled"]')).toHaveAttribute('href', /docs\.mcpproxy\.app\/features\/security-quarantine/)
   await expect(page.locator('[data-test="settings-docs-reference"]')).toBeVisible()

From 7585150957ecb3f58c168a0c68a7695eec06048c Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 29 May 2026 17:51:11 +0300
Subject: [PATCH 08/10] docs(routing-modes): drop misleading "Default MCP
 Endpoint" column

The overview table listed `/mcp` as each mode's "Default MCP Endpoint",
implying the mode maps to a distinct default path. All modes default to
`/mcp`; the per-mode dedicated endpoints (/mcp/call, /mcp/all, /mcp/code)
are documented in the Dedicated Endpoints section. Remove the confusing
column and add a one-line pointer to that section.
---
 docs/features/routing-modes.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/docs/features/routing-modes.md b/docs/features/routing-modes.md
index e114ce4d6..1905b62e7 100644
--- a/docs/features/routing-modes.md
+++ b/docs/features/routing-modes.md
@@ -13,11 +13,13 @@ MCPProxy supports three routing modes that control how upstream MCP tools are ex
 
 ## Overview
 
-| Mode | Default MCP Endpoint | Tool Exposure | Best For |
-|------|---------------------|---------------|----------|
-| `retrieve_tools` | `/mcp` | BM25 search via `retrieve_tools` + `call_tool_read/write/destructive` | Large tool sets (50+ tools), token-sensitive workloads |
-| `direct` | `/mcp` | All tools exposed as `serverName__toolName` | Small tool sets, simple setups, maximum compatibility |
-| `code_execution` | `/mcp` | `code_execution` + `retrieve_tools` for discovery | Multi-step orchestration, reduced round-trips |
+| Mode | Tool Exposure | Best For |
+|------|---------------|----------|
+| `retrieve_tools` | BM25 search via `retrieve_tools` + `call_tool_read/write/destructive` | Large tool sets (50+ tools), token-sensitive workloads |
+| `direct` | All tools exposed as `serverName__toolName` | Small tool sets, simple setups, maximum compatibility |
+| `code_execution` | `code_execution` + `retrieve_tools` for discovery | Multi-step orchestration, reduced round-trips |
+
+> The configured mode is served on the default `/mcp` endpoint. Each mode also has a dedicated endpoint (`/mcp/call`, `/mcp/all`, `/mcp/code`) — see [Dedicated Endpoints](#dedicated-endpoints) below.
 
 ## Configuration
 

From 6799ea9a1a6ed8b8f0b5d88c5bc01ed62220890f Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 29 May 2026 18:28:05 +0300
Subject: [PATCH 09/10] docs(060): fix broken link in settings-page.md

Linked ../configuration.md (nonexistent) which failed the Docusaurus
broken-links build gate. Point to the real configuration reference
(../configuration/config-file.md).
---
 docs/features/settings-page.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/features/settings-page.md b/docs/features/settings-page.md
index c8b7abe4f..a82d67f00 100644
--- a/docs/features/settings-page.md
+++ b/docs/features/settings-page.md
@@ -35,4 +35,4 @@ curl -X PATCH -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
 
 Complex lists/maps (Docker image map, custom detection patterns, environment
 vars) and `mcpServers` / `registries` are managed on their own pages or the Raw
-JSON tab. See [configuration.md](../configuration.md) for the full option reference.
+JSON tab. See the [configuration reference](../configuration/config-file.md) for the full option list.

From a95f1c39bc614fd805f3d8da4b61bd5f1e13ce3d Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Fri, 29 May 2026 18:40:23 +0300
Subject: [PATCH 10/10] fix(060): per-key prototype-pollution guard in setPath
 (CodeQL)

CodeQL's js/prototype-pollution-utility didn't recognise the top-level
Set.has(...) check as a barrier. Guard each traversal key (and the final key)
with an explicit __proto__/prototype/constructor comparison, which CodeQL
treats as a sanitising guard for the recursive property assignment.
---
 frontend/src/views/settings/fields.ts | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/frontend/src/views/settings/fields.ts b/frontend/src/views/settings/fields.ts
index 67b50d4aa..90c18797e 100644
--- a/frontend/src/views/settings/fields.ts
+++ b/frontend/src/views/settings/fields.ts
@@ -368,11 +368,10 @@ export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
 ]
 
 // ---- path helpers ----
-// Keys that would mutate the prototype chain. setPath refuses to traverse or
-// assign these so a crafted dot-path can never pollute Object.prototype
-// (CodeQL js/prototype-polluting-assignment). Settings keys come from the
-// static catalogue above, but we guard the generic helper regardless.
-const UNSAFE_KEYS = new Set(['__proto__', 'prototype', 'constructor'])
+// setPath guards every key against prototype-polluting names (__proto__,
+// prototype, constructor) so a crafted dot-path can never reach Object.prototype.
+// Settings keys come from the static catalogue above, but the generic helper is
+// guarded regardless.
 
 export function getPath(obj: any, path: string): any {
   return path.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj)
@@ -380,13 +379,19 @@ export function getPath(obj: any, path: string): any {
 
 export function setPath(obj: any, path: string, value: any): void {
   const keys = path.split('.')
-  if (keys.some((k) => UNSAFE_KEYS.has(k))) return // guard against prototype pollution
   let cur = obj
   for (let i = 0; i < keys.length - 1; i++) {
-    if (cur[keys[i]] == null || typeof cur[keys[i]] !== 'object') cur[keys[i]] = {}
-    cur = cur[keys[i]]
+    const k = keys[i]
+    // Guard every traversal key against prototype pollution. The explicit
+    // per-key comparison (rather than a Set lookup) is what CodeQL recognises
+    // as a sanitising barrier for js/prototype-pollution-utility.
+    if (k === '__proto__' || k === 'prototype' || k === 'constructor') return
+    if (cur[k] == null || typeof cur[k] !== 'object') cur[k] = {}
+    cur = cur[k]
   }
-  cur[keys[keys.length - 1]] = value
+  const last = keys[keys.length - 1]
+  if (last === '__proto__' || last === 'prototype' || last === 'constructor') return
+  cur[last] = value
 }
 
 // buildPartial assembles a nested object containing ONLY the given dot-path