docs: cover PR #466 headers/env editing + Convert-to-secret + new endpoints

REST API (docs/api/rest-api.md):
- New section on Header redaction and the ••••<last2> (<N> chars) mask
  format, when reveal_secret_headers applies, and why operators rarely
  need to flip it.
- New PATCH /api/v1/servers/{name} endpoint documented with full JSON
  Merge Patch (RFC 7396) semantics: non-null upserts, JSON null deletes,
  absent keys preserved. Includes worked curl examples and the
  empty-string-is-not-delete gotcha.
- New POST /api/v1/servers/{name}/config-to-secret endpoint —
  atomically moves a header/env value out of mcp_config.json into the
  OS keyring without the client ever holding the plaintext.

CLI (docs/cli/management-commands.md):
- New `upstream patch` subcommand with --header / --header-remove /
  --env / --env-remove flags and the deep-merge guarantee that no
  un-named key gets disturbed.

Configuration guide (docs/configuration/upstream-servers.md):
- New "Headers, Environment Variables, and Secrets" section explaining
  the wire mask, the three editing surfaces (Web UI / macOS tray /
  CLI / REST), and the ${keyring:NAME} / ${env:VAR} reference shapes.
- Cross-links to the REST PATCH reference, the CLI subcommand, and the
  keyring integration page.

Web UI (docs/web-ui/server-detail.md, new):
- Dedicated page for the Server Detail Configuration tab focused on
  the Headers and Environment Variables cards. Documents the value
  formats (masked literal, keyring chip, env chip, plain), the
  per-row actions (add / edit / delete / convert), and the
  convert-to-secret flow including the atomic backend swap.
- Two embedded screenshots showing the Headers card and the
  Convert-to-secret modal.

Screenshots (docs/screenshots/server-detail/):
- web-headers-card.png — the Headers card with masked Authorization
  + Convert to secret button. Captured against the live local
  instance with synapbus configured with a real Bearer token.
- web-convert-modal.png — the modal preview with auto-suggested
  secret name and the ${keyring:NAME} live preview.

Cross-references between the four pages so a reader can land anywhere
and find the relevant detail in two clicks.

Author: claude

docs/api/rest-api.md

@@ -117,6 +117,36 @@ Get server status and statistics.
 
 List all upstream servers with unified health status.
 
+##### Header redaction and the mask format
+
+By default, sensitive header values (`Authorization`, `X-API-Key`, `Cookie`,
+`Set-Cookie`, etc.) are replaced with a length-preserving mask of the form
+`••••<last2> (<N> chars)` before serialization. This applies to:
+
+- `GET /api/v1/servers` and its single-server children
+- The `/events` SSE `servers.changed` payloads
+- The `upstream_servers list` MCP tool
+
+The mask preserves enough information to identify which token is in use
+(the last two characters + total length) while keeping the secret out of
+the response. Values that are already secret references — `${keyring:NAME}`
+or `${env:VAR}` — pass through unchanged because they're labels, not
+secrets.
+
+Setting `reveal_secret_headers: true` in
+[`mcp_config.json`](../configuration/config-file.md) disables redaction on
+all three channels. This is **not normally needed**: the Web UI / macOS
+tray / CLI can edit, delete, and convert-to-secret without ever seeing
+the plaintext, because the PATCH endpoint deep-merges (omitted keys are
+preserved) and the [`config-to-secret`](#post-apiv1serversnameconfig-to-secret)
+endpoint reads the real value server-side. Flip the flag only if you
+need to inspect a raw value through the API for debugging.
+
+The MCP `upstream_servers` tool was the original motivator for redaction
+(see [PR #425](https://github.com/smart-mcp-proxy/mcpproxy-go/pull/425)) —
+a prompt-injected agent could otherwise read another upstream's PAT via
+`upstream_servers list`.
+
 **Response:**
 ```json
 {
@@ -167,6 +197,118 @@ List all upstream servers with unified health status.
 | `detail` | string | Optional additional context about the status |
 | `action` | string | Suggested remediation: `login`, `restart`, `enable`, `approve`, `view_logs`, or empty |
 
+#### PATCH /api/v1/servers/{name}
+
+Partial update of an existing upstream server. All request fields are optional;
+omitted fields are preserved as-is.
+
+The map-typed fields `headers` and `env` follow **JSON Merge Patch
+([RFC 7396](https://www.rfc-editor.org/rfc/rfc7396))** semantics:
+
+| Value in patch body | Effect on stored map |
+|---|---|
+| key present with a non-null string value | upsert (add or replace that key) |
+| key present with JSON `null` | delete that key |
+| key absent from the patch body | preserve as-is |
+
+This is the same convention the MCP `upstream_servers patch` tool uses. It
+lets the Web UI / macOS tray / CLI send a minimal diff — keys that match
+the server's current masked view (`••••<last2> (<N> chars)` — see
+[Header redaction](#header-redaction-and-the-mask-format) below) simply stay
+out of the patch body, so the real stored value is never overwritten by the
+mask string.
+
+**Request body** ([`AddServerRequest`](https://github.com/smart-mcp-proxy/mcpproxy-go/blob/main/internal/httpapi/server.go) — all fields optional):
+
+```json
+{
+  "url": "https://api.example.com/mcp",
+  "command": "uvx",
+  "args": ["mcp-server-foo"],
+  "env": {"API_KEY": "new-value", "OLD_VAR": null},
+  "headers": {"X-Trace": "on", "X-Stale": null},
+  "working_dir": "/path/to/dir",
+  "protocol": "http",
+  "enabled": true,
+  "quarantined": false,
+  "isolation": {"enabled": true, "image": "node:20"}
+}
+```
+
+**Examples:**
+
+```bash
+# Rotate a Bearer token without touching anything else on the server
+curl -X PATCH -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
+  -d '{"headers":{"Authorization":"Bearer new-token"}}' \
+  http://127.0.0.1:8080/api/v1/servers/synapbus
+
+# Remove a stale header (the JSON null is the delete signal)
+curl -X PATCH -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
+  -d '{"headers":{"X-Stale":null}}' \
+  http://127.0.0.1:8080/api/v1/servers/synapbus
+
+# Upsert one env var and delete another in a single round-trip
+curl -X PATCH -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
+  -d '{"env":{"LOG_LEVEL":"debug","OBSOLETE":null}}' \
+  http://127.0.0.1:8080/api/v1/servers/obsidian-pilot
+```
+
+**Notes:**
+
+- Empty string `""` is **set-to-empty**, NOT delete. JSON Merge Patch is
+  explicit about this — only the JSON `null` token deletes.
+- Boolean fields (`enabled`, `quarantined`, `reconnect_on_use`) use
+  pointer-style semantics: absent = preserve, present = explicit value.
+
+#### POST /api/v1/servers/{name}/config-to-secret
+
+Atomically move a header or env value out of `mcp_config.json` and into the
+OS keyring. The backend reads the real value from the loaded config, stores
+it in the keyring under `secret_name`, and rewrites the config field with
+`${keyring:<secret_name>}`. The client never needs to possess the plaintext
+— useful when the API redacts sensitive header values on the read path.
+
+**Request body:**
+
+```json
+{
+  "scope": "header",
+  "key": "Authorization",
+  "secret_name": "synapbus-auth"
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `scope` | string | `header` or `env` |
+| `key` | string | The key on the server's headers / env map |
+| `secret_name` | string | Name to store the value under in the OS keyring |
+
+**Response (200 OK):**
+
+```json
+{
+  "success": true,
+  "data": {
+    "message": "header \"Authorization\" on \"synapbus\" now references keyring secret \"synapbus-auth\"",
+    "reference": "${keyring:synapbus-auth}"
+  }
+}
+```
+
+**Failure cases:**
+
+| Status | Cause |
+|---|---|
+| 400 | Missing `scope` / `key` / `secret_name`, invalid scope, value is already a `${keyring:…}` or `${env:…}` reference, or value is empty |
+| 404 | Server or key not found |
+| 500 | Secret resolver unavailable, keyring store failed, or config update failed |
+
+This endpoint is what the Web UI and macOS tray "Convert to secret" button
+calls. It works even for headers the API redacts (the backend has the real
+value on disk).
+
 #### POST /api/v1/servers/{name}/enable
 
 Enable a server.

docs/cli/management-commands.md

@@ -84,6 +84,54 @@ mcpproxy upstream enable server-name
 mcpproxy upstream disable server-name
 ```
 
+### Patch Headers / Env
+
+`mcpproxy upstream patch` updates HTTP `headers` and stdio `env` on an
+existing server using JSON Merge Patch semantics — keys you specify are
+upserted, keys named in `--header-remove` / `--env-remove` are deleted,
+and every other key on the stored config is preserved.
+
+This means you can rotate a single Bearer token without seeing or
+touching any other header. The same applies to env vars on stdio servers.
+
+```bash
+# Rotate the Authorization header on a connected server
+mcpproxy upstream patch synapbus --header "Authorization: Bearer new-token"
+
+# Add a custom header without disturbing existing ones
+mcpproxy upstream patch synapbus --header "X-Trace: on"
+
+# Remove a stale header
+mcpproxy upstream patch synapbus --header-remove "X-Old"
+
+# Set + remove in one round-trip
+mcpproxy upstream patch synapbus --header "X-New: v" --header-remove "X-Old"
+
+# Update env vars on a stdio server
+mcpproxy upstream patch obsidian-pilot \
+  --env "LOG_LEVEL=debug" --env-remove "OBSOLETE_VAR"
+```
+
+**Flags** (all repeatable):
+
+| Flag | Semantics |
+|---|---|
+| `--header NAME: value` | Upsert one header (single colon delimits name and value) |
+| `--header-remove NAME` | Delete a header by name |
+| `--env KEY=value` | Upsert one env var |
+| `--env-remove KEY` | Delete an env var by name |
+
+**Notes:**
+
+- Requires the daemon to be running (`mcpproxy serve`). The subcommand
+  applies changes through the live REST endpoint so connection state
+  and OAuth tokens stay coordinated; editing `mcp_config.json` by hand
+  is only safe while the daemon is offline.
+- Specifying the same key in both `--header` and `--header-remove` is a
+  conflict and errors out with a useful message.
+- For new servers, use `upstream add` (HTTP/stdio) or
+  `upstream add-json` (full JSON shape) instead.
+
 ## Socket Communication
 
 CLI commands automatically detect and use Unix socket/named pipe communication when the daemon is running.
@@ -95,7 +143,7 @@ CLI commands automatically detect and use Unix socket/named pipe communication w
 - No redundant server connection overhead
 
 **Commands with socket support:**
-- `upstream list/logs/enable/disable/restart`
+- `upstream list/logs/enable/disable/restart/patch`
 - `doctor` (requires daemon)
 - `call tool`
 - `code exec`

docs/configuration/upstream-servers.md

@@ -73,6 +73,120 @@ Servers requiring OAuth 2.1 authentication:
 | `env` | object | No | Environment variables to pass |
 | `oauth` | object | No | OAuth configuration |
 
+## Headers, Environment Variables, and Secrets
+
+Both HTTP `headers` and stdio `env` are first-class config fields you can
+inspect and edit from the Web UI, the macOS tray, the CLI, and the REST
+API. The wire format and semantics are identical across surfaces.
+
+### How the API displays them
+
+The REST API (`GET /api/v1/servers`), the SSE `servers.changed` event, and
+the MCP `upstream_servers list` tool all redact sensitive header values
+by default. The mask format is:
+
+```
+••••<last2> (<N> chars)
+```
+
+…e.g. a 71-character Bearer token whose last two characters are `59`
+appears on the wire as `••••59 (71 chars)`. The mask preserves enough
+context to identify which token is in use without leaking the secret.
+
+Values that are already secret **references** — `${keyring:NAME}` or
+`${env:VAR}` — pass through unchanged: they're labels, not secrets.
+
+This redaction was added in PR #425 to close a real exfiltration path —
+a prompt-injected agent calling `upstream_servers list` would otherwise
+get back another upstream's Bearer token in plaintext.
+
+To disable redaction (for debugging only), set `reveal_secret_headers: true`
+in `mcp_config.json`. **It's not normally needed**: the editing flow
+described below works without ever exposing the plaintext to the client.
+
+### How you edit them
+
+#### Web UI / macOS tray
+
+The Server Detail page → Configuration tab has dedicated **Headers** and
+**Environment Variables** cards with per-row affordances:
+
+![Headers card on the Web UI](../screenshots/server-detail/web-headers-card.png)
+
+- **Add** — `+ Add header` / `+ Add variable` button at the top.
+- **Edit** — pencil icon turns the value cell into an input. Save / Cancel.
+- **Delete** — trash icon. Confirms first.
+- **Convert to secret** — lock icon. Opens a modal asking for a name,
+  then atomically moves the value into the OS keyring and replaces the
+  config field with `${keyring:NAME}`.
+
+![Convert-to-secret modal](../screenshots/server-detail/web-convert-modal.png)
+
+The Convert flow works even on masked headers: the backend has the real
+value in `mcp_config.json` and never needs the client to send it.
+
+`${keyring:…}` references render as a labeled chip instead of a masked
+literal, so converted headers are visually distinct.
+
+#### CLI
+
+```bash
+# Upsert one or more headers
+mcpproxy upstream patch synapbus --header "X-Trace: on"
+
+# Rotate Authorization in place
+mcpproxy upstream patch synapbus --header "Authorization: Bearer new-token"
+
+# Delete one
+mcpproxy upstream patch synapbus --header-remove "X-Stale"
+
+# Mix set + delete in a single round-trip
+mcpproxy upstream patch synapbus --header "X-New: v" --header-remove "X-Old"
+
+# Env vars (stdio servers)
+mcpproxy upstream patch obsidian-pilot --env "LOG_LEVEL=debug"
+mcpproxy upstream patch obsidian-pilot --env-remove "OBSOLETE"
+```
+
+See [Management Commands](../cli/management-commands.md#patch-headers--env)
+for the full flag reference.
+
+#### REST API
+
+`PATCH /api/v1/servers/{name}` follows JSON Merge Patch
+([RFC 7396](https://www.rfc-editor.org/rfc/rfc7396)):
+
+```bash
+curl -X PATCH -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
+  -d '{"headers":{"X-New":"value","X-Stale":null}}' \
+  http://127.0.0.1:8080/api/v1/servers/synapbus
+```
+
+- non-null string value → upsert
+- JSON `null` value → delete
+- key absent from body → preserve (this is how the UI sends a diff
+  against the masked view without overwriting unchanged values)
+
+See [REST API › PATCH](../api/rest-api.md#patch-apiv1serversname) for the
+full reference, including the
+[`/config-to-secret`](../api/rest-api.md#post-apiv1serversnameconfig-to-secret)
+endpoint that backs the "Convert to secret" affordance.
+
+### Secret references
+
+`headers` and `env` values support two reference shapes that get resolved
+at request time rather than stored in plaintext:
+
+| Reference | Source | Lifetime |
+|---|---|---|
+| `${keyring:NAME}` | OS keyring entry called `NAME` | Persists across restarts; managed via the Secrets page or `mcpproxy secrets` CLI |
+| `${env:VAR}` | The `VAR` environment variable on the mcpproxy process | Tied to the shell/launcher that started mcpproxy |
+
+When mcpproxy connects to an upstream it substitutes the reference with
+the actual secret. The reference itself never reaches the upstream MCP
+server. See [Keyring Integration](../features/keyring-integration.md)
+for the full secret-storage story.
+
 ## Docker Isolation
 
 For enhanced security, stdio servers can run in Docker containers: