fix: prefix auth routes with issuer_url base path

When an MCP server is deployed behind a gateway with a custom base
path (e.g., /custom/path), the OAuth auth routes (.well-known,
/authorize, /token, /register, /revoke) were hardcoded at root,
making them unreachable through the gateway.

Extract the path component from issuer_url and prefix it to all
auth route registrations. This matches the metadata URLs already
built by build_metadata(), which correctly use issuer_url + path.
Backward compatible: when issuer_url has no path, routes stay at root.

Github-Issue: #1335
Reported-by: whitewg77

Author: enjoykumawat

src/mcp/server/auth/routes.py

@@ -94,29 +94,34 @@ def create_auth_routes(
     client_authenticator = ClientAuthenticator(provider)
     token_handler = TokenHandler(provider, client_authenticator, identity_assertion_enabled=identity_assertion_enabled)
 
+    # Extract the base path from the issuer URL so that auth routes are
+    # registered under the same prefix. This is necessary when the server
+    # sits behind a gateway with a custom base path (e.g., /custom/path).
+    issuer_path = urlparse(str(issuer_url)).path.rstrip("/")
+
     # Create routes
     # Allow CORS requests for endpoints meant to be hit by the OAuth client
     # (with the client secret). This is intended to support things like MCP Inspector,
     # where the client runs in a web browser. CORS is the outermost wrapper so that
     # responses produced by inner layers (such as a 413) still carry CORS headers.
     routes = [
         Route(
-            "/.well-known/oauth-authorization-server",
+            issuer_path + "/.well-known/oauth-authorization-server",
             endpoint=cors_middleware(
                 MetadataHandler(metadata).handle,
                 ["GET", "OPTIONS"],
             ),
             methods=["GET", "OPTIONS"],
         ),
         Route(
-            AUTHORIZATION_PATH,
+            issuer_path + AUTHORIZATION_PATH,
             # do not allow CORS for authorization endpoint;
             # clients should just redirect to this
             endpoint=_body_limited(request_response(AuthorizationHandler(provider).handle)),
             methods=["GET", "POST"],
         ),
         Route(
-            TOKEN_PATH,
+            issuer_path + TOKEN_PATH,
             endpoint=_cors(_body_limited(request_response(token_handler.handle)), ["POST", "OPTIONS"]),
             methods=["POST", "OPTIONS"],
         ),
@@ -129,7 +134,7 @@ def create_auth_routes(
         )
         routes.append(
             Route(
-                REGISTRATION_PATH,
+                issuer_path + REGISTRATION_PATH,
                 endpoint=_cors(_body_limited(request_response(registration_handler.handle)), ["POST", "OPTIONS"]),
                 methods=["POST", "OPTIONS"],
             )
@@ -139,7 +144,7 @@ def create_auth_routes(
         revocation_handler = RevocationHandler(provider, client_authenticator)
         routes.append(
             Route(
-                REVOCATION_PATH,
+                issuer_path + REVOCATION_PATH,
                 endpoint=_cors(_body_limited(request_response(revocation_handler.handle)), ["POST", "OPTIONS"]),
                 methods=["POST", "OPTIONS"],
             )

tests/server/auth/test_routes.py

@@ -1,8 +1,9 @@
 import pytest
 from pydantic import AnyHttpUrl
 
-from mcp.server.auth.routes import build_metadata, validate_issuer_url
+from mcp.server.auth.routes import build_metadata, create_auth_routes, validate_issuer_url
 from mcp.server.auth.settings import AuthSettings, ClientRegistrationOptions, RevocationOptions
+from tests.server.mcpserver.auth.test_auth_integration import MockOAuthProvider
 
 
 def test_validate_issuer_url_https_allowed():
@@ -70,3 +71,52 @@ def test_build_metadata_serves_issuer_without_trailing_slash():
     assert served["issuer"] == "https://as.example.com"
     assert served["authorization_endpoint"] == "https://as.example.com/authorize"
     assert served["token_endpoint"] == "https://as.example.com/token"
+
+
+def test_create_auth_routes_default_paths():
+    """Auth routes are registered at root when issuer_url has no path."""
+    provider = MockOAuthProvider()
+    routes = create_auth_routes(
+        provider,
+        issuer_url=AnyHttpUrl("https://example.com"),
+        client_registration_options=ClientRegistrationOptions(enabled=True),
+        revocation_options=RevocationOptions(enabled=True),
+    )
+    paths = [route.path for route in routes]
+    assert "/.well-known/oauth-authorization-server" in paths
+    assert "/authorize" in paths
+    assert "/token" in paths
+    assert "/register" in paths
+    assert "/revoke" in paths
+
+
+def test_create_auth_routes_custom_base_path():
+    """Auth routes are prefixed with the issuer_url path for gateway deployments."""
+    provider = MockOAuthProvider()
+    routes = create_auth_routes(
+        provider,
+        issuer_url=AnyHttpUrl("https://example.com/custom/path"),
+        client_registration_options=ClientRegistrationOptions(enabled=True),
+        revocation_options=RevocationOptions(enabled=True),
+    )
+    paths = [route.path for route in routes]
+    assert "/custom/path/.well-known/oauth-authorization-server" in paths
+    assert "/custom/path/authorize" in paths
+    assert "/custom/path/token" in paths
+    assert "/custom/path/register" in paths
+    assert "/custom/path/revoke" in paths
+
+
+def test_create_auth_routes_trailing_slash_stripped():
+    """Trailing slash on issuer_url path is stripped to avoid double slashes."""
+    provider = MockOAuthProvider()
+    routes = create_auth_routes(
+        provider,
+        issuer_url=AnyHttpUrl("https://example.com/base/"),
+        client_registration_options=ClientRegistrationOptions(enabled=True),
+        revocation_options=RevocationOptions(enabled=True),
+    )
+    paths = [route.path for route in routes]
+    assert "/base/.well-known/oauth-authorization-server" in paths
+    assert "/base/authorize" in paths
+    assert "/base/token" in paths