smart-mcp-proxy
diff --git a/‎cmd/mcpproxy/upstream_cmd.go‎
Lines changed: 168 additions & 0 deletions b/‎cmd/mcpproxy/upstream_cmd.go‎
Lines changed: 168 additions & 0 deletions
diff --git a/‎docs/api/rest-api.md‎
Lines changed: 142 additions & 0 deletions b/‎docs/api/rest-api.md‎
Lines changed: 142 additions & 0 deletions
@@ -121,6 +121,39 @@ Examples:
 		RunE: runUpstreamAddJSON,
 	}
 
+	upstreamPatchCmd = &cobra.Command{
+		Use:   "patch <name>",
+		Short: "Update headers / env on an existing upstream server",
+		Long: `Update HTTP headers and stdio environment variables on an existing upstream server.
+
+The PATCH endpoint uses JSON Merge Patch semantics: keys you specify are
+upserted, keys you delete with -remove flags are explicitly removed, and
+every other key on the stored config is preserved. So you can safely
+rotate a single header without seeing or touching the rest — including
+sensitive values the backend redacts from list / inspect responses.
+
+Examples:
+  # rotate the Authorization header on the synapbus 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 header
+  mcpproxy upstream patch synapbus --header-remove "X-Stale"
+
+  # set + remove in a single 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 "OLD_VAR"
+
+Flags are repeatable. The corresponding null in the JSON Merge Patch body
+is constructed automatically — you never have to think about wire format.`,
+		Args: cobra.ExactArgs(1),
+		RunE: runUpstreamPatch,
+	}
+
 	upstreamInspectCmd = &cobra.Command{
 		Use:   "inspect <server-name>",
 		Short: "Inspect tool approval status for a server",
@@ -248,6 +281,12 @@ Examples:
 	// Inspect command flags
 	upstreamInspectTool string
 
+	// Patch command flags
+	upstreamPatchHeaders      []string
+	upstreamPatchHeaderRemove []string
+	upstreamPatchEnvs         []string
+	upstreamPatchEnvRemove    []string
+
 	// Import command flags
 	upstreamImportServer       string
 	upstreamImportFormat       string
@@ -272,6 +311,7 @@ func init() {
 	upstreamCmd.AddCommand(upstreamAddCmd)
 	upstreamCmd.AddCommand(upstreamRemoveCmd)
 	upstreamCmd.AddCommand(upstreamAddJSONCmd)
+	upstreamCmd.AddCommand(upstreamPatchCmd)
 	upstreamCmd.AddCommand(upstreamInspectCmd)
 	upstreamCmd.AddCommand(upstreamApproveCmd)
 	upstreamCmd.AddCommand(upstreamImportCmd)
@@ -316,6 +356,12 @@ func init() {
 	upstreamRemoveCmd.Flags().BoolVarP(&upstreamRemoveYes, "y", "y", false, "Skip confirmation prompt (short form)")
 	upstreamRemoveCmd.Flags().BoolVar(&upstreamRemoveIfExists, "if-exists", false, "Don't error if server doesn't exist")
 
+	// Patch command flags
+	upstreamPatchCmd.Flags().StringArrayVar(&upstreamPatchHeaders, "header", nil, "HTTP header to upsert in 'Name: value' format (repeatable)")
+	upstreamPatchCmd.Flags().StringArrayVar(&upstreamPatchHeaderRemove, "header-remove", nil, "HTTP header name to delete (repeatable)")
+	upstreamPatchCmd.Flags().StringArrayVar(&upstreamPatchEnvs, "env", nil, "Environment variable to upsert in KEY=value format (repeatable)")
+	upstreamPatchCmd.Flags().StringArrayVar(&upstreamPatchEnvRemove, "env-remove", nil, "Environment variable name to delete (repeatable)")
+
 	// Inspect command flags
 	upstreamInspectCmd.Flags().StringVar(&upstreamInspectTool, "tool", "", "Show details for a specific tool")
 
@@ -2006,3 +2052,125 @@ func applyImportedServersConfigMode(imported []*configimport.ImportedServer, glo
 
 	return nil
 }
+
+// runUpstreamPatch handles the 'upstream patch' command. Translates the
+// repeatable --header / --env / --header-remove / --env-remove flags into
+// a JSON Merge Patch (RFC 7396) body and POSTs it to PATCH /api/v1/servers/{name}.
+//
+// Upserts encode as {"headers": {"X-Foo": "bar"}}; deletes encode as
+// {"headers": {"X-Stale": null}}. Both shapes go through encoding/json
+// (`map[string]*string`) where a nil pointer renders as the literal
+// `null` token — verified by the backend's PATCH tests.
+func runUpstreamPatch(_ *cobra.Command, args []string) error {
+	serverName := strings.TrimSpace(args[0])
+	if serverName == "" {
+		return fmt.Errorf("server name is required")
+	}
+
+	if len(upstreamPatchHeaders) == 0 && len(upstreamPatchHeaderRemove) == 0 &&
+		len(upstreamPatchEnvs) == 0 && len(upstreamPatchEnvRemove) == 0 {
+		return fmt.Errorf("at least one of --header / --header-remove / --env / --env-remove must be specified")
+	}
+
+	headers := map[string]*string{}
+	for _, h := range upstreamPatchHeaders {
+		parts := strings.SplitN(h, ":", 2)
+		if len(parts) != 2 {
+			return fmt.Errorf("invalid --header format: %q (expected 'Name: value')", h)
+		}
+		key := strings.TrimSpace(parts[0])
+		val := strings.TrimSpace(parts[1])
+		if key == "" {
+			return fmt.Errorf("invalid --header: empty header name in %q", h)
+		}
+		headers[key] = &val
+	}
+	for _, k := range upstreamPatchHeaderRemove {
+		key := strings.TrimSpace(k)
+		if key == "" {
+			return fmt.Errorf("invalid --header-remove: empty name")
+		}
+		if _, dupe := headers[key]; dupe {
+			return fmt.Errorf("--header and --header-remove for %q conflict; pick one", key)
+		}
+		headers[key] = nil // JSON Merge Patch: null = delete
+	}
+
+	envs := map[string]*string{}
+	for _, e := range upstreamPatchEnvs {
+		parts := strings.SplitN(e, "=", 2)
+		if len(parts) != 2 {
+			return fmt.Errorf("invalid --env format: %q (expected 'KEY=value')", e)
+		}
+		key := strings.TrimSpace(parts[0])
+		val := parts[1]
+		if key == "" {
+			return fmt.Errorf("invalid --env: empty key in %q", e)
+		}
+		envs[key] = &val
+	}
+	for _, k := range upstreamPatchEnvRemove {
+		key := strings.TrimSpace(k)
+		if key == "" {
+			return fmt.Errorf("invalid --env-remove: empty name")
+		}
+		if _, dupe := envs[key]; dupe {
+			return fmt.Errorf("--env and --env-remove for %q conflict; pick one", key)
+		}
+		envs[key] = nil
+	}
+
+	body := map[string]interface{}{}
+	if len(headers) > 0 {
+		body["headers"] = headers
+	}
+	if len(envs) > 0 {
+		body["env"] = envs
+	}
+
+	bodyBytes, err := json.Marshal(body)
+	if err != nil {
+		return fmt.Errorf("failed to marshal patch body: %w", err)
+	}
+
+	ctx, cancel := context.WithTimeout(reqcontext.WithMetadata(context.Background(), reqcontext.SourceCLI), 15*time.Second)
+	defer cancel()
+
+	globalConfig, err := loadUpstreamConfig()
+	if err != nil {
+		return fmt.Errorf("failed to load config: %w", err)
+	}
+	if !shouldUseUpstreamDaemon(globalConfig.DataDir) {
+		return fmt.Errorf("mcpproxy daemon is not running — start it with `mcpproxy serve` first; the `patch` subcommand requires a live backend so configuration changes are applied with full deep-merge semantics and propagated to running upstream connections immediately. Editing the config file by hand only works while the daemon is offline")
+	}
+	logger, err := createUpstreamLogger("warn")
+	if err != nil {
+		return fmt.Errorf("failed to create logger: %w", err)
+	}
+	socketPath := socket.DetectSocketPath(globalConfig.DataDir)
+	client := cliclient.NewClient(socketPath, logger.Sugar())
+
+	if err := client.PatchServer(ctx, serverName, bodyBytes); err != nil {
+		return err
+	}
+
+	fmt.Printf("✅ Patched %s", serverName)
+	parts := []string{}
+	if n := len(upstreamPatchHeaders); n > 0 {
+		parts = append(parts, fmt.Sprintf("%d header(s) set", n))
+	}
+	if n := len(upstreamPatchHeaderRemove); n > 0 {
+		parts = append(parts, fmt.Sprintf("%d header(s) removed", n))
+	}
+	if n := len(upstreamPatchEnvs); n > 0 {
+		parts = append(parts, fmt.Sprintf("%d env var(s) set", n))
+	}
+	if n := len(upstreamPatchEnvRemove); n > 0 {
+		parts = append(parts, fmt.Sprintf("%d env var(s) removed", n))
+	}
+	if len(parts) > 0 {
+		fmt.Printf(": %s", strings.Join(parts, ", "))
+	}
+	fmt.Println()
+	return nil
+}
@@ -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.