Publisher-managed "deleted" support (#893)

(Updated auto-generated PR description from @tadasant / Claude on Feb 22, 2026) ## Motivation and Context Fixes #637 Server lifecycle management (deprecation and yanking) is a standard requirement for package registries. Use cases like rebranding, security vulnerabilities, and end-of-life servers demand the ability to mark servers as deprecated or deleted, with optional messaging to guide consumers toward alternatives. ## Changes ### New API endpoints - **`PATCH /v0/servers/{serverName}/versions/{version}/status`** — Update the lifecycle status of a single server version - **`PATCH /v0/servers/{serverName}/status`** — Update the lifecycle status of all versions of a server in a single transaction Both endpoints accept: ```json { "status": "active|deprecated|deleted", "statusMessage": "Optional message (max 500 chars) explaining the change" } ``` ### New CLI command - **`mcp-publisher status <serverName> [version]`** — Update server lifecycle status from the command line - `--status` (required): `active`, `deprecated`, or `deleted` - `--message`: Optional status message - `--all-versions`: Apply to all versions of the server (replaces the `<version>` argument) ### API response changes `RegistryExtensions` now includes two new fields: - `statusChangedAt` — Timestamp of the last status change - `statusMessage` — Optional free-form message (e.g., deprecation reason, migration guidance) ### List endpoint changes - New `include_deleted` query parameter on `GET /v0/servers` — defaults to `false`, hiding deleted servers from listings - When `updated_since` is provided, `include_deleted` is automatically set to `true` for incremental sync ### Database - Migration `013_add_status_fields.sql`: Adds `status_changed_at` (NOT NULL, initialized from `published_at`) and `status_message` columns to the `servers` table ### Design decisions (from review discussion) - **Dedicated status endpoints** rather than overloading the existing edit endpoint - **Bidirectional status transitions** — all transitions between `active`, `deprecated`, and `deleted` are allowed - **`statusMessage` as free-form text** — no structured `nextName` or `alternativeUrl` fields (per maintainer feedback, to avoid complexity around chaining, trust transfer, etc.) - **Publish permission** grants status change access (not limited to admin/edit) - **Status message auto-cleared** when transitioning back to `active` Good, now I have the full picture. Here's the addendum: ### Consumer-facing API changes The new status fields live inside `_meta["io.modelcontextprotocol.registry/official"]` on every `ServerResponse`. This is the existing `RegistryExtensions` object — two new fields are added alongside the existing ones: **Before:** ```json { "server": { "name": "com.example/my-server", "...": "..." }, "_meta": { "io.modelcontextprotocol.registry/official": { "status": "active", "publishedAt": "2025-06-01T00:00:00Z", "updatedAt": "2025-06-15T00:00:00Z", "isLatest": true } } } ``` **After:** ```json { "server": { "name": "com.example/my-server", "...": "..." }, "_meta": { "io.modelcontextprotocol.registry/official": { "status": "deprecated", "statusChangedAt": "2026-02-01T12:00:00Z", "statusMessage": "Deprecated in favor of com.example/my-server-v2", "publishedAt": "2025-06-01T00:00:00Z", "updatedAt": "2026-02-01T12:00:00Z", "isLatest": true } } } ``` | New field | Type | Present when | |-----------|------|-------------| | `statusChangedAt` | `string` (RFC3339) | Always — initialized to `publishedAt` for existing records | | `statusMessage` | `string` (max 500 chars) | Only when set — `null`/omitted for active servers (auto-cleared on transition to active) | These fields appear on **every endpoint that returns a `ServerResponse`**: `GET /v0/servers`, `GET /v0/servers/{name}`, `GET /v0/servers/{name}/versions/{version}`, and the new PATCH status endpoints. ### List endpoint filtering `GET /v0/servers` gains an `include_deleted` query parameter: | Scenario | Behavior | |----------|----------| | No `include_deleted` param | Deleted servers hidden (default `false`) | | `include_deleted=true` | Deleted servers included in results | | `updated_since` provided | `include_deleted` forced to `true` for incremental sync | ## How Has This Been Tested? - Unit tests for status handler (`status_test.go`) covering status transitions, permission checks, validation errors, and the all-versions endpoint - Unit tests for the CLI command (`status_test.go`) - Integration with existing server/edit handler tests - Database layer tests for the new status update and query methods - Tested locally with `make dev-compose` ## Types of changes - [x] New feature (non-breaking change which adds functionality) ## Checklist - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] My code follows the repository's style guidelines - [x] New and existing tests pass locally - [x] I have added appropriate error handling - [x] I have added or updated documentation as needed ## Open items from review - [ ] `include_deleted` silent override: When `updated_since` is provided and `include_deleted=false` is explicitly passed, should return a 400 error rather than silently overriding ([thread](https://github.com/modelcontextprotocol/registry/pull/893#discussion_r2100879360)) — agreed upon but may not yet be implemented
2026-02-27 22:30:07 +05:30 · 2026-02-27 22:30:07 +05:30 · bb84ea69e8
commit bb84ea69e8
parent 01e4e2b09e
6 changed files with 4153 additions and 474 deletions
--- a/docs/modelcontextprotocol-io/faq.mdx
+++ b/docs/modelcontextprotocol-io/faq.mdx
@ -18,7 +18,21 @@ sidebarTitle: FAQ

 ### Can I delete/unpublish my server?

-Currently, no. At the time of writing, there is [open discussion](https://github.com/modelcontextprotocol/registry/issues/104).
+Yes, you can change your server's status to `deleted` using the `mcp-publisher status` command:
+
+```bash
+# Delete a specific version
+mcp-publisher status --status deleted --message "No longer maintained" \
+  io.github.my-username/my-server 1.0.0
+
+# Delete all versions
+mcp-publisher status --status deleted --all-versions --message "Project archived" \
+  io.github.my-username/my-server
+```
+
+Deleted servers are hidden from default API listings but can still be retrieved with `include_deleted=true`. You can restore a deleted server by setting its status back to `active`.
+
+**Note**: Server metadata is never permanently removed from the registry. The `deleted` status hides the server from discovery but preserves the historical record.

 ### How do I update my server metadata?

--- a/docs/reference/api/CHANGELOG.md
+++ b/docs/reference/api/CHANGELOG.md
@ -2,6 +2,39 @@

 Changes to the REST API endpoints and responses.

+## Unreleased
+
+### Added
+
+#### Server Status Management Endpoints
+
+New endpoints for managing server lifecycle status:
+
+- `PATCH /v0/servers/{serverName}/versions/{version}/status` - Update status of a specific server version
+- `PATCH /v0/servers/{serverName}/status` - Update status of all versions of a server in a single transaction
+
+**Status values:**
+- `active` - Server is active and visible in default listings
+- `deprecated` - Server is deprecated but still visible with a warning message
+- `deleted` - Server is hidden from default listings
+
+**Authentication:** Requires `publish` or `edit` permission for the server namespace.
+
+#### New Response Fields
+
+New fields added to `_meta["io.modelcontextprotocol.registry/official"]` (RegistryExtensions):
+
+- `statusChangedAt` - Timestamp when the server status was last changed
+- `statusMessage` - Optional message explaining status change (e.g., deprecation reason, migration guidance)
+
+#### Server Filtering Enhancements
+
+New `include_deleted` query parameter added to multiple endpoints:
+
+- `GET /v0/servers` - Include deleted servers in list results (default: `false`, automatically `true` when `updated_since` is provided)
+- `GET /v0/servers/{serverName}/versions/{version}` - Include deleted servers in detail results (default: `false`)
+- `GET /v0/servers/{serverName}/versions` - Include deleted servers in version history (default: `false`)
+
 ## 2025-10-17

 ### Added
@ -120,4 +153,4 @@ API endpoints updated for consistent server identification across versions.

 ## 2025-07-09

-Initial release of the Registry API.
+Initial release of the Registry API.
--- a/docs/reference/api/generic-registry-api.md
+++ b/docs/reference/api/generic-registry-api.md
@ -20,6 +20,8 @@ The official registry has some more endpoints and restrictions on top of this. S
 - **`POST /v0.1/publish`** - Publish new server (optional, registry-specific authentication)
 - **`PUT /v0.1/servers/{serverName}/versions/{version}`** - Update specific server version (optional, not implemented by official registry)
 - **`DELETE /v0.1/servers/{serverName}/versions/{version}`** - Delete specific server version (optional, not implemented by official registry)
+- **`PATCH /v0.1/servers/{serverName}/versions/{version}/status`** - Update server version status (optional)
+- **`PATCH /v0.1/servers/{serverName}/status`** - Update status for all versions (optional)

 Server names and version strings should be URL-encoded in paths.

--- a/docs/reference/api/official-registry-api.md
+++ b/docs/reference/api/official-registry-api.md
@ -38,14 +38,36 @@ The official registry enforces additional [package validation requirements](../s
 The official registry extends the `GET /v0.1/servers` endpoint with additional query parameters for improved discovery and synchronization:

 - `updated_since` - Filter servers updated after RFC3339 timestamp (e.g., `2025-08-07T13:15:04.280Z`)
- `search` - Case-insensitive substring search on server names (e.g., `filesystem`)  
+- `search` - Case-insensitive substring search on server names (e.g., `filesystem`)
    - This is intentionally simple. For more advanced searching and filtering, use a subregistry.
 - `version` - Filter by version (currently supports `latest` for latest versions only)
+- `include_deleted` - Include deleted servers in results (default: `false`, but automatically `true` when `updated_since` is provided for incremental sync)

 These extensions enable efficient incremental synchronization for downstream registries and improved server discovery. Parameters can be combined and work with standard cursor-based pagination.

 Example: `GET /v0.1/servers?search=filesystem&updated_since=2025-08-01T00:00:00Z&version=latest`

+### Server Detail
+
+The `GET /v0.1/servers/{serverName}/versions/{version}` endpoint returns detailed information about a specific server version.
+
+**Path parameters:**
+- `serverName` - URL-encoded server name (e.g., `io.github.user%2Fmy-server`)
+- `version` - Server version or `latest` for the most recent version
+
+**Query parameters:**
+- `include_deleted` - Include deleted servers in results (default: `false`)
+
+### Server Version History
+
+The `GET /v0.1/servers/{serverName}/versions` endpoint returns all versions of a server.
+
+**Path parameters:**
+- `serverName` - URL-encoded server name (e.g., `io.github.user%2Fmy-server`)
+
+**Query parameters:**
+- `include_deleted` - Include deleted servers in results (default: `false`)
+
 ### Additional endpoints

 #### Auth endpoints
@ -55,6 +77,38 @@ Example: `GET /v0.1/servers?search=filesystem&updated_since=2025-08-01T00:00:00Z
 - POST `/v0.1/auth/github-oidc` - Exchange GitHub OIDC token for auth token
 - POST `/v0.1/auth/oidc` - Exchange Google OIDC token for auth token (for admins)

+#### Status endpoints
+
+##### Update Single Version Status
+
+`PATCH /v0.1/servers/{serverName}/versions/{version}/status` - Update status of a specific server version.
+
+**Path parameters:**
+- `serverName` - URL-encoded server name (e.g., `io.github.user%2Fmy-server`)
+- `version` - Server version to update
+
+**Request body:**
+- `status` (required) - New status: `active`, `deprecated`, or `deleted`
+- `statusMessage` (optional) - Message explaining the status change (max 500 characters, not allowed when status is `active`)
+
+##### Update All Versions Status
+
+`PATCH /v0.1/servers/{serverName}/status` - Update status of all versions of a server in a single transaction.
+
+**Path parameters:**
+- `serverName` - URL-encoded server name (e.g., `io.github.user%2Fmy-server`)
+
+**Request body:**
+- `status` (required) - New status: `active`, `deprecated`, or `deleted`
+- `statusMessage` (optional) - Message explaining the status change (max 500 characters, not allowed when status is `active`)
+
+**Status values:**
+- `active` - Server is active and visible in default listings
+- `deprecated` - Server is deprecated but still visible with a warning message
+- `deleted` - Server is hidden from default listings (use `include_deleted=true` to show)
+
+**Authentication:** Requires `publish` or `edit` permission for the server namespace.
+
 #### Admin endpoints
 - GET `/metrics` - Prometheus metrics endpoint
 - GET `/v0.1/health` - Basic health check endpoint
--- a/docs/reference/api/openapi.yaml
+++ b/docs/reference/api/openapi.yaml
@ -61,6 +61,13 @@ paths:
          schema:
            type: string
            example: "1.2.3"
+        - name: include_deleted
+          in: query
+          description: Include deleted servers in results (default false, but always true when updated_since is provided)
+          required: false
+          schema:
+            type: boolean
+            default: false
      responses:
        '200':
          description: A list of MCP servers
@ -307,6 +314,156 @@ paths:
                  error:
                    type: string
                    example: "Deletion is not supported by this registry"
+  /v0.1/servers/{serverName}/versions/{version}/status:
+    patch:
+      tags: [publish]
+      summary: Update server version status
+      description: |
+        Update the lifecycle status of a specific server version.
+
+        Requires `publish` or `edit` permission for the server namespace.
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: serverName
+          in: path
+          required: true
+          description: URL-encoded server name (e.g., "com.example%2Fmy-server")
+          schema:
+            type: string
+            example: "com.example%2Fmy-server"
+        - name: version
+          in: path
+          required: true
+          description: URL-encoded version to update
+          schema:
+            type: string
+            example: "1.0.0"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/StatusUpdateRequest'
+      responses:
+        '200':
+          description: Successfully updated server status
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ServerResponse'
+        '400':
+          description: Bad request - Invalid status transition or no changes to apply
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                    example: "No changes to apply: status is already deprecated"
+        '401':
+          description: Unauthorized - Invalid or missing authentication token
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                    example: "Invalid or expired Registry JWT token"
+        '403':
+          description: Forbidden - Insufficient permissions
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                    example: "You do not have publish or edit permissions for this server"
+        '404':
+          description: Server version not found
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                    example: "Server version not found"
+  /v0.1/servers/{serverName}/status:
+    patch:
+      tags: [publish]
+      summary: Update status for all server versions
+      description: |
+        Update the lifecycle status of all versions of a server in a single transaction.
+        Either all versions are updated or none on failure.
+
+        Requires `publish` or `edit` permission for the server namespace.
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: serverName
+          in: path
+          required: true
+          description: URL-encoded server name (e.g., "com.example%2Fmy-server")
+          schema:
+            type: string
+            example: "com.example%2Fmy-server"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/StatusUpdateRequest'
+      responses:
+        '200':
+          description: Successfully updated all versions
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AllVersionsStatusResponse'
+        '400':
+          description: Bad request - Invalid status value
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                    example: "Invalid status value"
+        '401':
+          description: Unauthorized - Invalid or missing authentication token
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                    example: "Invalid or expired Registry JWT token"
+        '403':
+          description: Forbidden - Insufficient permissions
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                    example: "You do not have publish or edit permissions for this server"
+        '404':
+          description: Server not found
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                    example: "Server not found"
  /v0.1/publish:
    post:
      tags: [publish]
@ -863,6 +1020,11 @@ components:
                  enum: ["active", "deprecated", "deleted"]
                  description: Server lifecycle status
                  example: "active"
+                statusMessage:
+                  type: string
+                  description: Optional message explaining the status (e.g., deprecation reason)
+                  example: "Please upgrade to version 2.0.0"
+                  maxLength: 500
                publishedAt:
                  type: string
                  format: date-time
@ -879,3 +1041,37 @@ components:
                  example: true
              additionalProperties: false
          additionalProperties: true
+
+    StatusUpdateRequest:
+      description: Request body for updating server status
+      type: object
+      required:
+        - status
+      properties:
+        status:
+          type: string
+          enum: ["active", "deprecated", "deleted"]
+          description: New server lifecycle status
+          example: "deprecated"
+        statusMessage:
+          type: string
+          description: Optional message explaining the status change (e.g., deprecation reason)
+          example: "Please upgrade to version 2.0.0"
+          maxLength: 500
+
+    AllVersionsStatusResponse:
+      description: Response from bulk status update for all versions
+      type: object
+      required:
+        - updatedCount
+        - servers
+      properties:
+        updatedCount:
+          type: integer
+          description: Number of versions updated
+          example: 3
+        servers:
+          type: array
+          description: List of all updated server versions
+          items:
+            $ref: '#/components/schemas/ServerResponse'
--- a/docs/reference/cli/commands.md
+++ b/docs/reference/cli/commands.md
@ -276,6 +276,51 @@ mcp-publisher publish
 mcp-publisher publish ./config/server.json
 ```

+### `mcp-publisher status`
+
+Update the lifecycle status of a published server.
+
+**Usage:**
+```bash
+mcp-publisher status --status <active|deprecated|deleted> [flags] <server-name> [version]
+```
+
+**Flags:**
+- `--status` (required) - New status: `active`, `deprecated`, or `deleted`
+- `--message` - Optional message explaining the status change (not allowed when status is `active`)
+- `--all-versions` - Apply status change to all versions of the server
+- `--yes`, `-y` - Skip confirmation prompt (only applies when using `--all-versions`)
+
+**Arguments:**
+- `server-name` - Full server name (e.g., `io.github.user/my-server`)
+- `version` - Server version to update (required unless `--all-versions` is set)
+
+**Status Values:**
+- `active` - Server is active and visible in default listings
+- `deprecated` - Server is deprecated but still visible with a warning message
+- `deleted` - Server is hidden from default listings
+
+**Examples:**
+```bash
+# Deprecate a specific version
+mcp-publisher status --status deprecated --message "Please upgrade to 2.0.0" \
+  io.github.user/my-server 1.0.0
+
+# Delete a version with security issues
+mcp-publisher status --status deleted --message "Critical security vulnerability" \
+  io.github.user/my-server 1.0.0
+
+# Restore a version to active
+mcp-publisher status --status active io.github.user/my-server 1.0.0
+
+# Deprecate all versions at once
+mcp-publisher status --status deprecated --all-versions --message "Project archived" \
+  io.github.user/my-server
+```
+
+**Requirements:**
+- Must be logged in with `publish` or `edit` permission for the server namespace
+
 ### `mcp-publisher logout`

 Clear stored authentication credentials.