Introduce v0.1 version of the API (#658)

<!-- Provide a brief summary of your changes -->

## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
The following PR adds a new v0.1 API version. 

The goal is to mark v0.1 as a "freeze" point while keeping v0 as the
moving target for new features so integrators can start building on top
of something stable(r).

Details:
* This change is quite simple - we re-register the same handlers twice,
once as `v0` and once as `v0.1`
* Going forward, we'll keep v0.1 frozen while we add changes either on
top of both (non-breaking) or we'll have to branch if breaking changes
are necessary
* We all acknowledge this is not exactly best-practice, but it gives us
a way to gather feedback and allow clients to start integrating with the
API without breaking them (**note** this implies a follow up PR that
would branch the handlers used in v0.1).
* For integrators/clients: please provide your feedback - what works
well, what doesn't so we can take this into account going towards GA.

## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->

## Breaking Changes
<!-- Will users need to update their code or configurations? -->
No, this just adds a new API version alongside the existing one.

## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update

## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [ ] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [ ] My code follows the repository's style guidelines
- [ ] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [ ] I have added or updated documentation as needed

## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
Fixes: #649

Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>

docs/guides/consuming/use-rest-api.md

@@ -4,13 +4,20 @@ Integration patterns and best practices for building applications that consume M
 
 ## Key details
 
-**Base URL**: `https://registry.modelcontextprotocol.io`  
+**Base URL**: `https://registry.modelcontextprotocol.io`
 
 **Authentication**: Not required for read-only access
 
-- **`GET /v0/servers`** - List all servers with pagination
-- **`GET /v0/servers/{serverName}/versions`** - List all versions of a server
-- **`GET /v0/servers/{serverName}/versions/{version}`** - Get specific version of server. Use the special version `latest` to get the latest version.
+**API Versions**:
+- `/v0/` - Development version with latest features (may receive additive changes)
+- `/v0.1/` - Stable version (only backward-compatible changes)
+
+**Recommendation**: Use `/v0.1/` for production applications requiring API stability. Both versions currently have identical functionality.
+
+**Core endpoints:**
+- **`GET /v0.1/servers`** - List all servers with pagination
+- **`GET /v0.1/servers/{serverName}/versions`** - List all versions of a server
+- **`GET /v0.1/servers/{serverName}/versions/{version}`** - Get specific version of server. Use the special version `latest` to get the latest version.
 
 Server names and version strings should be URL-encoded in paths.
 

docs/reference/api/CHANGELOG.md

@@ -4,6 +4,24 @@ Changes to the REST API endpoints and responses.
 
 ## Unreleased
 
+### Added
+
+#### API Versioning - v0.1 Introduction
+
+Introduced `/v0.1/` as a stable API version while `/v0/` continues as the development version.
+
+**New version paths:**
+- All `/v0/` endpoints are now also available at `/v0.1/`
+- Both versions currently share identical behavior
+- `/v0/` will continue to evolve with additive changes (new optional fields, new endpoints)
+- `/v0.1/` will remain stable with only additive, backward-compatible changes
+- Both versions will be maintained until a future v1.0 release
+
+**Migration guidance:**
+- Production applications should consider using `/v0.1/` for stability
+- Development and testing can continue using `/v0/` for latest features
+- No immediate action required - `/v0/` remains fully supported
+
 ### ⚠️ BREAKING CHANGES
 
 #### Endpoint Simplification

internal/api/handlers/v0/auth/dns.go

@@ -50,14 +50,14 @@ func (h *DNSAuthHandler) SetResolver(resolver DNSResolver) {
 }
 
 // RegisterDNSEndpoint registers the DNS authentication endpoint
-func RegisterDNSEndpoint(api huma.API, cfg *config.Config) {
+func RegisterDNSEndpoint(api huma.API, pathPrefix string, cfg *config.Config) {
 	handler := NewDNSAuthHandler(cfg)
 
 	// DNS authentication endpoint
 	huma.Register(api, huma.Operation{
-		OperationID: "exchange-dns-token",
+		OperationID: "exchange-dns-token" + pathPrefix,
 		Method:      http.MethodPost,
-		Path:        "/v0/auth/dns",
+		Path:        pathPrefix + "/auth/dns",
 		Summary:     "Exchange DNS signature for Registry JWT",
 		Description: "Authenticate using DNS TXT record public key and signed timestamp",
 		Tags:        []string{"auth"},

internal/api/handlers/v0/auth/github_at.go

@@ -42,15 +42,15 @@ func (h *GitHubHandler) SetBaseURL(url string) {
 	h.baseURL = url
 }
 
-// RegisterGitHubATEndpoint registers the GitHub access token authentication endpoint
-func RegisterGitHubATEndpoint(api huma.API, cfg *config.Config) {
+// RegisterGitHubATEndpoint registers the GitHub access token authentication endpoint with a custom path prefix
+func RegisterGitHubATEndpoint(api huma.API, pathPrefix string, cfg *config.Config) {
 	handler := NewGitHubHandler(cfg)
 
 	// GitHub token exchange endpoint
 	huma.Register(api, huma.Operation{
-		OperationID: "exchange-github-token",
+		OperationID: "exchange-github-token" + pathPrefix,
 		Method:      http.MethodPost,
-		Path:        "/v0/auth/github-at",
+		Path:        pathPrefix + "/auth/github-at",
 		Summary:     "Exchange GitHub OAuth access token for Registry JWT",
 		Description: "Exchange a GitHub OAuth access token for a short-lived Registry JWT token",
 		Tags:        []string{"auth"},

internal/api/handlers/v0/auth/github_oidc.go

@@ -226,14 +226,14 @@ func (h *GitHubOIDCHandler) SetValidator(validator OIDCValidator) {
 }
 
 // RegisterGitHubOIDCEndpoint registers the GitHub OIDC authentication endpoint
-func RegisterGitHubOIDCEndpoint(api huma.API, cfg *config.Config) {
+func RegisterGitHubOIDCEndpoint(api huma.API, pathPrefix string, cfg *config.Config) {
 	handler := NewGitHubOIDCHandler(cfg)
 
 	// GitHub OIDC token exchange endpoint
 	huma.Register(api, huma.Operation{
-		OperationID: "exchange-github-oidc-token",
+		OperationID: "exchange-github-oidc-token" + pathPrefix,
 		Method:      http.MethodPost,
-		Path:        "/v0/auth/github-oidc",
+		Path:        pathPrefix + "/auth/github-oidc",
 		Summary:     "Exchange GitHub OIDC token for Registry JWT",
 		Description: "Exchange a GitHub Actions OIDC token for a short-lived Registry JWT token",
 		Tags:        []string{"auth"},

internal/api/handlers/v0/auth/http.go

@@ -108,14 +108,14 @@ func (h *HTTPAuthHandler) SetFetcher(fetcher HTTPKeyFetcher) {
 }
 
 // RegisterHTTPEndpoint registers the HTTP authentication endpoint
-func RegisterHTTPEndpoint(api huma.API, cfg *config.Config) {
+func RegisterHTTPEndpoint(api huma.API, pathPrefix string, cfg *config.Config) {
 	handler := NewHTTPAuthHandler(cfg)
 
 	// HTTP authentication endpoint
 	huma.Register(api, huma.Operation{
-		OperationID: "exchange-http-token",
+		OperationID: "exchange-http-token" + pathPrefix,
 		Method:      http.MethodPost,
-		Path:        "/v0/auth/http",
+		Path:        pathPrefix + "/auth/http",
 		Summary:     "Exchange HTTP signature for Registry JWT",
 		Description: "Authenticate using HTTP-hosted public key and signed timestamp",
 		Tags:        []string{"auth"},

internal/api/handlers/v0/auth/main.go

@@ -5,23 +5,23 @@ import (
 	"github.com/modelcontextprotocol/registry/internal/config"
 )
 
-// RegisterAuthEndpoints registers all authentication endpoints
-func RegisterAuthEndpoints(api huma.API, cfg *config.Config) {
+// RegisterAuthEndpoints registers all authentication endpoints with a custom path prefix
+func RegisterAuthEndpoints(api huma.API, pathPrefix string, cfg *config.Config) {
 	// Register GitHub access token authentication endpoint
-	RegisterGitHubATEndpoint(api, cfg)
+	RegisterGitHubATEndpoint(api, pathPrefix, cfg)
 
 	// Register GitHub OIDC authentication endpoint
-	RegisterGitHubOIDCEndpoint(api, cfg)
+	RegisterGitHubOIDCEndpoint(api, pathPrefix, cfg)
 
 	// Register configurable OIDC authentication endpoints
-	RegisterOIDCEndpoints(api, cfg)
+	RegisterOIDCEndpoints(api, pathPrefix, cfg)
 
 	// Register DNS-based authentication endpoint
-	RegisterDNSEndpoint(api, cfg)
+	RegisterDNSEndpoint(api, pathPrefix, cfg)
 
 	// Register HTTP-based authentication endpoint
-	RegisterHTTPEndpoint(api, cfg)
+	RegisterHTTPEndpoint(api, pathPrefix, cfg)
 
 	// Register anonymous authentication endpoint
-	RegisterNoneEndpoint(api, cfg)
+	RegisterNoneEndpoint(api, pathPrefix, cfg)
 }

internal/api/handlers/v0/auth/none.go

@@ -28,7 +28,7 @@ func NewNoneHandler(cfg *config.Config) *NoneHandler {
 // RegisterNoneEndpoint registers the anonymous authentication endpoint
 // WARNING: This endpoint is intended for local development and automated tests only.
 // It should NOT be enabled in production environments as it bypasses normal authentication.
-func RegisterNoneEndpoint(api huma.API, cfg *config.Config) {
+func RegisterNoneEndpoint(api huma.API, pathPrefix string, cfg *config.Config) {
 	if !cfg.EnableAnonymousAuth {
 		return
 	}
@@ -39,7 +39,7 @@ func RegisterNoneEndpoint(api huma.API, cfg *config.Config) {
 	huma.Register(api, huma.Operation{
 		OperationID: "get-anonymous-token",
 		Method:      http.MethodPost,
-		Path:        "/v0/auth/none",
+		Path:        pathPrefix + "/auth/none",
 		Summary:     "Get anonymous Registry JWT (Development/Testing Only)",
 		Description: "Get a short-lived Registry JWT token for publishing and editing servers in the io.modelcontextprotocol.anonymous/* namespace. This endpoint is intended for local development and automated testing only.",
 		Tags:        []string{"auth"},

internal/api/handlers/v0/auth/oidc.go

@@ -145,7 +145,7 @@ func (h *OIDCHandler) SetValidator(validator GenericOIDCValidator) {
 }
 
 // RegisterOIDCEndpoints registers all OIDC authentication endpoints
-func RegisterOIDCEndpoints(api huma.API, cfg *config.Config) {
+func RegisterOIDCEndpoints(api huma.API, pathPrefix string, cfg *config.Config) {
 	if !cfg.OIDCEnabled {
 		return // Skip registration if OIDC is not enabled
 	}
@@ -154,9 +154,9 @@ func RegisterOIDCEndpoints(api huma.API, cfg *config.Config) {
 
 	// Direct token exchange endpoint
 	huma.Register(api, huma.Operation{
-		OperationID: "exchange-oidc-token",
+		OperationID: "exchange-oidc-token" + pathPrefix,
 		Method:      http.MethodPost,
-		Path:        "/v0/auth/oidc",
+		Path:        pathPrefix + "/auth/oidc",
 		Summary:     "Exchange OIDC ID token for Registry JWT",
 		Description: "Exchange an OIDC ID token from any configured provider for a short-lived Registry JWT token",
 		Tags:        []string{"auth"},

internal/api/handlers/v0/edit.go

@@ -25,15 +25,15 @@ type EditServerInput struct {
 	Body          apiv0.ServerJSON `body:""`
 }
 
-// RegisterEditEndpoints registers the edit endpoint
-func RegisterEditEndpoints(api huma.API, registry service.RegistryService, cfg *config.Config) {
+// RegisterEditEndpoints registers the edit endpoint with a custom path prefix
+func RegisterEditEndpoints(api huma.API, pathPrefix string, registry service.RegistryService, cfg *config.Config) {
 	jwtManager := auth.NewJWTManager(cfg)
 
 	// Edit server endpoint
 	huma.Register(api, huma.Operation{
-		OperationID: "edit-server",
+		OperationID: "edit-server" + pathPrefix,
 		Method:      http.MethodPut,
-		Path:        "/v0/servers/{serverName}/versions/{version}",
+		Path:        pathPrefix + "/servers/{serverName}/versions/{version}",
 		Summary:     "Edit MCP server",
 		Description: "Update a specific version of an existing MCP server (admin only).",
 		Tags:        []string{"admin"},

internal/api/handlers/v0/edit_test.go

@@ -371,7 +371,7 @@ func TestEditServerEndpoint(t *testing.T) {
 			api := humago.New(mux, huma.DefaultConfig("Test API", "1.0.0"))
 
 			// Register edit endpoints
-			v0.RegisterEditEndpoints(api, registryService, cfg)
+			v0.RegisterEditEndpoints(api, "/v0", registryService, cfg)
 
 			// Create request body
 			requestBody, err := json.Marshal(tc.requestBody)
@@ -469,7 +469,7 @@ func TestEditServerEndpointEdgeCases(t *testing.T) {
 	// Create API
 	mux := http.NewServeMux()
 	api := humago.New(mux, huma.DefaultConfig("Test API", "1.0.0"))
-	v0.RegisterEditEndpoints(api, registryService, cfg)
+	v0.RegisterEditEndpoints(api, "/v0", registryService, cfg)
 
 	t.Run("status transitions", func(t *testing.T) {
 		tests := []struct {

internal/api/handlers/v0/health.go

@@ -18,18 +18,18 @@ type HealthBody struct {
 	GitHubClientID string `json:"github_client_id,omitempty" doc:"GitHub OAuth App Client ID"`
 }
 
-// RegisterHealthEndpoint registers the health check endpoint
-func RegisterHealthEndpoint(api huma.API, cfg *config.Config, metrics *telemetry.Metrics) {
+// RegisterHealthEndpoint registers the health check endpoint with a custom path prefix
+func RegisterHealthEndpoint(api huma.API, pathPrefix string, cfg *config.Config, metrics *telemetry.Metrics) {
 	huma.Register(api, huma.Operation{
-		OperationID: "get-health",
+		OperationID: "get-health" + pathPrefix,
 		Method:      http.MethodGet,
-		Path:        "/v0/health",
+		Path:        pathPrefix + "/health",
 		Summary:     "Health check",
 		Description: "Check the health status of the API",
 		Tags:        []string{"health"},
 	}, func(ctx context.Context, _ *struct{}) (*Response[HealthBody], error) {
 		// Record the health check metrics
-		recordHealthMetrics(ctx, metrics, "/v0/health", cfg.Version)
+		recordHealthMetrics(ctx, metrics, pathPrefix+"/health", cfg.Version)
 
 		return &Response[HealthBody]{
 			Body: HealthBody{

internal/api/handlers/v0/health_test.go

@@ -56,7 +56,7 @@ func TestHealthEndpoint(t *testing.T) {
 			shutdownTelemetry, metrics, _ := telemetry.InitMetrics("test")
 
 			// Register the health endpoint
-			v0.RegisterHealthEndpoint(api, tc.config, metrics)
+			v0.RegisterHealthEndpoint(api, "/v0", tc.config, metrics)
 
 			// Create a test request
 			req := httptest.NewRequest(http.MethodGet, "/v0/health", nil)

internal/api/handlers/v0/ping.go

@@ -12,12 +12,12 @@ type PingBody struct {
 	Pong bool `json:"pong" example:"true" doc:"Ping response"`
 }
 
-// RegisterPingEndpoint registers the ping endpoint
-func RegisterPingEndpoint(api huma.API) {
+// RegisterPingEndpoint registers the ping endpoint with a custom path prefix
+func RegisterPingEndpoint(api huma.API, pathPrefix string) {
 	huma.Register(api, huma.Operation{
-		OperationID: "ping",
+		OperationID: "ping" + pathPrefix,
 		Method:      http.MethodGet,
-		Path:        "/v0/ping",
+		Path:        pathPrefix + "/ping",
 		Summary:     "Ping",
 		Description: "Simple ping endpoint",
 		Tags:        []string{"ping"},

internal/api/handlers/v0/ping_test.go

@@ -17,7 +17,7 @@ func TestPingEndpoint(t *testing.T) {
 	api := humago.New(mux, huma.DefaultConfig("Test API", "1.0.0"))
 
 	// Register the ping endpoint
-	v0.RegisterPingEndpoint(api)
+	v0.RegisterPingEndpoint(api, "/v0")
 
 	// Create a test request
 	req := httptest.NewRequest(http.MethodGet, "/v0/ping", nil)

internal/api/handlers/v0/publish.go

@@ -18,15 +18,15 @@ type PublishServerInput struct {
 	Body          apiv0.ServerJSON `body:""`
 }
 
-// RegisterPublishEndpoint registers the publish endpoint
-func RegisterPublishEndpoint(api huma.API, registry service.RegistryService, cfg *config.Config) {
+// RegisterPublishEndpoint registers the publish endpoint with a custom path prefix
+func RegisterPublishEndpoint(api huma.API, pathPrefix string, registry service.RegistryService, cfg *config.Config) {
 	// Create JWT manager for token validation
 	jwtManager := auth.NewJWTManager(cfg)
 
 	huma.Register(api, huma.Operation{
-		OperationID: "publish-server",
+		OperationID: "publish-server" + pathPrefix,
 		Method:      http.MethodPost,
-		Path:        "/v0/publish",
+		Path:        pathPrefix + "/publish",
 		Summary:     "Publish MCP server",
 		Description: "Publish a new MCP server to the registry or update an existing one",
 		Tags:        []string{"publish"},

internal/api/handlers/v0/publish_integration_test.go

@@ -53,7 +53,7 @@ func TestPublishIntegration(t *testing.T) {
 	api := humago.New(mux, huma.DefaultConfig("Test API", "1.0.0"))
 
 	// Register the endpoint
-	v0.RegisterPublishEndpoint(api, registryService, testConfig)
+	v0.RegisterPublishEndpoint(api, "/v0", registryService, testConfig)
 
 	t.Run("successful publish with GitHub auth", func(t *testing.T) {
 		publishReq := apiv0.ServerJSON{

internal/api/handlers/v0/publish_registry_validation_test.go

@@ -41,7 +41,7 @@ func TestPublishRegistryValidation(t *testing.T) {
 	api := humago.New(mux, huma.DefaultConfig("Test API", "1.0.0"))
 
 	// Register the endpoint
-	v0.RegisterPublishEndpoint(api, registryService, testConfig)
+	v0.RegisterPublishEndpoint(api, "/v0", registryService, testConfig)
 
 	t.Run("publish fails with npm registry validation error", func(t *testing.T) {
 		publishReq := apiv0.ServerJSON{

internal/api/handlers/v0/publish_test.go

@@ -381,7 +381,7 @@ func TestPublishEndpoint(t *testing.T) {
 			api := humago.New(mux, huma.DefaultConfig("Test API", "1.0.0"))
 
 			// Register the endpoint with test config
-			v0.RegisterPublishEndpoint(api, registryService, testConfig)
+			v0.RegisterPublishEndpoint(api, "/v0", registryService, testConfig)
 
 			// Prepare request body
 			var requestBody []byte
@@ -480,7 +480,7 @@ func TestPublishEndpoint_MultipleSlashesEdgeCases(t *testing.T) {
 			api := humago.New(mux, huma.DefaultConfig("Test API", "1.0.0"))
 
 			// Register the endpoint
-			v0.RegisterPublishEndpoint(api, registryService, testConfig)
+			v0.RegisterPublishEndpoint(api, "/v0", registryService, testConfig)
 
 			// Create request body
 			requestBody := apiv0.ServerJSON{

internal/api/handlers/v0/servers.go

@@ -40,13 +40,13 @@ type ServerVersionsInput struct {
 	ServerName string `path:"serverName" doc:"URL-encoded server name" example:"com.example%2Fmy-server"`
 }
 
-// RegisterServersEndpoints registers all server-related endpoints
-func RegisterServersEndpoints(api huma.API, registry service.RegistryService) {
+// RegisterServersEndpoints registers all server-related endpoints with a custom path prefix
+func RegisterServersEndpoints(api huma.API, pathPrefix string, registry service.RegistryService) {
 	// List servers endpoint
 	huma.Register(api, huma.Operation{
-		OperationID: "list-servers",
+		OperationID: "list-servers" + pathPrefix,
 		Method:      http.MethodGet,
-		Path:        "/v0/servers",
+		Path:        pathPrefix + "/servers",
 		Summary:     "List MCP servers",
 		Description: "Get a paginated list of MCP servers from the registry",
 		Tags:        []string{"servers"},
@@ -106,9 +106,9 @@ func RegisterServersEndpoints(api huma.API, registry service.RegistryService) {
 
 	// Get specific server version endpoint (supports "latest" as special version)
 	huma.Register(api, huma.Operation{
-		OperationID: "get-server-version",
+		OperationID: "get-server-version" + pathPrefix,
 		Method:      http.MethodGet,
-		Path:        "/v0/servers/{serverName}/versions/{version}",
+		Path:        pathPrefix + "/servers/{serverName}/versions/{version}",
 		Summary:     "Get specific MCP server version",
 		Description: "Get detailed information about a specific version of an MCP server. Use the special version 'latest' to get the latest version.",
 		Tags:        []string{"servers"},
@@ -147,9 +147,9 @@ func RegisterServersEndpoints(api huma.API, registry service.RegistryService) {
 
 	// Get server versions endpoint
 	huma.Register(api, huma.Operation{
-		OperationID: "get-server-versions",
+		OperationID: "get-server-versions" + pathPrefix,
 		Method:      http.MethodGet,
-		Path:        "/v0/servers/{serverName}/versions",
+		Path:        pathPrefix + "/servers/{serverName}/versions",
 		Summary:     "Get all versions of an MCP server",
 		Description: "Get all available versions for a specific MCP server",
 		Tags:        []string{"servers"},