Create envelope structure for server.json with versioning and servers list

[JAORMX]

Problem

The current server.json schema directly references ServerDetail without an envelope structure. This makes it difficult to:

1. Include explicit versioning information in the data structure
2. Properly structure server lists with metadata
3. Evolve the format while maintaining backward compatibility

Current State

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://modelcontextprotocol.io/schemas/draft/2025-07-09/server.json",
  "title": "MCP Server Detail",
  "$ref": "#/$defs/ServerDetail"
}

Proposed Solution

Create an envelope structure that wraps server data with versioning and proper list structure:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://modelcontextprotocol.io/schemas/draft/2025-07-09/server-envelope.json",
  "title": "MCP Server Registry Envelope",
  "type": "object",
  "required": ["version", "servers"],
  "properties": {
    "version": {
      "type": "string",
      "description": "Schema version using date-based versioning (YYYY-MM-DD)",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "example": "2025-07-09"
    },
    "servers": {
      "type": "array",
      "description": "List of MCP servers",
      "items": {
        "$ref": "https://modelcontextprotocol.io/schemas/draft/2025-07-09/server.json#/$defs/ServerDetail"
      }
    },
    "metadata": {
      "type": "object",
      "description": "Optional metadata about the server list",
      "properties": {
        "total_count": {
          "type": "integer",
          "description": "Total number of servers in the registry"
        },
        "last_updated": {
          "type": "string",
          "format": "date-time",
          "description": "When this server list was last updated"
        }
      }
    }
  }
}

Benefits

1. Explicit Versioning: Version is part of the data structure, not just the schema ID
2. Future-Proof: Can evolve the envelope without breaking existing server definitions
3. Structured Lists: Proper container for multiple servers with metadata
4. Backward Compatibility: Existing ServerDetail schemas remain unchanged
5. API Consistency: Aligns with REST API patterns for collections

Example Usage

{
  "version": "2025-07-09",
  "servers": [
    {
      "name": "io.modelcontextprotocol/filesystem",
      "description": "Filesystem operations server",
      "version_detail": {
        "version": "1.0.2"
      },
      "packages": [...]
    }
  ],
  "metadata": {
    "total_count": 1,
    "last_updated": "2025-07-09T10:30:00Z"
  }
}

Files to Update

• Create new docs/server-json/envelope-schema.json
• Update documentation to reference the envelope structure
• Consider migration path for existing implementations

[JAORMX]

Note I proposed versioning in https://github.com/modelcontextprotocol/registry/issues/300

[domdomegg]

The list servers endpoint I think does already do this?

E.g. see https://staging.registry.modelcontextprotocol.io/docs#/operations/list-servers

[JAORMX]

@domdomegg gotcha! thanks for the pointer. The part that is not entirely clear to me is why that isn't trickled down to the servers.json

[domdomegg]

I think https://github.com/modelcontextprotocol/registry/discussions/284 has a bunch more on this.