diff --git a/CLAUDE.md b/CLAUDE.md
index e5bef214..12157195 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -158,6 +158,7 @@ tail -f ~/Library/Logs/mcpproxy/main.log  # main log (macOS; Linux: ~/.mcpproxy/
 - **Windows installer**: [docs/github-actions-windows-wix-research.md](docs/github-actions-windows-wix-research.md). **Prerelease** (`next` branch + `v*-rc.*` tags, opt-in, off stable channels): [docs/prerelease-builds.md](docs/prerelease-builds.md).
 
 ## Recent Changes
+- 091-connect-client-form: Added Swift 5.9 (SwiftUI sheet + AppKit menu) + Go 1.25 (core) + existing `internal/connect` package (registry, preview, connect, undo, backup), `internal/httpapi/connect.go` routes; Swift `APIClient` over Unix socket (admin context)
 - 090-tray-glance-v2: Added Swift 5.9 (AppKit, SwiftUI for histogram only) + Go 1.25 (core) + AppKit `NSMenuItem` (incl. `subtitle`, macOS 14.4+), fixture-driven XCTest; Go: chi HTTP API, bbolt storage, zap
 - 088-scanner-trust-ui: Added TypeScript 5.9, Vue 3.5 (Composition API, `<script setup>`), Tailwind v4 + Existing only — hand-written `ApiClient` singleton (`frontend/src/services/api.ts`), Pinia stores (`stores/servers.ts`, `stores/system.ts`), generated `types/contracts.ts` (via `cmd/generate-types`), hand-written `types/api.ts`. **No new npm dependency.**
 - 084-toon-output: Adaptive TOON encoding of `call_tool_*` result text blocks (`internal/toonenc/`, seam in `internal/server/toon_encode.go`). Config `toon_output` (off|adaptive|always, per-server override) + `toon_min_savings_pct`; off by default, hot-reloadable; never-larger by construction; sanitise-before-encode, detection-parity, truncate-after-encode invariants. **New dependency: `github.com/toon-format/toon-go`** (the production encoder; shared with the spec-083 profiler). Docs: [docs/features/toon-output.md](docs/features/toon-output.md).
diff --git a/ROADMAP.md b/ROADMAP.md
index db62fa6b..4458a591 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -792,3 +792,4 @@ Legend: `shipped` ≥95% checked · `in-flight` 1–94% · `drafted` 0% · `—`
 | [088-scanner-trust-ui](./specs/088-scanner-trust-ui/) | `shipped` | 29/29 (100%) |
 | [089-remote-access-tunnel](./specs/089-remote-access-tunnel/) | — | — |
 | [090-tray-glance-v2](./specs/090-tray-glance-v2/) | `shipped` | 35/35 (100%) |
+| [091-connect-client-form](./specs/091-connect-client-form/) | `shipped` | 26/26 (100%) |
diff --git a/docs/api/rest-api.md b/docs/api/rest-api.md
index 9ba753fc..f229691f 100644
--- a/docs/api/rest-api.md
+++ b/docs/api/rest-api.md
@@ -720,6 +720,29 @@ never overwritten. Backups accumulate one per operation and are **never
 deleted automatically**; there is no retention bound, so an undo (below) can
 always find its backup.
 
+`POST` optionally accepts `precondition_token` (Spec 091) — the opaque token
+from the preview this write was confirmed against:
+
+```json
+{ "server_name": "mcpproxy", "force": true, "precondition_token": "…" }
+```
+
+When supplied, the core recomputes the token at write time and, if it no longer
+matches, responds **`409 Conflict`** having written **nothing** (the check runs
+before any backup or write). `force=true` does not override a stale token. When
+omitted, behavior is exactly as before.
+
+The `409` body carries a top-level `action` discriminating the two conflict
+kinds:
+
+| `action` | Meaning | Caller should |
+|----------|---------|---------------|
+| `precondition_failed` | The preview is stale — the config file, the existing entry, or the entry mcpproxy would now write has changed. | Re-fetch the preview; do not blindly retry. |
+| `already_exists` | Pre-existing semantics: an entry with that name is present and `force` was not set. | Confirm with the user, then retry with `force=true` (and a fresh token). |
+
+See [Connect Clients](../features/connect-clients.md) for the token's contents
+and threat model.
+
 #### GET /api/v1/connect/{client}/preview
 
 Returns the exact change a subsequent connect would make — target config path,
@@ -732,6 +755,17 @@ so on macOS this may raise an App-Data prompt; a denial returns `403` +
 remediation. Optional `?server_name=` mirrors the name a subsequent connect
 would use.
 
+Spec 091 adds three response fields:
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `existing_entry_summary` | object, present only when `entry_exists=true` | Sanitized description of the entry that would be **replaced**: `entry_name` (the key it actually lives under, which may differ from `server_name` when the write adopts an endpoint-equivalent entry), `type`, `endpoint` (query string, `user:pass@` userinfo and fragment stripped), `command`, `header_names` and `env_names` — **names only, never values**. Built by whitelist projection, so no other config content can reach the response. |
+| `precondition_token` | string, always present | Opaque keyed HMAC binding this preview to the exact pre-write state. Pass it to `POST` (above) to make a stale preview unwritable. Per-core-instance key, never persisted. |
+| `connect_refusal` | string, optional | The verbatim reason a subsequent connect would refuse regardless of user intent (today: a non-create-capable client such as **OpenCode** with no config present). Treat as "Connect unavailable". |
+
+The preview evaluates the refusal with the write's own guard, so the two cannot
+drift. Full semantics: [Connect Clients](../features/connect-clients.md).
+
 #### POST /api/v1/connect/{client}/undo
 
 One-click undo of the immediately-preceding connect (Spec 078 US3). Body:
diff --git a/docs/features/connect-clients.md b/docs/features/connect-clients.md
new file mode 100644
index 00000000..d52e233e
--- /dev/null
+++ b/docs/features/connect-clients.md
@@ -0,0 +1,130 @@
+---
+id: connect-clients
+title: Connect Clients
+sidebar_label: Connect Clients
+sidebar_position: 12
+description: Preview-before-write connect flow that registers mcpproxy in an MCP client's config file, with a sanitized disclosure of what is replaced and a precondition token that makes a stale preview unwritable
+keywords: [connect, client, preview, precondition, claude desktop, cursor, vs code, opencode]
+---
+
+# Connect Clients
+
+**Connect Clients** registers mcpproxy inside another MCP client's configuration
+file (Claude Desktop, Cursor, VS Code, Codex, Gemini, OpenCode, …) so that client
+talks to the proxy instead of to each upstream server directly. It is available
+from the Web UI wizard, the macOS tray ("Connect Client…"), and the
+`mcpproxy connect` CLI.
+
+The UI flows are **preview → confirm → write** (the CLI writes directly, with
+`--force` to overwrite an existing entry):
+
+1. `GET /api/v1/connect/{client}/preview` renders the exact change — target
+   config path, format, server key, and the entry that would be written (any
+   embedded API key masked).
+2. `POST /api/v1/connect/{client}` performs the write, taking a timestamped
+   backup of an existing file first.
+3. `POST /api/v1/connect/{client}/undo` reverts that write byte-for-byte (or
+   removes the file the connect created).
+
+Endpoint-level reference — request/response shapes, backup naming, undo
+semantics, and the macOS App Data privacy prompt — lives in the
+[REST API reference](../api/rest-api.md#connect-client-wizard).
+
+## What the preview discloses (Spec 091)
+
+A preview shows the entry that *will be written*, which mcpproxy constructs and
+can therefore mask. It historically said nothing about the entry being
+**replaced**, which is user-authored content mcpproxy cannot safely echo. Two
+preview fields close that gap without leaking config contents.
+
+### `existing_entry_summary`
+
+Present only when `entry_exists` is true. A fixed, whitelist-built projection of
+the entry the write would replace:
+
+| Field | Meaning |
+|-------|---------|
+| `entry_name` | The key the entry actually lives under. May differ from the requested `server_name` when the write **adopts** an endpoint-equivalent entry stored under a non-canonical name. |
+| `type` | Transport type (`http`, `stdio`, …). |
+| `endpoint` | Endpoint URL with **query string, userinfo (`user:pass@`) and fragment stripped**. |
+| `command` | Command path for stdio/bridge entries. |
+| `header_names` | Header **names** only — never values. Includes names parsed out of `--header` / `-H` bridge arguments. |
+| `env_names` | Environment variable **names** only — never values. |
+
+Secrecy holds *by construction*, not by masking heuristics: no other field of the
+existing entry is copied, header/env values are never read, and a URL-shaped
+field is emitted only after being reparsed into `scheme://host/path`. Backend
+tests feed entries containing rotated API keys, bearer headers, env secrets,
+`?apikey=` URLs and `user:pass@` URLs and assert none of those values appear
+anywhere in the serialized preview response.
+
+The summary is **display-only** and is never used for drift detection — that is
+the precondition token's job, which hashes the raw entry.
+
+### `connect_refusal`
+
+A string, present only when a subsequent connect would refuse **regardless of
+user intent**, carrying the same verbatim reason the write would return. The
+preview runs the write's own guard rather than a copy, so the two can't drift.
+
+Today the single case is a client that mcpproxy will not create a config for
+from scratch: **OpenCode** owns a config schema mcpproxy will not invent, so with
+no `opencode.jsonc` / `opencode.json` present the connect refuses instead of
+creating one. Consumers must treat a non-empty `connect_refusal` as
+"Connect unavailable" and surface the reason — the macOS form hides its Connect
+button entirely in that state.
+
+## Precondition token and the discriminated conflict (Spec 091)
+
+`precondition_token` is an opaque string **always present** in a preview
+response. Passing it back on the write binds the write to the exact state the
+preview described:
+
+```jsonc
+// POST /api/v1/connect/{client}
+{ "server_name": "mcpproxy", "force": true, "precondition_token": "…" }
+```
+
+The token is an HMAC-SHA256 over a canonical **length-prefixed** encoding of:
+
+- the config path,
+- whether the file exists (create vs. update),
+- the **resolved** target entry name — after the same equivalent-entry adoption
+  the write performs — and its **raw** value (so a credential rotation *inside*
+  the existing entry drifts the token even though the sanitized summary hides
+  it), and
+- the exact pending entry mcpproxy would write right now (so proxy-side drift —
+  API-key rotation, `require_mcp_auth` toggle, listen-address change —
+  invalidates the preview too, and a credential can never be embedded without
+  the credential notice having been shown).
+
+It is keyed with a **per-core-instance random in-memory key**: tokens are
+single-session by design, never persisted, and not usable as an offline
+confirmation oracle for masked values.
+
+### Behavior
+
+- **Token matches** → the write proceeds normally.
+- **Token stale** → `409 Conflict` with `"action": "precondition_failed"`, and
+  **nothing is written** — the check runs before any backup or write, so a
+  refusal is completely inert. The caller should re-preview, not retry.
+- **`force=true` with a stale token** → still `precondition_failed`, still no
+  write. The token, not the absence of `force`, is the overwrite safety.
+- **Token absent** → exactly the previous behavior. Existing Web UI and CLI
+  callers are unaffected.
+
+The `409` body is machine-discriminable at the top level via `action`:
+
+| `action` | Meaning | Caller should |
+|----------|---------|---------------|
+| `precondition_failed` | The preview is stale (file, existing entry, or pending entry changed). | Re-fetch the preview and show the user the new change. |
+| `already_exists` | Pre-existing semantics: an entry with that name is present and `force` was not set. | Ask the user, then retry with `force=true` (plus a fresh token). |
+
+### Consumers
+
+- The **macOS Connect Client form** always sends the token from its rendered
+  preview; replace flows send `force=true` **with** the token, never `force`
+  alone. A `precondition_failed` triggers exactly one automatic re-preview.
+- The **Web UI** ConnectModal is unchanged and may adopt the token later.
+- Write gating is unchanged: connect/disconnect routes still reject restricted
+  agent tokens, and the tray's Unix-socket transport carries admin context.
diff --git a/internal/connect/adoption_test.go b/internal/connect/adoption_test.go
new file mode 100644
index 00000000..0a17ae2d
--- /dev/null
+++ b/internal/connect/adoption_test.go
@@ -0,0 +1,167 @@
+package connect
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// Adoption resolution must be DETERMINISTIC and resolved exactly ONCE per
+// operation (Spec 091 FR-005). The precondition token promises it hashes "the
+// entry the write would actually replace"; if the preview, the token check and
+// the write each pick a different equivalent entry out of a randomly-ordered Go
+// map, that promise is void — the token covers one entry while the write
+// deletes another.
+
+// TestFindEquivalentJSONServerName_Deterministic pins the tie-break: an exact
+// name match wins, otherwise the lowest name in sorted order. Repeated over a
+// map whose iteration order Go deliberately randomizes.
+func TestFindEquivalentJSONServerName_Deterministic(t *testing.T) {
+	const baseURL = "http://127.0.0.1:8080/mcp"
+
+	t.Run("two url-equivalent entries resolve to the sorted-first name", func(t *testing.T) {
+		for i := 0; i < 200; i++ {
+			serversMap := map[string]interface{}{
+				"b-legacy": map[string]interface{}{"url": baseURL + "?apikey=old"},
+				"a-clean":  map[string]interface{}{"url": baseURL},
+				"unrelated": map[string]interface{}{
+					"url": "http://127.0.0.1:9999/mcp",
+				},
+			}
+			got, found := findEquivalentJSONServerName(serversMap, baseURL, "mcpproxy")
+			if !found {
+				t.Fatal("expected a match")
+			}
+			if got != "a-clean" {
+				t.Fatalf("iteration %d: resolved %q, want the deterministic sorted-first match %q", i, got, "a-clean")
+			}
+		}
+	})
+
+	t.Run("the requested name wins over a url-equivalent entry", func(t *testing.T) {
+		for i := 0; i < 200; i++ {
+			serversMap := map[string]interface{}{
+				"mcpproxy": map[string]interface{}{"url": "http://127.0.0.1:9999/mcp"},
+				"legacy":   map[string]interface{}{"url": baseURL},
+			}
+			got, found := findEquivalentJSONServerName(serversMap, baseURL, "mcpproxy")
+			if !found {
+				t.Fatal("expected a match")
+			}
+			if got != "mcpproxy" {
+				t.Fatalf("iteration %d: resolved %q, want the exact requested name (it is what the token and the summary cover)", i, got)
+			}
+		}
+	})
+}
+
+// TestConnect_OpenCodeAdoptionNeverDeletesAnUnnamedEntry is scenario B of the
+// nondeterminism: the requested name already exists, so preview/token/summary
+// cover exactly that key — yet the write's own independent adoption lookup used
+// to reach a URL-equivalent entry under another key and silently delete it.
+func TestConnect_OpenCodeAdoptionNeverDeletesAnUnnamedEntry(t *testing.T) {
+	for i := 0; i < 40; i++ {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("opencode", home)
+		writeFileT(t, cfgPath, `{"mcp":{`+
+			`"mcpproxy":{"type":"remote","url":"http://127.0.0.1:9999/mcp"},`+
+			`"legacy":{"type":"remote","url":"http://127.0.0.1:8080/mcp?apikey=old"}}}`)
+
+		preview, err := svc.Preview("opencode", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		if preview.ExistingEntrySummary == nil || preview.ExistingEntrySummary.EntryName != "mcpproxy" {
+			t.Fatalf("iteration %d: preview must name the exact-name entry, got %+v", i, preview.ExistingEntrySummary)
+		}
+
+		res, err := svc.ConnectWithPrecondition("opencode", "mcpproxy", true, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("ConnectWithPrecondition: %v", err)
+		}
+		if !res.Success {
+			t.Fatalf("iteration %d: expected success, got %+v", i, res)
+		}
+		if !strings.Contains(readConfigT(t, cfgPath), `"legacy"`) {
+			t.Fatalf("iteration %d: the write deleted an entry the token never hashed and the summary never named:\n%s",
+				i, readConfigT(t, cfgPath))
+		}
+	}
+}
+
+// TestConnect_OpenCodeAdoptionMatchesThePreviewedEntry is scenario A: two
+// URL-equivalent entries and a requested name that matches neither. The write
+// must adopt exactly the entry the preview resolved — never flip to the other
+// one (which would be a spurious precondition_failed, or a silent delete of an
+// entry the user was never shown).
+func TestConnect_OpenCodeAdoptionMatchesThePreviewedEntry(t *testing.T) {
+	for i := 0; i < 40; i++ {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("opencode", home)
+		writeFileT(t, cfgPath, `{"mcp":{`+
+			`"a-clean":{"type":"remote","url":"http://127.0.0.1:8080/mcp"},`+
+			`"b-legacy":{"type":"remote","url":"http://127.0.0.1:8080/mcp?apikey=old"}}}`)
+
+		preview, err := svc.Preview("opencode", "proxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		if preview.ExistingEntrySummary == nil {
+			t.Fatalf("iteration %d: expected an adopted existing entry", i)
+		}
+		adopted := preview.ExistingEntrySummary.EntryName
+		if adopted != "a-clean" {
+			t.Fatalf("iteration %d: preview adopted %q, want the deterministic %q", i, adopted, "a-clean")
+		}
+
+		res, err := svc.ConnectWithPrecondition("opencode", "proxy", true, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("ConnectWithPrecondition: %v", err)
+		}
+		if !res.Success {
+			t.Fatalf("iteration %d: a token minted from an unchanged config must not fail: %+v", i, res)
+		}
+
+		var data map[string]interface{}
+		if err := json.Unmarshal([]byte(readConfigT(t, cfgPath)), &data); err != nil {
+			t.Fatal(err)
+		}
+		servers, _ := data["mcp"].(map[string]interface{})
+		if _, gone := servers[adopted]; gone {
+			t.Fatalf("iteration %d: the adopted entry %q should have been replaced", i, adopted)
+		}
+		if _, kept := servers["b-legacy"]; !kept {
+			t.Fatalf("iteration %d: the write deleted %q, which the preview never named:\n%s",
+				i, "b-legacy", readConfigT(t, cfgPath))
+		}
+		if _, written := servers["proxy"]; !written {
+			t.Fatalf("iteration %d: expected the new entry under the requested name", i)
+		}
+	}
+}
+
+// TestUndoReplay_AdoptionIsDeterministic covers undo.go's use of the same
+// matcher: the replay must reconstruct the same bytes the write produced, so it
+// must reach the same adoption decision every time.
+func TestUndoReplay_AdoptionIsDeterministic(t *testing.T) {
+	svc, _ := testService(t)
+	client := FindClient("opencode")
+	backup := []byte(`{"mcp":{` +
+		`"a-clean":{"type":"remote","url":"http://127.0.0.1:8080/mcp"},` +
+		`"b-legacy":{"type":"remote","url":"http://127.0.0.1:8080/mcp?apikey=old"}}}`)
+
+	first, err := svc.replayConnectWrite(client, "proxy", backup)
+	if err != nil {
+		t.Fatalf("replayConnectWrite: %v", err)
+	}
+	for i := 0; i < 100; i++ {
+		again, err := svc.replayConnectWrite(client, "proxy", backup)
+		if err != nil {
+			t.Fatalf("replayConnectWrite: %v", err)
+		}
+		if string(again) != string(first) {
+			t.Fatalf("iteration %d: replay is nondeterministic, so undo would refuse a file it wrote itself:\n%s\n--- vs ---\n%s",
+				i, first, again)
+		}
+	}
+}
diff --git a/internal/connect/clients.go b/internal/connect/clients.go
index dfca2752..9c041179 100644
--- a/internal/connect/clients.go
+++ b/internal/connect/clients.go
@@ -204,7 +204,12 @@ func opencodeConfigCandidates(homeDir string) []string {
 func (s *Service) configPath(clientID string) string {
 	if clientID == "opencode" {
 		for _, p := range opencodeConfigCandidates(s.homeDir) {
-			if _, err := os.Stat(p); err == nil {
+			// A candidate we cannot stat counts as PRESENT: the only reason to
+			// prefer .jsonc is that it shadows .json, and skipping an
+			// unstattable one would silently target the shadowed file, where
+			// the write has no effect. Targeting it instead surfaces the real
+			// permission error on the read that follows.
+			if _, err := s.stat(p); err == nil || !os.IsNotExist(err) {
 				return p
 			}
 		}
diff --git a/internal/connect/connect.go b/internal/connect/connect.go
index dbff42a7..fff0898a 100644
--- a/internal/connect/connect.go
+++ b/internal/connect/connect.go
@@ -8,7 +8,9 @@ import (
 	"os"
 	"path/filepath"
 	"regexp"
+	"sort"
 	"strings"
+	"sync"
 
 	"github.com/BurntSushi/toml"
 )
@@ -82,6 +84,18 @@ type Service struct {
 	// readFile is the content-read seam (Spec 075 T003). Defaults to os.ReadFile;
 	// tests inject a permission-denied error or a call counter through it.
 	readFile func(string) ([]byte, error)
+	// statFile is the metadata seam alongside readFile. Defaults to os.Stat.
+	// Existence checks route through it so a stat that fails for a reason OTHER
+	// than "not there" can be classified honestly instead of being reported as
+	// an absent config.
+	statFile func(string) (os.FileInfo, error)
+
+	// tokenKey is the per-core-instance HMAC key for connect-preview
+	// precondition tokens (Spec 091 FR-005). Generated lazily by
+	// preconditionKey(), never persisted, never exposed: it keeps a token
+	// unforgeable and non-oracular, and scopes it to this process.
+	tokenKeyOnce sync.Once
+	tokenKey     []byte
 }
 
 // WithRequireMCPAuth sets whether the /mcp endpoint requires authentication,
@@ -148,6 +162,20 @@ func NewServiceWithReader(listenAddr, apiKey, homeDir string, readFile func(stri
 // setReadFile overrides the content-read seam (test helper).
 func (s *Service) setReadFile(fn func(string) ([]byte, error)) { s.readFile = fn }
 
+// setStat overrides the metadata seam (test helper), so a permission-blocked
+// stat can be exercised without depending on OS permission bits (which root
+// ignores and Windows does not model the same way).
+func (s *Service) setStat(fn func(string) (os.FileInfo, error)) { s.statFile = fn }
+
+// stat performs a metadata check through the seam, falling back to os.Stat for
+// a zero-value Service. No config content is read (Spec 075 FR-001).
+func (s *Service) stat(path string) (os.FileInfo, error) {
+	if s.statFile != nil {
+		return s.statFile(path)
+	}
+	return os.Stat(path)
+}
+
 // read performs a config content read through the seam, falling back to
 // os.ReadFile for a zero-value Service.
 func (s *Service) read(path string) ([]byte, error) {
@@ -282,8 +310,14 @@ func (s *Service) GetAllStatus() []ClientStatus {
 		}
 
 		// Metadata-only existence check (no content read).
-		if _, err := os.Stat(cfgPath); err == nil {
+		if _, err := s.stat(cfgPath); err == nil {
 			status.Exists = true
+		} else if !os.IsNotExist(err) {
+			// Still no content read — but a stat we were not allowed to make is
+			// not evidence of absence, and leaving the row to say "No config
+			// found" would name the wrong problem. Classifying the stat error
+			// costs nothing extra here.
+			status.AccessState = classifyAccess(err)
 		}
 
 		statuses = append(statuses, status)
@@ -315,8 +349,17 @@ func (s *Service) GetStatus(clientID string) (ClientStatus, error) {
 		AccessState: accessUnknown,
 	}
 
-	if _, err := os.Stat(cfgPath); err == nil {
+	if _, err := s.stat(cfgPath); err == nil {
 		status.Exists = true
+	} else if !os.IsNotExist(err) {
+		// We could not even look. Claiming "no config found" here would report a
+		// permission block as "not installed" and hide the remediation the user
+		// needs (Spec 075 FR-004).
+		status.AccessState = classifyAccess(err)
+		if status.AccessState == accessDenied {
+			status.Remediation = remediationText(c.Name)
+		}
+		return status, nil
 	}
 	if !status.Exists {
 		status.AccessState = accessAbsent
@@ -360,7 +403,26 @@ func (s *Service) entryAccess(client ClientDef, cfgPath string) (name string, fo
 // Connect registers MCPProxy in the specified client's configuration file.
 // serverName defaults to "mcpproxy" if empty. If force is false and an entry
 // already exists, an error is returned.
+//
+// This is the tokenless entry point kept for the Web UI, the CLI and every
+// existing caller; ConnectWithPrecondition adds the Spec 091 drift guard.
 func (s *Service) Connect(clientID, serverName string, force bool) (*ConnectResult, error) {
+	return s.ConnectWithPrecondition(clientID, serverName, force, "")
+}
+
+// ConnectWithPrecondition is Connect guarded by the opaque token a preview
+// returned (Spec 091 FR-005). When preconditionToken is non-empty, the core
+// re-resolves the raw pre-write state and the entry it would write, recomputes
+// the token, and refuses with the discriminated "precondition_failed" action —
+// writing nothing and taking no backup — if anything drifted since the preview:
+// the file appearing or vanishing, the resolved (possibly adopted) entry
+// changing in any way, or the proxy's own configuration changing what would be
+// written. force=true rides WITH the token for a replace-classified flow and
+// never rescues a stale one.
+//
+// An empty token means exactly today's behavior, so existing consumers are
+// unaffected (contracts §2).
+func (s *Service) ConnectWithPrecondition(clientID, serverName string, force bool, preconditionToken string) (*ConnectResult, error) {
 	client := FindClient(clientID)
 	if client == nil {
 		return nil, fmt.Errorf("unknown client: %s", clientID)
@@ -377,22 +439,37 @@ func (s *Service) Connect(clientID, serverName string, force bool) (*ConnectResu
 	if cfgPath == "" {
 		return nil, fmt.Errorf("cannot determine config path for %s", clientID)
 	}
-	if client.ID == "opencode" {
-		// configPath already prefers whichever candidate exists; reaching a
-		// nonexistent path here means NO OpenCode global config was found.
-		if _, err := os.Stat(cfgPath); os.IsNotExist(err) {
-			return nil, fmt.Errorf(
-				"no OpenCode config found (looked for opencode.jsonc and opencode.json in %s) — is OpenCode installed?",
-				filepath.Dir(cfgPath))
+	// Resolve the pre-write state ONCE for the whole operation. The token check
+	// and the write must cover the SAME entry — re-resolving per step is what
+	// let a token hash one entry while the write replaced or deleted another
+	// (Spec 091 FR-005).
+	fileExists, existing, _, err := s.preWriteState(client, cfgPath, serverName)
+	if err != nil {
+		return nil, s.asAccessError(client, cfgPath, err)
+	}
+
+	// Precondition check BEFORE any backup or write, so a refusal is completely
+	// inert (Spec 091 FR-005).
+	if preconditionToken != "" {
+		if stale := s.checkPrecondition(client, cfgPath, serverName, preconditionToken, fileExists, existing); stale != nil {
+			return stale, nil
 		}
 	}
 
+	// The refusal guard runs AFTER the drift check. Both orders refuse the
+	// write, but a caller that echoed a token describing a file which has since
+	// vanished is looking at drift, and FR-005 promises drift is reported as the
+	// discriminated conflict for every change kind — a flat refusal instead
+	// reads as a permanent "not connectable" and strands the form.
+	if err := connectRefusal(client, cfgPath); err != nil {
+		return nil, err
+	}
+
 	var res *ConnectResult
-	var err error
 	if client.Format == "toml" {
 		res, err = s.connectTOML(client, cfgPath, serverName, force)
 	} else {
-		res, err = s.connectJSON(client, cfgPath, serverName, force)
+		res, err = s.connectJSON(client, cfgPath, serverName, force, existing)
 	}
 	// A permission denial anywhere in the read/backup/write chain (the errors
 	// preserve their OS cause via %w) surfaces as a typed *AccessError with
@@ -400,6 +477,30 @@ func (s *Service) Connect(clientID, serverName string, force bool) (*ConnectResu
 	return res, s.asAccessError(client, cfgPath, err)
 }
 
+// connectRefusal reports the reason a connect would refuse for this client
+// regardless of user intent, or nil when the client is connectable.
+//
+// Today the single case is a non-create-capable client whose config is absent:
+// OpenCode owns a config schema mcpproxy will not invent, so connect refuses
+// rather than creating one. It is a package-level function, not a method,
+// precisely so the PREVIEW can run the exact same guard the write runs and
+// surface the reason verbatim before the user ever presses Connect (Spec 091
+// FR-003, research D8) — a divergent copy would let the form promise "a new
+// file will be created; Undo removes it" for a client where that is false.
+func connectRefusal(client *ClientDef, cfgPath string) error {
+	if client.ID != "opencode" {
+		return nil
+	}
+	// configPath already prefers whichever candidate exists; reaching a
+	// nonexistent path here means NO OpenCode global config was found.
+	if _, err := os.Stat(cfgPath); os.IsNotExist(err) {
+		return fmt.Errorf(
+			"no OpenCode config found (looked for opencode.jsonc and opencode.json in %s) — is OpenCode installed?",
+			filepath.Dir(cfgPath))
+	}
+	return nil
+}
+
 // Disconnect removes the MCPProxy entry from the specified client's configuration.
 func (s *Service) Disconnect(clientID, serverName string) (*ConnectResult, error) {
 	client := FindClient(clientID)
@@ -476,7 +577,12 @@ func (s *Service) guardJsoncComments(cfgPath string) error {
 	return nil
 }
 
-func (s *Service) connectJSON(client *ClientDef, cfgPath, serverName string, force bool) (*ConnectResult, error) {
+// connectJSON writes the entry, adopting the entry `resolved` names when it
+// differs from serverName. The resolution is passed in rather than recomputed
+// so the write acts on exactly the entry the preview described and the
+// precondition token hashed (Spec 091 FR-005); nil means "resolve nothing" for
+// the tokenless callers that never previewed.
+func (s *Service) connectJSON(client *ClientDef, cfgPath, serverName string, force bool, resolved *existingEntry) (*ConnectResult, error) {
 	if err := s.guardJsoncComments(cfgPath); err != nil {
 		return nil, err
 	}
@@ -508,8 +614,12 @@ func (s *Service) connectJSON(client *ClientDef, cfgPath, serverName string, for
 		action = "updated"
 	}
 
-	if client.ID == "opencode" {
-		if adoptedName, found := findEquivalentJSONServerName(serversMap, s.baseURL(), serverName); found && adoptedName != serverName {
+	// Adopt the entry the caller already resolved — never a freshly looked-up
+	// one. A key that has vanished from the file since is not adopted: there is
+	// nothing left to delete.
+	if client.ID == "opencode" && resolved != nil && resolved.name != serverName {
+		if _, present := serversMap[resolved.name]; present {
+			adoptedName := resolved.name
 			if !force {
 				return &ConnectResult{
 					Success:    true,
@@ -883,9 +993,28 @@ func (s *Service) verifyJSONEntry(path, serversKey, serverName string) error {
 	return nil
 }
 
+// findEquivalentJSONServerName resolves the entry a connect would adopt: the
+// requested name when it is already taken, otherwise an entry pointing at our
+// MCP endpoint under some other key (including the legacy ?apikey= shape) so an
+// upgrade updates the existing entry rather than duplicating it.
+//
+// The resolution is DETERMINISTIC by construction — exact name first, then the
+// lowest URL-equivalent name in sorted order. Go randomizes map iteration, and
+// this lookup feeds the preview's summary, the precondition token and the
+// write's delete: an order-dependent answer would let those cover different
+// entries, producing spurious precondition_failed refusals and, under force,
+// silently deleting an entry the user was never shown (Spec 091 FR-005).
 func findEquivalentJSONServerName(serversMap map[string]interface{}, baseURL, requestedServerName string) (string, bool) {
-	for name, rawEntry := range serversMap {
-		entry, ok := rawEntry.(map[string]interface{})
+	if _, taken := serversMap[requestedServerName]; taken {
+		return requestedServerName, true
+	}
+	names := make([]string, 0, len(serversMap))
+	for name := range serversMap {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	for _, name := range names {
+		entry, ok := serversMap[name].(map[string]interface{})
 		if !ok {
 			continue
 		}
@@ -894,15 +1023,10 @@ func findEquivalentJSONServerName(serversMap map[string]interface{}, baseURL, re
 			if !ok {
 				continue
 			}
-			// Match both a clean base URL and a legacy ?apikey= variant so an
-			// upgrade adopts/updates the existing entry rather than duplicating.
 			if entryURL == baseURL || strings.HasPrefix(entryURL, baseURL+"?") {
 				return name, true
 			}
 		}
-		if name == requestedServerName {
-			return name, true
-		}
 	}
 	return "", false
 }
diff --git a/internal/connect/connect_test.go b/internal/connect/connect_test.go
index 21808d60..6edf1355 100644
--- a/internal/connect/connect_test.go
+++ b/internal/connect/connect_test.go
@@ -1254,3 +1254,328 @@ func TestConnect_FilePermissionsPreserved(t *testing.T) {
 		t.Errorf("Expected permissions 0600, got %o", info.Mode().Perm())
 	}
 }
+
+// --- Spec 091: precondition-token guarded writes (FR-005, contracts §2) ---
+
+// backupCount reports how many timestamped backups exist beside a config, so a
+// refusal can be proven to happen BEFORE the backup step rather than after it.
+func backupCount(t *testing.T, cfgPath string) int {
+	t.Helper()
+	matches, err := filepath.Glob(cfgPath + ".bak.*")
+	if err != nil {
+		t.Fatalf("glob backups: %v", err)
+	}
+	return len(matches)
+}
+
+func readConfigT(t *testing.T, path string) string {
+	t.Helper()
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read %s: %v", path, err)
+	}
+	return string(raw)
+}
+
+// TestConnectWithPrecondition_ValidTokenWrites covers every change kind: a
+// create (absent file), an add (file present, no entry), a replace (same key)
+// and an adopted-entry replace (OpenCode, entry under a different key).
+func TestConnectWithPrecondition_ValidTokenWrites(t *testing.T) {
+	t.Run("create", func(t *testing.T) {
+		svc, home := testService(t)
+		preview, err := svc.Preview("claude-code", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		res, err := svc.ConnectWithPrecondition("claude-code", "mcpproxy", false, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("ConnectWithPrecondition: %v", err)
+		}
+		if !res.Success || res.Action != "created" {
+			t.Fatalf("expected a successful create, got %+v", res)
+		}
+		if _, err := os.Stat(ConfigPath("claude-code", home)); err != nil {
+			t.Fatalf("config should have been created: %v", err)
+		}
+	})
+
+	t.Run("add", func(t *testing.T) {
+		svc, home := testService(t)
+		seedClientConfig(t, home, "claude-code")
+		preview, err := svc.Preview("claude-code", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		res, err := svc.ConnectWithPrecondition("claude-code", "mcpproxy", false, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("ConnectWithPrecondition: %v", err)
+		}
+		if !res.Success {
+			t.Fatalf("expected success, got %+v", res)
+		}
+	})
+
+	t.Run("replace", func(t *testing.T) {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("claude-code", home)
+		writeFileT(t, cfgPath, `{"mcpServers":{"mcpproxy":{"type":"http","url":"http://127.0.0.1:9999/mcp"}}}`)
+		preview, err := svc.Preview("claude-code", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		if !preview.EntryExists {
+			t.Fatal("fixture should classify as replace")
+		}
+		// A replace sends force=true TOGETHER with the token: the token, not the
+		// absence of force, is the overwrite safety (contracts §2).
+		res, err := svc.ConnectWithPrecondition("claude-code", "mcpproxy", true, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("ConnectWithPrecondition: %v", err)
+		}
+		if !res.Success || res.Action != "updated" {
+			t.Fatalf("expected a successful replace, got %+v", res)
+		}
+		if strings.Contains(readConfigT(t, cfgPath), "9999") {
+			t.Fatal("stale entry should have been overwritten")
+		}
+	})
+
+	t.Run("adopted replace", func(t *testing.T) {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("opencode", home)
+		writeFileT(t, cfgPath, `{"mcp":{"proxy-alt":{"type":"remote","url":"http://127.0.0.1:8080/mcp"}}}`)
+		preview, err := svc.Preview("opencode", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		res, err := svc.ConnectWithPrecondition("opencode", "mcpproxy", true, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("ConnectWithPrecondition: %v", err)
+		}
+		if !res.Success {
+			t.Fatalf("expected success, got %+v", res)
+		}
+		if strings.Contains(readConfigT(t, cfgPath), "proxy-alt") {
+			t.Fatal("the adopted entry should have been replaced")
+		}
+	})
+}
+
+// TestConnectWithPrecondition_StaleTokenRefuses walks every drift class the
+// token exists to catch, and proves each refusal is inert: no write, no backup.
+func TestConnectWithPrecondition_StaleTokenRefuses(t *testing.T) {
+	t.Run("file appeared after an absent-file preview", func(t *testing.T) {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("claude-code", home)
+		preview, err := svc.Preview("claude-code", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+
+		const drifted = `{"mcpServers":{"other":{"type":"http","url":"http://127.0.0.1:7000/mcp"}}}`
+		writeFileT(t, cfgPath, drifted)
+
+		res, err := svc.ConnectWithPrecondition("claude-code", "mcpproxy", false, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		assertPreconditionRefusal(t, res, cfgPath, drifted)
+	})
+
+	t.Run("file disappeared after an add preview", func(t *testing.T) {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("claude-code", home)
+		seedClientConfig(t, home, "claude-code")
+		preview, err := svc.Preview("claude-code", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+
+		if err := os.Remove(cfgPath); err != nil {
+			t.Fatal(err)
+		}
+
+		res, err := svc.ConnectWithPrecondition("claude-code", "mcpproxy", false, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if res.Success || res.Action != "precondition_failed" {
+			t.Fatalf("expected a precondition refusal, got %+v", res)
+		}
+		if _, statErr := os.Stat(cfgPath); statErr == nil {
+			t.Fatal("a refused write must not create the config file")
+		}
+	})
+
+	t.Run("existing entry changed in a way the summary hides", func(t *testing.T) {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("claude-code", home)
+		writeFileT(t, cfgPath, `{"mcpServers":{"mcpproxy":{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"first"}}}}`)
+		preview, err := svc.Preview("claude-code", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+
+		// Only a header VALUE changes — the sanitized summary is byte-identical,
+		// so nothing but the token can catch this.
+		const drifted = `{"mcpServers":{"mcpproxy":{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"second"}}}}`
+		writeFileT(t, cfgPath, drifted)
+
+		// force=true must NOT rescue a stale token.
+		res, err := svc.ConnectWithPrecondition("claude-code", "mcpproxy", true, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		assertPreconditionRefusal(t, res, cfgPath, drifted)
+	})
+
+	t.Run("adopted entry changed under its own key", func(t *testing.T) {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("opencode", home)
+		writeFileT(t, cfgPath, `{"mcp":{"proxy-alt":{"type":"remote","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"first"}}}}`)
+		preview, err := svc.Preview("opencode", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+
+		const drifted = `{"mcp":{"proxy-alt":{"type":"remote","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"second"}}}}`
+		writeFileT(t, cfgPath, drifted)
+
+		res, err := svc.ConnectWithPrecondition("opencode", "mcpproxy", true, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		assertPreconditionRefusal(t, res, cfgPath, drifted)
+	})
+
+	t.Run("proxy-side drift changes what would be written", func(t *testing.T) {
+		home := t.TempDir()
+		t.Setenv("LOCALAPPDATA", filepath.Join(home, "AppData", "Local"))
+		t.Setenv("APPDATA", filepath.Join(home, "AppData", "Roaming"))
+		cfgPath := ConfigPath("claude-code", home)
+		const unchanged = `{"mcpServers":{}}`
+		writeFileT(t, cfgPath, unchanged)
+
+		apiKey, requireAuth := "key-one", false
+		svc := NewServiceWithHome("127.0.0.1:8080", apiKey, home).
+			WithConfigProvider(func() (string, string, bool) { return "127.0.0.1:8080", apiKey, requireAuth })
+
+		preview, err := svc.Preview("claude-code", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		if preview.ContainsAPIKey {
+			t.Fatal("fixture should preview a keyless entry")
+		}
+
+		// The user is looking at a keyless preview; auth is toggled on behind
+		// their back. Writing now would embed a credential the FR-004 notice
+		// never announced — the token must refuse even though the FILE is
+		// untouched.
+		requireAuth = true
+
+		res, err := svc.ConnectWithPrecondition("claude-code", "mcpproxy", false, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		assertPreconditionRefusal(t, res, cfgPath, unchanged)
+	})
+}
+
+// TestConnectWithPrecondition_AbsentTokenIsLegacyBehavior keeps the delta
+// backward compatible: without a token, the Web UI/CLI path behaves exactly as
+// before (contracts §2).
+func TestConnectWithPrecondition_AbsentTokenIsLegacyBehavior(t *testing.T) {
+	svc, home := testService(t)
+	cfgPath := ConfigPath("claude-code", home)
+	writeFileT(t, cfgPath, `{"mcpServers":{"mcpproxy":{"type":"http","url":"http://127.0.0.1:9999/mcp"}}}`)
+
+	res, err := svc.ConnectWithPrecondition("claude-code", "mcpproxy", false, "")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if res.Success || res.Action != "already_exists" {
+		t.Fatalf("expected the legacy already_exists refusal, got %+v", res)
+	}
+
+	// And Connect() itself is still the tokenless entry point.
+	forced, err := svc.Connect("claude-code", "mcpproxy", true)
+	if err != nil {
+		t.Fatalf("Connect: %v", err)
+	}
+	if !forced.Success || forced.Action != "updated" {
+		t.Fatalf("expected a forced update, got %+v", forced)
+	}
+}
+
+// assertPreconditionRefusal pins the refusal contract: a discriminated action
+// distinct from already_exists, a byte-identical config, and no backup — the
+// refusal happens BEFORE the backup step.
+func assertPreconditionRefusal(t *testing.T, res *ConnectResult, cfgPath, wantContent string) {
+	t.Helper()
+	if res == nil {
+		t.Fatal("expected a result, got nil")
+	}
+	if res.Success {
+		t.Fatalf("expected refusal, got success: %+v", res)
+	}
+	if res.Action != "precondition_failed" {
+		t.Fatalf("expected action precondition_failed (distinct from already_exists), got %q", res.Action)
+	}
+	if got := readConfigT(t, cfgPath); got != wantContent {
+		t.Fatalf("config must be byte-identical after a refusal:\n got:  %s\n want: %s", got, wantContent)
+	}
+	if n := backupCount(t, cfgPath); n != 0 {
+		t.Fatalf("a refused write must not create a backup, found %d", n)
+	}
+}
+
+// TestConnectWithPrecondition_OpenCodeFileVanished pins the drift contract for
+// the one client that also has a force-proof refusal. Spec 091 FR-005 lists
+// "the file disappearing after an add/replace preview" as a drift class for ALL
+// change kinds: the caller echoed a token that described an existing file, so it
+// must get the discriminated conflict and re-preview — not OpenCode's flat
+// "no config found" refusal, which reads as a permanent "not connectable" and
+// leaves the form in a dead-end failure state.
+func TestConnectWithPrecondition_OpenCodeFileVanished(t *testing.T) {
+	svc, home := testService(t)
+	cfgPath := ConfigPath("opencode", home)
+	writeFileT(t, cfgPath, `{"mcp":{}}`)
+
+	preview, err := svc.Preview("opencode", "mcpproxy")
+	if err != nil {
+		t.Fatalf("Preview: %v", err)
+	}
+	if preview.ConnectRefusal != "" {
+		t.Fatalf("a present OpenCode config is connectable, got refusal %q", preview.ConnectRefusal)
+	}
+	if preview.PreconditionToken == "" {
+		t.Fatal("expected a precondition token")
+	}
+
+	if err := os.Remove(cfgPath); err != nil {
+		t.Fatal(err)
+	}
+
+	res, err := svc.ConnectWithPrecondition("opencode", "mcpproxy", false, preview.PreconditionToken)
+	if err != nil {
+		t.Fatalf("a drifted write must be reported as a conflict, not an error: %v", err)
+	}
+	if res == nil || res.Success || res.Action != "precondition_failed" {
+		t.Fatalf("expected action precondition_failed, got %+v", res)
+	}
+	if _, statErr := os.Stat(cfgPath); statErr == nil {
+		t.Fatal("a refused write must not create the config file")
+	}
+}
+
+// Without a token the refusal is the whole answer: nothing described a
+// pre-write state, so there is no drift to report.
+func TestConnect_OpenCodeAbsentConfigStillRefuses(t *testing.T) {
+	svc, _ := testService(t)
+	if _, err := svc.Connect("opencode", "mcpproxy", false); err == nil {
+		t.Fatal("expected the absent-config refusal for a tokenless connect")
+	} else if !strings.Contains(err.Error(), "no OpenCode config found") {
+		t.Fatalf("expected the OpenCode refusal, got %v", err)
+	}
+}
diff --git a/internal/connect/path_injection_test.go b/internal/connect/path_injection_test.go
new file mode 100644
index 00000000..9127beb7
--- /dev/null
+++ b/internal/connect/path_injection_test.go
@@ -0,0 +1,74 @@
+package connect
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestConfigPathRejectsUnknownAndTraversalClientIDs pins the invariant that
+// makes CodeQL alert #164 (go/path-injection on the read/stat seams) a false
+// positive: the client ID reaching those seams comes from a URL path parameter
+// (`chi.URLParam(r, "client")`), but it is never joined into a path directly.
+// ConfigPath switches on the closed set of registry IDs and returns "" for
+// anything else, so an attacker-supplied ID cannot name a file.
+//
+// If someone later replaces the switch with a lookup that interpolates the ID
+// (e.g. filepath.Join(home, clientID+".json")), this test fails and the alert
+// stops being a false positive — which is exactly when we want to hear about it.
+func TestConfigPathRejectsUnknownAndTraversalClientIDs(t *testing.T) {
+	hostile := []string{
+		"../../../../etc/passwd",
+		"..%2f..%2fetc%2fpasswd",
+		"claude-code/../../../etc/passwd",
+		"./../.ssh/id_rsa",
+		"/etc/passwd",
+		"bogus",
+		"",
+	}
+
+	for _, id := range hostile {
+		if got := ConfigPath(id, "/home/u"); got != "" {
+			t.Errorf("ConfigPath(%q) = %q, want \"\" — an unknown client ID must never name a file", id, got)
+		}
+	}
+}
+
+// TestConfigPathKnownClientsCannotEscapeTheirRoot is the positive half: every
+// registry client resolves to a clean, traversal-free path, and any client
+// whose location derives from the supplied home directory stays inside it.
+//
+// Not every client derives from home — on Windows several correctly resolve to
+// %APPDATA% / %LOCALAPPDATA% instead — so membership is detected rather than
+// assumed: call ConfigPath with two different homes and see whether the answer
+// moves. That keeps the assertion meaningful on every platform instead of
+// encoding Unix layout.
+func TestConfigPathKnownClientsCannotEscapeTheirRoot(t *testing.T) {
+	homeA := filepath.Join(string(filepath.Separator), "home", "a")
+	homeB := filepath.Join(string(filepath.Separator), "home", "b")
+
+	for _, def := range GetAllClients() {
+		path := ConfigPath(def.ID, homeA)
+		if path == "" {
+			continue // not supported on this platform
+		}
+
+		if path != filepath.Clean(path) {
+			t.Errorf("ConfigPath(%q) = %q, want a cleaned path", def.ID, path)
+		}
+		for _, seg := range strings.Split(path, string(filepath.Separator)) {
+			if seg == ".." {
+				t.Errorf("ConfigPath(%q) = %q, want no parent-directory segments", def.ID, path)
+			}
+		}
+
+		// Home-derived? Then it must stay under the home it was given.
+		if ConfigPath(def.ID, homeB) == path {
+			continue // OS-standard location (e.g. %APPDATA%), independent of home
+		}
+		rel, err := filepath.Rel(homeA, path)
+		if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+			t.Errorf("ConfigPath(%q) = %q, want a path under %q (rel=%q, err=%v)", def.ID, path, homeA, rel, err)
+		}
+	}
+}
diff --git a/internal/connect/preview.go b/internal/connect/preview.go
index f0f42193..1a3c3174 100644
--- a/internal/connect/preview.go
+++ b/internal/connect/preview.go
@@ -35,6 +35,29 @@ type ConnectPreview struct {
 	// EntryExists (Spec 075): accessible|absent|malformed. A denied read never
 	// reaches here — it is returned as a typed *AccessError (403 + remediation).
 	AccessState string `json:"access_state"`
+
+	// ExistingEntrySummary describes the entry this connect would REPLACE, and
+	// is populated only when EntryExists (Spec 091 FR-003). It is built by
+	// construction from non-secret projections — see EntrySummary — so no
+	// arbitrary value from the user's config can ride out in a preview. It is
+	// display-only: drift detection uses PreconditionToken, never this.
+	ExistingEntrySummary *EntrySummary `json:"existing_entry_summary,omitempty"`
+
+	// PreconditionToken is the opaque, keyed digest of the raw pre-write state
+	// this preview describes plus the exact entry that would be written (Spec
+	// 091 FR-005). A caller echoes it on the subsequent write; the core
+	// recomputes and refuses with a discriminated conflict when anything has
+	// drifted — externally (the file or the target entry changed) or
+	// proxy-side (credential rotation, auth toggle, address change).
+	PreconditionToken string `json:"precondition_token"`
+
+	// ConnectRefusal carries, verbatim, the reason a connect would refuse for
+	// this client regardless of user intent — today only a non-create-capable
+	// client (OpenCode) whose config is absent. It is produced by the SAME guard
+	// the write runs, so the form can hide the Connect control and show the
+	// reason instead of letting the user discover it by clicking (Spec 091
+	// FR-003). Empty means connectable.
+	ConnectRefusal string `json:"connect_refusal,omitempty"`
 }
 
 // Preview computes the exact entry a Connect would write for the given client,
@@ -62,28 +85,16 @@ func (s *Service) Preview(clientID, serverName string) (*ConnectPreview, error)
 	// Determine create-vs-overwrite via an on-demand read. This is the same
 	// scoped, explicit-action read semantics as GetStatus: only touched when the
 	// file exists, so an absent config raises no macOS App-Data prompt.
-	accessState := accessAbsent
-	entryExists := false
-	if _, statErr := os.Stat(cfgPath); statErr == nil {
-		raw, rerr := s.read(cfgPath)
-		if rerr != nil {
-			if classifyAccess(rerr) == accessDenied {
-				// A denial must surface the actionable remediation, never a
-				// misleading "no changes" preview (Spec 078 FR-012).
-				return nil, s.newAccessError(client, cfgPath, rerr)
-			}
-			accessState = classifyAccess(rerr)
-		} else {
-			exists, parsedOK := s.previewEntryExists(*client, raw, serverName)
-			if parsedOK {
-				accessState = accessAccessible
-				entryExists = exists
-			} else {
-				// Unparseable config: the preview cannot claim "create" or
-				// "overwrite" honestly; report malformed and let the UI degrade.
-				accessState = accessMalformed
-			}
-		}
+	fileExists, existing, accessState, err := s.preWriteState(client, cfgPath, serverName)
+	if err != nil {
+		// A denial must surface the actionable remediation, never a misleading
+		// "no changes" preview (Spec 078 FR-012).
+		return nil, err
+	}
+	var existingSummary *EntrySummary
+	if existing != nil {
+		// Sanitized projections only — never the entry itself (Spec 091 FR-003).
+		existingSummary = buildEntrySummary(existing.name, existing.entry)
 	}
 
 	// Build the entry from the SAME constructor the write uses, with the
@@ -98,42 +109,132 @@ func (s *Service) Preview(clientID, serverName string) (*ConnectPreview, error)
 	}
 
 	return &ConnectPreview{
-		Client:         clientID,
-		ConfigPath:     cfgPath,
-		Format:         client.Format,
-		ServerKey:      client.ServerKey,
-		ServerName:     serverName,
-		Entry:          maskedEntry,
-		EntryText:      entryText,
-		EntryExists:    entryExists,
-		ContainsAPIKey: s.containsCredential(),
-		Bridge:         client.Bridge,
-		AccessState:    accessState,
+		Client:               clientID,
+		ConfigPath:           cfgPath,
+		Format:               client.Format,
+		ServerKey:            client.ServerKey,
+		ServerName:           serverName,
+		Entry:                maskedEntry,
+		EntryText:            entryText,
+		EntryExists:          existing != nil,
+		ContainsAPIKey:       s.containsCredential(),
+		Bridge:               client.Bridge,
+		AccessState:          accessState,
+		ExistingEntrySummary: existingSummary,
+		// The token binds THIS preview to the operation it described — this
+		// client, this file, this requested entry name — and to the state it
+		// just observed, over the unmasked pending entry the write would
+		// produce (Spec 091 FR-005).
+		PreconditionToken: s.preconditionToken(clientID, cfgPath, serverName, fileExists, existing,
+			buildServerEntry(clientID, s.entryParams(false))),
+		// Run the write's own refusal guards so the form learns "not
+		// connectable" from the preview, never from a failed click (FR-003).
+		// BOTH force-proof guards belong here: the absent-config refusal, and
+		// the commented-.jsonc refusal — a commented file parses leniently, so
+		// without this the preview would render a clean, enabled Connect for a
+		// write that always refuses.
+		ConnectRefusal: refusalText(connectRefusal(client, cfgPath), s.guardJsoncComments(cfgPath)),
 	}, nil
 }
 
-// previewEntryExists reports whether an entry under the exact serverName the
-// write would target already exists in the parsed config, and whether the bytes
-// parsed at all (parsedOK=false => malformed). It mirrors the create-vs-overwrite
-// decision connectJSON / connectTOML make (`serversMap[serverName]` presence),
-// so preview's classification matches the write's force behavior. It never
-// touches the filesystem — the caller supplies already-read bytes.
-func (s *Service) previewEntryExists(client ClientDef, raw []byte, serverName string) (exists, parsedOK bool) {
+// refusalText renders the first refusal error as its verbatim reason string, or
+// empty when every guard passed. Guards are evaluated in the order the write
+// runs them, so the reason the user is shown is the one they would have hit.
+func refusalText(errs ...error) string {
+	for _, err := range errs {
+		if err != nil {
+			return err.Error()
+		}
+	}
+	return ""
+}
+
+// preWriteState resolves the raw pre-write state shared by the preview and the
+// write's precondition check: whether the config file exists, which entry the
+// write would actually replace (adoption-aware, nil when none), and the Spec 075
+// access classification. Both callers must derive the token from the SAME
+// resolution — that is the whole point of the guarantee — so the lookup lives
+// here rather than being duplicated.
+//
+// A permission denial is returned as the typed *AccessError (403 + remediation);
+// an unreadable-but-not-denied or unparseable config yields the corresponding
+// access state with no resolved entry.
+func (s *Service) preWriteState(client *ClientDef, cfgPath, serverName string) (fileExists bool, existing *existingEntry, accessState string, err error) {
+	if _, statErr := s.stat(cfgPath); statErr != nil {
+		// ONLY "not there" is an absent config. Any other stat failure —
+		// a permission-blocked file or parent directory above all — means we do
+		// not know what is there, and reporting "absent" would render the create
+		// promise ("it will be created, and Undo removes it") over a write that
+		// cannot succeed, leaving the user to discover the denial by clicking.
+		if os.IsNotExist(statErr) {
+			return false, nil, accessAbsent, nil
+		}
+		state := classifyAccess(statErr)
+		if state == accessDenied {
+			return true, nil, state, s.newAccessError(client, cfgPath, statErr)
+		}
+		// Anything else is classified conservatively (malformed): no create
+		// promise, and the form offers no Connect control.
+		return true, nil, state, nil
+	}
+	raw, rerr := s.read(cfgPath)
+	if rerr != nil {
+		state := classifyAccess(rerr)
+		if state == accessDenied {
+			return true, nil, state, s.newAccessError(client, cfgPath, rerr)
+		}
+		return true, nil, state, nil
+	}
+	resolved, parsedOK := s.resolveExistingEntry(*client, raw, serverName)
+	if !parsedOK {
+		// Unparseable config: the preview cannot claim "create" or "overwrite"
+		// honestly; report malformed and let the UI degrade.
+		return true, nil, accessMalformed, nil
+	}
+	return true, resolved, accessAccessible, nil
+}
+
+// existingEntry is the entry a write would actually replace: the key it lives
+// under (which may differ from the requested server name after adoption), its
+// parsed value as an object (nil when the value is not one), and the raw value
+// exactly as the config held it.
+//
+// Both projections are needed: `entry` feeds the sanitized display summary,
+// which is defined over object fields, while `value` feeds the precondition
+// token, which must see every byte — a config hand-edited to hold a string, a
+// number or an array under the target key is still state the user was shown and
+// the write would clobber (Spec 091 FR-005).
+type existingEntry struct {
+	name  string
+	entry map[string]interface{}
+	value interface{}
+}
+
+// resolveExistingEntry returns the entry the write would target in the parsed
+// config — nil when there is none — and whether the bytes parsed at all
+// (parsedOK=false => malformed). It mirrors the create-vs-overwrite decision
+// connectJSON / connectTOML make (`serversMap[serverName]` presence, then
+// OpenCode's equivalent-entry adoption), so preview's classification matches the
+// write's force behavior, the sanitized summary names the key that actually
+// disappears, and the precondition token hashes the value the write would
+// clobber. It never touches the filesystem — the caller supplies already-read
+// bytes.
+func (s *Service) resolveExistingEntry(client ClientDef, raw []byte, serverName string) (found *existingEntry, parsedOK bool) {
 	var data map[string]interface{}
 	if client.Format == "toml" {
 		if _, err := toml.Decode(string(raw), &data); err != nil {
-			return false, false
+			return nil, false
 		}
 	} else if err := unmarshalLenientJSON(raw, &data); err != nil {
-		return false, false
+		return nil, false
 	}
 
 	serversMap, ok := data[client.ServerKey].(map[string]interface{})
 	if !ok {
-		return false, true
+		return nil, true
 	}
-	if _, ok := serversMap[serverName]; ok {
-		return true, true
+	if value, ok := serversMap[serverName]; ok {
+		return newExistingEntry(serverName, value), true
 	}
 	// OpenCode's write path adopts an already-installed entry pointing at our MCP
 	// URL even under a different key (incl. the legacy ?apikey= shape) and
@@ -141,11 +242,19 @@ func (s *Service) previewEntryExists(client ClientDef, raw []byte, serverName st
 	// instead of a misleading "create" that then diverges from the write (Spec
 	// 078 FR-002).
 	if client.ID == "opencode" {
-		if _, found := findEquivalentJSONServerName(serversMap, s.baseURL(), serverName); found {
-			return true, true
+		if adopted, found := findEquivalentJSONServerName(serversMap, s.baseURL(), serverName); found {
+			return newExistingEntry(adopted, serversMap[adopted]), true
 		}
 	}
-	return false, true
+	return nil, true
+}
+
+// newExistingEntry wraps a resolved config value; a non-object value yields a
+// nil entry map (the key exists, but there is nothing to project) while the raw
+// value is kept for the precondition token.
+func newExistingEntry(name string, value interface{}) *existingEntry {
+	obj, _ := value.(map[string]interface{})
+	return &existingEntry{name: name, entry: obj, value: value}
 }
 
 // renderEntrySnippet renders the entry as the merge-ready snippet in the
diff --git a/internal/connect/preview_test.go b/internal/connect/preview_test.go
index c92092e5..0b3441cd 100644
--- a/internal/connect/preview_test.go
+++ b/internal/connect/preview_test.go
@@ -560,3 +560,222 @@ func TestConnect_LegacyEntryMigration(t *testing.T) {
 		t.Fatalf("expected removed, got %s", res.Action)
 	}
 }
+
+// --- Spec 091: preview secrecy over arbitrary existing-config content ---
+
+// TestPreview_NeverLeaksExistingEntrySecrets is the adversarial half of FR-003:
+// the preview reads a client config that carries credentials in every carrier
+// mcpproxy knows about (header value, bridge --header arg, env value, ?apikey=
+// query, URL userinfo) plus a user-authored field, and asserts NONE of those
+// values appear anywhere in the serialized preview response. The proxy's own
+// live credential must not appear either — it is masked at construction.
+func TestPreview_NeverLeaksExistingEntrySecrets(t *testing.T) {
+	const liveKey = "LIVE-ROTATED-PROXY-KEY"
+
+	secrets := []string{
+		"HEADER-VALUE-SECRET", "BEARER-VALUE-SECRET", "ENV-VALUE-SECRET",
+		"QUERY-VALUE-SECRET", "USERINFO-VALUE-SECRET", "ARG-HEADER-SECRET",
+		"USER-AUTHORED-SECRET", liveKey,
+	}
+
+	cases := []struct {
+		clientID string
+		config   string
+	}{
+		{
+			clientID: "claude-code",
+			config: `{"mcpServers":{"mcpproxy":{"type":"http",` +
+				`"url":"http://user:USERINFO-VALUE-SECRET@127.0.0.1:8080/mcp?apikey=QUERY-VALUE-SECRET",` +
+				`"headers":{"X-API-Key":"HEADER-VALUE-SECRET","Authorization":"Bearer BEARER-VALUE-SECRET"},` +
+				`"env":{"TOKEN":"ENV-VALUE-SECRET"},"note":"USER-AUTHORED-SECRET"}}}`,
+		},
+		{
+			clientID: "claude-desktop",
+			config: `{"mcpServers":{"mcpproxy":{"command":"npx","args":` +
+				`["-y","mcp-remote","http://127.0.0.1:8080/mcp?apikey=QUERY-VALUE-SECRET",` +
+				`"--header","X-API-Key:ARG-HEADER-SECRET"],"env":{"TOKEN":"ENV-VALUE-SECRET"}}}}`,
+		},
+		{
+			clientID: "opencode",
+			config: `{"mcp":{"proxy-alt":{"type":"remote",` +
+				`"url":"http://127.0.0.1:8080/mcp?apikey=QUERY-VALUE-SECRET",` +
+				`"headers":{"X-API-Key":"HEADER-VALUE-SECRET"},"note":"USER-AUTHORED-SECRET"}}}`,
+		},
+	}
+
+	for _, tc := range cases {
+		tc := tc
+		t.Run(tc.clientID, func(t *testing.T) {
+			svc, home := serviceWithKey(t, liveKey)
+			svc.WithRequireMCPAuth(true)
+			cfgPath := ConfigPath(tc.clientID, home)
+			if err := os.MkdirAll(filepath.Dir(cfgPath), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			if err := os.WriteFile(cfgPath, []byte(tc.config), 0o644); err != nil {
+				t.Fatal(err)
+			}
+
+			preview, err := svc.Preview(tc.clientID, "mcpproxy")
+			if err != nil {
+				t.Fatalf("Preview: %v", err)
+			}
+			if !preview.EntryExists {
+				t.Fatalf("fixture should present an existing entry for %s", tc.clientID)
+			}
+			if preview.ExistingEntrySummary == nil {
+				t.Fatalf("expected an existing-entry summary for %s", tc.clientID)
+			}
+
+			serialized, err := json.Marshal(preview)
+			if err != nil {
+				t.Fatalf("marshal preview: %v", err)
+			}
+			for _, secret := range secrets {
+				if strings.Contains(string(serialized), secret) {
+					t.Errorf("preview leaked %q: %s", secret, serialized)
+				}
+			}
+		})
+	}
+}
+
+// TestPreview_TOMLExistingEntryNeverLeaksQuerySecret covers the TOML client's
+// ?apikey= carrier, the one shape whose credential lives inside the URL itself.
+func TestPreview_TOMLExistingEntryNeverLeaksQuerySecret(t *testing.T) {
+	svc, home := serviceWithKey(t, "LIVE-ROTATED-PROXY-KEY")
+	svc.WithRequireMCPAuth(true)
+	cfgPath := ConfigPath("codex", home)
+	if err := os.MkdirAll(filepath.Dir(cfgPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	body := "[mcp_servers.mcpproxy]\nurl = \"http://127.0.0.1:8080/mcp?apikey=CODEX-QUERY-SECRET\"\n"
+	if err := os.WriteFile(cfgPath, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	preview, err := svc.Preview("codex", "mcpproxy")
+	if err != nil {
+		t.Fatalf("Preview: %v", err)
+	}
+	serialized, err := json.Marshal(preview)
+	if err != nil {
+		t.Fatalf("marshal preview: %v", err)
+	}
+	for _, secret := range []string{"CODEX-QUERY-SECRET", "LIVE-ROTATED-PROXY-KEY"} {
+		if strings.Contains(string(serialized), secret) {
+			t.Errorf("preview leaked %q: %s", secret, serialized)
+		}
+	}
+}
+
+// --- Spec 091: the preview carries the write's refusal (research D8) ---
+
+// TestPreview_ConnectRefusal_MatchesWriteVerbatim pins FR-003's last clause: a
+// client the core will NOT create a config for (OpenCode) must surface that
+// refusal in the PREVIEW, verbatim, so the user never discovers it by clicking
+// Connect. The assertion compares against the real write's error text, which is
+// what makes "the preview runs the same guard the write would" testable rather
+// than aspirational.
+func TestPreview_ConnectRefusal_MatchesWriteVerbatim(t *testing.T) {
+	svc, _ := serviceWithKey(t, "")
+
+	preview, err := svc.Preview("opencode", "mcpproxy")
+	if err != nil {
+		t.Fatalf("Preview must still succeed and REPORT the refusal, got error: %v", err)
+	}
+	if preview.ConnectRefusal == "" {
+		t.Fatal("expected ConnectRefusal for OpenCode with no config file")
+	}
+
+	_, writeErr := svc.Connect("opencode", "mcpproxy", false)
+	if writeErr == nil {
+		t.Fatal("the write must refuse for OpenCode with no config file")
+	}
+	if preview.ConnectRefusal != writeErr.Error() {
+		t.Fatalf("refusal must be the write's reason verbatim:\n preview: %q\n write:   %q",
+			preview.ConnectRefusal, writeErr.Error())
+	}
+}
+
+// TestPreview_ConnectRefusal_EmptyWhenConnectable keeps the field strictly a
+// refusal signal: present ONLY when the write would refuse regardless of user
+// intent. A create-capable client with no config, and OpenCode WITH a config,
+// must both be connectable.
+func TestPreview_ConnectRefusal_EmptyWhenConnectable(t *testing.T) {
+	t.Run("create-capable client, absent config", func(t *testing.T) {
+		svc, _ := serviceWithKey(t, "")
+		preview, err := svc.Preview("claude-code", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		if preview.ConnectRefusal != "" {
+			t.Fatalf("claude-code is create-capable; got refusal %q", preview.ConnectRefusal)
+		}
+		if preview.AccessState != "absent" {
+			t.Fatalf("expected access_state=absent, got %q", preview.AccessState)
+		}
+	})
+
+	t.Run("opencode with an existing config", func(t *testing.T) {
+		svc, home := serviceWithKey(t, "")
+		seedClientConfig(t, home, "opencode")
+		preview, err := svc.Preview("opencode", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		if preview.ConnectRefusal != "" {
+			t.Fatalf("OpenCode with a config is connectable; got refusal %q", preview.ConnectRefusal)
+		}
+	})
+}
+
+// TestPreview_ConnectRefusal_CommentedJsonc is the second half of the refusal
+// parity guarantee (FR-003, research D8): the write has TWO force-proof refusal
+// guards, and the preview must surface both. A commented opencode.jsonc parses
+// leniently, so the preview used to report a clean, connectable "add" — and the
+// user discovered the comment refusal only by pressing Connect.
+func TestPreview_ConnectRefusal_CommentedJsonc(t *testing.T) {
+	svc, home := serviceWithKey(t, "")
+	// Platform-aware seeding: on Windows OpenCode lives under %LOCALAPPDATA%.
+	// A hardcoded ~/.config path would leave the file unread there, and this
+	// test would then pass on the absent-config refusal instead of the comment
+	// refusal it exists to check.
+	content := "{\n  // keep my comments\n  \"$schema\": \"https://opencode.ai/config.json\"\n}\n"
+	writeOpencodeFile(t, home, "opencode.jsonc", content)
+
+	preview, err := svc.Preview("opencode", "mcpproxy")
+	if err != nil {
+		t.Fatalf("Preview must report the refusal, not fail: %v", err)
+	}
+	if preview.ConnectRefusal == "" {
+		t.Fatal("expected ConnectRefusal for a commented .jsonc — the write refuses it regardless of intent")
+	}
+
+	_, writeErr := svc.Connect("opencode", "mcpproxy", false)
+	if writeErr == nil {
+		t.Fatal("the write must refuse a commented .jsonc")
+	}
+	if preview.ConnectRefusal != writeErr.Error() {
+		t.Fatalf("refusal must be the write's reason verbatim:\n preview: %q\n write:   %q",
+			preview.ConnectRefusal, writeErr.Error())
+	}
+}
+
+// A comment-free .jsonc rewrites safely (OpenCode's bootstrap stub), so it must
+// stay connectable — the guard is about comments, not about the extension.
+func TestPreview_ConnectRefusal_CommentFreeJsoncIsConnectable(t *testing.T) {
+	svc, home := serviceWithKey(t, "")
+	// Use the platform-aware helper: OpenCode resolves to %LOCALAPPDATA% on
+	// Windows, not ~/.config, so a hardcoded Unix path seeds a file the code
+	// never looks at and the preview reports "no OpenCode config found".
+	writeOpencodeFile(t, home, "opencode.jsonc", `{"$schema":"https://opencode.ai/config.json"}`)
+
+	preview, err := svc.Preview("opencode", "mcpproxy")
+	if err != nil {
+		t.Fatalf("Preview: %v", err)
+	}
+	if preview.ConnectRefusal != "" {
+		t.Fatalf("a comment-free .jsonc is connectable; got refusal %q", preview.ConnectRefusal)
+	}
+}
diff --git a/internal/connect/stat_access_test.go b/internal/connect/stat_access_test.go
new file mode 100644
index 00000000..e62f08c2
--- /dev/null
+++ b/internal/connect/stat_access_test.go
@@ -0,0 +1,141 @@
+package connect
+
+import (
+	"errors"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"runtime"
+	"syscall"
+	"testing"
+)
+
+// A config mcpproxy cannot even STAT is not an absent config. Every stat error
+// used to collapse to "absent", so a permission-blocked config rendered the
+// create promise ("this file does not exist; it will be created, and Undo
+// removes it") with the Connect control available — and the denial was
+// discovered only by clicking, which is exactly what running the write's guards
+// in the preview exists to prevent (FR-003 / Spec 075 FR-004).
+
+// denyingStat fails every stat with a permission error, the way an unreadable
+// parent directory (or a macOS App-Data block) does.
+func denyingStat(path string) (os.FileInfo, error) {
+	return nil, &fs.PathError{Op: "stat", Path: path, Err: syscall.EPERM}
+}
+
+func TestPreview_UnstattableConfigIsDeniedNotAbsent(t *testing.T) {
+	svc, home := testService(t)
+	writeFileT(t, ConfigPath("claude-code", home), `{"mcpServers":{}}`)
+	svc.setStat(denyingStat)
+
+	preview, err := svc.Preview("claude-code", "mcpproxy")
+	if err == nil {
+		t.Fatalf("a config that cannot be stat'ed must not preview as a create, got %+v", preview)
+	}
+	var accessErr *AccessError
+	if !errors.As(err, &accessErr) {
+		t.Fatalf("expected a typed *AccessError (403 + remediation), got %T: %v", err, err)
+	}
+	if accessErr.Remediation == "" {
+		t.Fatal("a denial must carry actionable remediation")
+	}
+}
+
+func TestGetStatus_UnstattableConfigIsDeniedNotAbsent(t *testing.T) {
+	svc, home := testService(t)
+	writeFileT(t, ConfigPath("claude-code", home), `{"mcpServers":{}}`)
+	svc.setStat(denyingStat)
+
+	status, err := svc.GetStatus("claude-code")
+	if err != nil {
+		t.Fatalf("GetStatus: %v", err)
+	}
+	if status.AccessState != accessDenied {
+		t.Fatalf("access_state = %q, want %q — an unstattable config is not a missing one",
+			status.AccessState, accessDenied)
+	}
+	if status.Remediation == "" {
+		t.Fatal("a denied status must carry remediation (Spec 075 FR-004)")
+	}
+}
+
+// The OpenCode resolver picks whichever candidate exists, because writing next
+// to an existing .jsonc is silently shadowed by it (#922). A candidate that
+// cannot be stat'ed must therefore be treated as present, not skipped: skipping
+// it targets the shadowed .json and the connect silently does nothing.
+func TestOpenCodeCandidate_UnstattableJsoncIsNotSkipped(t *testing.T) {
+	svc, home := testService(t)
+	dir := filepath.Dir(ConfigPath("opencode", home))
+	jsonc := filepath.Join(dir, "opencode.jsonc")
+	plain := filepath.Join(dir, "opencode.json")
+	writeFileT(t, jsonc, `{"mcp":{}}`)
+	writeFileT(t, plain, `{"mcp":{}}`)
+
+	svc.setStat(func(path string) (os.FileInfo, error) {
+		if filepath.Base(path) == "opencode.jsonc" {
+			return nil, &fs.PathError{Op: "stat", Path: path, Err: syscall.EPERM}
+		}
+		return os.Stat(path)
+	})
+
+	if got := svc.configPath("opencode"); got != jsonc {
+		t.Fatalf("configPath = %s, want the shadowing %s — a candidate we cannot stat must not be assumed absent",
+			got, jsonc)
+	}
+}
+
+// The same thing through real OS permissions rather than the seam.
+func TestPreview_PermissionBlockedParentDirIsDeniedNotAbsent(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("POSIX directory permissions do not deny stat on Windows")
+	}
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores permission bits")
+	}
+
+	svc, home := testService(t)
+	cfgPath := ConfigPath("claude-code", home)
+	writeFileT(t, cfgPath, `{"mcpServers":{}}`)
+	dir := filepath.Dir(cfgPath)
+	if err := os.Chmod(dir, 0o000); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chmod(dir, 0o755) })
+
+	if _, statErr := os.Stat(cfgPath); statErr == nil {
+		t.Skip("this filesystem still permits the stat")
+	}
+
+	preview, err := svc.Preview("claude-code", "mcpproxy")
+	if err == nil {
+		t.Fatalf("expected a denial, got a preview: access_state=%q entry_exists=%v",
+			preview.AccessState, preview.EntryExists)
+	}
+	var accessErr *AccessError
+	if !errors.As(err, &accessErr) {
+		t.Fatalf("expected a typed *AccessError, got %T: %v", err, err)
+	}
+}
+
+// The stat-only aggregate must not name the wrong problem either: it stays
+// content-read-free, but a stat it was not allowed to make is not evidence that
+// the client has no config.
+func TestGetAllStatus_UnstattableConfigIsNotSilentlyAbsent(t *testing.T) {
+	svc, _ := testService(t)
+	svc.setStat(denyingStat)
+
+	for _, st := range svc.GetAllStatus() {
+		if st.ID != "claude-code" {
+			continue
+		}
+		if st.Exists {
+			t.Fatal("a denied stat is not proof the file is there either")
+		}
+		if st.AccessState != accessDenied {
+			t.Fatalf("access_state = %q, want %q so the row does not read \"No config found\"",
+				st.AccessState, accessDenied)
+		}
+		return
+	}
+	t.Fatal("claude-code missing from GetAllStatus")
+}
diff --git a/internal/connect/summary.go b/internal/connect/summary.go
new file mode 100644
index 00000000..f961502e
--- /dev/null
+++ b/internal/connect/summary.go
@@ -0,0 +1,163 @@
+package connect
+
+import (
+	"net/url"
+	"sort"
+	"strings"
+)
+
+// EntrySummary is the sanitized, display-only description of the client-config
+// entry a connect would replace (Spec 091 FR-003).
+//
+// It exists because the preview must tell the user WHAT is being overwritten
+// without ever echoing config content: the pending entry is masked at
+// construction (entryParams substitutes the mask constant), which cannot
+// sanitize arbitrary user-authored content in an EXISTING entry. So the preview
+// renders no existing content at all — only this fixed set of parsed
+// projections, built by construction from a whitelist:
+//
+//	entry name | transport type | endpoint (query, userinfo and fragment
+//	stripped) | command | header NAMES | env NAMES
+//
+// Nothing else from the entry can reach the response: unknown fields are not
+// copied, values of headers/env are never read, and a URL-shaped field is
+// emitted only after being reparsed into scheme://host/path. Secrecy therefore
+// holds structurally rather than by masking heuristics (research D2).
+//
+// The summary is display-only: it is NEVER used for drift comparison — that is
+// the precondition token's job over the raw value (FR-005).
+type EntrySummary struct {
+	// EntryName is the key the entry actually lives under, which may differ
+	// from the requested server_name when the write adopts an equivalent entry.
+	EntryName   string   `json:"entry_name"`
+	Type        string   `json:"type,omitempty"`
+	Endpoint    string   `json:"endpoint,omitempty"`
+	Command     string   `json:"command,omitempty"`
+	HeaderNames []string `json:"header_names"`
+	EnvNames    []string `json:"env_names"`
+}
+
+// bridgeHeaderArgs are the argv flags whose following token is a
+// "Name: value" HTTP header (mcp-remote's --header). Only the NAME half is ever
+// projected.
+var bridgeHeaderArgs = map[string]bool{"--header": true, "-H": true}
+
+// buildEntrySummary projects a parsed config entry onto EntrySummary. entry may
+// be nil (an existing entry that is not an object): the summary then carries the
+// name alone, which is still the useful disclosure ("this key is replaced").
+func buildEntrySummary(entryName string, entry map[string]interface{}) *EntrySummary {
+	summary := &EntrySummary{
+		EntryName:   entryName,
+		HeaderNames: []string{},
+		EnvNames:    []string{},
+	}
+	if entry == nil {
+		return summary
+	}
+
+	if v, ok := entry["type"].(string); ok {
+		summary.Type = v
+	}
+	if v, ok := entry["command"].(string); ok {
+		summary.Command = v
+	}
+	// Endpoint carriers, in the same precedence the entry matcher uses.
+	for _, field := range []string{"url", "serverUrl", "httpUrl"} {
+		if v, ok := entry[field].(string); ok {
+			if sanitized := sanitizeEndpoint(v); sanitized != "" {
+				summary.Endpoint = sanitized
+				break
+			}
+		}
+	}
+	summary.HeaderNames = mapKeyNames(entry["headers"])
+	summary.EnvNames = mapKeyNames(entry["env"])
+
+	// Stdio-bridge entries carry the endpoint and the credential in argv. Only
+	// the URL-shaped arg (sanitized) and the header NAMES are projected; no arg
+	// value ever is.
+	if args, ok := entry["args"].([]interface{}); ok {
+		names := append([]string{}, summary.HeaderNames...)
+		expectHeader := false
+		for _, raw := range args {
+			arg, ok := raw.(string)
+			if !ok {
+				continue
+			}
+			switch {
+			case expectHeader:
+				expectHeader = false
+				if name := headerArgName(arg); name != "" {
+					names = append(names, name)
+				}
+			case bridgeHeaderArgs[arg]:
+				expectHeader = true
+			case strings.HasPrefix(arg, "--header="):
+				if name := headerArgName(strings.TrimPrefix(arg, "--header=")); name != "" {
+					names = append(names, name)
+				}
+			case summary.Endpoint == "":
+				if sanitized := sanitizeEndpoint(arg); sanitized != "" {
+					summary.Endpoint = sanitized
+				}
+			}
+		}
+		summary.HeaderNames = dedupeSorted(names)
+	}
+
+	return summary
+}
+
+// headerArgName extracts the header NAME from a "Name:value" argv token. An
+// empty result means the token had no name half and is dropped entirely.
+func headerArgName(arg string) string {
+	name, _, found := strings.Cut(arg, ":")
+	if !found {
+		return ""
+	}
+	return strings.TrimSpace(name)
+}
+
+// mapKeyNames returns the sorted KEYS of a JSON object field (headers, env).
+// Values are never touched. A non-object field yields an empty slice.
+func mapKeyNames(v interface{}) []string {
+	obj, ok := v.(map[string]interface{})
+	if !ok {
+		return []string{}
+	}
+	names := make([]string, 0, len(obj))
+	for name := range obj {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return names
+}
+
+func dedupeSorted(names []string) []string {
+	seen := make(map[string]bool, len(names))
+	out := make([]string, 0, len(names))
+	for _, n := range names {
+		if n == "" || seen[n] {
+			continue
+		}
+		seen[n] = true
+		out = append(out, n)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// sanitizeEndpoint reparses a URL-shaped value into a disclosure-safe endpoint:
+// scheme, host and path only — query (the ?apikey= credential carrier),
+// userinfo (user:pass@) and fragment are dropped. A value that is not a real
+// absolute URL is NOT projected at all (empty result): only a scheme://host
+// shape is known-safe, so an arbitrary string in a url field can never be
+// echoed back.
+func sanitizeEndpoint(raw string) string {
+	parsed, err := url.Parse(raw)
+	if err != nil || parsed.Scheme == "" || parsed.Host == "" {
+		return ""
+	}
+	clean := &url.URL{Scheme: parsed.Scheme, Host: parsed.Host, Path: parsed.Path}
+	return clean.String()
+}
diff --git a/internal/connect/summary_test.go b/internal/connect/summary_test.go
new file mode 100644
index 00000000..a54554e6
--- /dev/null
+++ b/internal/connect/summary_test.go
@@ -0,0 +1,275 @@
+package connect
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The existing-entry summary is the ONLY channel through which content of a
+// user's client config reaches a preview payload. Spec 091 FR-003 requires it to
+// be built by CONSTRUCTION from non-secret projections — entry name, transport
+// type, endpoint with query AND userinfo stripped, command, and the NAMES (never
+// the values) of headers and environment variables. These tests pin the
+// whitelist: anything not on it must not appear in the summary.
+
+func TestEntrySummary_ProjectsOnlyNonSecretFields(t *testing.T) {
+	entry := map[string]interface{}{
+		"type": "http",
+		"url":  "http://127.0.0.1:8080/mcp",
+		"headers": map[string]interface{}{
+			"X-API-Key":     "rotated-secret-value",
+			"Authorization": "Bearer sk-live-do-not-leak",
+		},
+		"env": map[string]interface{}{
+			"MCPPROXY_TOKEN": "env-secret-value",
+			"OTHER":          "another-secret",
+		},
+		// Arbitrary user-authored fields must be dropped entirely: the summary is
+		// a whitelist, not a blacklist.
+		"password": "user-authored-secret",
+		"notes":    "internal-only-secret",
+	}
+
+	got := buildEntrySummary("old-proxy", entry)
+	if got == nil {
+		t.Fatal("buildEntrySummary returned nil for a present entry")
+	}
+	if got.EntryName != "old-proxy" {
+		t.Errorf("EntryName = %q, want %q", got.EntryName, "old-proxy")
+	}
+	if got.Type != "http" {
+		t.Errorf("Type = %q, want %q", got.Type, "http")
+	}
+	if got.Endpoint != "http://127.0.0.1:8080/mcp" {
+		t.Errorf("Endpoint = %q, want %q", got.Endpoint, "http://127.0.0.1:8080/mcp")
+	}
+	if got.Command != "" {
+		t.Errorf("Command = %q, want empty", got.Command)
+	}
+	if strings.Join(got.HeaderNames, ",") != "Authorization,X-API-Key" {
+		t.Errorf("HeaderNames = %v, want sorted [Authorization X-API-Key]", got.HeaderNames)
+	}
+	if strings.Join(got.EnvNames, ",") != "MCPPROXY_TOKEN,OTHER" {
+		t.Errorf("EnvNames = %v, want sorted [MCPPROXY_TOKEN OTHER]", got.EnvNames)
+	}
+
+	serialized := mustMarshal(t, got)
+	for _, secret := range []string{
+		"rotated-secret-value", "sk-live-do-not-leak", "env-secret-value",
+		"another-secret", "user-authored-secret", "internal-only-secret",
+	} {
+		if strings.Contains(serialized, secret) {
+			t.Errorf("summary leaked %q: %s", secret, serialized)
+		}
+	}
+}
+
+func TestEntrySummary_EndpointStripsQueryAndUserinfo(t *testing.T) {
+	cases := []struct {
+		name  string
+		entry map[string]interface{}
+		want  string
+	}{
+		{
+			name:  "query stripped",
+			entry: map[string]interface{}{"url": "http://127.0.0.1:8080/mcp?apikey=QUERY-SECRET"},
+			want:  "http://127.0.0.1:8080/mcp",
+		},
+		{
+			name:  "userinfo stripped",
+			entry: map[string]interface{}{"url": "http://user:USERINFO-SECRET@127.0.0.1:8080/mcp"},
+			want:  "http://127.0.0.1:8080/mcp",
+		},
+		{
+			name:  "fragment stripped",
+			entry: map[string]interface{}{"url": "https://example.test/mcp#FRAGMENT-SECRET"},
+			want:  "https://example.test/mcp",
+		},
+		{
+			name:  "serverUrl carrier (windsurf)",
+			entry: map[string]interface{}{"serverUrl": "http://127.0.0.1:8080/mcp?apikey=QUERY-SECRET"},
+			want:  "http://127.0.0.1:8080/mcp",
+		},
+		{
+			name:  "httpUrl carrier (gemini)",
+			entry: map[string]interface{}{"httpUrl": "http://127.0.0.1:8080/mcp?apikey=QUERY-SECRET"},
+			want:  "http://127.0.0.1:8080/mcp",
+		},
+		{
+			name: "non-URL value is not projected at all",
+			// A URL field holding arbitrary user content is dropped rather than
+			// echoed: only a real scheme://host endpoint is a known-safe shape.
+			entry: map[string]interface{}{"url": "NOT-A-URL-SECRET"},
+			want:  "",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := buildEntrySummary("mcpproxy", tc.entry)
+			if got.Endpoint != tc.want {
+				t.Fatalf("Endpoint = %q, want %q", got.Endpoint, tc.want)
+			}
+			serialized := mustMarshal(t, got)
+			for _, secret := range []string{"QUERY-SECRET", "USERINFO-SECRET", "FRAGMENT-SECRET", "NOT-A-URL-SECRET"} {
+				if strings.Contains(serialized, secret) {
+					t.Fatalf("summary leaked %q: %s", secret, serialized)
+				}
+			}
+		})
+	}
+}
+
+func TestEntrySummary_BridgeEntryProjectsCommandAndHeaderNames(t *testing.T) {
+	// Claude Desktop's stdio bridge carries the endpoint and the credential in
+	// argv. Only the command, the URL-shaped arg (sanitized) and the --header
+	// NAMES are projected; no arg VALUE ever is.
+	entry := map[string]interface{}{
+		"command": "npx",
+		"args": []interface{}{
+			"-y", "mcp-remote",
+			"http://127.0.0.1:8080/mcp?apikey=ARG-QUERY-SECRET",
+			"--header", "X-API-Key:ARG-HEADER-SECRET",
+		},
+	}
+
+	got := buildEntrySummary("mcpproxy", entry)
+	if got.Command != "npx" {
+		t.Errorf("Command = %q, want npx", got.Command)
+	}
+	if got.Endpoint != "http://127.0.0.1:8080/mcp" {
+		t.Errorf("Endpoint = %q, want http://127.0.0.1:8080/mcp", got.Endpoint)
+	}
+	if strings.Join(got.HeaderNames, ",") != "X-API-Key" {
+		t.Errorf("HeaderNames = %v, want [X-API-Key]", got.HeaderNames)
+	}
+
+	serialized := mustMarshal(t, got)
+	for _, secret := range []string{"ARG-QUERY-SECRET", "ARG-HEADER-SECRET", "mcp-remote"} {
+		if strings.Contains(serialized, secret) {
+			t.Errorf("summary leaked %q: %s", secret, serialized)
+		}
+	}
+}
+
+func TestEntrySummary_IgnoresNonStringProjections(t *testing.T) {
+	entry := map[string]interface{}{
+		"type":    map[string]interface{}{"nested": "SECRET"},
+		"command": []interface{}{"SECRET"},
+		"headers": "SECRET",
+		"env":     42,
+	}
+	got := buildEntrySummary("mcpproxy", entry)
+	if got.Type != "" || got.Command != "" {
+		t.Fatalf("expected non-string projections dropped, got %+v", got)
+	}
+	if len(got.HeaderNames) != 0 || len(got.EnvNames) != 0 {
+		t.Fatalf("expected no header/env names, got %+v", got)
+	}
+	if serialized := mustMarshal(t, got); strings.Contains(serialized, "SECRET") {
+		t.Fatalf("summary leaked SECRET: %s", serialized)
+	}
+}
+
+// TestPreview_ExistingEntrySummary_NamesAdoptedEntry pins the adoption-aware
+// resolution: the summary must describe the entry the WRITE would replace, even
+// when it lives under a different key (OpenCode adoption), so the user is told
+// what actually disappears.
+func TestPreview_ExistingEntrySummary_NamesAdoptedEntry(t *testing.T) {
+	svc, home := serviceWithKey(t, "")
+	cfgPath := ConfigPath("opencode", home)
+	if err := os.MkdirAll(filepath.Dir(cfgPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(cfgPath, []byte(`{"mcp":{"proxy-alt":{"type":"remote","url":"http://127.0.0.1:8080/mcp?apikey=ADOPTED-SECRET","headers":{"X-API-Key":"ADOPTED-HEADER-SECRET"}}}}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	preview, err := svc.Preview("opencode", "mcpproxy")
+	if err != nil {
+		t.Fatalf("Preview: %v", err)
+	}
+	if !preview.EntryExists {
+		t.Fatal("expected EntryExists for the adopted entry")
+	}
+	if preview.ExistingEntrySummary == nil {
+		t.Fatal("expected ExistingEntrySummary for an existing (adopted) entry")
+	}
+	if preview.ExistingEntrySummary.EntryName != "proxy-alt" {
+		t.Errorf("summary EntryName = %q, want the adopted key %q",
+			preview.ExistingEntrySummary.EntryName, "proxy-alt")
+	}
+	if preview.ExistingEntrySummary.Type != "remote" {
+		t.Errorf("summary Type = %q, want remote", preview.ExistingEntrySummary.Type)
+	}
+	if preview.ExistingEntrySummary.Endpoint != "http://127.0.0.1:8080/mcp" {
+		t.Errorf("summary Endpoint = %q, want the query-stripped endpoint",
+			preview.ExistingEntrySummary.Endpoint)
+	}
+	if strings.Join(preview.ExistingEntrySummary.HeaderNames, ",") != "X-API-Key" {
+		t.Errorf("summary HeaderNames = %v, want [X-API-Key]", preview.ExistingEntrySummary.HeaderNames)
+	}
+}
+
+// TestPreview_ExistingEntrySummary_AbsentWhenNoEntry keeps the field strictly
+// tied to EntryExists (contracts §1: present ONLY when entry_exists=true).
+func TestPreview_ExistingEntrySummary_AbsentWhenNoEntry(t *testing.T) {
+	svc, home := serviceWithKey(t, "")
+	seedClientConfig(t, home, "claude-code")
+
+	preview, err := svc.Preview("claude-code", "mcpproxy")
+	if err != nil {
+		t.Fatalf("Preview: %v", err)
+	}
+	if preview.EntryExists {
+		t.Fatal("fixture should have no entry")
+	}
+	if preview.ExistingEntrySummary != nil {
+		t.Fatalf("expected no summary without an existing entry, got %+v", preview.ExistingEntrySummary)
+	}
+}
+
+// TestPreview_ExistingEntrySummary_TOMLClient covers the non-JSON format so the
+// summary is not silently JSON-only (Codex writes TOML).
+func TestPreview_ExistingEntrySummary_TOMLClient(t *testing.T) {
+	svc, home := serviceWithKey(t, "")
+	cfgPath := ConfigPath("codex", home)
+	if err := os.MkdirAll(filepath.Dir(cfgPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	toml := "[mcp_servers.mcpproxy]\nurl = \"http://127.0.0.1:8080/mcp?apikey=TOML-SECRET\"\n"
+	if err := os.WriteFile(cfgPath, []byte(toml), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	preview, err := svc.Preview("codex", "mcpproxy")
+	if err != nil {
+		t.Fatalf("Preview: %v", err)
+	}
+	if preview.ExistingEntrySummary == nil {
+		t.Fatal("expected ExistingEntrySummary for the existing TOML entry")
+	}
+	if preview.ExistingEntrySummary.EntryName != "mcpproxy" {
+		t.Errorf("summary EntryName = %q, want mcpproxy", preview.ExistingEntrySummary.EntryName)
+	}
+	if preview.ExistingEntrySummary.Endpoint != "http://127.0.0.1:8080/mcp" {
+		t.Errorf("summary Endpoint = %q, want the query-stripped endpoint",
+			preview.ExistingEntrySummary.Endpoint)
+	}
+	if serialized := mustMarshal(t, preview); strings.Contains(serialized, "TOML-SECRET") {
+		t.Errorf("preview leaked TOML-SECRET: %s", serialized)
+	}
+}
+
+// mustMarshal serializes v the way the HTTP layer would, so assertions run over
+// exactly the bytes that would leave the core.
+func mustMarshal(t *testing.T, v interface{}) string {
+	t.Helper()
+	b, err := json.Marshal(v)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	return string(b)
+}
diff --git a/internal/connect/token.go b/internal/connect/token.go
new file mode 100644
index 00000000..113942a4
--- /dev/null
+++ b/internal/connect/token.go
@@ -0,0 +1,198 @@
+package connect
+
+import (
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/binary"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"hash"
+)
+
+// tokenDomain namespaces the HMAC input so a token can never be confused with a
+// digest computed elsewhere over similar-looking material.
+const tokenDomain = "mcpproxy/connect/precondition/v1"
+
+// preconditionKeyLen is the per-core-instance random key size (256 bits, matching
+// the HMAC-SHA256 block security level).
+const preconditionKeyLen = 32
+
+// PreconditionState is everything a precondition token binds a rendered preview
+// to: the operation it described AND the pre-write state it observed. Two
+// operations that would touch the config differently must differ in at least
+// one field here, or a token minted for one authorizes the other.
+type PreconditionState struct {
+	// ClientID scopes the token to one client's connect flow.
+	ClientID string
+	// ConfigPath is which file is being written.
+	ConfigPath string
+	// Requested is the entry name the caller asked for — the key the write
+	// creates when nothing is adopted. It is NOT implied by ResolvedEntryName:
+	// that one is empty for every absent target, so without this a preview for
+	// one name validated a write under any other.
+	Requested string
+	// FileExists distinguishes create from update (a file appearing or
+	// vanishing between preview and write).
+	FileExists bool
+	// ResolvedEntryName is the key the write would replace, AFTER the same
+	// equivalent-entry adoption the write performs. Empty when none resolved.
+	ResolvedEntryName string
+	// RawResolvedEntry is that entry's value; nil when there is none. It
+	// includes values the sanitized summary deliberately hides, so a credential
+	// rotation inside the existing entry drifts.
+	RawResolvedEntry json.RawMessage
+	// PendingEntry is the entry the proxy would write right now, so proxy-side
+	// drift (API-key rotation, require_mcp_auth toggle, listen-address change)
+	// invalidates the preview too — otherwise a credential could be embedded
+	// without the FR-004 notice ever having been shown.
+	PendingEntry json.RawMessage
+}
+
+// DerivePreconditionToken computes the opaque precondition token that binds a
+// rendered connect preview to the exact operation and pre-write state it
+// described (Spec 091 FR-005).
+//
+// It is an HMAC-SHA256, hex-encoded, over a canonical LENGTH-PREFIXED encoding
+// of every field, so:
+//
+//   - no two distinct states share a preimage — a byte moved from one field into
+//     the next changes the encoding, which a delimiter- or concatenation-based
+//     scheme would not catch;
+//   - the token is KEYED with a per-core-instance random in-memory key, so it is
+//     not an offline confirmation oracle: an attacker who knows everything about
+//     the state except a masked or weak credential still cannot test guesses.
+//
+// The token is never persisted and never leaves this process except as an opaque
+// string in the preview response.
+func DerivePreconditionToken(key []byte, state PreconditionState) string {
+	mac := hmac.New(sha256.New, key)
+	writeTokenField(mac, []byte(tokenDomain))
+	writeTokenField(mac, []byte(state.ClientID))
+	writeTokenField(mac, []byte(state.ConfigPath))
+	writeTokenField(mac, []byte(state.Requested))
+	writeTokenField(mac, []byte{boolByte(state.FileExists)})
+	// Presence is its own field so "entry absent" and "entry present but empty"
+	// can never encode identically.
+	writeTokenField(mac, []byte{boolByte(state.RawResolvedEntry != nil)})
+	writeTokenField(mac, []byte(state.ResolvedEntryName))
+	writeTokenField(mac, state.RawResolvedEntry)
+	writeTokenField(mac, state.PendingEntry)
+	return hex.EncodeToString(mac.Sum(nil))
+}
+
+// writeTokenField appends one length-prefixed field (8-byte big-endian length,
+// then the bytes) to the running MAC. hash.Hash writes never fail.
+func writeTokenField(h hash.Hash, field []byte) {
+	var lengthPrefix [8]byte
+	binary.BigEndian.PutUint64(lengthPrefix[:], uint64(len(field)))
+	_, _ = h.Write(lengthPrefix[:])
+	_, _ = h.Write(field)
+}
+
+func boolByte(v bool) byte {
+	if v {
+		return 1
+	}
+	return 0
+}
+
+// preconditionKey returns this Service's in-memory HMAC key, generating it on
+// first use. The key lives only for the life of the process, which is precisely
+// the intended token lifetime: a preview minted by one core instance is
+// meaningless to another (and to a restarted one), so a stale token can never
+// authorize a write against state it never observed.
+func (s *Service) preconditionKey() []byte {
+	s.tokenKeyOnce.Do(func() {
+		key := make([]byte, preconditionKeyLen)
+		if _, err := rand.Read(key); err != nil {
+			// crypto/rand failure is fatal for the guarantee; fall back to a
+			// key that still differs per Service value rather than a constant.
+			panic("connect: cannot generate precondition key: " + err.Error())
+		}
+		s.tokenKey = key
+	})
+	return s.tokenKey
+}
+
+// preconditionToken derives the token for a resolved pre-write state under this
+// Service's key. existing is nil when no entry would be replaced.
+//
+// The raw entry is re-marshaled canonically (encoding/json sorts object keys)
+// rather than hashed as source bytes, so reformatting the config alone does not
+// invalidate a preview while any semantic change to the entry does.
+func (s *Service) preconditionToken(clientID, cfgPath, requestedName string, fileExists bool, existing *existingEntry, pendingEntry map[string]interface{}) string {
+	var resolvedName string
+	var rawResolved json.RawMessage
+	if existing != nil {
+		resolvedName = existing.name
+		// The RAW value, not the object projection: hashing the projection
+		// collapsed every non-object value (string, number, array) into the same
+		// "null" digest, hiding drift between two of them.
+		rawResolved = canonicalJSON(existing.value)
+	}
+	return DerivePreconditionToken(s.preconditionKey(), PreconditionState{
+		ClientID:          clientID,
+		ConfigPath:        cfgPath,
+		Requested:         requestedName,
+		FileExists:        fileExists,
+		ResolvedEntryName: resolvedName,
+		RawResolvedEntry:  rawResolved,
+		PendingEntry:      canonicalJSON(pendingEntry),
+	})
+}
+
+// actionPreconditionFailed is the machine-readable discriminator for a write
+// refused because the preview it echoed no longer describes reality. It is
+// deliberately distinct from "already_exists": that one means "an entry is
+// there, pass force"; this one means "your view is stale, re-preview" — a client
+// that confused the two would either loop forever or force a write over state
+// the user never saw (research D9).
+const actionPreconditionFailed = "precondition_failed"
+
+// checkPrecondition recomputes the token for the pre-write state the caller
+// resolved and compares it with the one the caller echoed from its preview. It
+// returns a refusal result on drift and nil when the precondition holds.
+//
+// The state is passed in, not re-resolved: the write acts on exactly this
+// resolution, so checking a second, independently-resolved one would compare a
+// state neither the preview nor the write ever used (Spec 091 FR-005).
+func (s *Service) checkPrecondition(client *ClientDef, cfgPath, serverName, token string, fileExists bool, existing *existingEntry) *ConnectResult {
+	// serverName rides INTO the MAC, not just into the message below: it is the
+	// key this write would create, and a token that ignored it could be
+	// replayed under a different name the user never previewed.
+	current := s.preconditionToken(client.ID, cfgPath, serverName, fileExists, existing,
+		buildServerEntry(client.ID, s.entryParams(false)))
+	// Constant-time: the token is a MAC, and a byte-at-a-time comparison would
+	// leak enough to forge one.
+	if hmac.Equal([]byte(current), []byte(token)) {
+		return nil
+	}
+	return &ConnectResult{
+		Success:    false,
+		Client:     client.ID,
+		ConfigPath: cfgPath,
+		ServerName: serverName,
+		Action:     actionPreconditionFailed,
+		Message: fmt.Sprintf(
+			"%s or the entry MCPProxy would write changed since the preview was generated; nothing was written — re-run the preview and confirm the new change",
+			cfgPath),
+	}
+}
+
+// canonicalJSON marshals a parsed value deterministically (encoding/json sorts
+// object keys), so reformatting the config alone does not invalidate a preview
+// while any semantic change does. A JSON-null value still yields a non-nil
+// "null" payload, which the presence field keeps distinguishable from an absent
+// entry (that one passes nil directly).
+func canonicalJSON(v interface{}) json.RawMessage {
+	encoded, err := json.Marshal(v)
+	if err != nil {
+		// Values here come from encoding/json or toml decoding, so this is
+		// unreachable in practice; hash the error text rather than silently
+		// hashing nothing (which would weaken drift detection).
+		return json.RawMessage("marshal-error:" + err.Error())
+	}
+	return encoded
+}
diff --git a/internal/connect/token_test.go b/internal/connect/token_test.go
new file mode 100644
index 00000000..5cc606be
--- /dev/null
+++ b/internal/connect/token_test.go
@@ -0,0 +1,523 @@
+package connect
+
+import (
+	"encoding/hex"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The precondition token binds a rendered preview to the exact pre-write state
+// it described (Spec 091 FR-005). It must be:
+//
+//   - KEYED (HMAC-SHA256 with a per-core-instance in-memory key), so it is not
+//     an offline confirmation oracle for a masked or weak secret whose preimage
+//     is otherwise fully known;
+//   - computed over a CANONICAL, LENGTH-PREFIXED encoding, so no two distinct
+//     states can encode to the same byte string;
+//   - sensitive to every drift class: file existence, the resolved (possibly
+//     adopted) entry's presence and raw value — including values the sanitized
+//     summary deliberately hides — and the pending entry the proxy would write.
+
+var (
+	tokenKeyA = []byte("key-a-0123456789abcdef0123456789")
+	tokenKeyB = []byte("key-b-0123456789abcdef0123456789")
+)
+
+func TestDerivePreconditionToken_DeterministicPerKey(t *testing.T) {
+	raw := json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp"}`)
+	pending := json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp"}`)
+
+	first := DerivePreconditionToken(tokenKeyA, PreconditionState{
+		ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+		ResolvedEntryName: "mcpproxy", RawResolvedEntry: raw, PendingEntry: pending})
+	second := DerivePreconditionToken(tokenKeyA, PreconditionState{
+		ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+		ResolvedEntryName: "mcpproxy", RawResolvedEntry: raw, PendingEntry: pending})
+	if first != second {
+		t.Fatalf("token not deterministic: %q vs %q", first, second)
+	}
+	if first == "" {
+		t.Fatal("token must not be empty")
+	}
+	// HMAC-SHA256, hex-encoded.
+	if len(first) != 64 {
+		t.Fatalf("token length = %d, want 64 hex chars (HMAC-SHA256)", len(first))
+	}
+	if _, err := hex.DecodeString(first); err != nil {
+		t.Fatalf("token is not hex: %v", err)
+	}
+}
+
+func TestDerivePreconditionToken_DifferentKeyDifferentToken(t *testing.T) {
+	raw := json.RawMessage(`{"url":"http://127.0.0.1:8080/mcp"}`)
+	pending := json.RawMessage(`{"url":"http://127.0.0.1:8080/mcp"}`)
+
+	a := DerivePreconditionToken(tokenKeyA, PreconditionState{
+		ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+		ResolvedEntryName: "mcpproxy", RawResolvedEntry: raw, PendingEntry: pending})
+	b := DerivePreconditionToken(tokenKeyB, PreconditionState{
+		ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+		ResolvedEntryName: "mcpproxy", RawResolvedEntry: raw, PendingEntry: pending})
+	if a == b {
+		t.Fatal("tokens must differ under different keys (the key is what makes the token non-forgeable)")
+	}
+}
+
+func TestDerivePreconditionToken_DistinctPerDriftClass(t *testing.T) {
+	base := func() string {
+		return DerivePreconditionToken(tokenKeyA, PreconditionState{
+			ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+			ResolvedEntryName: "mcpproxy", RawResolvedEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"old"}}`), PendingEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp"}`)})
+	}
+
+	cases := []struct {
+		name string
+		got  string
+	}{
+		{
+			name: "file existence flipped",
+			got: DerivePreconditionToken(tokenKeyA, PreconditionState{
+				ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: false,
+				ResolvedEntryName: "mcpproxy", RawResolvedEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"old"}}`), PendingEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp"}`)}),
+		},
+		{
+			name: "resolved entry absent",
+			got: DerivePreconditionToken(tokenKeyA, PreconditionState{
+				ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+				ResolvedEntryName: "", RawResolvedEntry: nil, PendingEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp"}`)}),
+		},
+		{
+			name: "resolved entry lives under an adopted key",
+			got: DerivePreconditionToken(tokenKeyA, PreconditionState{
+				ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+				ResolvedEntryName: "proxy-alt", RawResolvedEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"old"}}`), PendingEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp"}`)}),
+		},
+		{
+			name: "masked credential value of the existing entry changed",
+			got: DerivePreconditionToken(tokenKeyA, PreconditionState{
+				ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+				ResolvedEntryName: "mcpproxy", RawResolvedEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"rotated"}}`), PendingEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp"}`)}),
+		},
+		{
+			name: "pending entry changed (proxy-side drift)",
+			got: DerivePreconditionToken(tokenKeyA, PreconditionState{
+				ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+				ResolvedEntryName: "mcpproxy", RawResolvedEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"old"}}`), PendingEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:9090/mcp"}`)}),
+		},
+		{
+			name: "config path changed",
+			got: DerivePreconditionToken(tokenKeyA, PreconditionState{
+				ConfigPath: "/other.json", Requested: "mcpproxy", FileExists: true,
+				ResolvedEntryName: "mcpproxy", RawResolvedEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"old"}}`), PendingEntry: json.RawMessage(`{"type":"http","url":"http://127.0.0.1:8080/mcp"}`)}),
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if tc.got == base() {
+				t.Fatalf("token must change when %s", tc.name)
+			}
+		})
+	}
+}
+
+// TestDerivePreconditionToken_LengthPrefixedEncoding pins the canonical encoding:
+// with a naive separator-free or delimiter-joined concatenation, shifting a byte
+// from one field to the next produces the same preimage. Length prefixes make
+// that impossible.
+func TestDerivePreconditionToken_LengthPrefixedEncoding(t *testing.T) {
+	pending := json.RawMessage(`{}`)
+	a := DerivePreconditionToken(tokenKeyA, PreconditionState{
+		ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+		ResolvedEntryName: "ab", RawResolvedEntry: json.RawMessage(`"c"`), PendingEntry: pending})
+	b := DerivePreconditionToken(tokenKeyA, PreconditionState{
+		ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+		ResolvedEntryName: "a", RawResolvedEntry: json.RawMessage(`b"c"`), PendingEntry: pending})
+	if a == b {
+		t.Fatal("field boundaries are ambiguous: encoding is not length-prefixed")
+	}
+
+	c := DerivePreconditionToken(tokenKeyA, PreconditionState{
+		ConfigPath: "/cfg", Requested: "mcpproxy", FileExists: true,
+		ResolvedEntryName: ".jsonmcpproxy", RawResolvedEntry: nil, PendingEntry: pending})
+	d := DerivePreconditionToken(tokenKeyA, PreconditionState{
+		ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+		ResolvedEntryName: "mcpproxy", RawResolvedEntry: nil, PendingEntry: pending})
+	if c == d {
+		t.Fatal("path/name boundary is ambiguous: encoding is not length-prefixed")
+	}
+}
+
+// TestDerivePreconditionToken_CarriesNoSecretSubstring: the token is a
+// fixed-width HMAC digest, so no fragment of the hashed state — least of all a
+// credential — can survive into it.
+func TestDerivePreconditionToken_CarriesNoSecretSubstring(t *testing.T) {
+	const secret = "SUPER-SECRET-CREDENTIAL"
+	token := DerivePreconditionToken(tokenKeyA, PreconditionState{
+		ConfigPath: "/cfg.json", Requested: "mcpproxy", FileExists: true,
+		ResolvedEntryName: "mcpproxy",
+		RawResolvedEntry:  json.RawMessage(`{"headers":{"X-API-Key":"` + secret + `"}}`),
+		PendingEntry:      json.RawMessage(`{"headers":{"X-API-Key":"` + secret + `"}}`)})
+	if strings.Contains(token, secret) {
+		t.Fatalf("token leaked the secret: %s", token)
+	}
+	for _, frag := range []string{"SUPER", "SECRET", "CREDENTIAL", "X-API-Key"} {
+		if strings.Contains(token, frag) {
+			t.Fatalf("token leaked %q: %s", frag, token)
+		}
+	}
+}
+
+// --- Service-level wiring: the preview carries a token over its own state ---
+
+func TestPreview_PreconditionToken_StableForUnchangedState(t *testing.T) {
+	svc, home := serviceWithKey(t, "")
+	seedClientConfig(t, home, "claude-code")
+
+	first := previewToken(t, svc, "claude-code")
+	second := previewToken(t, svc, "claude-code")
+	if first != second {
+		t.Fatalf("token must be stable while nothing drifts: %q vs %q", first, second)
+	}
+	if first == "" {
+		t.Fatal("preview must always carry a precondition token")
+	}
+}
+
+func TestPreview_PreconditionToken_PerInstanceKey(t *testing.T) {
+	// Tokens are single-session by design: a second core instance must not
+	// accept a token minted by the first.
+	home := t.TempDir()
+	t.Setenv("LOCALAPPDATA", filepath.Join(home, "AppData", "Local"))
+	t.Setenv("APPDATA", filepath.Join(home, "AppData", "Roaming"))
+	seedClientConfig(t, home, "claude-code")
+
+	a := NewServiceWithHome("127.0.0.1:8080", "", home)
+	b := NewServiceWithHome("127.0.0.1:8080", "", home)
+	if previewToken(t, a, "claude-code") == previewToken(t, b, "claude-code") {
+		t.Fatal("two service instances must derive tokens under different keys")
+	}
+}
+
+func TestPreview_PreconditionToken_FileAndEntryDrift(t *testing.T) {
+	svc, home := serviceWithKey(t, "")
+	cfgPath := ConfigPath("claude-code", home)
+
+	absent := previewToken(t, svc, "claude-code")
+
+	seedClientConfig(t, home, "claude-code")
+	present := previewToken(t, svc, "claude-code")
+	if present == absent {
+		t.Fatal("token must change when the config file appears")
+	}
+
+	writeFileT(t, cfgPath, `{"mcpServers":{"mcpproxy":{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"first"}}}}`)
+	withEntry := previewToken(t, svc, "claude-code")
+	if withEntry == present {
+		t.Fatal("token must change when the resolved entry appears")
+	}
+
+	// A change the sanitized summary deliberately hides (header VALUE) must
+	// still invalidate the token — the summary is display-only.
+	writeFileT(t, cfgPath, `{"mcpServers":{"mcpproxy":{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"second"}}}}`)
+	if rotated := previewToken(t, svc, "claude-code"); rotated == withEntry {
+		t.Fatal("token must change when a hidden (masked) value of the existing entry changes")
+	}
+}
+
+func TestPreview_PreconditionToken_AdoptedEntryDrift(t *testing.T) {
+	svc, home := serviceWithKey(t, "")
+	cfgPath := ConfigPath("opencode", home)
+	if err := os.MkdirAll(filepath.Dir(cfgPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	writeFileT(t, cfgPath, `{"mcp":{"proxy-alt":{"type":"remote","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"first"}}}}`)
+	before := previewToken(t, svc, "opencode")
+
+	// The adopted entry lives under a DIFFERENT key than the requested one; a
+	// change to it is exactly the drift class an unresolved serversMap[name]
+	// lookup would miss.
+	writeFileT(t, cfgPath, `{"mcp":{"proxy-alt":{"type":"remote","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"second"}}}}`)
+	if after := previewToken(t, svc, "opencode"); after == before {
+		t.Fatal("token must change when the ADOPTED entry changes under its own key")
+	}
+}
+
+func TestPreview_PreconditionToken_PendingEntryDrift(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("LOCALAPPDATA", filepath.Join(home, "AppData", "Local"))
+	t.Setenv("APPDATA", filepath.Join(home, "AppData", "Roaming"))
+	seedClientConfig(t, home, "claude-code")
+
+	listenAddr, apiKey, requireAuth := "127.0.0.1:8080", "key-one", false
+	svc := NewServiceWithHome(listenAddr, apiKey, home).
+		WithConfigProvider(func() (string, string, bool) { return listenAddr, apiKey, requireAuth })
+
+	base := previewToken(t, svc, "claude-code")
+
+	// require_mcp_auth toggled on: the pending entry gains the credential —
+	// the FR-004 notice the user never saw. The token must invalidate.
+	requireAuth = true
+	authOn := previewToken(t, svc, "claude-code")
+	if authOn == base {
+		t.Fatal("token must change when require_mcp_auth flips the pending entry")
+	}
+
+	// Credential rotated while the preview was on screen.
+	apiKey = "key-two"
+	rotated := previewToken(t, svc, "claude-code")
+	if rotated == authOn {
+		t.Fatal("token must change when the API key rotates")
+	}
+
+	// Listen address changed: the entry would point somewhere else.
+	listenAddr = "127.0.0.1:9090"
+	if moved := previewToken(t, svc, "claude-code"); moved == rotated {
+		t.Fatal("token must change when the listen address changes")
+	}
+}
+
+// previewToken runs a preview and returns its precondition token.
+func previewToken(t *testing.T, svc *Service, clientID string) string {
+	t.Helper()
+	preview, err := svc.Preview(clientID, "mcpproxy")
+	if err != nil {
+		t.Fatalf("Preview(%s): %v", clientID, err)
+	}
+	return preview.PreconditionToken
+}
+
+func writeFileT(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// TestPreview_PreconditionToken_NonObjectEntryDrift closes the drift class the
+// map projection hid: a resolved entry whose value is NOT an object (a
+// hand-edited string, number or array) used to canonicalize to the constant
+// "null", so two entirely different values produced byte-identical tokens and
+// the write proceeded over state the user never saw (FR-005).
+func TestPreview_PreconditionToken_NonObjectEntryDrift(t *testing.T) {
+	svc, home := serviceWithKey(t, "")
+	cfgPath := ConfigPath("claude-code", home)
+
+	values := []string{
+		`"http://old-endpoint"`,
+		`"http://new-endpoint"`,
+		`["http://a"]`,
+		`["http://b"]`,
+		`42`,
+		`null`,
+		`{"type":"http","url":"http://127.0.0.1:8080/mcp"}`,
+	}
+	seen := map[string]string{}
+	for _, value := range values {
+		writeFileT(t, cfgPath, `{"mcpServers":{"mcpproxy":`+value+`}}`)
+		token := previewToken(t, svc, "claude-code")
+		if other, clash := seen[token]; clash {
+			t.Fatalf("entry values %s and %s produce the SAME token — drift between them is invisible", other, value)
+		}
+		seen[token] = value
+	}
+
+	// And an absent entry must still be distinguishable from a present one
+	// whose value happens to be JSON null.
+	writeFileT(t, cfgPath, `{"mcpServers":{}}`)
+	absentEntry := previewToken(t, svc, "claude-code")
+	writeFileT(t, cfgPath, `{"mcpServers":{"mcpproxy":null}}`)
+	if nullEntry := previewToken(t, svc, "claude-code"); nullEntry == absentEntry {
+		t.Fatal("a present entry valued null must not hash like an absent one")
+	}
+}
+
+// The write side of the same class: a valid token minted over a non-object
+// entry must be refused once that value changes — force must not rescue it.
+func TestConnectWithPrecondition_NonObjectEntryDriftRefuses(t *testing.T) {
+	t.Run("array value changed", func(t *testing.T) {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("claude-code", home)
+		writeFileT(t, cfgPath, `{"mcpServers":{"mcpproxy":["http://a"]}}`)
+		preview, err := svc.Preview("claude-code", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		if !preview.EntryExists {
+			t.Fatal("a present non-object value is still an existing entry")
+		}
+
+		const drifted = `{"mcpServers":{"mcpproxy":["http://totally-different"]}}`
+		writeFileT(t, cfgPath, drifted)
+
+		res, err := svc.ConnectWithPrecondition("claude-code", "mcpproxy", true, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		assertPreconditionRefusal(t, res, cfgPath, drifted)
+	})
+
+	t.Run("string value changed", func(t *testing.T) {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("claude-code", home)
+		writeFileT(t, cfgPath, `{"mcpServers":{"mcpproxy":"http://old-endpoint"}}`)
+		preview, err := svc.Preview("claude-code", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+
+		const drifted = `{"mcpServers":{"mcpproxy":"http://new-endpoint"}}`
+		writeFileT(t, cfgPath, drifted)
+
+		res, err := svc.ConnectWithPrecondition("claude-code", "mcpproxy", true, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		assertPreconditionRefusal(t, res, cfgPath, drifted)
+	})
+
+	t.Run("an unchanged non-object entry still writes", func(t *testing.T) {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("claude-code", home)
+		writeFileT(t, cfgPath, `{"mcpServers":{"mcpproxy":"http://old-endpoint"}}`)
+		preview, err := svc.Preview("claude-code", "mcpproxy")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		res, err := svc.ConnectWithPrecondition("claude-code", "mcpproxy", true, preview.PreconditionToken)
+		if err != nil {
+			t.Fatalf("ConnectWithPrecondition: %v", err)
+		}
+		if !res.Success {
+			t.Fatalf("an unchanged config must still write, got %+v", res)
+		}
+	})
+}
+
+// The token binds a preview to the entry the write would produce, so the
+// REQUESTED name is part of that binding. It used to be absent from the
+// preimage: only the RESOLVED name was hashed, and that is the empty string
+// whenever the target entry does not exist yet. Two previews for two different
+// names over the same config therefore produced the same token, and one could
+// be replayed to create a key the user never previewed.
+func TestPreconditionToken_BoundToTheRequestedEntryName(t *testing.T) {
+	t.Run("two absent targets do not share a token", func(t *testing.T) {
+		svc, home := serviceWithKey(t, "")
+		writeFileT(t, ConfigPath("claude-code", home), `{"mcpServers":{}}`)
+
+		alpha, err := svc.Preview("claude-code", "alpha")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		beta, err := svc.Preview("claude-code", "beta")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		if alpha.PreconditionToken == beta.PreconditionToken {
+			t.Fatal("previews for different entry names must not share a token")
+		}
+	})
+
+	t.Run("two requested names adopting the same entry do not share a token", func(t *testing.T) {
+		svc, home := serviceWithKey(t, "")
+		writeFileT(t, ConfigPath("opencode", home),
+			`{"mcp":{"legacy":{"type":"remote","url":"http://127.0.0.1:8080/mcp"}}}`)
+
+		alpha, err := svc.Preview("opencode", "alpha")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		beta, err := svc.Preview("opencode", "beta")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		if alpha.ExistingEntrySummary == nil || alpha.ExistingEntrySummary.EntryName != "legacy" {
+			t.Fatalf("precondition: both previews must adopt the same entry, got %+v", alpha.ExistingEntrySummary)
+		}
+		if alpha.PreconditionToken == beta.PreconditionToken {
+			t.Fatal("previews that would write DIFFERENT keys must not share a token")
+		}
+	})
+
+	t.Run("the client is part of the binding", func(t *testing.T) {
+		state := PreconditionState{
+			ConfigPath:   "/cfg.json",
+			Requested:    "mcpproxy",
+			FileExists:   true,
+			PendingEntry: json.RawMessage(`{"type":"http"}`),
+		}
+		other := state
+		other.ClientID = "cursor"
+		if DerivePreconditionToken(tokenKeyA, state) == DerivePreconditionToken(tokenKeyA, other) {
+			t.Fatal("a token minted for one client must not validate for another")
+		}
+	})
+}
+
+// The end of the same story: a token minted for one entry name must not
+// authorize a write under another. Nothing is written, and the refusal is the
+// ordinary discriminated conflict.
+func TestConnectWithPrecondition_TokenIsNotTransferableToAnotherName(t *testing.T) {
+	t.Run("absent target", func(t *testing.T) {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("claude-code", home)
+		const original = `{"mcpServers":{}}`
+		writeFileT(t, cfgPath, original)
+
+		alpha, err := svc.Preview("claude-code", "alpha")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+
+		res, err := svc.ConnectWithPrecondition("claude-code", "beta", false, alpha.PreconditionToken)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		assertPreconditionRefusal(t, res, cfgPath, original)
+		if strings.Contains(readConfigT(t, cfgPath), "beta") {
+			t.Fatal("a replayed token must not create an entry the user never previewed")
+		}
+	})
+
+	t.Run("adopted target", func(t *testing.T) {
+		svc, home := testService(t)
+		cfgPath := ConfigPath("opencode", home)
+		const original = `{"mcp":{"legacy":{"type":"remote","url":"http://127.0.0.1:8080/mcp"}}}`
+		writeFileT(t, cfgPath, original)
+
+		alpha, err := svc.Preview("opencode", "alpha")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+
+		// force rides with the token, and must not rescue a name substitution.
+		res, err := svc.ConnectWithPrecondition("opencode", "beta", true, alpha.PreconditionToken)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		assertPreconditionRefusal(t, res, cfgPath, original)
+	})
+
+	t.Run("the previewed name still writes", func(t *testing.T) {
+		svc, home := testService(t)
+		writeFileT(t, ConfigPath("claude-code", home), `{"mcpServers":{}}`)
+
+		alpha, err := svc.Preview("claude-code", "alpha")
+		if err != nil {
+			t.Fatalf("Preview: %v", err)
+		}
+		res, err := svc.ConnectWithPrecondition("claude-code", "alpha", false, alpha.PreconditionToken)
+		if err != nil {
+			t.Fatalf("ConnectWithPrecondition: %v", err)
+		}
+		if !res.Success {
+			t.Fatalf("the previewed name must still write, got %+v", res)
+		}
+	})
+}
diff --git a/internal/httpapi/connect.go b/internal/httpapi/connect.go
index 231e7257..a0f9c163 100644
--- a/internal/httpapi/connect.go
+++ b/internal/httpapi/connect.go
@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"net/http"
 
 	"github.com/go-chi/chi/v5"
@@ -15,6 +16,30 @@ import (
 type ConnectRequest struct {
 	ServerName string `json:"server_name,omitempty"` // Defaults to "mcpproxy"
 	Force      bool   `json:"force,omitempty"`       // Overwrite existing entry
+	// PreconditionToken is the opaque token from the preview this write was
+	// confirmed against (Spec 091 FR-005). When present, the core rechecks it
+	// at write time and responds 409 with action "precondition_failed" —
+	// writing nothing — if the config or the entry MCPProxy would write has
+	// drifted since; the caller then re-previews instead of retrying. Absent
+	// means exactly the pre-091 behavior. A replace-classified flow sends this
+	// TOGETHER with force=true: the token, not the absence of force, is the
+	// overwrite safety.
+	PreconditionToken string `json:"precondition_token,omitempty"`
+}
+
+// ConnectConflictResponse is the 409 body of POST /api/v1/connect/{client}.
+//
+// It is a typed response rather than the generic error shape because Action is
+// the machine-readable discriminator the contract depends on: "already_exists"
+// means "an entry is there, pass force", "precondition_failed" means "your
+// preview is stale, re-preview". A client that cannot tell them apart either
+// loops forever or forces a write over state the user never saw (research D9),
+// so the field must be visible in the OpenAPI document, not only in prose.
+type ConnectConflictResponse struct {
+	Success bool                  `json:"success"` // Always false
+	Data    connect.ConnectResult `json:"data"`    // The full result; its action mirrors the top-level one
+	Error   string                `json:"error"`   // Human-readable message
+	Action  string                `json:"action"`  // already_exists | precondition_failed
 }
 
 // handleGetConnectStatus godoc
@@ -86,6 +111,14 @@ func (s *Server) handleGetConnectClientStatus(w http.ResponseWriter, r *http.Req
 // @Description entry_exists distinguishes a create from an overwrite of a same-named entry.
 // @Description Reads the config on demand to classify create-vs-overwrite, so on macOS this
 // @Description may raise an App-Data privacy prompt; a denial returns 403 + remediation.
+// @Description Spec 091 adds three fields: existing_entry_summary (present only when
+// @Description entry_exists — a sanitized, non-secret projection of the entry being replaced:
+// @Description its name, type, endpoint with query/userinfo stripped, command, and header and
+// @Description env NAMES, never values); precondition_token (always present — an opaque keyed
+// @Description digest of the raw pre-write state and the pending entry, echoed back on POST
+// @Description connect to detect drift); and connect_refusal (present when the write would
+// @Description refuse regardless of intent, e.g. a non-create-capable client with no config —
+// @Description treat its presence as "Connect unavailable").
 // @Tags        connect
 // @Produce     json
 // @Security    ApiKeyAuth
@@ -134,18 +167,24 @@ func (s *Server) handleConnectClientPreview(w http.ResponseWriter, r *http.Reque
 // @Summary     Connect MCPProxy to a client
 // @Description Register MCPProxy as an MCP server in the specified client's configuration file.
 // @Description Creates a backup of the existing config before modifying.
+// @Description Optionally accepts precondition_token from a preview (Spec 091): when supplied,
+// @Description the core rechecks the raw pre-write state and the entry it would write, and
+// @Description refuses a drifted write with 409 before taking any backup. The 409 body's
+// @Description action discriminates the two conflict kinds: "precondition_failed" (stale
+// @Description preview — re-preview, do not retry) vs "already_exists" (entry present — pass
+// @Description force=true). force=true never rescues a stale token.
 // @Tags        connect
 // @Accept      json
 // @Produce     json
 // @Security    ApiKeyAuth
 // @Security    ApiKeyQuery
 // @Param       client path   string         true  "Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)"
-// @Param       body   body   ConnectRequest false "Optional connection parameters"
+// @Param       body   body   ConnectRequest false "Optional connection parameters (server_name, force, precondition_token)"
 // @Success     200    {object} contracts.APIResponse "ConnectResult"
 // @Failure     400    {object} contracts.ErrorResponse "Bad request"
 // @Failure     403    {object} contracts.ErrorResponse "Permission denied (macOS App-Data block)"
 // @Failure     404    {object} contracts.ErrorResponse "Unknown client"
-// @Failure     409    {object} contracts.ErrorResponse "Already connected (use force=true)"
+// @Failure     409    {object} ConnectConflictResponse "Conflict: action=already_exists (use force=true) or action=precondition_failed (preview is stale; re-preview)"
 // @Failure     503    {object} contracts.ErrorResponse "Service unavailable"
 // @Router      /api/v1/connect/{client} [post]
 func (s *Server) handleConnectClient(w http.ResponseWriter, r *http.Request) {
@@ -162,14 +201,12 @@ func (s *Server) handleConnectClient(w http.ResponseWriter, r *http.Request) {
 	}
 
 	var req ConnectRequest
-	if r.Body != nil && r.ContentLength > 0 {
-		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-			s.writeError(w, r, http.StatusBadRequest, fmt.Sprintf("invalid request body: %v", err))
-			return
-		}
+	if err := decodeOptionalJSONBody(r, &req); err != nil {
+		s.writeError(w, r, http.StatusBadRequest, fmt.Sprintf("invalid request body: %v", err))
+		return
 	}
 
-	result, err := svc.Connect(clientID, req.ServerName, req.Force)
+	result, err := svc.ConnectWithPrecondition(clientID, req.ServerName, req.Force, req.PreconditionToken)
 	if err != nil {
 		// A macOS App-Data (TCC) denial surfaces as 403 carrying remediation,
 		// distinct from a generic 400 or a 404 not-found (Spec 075 contract).
@@ -186,11 +223,17 @@ func (s *Server) handleConnectClient(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if !result.Success && result.Action == "already_exists" {
-		s.writeJSON(w, http.StatusConflict, map[string]interface{}{
-			"success": false,
-			"data":    result,
-			"error":   result.Message,
+	// Both 409 kinds carry their discriminator in `action` — mirrored at the top
+	// level so a client can branch without unwrapping `data`. "already_exists"
+	// means "an entry is there, pass force"; "precondition_failed" means "your
+	// preview is stale, re-preview" (contracts §2). Conflating them would make a
+	// replace flow either loop or force a write over unseen state.
+	if !result.Success && (result.Action == "already_exists" || result.Action == "precondition_failed") {
+		s.writeJSON(w, http.StatusConflict, ConnectConflictResponse{
+			Success: false,
+			Data:    *result,
+			Error:   result.Message,
+			Action:  result.Action,
 		})
 		return
 	}
@@ -229,9 +272,7 @@ func (s *Server) handleDisconnectClient(w http.ResponseWriter, r *http.Request)
 	}
 
 	var req ConnectRequest
-	if r.Body != nil && r.ContentLength > 0 {
-		_ = json.NewDecoder(r.Body).Decode(&req) // best effort
-	}
+	_ = decodeOptionalJSONBody(r, &req) // best effort
 
 	result, err := svc.Disconnect(clientID, req.ServerName)
 	if err != nil {
@@ -307,11 +348,9 @@ func (s *Server) handleUndoConnectClient(w http.ResponseWriter, r *http.Request)
 	}
 
 	var req UndoConnectRequest
-	if r.Body != nil && r.ContentLength > 0 {
-		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-			s.writeError(w, r, http.StatusBadRequest, fmt.Sprintf("invalid request body: %v", err))
-			return
-		}
+	if err := decodeOptionalJSONBody(r, &req); err != nil {
+		s.writeError(w, r, http.StatusBadRequest, fmt.Sprintf("invalid request body: %v", err))
+		return
 	}
 
 	result, err := svc.Undo(clientID, req.ServerName, req.BackupName)
@@ -347,6 +386,24 @@ func (s *Server) handleUndoConnectClient(w http.ResponseWriter, r *http.Request)
 	s.writeSuccess(w, result)
 }
 
+// decodeOptionalJSONBody decodes an optional JSON request body. An absent or
+// empty body leaves out untouched — that is what "no body" means for these
+// endpoints — and any other malformed input is returned as an error.
+//
+// Deliberately NOT gated on Content-Length: a chunked or otherwise streamed
+// request arrives with ContentLength == -1, and skipping the decode there
+// silently dropped the fields the caller relies on for safety (force and,
+// above all, precondition_token), running the write in unguarded legacy mode.
+func decodeOptionalJSONBody(r *http.Request, out interface{}) error {
+	if r.Body == nil {
+		return nil
+	}
+	if err := json.NewDecoder(r.Body).Decode(out); err != nil && !errors.Is(err, io.EOF) {
+		return err
+	}
+	return nil
+}
+
 // writeIfAccessDenied maps a permission-denied client-config access to a 403
 // response whose body carries the remediation text. It returns true when it
 // handled the error (a typed *connect.AccessError), so callers can stop. This
diff --git a/internal/httpapi/connect_oas_test.go b/internal/httpapi/connect_oas_test.go
new file mode 100644
index 00000000..730136cb
--- /dev/null
+++ b/internal/httpapi/connect_oas_test.go
@@ -0,0 +1,56 @@
+package httpapi
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gopkg.in/yaml.v3"
+)
+
+// The 409 from POST /api/v1/connect/{client} carries a top-level `action`
+// discriminator, and spec 091 makes it THE machine-readable signal telling
+// "an entry is there, pass force" (already_exists) apart from "your view is
+// stale, re-preview" (precondition_failed). A client generated from the OpenAPI
+// document must therefore SEE that field: documenting the body as a plain
+// error response leaves the discriminator visible only in prose, and a
+// generated client that cannot read it either loops or forces a write over
+// state the user never saw (research D9).
+func TestOAS_ConnectConflictDocumentsTheActionDiscriminator(t *testing.T) {
+	raw, err := os.ReadFile(filepath.Join("..", "..", "oas", "swagger.yaml"))
+	require.NoError(t, err, "oas/swagger.yaml must be committed")
+
+	var doc struct {
+		Paths map[string]map[string]struct {
+			Responses map[string]struct {
+				Content map[string]struct {
+					Schema map[string]interface{} `yaml:"schema"`
+				} `yaml:"content"`
+			} `yaml:"responses"`
+		} `yaml:"paths"`
+		Components struct {
+			Schemas map[string]struct {
+				Properties map[string]interface{} `yaml:"properties"`
+			} `yaml:"schemas"`
+		} `yaml:"components"`
+	}
+	require.NoError(t, yaml.Unmarshal(raw, &doc))
+
+	conflict, ok := doc.Paths["/api/v1/connect/{client}"]["post"].Responses["409"]
+	require.True(t, ok, "POST /api/v1/connect/{client} must document a 409")
+	ref, _ := conflict.Content["application/json"].Schema["$ref"].(string)
+	require.NotEmpty(t, ref, "the 409 body must reference a schema")
+
+	name := filepath.Base(ref)
+	schema, ok := doc.Components.Schemas[name]
+	require.True(t, ok, "referenced schema %q must be defined", name)
+
+	assert.Contains(t, schema.Properties, "action",
+		"the 409 schema (%s) must expose the action discriminator the contract depends on", name)
+	assert.Contains(t, schema.Properties, "data",
+		"the 409 schema (%s) must expose the ConnectResult payload the handler writes", name)
+	assert.Contains(t, schema.Properties, "error", "the 409 schema (%s) must expose the message", name)
+	assert.Contains(t, schema.Properties, "success", "the 409 schema (%s) must expose success", name)
+}
diff --git a/internal/httpapi/connect_test.go b/internal/httpapi/connect_test.go
index b788073d..3c18204f 100644
--- a/internal/httpapi/connect_test.go
+++ b/internal/httpapi/connect_test.go
@@ -3,6 +3,7 @@ package httpapi
 import (
 	"bytes"
 	"encoding/json"
+	"io"
 	"io/fs"
 	"net/http"
 	"net/http/httptest"
@@ -631,3 +632,260 @@ func TestHandleUndoConnectClient_NoPriorFileDeletes(t *testing.T) {
 	_, statErr := os.Stat(res.ConfigPath)
 	assert.True(t, os.IsNotExist(statErr), "config created by connect must be removed")
 }
+
+// --- Spec 091: precondition token over the HTTP connect surface (contracts §1–2) ---
+
+// connectTestServer builds a server with a connect service rooted at an
+// isolated home, returning both plus the home dir.
+func connectTestServer(t *testing.T) (*Server, *connect.Service, string) {
+	t.Helper()
+	logger := zap.NewNop().Sugar()
+	srv := NewServer(&mockRoutingController{apiKey: "test-key", routingMode: "retrieve_tools"}, logger, nil)
+	home := t.TempDir()
+	t.Setenv("LOCALAPPDATA", filepath.Join(home, "AppData", "Local"))
+	t.Setenv("APPDATA", filepath.Join(home, "AppData", "Roaming"))
+	svc := connect.NewServiceWithHome("127.0.0.1:8080", "", home)
+	srv.SetConnectService(svc)
+	return srv, svc, home
+}
+
+// fetchPreview drives GET /api/v1/connect/{client}/preview and returns the
+// decoded payload as a generic map, so assertions run over the SERIALIZED
+// contract rather than the Go struct.
+func fetchPreview(t *testing.T, srv *Server, clientID string) map[string]interface{} {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/connect/"+clientID+"/preview?server_name=mcpproxy", nil)
+	req.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.ServeHTTP(w, req)
+	require.Equal(t, http.StatusOK, w.Code, w.Body.String())
+
+	var resp struct {
+		Success bool                   `json:"success"`
+		Data    map[string]interface{} `json:"data"`
+	}
+	require.NoError(t, json.NewDecoder(w.Body).Decode(&resp))
+	require.True(t, resp.Success)
+	return resp.Data
+}
+
+func postConnect(t *testing.T, srv *Server, clientID string, body ConnectRequest) *httptest.ResponseRecorder {
+	t.Helper()
+	encoded, err := json.Marshal(body)
+	require.NoError(t, err)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/connect/"+clientID, bytes.NewReader(encoded))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-API-Key", "test-key")
+	w := httptest.NewRecorder()
+	srv.ServeHTTP(w, req)
+	return w
+}
+
+// TestHandleConnectClientPreview_SerializesSpec091Fields pins contracts §1: the
+// preview response carries the three new fields with the documented shapes.
+func TestHandleConnectClientPreview_SerializesSpec091Fields(t *testing.T) {
+	srv, _, home := connectTestServer(t)
+	cfgPath := connect.ConfigPath("claude-code", home)
+	require.NoError(t, os.MkdirAll(filepath.Dir(cfgPath), 0o755))
+	require.NoError(t, os.WriteFile(cfgPath, []byte(
+		`{"mcpServers":{"mcpproxy":{"type":"http","url":"http://127.0.0.1:8080/mcp?apikey=WIRE-SECRET","headers":{"X-API-Key":"WIRE-HEADER-SECRET"}}}}`), 0o644))
+
+	data := fetchPreview(t, srv, "claude-code")
+
+	token, ok := data["precondition_token"].(string)
+	require.True(t, ok, "precondition_token must always be present: %v", data)
+	assert.NotEmpty(t, token)
+
+	summary, ok := data["existing_entry_summary"].(map[string]interface{})
+	require.True(t, ok, "existing_entry_summary must be present when entry_exists: %v", data)
+	assert.Equal(t, "mcpproxy", summary["entry_name"])
+	assert.Equal(t, "http", summary["type"])
+	assert.Equal(t, "http://127.0.0.1:8080/mcp", summary["endpoint"])
+	assert.Equal(t, []interface{}{"X-API-Key"}, summary["header_names"])
+
+	// connect_refusal is omitted for a connectable client.
+	assert.Nil(t, data["connect_refusal"])
+
+	// Nothing secret rides out on the wire.
+	serialized, err := json.Marshal(data)
+	require.NoError(t, err)
+	assert.NotContains(t, string(serialized), "WIRE-SECRET")
+	assert.NotContains(t, string(serialized), "WIRE-HEADER-SECRET")
+}
+
+// TestHandleConnectClientPreview_SerializesConnectRefusal covers the third
+// field: a non-create-capable client with an absent config.
+func TestHandleConnectClientPreview_SerializesConnectRefusal(t *testing.T) {
+	srv, _, _ := connectTestServer(t)
+	data := fetchPreview(t, srv, "opencode")
+	refusal, ok := data["connect_refusal"].(string)
+	require.True(t, ok, "connect_refusal must be present for OpenCode without a config: %v", data)
+	assert.Contains(t, refusal, "no OpenCode config found")
+}
+
+// TestHandleConnectClient_AcceptsPreconditionToken proves the POST body carries
+// the token through to a successful write.
+func TestHandleConnectClient_AcceptsPreconditionToken(t *testing.T) {
+	srv, _, home := connectTestServer(t)
+	cfgPath := connect.ConfigPath("claude-code", home)
+	require.NoError(t, os.MkdirAll(filepath.Dir(cfgPath), 0o755))
+	require.NoError(t, os.WriteFile(cfgPath, []byte(`{"mcpServers":{}}`), 0o644))
+
+	token := fetchPreview(t, srv, "claude-code")["precondition_token"].(string)
+
+	w := postConnect(t, srv, "claude-code", ConnectRequest{
+		ServerName: "mcpproxy", PreconditionToken: token,
+	})
+	require.Equal(t, http.StatusOK, w.Code, w.Body.String())
+
+	var resp struct {
+		Success bool                  `json:"success"`
+		Data    connect.ConnectResult `json:"data"`
+	}
+	require.NoError(t, json.NewDecoder(w.Body).Decode(&resp))
+	assert.True(t, resp.Success)
+}
+
+// TestHandleConnectClient_StaleTokenReturnsDiscriminatedConflict pins contracts
+// §2: drift is a 409 whose action discriminates it from the legacy
+// already_exists conflict, so a client knows to re-preview rather than retry.
+func TestHandleConnectClient_StaleTokenReturnsDiscriminatedConflict(t *testing.T) {
+	srv, _, home := connectTestServer(t)
+	cfgPath := connect.ConfigPath("claude-code", home)
+	require.NoError(t, os.MkdirAll(filepath.Dir(cfgPath), 0o755))
+	require.NoError(t, os.WriteFile(cfgPath, []byte(
+		`{"mcpServers":{"mcpproxy":{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"first"}}}}`), 0o644))
+
+	token := fetchPreview(t, srv, "claude-code")["precondition_token"].(string)
+
+	drifted := []byte(`{"mcpServers":{"mcpproxy":{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"second"}}}}`)
+	require.NoError(t, os.WriteFile(cfgPath, drifted, 0o644))
+
+	// force=true rides WITH the token and still must not rescue it.
+	w := postConnect(t, srv, "claude-code", ConnectRequest{
+		ServerName: "mcpproxy", Force: true, PreconditionToken: token,
+	})
+	require.Equal(t, http.StatusConflict, w.Code, w.Body.String())
+
+	var resp struct {
+		Success bool                  `json:"success"`
+		Action  string                `json:"action"`
+		Data    connect.ConnectResult `json:"data"`
+		Error   string                `json:"error"`
+	}
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))
+	assert.False(t, resp.Success)
+	assert.Equal(t, "precondition_failed", resp.Data.Action)
+	assert.Equal(t, "precondition_failed", resp.Action, "the discriminator must be readable at the top level too")
+	assert.NotEmpty(t, resp.Error)
+
+	// Nothing was written.
+	after, err := os.ReadFile(cfgPath)
+	require.NoError(t, err)
+	assert.Equal(t, string(drifted), string(after))
+}
+
+// TestHandleConnectClient_LegacyConflictKeepsItsDiscriminator guards the other
+// side of the discriminator: a tokenless force=false write over an existing
+// entry is still already_exists, which a client must NOT treat as re-previewable.
+func TestHandleConnectClient_LegacyConflictKeepsItsDiscriminator(t *testing.T) {
+	srv, svc, _ := connectTestServer(t)
+	_, err := svc.Connect("claude-code", "mcpproxy", false)
+	require.NoError(t, err)
+
+	w := postConnect(t, srv, "claude-code", ConnectRequest{ServerName: "mcpproxy"})
+	require.Equal(t, http.StatusConflict, w.Code)
+
+	var resp struct {
+		Action string                `json:"action"`
+		Data   connect.ConnectResult `json:"data"`
+	}
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))
+	assert.Equal(t, "already_exists", resp.Data.Action)
+	assert.Equal(t, "already_exists", resp.Action)
+}
+
+// chunkedBody hides the reader's Len method so net/http cannot compute a
+// Content-Length and streams the body with Transfer-Encoding: chunked — what
+// curl --header 'Transfer-Encoding: chunked' and any streaming HTTP client
+// produce. The handler sees ContentLength == -1.
+func chunkedBody(payload []byte) io.Reader {
+	return struct{ io.Reader }{bytes.NewReader(payload)}
+}
+
+// TestHandleConnectClient_ChunkedBodyIsDecoded pins that the request body is
+// read from the BODY, not from a Content-Length guess: force and, above all,
+// precondition_token are safety fields, and silently dropping them ran the
+// write in unguarded legacy mode.
+func TestHandleConnectClient_ChunkedBodyIsDecoded(t *testing.T) {
+	newFixture := func(t *testing.T) (*httptest.Server, *connect.Service, string) {
+		t.Helper()
+		logger := zap.NewNop().Sugar()
+		mockCtrl := &mockRoutingController{apiKey: "test-key", routingMode: "retrieve_tools"}
+		srv := NewServer(mockCtrl, logger, nil)
+		home := t.TempDir()
+		t.Setenv("LOCALAPPDATA", filepath.Join(home, "AppData", "Local"))
+		t.Setenv("APPDATA", filepath.Join(home, "AppData", "Roaming"))
+		svc := connect.NewServiceWithHome("127.0.0.1:8080", "", home)
+		srv.SetConnectService(svc)
+		ts := httptest.NewServer(srv)
+		t.Cleanup(ts.Close)
+		return ts, svc, home
+	}
+
+	post := func(t *testing.T, ts *httptest.Server, payload ConnectRequest) (int, map[string]interface{}) {
+		t.Helper()
+		body, err := json.Marshal(payload)
+		require.NoError(t, err)
+		req, err := http.NewRequest(http.MethodPost, ts.URL+"/api/v1/connect/claude-code", chunkedBody(body))
+		require.NoError(t, err)
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("X-API-Key", "test-key")
+		// Streamed, so the handler sees ContentLength == -1 (the transport also
+		// chunks an unknown-length body on its own; this makes it explicit).
+		req.TransferEncoding = []string{"chunked"}
+		resp, err := ts.Client().Do(req)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+		var decoded map[string]interface{}
+		require.NoError(t, json.NewDecoder(resp.Body).Decode(&decoded))
+		return resp.StatusCode, decoded
+	}
+
+	t.Run("force is honored", func(t *testing.T) {
+		ts, svc, _ := newFixture(t)
+		_, err := svc.Connect("claude-code", "mcpproxy", false)
+		require.NoError(t, err)
+
+		status, decoded := post(t, ts, ConnectRequest{ServerName: "mcpproxy", Force: true})
+		assert.Equal(t, http.StatusOK, status, "force=true in a chunked body must overwrite, not 409: %v", decoded)
+		data, _ := decoded["data"].(map[string]interface{})
+		assert.Equal(t, "updated", data["action"])
+	})
+
+	t.Run("a stale precondition token still refuses", func(t *testing.T) {
+		ts, svc, home := newFixture(t)
+		cfgPath := connect.ConfigPath("claude-code", home)
+		require.NoError(t, os.WriteFile(cfgPath,
+			[]byte(`{"mcpServers":{"mcpproxy":{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"first"}}}}`), 0o644))
+		preview, err := svc.Preview("claude-code", "mcpproxy")
+		require.NoError(t, err)
+		require.NotEmpty(t, preview.PreconditionToken)
+
+		// Drift after the preview: the echoed token no longer describes reality.
+		const drifted = `{"mcpServers":{"mcpproxy":{"type":"http","url":"http://127.0.0.1:8080/mcp","headers":{"X-API-Key":"second"}}}}`
+		require.NoError(t, os.WriteFile(cfgPath, []byte(drifted), 0o644))
+
+		status, decoded := post(t, ts, ConnectRequest{
+			ServerName:        "mcpproxy",
+			Force:             true,
+			PreconditionToken: preview.PreconditionToken,
+		})
+		assert.Equal(t, http.StatusConflict, status, "a token sent in a chunked body must still be checked: %v", decoded)
+		assert.Equal(t, "precondition_failed", decoded["action"])
+
+		after, err := os.ReadFile(cfgPath)
+		require.NoError(t, err)
+		assert.Equal(t, drifted, string(after), "a refused write must not touch the config")
+	})
+}
diff --git a/internal/server/connect_socket_e2e_test.go b/internal/server/connect_socket_e2e_test.go
new file mode 100644
index 00000000..0fe343d9
--- /dev/null
+++ b/internal/server/connect_socket_e2e_test.go
@@ -0,0 +1,214 @@
+//go:build (linux || darwin) && !windows
+
+package server
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/auth"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/connect"
+	"github.com/smart-mcp-proxy/mcpproxy-go/internal/httpapi"
+)
+
+// SC-006: an integration test proving a request over the private local socket
+// reaches the gated connect-write route as an ADMINISTRATIVE caller, end to end.
+//
+// The existing coverage is all unit-level and each piece assumes the next: the
+// listener tests check that a Unix connection is tagged, the middleware tests
+// check that a tray-tagged context becomes an admin auth context, and the gating
+// tests check that an admin context passes requireServerOp. httptest cannot join
+// them — it never creates a connection, so ConnContext never runs and the tag
+// never exists. Only a real socket, accepted through the production multiplex
+// listener and served with the production ConnContext, exercises
+// listener → tagging → auth conversion → gate → handler as one path.
+//
+// The native Connect Client form depends on exactly this chain: it sends its
+// mutating requests over the socket with NO credential, so if any link breaks
+// the form silently loses the ability to write client configs (or, worse, only
+// works because something else authenticated it).
+
+// socketE2EServer starts an httpapi server on a real Unix socket AND a real TCP
+// port, through the same ListenerManager, multiplexListener and ConnContext the
+// production server uses. It returns the socket path, the TCP address, and the
+// isolated home the connect service writes into.
+func socketE2EServer(t *testing.T, api *httpapi.Server) (socketPath, tcpAddr string) {
+	t.Helper()
+
+	// Socket paths are capped at ~104 bytes; t.TempDir() under macOS's long
+	// per-test path blows that limit, so anchor the data dir in /tmp.
+	dataDir, err := os.MkdirTemp("/tmp", "mcpx-sock")
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = os.RemoveAll(dataDir) })
+	require.NoError(t, os.Chmod(dataDir, 0o700))
+
+	logger := zap.NewNop()
+	manager := NewListenerManager(&ListenerConfig{
+		DataDir:    dataDir,
+		TCPAddress: "127.0.0.1:0",
+		Logger:     logger,
+	})
+	tcpListener, err := manager.CreateTCPListener()
+	require.NoError(t, err)
+	require.NotNil(t, tcpListener)
+
+	trayListener, err := manager.CreateTrayListener()
+	require.NoError(t, err)
+	require.NotNil(t, trayListener, "the tray socket listener is the subject of this test")
+	require.Equal(t, ConnectionSourceTray, trayListener.Source)
+
+	mux := &multiplexListener{
+		listeners: []*Listener{tcpListener, trayListener},
+		logger:    logger,
+	}
+
+	httpSrv := &http.Server{
+		Handler:           api,
+		ReadHeaderTimeout: 10 * time.Second,
+		// The production tagging hook, shared verbatim — a copy here would
+		// prove only that the copy works.
+		ConnContext: taggedConnContext,
+	}
+	go func() { _ = httpSrv.Serve(mux) }()
+	t.Cleanup(func() {
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+		defer cancel()
+		_ = httpSrv.Shutdown(shutdownCtx)
+		_ = mux.Close()
+		_ = manager.CloseAll()
+	})
+
+	return filepath.Join(dataDir, "mcpproxy.sock"), tcpListener.Address
+}
+
+// socketHTTPClient dials the Unix socket for every request, the way the tray's
+// administrative transport does.
+func socketHTTPClient(socketPath string) *http.Client {
+	return &http.Client{
+		Timeout: 10 * time.Second,
+		Transport: &http.Transport{
+			DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
+				var d net.Dialer
+				return d.DialContext(ctx, "unix", socketPath)
+			},
+		},
+	}
+}
+
+// TestConnectSocketE2E_SocketCallerIsAdminOnGatedWriteRoute drives
+// POST /api/v1/connect/{client} over a real Unix socket with NO credential of
+// any kind and requires the write to happen: the admin context can only have
+// come from the transport.
+func TestConnectSocketE2E_SocketCallerIsAdminOnGatedWriteRoute(t *testing.T) {
+	srv := newConsistencyServer(t)
+	api := httpapi.NewServer(srv, zap.NewNop().Sugar(), nil)
+
+	home := t.TempDir()
+	api.SetConnectService(connect.NewServiceWithHome("127.0.0.1:8080", "", home))
+
+	socketPath, _ := socketE2EServer(t, api)
+	client := socketHTTPClient(socketPath)
+
+	// No X-API-Key, no bearer token, no query credential.
+	resp, err := client.Post("http://mcpproxy/api/v1/connect/claude-code",
+		"application/json", strings.NewReader(`{"server_name":"mcpproxy"}`))
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	require.Equal(t, http.StatusOK, resp.StatusCode,
+		"an unauthenticated socket caller must reach the gated write route as admin")
+
+	// Reaching the route is not enough — the write itself must have happened,
+	// which proves the gate passed rather than something short-circuiting.
+	cfgPath := connect.ConfigPath("claude-code", home)
+	written, err := os.ReadFile(cfgPath)
+	require.NoError(t, err, "the connect write must have created %s", cfgPath)
+	assert.Contains(t, string(written), "mcpproxy")
+}
+
+// TestConnectSocketE2E_AgentTokenOverTCPIsRejected is the negative control on
+// the same route and the same running server: the socket's admin treatment is a
+// property of the transport, not a hole in the gate.
+func TestConnectSocketE2E_AgentTokenOverTCPIsRejected(t *testing.T) {
+	srv := newConsistencyServer(t)
+	api := httpapi.NewServer(srv, zap.NewNop().Sugar(), nil)
+
+	home := t.TempDir()
+	api.SetConnectService(connect.NewServiceWithHome("127.0.0.1:8080", "", home))
+
+	tokenDir := t.TempDir()
+	_, err := auth.GetOrCreateHMACKey(tokenDir)
+	require.NoError(t, err)
+	rawToken, err := auth.GenerateToken()
+	require.NoError(t, err)
+	api.SetTokenStore(&socketE2ETokenStore{
+		raw: rawToken,
+		token: &auth.AgentToken{
+			Name:           "socket-e2e-agent",
+			TokenPrefix:    auth.TokenPrefix(rawToken),
+			AllowedServers: []string{"*"},
+			// Deliberately generous: read+write on every server, so a rejection
+			// can only come from the admin-operation policy.
+			Permissions: []string{auth.PermRead, auth.PermWrite},
+			ExpiresAt:   time.Now().Add(time.Hour),
+			CreatedAt:   time.Now(),
+		},
+	}, tokenDir)
+
+	_, tcpAddr := socketE2EServer(t, api)
+
+	req, err := http.NewRequest(http.MethodPost,
+		fmt.Sprintf("http://%s/api/v1/connect/claude-code", tcpAddr),
+		strings.NewReader(`{"server_name":"mcpproxy"}`))
+	require.NoError(t, err)
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-API-Key", rawToken)
+
+	resp, err := (&http.Client{Timeout: 10 * time.Second}).Do(req)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	require.Equal(t, http.StatusForbidden, resp.StatusCode,
+		"a restricted agent token must not reach the connect write route over TCP")
+
+	if _, statErr := os.Stat(connect.ConfigPath("claude-code", home)); statErr == nil {
+		t.Fatal("a rejected request must not have written the client config")
+	}
+}
+
+// socketE2ETokenStore is a minimal httpapi.TokenStore that validates exactly one
+// agent token; the management endpoints are unused by this test.
+type socketE2ETokenStore struct {
+	raw   string
+	token *auth.AgentToken
+}
+
+func (s *socketE2ETokenStore) ValidateAgentToken(rawToken string, _ []byte) (*auth.AgentToken, error) {
+	if rawToken == s.raw {
+		return s.token, nil
+	}
+	return nil, fmt.Errorf("token not found")
+}
+
+func (s *socketE2ETokenStore) CreateAgentToken(auth.AgentToken, string, []byte) error { return nil }
+func (s *socketE2ETokenStore) ListAgentTokens() ([]auth.AgentToken, error)            { return nil, nil }
+func (s *socketE2ETokenStore) GetAgentTokenByName(string) (*auth.AgentToken, error) {
+	return nil, fmt.Errorf("not found")
+}
+func (s *socketE2ETokenStore) RevokeAgentToken(string) error { return nil }
+func (s *socketE2ETokenStore) DeleteAgentToken(string) error { return nil }
+func (s *socketE2ETokenStore) RegenerateAgentToken(string, string, []byte) (*auth.AgentToken, error) {
+	return nil, fmt.Errorf("not supported")
+}
+func (s *socketE2ETokenStore) UpdateAgentTokenLastUsed(string) error { return nil }
diff --git a/internal/server/listener_mux.go b/internal/server/listener_mux.go
index 212a5424..21ce1a78 100644
--- a/internal/server/listener_mux.go
+++ b/internal/server/listener_mux.go
@@ -1,6 +1,7 @@
 package server
 
 import (
+	"context"
 	"fmt"
 	"net"
 	"sync"
@@ -123,6 +124,23 @@ type taggedConn struct {
 	source ConnectionSource
 }
 
+// taggedConnContext is the http.Server ConnContext hook that carries a
+// connection's source into every request context served over it. It is the ONLY
+// place the transport identity enters the request path: the API-key middleware
+// grants an admin auth context to tray (Unix socket / named pipe) connections on
+// its strength, so the admin write gate ultimately rests on this hook.
+//
+// Named (rather than inlined at the http.Server literal) so an integration test
+// can serve the real handler over a real socket through the exact production
+// tagging, instead of a look-alike copy that could drift from it.
+func taggedConnContext(ctx context.Context, c net.Conn) context.Context {
+	// Extract source from tagged connection
+	if tc, ok := c.(*taggedConn); ok {
+		return TagConnectionContext(ctx, tc.source)
+	}
+	return TagConnectionContext(ctx, ConnectionSourceTCP) // Default to TCP
+}
+
 // PermissionError represents a permission-related error (exit code 5)
 type PermissionError struct {
 	Path string
diff --git a/internal/server/server.go b/internal/server/server.go
index 046c1300..ddd22b97 100644
--- a/internal/server/server.go
+++ b/internal/server/server.go
@@ -2462,13 +2462,7 @@ func (s *Server) startCustomHTTPServer(ctx context.Context, streamableServer *se
 		// Enable connection state tracking for better debugging
 		ConnState: s.logConnectionState,
 		// Tag connections with their source (TCP vs Tray)
-		ConnContext: func(ctx context.Context, c net.Conn) context.Context {
-			// Extract source from tagged connection
-			if tc, ok := c.(*taggedConn); ok {
-				return TagConnectionContext(ctx, tc.source)
-			}
-			return TagConnectionContext(ctx, ConnectionSourceTCP) // Default to TCP
-		},
+		ConnContext: taggedConnContext,
 	}
 	s.running = true
 	s.runtime.SetRunning(true)
diff --git a/native/macos/MCPProxy/MCPProxy/API/APIClient.swift b/native/macos/MCPProxy/MCPProxy/API/APIClient.swift
index 78873f32..03ea201b 100644
--- a/native/macos/MCPProxy/MCPProxy/API/APIClient.swift
+++ b/native/macos/MCPProxy/MCPProxy/API/APIClient.swift
@@ -9,6 +9,14 @@ enum APIClientError: Error, LocalizedError {
     case decodingError(underlying: Error)
     case noData
     case invalidURL(String)
+    /// A 409 from the connect write, carrying the core's own discriminator:
+    /// `precondition_failed` (the previewed state drifted — re-preview) versus
+    /// `already_exists` (the legacy conflict). Callers must be able to tell them
+    /// apart without string matching (contracts §2, research D9).
+    case connectConflict(action: String, message: String)
+    /// An administrative write was attempted while the app is not talking to the
+    /// core over its private local socket. Never sent, by design.
+    case socketRequired
 
     var errorDescription: String? {
         switch self {
@@ -22,6 +30,11 @@ enum APIClientError: Error, LocalizedError {
             return "No data in response"
         case .invalidURL(let url):
             return "Invalid URL: \(url)"
+        case .connectConflict(_, let message):
+            return message
+        case .socketRequired:
+            return "This action requires MCPProxy's private local socket; "
+                + "the app is currently talking to the core over TCP."
         }
     }
 }
@@ -37,6 +50,22 @@ actor APIClient {
     private let baseURL: String
     private let apiKey: String?
 
+    /// Which transport this client was configured for.
+    ///
+    /// The core treats socket callers as administrative, so the native form
+    /// gates its mutating controls on this identity (research D6). It is derived
+    /// from the configured endpoint, never probed — a probe answers "is the
+    /// socket up right now", which is a different question from "is this client
+    /// an administrative caller at all".
+    enum TransportKind: Equatable {
+        case unixSocket
+        case tcp
+    }
+
+    /// Transport identity of this client. `nonisolated` because callers need it
+    /// synchronously to decide whether a control is even enabled.
+    nonisolated let transportKind: TransportKind
+
     /// Create an API client.
     ///
     /// - Parameters:
@@ -63,18 +92,29 @@ actor APIClient {
         if let path = socketPath, path.isEmpty {
             // Explicitly requested TCP-only
             self.session = SocketTransport.makeTCPSession(timeout: requestTimeout)
+            self.transportKind = .tcp
         } else {
             // Always use socket-backed session — SocketURLProtocol falls through
             // to standard networking if the socket file doesn't exist yet.
             self.session = SocketTransport.makeURLSession(socketPath: socketPath, timeout: requestTimeout)
+            self.transportKind = .unixSocket
         }
     }
 
     /// Create an API client with an explicit URLSession (for testing).
-    init(session: URLSession, baseURL: String = "http://127.0.0.1:8080", apiKey: String? = nil) {
+    ///
+    /// A stubbed session has no transport of its own, so tests state the
+    /// identity they mean to exercise.
+    init(
+        session: URLSession,
+        baseURL: String = "http://127.0.0.1:8080",
+        apiKey: String? = nil,
+        transportKind: TransportKind = .unixSocket
+    ) {
         self.session = session
         self.baseURL = baseURL
         self.apiKey = apiKey
+        self.transportKind = transportKind
     }
 
     // MARK: - Health
@@ -245,8 +285,13 @@ actor APIClient {
 
     // MARK: - Connect (Client Registration)
 
-    /// Client status model returned by `GET /api/v1/connect`.
-    struct ClientStatus: Codable, Identifiable {
+    /// Client status model returned by `GET /api/v1/connect` (list, existence
+    /// checks only) and `GET /api/v1/connect/{id}` (detail, one on-demand read).
+    ///
+    /// Every spec-091 addition is optional: a core older than this app sends
+    /// none of them, and a list that refuses to decode is a much worse outcome
+    /// than a row rendered with defaults.
+    struct ClientStatus: Codable, Identifiable, Equatable {
         var id: String { clientId }
         let clientId: String
         let name: String
@@ -255,17 +300,59 @@ actor APIClient {
         let connected: Bool
         let supported: Bool
         let reason: String?
+        /// Icon slug from the core registry ("claude-code", "cursor", …) — a
+        /// registry identity, NOT an SF Symbol name; see `symbolName`.
+        let icon: String?
+        /// Entry name under which mcpproxy is registered, when connected.
+        let serverName: String?
+        /// Resolved by the detail read; absent in the content-read-free list.
+        let accessState: ConnectAccessState?
+        /// Actionable fix text, populated only when access is denied.
+        let remediation: String?
+        /// Caveat for a supported client (e.g. a bridge requirement).
+        let note: String?
+        /// Connects through a stdio bridge; connectable without an existing config.
+        let bridge: Bool?
 
         enum CodingKeys: String, CodingKey {
             case clientId = "id"
             case name
             case configPath = "config_path"
-            case exists, connected, supported, reason
+            case exists, connected, supported, reason, icon, note, bridge
+            case serverName = "server_name"
+            case accessState = "access_state"
+            case remediation
+        }
+
+        /// Name to render; a core newer than the app may report a client this
+        /// build never heard of, which still renders by name (FR-009).
+        var displayName: String { name.isEmpty ? clientId : name }
+
+        /// SF Symbol for the row. The core's `icon` is a registry slug, so an
+        /// unknown one — the newer-core case — resolves to the generic symbol
+        /// rather than an empty image.
+        var symbolName: String {
+            switch icon ?? clientId {
+            case "claude-code", "claude-desktop":
+                return "brain"
+            case "cursor":
+                return "cursorarrow.rays"
+            case "vscode", "copilot":
+                return "chevron.left.forwardslash.chevron.right"
+            case "windsurf":
+                return "wind"
+            case "codex", "opencode":
+                return "terminal"
+            case "gemini":
+                return "sparkles"
+            default:
+                return "app.connected.to.app.below.fill"
+            }
         }
     }
 
     /// Result of a connect/disconnect action.
-    struct ConnectResult: Codable {
+    struct ConnectResult: Codable, Equatable {
         let success: Bool
         let client: String?
         let configPath: String?
@@ -311,26 +398,137 @@ actor APIClient {
         return []
     }
 
-    /// Connect MCPProxy to a client via `POST /api/v1/connect/{clientId}`.
-    func connectToClient(_ clientId: String) async throws -> ConnectResult {
-        let data = try await postRaw(path: "/api/v1/connect/\(clientId)")
-        let decoder = JSONDecoder()
-        if let wrapper = try? decoder.decode(APIResponse<ConnectResult>.self, from: data),
-           let payload = wrapper.data {
-            return payload
+    // MARK: - Connect (native form surface, Spec 091)
+    //
+    // The preview-less `connectToClient` / `disconnectFromClient` pair that the
+    // legacy dashboard sheet used is deliberately gone (FR-012): the only writes
+    // this app can perform are the token-bound, preview-gated ones below.
+
+    /// One client's authoritative state via `GET /api/v1/connect/{id}` — the
+    /// only Connect read that opens a client config file, so it happens strictly
+    /// on an explicit user selection.
+    func clientDetail(_ clientId: String) async throws -> ClientStatus {
+        let (data, _) = try await performRequest(
+            path: "/api/v1/connect/\(clientId.uriComponentEncoded)", method: "GET")
+        return try decodeConnectPayload(ClientStatus.self, from: data)
+    }
+
+    /// The no-write preview via `GET /api/v1/connect/{id}/preview?server_name=…`.
+    /// The entry name is mirrored from what the subsequent write would send, so
+    /// the preview describes exactly the pending change (FR-003).
+    func connectPreview(
+        _ clientId: String,
+        serverName: String = ConnectPreviewModel.defaultServerName
+    ) async throws -> ConnectPreviewModel {
+        let path = "/api/v1/connect/\(clientId.uriComponentEncoded)/preview"
+            + "?server_name=\(serverName.uriComponentEncoded)"
+        let (data, _) = try await performRequest(path: path, method: "GET")
+        return try decodeConnectPayload(ConnectPreviewModel.self, from: data)
+    }
+
+    /// Write the entry via `POST /api/v1/connect/{id}`, echoing the preview's
+    /// precondition token (FR-005). A 409 surfaces as `.connectConflict` with
+    /// the core's own discriminator so the caller can re-preview on drift
+    /// instead of retrying blindly.
+    func connect(
+        _ clientId: String,
+        serverName: String = ConnectPreviewModel.defaultServerName,
+        force: Bool,
+        preconditionToken: String?
+    ) async throws -> ConnectResult {
+        var body: [String: Any] = ["server_name": serverName]
+        if force { body["force"] = true }
+        if let preconditionToken, !preconditionToken.isEmpty {
+            body["precondition_token"] = preconditionToken
+        }
+        return try await mutatingConnectRequest(
+            path: "/api/v1/connect/\(clientId.uriComponentEncoded)", method: "POST", body: body)
+    }
+
+    /// Reverse the connect that produced `backupName` via
+    /// `POST /api/v1/connect/{id}/undo`. A nil backup identity means the connect
+    /// CREATED the file, and undo removes it — the core reads that from the
+    /// field being absent, so an empty string must not be sent instead.
+    func undoConnect(
+        _ clientId: String,
+        serverName: String = ConnectPreviewModel.defaultServerName,
+        backupName: String?
+    ) async throws -> ConnectResult {
+        var body: [String: Any] = ["server_name": serverName]
+        if let backupName, !backupName.isEmpty { body["backup_name"] = backupName }
+        return try await mutatingConnectRequest(
+            path: "/api/v1/connect/\(clientId.uriComponentEncoded)/undo", method: "POST", body: body)
+    }
+
+    /// Remove the entry via `DELETE /api/v1/connect/{id}`.
+    func disconnect(
+        _ clientId: String,
+        serverName: String = ConnectPreviewModel.defaultServerName
+    ) async throws -> ConnectResult {
+        try await mutatingConnectRequest(
+            path: "/api/v1/connect/\(clientId.uriComponentEncoded)",
+            method: "DELETE",
+            body: ["server_name": serverName]
+        )
+    }
+
+    /// Shared shape of the three mutating connect calls: socket-gated, sent in
+    /// strict-socket mode, and 409-aware.
+    private func mutatingConnectRequest(
+        path: String,
+        method: String,
+        body: [String: Any]
+    ) async throws -> ConnectResult {
+        guard transportKind == .unixSocket else { throw APIClientError.socketRequired }
+        let bodyData = try JSONSerialization.data(withJSONObject: body)
+        let (data, response) = try await rawRequest(
+            path: path, method: method, body: bodyData, strictSocket: true)
+
+        if response.statusCode == http409Conflict {
+            throw connectConflict(from: data)
         }
-        return try decoder.decode(ConnectResult.self, from: data)
+        guard (200...299).contains(response.statusCode) else {
+            throw APIClientError.httpError(
+                statusCode: response.statusCode, message: errorMessage(from: data, response: response))
+        }
+        return try decodeConnectPayload(ConnectResult.self, from: data)
+    }
+
+    private var http409Conflict: Int { 409 }
+
+    /// Build the typed conflict from a 409 body, preferring the typed result's
+    /// `action` (the machine-readable discriminator) over the error string.
+    private func connectConflict(from data: Data) -> APIClientError {
+        let decoder = JSONDecoder()
+        let result = (try? decoder.decode(APIResponse<ConnectResult>.self, from: data))?.data
+            ?? (try? decoder.decode(ConnectResult.self, from: data))
+        let errorText = (try? decoder.decode(APIErrorResponse.self, from: data))?.error
+        return .connectConflict(
+            action: result?.action ?? "conflict",
+            message: result?.message ?? errorText ?? "The client configuration changed."
+        )
     }
 
-    /// Disconnect MCPProxy from a client via `DELETE /api/v1/connect/{clientId}`.
-    func disconnectFromClient(_ clientId: String) async throws -> ConnectResult {
-        let data = try await deleteRaw(path: "/api/v1/connect/\(clientId)")
+    /// Decode a payload that may or may not be enveloped.
+    private func decodeConnectPayload<T: Decodable>(_ type: T.Type, from data: Data) throws -> T {
         let decoder = JSONDecoder()
-        if let wrapper = try? decoder.decode(APIResponse<ConnectResult>.self, from: data),
+        if let wrapper = try? decoder.decode(APIResponse<T>.self, from: data),
            let payload = wrapper.data {
             return payload
         }
-        return try decoder.decode(ConnectResult.self, from: data)
+        do {
+            return try decoder.decode(T.self, from: data)
+        } catch {
+            throw APIClientError.decodingError(underlying: error)
+        }
+    }
+
+    private func errorMessage(from data: Data, response: HTTPURLResponse) -> String {
+        if let body = try? JSONDecoder().decode(APIErrorResponse.self, from: data),
+           let apiError = body.error {
+            return apiError
+        }
+        return HTTPURLResponse.localizedString(forStatusCode: response.statusCode)
     }
 
     // MARK: - Sessions
@@ -748,7 +946,8 @@ actor APIClient {
     private func rawRequest(
         path: String,
         method: String,
-        body: Data? = nil
+        body: Data? = nil,
+        strictSocket: Bool = false
     ) async throws -> (Data, HTTPURLResponse) {
         guard let url = URL(string: baseURL + path) else {
             throw APIClientError.invalidURL(baseURL + path)
@@ -758,6 +957,13 @@ actor APIClient {
         request.httpMethod = method
         request.setValue("application/json", forHTTPHeaderField: "Accept")
 
+        // Administrative writes must never fall back to TCP if the socket
+        // disappears mid-session (research D6); the transport strips this hint
+        // before anything goes on the wire.
+        if strictSocket {
+            request.setValue("1", forHTTPHeaderField: SocketURLProtocol.strictSocketHeader)
+        }
+
         // Spec 042: telemetry surface header so the daemon can attribute
         // requests to the macOS tray for the surface_requests counter.
         let trayVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "dev"
diff --git a/native/macos/MCPProxy/MCPProxy/API/ConnectModels.swift b/native/macos/MCPProxy/MCPProxy/API/ConnectModels.swift
new file mode 100644
index 00000000..602647da
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxy/API/ConnectModels.swift
@@ -0,0 +1,274 @@
+import Foundation
+
+// MARK: - Access state
+
+/// How readable the core found a client's config during an on-demand read
+/// (Spec 075's `access_state`, consumed here by the native Connect form).
+///
+/// Decoding is deliberately total: a core newer than this app can name a state
+/// this build has never heard of, and a client list that fails to decode is a
+/// far worse outcome than one unknown row.
+enum ConnectAccessState: String, Codable, Equatable {
+    case accessible
+    case absent
+    case malformed
+    case denied
+    /// Anything the core reports that this build does not recognise.
+    case unknown
+
+    init(from decoder: Decoder) throws {
+        let raw = try decoder.singleValueContainer().decode(String.self)
+        self = ConnectAccessState(rawValue: raw) ?? .unknown
+    }
+}
+
+// MARK: - Existing-entry summary
+
+/// The sanitized, structural description of the entry a connect would replace.
+///
+/// Built core-side from non-secret projections ONLY (entry name, transport type,
+/// query+userinfo-stripped endpoint, command, and the NAMES of headers and
+/// environment variables). Nothing here is ever compared against anything — it
+/// is display-only; the precondition token carries the comparison (FR-005).
+struct ConnectEntrySummary: Codable, Equatable {
+    let entryName: String
+    let type: String?
+    let endpoint: String?
+    let command: String?
+    let headerNames: [String]
+    let envNames: [String]
+
+    enum CodingKeys: String, CodingKey {
+        case entryName = "entry_name"
+        case type
+        case endpoint
+        case command
+        case headerNames = "header_names"
+        case envNames = "env_names"
+    }
+
+    init(
+        entryName: String,
+        type: String? = nil,
+        endpoint: String? = nil,
+        command: String? = nil,
+        headerNames: [String] = [],
+        envNames: [String] = []
+    ) {
+        self.entryName = entryName
+        self.type = type
+        self.endpoint = endpoint
+        self.command = command
+        self.headerNames = headerNames
+        self.envNames = envNames
+    }
+
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        entryName = try container.decodeIfPresent(String.self, forKey: .entryName) ?? ""
+        type = try container.decodeIfPresent(String.self, forKey: .type)
+        endpoint = try container.decodeIfPresent(String.self, forKey: .endpoint)
+        command = try container.decodeIfPresent(String.self, forKey: .command)
+        // Go emits `null` for an empty slice; a nil array would force every
+        // rendering site to special-case the same thing.
+        headerNames = try container.decodeIfPresent([String].self, forKey: .headerNames) ?? []
+        envNames = try container.decodeIfPresent([String].self, forKey: .envNames) ?? []
+    }
+}
+
+// MARK: - Change classification
+
+/// What the pending connect would do to the client's config file.
+///
+/// Derived from the preview alone (data-model): the form never inspects a config
+/// file itself, and never re-derives this from anything it typed.
+enum ConnectChangeKind: Equatable {
+    /// The core would refuse the write regardless of user intent; the string is
+    /// its verbatim reason (e.g. a non-create-capable client with no config).
+    case refused(String)
+    /// The config could not be read (malformed / denied): no pending entry, no
+    /// Connect control.
+    case blockedByAccess(ConnectAccessState)
+    /// No config file: the write creates one, and Undo removes it.
+    case create
+    /// Readable config without the entry: the write adds it after a backup.
+    case add
+    /// The entry (possibly adopted under another key) exists and is replaced.
+    case replace(entryName: String)
+
+    /// Whether a Connect control may exist for this classification (SC-002).
+    var allowsConnect: Bool {
+        switch self {
+        case .refused, .blockedByAccess:
+            return false
+        case .create, .add, .replace:
+            return true
+        }
+    }
+
+    /// A replace is the only kind that overwrites, so it is the only one that
+    /// sends `force` — always together with the precondition token (FR-005).
+    var requiresForce: Bool {
+        if case .replace = self { return true }
+        return false
+    }
+}
+
+// MARK: - Connect preview
+
+/// The core's no-write preview of a connect (`GET /api/v1/connect/{id}/preview`),
+/// including the spec-091 additions: the sanitized existing-entry summary, the
+/// opaque precondition token, and the connect refusal.
+struct ConnectPreviewModel: Codable, Equatable {
+    let client: String?
+    let configPath: String
+    let serverName: String
+    let entryText: String
+    let entryExists: Bool
+    let containsAPIKey: Bool
+    let accessState: ConnectAccessState
+    let existingEntrySummary: ConnectEntrySummary?
+    /// Opaque, keyed, single-session token binding this preview to the raw
+    /// pre-write state AND the pending entry.
+    ///
+    /// Empty or nil from a spec-091 core means the write cannot be bound to
+    /// this preview, and an overwrite is then NOT offered — the form never
+    /// sends `force` without a token (FR-005). That is different from a
+    /// pre-091 core, which does not send the field at all: see
+    /// `coreSupportsPreconditionTokens`.
+    let preconditionToken: String?
+    /// Verbatim refusal from the same guard the write runs; presence means
+    /// "Connect unavailable" (contracts §1).
+    let connectRefusal: String?
+    /// Whether the core that produced this preview speaks the spec-091
+    /// precondition protocol at all — i.e. it sent `precondition_token`, which
+    /// a 091 core always does even when the value is empty.
+    ///
+    /// A pre-091 core omits the field entirely and its write falls back to its
+    /// legacy behaviour, so for THAT core the overwrite stays available and is
+    /// sent tokenless. Gating on the value alone left an app newer than its
+    /// core showing a full preview with no action and no explanation.
+    let coreSupportsPreconditionTokens: Bool
+
+    enum CodingKeys: String, CodingKey {
+        case client
+        case configPath = "config_path"
+        case serverName = "server_name"
+        case entryText = "entry_text"
+        case entryExists = "entry_exists"
+        case containsAPIKey = "contains_api_key"
+        case accessState = "access_state"
+        case existingEntrySummary = "existing_entry_summary"
+        case preconditionToken = "precondition_token"
+        case connectRefusal = "connect_refusal"
+    }
+
+    init(
+        client: String? = nil,
+        configPath: String,
+        serverName: String,
+        entryText: String,
+        entryExists: Bool,
+        containsAPIKey: Bool,
+        accessState: ConnectAccessState,
+        existingEntrySummary: ConnectEntrySummary? = nil,
+        preconditionToken: String? = nil,
+        connectRefusal: String? = nil,
+        coreSupportsPreconditionTokens: Bool = true
+    ) {
+        self.client = client
+        self.configPath = configPath
+        self.serverName = serverName
+        self.entryText = entryText
+        self.entryExists = entryExists
+        self.containsAPIKey = containsAPIKey
+        self.accessState = accessState
+        self.existingEntrySummary = existingEntrySummary
+        self.preconditionToken = preconditionToken
+        self.connectRefusal = connectRefusal
+        self.coreSupportsPreconditionTokens = coreSupportsPreconditionTokens
+    }
+
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        client = try container.decodeIfPresent(String.self, forKey: .client)
+        configPath = try container.decodeIfPresent(String.self, forKey: .configPath) ?? ""
+        serverName = try container.decodeIfPresent(String.self, forKey: .serverName)
+            ?? ConnectPreviewModel.defaultServerName
+        entryText = try container.decodeIfPresent(String.self, forKey: .entryText) ?? ""
+        entryExists = try container.decodeIfPresent(Bool.self, forKey: .entryExists) ?? false
+        containsAPIKey = try container.decodeIfPresent(Bool.self, forKey: .containsAPIKey) ?? false
+        accessState = try container.decodeIfPresent(ConnectAccessState.self, forKey: .accessState)
+            ?? .unknown
+        existingEntrySummary = try container.decodeIfPresent(
+            ConnectEntrySummary.self, forKey: .existingEntrySummary)
+        preconditionToken = try container.decodeIfPresent(String.self, forKey: .preconditionToken)
+        // The KEY, not the value: a 091 core always sends the field (possibly
+        // empty), a pre-091 core never does — and only the latter is entitled
+        // to the legacy tokenless write.
+        coreSupportsPreconditionTokens = container.contains(.preconditionToken)
+        // An empty string is the Go zero value for an omitted refusal; treat it
+        // as "no refusal" so `connect_refusal: ""` cannot disable Connect.
+        let refusal = try container.decodeIfPresent(String.self, forKey: .connectRefusal)
+        connectRefusal = (refusal?.isEmpty ?? true) ? nil : refusal
+    }
+
+    /// The entry name the form defaults to, matching the core's own default.
+    static let defaultServerName = "mcpproxy"
+
+    // MARK: Derived
+
+    /// Classification of the pending change (data-model). Refusal outranks
+    /// everything: an OpenCode preview with an absent config is refused, NOT a
+    /// create, or the form would promise a file it can never write.
+    var changeKind: ConnectChangeKind {
+        if let connectRefusal, !connectRefusal.isEmpty {
+            return .refused(connectRefusal)
+        }
+        switch accessState {
+        case .denied, .malformed:
+            return .blockedByAccess(accessState)
+        case .absent:
+            return .create
+        case .accessible, .unknown:
+            break
+        }
+        if entryExists {
+            return .replace(entryName: existingEntrySummary?.entryName.isEmpty == false
+                            ? existingEntrySummary!.entryName
+                            : serverName)
+        }
+        return .add
+    }
+
+    /// Whether a Connect control may exist for this preview (SC-002).
+    var allowsConnect: Bool { changeKind.allowsConnect }
+
+    /// An overwrite this form may not offer: the core speaks the precondition
+    /// protocol but gave no token, so the write could not be bound to what the
+    /// user is looking at, and `force` is never sent without one (FR-005).
+    var replaceIsBlockedByAMissingToken: Bool {
+        changeKind.requiresForce && coreSupportsPreconditionTokens
+            && (preconditionToken ?? "").isEmpty
+    }
+
+    /// The safety net the user is promised BEFORE the action button (FR-003).
+    var safetyNetStatement: String? {
+        // Never promise a backup for a write that cannot even be started.
+        if replaceIsBlockedByAMissingToken { return nil }
+        switch changeKind {
+        case .create:
+            return "This file does not exist; it will be created, and Undo removes it."
+        case .add, .replace:
+            return "A timestamped backup of this file will be created alongside it."
+        case .refused, .blockedByAccess:
+            return nil
+        }
+    }
+
+    /// Disclosure that the pending entry embeds the admin credential (FR-004).
+    var credentialNotice: String? {
+        guard containsAPIKey else { return nil }
+        return "This entry embeds the MCPProxy API key in the client's config file."
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Core/SocketTransport.swift b/native/macos/MCPProxy/MCPProxy/Core/SocketTransport.swift
index c35f3b91..af2799c3 100644
--- a/native/macos/MCPProxy/MCPProxy/Core/SocketTransport.swift
+++ b/native/macos/MCPProxy/MCPProxy/Core/SocketTransport.swift
@@ -37,6 +37,33 @@ final class SocketURLProtocol: URLProtocol {
     /// `/Users/<name>/.mcpproxy/mcpproxy.sock` is not.
     static let routeHeader = "X-MCPProxy-Route"
 
+    /// Header marking a request that must NEVER leave over TCP.
+    ///
+    /// The unrouted fallback below ("intercept only if the default socket
+    /// exists, otherwise let it go out over TCP") is right for reads and wrong
+    /// for administrative writes: if the socket disappears mid-session, a
+    /// connect/undo/disconnect would silently ride 127.0.0.1:8080 instead, which
+    /// is exactly the non-socket case the spec forbids (research D6). A strict
+    /// request is intercepted regardless, so it fails loudly instead.
+    ///
+    /// Like the route header it is a transport hint and never goes on the wire.
+    static let strictSocketHeader = "X-MCPProxy-Strict-Socket"
+
+    /// Whether this request refuses a TCP fallback.
+    static func isStrictSocket(_ request: URLRequest) -> Bool {
+        request.value(forHTTPHeaderField: strictSocketHeader) != nil
+    }
+
+    /// The interception rule, as a pure function of the request and whether the
+    /// default socket file exists — so it can be tested without a socket.
+    static func shouldIntercept(request: URLRequest, defaultSocketExists: Bool) -> Bool {
+        // A request that carries a route is PINNED to that socket (see canInit).
+        if routedSocketPath(for: request) != nil { return true }
+        // A strict request may not fall back to TCP, ever.
+        if isStrictSocket(request) { return true }
+        return defaultSocketExists
+    }
+
     /// token -> socket path. Written once per session at creation and read on
     /// every request. Not an alias for "the current path": each entry belongs to
     /// exactly one session, which is the whole point.
@@ -105,12 +132,13 @@ final class SocketURLProtocol: URLProtocol {
         // there would silently send a client that was told "talk to this core"
         // to whatever happens to be listening on 127.0.0.1:8080 — a different
         // core's health reported as this one's, which is precisely the failure
-        // the routing exists to prevent.
-        if routedSocketPath(for: request) != nil { return true }
-
-        // Unrouted request: legacy behaviour, intercept only if the default
-        // socket exists, otherwise let it go out over TCP.
-        return FileManager.default.fileExists(atPath: socketPath)
+        // the routing exists to prevent. A strict request refuses the fallback
+        // for the same reason. Everything else keeps the legacy behaviour:
+        // intercept only if the default socket exists.
+        return shouldIntercept(
+            request: request,
+            defaultSocketExists: FileManager.default.fileExists(atPath: socketPath)
+        )
     }
 
     override class func canonicalRequest(for request: URLRequest) -> URLRequest {
@@ -249,8 +277,9 @@ final class SocketURLProtocol: URLProtocol {
             for (key, value) in allHeaders {
                 let lowerKey = key.lowercased()
                 if lowerKey == "host" { continue } // already added
-                // Transport routing hint — never goes on the wire.
+                // Transport routing hints — never go on the wire.
                 if lowerKey == Self.routeHeader.lowercased() { continue }
+                if lowerKey == Self.strictSocketHeader.lowercased() { continue }
                 if lowerKey == "content-length" { hasContentLength = true }
                 lines.append("\(key): \(value)")
             }
diff --git a/native/macos/MCPProxy/MCPProxy/MCPProxyApp.swift b/native/macos/MCPProxy/MCPProxy/MCPProxyApp.swift
index f59f4a1b..0c151cb9 100644
--- a/native/macos/MCPProxy/MCPProxy/MCPProxyApp.swift
+++ b/native/macos/MCPProxy/MCPProxy/MCPProxyApp.swift
@@ -62,6 +62,11 @@ final class AppController: NSObject, NSApplicationDelegate, NSWindowDelegate, NS
 
     private var mainWindow: NSWindow?
     private var settingsWindow: NSWindow?
+    /// The Connect Client form. Presented as a sheet on the main window when one
+    /// is up, and as its own window otherwise. The lifecycle owns the window and
+    /// its model together so BOTH exits — the form's Close button and the
+    /// titlebar's red button — tear the form down (see the type's header).
+    @MainActor private let connectClientForm = ConnectFormWindowLifecycle()
     private var cancellables = Set<AnyCancellable>()
     private var keyMonitor: Any?
 
@@ -269,6 +274,14 @@ final class AppController: NSObject, NSApplicationDelegate, NSWindowDelegate, NS
             name: .openWebUI, object: nil
         )
 
+        // Spec 091: the one route into the native Connect Client form. Presented
+        // directly from here — no delayed notification chains, which is what
+        // made the Add Server path fragile.
+        NotificationCenter.default.addObserver(
+            self, selector: #selector(presentConnectClientForm),
+            name: ConnectClientPresentation.route, object: nil
+        )
+
         // Start core
         Task {
             await startCore()
@@ -436,6 +449,70 @@ final class AppController: NSObject, NSApplicationDelegate, NSWindowDelegate, NS
         }
     }
 
+    /// Present the native Connect Client form (spec 091).
+    ///
+    /// Direct presentation, on purpose: the Add Server path posts a notification
+    /// and then hopes two `asyncAfter` hops land in the right order, which is a
+    /// race dressed as a workflow (research D5). Here the window is built and
+    /// shown in this call.
+    @MainActor @objc func presentConnectClientForm() {
+        if connectClientForm.makeKeyIfPresenting() {
+            NSApp.activate(ignoringOtherApps: true)
+            return
+        }
+
+        // Resolved per call: the form may be opened before the core is up, and
+        // must populate itself once it answers rather than needing a reopen.
+        let appState = self.appState
+        let source = DeferredConnectSource(
+            transportKind: appState.apiClient?.transportKind ?? .unixSocket,
+            resolve: { await MainActor.run { appState.apiClient } }
+        )
+        let model = ConnectClientModel(source: source)
+
+        let window = NSWindow(
+            contentRect: NSRect(x: 0, y: 0, width: 820, height: 520),
+            styleMask: [.titled, .closable, .resizable],
+            backing: .buffered,
+            defer: false
+        )
+        window.title = "Connect Client"
+        window.isReleasedWhenClosed = false
+        window.contentView = NSHostingView(
+            rootView: ConnectClientView(model: model, onClose: { [weak self] in
+                self?.dismissConnectClientForm()
+            })
+        )
+        // A sheet on the main window when there is one — the form belongs to the
+        // app the user is already looking at; a standalone window otherwise,
+        // because a menu-bar app often has no window at all.
+        if let host = mainWindow, host.isVisible {
+            // The host is recorded so that closing IT tears the form down: a
+            // sheet gets no close notification of its own, and beginSheet's
+            // completion never runs when the parent closes underneath it.
+            connectClientForm.adopt(window, model: model, host: host)
+            host.beginSheet(window) { [weak self] _ in
+                self?.connectClientForm.windowWillClose(window)
+            }
+            return
+        }
+
+        connectClientForm.adopt(window, model: model)
+
+        NSApp.setActivationPolicy(.regular)
+        window.center()
+        // Owning the delegate is what makes the red button reach the teardown.
+        window.delegate = self
+        setupMainMenu()
+        window.makeKeyAndOrderFront(nil)
+        NSApp.activate(ignoringOtherApps: true)
+    }
+
+    /// Dismiss the form from its own Close button, whichever way it was shown.
+    @MainActor private func dismissConnectClientForm() {
+        connectClientForm.dismiss()
+    }
+
     @objc private func showAddServer() {
         showMainWindow()
         // First switch to the Servers tab so ServersView is mounted and
@@ -460,6 +537,12 @@ final class AppController: NSObject, NSApplicationDelegate, NSWindowDelegate, NS
 
     // NSWindowDelegate — hide from Dock when the last managed window closes.
     func windowWillClose(_ notification: Notification) {
+        // The titlebar's red button lands here and nowhere else: without this,
+        // closing the Connect form that way left its model and its 2 s
+        // reachability poll alive inside a retained, invisible window.
+        MainActor.assumeIsolated {
+            connectClientForm.windowWillClose(notification.object as? NSWindow)
+        }
         // Defer so the closing window has already left the visible set.
         DispatchQueue.main.async { [weak self] in self?.restoreAccessoryIfNoVisibleWindows() }
     }
@@ -925,6 +1008,11 @@ final class AppController: NSObject, NSApplicationDelegate, NSWindowDelegate, NS
         addServer.target = self
         menu.addItem(addServer)
 
+        // Spec 091 FR-001: the native connect journey, beside Add Server. The
+        // item is built by its router so the item and its routing are tested
+        // together (a nil target would make it silently do nothing).
+        menu.addItem(ConnectClientMenuRouter.shared.makeMenuItem())
+
         let openApp = NSMenuItem(title: "Open MCPProxy...", action: #selector(openMainWindow), keyEquivalent: "")
         openApp.target = self
         menu.addItem(openApp)
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ConnectClientModel.swift b/native/macos/MCPProxy/MCPProxy/Views/ConnectClientModel.swift
new file mode 100644
index 00000000..cc931db5
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxy/Views/ConnectClientModel.swift
@@ -0,0 +1,737 @@
+import Foundation
+
+// MARK: - Seams
+
+/// The narrow API surface the Connect Client form depends on.
+///
+/// The form binds to this protocol rather than to `APIClient` so the whole state
+/// machine — above all SC-002's "the Connect control cannot exist without a
+/// matching rendered preview" — is testable from synthesized responses, with no
+/// core, no socket and no client config file involved.
+protocol ConnectClientDataSource: Sendable {
+    /// Whether this client talks to the core over its private local socket. The
+    /// core treats socket callers as administrative, so the mutating controls
+    /// are gated on it (research D6).
+    var transportKind: APIClient.TransportKind { get }
+
+    /// `GET /api/v1/connect` — existence checks only, no config contents read.
+    func connectClients() async throws -> [APIClient.ClientStatus]
+
+    /// `GET /api/v1/connect/{id}` — the one user-initiated content read.
+    func clientDetail(_ clientId: String) async throws -> APIClient.ClientStatus
+
+    /// `GET /api/v1/connect/{id}/preview?server_name=…` — no write.
+    func connectPreview(_ clientId: String, serverName: String) async throws -> ConnectPreviewModel
+
+    /// `POST /api/v1/connect/{id}` — the only write in the happy path.
+    func connect(
+        _ clientId: String,
+        serverName: String,
+        force: Bool,
+        preconditionToken: String?
+    ) async throws -> APIClient.ConnectResult
+
+    /// `POST /api/v1/connect/{id}/undo`.
+    func undoConnect(
+        _ clientId: String,
+        serverName: String,
+        backupName: String?
+    ) async throws -> APIClient.ConnectResult
+
+    /// `DELETE /api/v1/connect/{id}`.
+    func disconnect(_ clientId: String, serverName: String) async throws -> APIClient.ConnectResult
+}
+
+extension APIClient: ConnectClientDataSource {}
+
+/// How the model waits between reachability polls. Injected so tests assert the
+/// interval instead of spending it.
+typealias ConnectClientSleeper = @MainActor @Sendable (TimeInterval) async -> Void
+
+/// A data source that resolves the app's API client at call time.
+///
+/// The form can be opened before the core is up: until a client exists every
+/// call throws `notReady`, which the model renders as the waiting state and
+/// re-tries every two seconds, so the form populates itself the moment the core
+/// answers (FR-013) — no reopening.
+final class DeferredConnectSource: ConnectClientDataSource, @unchecked Sendable {
+
+    /// The tray only ever builds socket-routed clients (`CoreProcessManager`),
+    /// so the identity is known before the client exists. It is passed in rather
+    /// than assumed so a TCP-configured app still disables its writes.
+    let transportKind: APIClient.TransportKind
+
+    private let resolve: @Sendable () async -> APIClient?
+
+    init(
+        transportKind: APIClient.TransportKind = .unixSocket,
+        resolve: @escaping @Sendable () async -> APIClient?
+    ) {
+        self.transportKind = transportKind
+        self.resolve = resolve
+    }
+
+    private func client() async throws -> APIClient {
+        guard let client = await resolve() else { throw APIClientError.notReady }
+        return client
+    }
+
+    func connectClients() async throws -> [APIClient.ClientStatus] {
+        try await client().connectClients()
+    }
+
+    func clientDetail(_ clientId: String) async throws -> APIClient.ClientStatus {
+        try await client().clientDetail(clientId)
+    }
+
+    func connectPreview(_ clientId: String, serverName: String) async throws -> ConnectPreviewModel {
+        try await client().connectPreview(clientId, serverName: serverName)
+    }
+
+    func connect(
+        _ clientId: String,
+        serverName: String,
+        force: Bool,
+        preconditionToken: String?
+    ) async throws -> APIClient.ConnectResult {
+        try await client().connect(
+            clientId, serverName: serverName, force: force, preconditionToken: preconditionToken)
+    }
+
+    func undoConnect(
+        _ clientId: String,
+        serverName: String,
+        backupName: String?
+    ) async throws -> APIClient.ConnectResult {
+        try await client().undoConnect(clientId, serverName: serverName, backupName: backupName)
+    }
+
+    func disconnect(_ clientId: String, serverName: String) async throws -> APIClient.ConnectResult {
+        try await client().disconnect(clientId, serverName: serverName)
+    }
+}
+
+// MARK: - Model
+
+/// State machine behind the native Connect Client form (spec 091).
+///
+/// Everything the view renders is derived here, so the two guarantees that
+/// matter are structural rather than a matter of view discipline:
+///
+/// 1. The Connect control EXISTS only while a preview is resolved for exactly
+///    the current (client, entry name) pair, and only when the core did not
+///    refuse the write and the config was readable (SC-002 / FR-003).
+/// 2. A write is bound to that preview's precondition token; an overwrite sends
+///    `force` only TOGETHER with the token (FR-005).
+@MainActor
+final class ConnectClientModel: ObservableObject {
+
+    /// Reachability poll cadence while the core is down (FR-013).
+    static let pollInterval: TimeInterval = 2
+
+    // MARK: State
+
+    enum ListState: Equatable {
+        case loading
+        /// Rows straight from the stat-only aggregate; no config was read.
+        case loaded([APIClient.ClientStatus])
+        /// Core unreachable; the model keeps polling and populates itself.
+        case coreUnreachable(String)
+    }
+
+    enum DetailState: Equatable {
+        case idle
+        case loading
+        case resolved(APIClient.ClientStatus)
+        case failed(String)
+    }
+
+    enum PreviewState: Equatable {
+        case idle
+        case loading
+        case resolved(ConnectPreviewModel)
+        case failed(String)
+    }
+
+    enum ActionState: Equatable {
+        case idle
+        case inFlight
+        case succeeded(APIClient.ConnectResult)
+        /// A discriminated `precondition_failed` conflict: the previewed state
+        /// drifted, so the form re-previews instead of retrying.
+        case conflict(String)
+        case failed(String)
+    }
+
+    /// The reversibility of the connect performed in THIS form instance.
+    ///
+    /// The core keeps no cross-session undo state — undo depends on the backup
+    /// identity a connect returned — so this is deliberately session-scoped
+    /// (FR-006).
+    enum UndoState: Equatable {
+        case unavailable
+        /// `backupName` nil means the connect CREATED the file, and undo removes
+        /// it; otherwise it is the bare filename of the backup to restore.
+        case available(clientId: String, entryName: String, backupName: String?)
+    }
+
+    /// A disconnect the user asked for and has not yet confirmed. Nothing is
+    /// sent while this is pending: the confirmation names the file and the entry
+    /// first (FR-006, US3 scenario 3).
+    struct DisconnectConfirmation: Equatable {
+        let clientId: String
+        let configPath: String
+        let entryName: String
+
+        /// The disclosure itself: there is no diff endpoint for a disconnect, so
+        /// naming the file and the entry is the defined and sufficient warning.
+        var message: String {
+            "Remove the \"\(entryName)\" entry from \(configPath)? "
+                + "The client stops seeing MCPProxy until you connect it again."
+        }
+    }
+
+    /// One rendered client row (US2).
+    ///
+    /// Its label is the cheap truth from the existence-only aggregate until the
+    /// user selects the client; from then on it is the authoritative state the
+    /// core resolved. The tray never opens a client config to compute any of it.
+    struct ClientRow: Equatable, Identifiable {
+        let clientId: String
+        let displayName: String
+        let symbolName: String
+        /// A statement about the config FILE (or, once resolved, the connection)
+        /// — never about whether the application is installed.
+        let stateLabel: String
+        /// Unsupported clients stay visible but unselectable (FR-009).
+        let isSelectable: Bool
+        /// Extra guidance for the row: the core's remediation when access is
+        /// denied, or its caveat for a supported client.
+        let note: String?
+        let connected: Bool
+
+        var id: String { clientId }
+    }
+
+    @Published private(set) var list: ListState = .loading
+    @Published private(set) var selection: String?
+    @Published private(set) var detail: DetailState = .idle
+    @Published private(set) var preview: PreviewState = .idle
+    @Published private(set) var action: ActionState = .idle
+
+    @Published private(set) var undoState: UndoState = .unavailable
+    @Published private(set) var pendingDisconnect: DisconnectConfirmation?
+
+    /// Authoritative per-client state, keyed by client id, as resolved by the
+    /// explicit detail reads. Only clients the user actually selected appear
+    /// here — that is what keeps opening the list content-read-free (FR-002).
+    @Published private(set) var resolvedDetails: [String: APIClient.ClientStatus] = [:]
+
+    /// Entry name written into the client's config; the advanced override.
+    ///
+    /// Changing it destroys the rendered preview *immediately* — before any
+    /// refetch — because the Connect control is bound to a preview of the
+    /// current inputs and to nothing else.
+    @Published var entryName: String = ConnectPreviewModel.defaultServerName {
+        didSet {
+            guard oldValue != entryName else { return }
+            invalidatePreview()
+        }
+    }
+
+    private let source: ConnectClientDataSource
+    private let sleeper: ConnectClientSleeper
+
+    /// A mutating request is outstanding.
+    ///
+    /// Deliberately NOT derived from `action`: this model is @MainActor, so
+    /// every `await` is a reentrancy point, and the list, the entry-name field
+    /// and the buttons all stay live while a POST is suspended. `action` is the
+    /// OUTCOME the pane displays and gets reset whenever the preview is
+    /// invalidated (a row click, a name edit) — reading busy off it made the
+    /// double-submit protection disappear mid-write, which is how two
+    /// concurrent read-modify-write cycles could land on the same config file.
+    @Published private(set) var inFlight = false
+
+    /// Inputs the currently resolved preview was fetched for.
+    private var previewKey: PreviewKey?
+
+    private struct PreviewKey: Equatable {
+        let clientId: String
+        let entryName: String
+    }
+
+    init(
+        source: ConnectClientDataSource,
+        sleeper: @escaping ConnectClientSleeper = { interval in
+            try? await Task.sleep(nanoseconds: UInt64(interval * 1_000_000_000))
+        }
+    ) {
+        self.source = source
+        self.sleeper = sleeper
+    }
+
+    // MARK: - List
+
+    /// Load the client list, polling every `pollInterval` while the core is
+    /// unreachable and populating without user action once it answers (FR-013).
+    func loadList() async {
+        if case .loaded = list {} else { list = .loading }
+        while !Task.isCancelled {
+            do {
+                list = .loaded(try await source.connectClients())
+                return
+            } catch {
+                list = .coreUnreachable(Self.message(for: error))
+                await sleeper(Self.pollInterval)
+            }
+        }
+    }
+
+    // MARK: - Selection
+
+    /// The selection the list may hold, given the row the user just clicked.
+    ///
+    /// An unsupported client is visible but is NOT a selection (FR-009) — and a
+    /// click on it still moves the list's own highlight. Left there, the
+    /// highlight names one client while the detail pane, the preview and an
+    /// enabled Connect button all still target the previous one, so the form
+    /// would write a config the user was not looking at. The view snaps the
+    /// highlight back to whatever this returns.
+    func listSelection(for candidate: String?) -> String? {
+        guard let candidate,
+              rows.first(where: { $0.clientId == candidate })?.isSelectable == true
+        else { return selection }
+        return candidate
+    }
+
+    /// Select a client: resolve its authoritative state and a fresh preview.
+    /// This is the only place a client config's *contents* are read, and only
+    /// because the user explicitly asked for this client (FR-002).
+    func select(_ clientId: String) async {
+        selection = clientId
+        entryName = ConnectPreviewModel.defaultServerName
+        invalidatePreview()
+        // A confirmation the user walked away from must never survive into
+        // another client's config.
+        pendingDisconnect = nil
+        detail = .idle
+        await refreshDetail()
+        await refreshPreview()
+    }
+
+    func refreshDetail() async {
+        guard let clientId = selection else { return }
+        await refreshDetail(for: clientId)
+    }
+
+    /// Re-read one client's authoritative state. The row keeps it whether or not
+    /// that client is still the selected one — it was read for this client and
+    /// remains true of it — while the detail PANE is only touched when it is.
+    private func refreshDetail(for clientId: String) async {
+        if selection == clientId { detail = .loading }
+        do {
+            let status = try await source.clientDetail(clientId)
+            // The row keeps the resolved state even if the selection moved on:
+            // it was read for this client and remains true of it.
+            resolvedDetails[clientId] = status
+            guard selection == clientId else { return }
+            detail = .resolved(status)
+        } catch {
+            guard selection == clientId else { return }
+            detail = .failed(Self.message(for: error))
+        }
+    }
+
+    /// Fetch the no-write preview for the current (client, entry name).
+    func refreshPreview() async {
+        guard let clientId = selection else { return }
+        let key = PreviewKey(clientId: clientId, entryName: entryName)
+        preview = .loading
+        previewKey = nil
+        do {
+            let fetched = try await source.connectPreview(clientId, serverName: key.entryName)
+            // Inputs may have moved while the request was in flight; a preview
+            // for anything but the current inputs must never gate a write.
+            guard selection == key.clientId, entryName == key.entryName else { return }
+            guard fetched.serverName == key.entryName else {
+                preview = .failed(
+                    "The core previewed entry \"\(fetched.serverName)\", not \"\(key.entryName)\".")
+                return
+            }
+            preview = .resolved(fetched)
+            previewKey = key
+        } catch {
+            guard selection == key.clientId, entryName == key.entryName else { return }
+            preview = .failed(Self.message(for: error))
+        }
+    }
+
+    private func invalidatePreview() {
+        preview = .idle
+        previewKey = nil
+        // Only a SETTLED outcome is cleared: a request still in flight will
+        // publish its own, and erasing its marker here would hide the spinner
+        // while the write is still running.
+        if !inFlight { action = .idle }
+    }
+
+    // MARK: - Rows (US2)
+
+    /// The client list as rendered: stat-only labels, overlaid with whatever the
+    /// core has resolved for clients the user selected (FR-002, US2).
+    var rows: [ClientRow] {
+        guard case .loaded(let clients) = list else { return [] }
+        return clients.map(row(for:))
+    }
+
+    private func row(for client: APIClient.ClientStatus) -> ClientRow {
+        let resolved = resolvedDetails[client.clientId] ?? client
+        return ClientRow(
+            clientId: client.clientId,
+            displayName: client.displayName,
+            symbolName: client.symbolName,
+            stateLabel: Self.stateLabel(for: resolved),
+            isSelectable: client.supported,
+            note: Self.note(for: resolved),
+            connected: resolved.connected
+        )
+    }
+
+    /// The row's one-line state. Order matters: platform support first (nothing
+    /// else is meaningful for a client that cannot be connected here), then the
+    /// access states that block a write, then the connection, then the file.
+    private static func stateLabel(for client: APIClient.ClientStatus) -> String {
+        if !client.supported {
+            let reason = client.reason ?? ""
+            return reason.isEmpty ? "Not supported on this platform" : reason
+        }
+        switch client.accessState {
+        case .malformed:
+            return "Config unreadable"
+        case .denied:
+            return "Access not granted"
+        case .accessible, .absent, .unknown, .none:
+            break
+        }
+        if client.connected {
+            let entry = client.serverName ?? ""
+            return entry.isEmpty ? "Connected" : "Connected as \"\(entry)\""
+        }
+        // The cheap truth: about the config FILE, not about the application.
+        return client.exists ? "Config present" : "No config found"
+    }
+
+    private static func note(for client: APIClient.ClientStatus) -> String? {
+        if client.accessState == .denied, let remediation = client.remediation,
+           !remediation.isEmpty {
+            return remediation
+        }
+        if let note = client.note, !note.isEmpty { return note }
+        return nil
+    }
+
+    // MARK: - Derived
+
+    /// The currently rendered preview, or nil when none is bound to the current
+    /// inputs.
+    var currentPreview: ConnectPreviewModel? {
+        guard let selection,
+              case .resolved(let preview) = preview,
+              previewKey == PreviewKey(clientId: selection, entryName: entryName)
+        else { return nil }
+        return preview
+    }
+
+    /// SC-002: whether a Connect control may be rendered at all.
+    ///
+    /// It requires a preview resolved for exactly these inputs, a change the
+    /// core did not refuse, a readable config — and, for an overwrite, a
+    /// precondition token, because the form never sends `force` without one.
+    var connectControlExists: Bool {
+        guard let preview = currentPreview, preview.allowsConnect else { return false }
+        return !preview.replaceIsBlockedByAMissingToken
+    }
+
+    /// Why a resolved preview offers no Connect control, or nil when it does (or
+    /// when the core's own refusal already explains it).
+    ///
+    /// A preview that renders in full with no button and nothing said about it
+    /// is a dead end: the user has no way to tell a deliberate safety stop from
+    /// a broken form.
+    var connectBlockedReason: String? {
+        guard let preview = currentPreview, preview.allowsConnect,
+              preview.replaceIsBlockedByAMissingToken
+        else { return nil }
+        return "MCPProxy could not bind this replacement to the preview above, "
+            + "so it will not overwrite the existing entry. Reopen the form or "
+            + "reselect this client to get a fresh preview."
+    }
+
+    /// Why the mutating controls are disabled, or nil when they are usable.
+    /// The list, detail and preview are unaffected — off-socket the form still
+    /// explains the state it cannot change.
+    var mutatingDisabledReason: String? {
+        guard source.transportKind != .unixSocket else { return nil }
+        return "Connect, Undo and Disconnect need MCPProxy's private local socket. "
+            + "This app is talking to the core over TCP, so they are unavailable."
+    }
+
+    /// A request is in flight; every action button disables (double-click
+    /// protection, spec Edge Cases).
+    var isBusy: Bool { inFlight }
+
+    var isConnectEnabled: Bool {
+        connectControlExists && mutatingDisabledReason == nil && !isBusy
+    }
+
+    /// The core's verbatim refusal for the rendered preview, when it refused.
+    var connectRefusal: String? {
+        guard case .refused(let reason)? = currentPreview?.changeKind else { return nil }
+        return reason
+    }
+
+    // MARK: - Connect
+
+    /// Perform the previewed write: the preview's token always rides along, and
+    /// `force` only ever together with it (FR-005).
+    func connect() async {
+        guard let clientId = selection,
+              let preview = currentPreview,
+              isConnectEnabled
+        else { return }
+
+        let entryName = self.entryName
+        beginRequest()
+
+        var outcome: ActionState
+        var rePreviewOnly = false
+        do {
+            let result = try await source.connect(
+                clientId,
+                serverName: entryName,
+                force: preview.changeKind.requiresForce,
+                preconditionToken: preview.preconditionToken
+            )
+            outcome = .succeeded(result)
+            // FR-006: undo becomes available for exactly this connect, carrying
+            // the identity it returned — no identity means it created the file.
+            undoState = .available(
+                clientId: clientId,
+                entryName: entryName,
+                backupName: Self.backupIdentity(from: result.backupPath))
+        } catch let error as APIClientError {
+            switch error {
+            case .connectConflict(let conflictAction, let message)
+                where conflictAction == Self.preconditionFailedAction:
+                // The previewed state drifted: re-preview ONCE. Never retry the
+                // write — that is what would loop.
+                outcome = .conflict(message)
+                rePreviewOnly = true
+            case .connectConflict(_, let message):
+                // The legacy `already_exists` conflict cannot occur in this flow
+                // (a replace always sends force); if it does it is a plain
+                // failure, and re-previewing on it would loop forever.
+                outcome = .failed(message)
+            default:
+                outcome = .failed(Self.message(for: error))
+            }
+        } catch {
+            outcome = .failed(Self.message(for: error))
+        }
+
+        // The request is settled BEFORE the refresh: the refresh reads, it does
+        // not write, so the controls are usable again while it runs.
+        endRequest(with: outcome, for: clientId)
+
+        if rePreviewOnly {
+            await refreshPreviewPreservingAction(for: clientId)
+        } else if case .succeeded = outcome {
+            // The form shows the refreshed state without being reopened.
+            await refreshAffectedClient(clientId)
+        }
+    }
+
+    /// Mark a mutating request as started. `action` carries the marker for the
+    /// pane's spinner; `inFlight` is what actually gates the controls.
+    private func beginRequest() {
+        inFlight = true
+        action = .inFlight
+    }
+
+    /// Settle a mutating request. The outcome is published ONLY into the pane of
+    /// the client it belongs to: the user may have moved on while it was in
+    /// flight, and one client's success banner must never appear under another
+    /// client's name.
+    private func endRequest(with outcome: ActionState, for clientId: String) {
+        inFlight = false
+        guard selection == clientId else {
+            if action == .inFlight { action = .idle }
+            return
+        }
+        action = outcome
+    }
+
+    /// The core's discriminator for "the state you previewed has changed".
+    static let preconditionFailedAction = "precondition_failed"
+
+    // MARK: - Undo (session-scoped)
+
+    /// FR-006: the undo affordance exists only for a connect performed in this
+    /// open form, and only while its client is the one on screen.
+    var undoControlExists: Bool {
+        guard case .available(let clientId, _, _) = undoState else { return false }
+        return clientId == selection
+    }
+
+    var isUndoEnabled: Bool {
+        undoControlExists && mutatingDisabledReason == nil && !isBusy
+    }
+
+    /// Reverse the connect performed in this form: restore its backup, or — when
+    /// it created the file — remove that file. The affordance disappears once
+    /// used; there is no second undo to give.
+    func undo() async {
+        guard case .available(let clientId, let entry, let backupName) = undoState,
+              isUndoEnabled
+        else { return }
+
+        beginRequest()
+        var outcome: ActionState
+        do {
+            let result = try await source.undoConnect(
+                clientId, serverName: entry, backupName: backupName)
+            undoState = .unavailable
+            outcome = .succeeded(result)
+        } catch {
+            // The connect stands, so the affordance stands: the user can retry.
+            outcome = .failed(Self.message(for: error))
+        }
+        endRequest(with: outcome, for: clientId)
+        if case .succeeded = outcome {
+            await refreshAffectedClient(clientId)
+        }
+    }
+
+    /// The core takes the BARE FILENAME of the backup (a path is a 400), while
+    /// the connect result reports the full path — so the identity is reduced
+    /// here, once, rather than at each call site.
+    private static func backupIdentity(from backupPath: String?) -> String? {
+        guard let backupPath, !backupPath.isEmpty else { return nil }
+        let name = (backupPath as NSString).lastPathComponent
+        return name.isEmpty ? nil : name
+    }
+
+    /// Called when the form closes: the undo's scope ends with it, and an
+    /// unanswered confirmation is abandoned rather than remembered.
+    func formWillClose() {
+        undoState = .unavailable
+        pendingDisconnect = nil
+    }
+
+    // MARK: - Disconnect
+
+    /// The entry this client is currently registered under, when it is
+    /// connected — the name a disconnect would remove.
+    var connectedEntryName: String? {
+        guard let clientId = selection, let resolved = resolvedDetails[clientId],
+              resolved.connected
+        else { return nil }
+        let entry = resolved.serverName ?? ""
+        return entry.isEmpty ? entryName : entry
+    }
+
+    /// Disconnect is offered for any connected client (FR-006).
+    var disconnectControlExists: Bool { connectedEntryName != nil }
+
+    var isDisconnectEnabled: Bool {
+        disconnectControlExists && mutatingDisabledReason == nil && !isBusy
+    }
+
+    /// Ask for the disconnect. This only raises the confirmation — the request
+    /// is sent by `confirmDisconnect`, so there is no code path from the button
+    /// to the write that skips the disclosure (FR-006).
+    func requestDisconnect() {
+        guard let clientId = selection,
+              let entry = connectedEntryName,
+              isDisconnectEnabled
+        else { return }
+
+        pendingDisconnect = DisconnectConfirmation(
+            clientId: clientId,
+            configPath: disconnectConfigPath(for: clientId),
+            entryName: entry)
+    }
+
+    func cancelDisconnect() {
+        pendingDisconnect = nil
+    }
+
+    /// Send the confirmed disconnect and refresh only that client (US2 sc. 3).
+    func confirmDisconnect() async {
+        guard let confirmation = pendingDisconnect else { return }
+        pendingDisconnect = nil
+        guard selection == confirmation.clientId, isDisconnectEnabled else { return }
+
+        beginRequest()
+        var outcome: ActionState
+        do {
+            let result = try await source.disconnect(
+                confirmation.clientId, serverName: confirmation.entryName)
+            outcome = .succeeded(result)
+        } catch {
+            outcome = .failed(Self.message(for: error))
+        }
+        endRequest(with: outcome, for: confirmation.clientId)
+        if case .succeeded = outcome {
+            await refreshAffectedClient(confirmation.clientId)
+        }
+    }
+
+    /// The file the confirmation names: the core's own path for this client,
+    /// never one the tray composed itself.
+    private func disconnectConfigPath(for clientId: String) -> String {
+        if let resolved = resolvedDetails[clientId], !resolved.configPath.isEmpty {
+            return resolved.configPath
+        }
+        return currentPreview?.configPath ?? ""
+    }
+
+    /// After a completed action, re-read ONLY the affected client and re-run its
+    /// preview, so the form shows the new truth without being reopened and
+    /// without refetching (or reading) anything else (US2 scenario 3).
+    ///
+    /// The client is the one the action was performed on, not whatever is
+    /// selected now: its row must show what the write produced even if the user
+    /// has moved on — but the PREVIEW pane belongs to the current selection, so
+    /// it is only re-run while that is still the same client.
+    private func refreshAffectedClient(_ clientId: String) async {
+        await refreshDetail(for: clientId)
+        guard selection == clientId else { return }
+        await refreshPreviewPreservingAction(for: clientId)
+    }
+
+    /// Re-run the preview without letting `invalidatePreview`'s action reset
+    /// erase the outcome the user is being shown.
+    ///
+    /// The outcome is restored ONLY if nothing newer took the action's place
+    /// while the refetch was in flight. Writing it back unconditionally
+    /// resurrected a settled outcome over a request the user had started since
+    /// (an Undo clicked during this very refresh), which both hid that
+    /// request's own result and re-enabled the button that sent it.
+    private func refreshPreviewPreservingAction(for clientId: String) async {
+        let outcome = action
+        await refreshPreview()
+        guard selection == clientId, action == .idle else { return }
+        action = outcome
+    }
+
+    // MARK: - Helpers
+
+    private static func message(for error: Error) -> String {
+        if let localized = error as? LocalizedError, let description = localized.errorDescription {
+            return description
+        }
+        return error.localizedDescription
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ConnectClientView.swift b/native/macos/MCPProxy/MCPProxy/Views/ConnectClientView.swift
new file mode 100644
index 00000000..424c0bbf
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxy/Views/ConnectClientView.swift
@@ -0,0 +1,490 @@
+import SwiftUI
+import AppKit
+
+// MARK: - Presentation route
+
+/// The single way into the Connect Client form.
+///
+/// Both the tray menu item and (FR-012) the dashboard's connect control post
+/// this route, so no native path can reach a config write that skipped the
+/// preview step.
+enum ConnectClientPresentation {
+    /// Posted to request the form. Observed by the app delegate, which presents
+    /// it directly — no delayed notification chains (research D5).
+    static let route = Notification.Name("MCPProxy.showConnectClient")
+
+    /// Title of the tray menu item, beside "Add Server…".
+    static let menuTitle = "Connect Client…"
+
+    /// Request the form.
+    static func present() {
+        NotificationCenter.default.post(name: route, object: nil)
+    }
+}
+
+/// Owns the tray menu item so the item and its routing are testable together:
+/// a menu item with an action but no target silently does nothing.
+final class ConnectClientMenuRouter: NSObject {
+    static let shared = ConnectClientMenuRouter()
+
+    @objc func openConnectClientForm(_ sender: Any?) {
+        ConnectClientPresentation.present()
+    }
+
+    func makeMenuItem(keyEquivalent: String = "") -> NSMenuItem {
+        let item = NSMenuItem(
+            title: ConnectClientPresentation.menuTitle,
+            action: #selector(openConnectClientForm(_:)),
+            keyEquivalent: keyEquivalent
+        )
+        item.target = self
+        return item
+    }
+}
+
+// MARK: - Accessibility identifiers
+
+/// Stable identifiers for VoiceOver and UI tests (FR-010). These are a contract
+/// with external callers: rename one and a UI test stops finding the element.
+enum ConnectClientAccessibility {
+    static let list = "connect-client-list"
+    static let preview = "connect-client-preview"
+    static let entryText = "connect-client-entry-text"
+    static let configPath = "connect-client-config-path"
+    static let existingSummary = "connect-client-existing-summary"
+    static let safetyNet = "connect-client-safety-net"
+    static let credentialNotice = "connect-client-credential-notice"
+    static let refusal = "connect-client-refusal"
+    /// Shown where the Connect button would be when the write is not offered.
+    static let connectBlocked = "connect-client-connect-blocked"
+    static let entryNameField = "connect-client-entry-name"
+    static let advancedDisclosure = "connect-client-advanced"
+    static let connectButton = "connect-client-connect"
+    static let undoButton = "connect-client-undo"
+    static let disconnectButton = "connect-client-disconnect"
+    static let disconnectConfirm = "connect-client-disconnect-confirm"
+    static let closeButton = "connect-client-close"
+    static let status = "connect-client-status"
+    static let waiting = "connect-client-waiting"
+    static let transportNotice = "connect-client-transport-notice"
+
+    /// Identifier of one client row.
+    static func row(_ clientId: String) -> String { "connect-client-row-\(clientId)" }
+
+    /// Every fixed identifier, for the uniqueness check.
+    static let allIdentifiers: [String] = [
+        list, preview, entryText, configPath, existingSummary, safetyNet,
+        credentialNotice, refusal, connectBlocked, entryNameField, advancedDisclosure,
+        connectButton, undoButton, disconnectButton, disconnectConfirm,
+        closeButton, status, waiting, transportNotice
+    ]
+}
+
+// MARK: - View
+
+/// The native Connect Client form: a stat-only client list on the left, and the
+/// selected client's authoritative state plus the no-write preview on the right.
+///
+/// Deliberately thin — every decision (what the change is, whether a Connect
+/// control may exist at all, what a failure says) lives in `ConnectClientModel`
+/// and is unit-tested there.
+struct ConnectClientView: View {
+    @ObservedObject var model: ConnectClientModel
+    var onClose: () -> Void = {}
+
+    @State private var selectedID: String?
+    @State private var showAdvanced = false
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 0) {
+            header
+            Divider()
+            HStack(spacing: 0) {
+                clientList
+                    .frame(width: 260)
+                Divider()
+                detailPane
+                    .frame(maxWidth: .infinity, alignment: .topLeading)
+            }
+            Divider()
+            actionBar
+        }
+        .frame(minWidth: 760, minHeight: 480)
+        .task { await model.loadList() }
+        .alert("Disconnect this client?", isPresented: disconnectConfirmationIsPresented,
+               presenting: model.pendingDisconnect) { _ in
+            Button("Cancel", role: .cancel) { model.cancelDisconnect() }
+            Button("Disconnect", role: .destructive) {
+                Task { await model.confirmDisconnect() }
+            }
+            .accessibilityIdentifier(ConnectClientAccessibility.disconnectConfirm)
+        } message: { confirmation in
+            Text(confirmation.message)
+        }
+    }
+
+    /// Presentation is driven by the model's pending confirmation. The setter is
+    /// deliberately inert: both buttons resolve the state themselves, and having
+    /// dismissal clear it would race the confirm action into a no-op.
+    private var disconnectConfirmationIsPresented: Binding<Bool> {
+        Binding(get: { model.pendingDisconnect != nil }, set: { _ in })
+    }
+
+    // MARK: Header
+
+    private var header: some View {
+        VStack(alignment: .leading, spacing: 4) {
+            Text("Connect a Client")
+                .font(.headline)
+            Text("Register MCPProxy in an AI client's MCP config. "
+                 + "Nothing is written until you review the change and press Connect.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+        .padding(16)
+    }
+
+    // MARK: List
+
+    @ViewBuilder
+    private var clientList: some View {
+        switch model.list {
+        case .loading:
+            ProgressView("Loading clients…")
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+        case .coreUnreachable(let reason):
+            VStack(spacing: 8) {
+                Image(systemName: "bolt.horizontal.circle")
+                    .font(.title2)
+                    .foregroundStyle(.secondary)
+                Text("Waiting for the MCPProxy core…")
+                    .font(.subheadline)
+                Text(reason)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .multilineTextAlignment(.center)
+            }
+            .padding()
+            .frame(maxWidth: .infinity, maxHeight: .infinity)
+            .accessibilityIdentifier(ConnectClientAccessibility.waiting)
+        case .loaded:
+            List(model.rows, selection: $selectedID) { row in
+                rowView(row)
+                    .tag(row.clientId)
+                    .modifier(RowSelectability(isSelectable: row.isSelectable))
+                    .accessibilityIdentifier(ConnectClientAccessibility.row(row.clientId))
+            }
+            .accessibilityIdentifier(ConnectClientAccessibility.list)
+            // Changing client mid-write would leave the outcome pointing at a
+            // pane the user is no longer looking at (the model scopes it, but
+            // the interaction is meaningless anyway while a write runs).
+            .disabled(model.isBusy)
+            .onChange(of: selectedID) { newValue in
+                // An unsupported client stays visible but is not a selection:
+                // there is nothing the form could do for it (FR-009). Leaving
+                // the highlight on it would point at one client while the pane
+                // and the Connect button still target another, so it snaps back.
+                let allowed = model.listSelection(for: newValue)
+                guard allowed == newValue else {
+                    selectedID = allowed
+                    return
+                }
+                guard let newValue, newValue != model.selection else { return }
+                Task { await model.select(newValue) }
+            }
+        }
+    }
+
+    /// Tells the List which rows are not selectable, so keyboard navigation
+    /// SKIPS them instead of landing on one and being bounced back by the
+    /// snap-back guard — which, on an arrow-key walk, makes every supported row
+    /// below an unsupported one unreachable (the mouse can jump past it; the
+    /// arrows cannot).
+    ///
+    /// `selectionDisabled` is macOS 14+. On macOS 13 the model-side guard stays
+    /// the only backstop: a click still moves the highlight and snaps back.
+    private struct RowSelectability: ViewModifier {
+        let isSelectable: Bool
+
+        func body(content: Content) -> some View {
+            if #available(macOS 14.0, *) {
+                content.selectionDisabled(!isSelectable)
+            } else {
+                content
+            }
+        }
+    }
+
+    /// Every label here is derived in the model (and unit-tested there); the row
+    /// only renders it.
+    private func rowView(_ row: ConnectClientModel.ClientRow) -> some View {
+        HStack(spacing: 10) {
+            Image(systemName: row.symbolName)
+                .foregroundStyle(row.connected ? Color.green : Color.secondary)
+                .frame(width: 20)
+            VStack(alignment: .leading, spacing: 2) {
+                Text(row.displayName)
+                    .font(.subheadline)
+                Text(row.stateLabel)
+                    .font(.caption2)
+                    .foregroundStyle(.secondary)
+                if let note = row.note {
+                    Text(note)
+                        .font(.caption2)
+                        .foregroundStyle(.orange)
+                }
+            }
+            Spacer()
+        }
+        .padding(.vertical, 2)
+        .opacity(row.isSelectable ? 1 : 0.5)
+        .accessibilityElement(children: .combine)
+        .accessibilityLabel("\(row.displayName), \(row.stateLabel)")
+    }
+
+    // MARK: Detail + preview
+
+    @ViewBuilder
+    private var detailPane: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 12) {
+                if model.selection == nil {
+                    Text("Select a client to see what would be written.")
+                        .font(.callout)
+                        .foregroundStyle(.secondary)
+                } else {
+                    detailSection
+                    previewSection
+                    advancedSection
+                    statusSection
+                }
+            }
+            .padding(16)
+            .frame(maxWidth: .infinity, alignment: .leading)
+        }
+    }
+
+    @ViewBuilder
+    private var detailSection: some View {
+        switch model.detail {
+        case .idle, .loading:
+            ProgressView().controlSize(.small)
+        case .failed(let message):
+            Label(message, systemImage: "exclamationmark.triangle")
+                .font(.caption)
+                .foregroundStyle(.orange)
+        case .resolved(let status):
+            VStack(alignment: .leading, spacing: 4) {
+                Text(status.displayName).font(.title3)
+                Text(status.connected
+                     ? "Connected as \"\(status.serverName ?? model.entryName)\""
+                     : "Not connected to this proxy")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                if let remediation = status.remediation, !remediation.isEmpty {
+                    Text(remediation)
+                        .font(.caption)
+                        .foregroundStyle(.orange)
+                }
+            }
+        }
+    }
+
+    @ViewBuilder
+    private var previewSection: some View {
+        switch model.preview {
+        case .idle, .loading:
+            ProgressView("Preparing preview…")
+                .controlSize(.small)
+        case .failed(let message):
+            Label(message, systemImage: "exclamationmark.triangle.fill")
+                .font(.caption)
+                .foregroundStyle(.red)
+                .accessibilityIdentifier(ConnectClientAccessibility.preview)
+        case .resolved(let preview):
+            VStack(alignment: .leading, spacing: 10) {
+                labelledRow("Config file", preview.configPath,
+                            identifier: ConnectClientAccessibility.configPath)
+
+                VStack(alignment: .leading, spacing: 4) {
+                    Text("Entry to be written").font(.caption).foregroundStyle(.secondary)
+                    Text(preview.entryText)
+                        .font(.system(.caption, design: .monospaced))
+                        .textSelection(.enabled)
+                        .padding(8)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+                        .background(Color.secondary.opacity(0.08))
+                        .clipShape(RoundedRectangle(cornerRadius: 6))
+                        .accessibilityIdentifier(ConnectClientAccessibility.entryText)
+                }
+
+                if let summary = preview.existingEntrySummary {
+                    existingSummaryView(summary)
+                }
+
+                if let safetyNet = preview.safetyNetStatement {
+                    Label(safetyNet, systemImage: "arrow.uturn.backward.circle")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .accessibilityIdentifier(ConnectClientAccessibility.safetyNet)
+                }
+
+                if let credential = preview.credentialNotice {
+                    Label(credential, systemImage: "key.fill")
+                        .font(.caption)
+                        .foregroundStyle(.orange)
+                        .accessibilityIdentifier(ConnectClientAccessibility.credentialNotice)
+                }
+
+                if let refusal = model.connectRefusal {
+                    Label(refusal, systemImage: "nosign")
+                        .font(.caption)
+                        .foregroundStyle(.red)
+                        .accessibilityIdentifier(ConnectClientAccessibility.refusal)
+                }
+
+                // A control that cannot exist always says so — a full preview
+                // with no button and no explanation is a dead end.
+                if let blocked = model.connectBlockedReason {
+                    Label(blocked, systemImage: "exclamationmark.triangle")
+                        .font(.caption)
+                        .foregroundStyle(.orange)
+                        .accessibilityIdentifier(ConnectClientAccessibility.connectBlocked)
+                }
+            }
+            .accessibilityIdentifier(ConnectClientAccessibility.preview)
+        }
+    }
+
+    /// The structural, non-secret description of the entry being replaced. It
+    /// carries names only — never a header or environment VALUE.
+    private func existingSummaryView(_ summary: ConnectEntrySummary) -> some View {
+        VStack(alignment: .leading, spacing: 3) {
+            Text("Replacing existing entry \"\(summary.entryName)\"")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+            if let type = summary.type { Text("Type: \(type)").font(.caption2) }
+            if let endpoint = summary.endpoint { Text("Endpoint: \(endpoint)").font(.caption2) }
+            if let command = summary.command { Text("Command: \(command)").font(.caption2) }
+            if !summary.headerNames.isEmpty {
+                Text("Headers: \(summary.headerNames.joined(separator: ", "))").font(.caption2)
+            }
+            if !summary.envNames.isEmpty {
+                Text("Environment: \(summary.envNames.joined(separator: ", "))").font(.caption2)
+            }
+        }
+        .foregroundStyle(.secondary)
+        .padding(8)
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .background(Color.secondary.opacity(0.06))
+        .clipShape(RoundedRectangle(cornerRadius: 6))
+        .accessibilityIdentifier(ConnectClientAccessibility.existingSummary)
+    }
+
+    /// FR-007: the entry-name override is advanced and collapsed by default.
+    private var advancedSection: some View {
+        DisclosureGroup("Advanced", isExpanded: $showAdvanced) {
+            VStack(alignment: .leading, spacing: 4) {
+                TextField("Entry name", text: $model.entryName)
+                    .textFieldStyle(.roundedBorder)
+                    // The name is bound to the write that is already running.
+                    .disabled(model.isBusy)
+                    .accessibilityIdentifier(ConnectClientAccessibility.entryNameField)
+                Text("Changing this discards the preview and fetches a new one.")
+                    .font(.caption2)
+                    .foregroundStyle(.secondary)
+            }
+            .padding(.top, 4)
+        }
+        .font(.caption)
+        .accessibilityIdentifier(ConnectClientAccessibility.advancedDisclosure)
+        .onChange(of: model.entryName) { _ in
+            Task { await model.refreshPreview() }
+        }
+    }
+
+    @ViewBuilder
+    private var statusSection: some View {
+        switch model.action {
+        case .idle, .inFlight:
+            EmptyView()
+        case .succeeded(let result):
+            Label(result.message ?? "Connected.", systemImage: "checkmark.circle.fill")
+                .font(.caption)
+                .foregroundStyle(.green)
+                .accessibilityIdentifier(ConnectClientAccessibility.status)
+        case .conflict(let reason):
+            Label("\(reason) The preview has been refreshed — review it and try again.",
+                  systemImage: "arrow.triangle.2.circlepath")
+                .font(.caption)
+                .foregroundStyle(.orange)
+                .accessibilityIdentifier(ConnectClientAccessibility.status)
+        case .failed(let reason):
+            Label(reason, systemImage: "xmark.octagon.fill")
+                .font(.caption)
+                .foregroundStyle(.red)
+                .accessibilityIdentifier(ConnectClientAccessibility.status)
+        }
+    }
+
+    // MARK: Actions
+
+    private var actionBar: some View {
+        HStack(spacing: 10) {
+            if let reason = model.mutatingDisabledReason {
+                Label(reason, systemImage: "lock.fill")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .accessibilityIdentifier(ConnectClientAccessibility.transportNotice)
+            }
+            Spacer()
+            if model.undoControlExists {
+                Button("Undo") {
+                    Task { await model.undo() }
+                }
+                .disabled(!model.isUndoEnabled)
+                .accessibilityIdentifier(ConnectClientAccessibility.undoButton)
+            }
+            if model.disconnectControlExists {
+                Button("Disconnect…") {
+                    model.requestDisconnect()
+                }
+                .disabled(!model.isDisconnectEnabled)
+                .accessibilityIdentifier(ConnectClientAccessibility.disconnectButton)
+            }
+            Button("Close") {
+                // The undo's scope ends with the form (FR-006).
+                model.formWillClose()
+                onClose()
+            }
+                .keyboardShortcut(.cancelAction)
+                .accessibilityIdentifier(ConnectClientAccessibility.closeButton)
+            if model.connectControlExists {
+                Button {
+                    Task { await model.connect() }
+                } label: {
+                    if model.isBusy {
+                        ProgressView().controlSize(.small)
+                    } else {
+                        Text("Connect")
+                    }
+                }
+                .buttonStyle(.borderedProminent)
+                .keyboardShortcut(.defaultAction)
+                .disabled(!model.isConnectEnabled)
+                .accessibilityIdentifier(ConnectClientAccessibility.connectButton)
+            }
+        }
+        .padding(16)
+    }
+
+    private func labelledRow(_ title: String, _ value: String, identifier: String) -> some View {
+        VStack(alignment: .leading, spacing: 2) {
+            Text(title).font(.caption).foregroundStyle(.secondary)
+            Text(value)
+                .font(.system(.caption, design: .monospaced))
+                .textSelection(.enabled)
+                .accessibilityIdentifier(identifier)
+        }
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Views/ConnectFormWindowLifecycle.swift b/native/macos/MCPProxy/MCPProxy/Views/ConnectFormWindowLifecycle.swift
new file mode 100644
index 00000000..d5687934
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxy/Views/ConnectFormWindowLifecycle.swift
@@ -0,0 +1,86 @@
+import AppKit
+
+/// Owns the Connect Client form's window together with its model, so the form's
+/// lifetime ends however it is dismissed.
+///
+/// The form has two exits: its own Close button and the titlebar's red button.
+/// Only the first used to run through the app's dismissal path, and because the
+/// window is created with `isReleasedWhenClosed = false`, a red-button close
+/// merely orders it out — the NSHostingView, the model, and the SwiftUI `.task`
+/// driving the 2 s core-reachability poll (FR-013) all stayed alive, polling
+/// from a window nobody could see, until the next presentation replaced them.
+///
+/// Both exits now run the same teardown: the session-scoped undo ends (FR-006)
+/// and the view hierarchy is released, which is what actually cancels the task.
+@MainActor
+final class ConnectFormWindowLifecycle {
+
+    private(set) var window: NSWindow?
+    private(set) var model: ConnectClientModel?
+
+    /// The window the form is attached to as a sheet, when it is presented that
+    /// way. Recorded at adoption rather than read back from `sheetParent`
+    /// alone, so the relationship is known before AppKit has attached anything.
+    private weak var host: NSWindow?
+
+    /// A form is on screen right now.
+    var isPresenting: Bool { window?.isVisible == true }
+
+    /// Take ownership of a freshly built form. `host` is the window it is being
+    /// presented on as a sheet, if any.
+    func adopt(_ window: NSWindow, model: ConnectClientModel, host: NSWindow? = nil) {
+        self.window = window
+        self.model = model
+        self.host = host
+    }
+
+    /// Bring an already-presented form forward. Returns false when there is
+    /// none, so the caller knows it has to build one.
+    @discardableResult
+    func makeKeyIfPresenting() -> Bool {
+        guard let window, window.isVisible else { return false }
+        window.makeKeyAndOrderFront(nil)
+        return true
+    }
+
+    /// Handle a window-close notification. Returns true when the closing window
+    /// was this form's — or the window it is attached to as a sheet.
+    ///
+    /// The host matters because a sheet gets no close notification of its own:
+    /// AppKit lets a sheet-bearing parent close, orders the sheet out with it,
+    /// posts `willClose` for the HOST only, and never runs `beginSheet`'s
+    /// completion handler. Without this, closing the main window while the
+    /// Connect sheet was up left the model and its reachability poll alive.
+    @discardableResult
+    func windowWillClose(_ closing: NSWindow?) -> Bool {
+        guard let window, let closing else { return false }
+        guard closing === window || closing === host || closing === window.sheetParent
+        else { return false }
+        tearDown()
+        return true
+    }
+
+    /// Dismiss from the form's own Close button, whichever way it was shown.
+    func dismiss() {
+        guard let window else { return }
+        if let host = window.sheetParent {
+            host.endSheet(window)
+        } else {
+            window.close()
+        }
+        tearDown()
+    }
+
+    private func tearDown() {
+        // The undo affordance is scoped to this open form, and an unanswered
+        // confirmation is abandoned rather than remembered (FR-006).
+        model?.formWillClose()
+        // Replacing the content view releases the hosting view and everything
+        // SwiftUI built under it, so the reachability poll is cancelled even
+        // though AppKit keeps the (closed, invisible) window itself around.
+        window?.contentView = NSView()
+        window = nil
+        model = nil
+        host = nil
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxy/Views/DashboardView.swift b/native/macos/MCPProxy/MCPProxy/Views/DashboardView.swift
index 7c05f5d9..606a7ed4 100644
--- a/native/macos/MCPProxy/MCPProxy/Views/DashboardView.swift
+++ b/native/macos/MCPProxy/MCPProxy/Views/DashboardView.swift
@@ -7,12 +7,27 @@
 
 import SwiftUI
 
+// MARK: - Connect Clients Control
+
+/// The dashboard's way into the native Connect Client form (FR-012).
+///
+/// The dashboard used to own a sheet that connected a client *directly* — no
+/// preview, no backup disclosure. That sheet is gone: this control only opens
+/// the shared form, so every native config write goes through the same
+/// preview-before-write path as the tray menu item.
+enum DashboardConnectControl {
+    static let title = "Connect Clients…"
+
+    static func activate() {
+        ConnectClientPresentation.present()
+    }
+}
+
 // MARK: - Dashboard View
 
 struct DashboardView: View {
     @ObservedObject var appState: AppState
     @Environment(\.fontScale) var fontScale
-    @State private var showConnectClients = false
     @State private var mcpSessions: [APIClient.MCPSession] = []
 
     var body: some View {
@@ -53,9 +68,6 @@ struct DashboardView: View {
                 // Non-fatal; sessions will be empty
             }
         }
-        .sheet(isPresented: $showConnectClients) {
-            ConnectClientsSheet(appState: appState, isPresented: $showConnectClients)
-        }
     }
 
     // MARK: - Hub Visualization
@@ -130,9 +142,9 @@ struct DashboardView: View {
                     // Left column buttons
                     VStack(spacing: 6) {
                         Button {
-                            showConnectClients = true
+                            DashboardConnectControl.activate()
                         } label: {
-                            Label("Connect Clients", systemImage: "link")
+                            Label(DashboardConnectControl.title, systemImage: "link")
                                 .font(.scaled(.caption, scale: fontScale))
                                 .frame(maxWidth: .infinity)
                         }
@@ -1060,279 +1072,3 @@ private struct AttentionRow: View {
         }
     }
 }
-
-// MARK: - Connect Clients Sheet
-
-private struct ConnectClientsSheet: View {
-    @ObservedObject var appState: AppState
-    @Binding var isPresented: Bool
-    @State private var clients: [APIClient.ClientStatus] = []
-    @State private var loading = true
-    @State private var errorMessage: String?
-    @State private var successMessage: String?
-    @State private var actionInProgress: String?
-
-    var body: some View {
-        VStack(alignment: .leading, spacing: 16) {
-            // Header
-            VStack(alignment: .leading, spacing: 4) {
-                Text("Connect MCPProxy to AI Agents")
-                    .font(.headline)
-                Text("Register MCPProxy in your AI tools' MCP config files so they can discover and use your upstream servers.")
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
-            }
-
-            Divider()
-
-            if loading {
-                HStack {
-                    Spacer()
-                    ProgressView("Loading clients...")
-                    Spacer()
-                }
-                .padding(.vertical, 20)
-            } else if clients.isEmpty {
-                HStack {
-                    Spacer()
-                    VStack(spacing: 8) {
-                        Image(systemName: "questionmark.circle")
-                            .font(.title2)
-                            .foregroundStyle(.secondary)
-                        Text("No AI clients detected")
-                            .font(.subheadline)
-                            .foregroundStyle(.secondary)
-                        Text("The connect API may not be available in this version.")
-                            .font(.caption)
-                            .foregroundStyle(.tertiary)
-                    }
-                    Spacer()
-                }
-                .padding(.vertical, 20)
-            } else {
-                ScrollView {
-                    VStack(spacing: 0) {
-                        ForEach(clients) { client in
-                            clientRow(client)
-                            if client.id != clients.last?.id {
-                                Divider().padding(.leading, 8)
-                            }
-                        }
-                    }
-                }
-                .frame(maxHeight: 300)
-            }
-
-            // Status messages
-            if let msg = successMessage {
-                HStack(spacing: 6) {
-                    Image(systemName: "checkmark.circle.fill")
-                        .foregroundStyle(.green)
-                    Text(msg)
-                        .font(.caption)
-                        .foregroundStyle(.green)
-                }
-            }
-
-            if let err = errorMessage {
-                HStack(spacing: 6) {
-                    Image(systemName: "exclamationmark.triangle.fill")
-                        .foregroundStyle(.red)
-                    Text(err)
-                        .font(.caption)
-                        .foregroundStyle(.red)
-                }
-            }
-
-            Divider()
-
-            // Footer
-            HStack {
-                Button("Refresh") {
-                    loadClients()
-                }
-                .controlSize(.small)
-
-                Spacer()
-
-                Button("Close") {
-                    isPresented = false
-                }
-                .keyboardShortcut(.cancelAction)
-            }
-        }
-        .padding(20)
-        .frame(width: 500)
-        .onAppear { loadClients() }
-    }
-
-    @ViewBuilder
-    private func clientRow(_ client: APIClient.ClientStatus) -> some View {
-        HStack(spacing: 12) {
-            // Client icon
-            Image(systemName: clientIcon(for: client.clientId))
-                .font(.title3)
-                .foregroundStyle(client.connected ? .green : .secondary)
-                .frame(width: 24)
-
-            // Client info
-            VStack(alignment: .leading, spacing: 2) {
-                HStack(spacing: 6) {
-                    Text(client.name)
-                        .font(.subheadline)
-                        .fontWeight(.medium)
-                    if client.connected {
-                        Text("Connected")
-                            .font(.caption2)
-                            .fontWeight(.semibold)
-                            .padding(.horizontal, 6)
-                            .padding(.vertical, 2)
-                            .background(Color.green.opacity(0.15))
-                            .foregroundStyle(.green)
-                            .clipShape(Capsule())
-                    }
-                }
-                Text(client.configPath)
-                    .font(.caption2)
-                    .foregroundStyle(.tertiary)
-                    .lineLimit(1)
-                    .truncationMode(.middle)
-            }
-
-            Spacer()
-
-            // Action button
-            if !client.supported {
-                Text(client.reason ?? "Not supported")
-                    .font(.caption2)
-                    .foregroundStyle(.secondary)
-            } else if client.connected {
-                Button {
-                    disconnect(client.clientId)
-                } label: {
-                    if actionInProgress == client.clientId {
-                        ProgressView()
-                            .controlSize(.small)
-                    } else {
-                        Text("Disconnect")
-                    }
-                }
-                .buttonStyle(.bordered)
-                .controlSize(.small)
-                .disabled(actionInProgress != nil)
-            } else {
-                Button {
-                    connect(client.clientId)
-                } label: {
-                    if actionInProgress == client.clientId {
-                        ProgressView()
-                            .controlSize(.small)
-                    } else {
-                        Text("Connect")
-                    }
-                }
-                .buttonStyle(.borderedProminent)
-                .controlSize(.small)
-                .disabled(actionInProgress != nil)
-            }
-        }
-        .padding(.horizontal, 8)
-        .padding(.vertical, 8)
-    }
-
-    private func clientIcon(for clientId: String) -> String {
-        switch clientId {
-        case "claude-code", "claude-desktop":
-            return "brain"
-        case "cursor":
-            return "cursorarrow.rays"
-        case "vscode", "copilot":
-            return "chevron.left.forwardslash.chevron.right"
-        case "windsurf":
-            return "wind"
-        default:
-            return "app.connected.to.app.below.fill"
-        }
-    }
-
-    private func loadClients() {
-        loading = true
-        errorMessage = nil
-        successMessage = nil
-        Task {
-            guard let client = appState.apiClient else {
-                await MainActor.run {
-                    loading = false
-                    errorMessage = "Core is not connected"
-                }
-                return
-            }
-            do {
-                let result = try await client.connectClients()
-                await MainActor.run {
-                    clients = result
-                    loading = false
-                }
-            } catch {
-                await MainActor.run {
-                    loading = false
-                    errorMessage = error.localizedDescription
-                }
-            }
-        }
-    }
-
-    private func connect(_ clientId: String) {
-        errorMessage = nil
-        successMessage = nil
-        actionInProgress = clientId
-        Task {
-            guard let client = appState.apiClient else { return }
-            do {
-                let result = try await client.connectToClient(clientId)
-                await MainActor.run {
-                    actionInProgress = nil
-                    if result.success {
-                        successMessage = result.message ?? "Connected to \(clientId)"
-                    } else {
-                        errorMessage = result.message ?? "Failed to connect"
-                    }
-                }
-                // Reload the list to reflect changes
-                loadClients()
-            } catch {
-                await MainActor.run {
-                    actionInProgress = nil
-                    errorMessage = error.localizedDescription
-                }
-            }
-        }
-    }
-
-    private func disconnect(_ clientId: String) {
-        errorMessage = nil
-        successMessage = nil
-        actionInProgress = clientId
-        Task {
-            guard let client = appState.apiClient else { return }
-            do {
-                let result = try await client.disconnectFromClient(clientId)
-                await MainActor.run {
-                    actionInProgress = nil
-                    if result.success {
-                        successMessage = result.message ?? "Disconnected from \(clientId)"
-                    } else {
-                        errorMessage = result.message ?? "Failed to disconnect"
-                    }
-                }
-                // Reload the list to reflect changes
-                loadClients()
-            } catch {
-                await MainActor.run {
-                    actionInProgress = nil
-                    errorMessage = error.localizedDescription
-                }
-            }
-        }
-    }
-}
diff --git a/native/macos/MCPProxy/MCPProxyTests/APIClientConnectTests.swift b/native/macos/MCPProxy/MCPProxyTests/APIClientConnectTests.swift
new file mode 100644
index 00000000..c599a786
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/APIClientConnectTests.swift
@@ -0,0 +1,309 @@
+import XCTest
+@testable import MCPProxy
+
+/// Request-shape tests for the Connect form's five API calls, the transport
+/// identity the form gates its mutating controls on, and the strict-socket mode
+/// that keeps an admin write from silently riding TCP (spec 091 T014, research D6).
+final class APIClientConnectTests: XCTestCase {
+
+    override func setUp() {
+        super.setUp()
+        ConnectStubURLProtocol.reset()
+    }
+
+    override func tearDown() {
+        ConnectStubURLProtocol.reset()
+        super.tearDown()
+    }
+
+    private var lastRequest: ConnectStubURLProtocol.Recorded {
+        get throws { try XCTUnwrap(ConnectStubURLProtocol.recorded.last) }
+    }
+
+    private static let statusJSON = """
+    {"id":"claude-code","name":"Claude Code","config_path":"/Users/x/.claude.json",
+     "exists":true,"connected":true,"supported":true,"icon":"claude-code",
+     "server_name":"mcpproxy","access_state":"accessible"}
+    """
+
+    private static let resultJSON = """
+    {"success":true,"client":"claude-code","config_path":"/Users/x/.claude.json",
+     "backup_path":"/Users/x/.claude.json.backup-20260731-180000","server_name":"mcpproxy",
+     "action":"updated","message":"connected"}
+    """
+
+    // MARK: - Reads
+
+    func testClientDetailRequestsTheSingleClientEndpoint() async throws {
+        ConnectStubURLProtocol.responseBody = ConnectStubURLProtocol.envelope(Self.statusJSON)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        let detail = try await client.clientDetail("claude-code")
+
+        let request = try lastRequest
+        XCTAssertEqual(request.url, "http://127.0.0.1:8080/api/v1/connect/claude-code")
+        XCTAssertEqual(request.method, "GET")
+        XCTAssertEqual(detail.accessState, .accessible)
+        XCTAssertEqual(detail.serverName, "mcpproxy")
+    }
+
+    func testConnectPreviewCarriesTheEntryNameAsAQueryParameter() async throws {
+        ConnectStubURLProtocol.responseBody = ConnectStubURLProtocol.envelope("""
+        {"client":"claude-code","config_path":"/Users/x/.claude.json","server_name":"my proxy",
+         "entry_text":"…","entry_exists":false,"contains_api_key":false,
+         "access_state":"accessible","precondition_token":"tok"}
+        """)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        let preview = try await client.connectPreview("claude-code", serverName: "my proxy")
+
+        let request = try lastRequest
+        XCTAssertEqual(
+            request.url,
+            "http://127.0.0.1:8080/api/v1/connect/claude-code/preview?server_name=my%20proxy"
+        )
+        XCTAssertEqual(request.method, "GET")
+        XCTAssertEqual(preview.preconditionToken, "tok")
+        XCTAssertEqual(preview.changeKind, .add)
+    }
+
+    /// Reads may ride TCP when the socket is unavailable (the list and previews
+    /// stay useful off-socket); only writes are strict.
+    func testReadsAreNotSentInStrictSocketMode() async throws {
+        ConnectStubURLProtocol.responseBody = ConnectStubURLProtocol.envelope(Self.statusJSON)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        _ = try await client.clientDetail("claude-code")
+
+        XCTAssertNil(try lastRequest.headers[SocketURLProtocol.strictSocketHeader])
+    }
+
+    // MARK: - Connect
+
+    func testConnectPostsEntryNameForceAndPreconditionToken() async throws {
+        ConnectStubURLProtocol.responseBody = ConnectStubURLProtocol.envelope(Self.resultJSON)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        let result = try await client.connect(
+            "claude-code", serverName: "mcpproxy", force: true, preconditionToken: "tok-1")
+
+        let request = try lastRequest
+        XCTAssertEqual(request.url, "http://127.0.0.1:8080/api/v1/connect/claude-code")
+        XCTAssertEqual(request.method, "POST")
+        XCTAssertEqual(request.json["server_name"] as? String, "mcpproxy")
+        XCTAssertEqual(request.json["force"] as? Bool, true)
+        XCTAssertEqual(request.json["precondition_token"] as? String, "tok-1")
+        XCTAssertEqual(result.action, "updated")
+        XCTAssertEqual(result.backupPath, "/Users/x/.claude.json.backup-20260731-180000")
+    }
+
+    /// An add/create sends neither `force` nor an absent token, so a legacy core
+    /// keeps behaving exactly as it does today (contracts §2).
+    func testConnectOmitsForceAndTokenWhenNeitherApplies() async throws {
+        ConnectStubURLProtocol.responseBody = ConnectStubURLProtocol.envelope(Self.resultJSON)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        _ = try await client.connect(
+            "cursor", serverName: "mcpproxy", force: false, preconditionToken: nil)
+
+        let body = try lastRequest.json
+        XCTAssertEqual(body["server_name"] as? String, "mcpproxy")
+        XCTAssertNil(body["force"])
+        XCTAssertNil(body["precondition_token"])
+    }
+
+    func testConnectSurfacesPreconditionFailedAsADiscriminatedConflict() async throws {
+        ConnectStubURLProtocol.statusCode = 409
+        ConnectStubURLProtocol.responseBody = Data("""
+        {"success":false,
+         "data":{"success":false,"client":"claude-code","action":"precondition_failed",
+                 "message":"the config changed since the preview"},
+         "error":"the config changed since the preview"}
+        """.utf8)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        do {
+            _ = try await client.connect(
+                "claude-code", serverName: "mcpproxy", force: true, preconditionToken: "stale")
+            XCTFail("a stale token must not resolve as a successful connect")
+        } catch let error as APIClientError {
+            guard case .connectConflict(let action, let message) = error else {
+                return XCTFail("expected .connectConflict, got \(error)")
+            }
+            XCTAssertEqual(action, "precondition_failed")
+            XCTAssertEqual(message, "the config changed since the preview")
+        }
+    }
+
+    /// The legacy 409 must stay distinguishable, or the form cannot tell
+    /// "re-preview" from "this is a hard failure" (research D9).
+    func testConnectSurfacesAlreadyExistsAsItsOwnConflictAction() async throws {
+        ConnectStubURLProtocol.statusCode = 409
+        ConnectStubURLProtocol.responseBody = Data("""
+        {"success":false,
+         "data":{"success":false,"action":"already_exists","message":"entry already exists"},
+         "error":"entry already exists"}
+        """.utf8)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        do {
+            _ = try await client.connect(
+                "claude-code", serverName: "mcpproxy", force: false, preconditionToken: "tok")
+            XCTFail("a 409 must not resolve as a successful connect")
+        } catch let error as APIClientError {
+            guard case .connectConflict(let action, _) = error else {
+                return XCTFail("expected .connectConflict, got \(error)")
+            }
+            XCTAssertEqual(action, "already_exists")
+        }
+    }
+
+    // MARK: - Undo / disconnect
+
+    func testUndoConnectPostsTheBackupIdentityItWasGiven() async throws {
+        ConnectStubURLProtocol.responseBody = ConnectStubURLProtocol.envelope(Self.resultJSON)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        _ = try await client.undoConnect(
+            "claude-code", serverName: "mcpproxy", backupName: ".claude.json.backup-20260731")
+
+        let request = try lastRequest
+        XCTAssertEqual(request.url, "http://127.0.0.1:8080/api/v1/connect/claude-code/undo")
+        XCTAssertEqual(request.method, "POST")
+        XCTAssertEqual(request.json["backup_name"] as? String, ".claude.json.backup-20260731")
+        XCTAssertEqual(request.json["server_name"] as? String, "mcpproxy")
+    }
+
+    /// A connect that CREATED the file returns no backup; undo then means
+    /// "remove the created file", which the core reads from an absent
+    /// backup_name — sending an empty string would be a different request.
+    func testUndoOfACreatedFileOmitsTheBackupName() async throws {
+        ConnectStubURLProtocol.responseBody = ConnectStubURLProtocol.envelope(Self.resultJSON)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        _ = try await client.undoConnect("cursor", serverName: "mcpproxy", backupName: nil)
+
+        XCTAssertNil(try lastRequest.json["backup_name"])
+    }
+
+    func testDisconnectUsesDeleteAndNamesTheEntry() async throws {
+        ConnectStubURLProtocol.responseBody = ConnectStubURLProtocol.envelope("""
+        {"success":true,"client":"claude-code","config_path":"/Users/x/.claude.json",
+         "server_name":"mcpproxy","action":"removed","message":"disconnected"}
+        """)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        let result = try await client.disconnect("claude-code", serverName: "mcpproxy")
+
+        let request = try lastRequest
+        XCTAssertEqual(request.url, "http://127.0.0.1:8080/api/v1/connect/claude-code")
+        XCTAssertEqual(request.method, "DELETE")
+        XCTAssertEqual(request.json["server_name"] as? String, "mcpproxy")
+        XCTAssertEqual(result.action, "removed")
+    }
+
+    // MARK: - Transport identity
+
+    func testTransportKindIsTheSocketUnlessTCPWasRequested() {
+        XCTAssertEqual(APIClient(socketPath: nil).transportKind, .unixSocket)
+        XCTAssertEqual(APIClient(socketPath: "/tmp/mcpproxy-test.sock").transportKind, .unixSocket)
+        XCTAssertEqual(APIClient(socketPath: "").transportKind, .tcp,
+                       "an empty socket path is the explicit TCP-only mode")
+    }
+
+    // MARK: - Strict-socket writes
+
+    func testEveryMutatingCallIsSentInStrictSocketMode() async throws {
+        ConnectStubURLProtocol.responseBody = ConnectStubURLProtocol.envelope(Self.resultJSON)
+        let client = ConnectStubURLProtocol.makeClient()
+
+        _ = try await client.connect(
+            "claude-code", serverName: "mcpproxy", force: false, preconditionToken: "tok")
+        _ = try await client.undoConnect("claude-code", serverName: "mcpproxy", backupName: "b")
+        _ = try await client.disconnect("claude-code", serverName: "mcpproxy")
+
+        XCTAssertEqual(ConnectStubURLProtocol.recorded.count, 3)
+        for request in ConnectStubURLProtocol.recorded {
+            XCTAssertEqual(request.headers[SocketURLProtocol.strictSocketHeader], "1",
+                           "\(request.method) \(request.url) was not marked strict-socket")
+        }
+    }
+
+    /// The transport gate is client-side too: with the app on TCP the write must
+    /// never leave the process (spec's non-socket edge case).
+    func testMutatingCallsRefuseToRideTCPAndSendNothing() async {
+        let client = ConnectStubURLProtocol.makeClient(transportKind: .tcp)
+
+        do {
+            _ = try await client.connect(
+                "claude-code", serverName: "mcpproxy", force: false, preconditionToken: "tok")
+            XCTFail("a TCP-transport client must refuse an administrative write")
+        } catch let error as APIClientError {
+            guard case .socketRequired = error else {
+                return XCTFail("expected .socketRequired, got \(error)")
+            }
+        } catch {
+            XCTFail("expected APIClientError, got \(error)")
+        }
+
+        XCTAssertTrue(ConnectStubURLProtocol.recorded.isEmpty,
+                      "the request must not be attempted at all")
+    }
+
+    /// Reads stay available off-socket — the list and previews are what the form
+    /// shows while explaining why the actions are disabled.
+    func testReadsStillWorkOffSocket() async throws {
+        ConnectStubURLProtocol.responseBody = ConnectStubURLProtocol.envelope(Self.statusJSON)
+        let client = ConnectStubURLProtocol.makeClient(transportKind: .tcp)
+
+        _ = try await client.clientDetail("claude-code")
+
+        XCTAssertEqual(ConnectStubURLProtocol.recorded.count, 1)
+    }
+
+    // MARK: - Strict interception rule
+
+    private func request(strict: Bool, route: String? = nil) -> URLRequest {
+        var request = URLRequest(url: URL(string: "http://127.0.0.1:8080/api/v1/connect/x")!)
+        if strict {
+            request.setValue("1", forHTTPHeaderField: SocketURLProtocol.strictSocketHeader)
+        }
+        if let route {
+            request.setValue(SocketURLProtocol.makeRoute(to: route),
+                             forHTTPHeaderField: SocketURLProtocol.routeHeader)
+        }
+        return request
+    }
+
+    /// The hole research D6 found: with the socket gone, an unrouted request
+    /// falls through to TCP. A strict request must be intercepted anyway so it
+    /// FAILS instead of delivering an admin write over the network.
+    func testAStrictRequestIsInterceptedEvenWithNoSocketFile() {
+        XCTAssertTrue(
+            SocketURLProtocol.shouldIntercept(
+                request: request(strict: true), defaultSocketExists: false)
+        )
+    }
+
+    func testANonStrictRequestStillFallsBackToTCPWithNoSocketFile() {
+        XCTAssertFalse(
+            SocketURLProtocol.shouldIntercept(
+                request: request(strict: false), defaultSocketExists: false)
+        )
+    }
+
+    func testANonStrictRequestIsInterceptedWhenTheSocketExists() {
+        XCTAssertTrue(
+            SocketURLProtocol.shouldIntercept(
+                request: request(strict: false), defaultSocketExists: true)
+        )
+    }
+
+    func testARoutedRequestIsPinnedRegardlessOfStrictness() {
+        XCTAssertTrue(
+            SocketURLProtocol.shouldIntercept(
+                request: request(strict: false, route: "/nonexistent/mcpproxy.sock"),
+                defaultSocketExists: false)
+        )
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxyTests/ConnectClientInFlightTests.swift b/native/macos/MCPProxy/MCPProxyTests/ConnectClientInFlightTests.swift
new file mode 100644
index 00000000..81fbe29a
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/ConnectClientInFlightTests.swift
@@ -0,0 +1,200 @@
+import XCTest
+@testable import MCPProxy
+
+/// What happens when the user keeps using the form while a write is still in
+/// flight (spec 091 Edge Cases: "double-click protection").
+///
+/// `ConnectClientModel` is a @MainActor class, so every `await` is a reentrancy
+/// point: the list, the entry-name field and the action buttons all stay live
+/// while a POST is suspended. These tests pin that the busy state survives that
+/// interleaving and that an outcome is only ever shown for the client it
+/// belongs to.
+@MainActor
+final class ConnectClientInFlightTests: XCTestCase {
+
+    /// A one-shot gate: `wait()` suspends until `open()` is called, so a test
+    /// can hold a request open and observe the window while it is pending.
+    @MainActor
+    final class Gate {
+        private var continuation: CheckedContinuation<Void, Never>?
+        private var isOpen = false
+
+        func wait() async {
+            if isOpen { return }
+            await withCheckedContinuation { self.continuation = $0 }
+        }
+
+        func open() {
+            isOpen = true
+            continuation?.resume()
+            continuation = nil
+        }
+    }
+
+    private func makeModel(_ source: FakeConnectSource) -> ConnectClientModel {
+        ConnectClientModel(source: source, sleeper: { _ in })
+    }
+
+    // MARK: - Busy state
+
+    /// The entry-name field is editable while a connect is in flight, and
+    /// editing it invalidates the preview. That must not be mistaken for "the
+    /// request finished": the busy state is the only thing standing between the
+    /// user and a second concurrent read-modify-write of the same config file.
+    func testEditingTheEntryNameDuringAConnectKeepsTheFormBusy() async {
+        let source = FakeConnectSource()
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        var busyAfterEdit: Bool?
+        var connectEnabledAfterEdit: Bool?
+        source.whileConnectInFlight = { [weak model] in
+            guard let model else { return }
+            model.entryName = "other-name"
+            busyAfterEdit = model.isBusy
+            connectEnabledAfterEdit = model.isConnectEnabled
+        }
+
+        await model.connect()
+
+        XCTAssertEqual(busyAfterEdit, true,
+                       "the POST is still outstanding, so the form is still busy")
+        XCTAssertEqual(connectEnabledAfterEdit, false)
+        XCTAssertEqual(source.connectCalls.count, 1)
+    }
+
+    /// Same for a selection change: clicking another row while the write is in
+    /// flight must not unlock the controls.
+    func testSelectingAnotherClientDuringAConnectKeepsTheFormBusy() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [.success([
+            FakeConnectSource.client(id: "claude-code"),
+            FakeConnectSource.client(id: "cursor")
+        ])]
+        let model = makeModel(source)
+        await model.loadList()
+        await model.select("claude-code")
+
+        var busyDuring: Bool?
+        source.duringConnect = { [weak model] in
+            guard let model else { return }
+            await model.select("cursor")
+            busyDuring = model.isBusy
+        }
+
+        await model.connect()
+
+        XCTAssertEqual(busyDuring, true,
+                       "a write against claude-code is still outstanding")
+        XCTAssertEqual(source.connectCalls.count, 1)
+    }
+
+    // MARK: - Outcome ownership
+
+    /// The outcome of a write belongs to the client it was performed on. If the
+    /// user moved to another client while it was in flight, that client's pane
+    /// must not display the first client's success banner — while the first
+    /// client's ROW must still pick up its refreshed state.
+    func testAnOutcomeIsNeverShownInAnotherClientsPane() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [.success([
+            FakeConnectSource.client(id: "claude-code", name: "Claude Code"),
+            FakeConnectSource.client(id: "cursor", name: "Cursor", exists: false)
+        ])]
+        source.detailResults = [
+            .success(FakeConnectSource.client(id: "claude-code", name: "Claude Code")),
+            .success(FakeConnectSource.client(id: "cursor", name: "Cursor", exists: false)),
+            .success(FakeConnectSource.client(id: "claude-code", name: "Claude Code",
+                                              connected: true, serverName: "mcpproxy"))
+        ]
+        let model = makeModel(source)
+        await model.loadList()
+        await model.select("claude-code")
+
+        source.duringConnect = { [weak model] in
+            await model?.select("cursor")
+        }
+
+        await model.connect()
+
+        XCTAssertEqual(model.selection, "cursor")
+        if case .succeeded = model.action {
+            XCTFail("claude-code's success banner must not render in cursor's pane")
+        }
+        XCTAssertEqual(source.detailCalls, ["claude-code", "cursor", "claude-code"],
+                       "the client that was written to is the one that refreshes")
+        XCTAssertEqual(model.rows.first(where: { $0.clientId == "claude-code" })?.stateLabel,
+                       "Connected as \"mcpproxy\"",
+                       "its row must show the state the write produced")
+        XCTAssertEqual(source.previewCalls.map(\.clientId), ["claude-code", "cursor"],
+                       "the previous client's preview must not overwrite the current pane's")
+    }
+
+    // MARK: - Stale action restore
+
+    /// The post-connect preview refresh captures the action before its await and
+    /// writes it back after. If the user starts an undo during that await, the
+    /// captured (older) outcome must NOT be restored over it — the form would
+    /// then show the connect's success while the undo is still in flight, and
+    /// would hide the undo's own result.
+    func testThePostConnectRefreshNeverRestoresAnOutcomeOverANewerAction() async {
+        let source = FakeConnectSource()
+        source.connectResults = [.success(
+            FakeConnectSource.result(action: "created", backupPath: "/Users/x/.claude.json.bak"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        let undoGate = Gate()
+        var undoTask: Task<Void, Never>?
+        source.duringUndo = { await undoGate.wait() }
+        source.duringPreview = { [weak model] index in
+            // Call 1 is the selection's own preview; call 2 is the post-connect
+            // refresh — the window in which Undo is offered and clickable.
+            guard index == 2, let model else { return }
+            XCTAssertTrue(model.isUndoEnabled, "Undo is offered during the refresh")
+            undoTask = Task { await model.undo() }
+            // Let the undo reach its own suspension point (the POST).
+            for _ in 0..<20 where source.undoCalls.isEmpty { await Task.yield() }
+        }
+
+        await model.connect()
+
+        XCTAssertEqual(source.undoCalls.count, 1, "the undo request was started")
+        XCTAssertEqual(model.action, .inFlight,
+                       "the pending undo owns the action; the older connect outcome must not be restored over it")
+        XCTAssertTrue(model.isBusy, "a request is still in flight")
+        XCTAssertFalse(model.isUndoEnabled, "so the undo cannot be sent a second time")
+
+        undoGate.open()
+        await undoTask?.value
+
+        XCTAssertEqual(source.undoCalls.count, 1, "the undo must not be sent twice")
+        guard case .succeeded(let result) = model.action else {
+            return XCTFail("expected the undo's own outcome, got \(model.action)")
+        }
+        XCTAssertEqual(result.action, "restored")
+    }
+
+    /// The same restore must not bury a FAILED undo under the connect's success.
+    func testAFailedUndoDuringTheRefreshKeepsItsOwnMessage() async {
+        let source = FakeConnectSource()
+        source.connectResults = [.success(FakeConnectSource.result(action: "created"))]
+        source.undoResults = [.failure(APIClientError.httpError(statusCode: 500, message: "restore failed"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        source.duringPreview = { [weak model] index in
+            // The undo runs to completion while the post-connect refresh is
+            // suspended, so the restore lands strictly after its outcome.
+            guard index == 2, let model else { return }
+            await model.undo()
+        }
+
+        await model.connect()
+
+        guard case .failed(let message) = model.action else {
+            return XCTFail("the undo's failure must survive the preview refresh, got \(model.action)")
+        }
+        XCTAssertTrue(message.contains("restore failed"), "got: \(message)")
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxyTests/ConnectClientModelTests.swift b/native/macos/MCPProxy/MCPProxyTests/ConnectClientModelTests.swift
new file mode 100644
index 00000000..b8ec05b2
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/ConnectClientModelTests.swift
@@ -0,0 +1,937 @@
+import XCTest
+import AppKit
+@testable import MCPProxy
+
+/// State-machine tests for the native Connect Client form (spec 091 T016).
+///
+/// Everything the model does is driven from synthesized API responses through
+/// `FakeConnectSource`, so these tests pin the invariants — above all SC-002's
+/// "no Connect control without a matching rendered preview" — without a core.
+@MainActor
+final class ConnectClientModelTests: XCTestCase {
+
+    /// Records what the model asked the clock for, so the 2 s reachability poll
+    /// is asserted rather than waited on.
+    @MainActor
+    final class SleepRecorder {
+        var intervals: [TimeInterval] = []
+        var listStates: [ConnectClientModel.ListState] = []
+        var rowSnapshots: [[ConnectClientModel.ClientRow]] = []
+        weak var model: ConnectClientModel?
+
+        var sleeper: ConnectClientSleeper {
+            { [weak self] interval in
+                self?.intervals.append(interval)
+                if let model = self?.model {
+                    self?.listStates.append(model.list)
+                    self?.rowSnapshots.append(model.rows)
+                }
+            }
+        }
+    }
+
+    private func makeModel(
+        _ source: FakeConnectSource,
+        recorder: SleepRecorder? = nil
+    ) -> ConnectClientModel {
+        let noSleep: ConnectClientSleeper = { _ in }
+        let model = ConnectClientModel(source: source, sleeper: recorder?.sleeper ?? noSleep)
+        recorder?.model = model
+        return model
+    }
+
+    // MARK: - List
+
+    func testListLoadsFromTheStatOnlyAggregate() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [.success([
+            FakeConnectSource.client(id: "claude-code", name: "Claude Code"),
+            FakeConnectSource.client(id: "cursor", name: "Cursor", exists: false)
+        ])]
+        let model = makeModel(source)
+
+        XCTAssertEqual(model.list, .loading)
+        await model.loadList()
+
+        guard case .loaded(let rows) = model.list else {
+            return XCTFail("expected .loaded, got \(model.list)")
+        }
+        XCTAssertEqual(rows.map(\.clientId), ["claude-code", "cursor"])
+        // Opening the list must not read any client config content — i.e. no
+        // per-client detail call is made (FR-002 / SC-004).
+        XCTAssertTrue(source.detailCalls.isEmpty)
+        XCTAssertTrue(source.previewCalls.isEmpty)
+    }
+
+    /// FR-013: while the core is unreachable the form waits, polls every 2 s and
+    /// populates itself when the core answers — with no user action.
+    func testUnreachableCorePollsEveryTwoSecondsUntilItAnswers() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [
+            .failure(APIClientError.notReady),
+            .success([FakeConnectSource.client(id: "claude-code")])
+        ]
+        let recorder = SleepRecorder()
+        let model = makeModel(source, recorder: recorder)
+
+        await model.loadList()
+
+        XCTAssertEqual(recorder.intervals, [ConnectClientModel.pollInterval])
+        XCTAssertEqual(ConnectClientModel.pollInterval, 2)
+        XCTAssertEqual(recorder.listStates.count, 1)
+        guard case .coreUnreachable(let reason) = recorder.listStates[0] else {
+            return XCTFail("expected .coreUnreachable while polling, got \(recorder.listStates[0])")
+        }
+        XCTAssertFalse(reason.isEmpty, "the waiting state must say what is wrong")
+        guard case .loaded(let rows) = model.list else {
+            return XCTFail("expected .loaded after the core answered, got \(model.list)")
+        }
+        XCTAssertEqual(rows.count, 1)
+        XCTAssertEqual(source.clientsCallCount, 2)
+    }
+
+    // MARK: - Selection → detail + preview
+
+    func testSelectingAClientResolvesDetailAndPreview() async {
+        let source = FakeConnectSource()
+        source.detailResults = [.success(
+            FakeConnectSource.client(id: "claude-code", connected: true,
+                                     accessState: .accessible, serverName: "mcpproxy"))]
+        source.previewResults = [.success(FakeConnectSource.preview())]
+        let model = makeModel(source)
+
+        await model.select("claude-code")
+
+        XCTAssertEqual(model.selection, "claude-code")
+        XCTAssertEqual(source.detailCalls, ["claude-code"])
+        XCTAssertEqual(source.previewCalls.map(\.clientId), ["claude-code"])
+        guard case .resolved(let detail) = model.detail else {
+            return XCTFail("expected resolved detail, got \(model.detail)")
+        }
+        XCTAssertTrue(detail.connected)
+        XCTAssertEqual(detail.serverName, "mcpproxy")
+        guard case .resolved = model.preview else {
+            return XCTFail("expected resolved preview, got \(model.preview)")
+        }
+    }
+
+    func testEntryNameDefaultsToMCPProxyAndIsPreviewed() async {
+        let source = FakeConnectSource()
+        let model = makeModel(source)
+
+        XCTAssertEqual(model.entryName, "mcpproxy")
+        await model.select("claude-code")
+
+        XCTAssertEqual(source.previewCalls.first?.serverName, "mcpproxy")
+    }
+
+    // MARK: - SC-002: the Connect control is structurally preview-bound
+
+    func testConnectControlDoesNotExistBeforeAPreviewIsResolved() async {
+        let source = FakeConnectSource()
+        let model = makeModel(source)
+
+        XCTAssertFalse(model.connectControlExists, "no selection, no preview, no control")
+
+        await model.select("claude-code")
+        XCTAssertTrue(model.connectControlExists)
+    }
+
+    /// Editing the entry name destroys the rendered preview immediately — before
+    /// any refetch — so no write can be bound to a preview of a different input.
+    func testEditingTheEntryNameDiscardsThePreviewAndTheControl() async {
+        let source = FakeConnectSource()
+        let model = makeModel(source)
+        await model.select("claude-code")
+        XCTAssertTrue(model.connectControlExists)
+
+        model.entryName = "my-proxy"
+
+        XCTAssertEqual(model.preview, .idle)
+        XCTAssertFalse(model.connectControlExists)
+
+        await model.refreshPreview()
+
+        XCTAssertTrue(model.connectControlExists)
+        XCTAssertEqual(source.previewCalls.map(\.serverName), ["mcpproxy", "my-proxy"])
+    }
+
+    /// A preview that arrives for inputs the user has already changed must not
+    /// resurrect the control (the late-response race).
+    func testAPreviewForStaleInputsIsDiscarded() async {
+        let source = FakeConnectSource()
+        source.previewResults = [.success(FakeConnectSource.preview(serverName: "mcpproxy"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        model.entryName = "my-proxy"
+        // The scripted preview still answers with the OLD entry name.
+        await model.refreshPreview()
+
+        XCTAssertFalse(model.connectControlExists,
+                       "a preview naming another entry must not gate this write")
+    }
+
+    func testARefusedPreviewOffersNoConnectControlAndShowsTheCoreReasonVerbatim() async {
+        let reason = "opencode requires an existing config file; create one first"
+        let source = FakeConnectSource()
+        source.previewResults = [.success(
+            FakeConnectSource.preview(client: "opencode", accessState: .absent, refusal: reason))]
+        let model = makeModel(source)
+
+        await model.select("opencode")
+
+        XCTAssertFalse(model.connectControlExists)
+        XCTAssertEqual(model.connectRefusal, reason)
+    }
+
+    func testAnUnreadableConfigOffersNoConnectControl() async {
+        let source = FakeConnectSource()
+        source.previewResults = [
+            .success(FakeConnectSource.preview(accessState: .malformed)),
+            .success(FakeConnectSource.preview(accessState: .denied))
+        ]
+        let model = makeModel(source)
+
+        await model.select("cursor")
+        XCTAssertFalse(model.connectControlExists, "malformed config: no Connect")
+
+        await model.refreshPreview()
+        XCTAssertFalse(model.connectControlExists, "denied access: no Connect")
+    }
+
+    func testAFailedPreviewOffersNoConnectControlAndKeepsTheCoreMessage() async {
+        let source = FakeConnectSource()
+        source.previewResults = [.failure(
+            APIClientError.httpError(statusCode: 403, message: "operation not permitted"))]
+        let model = makeModel(source)
+
+        await model.select("cursor")
+
+        XCTAssertFalse(model.connectControlExists)
+        guard case .failed(let message) = model.preview else {
+            return XCTFail("expected a failed preview, got \(model.preview)")
+        }
+        XCTAssertTrue(message.contains("operation not permitted"), "got: \(message)")
+    }
+
+    // MARK: - Connect
+
+    func testAnAddSendsTheTokenWithoutForce() async {
+        let source = FakeConnectSource()
+        source.previewResults = [.success(FakeConnectSource.preview(entryExists: false, token: "tok-add"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        await model.connect()
+
+        XCTAssertEqual(source.connectCalls, [
+            .init(clientId: "claude-code", serverName: "mcpproxy",
+                  force: false, preconditionToken: "tok-add")
+        ])
+    }
+
+    /// A replace overwrites, so it sends `force` — but only ever TOGETHER with
+    /// the token, which is the actual safety (FR-005).
+    func testAReplaceSendsForceTogetherWithTheToken() async {
+        let source = FakeConnectSource()
+        source.previewResults = [.success(FakeConnectSource.preview(
+            entryExists: true,
+            summary: ConnectEntrySummary(entryName: "old-proxy", type: "http"),
+            token: "tok-replace"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        await model.connect()
+
+        XCTAssertEqual(source.connectCalls.first?.force, true)
+        XCTAssertEqual(source.connectCalls.first?.preconditionToken, "tok-replace")
+    }
+
+    /// The form never sends the overwrite flag without a valid token, so against
+    /// a core that issues no token a replace is simply not offered.
+    func testAReplaceWithoutATokenIsNotOfferedAtAll() async {
+        let source = FakeConnectSource()
+        source.previewResults = [.success(
+            FakeConnectSource.preview(entryExists: true, token: nil))]
+        let model = makeModel(source)
+
+        await model.select("claude-code")
+        await model.connect()
+
+        XCTAssertFalse(model.connectControlExists)
+        XCTAssertTrue(source.connectCalls.isEmpty, "force must never be sent tokenless")
+    }
+
+    /// ...and when it is not offered, the form says why. A resolved preview, a
+    /// backup promise and no button with no explanation is a silent dead end.
+    func testABlockedReplaceStatesWhyAndPromisesNoBackup() async {
+        let source = FakeConnectSource()
+        source.previewResults = [.success(
+            FakeConnectSource.preview(entryExists: true, token: nil))]
+        let model = makeModel(source)
+
+        await model.select("claude-code")
+
+        XCTAssertFalse(model.connectControlExists)
+        let reason = try? XCTUnwrap(model.connectBlockedReason)
+        XCTAssertFalse((reason ?? "").isEmpty, "a hidden control must have a stated reason")
+        XCTAssertNil(model.currentPreview?.safetyNetStatement,
+                     "no backup is promised for a write that cannot be started")
+    }
+
+    /// Against a PRE-091 core (no precondition_token field at all) the write
+    /// falls back to its legacy behaviour, so the control stays available and
+    /// the replace is sent with force and NO token — the alternative is a form
+    /// that shows a full preview and offers nothing, forever.
+    func testAReplaceAgainstAPre091CoreIsOfferedAndSendsNoToken() async {
+        let source = FakeConnectSource()
+        source.previewResults = [.success(
+            FakeConnectSource.preview(entryExists: true, token: nil, coreSupportsTokens: false))]
+        let model = makeModel(source)
+
+        await model.select("claude-code")
+
+        XCTAssertTrue(model.connectControlExists,
+                      "a core that never speaks the token protocol must not disable the form")
+        XCTAssertNil(model.connectBlockedReason)
+
+        await model.connect()
+
+        XCTAssertEqual(source.connectCalls.count, 1)
+        XCTAssertEqual(source.connectCalls.first?.force, true)
+        XCTAssertNil(source.connectCalls.first?.preconditionToken,
+                     "there is no token to send; the core falls back to its legacy write")
+    }
+
+    func testASuccessfulConnectRefreshesTheClientState() async {
+        let source = FakeConnectSource()
+        source.detailResults = [
+            .success(FakeConnectSource.client(id: "claude-code", connected: false)),
+            .success(FakeConnectSource.client(id: "claude-code", connected: true,
+                                              serverName: "mcpproxy"))
+        ]
+        source.connectResults = [.success(
+            FakeConnectSource.result(action: "created", backupPath: "/Users/x/.claude.json.bak"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        await model.connect()
+
+        guard case .succeeded(let result) = model.action else {
+            return XCTFail("expected .succeeded, got \(model.action)")
+        }
+        XCTAssertEqual(result.action, "created")
+        XCTAssertEqual(source.detailCalls, ["claude-code", "claude-code"],
+                       "the affected client's state must refresh from the core")
+        guard case .resolved(let detail) = model.detail, detail.connected else {
+            return XCTFail("expected the refreshed detail to show connected, got \(model.detail)")
+        }
+    }
+
+    /// Drift → `.conflict` → exactly ONE automatic re-preview, and no retry of
+    /// the write (research D9).
+    func testAPreconditionFailureConflictsAndRePreviewsExactlyOnce() async {
+        let source = FakeConnectSource()
+        source.connectResults = [.failure(APIClientError.connectConflict(
+            action: "precondition_failed", message: "the config changed since the preview"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+        XCTAssertEqual(source.previewCalls.count, 1)
+
+        await model.connect()
+
+        guard case .conflict(let reason) = model.action else {
+            return XCTFail("expected .conflict, got \(model.action)")
+        }
+        XCTAssertEqual(reason, "the config changed since the preview")
+        XCTAssertEqual(source.connectCalls.count, 1, "the write must not be retried")
+        XCTAssertEqual(source.previewCalls.count, 2, "exactly one automatic re-preview")
+    }
+
+    /// The legacy 409 cannot occur in this flow (a replace always sends force),
+    /// and if it does it is a plain failure — re-previewing on it would loop.
+    func testALegacyAlreadyExistsConflictIsAFailureNotARePreview() async {
+        let source = FakeConnectSource()
+        source.connectResults = [.failure(APIClientError.connectConflict(
+            action: "already_exists", message: "entry already exists"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        await model.connect()
+
+        guard case .failed(let message) = model.action else {
+            return XCTFail("expected .failed, got \(model.action)")
+        }
+        XCTAssertEqual(message, "entry already exists")
+        XCTAssertEqual(source.previewCalls.count, 1, "must not re-preview and loop")
+    }
+
+    func testAFailedConnectKeepsTheCoreMessage() async {
+        let source = FakeConnectSource()
+        source.connectResults = [.failure(
+            APIClientError.httpError(statusCode: 400, message: "config is not writable"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        await model.connect()
+
+        guard case .failed(let message) = model.action else {
+            return XCTFail("expected .failed, got \(model.action)")
+        }
+        XCTAssertTrue(message.contains("config is not writable"), "got: \(message)")
+    }
+
+    func testActionsAreDisabledWhileARequestIsInFlight() async {
+        let source = FakeConnectSource()
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        var inFlightState: ConnectClientModel.ActionState?
+        var connectEnabledInFlight: Bool?
+        source.whileConnectInFlight = { [weak model] in
+            inFlightState = model?.action
+            connectEnabledInFlight = model?.isConnectEnabled
+        }
+
+        await model.connect()
+
+        XCTAssertEqual(inFlightState, .inFlight)
+        XCTAssertEqual(connectEnabledInFlight, false,
+                       "double-click protection: the button disables while in flight")
+        XCTAssertTrue(model.isConnectEnabled, "and re-enables once the request settles")
+    }
+
+    // MARK: - Transport
+
+    /// Off-socket the mutating controls are DISABLED with an explanation — the
+    /// list, detail and preview keep working (spec's non-socket edge case).
+    func testOffSocketDisablesMutatingControlsWithAnExplanation() async {
+        let source = FakeConnectSource()
+        source.transportKind = .tcp
+        let model = makeModel(source)
+
+        await model.select("claude-code")
+
+        XCTAssertTrue(model.connectControlExists, "the preview still renders")
+        XCTAssertFalse(model.isConnectEnabled)
+        let reason = try? XCTUnwrap(model.mutatingDisabledReason)
+        XCTAssertFalse(reason?.isEmpty ?? true, "the user must be told why")
+        guard case .resolved = model.preview else {
+            return XCTFail("previews must remain available off-socket")
+        }
+    }
+
+    func testOnSocketTheMutatingControlsCarryNoExplanation() async {
+        let source = FakeConnectSource()
+        let model = makeModel(source)
+
+        await model.select("claude-code")
+
+        XCTAssertNil(model.mutatingDisabledReason)
+        XCTAssertTrue(model.isConnectEnabled)
+    }
+
+    /// Belt and braces for the same rule at the model level: with the transport
+    /// off-socket, invoking connect sends nothing at all.
+    func testOffSocketConnectSendsNothing() async {
+        let source = FakeConnectSource()
+        source.transportKind = .tcp
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        await model.connect()
+
+        XCTAssertTrue(source.connectCalls.isEmpty)
+    }
+
+    // MARK: - US2: configuration state at a glance (T020)
+
+    /// The list speaks only the cheap truth — a statement about the config FILE,
+    /// derived from the existence-only aggregate. Rendering it must not read a
+    /// single client config's contents (FR-002 / SC-004).
+    func testListRowsRenderStatOnlyStatesWithoutReadingAnyConfig() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [.success([
+            FakeConnectSource.client(id: "claude-code", name: "Claude Code", exists: true),
+            FakeConnectSource.client(id: "cursor", name: "Cursor", exists: false),
+            FakeConnectSource.client(id: "windsurf", name: "Windsurf", exists: false,
+                                     supported: false, reason: "Not available on this platform")
+        ])]
+        let model = makeModel(source)
+
+        await model.loadList()
+
+        XCTAssertEqual(model.rows.map(\.clientId), ["claude-code", "cursor", "windsurf"])
+        XCTAssertEqual(model.rows.map(\.stateLabel),
+                       ["Config present", "No config found", "Not available on this platform"])
+        // FR-009: an unsupported client is visible but disabled with its reason,
+        // never hidden.
+        XCTAssertEqual(model.rows.map(\.isSelectable), [true, true, false])
+        XCTAssertEqual(model.rows.map(\.displayName), ["Claude Code", "Cursor", "Windsurf"])
+        // "No config found" is a claim about the file, never about the app.
+        XCTAssertFalse(
+            model.rows.contains { $0.stateLabel.localizedCaseInsensitiveContains("installed") },
+            "labels must never claim an application is or is not installed")
+        XCTAssertTrue(source.detailCalls.isEmpty, "opening the list reads no config contents")
+        XCTAssertTrue(source.previewCalls.isEmpty)
+    }
+
+    /// An unsupported client the core gave no reason for still renders disabled
+    /// with a defined label rather than an empty one.
+    func testAnUnsupportedRowWithoutAReasonStillCarriesALabel() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [.success([
+            FakeConnectSource.client(id: "codex", supported: false)
+        ])]
+        let model = makeModel(source)
+
+        await model.loadList()
+
+        XCTAssertEqual(model.rows.first?.isSelectable, false)
+        XCTAssertEqual(model.rows.first?.stateLabel, "Not supported on this platform")
+    }
+
+    /// US2 scenario 2: the authoritative "connected, and under which entry name"
+    /// appears only once the user selects the client — the explicit read.
+    func testSelectingResolvesConnectedStateAndEntryNameInTheRow() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [.success([
+            FakeConnectSource.client(id: "claude-code", name: "Claude Code", exists: true)
+        ])]
+        source.detailResults = [.success(FakeConnectSource.client(
+            id: "claude-code", name: "Claude Code", exists: true, connected: true,
+            accessState: .accessible, serverName: "my-proxy"))]
+        let model = makeModel(source)
+        await model.loadList()
+        XCTAssertEqual(model.rows.first?.stateLabel, "Config present")
+        XCTAssertEqual(model.rows.first?.connected, false)
+
+        await model.select("claude-code")
+
+        XCTAssertEqual(model.rows.first?.stateLabel, "Connected as \"my-proxy\"")
+        XCTAssertEqual(model.rows.first?.connected, true)
+    }
+
+    /// FR-009: the two unreadable access states get their defined labels, and
+    /// denied carries the core's remediation.
+    func testUnreadableAndDeniedRowsCarryTheirMappedLabels() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [.success([
+            FakeConnectSource.client(id: "cursor", exists: true)
+        ])]
+        source.detailResults = [
+            .success(FakeConnectSource.client(id: "cursor", exists: true, accessState: .malformed)),
+            .success(FakeConnectSource.client(id: "cursor", exists: true, accessState: .denied,
+                                              remediation: "Grant Full Disk Access to MCPProxy"))
+        ]
+        let model = makeModel(source)
+        await model.loadList()
+
+        await model.select("cursor")
+        XCTAssertEqual(model.rows.first?.stateLabel, "Config unreadable")
+
+        await model.refreshDetail()
+        XCTAssertEqual(model.rows.first?.stateLabel, "Access not granted")
+        XCTAssertEqual(model.rows.first?.note, "Grant Full Disk Access to MCPProxy")
+    }
+
+    /// US2 scenario 3: a completed connect refreshes the AFFECTED client from the
+    /// core — not the whole list, and never by the tray reading a config itself.
+    func testOnlyTheAffectedClientRefreshesAfterAConnect() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [.success([
+            FakeConnectSource.client(id: "claude-code", name: "Claude Code", exists: true),
+            FakeConnectSource.client(id: "cursor", name: "Cursor", exists: false)
+        ])]
+        source.detailResults = [
+            .success(FakeConnectSource.client(id: "claude-code", name: "Claude Code",
+                                              exists: true, connected: false)),
+            .success(FakeConnectSource.client(id: "claude-code", name: "Claude Code",
+                                              exists: true, connected: true,
+                                              serverName: "mcpproxy"))
+        ]
+        let model = makeModel(source)
+        await model.loadList()
+        await model.select("claude-code")
+
+        await model.connect()
+
+        XCTAssertEqual(source.clientsCallCount, 1,
+                       "the whole list must not be refetched after an action")
+        XCTAssertEqual(source.detailCalls, ["claude-code", "claude-code"],
+                       "only the affected client's state is re-read")
+        XCTAssertEqual(model.rows.map(\.stateLabel),
+                       ["Connected as \"mcpproxy\"", "No config found"])
+    }
+
+    /// A disconnect settles the same way: the affected row re-reads, the rest of
+    /// the list is left alone.
+    func testOnlyTheAffectedClientRefreshesAfterADisconnect() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [.success([
+            FakeConnectSource.client(id: "claude-code", name: "Claude Code", exists: true),
+            FakeConnectSource.client(id: "cursor", name: "Cursor", exists: false)
+        ])]
+        source.detailResults = [
+            .success(FakeConnectSource.client(id: "claude-code", name: "Claude Code",
+                                              exists: true, connected: true,
+                                              serverName: "mcpproxy")),
+            .success(FakeConnectSource.client(id: "claude-code", name: "Claude Code",
+                                              exists: true, connected: false))
+        ]
+        let model = makeModel(source)
+        await model.loadList()
+        await model.select("claude-code")
+        XCTAssertEqual(model.rows.first?.stateLabel, "Connected as \"mcpproxy\"")
+
+        model.requestDisconnect()
+        await model.confirmDisconnect()
+
+        XCTAssertEqual(source.disconnectCalls, ["claude-code"])
+        XCTAssertEqual(source.clientsCallCount, 1)
+        XCTAssertEqual(model.rows.map(\.stateLabel), ["Config present", "No config found"])
+    }
+
+    /// The rows exist only for a loaded list; while waiting there is nothing to
+    /// render and nothing to select.
+    func testRowsAreEmptyUntilTheListLoads() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [
+            .failure(APIClientError.notReady),
+            .success([FakeConnectSource.client(id: "claude-code")])
+        ]
+        let recorder = SleepRecorder()
+        let model = makeModel(source, recorder: recorder)
+
+        XCTAssertTrue(model.rows.isEmpty, "nothing to render while loading")
+        await model.loadList()
+
+        XCTAssertEqual(recorder.rowSnapshots.first?.isEmpty, true,
+                       "an unreachable core renders no rows")
+        XCTAssertEqual(model.rows.count, 1)
+    }
+
+    // MARK: - US3: session-scoped undo (T022)
+
+    /// FR-006: undo exists for a connect performed in THIS open form, and for
+    /// nothing else — not for a freshly opened form over an already connected
+    /// client, whose backup identity this session never saw.
+    func testUndoIsNotOfferedBeforeAConnect() async {
+        let source = FakeConnectSource()
+        source.detailResults = [.success(FakeConnectSource.client(
+            id: "claude-code", connected: true, serverName: "mcpproxy"))]
+        let model = makeModel(source)
+
+        await model.select("claude-code")
+
+        XCTAssertFalse(model.undoControlExists,
+                       "a connect this session did not perform has no undo")
+        await model.undo()
+        XCTAssertTrue(source.undoCalls.isEmpty)
+    }
+
+    /// The undo carries the backup identity of exactly that connect — and the
+    /// core wants the BARE FILENAME, so a full path must not be sent (it is a
+    /// 400 by contract).
+    func testUndoCarriesTheBackupIdentityOfThatConnectAsABareFilename() async {
+        let source = FakeConnectSource()
+        source.connectResults = [.success(FakeConnectSource.result(
+            action: "updated",
+            backupPath: "/Users/x/.claude.json.20260731-120000.bak"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        await model.connect()
+        XCTAssertTrue(model.undoControlExists)
+        await model.undo()
+
+        XCTAssertEqual(source.undoCalls.count, 1)
+        XCTAssertEqual(source.undoCalls.first?.clientId, "claude-code")
+        XCTAssertEqual(source.undoCalls.first?.backupName,
+                       ".claude.json.20260731-120000.bak",
+                       "the core rejects a path; only the bare backup filename is valid")
+    }
+
+    /// The created-file case: no backup exists, so no identity is sent and the
+    /// core removes the file the connect created.
+    func testUndoAfterACreateSendsNoBackupIdentity() async {
+        let source = FakeConnectSource()
+        source.connectResults = [.success(FakeConnectSource.result(action: "created"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        await model.connect()
+        await model.undo()
+
+        XCTAssertEqual(source.undoCalls.count, 1)
+        XCTAssertNil(source.undoCalls.first?.backupName,
+                     "an empty identity must be absent, not an empty string")
+    }
+
+    func testUndoDisappearsOnceUsed() async {
+        let source = FakeConnectSource()
+        let model = makeModel(source)
+        await model.select("claude-code")
+        await model.connect()
+        XCTAssertTrue(model.undoControlExists)
+
+        await model.undo()
+
+        XCTAssertFalse(model.undoControlExists)
+        await model.undo()
+        XCTAssertEqual(source.undoCalls.count, 1, "a used undo cannot be replayed")
+    }
+
+    /// FR-006: closing the form ends the undo's scope; the core keeps no
+    /// cross-session undo state, so offering it after a reopen would lie.
+    func testUndoDisappearsWhenTheFormCloses() async {
+        let source = FakeConnectSource()
+        let model = makeModel(source)
+        await model.select("claude-code")
+        await model.connect()
+        XCTAssertTrue(model.undoControlExists)
+
+        model.formWillClose()
+
+        XCTAssertFalse(model.undoControlExists)
+        await model.undo()
+        XCTAssertTrue(source.undoCalls.isEmpty)
+    }
+
+    func testAFailedConnectOffersNoUndo() async {
+        let source = FakeConnectSource()
+        source.connectResults = [.failure(
+            APIClientError.httpError(statusCode: 400, message: "config is not writable"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        await model.connect()
+
+        XCTAssertFalse(model.undoControlExists, "nothing was written, nothing to undo")
+    }
+
+    /// The undo belongs to the client it was performed on: browsing to another
+    /// client hides it, and coming back shows it again.
+    func testUndoIsScopedToTheClientItWasPerformedOn() async {
+        let source = FakeConnectSource()
+        let model = makeModel(source)
+        await model.select("claude-code")
+        await model.connect()
+        XCTAssertTrue(model.undoControlExists)
+
+        await model.select("cursor")
+        XCTAssertFalse(model.undoControlExists)
+
+        await model.select("claude-code")
+        XCTAssertTrue(model.undoControlExists)
+    }
+
+    /// Off-socket the undo is visible but disabled, like every mutating control.
+    func testOffSocketUndoSendsNothing() async {
+        let source = FakeConnectSource()
+        let model = makeModel(source)
+        await model.select("claude-code")
+        await model.connect()
+        source.transportKind = .tcp
+
+        await model.undo()
+
+        XCTAssertTrue(source.undoCalls.isEmpty)
+        XCTAssertFalse(model.isUndoEnabled)
+    }
+
+    // MARK: - US3: disconnect confirmation (T022)
+
+    /// US3 scenario 3 / FR-006: the confirmation names the config file and the
+    /// entry, and NOTHING is sent until it is confirmed.
+    func testDisconnectAsksForAConfirmationNamingTheFileAndEntryBeforeSendingAnything() async {
+        let source = FakeConnectSource()
+        source.detailResults = [.success(FakeConnectSource.client(
+            id: "claude-code", connected: true, serverName: "my-proxy"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        model.requestDisconnect()
+
+        let confirmation = try? XCTUnwrap(model.pendingDisconnect)
+        XCTAssertEqual(confirmation?.clientId, "claude-code")
+        XCTAssertEqual(confirmation?.entryName, "my-proxy")
+        XCTAssertEqual(confirmation?.configPath, "/Users/x/.claude-code/config.json")
+        XCTAssertTrue(confirmation?.message.contains("my-proxy") ?? false,
+                      "the confirmation must name the entry: \(confirmation?.message ?? "")")
+        XCTAssertTrue(confirmation?.message.contains("/Users/x/.claude-code/config.json") ?? false,
+                      "the confirmation must name the file: \(confirmation?.message ?? "")")
+        XCTAssertTrue(source.disconnectCalls.isEmpty, "asking must not remove anything")
+
+        await model.confirmDisconnect()
+
+        XCTAssertEqual(source.disconnectCalls, ["claude-code"])
+        XCTAssertNil(model.pendingDisconnect)
+    }
+
+    func testCancellingTheDisconnectConfirmationSendsNothing() async {
+        let source = FakeConnectSource()
+        source.detailResults = [.success(FakeConnectSource.client(
+            id: "claude-code", connected: true, serverName: "mcpproxy"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        model.requestDisconnect()
+        model.cancelDisconnect()
+        await model.confirmDisconnect()
+
+        XCTAssertNil(model.pendingDisconnect)
+        XCTAssertTrue(source.disconnectCalls.isEmpty)
+    }
+
+    /// A client that is not connected has no entry to remove, so the control is
+    /// absent and asking for it does nothing.
+    func testDisconnectIsNotOfferedForAClientThatIsNotConnected() async {
+        let source = FakeConnectSource()
+        source.detailResults = [.success(
+            FakeConnectSource.client(id: "cursor", connected: false))]
+        let model = makeModel(source)
+        await model.select("cursor")
+
+        XCTAssertFalse(model.disconnectControlExists)
+        model.requestDisconnect()
+
+        XCTAssertNil(model.pendingDisconnect)
+    }
+
+    /// Selecting another client abandons a confirmation the user left open, so a
+    /// later confirm cannot remove an entry from the wrong client's config.
+    func testChangingTheSelectionAbandonsAPendingDisconnectConfirmation() async {
+        let source = FakeConnectSource()
+        source.detailResults = [
+            .success(FakeConnectSource.client(id: "claude-code", connected: true,
+                                              serverName: "mcpproxy")),
+            .success(FakeConnectSource.client(id: "cursor", connected: false))
+        ]
+        let model = makeModel(source)
+        await model.select("claude-code")
+        model.requestDisconnect()
+        XCTAssertNotNil(model.pendingDisconnect)
+
+        await model.select("cursor")
+
+        XCTAssertNil(model.pendingDisconnect)
+        await model.confirmDisconnect()
+        XCTAssertTrue(source.disconnectCalls.isEmpty)
+    }
+
+    func testOffSocketDisconnectSendsNothing() async {
+        let source = FakeConnectSource()
+        source.transportKind = .tcp
+        source.detailResults = [.success(FakeConnectSource.client(
+            id: "claude-code", connected: true, serverName: "mcpproxy"))]
+        let model = makeModel(source)
+        await model.select("claude-code")
+
+        model.requestDisconnect()
+        await model.confirmDisconnect()
+
+        XCTAssertTrue(source.disconnectCalls.isEmpty)
+        XCTAssertFalse(model.isDisconnectEnabled)
+    }
+
+    // MARK: - List selection (FR-009)
+
+    /// An unsupported client stays visible but is not a selection. Clicking it
+    /// still moves the list's own highlight, so the model has to say what the
+    /// selection may be — otherwise the highlight sits on one client while the
+    /// detail pane, the preview and an ENABLED Connect button still target
+    /// another, and the user writes a config they were not looking at.
+    func testAnUnsupportedRowIsNotASelectionAndSnapsBack() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [.success([
+            FakeConnectSource.client(id: "cursor", name: "Cursor"),
+            FakeConnectSource.client(id: "opencode", name: "OpenCode", supported: false,
+                                     reason: "not supported on this platform")
+        ])]
+        let model = makeModel(source)
+        await model.loadList()
+        await model.select("cursor")
+
+        XCTAssertEqual(model.listSelection(for: "opencode"), "cursor",
+                       "the highlight must snap back to the client the form is showing")
+        XCTAssertEqual(model.listSelection(for: "cursor"), "cursor")
+        XCTAssertEqual(model.listSelection(for: nil), "cursor",
+                       "clearing the highlight must not orphan the pane either")
+        XCTAssertEqual(model.selection, "cursor", "and nothing about the form changed")
+    }
+
+    /// With nothing selected yet, an unsupported row resolves to no selection —
+    /// the pane keeps its "select a client" placeholder.
+    func testAnUnsupportedRowResolvesToNoSelectionWhenNoneExists() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [.success([
+            FakeConnectSource.client(id: "opencode", name: "OpenCode", supported: false)
+        ])]
+        let model = makeModel(source)
+        await model.loadList()
+
+        XCTAssertNil(model.listSelection(for: "opencode"))
+        XCTAssertNil(model.selection)
+    }
+}
+
+/// Presentation wiring for the Connect Client form (spec 091 T018): one shared
+/// route into the form, and accessibility identifiers a UI test can rely on.
+@MainActor
+final class ConnectClientPresentationTests: XCTestCase {
+
+    /// The tray item and (FR-012) the dashboard must both go through the same
+    /// route, so no native path can reach a connect without the preview step.
+    func testTheMenuItemIsTitledConnectClientAndCarriesBothTargetAndAction() {
+        let item = ConnectClientMenuRouter.shared.makeMenuItem()
+
+        XCTAssertEqual(item.title, ConnectClientPresentation.menuTitle)
+        XCTAssertEqual(item.title, "Connect Client…")
+        XCTAssertNotNil(item.action)
+        XCTAssertTrue(item.target === ConnectClientMenuRouter.shared,
+                      "a nil target makes the row silently do nothing")
+    }
+
+    func testDispatchingTheMenuItemPostsTheSharedPresentationRoute() throws {
+        let item = ConnectClientMenuRouter.shared.makeMenuItem()
+        let received = expectation(description: "presentation route posted")
+        let token = NotificationCenter.default.addObserver(
+            forName: ConnectClientPresentation.route, object: nil, queue: .main
+        ) { _ in received.fulfill() }
+        defer { NotificationCenter.default.removeObserver(token) }
+
+        let dispatched = NSApplication.shared.sendAction(
+            try XCTUnwrap(item.action), to: item.target, from: item)
+
+        XCTAssertTrue(dispatched, "the menu item did not dispatch")
+        wait(for: [received], timeout: 1)
+    }
+
+    /// FR-010: the identifiers are a contract with the UI tests, so they are
+    /// pinned literally — renaming one silently breaks an external caller.
+    func testAccessibilityIdentifiersAreStable() {
+        XCTAssertEqual(ConnectClientAccessibility.list, "connect-client-list")
+        XCTAssertEqual(ConnectClientAccessibility.row("claude-code"),
+                       "connect-client-row-claude-code")
+        XCTAssertEqual(ConnectClientAccessibility.preview, "connect-client-preview")
+        XCTAssertEqual(ConnectClientAccessibility.entryText, "connect-client-entry-text")
+        XCTAssertEqual(ConnectClientAccessibility.configPath, "connect-client-config-path")
+        XCTAssertEqual(ConnectClientAccessibility.existingSummary,
+                       "connect-client-existing-summary")
+        XCTAssertEqual(ConnectClientAccessibility.safetyNet, "connect-client-safety-net")
+        XCTAssertEqual(ConnectClientAccessibility.credentialNotice,
+                       "connect-client-credential-notice")
+        XCTAssertEqual(ConnectClientAccessibility.refusal, "connect-client-refusal")
+        XCTAssertEqual(ConnectClientAccessibility.entryNameField, "connect-client-entry-name")
+        XCTAssertEqual(ConnectClientAccessibility.connectButton, "connect-client-connect")
+    }
+
+    func testAccessibilityIdentifiersAreUnique() {
+        let identifiers = ConnectClientAccessibility.allIdentifiers
+        XCTAssertEqual(Set(identifiers).count, identifiers.count,
+                       "two elements sharing an identifier make a UI test ambiguous")
+        XCTAssertTrue(identifiers.allSatisfy { $0.hasPrefix("connect-client-") })
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxyTests/ConnectFormWindowLifecycleTests.swift b/native/macos/MCPProxy/MCPProxyTests/ConnectFormWindowLifecycleTests.swift
new file mode 100644
index 00000000..f6be9100
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/ConnectFormWindowLifecycleTests.swift
@@ -0,0 +1,204 @@
+import XCTest
+import AppKit
+import SwiftUI
+@testable import MCPProxy
+
+/// The Connect form's window can be dismissed two ways — its own Close button
+/// and the titlebar's red button — and only the first used to run through the
+/// app's dismissal path. With `isReleasedWhenClosed = false` a red-button close
+/// merely orders the window out: the hosting view, the model and the SwiftUI
+/// `.task` behind them stay alive, so the form's 2 s core-reachability poll kept
+/// running from a window nobody could see. Both routes must end the same way.
+@MainActor
+final class ConnectFormWindowLifecycleTests: XCTestCase {
+
+    private func makeWindow() -> NSWindow {
+        let window = NSWindow(
+            contentRect: NSRect(x: 0, y: 0, width: 400, height: 300),
+            styleMask: [.titled, .closable, .resizable],
+            backing: .buffered,
+            defer: false)
+        window.isReleasedWhenClosed = false
+        return window
+    }
+
+    func testTheTitlebarCloseEndsTheSessionScopedUndo() async {
+        let source = FakeConnectSource()
+        let model = ConnectClientModel(source: source, sleeper: { _ in })
+        await model.select("claude-code")
+        await model.connect()
+        XCTAssertTrue(model.undoControlExists, "precondition: this form performed a connect")
+
+        let lifecycle = ConnectFormWindowLifecycle()
+        let window = makeWindow()
+        lifecycle.adopt(window, model: model)
+
+        XCTAssertTrue(lifecycle.windowWillClose(window),
+                      "the notification belongs to the form's window")
+
+        XCTAssertFalse(model.undoControlExists, "the undo's scope ends with the form (FR-006)")
+        XCTAssertNil(lifecycle.window, "a closed window must not stay adopted")
+        XCTAssertNil(lifecycle.model)
+    }
+
+    /// The teardown must actually RELEASE the view hierarchy — that is what
+    /// cancels the SwiftUI task driving the poll. Merely forgetting the window
+    /// reference would leave the retained, invisible window polling.
+    func testTheTitlebarCloseReleasesTheFormAndItsPollLoop() {
+        let lifecycle = ConnectFormWindowLifecycle()
+        let window = makeWindow()
+        weak var hostingView: NSView?
+        weak var weakModel: ConnectClientModel?
+
+        autoreleasepool {
+            let model = ConnectClientModel(source: FakeConnectSource(), sleeper: { _ in })
+            let hosting = NSHostingView(rootView: ConnectClientView(model: model))
+            window.contentView = hosting
+            lifecycle.adopt(window, model: model)
+            hostingView = hosting
+            weakModel = model
+        }
+        XCTAssertNotNil(hostingView, "precondition: the form is presented")
+
+        autoreleasepool {
+            lifecycle.windowWillClose(window)
+        }
+
+        XCTAssertNil(hostingView, "the hosting view must be released, cancelling its .task")
+        XCTAssertNil(weakModel, "so the 2 s reachability poll cannot keep running unseen")
+    }
+
+    /// Presented as a SHEET, the form's own window never gets a close
+    /// notification of its own: closing the host takes the sheet with it.
+    ///
+    /// Probed on this macOS: AppKit lets a sheet-bearing parent close, orders
+    /// the sheet out with it, posts `willClose` for the HOST ONLY, and never
+    /// runs `beginSheet`'s completion handler — so that completion cannot be
+    /// the teardown hook, and the host's close has to be.
+    func testClosingTheHostOfAnAttachedSheetTearsTheFormDown() {
+        let lifecycle = ConnectFormWindowLifecycle()
+        let host = makeWindow()
+        let sheet = makeWindow()
+        let model = ConnectClientModel(source: FakeConnectSource(), sleeper: { _ in })
+        lifecycle.adopt(sheet, model: model, host: host)
+
+        XCTAssertTrue(lifecycle.windowWillClose(host),
+                      "the host's close is the only notification this form will see")
+
+        XCTAssertNil(lifecycle.window)
+        XCTAssertNil(lifecycle.model)
+    }
+
+    /// Belt and braces: even a form adopted without its host is recognised
+    /// through AppKit's own sheet relationship.
+    func testClosingTheSheetParentTearsTheFormDown() throws {
+        let lifecycle = ConnectFormWindowLifecycle()
+        let host = makeWindow()
+        let sheet = makeWindow()
+        host.makeKeyAndOrderFront(nil)
+        host.beginSheet(sheet) { _ in }
+        RunLoop.current.run(until: Date().addingTimeInterval(0.2))
+        try XCTSkipIf(sheet.sheetParent == nil, "AppKit did not attach the sheet in this environment")
+
+        lifecycle.adopt(sheet, model: ConnectClientModel(source: FakeConnectSource(), sleeper: { _ in }))
+
+        XCTAssertTrue(lifecycle.windowWillClose(host))
+        XCTAssertNil(lifecycle.model)
+
+        host.endSheet(sheet)
+        host.close()
+    }
+
+    /// Counts what the poll asked the clock for, so "it stopped" is a measured
+    /// fact rather than an inference.
+    @MainActor
+    final class PollCounter {
+        private(set) var ticks = 0
+        func tick() { ticks += 1 }
+    }
+
+    /// The leak that mattered is a poll that keeps running, so this drives the
+    /// poll for real: against an unreachable core it iterates, and once the task
+    /// carrying it is cancelled the counter FREEZES.
+    ///
+    /// Cancellation is what the teardown ultimately triggers — SwiftUI cancels
+    /// the `.task` when the hosting view goes away, which the release test above
+    /// pins by proving that view and model are deallocated. That SwiftUI link
+    /// cannot be exercised here: probed on this machine, a `.task` never starts
+    /// under `swift test` even with a key, activated window and a hosting
+    /// controller (zero iterations, the view stays in its initial state), so
+    /// this covers the half that is ours — that `loadList` honours the
+    /// cancellation it is sent.
+    ///
+    /// Note the sleeper mirrors the production one, which returns IMMEDIATELY
+    /// once cancelled (`try? await Task.sleep`): a loop that did not check
+    /// `Task.isCancelled` would not slow down here, it would spin.
+    func testTheReachabilityPollRunsAndThenProvablyStops() async {
+        let source = FakeConnectSource()
+        source.clientsResults = [.failure(APIClientError.notReady)]
+        let counter = PollCounter()
+        let model = ConnectClientModel(source: source, sleeper: { _ in
+            counter.tick()
+            try? await Task.sleep(nanoseconds: 5_000_000)
+        })
+
+        let poll = Task { await model.loadList() }
+        defer { poll.cancel() }
+
+        // It is polling: wait for real iterations rather than assuming any.
+        for _ in 0..<200 where counter.ticks < 3 {
+            try? await Task.sleep(nanoseconds: 5_000_000)
+        }
+        XCTAssertGreaterThanOrEqual(counter.ticks, 3,
+                                    "precondition: the form is polling an unreachable core")
+        XCTAssertEqual(model.list, .coreUnreachable(APIClientError.notReady.errorDescription ?? ""))
+
+        poll.cancel()
+        let atCancellation = counter.ticks
+
+        // Well past several poll intervals at this cadence.
+        try? await Task.sleep(nanoseconds: 200_000_000)
+
+        XCTAssertEqual(counter.ticks, atCancellation,
+                       "the poll must STOP, not merely slow down, once its task is cancelled")
+    }
+
+    func testAnUnrelatedWindowClosingIsIgnored() {
+        let lifecycle = ConnectFormWindowLifecycle()
+        let window = makeWindow()
+        let model = ConnectClientModel(source: FakeConnectSource(), sleeper: { _ in })
+        lifecycle.adopt(window, model: model)
+
+        XCTAssertFalse(lifecycle.windowWillClose(makeWindow()),
+                       "another window's close is none of the form's business")
+        XCTAssertNotNil(lifecycle.window)
+        XCTAssertNotNil(lifecycle.model)
+    }
+
+    /// The form's own Close button goes through the same teardown, so the two
+    /// routes cannot drift apart again.
+    func testDismissClosesTheWindowAndTearsDown() {
+        let lifecycle = ConnectFormWindowLifecycle()
+        let window = makeWindow()
+        let model = ConnectClientModel(source: FakeConnectSource(), sleeper: { _ in })
+        lifecycle.adopt(window, model: model)
+
+        lifecycle.dismiss()
+
+        XCTAssertFalse(window.isVisible)
+        XCTAssertNil(lifecycle.window)
+        XCTAssertNil(lifecycle.model)
+    }
+
+    func testAdoptingReplacesAPreviousForm() {
+        let lifecycle = ConnectFormWindowLifecycle()
+        let first = makeWindow()
+        lifecycle.adopt(first, model: ConnectClientModel(source: FakeConnectSource(), sleeper: { _ in }))
+        let second = makeWindow()
+        lifecycle.adopt(second, model: ConnectClientModel(source: FakeConnectSource(), sleeper: { _ in }))
+
+        XCTAssertTrue(lifecycle.window === second)
+        XCTAssertFalse(lifecycle.windowWillClose(first),
+                       "the replaced window no longer drives the lifecycle")
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxyTests/ConnectModelsDecodingTests.swift b/native/macos/MCPProxy/MCPProxyTests/ConnectModelsDecodingTests.swift
new file mode 100644
index 00000000..b5526345
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/ConnectModelsDecodingTests.swift
@@ -0,0 +1,300 @@
+import XCTest
+@testable import MCPProxy
+
+/// Wire-format tests for the Connect Client form's models (spec 091 T012).
+///
+/// Every fixture here is JSON the core actually emits — synthesized, never
+/// fetched — so the whole Swift track runs without a live core.
+final class ConnectModelsDecodingTests: XCTestCase {
+
+    private func decodeStatus(_ json: String) throws -> APIClient.ClientStatus {
+        try JSONDecoder().decode(APIClient.ClientStatus.self, from: Data(json.utf8))
+    }
+
+    private func decodePreview(_ json: String) throws -> ConnectPreviewModel {
+        try JSONDecoder().decode(ConnectPreviewModel.self, from: Data(json.utf8))
+    }
+
+    // MARK: - ClientStatus (extended)
+
+    func testClientStatusDecodesTheExtendedFields() throws {
+        let status = try decodeStatus("""
+        {"id":"claude-code","name":"Claude Code",
+         "config_path":"/Users/x/.claude.json","exists":true,"connected":true,
+         "supported":true,"icon":"claude-code","server_name":"mcpproxy",
+         "access_state":"accessible"}
+        """)
+
+        XCTAssertEqual(status.clientId, "claude-code")
+        XCTAssertEqual(status.icon, "claude-code")
+        XCTAssertEqual(status.serverName, "mcpproxy")
+        XCTAssertEqual(status.accessState, .accessible)
+        XCTAssertNil(status.remediation)
+    }
+
+    func testClientStatusDecodesDeniedAccessWithRemediation() throws {
+        let status = try decodeStatus("""
+        {"id":"cursor","name":"Cursor","config_path":"/Users/x/.cursor/mcp.json",
+         "exists":true,"connected":false,"supported":true,"icon":"cursor",
+         "access_state":"denied",
+         "remediation":"Grant MCPProxy access to App Data in System Settings › Privacy & Security."}
+        """)
+
+        XCTAssertEqual(status.accessState, .denied)
+        XCTAssertEqual(
+            status.remediation,
+            "Grant MCPProxy access to App Data in System Settings › Privacy & Security."
+        )
+    }
+
+    /// A core older than spec 091 sends none of the four additive fields; the
+    /// row must still decode rather than blanking the whole list.
+    func testClientStatusToleratesACoreWithoutTheExtendedFields() throws {
+        let status = try decodeStatus("""
+        {"id":"gemini","name":"Gemini CLI","config_path":"/Users/x/.gemini/settings.json",
+         "exists":false,"connected":false,"supported":true}
+        """)
+
+        XCTAssertNil(status.icon)
+        XCTAssertNil(status.serverName)
+        XCTAssertNil(status.accessState)
+        // A known client whose old core sent no `icon` still resolves its symbol
+        // through the client id; only a genuinely unknown identity falls all the
+        // way through to the generic symbol (asserted below).
+        XCTAssertEqual(status.symbolName, "sparkles")
+    }
+
+    /// A core newer than the app can report a client this build has never heard
+    /// of. It renders by name with the default icon and stays fully functional
+    /// (FR-009), so nothing about the decode may be id-conditional.
+    func testUnknownClientIDDecodesGenerically() throws {
+        let status = try decodeStatus("""
+        {"id":"brand-new-client","name":"Brand New Client",
+         "config_path":"/Users/x/.brandnew/config.json","exists":true,
+         "connected":false,"supported":true,"icon":"brand-new-client",
+         "access_state":"accessible"}
+        """)
+
+        XCTAssertEqual(status.displayName, "Brand New Client")
+        XCTAssertEqual(status.symbolName, "app.connected.to.app.below.fill")
+        XCTAssertTrue(status.supported)
+    }
+
+    /// An unrecognised access_state string must not fail the decode.
+    func testUnknownAccessStateDecodesAsUnknown() throws {
+        let status = try decodeStatus("""
+        {"id":"codex","name":"Codex","config_path":"/x","exists":true,
+         "connected":false,"supported":true,"access_state":"future-state"}
+        """)
+
+        XCTAssertEqual(status.accessState, .unknown)
+    }
+
+    // MARK: - ConnectPreviewModel — the three new fields
+
+    private static let replacePreviewJSON = """
+    {"client":"claude-code","config_path":"/Users/x/.claude.json","format":"json",
+     "server_key":"mcpServers","server_name":"mcpproxy",
+     "entry":{"type":"http","url":"http://127.0.0.1:8080/mcp"},
+     "entry_text":"\\"mcpproxy\\": {\\n  \\"type\\": \\"http\\"\\n}",
+     "entry_exists":true,"contains_api_key":true,"access_state":"accessible",
+     "existing_entry_summary":{"entry_name":"old-proxy","type":"http",
+       "endpoint":"http://127.0.0.1:9090/mcp","command":null,
+       "header_names":["X-API-Key"],"env_names":[]},
+     "precondition_token":"9f2c…opaque","connect_refusal":null}
+    """
+
+    func testPreviewDecodesTheThreeNewFields() throws {
+        let preview = try decodePreview(Self.replacePreviewJSON)
+
+        XCTAssertEqual(preview.configPath, "/Users/x/.claude.json")
+        XCTAssertEqual(preview.serverName, "mcpproxy")
+        XCTAssertTrue(preview.entryExists)
+        XCTAssertTrue(preview.containsAPIKey)
+        XCTAssertEqual(preview.accessState, .accessible)
+        XCTAssertEqual(preview.preconditionToken, "9f2c…opaque")
+        XCTAssertNil(preview.connectRefusal)
+
+        let summary = try XCTUnwrap(preview.existingEntrySummary)
+        XCTAssertEqual(summary.entryName, "old-proxy")
+        XCTAssertEqual(summary.type, "http")
+        XCTAssertEqual(summary.endpoint, "http://127.0.0.1:9090/mcp")
+        XCTAssertNil(summary.command)
+        XCTAssertEqual(summary.headerNames, ["X-API-Key"])
+        XCTAssertEqual(summary.envNames, [])
+    }
+
+    /// Go omits empty slices as `null` (or drops them); neither may produce nil
+    /// arrays the view would have to special-case.
+    func testSummaryTreatsMissingNameArraysAsEmpty() throws {
+        let preview = try decodePreview("""
+        {"config_path":"/x","server_name":"mcpproxy","entry_text":"…",
+         "entry_exists":true,"contains_api_key":false,"access_state":"accessible",
+         "existing_entry_summary":{"entry_name":"mcpproxy","type":"stdio",
+           "command":"/usr/local/bin/mcpproxy"},
+         "precondition_token":"tok"}
+        """)
+
+        let summary = try XCTUnwrap(preview.existingEntrySummary)
+        XCTAssertEqual(summary.headerNames, [])
+        XCTAssertEqual(summary.envNames, [])
+        XCTAssertEqual(summary.command, "/usr/local/bin/mcpproxy")
+        XCTAssertNil(summary.endpoint)
+    }
+
+    /// A pre-091 core sends no token, no summary and no refusal. Decoding must
+    /// tolerate that; the model decides separately what it may still write.
+    func testPreviewToleratesALegacyCoreWithoutTheNewFields() throws {
+        let preview = try decodePreview("""
+        {"client":"cursor","config_path":"/x","server_name":"mcpproxy",
+         "entry_text":"…","entry_exists":false,"contains_api_key":false,
+         "access_state":"accessible"}
+        """)
+
+        XCTAssertNil(preview.preconditionToken)
+        XCTAssertNil(preview.existingEntrySummary)
+        XCTAssertNil(preview.connectRefusal)
+        XCTAssertEqual(preview.changeKind, .add)
+        XCTAssertFalse(preview.coreSupportsPreconditionTokens,
+                       "a core that omits the field entirely does not speak the 091 protocol")
+    }
+
+    /// A spec-091 core ALWAYS sends the field, even when the value is empty, so
+    /// its presence is what distinguishes "this core has no tokens" from "this
+    /// core gave me no token".
+    func testAPresentButEmptyTokenStillMeansTheCoreSpeaksTheProtocol() throws {
+        let preview = try decodePreview("""
+        {"client":"cursor","config_path":"/x","server_name":"mcpproxy",
+         "entry_text":"…","entry_exists":true,"contains_api_key":false,
+         "access_state":"accessible","precondition_token":""}
+        """)
+
+        XCTAssertTrue(preview.coreSupportsPreconditionTokens)
+        XCTAssertTrue(preview.replaceIsBlockedByAMissingToken,
+                      "a 091 core owes a token for a replace; without one the write is not offered")
+    }
+
+    /// Against a PRE-091 core a replace is not blocked: that core never sends a
+    /// token and its write legitimately falls back to the legacy behaviour, so
+    /// blocking would leave the user with a full preview and no action at all.
+    func testAReplaceAgainstAPre091CoreIsNotBlocked() throws {
+        let preview = try decodePreview("""
+        {"client":"cursor","config_path":"/x","server_name":"mcpproxy",
+         "entry_text":"…","entry_exists":true,"contains_api_key":false,
+         "access_state":"accessible"}
+        """)
+
+        XCTAssertEqual(preview.changeKind, .replace(entryName: "mcpproxy"))
+        XCTAssertFalse(preview.replaceIsBlockedByAMissingToken)
+    }
+
+    // MARK: - changeKind derivation (all six cases)
+
+    private func preview(
+        entryExists: Bool = false,
+        accessState: String = "accessible",
+        refusal: String? = nil,
+        summaryName: String? = nil,
+        containsAPIKey: Bool = false
+    ) throws -> ConnectPreviewModel {
+        let summary = summaryName.map {
+            """
+            ,"existing_entry_summary":{"entry_name":"\($0)","type":"http",
+              "endpoint":"http://127.0.0.1:9090/mcp","header_names":[],"env_names":[]}
+            """
+        } ?? ""
+        let refusalField = refusal.map { ",\"connect_refusal\":\"\($0)\"" } ?? ""
+        return try decodePreview("""
+        {"client":"c","config_path":"/x","server_name":"mcpproxy","entry_text":"…",
+         "entry_exists":\(entryExists),"contains_api_key":\(containsAPIKey),
+         "access_state":"\(accessState)","precondition_token":"tok"\(summary)\(refusalField)}
+        """)
+    }
+
+    func testRefusalOutranksEveryOtherClassification() throws {
+        let refused = try preview(
+            accessState: "absent",
+            refusal: "opencode requires an existing config file; create one first"
+        )
+
+        XCTAssertEqual(
+            refused.changeKind,
+            .refused("opencode requires an existing config file; create one first")
+        )
+        XCTAssertFalse(refused.allowsConnect,
+                       "a refusal-bearing preview must never offer Connect")
+        XCTAssertNil(refused.safetyNetStatement,
+                     "no file will be created, so the create statement must not render")
+    }
+
+    func testAbsentConfigIsACreate() throws {
+        let create = try preview(accessState: "absent")
+
+        XCTAssertEqual(create.changeKind, .create)
+        XCTAssertTrue(create.allowsConnect)
+        XCTAssertEqual(
+            create.safetyNetStatement,
+            "This file does not exist; it will be created, and Undo removes it."
+        )
+    }
+
+    func testReadableConfigWithoutTheEntryIsAnAdd() throws {
+        let add = try preview(entryExists: false, accessState: "accessible")
+
+        XCTAssertEqual(add.changeKind, .add)
+        XCTAssertTrue(add.allowsConnect)
+        XCTAssertEqual(
+            add.safetyNetStatement,
+            "A timestamped backup of this file will be created alongside it."
+        )
+    }
+
+    /// The write adopts an equivalent entry living under a different key; the
+    /// summary names that key, and the change kind must carry it so the form
+    /// can say what it is really replacing.
+    func testExistingEntryIsAReplaceNamedAfterTheAdoptedEntry() throws {
+        let replace = try preview(entryExists: true, summaryName: "old-proxy")
+
+        XCTAssertEqual(replace.changeKind, .replace(entryName: "old-proxy"))
+        XCTAssertTrue(replace.allowsConnect)
+        XCTAssertEqual(
+            replace.safetyNetStatement,
+            "A timestamped backup of this file will be created alongside it."
+        )
+    }
+
+    /// Without a summary (older core) the replace still classifies, falling back
+    /// to the requested entry name.
+    func testReplaceWithoutASummaryFallsBackToTheRequestedEntryName() throws {
+        let replace = try preview(entryExists: true)
+
+        XCTAssertEqual(replace.changeKind, .replace(entryName: "mcpproxy"))
+    }
+
+    func testMalformedConfigBlocksTheConnectControl() throws {
+        let blocked = try preview(accessState: "malformed")
+
+        XCTAssertEqual(blocked.changeKind, .blockedByAccess(.malformed))
+        XCTAssertFalse(blocked.allowsConnect)
+        XCTAssertNil(blocked.safetyNetStatement)
+    }
+
+    func testDeniedConfigBlocksTheConnectControl() throws {
+        let blocked = try preview(accessState: "denied")
+
+        XCTAssertEqual(blocked.changeKind, .blockedByAccess(.denied))
+        XCTAssertFalse(blocked.allowsConnect)
+        XCTAssertNil(blocked.safetyNetStatement)
+    }
+
+    // MARK: - Credential notice (FR-004)
+
+    func testCredentialNoticeAppearsOnlyWhenTheEntryEmbedsTheKey() throws {
+        let withKey = try preview(accessState: "absent", containsAPIKey: true)
+        let withoutKey = try preview(accessState: "absent", containsAPIKey: false)
+
+        XCTAssertNotNil(withKey.credentialNotice)
+        XCTAssertEqual(withKey.credentialNotice?.isEmpty, false)
+        XCTAssertNil(withoutKey.credentialNotice)
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxyTests/ConnectStubURLProtocol.swift b/native/macos/MCPProxy/MCPProxyTests/ConnectStubURLProtocol.swift
new file mode 100644
index 00000000..c5a50666
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/ConnectStubURLProtocol.swift
@@ -0,0 +1,110 @@
+// ConnectStubURLProtocol.swift
+// MCPProxyTests
+//
+// A URLProtocol that records the full shape of every request — URL, method,
+// headers and body — and replays a canned JSON body. The Connect form's API
+// surface is mutating, so the tests must assert what goes OUT, not only what
+// comes back.
+
+import Foundation
+@testable import MCPProxy
+
+final class ConnectStubURLProtocol: URLProtocol {
+
+    struct Recorded {
+        let url: String
+        let method: String
+        let headers: [String: String]
+        let body: Data?
+
+        /// The request body decoded as a JSON object, for field-level asserts.
+        var json: [String: Any] {
+            guard let body,
+                  let object = try? JSONSerialization.jsonObject(with: body) as? [String: Any]
+            else { return [:] }
+            return object
+        }
+    }
+
+    /// Requests seen by the stub, in order.
+    static var recorded: [Recorded] = []
+
+    /// Body replayed for every request.
+    static var responseBody = Data()
+
+    /// Status code replayed for every request.
+    static var statusCode = 200
+
+    static func reset() {
+        recorded = []
+        responseBody = Data()
+        statusCode = 200
+    }
+
+    /// An APIClient whose traffic is intercepted by this stub.
+    ///
+    /// `transportKind` is explicit because the mutating calls refuse to ride
+    /// anything but the private socket, and a stubbed session has no transport
+    /// identity of its own.
+    static func makeClient(transportKind: APIClient.TransportKind = .unixSocket) -> APIClient {
+        let config = URLSessionConfiguration.ephemeral
+        config.protocolClasses = [ConnectStubURLProtocol.self]
+        return APIClient(
+            session: URLSession(configuration: config),
+            baseURL: "http://127.0.0.1:8080",
+            apiKey: nil,
+            transportKind: transportKind
+        )
+    }
+
+    /// Wrap a payload in the standard `{"success":true,"data":…}` envelope.
+    static func envelope(_ json: String) -> Data {
+        Data("{\"success\":true,\"data\":\(json)}".utf8)
+    }
+
+    override class func canInit(with request: URLRequest) -> Bool { true }
+
+    override class func canonicalRequest(for request: URLRequest) -> URLRequest { request }
+
+    override func startLoading() {
+        ConnectStubURLProtocol.recorded.append(
+            Recorded(
+                url: request.url?.absoluteString ?? "",
+                method: request.httpMethod ?? "",
+                headers: request.allHTTPHeaderFields ?? [:],
+                body: Self.body(of: request)
+            )
+        )
+        let response = HTTPURLResponse(
+            url: request.url ?? URL(string: "http://127.0.0.1:8080")!,
+            statusCode: ConnectStubURLProtocol.statusCode,
+            httpVersion: "HTTP/1.1",
+            headerFields: ["Content-Type": "application/json"]
+        )!
+        client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
+        client?.urlProtocol(self, didLoad: ConnectStubURLProtocol.responseBody)
+        client?.urlProtocolDidFinishLoading(self)
+    }
+
+    override func stopLoading() {}
+
+    /// URLSession converts `httpBody` into `httpBodyStream` before a custom
+    /// protocol sees the request, so reading only `httpBody` records nil for
+    /// every POST — exactly the requests these tests exist to inspect.
+    private static func body(of request: URLRequest) -> Data? {
+        if let body = request.httpBody { return body }
+        guard let stream = request.httpBodyStream else { return nil }
+        stream.open()
+        defer { stream.close() }
+        var data = Data()
+        let size = 4096
+        let buffer = UnsafeMutablePointer<UInt8>.allocate(capacity: size)
+        defer { buffer.deallocate() }
+        while stream.hasBytesAvailable {
+            let read = stream.read(buffer, maxLength: size)
+            if read <= 0 { break }
+            data.append(buffer, count: read)
+        }
+        return data.isEmpty ? nil : data
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxyTests/DashboardRoutingTests.swift b/native/macos/MCPProxy/MCPProxyTests/DashboardRoutingTests.swift
new file mode 100644
index 00000000..3ad9a4a9
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/DashboardRoutingTests.swift
@@ -0,0 +1,82 @@
+import XCTest
+@testable import MCPProxy
+
+/// FR-012 (spec 091 T024): the dashboard's connect control must go through the
+/// shared Connect Client presentation path, and the legacy preview-less sheet —
+/// which wrote a client config straight from a button, with no preview and no
+/// backup disclosure — must be gone.
+@MainActor
+final class DashboardRoutingTests: XCTestCase {
+
+    /// The dashboard now opens the form instead of connecting: activating its
+    /// control posts exactly the route the tray menu item posts.
+    func testTheDashboardConnectControlPostsTheSharedPresentationRoute() {
+        let received = expectation(description: "presentation route posted")
+        let token = NotificationCenter.default.addObserver(
+            forName: ConnectClientPresentation.route, object: nil, queue: .main
+        ) { _ in received.fulfill() }
+        defer { NotificationCenter.default.removeObserver(token) }
+
+        DashboardConnectControl.activate()
+
+        wait(for: [received], timeout: 1)
+    }
+
+    /// The control is a doorway, not an action: its title says so, so nobody
+    /// expects a write from pressing it.
+    func testTheDashboardControlIsLabelledAsOpeningTheForm() {
+        XCTAssertEqual(DashboardConnectControl.title, "Connect Clients…")
+        XCTAssertFalse(DashboardConnectControl.title.isEmpty)
+    }
+
+    /// The preview-less flow is deleted, not merely bypassed: a dormant sheet
+    /// would be one `showConnectClients = true` away from writing configs again.
+    func testTheLegacyPreviewLessConnectFlowIsGone() throws {
+        let source = try dashboardSource()
+
+        for forbidden in [
+            "ConnectClientsSheet",      // the sheet itself
+            "showConnectClients",       // its presentation flag
+            "connectToClient(",         // the preview-less write
+            "disconnectFromClient("     // and its unconfirmed counterpart
+        ] {
+            XCTAssertFalse(source.contains(forbidden),
+                           "DashboardView.swift still references \(forbidden)")
+        }
+        XCTAssertTrue(source.contains("DashboardConnectControl"),
+                      "the dashboard must route through the shared presentation path")
+    }
+
+    /// The legacy API methods went with it — a preview-less connect is not a
+    /// capability this app keeps lying around.
+    func testTheLegacyPreviewLessAPIMethodsAreGone() throws {
+        let source = try apiClientSource()
+
+        XCTAssertFalse(source.contains("func connectToClient("),
+                       "APIClient still exposes the preview-less connect")
+        XCTAssertFalse(source.contains("func disconnectFromClient("),
+                       "APIClient still exposes the unconfirmed disconnect")
+    }
+
+    // MARK: - Helpers
+
+    private func dashboardSource() throws -> String {
+        try source(at: "MCPProxy/Views/DashboardView.swift")
+    }
+
+    private func apiClientSource() throws -> String {
+        try source(at: "MCPProxy/API/APIClient.swift")
+    }
+
+    /// Reads a source file from the package the tests were compiled from, so the
+    /// guard travels with the checkout rather than with a build product.
+    private func source(at relativePath: String) throws -> String {
+        let packageRoot = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()   // MCPProxyTests
+            .deletingLastPathComponent()   // package root
+        let url = packageRoot.appendingPathComponent(relativePath)
+        XCTAssertTrue(FileManager.default.fileExists(atPath: url.path),
+                      "missing source file at \(url.path)")
+        return try String(contentsOf: url, encoding: .utf8)
+    }
+}
diff --git a/native/macos/MCPProxy/MCPProxyTests/Support/FakeConnectSource.swift b/native/macos/MCPProxy/MCPProxyTests/Support/FakeConnectSource.swift
new file mode 100644
index 00000000..34332ab8
--- /dev/null
+++ b/native/macos/MCPProxy/MCPProxyTests/Support/FakeConnectSource.swift
@@ -0,0 +1,188 @@
+// FakeConnectSource.swift
+// MCPProxyTests/Support
+//
+// The Connect form's data source, scripted. Every response is synthesized here,
+// so the whole ConnectClientModel suite runs without a core, a socket, or a
+// client config file anywhere on disk.
+
+import Foundation
+@testable import MCPProxy
+
+/// A scripted `ConnectClientDataSource`.
+///
+/// Each queue is consumed front-to-back; when it runs dry the last element
+/// repeats, so a test only scripts the transitions it cares about.
+final class FakeConnectSource: ConnectClientDataSource, @unchecked Sendable {
+
+    // MARK: Scripted responses
+
+    var transportKind: APIClient.TransportKind = .unixSocket
+    var clientsResults: [Result<[APIClient.ClientStatus], Error>] = [.success([])]
+    var detailResults: [Result<APIClient.ClientStatus, Error>] = []
+    var previewResults: [Result<ConnectPreviewModel, Error>] = []
+    var connectResults: [Result<APIClient.ConnectResult, Error>] = []
+    var undoResults: [Result<APIClient.ConnectResult, Error>] = []
+    var disconnectResults: [Result<APIClient.ConnectResult, Error>] = []
+
+    /// Run on the main actor while a connect is in flight — the only way to
+    /// observe the model's in-flight state from outside without a real clock.
+    var whileConnectInFlight: (@MainActor @Sendable () -> Void)?
+
+    /// Awaited while a connect is in flight, so a test can interleave a whole
+    /// user action (selecting another client) with a suspended write.
+    var duringConnect: (@MainActor @Sendable () async -> Void)?
+
+    /// Awaited while a preview is in flight, receiving the 1-based call index —
+    /// the seam for "the user acted while the post-action refresh was running".
+    var duringPreview: (@MainActor @Sendable (Int) async -> Void)?
+
+    /// Awaited while an undo is in flight; a test releases it to let the undo
+    /// settle, so the window where the undo is still pending is observable.
+    var duringUndo: (@MainActor @Sendable () async -> Void)?
+
+    // MARK: Recorded calls
+
+    struct ConnectCall: Equatable {
+        let clientId: String
+        let serverName: String
+        let force: Bool
+        let preconditionToken: String?
+    }
+
+    private(set) var clientsCallCount = 0
+    private(set) var detailCalls: [String] = []
+    private(set) var previewCalls: [(clientId: String, serverName: String)] = []
+    private(set) var connectCalls: [ConnectCall] = []
+    private(set) var undoCalls: [(clientId: String, backupName: String?)] = []
+    private(set) var disconnectCalls: [String] = []
+
+    // MARK: ConnectClientDataSource
+
+    func connectClients() async throws -> [APIClient.ClientStatus] {
+        clientsCallCount += 1
+        return try next(&clientsResults, fallback: [])
+    }
+
+    func clientDetail(_ clientId: String) async throws -> APIClient.ClientStatus {
+        detailCalls.append(clientId)
+        return try next(&detailResults, fallback: FakeConnectSource.client(id: clientId))
+    }
+
+    func connectPreview(_ clientId: String, serverName: String) async throws -> ConnectPreviewModel {
+        previewCalls.append((clientId, serverName))
+        if let hook = duringPreview { await hook(previewCalls.count) }
+        return try next(&previewResults, fallback: FakeConnectSource.preview(serverName: serverName))
+    }
+
+    func connect(
+        _ clientId: String,
+        serverName: String,
+        force: Bool,
+        preconditionToken: String?
+    ) async throws -> APIClient.ConnectResult {
+        connectCalls.append(
+            ConnectCall(clientId: clientId, serverName: serverName,
+                        force: force, preconditionToken: preconditionToken))
+        if let hook = whileConnectInFlight {
+            await MainActor.run { hook() }
+        }
+        if let hook = duringConnect { await hook() }
+        return try next(&connectResults, fallback: FakeConnectSource.result(action: "created"))
+    }
+
+    func undoConnect(
+        _ clientId: String,
+        serverName: String,
+        backupName: String?
+    ) async throws -> APIClient.ConnectResult {
+        undoCalls.append((clientId, backupName))
+        if let hook = duringUndo { await hook() }
+        return try next(&undoResults, fallback: FakeConnectSource.result(action: "restored"))
+    }
+
+    func disconnect(_ clientId: String, serverName: String) async throws -> APIClient.ConnectResult {
+        disconnectCalls.append(clientId)
+        return try next(&disconnectResults, fallback: FakeConnectSource.result(action: "removed"))
+    }
+
+    private func next<T>(_ queue: inout [Result<T, Error>], fallback: @autoclosure () -> T) throws -> T {
+        guard !queue.isEmpty else { return fallback() }
+        let result = queue.count == 1 ? queue[0] : queue.removeFirst()
+        return try result.get()
+    }
+
+    // MARK: Fixtures
+
+    static func client(
+        id: String,
+        name: String? = nil,
+        exists: Bool = true,
+        connected: Bool = false,
+        supported: Bool = true,
+        reason: String? = nil,
+        accessState: ConnectAccessState? = nil,
+        remediation: String? = nil,
+        serverName: String? = nil
+    ) -> APIClient.ClientStatus {
+        let json: [String: Any?] = [
+            "id": id,
+            "name": name ?? id.capitalized,
+            "config_path": "/Users/x/.\(id)/config.json",
+            "exists": exists,
+            "connected": connected,
+            "supported": supported,
+            "reason": reason,
+            "icon": id,
+            "server_name": serverName,
+            "access_state": accessState?.rawValue,
+            "remediation": remediation
+        ]
+        let data = try! JSONSerialization.data(
+            withJSONObject: json.compactMapValues { $0 })
+        return try! JSONDecoder().decode(APIClient.ClientStatus.self, from: data)
+    }
+
+    static func preview(
+        client: String = "claude-code",
+        serverName: String = "mcpproxy",
+        entryExists: Bool = false,
+        accessState: ConnectAccessState = .accessible,
+        containsAPIKey: Bool = false,
+        summary: ConnectEntrySummary? = nil,
+        token: String? = "tok",
+        refusal: String? = nil,
+        coreSupportsTokens: Bool = true
+    ) -> ConnectPreviewModel {
+        ConnectPreviewModel(
+            client: client,
+            configPath: "/Users/x/.\(client)/config.json",
+            serverName: serverName,
+            entryText: "\"\(serverName)\": { \"type\": \"http\" }",
+            entryExists: entryExists,
+            containsAPIKey: containsAPIKey,
+            accessState: accessState,
+            existingEntrySummary: summary,
+            preconditionToken: token,
+            connectRefusal: refusal,
+            coreSupportsPreconditionTokens: coreSupportsTokens
+        )
+    }
+
+    static func result(
+        action: String,
+        backupPath: String? = nil,
+        message: String = "done"
+    ) -> APIClient.ConnectResult {
+        var json: [String: Any] = [
+            "success": true,
+            "client": "claude-code",
+            "config_path": "/Users/x/.claude-code/config.json",
+            "server_name": "mcpproxy",
+            "action": action,
+            "message": message
+        ]
+        if let backupPath { json["backup_path"] = backupPath }
+        let data = try! JSONSerialization.data(withJSONObject: json)
+        return try! JSONDecoder().decode(APIClient.ConnectResult.self, from: data)
+    }
+}
diff --git a/oas/docs.go b/oas/docs.go
index ceaada3e..f67b0654 100644
--- a/oas/docs.go
+++ b/oas/docs.go
@@ -6,10 +6,10 @@ import "github.com/swaggo/swag/v2"
 
 const docTemplate = `{
     "schemes": {{ marshal .Schemes }},
-    "components": {"schemas":{"config.Config":{"properties":{"activity_cleanup_interval_min":{"description":"Background cleanup interval in minutes (default: 60)","type":"integer"},"activity_max_records":{"description":"Max records before pruning (default: 100000)","type":"integer"},"activity_max_response_size":{"description":"Response truncation limit in bytes (default: 65536)","type":"integer"},"activity_max_size_mb":{"description":"Max total activity-log size in MB before pruning oldest (default: 256, 0=disabled)","type":"integer"},"activity_retention_days":{"description":"Activity logging settings (RFC-003)","type":"integer"},"allow_private_registry_fetch":{"description":"AllowPrivateRegistryFetch opts out of the registry SSRF guard (MCP-1076,\nCWE-918). By default (false) registry fetches refuse any host that is — or\nresolves to — a non-routable address (loopback, RFC1918/CGNAT private,\nlink-local incl. the 169.254.169.254 cloud-metadata endpoint), so a\nmalicious or typo'd registry source cannot turn the daemon into a\nrequest-forgery vector against internal services.\n\nThis opt-out is BLANKET (all-or-nothing): setting it true disables the\nguard for EVERY non-routable range at once — loopback, RFC1918/CGNAT\nprivate, link-local AND the 169.254.169.254 cloud-metadata endpoint. There\nis no way to allow only loopback; enabling it for a localhost dev registry\nalso re-opens the cloud-metadata SSRF vector. Set true ONLY when you\nintentionally run a trusted registry mirror on an internal/private address,\nideally on a host with no cloud-metadata exposure. The change takes effect\nonly on daemon (re)start or config reload.","type":"boolean"},"allow_server_add":{"type":"boolean"},"allow_server_remove":{"type":"boolean"},"api_key":{"description":"Security settings","type":"string"},"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"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned stdio upstream servers (MCP-2769). OFF by\ndefault: proxy URLs commonly embed credentials (http://user:pass@proxy), so\nforwarding them to every upstream is a credential-leak risk. When enabled,\nvalues are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"health_check_interval":{"description":"Discovery \u0026 health-check cadence (spec 074, #608). Both are *Duration\ntri-state pointers: nil = inherit the built-in default; a pointer to 0s =\nthe loop is disabled; a positive value = that interval. Defaults live only\nin the resolvers (ResolveHealthCheckInterval / ResolveToolDiscoveryInterval)\nso an unset key behaves exactly as before this feature (SC-005). Validated\nin Validate(): health-check ∈ {0} ∪ [5s,1h]; tool-discovery ∈ {0} ∪ [30s,24h].","type":"string"},"init_timeout":{"description":"InitTimeout is the global default deadline for an upstream's MCP\n` + "`" + `initialize` + "`" + ` handshake (MCP-3322 / GH #760). *Duration tri-state: nil =\ninherit the built-in 30s default; a positive value = that deadline. A\nper-server InitTimeout overrides this. Resolved by ResolveInitTimeout;\nvalidated to {0} ∪ [1s, 30m] in Validate(). Servers doing legitimate\nfirst-run warmup (cache/index build) before answering ` + "`" + `initialize` + "`" + ` can\nraise this so they are not killed mid-startup.","type":"string"},"instructions":{"description":"Instructions text returned in the MCP initialize response to guide AI agents.\nWhen empty, a built-in default is used that explains retrieve_tools workflow.","type":"string"},"intent_declaration":{"$ref":"#/components/schemas/config.IntentDeclarationConfig"},"listen":{"type":"string"},"logging":{"$ref":"#/components/schemas/config.LogConfig"},"max_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"},"observability":{"$ref":"#/components/schemas/config.ObservabilityConfig"},"output_sanitisation":{"$ref":"#/components/schemas/config.OutputSanitisationConfig"},"output_validation":{"$ref":"#/components/schemas/config.OutputValidationConfig"},"profiles":{"description":"Profiles are optional named, server-scoped views exposed at /mcp/p/\u003cname\u003e\n(Spec 057). Absent/empty is fully supported — /mcp is unchanged and configs\nwithout this key serialize byte-identically (SC-004).","items":{"$ref":"#/components/schemas/config.ProfileConfig"},"type":"array","uniqueItems":false},"quarantine_enabled":{"description":"QuarantineEnabled controls whether quarantine is active. It gates two\nthings together:\n  1. Server-level auto-quarantine for newly added servers (issue #370).\n     When true, servers added via the upstream_servers MCP tool or the\n     REST API default to quarantined=true; when false, they default to\n     quarantined=false. Explicit per-request values always win.\n  2. Tool-level quarantine (Spec 032): per-tool SHA-256 approval of\n     tool descriptions/schemas.\nWhen nil (default), quarantine is enabled (secure by default). Set to\nexplicit false to opt out of both. Per-server SkipQuarantine still\napplies for the tool-level check on individual servers.","type":"boolean"},"read_only_mode":{"type":"boolean"},"registries":{"description":"Registries configuration for MCP server discovery","items":{"$ref":"#/components/schemas/config.RegistryEntry"},"type":"array","uniqueItems":false},"registries_locked":{"description":"RegistriesLocked is an enterprise stub knob (MCP-866): when true, runtime\nadditions of custom registries (e.g. ` + "`" + `registry add-source` + "`" + `, the REST/MCP\nadd-source surface) are rejected so an administrator can pin the discovery\nsources. Built-in defaults are unaffected. Documented but otherwise inert\nbeyond the add-source rejection.","type":"boolean"},"require_mcp_auth":{"description":"Require authentication on /mcp endpoint (default: false)","type":"boolean"},"reveal_secret_headers":{"description":"RevealSecretHeaders, when true, disables the redaction of the\nsecret-bearing server fields — sensitive header values (Authorization,\nX-API-Key, Cookie, …), env-var secrets, and URL query credentials — in\nresponses from the ` + "`" + `upstream_servers` + "`" + ` MCP tool, the ` + "`" + `/api/v1/servers` + "`" + `\nREST API, and the SSE event stream. It also lets URL secrets echoed\ninto last_error / health.detail through unscrubbed.\n\nDefault false — sensitive values are surfaced masked as\n` + "`" + `••••\u003clast2\u003e (\u003cN\u003e chars)` + "`" + ` (error strings use ` + "`" + `***REDACTED***` + "`" + `) so an\nMCP agent cannot read Bearer tokens / API keys / URL secrets out of\nanother upstream's config (PR #425, issue #872). ${env:…}/${keyring:…}\nreferences are labels, not secrets, and pass through unchanged.\n\nThe Web UI / macOS tray edit forms work without seeing the real\nvalues: PATCH /api/v1/servers/{id} deep-merges (omitted keys are\npreserved, see ` + "`" + `headers_remove` + "`" + ` / ` + "`" + `env_remove` + "`" + ` for explicit\ndeletes), so clients compute a diff and only send the keys that\nactually changed. Redacted-but-unchanged values never round-trip\n— the backend keeps the real string. Set this to true if a\ndownstream tool genuinely needs raw values in the response.","type":"boolean"},"routing_mode":{"description":"Routing mode (Spec 031): how MCP tools are exposed to clients\nValid values: \"retrieve_tools\" (default), \"direct\", \"code_execution\"","type":"string"},"security":{"$ref":"#/components/schemas/config.SecurityConfig"},"sensitive_data_detection":{"$ref":"#/components/schemas/config.SensitiveDataDetectionConfig"},"telemetry":{"$ref":"#/components/schemas/config.TelemetryConfig"},"tls":{"$ref":"#/components/schemas/config.TLSConfig"},"tokenizer":{"$ref":"#/components/schemas/config.TokenizerConfig"},"tool_discovery_interval":{"type":"string"},"tool_response_limit":{"type":"integer"},"tool_response_mode":{"description":"Tool response mode (Spec 085): how retrieve_tools serializes results.\nValid values: \"\" (= full), \"full\" (default: today's schema-bearing\nentries), \"compact\" (signature + first-sentence entries). Orthogonal to\nrouting_mode — routing_mode selects the tool SURFACE, this selects the\nSERIALIZATION within the retrieve_tools surface. Serialization-only: it\nnever affects the query, ranking, or result set. Hot-reloadable.","type":"string"},"tool_response_session_risk_warning":{"description":"ToolResponseSessionRiskWarning controls whether the prose ` + "`" + `warning` + "`" + ` field\nis included in the ` + "`" + `session_risk` + "`" + ` object returned by ` + "`" + `retrieve_tools` + "`" + `.\nThe structured fields (level, lethal_trifecta, has_open_world_tools, etc.)\nare always included. Default: false (quiet for LLM clients) — see issue #406.\nMost tools lack annotations, so the MCP-spec defaults treat them as fully\npermissive across all three risk axes, which makes the prose warning fire\non almost every call and wastes tokens.","type":"boolean"},"tools_limit":{"type":"integer"},"toon_min_savings_pct":{"description":"ToonMinSavingsPct is the minimum byte-savings percentage (validated\n1-90; 0/unset → 15) the complete TOON emission (marker + hint + body)\nmust achieve over the exact passthrough emission for adaptive mode to\nencode a block. Byte savings approximate token savings for the tabular\npayload class; the spec-083 profiler reports true token deltas.\nGlobal-only (no per-server override, FR-001).","type":"integer"},"toon_output":{"description":"ToonOutput selects the TOON encoding mode for call_tool_* result text\nblocks (spec 084): \"off\" (default — responses byte-identical to\npre-feature behavior), \"adaptive\" (encode only tabular-uniform payloads\nthat beat compact JSON by ToonMinSavingsPct), or \"always\"\n(benchmark/debug only — encodes every JSON-parseable block and can\nINCREASE token cost). Per-server override: ServerConfig.ToonOutput.\nResolved by ResolveToonOutput; hot-reloadable.","type":"string"},"top_k":{"description":"Deprecated: TopK is superseded by ToolsLimit and has no runtime effect. Kept for backward compatibility.","type":"integer"},"tray_endpoint":{"description":"Tray endpoint override (unix:// or npipe://)","type":"string"},"trusted_hosts":{"description":"TrustedHosts lists non-loopback Host header values accepted on loopback\nlisteners (GH #898). DNS-rebinding protection rejects requests whose Host\nheader is not a loopback address when mcpproxy listens on loopback; a\nreverse proxy (nginx → 127.0.0.1) forwarding the public domain in Host\ntrips it. Entries are hostnames, case-insensitive; an entry without a\nport matches any port, with a port it must match exactly; a leading dot\n(\".example.com\") is a subdomain wildcard. The single entry \"*\" disables\nHost and Origin validation entirely. The same list also validates the\nOrigin header when present (MCP spec DNS-rebinding defense). Empty\n(default) keeps full protection. Env override: MCPPROXY_TRUSTED_HOSTS\n(comma-separated).","items":{"type":"string"},"type":"array","uniqueItems":false},"update_check":{"$ref":"#/components/schemas/config.UpdateCheckConfig"}},"type":"object"},"config.CustomPattern":{"properties":{"category":{"description":"Category (defaults to \"custom\")","type":"string"},"keywords":{"description":"Keywords to match (mutually exclusive with Regex)","items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"description":"Unique identifier for this pattern","type":"string"},"regex":{"description":"Regex pattern (mutually exclusive with Keywords)","type":"string"},"severity":{"description":"Risk level: critical, high, medium, low","type":"string"}},"type":"object"},"config.DeepScanConfig":{"description":"DeepScan is the opt-in \"deep scan\" layer (Spec 077 US3). It subsumes the\ndeprecated top-level scanner_fetch_package_source / scanner_disable_no_new_privileges\nkeys (migrated on load) and gates the heavy Docker-based scanners + source\nextraction. Disabled by default (FR-006): only the deterministic in-process\nbaseline scanner runs. A deep-scan failure NEVER changes the baseline verdict\n(FR-007/FR-008).","properties":{"disable_no_new_privileges":{"description":"DisableNoNewPrivileges, when true, omits the ` + "`" + `--security-opt\nno-new-privileges` + "`" + ` flag from scanner container runs (snap-docker/AppArmor\nescape hatch). Absorbs the deprecated top-level\nscanner_disable_no_new_privileges. Default false.","type":"boolean"},"enabled":{"description":"Enabled is the master opt-in for the heavy layer (FR-006). Default false.","type":"boolean"},"fetch_package_source":{"description":"FetchPackageSource controls whether the scanner fetches the PUBLISHED\nsource of package-runner servers (npx/uvx) — without executing it — when\nno local source is available. Absorbs the deprecated top-level\nscanner_fetch_package_source. Default (nil) is ENABLED within deep scan.","type":"boolean"},"scanners":{"description":"Scanners optionally restricts which deep scanners may run under the\numbrella (by scanner id). Empty ⇒ all enabled deep scanners are eligible.","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.DockerIsolationConfig":{"description":"Docker isolation settings","properties":{"cpu_limit":{"description":"CPU limit for containers","type":"string"},"default_images":{"additionalProperties":{"type":"string"},"description":"Map of runtime type to Docker image","type":"object"},"enable_cache_volume":{"description":"Mount shared cache volumes for faster restarts (default: true)","type":"boolean"},"enabled":{"description":"Global enable/disable for Docker isolation (legacy; superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments","items":{"type":"string"},"type":"array","uniqueItems":false},"log_driver":{"description":"Docker log driver (default: json-file)","type":"string"},"log_max_files":{"description":"Maximum number of log files (default: 3)","type":"string"},"log_max_size":{"description":"Maximum size of log files (default: 100m)","type":"string"},"memory_limit":{"description":"Memory limit for containers","type":"string"},"mode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"network_mode":{"description":"Docker network mode (default: bridge)","type":"string"},"registry":{"description":"Custom registry (defaults to docker.io)","type":"string"},"timeout":{"description":"Container startup timeout","type":"string"}},"type":"object"},"config.DockerRecoveryConfig":{"description":"Docker recovery settings","properties":{"enabled":{"description":"Enable Docker recovery monitoring (default: true)","type":"boolean"},"max_retries":{"description":"Maximum retry attempts (0 = unlimited)","type":"integer"},"notify_on_failure":{"description":"Show notification on recovery failure (default: true)","type":"boolean"},"notify_on_retry":{"description":"Show notification on each retry (default: false)","type":"boolean"},"notify_on_start":{"description":"Show notification when recovery starts (default: true)","type":"boolean"},"notify_on_success":{"description":"Show notification on successful recovery (default: true)","type":"boolean"},"persistent_state":{"description":"Save recovery state across restarts (default: true)","type":"boolean"}},"type":"object"},"config.FeatureFlags":{"description":"Deprecated: Features flags are unused and have no runtime effect. Kept for backward compatibility.","properties":{"enable_async_storage":{"type":"boolean"},"enable_caching":{"type":"boolean"},"enable_contract_tests":{"type":"boolean"},"enable_debug_logging":{"description":"Development features","type":"boolean"},"enable_docker_isolation":{"type":"boolean"},"enable_event_bus":{"type":"boolean"},"enable_health_checks":{"type":"boolean"},"enable_metrics":{"type":"boolean"},"enable_oauth":{"description":"Security features","type":"boolean"},"enable_observability":{"description":"Observability features","type":"boolean"},"enable_quarantine":{"type":"boolean"},"enable_runtime":{"description":"Runtime features","type":"boolean"},"enable_search":{"description":"Storage features","type":"boolean"},"enable_sse":{"type":"boolean"},"enable_tracing":{"type":"boolean"},"enable_tray":{"type":"boolean"},"enable_web_ui":{"description":"UI features","type":"boolean"}},"type":"object"},"config.IntentDeclarationConfig":{"description":"Intent declaration settings (Spec 018)","properties":{"strict_server_validation":{"description":"StrictServerValidation controls whether server annotation mismatches\ncause rejection (true) or just warnings (false).\nDefault: true (reject mismatches)","type":"boolean"}},"type":"object"},"config.IsolationConfig":{"description":"Per-server isolation settings","properties":{"enabled":{"description":"Enable Docker isolation for this server (nil = inherit global; legacy, superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments for this server","items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"description":"Custom Docker image (overrides default)","type":"string"},"log_driver":{"description":"Docker log driver override for this server","type":"string"},"log_max_files":{"description":"Maximum number of log files override","type":"string"},"log_max_size":{"description":"Maximum size of log files override","type":"string"},"mode":{"$ref":"#/components/schemas/config.IsolationMode"},"network_mode":{"description":"Custom network mode for this server","type":"string"},"working_dir":{"description":"Custom working directory in container","type":"string"}},"type":"object"},"config.IsolationMode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"config.LogConfig":{"description":"Logging configuration","properties":{"compress":{"type":"boolean"},"enable_console":{"type":"boolean"},"enable_file":{"type":"boolean"},"filename":{"type":"string"},"json_format":{"type":"boolean"},"level":{"type":"string"},"log_dir":{"description":"Custom log directory","type":"string"},"max_age":{"description":"days","type":"integer"},"max_backups":{"description":"number of backup files","type":"integer"},"max_size":{"description":"MB","type":"integer"}},"type":"object"},"config.MetricsExporterConfig":{"description":"Metrics gates the Prometheus /metrics scrape endpoint (MCP-32). Disabled\nby default — operators opt in for k8s/enterprise deployments.","properties":{"enabled":{"description":"Enabled exposes /metrics on the existing HTTP listener when true.","type":"boolean"}},"type":"object"},"config.OAuthConfig":{"description":"OAuth configuration (keep even when empty to signal OAuth requirement)","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"description":"Additional OAuth parameters (e.g., RFC 8707 resource)","type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_uri":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ObservabilityConfig":{"description":"Observability settings (Spec 069): usage aggregate cache/persistence cadence.","properties":{"metrics":{"$ref":"#/components/schemas/config.MetricsExporterConfig"},"tracing":{"$ref":"#/components/schemas/config.TracingExporterConfig"},"usage_cache_ttl":{"description":"UsageCacheTTL bounds the freshness of the usage endpoint's read cache for\nwide windows (FR-005). Default 5s.","type":"string"},"usage_persist_interval":{"description":"UsagePersistInterval is how often the actor-owned usage aggregate snapshot\nis flushed to storage. Default 30s.","type":"string"}},"type":"object"},"config.OutputSanitisationConfig":{"description":"Output sanitisation settings (Spec 054 Track B)","properties":{"max_redactions":{"description":"cap on redactions per response; default 100","type":"integer"},"response_action":{"description":"\"spotlight\" | \"redact\" | \"block\"; default \"spotlight\"","type":"string"},"spotlight_untrusted":{"description":"wrap untrusted output in spotlight markers; default true","type":"boolean"},"strip_classes":{"description":"classes to strip: ansi/c0c1/bidi/zero_width","items":{"type":"string"},"type":"array","uniqueItems":false},"strip_control_chars":{"description":"strip control-character classes; default false","type":"boolean"}},"type":"object"},"config.OutputValidationConfig":{"description":"Output-schema validation settings (Spec 056)","properties":{"max_bytes":{"description":"structured payload byte cap; default 5\u003c\u003c20","type":"integer"},"max_depth":{"description":"nesting depth cap; default 64","type":"integer"},"missing_structured_content":{"description":"\"allow\" | \"block\"; default \"allow\"","type":"string"},"mode":{"description":"\"off\" | \"warn\" | \"strict\"; default \"warn\"","type":"string"}},"type":"object"},"config.ProfileConfig":{"properties":{"name":{"description":"URL slug, validated","type":"string"},"servers":{"description":"references to mcpServers[].name","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.RegistryEntry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag for this registry (MCP-866):\nRegistryProvenanceOfficial for built-in defaults, RegistryProvenanceCustom\nfor user-added registries. It is authoritatively (re)computed by the\nregistries merge from whether the ID is a shipped default — a user cannot\nclaim \"official\" by writing it into their config.","type":"string"},"requires_key":{"description":"RequiresKey marks a registry that needs an API key to be queried. When\ntrue and no key is configured, the registry is skipped/marked unavailable\nrather than failing the whole search (FR-008).","type":"boolean"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"type":"string"}},"type":"object"},"config.SecurityConfig":{"description":"Security scanner settings (Spec 039)","properties":{"deep_scan":{"$ref":"#/components/schemas/config.DeepScanConfig"},"integrity_check_interval":{"type":"string"},"integrity_check_on_restart":{"type":"boolean"},"runtime_read_only":{"type":"boolean"},"runtime_tmpfs_size":{"type":"string"},"scan_timeout_default":{"type":"string"},"scanner_disable_no_new_privileges":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.DisableNoNewPrivileges\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.IsDisableNoNewPrivileges. Cleared after migration.\n\nScannerDisableNoNewPrivileges, when true, omits the\n` + "`" + `--security-opt no-new-privileges` + "`" + ` flag from scanner container runs.\n\nBackground: snap-installed Docker on Ubuntu confines dockerd under the\n` + "`" + `snap.docker.dockerd` + "`" + ` AppArmor profile. When runc tries to transition\nthe container into the inner ` + "`" + `docker-default` + "`" + ` profile to exec the\nentrypoint, AppArmor refuses the transition because NO_NEW_PRIVS\nforbids privilege/profile changes on exec — the result is EPERM\n(\"operation not permitted\") and every scanner fails immediately.\n\nSet this to true ONLY on hosts hitting that incompatibility. Scanner\ncontainers still run with read-only rootfs, tmpfs /tmp, no-network by\ndefault, and read-only source mounts, so the marginal isolation loss\nis small. The preferred fix remains replacing snap docker with a\ndistro-packaged docker.","type":"boolean"},"scanner_fetch_package_source":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.FetchPackageSource\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.EffectiveFetchPackageSource. Cleared after migration.\n\nScannerFetchPackageSource controls whether the scanner fetches the\nPUBLISHED source of package-runner servers (npx/uvx) — without executing\nit — when no local source is available (no Docker container, no local\npackage cache, no working_dir). This is the primary quarantine/scan\ntarget: a quarantined-on-add server is never run locally, so without this\nthe scan degrades to tool-definitions-only (no real source-level\nanalysis). See MCP-2206.\n\nFetching uses ` + "`" + `npm pack --ignore-scripts` + "`" + ` (npm) and ` + "`" + `uv pip download` + "`" + ` /\n` + "`" + `pip download` + "`" + ` with ` + "`" + `--only-binary=:all:` + "`" + ` (Python), which only download +\nunpack archives and NEVER run install, build, or setup.py — a scanner must\nnot execute the untrusted code it is scanning. The Python\n` + "`" + `--only-binary=:all:` + "`" + ` flag is required because downloading an sdist would\ninvoke its build backend (setup.py); packages with no wheel fall back to\ntool-definitions-only instead. Extraction is hardened against path\ntraversal and decompression bombs.\n\nDefault (nil) is ENABLED. Set to false on air-gapped deployments to\nforbid the scanner's network egress; such servers then fall back to the\ntool-definitions-only scan with no regression.","type":"boolean"},"scanner_registry_url":{"type":"string"}},"type":"object"},"config.SensitiveDataDetectionConfig":{"description":"Sensitive data detection settings (Spec 026)","properties":{"categories":{"additionalProperties":{"type":"boolean"},"description":"Enable/disable specific detection categories","type":"object"},"custom_patterns":{"description":"User-defined detection patterns","items":{"$ref":"#/components/schemas/config.CustomPattern"},"type":"array","uniqueItems":false},"enabled":{"description":"Enable sensitive data detection (default: true)","type":"boolean"},"entropy_threshold":{"description":"Shannon entropy threshold for high-entropy detection (default: 4.5)","type":"number"},"max_payload_size_kb":{"description":"Max size to scan before truncating (default: 1024)","type":"integer"},"scan_requests":{"description":"Scan tool call arguments (default: true)","type":"boolean"},"scan_responses":{"description":"Scan tool responses (default: true)","type":"boolean"},"sensitive_keywords":{"description":"Keywords to flag","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ServerConfig":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve tool\nchanges/additions (disabling per-server rug-pull protection). Supersedes\nskip_quarantine. MCP-2930 only ACCEPTS, persists, and migrates this flag — it\nis NOT yet consulted at runtime; auto-approval is still governed by\nSkipQuarantine until the trust-baseline behavior change (MCP-2931) migrates the\nruntime consumers onto it.\nTri-state pointer (mirrors QuarantineEnabled): nil = unset (inherit/migrate\nfrom legacy skip_quarantine), explicit true/false = honored as-is so an\nexplicit auto_approve_tool_changes:false overrides a legacy skip_quarantine:true.\nRead via IsAutoApproveToolChanges().","type":"boolean"},"command":{"type":"string"},"created":{"type":"string"},"disabled_tools":{"description":"Denylist: these tools are hidden; mutually exclusive with enabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"},"enabled_tools":{"description":"Allowlist: only these tools are exposed; mutually exclusive with disabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"env":{"additionalProperties":{"type":"string"},"type":"object"},"headers":{"additionalProperties":{"type":"string"},"description":"For HTTP servers","type":"object"},"health_check_interval":{"description":"Per-server discovery \u0026 health-check overrides (spec 074). Same *Duration\ntri-state as the global keys: nil = inherit the global value (or default),\npointer to 0s = disabled for this server, positive = that interval.\nHealthCheckInterval is fully wired into the per-server health loop;\nToolDiscoveryInterval is accepted/validated and round-trips for\nforward-compat, but the periodic index sweep is governed by the global\ncadence in this iteration (see spec 074 plan §C).","type":"string"},"init_timeout":{"description":"InitTimeout overrides the global init_timeout for this server's MCP\n` + "`" + `initialize` + "`" + ` handshake deadline (MCP-3322 / GH #760). *Duration tri-state:\nnil = inherit the global value (or 30s default), positive = that deadline.\nResolved by Config.ResolveInitTimeout; validated to {0} ∪ [1s, 30m]. Raise\nthis for upstreams that do legitimate first-run warmup (e.g. caching many\nchannels/users) before responding to ` + "`" + `initialize` + "`" + `.","type":"string"},"isolation":{"$ref":"#/components/schemas/config.IsolationConfig"},"launcher_wait_timeout":{"description":"LauncherWaitTimeout caps how long mcpproxy will wait for a locally-launched\nHTTP/SSE upstream's URL to become reachable after Spawn(). Only consulted\nwhen the server is configured with both Command and an HTTP/SSE URL — i.e.,\nmcpproxy starts the process AND connects via network. Stdio servers ignore\nthis field. Zero or unset → 30s default.","type":"string"},"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":"SkipQuarantine is DEPRECATED (MCP-2930): use AutoApproveToolChanges instead.\nKept for back-compat parsing; on config load a legacy skip_quarantine:true is\nmigrated to auto_approve_tool_changes:true only when the new field is unset\n(see normalizeServerQuarantineFlags).","type":"boolean"},"source_registry_id":{"description":"SourceRegistryID records which registry this server was added from (empty\nfor manually-configured servers). MCP-866: surfaced in the approval /\nquarantine view so a reviewer can see a server's origin.","type":"string"},"source_registry_provenance":{"description":"SourceRegistryProvenance records the source registry's provenance at add\ntime (RegistryProvenanceOfficial / RegistryProvenanceCustom). It is purely\ninformational (MCP-1072) — surfaced so a reviewer can see a server's origin\n— and no longer gates quarantine or skip_quarantine.","type":"string"},"tool_discovery_interval":{"type":"string"},"toon_output":{"description":"ToonOutput overrides the global toon_output mode for this server's\ntools (spec 084, FR-001). Plain string, not a pointer: \"\"/absent =\ninherit the global value; \"off\"|\"adaptive\"|\"always\" = override (\"off\"\nis the explicit force-off). Resolved by Config.ResolveToonOutput.","type":"string"},"trust_mode":{"description":"TrustMode is the per-server trust tier: auto|scan|manual. Supersedes\nauto_approve_tool_changes (spec 086). An empty value is derived from the\nlegacy fields at load via normalizeServerQuarantineFlags; the single\nresolution point is EffectiveTrustMode(), which treats an empty or\nunrecognized value as manual (secure by default). Read via\nEffectiveTrustMode(), never the raw string.","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"working_dir":{"description":"Working directory for stdio servers","type":"string"}},"type":"object"},"config.TLSConfig":{"description":"TLS configuration","properties":{"certs_dir":{"description":"Directory for certificates","type":"string"},"enabled":{"description":"Enable HTTPS","type":"boolean"},"hsts":{"description":"Enable HTTP Strict Transport Security","type":"boolean"},"require_client_cert":{"description":"Enable mTLS","type":"boolean"}},"type":"object"},"config.TelemetryConfig":{"description":"Telemetry settings (Spec 036)","properties":{"anonymous_id":{"description":"Auto-generated UUIDv4","type":"string"},"anonymous_id_created_at":{"description":"Spec 042 (Tier 2) additions — all default-zero, all backwards-compatible.","type":"string"},"enabled":{"description":"Default: true (opt-out)","type":"boolean"},"endpoint":{"description":"Override for testing","type":"string"},"last_reported_version":{"description":"Upgrade funnel","type":"string"},"last_startup_outcome":{"description":"success|port_conflict|db_locked|...","type":"string"},"notice_shown":{"description":"First-run notice flag","type":"boolean"}},"type":"object"},"config.TokenizerConfig":{"description":"Tokenizer configuration for token counting","properties":{"default_model":{"description":"Default model for tokenization (e.g., \"gpt-4\")","type":"string"},"enabled":{"description":"Enable token counting","type":"boolean"},"encoding":{"description":"Default encoding (e.g., \"cl100k_base\")","type":"string"}},"type":"object"},"config.TracingExporterConfig":{"description":"Tracing gates the OpenTelemetry OTLP trace exporter (MCP-32). Disabled by\ndefault.","properties":{"enabled":{"description":"Enabled turns on OTLP trace export for tool calls and upstream hops.","type":"boolean"},"endpoint":{"description":"Endpoint is the collector address as host:port (no scheme), e.g.\n\"localhost:4318\" for http or \"localhost:4317\" for grpc.","type":"string"},"protocol":{"description":"Protocol selects the OTLP transport: \"http\" or \"grpc\".","type":"string"},"sample_rate":{"description":"SampleRate is the head-based trace sampling ratio in [0,1]. Default 0.1.","type":"number"}},"type":"object"},"config.UpdateCheckConfig":{"description":"Update-check settings (Spec 079 FR-012): config-file control of the\nbackground upgrade-awareness checker (internal/updatecheck). nil =\nenabled on the stable channel (existing default behavior). The existing\nenvironment switches keep working and WIN over these keys (FR-014):\nMCPPROXY_DISABLE_AUTO_UPDATE=true force-disables even when\nenabled=true, and MCPPROXY_ALLOW_PRERELEASE_UPDATES=true force-selects\nthe rc channel even when channel=stable.","properties":{"channel":{"description":"Channel selects which releases are offered as updates: \"stable\"\n(default; prereleases never offered) or \"rc\" (prereleases included).\nEmpty resolves to stable. Validated in ValidateDetailed.","type":"string"},"enabled":{"description":"Enabled gates all update checking. Tri-state: nil/absent = enabled\n(default true, matching pre-079 behavior). When false, no network\ncheck is performed and no upgrade nudge appears on any surface\n(FR-015) — /api/v1/info omits the update object entirely.","type":"boolean"}},"type":"object"},"configimport.FailedServer":{"properties":{"details":{"type":"string"},"error":{"type":"string"},"name":{"type":"string"}},"type":"object"},"configimport.ImportSummary":{"properties":{"failed":{"type":"integer"},"imported":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"configimport.SkippedServer":{"properties":{"name":{"type":"string"},"reason":{"description":"\"already_exists\", \"filtered_out\", \"invalid_name\"","type":"string"}},"type":"object"},"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 transport session ID (regenerated on every reconnect)","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"},"work_session_id":{"description":"Spec 082: one client, one project, across reconnects","type":"string"}},"type":"object"},"contracts.ActivitySource":{"description":"How activity was triggered: \"mcp\", \"cli\", \"api\"","type":"string","x-enum-varnames":["ActivitySourceMCP","ActivitySourceCLI","ActivitySourceAPI"]},"contracts.ActivitySummaryResponse":{"properties":{"blocked_count":{"description":"Count of blocked activities","type":"integer"},"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.AddFromRegistryRequest":{"properties":{"enabled":{"description":"defaults to true when nil","type":"boolean"},"env":{"additionalProperties":{"type":"string"},"description":"overrides + required-input values","type":"object"},"name":{"description":"optional name override","type":"string"}},"type":"object"},"contracts.AddRegistrySourceRequest":{"properties":{"id":{"description":"derived from the host when empty","type":"string"},"name":{"description":"defaults to the id","type":"string"},"protocol":{"description":"defaults to modelcontextprotocol/registry","type":"string"},"url":{"description":"required https registry URL","type":"string"}},"type":"object"},"contracts.ConfigApplyResult":{"properties":{"applied_immediately":{"type":"boolean"},"changed_fields":{"items":{"type":"string"},"type":"array","uniqueItems":false},"requires_restart":{"type":"boolean"},"restart_reason":{"type":"string"},"success":{"type":"boolean"},"validation_errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DCRStatus":{"properties":{"attempted":{"type":"boolean"},"error":{"type":"string"},"status_code":{"type":"integer"},"success":{"type":"boolean"}},"type":"object"},"contracts.DeepScanDescriptor":{"description":"DeepScan reports the opt-in \"deep scan\" layer status (Spec 077 US3),\nSEPARATELY from the baseline verdict above. Always emitted on a computed\nsummary — when deep scan is off (the default) it reports enabled=false\nplus any enabled-but-skipped Docker scanners. It never influences Status.","properties":{"available":{"type":"boolean"},"enabled":{"type":"boolean"},"ran":{"type":"boolean"},"scanners_failed":{"items":{"$ref":"#/components/schemas/contracts.DeepScanScannerFailure"},"type":"array","uniqueItems":false},"skipped_scanners":{"description":"SkippedScanners lists Docker scanners the user enabled that are skipped\nbecause security.deep_scan.enabled is false (informational).","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DeepScanScannerFailure":{"properties":{"id":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"contracts.DeprecatedConfigWarning":{"properties":{"field":{"type":"string"},"message":{"type":"string"},"replacement":{"type":"string"}},"type":"object"},"contracts.Diagnostic":{"description":"Spec 044 — structured diagnostic error and stable error code. Both\nare populated when the server is in a failed state and the error\nhas been classified by internal/diagnostics. Healthy servers omit\nthese fields.","properties":{"cause":{"type":"string"},"code":{"type":"string"},"detected_at":{"type":"string"},"docs_url":{"type":"string"},"fix_steps":{"items":{"$ref":"#/components/schemas/contracts.DiagnosticFixStep"},"type":"array","uniqueItems":false},"severity":{"type":"string"},"user_message":{"type":"string"}},"type":"object"},"contracts.DiagnosticFixStep":{"properties":{"command":{"type":"string"},"destructive":{"type":"boolean"},"fixer_key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"}},"type":"object"},"contracts.Diagnostics":{"properties":{"deprecated_configs":{"description":"Deprecated config fields found","items":{"$ref":"#/components/schemas/contracts.DeprecatedConfigWarning"},"type":"array","uniqueItems":false},"docker_status":{"$ref":"#/components/schemas/contracts.DockerStatus"},"missing_secrets":{"description":"Renamed to avoid conflict","items":{"$ref":"#/components/schemas/contracts.MissingSecretInfo"},"type":"array","uniqueItems":false},"oauth_issues":{"description":"OAuth parameter mismatches","items":{"$ref":"#/components/schemas/contracts.OAuthIssue"},"type":"array","uniqueItems":false},"oauth_required":{"items":{"$ref":"#/components/schemas/contracts.OAuthRequirement"},"type":"array","uniqueItems":false},"runtime_warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false},"timestamp":{"type":"string"},"total_issues":{"type":"integer"},"upstream_errors":{"items":{"$ref":"#/components/schemas/contracts.UpstreamError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DockerStatus":{"properties":{"available":{"type":"boolean"},"error":{"type":"string"},"version":{"type":"string"}},"type":"object"},"contracts.EditRegistrySourceRequest":{"properties":{"name":{"description":"new display name","type":"string"},"servers_url":{"description":"explicit servers-collection URL","type":"string"},"url":{"description":"new base/servers https URL","type":"string"}},"type":"object"},"contracts.ErrorResponse":{"properties":{"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.FindingCounts":{"properties":{"dangerous":{"description":"Tool poisoning, active prompt injection","type":"integer"},"info":{"description":"Low-severity CVEs, informational","type":"integer"},"total":{"type":"integer"},"warning":{"description":"Rug pull, supply chain CVEs with exploits","type":"integer"}},"type":"object"},"contracts.GetConfigResponse":{"properties":{"config":{"description":"The configuration object","type":"object"},"config_path":{"description":"Path to config file","type":"string"}},"type":"object"},"contracts.GetRegistriesResponse":{"properties":{"registries":{"items":{"$ref":"#/components/schemas/contracts.Registry"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerLogsResponse":{"properties":{"count":{"type":"integer"},"logs":{"items":{"$ref":"#/components/schemas/contracts.LogEntry"},"type":"array","uniqueItems":false},"server_name":{"type":"string"}},"type":"object"},"contracts.GetServerToolCallsResponse":{"properties":{"server_name":{"type":"string"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerToolsResponse":{"properties":{"count":{"type":"integer"},"server_name":{"type":"string"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GetServersResponse":{"properties":{"servers":{"items":{"$ref":"#/components/schemas/contracts.Server"},"type":"array","uniqueItems":false},"stats":{"$ref":"#/components/schemas/contracts.ServerStats"}},"type":"object"},"contracts.GetSessionDetailResponse":{"properties":{"session":{"$ref":"#/components/schemas/contracts.MCPSession"}},"type":"object"},"contracts.GetSessionsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"sessions":{"items":{"$ref":"#/components/schemas/contracts.MCPSession"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetToolCallDetailResponse":{"properties":{"tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"}},"type":"object"},"contracts.GetToolCallsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GlobalToolsResponse":{"properties":{"failed_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"partial":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/contracts.GlobalToolsStats"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GlobalToolsStats":{"properties":{"disabled":{"type":"integer"},"enabled":{"type":"integer"},"pending_approval":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.HealthStatus":{"description":"Unified health status calculated by the backend","properties":{"action":{"description":"Action is the suggested fix action: \"login\", \"restart\", \"enable\", \"approve\", \"view_logs\", \"set_secret\", \"configure\", 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"},"work_session_id":{"type":"string"},"workspace_name":{"description":"Workspace / work session (Spec 082). WorkspaceName is the project's\nbasename — the full local path is never exposed. WorkSessionID groups the\nreconnects that make up one stretch of user work.","type":"string"}},"type":"object"},"contracts.MetadataStatus":{"properties":{"authorization_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"error":{"type":"string"},"found":{"type":"boolean"},"url_checked":{"type":"string"}},"type":"object"},"contracts.MissingSecretInfo":{"properties":{"secret_name":{"type":"string"},"used_by":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.NPMPackageInfo":{"properties":{"exists":{"type":"boolean"},"install_cmd":{"type":"string"}},"type":"object"},"contracts.OAuthConfig":{"properties":{"auth_url":{"type":"string"},"client_id":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_port":{"type":"integer"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false},"token_expires_at":{"description":"When the OAuth token expires","type":"string"},"token_url":{"type":"string"},"token_valid":{"description":"Whether token is currently valid","type":"boolean"}},"type":"object"},"contracts.OAuthErrorDetails":{"description":"Structured discovery/failure details","properties":{"authorization_server_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"dcr_status":{"$ref":"#/components/schemas/contracts.DCRStatus"},"protected_resource_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"server_url":{"type":"string"}},"type":"object"},"contracts.OAuthFlowError":{"properties":{"correlation_id":{"description":"Flow tracking ID for log correlation","type":"string"},"debug_hint":{"description":"CLI command for log lookup","type":"string"},"details":{"$ref":"#/components/schemas/contracts.OAuthErrorDetails"},"error_code":{"description":"Machine-readable error code (e.g., OAUTH_NO_METADATA)","type":"string"},"error_type":{"description":"Category of OAuth runtime failure","type":"string"},"message":{"description":"Human-readable error description","type":"string"},"request_id":{"description":"HTTP request ID (from PR #237)","type":"string"},"server_name":{"description":"Server that failed OAuth","type":"string"},"success":{"description":"Always false","type":"boolean"},"suggestion":{"description":"Actionable remediation hint","type":"string"}},"type":"object"},"contracts.OAuthIssue":{"properties":{"documentation_url":{"type":"string"},"error":{"type":"string"},"issue":{"type":"string"},"missing_params":{"items":{"type":"string"},"type":"array","uniqueItems":false},"resolution":{"type":"string"},"server_name":{"type":"string"}},"type":"object"},"contracts.OAuthRequirement":{"properties":{"expires_at":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"state":{"type":"string"}},"type":"object"},"contracts.OAuthStartResponse":{"properties":{"auth_url":{"description":"Authorization URL (always included for manual use)","type":"string"},"browser_error":{"description":"Error message if browser launch failed","type":"string"},"browser_opened":{"description":"Whether browser launch succeeded","type":"boolean"},"correlation_id":{"description":"UUID for tracking this flow","type":"string"},"message":{"description":"Human-readable status message","type":"string"},"server_name":{"description":"Name of the server being authenticated","type":"string"},"success":{"description":"Always true for successful start","type":"boolean"}},"type":"object"},"contracts.QuarantineStats":{"description":"Tool quarantine metrics for this server","properties":{"blocked_count":{"description":"Number of disabled (blocked) tools","type":"integer"},"changed_count":{"description":"Number of tools whose description/schema changed since approval","type":"integer"},"pending_count":{"description":"Number of newly discovered tools awaiting approval","type":"integer"}},"type":"object"},"contracts.RefreshRegistryResponse":{"properties":{"cleared":{"description":"number of cached entries dropped","type":"integer"},"registry_id":{"type":"string"}},"type":"object"},"contracts.Registry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag (MCP-866): \"official/trusted\" for built-in\ndefaults, \"custom/unverified\" for user-added registries.","type":"string"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"trusted":{"description":"Trusted indicates whether this is an official, shipped-by-default\nregistry. Trust is derived from membership in the default set, never\nfrom self-assertion in config.","type":"boolean"},"url":{"type":"string"}},"type":"object"},"contracts.RegistryCacheInfo":{"properties":{"age_seconds":{"type":"number"},"stale":{"type":"boolean"}},"type":"object"},"contracts.RegistryUnavailable":{"properties":{"reason":{"type":"string"}},"type":"object"},"contracts.ReplayToolCallRequest":{"properties":{"arguments":{"description":"Modified arguments for replay","type":"object"}},"type":"object"},"contracts.ReplayToolCallResponse":{"properties":{"error":{"description":"Error if replay failed","type":"string"},"new_call_id":{"description":"ID of the newly created call","type":"string"},"new_tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"replayed_from":{"description":"Original call ID","type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.RepositoryInfo":{"description":"Detected package info","properties":{"npm":{"$ref":"#/components/schemas/contracts.NPMPackageInfo"}},"type":"object"},"contracts.RepositoryServer":{"properties":{"connect_url":{"description":"Alternative connection URL","type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"install_cmd":{"description":"Installation command","type":"string"},"name":{"type":"string"},"registry":{"description":"Which registry this came from","type":"string"},"repository_info":{"$ref":"#/components/schemas/contracts.RepositoryInfo"},"source_code_url":{"description":"Source repository URL","type":"string"},"updated_at":{"type":"string"},"url":{"description":"MCP endpoint for remote servers only","type":"string"}},"type":"object"},"contracts.SearchRegistryServersResponse":{"properties":{"cache":{"$ref":"#/components/schemas/contracts.RegistryCacheInfo"},"query":{"type":"string"},"registry_id":{"type":"string"},"servers":{"items":{"$ref":"#/components/schemas/contracts.RepositoryServer"},"type":"array","uniqueItems":false},"tag":{"type":"string"},"total":{"type":"integer"},"unavailable":{"$ref":"#/components/schemas/contracts.RegistryUnavailable"}},"type":"object"},"contracts.SearchResult":{"properties":{"matches":{"type":"integer"},"score":{"type":"number"},"snippet":{"type":"string"},"tool":{"$ref":"#/components/schemas/contracts.Tool"}},"type":"object"},"contracts.SearchToolsResponse":{"properties":{"query":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/contracts.SearchResult"},"type":"array","uniqueItems":false},"took":{"type":"string"},"total":{"type":"integer"}},"type":"object"},"contracts.SecurityScanSummary":{"description":"Latest security scan results summary","properties":{"deep_scan":{"$ref":"#/components/schemas/contracts.DeepScanDescriptor"},"finding_counts":{"$ref":"#/components/schemas/contracts.FindingCounts"},"last_scan_at":{"type":"string"},"risk_score":{"description":"0-100","type":"integer"},"scanners_failed":{"type":"integer"},"scanners_run":{"description":"Scanner coverage for the primary (baseline) scan pass — informational only.\nSpec 077 US3 (FR-008/FR-014): Status is derived SOLELY from the\ndeterministic baseline findings; a failed Docker deep scanner no longer\ndowngrades a clean verdict. That failure is surfaced via DeepScan instead.","type":"integer"},"scanners_total":{"type":"integer"},"status":{"description":"\"clean\", \"warnings\", \"dangerous\", \"failed\", \"not_scanned\", \"scanning\"","type":"string"}},"type":"object"},"contracts.Server":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"authenticated":{"description":"OAuth authentication status","type":"boolean"},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges mirrors config.ServerConfig.AutoApproveToolChanges\n(MCP-2930): the per-server intent to auto-approve new/changed tools past\nthe trust baseline. Tri-state *bool — nil means \"never set\" (omitted from\nthe payload), so the Web UI toggle (MCP-2932) can distinguish unset from\nan explicit false. Read-only on the GET path; PATCH/POST accept it via\nAddServerRequest.","type":"boolean"},"command":{"type":"string"},"connected":{"type":"boolean"},"connected_at":{"type":"string"},"connecting":{"type":"boolean"},"created":{"type":"string"},"diagnostic":{"$ref":"#/components/schemas/contracts.Diagnostic"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"error_code":{"type":"string"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"health":{"$ref":"#/components/schemas/contracts.HealthStatus"},"id":{"type":"string"},"init_timeout":{"description":"InitTimeout mirrors config.ServerConfig.InitTimeout (MCP-3322 / GH #760):\nthe per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override. Serialized as\na duration string (e.g. \"120s\"); nil/omitted means \"inherit the global\ndefault\". Surfaced on the GET path so clients can read back a configured\noverride; PATCH/POST accept it via AddServerRequest.","type":"string"},"isolation":{"$ref":"#/components/schemas/contracts.IsolationConfig"},"isolation_defaults":{"$ref":"#/components/schemas/contracts.IsolationDefaults"},"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"},"source_registry_id":{"description":"MCP-901 — registry provenance of an upstream that was added from a\nregistry. SourceRegistryID names the source registry (empty for\nmanually-configured servers); SourceRegistryProvenance is the trust tag\nrecorded at add time (\"official/trusted\" or \"custom/unverified\"). Both\nare projected from config.ServerConfig so the approval/quarantine view\ncan render an \"added from \u003cregistry\u003e · unverified\" origin badge. Optional\nand omitted when empty — clients that pre-date this treat them as absent.","type":"string"},"source_registry_provenance":{"type":"string"},"status":{"type":"string"},"token_expires_at":{"description":"When the OAuth token expires (ISO 8601)","type":"string"},"tool_count":{"type":"integer"},"tool_list_token_size":{"description":"Token size for this server's tools","type":"integer"},"trust_mode":{"description":"TrustMode mirrors config.ServerConfig.TrustMode (spec 086): the per-server\ntrust tier (\"auto\"/\"scan\"/\"manual\"). Surfaced on the GET path so clients can\nread back the persisted mode; PATCH/POST accept it via AddServerRequest.\nOmitted when empty (server predates the field / relies on legacy flags).","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"user_logged_out":{"description":"True if user explicitly logged out (prevents auto-reconnection)","type":"boolean"},"working_dir":{"type":"string"}},"type":"object"},"contracts.ServerActionResponse":{"properties":{"action":{"type":"string"},"async":{"type":"boolean"},"server":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ServerStats":{"properties":{"connected_servers":{"type":"integer"},"docker_containers":{"type":"integer"},"quarantined_servers":{"type":"integer"},"token_metrics":{"$ref":"#/components/schemas/contracts.ServerTokenMetrics"},"total_servers":{"type":"integer"},"total_tools":{"type":"integer"}},"type":"object"},"contracts.ServerTokenMetrics":{"properties":{"average_query_result_size":{"description":"Typical retrieve_tools output (tokens)","type":"integer"},"per_server_tool_list_sizes":{"additionalProperties":{"type":"integer"},"description":"Token size per server","type":"object"},"saved_tokens":{"description":"Difference","type":"integer"},"saved_tokens_percentage":{"description":"Percentage saved","type":"number"},"total_server_tool_list_size":{"description":"All upstream tools combined (tokens)","type":"integer"}},"type":"object"},"contracts.SuccessResponse":{"properties":{"data":{"type":"object"},"success":{"type":"boolean"}},"type":"object"},"contracts.TokenMetrics":{"description":"Token usage metrics (nil for older records)","properties":{"encoding":{"description":"Encoding used (e.g., cl100k_base)","type":"string"},"estimated_cost":{"description":"Optional cost estimate","type":"number"},"input_tokens":{"description":"Tokens in the request","type":"integer"},"model":{"description":"Model used for tokenization","type":"string"},"output_tokens":{"description":"Tokens in the response","type":"integer"},"total_tokens":{"description":"Total tokens (input + output)","type":"integer"},"truncated_tokens":{"description":"Tokens removed by truncation","type":"integer"},"was_truncated":{"description":"Whether response was truncated","type":"boolean"}},"type":"object"},"contracts.Tool":{"properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"approval_status":{"type":"string"},"config_denied":{"description":"ConfigDenied is true when the tool is denied by the server's static\nenabled_tools / disabled_tools config. The user cannot override this toggle.","type":"boolean"},"description":{"type":"string"},"disabled":{"description":"Disabled mirrors ToolApprovalRecord.Disabled so per-tool enable state is\navailable without a second round-trip to the approvals endpoint. Absent\nin the JSON when false (default) to keep responses compact.","type":"boolean"},"held_reason":{"description":"HeldReason, HeldVerdict and HeldSignals mirror the same-named fields on\nstorage.ToolApprovalRecord: the offline-scan evidence that made\ntrust_mode: scan hold this tool for review (spec 086 FR-018). HeldSignals\nnames the matched deterministic check ids, e.g.\n\"tpa.TPA-2026-0001.hidden_instruction\", so a reviewer can see WHY the tool\nis held. All three are omitted for tools that are not held by the scan gate\n(including every record written before the field existed).","type":"string"},"held_signals":{"items":{"type":"string"},"type":"array","uniqueItems":false},"held_verdict":{"type":"string"},"last_used":{"type":"string"},"name":{"type":"string"},"schema":{"type":"object"},"server_name":{"type":"string"},"usage":{"type":"integer"}},"type":"object"},"contracts.ToolAnnotation":{"description":"Tool behavior hints snapshot","properties":{"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"},"readOnlyHint":{"type":"boolean"},"title":{"type":"string"}},"type":"object"},"contracts.ToolCallRecord":{"description":"The new tool call record","properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"arguments":{"description":"Tool arguments","type":"object"},"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"},"install_channel":{"description":"Detected install channel (homebrew, dmg, deb, rpm, docker, go-install, windows-installer, tarball, unknown) — Spec 079 FR-008","type":"string"},"is_prerelease":{"description":"Whether the latest version is a prerelease","type":"boolean"},"latest_version":{"description":"Latest version available (e.g., \"v1.2.3\")","type":"string"},"nudges_suppressed":{"description":"UI surfaces must stay quiet (CI / non-interactive context); machine-readable fields still report the facts — Spec 079 FR-019","type":"boolean"},"release_url":{"description":"URL to the release page","type":"string"},"update_command":{"description":"One-line update command for the channel; only set when an update is available and the channel has one — Spec 079 FR-009","type":"string"}},"type":"object"},"contracts.UpstreamError":{"properties":{"error_message":{"type":"string"},"server_name":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.UsageAggregateResponse":{"properties":{"freshness_ms":{"description":"age of the underlying snapshot in ms","type":"integer"},"generated_at":{"type":"string"},"other":{"$ref":"#/components/schemas/contracts.UsageOtherBucket"},"timeline":{"items":{"$ref":"#/components/schemas/contracts.UsageTimeBucket"},"type":"array","uniqueItems":false},"token_source":{"description":"\"bytes\" (size-based proxy, FR-006)","type":"string"},"tokens_saved":{"description":"echoed from ServerTokenMetrics (FR-007)","type":"integer"},"tokens_saved_percentage":{"type":"number"},"tools":{"items":{"$ref":"#/components/schemas/contracts.UsageToolStat"},"type":"array","uniqueItems":false},"window":{"type":"string"}},"type":"object"},"contracts.UsageOtherBucket":{"description":"present only when the list was truncated to top-N","properties":{"calls":{"type":"integer"},"tools_folded":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageTimeBucket":{"properties":{"calls":{"type":"integer"},"errors":{"type":"integer"},"start":{"type":"string"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageToolStat":{"properties":{"avg_req_bytes":{"description":"null when no sized request calls","type":"integer"},"avg_resp_bytes":{"description":"null when sized_calls == 0 (only legacy 0-byte calls)","type":"integer"},"blocked":{"type":"integer"},"calls":{"type":"integer"},"error_rate":{"type":"number"},"errors":{"type":"integer"},"last_used":{"type":"string"},"p50_ms":{"type":"integer"},"p95_ms":{"type":"integer"},"server":{"type":"string"},"sized_calls":{"description":"calls with known response size (basis for avg_resp_bytes)","type":"integer"},"tool":{"type":"string"},"total_req_bytes":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.ValidateConfigResponse":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false},"valid":{"type":"boolean"}},"type":"object"},"contracts.ValidationError":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"data":{"properties":{"data":{"$ref":"#/components/schemas/contracts.InfoResponse"}},"type":"object"},"httpapi.AddServerRequest":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve\nnew/changed tools past the trust baseline (MCP-2930). Tri-state *bool:\na nil pointer means \"leave unchanged\" on PATCH; a present value\n(including false) is applied. Mirrors config.ServerConfig's *bool\nsemantics — do NOT collapse to a plain bool, or an omitted field would\nsilently reset a previously-set value.","type":"boolean"},"command":{"type":"string"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"init_timeout":{"description":"InitTimeout is the per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override\n(MCP-3322 / GH #760), serialized as a duration string (e.g. \"120s\"). A nil\npointer means \"leave unchanged\" on PATCH; a present value is applied.\nMirrors config.ServerConfig.InitTimeout's *Duration tri-state.","type":"string"},"isolation":{"$ref":"#/components/schemas/httpapi.IsolationRequest"},"name":{"type":"string"},"protocol":{"type":"string"},"quarantined":{"type":"boolean"},"reconnect_on_use":{"type":"boolean"},"trust_mode":{"description":"TrustMode is the per-server trust tier (spec 086): \"auto\", \"scan\", or\n\"manual\". Empty means \"leave unchanged\" on PATCH (and inherit the migrated\ndefault on create). A non-empty value is applied to ServerConfig.TrustMode\nand resolved by EffectiveTrustMode (an unrecognized value fails closed to\nmanual). This is the REST seam for changing the trust tier via\nPOST/PATCH /api/v1/servers.","type":"string"},"url":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.CanonicalConfigPath":{"properties":{"description":{"description":"Brief description","type":"string"},"exists":{"description":"Whether the file exists","type":"boolean"},"format":{"description":"Format identifier (e.g., \"claude_desktop\")","type":"string"},"name":{"description":"Display name (e.g., \"Claude Desktop\")","type":"string"},"os":{"description":"Operating system (darwin, windows, linux)","type":"string"},"path":{"description":"Full path to the config file","type":"string"}},"type":"object"},"httpapi.CanonicalConfigPathsResponse":{"properties":{"os":{"description":"Current operating system","type":"string"},"paths":{"description":"List of canonical config paths","items":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPath"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.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 a server name → new name. Applied after parsing so the\ncaller can disambiguate cross-source name collisions (Spec 046 v2 —\ne.g. \"mcpproxy\" → \"mcpproxy_claude_code\"). Keys are matched against\neither the raw source name (OriginalName) or the sanitized name shown\nin the preview (Server.Name); these differ for names that need\nsanitizing (e.g. \"Figma Desktop\" → \"Figma_Desktop\"). Keys not present\nin the imported set are ignored.","type":"object"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportRequest":{"properties":{"content":{"description":"Raw JSON or TOML content","type":"string"},"format":{"description":"Optional format hint","type":"string"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportResponse":{"properties":{"failed":{"items":{"$ref":"#/components/schemas/configimport.FailedServer"},"type":"array","uniqueItems":false},"format":{"type":"string"},"format_name":{"type":"string"},"imported":{"items":{"$ref":"#/components/schemas/httpapi.ImportedServerResponse"},"type":"array","uniqueItems":false},"skipped":{"items":{"$ref":"#/components/schemas/configimport.SkippedServer"},"type":"array","uniqueItems":false},"summary":{"$ref":"#/components/schemas/configimport.ImportSummary"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportedServerResponse":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"command":{"type":"string"},"fields_skipped":{"items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"type":"string"},"original_name":{"type":"string"},"protocol":{"type":"string"},"source_format":{"type":"string"},"url":{"type":"string"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.IsolationRequest":{"description":"Isolation carries per-server Docker isolation overrides (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. The stored enum is wider (Spec 080\nFR-001): a \"skipped\" request for a previously untouched connect step\nis upgraded server-side to \"completed_external\" when the install\nshows positive evidence of an external connection (Spec 080 FR-002).\n\"completed_external\" is NOT accepted from clients — it must never be\npersisted without that server-verified evidence (edge case: \"never\nguess completed_external without positive evidence\").","type":"string"},"engaged":{"description":"Engaged marks the wizard as engaged (completed or explicitly skipped).\nOnce true, the wizard does not auto-show again.","type":"boolean"},"mark_shown":{"description":"MarkShown records the wizard's first display time if not already set.","type":"boolean"},"server_step_status":{"description":"ServerStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value.","type":"string"}},"type":"object"},"httpapi.SetActiveProfileRequest":{"properties":{"active_profile":{"type":"string"},"profile":{"type":"string"}},"type":"object"},"httpapi.UndoConnectRequest":{"properties":{"backup_name":{"description":"BackupName is the bare filename (filepath.Base) of the backup returned as\nbackup_path by the preceding connect — a name, never a path. Undo resolves\nthe full path server-side by joining it with the client's own config\ndirectory, so a client-supplied value can never contribute a directory\ncomponent (traversal is impossible by construction). Empty means the\nconnect created the file (no prior file existed), so undo removes it.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"management.BulkOperationResult":{"properties":{"errors":{"additionalProperties":{"type":"string"},"description":"Map of server name to error message","type":"object"},"failed":{"description":"Number of failed operations","type":"integer"},"successful":{"description":"Number of successful operations","type":"integer"},"total":{"description":"Total servers processed","type":"integer"}},"type":"object"},"observability.HealthResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"observability.HealthStatus":{"properties":{"error":{"type":"string"},"latency":{"type":"string"},"name":{"type":"string"},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"}},"type":"object"},"observability.ReadinessResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"ready\" or \"not_ready\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"secureenv.EnvConfig":{"description":"Environment configuration for secure variable filtering","properties":{"allowed_system_vars":{"items":{"type":"string"},"type":"array","uniqueItems":false},"custom_vars":{"additionalProperties":{"type":"string"},"type":"object"},"enhance_path":{"description":"Enable PATH enhancement for Launchd scenarios","type":"boolean"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned upstream servers (MCP-2769). It is OFF by\ndefault and deliberately kept out of the AllowedSystemVars default list:\nproxy URLs frequently carry credentials (http://user:pass@proxy), so\nforwarding them to every stdio upstream is a credential-leak risk. When\nenabled, values are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"inherit_system_safe":{"type":"boolean"}},"type":"object"},"telemetry.FeedbackContext":{"properties":{"arch":{"type":"string"},"connected_server_count":{"type":"integer"},"edition":{"type":"string"},"os":{"type":"string"},"routing_mode":{"type":"string"},"server_count":{"type":"integer"},"version":{"type":"string"}},"type":"object"},"telemetry.FeedbackRequest":{"properties":{"category":{"description":"bug, feature, other","type":"string"},"context":{"$ref":"#/components/schemas/telemetry.FeedbackContext"},"email":{"type":"string"},"message":{"type":"string"}},"type":"object"},"telemetry.FeedbackResponse":{"properties":{"error":{"type":"string"},"issue_url":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"API key authentication via query parameter. Use ?apikey=your-key","in":"query","name":"apikey","type":"apiKey"}}},
+    "components": {"schemas":{"config.Config":{"properties":{"activity_cleanup_interval_min":{"description":"Background cleanup interval in minutes (default: 60)","type":"integer"},"activity_max_records":{"description":"Max records before pruning (default: 100000)","type":"integer"},"activity_max_response_size":{"description":"Response truncation limit in bytes (default: 65536)","type":"integer"},"activity_max_size_mb":{"description":"Max total activity-log size in MB before pruning oldest (default: 256, 0=disabled)","type":"integer"},"activity_retention_days":{"description":"Activity logging settings (RFC-003)","type":"integer"},"allow_private_registry_fetch":{"description":"AllowPrivateRegistryFetch opts out of the registry SSRF guard (MCP-1076,\nCWE-918). By default (false) registry fetches refuse any host that is — or\nresolves to — a non-routable address (loopback, RFC1918/CGNAT private,\nlink-local incl. the 169.254.169.254 cloud-metadata endpoint), so a\nmalicious or typo'd registry source cannot turn the daemon into a\nrequest-forgery vector against internal services.\n\nThis opt-out is BLANKET (all-or-nothing): setting it true disables the\nguard for EVERY non-routable range at once — loopback, RFC1918/CGNAT\nprivate, link-local AND the 169.254.169.254 cloud-metadata endpoint. There\nis no way to allow only loopback; enabling it for a localhost dev registry\nalso re-opens the cloud-metadata SSRF vector. Set true ONLY when you\nintentionally run a trusted registry mirror on an internal/private address,\nideally on a host with no cloud-metadata exposure. The change takes effect\nonly on daemon (re)start or config reload.","type":"boolean"},"allow_server_add":{"type":"boolean"},"allow_server_remove":{"type":"boolean"},"api_key":{"description":"Security settings","type":"string"},"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"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned stdio upstream servers (MCP-2769). OFF by\ndefault: proxy URLs commonly embed credentials (http://user:pass@proxy), so\nforwarding them to every upstream is a credential-leak risk. When enabled,\nvalues are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"health_check_interval":{"description":"Discovery \u0026 health-check cadence (spec 074, #608). Both are *Duration\ntri-state pointers: nil = inherit the built-in default; a pointer to 0s =\nthe loop is disabled; a positive value = that interval. Defaults live only\nin the resolvers (ResolveHealthCheckInterval / ResolveToolDiscoveryInterval)\nso an unset key behaves exactly as before this feature (SC-005). Validated\nin Validate(): health-check ∈ {0} ∪ [5s,1h]; tool-discovery ∈ {0} ∪ [30s,24h].","type":"string"},"init_timeout":{"description":"InitTimeout is the global default deadline for an upstream's MCP\n` + "`" + `initialize` + "`" + ` handshake (MCP-3322 / GH #760). *Duration tri-state: nil =\ninherit the built-in 30s default; a positive value = that deadline. A\nper-server InitTimeout overrides this. Resolved by ResolveInitTimeout;\nvalidated to {0} ∪ [1s, 30m] in Validate(). Servers doing legitimate\nfirst-run warmup (cache/index build) before answering ` + "`" + `initialize` + "`" + ` can\nraise this so they are not killed mid-startup.","type":"string"},"instructions":{"description":"Instructions text returned in the MCP initialize response to guide AI agents.\nWhen empty, a built-in default is used that explains retrieve_tools workflow.","type":"string"},"intent_declaration":{"$ref":"#/components/schemas/config.IntentDeclarationConfig"},"listen":{"type":"string"},"logging":{"$ref":"#/components/schemas/config.LogConfig"},"max_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"},"observability":{"$ref":"#/components/schemas/config.ObservabilityConfig"},"output_sanitisation":{"$ref":"#/components/schemas/config.OutputSanitisationConfig"},"output_validation":{"$ref":"#/components/schemas/config.OutputValidationConfig"},"profiles":{"description":"Profiles are optional named, server-scoped views exposed at /mcp/p/\u003cname\u003e\n(Spec 057). Absent/empty is fully supported — /mcp is unchanged and configs\nwithout this key serialize byte-identically (SC-004).","items":{"$ref":"#/components/schemas/config.ProfileConfig"},"type":"array","uniqueItems":false},"quarantine_enabled":{"description":"QuarantineEnabled controls whether quarantine is active. It gates two\nthings together:\n  1. Server-level auto-quarantine for newly added servers (issue #370).\n     When true, servers added via the upstream_servers MCP tool or the\n     REST API default to quarantined=true; when false, they default to\n     quarantined=false. Explicit per-request values always win.\n  2. Tool-level quarantine (Spec 032): per-tool SHA-256 approval of\n     tool descriptions/schemas.\nWhen nil (default), quarantine is enabled (secure by default). Set to\nexplicit false to opt out of both. Per-server SkipQuarantine still\napplies for the tool-level check on individual servers.","type":"boolean"},"read_only_mode":{"type":"boolean"},"registries":{"description":"Registries configuration for MCP server discovery","items":{"$ref":"#/components/schemas/config.RegistryEntry"},"type":"array","uniqueItems":false},"registries_locked":{"description":"RegistriesLocked is an enterprise stub knob (MCP-866): when true, runtime\nadditions of custom registries (e.g. ` + "`" + `registry add-source` + "`" + `, the REST/MCP\nadd-source surface) are rejected so an administrator can pin the discovery\nsources. Built-in defaults are unaffected. Documented but otherwise inert\nbeyond the add-source rejection.","type":"boolean"},"require_mcp_auth":{"description":"Require authentication on /mcp endpoint (default: false)","type":"boolean"},"reveal_secret_headers":{"description":"RevealSecretHeaders, when true, disables the redaction of the\nsecret-bearing server fields — sensitive header values (Authorization,\nX-API-Key, Cookie, …), env-var secrets, and URL query credentials — in\nresponses from the ` + "`" + `upstream_servers` + "`" + ` MCP tool, the ` + "`" + `/api/v1/servers` + "`" + `\nREST API, and the SSE event stream. It also lets URL secrets echoed\ninto last_error / health.detail through unscrubbed.\n\nDefault false — sensitive values are surfaced masked as\n` + "`" + `••••\u003clast2\u003e (\u003cN\u003e chars)` + "`" + ` (error strings use ` + "`" + `***REDACTED***` + "`" + `) so an\nMCP agent cannot read Bearer tokens / API keys / URL secrets out of\nanother upstream's config (PR #425, issue #872). ${env:…}/${keyring:…}\nreferences are labels, not secrets, and pass through unchanged.\n\nThe Web UI / macOS tray edit forms work without seeing the real\nvalues: PATCH /api/v1/servers/{id} deep-merges (omitted keys are\npreserved, see ` + "`" + `headers_remove` + "`" + ` / ` + "`" + `env_remove` + "`" + ` for explicit\ndeletes), so clients compute a diff and only send the keys that\nactually changed. Redacted-but-unchanged values never round-trip\n— the backend keeps the real string. Set this to true if a\ndownstream tool genuinely needs raw values in the response.","type":"boolean"},"routing_mode":{"description":"Routing mode (Spec 031): how MCP tools are exposed to clients\nValid values: \"retrieve_tools\" (default), \"direct\", \"code_execution\"","type":"string"},"security":{"$ref":"#/components/schemas/config.SecurityConfig"},"sensitive_data_detection":{"$ref":"#/components/schemas/config.SensitiveDataDetectionConfig"},"telemetry":{"$ref":"#/components/schemas/config.TelemetryConfig"},"tls":{"$ref":"#/components/schemas/config.TLSConfig"},"tokenizer":{"$ref":"#/components/schemas/config.TokenizerConfig"},"tool_discovery_interval":{"type":"string"},"tool_response_limit":{"type":"integer"},"tool_response_mode":{"description":"Tool response mode (Spec 085): how retrieve_tools serializes results.\nValid values: \"\" (= full), \"full\" (default: today's schema-bearing\nentries), \"compact\" (signature + first-sentence entries). Orthogonal to\nrouting_mode — routing_mode selects the tool SURFACE, this selects the\nSERIALIZATION within the retrieve_tools surface. Serialization-only: it\nnever affects the query, ranking, or result set. Hot-reloadable.","type":"string"},"tool_response_session_risk_warning":{"description":"ToolResponseSessionRiskWarning controls whether the prose ` + "`" + `warning` + "`" + ` field\nis included in the ` + "`" + `session_risk` + "`" + ` object returned by ` + "`" + `retrieve_tools` + "`" + `.\nThe structured fields (level, lethal_trifecta, has_open_world_tools, etc.)\nare always included. Default: false (quiet for LLM clients) — see issue #406.\nMost tools lack annotations, so the MCP-spec defaults treat them as fully\npermissive across all three risk axes, which makes the prose warning fire\non almost every call and wastes tokens.","type":"boolean"},"tools_limit":{"type":"integer"},"toon_min_savings_pct":{"description":"ToonMinSavingsPct is the minimum byte-savings percentage (validated\n1-90; 0/unset → 15) the complete TOON emission (marker + hint + body)\nmust achieve over the exact passthrough emission for adaptive mode to\nencode a block. Byte savings approximate token savings for the tabular\npayload class; the spec-083 profiler reports true token deltas.\nGlobal-only (no per-server override, FR-001).","type":"integer"},"toon_output":{"description":"ToonOutput selects the TOON encoding mode for call_tool_* result text\nblocks (spec 084): \"off\" (default — responses byte-identical to\npre-feature behavior), \"adaptive\" (encode only tabular-uniform payloads\nthat beat compact JSON by ToonMinSavingsPct), or \"always\"\n(benchmark/debug only — encodes every JSON-parseable block and can\nINCREASE token cost). Per-server override: ServerConfig.ToonOutput.\nResolved by ResolveToonOutput; hot-reloadable.","type":"string"},"top_k":{"description":"Deprecated: TopK is superseded by ToolsLimit and has no runtime effect. Kept for backward compatibility.","type":"integer"},"tray_endpoint":{"description":"Tray endpoint override (unix:// or npipe://)","type":"string"},"trusted_hosts":{"description":"TrustedHosts lists non-loopback Host header values accepted on loopback\nlisteners (GH #898). DNS-rebinding protection rejects requests whose Host\nheader is not a loopback address when mcpproxy listens on loopback; a\nreverse proxy (nginx → 127.0.0.1) forwarding the public domain in Host\ntrips it. Entries are hostnames, case-insensitive; an entry without a\nport matches any port, with a port it must match exactly; a leading dot\n(\".example.com\") is a subdomain wildcard. The single entry \"*\" disables\nHost and Origin validation entirely. The same list also validates the\nOrigin header when present (MCP spec DNS-rebinding defense). Empty\n(default) keeps full protection. Env override: MCPPROXY_TRUSTED_HOSTS\n(comma-separated).","items":{"type":"string"},"type":"array","uniqueItems":false},"update_check":{"$ref":"#/components/schemas/config.UpdateCheckConfig"}},"type":"object"},"config.CustomPattern":{"properties":{"category":{"description":"Category (defaults to \"custom\")","type":"string"},"keywords":{"description":"Keywords to match (mutually exclusive with Regex)","items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"description":"Unique identifier for this pattern","type":"string"},"regex":{"description":"Regex pattern (mutually exclusive with Keywords)","type":"string"},"severity":{"description":"Risk level: critical, high, medium, low","type":"string"}},"type":"object"},"config.DeepScanConfig":{"description":"DeepScan is the opt-in \"deep scan\" layer (Spec 077 US3). It subsumes the\ndeprecated top-level scanner_fetch_package_source / scanner_disable_no_new_privileges\nkeys (migrated on load) and gates the heavy Docker-based scanners + source\nextraction. Disabled by default (FR-006): only the deterministic in-process\nbaseline scanner runs. A deep-scan failure NEVER changes the baseline verdict\n(FR-007/FR-008).","properties":{"disable_no_new_privileges":{"description":"DisableNoNewPrivileges, when true, omits the ` + "`" + `--security-opt\nno-new-privileges` + "`" + ` flag from scanner container runs (snap-docker/AppArmor\nescape hatch). Absorbs the deprecated top-level\nscanner_disable_no_new_privileges. Default false.","type":"boolean"},"enabled":{"description":"Enabled is the master opt-in for the heavy layer (FR-006). Default false.","type":"boolean"},"fetch_package_source":{"description":"FetchPackageSource controls whether the scanner fetches the PUBLISHED\nsource of package-runner servers (npx/uvx) — without executing it — when\nno local source is available. Absorbs the deprecated top-level\nscanner_fetch_package_source. Default (nil) is ENABLED within deep scan.","type":"boolean"},"scanners":{"description":"Scanners optionally restricts which deep scanners may run under the\numbrella (by scanner id). Empty ⇒ all enabled deep scanners are eligible.","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.DockerIsolationConfig":{"description":"Docker isolation settings","properties":{"cpu_limit":{"description":"CPU limit for containers","type":"string"},"default_images":{"additionalProperties":{"type":"string"},"description":"Map of runtime type to Docker image","type":"object"},"enable_cache_volume":{"description":"Mount shared cache volumes for faster restarts (default: true)","type":"boolean"},"enabled":{"description":"Global enable/disable for Docker isolation (legacy; superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments","items":{"type":"string"},"type":"array","uniqueItems":false},"log_driver":{"description":"Docker log driver (default: json-file)","type":"string"},"log_max_files":{"description":"Maximum number of log files (default: 3)","type":"string"},"log_max_size":{"description":"Maximum size of log files (default: 100m)","type":"string"},"memory_limit":{"description":"Memory limit for containers","type":"string"},"mode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"network_mode":{"description":"Docker network mode (default: bridge)","type":"string"},"registry":{"description":"Custom registry (defaults to docker.io)","type":"string"},"timeout":{"description":"Container startup timeout","type":"string"}},"type":"object"},"config.DockerRecoveryConfig":{"description":"Docker recovery settings","properties":{"enabled":{"description":"Enable Docker recovery monitoring (default: true)","type":"boolean"},"max_retries":{"description":"Maximum retry attempts (0 = unlimited)","type":"integer"},"notify_on_failure":{"description":"Show notification on recovery failure (default: true)","type":"boolean"},"notify_on_retry":{"description":"Show notification on each retry (default: false)","type":"boolean"},"notify_on_start":{"description":"Show notification when recovery starts (default: true)","type":"boolean"},"notify_on_success":{"description":"Show notification on successful recovery (default: true)","type":"boolean"},"persistent_state":{"description":"Save recovery state across restarts (default: true)","type":"boolean"}},"type":"object"},"config.FeatureFlags":{"description":"Deprecated: Features flags are unused and have no runtime effect. Kept for backward compatibility.","properties":{"enable_async_storage":{"type":"boolean"},"enable_caching":{"type":"boolean"},"enable_contract_tests":{"type":"boolean"},"enable_debug_logging":{"description":"Development features","type":"boolean"},"enable_docker_isolation":{"type":"boolean"},"enable_event_bus":{"type":"boolean"},"enable_health_checks":{"type":"boolean"},"enable_metrics":{"type":"boolean"},"enable_oauth":{"description":"Security features","type":"boolean"},"enable_observability":{"description":"Observability features","type":"boolean"},"enable_quarantine":{"type":"boolean"},"enable_runtime":{"description":"Runtime features","type":"boolean"},"enable_search":{"description":"Storage features","type":"boolean"},"enable_sse":{"type":"boolean"},"enable_tracing":{"type":"boolean"},"enable_tray":{"type":"boolean"},"enable_web_ui":{"description":"UI features","type":"boolean"}},"type":"object"},"config.IntentDeclarationConfig":{"description":"Intent declaration settings (Spec 018)","properties":{"strict_server_validation":{"description":"StrictServerValidation controls whether server annotation mismatches\ncause rejection (true) or just warnings (false).\nDefault: true (reject mismatches)","type":"boolean"}},"type":"object"},"config.IsolationConfig":{"description":"Per-server isolation settings","properties":{"enabled":{"description":"Enable Docker isolation for this server (nil = inherit global; legacy, superseded by Mode)","type":"boolean"},"extra_args":{"description":"Additional docker run arguments for this server","items":{"type":"string"},"type":"array","uniqueItems":false},"image":{"description":"Custom Docker image (overrides default)","type":"string"},"log_driver":{"description":"Docker log driver override for this server","type":"string"},"log_max_files":{"description":"Maximum number of log files override","type":"string"},"log_max_size":{"description":"Maximum size of log files override","type":"string"},"mode":{"$ref":"#/components/schemas/config.IsolationMode"},"network_mode":{"description":"Custom network mode for this server","type":"string"},"working_dir":{"description":"Custom working directory in container","type":"string"}},"type":"object"},"config.IsolationMode":{"description":"Isolation mode: \"docker\" | \"sandbox\" | \"none\" (MCP-34.2). Unset per-server inherits the global mode; unset globally falls back to the legacy \"enabled\" flag (true ⇒ docker, false ⇒ none)","type":"string","x-enum-varnames":["IsolationModeDocker","IsolationModeSandbox","IsolationModeNone"]},"config.LogConfig":{"description":"Logging configuration","properties":{"compress":{"type":"boolean"},"enable_console":{"type":"boolean"},"enable_file":{"type":"boolean"},"filename":{"type":"string"},"json_format":{"type":"boolean"},"level":{"type":"string"},"log_dir":{"description":"Custom log directory","type":"string"},"max_age":{"description":"days","type":"integer"},"max_backups":{"description":"number of backup files","type":"integer"},"max_size":{"description":"MB","type":"integer"}},"type":"object"},"config.MetricsExporterConfig":{"description":"Metrics gates the Prometheus /metrics scrape endpoint (MCP-32). Disabled\nby default — operators opt in for k8s/enterprise deployments.","properties":{"enabled":{"description":"Enabled exposes /metrics on the existing HTTP listener when true.","type":"boolean"}},"type":"object"},"config.OAuthConfig":{"description":"OAuth configuration (keep even when empty to signal OAuth requirement)","properties":{"client_id":{"type":"string"},"client_secret":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"description":"Additional OAuth parameters (e.g., RFC 8707 resource)","type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_uri":{"type":"string"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ObservabilityConfig":{"description":"Observability settings (Spec 069): usage aggregate cache/persistence cadence.","properties":{"metrics":{"$ref":"#/components/schemas/config.MetricsExporterConfig"},"tracing":{"$ref":"#/components/schemas/config.TracingExporterConfig"},"usage_cache_ttl":{"description":"UsageCacheTTL bounds the freshness of the usage endpoint's read cache for\nwide windows (FR-005). Default 5s.","type":"string"},"usage_persist_interval":{"description":"UsagePersistInterval is how often the actor-owned usage aggregate snapshot\nis flushed to storage. Default 30s.","type":"string"}},"type":"object"},"config.OutputSanitisationConfig":{"description":"Output sanitisation settings (Spec 054 Track B)","properties":{"max_redactions":{"description":"cap on redactions per response; default 100","type":"integer"},"response_action":{"description":"\"spotlight\" | \"redact\" | \"block\"; default \"spotlight\"","type":"string"},"spotlight_untrusted":{"description":"wrap untrusted output in spotlight markers; default true","type":"boolean"},"strip_classes":{"description":"classes to strip: ansi/c0c1/bidi/zero_width","items":{"type":"string"},"type":"array","uniqueItems":false},"strip_control_chars":{"description":"strip control-character classes; default false","type":"boolean"}},"type":"object"},"config.OutputValidationConfig":{"description":"Output-schema validation settings (Spec 056)","properties":{"max_bytes":{"description":"structured payload byte cap; default 5\u003c\u003c20","type":"integer"},"max_depth":{"description":"nesting depth cap; default 64","type":"integer"},"missing_structured_content":{"description":"\"allow\" | \"block\"; default \"allow\"","type":"string"},"mode":{"description":"\"off\" | \"warn\" | \"strict\"; default \"warn\"","type":"string"}},"type":"object"},"config.ProfileConfig":{"properties":{"name":{"description":"URL slug, validated","type":"string"},"servers":{"description":"references to mcpServers[].name","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.RegistryEntry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag for this registry (MCP-866):\nRegistryProvenanceOfficial for built-in defaults, RegistryProvenanceCustom\nfor user-added registries. It is authoritatively (re)computed by the\nregistries merge from whether the ID is a shipped default — a user cannot\nclaim \"official\" by writing it into their config.","type":"string"},"requires_key":{"description":"RequiresKey marks a registry that needs an API key to be queried. When\ntrue and no key is configured, the registry is skipped/marked unavailable\nrather than failing the whole search (FR-008).","type":"boolean"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"url":{"type":"string"}},"type":"object"},"config.SecurityConfig":{"description":"Security scanner settings (Spec 039)","properties":{"deep_scan":{"$ref":"#/components/schemas/config.DeepScanConfig"},"integrity_check_interval":{"type":"string"},"integrity_check_on_restart":{"type":"boolean"},"runtime_read_only":{"type":"boolean"},"runtime_tmpfs_size":{"type":"string"},"scan_timeout_default":{"type":"string"},"scanner_disable_no_new_privileges":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.DisableNoNewPrivileges\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.IsDisableNoNewPrivileges. Cleared after migration.\n\nScannerDisableNoNewPrivileges, when true, omits the\n` + "`" + `--security-opt no-new-privileges` + "`" + ` flag from scanner container runs.\n\nBackground: snap-installed Docker on Ubuntu confines dockerd under the\n` + "`" + `snap.docker.dockerd` + "`" + ` AppArmor profile. When runc tries to transition\nthe container into the inner ` + "`" + `docker-default` + "`" + ` profile to exec the\nentrypoint, AppArmor refuses the transition because NO_NEW_PRIVS\nforbids privilege/profile changes on exec — the result is EPERM\n(\"operation not permitted\") and every scanner fails immediately.\n\nSet this to true ONLY on hosts hitting that incompatibility. Scanner\ncontainers still run with read-only rootfs, tmpfs /tmp, no-network by\ndefault, and read-only source mounts, so the marginal isolation loss\nis small. The preferred fix remains replacing snap docker with a\ndistro-packaged docker.","type":"boolean"},"scanner_fetch_package_source":{"description":"Deprecated (Spec 077 US3): migrated on load into DeepScan.FetchPackageSource\n(see migrateDeepScanConfig). Retained only so existing configs that still carry\nthe top-level key parse; consumers MUST read the effective value via\nSecurityConfig.EffectiveFetchPackageSource. Cleared after migration.\n\nScannerFetchPackageSource controls whether the scanner fetches the\nPUBLISHED source of package-runner servers (npx/uvx) — without executing\nit — when no local source is available (no Docker container, no local\npackage cache, no working_dir). This is the primary quarantine/scan\ntarget: a quarantined-on-add server is never run locally, so without this\nthe scan degrades to tool-definitions-only (no real source-level\nanalysis). See MCP-2206.\n\nFetching uses ` + "`" + `npm pack --ignore-scripts` + "`" + ` (npm) and ` + "`" + `uv pip download` + "`" + ` /\n` + "`" + `pip download` + "`" + ` with ` + "`" + `--only-binary=:all:` + "`" + ` (Python), which only download +\nunpack archives and NEVER run install, build, or setup.py — a scanner must\nnot execute the untrusted code it is scanning. The Python\n` + "`" + `--only-binary=:all:` + "`" + ` flag is required because downloading an sdist would\ninvoke its build backend (setup.py); packages with no wheel fall back to\ntool-definitions-only instead. Extraction is hardened against path\ntraversal and decompression bombs.\n\nDefault (nil) is ENABLED. Set to false on air-gapped deployments to\nforbid the scanner's network egress; such servers then fall back to the\ntool-definitions-only scan with no regression.","type":"boolean"},"scanner_registry_url":{"type":"string"}},"type":"object"},"config.SensitiveDataDetectionConfig":{"description":"Sensitive data detection settings (Spec 026)","properties":{"categories":{"additionalProperties":{"type":"boolean"},"description":"Enable/disable specific detection categories","type":"object"},"custom_patterns":{"description":"User-defined detection patterns","items":{"$ref":"#/components/schemas/config.CustomPattern"},"type":"array","uniqueItems":false},"enabled":{"description":"Enable sensitive data detection (default: true)","type":"boolean"},"entropy_threshold":{"description":"Shannon entropy threshold for high-entropy detection (default: 4.5)","type":"number"},"max_payload_size_kb":{"description":"Max size to scan before truncating (default: 1024)","type":"integer"},"scan_requests":{"description":"Scan tool call arguments (default: true)","type":"boolean"},"scan_responses":{"description":"Scan tool responses (default: true)","type":"boolean"},"sensitive_keywords":{"description":"Keywords to flag","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"config.ServerConfig":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve tool\nchanges/additions (disabling per-server rug-pull protection). Supersedes\nskip_quarantine. MCP-2930 only ACCEPTS, persists, and migrates this flag — it\nis NOT yet consulted at runtime; auto-approval is still governed by\nSkipQuarantine until the trust-baseline behavior change (MCP-2931) migrates the\nruntime consumers onto it.\nTri-state pointer (mirrors QuarantineEnabled): nil = unset (inherit/migrate\nfrom legacy skip_quarantine), explicit true/false = honored as-is so an\nexplicit auto_approve_tool_changes:false overrides a legacy skip_quarantine:true.\nRead via IsAutoApproveToolChanges().","type":"boolean"},"command":{"type":"string"},"created":{"type":"string"},"disabled_tools":{"description":"Denylist: these tools are hidden; mutually exclusive with enabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"enabled":{"type":"boolean"},"enabled_tools":{"description":"Allowlist: only these tools are exposed; mutually exclusive with disabled_tools","items":{"type":"string"},"type":"array","uniqueItems":false},"env":{"additionalProperties":{"type":"string"},"type":"object"},"headers":{"additionalProperties":{"type":"string"},"description":"For HTTP servers","type":"object"},"health_check_interval":{"description":"Per-server discovery \u0026 health-check overrides (spec 074). Same *Duration\ntri-state as the global keys: nil = inherit the global value (or default),\npointer to 0s = disabled for this server, positive = that interval.\nHealthCheckInterval is fully wired into the per-server health loop;\nToolDiscoveryInterval is accepted/validated and round-trips for\nforward-compat, but the periodic index sweep is governed by the global\ncadence in this iteration (see spec 074 plan §C).","type":"string"},"init_timeout":{"description":"InitTimeout overrides the global init_timeout for this server's MCP\n` + "`" + `initialize` + "`" + ` handshake deadline (MCP-3322 / GH #760). *Duration tri-state:\nnil = inherit the global value (or 30s default), positive = that deadline.\nResolved by Config.ResolveInitTimeout; validated to {0} ∪ [1s, 30m]. Raise\nthis for upstreams that do legitimate first-run warmup (e.g. caching many\nchannels/users) before responding to ` + "`" + `initialize` + "`" + `.","type":"string"},"isolation":{"$ref":"#/components/schemas/config.IsolationConfig"},"launcher_wait_timeout":{"description":"LauncherWaitTimeout caps how long mcpproxy will wait for a locally-launched\nHTTP/SSE upstream's URL to become reachable after Spawn(). Only consulted\nwhen the server is configured with both Command and an HTTP/SSE URL — i.e.,\nmcpproxy starts the process AND connects via network. Stdio servers ignore\nthis field. Zero or unset → 30s default.","type":"string"},"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":"SkipQuarantine is DEPRECATED (MCP-2930): use AutoApproveToolChanges instead.\nKept for back-compat parsing; on config load a legacy skip_quarantine:true is\nmigrated to auto_approve_tool_changes:true only when the new field is unset\n(see normalizeServerQuarantineFlags).","type":"boolean"},"source_registry_id":{"description":"SourceRegistryID records which registry this server was added from (empty\nfor manually-configured servers). MCP-866: surfaced in the approval /\nquarantine view so a reviewer can see a server's origin.","type":"string"},"source_registry_provenance":{"description":"SourceRegistryProvenance records the source registry's provenance at add\ntime (RegistryProvenanceOfficial / RegistryProvenanceCustom). It is purely\ninformational (MCP-1072) — surfaced so a reviewer can see a server's origin\n— and no longer gates quarantine or skip_quarantine.","type":"string"},"tool_discovery_interval":{"type":"string"},"toon_output":{"description":"ToonOutput overrides the global toon_output mode for this server's\ntools (spec 084, FR-001). Plain string, not a pointer: \"\"/absent =\ninherit the global value; \"off\"|\"adaptive\"|\"always\" = override (\"off\"\nis the explicit force-off). Resolved by Config.ResolveToonOutput.","type":"string"},"trust_mode":{"description":"TrustMode is the per-server trust tier: auto|scan|manual. Supersedes\nauto_approve_tool_changes (spec 086). An empty value is derived from the\nlegacy fields at load via normalizeServerQuarantineFlags; the single\nresolution point is EffectiveTrustMode(), which treats an empty or\nunrecognized value as manual (secure by default). Read via\nEffectiveTrustMode(), never the raw string.","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"working_dir":{"description":"Working directory for stdio servers","type":"string"}},"type":"object"},"config.TLSConfig":{"description":"TLS configuration","properties":{"certs_dir":{"description":"Directory for certificates","type":"string"},"enabled":{"description":"Enable HTTPS","type":"boolean"},"hsts":{"description":"Enable HTTP Strict Transport Security","type":"boolean"},"require_client_cert":{"description":"Enable mTLS","type":"boolean"}},"type":"object"},"config.TelemetryConfig":{"description":"Telemetry settings (Spec 036)","properties":{"anonymous_id":{"description":"Auto-generated UUIDv4","type":"string"},"anonymous_id_created_at":{"description":"Spec 042 (Tier 2) additions — all default-zero, all backwards-compatible.","type":"string"},"enabled":{"description":"Default: true (opt-out)","type":"boolean"},"endpoint":{"description":"Override for testing","type":"string"},"last_reported_version":{"description":"Upgrade funnel","type":"string"},"last_startup_outcome":{"description":"success|port_conflict|db_locked|...","type":"string"},"notice_shown":{"description":"First-run notice flag","type":"boolean"}},"type":"object"},"config.TokenizerConfig":{"description":"Tokenizer configuration for token counting","properties":{"default_model":{"description":"Default model for tokenization (e.g., \"gpt-4\")","type":"string"},"enabled":{"description":"Enable token counting","type":"boolean"},"encoding":{"description":"Default encoding (e.g., \"cl100k_base\")","type":"string"}},"type":"object"},"config.TracingExporterConfig":{"description":"Tracing gates the OpenTelemetry OTLP trace exporter (MCP-32). Disabled by\ndefault.","properties":{"enabled":{"description":"Enabled turns on OTLP trace export for tool calls and upstream hops.","type":"boolean"},"endpoint":{"description":"Endpoint is the collector address as host:port (no scheme), e.g.\n\"localhost:4318\" for http or \"localhost:4317\" for grpc.","type":"string"},"protocol":{"description":"Protocol selects the OTLP transport: \"http\" or \"grpc\".","type":"string"},"sample_rate":{"description":"SampleRate is the head-based trace sampling ratio in [0,1]. Default 0.1.","type":"number"}},"type":"object"},"config.UpdateCheckConfig":{"description":"Update-check settings (Spec 079 FR-012): config-file control of the\nbackground upgrade-awareness checker (internal/updatecheck). nil =\nenabled on the stable channel (existing default behavior). The existing\nenvironment switches keep working and WIN over these keys (FR-014):\nMCPPROXY_DISABLE_AUTO_UPDATE=true force-disables even when\nenabled=true, and MCPPROXY_ALLOW_PRERELEASE_UPDATES=true force-selects\nthe rc channel even when channel=stable.","properties":{"channel":{"description":"Channel selects which releases are offered as updates: \"stable\"\n(default; prereleases never offered) or \"rc\" (prereleases included).\nEmpty resolves to stable. Validated in ValidateDetailed.","type":"string"},"enabled":{"description":"Enabled gates all update checking. Tri-state: nil/absent = enabled\n(default true, matching pre-079 behavior). When false, no network\ncheck is performed and no upgrade nudge appears on any surface\n(FR-015) — /api/v1/info omits the update object entirely.","type":"boolean"}},"type":"object"},"configimport.FailedServer":{"properties":{"details":{"type":"string"},"error":{"type":"string"},"name":{"type":"string"}},"type":"object"},"configimport.ImportSummary":{"properties":{"failed":{"type":"integer"},"imported":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"configimport.SkippedServer":{"properties":{"name":{"type":"string"},"reason":{"description":"\"already_exists\", \"filtered_out\", \"invalid_name\"","type":"string"}},"type":"object"},"connect.ConnectResult":{"description":"The full result; its action mirrors the top-level one","properties":{"action":{"description":"\"created\", \"updated\", \"already_exists\", \"removed\", \"not_found\"","type":"string"},"backup_path":{"type":"string"},"client":{"type":"string"},"config_path":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.APIResponse":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ActivityDetailResponse":{"properties":{"activity":{"$ref":"#/components/schemas/contracts.ActivityRecord"}},"type":"object"},"contracts.ActivityListResponse":{"properties":{"activities":{"items":{"$ref":"#/components/schemas/contracts.ActivityRecord"},"type":"array","uniqueItems":false},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.ActivityRecord":{"properties":{"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 transport session ID (regenerated on every reconnect)","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"},"work_session_id":{"description":"Spec 082: one client, one project, across reconnects","type":"string"}},"type":"object"},"contracts.ActivitySource":{"description":"How activity was triggered: \"mcp\", \"cli\", \"api\"","type":"string","x-enum-varnames":["ActivitySourceMCP","ActivitySourceCLI","ActivitySourceAPI"]},"contracts.ActivitySummaryResponse":{"properties":{"blocked_count":{"description":"Count of blocked activities","type":"integer"},"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.AddFromRegistryRequest":{"properties":{"enabled":{"description":"defaults to true when nil","type":"boolean"},"env":{"additionalProperties":{"type":"string"},"description":"overrides + required-input values","type":"object"},"name":{"description":"optional name override","type":"string"}},"type":"object"},"contracts.AddRegistrySourceRequest":{"properties":{"id":{"description":"derived from the host when empty","type":"string"},"name":{"description":"defaults to the id","type":"string"},"protocol":{"description":"defaults to modelcontextprotocol/registry","type":"string"},"url":{"description":"required https registry URL","type":"string"}},"type":"object"},"contracts.ConfigApplyResult":{"properties":{"applied_immediately":{"type":"boolean"},"changed_fields":{"items":{"type":"string"},"type":"array","uniqueItems":false},"requires_restart":{"type":"boolean"},"restart_reason":{"type":"string"},"success":{"type":"boolean"},"validation_errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DCRStatus":{"properties":{"attempted":{"type":"boolean"},"error":{"type":"string"},"status_code":{"type":"integer"},"success":{"type":"boolean"}},"type":"object"},"contracts.DeepScanDescriptor":{"description":"DeepScan reports the opt-in \"deep scan\" layer status (Spec 077 US3),\nSEPARATELY from the baseline verdict above. Always emitted on a computed\nsummary — when deep scan is off (the default) it reports enabled=false\nplus any enabled-but-skipped Docker scanners. It never influences Status.","properties":{"available":{"type":"boolean"},"enabled":{"type":"boolean"},"ran":{"type":"boolean"},"scanners_failed":{"items":{"$ref":"#/components/schemas/contracts.DeepScanScannerFailure"},"type":"array","uniqueItems":false},"skipped_scanners":{"description":"SkippedScanners lists Docker scanners the user enabled that are skipped\nbecause security.deep_scan.enabled is false (informational).","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DeepScanScannerFailure":{"properties":{"id":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"contracts.DeprecatedConfigWarning":{"properties":{"field":{"type":"string"},"message":{"type":"string"},"replacement":{"type":"string"}},"type":"object"},"contracts.Diagnostic":{"description":"Spec 044 — structured diagnostic error and stable error code. Both\nare populated when the server is in a failed state and the error\nhas been classified by internal/diagnostics. Healthy servers omit\nthese fields.","properties":{"cause":{"type":"string"},"code":{"type":"string"},"detected_at":{"type":"string"},"docs_url":{"type":"string"},"fix_steps":{"items":{"$ref":"#/components/schemas/contracts.DiagnosticFixStep"},"type":"array","uniqueItems":false},"severity":{"type":"string"},"user_message":{"type":"string"}},"type":"object"},"contracts.DiagnosticFixStep":{"properties":{"command":{"type":"string"},"destructive":{"type":"boolean"},"fixer_key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"}},"type":"object"},"contracts.Diagnostics":{"properties":{"deprecated_configs":{"description":"Deprecated config fields found","items":{"$ref":"#/components/schemas/contracts.DeprecatedConfigWarning"},"type":"array","uniqueItems":false},"docker_status":{"$ref":"#/components/schemas/contracts.DockerStatus"},"missing_secrets":{"description":"Renamed to avoid conflict","items":{"$ref":"#/components/schemas/contracts.MissingSecretInfo"},"type":"array","uniqueItems":false},"oauth_issues":{"description":"OAuth parameter mismatches","items":{"$ref":"#/components/schemas/contracts.OAuthIssue"},"type":"array","uniqueItems":false},"oauth_required":{"items":{"$ref":"#/components/schemas/contracts.OAuthRequirement"},"type":"array","uniqueItems":false},"runtime_warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false},"timestamp":{"type":"string"},"total_issues":{"type":"integer"},"upstream_errors":{"items":{"$ref":"#/components/schemas/contracts.UpstreamError"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.DockerStatus":{"properties":{"available":{"type":"boolean"},"error":{"type":"string"},"version":{"type":"string"}},"type":"object"},"contracts.EditRegistrySourceRequest":{"properties":{"name":{"description":"new display name","type":"string"},"servers_url":{"description":"explicit servers-collection URL","type":"string"},"url":{"description":"new base/servers https URL","type":"string"}},"type":"object"},"contracts.ErrorResponse":{"properties":{"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.FindingCounts":{"properties":{"dangerous":{"description":"Tool poisoning, active prompt injection","type":"integer"},"info":{"description":"Low-severity CVEs, informational","type":"integer"},"total":{"type":"integer"},"warning":{"description":"Rug pull, supply chain CVEs with exploits","type":"integer"}},"type":"object"},"contracts.GetConfigResponse":{"properties":{"config":{"description":"The configuration object","type":"object"},"config_path":{"description":"Path to config file","type":"string"}},"type":"object"},"contracts.GetRegistriesResponse":{"properties":{"registries":{"items":{"$ref":"#/components/schemas/contracts.Registry"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerLogsResponse":{"properties":{"count":{"type":"integer"},"logs":{"items":{"$ref":"#/components/schemas/contracts.LogEntry"},"type":"array","uniqueItems":false},"server_name":{"type":"string"}},"type":"object"},"contracts.GetServerToolCallsResponse":{"properties":{"server_name":{"type":"string"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetServerToolsResponse":{"properties":{"count":{"type":"integer"},"server_name":{"type":"string"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GetServersResponse":{"properties":{"servers":{"items":{"$ref":"#/components/schemas/contracts.Server"},"type":"array","uniqueItems":false},"stats":{"$ref":"#/components/schemas/contracts.ServerStats"}},"type":"object"},"contracts.GetSessionDetailResponse":{"properties":{"session":{"$ref":"#/components/schemas/contracts.MCPSession"}},"type":"object"},"contracts.GetSessionsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"sessions":{"items":{"$ref":"#/components/schemas/contracts.MCPSession"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GetToolCallDetailResponse":{"properties":{"tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"}},"type":"object"},"contracts.GetToolCallsResponse":{"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"tool_calls":{"items":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"type":"array","uniqueItems":false},"total":{"type":"integer"}},"type":"object"},"contracts.GlobalToolsResponse":{"properties":{"failed_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"partial":{"type":"boolean"},"stats":{"$ref":"#/components/schemas/contracts.GlobalToolsStats"},"tools":{"items":{"$ref":"#/components/schemas/contracts.Tool"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.GlobalToolsStats":{"properties":{"disabled":{"type":"integer"},"enabled":{"type":"integer"},"pending_approval":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"contracts.HealthStatus":{"description":"Unified health status calculated by the backend","properties":{"action":{"description":"Action is the suggested fix action: \"login\", \"restart\", \"enable\", \"approve\", \"view_logs\", \"set_secret\", \"configure\", 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"},"work_session_id":{"type":"string"},"workspace_name":{"description":"Workspace / work session (Spec 082). WorkspaceName is the project's\nbasename — the full local path is never exposed. WorkSessionID groups the\nreconnects that make up one stretch of user work.","type":"string"}},"type":"object"},"contracts.MetadataStatus":{"properties":{"authorization_servers":{"items":{"type":"string"},"type":"array","uniqueItems":false},"error":{"type":"string"},"found":{"type":"boolean"},"url_checked":{"type":"string"}},"type":"object"},"contracts.MissingSecretInfo":{"properties":{"secret_name":{"type":"string"},"used_by":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"contracts.NPMPackageInfo":{"properties":{"exists":{"type":"boolean"},"install_cmd":{"type":"string"}},"type":"object"},"contracts.OAuthConfig":{"properties":{"auth_url":{"type":"string"},"client_id":{"type":"string"},"extra_params":{"additionalProperties":{"type":"string"},"type":"object"},"pkce_enabled":{"type":"boolean"},"redirect_port":{"type":"integer"},"scopes":{"items":{"type":"string"},"type":"array","uniqueItems":false},"token_expires_at":{"description":"When the OAuth token expires","type":"string"},"token_url":{"type":"string"},"token_valid":{"description":"Whether token is currently valid","type":"boolean"}},"type":"object"},"contracts.OAuthErrorDetails":{"description":"Structured discovery/failure details","properties":{"authorization_server_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"dcr_status":{"$ref":"#/components/schemas/contracts.DCRStatus"},"protected_resource_metadata":{"$ref":"#/components/schemas/contracts.MetadataStatus"},"server_url":{"type":"string"}},"type":"object"},"contracts.OAuthFlowError":{"properties":{"correlation_id":{"description":"Flow tracking ID for log correlation","type":"string"},"debug_hint":{"description":"CLI command for log lookup","type":"string"},"details":{"$ref":"#/components/schemas/contracts.OAuthErrorDetails"},"error_code":{"description":"Machine-readable error code (e.g., OAUTH_NO_METADATA)","type":"string"},"error_type":{"description":"Category of OAuth runtime failure","type":"string"},"message":{"description":"Human-readable error description","type":"string"},"request_id":{"description":"HTTP request ID (from PR #237)","type":"string"},"server_name":{"description":"Server that failed OAuth","type":"string"},"success":{"description":"Always false","type":"boolean"},"suggestion":{"description":"Actionable remediation hint","type":"string"}},"type":"object"},"contracts.OAuthIssue":{"properties":{"documentation_url":{"type":"string"},"error":{"type":"string"},"issue":{"type":"string"},"missing_params":{"items":{"type":"string"},"type":"array","uniqueItems":false},"resolution":{"type":"string"},"server_name":{"type":"string"}},"type":"object"},"contracts.OAuthRequirement":{"properties":{"expires_at":{"type":"string"},"message":{"type":"string"},"server_name":{"type":"string"},"state":{"type":"string"}},"type":"object"},"contracts.OAuthStartResponse":{"properties":{"auth_url":{"description":"Authorization URL (always included for manual use)","type":"string"},"browser_error":{"description":"Error message if browser launch failed","type":"string"},"browser_opened":{"description":"Whether browser launch succeeded","type":"boolean"},"correlation_id":{"description":"UUID for tracking this flow","type":"string"},"message":{"description":"Human-readable status message","type":"string"},"server_name":{"description":"Name of the server being authenticated","type":"string"},"success":{"description":"Always true for successful start","type":"boolean"}},"type":"object"},"contracts.QuarantineStats":{"description":"Tool quarantine metrics for this server","properties":{"blocked_count":{"description":"Number of disabled (blocked) tools","type":"integer"},"changed_count":{"description":"Number of tools whose description/schema changed since approval","type":"integer"},"pending_count":{"description":"Number of newly discovered tools awaiting approval","type":"integer"}},"type":"object"},"contracts.RefreshRegistryResponse":{"properties":{"cleared":{"description":"number of cached entries dropped","type":"integer"},"registry_id":{"type":"string"}},"type":"object"},"contracts.Registry":{"properties":{"count":{"description":"number or string","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"protocol":{"type":"string"},"provenance":{"description":"Provenance is the trust tag (MCP-866): \"official/trusted\" for built-in\ndefaults, \"custom/unverified\" for user-added registries.","type":"string"},"servers_url":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array","uniqueItems":false},"trusted":{"description":"Trusted indicates whether this is an official, shipped-by-default\nregistry. Trust is derived from membership in the default set, never\nfrom self-assertion in config.","type":"boolean"},"url":{"type":"string"}},"type":"object"},"contracts.RegistryCacheInfo":{"properties":{"age_seconds":{"type":"number"},"stale":{"type":"boolean"}},"type":"object"},"contracts.RegistryUnavailable":{"properties":{"reason":{"type":"string"}},"type":"object"},"contracts.ReplayToolCallRequest":{"properties":{"arguments":{"description":"Modified arguments for replay","type":"object"}},"type":"object"},"contracts.ReplayToolCallResponse":{"properties":{"error":{"description":"Error if replay failed","type":"string"},"new_call_id":{"description":"ID of the newly created call","type":"string"},"new_tool_call":{"$ref":"#/components/schemas/contracts.ToolCallRecord"},"replayed_from":{"description":"Original call ID","type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.RepositoryInfo":{"description":"Detected package info","properties":{"npm":{"$ref":"#/components/schemas/contracts.NPMPackageInfo"}},"type":"object"},"contracts.RepositoryServer":{"properties":{"connect_url":{"description":"Alternative connection URL","type":"string"},"created_at":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"install_cmd":{"description":"Installation command","type":"string"},"name":{"type":"string"},"registry":{"description":"Which registry this came from","type":"string"},"repository_info":{"$ref":"#/components/schemas/contracts.RepositoryInfo"},"source_code_url":{"description":"Source repository URL","type":"string"},"updated_at":{"type":"string"},"url":{"description":"MCP endpoint for remote servers only","type":"string"}},"type":"object"},"contracts.SearchRegistryServersResponse":{"properties":{"cache":{"$ref":"#/components/schemas/contracts.RegistryCacheInfo"},"query":{"type":"string"},"registry_id":{"type":"string"},"servers":{"items":{"$ref":"#/components/schemas/contracts.RepositoryServer"},"type":"array","uniqueItems":false},"tag":{"type":"string"},"total":{"type":"integer"},"unavailable":{"$ref":"#/components/schemas/contracts.RegistryUnavailable"}},"type":"object"},"contracts.SearchResult":{"properties":{"matches":{"type":"integer"},"score":{"type":"number"},"snippet":{"type":"string"},"tool":{"$ref":"#/components/schemas/contracts.Tool"}},"type":"object"},"contracts.SearchToolsResponse":{"properties":{"query":{"type":"string"},"results":{"items":{"$ref":"#/components/schemas/contracts.SearchResult"},"type":"array","uniqueItems":false},"took":{"type":"string"},"total":{"type":"integer"}},"type":"object"},"contracts.SecurityScanSummary":{"description":"Latest security scan results summary","properties":{"deep_scan":{"$ref":"#/components/schemas/contracts.DeepScanDescriptor"},"finding_counts":{"$ref":"#/components/schemas/contracts.FindingCounts"},"last_scan_at":{"type":"string"},"risk_score":{"description":"0-100","type":"integer"},"scanners_failed":{"type":"integer"},"scanners_run":{"description":"Scanner coverage for the primary (baseline) scan pass — informational only.\nSpec 077 US3 (FR-008/FR-014): Status is derived SOLELY from the\ndeterministic baseline findings; a failed Docker deep scanner no longer\ndowngrades a clean verdict. That failure is surfaced via DeepScan instead.","type":"integer"},"scanners_total":{"type":"integer"},"status":{"description":"\"clean\", \"warnings\", \"dangerous\", \"failed\", \"not_scanned\", \"scanning\"","type":"string"}},"type":"object"},"contracts.Server":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"authenticated":{"description":"OAuth authentication status","type":"boolean"},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges mirrors config.ServerConfig.AutoApproveToolChanges\n(MCP-2930): the per-server intent to auto-approve new/changed tools past\nthe trust baseline. Tri-state *bool — nil means \"never set\" (omitted from\nthe payload), so the Web UI toggle (MCP-2932) can distinguish unset from\nan explicit false. Read-only on the GET path; PATCH/POST accept it via\nAddServerRequest.","type":"boolean"},"command":{"type":"string"},"connected":{"type":"boolean"},"connected_at":{"type":"string"},"connecting":{"type":"boolean"},"created":{"type":"string"},"diagnostic":{"$ref":"#/components/schemas/contracts.Diagnostic"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"error_code":{"type":"string"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"health":{"$ref":"#/components/schemas/contracts.HealthStatus"},"id":{"type":"string"},"init_timeout":{"description":"InitTimeout mirrors config.ServerConfig.InitTimeout (MCP-3322 / GH #760):\nthe per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override. Serialized as\na duration string (e.g. \"120s\"); nil/omitted means \"inherit the global\ndefault\". Surfaced on the GET path so clients can read back a configured\noverride; PATCH/POST accept it via AddServerRequest.","type":"string"},"isolation":{"$ref":"#/components/schemas/contracts.IsolationConfig"},"isolation_defaults":{"$ref":"#/components/schemas/contracts.IsolationDefaults"},"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"},"source_registry_id":{"description":"MCP-901 — registry provenance of an upstream that was added from a\nregistry. SourceRegistryID names the source registry (empty for\nmanually-configured servers); SourceRegistryProvenance is the trust tag\nrecorded at add time (\"official/trusted\" or \"custom/unverified\"). Both\nare projected from config.ServerConfig so the approval/quarantine view\ncan render an \"added from \u003cregistry\u003e · unverified\" origin badge. Optional\nand omitted when empty — clients that pre-date this treat them as absent.","type":"string"},"source_registry_provenance":{"type":"string"},"status":{"type":"string"},"token_expires_at":{"description":"When the OAuth token expires (ISO 8601)","type":"string"},"tool_count":{"type":"integer"},"tool_list_token_size":{"description":"Token size for this server's tools","type":"integer"},"trust_mode":{"description":"TrustMode mirrors config.ServerConfig.TrustMode (spec 086): the per-server\ntrust tier (\"auto\"/\"scan\"/\"manual\"). Surfaced on the GET path so clients can\nread back the persisted mode; PATCH/POST accept it via AddServerRequest.\nOmitted when empty (server predates the field / relies on legacy flags).","type":"string"},"updated":{"type":"string"},"url":{"type":"string"},"user_logged_out":{"description":"True if user explicitly logged out (prevents auto-reconnection)","type":"boolean"},"working_dir":{"type":"string"}},"type":"object"},"contracts.ServerActionResponse":{"properties":{"action":{"type":"string"},"async":{"type":"boolean"},"server":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"contracts.ServerStats":{"properties":{"connected_servers":{"type":"integer"},"docker_containers":{"type":"integer"},"quarantined_servers":{"type":"integer"},"token_metrics":{"$ref":"#/components/schemas/contracts.ServerTokenMetrics"},"total_servers":{"type":"integer"},"total_tools":{"type":"integer"}},"type":"object"},"contracts.ServerTokenMetrics":{"properties":{"average_query_result_size":{"description":"Typical retrieve_tools output (tokens)","type":"integer"},"per_server_tool_list_sizes":{"additionalProperties":{"type":"integer"},"description":"Token size per server","type":"object"},"saved_tokens":{"description":"Difference","type":"integer"},"saved_tokens_percentage":{"description":"Percentage saved","type":"number"},"total_server_tool_list_size":{"description":"All upstream tools combined (tokens)","type":"integer"}},"type":"object"},"contracts.SuccessResponse":{"properties":{"data":{"type":"object"},"success":{"type":"boolean"}},"type":"object"},"contracts.TokenMetrics":{"description":"Token usage metrics (nil for older records)","properties":{"encoding":{"description":"Encoding used (e.g., cl100k_base)","type":"string"},"estimated_cost":{"description":"Optional cost estimate","type":"number"},"input_tokens":{"description":"Tokens in the request","type":"integer"},"model":{"description":"Model used for tokenization","type":"string"},"output_tokens":{"description":"Tokens in the response","type":"integer"},"total_tokens":{"description":"Total tokens (input + output)","type":"integer"},"truncated_tokens":{"description":"Tokens removed by truncation","type":"integer"},"was_truncated":{"description":"Whether response was truncated","type":"boolean"}},"type":"object"},"contracts.Tool":{"properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"approval_status":{"type":"string"},"config_denied":{"description":"ConfigDenied is true when the tool is denied by the server's static\nenabled_tools / disabled_tools config. The user cannot override this toggle.","type":"boolean"},"description":{"type":"string"},"disabled":{"description":"Disabled mirrors ToolApprovalRecord.Disabled so per-tool enable state is\navailable without a second round-trip to the approvals endpoint. Absent\nin the JSON when false (default) to keep responses compact.","type":"boolean"},"held_reason":{"description":"HeldReason, HeldVerdict and HeldSignals mirror the same-named fields on\nstorage.ToolApprovalRecord: the offline-scan evidence that made\ntrust_mode: scan hold this tool for review (spec 086 FR-018). HeldSignals\nnames the matched deterministic check ids, e.g.\n\"tpa.TPA-2026-0001.hidden_instruction\", so a reviewer can see WHY the tool\nis held. All three are omitted for tools that are not held by the scan gate\n(including every record written before the field existed).","type":"string"},"held_signals":{"items":{"type":"string"},"type":"array","uniqueItems":false},"held_verdict":{"type":"string"},"last_used":{"type":"string"},"name":{"type":"string"},"schema":{"type":"object"},"server_name":{"type":"string"},"usage":{"type":"integer"}},"type":"object"},"contracts.ToolAnnotation":{"description":"Tool behavior hints snapshot","properties":{"destructiveHint":{"type":"boolean"},"idempotentHint":{"type":"boolean"},"openWorldHint":{"type":"boolean"},"readOnlyHint":{"type":"boolean"},"title":{"type":"string"}},"type":"object"},"contracts.ToolCallRecord":{"description":"The new tool call record","properties":{"annotations":{"$ref":"#/components/schemas/contracts.ToolAnnotation"},"arguments":{"description":"Tool arguments","type":"object"},"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"},"install_channel":{"description":"Detected install channel (homebrew, dmg, deb, rpm, docker, go-install, windows-installer, tarball, unknown) — Spec 079 FR-008","type":"string"},"is_prerelease":{"description":"Whether the latest version is a prerelease","type":"boolean"},"latest_version":{"description":"Latest version available (e.g., \"v1.2.3\")","type":"string"},"nudges_suppressed":{"description":"UI surfaces must stay quiet (CI / non-interactive context); machine-readable fields still report the facts — Spec 079 FR-019","type":"boolean"},"release_url":{"description":"URL to the release page","type":"string"},"update_command":{"description":"One-line update command for the channel; only set when an update is available and the channel has one — Spec 079 FR-009","type":"string"}},"type":"object"},"contracts.UpstreamError":{"properties":{"error_message":{"type":"string"},"server_name":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"contracts.UsageAggregateResponse":{"properties":{"freshness_ms":{"description":"age of the underlying snapshot in ms","type":"integer"},"generated_at":{"type":"string"},"other":{"$ref":"#/components/schemas/contracts.UsageOtherBucket"},"timeline":{"items":{"$ref":"#/components/schemas/contracts.UsageTimeBucket"},"type":"array","uniqueItems":false},"token_source":{"description":"\"bytes\" (size-based proxy, FR-006)","type":"string"},"tokens_saved":{"description":"echoed from ServerTokenMetrics (FR-007)","type":"integer"},"tokens_saved_percentage":{"type":"number"},"tools":{"items":{"$ref":"#/components/schemas/contracts.UsageToolStat"},"type":"array","uniqueItems":false},"window":{"type":"string"}},"type":"object"},"contracts.UsageOtherBucket":{"description":"present only when the list was truncated to top-N","properties":{"calls":{"type":"integer"},"tools_folded":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageTimeBucket":{"properties":{"calls":{"type":"integer"},"errors":{"type":"integer"},"start":{"type":"string"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.UsageToolStat":{"properties":{"avg_req_bytes":{"description":"null when no sized request calls","type":"integer"},"avg_resp_bytes":{"description":"null when sized_calls == 0 (only legacy 0-byte calls)","type":"integer"},"blocked":{"type":"integer"},"calls":{"type":"integer"},"error_rate":{"type":"number"},"errors":{"type":"integer"},"last_used":{"type":"string"},"p50_ms":{"type":"integer"},"p95_ms":{"type":"integer"},"server":{"type":"string"},"sized_calls":{"description":"calls with known response size (basis for avg_resp_bytes)","type":"integer"},"tool":{"type":"string"},"total_req_bytes":{"type":"integer"},"total_resp_bytes":{"type":"integer"}},"type":"object"},"contracts.ValidateConfigResponse":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/contracts.ValidationError"},"type":"array","uniqueItems":false},"valid":{"type":"boolean"}},"type":"object"},"contracts.ValidationError":{"properties":{"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"data":{"properties":{"data":{"$ref":"#/components/schemas/contracts.InfoResponse"}},"type":"object"},"httpapi.AddServerRequest":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"auto_approve_tool_changes":{"description":"AutoApproveToolChanges is the per-server intent to auto-approve\nnew/changed tools past the trust baseline (MCP-2930). Tri-state *bool:\na nil pointer means \"leave unchanged\" on PATCH; a present value\n(including false) is applied. Mirrors config.ServerConfig's *bool\nsemantics — do NOT collapse to a plain bool, or an omitted field would\nsilently reset a previously-set value.","type":"boolean"},"command":{"type":"string"},"enabled":{"type":"boolean"},"env":{"additionalProperties":{"type":"string"},"type":"object"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"init_timeout":{"description":"InitTimeout is the per-server MCP ` + "`" + `initialize` + "`" + ` handshake deadline override\n(MCP-3322 / GH #760), serialized as a duration string (e.g. \"120s\"). A nil\npointer means \"leave unchanged\" on PATCH; a present value is applied.\nMirrors config.ServerConfig.InitTimeout's *Duration tri-state.","type":"string"},"isolation":{"$ref":"#/components/schemas/httpapi.IsolationRequest"},"name":{"type":"string"},"protocol":{"type":"string"},"quarantined":{"type":"boolean"},"reconnect_on_use":{"type":"boolean"},"trust_mode":{"description":"TrustMode is the per-server trust tier (spec 086): \"auto\", \"scan\", or\n\"manual\". Empty means \"leave unchanged\" on PATCH (and inherit the migrated\ndefault on create). A non-empty value is applied to ServerConfig.TrustMode\nand resolved by EffectiveTrustMode (an unrecognized value fails closed to\nmanual). This is the REST seam for changing the trust tier via\nPOST/PATCH /api/v1/servers.","type":"string"},"url":{"type":"string"},"working_dir":{"type":"string"}},"type":"object"},"httpapi.CanonicalConfigPath":{"properties":{"description":{"description":"Brief description","type":"string"},"exists":{"description":"Whether the file exists","type":"boolean"},"format":{"description":"Format identifier (e.g., \"claude_desktop\")","type":"string"},"name":{"description":"Display name (e.g., \"Claude Desktop\")","type":"string"},"os":{"description":"Operating system (darwin, windows, linux)","type":"string"},"path":{"description":"Full path to the config file","type":"string"}},"type":"object"},"httpapi.CanonicalConfigPathsResponse":{"properties":{"os":{"description":"Current operating system","type":"string"},"paths":{"description":"List of canonical config paths","items":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPath"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ConnectConflictResponse":{"properties":{"action":{"description":"already_exists | precondition_failed","type":"string"},"data":{"$ref":"#/components/schemas/connect.ConnectResult"},"error":{"description":"Human-readable message","type":"string"},"success":{"description":"Always false","type":"boolean"}},"type":"object"},"httpapi.ConnectRequest":{"properties":{"force":{"description":"Overwrite existing entry","type":"boolean"},"precondition_token":{"description":"PreconditionToken is the opaque token from the preview this write was\nconfirmed against (Spec 091 FR-005). When present, the core rechecks it\nat write time and responds 409 with action \"precondition_failed\" —\nwriting nothing — if the config or the entry MCPProxy would write has\ndrifted since; the caller then re-previews instead of retrying. Absent\nmeans exactly the pre-091 behavior. A replace-classified flow sends this\nTOGETHER with force=true: the token, not the absence of force, is the\noverwrite safety.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"httpapi.ImportFromPathRequest":{"properties":{"format":{"description":"Optional format hint","type":"string"},"path":{"description":"File path to import from","type":"string"},"rename":{"additionalProperties":{"type":"string"},"description":"Rename maps a server name → new name. Applied after parsing so the\ncaller can disambiguate cross-source name collisions (Spec 046 v2 —\ne.g. \"mcpproxy\" → \"mcpproxy_claude_code\"). Keys are matched against\neither the raw source name (OriginalName) or the sanitized name shown\nin the preview (Server.Name); these differ for names that need\nsanitizing (e.g. \"Figma Desktop\" → \"Figma_Desktop\"). Keys not present\nin the imported set are ignored.","type":"object"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportRequest":{"properties":{"content":{"description":"Raw JSON or TOML content","type":"string"},"format":{"description":"Optional format hint","type":"string"},"server_names":{"description":"Optional: import only these servers","items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportResponse":{"properties":{"failed":{"items":{"$ref":"#/components/schemas/configimport.FailedServer"},"type":"array","uniqueItems":false},"format":{"type":"string"},"format_name":{"type":"string"},"imported":{"items":{"$ref":"#/components/schemas/httpapi.ImportedServerResponse"},"type":"array","uniqueItems":false},"skipped":{"items":{"$ref":"#/components/schemas/configimport.SkippedServer"},"type":"array","uniqueItems":false},"summary":{"$ref":"#/components/schemas/configimport.ImportSummary"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.ImportedServerResponse":{"properties":{"args":{"items":{"type":"string"},"type":"array","uniqueItems":false},"command":{"type":"string"},"fields_skipped":{"items":{"type":"string"},"type":"array","uniqueItems":false},"name":{"type":"string"},"original_name":{"type":"string"},"protocol":{"type":"string"},"source_format":{"type":"string"},"url":{"type":"string"},"warnings":{"items":{"type":"string"},"type":"array","uniqueItems":false}},"type":"object"},"httpapi.IsolationRequest":{"description":"Isolation carries per-server Docker isolation overrides (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. The stored enum is wider (Spec 080\nFR-001): a \"skipped\" request for a previously untouched connect step\nis upgraded server-side to \"completed_external\" when the install\nshows positive evidence of an external connection (Spec 080 FR-002).\n\"completed_external\" is NOT accepted from clients — it must never be\npersisted without that server-verified evidence (edge case: \"never\nguess completed_external without positive evidence\").","type":"string"},"engaged":{"description":"Engaged marks the wizard as engaged (completed or explicitly skipped).\nOnce true, the wizard does not auto-show again.","type":"boolean"},"mark_shown":{"description":"MarkShown records the wizard's first display time if not already set.","type":"boolean"},"server_step_status":{"description":"ServerStepStatus is one of: \"\", \"completed\", \"skipped\". Empty\npreserves the existing value.","type":"string"}},"type":"object"},"httpapi.SetActiveProfileRequest":{"properties":{"active_profile":{"type":"string"},"profile":{"type":"string"}},"type":"object"},"httpapi.UndoConnectRequest":{"properties":{"backup_name":{"description":"BackupName is the bare filename (filepath.Base) of the backup returned as\nbackup_path by the preceding connect — a name, never a path. Undo resolves\nthe full path server-side by joining it with the client's own config\ndirectory, so a client-supplied value can never contribute a directory\ncomponent (traversal is impossible by construction). Empty means the\nconnect created the file (no prior file existed), so undo removes it.","type":"string"},"server_name":{"description":"Defaults to \"mcpproxy\"","type":"string"}},"type":"object"},"management.BulkOperationResult":{"properties":{"errors":{"additionalProperties":{"type":"string"},"description":"Map of server name to error message","type":"object"},"failed":{"description":"Number of failed operations","type":"integer"},"successful":{"description":"Number of successful operations","type":"integer"},"total":{"description":"Total servers processed","type":"integer"}},"type":"object"},"observability.HealthResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"observability.HealthStatus":{"properties":{"error":{"type":"string"},"latency":{"type":"string"},"name":{"type":"string"},"status":{"description":"\"healthy\" or \"unhealthy\"","type":"string"}},"type":"object"},"observability.ReadinessResponse":{"properties":{"components":{"items":{"$ref":"#/components/schemas/observability.HealthStatus"},"type":"array","uniqueItems":false},"status":{"description":"\"ready\" or \"not_ready\"","type":"string"},"timestamp":{"type":"string"}},"type":"object"},"secureenv.EnvConfig":{"description":"Environment configuration for secure variable filtering","properties":{"allowed_system_vars":{"items":{"type":"string"},"type":"array","uniqueItems":false},"custom_vars":{"additionalProperties":{"type":"string"},"type":"object"},"enhance_path":{"description":"Enable PATH enhancement for Launchd scenarios","type":"boolean"},"forward_proxy_env":{"description":"ForwardProxyEnv opts in to forwarding the ambient HTTP(S)/ALL/NO/FTP proxy\nenvironment variables to spawned upstream servers (MCP-2769). It is OFF by\ndefault and deliberately kept out of the AllowedSystemVars default list:\nproxy URLs frequently carry credentials (http://user:pass@proxy), so\nforwarding them to every stdio upstream is a credential-leak risk. When\nenabled, values are forwarded with their userinfo (credentials) redacted.","type":"boolean"},"inherit_system_safe":{"type":"boolean"}},"type":"object"},"telemetry.FeedbackContext":{"properties":{"arch":{"type":"string"},"connected_server_count":{"type":"integer"},"edition":{"type":"string"},"os":{"type":"string"},"routing_mode":{"type":"string"},"server_count":{"type":"integer"},"version":{"type":"string"}},"type":"object"},"telemetry.FeedbackRequest":{"properties":{"category":{"description":"bug, feature, other","type":"string"},"context":{"$ref":"#/components/schemas/telemetry.FeedbackContext"},"email":{"type":"string"},"message":{"type":"string"}},"type":"object"},"telemetry.FeedbackResponse":{"properties":{"error":{"type":"string"},"issue_url":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"API key authentication via query parameter. Use ?apikey=your-key","in":"query","name":"apikey","type":"apiKey"}}},
     "info": {"contact":{"name":"MCPProxy Support","url":"https://github.com/smart-mcp-proxy/mcpproxy-go"},"description":"{{escape .Description}}","license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"},"title":"{{.Title}}","version":"{{.Version}}"},
     "externalDocs": {"description":"","url":""},
-    "paths": {"/api/v1/activity":{"get":{"description":"Returns paginated list of activity records with optional filtering","parameters":[{"description":"Filter by activity type(s), comma-separated for multiple (Spec 024)","in":"query","name":"type","schema":{"enum":["tool_call","policy_decision","quarantine_change","server_change","system_start","system_stop","internal_tool_call","config_change"],"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"enum":["success","error","blocked"],"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"}},{"description":"Omit arguments, response and metadata except a contextual whitelist (intent.reason, intent.operation_type, decision, reason, client_name, client_version) (default: false). For clients that render summary fields only; has_sensitive_data is still derived before metadata is dropped.","in":"query","name":"exclude_payloads","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"List activity records","tags":["Activity"]}},"/api/v1/activity/export":{"get":{"description":"Exports activity records in JSON Lines or CSV format for compliance","parameters":[{"description":"Export format: json (default) or csv","in":"query","name":"format","schema":{"type":"string"}},{"description":"Filter by activity type","in":"query","name":"type","schema":{"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"type":"string"}},{"description":"Filter activities after this time (RFC3339)","in":"query","name":"start_time","schema":{"type":"string"}},{"description":"Filter activities before this time (RFC3339)","in":"query","name":"end_time","schema":{"type":"string"}},{"description":"Maximum records to export (1-50000, default 10000)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Pagination offset (default 0)","in":"query","name":"offset","schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}}},"description":"Streamed activity records"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Export activity records","tags":["Activity"]}},"/api/v1/activity/summary":{"get":{"description":"Returns aggregated activity statistics for a time period","parameters":[{"description":"Time period: 1h, 24h (default), 7d, 30d","in":"query","name":"period","schema":{"type":"string"}},{"description":"Group by: server, tool (optional)","in":"query","name":"group_by","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity summary statistics","tags":["Activity"]}},"/api/v1/activity/usage":{"get":{"description":"Returns the actor-owned usage aggregate (per-tool rollup + timeline + tokens-saved headline) for the Web UI usage graphs (Spec 069). Served from an in-memory snapshot — never a per-request full-log scan. Per-tool metrics are lifetime-cumulative; ` + "`" + `window` + "`" + ` scopes the timeline and filters the tool list to tools active within the span.","parameters":[{"description":"Time window for timeline + tool-list membership","in":"query","name":"window","schema":{"enum":["24h","7d","all"],"type":"string"}},{"description":"Filter to one server","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter to one tool","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter to tools with activity of this status","in":"query","name":"status","schema":{"enum":["success","error","blocked"],"type":"string"}},{"description":"Top-N tools by sort key; remainder folded into 'other' (default 20)","in":"query","name":"top","schema":{"type":"integer"}},{"description":"Ranking key for the per-tool list","in":"query","name":"sort","schema":{"enum":["calls","resp_bytes","error_rate","p95"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get usage statistics aggregate","tags":["Activity"]}},"/api/v1/activity/{id}":{"get":{"description":"Returns full details for a single activity record","parameters":[{"description":"Activity record ID (ULID)","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Not Found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity record details","tags":["Activity"]}},"/api/v1/annotations/coverage":{"get":{"description":"Reports how many upstream tools have MCP annotations vs don't, broken down by server","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Annotation coverage report"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get annotation coverage report","tags":["annotations"]}},"/api/v1/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"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to read or apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update configuration","tags":["config"]}},"/api/v1/config/apply":{"post":{"description":"Applies a new MCPProxy configuration. Validates and persists the configuration to disk. Some changes apply immediately, while others may require a restart. Returns detailed information about applied changes and restart requirements.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to apply","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Configuration applied successfully with change details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Apply configuration","tags":["config"]}},"/api/v1/config/docker-isolation":{"patch":{"description":"Convenience endpoint to flip ` + "`" + `docker_isolation.enabled` + "`" + ` without resending the full config. Persists to disk via the existing config writer — the file watcher then hot-reloads the change. Returns the new state and whether a restart is required for existing connections to pick it up.","requestBody":{"content":{"application/json":{"schema":{"properties":{"enabled":{"type":"boolean"}},"type":"object"}}},"description":"New isolation state","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Isolation toggle applied"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Toggle global Docker isolation","tags":["config"]}},"/api/v1/config/validate":{"post":{"description":"Validates a provided MCPProxy configuration without applying it. Checks for syntax errors, invalid server definitions, conflicting settings, and other configuration issues.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to validate","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ValidateConfigResponse"}}},"description":"Configuration validation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Validation failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Validate configuration","tags":["config"]}},"/api/v1/connect":{"get":{"description":"Returns the connection status for all known MCP client applications.\nEach entry indicates whether the client config file exists and whether\nMCPProxy is currently registered in it.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"List of ClientStatus objects"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List client connection status","tags":["connect"]}},"/api/v1/connect/{client}":{"delete":{"description":"Remove the MCPProxy entry from the specified client's configuration file.\nCreates a backup of the existing config before modifying.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional parameters (server_name)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or entry not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disconnect MCPProxy from a client","tags":["connect"]},"get":{"description":"Resolves one client's status by reading its config file on demand.\nThis is the only Connect endpoint that opens a client config file, so\non macOS it is the sole place an App-Data privacy prompt may legitimately\nappear (scoped to this user action). Resolves access_state to\naccessible|absent|denied|malformed and populates remediation when denied.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ClientStatus"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get a single client's connection status (on-demand)","tags":["connect"]},"post":{"description":"Register MCPProxy as an MCP server in the specified client's configuration file.\nCreates a backup of the existing config before modifying.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","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"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/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/connect/{client}/preview":{"get":{"description":"Returns the exact entry a subsequent connect would add to the client's\nconfig — target path, server key, entry name, and entry contents — WITHOUT\nmodifying the file or creating a backup (Spec 078 US1). The embedded API key\nis masked in the payload; contains_api_key flags that a credential is written.\nentry_exists distinguishes a create from an overwrite of a same-named entry.\nReads the config on demand to classify create-vs-overwrite, so on macOS this\nmay raise an App-Data privacy prompt; a denial returns 403 + remediation.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}},{"description":"Entry name to preview (defaults to mcpproxy); mirror the value passed to POST connect","in":"query","name":"server_name","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectPreview"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Preview the change a connect would make (no write)","tags":["connect"]}},"/api/v1/connect/{client}/undo":{"post":{"description":"Reverts the connect that produced the named backup (Spec 078 US3):\nrestores the client config byte-for-byte from that backup, or — when\nbackup_name is empty because the connect created the file — deletes the\ncreated file. backup_name is the bare filename of the backup the connect\nreturned (never a path); undo resolves the full path server-side inside\nthe client's own config directory, so a client value cannot escape it.\nRefuses with 409 when the config changed since the connect (undo never\nclobbers later edits; use DELETE /connect/{client} for a surgical entry\nremoval instead). Takes its own safety backup first; its path is returned\nas backup_path in the result.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.UndoConnectRequest"}}},"description":"Undo parameters (server_name, backup_name = the bare filename of the backup the preceding connect returned)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult (action restored|deleted)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (e.g. backup_name is a path, or not a backup of this client's config)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or backup no longer exists"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Config changed since connect; undo refused"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Undo a connect, restoring the pre-connect config","tags":["connect"]}},"/api/v1/diagnostics":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/docker/status":{"get":{"description":"Retrieve current Docker availability and recovery status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Docker status information"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get Docker status","tags":["docker"]}},"/api/v1/doctor":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/feedback":{"post":{"description":"Submit a bug report, feature request, or general feedback","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackRequest"}}},"description":"Feedback request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Bad Request"},"429":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"Submit feedback","tags":["feedback"]}},"/api/v1/index/search":{"get":{"description":"Search across all upstream MCP server tools using BM25 keyword search","parameters":[{"description":"Search query","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"description":"Maximum number of results","in":"query","name":"limit","schema":{"default":10,"maximum":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchToolsResponse"}}},"description":"Search results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing query parameter)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search for tools","tags":["tools"]}},"/api/v1/info":{"get":{"description":"Get essential server metadata including version, web UI URL, endpoint addresses, and update availability\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/profiles":{"get":{"description":"List all configured profiles with their effective servers and indexed tool count (Profiles v2). A profile scopes tool discovery and calls to a named subset of upstream servers.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Profile list"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Configuration unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List configured profiles","tags":["profiles"]}},"/api/v1/profiles/active":{"get":{"description":"Get the server-level default active profile used by UI surfaces (Web UI / tray). Empty string means \"all servers\". Note: within a live MCP session, the set_profile tool selection takes precedence over this default.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get the default active profile","tags":["profiles"]},"put":{"description":"Set the server-level default active profile for UI surfaces. The slug must match a configured profile; pass an empty string to clear. This does not affect live MCP sessions, which use the set_profile tool.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.SetActiveProfileRequest"}}},"description":"Profile slug to activate (empty clears)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid request body"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Set the default active profile","tags":["profiles"]}},"/api/v1/registries":{"get":{"description":"Retrieves list of all MCP server registries that can be browsed for discovering and installing new upstream servers. Includes registry metadata, server counts, and API endpoints.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetRegistriesResponse"}}},"description":"Registries retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to list registries"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List available MCP server registries","tags":["registries"]},"post":{"description":"Adds a generic modelcontextprotocol/registry v0.1 https endpoint as a custom registry (MCP-866). The source is always tagged custom/unverified, so every server discovered through it lands quarantined and can never skip quarantine.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddRegistrySourceRequest"}}},"description":"Registry source (https url + optional protocol/id/name)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source added"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/contracts.ErrorResponse"},{"$ref":"#/components/schemas/contracts.ErrorResponse"}]}}},"description":"Forbidden (agent tokens cannot mutate registries)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin | duplicate_registry"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a user-supplied registry source","tags":["registries"]}},"/api/v1/registries/{id}":{"delete":{"description":"Removes a custom/unverified registry previously added via add-source (MCP-1057). Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source removed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove a user-added custom registry source","tags":["registries"]},"put":{"description":"Updates a custom registry previously added via add-source (MCP-1072): name, url, servers-url. Empty fields are left unchanged. Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found; a non-https url yields invalid_registry_url. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.EditRegistrySourceRequest"}}},"description":"Fields to update (name/url/servers_url; empty = unchanged)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required | invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Edit a user-added custom registry source","tags":["registries"]}},"/api/v1/registries/{id}/refresh":{"post":{"description":"Invalidates the cached server lists for a registry so the next search re-fetches fresh data from the source (spec 070 FR-007). Returns how many cache entries were dropped.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.RefreshRegistryResponse"}}},"description":"Registry cache refreshed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh registry cache"}},"summary":"Refresh a registry's cached server list","tags":["registries"]}},"/api/v1/registries/{id}/servers":{"get":{"description":"Searches for MCP servers within a specific registry by keyword or tag. Returns server metadata including installation commands, source code URLs, and npm package information for easy discovery and installation.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Search query keyword","in":"query","name":"q","schema":{"type":"string"}},{"description":"Filter by tag","in":"query","name":"tag","schema":{"type":"string"}},{"description":"Maximum number of results (default 10)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchRegistryServersResponse"}}},"description":"Servers retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to search servers"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search MCP servers in a registry","tags":["registries"]}},"/api/v1/registries/{id}/servers/{serverId}/add":{"post":{"description":"Resolves a registry server reference server-side, re-derives a validated config, and persists it quarantined (spec 070 keystone). The client never sends a config blob — command/args/url and the quarantine flag are derived from the registry entry, not the request.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Server ID within the registry","in":"path","name":"serverId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddFromRegistryRequest"}}},"description":"Optional overrides (name, env, enabled)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server added (quarantined)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"no_install_info | missing_required_input | duplicate_name"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot add servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found | server_not_found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add an upstream server from a registry reference","tags":["registries"]}},"/api/v1/routing":{"get":{"description":"Get the current routing mode and available MCP endpoints","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"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Conflict - server with this name already exists"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a new upstream server","tags":["servers"]}},"/api/v1/servers/disable_all":{"post":{"description":"Disable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk disable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable all servers","tags":["servers"]}},"/api/v1/servers/enable_all":{"post":{"description":"Enable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk enable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable all servers","tags":["servers"]}},"/api/v1/servers/import":{"post":{"description":"Import MCP server configurations from a Claude Desktop, Claude Code, Cursor IDE, Codex CLI, or Gemini CLI configuration file","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}},{"description":"Force format (claude-desktop, claude-code, cursor, codex, gemini)","in":"query","name":"format","schema":{"type":"string"}},{"description":"Comma-separated list of server names to import","in":"query","name":"server_names","schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"file"}}},"description":"Configuration file to import","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid file or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from uploaded configuration file","tags":["servers"]}},"/api/v1/servers/import/json":{"post":{"description":"Import MCP server configurations from raw JSON or TOML content (useful for pasting configurations)","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportRequest"}}},"description":"Import request with content","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid content or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from JSON/TOML content","tags":["servers"]}},"/api/v1/servers/import/path":{"post":{"description":"Import MCP server configurations by reading a file from the server's filesystem","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportFromPathRequest"}}},"description":"Import request with file path","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid path or format"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"File not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from a file path","tags":["servers"]}},"/api/v1/servers/import/paths":{"get":{"description":"Returns well-known configuration file paths for supported formats with existence check","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPathsResponse"}}},"description":"Canonical config paths"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get canonical config file paths","tags":["servers"]}},"/api/v1/servers/reconnect":{"post":{"description":"Force reconnection to all upstream MCP servers","parameters":[{"description":"Reason for reconnection","in":"query","name":"reason","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"All servers reconnected successfully"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Reconnect all servers","tags":["servers"]}},"/api/v1/servers/restart_all":{"post":{"description":"Restart all configured upstream MCP servers sequentially with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk restart results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart all servers","tags":["servers"]}},"/api/v1/servers/{id}":{"delete":{"description":"Remove an MCP upstream server from the configuration. This stops the server if running and removes it from config.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server removed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove an upstream server","tags":["servers"]},"patch":{"description":"Update specific fields of an existing upstream MCP server configuration.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.AddServerRequest"}}},"description":"Fields to update (all optional)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server updated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - no fields or invalid body"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/config-to-secret":{"post":{"description":"Atomically reads the real value from the server config, stores it in the OS keyring, and rewrites the config field to ` + "`" + `${keyring:\u003cname\u003e}` + "`" + `. Unblocks the UI's Convert-to-secret affordance for values the API redacts on the read path.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret stored, config updated with reference"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad scope/key/secret_name, or value is already a reference / empty"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server or key not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver or config update failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Convert a header / env value to a keyring secret","tags":["servers"]}},"/api/v1/servers/{id}/disable":{"post":{"description":"Disable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server disabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/discover-tools":{"post":{"description":"Manually trigger tool discovery and indexing for a specific upstream MCP server. This forces an immediate refresh of the server's tool cache.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool discovery triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot discover tools)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to discover tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Discover tools for a specific server","tags":["servers"]}},"/api/v1/servers/{id}/enable":{"post":{"description":"Enable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server enabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/login":{"post":{"description":"Initiate OAuth authentication flow for a specific upstream MCP server. Returns structured OAuth start response with correlation ID for tracking.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthStartResponse"}}},"description":"OAuth login initiated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthFlowError"}}},"description":"OAuth error (client_id required, DCR failed, etc.)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Trigger OAuth login for server","tags":["servers"]}},"/api/v1/servers/{id}/logout":{"post":{"description":"Clear OAuth authentication token and disconnect a specific upstream MCP server. The server will need to re-authenticate before tools can be used again.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"OAuth logout completed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled or read-only mode)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Clear OAuth token and disconnect server","tags":["servers"]}},"/api/v1/servers/{id}/logs":{"get":{"description":"Retrieve log entries for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Number of log lines to retrieve","in":"query","name":"tail","schema":{"default":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerLogsResponse"}}},"description":"Server logs retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server logs","tags":["servers"]}},"/api/v1/servers/{id}/quarantine":{"post":{"description":"Place a specific upstream MCP server in quarantine to prevent tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server quarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Quarantine a server","tags":["servers"]}},"/api/v1/servers/{id}/refresh":{"post":{"description":"Re-discover and re-index a specific upstream MCP server's tools without changing any security state. Alias of discover-tools, named for the upstream_servers 'refresh' operation; use it to make just-approved tools searchable immediately.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool refresh triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot refresh)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Refresh a server's tools","tags":["servers"]}},"/api/v1/servers/{id}/restart":{"post":{"description":"Restart the connection to a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server restarted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/tool-calls":{"get":{"description":"Retrieves tool call history filtered by upstream server ID. Returns recent tool executions for the specified server including timestamps, arguments, results, and errors. Useful for server-specific debugging and monitoring.","parameters":[{"description":"Upstream server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Maximum number of records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolCallsResponse"}}},"description":"Server tool calls retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get server tool calls"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call history for specific server","tags":["tool-calls"]}},"/api/v1/servers/{id}/tools":{"get":{"description":"Retrieve all available tools for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolsResponse"}}},"description":"Server tools retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/block":{"post":{"description":"Atomically approves AND disables the given tools (or all pending/changed tools when block_all=true) for a server. The approve and disable land in a single write per tool, so a tool is never left in the approved+enabled state. The \"blocked\" field counts tools actually blocked.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Block result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Block (approve+disable) tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/disable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/enable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/unquarantine":{"post":{"description":"Remove a specific upstream MCP server from quarantine to allow tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server unquarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Unquarantine a server","tags":["servers"]}},"/api/v1/sessions":{"get":{"description":"Retrieves paginated list of active and recent MCP client sessions. Each session represents a connection from an MCP client to MCPProxy, tracking initialization time, tool calls, and connection status.","parameters":[{"description":"Maximum number of sessions to return (1-100, default 10)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Number of sessions to skip for pagination (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Filter by session status","in":"query","name":"status","schema":{"enum":["active","closed"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionsResponse"}}},"description":"Sessions retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid status filter"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"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 transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"enum":["success","error","blocked"],"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"}},{"description":"Omit arguments, response and metadata except a contextual whitelist (intent.reason, intent.operation_type, decision, reason, client_name, client_version) (default: false). For clients that render summary fields only; has_sensitive_data is still derived before metadata is dropped.","in":"query","name":"exclude_payloads","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"List activity records","tags":["Activity"]}},"/api/v1/activity/export":{"get":{"description":"Exports activity records in JSON Lines or CSV format for compliance","parameters":[{"description":"Export format: json (default) or csv","in":"query","name":"format","schema":{"type":"string"}},{"description":"Filter by activity type","in":"query","name":"type","schema":{"type":"string"}},{"description":"Filter by server name","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter by tool name","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter by MCP transport session ID","in":"query","name":"session_id","schema":{"type":"string"}},{"description":"Filter by work session (one client, one project, across reconnects)","in":"query","name":"work_session_id","schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","schema":{"type":"string"}},{"description":"Filter activities after this time (RFC3339)","in":"query","name":"start_time","schema":{"type":"string"}},{"description":"Filter activities before this time (RFC3339)","in":"query","name":"end_time","schema":{"type":"string"}},{"description":"Maximum records to export (1-50000, default 10000)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Pagination offset (default 0)","in":"query","name":"offset","schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}}},"description":"Streamed activity records"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Export activity records","tags":["Activity"]}},"/api/v1/activity/summary":{"get":{"description":"Returns aggregated activity statistics for a time period","parameters":[{"description":"Time period: 1h, 24h (default), 7d, 30d","in":"query","name":"period","schema":{"type":"string"}},{"description":"Group by: server, tool (optional)","in":"query","name":"group_by","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity summary statistics","tags":["Activity"]}},"/api/v1/activity/usage":{"get":{"description":"Returns the actor-owned usage aggregate (per-tool rollup + timeline + tokens-saved headline) for the Web UI usage graphs (Spec 069). Served from an in-memory snapshot — never a per-request full-log scan. Per-tool metrics are lifetime-cumulative; ` + "`" + `window` + "`" + ` scopes the timeline and filters the tool list to tools active within the span.","parameters":[{"description":"Time window for timeline + tool-list membership","in":"query","name":"window","schema":{"enum":["24h","7d","all"],"type":"string"}},{"description":"Filter to one server","in":"query","name":"server","schema":{"type":"string"}},{"description":"Filter to one tool","in":"query","name":"tool","schema":{"type":"string"}},{"description":"Filter to tools with activity of this status","in":"query","name":"status","schema":{"enum":["success","error","blocked"],"type":"string"}},{"description":"Top-N tools by sort key; remainder folded into 'other' (default 20)","in":"query","name":"top","schema":{"type":"integer"}},{"description":"Ranking key for the per-tool list","in":"query","name":"sort","schema":{"enum":["calls","resp_bytes","error_rate","p95"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get usage statistics aggregate","tags":["Activity"]}},"/api/v1/activity/{id}":{"get":{"description":"Returns full details for a single activity record","parameters":[{"description":"Activity record ID (ULID)","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/data"}],"properties":{"data":{"type":"object"},"error":{"type":"string"},"request_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}},"description":"OK"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Unauthorized"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Not Found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"summary":"Get activity record details","tags":["Activity"]}},"/api/v1/annotations/coverage":{"get":{"description":"Reports how many upstream tools have MCP annotations vs don't, broken down by server","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Annotation coverage report"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get annotation coverage report","tags":["annotations"]}},"/api/v1/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"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to read or apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update configuration","tags":["config"]}},"/api/v1/config/apply":{"post":{"description":"Applies a new MCPProxy configuration. Validates and persists the configuration to disk. Some changes apply immediately, while others may require a restart. Returns detailed information about applied changes and restart requirements.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to apply","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Configuration applied successfully with change details"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Apply configuration","tags":["config"]}},"/api/v1/config/docker-isolation":{"patch":{"description":"Convenience endpoint to flip ` + "`" + `docker_isolation.enabled` + "`" + ` without resending the full config. Persists to disk via the existing config writer — the file watcher then hot-reloads the change. Returns the new state and whether a restart is required for existing connections to pick it up.","requestBody":{"content":{"application/json":{"schema":{"properties":{"enabled":{"type":"boolean"}},"type":"object"}}},"description":"New isolation state","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ConfigApplyResult"}}},"description":"Isolation toggle applied"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate configuration)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to apply configuration"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Toggle global Docker isolation","tags":["config"]}},"/api/v1/config/validate":{"post":{"description":"Validates a provided MCPProxy configuration without applying it. Checks for syntax errors, invalid server definitions, conflicting settings, and other configuration issues.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/config.Config"}}},"description":"Configuration to validate","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ValidateConfigResponse"}}},"description":"Configuration validation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid JSON payload"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Validation failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Validate configuration","tags":["config"]}},"/api/v1/connect":{"get":{"description":"Returns the connection status for all known MCP client applications.\nEach entry indicates whether the client config file exists and whether\nMCPProxy is currently registered in it.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"List of ClientStatus objects"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List client connection status","tags":["connect"]}},"/api/v1/connect/{client}":{"delete":{"description":"Remove the MCPProxy entry from the specified client's configuration file.\nCreates a backup of the existing config before modifying.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional parameters (server_name)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or entry not found"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disconnect MCPProxy from a client","tags":["connect"]},"get":{"description":"Resolves one client's status by reading its config file on demand.\nThis is the only Connect endpoint that opens a client config file, so\non macOS it is the sole place an App-Data privacy prompt may legitimately\nappear (scoped to this user action). Resolves access_state to\naccessible|absent|denied|malformed and populates remediation when denied.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ClientStatus"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get a single client's connection status (on-demand)","tags":["connect"]},"post":{"description":"Register MCPProxy as an MCP server in the specified client's configuration file.\nCreates a backup of the existing config before modifying.\nOptionally accepts precondition_token from a preview (Spec 091): when supplied,\nthe core rechecks the raw pre-write state and the entry it would write, and\nrefuses a drifted write with 409 before taking any backup. The 409 body's\naction discriminates the two conflict kinds: \"precondition_failed\" (stale\npreview — re-preview, do not retry) vs \"already_exists\" (entry present — pass\nforce=true). force=true never rescues a stale token.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectRequest"}}},"description":"Optional connection parameters (server_name, force, precondition_token)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ConnectConflictResponse"}}},"description":"Conflict: action=already_exists (use force=true) or action=precondition_failed (preview is stale; re-preview)"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Connect MCPProxy to a client","tags":["connect"]}},"/api/v1/connect/{client}/preview":{"get":{"description":"Returns the exact entry a subsequent connect would add to the client's\nconfig — target path, server key, entry name, and entry contents — WITHOUT\nmodifying the file or creating a backup (Spec 078 US1). The embedded API key\nis masked in the payload; contains_api_key flags that a credential is written.\nentry_exists distinguishes a create from an overwrite of a same-named entry.\nReads the config on demand to classify create-vs-overwrite, so on macOS this\nmay raise an App-Data privacy prompt; a denial returns 403 + remediation.\nSpec 091 adds three fields: existing_entry_summary (present only when\nentry_exists — a sanitized, non-secret projection of the entry being replaced:\nits name, type, endpoint with query/userinfo stripped, command, and header and\nenv NAMES, never values); precondition_token (always present — an opaque keyed\ndigest of the raw pre-write state and the pending entry, echoed back on POST\nconnect to detect drift); and connect_refusal (present when the write would\nrefuse regardless of intent, e.g. a non-create-capable client with no config —\ntreat its presence as \"Connect unavailable\").","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}},{"description":"Entry name to preview (defaults to mcpproxy); mirror the value passed to POST connect","in":"query","name":"server_name","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectPreview"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Preview the change a connect would make (no write)","tags":["connect"]}},"/api/v1/connect/{client}/undo":{"post":{"description":"Reverts the connect that produced the named backup (Spec 078 US3):\nrestores the client config byte-for-byte from that backup, or — when\nbackup_name is empty because the connect created the file — deletes the\ncreated file. backup_name is the bare filename of the backup the connect\nreturned (never a path); undo resolves the full path server-side inside\nthe client's own config directory, so a client value cannot escape it.\nRefuses with 409 when the config changed since the connect (undo never\nclobbers later edits; use DELETE /connect/{client} for a surgical entry\nremoval instead). Takes its own safety backup first; its path is returned\nas backup_path in the result.","parameters":[{"description":"Client ID (claude-code, claude-desktop, cursor, windsurf, vscode, codex, gemini, opencode)","in":"path","name":"client","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.UndoConnectRequest"}}},"description":"Undo parameters (server_name, backup_name = the bare filename of the backup the preceding connect returned)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.APIResponse"}}},"description":"ConnectResult (action restored|deleted)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (e.g. backup_name is a path, or not a backup of this client's config)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Permission denied (macOS App-Data block)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown client or backup no longer exists"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Config changed since connect; undo refused"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Service unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Undo a connect, restoring the pre-connect config","tags":["connect"]}},"/api/v1/diagnostics":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/docker/status":{"get":{"description":"Retrieve current Docker availability and recovery status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Docker status information"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get Docker status","tags":["docker"]}},"/api/v1/doctor":{"get":{"description":"Get comprehensive health diagnostics including upstream errors, OAuth requirements, missing secrets, and Docker status","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.Diagnostics"}}},"description":"Health diagnostics"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get health diagnostics","tags":["diagnostics"]}},"/api/v1/feedback":{"post":{"description":"Submit a bug report, feature request, or general feedback","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackRequest"}}},"description":"Feedback request","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/telemetry.FeedbackResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Bad Request"},"429":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Too Many Requests"},"500":{"content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}},"description":"Internal Server Error"}},"security":[{"ApiKeyAuth":[]}],"summary":"Submit feedback","tags":["feedback"]}},"/api/v1/index/search":{"get":{"description":"Search across all upstream MCP server tools using BM25 keyword search","parameters":[{"description":"Search query","in":"query","name":"q","required":true,"schema":{"type":"string"}},{"description":"Maximum number of results","in":"query","name":"limit","schema":{"default":10,"maximum":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchToolsResponse"}}},"description":"Search results"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing query parameter)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search for tools","tags":["tools"]}},"/api/v1/info":{"get":{"description":"Get essential server metadata including version, web UI URL, endpoint addresses, and update availability\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/profiles":{"get":{"description":"List all configured profiles with their effective servers and indexed tool count (Profiles v2). A profile scopes tool discovery and calls to a named subset of upstream servers.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Profile list"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Configuration unavailable"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List configured profiles","tags":["profiles"]}},"/api/v1/profiles/active":{"get":{"description":"Get the server-level default active profile used by UI surfaces (Web UI / tray). Empty string means \"all servers\". Note: within a live MCP session, the set_profile tool selection takes precedence over this default.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get the default active profile","tags":["profiles"]},"put":{"description":"Set the server-level default active profile for UI surfaces. The slug must match a configured profile; pass an empty string to clear. This does not affect live MCP sessions, which use the set_profile tool.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.SetActiveProfileRequest"}}},"description":"Profile slug to activate (empty clears)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Active profile updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid request body"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unknown profile"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Set the default active profile","tags":["profiles"]}},"/api/v1/registries":{"get":{"description":"Retrieves list of all MCP server registries that can be browsed for discovering and installing new upstream servers. Includes registry metadata, server counts, and API endpoints.","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetRegistriesResponse"}}},"description":"Registries retrieved successfully"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to list registries"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"List available MCP server registries","tags":["registries"]},"post":{"description":"Adds a generic modelcontextprotocol/registry v0.1 https endpoint as a custom registry (MCP-866). The source is always tagged custom/unverified, so every server discovered through it lands quarantined and can never skip quarantine.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddRegistrySourceRequest"}}},"description":"Registry source (https url + optional protocol/id/name)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source added"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/contracts.ErrorResponse"},{"$ref":"#/components/schemas/contracts.ErrorResponse"}]}}},"description":"Forbidden (agent tokens cannot mutate registries)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin | duplicate_registry"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a user-supplied registry source","tags":["registries"]}},"/api/v1/registries/{id}":{"delete":{"description":"Removes a custom/unverified registry previously added via add-source (MCP-1057). Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source removed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove a user-added custom registry source","tags":["registries"]},"put":{"description":"Updates a custom registry previously added via add-source (MCP-1072): name, url, servers-url. Empty fields are left unchanged. Built-in registries are refused with registry_shadows_builtin; an unknown id yields registry_not_found; a non-https url yields invalid_registry_url. The change is persisted copy-on-write.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.EditRegistrySourceRequest"}}},"description":"Fields to update (name/url/servers_url; empty = unchanged)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Registry source updated"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required | invalid_registry_url"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registries_locked"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_shadows_builtin"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Edit a user-added custom registry source","tags":["registries"]}},"/api/v1/registries/{id}/refresh":{"post":{"description":"Invalidates the cached server lists for a registry so the next search re-fetches fresh data from the source (spec 070 FR-007). Returns how many cache entries were dropped.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.RefreshRegistryResponse"}}},"description":"Registry cache refreshed"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID is required"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh registry cache"}},"summary":"Refresh a registry's cached server list","tags":["registries"]}},"/api/v1/registries/{id}/servers":{"get":{"description":"Searches for MCP servers within a specific registry by keyword or tag. Returns server metadata including installation commands, source code URLs, and npm package information for easy discovery and installation.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Search query keyword","in":"query","name":"q","schema":{"type":"string"}},{"description":"Filter by tag","in":"query","name":"tag","schema":{"type":"string"}},{"description":"Maximum number of results (default 10)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SearchRegistryServersResponse"}}},"description":"Servers retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Registry ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to search servers"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Search MCP servers in a registry","tags":["registries"]}},"/api/v1/registries/{id}/servers/{serverId}/add":{"post":{"description":"Resolves a registry server reference server-side, re-derives a validated config, and persists it quarantined (spec 070 keystone). The client never sends a config blob — command/args/url and the quarantine flag are derived from the registry entry, not the request.","parameters":[{"description":"Registry ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Server ID within the registry","in":"path","name":"serverId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.AddFromRegistryRequest"}}},"description":"Optional overrides (name, env, enabled)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server added (quarantined)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"no_install_info | missing_required_input | duplicate_name"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot add servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"registry_not_found | server_not_found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add an upstream server from a registry reference","tags":["registries"]}},"/api/v1/routing":{"get":{"description":"Get the current routing mode and available MCP endpoints","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"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Conflict - server with this name already exists"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Add a new upstream server","tags":["servers"]}},"/api/v1/servers/disable_all":{"post":{"description":"Disable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk disable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable all servers","tags":["servers"]}},"/api/v1/servers/enable_all":{"post":{"description":"Enable all configured upstream MCP servers with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk enable results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable all servers","tags":["servers"]}},"/api/v1/servers/import":{"post":{"description":"Import MCP server configurations from a Claude Desktop, Claude Code, Cursor IDE, Codex CLI, or Gemini CLI configuration file","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}},{"description":"Force format (claude-desktop, claude-code, cursor, codex, gemini)","in":"query","name":"format","schema":{"type":"string"}},{"description":"Comma-separated list of server names to import","in":"query","name":"server_names","schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"file"}}},"description":"Configuration file to import","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid file or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from uploaded configuration file","tags":["servers"]}},"/api/v1/servers/import/json":{"post":{"description":"Import MCP server configurations from raw JSON or TOML content (useful for pasting configurations)","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportRequest"}}},"description":"Import request with content","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid content or format"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from JSON/TOML content","tags":["servers"]}},"/api/v1/servers/import/path":{"post":{"description":"Import MCP server configurations by reading a file from the server's filesystem","parameters":[{"description":"If true, return preview without importing","in":"query","name":"preview","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportFromPathRequest"}}},"description":"Import request with file path","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.ImportResponse"}}},"description":"Import result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - invalid path or format"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"File not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Import servers from a file path","tags":["servers"]}},"/api/v1/servers/import/paths":{"get":{"description":"Returns well-known configuration file paths for supported formats with existence check","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.CanonicalConfigPathsResponse"}}},"description":"Canonical config paths"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get canonical config file paths","tags":["servers"]}},"/api/v1/servers/reconnect":{"post":{"description":"Force reconnection to all upstream MCP servers","parameters":[{"description":"Reason for reconnection","in":"query","name":"reason","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"All servers reconnected successfully"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Reconnect all servers","tags":["servers"]}},"/api/v1/servers/restart_all":{"post":{"description":"Restart all configured upstream MCP servers sequentially with partial failure handling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/management.BulkOperationResult"}}},"description":"Bulk restart results with success/failure counts"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart all servers","tags":["servers"]}},"/api/v1/servers/{id}":{"delete":{"description":"Remove an MCP upstream server from the configuration. This stops the server if running and removes it from config.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server removed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Remove an upstream server","tags":["servers"]},"patch":{"description":"Update specific fields of an existing upstream MCP server configuration.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/httpapi.AddServerRequest"}}},"description":"Fields to update (all optional)","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Server updated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request - no fields or invalid body"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Partially update an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/config-to-secret":{"post":{"description":"Atomically reads the real value from the server config, stores it in the OS keyring, and rewrites the config field to ` + "`" + `${keyring:\u003cname\u003e}` + "`" + `. Unblocks the UI's Convert-to-secret affordance for values the API redacts on the read path.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":{},"type":"object"}}},"description":"Secret stored, config updated with reference"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad scope/key/secret_name, or value is already a reference / empty"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server or key not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Secret resolver or config update failed"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Convert a header / env value to a keyring secret","tags":["servers"]}},"/api/v1/servers/{id}/disable":{"post":{"description":"Disable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server disabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Disable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/discover-tools":{"post":{"description":"Manually trigger tool discovery and indexing for a specific upstream MCP server. This forces an immediate refresh of the server's tool cache.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool discovery triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot discover tools)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to discover tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Discover tools for a specific server","tags":["servers"]}},"/api/v1/servers/{id}/enable":{"post":{"description":"Enable a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server enabled successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/login":{"post":{"description":"Initiate OAuth authentication flow for a specific upstream MCP server. Returns structured OAuth start response with correlation ID for tracking.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthStartResponse"}}},"description":"OAuth login initiated successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.OAuthFlowError"}}},"description":"OAuth error (client_id required, DCR failed, etc.)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Trigger OAuth login for server","tags":["servers"]}},"/api/v1/servers/{id}/logout":{"post":{"description":"Clear OAuth authentication token and disconnect a specific upstream MCP server. The server will need to re-authenticate before tools can be used again.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"OAuth logout completed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (management disabled or read-only mode)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Clear OAuth token and disconnect server","tags":["servers"]}},"/api/v1/servers/{id}/logs":{"get":{"description":"Retrieve log entries for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Number of log lines to retrieve","in":"query","name":"tail","schema":{"default":100,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerLogsResponse"}}},"description":"Server logs retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get server logs","tags":["servers"]}},"/api/v1/servers/{id}/quarantine":{"post":{"description":"Place a specific upstream MCP server in quarantine to prevent tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server quarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Quarantine a server","tags":["servers"]}},"/api/v1/servers/{id}/refresh":{"post":{"description":"Re-discover and re-index a specific upstream MCP server's tools without changing any security state. Alias of discover-tools, named for the upstream_servers 'refresh' operation; use it to make just-approved tools searchable immediately.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Tool refresh triggered successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot refresh)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to refresh tools"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Refresh a server's tools","tags":["servers"]}},"/api/v1/servers/{id}/restart":{"post":{"description":"Restart the connection to a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server restarted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Restart an upstream server","tags":["servers"]}},"/api/v1/servers/{id}/tool-calls":{"get":{"description":"Retrieves tool call history filtered by upstream server ID. Returns recent tool executions for the specified server including timestamps, arguments, results, and errors. Useful for server-specific debugging and monitoring.","parameters":[{"description":"Upstream server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Maximum number of records to return (1-100, default 50)","in":"query","name":"limit","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolCallsResponse"}}},"description":"Server tool calls retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server ID required"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"405":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Method not allowed"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Failed to get server tool calls"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tool call history for specific server","tags":["tool-calls"]}},"/api/v1/servers/{id}/tools":{"get":{"description":"Retrieve all available tools for a specific upstream MCP server","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetServerToolsResponse"}}},"description":"Server tools retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Get tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/block":{"post":{"description":"Atomically approves AND disables the given tools (or all pending/changed tools when block_all=true) for a server. The approve and disable land in a single write per tool, so a tool is never left in the approved+enabled state. The \"blocked\" field counts tools actually blocked.","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Block result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Block (approve+disable) tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/disable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/tools/enable_all":{"post":{"description":"Bulk-toggles every known tool of a server. The \"changed\" field","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.SuccessResponse"}}},"description":"Operation result"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Enable or disable all tools for a server","tags":["servers"]}},"/api/v1/servers/{id}/unquarantine":{"post":{"description":"Remove a specific upstream MCP server from quarantine to allow tool execution","parameters":[{"description":"Server ID or name","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ServerActionResponse"}}},"description":"Server unquarantined successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Bad request (missing server ID)"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Forbidden (agent tokens cannot mutate servers)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Server not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Internal server error"}},"security":[{"ApiKeyAuth":[]},{"ApiKeyQuery":[]}],"summary":"Unquarantine a server","tags":["servers"]}},"/api/v1/sessions":{"get":{"description":"Retrieves paginated list of active and recent MCP client sessions. Each session represents a connection from an MCP client to MCPProxy, tracking initialization time, tool calls, and connection status.","parameters":[{"description":"Maximum number of sessions to return (1-100, default 10)","in":"query","name":"limit","schema":{"type":"integer"}},{"description":"Number of sessions to skip for pagination (default 0)","in":"query","name":"offset","schema":{"type":"integer"}},{"description":"Filter by session status","in":"query","name":"status","schema":{"enum":["active","closed"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.GetSessionsResponse"}}},"description":"Sessions retrieved successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Invalid status filter"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/contracts.ErrorResponse"}}},"description":"Unauthorized - missing or invalid API key"},"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 592e326c..30ceed1d 100644
--- a/oas/swagger.yaml
+++ b/oas/swagger.yaml
@@ -1068,6 +1068,25 @@ components:
           description: '"already_exists", "filtered_out", "invalid_name"'
           type: string
       type: object
+    connect.ConnectResult:
+      description: The full result; its action mirrors the top-level one
+      properties:
+        action:
+          description: '"created", "updated", "already_exists", "removed", "not_found"'
+          type: string
+        backup_path:
+          type: string
+        client:
+          type: string
+        config_path:
+          type: string
+        message:
+          type: string
+        server_name:
+          type: string
+        success:
+          type: boolean
+      type: object
     contracts.APIResponse:
       allOf:
       - $ref: '#/components/schemas/data'
@@ -2660,11 +2679,36 @@ components:
           type: array
           uniqueItems: false
       type: object
+    httpapi.ConnectConflictResponse:
+      properties:
+        action:
+          description: already_exists | precondition_failed
+          type: string
+        data:
+          $ref: '#/components/schemas/connect.ConnectResult'
+        error:
+          description: Human-readable message
+          type: string
+        success:
+          description: Always false
+          type: boolean
+      type: object
     httpapi.ConnectRequest:
       properties:
         force:
           description: Overwrite existing entry
           type: boolean
+        precondition_token:
+          description: |-
+            PreconditionToken is the opaque token from the preview this write was
+            confirmed against (Spec 091 FR-005). When present, the core rechecks it
+            at write time and responds 409 with action "precondition_failed" —
+            writing nothing — if the config or the entry MCPProxy would write has
+            drifted since; the caller then re-previews instead of retrying. Absent
+            means exactly the pre-091 behavior. A replace-classified flow sends this
+            TOGETHER with force=true: the token, not the absence of force, is the
+            overwrite safety.
+          type: string
         server_name:
           description: Defaults to "mcpproxy"
           type: string
@@ -3832,6 +3876,12 @@ paths:
       description: |-
         Register MCPProxy as an MCP server in the specified client's configuration file.
         Creates a backup of the existing config before modifying.
+        Optionally accepts precondition_token from a preview (Spec 091): when supplied,
+        the core rechecks the raw pre-write state and the entry it would write, and
+        refuses a drifted write with 409 before taking any backup. The 409 body's
+        action discriminates the two conflict kinds: "precondition_failed" (stale
+        preview — re-preview, do not retry) vs "already_exists" (entry present — pass
+        force=true). force=true never rescues a stale token.
       parameters:
       - description: Client ID (claude-code, claude-desktop, cursor, windsurf, vscode,
           codex, gemini, opencode)
@@ -3845,7 +3895,7 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/httpapi.ConnectRequest'
-        description: Optional connection parameters
+        description: Optional connection parameters (server_name, force, precondition_token)
       responses:
         "200":
           content:
@@ -3875,8 +3925,9 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/contracts.ErrorResponse'
-          description: Already connected (use force=true)
+                $ref: '#/components/schemas/httpapi.ConnectConflictResponse'
+          description: 'Conflict: action=already_exists (use force=true) or action=precondition_failed
+            (preview is stale; re-preview)'
         "503":
           content:
             application/json:
@@ -3899,6 +3950,14 @@ paths:
         entry_exists distinguishes a create from an overwrite of a same-named entry.
         Reads the config on demand to classify create-vs-overwrite, so on macOS this
         may raise an App-Data privacy prompt; a denial returns 403 + remediation.
+        Spec 091 adds three fields: existing_entry_summary (present only when
+        entry_exists — a sanitized, non-secret projection of the entry being replaced:
+        its name, type, endpoint with query/userinfo stripped, command, and header and
+        env NAMES, never values); precondition_token (always present — an opaque keyed
+        digest of the raw pre-write state and the pending entry, echoed back on POST
+        connect to detect drift); and connect_refusal (present when the write would
+        refuse regardless of intent, e.g. a non-create-capable client with no config —
+        treat its presence as "Connect unavailable").
       parameters:
       - description: Client ID (claude-code, claude-desktop, cursor, windsurf, vscode,
           codex, gemini, opencode)
diff --git a/specs/091-connect-client-form/checklists/requirements.md b/specs/091-connect-client-form/checklists/requirements.md
new file mode 100644
index 00000000..7b229ad9
--- /dev/null
+++ b/specs/091-connect-client-form/checklists/requirements.md
@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Native Connect Client Form
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-07-31
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- The preview-before-write rule (FR-003/SC-002) encodes standing user feedback on this exact flow and is enforced structurally, not by convention.
+- The no-config-file-reads rule (FR-002/SC-004) preserves the existing tray discipline that all state comes from the core.
diff --git a/specs/091-connect-client-form/contracts/api-deltas.md b/specs/091-connect-client-form/contracts/api-deltas.md
new file mode 100644
index 00000000..c50bc6f0
--- /dev/null
+++ b/specs/091-connect-client-form/contracts/api-deltas.md
@@ -0,0 +1,79 @@
+# API Contract Deltas — Spec 091 (rev 2, post-panel-review)
+
+No new endpoints. Additive, backward-compatible deltas on the existing connect
+surface.
+
+## 1. `GET /api/v1/connect/{client}/preview` — three new response fields
+
+```json
+{
+  "config_path": "…",
+  "entry": { … },
+  "entry_text": "…pending entry, credential masked at construction…",
+  "entry_exists": true,
+  "contains_api_key": true,
+  "access_state": "accessible",
+
+  "existing_entry_summary": {
+    "entry_name": "old-proxy",
+    "type": "http",
+    "endpoint": "http://127.0.0.1:8080/mcp",
+    "command": null,
+    "header_names": ["X-API-Key"],
+    "env_names": []
+  },
+  "precondition_token": "opaque",
+  "connect_refusal": null
+}
+```
+
+- `existing_entry_summary` (object, optional): present only when
+  `entry_exists=true`. Built **by construction from non-secret projections
+  only** — entry name (which may differ from the requested `server_name` when
+  the write would adopt an equivalent entry), transport type, endpoint with
+  **query parameters stripped**, command, and the **names** (never values) of
+  headers and environment variables. No field of this object ever carries an
+  arbitrary value from the config file except the query-stripped endpoint and
+  command path. Backend tests feed entries containing rotated API keys,
+  bearer headers, env secrets, `?apikey=` URLs, and `user:pass@` URLs and
+  assert none of those values appear anywhere in the serialized response
+  (userinfo is stripped from endpoints along with the query).
+- `precondition_token` (string, always present): opaque **HMAC-SHA256** over a
+  canonical **length-prefixed** encoding of: config path, file existence, the
+  *resolved* target entry name (after the same equivalent-entry adoption the
+  write performs) and its raw value, and the exact pending entry that would be
+  written. Keyed with a per-core-instance random in-memory key (tokens are
+  single-session by design), so it is neither reversible nor usable as an
+  offline confirmation oracle for masked values. Never persisted.
+- `connect_refusal` (string, optional): populated when the write would refuse
+  regardless of user intent (e.g. a non-create-capable client with an absent
+  config — OpenCode); carries the same verbatim reason the write would return.
+  Consumers must treat its presence as "Connect unavailable".
+
+## 2. `POST /api/v1/connect/{client}` — precondition + discriminated conflict
+
+Request body:
+
+```json
+{ "server_name": "mcpproxy", "force": true, "precondition_token": "opaque" }
+```
+
+- `precondition_token` (optional): when present, the core recomputes at write
+  time and responds **409** when stale, writing nothing.
+- The 409 body is machine-discriminable via `action`:
+  - `"action": "precondition_failed"` — token drift → the client re-previews.
+  - `"action": "already_exists"` — existing semantics (entry exists,
+    `force=false`, no token involved).
+- A replace-classified flow sends `force=true` **with** the token — the token,
+  not the absence of force, is the overwrite safety. `force=true` with a stale
+  token still yields `precondition_failed` and no write.
+- Absent token → exactly today's behavior (Web UI/CLI unchanged).
+- Gating unchanged: write routes still reject restricted agent tokens; the
+  tray's socket transport carries admin context. The tray sends mutating
+  requests in strict-socket mode (client-side; no TCP fallback for writes).
+
+## Consumers
+
+- The native form always sends the token from its rendered preview; replace
+  flows add `force=true`; it never sends `force` without a token.
+- Web UI ConnectModal is unchanged (may adopt the token later).
diff --git a/specs/091-connect-client-form/data-model.md b/specs/091-connect-client-form/data-model.md
new file mode 100644
index 00000000..7e3e14f4
--- /dev/null
+++ b/specs/091-connect-client-form/data-model.md
@@ -0,0 +1,91 @@
+# Data Model — Native Connect Client Form (Spec 091, rev 2)
+
+## Go (core) — additive
+
+### ConnectPreview (internal/connect/preview.go)
+
+Three new fields (contracts §1): `ExistingEntrySummary *EntrySummary` (only
+when `EntryExists`), `PreconditionToken string` (always),
+`ConnectRefusal string` (only when the write would refuse).
+
+### EntrySummary (internal/connect/summary.go, new)
+
+`EntryName, Type, Endpoint (query+userinfo stripped), Command, HeaderNames [],
+EnvNames []` — built from parsed projections only; no arbitrary values.
+Resolved via the same equivalent-entry adoption lookup the write performs.
+
+### Token (internal/connect/token.go, new)
+
+`DerivePreconditionToken(key []byte, configPath string, fileExists bool,
+resolvedEntryName string, rawResolvedEntry json.RawMessage,
+pendingEntry json.RawMessage) string` — canonical length-prefixed encoding →
+HMAC-SHA256(per-instance in-memory random key) → hex. Deterministic per key;
+distinct for: absent vs present file, resolved entry present vs absent, any
+raw byte change of the resolved (possibly adopted) entry — including values
+the summary hides — and any change in the pending entry (credential rotation,
+auth toggle, address change).
+
+### Connect request (internal/httpapi/connect.go)
+
+Body gains `PreconditionToken string` (optional). Validation order: resolve
+current raw state (same adoption lookup) + rebuild pending entry → if token
+present and mismatch → **409 `{"action":"precondition_failed", reason}`**,
+nothing written → else existing flow (backup when file exists, write). Legacy
+`already_exists` 409 keeps its `action`. Absent token = legacy behavior.
+
+## Swift — models and state machine
+
+### ClientStatus (extended decode)
+
+Adds: `icon`, `server_name`, `access_state`, `remediation` (all optional —
+tolerate older cores). Unknown client ids decode generically (name fallback,
+default icon).
+
+### ConnectPreviewModel (new)
+
+`configPath, entryText, entryExists, existingEntrySummary?, containsAPIKey,
+accessState, preconditionToken, connectRefusal?`. Derived `changeKind`:
+refusal present → `.refused(reason)` (no Connect control);
+absent → `.create`; readable && !entryExists → `.add`; entryExists → `.replace`
+(summary names the adopted entry when its key differs);
+unreadable/denied → `.blockedByAccess` (no Connect control).
+Derived safety-net statement: `.create` → "file will be created… Undo removes
+it"; `.add`/`.replace` → "timestamped backup will be created alongside it".
+`containsAPIKey` → credential notice.
+
+### ConnectClientModel (new, @MainActor)
+
+States:
+
+| Slice | Values |
+|-------|--------|
+| `list` | `.loading` / `.loaded([ClientRow])` / `.coreUnreachable(polling)` |
+| `selection` | `nil` / clientID |
+| `detail` | `.loading` / `.resolved(ClientDetail)` |
+| `preview` | `.idle` / `.loading` / `.resolved(ConnectPreviewModel)` / `.failed(reason)` |
+| `action` | `.idle` / `.inFlight` / `.failed(reason)` / `.conflict(reason)` / `.succeeded(ConnectResult)` |
+| `undo` | `nil` / `.available(backupIdentity, clientID)` — cleared on use or form close |
+| `entryName` | default "mcpproxy"; editing resets `preview` to `.idle` and refetches |
+
+Invariants (unit-tested):
+
+- The Connect control exists iff `preview == .resolved` for the CURRENT
+  (selection, entryName) AND `changeKind` is not `.refused`/`.blockedByAccess`
+  — SC-002's structural guarantee.
+- Replace-classified connects send `force=true` + token; `.conflict` is set
+  ONLY from a 409 with `action == "precondition_failed"` and triggers an
+  automatic re-preview (a legacy `already_exists` 409 is a `.failed` — it
+  cannot occur in this flow and must not loop).
+- `undo` is set only from a `.succeeded` connect in this form instance.
+- Off-socket transport (`APIClient.transportKind != .unixSocket`) ⇒
+  Connect/Undo/Disconnect disabled with explanation; list/detail/preview
+  unaffected. Mutating requests use strict-socket mode: mid-session socket
+  loss fails the request rather than silently riding TCP.
+- `coreUnreachable` polls every 2 s until loaded.
+- Unsupported client rows are disabled with reason; unreadable/denied rows
+  show the mapped label ("config unreadable" / "access not granted" +
+  remediation); the Connect control is absent.
+
+### ConnectResult
+
+`success(backupIdentity?)` / failure(reason). Backup identity feeds `undo`.
diff --git a/specs/091-connect-client-form/plan.md b/specs/091-connect-client-form/plan.md
new file mode 100644
index 00000000..349166ed
--- /dev/null
+++ b/specs/091-connect-client-form/plan.md
@@ -0,0 +1,85 @@
+# Implementation Plan: Native Connect Client Form
+
+**Branch**: `091-connect-client-form` | **Date**: 2026-07-31 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/091-connect-client-form/spec.md`
+
+## Summary
+
+A native tray path for connecting AI clients: a "Connect Client…" menu item opens a SwiftUI form that lists registry clients (stat-only, TCC-safe), resolves detail + a no-write preview on selection, and performs connect / session-scoped undo / disconnect with the preview-before-write discipline. Two additive backend changes carry it: the preview response gains the sanitized existing-entry content plus an opaque precondition token, and the connect write validates that token (conflict on drift). The legacy preview-less dashboard connect sheet is routed into the new form.
+
+## Technical Context
+
+**Language/Version**: Swift 5.9 (SwiftUI sheet + AppKit menu) + Go 1.25 (core)
+**Primary Dependencies**: existing `internal/connect` package (registry, preview, connect, undo, backup), `internal/httpapi/connect.go` routes; Swift `APIClient` over Unix socket (admin context)
+**Storage**: none new — client config files remain core-managed; token is stateless (HMAC/hash, not persisted)
+**Testing**: `go test ./internal/connect/... ./internal/httpapi/...`, `swift test` (form state model, API model decoding), fixture-free unit tests
+**Target Platform**: macOS 13+ (SwiftUI form uses existing app baseline; no 14.4-only API needed)
+**Project Type**: Native macOS app + Go backend
+**Performance Goals**: list opens instantly from the stat-only aggregate; per-client detail+preview resolve in one round-trip each
+**Constraints**: zero client-config reads in the tray process; no config-content reads core-side on list (TCC); mutating actions require the socket transport; preview-before-write enforced structurally; session-scoped undo only
+**Scale/Scope**: 8 registry clients today; one new SwiftUI view + view model; 2 additive backend fields
+
+## Constitution Check
+
+*GATE: evaluated pre-Phase-0 and re-checked post-design — PASS, no violations.*
+
+- **I. Performance at Scale**: N/A-scale feature (8 clients); stat-only list avoids per-client file reads. PASS.
+- **II. Actor-Based Concurrency**: no new goroutines beyond request handlers; Swift view model is @MainActor with async API calls. PASS.
+- **III. Configuration-Driven Architecture**: tray keeps zero state (session-scoped undo state is UI-session state, explicitly specced); all mutations via core REST. PASS.
+- **IV. Security by Default**: preview sanitization gets explicit no-raw-secrets backend tests; the precondition token is a non-reversible hash; connect-write endpoints stay gated (agent tokens rejected); socket stays 0600. PASS — this feature strengthens the security posture (no silent overwrites).
+- **V. TDD**: state-model tests for every list/detail/preview/action state; backend tests for sanitization, token, conflict. PASS.
+- **VI. Documentation Hygiene**: connect feature docs updated with the two new fields; swagger regenerated. PASS.
+- **Core+Tray split**: form renders; core owns files. PASS.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/091-connect-client-form/
+├── spec.md, plan.md, research.md, data-model.md, quickstart.md
+├── contracts/api-deltas.md
+├── verification/manual-protocol.md
+└── tasks.md   # Phase 2 (/speckit.tasks)
+```
+
+### Source Code (repository root)
+
+```text
+# Go core (additive deltas)
+internal/connect/preview.go             # summary + precondition token + connect_refusal in ConnectPreview
+internal/connect/preview_test.go        # no-raw-secrets tests (rotated keys, bearer/env secrets, ?apikey=, user:pass@)
+internal/connect/summary.go             # NEW: EntrySummary built from non-secret projections (adoption-aware)
+internal/connect/summary_test.go        # projection whitelist, query+userinfo stripping, adopted-entry naming
+internal/connect/connect.go             # Connect accepts optional precondition token → discriminated 409 on drift
+internal/connect/connect_test.go        # token validation: create/add/replace/adopted drift, force+token, absent-token back-compat
+internal/connect/token.go               # NEW: HMAC-SHA256 token (per-instance key, length-prefixed canonical encoding,
+                                        #   resolved entry + pending entry in the preimage)
+internal/connect/token_test.go          # determinism per key, drift detection incl. masked-value + adopted-entry +
+                                        #   pending-entry (config rotation) drift, key rotation invalidates
+internal/httpapi/connect.go             # request body precondition_token; 409 action discriminator; swagger annotations
+internal/httpapi/connect_test.go        # endpoint-level: preview fields present, precondition_failed vs already_exists
+internal/server/connect_socket_e2e_test.go # NEW: SC-006 — real Unix socket → gated connect-write as admin; agent token rejected
+oas/swagger.yaml, oas/docs.go           # make swagger
+
+# Swift app (native/macos/MCPProxy/MCPProxy)
+Views/ConnectClientView.swift           # NEW: the form (list → detail+preview → actions)
+Views/ConnectClientModel.swift          # NEW: @MainActor state model (pure-testable reducer around APIClient calls)
+Views/DashboardView.swift               # legacy connect sheet routed into the new form (FR-012)
+MCPProxyApp.swift                       # "Connect Client…" menu item next to "Add Server…"; window/sheet plumbing
+API/APIClient.swift                     # clientDetail, connectPreview, connect(token+force), undo, disconnect;
+                                        #   transportKind identity + strict-socket mode for mutating requests
+Core/SocketTransport.swift              # strict-socket request option (no TCP fallback for writes)
+API/Models.swift (or ConnectModels)     # richer ClientStatus + ConnectPreview/ConnectResult models
+
+# Swift tests (native/macos/MCPProxy/MCPProxyTests)
+ConnectClientModelTests.swift           # NEW: every state/action of the model (FR-009 states, preview gating, undo scoping)
+ConnectModelsDecodingTests.swift        # NEW: decode fixtures incl. unknown client ids, new preview fields
+APIClientConnectTests.swift             # NEW: exact URLs/bodies incl. precondition token passthrough
+```
+
+**Structure Decision**: form logic lives in a view-model (`ConnectClientModel`) so the preview-before-write gating, session-scoped undo, and error surfacing are unit-testable without SwiftUI rendering; the view stays thin, mirroring how AddServerView is structured but with the state machine extracted (AddServerView's inline state is the pattern's known weakness).
+
+## Complexity Tracking
+
+No constitution violations; table intentionally empty.
diff --git a/specs/091-connect-client-form/quickstart.md b/specs/091-connect-client-form/quickstart.md
new file mode 100644
index 00000000..f0bd6673
--- /dev/null
+++ b/specs/091-connect-client-form/quickstart.md
@@ -0,0 +1,61 @@
+# Quickstart — Native Connect Client Form (Spec 091)
+
+## Build & test
+
+```bash
+# Go: connect package + endpoint tests (token, summary secrecy, conflict)
+go test ./internal/connect/... ./internal/httpapi/... -count=1
+
+# SC-006: socket → gated connect-write route end-to-end
+go test ./internal/server -run ConnectSocket -count=1
+
+# Swagger after the two contract deltas
+make swagger && make swagger-verify
+
+# Swift: model/state-machine + decoding tests
+cd native/macos/MCPProxy && swift test
+
+# Binaries
+make build
+scripts/build-swift-app.sh
+```
+
+## Manual run (isolated dev core — never the personal instance)
+
+`--config` must point at a file that already EXISTS — the core exits with
+`failed to read config file: … no such file or directory` rather than creating
+one. Seed it first:
+
+```bash
+printf '{"listen":"127.0.0.1:18091","data_dir":"/tmp/mcpproxy-091-data","mcpServers":[]}\n' \
+  > /tmp/mcpproxy-091-config.json
+
+./mcpproxy serve --listen 127.0.0.1:18091 \
+  --data-dir /tmp/mcpproxy-091-data --config /tmp/mcpproxy-091-config.json
+```
+
+Smoke-check the deltas over the core's admin socket (a preview never writes and
+never takes a backup):
+
+```bash
+curl -s --unix-socket /tmp/mcpproxy-091-data/mcpproxy.sock \
+  http://localhost/api/v1/connect/cursor/preview
+```
+
+Expect `precondition_token` (64 hex chars), `existing_entry_summary` when
+`entry_exists` is true, and `connect_refusal` for OpenCode with no config.
+
+Seed scratch client configs per
+`specs/091-connect-client-form/verification/manual-protocol.md` (create-capable
+absent, OpenCode absent, malformed, connected, unconnected) and run its checks.
+
+## Invariants to keep green
+
+- No raw secret ever appears in a preview response (`internal/connect` tests
+  incl. rotated keys, bearer/env secrets, `?apikey=`, `user:pass@`).
+- 409 `precondition_failed` + zero write on token drift (file OR adopted-entry
+  OR pending-entry drift); absent token = legacy behavior.
+- Connect control cannot exist before a refusal-free preview has rendered
+  (model tests); replace flows send force+token, never force alone.
+- Tray performs zero client-config file reads; list causes zero content reads;
+  mutating requests are strict-socket (no silent TCP fallback).
diff --git a/specs/091-connect-client-form/research.md b/specs/091-connect-client-form/research.md
new file mode 100644
index 00000000..27e703b7
--- /dev/null
+++ b/specs/091-connect-client-form/research.md
@@ -0,0 +1,119 @@
+# Research — Native Connect Client Form (Spec 091, rev 2)
+
+Rev 1 was reviewed by an internal adversarial 3-lens panel (Codex quota-locked,
+Gemini tier sunset); its P1/P2 findings reshaped D1/D2/D6/D8 and added D9/D10.
+
+## D1. Precondition token: keyed HMAC over resolved state + pending entry
+
+- **Decision**: `internal/connect/token.go` computes HMAC-SHA256 with a
+  per-core-instance random in-memory key over a canonical, **length-prefixed**
+  encoding of `(clientID, configPath, requestedServerName, fileExists,
+  resolvedEntryName, rawResolvedEntry, pendingEntrySerialized)`. "Resolved"
+  means: the same equivalent-entry adoption lookup the write performs
+  (`findEquivalentJSONServerName` for OpenCode-style adoption) picks the entry
+  the write would actually replace — under whatever key it lives; that lookup
+  is deterministic (exact name first, then sorted order) and resolved ONCE per
+  operation, so the token and the write cover the same entry. The requested
+  name and client are bound too: `resolvedEntryName` is empty for every absent
+  target, so without them a token minted for one entry name validated a write
+  under any other, creating a key the user never previewed. The pending entry (unmasked, as it would be
+  written) is included so proxy-side drift (API-key rotation,
+  `require_mcp_auth` toggle, listen-address change) also invalidates the token.
+  Validation recomputes at write time; mismatch → discriminated 409, no write.
+  Absent token → legacy behavior.
+- **Rationale (panel findings closed)**: plain sha256 was an offline
+  confirmation oracle for weak user secrets (preimage fully known but the
+  masked value); pipe-joined fields were ambiguous; the unresolved
+  `serversMap[serverName]` read missed the adopted-entry drift class; file-only
+  state missed pending-entry drift (credential embedded without the FR-004
+  notice ever shown).
+- **Alternatives**: mtime/size (misses same-size edits); server-side revision
+  store (state + expiry for no benefit); unkeyed hash (oracle).
+
+## D2. Existing-entry disclosure: structural summary by construction (NOT masking)
+
+- **Decision**: there is **no reusable masking routine** — the pending entry is
+  masked at *construction* (`entryParams(true)` substitutes the mask constant),
+  which cannot sanitize arbitrary user-authored content. So the preview never
+  renders existing-entry content at all. Instead `internal/connect/summary.go`
+  (new) builds `existing_entry_summary` from parsed non-secret projections
+  only: resolved entry name, type, endpoint with query **and userinfo**
+  stripped, command, header NAMES, env NAMES. Values other than the stripped
+  endpoint/command never leave the core. Tests feed rotated keys, bearer
+  headers, env secrets, `?apikey=` and `user:pass@` URLs and assert none
+  appear in the serialized response.
+- **Rationale**: whitelist-by-construction is provable; masking heuristics
+  over arbitrary content are not. The user's real need in the stale-entry case
+  is "which endpoint/name is being replaced", which the summary answers.
+
+## D3. Aggregate list stays stat-only; detail resolves on selection
+
+- Unchanged from rev 1: list binds to `GET /api/v1/connect` (config-presence
+  only, no content reads, no TCC prompts); selection fires
+  `GET /api/v1/connect/{client}` + `/preview`. One user-initiated content read
+  per selection.
+
+## D4. Swift shape: extracted @MainActor view model, thin SwiftUI view
+
+- Unchanged from rev 1: `ConnectClientModel` reducer owns list/detail/preview/
+  action/undo state; the Connect control is derived (exists only with a
+  resolved, input-matching, refusal-free preview) — SC-002's structural
+  guarantee; `AddServerView`'s inline-state pattern deliberately not repeated.
+
+## D5. Menu + window plumbing
+
+- Unchanged from rev 1: "Connect Client…" beside "Add Server…" in
+  `MCPProxyApp.swift`; direct sheet presentation (no asyncAfter chains); the
+  legacy preview-less dashboard connect sheet (`DashboardView.swift` ~1275)
+  routes into the same presentation path (FR-012).
+
+## D6. Off-socket behavior: explicit transport seam + strict-socket writes
+
+- **Decision**: `APIClient` gains an explicit transport identity
+  (`transportKind: .unixSocket | .tcp`) derived from its configured endpoint,
+  AND the three mutating calls (connect/undo/disconnect) send in a
+  strict-socket mode that FAILS (surfaced as an actionable error) instead of
+  falling back to TCP when the socket disappears mid-session —
+  `SocketTransport`'s per-request fallback ("otherwise let it go out over
+  TCP") is exactly the hole the panel found. The model disables mutating
+  controls when `transportKind != .unixSocket`.
+- **Rationale**: rev 1 assumed a transport-identity API that does not exist;
+  and without strict mode, a mid-session socket loss silently sent admin
+  writes over TCP, violating the spec's non-socket edge case.
+
+## D7. Reachability polling
+
+- Unchanged: 2 s cancellable poll while unreachable (FR-013).
+
+## D8. Non-create-capable absent case: refusal comes from the PREVIEW
+
+- **Decision**: the preview handler runs the same guard the write uses
+  (`connect.go`'s absent-config refusal) and populates `connect_refusal`
+  (verbatim reason). The model maps a refusal-bearing preview to a
+  non-connectable state: Connect control absent, refusal shown. No client-side
+  capability table; capability knowledge stays core-side.
+- **Rationale (panel P1 closed)**: rev 1's click-to-discover contradicted the
+  spec's "non-connectable" requirement and rendered a false
+  "file will be created… Undo removes it" statement for OpenCode; manual check
+  9d ("Connect unavailable") was unsatisfiable without this third field.
+
+## D9. Conflict discrimination and force semantics (new)
+
+- **Decision**: the write's 409 body carries `action`:
+  `"precondition_failed"` (token drift → model auto-re-previews) vs
+  `"already_exists"` (legacy). Replace-classified flows send `force=true`
+  together with the token; the token is the overwrite safety. `force=true` +
+  stale token still refuses.
+- **Rationale (panel P1 closed)**: without the discriminator and the force
+  rule, a replace flow either looped forever on the legacy 409 (force=false)
+  or could not distinguish "re-preview" from "retry with force".
+
+## D10. SC-006 test home (new)
+
+- **Decision**: `internal/server/connect_socket_e2e_test.go` (new) starts the
+  server on a real Unix socket and drives `POST /api/v1/connect/{client}`
+  end-to-end, asserting the socket caller reaches the gated write route with
+  admin context (and that an agent-token TCP caller is still rejected).
+  Quickstart's test commands gain `./internal/server -run ConnectSocket`.
+- **Rationale (panel P1 closed)**: rev 1 planned no home for SC-006; httptest
+  cannot prove the listener→tagging→auth-conversion→gate path.
diff --git a/specs/091-connect-client-form/spec.md b/specs/091-connect-client-form/spec.md
new file mode 100644
index 00000000..1fa8d9d5
--- /dev/null
+++ b/specs/091-connect-client-form/spec.md
@@ -0,0 +1,158 @@
+# Feature Specification: Native Connect Client Form
+
+**Feature Branch**: `091-connect-client-form`
+**Created**: 2026-07-31
+**Status**: Approved after 4 Codex rounds; revised round 5 by internal adversarial panel (Codex quota-locked, Gemini tier sunset) — preview summary/refusal/token hardening
+**Input**: User description: "Add client must open macOS app form — a native tray menu item and form for connecting AI clients (Claude Code, Cursor, etc.) to the proxy, replacing the current Web-UI-only flow."
+
+## Context
+
+The proxy already knows how to connect AI client applications: a client registry (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex, Gemini, OpenCode) with per-client status, a no-write preview, a config-writing connect action that backs up an existing client config first, plus undo and disconnect. Today the only preview-first UI is the Web UI's Connect modal; the native app has a legacy dashboard sheet that connects *without* preview. Field feedback: "Add server, Add client must open macOS app form."
+
+A standing product rule (learned from earlier feedback on this exact flow) applies: any config-mutating connect flow must show the pending change and the backup consequences BEFORE the action button.
+
+Two platform realities shape this design:
+
+- The aggregate client list is deliberately cheap (file-existence checks only) so that merely opening a list does not trigger macOS data-access prompts for every client's container. Reading a config's *contents* — needed to know "connected or not" and to build a preview — happens only for a client the user explicitly selects.
+- Undo depends on the backup name returned by the connect that created it; the core keeps no cross-session undo state. Undo is therefore an in-form affordance for the connect you just performed (identical to the Web UI's behavior).
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Connect a client from the tray (Priority: P1)
+
+The user picks "Connect Client…" from the tray menu. A native window lists the known AI clients, showing which have a config file present. They select Claude Code; the form reads its state (connected or not) and shows a preview: the exact entry that will be written, the config file path, whether an existing entry is being replaced (with a structural summary of it — name, type, endpoint, never secret values), and what the safety net is — a timestamped backup for an existing file, or "a new file will be created; Undo removes it" when none exists. They press Connect, and the row flips to connected.
+
+**Why this priority**: This is the requested capability — the entire feature exists so this journey never leaves the native app.
+
+**Independent Test**: With a core running, open the form, select a client whose config exists, verify the preview renders the pending entry, path, and backup consequence before any write occurs, connect, and verify the client's status updates.
+
+**Acceptance Scenarios**:
+
+1. **Given** the tray menu is open, **When** the user chooses "Connect Client…", **Then** a native window opens listing every registry client with name, icon, and config-presence state — no browser is involved, and no client config *contents* are read yet.
+2. **Given** the user selects a client, **When** its detailed state loads, **Then** the form shows whether it is currently connected and renders the preview: the entry text that will be written, the config path, and — when an entry already exists — a structural summary of the entry being replaced.
+3. **Given** the preview is displayed, **When** the user presses Connect, **Then** the write happens (backup first when the file existed), and the form shows the refreshed state without being reopened.
+4. **Given** a create-capable client whose config file does not exist, **When** the preview renders, **Then** it states that a new file will be created at the path and that Undo will remove that file (no pre-existing content exists to back up).
+5. **Given** the core is unreachable, **When** the form opens, **Then** it shows a clear "core not running" state, retries in the background, and populates when the core becomes reachable without reopening.
+6. **Given** a client the registry marks unsupported on this platform, **When** the list renders, **Then** the client appears disabled with the reason, not hidden.
+
+---
+
+### User Story 2 - See client configuration state at a glance (Priority: P2)
+
+The user opens the form to check which of their AI tools have a config the proxy recognizes. The list answers with the cheap truth (config present / no config found / unsupported), and the user drills into any client to see the authoritative state (connected to this proxy or not, and under which entry name) — an explicit, user-initiated read.
+
+**Why this priority**: Complements the tray's Clients presence section (spec 090): presence says who *talked* recently; this form says who is *configured* to talk.
+
+**Independent Test**: Seed config files for some clients and not others; open the form; verify list states come from existence checks only; select a client and verify the connected/not-connected resolution appears only then.
+
+**Acceptance Scenarios**:
+
+1. **Given** clients with and without config files, **When** the form opens, **Then** rows show "config present" / "no config found" respectively, and no config contents have been read.
+2. **Given** a selected client whose config contains the proxy entry, **When** its detail loads, **Then** the row shows connected and the entry name in use.
+3. **Given** the form is open, **When** a connect or disconnect completes, **Then** the affected client's state refreshes from the core — the tray process never reads or parses client config files itself.
+
+---
+
+### User Story 3 - Undo or disconnect safely (Priority: P2)
+
+After connecting, the user changes their mind. While the form remains open, Undo reverses the connect they just performed: restoring the timestamped backup, or removing the file the connect created. Disconnect (for any connected client, any time) removes the proxy entry after a confirmation that names the file and the entry.
+
+**Why this priority**: A config-writing feature without a visible way back teaches users not to trust it.
+
+**Independent Test**: Connect a client, then undo; verify the config returns to its pre-connect content (or the created file is removed) and the row reflects it. Disconnect a connected client; verify the entry is removed after confirmation.
+
+**Acceptance Scenarios**:
+
+1. **Given** a connect just performed in this open form, **When** the user chooses Undo, **Then** the pre-connect state is restored (backup restored, or created file removed) and the row reflects it.
+2. **Given** the form was closed and reopened after a connect, **When** the row renders, **Then** Undo is not offered (undo state is scoped to the connect performed in the open form) — Disconnect remains available.
+3. **Given** a connected client, **When** the user chooses Disconnect, **Then** a confirmation names the config file and the entry to be removed before anything happens, and the entry is removed after.
+
+---
+
+### Edge Cases
+
+- **Existing entry pointing elsewhere** (stale port/URL): the preview shows the structural summary of the existing entry alongside the replacement; connecting requires the same explicit confirmation, no silent overwrite.
+- **Credential embedding**: when the pending entry would contain the admin credential, the preview says so explicitly.
+- **Malformed config**: a client whose config cannot be parsed shows a "config unreadable" state with the path; the Connect control is absent (a write would fail) and the user is pointed at the file.
+- **Access denied**: a client whose config the core cannot read shows "access not granted" with remediation guidance; the Connect control is absent until access resolves.
+- **Preview staleness**: changing any input (selected client, entry-name override) discards the preview and fetches a fresh one; the Connect button is bound to the currently rendered preview. Every preview carries an opaque, keyed precondition token over the raw pre-write state (file existence + resolved target entry presence and raw value, including an adopted equivalent entry) and the pending entry content; the write echoes it, and the core rejects with a discriminated conflict when anything has drifted — a file appearing after an absent-file preview, disappearing after an add/replace preview, the entry changing (even in ways the summary hides), or the proxy's own config changing what would be written — upon which the form re-previews. Replace-classified connects send the overwrite flag together with the token; the form never sends the overwrite flag without a valid token.
+- **Client requiring an existing config** (e.g. OpenCode): when its config file is absent, the core refuses to create one; the PREVIEW already carries that refusal (the preview runs the same guard the write would), so the Connect control is absent and the refusal is shown verbatim — the user never discovers it by clicking. The generic create statement applies only to clients the core will create configs for.
+- **Double-click protection**: action buttons disable while a request is in flight.
+- **Unknown client** (core newer than app): rendered by name with a default icon, fully functional.
+- **Non-socket transport**: when the app is not talking to the core over its private local socket (administrative transport), the mutating actions are disabled with an explanation; the list and previews remain available if the transport permits.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The tray menu MUST offer a "Connect Client…" item adjacent to the existing "Add Server…" item, opening a native form; no step of the journey may require a browser.
+- **FR-002**: The form's list MUST come from the core's aggregate client registry (existence-only checks): name, icon, platform support, and config-presence. The tray process MUST NOT read or parse client config files, and opening the list MUST NOT cause client config *contents* to be read.
+- **FR-003**: Selecting a client MUST fetch its detailed state (connected / not connected, entry name, access state) and a no-write preview, displayed before the Connect control exists: the entry text to be written, the config file path, a sanitized structural summary of the existing entry when one is present (constructed ONLY from non-secret projections: entry type, endpoint address with query parameters and userinfo stripped, command, and the names — never the values — of headers and environment variables; the summary reflects the same equivalent-entry the write would replace, even when it lives under a different key), and the safety-net statement — "a timestamped backup of this file will be created alongside it" for an existing file, or "this file does not exist; it will be created, and Undo removes it" otherwise. When the preview carries the core's connect refusal (e.g. a non-create-capable client with an absent config), the Connect control does not exist and the refusal is shown verbatim.
+- **FR-004**: When the pending entry would embed the admin credential into the client's config, the preview MUST say so.
+- **FR-005**: Connect MUST perform the existing connect operation (backup when the file exists, then write), and the form MUST refresh the client's state afterward. The write request MUST echo the preview's opaque precondition token, derived backend-side (keyed, non-reversible) from: raw file existence, the presence and raw value of the entry the write would actually replace (resolving the same equivalent-entry adoption the write performs), and the exact entry content that would be written — so external file drift AND proxy-side configuration drift (credential rotation, auth toggle, address change) both invalidate it, for all change kinds. The core MUST reject a stale-token write with a machine-readably discriminated conflict (distinct from "entry already exists"), writing nothing; the form then re-runs the preview instead of retrying. For a replace-classified preview the form sends the overwrite flag TOGETHER with the token (the token is the safety); it never sends the overwrite flag without a valid token. The sanitized summary is display-only and never used for comparison.
+- **FR-006**: Undo MUST be offered exactly for a connect performed while the form has been open (using that connect's returned backup identity; for a created file, undo removes it) and MUST disappear once used or once the form closes. Disconnect MUST be offered for any connected client, preceded by a confirmation naming the config file and entry.
+- **FR-007**: The proxy entry name defaults to the standard name; an advanced, collapsed-by-default field allows overriding it. Any change to it discards and refetches the preview.
+- **FR-008**: Failures (unreachable core, rejected write, preview error) MUST present the core's message text unaltered in content (a status-code prefix is acceptable); action buttons disable while a request is in flight.
+- **FR-009**: Client states beyond the happy path MUST render with defined labels and affordances: unsupported-on-platform (disabled + reason), config unreadable (Connect control absent + path), access not granted (Connect control absent + remediation), unknown client id (generic rendering, fully functional).
+- **FR-010**: The form MUST be fully keyboard-navigable and announced correctly by VoiceOver: list navigation, preview content, and action buttons, with stable accessibility identifiers for testing.
+- **FR-011**: Opening the form MUST NOT modify anything; the only mutations are the explicit Connect / Undo / Disconnect confirmations.
+- **FR-012**: The legacy native dashboard connect control (which connects without preview) MUST be routed into this form, so no native path performs a connect without the preview step.
+- **FR-013**: While the core is starting or unreachable, the form MUST show a waiting state and poll (every 2 seconds) until reachable, then populate without user action.
+
+### Key Entities
+
+- **Registry client (list row)**: identity (name, icon), platform support, config-presence — the cheap, prompt-free view.
+- **Client detail (selected)**: connected state, entry name in use, access state (readable / absent / unreadable / denied) — the authoritative, user-initiated view.
+- **Connect preview**: the entry text to be written, config path, a structural summary of the existing entry when present (built only from non-secret projections — type, query+userinfo-stripped endpoint, command, header/env names — never arbitrary values, so secrecy holds by construction rather than by masking heuristics; reflects the adopted equivalent entry when the write would replace one under a different key), credential-embedding flag, an opaque keyed precondition token binding the preview to the raw pre-write state AND the pending entry content, an optional connect-refusal (verbatim core reason, e.g. non-create-capable client with absent config), and the derived safety-net statement (backup vs. create-and-undo-removes). Derivation of "create vs add vs replace" is defined: file absent → create (or refusal present → non-connectable); readable without entry → add; readable with entry (including an adopted equivalent) → replace; unreadable/denied → no pending-entry preview; the Connect control is absent.
+- **Connect action result**: success (with backup identity for Undo) or the core's reason; drives the in-form Undo affordance.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: Following the manual protocol (`specs/091-connect-client-form/verification/manual-protocol.md`), a user goes from opening the tray menu to a connected client in under 30 seconds with no browser involved (stopwatch step in the protocol).
+- **SC-002**: Every config write performed through the form is structurally preceded by a rendered preview for the exact (client, entry-name) pair being written — the Connect control does not exist before that preview has rendered, and input changes destroy it; verified by unit tests of the form's state model.
+- **SC-003**: The undo round-trip test restores the client's config to its exact pre-connect content for the existing-file case, and removes the created file for the new-file case.
+- **SC-004**: The tray process performs zero client-config file reads (all state via the core); opening the form's list causes zero config-content reads core-side (existence checks only).
+- **SC-005**: Unit tests of the form's state model cover: all list states of FR-009, the detail resolution, preview derivation for all four access states, connect success/conflict/failure, session-scoped undo appearance and disappearance, and disconnect confirmation. Visual flow is covered by the manual protocol.
+- **SC-006**: An integration test proves a request over the private local socket reaches the gated connect-write route as an administrative caller end-to-end (complementing the existing separate middleware tests).
+
+## Assumptions
+
+- Backend surface: existing endpoints suffice, with additive changes and no new endpoints: (1) the preview response gains a structural existing-entry summary (non-secret projections only; backend tests must prove no raw secret value can enter the response, including rotated credentials and user-authored secrets), an opaque KEYED precondition token (HMAC over canonical, length-prefixed raw pre-write state — resolved entry presence/value plus the pending entry content — using a per-instance in-memory key, so the token is neither reversible nor an offline confirmation oracle), and a connect-refusal field populated by the same guard the write uses; (2) the connect write request gains an optional precondition-token field, rejected with a machine-readably discriminated conflict when stale (backward-compatible: absent token preserves today's behavior, existing consumers unchanged). Undo/disconnect behavior is unchanged.
+- The tray's administrative transport is the private local socket; socket callers are treated as administrative by the core (verified: socket connections are tagged and granted admin context; the write gate rejects only restricted agent tokens). TCP fallback exists for reads, so mutating actions require the socket per the non-socket edge case — enforced structurally: the form's mutating requests are sent in a strict-socket mode that FAILS rather than silently falling back to TCP if the socket disappears mid-session, and the mutating controls are disabled whenever the transport is not the socket.
+- "No config found" is a statement about the config file, not about whether the application is installed; labels say "no config found", never "not installed".
+- Disconnect has no exact-diff preview endpoint; a confirmation naming file and entry is the defined and sufficient disclosure.
+- Bridge/binary installation for clients that need a bridge is out of scope; such clients surface whatever state the core reports.
+- The form is a window/sheet of the existing native app, consistent with the Add Server form's presentation.
+
+## Out of Scope
+
+- Web UI changes (the Web UI Connect modal remains as is).
+- Adding new clients to the registry or changing detection/config-writing logic in the core.
+- Cross-session (persistent) undo — would require new backend state.
+- Application-installation detection (beyond config presence).
+- The "Add Server…" form (already native and shipped).
+- Windows/Linux tray parity.
+- Automatic connection health checks after connect (spec 090's presence section covers observed traffic).
+
+## Commit Message Conventions *(mandatory)*
+
+### Issue References
+- ✅ **Use**: `Related #[issue-number]` - Links the commit to the issue without auto-closing
+- ❌ **Do NOT use**: `Fixes #[issue-number]`, `Closes #[issue-number]`, `Resolves #[issue-number]` - These auto-close issues on merge
+
+### Co-Authorship
+- ❌ **Do NOT include**: `Co-Authored-By: Claude <noreply@anthropic.com>`
+- ❌ **Do NOT include**: "🤖 Generated with [Claude Code](https://claude.com/claude-code)"
+
+### Example Commit Message
+```
+feat(macos): native Connect Client form
+
+Related #[issue-number]
+
+Tray menu item and native form over the core connect surface: status
+list, preview-before-write with backup notice, connect, session-scoped
+undo, disconnect.
+```
diff --git a/specs/091-connect-client-form/tasks.md b/specs/091-connect-client-form/tasks.md
new file mode 100644
index 00000000..03f3a471
--- /dev/null
+++ b/specs/091-connect-client-form/tasks.md
@@ -0,0 +1,67 @@
+# Tasks: Native Connect Client Form
+
+**Input**: Design documents from `/specs/091-connect-client-form/` (spec.md rev 2.2, plan.md, research.md D1–D10, data-model.md, contracts/api-deltas.md)
+**Tests**: Strict TDD — every implementation task has a distinct preceding failing-test task (a test failing to compile against a not-yet-existing symbol counts as red).
+
+Swift paths relative to `native/macos/MCPProxy/` (sources `MCPProxy/`, tests `MCPProxyTests/`); Go paths repo-relative. The Go track (Phase 2) and the Swift model work (T012+) are parallelizable — Swift tests synthesize JSON and never need a live core.
+
+## Phase 1: Setup
+
+- [x] T001 Verify green baseline on branch 091-connect-client-form: `cd native/macos/MCPProxy && swift test` and `go test ./internal/connect/... ./internal/httpapi/... -count=1` pass before any change (record pre-existing failures in specs/091-connect-client-form/verification/baseline.md). Record in baseline.md that SC-003 (undo round-trip: byte-exact restore + created-file removal) is already covered by the unchanged internal/connect/undo_test.go suite (TestUndo_RestoresByteIdenticalPreConnectFile, TestUndo_NoPriorFile_RemovesCreatedFile) — confirm both green here; manual checks 9/9b re-verify live
+
+## Phase 2: Foundational — Go contract deltas (blocking for live use; parallel to Swift model tasks)
+
+- [x] T002 [P] Write failing tests in internal/connect/summary_test.go: `EntrySummary` built ONLY from non-secret projections (entry name — including the ADOPTED equivalent entry's actual key via the same lookup the write performs —, type, endpoint with query params AND userinfo stripped, command, header NAMES, env NAMES); plus secrecy cases in internal/connect/preview_test.go feeding entries with a rotated X-API-Key header value, `--header` arg keys, bearer/env secrets, `?apikey=` URLs, and `user:pass@` URLs, asserting none of those values appear anywhere in the serialized preview response (research D2, contracts §1)
+- [x] T003 Implement internal/connect/summary.go (`EntrySummary`, adoption-aware resolution) and wire `ExistingEntrySummary` into ConnectPreview in internal/connect/preview.go; T002 green
+- [x] T004 [P] Write failing tests in internal/connect/token_test.go: HMAC-SHA256 with injected key over canonical LENGTH-PREFIXED encoding; deterministic per key; distinct tokens for — file absent↔present, resolved entry absent↔present, any raw byte change of the resolved entry (incl. a masked credential value change and an ADOPTED-entry change under a different key), any pending-entry change (API-key rotation / require_mcp_auth toggle / listen-address change); different key ⇒ different token; token contains no substring of any secret (research D1)
+- [x] T005 Implement internal/connect/token.go (`DerivePreconditionToken(key, configPath, fileExists, resolvedEntryName, rawResolvedEntry, pendingEntry)`) with a per-core-instance random in-memory key owned by the connect service; wire `PreconditionToken` into the preview response in internal/connect/preview.go; T004 green
+- [x] T006 Write failing tests (after T002 — same file): internal/connect/preview_test.go asserts `ConnectRefusal` is populated for a non-create-capable client (OpenCode) with an absent config using the SAME guard the write uses, and empty otherwise (research D8)
+- [x] T007 Implement the refusal wiring in internal/connect/preview.go (extract/reuse the write's absent-config guard from internal/connect/connect.go); T006 green
+- [x] T008 [P] Write failing tests: internal/connect/connect_test.go — write with valid token succeeds (create/add/replace incl. adopted-entry replace); stale token (each drift class) ⇒ discriminated conflict, file byte-identical after; `force=true` + stale token still refuses; absent token = legacy behavior; internal/httpapi/connect_test.go — POST body accepts `precondition_token`, 409 body carries `"action":"precondition_failed"` for drift vs `"already_exists"` for the legacy case, preview response serializes the three new fields (contracts §1–2)
+- [x] T009 Implement token validation in internal/connect/connect.go (resolve current raw state with the same adoption lookup + rebuild pending entry, compare, refuse-before-backup) and the request field + 409 discriminator + swagger annotations in internal/httpapi/connect.go; run `make swagger`; T008 green, `make swagger-verify` green
+- [x] T010 [P] Write failing SC-006 test in internal/server/connect_socket_e2e_test.go: start the server on a real Unix socket, POST /api/v1/connect/{client} over it, assert admin context reaches the gated write route end-to-end; and an agent-token TCP caller is rejected on the same route (research D10)
+- [x] T011 Make T010 green (test-only if the path already works; fix wiring if not); run `go test ./internal/connect/... ./internal/httpapi/... -count=1` and `go test ./internal/server -run ConnectSocket -count=1`
+
+## Phase 3: User Story 1 — Connect a client from the tray (P1) 🎯 MVP
+
+**Goal**: Menu item → native form → stat-only list → detail+preview on selection → token-guarded connect.
+
+**Independent test**: Drive the model with synthesized API responses; verify the preview-before-write structural guarantee and the connect flow; then the live journey via the manual protocol.
+
+- [x] T012 [US1] Write failing decode tests in MCPProxyTests/ConnectModelsDecodingTests.swift: extended ClientStatus (`icon`, `server_name`, `access_state`, `remediation` all optional; unknown client id decodes generically), ConnectPreviewModel (three new fields incl. `existing_entry_summary` object and `connect_refusal`), `changeKind` derivation for all six cases (refused / create / add / replace incl. adopted-name summary / blockedByAccess for unreadable and denied), safety-net statement derivation, credential notice flag (data-model)
+- [x] T013 [US1] Implement the models (extend ClientStatus decode in MCPProxy/API/Models.swift or a new MCPProxy/API/ConnectModels.swift; ConnectPreviewModel with changeKind) — T012 green
+- [x] T014 [US1] Write failing tests in MCPProxyTests/APIClientConnectTests.swift: exact URLs/bodies for `clientDetail(id)`, `connectPreview(id, serverName)`, `connect(id, serverName, force, preconditionToken)`, `undoConnect(id, backupIdentity)`, `disconnect(id)`; `transportKind` reports `.unixSocket` vs `.tcp` from the configured endpoint; mutating calls use strict-socket mode — with the socket gone, the request FAILS instead of falling back to TCP (red: none of these symbols exist)
+- [x] T015 [US1] Implement the five APIClient methods + `transportKind` in MCPProxy/API/APIClient.swift and the strict-socket request option in MCPProxy/Core/SocketTransport.swift (research D6); T014 green
+- [x] T016 [US1] Write failing state-machine tests in MCPProxyTests/ConnectClientModelTests.swift: list loading/loaded/coreUnreachable (2 s poll transitions with an injected clock); selection → detail+preview fetch; `entryName` defaults to "mcpproxy"; the Connect control EXISTS iff preview is `.resolved` for the current (selection, entryName) AND changeKind ∉ {refused, blockedByAccess} (SC-002); entry-name edit resets preview; replace flows send force=true WITH the token, never force alone; 409 `precondition_failed` → `.conflict` → automatic single re-preview (no loop on `already_exists`, which maps to `.failed`); action buttons disabled in-flight; off-socket ⇒ mutating controls disabled with explanation; core refusal (OpenCode absent) ⇒ Connect control absent + verbatim reason (data-model invariants)
+- [x] T017 [US1] Implement MCPProxy/Views/ConnectClientModel.swift (@MainActor reducer over the APIClient seam); T016 green
+- [x] T018 [US1] Write failing presentation tests (red = compile failure acceptable): MCPProxyTests/ConnectClientModelTests.swift additions asserting the menu-item action posts the shared presentation route, and the view exposes stable accessibility identifiers for list/preview/actions (FR-010)
+- [x] T019 [US1] Implement MCPProxy/Views/ConnectClientView.swift (thin SwiftUI over the model: list with state labels, preview pane — pending entry text, path, existing-entry summary, safety-net statement, credential notice, refusal — the advanced entry-name override field COLLAPSED by default (FR-007), and action bar) plus the "Connect Client…" menu item beside "Add Server…" in MCPProxy/MCPProxyApp.swift with direct sheet presentation (no asyncAfter chains, research D5); T018 and full `swift test` green
+
+**Checkpoint**: MVP — the full connect journey works natively.
+
+## Phase 4: User Story 2 — Client configuration state at a glance (P2)
+
+- [x] T020 [US2] Write failing tests in MCPProxyTests/ConnectClientModelTests.swift: list rows render "config present" / "no config found" / unsupported-disabled (+reason) from the stat-only aggregate WITHOUT any detail fetch; selecting resolves connected + entry name; after a connect/disconnect completes only the affected client's state refetches (FR-002, US2 scenarios)
+- [x] T021 [US2] Implement the list-state presentation + post-action refresh in MCPProxy/Views/ConnectClientModel.swift and ConnectClientView.swift; T020 green
+
+## Phase 5: User Story 3 — Undo and disconnect safely (P2)
+
+- [x] T022 [US3] Write failing tests in MCPProxyTests/ConnectClientModelTests.swift: undo appears ONLY after a `.succeeded` connect in this form instance (carrying that connect's backup identity; created-file case = removal), disappears on use and on form close; disconnect requires a confirmation naming config file + entry before the request fires (US3 scenarios)
+- [x] T023 [US3] Implement session-scoped undo + disconnect confirmation in MCPProxy/Views/ConnectClientModel.swift and ConnectClientView.swift; T022 green
+- [x] T024 [US3] Write failing test: the dashboard's connect action routes into the shared Connect Client presentation path and the legacy preview-less sheet is gone (red: assert against the new routing symbol) in MCPProxyTests/ConnectClientModelTests.swift or a small MCPProxyTests/DashboardRoutingTests.swift
+- [x] T025 [US3] Route MCPProxy/Views/DashboardView.swift (~line 1275 legacy connect sheet) into the new form's presentation path, deleting the preview-less flow (FR-012); T024 and full `swift test` green
+
+## Phase 6: Polish & Cross-Cutting
+
+- [x] T026 Gates + docs: run `./scripts/run-linter.sh`, `go test ./internal/...`, `cd native/macos/MCPProxy && swift test`, `make swagger-verify`; document the two connect-surface deltas in the connect feature docs (docs/features/, wherever connect is documented — create a short section if absent); validate specs/091-connect-client-form/quickstart.md commands; mark manual protocol status (NOT RUN unless actually run); verify all checkboxes T001–T025, then this one
+
+## Dependencies & Execution Order
+
+- Phase 1 first. Phase 2 (Go) and the Swift chain T012→T019 can run in PARALLEL (Swift tests synthesize JSON); T011 must complete before any LIVE (manual-protocol) verification, not before Swift unit work.
+- Within Phase 2, [P] test tasks (T002/T004/T008/T010) touch distinct test files and may be authored in parallel; T006 shares preview_test.go with T002 and follows it; implementation tasks are sequential where they share preview.go (T003 → T005 → T007) and connect.go/httpapi (T009 → T011).
+- Swift: T012→T013→T014→T015→T016→T017→T018→T019 strictly sequential (shared files); US2 (T020–T021) and US3 (T022–T025) follow US1 and are sequential with each other (same model/view files).
+- T026 last.
+
+## Implementation Strategy
+
+MVP = Phases 1–3. US2 → US3 → polish. Each pair ends green before the next; commits per pair, conventional format, no AI attribution. If the pre-commit hook demands ROADMAP.md regeneration on tasks.md checkbox changes, run `python3 scripts/gen-roadmap.py` and stage it.
diff --git a/specs/091-connect-client-form/verification/baseline.md b/specs/091-connect-client-form/verification/baseline.md
new file mode 100644
index 00000000..d14908c0
--- /dev/null
+++ b/specs/091-connect-client-form/verification/baseline.md
@@ -0,0 +1,67 @@
+# T001 — Green baseline on branch `091-connect-client-form`
+
+Recorded before any spec-091 change. Go track only; the Swift (`swift test`)
+half of T001 is recorded by the Swift track in the section reserved below.
+
+## Go — `go test ./internal/connect/... ./internal/httpapi/... -count=1`
+
+Toolchain: `go1.25.5 darwin/arm64`. Baseline commit: `21049e7e9`.
+
+```
+ok  	github.com/smart-mcp-proxy/mcpproxy-go/internal/connect	0.322s
+ok  	github.com/smart-mcp-proxy/mcpproxy-go/internal/httpapi	0.664s
+```
+
+**Pre-existing failures: none.** Both packages are fully green, so any red
+observed during Phase 2 is attributable to the spec-091 change under test.
+
+## SC-003 — already covered by the unchanged undo suite
+
+SC-003 ("the undo round-trip restores the client's config to its exact
+pre-connect content for the existing-file case, and removes the created file for
+the new-file case") requires **no new Go test**: `internal/connect/undo_test.go`
+already asserts exactly both halves, and spec 091 does not modify `undo.go`.
+
+Confirmed green at baseline:
+
+```
+$ go test ./internal/connect/ -run 'TestUndo_RestoresByteIdenticalPreConnectFile|TestUndo_NoPriorFile_RemovesCreatedFile' -count=1 -v
+=== RUN   TestUndo_RestoresByteIdenticalPreConnectFile
+--- PASS: TestUndo_RestoresByteIdenticalPreConnectFile (0.00s)
+=== RUN   TestUndo_NoPriorFile_RemovesCreatedFile
+--- PASS: TestUndo_NoPriorFile_RemovesCreatedFile (0.00s)
+PASS
+ok  	github.com/smart-mcp-proxy/mcpproxy-go/internal/connect	0.178s
+```
+
+- `TestUndo_RestoresByteIdenticalPreConnectFile` → byte-exact restore of the
+  pre-connect file (existing-file case).
+- `TestUndo_NoPriorFile_RemovesCreatedFile` → removal of the file the connect
+  created (new-file case).
+
+These two must stay green through Phase 2 (they are part of the
+`./internal/connect/...` run in T011). Manual protocol checks 9 / 9b re-verify
+the same round-trip live against a running core; that live re-verification is
+the only SC-003 work remaining.
+
+## Swift — `cd native/macos/MCPProxy && swift test`
+
+Toolchain: `Apple Swift version 6.3.3 (swiftlang-6.3.3.1.3)`, target
+`arm64-apple-macosx26.0`, package tools-version 5.9. Baseline commit `075adaed3`
+(same tree as the Go baseline above — no spec-091 source change yet).
+
+```
+Test Suite 'MCPProxyPackageTests.xctest' passed at 2026-07-31 18:07:08.149.
+	 Executed 502 tests, with 0 failures (0 unexpected) in 34.630 (34.660) seconds
+Test Suite 'All tests' passed at 2026-07-31 18:07:08.149.
+	 Executed 502 tests, with 0 failures (0 unexpected) in 34.630 (34.666) seconds
+✔ Test run with 0 tests in 0 suites passed after 0.001 seconds.
+```
+
+**Pre-existing failures: none.** All 502 XCTest cases pass (the swift-testing
+runner reports 0 suites — the package has no swift-testing tests). Any red seen
+in the Swift track from here is attributable to the spec-091 change under test.
+
+The Swift tasks (T012+) synthesize API JSON through a stub `URLProtocol` and an
+injected data-source seam, so none of them requires a running core; the Go track
+can land in parallel without affecting this baseline.
diff --git a/specs/091-connect-client-form/verification/manual-protocol.md b/specs/091-connect-client-form/verification/manual-protocol.md
new file mode 100644
index 00000000..e3f95679
--- /dev/null
+++ b/specs/091-connect-client-form/verification/manual-protocol.md
@@ -0,0 +1,85 @@
+# Manual Verification Protocol — Native Connect Client Form (Spec 091)
+
+Run on the built app (`scripts/build-swift-app.sh`) against a dev core
+(isolated data dir + config, high port). Capture screenshots into
+`specs/091-connect-client-form/verification/shots/`.
+
+## Setup
+
+1. Seed client configs in a scratch HOME (or point the core's client registry
+   paths at scratch copies): one client with an mcpproxy entry (connected),
+   one with a config but no entry, one CREATE-CAPABLE client with no config
+   file (e.g. Cursor), one non-create-capable client with no config file
+   (OpenCode), and one with a deliberately malformed config (invalid JSON).
+2. Start the core; start the app connected over the local socket.
+
+## Checks
+
+| # | Check | Expect | Screenshot |
+|---|-------|--------|------------|
+| 1 | Menu item | "Connect Client…" next to "Add Server…" | `01-menu.png` |
+| 2 | List states | config present / no config found / unsupported-disabled rows | `02-list.png` |
+| 2b | No content reads on open | run once against a REAL client location under App-Data TCC (e.g. actual Claude Desktop container): opening the list triggers no TCC prompt; alternatively verify via core logs that zero config-content reads occur on list | `02b-tcc.png` or log excerpt |
+| 3 | SC-001 stopwatch | menu → connected client < 30 s, no browser | note time below |
+| 4 | Preview (add) | entry text + path + timestamped-backup statement, before any Connect control | `03-preview-add.png` |
+| 5 | Preview (replace) | structural summary of the existing entry (name/type/query+userinfo-stripped endpoint/header+env names — no secret values) AND the replacement both visible; for an adopted equivalent entry the summary names its actual key | `04-preview-replace.png` |
+| 6 | Preview (create) | "file will be created… Undo removes it" statement | `05-preview-create.png` |
+| 7 | Credential notice | shown when entry embeds the admin credential | `06-credential.png` |
+| 8 | Connect + refresh | row flips to connected without reopening | `07-connected.png` |
+| 9 | Undo (session) | Undo visible after connect; restores config byte-exact (diff the file); gone after form reopen | `08-undo.png` |
+| 9b | Undo (created file) | for the create-capable no-config client: connect creates the file, Undo removes it (verify file absent afterwards) | `08b-undo-create.png` |
+| 9c | Conflict precondition | between preview and Connect, externally change ONLY a masked credential value inside the existing entry: core rejects with conflict (token detects what sanitization hides), form re-previews | `08c-conflict.png` |
+| 9d | Non-create-capable absent | OpenCode with no config: Connect unavailable, core refusal shown verbatim | `08d-opencode.png` |
+| 10 | Disconnect | confirmation names file + entry; entry removed after | `09-disconnect.png` |
+| 11 | Malformed config | "config unreadable" state, Connect control absent | `10-malformed.png` |
+| 12 | Core down | waiting state; auto-populates when core starts (≤ 2 s poll) | `11-waiting.png` |
+| 13 | Legacy path | dashboard connect control routes into this form (no preview-less native connect remains) | `12-dashboard.png` |
+| 14 | VoiceOver | ⌘F5: list rows, preview text, and buttons announced; identifiers stable | note below |
+
+## Results (executed)
+
+**Status: RUN 2026-08-01 06:22–06:40** — macOS 26 / Darwin 25.5.0; app built from this branch (+ `MCPPROXY_SOCKET_PATH` override), isolated core `:18091` at `/tmp/mp91` with **`HOME=/tmp/mpqa-home`** so the user's real client configs were never touched. Seeded: cursor (entry present, stale port + secret header), windsurf (config, no entry), vscode (malformed JSON), gemini (user-authored entry with `user:pass@…?apikey=` URL), claude-code/codex/opencode (absent).
+
+| # | Check | Result | Evidence |
+|---|-------|--------|----------|
+| 1 | Menu item | PASS — "Connect Client…" directly under "Add Server…" | menu listing |
+| 2 | List states | PASS — Config present / No config found / bridge note for Claude Desktop; no TCC prompts on open | `shots/02-list.png` |
+| 2b | No content reads on open | PASS (log-verified: aggregate is stat-only; detail+preview fire only on selection) | core log |
+| 3 | SC-001 stopwatch | PASS — menu → connected in ~25 s, no browser | timed run |
+| 4/5 | Preview (replace) | PASS — pending entry, path, **structural summary** (`Replacing existing entry "mcpproxy"`, Type, Endpoint `…:9999/mcp`, `Headers: X-API-Key`) — **no secret values**, backup statement, Advanced collapsed | `shots/04-preview-replace.png` |
+| 7 | Credential notice | N/A this run — dev core had `require_mcp_auth` off, so the pending entry embedded no credential (correctly no notice) | — |
+| 8 | Connect + refresh | PASS — file written, `mcp.json.bak.20260801-062951` created, green banner, row → Connected without reopening | `shots/07-connected.png` |
+| 9 | Undo (session) | PASS — Undo appeared post-connect; restored the file **byte-exactly** (md5 `5e6ed766…` before == after) incl. the secret header | md5 diff |
+| 9d | Non-create-capable absent | PASS — OpenCode shows the core refusal verbatim in red; **Connect control absent** (Close only) | `shots/08d-opencode.png` |
+| 10 | Disconnect | PASS — confirmation names entry AND file before anything happens; Cancel wrote nothing (md5 unchanged) | `shots/09-disconnect.png` |
+| 11 | Malformed config | PASS — row "Config unreadable", path shown, **Connect control absent** | `shots/10-malformed.png` |
+| 14 | VoiceOver | WAIVED — user actively at the machine; AX identifiers unit-tested | — |
+
+**Waived / not run:** 6 (create-case preview — covered by 9d's sibling path and unit tests), 9b (created-file undo — unit-tested), 9c (live conflict re-preview — unit-tested incl. masked-credential drift), 12 (core-down waiting state — unit-tested 2 s poll), 13 (dashboard routing — unit-tested `DashboardConnectControl` → shared presentation path).
+
+**Observations (non-blocking):**
+- The malformed detail pane shows the path and withholds Connect, but gives no inline "why". Row label carries it. Possible polish.
+- `~/.config/opencode/opencode.json` and `~/.claude.json` **are** found correctly against a real home — verified separately (`exists=true` for claude-code, claude-desktop, cursor, codex, gemini, opencode). The "No config found" rows in these shots are an artifact of the deliberate scratch `HOME`, not a detection bug.
+
+## Results (template)
+
+**Status: NOT RUN.**
+
+No live run has happened. The automated gates (T026) are green — linter,
+`go test ./internal/...`, `swift test` (585 XCTest cases), `make swagger-verify`
+— and the model-level guarantees they cover are asserted by unit tests against
+synthesized API JSON, but every check in the table above requires the built app
+driven by a human against a running core and none of them has been executed.
+`verification/shots/` does not exist.
+
+Automated coverage does NOT substitute for these checks. In particular, checks
+2b (no TCC prompt on list), 3 (SC-001 stopwatch), 9/9b (live undo round-trip —
+the live half of SC-003, see `baseline.md`), 9c (live conflict/re-preview) and
+14 (VoiceOver) have no unit-test equivalent.
+
+- Date / macOS version / app build: —
+- SC-001 time: —
+- Checks passed: 0 / 18 (none attempted)
+- Waived: none
+- Notes: run per the Setup section above before the feature is declared
+  verified; record results by replacing this block.
diff --git a/specs/091-connect-client-form/verification/shots/02-list.png b/specs/091-connect-client-form/verification/shots/02-list.png
new file mode 100644
index 00000000..6e25c95b
Binary files /dev/null and b/specs/091-connect-client-form/verification/shots/02-list.png differ
diff --git a/specs/091-connect-client-form/verification/shots/04-preview-replace.png b/specs/091-connect-client-form/verification/shots/04-preview-replace.png
new file mode 100644
index 00000000..83cd35c2
Binary files /dev/null and b/specs/091-connect-client-form/verification/shots/04-preview-replace.png differ
diff --git a/specs/091-connect-client-form/verification/shots/07-connected.png b/specs/091-connect-client-form/verification/shots/07-connected.png
new file mode 100644
index 00000000..9f1f0dd4
Binary files /dev/null and b/specs/091-connect-client-form/verification/shots/07-connected.png differ
diff --git a/specs/091-connect-client-form/verification/shots/08d-opencode.png b/specs/091-connect-client-form/verification/shots/08d-opencode.png
new file mode 100644
index 00000000..76bec797
Binary files /dev/null and b/specs/091-connect-client-form/verification/shots/08d-opencode.png differ
diff --git a/specs/091-connect-client-form/verification/shots/09-disconnect.png b/specs/091-connect-client-form/verification/shots/09-disconnect.png
new file mode 100644
index 00000000..be6c4e11
Binary files /dev/null and b/specs/091-connect-client-form/verification/shots/09-disconnect.png differ
diff --git a/specs/091-connect-client-form/verification/shots/10-malformed.png b/specs/091-connect-client-form/verification/shots/10-malformed.png
new file mode 100644
index 00000000..5ef455a6
Binary files /dev/null and b/specs/091-connect-client-form/verification/shots/10-malformed.png differ