mcp: serve well-known resources at the mcp route path (#1596)

**Description**

Only serve the `.well-known` endpoints at the paths exposed by the
`MCPRoute` and not serve on `/` by default.

According to the spec [1], clients **MUST** use the URL returned in the
`WWW-Authenticate` header and support requesting a `well-known` resource
in the configured path. The "root" resource is just a fallback.

We can't expose the resource at the root because we can have multiple
MCPRoutes with different security configurations, so we need to rely on
clients properly implementing the spec and fetching the well-known
resources from the right path.

**Related Issues/PRs (if applicable)**

Fixes #1585

**Special notes for reviewers (if applicable)**

This has been tested with the MCP inspector and Goose as two of the
popular clients, with Descope as the Authentication provider, and
validated that it works fine with them.

1:
https://mcp.mintlify.app/specification/2025-11-25/basic/authorization#protected-resource-metadata-discovery-requirements

Signed-off-by: Ignasi Barrera <[email protected]>

Author: nacx

internal/controller/mcp_route.go

@@ -9,6 +9,7 @@ import (
 	"cmp"
 	"context"
 	"fmt"
+	"strings"
 
 	egv1a1 "github.com/envoyproxy/gateway/api/v1alpha1"
 	"github.com/go-logr/logr"
@@ -251,23 +252,20 @@ func (c *MCPRouteController) newMainHTTPRoute(dst *gwapiv1.HTTPRoute, mcpRoute *
 
 	// Add OAuth metadata endpoints if authentication is configured.
 	if mcpRoute.Spec.SecurityPolicy != nil && mcpRoute.Spec.SecurityPolicy.OAuth != nil {
-		// Extract path component for RFC 8414 compliant well-known URI construction
-		// RFC 8414: https://datatracker.ietf.org/doc/html/rfc8414#section-3.1
-		// Pattern: "/.well-known/oauth-authorization-server" + issuer_path_component.
-
 		// OAuth 2.0 Protected Resource Metadata (RFC 9728) - serve in both root and suffix paths because different clients
 		// may expect either.
 		// TODO: only one MCPRoute targeting the same listener can be configured with OAuth due to the fixed well-known path.
 		httpRouteFilterName := oauthProtectedResourceMetadataName(mcpRoute.Name)
 
-		// Root path: /.well-known/oauth-protected-resource.
-		protectedResourceRootRule := gwapiv1.HTTPRouteRule{
-			Name: ptr.To(gwapiv1.SectionName("oauth-protected-resource-metadata-root")),
+		// Suffix path: /.well-known/oauth-protected-resource{pathPrefix} (if pathPrefix exists).
+		protectedResourceSuffixPath := fmt.Sprintf("/.well-known/oauth-protected-resource%s", strings.TrimSuffix(servingPath, "/"))
+		protectedResourceSuffixRule := gwapiv1.HTTPRouteRule{
+			Name: ptr.To(gwapiv1.SectionName("oauth-protected-resource-metadata")),
 			Matches: []gwapiv1.HTTPRouteMatch{
 				{
 					Path: &gwapiv1.HTTPPathMatch{
 						Type:  ptr.To(gwapiv1.PathMatchExact),
-						Value: ptr.To(oauthWellKnownProtectedResourceMetadataPath),
+						Value: ptr.To(protectedResourceSuffixPath),
 					},
 				},
 			},
@@ -282,47 +280,22 @@ func (c *MCPRouteController) newMainHTTPRoute(dst *gwapiv1.HTTPRoute, mcpRoute *
 				},
 			},
 		}
-		rules = append(rules, protectedResourceRootRule)
-
-		// Suffix path: /.well-known/oauth-protected-resource{pathPrefix} (if pathPrefix exists).
-		if servingPath != "/" {
-			protectedResourceSuffixPath := fmt.Sprintf("/.well-known/oauth-protected-resource%s", servingPath)
-			protectedResourceSuffixRule := gwapiv1.HTTPRouteRule{
-				Name: ptr.To(gwapiv1.SectionName("oauth-protected-resource-metadata-suffix")),
-				Matches: []gwapiv1.HTTPRouteMatch{
-					{
-						Path: &gwapiv1.HTTPPathMatch{
-							Type:  ptr.To(gwapiv1.PathMatchExact),
-							Value: ptr.To(protectedResourceSuffixPath),
-						},
-					},
-				},
-				Filters: []gwapiv1.HTTPRouteFilter{
-					{
-						Type: gwapiv1.HTTPRouteFilterExtensionRef,
-						ExtensionRef: &gwapiv1.LocalObjectReference{
-							Group: gwapiv1.Group("gateway.envoyproxy.io"),
-							Kind:  gwapiv1.Kind("HTTPRouteFilter"),
-							Name:  gwapiv1.ObjectName(httpRouteFilterName),
-						},
-					},
-				},
-			}
-			rules = append(rules, protectedResourceSuffixRule)
-		}
+		rules = append(rules, protectedResourceSuffixRule)
 
-		// OAuth 2.0 Authorization Server Metadata (RFC 8414) - serve in both root and suffix paths because different clients
-		// may expect either.
+		// Extract path component for RFC 8414 compliant well-known URI construction
+		// RFC 8414: https://datatracker.ietf.org/doc/html/rfc8414#section-3.1
+		// Pattern: "/.well-known/oauth-authorization-server" + issuer_path_component.
 		authServerMeataFilterName := oauthAuthServerMetadataFilterName(mcpRoute.Name)
 
-		// Root path: /.well-known/oauth-authorization-server.
-		authServerRootRule := gwapiv1.HTTPRouteRule{
-			Name: ptr.To(gwapiv1.SectionName("oauth-authorization-server-metadata-root")),
+		// Suffix path: /.well-known/oauth-authorization-server{pathPrefix} (if pathPrefix exists).
+		authServerSuffixPath := fmt.Sprintf("%s%s", oauthWellKnownAuthorizationServerMetadataPath, strings.TrimSuffix(servingPath, "/"))
+		authServerSuffixRule := gwapiv1.HTTPRouteRule{
+			Name: ptr.To(gwapiv1.SectionName("oauth-authorization-server-metadata")),
 			Matches: []gwapiv1.HTTPRouteMatch{
 				{
 					Path: &gwapiv1.HTTPPathMatch{
 						Type:  ptr.To(gwapiv1.PathMatchExact),
-						Value: ptr.To(oauthWellKnownAuthorizationServerMetadataPath),
+						Value: ptr.To(authServerSuffixPath),
 					},
 				},
 			},
@@ -337,14 +310,15 @@ func (c *MCPRouteController) newMainHTTPRoute(dst *gwapiv1.HTTPRoute, mcpRoute *
 				},
 			},
 		}
-		// Root path: /.well-known/openid-configuration.
-		authServerRootOIDCRule := gwapiv1.HTTPRouteRule{
-			Name: ptr.To(gwapiv1.SectionName("oauth-authorization-server-metadata-root-oidc")),
+		// Suffix path: /.well-known/openid-configuration{pathPrefix} (if pathPrefix exists).
+		authServerSuffixPathOIDC := fmt.Sprintf("%s%s", oidcWellKnownMetadataPath, servingPath)
+		authServerSuffixRuleOIDC := gwapiv1.HTTPRouteRule{
+			Name: ptr.To(gwapiv1.SectionName("oauth-authorization-server-metadata-oidc")),
 			Matches: []gwapiv1.HTTPRouteMatch{
 				{
 					Path: &gwapiv1.HTTPPathMatch{
 						Type:  ptr.To(gwapiv1.PathMatchExact),
-						Value: ptr.To(oidcWellKnownMetadataPath),
+						Value: ptr.To(authServerSuffixPathOIDC),
 					},
 				},
 			},
@@ -359,57 +333,7 @@ func (c *MCPRouteController) newMainHTTPRoute(dst *gwapiv1.HTTPRoute, mcpRoute *
 				},
 			},
 		}
-		rules = append(rules, authServerRootRule, authServerRootOIDCRule)
-
-		if servingPath != "/" {
-			// Suffix path: /.well-known/oauth-authorization-server{pathPrefix} (if pathPrefix exists).
-			authServerSuffixPath := fmt.Sprintf("%s%s", oauthWellKnownAuthorizationServerMetadataPath, servingPath)
-			authServerSuffixRule := gwapiv1.HTTPRouteRule{
-				Name: ptr.To(gwapiv1.SectionName("oauth-authorization-server-metadata-suffix")),
-				Matches: []gwapiv1.HTTPRouteMatch{
-					{
-						Path: &gwapiv1.HTTPPathMatch{
-							Type:  ptr.To(gwapiv1.PathMatchExact),
-							Value: ptr.To(authServerSuffixPath),
-						},
-					},
-				},
-				Filters: []gwapiv1.HTTPRouteFilter{
-					{
-						Type: gwapiv1.HTTPRouteFilterExtensionRef,
-						ExtensionRef: &gwapiv1.LocalObjectReference{
-							Group: gwapiv1.Group("gateway.envoyproxy.io"),
-							Kind:  gwapiv1.Kind("HTTPRouteFilter"),
-							Name:  gwapiv1.ObjectName(authServerMeataFilterName),
-						},
-					},
-				},
-			}
-			// Suffix path: /.well-known/openid-configuration{pathPrefix} (if pathPrefix exists).
-			authServerSuffixPathOIDC := fmt.Sprintf("%s%s", oidcWellKnownMetadataPath, servingPath)
-			authServerSuffixRuleOIDC := gwapiv1.HTTPRouteRule{
-				Name: ptr.To(gwapiv1.SectionName("oauth-authorization-server-metadata-suffix-oidc")),
-				Matches: []gwapiv1.HTTPRouteMatch{
-					{
-						Path: &gwapiv1.HTTPPathMatch{
-							Type:  ptr.To(gwapiv1.PathMatchExact),
-							Value: ptr.To(authServerSuffixPathOIDC),
-						},
-					},
-				},
-				Filters: []gwapiv1.HTTPRouteFilter{
-					{
-						Type: gwapiv1.HTTPRouteFilterExtensionRef,
-						ExtensionRef: &gwapiv1.LocalObjectReference{
-							Group: gwapiv1.Group("gateway.envoyproxy.io"),
-							Kind:  gwapiv1.Kind("HTTPRouteFilter"),
-							Name:  gwapiv1.ObjectName(authServerMeataFilterName),
-						},
-					},
-				},
-			}
-			rules = append(rules, authServerSuffixRule, authServerSuffixRuleOIDC)
-		}
+		rules = append(rules, authServerSuffixRule, authServerSuffixRuleOIDC)
 	}
 	dst.Spec.Rules = rules
 

internal/controller/mcp_route_security_policy.go

@@ -290,8 +290,11 @@ func buildWWWAuthenticateHeaderValue(metadata *aigv1a1.ProtectedResourceMetadata
 	// Extract base URL and path from resource identifier.
 	resourceURL := strings.TrimSuffix(metadata.Resource, "/")
 
-	var baseURL string
-	var prefixLen int
+	var (
+		baseURL       string
+		prefixLen     int
+		pathComponent string
+	)
 	switch {
 	case strings.HasPrefix(resourceURL, "https://"):
 		prefixLen = 8
@@ -303,14 +306,17 @@ func buildWWWAuthenticateHeaderValue(metadata *aigv1a1.ProtectedResourceMetadata
 
 	if idx := strings.Index(resourceURL[prefixLen:], "/"); idx != -1 {
 		baseURL = resourceURL[:prefixLen+idx]
+		pathComponent = resourceURL[prefixLen+idx:]
 	} else {
 		baseURL = resourceURL
 	}
 
-	// Some agents do not expect the path component to be included in the resource_metadata URL.
-	// TODO: test with different agents and see if this would cause issues.
-	// resourceMetadataURL := fmt.Sprintf("%s/.well-known/oauth-protected-resource%s", baseURL, pathComponent).
-	resourceMetadataURL := fmt.Sprintf("%s%s", baseURL, oauthWellKnownProtectedResourceMetadataPath)
+	// Some agents do not expect the path component to be included in the resource_metadata URL, but according to the
+	// spec https://mcp.mintlify.app/specification/2025-11-25/basic/authorization#protected-resource-metadata-discovery-requirements
+	// they should honor hte value returned here.
+	// We can't expose these resource at the root, because there may be multiple MCP routes with different OAuth settings, so we need
+	// to rely on clients properly implementing the spec and using this value returned in the header.
+	resourceMetadataURL := fmt.Sprintf("%s%s%s", baseURL, oauthWellKnownProtectedResourceMetadataPath, pathComponent)
 	// Build the basic Bearer challenge.
 	headerValue := `Bearer error="invalid_request", error_description="No access token was provided in this request"`
 

internal/controller/mcp_route_security_policy_test.go

@@ -596,7 +596,7 @@ func Test_buildWWWAuthenticateHeaderValue(t *testing.T) {
 			metadata: &aigv1a1.ProtectedResourceMetadata{
 				Resource: "https://api.example.com/mcp/v1",
 			},
-			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"`,
+			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp/v1"`,
 		},
 		{
 			name: "https URL without path",
@@ -610,14 +610,14 @@ func Test_buildWWWAuthenticateHeaderValue(t *testing.T) {
 			metadata: &aigv1a1.ProtectedResourceMetadata{
 				Resource: "https://api.example.com/mcp/",
 			},
-			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"`,
+			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp"`,
 		},
 		{
 			name: "http URL with path",
 			metadata: &aigv1a1.ProtectedResourceMetadata{
 				Resource: "http://api.example.com/mcp/v1",
 			},
-			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="http://api.example.com/.well-known/oauth-protected-resource"`,
+			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="http://api.example.com/.well-known/oauth-protected-resource/mcp/v1"`,
 		},
 		{
 			name: "http URL without path",
@@ -631,28 +631,28 @@ func Test_buildWWWAuthenticateHeaderValue(t *testing.T) {
 			metadata: &aigv1a1.ProtectedResourceMetadata{
 				Resource: "http://api.example.com/mcp/",
 			},
-			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="http://api.example.com/.well-known/oauth-protected-resource"`,
+			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="http://api.example.com/.well-known/oauth-protected-resource/mcp"`,
 		},
 		{
 			name: "URL with port number https",
 			metadata: &aigv1a1.ProtectedResourceMetadata{
 				Resource: "https://api.example.com:8080/mcp",
 			},
-			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="https://api.example.com:8080/.well-known/oauth-protected-resource"`,
+			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="https://api.example.com:8080/.well-known/oauth-protected-resource/mcp"`,
 		},
 		{
 			name: "URL with port number http",
 			metadata: &aigv1a1.ProtectedResourceMetadata{
 				Resource: "http://api.example.com:8080/mcp",
 			},
-			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="http://api.example.com:8080/.well-known/oauth-protected-resource"`,
+			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="http://api.example.com:8080/.well-known/oauth-protected-resource/mcp"`,
 		},
 		{
 			name: "complex path with multiple segments",
 			metadata: &aigv1a1.ProtectedResourceMetadata{
 				Resource: "https://api.example.com/v1/mcp/endpoint",
 			},
-			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"`,
+			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/v1/mcp/endpoint"`,
 		},
 	}
 

internal/controller/mcp_route_test.go

@@ -217,19 +217,14 @@ func Test_newHTTPRoute_MCPOauth(t *testing.T) {
 	err := ctrlr.newMainHTTPRoute(httpRoute, mcpRoute)
 	require.NoError(t, err)
 
-	require.Len(t, httpRoute.Spec.Rules, 7) // 6 default routes for oauth which begins from index 1.
+	require.Len(t, httpRoute.Spec.Rules, 4) // 3 default routes for oauth which begins from index 1.
 	oauthRules := httpRoute.Spec.Rules[1:]
-	require.Equal(t, "oauth-protected-resource-metadata-root", string(ptr.Deref(oauthRules[0].Name, "")))
-	require.Equal(t, "oauth-protected-resource-metadata-suffix", string(ptr.Deref(oauthRules[1].Name, "")))
-	require.Equal(t, "oauth-authorization-server-metadata-root", string(ptr.Deref(oauthRules[2].Name, "")))
-	require.Equal(t, "oauth-authorization-server-metadata-root-oidc", string(ptr.Deref(oauthRules[3].Name, "")))
-	require.Equal(t, "oauth-authorization-server-metadata-suffix", string(ptr.Deref(oauthRules[4].Name, "")))
-	require.Equal(t, "oauth-authorization-server-metadata-suffix-oidc", string(ptr.Deref(oauthRules[5].Name, "")))
-
-	require.Equal(t, "/.well-known/oauth-authorization-server", ptr.Deref(oauthRules[2].Matches[0].Path.Value, ""))
-	require.Equal(t, "/.well-known/openid-configuration", ptr.Deref(oauthRules[3].Matches[0].Path.Value, ""))
-	require.Equal(t, "/.well-known/oauth-authorization-server/mcp", ptr.Deref(oauthRules[4].Matches[0].Path.Value, ""))
-	require.Equal(t, "/.well-known/openid-configuration/mcp", ptr.Deref(oauthRules[5].Matches[0].Path.Value, ""))
+	require.Equal(t, "oauth-protected-resource-metadata", string(ptr.Deref(oauthRules[0].Name, "")))
+	require.Equal(t, "oauth-authorization-server-metadata", string(ptr.Deref(oauthRules[1].Name, "")))
+	require.Equal(t, "oauth-authorization-server-metadata-oidc", string(ptr.Deref(oauthRules[2].Name, "")))
+	require.Equal(t, "/.well-known/oauth-protected-resource/mcp", ptr.Deref(oauthRules[0].Matches[0].Path.Value, ""))
+	require.Equal(t, "/.well-known/oauth-authorization-server/mcp", ptr.Deref(oauthRules[1].Matches[0].Path.Value, ""))
+	require.Equal(t, "/.well-known/openid-configuration/mcp", ptr.Deref(oauthRules[2].Matches[0].Path.Value, ""))
 }
 
 func TestMCPRouteController_updateMCPRouteStatus(t *testing.T) {