feat(registries): add-source CLI + REST/MCP surface + quarantine enforcement (MCP-866)

Builds on the provenance foundation to let users add their own MCP registry
sources, always tagged custom/unverified so their servers can never escape
quarantine. There is no allowlist a user can add themselves into.

- `mcpproxy registry add-source <https-url> [--protocol|--id|--name]`: daemon-first
  CLI that adds a generic modelcontextprotocol/registry v0.1 endpoint. Writes
  cfg.Registries copy-on-write via UpdateConfig + persists, and rebuilds the
  effective catalog so the source is immediately searchable.
- Server keystone (add_from_registry): stamp SourceRegistryID/Provenance onto the
  derived ServerConfig from the resolved registry; a custom/unverified source
  forces Quarantined=true and SkipQuarantine=false regardless of the global
  default (CN-002 extended).
- New add-source op (add_registry_source.go): pure URL→entry derivation (https
  validation, id-from-host slug, v0.1 servers-url derivation) + guardrails
  (registries_locked, no shadowing a built-in id, no duplicate). Stable
  cross-surface error codes: invalid_registry_url / registries_locked /
  registry_shadows_builtin / duplicate_registry.
- REST POST /api/v1/registries; cliclient.AddRegistrySource; provenance + trusted
  surfaced in list_registries across runtime REST + MCP so a UI can show the
  one-time third-party-registry warning.
- Docs: docs/registries.md trust model + add-source + registries_locked stub.
- OpenAPI regenerated.

TDD: add-source derivation/validation unit tests, custom-origin quarantine-always
keystone tests, and a registries integration test proving a user-added v0.1
endpoint is searchable AND tagged custom/unverified. Local: go build ./...,
config/registries/server/httpapi/cliclient/contracts/cmd suites green (-race on
the pure-logic packages), binary API + MCP e2e green, golangci-lint 0 issues,
approval-hash stability canary green.

Related MCP-866

Co-Authored-By: Paperclip <noreply@paperclip.ing>

Author: Dumbris

cmd/mcpproxy/registry_cmd.go

@@ -21,12 +21,15 @@ import (
 
 // Registry command flags (spec 070).
 var (
-	registryConfigPath string
-	registrySearchTag  string
-	registryLimit      int
-	registryAddName    string
-	registryAddEnv     []string
-	registryAddEnabled bool
+	registryConfigPath     string
+	registrySearchTag      string
+	registryLimit          int
+	registryAddName        string
+	registryAddEnv         []string
+	registryAddEnabled     bool
+	registryAddSourceProto string // MCP-866
+	registryAddSourceID    string
+	registryAddSourceName  string
 )
 
 // GetRegistryCommand builds the `registry` command group (spec 070): a single
@@ -53,12 +56,79 @@ Typical flow:
   mcpproxy registry add pulse weather-mcp       # add it (quarantined)
   mcpproxy upstream approve weather-mcp          # approve once you trust it
 
-'registry add' talks to the running mcpproxy daemon. 'list' and 'search' use the
-daemon when available and otherwise read the registries directly.`,
+Add your own registry source (any official modelcontextprotocol/registry v0.1 endpoint):
+  mcpproxy registry add-source https://registry.example.com   # custom/unverified
+
+'registry add' and 'registry add-source' talk to the running mcpproxy daemon.
+'list' and 'search' use the daemon when available and otherwise read the
+registries directly.`,
 	}
 
 	cmd.PersistentFlags().StringVarP(&registryConfigPath, "config", "c", "", "Path to MCP configuration file")
-	cmd.AddCommand(newRegistryListCmd(), newRegistrySearchCmd(), newRegistryAddCmd())
+	cmd.AddCommand(newRegistryListCmd(), newRegistrySearchCmd(), newRegistryAddCmd(), newRegistryAddSourceCmd())
+	return cmd
+}
+
+func newRegistryAddSourceCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "add-source <https-url>",
+		Short: "Add a custom MCP registry source (quarantine-always)",
+		Long: `Add your own MCP server registry — any https endpoint implementing the
+official modelcontextprotocol/registry v0.1 protocol (the same protocol shipped
+by Copilot/VS Code/Azure).
+
+The added source is ALWAYS tagged custom/unverified: there is no allowlist you
+can add yourself into. Every server you discover and add through a custom source
+lands quarantined and can never skip quarantine — review and approve it once you
+trust it:
+  mcpproxy registry search <query> -r <id>
+  mcpproxy registry add <id> <serverId>
+  mcpproxy upstream approve <name>`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(_ *cobra.Command, args []string) error {
+			sourceURL := args[0]
+
+			cfg, err := loadRegistryConfig()
+			if err != nil {
+				return outputError(clioutput.NewStructuredError(clioutput.ErrCodeConfigNotFound, err.Error()).
+					WithRecoveryCommand("mcpproxy doctor"), clioutput.ErrCodeConfigNotFound)
+			}
+
+			// add-source MUST go through the daemon: the registry list lives on the
+			// runtime config snapshot and is updated copy-on-write via UpdateConfig.
+			if !shouldUseUpstreamDaemon(cfg.DataDir) {
+				return outputError(clioutput.NewStructuredError(clioutput.ErrCodeConnectionFailed,
+					"adding a registry source requires a running mcpproxy daemon").
+					WithGuidance("Start the daemon, then retry").
+					WithRecoveryCommand("mcpproxy serve"), clioutput.ErrCodeConnectionFailed)
+			}
+
+			ctx, cancel := registryContext()
+			defer cancel()
+
+			client := cliclient.NewClient(socket.DetectSocketPath(cfg.DataDir), nil)
+			reg, err := client.AddRegistrySource(ctx, sourceURL, registryAddSourceProto, registryAddSourceID, registryAddSourceName)
+			if err != nil {
+				return registryAddErrorOutput(err)
+			}
+
+			outputFormat := ResolveOutputFormat()
+			if outputFormat == "json" || outputFormat == "yaml" {
+				formatter, _ := GetOutputFormatter()
+				out, _ := formatter.Format(reg)
+				fmt.Println(out)
+				return nil
+			}
+
+			fmt.Printf("✅ Added registry source '%s' (%s)\n", reg.ID, reg.Provenance)
+			fmt.Printf("⚠️  This is a third-party, unverified registry — its servers are always quarantined until you approve them.\n")
+			fmt.Printf("   Search it with: mcpproxy registry search <query> -r %s\n", reg.ID)
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&registryAddSourceProto, "protocol", "", "Registry protocol (default: modelcontextprotocol/registry)")
+	cmd.Flags().StringVar(&registryAddSourceID, "id", "", "Override the derived registry id")
+	cmd.Flags().StringVar(&registryAddSourceName, "name", "", "Override the registry display name")
 	return cmd
 }
 
@@ -270,6 +340,18 @@ func registryAddErrorOutput(err error) error {
 	case "registry_not_found", "server_not_found":
 		return outputError(clioutput.NewStructuredError(clioutput.ErrCodeServerNotFound, addErr.Message).
 			WithGuidance("Check the ids with 'mcpproxy registry list' and 'mcpproxy registry search'"), clioutput.ErrCodeServerNotFound)
+	case "invalid_registry_url":
+		return outputError(clioutput.NewStructuredError(clioutput.ErrCodeInvalidInput, addErr.Message).
+			WithGuidance("Provide an https URL, e.g. https://registry.example.com"), clioutput.ErrCodeInvalidInput)
+	case "registries_locked":
+		return outputError(clioutput.NewStructuredError(clioutput.ErrCodeOperationFailed, addErr.Message).
+			WithGuidance("Registry additions are disabled by policy (registries_locked)"), clioutput.ErrCodeOperationFailed)
+	case "registry_shadows_builtin":
+		return outputError(clioutput.NewStructuredError(clioutput.ErrCodeInvalidInput, addErr.Message).
+			WithGuidance("Choose a different --id; built-in registry ids cannot be replaced"), clioutput.ErrCodeInvalidInput)
+	case "duplicate_registry":
+		return outputError(clioutput.NewStructuredError(clioutput.ErrCodeOperationFailed, addErr.Message).
+			WithGuidance("A registry with that id already exists; pass a different --id"), clioutput.ErrCodeOperationFailed)
 	default:
 		return outputError(clioutput.NewStructuredError(clioutput.ErrCodeOperationFailed, addErr.Message), clioutput.ErrCodeOperationFailed)
 	}

docs/registries.md

@@ -23,6 +23,61 @@ key is configured it is sent on every request to that registry as an
 User-configured registries in `mcp_config.json` (`registries: [...]`) are **merged**
 with these defaults (keyed by ID); a custom entry never drops the shipped set.
 
+## Trust model & user-added registries
+
+Every registry carries a **provenance** tag:
+
+| Provenance | Meaning |
+|---|---|
+| `official/trusted` | A shipped, built-in default (the five above). |
+| `custom/unverified` | Any registry the user added at runtime, or any non-default ID in `mcp_config.json`. |
+
+Trust is **derived, not asserted** — it comes solely from whether the registry ID
+is one of the shipped defaults. Writing `"provenance": "official/trusted"` into a
+custom `mcp_config.json` entry has no effect; mcpproxy recomputes provenance on
+every merge. **There is no allowlist a user can add themselves into.**
+
+Consequences for `custom/unverified` registries:
+
+- Servers discovered through them are **always quarantined** on add, regardless of
+  the global quarantine default — and they can **never** set `skip_quarantine`
+  (enforced in config validation *and* at server-add time). A server's origin is
+  recorded on its config as `source_registry_id` / `source_registry_provenance`
+  and surfaced in the approval/quarantine view.
+- The `list_registries` output (MCP, REST, CLI) includes `provenance` and a
+  `trusted` boolean so a UI can show a one-time third-party-registry warning.
+
+### Adding your own registry source
+
+`mcpproxy registry add-source` adds any https endpoint that implements the official
+`modelcontextprotocol/registry` v0.1 protocol (the same protocol Copilot / VS Code /
+Azure ship):
+
+```bash
+mcpproxy registry add-source https://registry.example.com
+mcpproxy registry add-source https://registry.example.com --id acme --name "Acme Corp"
+```
+
+The ID is derived from the host when omitted; `--protocol` defaults to
+`modelcontextprotocol/registry`. The source is always tagged `custom/unverified`.
+This requires a running daemon — the registry list is updated copy-on-write on the
+runtime config snapshot and persisted to `mcp_config.json`.
+
+Equivalent surfaces:
+
+- **REST:** `POST /api/v1/registries` with `{ "url": "https://…", "protocol": "…", "id": "…", "name": "…" }`.
+- **CLI:** `mcpproxy registry add-source <https-url>`.
+
+Errors share a stable code across surfaces: `invalid_registry_url` (400),
+`registries_locked` (403), `registry_shadows_builtin` / `duplicate_registry` (409).
+
+### Enterprise: `registries_locked` (stub)
+
+Setting `"registries_locked": true` in `mcp_config.json` disables runtime registry
+additions (`registry add-source` and the REST/MCP add-source surface return
+`registries_locked`). Built-in defaults are unaffected. This is a forward-looking
+stub for enterprise policy pinning.
+
 ## Official v0.1 protocol
 
 The official registry returns a cursor-paginated list of wrapped entries:

internal/cliclient/client.go

@@ -1862,3 +1862,56 @@ func (c *Client) AddFromRegistry(ctx context.Context, registryID, serverID, name
 	}
 	return &apiResp.Data.Server, nil
 }
+
+// AddRegistrySource adds a user-supplied registry source via the daemon
+// (MCP-866). POST /api/v1/registries → data.registry. On failure it returns a
+// *RegistryAddError carrying the stable cross-surface code.
+func (c *Client) AddRegistrySource(ctx context.Context, sourceURL, protocol, id, name string) (*contracts.RegistrySummary, error) {
+	body := contracts.AddRegistrySourceRequest{URL: sourceURL, Protocol: protocol, ID: id, Name: name}
+	bodyBytes, err := json.Marshal(body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	u := c.baseURL + "/api/v1/registries"
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, u, bytes.NewReader(bodyBytes))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	c.prepareRequest(ctx, req)
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to call add-registry-source API: %w", err)
+	}
+	defer resp.Body.Close()
+
+	respBytes, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+
+	var apiResp struct {
+		Success   bool                             `json:"success"`
+		Data      *contracts.AddRegistrySourceData `json:"data"`
+		Error     string                           `json:"error"`
+		Code      string                           `json:"code"`
+		RequestID string                           `json:"request_id"`
+	}
+	if err := json.Unmarshal(respBytes, &apiResp); err != nil {
+		return nil, fmt.Errorf("failed to parse response (status %d): %s", resp.StatusCode, string(respBytes))
+	}
+
+	if !apiResp.Success || resp.StatusCode != http.StatusOK {
+		msg := apiResp.Error
+		if msg == "" {
+			msg = fmt.Sprintf("API returned status %d", resp.StatusCode)
+		}
+		return nil, &RegistryAddError{Code: apiResp.Code, Message: msg, RequestID: apiResp.RequestID}
+	}
+	if apiResp.Data == nil {
+		return nil, fmt.Errorf("daemon returned success with no registry data")
+	}
+	return &apiResp.Data.Registry, nil
+}

internal/contracts/types.go

@@ -964,6 +964,33 @@ type RegistryAddError struct {
 	MissingInputs []string `json:"missing_inputs,omitempty"`
 }
 
+// AddRegistrySourceRequest is the POST body for adding a user-supplied registry
+// source (MCP-866, POST /api/v1/registries). Provenance is NOT part of the
+// request — the server always tags an added source custom/unverified.
+type AddRegistrySourceRequest struct {
+	URL      string `json:"url"`                // required https registry URL
+	Protocol string `json:"protocol,omitempty"` // defaults to modelcontextprotocol/registry
+	ID       string `json:"id,omitempty"`       // derived from the host when empty
+	Name     string `json:"name,omitempty"`     // defaults to the id
+}
+
+// RegistrySummary is a slim, stable projection of a registry, including its
+// provenance/trust so surfaces can flag third-party sources (MCP-866).
+type RegistrySummary struct {
+	ID         string `json:"id"`
+	Name       string `json:"name"`
+	URL        string `json:"url,omitempty"`
+	ServersURL string `json:"servers_url,omitempty"`
+	Protocol   string `json:"protocol,omitempty"`
+	Provenance string `json:"provenance,omitempty"`
+	Trusted    bool   `json:"trusted"`
+}
+
+// AddRegistrySourceData is the success `data` payload for add-source.
+type AddRegistrySourceData struct {
+	Registry RegistrySummary `json:"registry"`
+}
+
 // SuccessResponse is the standard success response wrapper for API endpoints.
 type SuccessResponse struct {
 	Success bool        `json:"success"`

internal/httpapi/code_exec_test.go

@@ -97,6 +97,9 @@ func (m *mockController) RefreshRegistryCache(registryID string) (int, error) {
 func (m *mockController) AddServerFromRegistryRef(_ context.Context, _, _, _ string, _ map[string]string, _ *bool) (*config.ServerConfig, *contracts.RegistryAddError, error) {
 	return nil, nil, nil
 }
+func (m *mockController) AddRegistrySourceRef(_, _, _, _ string) (*config.RegistryEntry, *contracts.RegistryAddError, error) {
+	return nil, nil, nil
+}
 func (m *mockController) GetManagementService() interface{}                       { return nil }
 func (m *mockController) GetRuntime() interface{}                                 { return nil }
 func (m *mockController) GetSessions(limit, offset int) (interface{}, int, error) { return nil, 0, nil }

internal/httpapi/contracts_test.go

@@ -315,6 +315,9 @@ func (m *MockServerController) RefreshRegistryCache(_ string) (int, error) {
 func (m *MockServerController) AddServerFromRegistryRef(_ context.Context, _, _, _ string, _ map[string]string, _ *bool) (*config.ServerConfig, *contracts.RegistryAddError, error) {
 	return nil, nil, nil
 }
+func (m *MockServerController) AddRegistrySourceRef(_, _, _, _ string) (*config.RegistryEntry, *contracts.RegistryAddError, error) {
+	return nil, nil, nil
+}
 
 // Version and updates
 func (m *MockServerController) GetVersionInfo() *updatecheck.VersionInfo {

internal/httpapi/security_test.go

@@ -297,6 +297,9 @@ func (m *baseController) RefreshRegistryCache(registryID string) (int, error) {
 func (m *baseController) AddServerFromRegistryRef(_ context.Context, _, _, _ string, _ map[string]string, _ *bool) (*config.ServerConfig, *contracts.RegistryAddError, error) {
 	return nil, nil, nil
 }
+func (m *baseController) AddRegistrySourceRef(_, _, _, _ string) (*config.RegistryEntry, *contracts.RegistryAddError, error) {
+	return nil, nil, nil
+}
 func (m *baseController) CallTool(ctx context.Context, toolName string, args map[string]interface{}) (interface{}, error) {
 	return nil, nil
 }

internal/httpapi/server.go

@@ -128,6 +128,10 @@ type ServerController interface {
 	// stable cross-surface error code (*contracts.RegistryAddError) alongside
 	// the raw error so the handler can map code → HTTP status.
 	AddServerFromRegistryRef(ctx context.Context, registryID, serverID, name string, env map[string]string, enabled *bool) (*config.ServerConfig, *contracts.RegistryAddError, error)
+	// AddRegistrySourceRef adds a user-supplied generic registry source
+	// (MCP-866), always tagged custom/unverified. On failure it returns a stable
+	// cross-surface error code alongside the raw error.
+	AddRegistrySourceRef(url, protocol, id, name string) (*config.RegistryEntry, *contracts.RegistryAddError, error)
 
 	// Version and updates
 	GetVersionInfo() *updatecheck.VersionInfo
@@ -679,6 +683,7 @@ func (s *Server) setupRoutes() {
 
 		// Registry browsing (Phase 7)
 		r.Get("/registries", s.handleListRegistries)
+		r.Post("/registries", s.handleAddRegistrySource) // MCP-866 user-added registry source
 		r.Get("/registries/{id}/servers", s.handleSearchRegistryServers)
 		r.Post("/registries/{id}/refresh", s.handleRefreshRegistryCache)           // spec 070 FR-007
 		r.Post("/registries/{id}/servers/{serverId}/add", s.handleAddFromRegistry) // spec 070 keystone add
@@ -4170,6 +4175,55 @@ func (s *Server) handleAddFromRegistry(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
+// handleAddRegistrySource godoc
+// @Summary      Add a user-supplied registry source
+// @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.
+// @Tags         registries
+// @Accept       json
+// @Produce      json
+// @Param        body  body      contracts.AddRegistrySourceRequest  true  "Registry source (https url + optional protocol/id/name)"
+// @Success      200   {object}  contracts.SuccessResponse           "Registry source added"
+// @Failure      400   {object}  contracts.ErrorResponse             "invalid_registry_url"
+// @Failure      403   {object}  contracts.ErrorResponse             "registries_locked"
+// @Failure      409   {object}  contracts.ErrorResponse             "registry_shadows_builtin | duplicate_registry"
+// @Security     ApiKeyAuth
+// @Security     ApiKeyQuery
+// @Router       /api/v1/registries [post]
+func (s *Server) handleAddRegistrySource(w http.ResponseWriter, r *http.Request) {
+	var req contracts.AddRegistrySourceRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil && !errors.Is(err, io.EOF) {
+		s.writeError(w, r, http.StatusBadRequest, fmt.Sprintf("Invalid request body: %v", err))
+		return
+	}
+	if req.URL == "" {
+		s.writeError(w, r, http.StatusBadRequest, "url is required")
+		return
+	}
+
+	logger := s.getRequestLogger(r)
+	entry, rerr, err := s.controller.AddRegistrySourceRef(req.URL, req.Protocol, req.ID, req.Name)
+	if err != nil {
+		status := registryAddErrorStatus(rerr.Code)
+		if status >= http.StatusInternalServerError {
+			logger.Error("Add registry source failed", "url", req.URL, "error", err)
+		}
+		s.writeRegistryAddError(w, r, status, rerr)
+		return
+	}
+
+	s.writeSuccess(w, contracts.AddRegistrySourceData{
+		Registry: contracts.RegistrySummary{
+			ID:         entry.ID,
+			Name:       entry.Name,
+			URL:        entry.URL,
+			ServersURL: entry.ServersURL,
+			Protocol:   entry.Protocol,
+			Provenance: entry.Provenance,
+			Trusted:    entry.IsTrusted(),
+		},
+	})
+}
+
 // handleRefreshRegistryCache godoc
 // @Summary      Refresh a registry's cached server list
 // @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.
@@ -4206,8 +4260,12 @@ func registryAddErrorStatus(code string) int {
 	switch code {
 	case "registry_not_found", "server_not_found":
 		return http.StatusNotFound
-	case "no_install_info", "missing_required_input", "duplicate_name":
+	case "no_install_info", "missing_required_input", "duplicate_name", "invalid_registry_url":
 		return http.StatusBadRequest
+	case "registries_locked":
+		return http.StatusForbidden
+	case "registry_shadows_builtin", "duplicate_registry":
+		return http.StatusConflict
 	default:
 		return http.StatusInternalServerError
 	}