π The fast, Pythonic way to build MCP servers and clients.
Improve DescopeProvider scope discovery and well-known URL support (#4489)
Kevin J Gao3fdeedb5679c
diff --git a/docs/integrations/descope.mdx b/docs/integrations/descope.mdxindex bfb6cd9c8..33786b6e2 100644--- a/docs/integrations/descope.mdx+++ b/docs/integrations/descope.mdx@@ -23,11 +23,10 @@ Before you begin, you will need:### Step 1: Configure Descope<Steps>-<Step title="Create an MCP Server">- 1. Go to the [MCP Servers page](https://app.descope.com/mcp-servers) of the Descope Console, and create a new MCP Server.- 2. Give the MCP server a name and description.- 3. Ensure that **Dynamic Client Registration (DCR)** is enabled. Then click **Create**.- 4. Once you've created the MCP Server, note your Well-Known URL.+<Step title="Configure a Descope application">+ You can use either a resource-specific Descope MCP Server or a project-level inbound app.++ To create an MCP Server, go to the [MCP Servers page](https://app.descope.com/mcp-servers) of the Descope Console, create a server, and enable **Dynamic Client Registration (DCR)**.<Warning>@@ -35,10 +34,17 @@ Before you begin, you will need:</Warning></Step>-<Step title="Note Your Well-Known URL">- Save your Well-Known URL from [MCP Server Settings](https://app.descope.com/mcp-servers):+<Step title="Copy the Well-Known URL">+ `DescopeProvider` accepts both resource-specific MCP Server URLs:++ ```+ https://api.descope.com/v1/apps/agentic/P.../M.../.well-known/openid-configuration+ ```++ and project-level inbound app URLs:+```- Well-Known URL: https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration+ https://api.descope.com/v1/apps/P.../.well-known/openid-configuration```</Step></Steps>@@ -48,7 +54,7 @@ Before you begin, you will need:Create a `.env` file with your Descope configuration:```bash-DESCOPE_CONFIG_URL=https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration # Your Descope Well-Known URL+DESCOPE_CONFIG_URL=https://api.descope.com/v1/apps/P.../.well-known/openid-configurationSERVER_URL=http://localhost:3000 # Your server's base URL```@@ -60,18 +66,35 @@ Create your FastMCP server file and use the DescopeProvider to handle all the OAfrom fastmcp import FastMCPfrom fastmcp.server.auth.providers.descope import DescopeProvider-# The DescopeProvider automatically discovers Descope endpoints-# and configures JWT token validation+# DescopeProvider accepts either supported Well-Known URL format.auth_provider = DescopeProvider(- config_url="https://.../.well-known/openid-configuration", # Your MCP Server .well-known URL- base_url=SERVER_URL, # Your server's public URL+ config_url="https://api.descope.com/v1/apps/P.../.well-known/openid-configuration",+ base_url="https://your-fastmcp-server.com",)# Create FastMCP server with authmcp = FastMCP(name="My Descope Protected Server", auth=auth_provider)+```++### Scope discovery and validation+When both `scopes_supported` and `required_scopes` are omitted, `DescopeProvider` discovers `scopes_supported` lazily from the OpenID configuration and advertises them to MCP clients. Provider construction remains network-free, and a transient discovery failure is retried on a later metadata request.++Set both options when clients should request a broader set of scopes than the server requires on every token:++```python+from fastmcp.server.auth.providers.descope import DescopeProvider++auth_provider = DescopeProvider(+ config_url="https://api.descope.com/v1/apps/P.../.well-known/openid-configuration",+ base_url="https://your-fastmcp-server.com",+ scopes_supported=["mcp:read", "mcp:write"],+ required_scopes=["mcp:read"],+)```+`scopes_supported` controls what the protected resource metadata advertises. `required_scopes` controls what the JWT verifier requires during token validation. When only `required_scopes` is set, those scopes are also advertised to clients.+## TestingTo test your server, you can use the `fastmcp` CLI to run it locally. Assuming you've saved the above code to `server.py` (after replacing the environment variables with your actual values!), you can run the following command:diff --git a/fastmcp_slim/fastmcp/server/auth/providers/descope.py b/fastmcp_slim/fastmcp/server/auth/providers/descope.pyindex 3741aeefe..aa1255ad1 100644--- a/fastmcp_slim/fastmcp/server/auth/providers/descope.py+++ b/fastmcp_slim/fastmcp/server/auth/providers/descope.py@@ -7,11 +7,16 @@ for seamless MCP client authentication.from __future__ import annotations+import asynciofrom urllib.parse import urlparseimport httpx2+from mcp.server.auth.json_response import PydanticJSONResponse+from mcp.server.auth.routes import build_resource_metadata_url, cors_middleware+from mcp.shared.auth import ProtectedResourceMetadatafrom pydantic import AnyHttpUrl-from starlette.responses import JSONResponse+from starlette.requests import Request+from starlette.responses import JSONResponse, Responsefrom starlette.routing import Routefrom fastmcp.server.auth import RemoteAuthProvider, TokenVerifier@@ -21,43 +26,87 @@ from fastmcp.utilities.logging import get_loggerlogger = get_logger(__name__)+_OPENID_WK = "/.well-known/openid-configuration"+_OAUTH_WK = "/.well-known/oauth-authorization-server"-class DescopeProvider(RemoteAuthProvider):- """Descope metadata provider for DCR (Dynamic Client Registration).- This provider implements Descope integration using metadata forwarding.- This is the recommended approach for Descope DCR- as it allows Descope to handle the OAuth flow directly while FastMCP acts- as a resource server.+def _parse_descope_config_url(config_url: str) -> tuple[str, str, str, str]:+ openid_url = config_url.rstrip("/")+ if not openid_url.endswith(_OPENID_WK):+ openid_url = f"{openid_url}{_OPENID_WK}"++ issuer_url = openid_url[: -len(_OPENID_WK)]+ parsed = urlparse(issuer_url)+ parts = parsed.path.strip("/").split("/")+ descope_base_url = f"{parsed.scheme}://{parsed.netloc}".rstrip("/")++ if "agentic" in parts:+ index = parts.index("agentic") + 1+ project_id = parts[index] if index < len(parts) else ""+ elif "apps" in parts:+ index = parts.index("apps") + 1+ project_id = parts[index] if index < len(parts) else ""+ if project_id == "agentic":+ project_id = ""+ else:+ project_id = ""- IMPORTANT SETUP REQUIREMENTS:+ if not project_id:+ raise ValueError(f"Could not extract project_id from config_url: {issuer_url}")- 1. Create an MCP Server in Descope Console:- - Go to the [MCP Servers page](https://app.descope.com/mcp-servers) of the Descope Console- - Create a new MCP Server- - Ensure that **Dynamic Client Registration (DCR)** is enabled- - Note your Well-Known URL+ return descope_base_url, project_id, issuer_url, openid_url- 2. Note your Well-Known URL:- - Save your Well-Known URL from [MCP Server Settings](https://app.descope.com/mcp-servers)- - Format: ``https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration``- For detailed setup instructions, see:- https://docs.descope.com/identity-federation/inbound-apps/creating-inbound-apps#method-2-dynamic-client-registration-dcr+async def _discover_scopes(openid_configuration_url: str) -> list[str] | None:+ try:+ async with httpx2.AsyncClient() as client:+ response = await client.get(openid_configuration_url, timeout=10.0)+ response.raise_for_status()+ scopes = response.json().get("scopes_supported")+ if isinstance(scopes, list):+ parsed = [scope for scope in scopes if isinstance(scope, str)]+ if not scopes or parsed:+ return parsed+ except Exception:+ logger.warning(+ "Failed to fetch Descope OpenID configuration from %s",+ openid_configuration_url,+ exc_info=True,+ )+ return None+++class DescopeProvider(RemoteAuthProvider):+ """Descope metadata provider for Dynamic Client Registration (DCR).++ The provider accepts either a resource-specific Descope MCP Server URL such+ as `/v1/apps/agentic/P.../M.../.well-known/openid-configuration` or a+ project-level inbound app URL such as+ `/v1/apps/P.../.well-known/openid-configuration`.++ When neither `scopes_supported` nor `required_scopes` is provided, advertised+ scopes are discovered lazily from the OpenID configuration. Use+ `scopes_supported` and `required_scopes` together when the scopes clients+ should request differ from the scopes enforced during token validation.Example:```python+ from fastmcp import FastMCPfrom fastmcp.server.auth.providers.descope import DescopeProvider- # Create Descope metadata provider (JWT verifier created automatically)- descope_auth = DescopeProvider(- config_url="https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration",+ auth = DescopeProvider(+ config_url=(+ "https://api.descope.com/v1/apps/P.../"+ ".well-known/openid-configuration"+ ),base_url="https://your-fastmcp-server.com",)- # Use with FastMCP- mcp = FastMCP("My App", auth=descope_auth)+ mcp = FastMCP("My App", auth=auth)```++ See [Descope's inbound app documentation](https://docs.descope.com/identity-federation/inbound-apps/creating-inbound-apps#method-2-dynamic-client-registration-dcr)+ for DCR setup instructions."""def __init__(@@ -73,121 +122,182 @@ class DescopeProvider(RemoteAuthProvider):resource_documentation: AnyHttpUrl | None = None,token_verifier: TokenVerifier | None = None,):- """Initialize Descope metadata provider.+ """Initialize the Descope provider.Args:- base_url: Public URL of this FastMCP server- config_url: Your Descope Well-Known URL (e.g., "https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration")- This is the new recommended way. If provided, project_id and descope_base_url are ignored.- project_id: Your Descope Project ID (e.g., "P2abc123"). Used with descope_base_url for backwards compatibility.- descope_base_url: Your Descope base URL (e.g., "https://api.descope.com"). Used with project_id for backwards compatibility.- required_scopes: Optional list of scopes that must be present in validated tokens.- These scopes will be included in the protected resource metadata.- scopes_supported: Optional list of scopes to advertise in OAuth metadata.- If None, uses required_scopes. Use this when the scopes clients should- request differ from the scopes enforced on tokens.- resource_name: Optional name for the protected resource metadata.- resource_documentation: Optional documentation URL for the protected resource.- token_verifier: Optional token verifier. If None, creates JWT verifier for Descope+ base_url: Public URL of this FastMCP server.+ config_url: A resource-specific or project-level Descope OpenID+ configuration URL. When provided, `project_id` and+ `descope_base_url` are ignored.+ project_id: Descope project ID. Used with `descope_base_url` for+ backwards compatibility.+ descope_base_url: Descope API base URL. Used with `project_id` for+ backwards compatibility.+ required_scopes: Scopes required during token validation. When+ `scopes_supported` is omitted, these are also advertised to clients.+ scopes_supported: Scopes advertised to OAuth clients. When both this+ and `required_scopes` are omitted, scopes are discovered lazily+ from `config_url`.+ resource_name: Optional protected resource name.+ resource_documentation: Optional protected resource documentation URL.+ token_verifier: Optional custom token verifier. A Descope JWT verifier+ is created when omitted."""self.base_url = AnyHttpUrl(str(base_url).rstrip("/"))- # Parse scopes if provided as string- parsed_scopes = (+ parsed_required_scopes = (parse_scopes(required_scopes) if required_scopes is not None else None)+ parsed_scopes_supported = (+ parse_scopes(scopes_supported) if scopes_supported is not None else None+ )- # Determine which API is being usedif config_url is not None:- # New API: use config_url- # Strip /.well-known/openid-configuration from config_url if present- issuer_url = str(config_url)- if issuer_url.endswith("/.well-known/openid-configuration"):- issuer_url = issuer_url[: -len("/.well-known/openid-configuration")]-- # Parse the issuer URL to extract descope_base_url and project_id for other uses- parsed_url = urlparse(issuer_url)- path_parts = parsed_url.path.strip("/").split("/")-- # Extract project_id from path (format: /v1/apps/agentic/P.../M...)- if "agentic" in path_parts:- agentic_index = path_parts.index("agentic")- if agentic_index + 1 < len(path_parts):- self.project_id = path_parts[agentic_index + 1]- else:- raise ValueError(- f"Could not extract project_id from config_url: {issuer_url}"- )- else:- raise ValueError(- f"Could not find 'agentic' in config_url path: {issuer_url}"- )-- # Extract descope_base_url (scheme + netloc)- self.descope_base_url = f"{parsed_url.scheme}://{parsed_url.netloc}".rstrip(- "/"- )+ (+ self.descope_base_url,+ self.project_id,+ issuer_url,+ self.openid_configuration_url,+ ) = _parse_descope_config_url(str(config_url))elif project_id is not None and descope_base_url is not None:- # Old API: use project_id and descope_base_urlself.project_id = project_iddescope_base_url_str = str(descope_base_url).rstrip("/")- # Ensure descope_base_url has a schemeif not descope_base_url_str.startswith(("http://", "https://")):descope_base_url_str = f"https://{descope_base_url_str}"self.descope_base_url = descope_base_url_str- # Old issuer formatissuer_url = f"{self.descope_base_url}/v1/apps/{self.project_id}"+ self.openid_configuration_url = f"{issuer_url}{_OPENID_WK}"else:raise ValueError("Either config_url (new API) or both project_id and descope_base_url (old API) must be provided")- # Create default JWT verifier if none provided+ self.oauth_authorization_server_metadata_url = (+ self.openid_configuration_url.replace(_OPENID_WK, _OAUTH_WK)+ )++ # Advertised scopes are discovered from Descope's OpenID configuration+ # only when the caller supplied neither explicit advertised scopes nor+ # required scopes. Discovery is deferred to the first protected resource+ # metadata request (see get_routes) so construction never performs I/O+ # and a transient failure can be retried instead of being frozen for the+ # provider's lifetime.+ custom_verifier_scopes = (+ token_verifier.scopes_supported if token_verifier is not None else []+ )+ self._scopes_discovery_enabled = (+ parsed_scopes_supported is None+ and parsed_required_scopes is None+ and not custom_verifier_scopes+ )+ self._discovered_scopes: list[str] | None = None+ self._scopes_discovered = False+ self._scopes_discovery_lock = asyncio.Lock()+if token_verifier is None:token_verifier = JWTVerifier(jwks_uri=f"{self.descope_base_url}/{self.project_id}/.well-known/jwks.json",issuer=issuer_url,algorithm="RS256",audience=self.project_id,- required_scopes=parsed_scopes,+ required_scopes=parsed_required_scopes,)- # Initialize RemoteAuthProvider with Descope as the authorization serversuper().__init__(token_verifier=token_verifier,authorization_servers=[AnyHttpUrl(issuer_url)],base_url=self.base_url,- scopes_supported=scopes_supported,+ scopes_supported=parsed_scopes_supported,resource_name=resource_name,resource_documentation=resource_documentation,)+ async def _get_scopes_supported(self) -> list[str] | None:+ """Return the advertised scopes, discovering them lazily if enabled.++ The result of a successful discovery is cached for the provider's+ lifetime. Transient failures return ``None`` without caching, so the+ next protected resource metadata request retries discovery.+ """+ if self._scopes_discovered:+ return self._discovered_scopes++ async with self._scopes_discovery_lock:+ if self._scopes_discovered:+ return self._discovered_scopes++ scopes = await _discover_scopes(self.openid_configuration_url)+ if scopes is not None:+ self._discovered_scopes = scopes+ self._scopes_discovered = True+ return scopes++ def _create_protected_resource_route(self, resource_url: AnyHttpUrl) -> Route:+ """Build a protected resource metadata route that discovers scopes lazily.++ Mirrors ``create_protected_resource_routes`` (RFC 9728) but resolves+ ``scopes_supported`` per request so the value can be discovered from+ Descope after construction.+ """++ async def protected_resource_metadata(request: Request) -> Response:+ scopes_supported = await self._get_scopes_supported()+ metadata = ProtectedResourceMetadata(+ resource=resource_url,+ authorization_servers=self.authorization_servers,+ scopes_supported=scopes_supported,+ resource_name=self.resource_name,+ resource_documentation=self.resource_documentation,+ )+ cache_control = (+ "public, max-age=3600" if self._scopes_discovered else "no-store"+ )+ return PydanticJSONResponse(+ content=metadata,+ headers={"Cache-Control": cache_control},+ )++ well_known_path = urlparse(str(build_resource_metadata_url(resource_url))).path+ return Route(+ well_known_path,+ endpoint=cors_middleware(protected_resource_metadata, ["GET", "OPTIONS"]),+ methods=["GET", "OPTIONS"],+ )+def get_routes(self,mcp_path: str | None = None,) -> list[Route]:- """Get OAuth routes including Descope authorization server metadata forwarding.-- This returns the standard protected resource routes plus an authorization server- metadata endpoint that forwards Descope's OAuth metadata to clients.-- Args:- mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")- This is used to advertise the resource URL in metadata.- """- # Get the standard protected resource routes from RemoteAuthProvider- routes = super().get_routes(mcp_path)+ if self._scopes_discovery_enabled:+ # Serve protected resource metadata from an async handler that+ # discovers scopes_supported lazily. The parent's static route would+ # freeze the (as-yet-unknown) scopes at startup.+ self.set_mcp_path(mcp_path)+ routes = []+ resource_url = self._get_resource_url(mcp_path)+ if resource_url:+ routes.append(self._create_protected_resource_route(resource_url))+ else:+ # Advertised scopes are already known; the parent builds the static+ # protected resource metadata route with no network access.+ routes = super().get_routes(mcp_path)async def oauth_authorization_server_metadata(request):- """Forward Descope OAuth authorization server metadata with FastMCP customizations."""+ metadata_urls = [self.oauth_authorization_server_metadata_url]+ project_metadata_url = (+ f"{self.descope_base_url}/v1/apps/{self.project_id}{_OAUTH_WK}"+ )+ if project_metadata_url != self.oauth_authorization_server_metadata_url:+ metadata_urls.append(project_metadata_url)try:async with httpx2.AsyncClient() as client:- response = await client.get(- f"{self.descope_base_url}/v1/apps/{self.project_id}/.well-known/oauth-authorization-server"- )- response.raise_for_status()- metadata = response.json()- return JSONResponse(metadata)+ for metadata_url in metadata_urls:+ try:+ response = await client.get(metadata_url)+ response.raise_for_status()+ return JSONResponse(response.json())+ except Exception:+ continueexcept Exception as e:return JSONResponse({@@ -197,7 +307,14 @@ class DescopeProvider(RemoteAuthProvider):status_code=500,)- # Add Descope authorization server metadata forwarding+ return JSONResponse(+ {+ "error": "server_error",+ "error_description": "Failed to fetch Descope metadata",+ },+ status_code=500,+ )+routes.append(Route("/.well-known/oauth-authorization-server",diff --git a/tests/server/auth/providers/test_descope.py b/tests/server/auth/providers/test_descope.pyindex cbf4607f2..b35b2dd00 100644--- a/tests/server/auth/providers/test_descope.py+++ b/tests/server/auth/providers/test_descope.py@@ -1,10 +1,12 @@"""Tests for Descope OAuth provider."""import os-from unittest.mock import patch+from unittest.mock import AsyncMock, patch+import httpx2import pytestfrom mcp import MCPError+from starlette.requests import Requestfrom fastmcp import Client, FastMCPfrom fastmcp.client.transports import StreamableHttpTransport@@ -12,6 +14,12 @@ from fastmcp.server.auth.providers.descope import DescopeProviderfrom fastmcp.server.auth.providers.jwt import JWTVerifierfrom fastmcp.utilities.tests import HeadlessOAuth, run_server_async+PROJECT_LEVEL_OPENID_CONFIGURATION = {+ "issuer": "https://api.descope.com/v1/apps/P2v9EBlmO4XTrOwMRfsY1jeUONxU",+ "scopes_supported": ["mcp:read"],+ "jwks_uri": "https://api.descope.com/P2v9EBlmO4XTrOwMRfsY1jeUONxU/.well-known/jwks.json",+}+class TestDescopeProvider:"""Test Descope OAuth provider functionality."""@@ -66,6 +74,229 @@ class TestDescopeProvider:assert str(provider3.descope_base_url) == "https://api.descope.com"assert provider3.project_id == "P2abc123"+ def test_project_level_config_url_parsing(self):+ """Test project-level well-known URLs without the agentic path segment."""+ provider = DescopeProvider(+ config_url="https://api.descope.com/v1/apps/P2v9EBlmO4XTrOwMRfsY1jeUONxU/.well-known/openid-configuration",+ base_url="https://myserver.com",+ )++ assert provider.project_id == "P2v9EBlmO4XTrOwMRfsY1jeUONxU"+ assert str(provider.descope_base_url) == "https://api.descope.com"+ assert isinstance(provider.token_verifier, JWTVerifier)+ assert (+ provider.token_verifier.issuer+ == "https://api.descope.com/v1/apps/P2v9EBlmO4XTrOwMRfsY1jeUONxU"+ )+ assert provider.openid_configuration_url == (+ "https://api.descope.com/v1/apps/P2v9EBlmO4XTrOwMRfsY1jeUONxU/.well-known/openid-configuration"+ )+ assert provider.oauth_authorization_server_metadata_url == (+ "https://api.descope.com/v1/apps/P2v9EBlmO4XTrOwMRfsY1jeUONxU/.well-known/oauth-authorization-server"+ )++ def test_construction_is_network_free(self):+ """Construction must not perform discovery I/O, even when it is enabled."""+ config_url = "https://api.descope.com/v1/apps/P2v9EBlmO4XTrOwMRfsY1jeUONxU/.well-known/openid-configuration"++ no_network = AsyncMock(side_effect=AssertionError("no network during init"))+ with patch("httpx2.AsyncClient.get", new=no_network):+ provider = DescopeProvider(+ config_url=config_url,+ base_url="https://myserver.com",+ )++ # Discovery is enabled but deferred; nothing has been fetched yet.+ assert provider._scopes_discovery_enabled is True+ assert provider._scopes_supported is None+ assert provider._discovered_scopes is None+ assert provider._scopes_discovered is False+ assert provider.token_verifier.required_scopes == []++ async def test_discover_scopes_supported_lazily(self):+ """scopes_supported are discovered lazily and cached after first fetch."""+ config_url = "https://api.descope.com/v1/apps/P2v9EBlmO4XTrOwMRfsY1jeUONxU/.well-known/openid-configuration"+ provider = DescopeProvider(+ config_url=config_url,+ base_url="https://myserver.com",+ )++ mock_response = httpx2.Response(+ 200,+ json=PROJECT_LEVEL_OPENID_CONFIGURATION,+ request=httpx2.Request("GET", config_url),+ )++ with patch(+ "httpx2.AsyncClient.get", new=AsyncMock(return_value=mock_response)+ ) as mock_get:+ scopes = await provider._get_scopes_supported()+ # A second call returns the cached result without another fetch.+ scopes_again = await provider._get_scopes_supported()++ assert scopes == ["mcp:read"]+ assert scopes_again == ["mcp:read"]+ assert provider._discovered_scopes == ["mcp:read"]+ assert provider._scopes_discovered is True+ mock_get.assert_awaited_once()++ async def test_scope_discovery_retries_after_transient_failure(self):+ """A transient discovery failure is not cached and is retried."""+ config_url = "https://api.descope.com/v1/apps/P2v9EBlmO4XTrOwMRfsY1jeUONxU/.well-known/openid-configuration"+ provider = DescopeProvider(+ config_url=config_url,+ base_url="https://myserver.com",+ )++ failing = AsyncMock(side_effect=httpx2.ConnectError("boom"))+ with patch("httpx2.AsyncClient.get", new=failing):+ first = await provider._get_scopes_supported()++ # Failure yields no scopes and is not frozen for the provider's lifetime.+ assert first is None+ assert provider._scopes_discovered is False+ assert provider._discovered_scopes is None++ mock_response = httpx2.Response(+ 200,+ json=PROJECT_LEVEL_OPENID_CONFIGURATION,+ request=httpx2.Request("GET", config_url),+ )+ with patch("httpx2.AsyncClient.get", new=AsyncMock(return_value=mock_response)):+ second = await provider._get_scopes_supported()++ assert second == ["mcp:read"]+ assert provider._scopes_discovered is True++ async def test_empty_scope_discovery_is_cached_as_success(self):+ """An explicitly empty Descope scope list is a successful discovery."""+ config_url = (+ "https://api.descope.com/v1/apps/P2abc123/.well-known/openid-configuration"+ )+ provider = DescopeProvider(+ config_url=config_url,+ base_url="https://myserver.com",+ )+ mock_response = httpx2.Response(+ 200,+ json={"scopes_supported": []},+ request=httpx2.Request("GET", config_url),+ )++ with patch(+ "httpx2.AsyncClient.get", new=AsyncMock(return_value=mock_response)+ ) as mock_get:+ first = await provider._get_scopes_supported()+ second = await provider._get_scopes_supported()++ assert first == []+ assert second == []+ assert provider._scopes_discovered is True+ assert provider._discovered_scopes == []+ mock_get.assert_awaited_once()++ def test_get_routes_is_network_free(self):+ """get_routes must not perform discovery I/O when building routes."""+ config_url = "https://api.descope.com/v1/apps/P2v9EBlmO4XTrOwMRfsY1jeUONxU/.well-known/openid-configuration"+ provider = DescopeProvider(+ config_url=config_url,+ base_url="https://myserver.com",+ )++ no_network = AsyncMock(side_effect=AssertionError("no network at get_routes"))+ with patch("httpx2.AsyncClient.get", new=no_network):+ routes = provider.get_routes("/mcp")++ paths = [route.path for route in routes]+ assert any("oauth-protected-resource" in path for path in paths)+ assert any("oauth-authorization-server" in path for path in paths)++ async def test_project_level_metadata_failure_is_not_retried(self):+ """Identical project-level primary and fallback URLs are fetched once."""+ provider = DescopeProvider(+ config_url="https://api.descope.com/v1/apps/P2abc123/.well-known/openid-configuration",+ base_url="https://myserver.com",+ )+ metadata_route = next(+ route+ for route in provider.get_routes("/mcp")+ if route.path == "/.well-known/oauth-authorization-server"+ )+ request = Request(+ {+ "type": "http",+ "method": "GET",+ "path": metadata_route.path,+ "headers": [],+ }+ )++ failing = AsyncMock(side_effect=httpx2.ConnectError("boom"))+ with patch("httpx2.AsyncClient.get", new=failing):+ response = await metadata_route.endpoint(request)++ assert response.status_code == 500+ failing.assert_awaited_once_with(+ provider.oauth_authorization_server_metadata_url+ )++ def test_scopes_supported_and_required_scopes_can_differ(self):+ """Test that scopes_supported and required_scopes can be configured independently."""+ provider = DescopeProvider(+ config_url="https://api.descope.com/v1/apps/agentic/P2abc123/M123/.well-known/openid-configuration",+ base_url="https://myserver.com",+ scopes_supported=["mcp:read", "mcp:write"],+ required_scopes=["mcp:read"],+ )++ assert provider._scopes_supported == ["mcp:read", "mcp:write"]+ assert provider.token_verifier.required_scopes == ["mcp:read"]++ def test_explicit_required_scopes_skip_discovery(self):+ """Test that explicit required_scopes disable well-known discovery."""+ config_url = "https://api.descope.com/v1/apps/P2v9EBlmO4XTrOwMRfsY1jeUONxU/.well-known/openid-configuration"++ provider = DescopeProvider(+ config_url=config_url,+ base_url="https://myserver.com",+ required_scopes=["custom:scope"],+ )++ assert provider._scopes_discovery_enabled is False+ assert provider.token_verifier.required_scopes == ["custom:scope"]+ assert provider._scopes_supported is None++ def test_explicit_scopes_supported_skip_discovery(self):+ """Test that explicit scopes_supported disable well-known discovery."""+ config_url = "https://api.descope.com/v1/apps/P2v9EBlmO4XTrOwMRfsY1jeUONxU/.well-known/openid-configuration"++ provider = DescopeProvider(+ config_url=config_url,+ base_url="https://myserver.com",+ scopes_supported=["custom:advertised"],+ )++ assert provider._scopes_discovery_enabled is False+ assert provider._scopes_supported == ["custom:advertised"]+ assert provider.token_verifier.required_scopes == []++ def test_custom_token_verifier_scopes_skip_discovery(self):+ """Scopes supplied by a custom verifier retain the parent behavior."""+ token_verifier = JWTVerifier(+ public_key="secret",+ algorithm="HS256",+ required_scopes=["custom:scope"],+ )+ provider = DescopeProvider(+ config_url="https://api.descope.com/v1/apps/P2abc123/.well-known/openid-configuration",+ base_url="https://myserver.com",+ token_verifier=token_verifier,+ )++ assert provider._scopes_discovery_enabled is False+ assert provider._scopes_supported is None+ assert provider.token_verifier.scopes_supported == ["custom:scope"]+def test_requires_config_url_or_project_id_and_descope_base_url(self):"""Test that either config_url or both project_id and descope_base_url are required."""# Should raise error when neither API is provided@@ -221,6 +452,52 @@ def client_with_headless_oauth(mcp_server_url: str) -> Client:class TestDescopeProviderIntegration:+ async def test_protected_resource_metadata_serves_discovered_scopes(self):+ """The protected resource metadata endpoint advertises discovered scopes."""+ provider = DescopeProvider(+ config_url="https://api.descope.com/v1/apps/agentic/P2test123/M123/.well-known/openid-configuration",+ base_url="http://localhost:4321",+ )+ mcp = FastMCP(auth=provider)++ with patch(+ "fastmcp.server.auth.providers.descope._discover_scopes",+ new=AsyncMock(return_value=["mcp:read"]),+ ):+ async with run_server_async(mcp, transport="http") as url:+ metadata_url = url.replace(+ "/mcp", "/.well-known/oauth-protected-resource/mcp"+ )+ async with httpx2.AsyncClient() as client:+ response = await client.get(metadata_url)++ response.raise_for_status()+ assert response.json()["scopes_supported"] == ["mcp:read"]+ assert response.headers["cache-control"] == "public, max-age=3600"++ async def test_failed_scope_discovery_is_not_cached(self):+ """Clients can retry metadata discovery immediately after a failure."""+ provider = DescopeProvider(+ config_url="https://api.descope.com/v1/apps/agentic/P2test123/M123/.well-known/openid-configuration",+ base_url="http://localhost:4321",+ )+ mcp = FastMCP(auth=provider)++ with patch(+ "fastmcp.server.auth.providers.descope._discover_scopes",+ new=AsyncMock(return_value=None),+ ):+ async with run_server_async(mcp, transport="http") as url:+ metadata_url = url.replace(+ "/mcp", "/.well-known/oauth-protected-resource/mcp"+ )+ async with httpx2.AsyncClient() as client:+ response = await client.get(metadata_url)++ response.raise_for_status()+ assert "scopes_supported" not in response.json()+ assert response.headers["cache-control"] == "no-store"+async def test_unauthorized_access(self, mcp_server_url: str):# SDK v2 surfaces the server's 401 as a generic MCPError at the client# boundary rather than re-raising httpx2.HTTPStatusError.