feat: add MCP HTTP server experiment and improve experiment middleware (#18712)

# Add MCP HTTP Server Experiment

This PR adds a new experiment flag `mcp-server-http` to enable the MCP HTTP server functionality. The changes include:

1. Added a new experiment constant `ExperimentMCPServerHTTP` with the value "mcp-server-http"
2. Added display name and documentation for the new experiment
3. Improved the experiment middleware to:
   - Support requiring multiple experiments
   - Provide better error messages with experiment display names
   - Add a development mode bypass option
4. Applied the new experiment requirement to the MCP HTTP endpoint
5. Replaced the custom OAuth2 middleware with the standard experiment middleware

The PR also improves the `Enabled()` method on the `Experiments` type by using `slices.Contains()` for better readability.

coderd/apidoc/docs.go

@@ -12551,11 +12551,13 @@ const docTemplate = `{
                 "notifications",
                 "workspace-usage",
                 "web-push",
-                "oauth2"
+                "oauth2",
+                "mcp-server-http"
             ],
             "x-enum-comments": {
                 "ExperimentAutoFillParameters": "This should not be taken out of experiments until we have redesigned the feature.",
                 "ExperimentExample": "This isn't used for anything.",
+                "ExperimentMCPServerHTTP": "Enables the MCP HTTP server functionality.",
                 "ExperimentNotifications": "Sends notifications via SMTP and webhooks following certain events.",
                 "ExperimentOAuth2": "Enables OAuth2 provider functionality.",
                 "ExperimentWebPush": "Enables web push notifications through the browser.",
@@ -12567,7 +12569,8 @@ const docTemplate = `{
                 "ExperimentNotifications",
                 "ExperimentWorkspaceUsage",
                 "ExperimentWebPush",
-                "ExperimentOAuth2"
+                "ExperimentOAuth2",
+                "ExperimentMCPServerHTTP"
             ]
         },
         "codersdk.ExternalAuth": {

coderd/apidoc/swagger.json

@@ -11232,11 +11232,13 @@
 				"notifications",
 				"workspace-usage",
 				"web-push",
-				"oauth2"
+				"oauth2",
+				"mcp-server-http"
 			],
 			"x-enum-comments": {
 				"ExperimentAutoFillParameters": "This should not be taken out of experiments until we have redesigned the feature.",
 				"ExperimentExample": "This isn't used for anything.",
+				"ExperimentMCPServerHTTP": "Enables the MCP HTTP server functionality.",
 				"ExperimentNotifications": "Sends notifications via SMTP and webhooks following certain events.",
 				"ExperimentOAuth2": "Enables OAuth2 provider functionality.",
 				"ExperimentWebPush": "Enables web push notifications through the browser.",
@@ -11248,7 +11250,8 @@
 				"ExperimentNotifications",
 				"ExperimentWorkspaceUsage",
 				"ExperimentWebPush",
-				"ExperimentOAuth2"
+				"ExperimentOAuth2",
+				"ExperimentMCPServerHTTP"
 			]
 		},
 		"codersdk.ExternalAuth": {

coderd/coderd.go

@@ -922,7 +922,7 @@ func New(options *Options) *API {
 	// logging into Coder with an external OAuth2 provider.
 	r.Route("/oauth2", func(r chi.Router) {
 		r.Use(
-			api.oAuth2ProviderMiddleware,
+			httpmw.RequireExperimentWithDevBypass(api.Experiments, codersdk.ExperimentOAuth2),
 		)
 		r.Route("/authorize", func(r chi.Router) {
 			r.Use(
@@ -973,6 +973,9 @@ func New(options *Options) *API {
 			r.Get("/prompts", api.aiTasksPrompts)
 		})
 		r.Route("/mcp", func(r chi.Router) {
+			r.Use(
+				httpmw.RequireExperimentWithDevBypass(api.Experiments, codersdk.ExperimentOAuth2, codersdk.ExperimentMCPServerHTTP),
+			)
 			// MCP HTTP transport endpoint with mandatory authentication
 			r.Mount("/http", api.mcpHTTPHandler())
 		})
@@ -1473,7 +1476,7 @@ func New(options *Options) *API {
 		r.Route("/oauth2-provider", func(r chi.Router) {
 			r.Use(
 				apiKeyMiddleware,
-				api.oAuth2ProviderMiddleware,
+				httpmw.RequireExperimentWithDevBypass(api.Experiments, codersdk.ExperimentOAuth2),
 			)
 			r.Route("/apps", func(r chi.Router) {
 				r.Get("/", api.oAuth2ProviderApps)

coderd/httpmw/experiments.go

@@ -3,21 +3,59 @@ package httpmw
 import (
 	"fmt"
 	"net/http"
+	"strings"
 
+	"github.com/coder/coder/v2/buildinfo"
 	"github.com/coder/coder/v2/coderd/httpapi"
 	"github.com/coder/coder/v2/codersdk"
 )
 
-func RequireExperiment(experiments codersdk.Experiments, experiment codersdk.Experiment) func(next http.Handler) http.Handler {
+// RequireExperiment returns middleware that checks if all required experiments are enabled.
+// If any experiment is disabled, it returns a 403 Forbidden response with details about the missing experiments.
+func RequireExperiment(experiments codersdk.Experiments, requiredExperiments ...codersdk.Experiment) func(next http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			if !experiments.Enabled(experiment) {
+			for _, experiment := range requiredExperiments {
-				httpapi.Write(r.Context(), w, http.StatusForbidden, codersdk.Response{
+				if !experiments.Enabled(experiment) {
-					Message: fmt.Sprintf("Experiment '%s' is required but not enabled", experiment),
+					var experimentNames []string
-				})
+					for _, exp := range requiredExperiments {
-				return
+						experimentNames = append(experimentNames, string(exp))
+					}
+
+					// Print a message that includes the experiment names
+					// even if some experiments are already enabled.
+					var message string
+					if len(requiredExperiments) == 1 {
+						message = fmt.Sprintf("%s functionality requires enabling the '%s' experiment.",
+							requiredExperiments[0].DisplayName(), requiredExperiments[0])
+					} else {
+						message = fmt.Sprintf("This functionality requires enabling the following experiments: %s",
+							strings.Join(experimentNames, ", "))
+					}
+
+					httpapi.Write(r.Context(), w, http.StatusForbidden, codersdk.Response{
+						Message: message,
+					})
+					return
+				}
 			}
+
 			next.ServeHTTP(w, r)
 		})
 	}
 }
+
+// RequireExperimentWithDevBypass checks if ALL the given experiments are enabled,
+// but bypasses the check in development mode (buildinfo.IsDev()).
+func RequireExperimentWithDevBypass(experiments codersdk.Experiments, requiredExperiments ...codersdk.Experiment) func(next http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if buildinfo.IsDev() {
+				next.ServeHTTP(w, r)
+				return
+			}
+
+			RequireExperiment(experiments, requiredExperiments...)(next).ServeHTTP(w, r)
+		})
+	}
+}

coderd/oauth2.go

@@ -16,7 +16,6 @@ import (
 
 	"github.com/sqlc-dev/pqtype"
 
-	"github.com/coder/coder/v2/buildinfo"
 	"github.com/coder/coder/v2/coderd/audit"
 	"github.com/coder/coder/v2/coderd/database"
 	"github.com/coder/coder/v2/coderd/database/db2sdk"
@@ -37,19 +36,6 @@ const (
 	displaySecretLength = 6  // Length of visible part in UI (last 6 characters)
 )
 
-func (api *API) oAuth2ProviderMiddleware(next http.Handler) http.Handler {
-	return http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) {
-		if !api.Experiments.Enabled(codersdk.ExperimentOAuth2) && !buildinfo.IsDev() {
-			httpapi.Write(r.Context(), rw, http.StatusForbidden, codersdk.Response{
-				Message: "OAuth2 provider functionality requires enabling the 'oauth2' experiment.",
-			})
-			return
-		}
-
-		next.ServeHTTP(rw, r)
-	})
-}
-
 // @Summary Get OAuth2 applications.
 // @ID get-oauth2-applications
 // @Security CoderSessionToken

codersdk/deployment.go

@@ -16,6 +16,8 @@ import (
 
 	"github.com/google/uuid"
 	"golang.org/x/mod/semver"
+	"golang.org/x/text/cases"
+	"golang.org/x/text/language"
 	"golang.org/x/xerrors"
 
 	"github.com/coreos/go-oidc/v3/oidc"
@@ -3342,8 +3344,33 @@ const (
 	ExperimentWorkspaceUsage     Experiment = "workspace-usage"      // Enables the new workspace usage tracking.
 	ExperimentWebPush            Experiment = "web-push"             // Enables web push notifications through the browser.
 	ExperimentOAuth2             Experiment = "oauth2"               // Enables OAuth2 provider functionality.
+	ExperimentMCPServerHTTP      Experiment = "mcp-server-http"      // Enables the MCP HTTP server functionality.
 )
 
+func (e Experiment) DisplayName() string {
+	switch e {
+	case ExperimentExample:
+		return "Example Experiment"
+	case ExperimentAutoFillParameters:
+		return "Auto-fill Template Parameters"
+	case ExperimentNotifications:
+		return "SMTP and Webhook Notifications"
+	case ExperimentWorkspaceUsage:
+		return "Workspace Usage Tracking"
+	case ExperimentWebPush:
+		return "Browser Push Notifications"
+	case ExperimentOAuth2:
+		return "OAuth2 Provider Functionality"
+	case ExperimentMCPServerHTTP:
+		return "MCP HTTP Server Functionality"
+	default:
+		// Split on hyphen and convert to title case
+		// e.g. "web-push" -> "Web Push", "mcp-server-http" -> "Mcp Server Http"
+		caser := cases.Title(language.English)
+		return caser.String(strings.ReplaceAll(string(e), "-", " "))
+	}
+}
+
 // ExperimentsKnown should include all experiments defined above.
 var ExperimentsKnown = Experiments{
 	ExperimentExample,
@@ -3352,6 +3379,7 @@ var ExperimentsKnown = Experiments{
 	ExperimentWorkspaceUsage,
 	ExperimentWebPush,
 	ExperimentOAuth2,
+	ExperimentMCPServerHTTP,
 }
 
 // ExperimentsSafe should include all experiments that are safe for
@@ -3369,14 +3397,9 @@ var ExperimentsSafe = Experiments{}
 // @typescript-ignore Experiments
 type Experiments []Experiment
 
-// Returns a list of experiments that are enabled for the deployment.
+// Enabled returns a list of experiments that are enabled for the deployment.
 func (e Experiments) Enabled(ex Experiment) bool {
-	for _, v := range e {
+	return slices.Contains(e, ex)
-		if v == ex {
-			return true
-		}
-	}
-	return false
 }
 
 func (c *Client) Experiments(ctx context.Context) (Experiments, error) {

docs/reference/api/schemas.md

@@ -3040,6 +3040,7 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o
 | `workspace-usage`      |
 | `web-push`             |
 | `oauth2`               |
+| `mcp-server-http`      |
 
 ## codersdk.ExternalAuth
 

go.mod

@@ -206,7 +206,7 @@ require (
 	golang.org/x/sync v0.14.0
 	golang.org/x/sys v0.33.0
 	golang.org/x/term v0.32.0
-	golang.org/x/text v0.25.0 // indirect
+	golang.org/x/text v0.25.0
 	golang.org/x/tools v0.33.0
 	golang.org/x/xerrors v0.0.0-20240903120638-7835f813f4da
 	google.golang.org/api v0.231.0

site/src/api/typesGenerated.ts

@@ -794,6 +794,7 @@ export const EntitlementsWarningHeader = "X-Coder-Entitlements-Warning";
 export type Experiment =
 	| "auto-fill-parameters"
 	| "example"
+	| "mcp-server-http"
 	| "notifications"
 	| "oauth2"
 	| "web-push"
@@ -802,6 +803,7 @@ export type Experiment =
 export const Experiments: Experiment[] = [
 	"auto-fill-parameters",
 	"example",
+	"mcp-server-http",
 	"notifications",
 	"oauth2",
 	"web-push",