Refactor authentication middleware and routes

- Updated RequireAuthMiddleware to accept an optional resource_metadata_url parameter for enhanced error handling.
- Adjusted create_auth_routes to include resource_server_url and resource_name parameters.
- Modified OAuthProtectedResourceMetadata to change resource_documentation type to AnyHttpUrl.
- Updated tests to reflect changes in resource_server_url and resource_name parameters.

Signed-off-by: Xin Fu <xfu83@bloomberg.net>

Author: imfing

src/mcp/client/session_group.py

@@ -154,7 +154,6 @@ async def __aexit__(
             for exit_stack in self._session_exit_stacks.values():
                 tg.start_soon(exit_stack.aclose)
 
-
     @property
     def sessions(self) -> list[mcp.ClientSession]:
         """Returns the list of sessions being managed."""

src/mcp/server/auth/middleware/bearer_auth.py

@@ -67,25 +67,36 @@ class RequireAuthMiddleware:
     auth info in the request state.
     """
 
-    def __init__(self, app: Any, required_scopes: list[str]):
+    def __init__(
+        self,
+        app: Any,
+        required_scopes: list[str] | None = None,
+        resource_metadata_url: str | None = None,
+    ):
         """
         Initialize the middleware.
 
         Args:
             app: ASGI application
-            provider: Authentication provider to validate tokens
             required_scopes: Optional list of scopes that the token must have
+            resource_metadata_url: Optional resource metadata URL
         """
         self.app = app
         self.required_scopes = required_scopes
+        self.resource_metadata_url = resource_metadata_url
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         auth_user = scope.get("user")
         if not isinstance(auth_user, AuthenticatedUser):
-            raise HTTPException(status_code=401, detail="Unauthorized")
+            headers = (
+                {"WWW-Authenticate": f'Bearer resource="{self.resource_metadata_url}"'}
+                if self.resource_metadata_url
+                else None
+            )
+            raise HTTPException(status_code=401, detail="Unauthorized", headers=headers)
         auth_credentials = scope.get("auth")
 
-        for required_scope in self.required_scopes:
+        for required_scope in self.required_scopes or []:
             # auth_credentials should always be provided; this is just paranoia
             if (
                 auth_credentials is None

src/mcp/server/auth/routes.py

@@ -92,7 +92,7 @@ def create_auth_routes(
         authorization_servers=[metadata.issuer],
         scopes_supported=metadata.scopes_supported,
         resource_name=resource_name,
-        resource_documentation= service_documentation_url,
+        resource_documentation=service_documentation_url,
     )
 
     # Create routes

src/mcp/server/fastmcp/server.py

@@ -715,9 +715,11 @@ async def handle_sse(scope: Scope, receive: Receive, send: Send):
                 create_auth_routes(
                     provider=self._auth_server_provider,
                     issuer_url=self.settings.auth.issuer_url,
+                    resource_server_url=self.settings.auth.resource_server_url,
                     service_documentation_url=self.settings.auth.service_documentation_url,
                     client_registration_options=self.settings.auth.client_registration_options,
                     revocation_options=self.settings.auth.revocation_options,
+                    resource_name=self.settings.auth.resource_name,
                 )
             )
 

src/mcp/shared/auth.py

@@ -150,7 +150,7 @@ class OAuthProtectedResourceMetadata(BaseModel):
     bearer_methods_supported: list[str] | None = None
     resource_signing_alg_values_supported: list[str] | None = None
     resource_name: str | None = None
-    resource_documentation: str | None = None
+    resource_documentation: AnyHttpUrl | None = None
     resource_policy_uri: AnyHttpUrl | None = None
     resource_tos_uri: AnyHttpUrl | None = None
     tls_client_certificate_bound_access_tokens: bool | None = None

tests/server/auth/test_error_handling.py

@@ -40,6 +40,8 @@ def app(oauth_provider):
     auth_routes = create_auth_routes(
         oauth_provider,
         issuer_url=AnyHttpUrl("http://localhost"),
+        resource_server_url=AnyHttpUrl("http://localhost"),
+        resource_name="Test Resource",
         client_registration_options=client_registration_options,
         revocation_options=revocation_options,
     )