fastmcp 2.12.3__py3-none-any.whl → 2.12.4__py3-none-any.whl

fastmcp/server/auth/providers/aws.py

@@ -0,0 +1,237 @@
+"""AWS Cognito OAuth provider for FastMCP.
+
+This module provides a complete AWS Cognito OAuth integration that's ready to use
+with a user pool ID, domain prefix, client ID and client secret. It handles all
+the complexity of AWS Cognito's OAuth flow, token validation, and user management.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.aws_cognito import AWSCognitoProvider
+
+    # Simple AWS Cognito OAuth protection
+    auth = AWSCognitoProvider(
+        user_pool_id="your-user-pool-id",
+        aws_region="eu-central-1",
+        client_id="your-cognito-client-id",
+        client_secret="your-cognito-client-secret"
+    )
+
+    mcp = FastMCP("My Protected Server", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+from pydantic import AnyHttpUrl, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oidc_proxy import OIDCProxy
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import NotSet, NotSetT
+
+logger = get_logger(__name__)
+
+
+class AWSCognitoProviderSettings(BaseSettings):
+    """Settings for AWS Cognito OAuth provider."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_SERVER_AUTH_AWS_COGNITO_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    user_pool_id: str | None = None
+    aws_region: str | None = None
+    client_id: str | None = None
+    client_secret: SecretStr | None = None
+    base_url: AnyHttpUrl | str | None = None
+    redirect_path: str | None = None
+    required_scopes: list[str] | None = None
+    allowed_client_redirect_uris: list[str] | None = None
+
+    @field_validator("required_scopes", mode="before")
+    @classmethod
+    def _parse_scopes(cls, v):
+        return parse_scopes(v)
+
+
+class AWSCognitoTokenVerifier(JWTVerifier):
+    """Token verifier that filters claims to Cognito-specific subset."""
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify token and filter claims to Cognito-specific subset."""
+        # Use base JWT verification
+        access_token = await super().verify_token(token)
+        if not access_token:
+            return None
+
+        # Filter claims to Cognito-specific subset
+        cognito_claims = {
+            "sub": access_token.claims.get("sub"),
+            "username": access_token.claims.get("username"),
+            "cognito:groups": access_token.claims.get("cognito:groups", []),
+        }
+
+        # Return new AccessToken with filtered claims
+        return AccessToken(
+            token=access_token.token,
+            client_id=access_token.client_id,
+            scopes=access_token.scopes,
+            expires_at=access_token.expires_at,
+            claims=cognito_claims,
+        )
+
+
+class AWSCognitoProvider(OIDCProxy):
+    """Complete AWS Cognito OAuth provider for FastMCP.
+
+    This provider makes it trivial to add AWS Cognito OAuth protection to any
+    FastMCP server using OIDC Discovery. Just provide your Cognito User Pool details,
+    client credentials, and a base URL, and you're ready to go.
+
+    Features:
+    - Automatic OIDC Discovery from AWS Cognito User Pool
+    - Automatic JWT token validation via Cognito's public keys
+    - Cognito-specific claim filtering (sub, username, cognito:groups)
+    - Support for Cognito User Pools
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.aws_cognito import AWSCognitoProvider
+
+        auth = AWSCognitoProvider(
+            user_pool_id="eu-central-1_XXXXXXXXX",
+            aws_region="eu-central-1",
+            client_id="your-cognito-client-id",
+            client_secret="your-cognito-client-secret",
+            base_url="https://my-server.com",
+            redirect_path="/custom/callback",
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        user_pool_id: str | NotSetT = NotSet,
+        aws_region: str | NotSetT = NotSet,
+        client_id: str | NotSetT = NotSet,
+        client_secret: str | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        redirect_path: str | NotSetT = NotSet,
+        required_scopes: list[str] | NotSetT = NotSet,
+        allowed_client_redirect_uris: list[str] | NotSetT = NotSet,
+    ):
+        """Initialize AWS Cognito OAuth provider.
+
+        Args:
+            user_pool_id: Your Cognito User Pool ID (e.g., "eu-central-1_XXXXXXXXX")
+            aws_region: AWS region where your User Pool is located (defaults to "eu-central-1")
+            client_id: Cognito app client ID
+            client_secret: Cognito app client secret
+            base_url: Public URL of your FastMCP server (for OAuth callbacks)
+            redirect_path: Redirect path configured in Cognito app (defaults to "/auth/callback")
+            required_scopes: Required Cognito scopes (defaults to ["openid"])
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+        """
+
+        settings = AWSCognitoProviderSettings.model_validate(
+            {
+                k: v
+                for k, v in {
+                    "user_pool_id": user_pool_id,
+                    "aws_region": aws_region,
+                    "client_id": client_id,
+                    "client_secret": client_secret,
+                    "base_url": base_url,
+                    "redirect_path": redirect_path,
+                    "required_scopes": required_scopes,
+                    "allowed_client_redirect_uris": allowed_client_redirect_uris,
+                }.items()
+                if v is not NotSet
+            }
+        )
+
+        # Validate required settings
+        if not settings.user_pool_id:
+            raise ValueError(
+                "user_pool_id is required - set via parameter or FASTMCP_SERVER_AUTH_AWS_COGNITO_USER_POOL_ID"
+            )
+        if not settings.client_id:
+            raise ValueError(
+                "client_id is required - set via parameter or FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_ID"
+            )
+        if not settings.client_secret:
+            raise ValueError(
+                "client_secret is required - set via parameter or FASTMCP_SERVER_AUTH_AWS_COGNITO_CLIENT_SECRET"
+            )
+
+        # Apply defaults
+        required_scopes_final = settings.required_scopes or ["openid"]
+        allowed_client_redirect_uris_final = settings.allowed_client_redirect_uris
+        aws_region_final = settings.aws_region or "eu-central-1"
+        redirect_path_final = settings.redirect_path or "/auth/callback"
+
+        # Construct OIDC discovery URL
+        config_url = f"https://cognito-idp.{aws_region_final}.amazonaws.com/{settings.user_pool_id}/.well-known/openid-configuration"
+
+        # Extract secret string from SecretStr
+        client_secret_str = (
+            settings.client_secret.get_secret_value() if settings.client_secret else ""
+        )
+
+        # Store Cognito-specific info for claim filtering
+        self.user_pool_id = settings.user_pool_id
+        self.aws_region = aws_region_final
+
+        # Initialize OIDC proxy with Cognito discovery
+        super().__init__(
+            config_url=config_url,
+            client_id=settings.client_id,
+            client_secret=client_secret_str,
+            algorithm="RS256",
+            required_scopes=required_scopes_final,
+            base_url=settings.base_url,
+            redirect_path=redirect_path_final,
+            allowed_client_redirect_uris=allowed_client_redirect_uris_final,
+        )
+
+        logger.info(
+            "Initialized AWS Cognito OAuth provider for client %s with scopes: %s",
+            settings.client_id,
+            required_scopes_final,
+        )
+
+    def get_token_verifier(
+        self,
+        *,
+        algorithm: str | None = None,
+        audience: str | None = None,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int | None = None,
+    ) -> TokenVerifier:
+        """Creates a Cognito-specific token verifier with claim filtering.
+
+        Args:
+            algorithm: Optional token verifier algorithm
+            audience: Optional token verifier audience
+            required_scopes: Optional token verifier required_scopes
+            timeout_seconds: HTTP request timeout in seconds
+        """
+        return AWSCognitoTokenVerifier(
+            issuer=str(self.oidc_config.issuer),
+            audience=audience,
+            algorithm=algorithm,
+            jwks_uri=str(self.oidc_config.jwks_uri),
+            required_scopes=required_scopes,
+        )

fastmcp/server/auth/providers/azure.py

@@ -14,6 +14,7 @@ from fastmcp.server.auth import AccessToken, TokenVerifier
 from fastmcp.server.auth.oauth_proxy import OAuthProxy
 from fastmcp.utilities.auth import parse_scopes
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.storage import KVStorage
 from fastmcp.utilities.types import NotSet, NotSetT
 
 logger = get_logger(__name__)
@@ -160,6 +161,7 @@ class AzureProvider(OAuthProxy):
         required_scopes: list[str] | None | NotSetT = NotSet,
         timeout_seconds: int | NotSetT = NotSet,
         allowed_client_redirect_uris: list[str] | NotSetT = NotSet,
+        client_storage: KVStorage | None = None,
     ):
         """Initialize Azure OAuth provider.
 
@@ -173,6 +175,8 @@ class AzureProvider(OAuthProxy):
             timeout_seconds: HTTP request timeout for Azure API calls
             allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
                 If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage implementation for OAuth client registrations.
+                Defaults to file-based storage if not specified.
         """
         settings = AzureProviderSettings.model_validate(
             {
@@ -211,7 +215,6 @@ class AzureProvider(OAuthProxy):
         # Apply defaults
         tenant_id_final = settings.tenant_id
 
-        redirect_path_final = settings.redirect_path or "/auth/callback"
         timeout_seconds_final = settings.timeout_seconds or 10
         # Default scopes for Azure - User.Read gives us access to user info via Graph API
         scopes_final = settings.required_scopes or [
@@ -249,9 +252,10 @@ class AzureProvider(OAuthProxy):
             upstream_client_secret=client_secret_str,
             token_verifier=token_verifier,
             base_url=settings.base_url,
-            redirect_path=redirect_path_final,
+            redirect_path=settings.redirect_path,
             issuer_url=settings.base_url,
             allowed_client_redirect_uris=allowed_client_redirect_uris_final,
+            client_storage=client_storage,
         )
 
         logger.info(

fastmcp/server/auth/providers/descope.py

@@ -0,0 +1,172 @@
+"""Descope authentication provider for FastMCP.
+
+This module provides DescopeProvider - a complete authentication solution that integrates
+with Descope's OAuth 2.1 and OpenID Connect services, supporting Dynamic Client Registration (DCR)
+for seamless MCP client authentication.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from pydantic import AnyHttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from fastmcp.server.auth import RemoteAuthProvider, TokenVerifier
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import NotSet, NotSetT
+
+logger = get_logger(__name__)
+
+
+class DescopeProviderSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_SERVER_AUTH_DESCOPEPROVIDER_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    project_id: str
+    base_url: AnyHttpUrl
+    descope_base_url: AnyHttpUrl = AnyHttpUrl("https://api.descope.com")
+
+
+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.
+
+    IMPORTANT SETUP REQUIREMENTS:
+
+    1. Enable Dynamic Client Registration in Descope Console:
+       - Go to the [Inbound Apps page](https://app.descope.com/apps/inbound) of the Descope Console
+       - Click **DCR Settings**
+       - Enable **Dynamic Client Registration (DCR)**
+       - Define allowed scopes
+
+    2. Note your Project ID:
+       - Save your Project ID from [Project Settings](https://app.descope.com/settings/project)
+       - Example: P2abc...123
+
+    For detailed setup instructions, see:
+    https://docs.descope.com/identity-federation/inbound-apps/creating-inbound-apps#method-2-dynamic-client-registration-dcr
+
+    Example:
+        ```python
+        from fastmcp.server.auth.providers.descope import DescopeProvider
+
+        # Create Descope metadata provider (JWT verifier created automatically)
+        descope_auth = DescopeProvider(
+            project_id="P2abc...123",
+            base_url="https://your-fastmcp-server.com",
+            descope_base_url="https://api.descope.com",
+        )
+
+        # Use with FastMCP
+        mcp = FastMCP("My App", auth=descope_auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        project_id: str | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        descope_base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        token_verifier: TokenVerifier | None = None,
+    ):
+        """Initialize Descope metadata provider.
+
+        Args:
+            project_id: Your Descope Project ID (e.g., "P2abc...123")
+            base_url: Public URL of this FastMCP server
+            descope_base_url: Descope API base URL (defaults to https://api.descope.com)
+            token_verifier: Optional token verifier. If None, creates JWT verifier for Descope
+        """
+        settings = DescopeProviderSettings.model_validate(
+            {
+                k: v
+                for k, v in {
+                    "project_id": project_id,
+                    "base_url": base_url,
+                    "descope_base_url": descope_base_url,
+                }.items()
+                if v is not NotSet
+            }
+        )
+
+        self.project_id = settings.project_id
+        self.base_url = str(settings.base_url).rstrip("/")
+        self.descope_base_url = str(settings.descope_base_url).rstrip("/")
+
+        # Create default JWT verifier if none provided
+        if token_verifier is None:
+            token_verifier = JWTVerifier(
+                jwks_uri=f"{self.descope_base_url}/{self.project_id}/.well-known/jwks.json",
+                issuer=f"{self.descope_base_url}/v1/apps/{self.project_id}",
+                algorithm="RS256",
+                audience=self.project_id,
+            )
+
+        # Initialize RemoteAuthProvider with Descope as the authorization server
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[
+                AnyHttpUrl(f"{self.descope_base_url}/v1/apps/{self.project_id}")
+            ],
+            base_url=self.base_url,
+        )
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+        mcp_endpoint: Any | 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")
+            mcp_endpoint: The MCP endpoint handler to protect with auth
+        """
+        # Get the standard protected resource routes from RemoteAuthProvider
+        routes = super().get_routes(mcp_path, mcp_endpoint)
+
+        async def oauth_authorization_server_metadata(request):
+            """Forward Descope OAuth authorization server metadata with FastMCP customizations."""
+            try:
+                async with httpx.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)
+            except Exception as e:
+                return JSONResponse(
+                    {
+                        "error": "server_error",
+                        "error_description": f"Failed to fetch Descope metadata: {e}",
+                    },
+                    status_code=500,
+                )
+
+        # Add Descope authorization server metadata forwarding
+        routes.append(
+            Route(
+                "/.well-known/oauth-authorization-server",
+                endpoint=oauth_authorization_server_metadata,
+                methods=["GET"],
+            )
+        )
+
+        return routes

fastmcp/server/auth/providers/github.py

@@ -30,6 +30,7 @@ from fastmcp.server.auth.auth import AccessToken
 from fastmcp.server.auth.oauth_proxy import OAuthProxy
 from fastmcp.utilities.auth import parse_scopes
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.storage import KVStorage
 from fastmcp.utilities.types import NotSet, NotSetT
 
 logger = get_logger(__name__)
@@ -201,6 +202,7 @@ class GitHubProvider(OAuthProxy):
         required_scopes: list[str] | NotSetT = NotSet,
         timeout_seconds: int | NotSetT = NotSet,
         allowed_client_redirect_uris: list[str] | NotSetT = NotSet,
+        client_storage: KVStorage | None = None,
     ):
         """Initialize GitHub OAuth provider.
 
@@ -213,6 +215,8 @@ class GitHubProvider(OAuthProxy):
             timeout_seconds: HTTP request timeout for GitHub API calls
             allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
                 If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage implementation for OAuth client registrations.
+                Defaults to file-based storage if not specified.
         """
 
         settings = GitHubProviderSettings.model_validate(
@@ -243,7 +247,6 @@ class GitHubProvider(OAuthProxy):
 
         # Apply defaults
 
-        redirect_path_final = settings.redirect_path or "/auth/callback"
         timeout_seconds_final = settings.timeout_seconds or 10
         required_scopes_final = settings.required_scopes or ["user"]
         allowed_client_redirect_uris_final = settings.allowed_client_redirect_uris
@@ -267,9 +270,10 @@ class GitHubProvider(OAuthProxy):
             upstream_client_secret=client_secret_str,
             token_verifier=token_verifier,
             base_url=settings.base_url,
-            redirect_path=redirect_path_final,
+            redirect_path=settings.redirect_path,
             issuer_url=settings.base_url,  # We act as the issuer for client registration
             allowed_client_redirect_uris=allowed_client_redirect_uris_final,
+            client_storage=client_storage,
         )
 
         logger.info(

fastmcp/server/auth/providers/google.py

@@ -32,6 +32,7 @@ from fastmcp.server.auth.auth import AccessToken
 from fastmcp.server.auth.oauth_proxy import OAuthProxy
 from fastmcp.utilities.auth import parse_scopes
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.storage import KVStorage
 from fastmcp.utilities.types import NotSet, NotSetT
 
 logger = get_logger(__name__)
@@ -217,6 +218,7 @@ class GoogleProvider(OAuthProxy):
         required_scopes: list[str] | NotSetT = NotSet,
         timeout_seconds: int | NotSetT = NotSet,
         allowed_client_redirect_uris: list[str] | NotSetT = NotSet,
+        client_storage: KVStorage | None = None,
     ):
         """Initialize Google OAuth provider.
 
@@ -232,6 +234,8 @@ class GoogleProvider(OAuthProxy):
             timeout_seconds: HTTP request timeout for Google API calls
             allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
                 If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage implementation for OAuth client registrations.
+                Defaults to file-based storage if not specified.
         """
 
         settings = GoogleProviderSettings.model_validate(
@@ -261,7 +265,6 @@ class GoogleProvider(OAuthProxy):
             )
 
         # Apply defaults
-        redirect_path_final = settings.redirect_path or "/auth/callback"
         timeout_seconds_final = settings.timeout_seconds or 10
         # Google requires at least one scope - openid is the minimal OIDC scope
         required_scopes_final = settings.required_scopes or ["openid"]
@@ -286,9 +289,10 @@ class GoogleProvider(OAuthProxy):
             upstream_client_secret=client_secret_str,
             token_verifier=token_verifier,
             base_url=settings.base_url,
-            redirect_path=redirect_path_final,
+            redirect_path=settings.redirect_path,
             issuer_url=settings.base_url,  # We act as the issuer for client registration
             allowed_client_redirect_uris=allowed_client_redirect_uris_final,
+            client_storage=client_storage,
         )
 
         logger.info(

fastmcp/server/auth/providers/workos.py

@@ -23,6 +23,7 @@ from fastmcp.server.auth.oauth_proxy import OAuthProxy
 from fastmcp.server.auth.providers.jwt import JWTVerifier
 from fastmcp.utilities.auth import parse_scopes
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.storage import KVStorage
 from fastmcp.utilities.types import NotSet, NotSetT
 
 logger = get_logger(__name__)
@@ -169,6 +170,7 @@ class WorkOSProvider(OAuthProxy):
         required_scopes: list[str] | None | NotSetT = NotSet,
         timeout_seconds: int | NotSetT = NotSet,
         allowed_client_redirect_uris: list[str] | NotSetT = NotSet,
+        client_storage: KVStorage | None = None,
     ):
         """Initialize WorkOS OAuth provider.
 
@@ -182,6 +184,8 @@ class WorkOSProvider(OAuthProxy):
             timeout_seconds: HTTP request timeout for WorkOS API calls
             allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
                 If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage implementation for OAuth client registrations.
+                Defaults to file-based storage if not specified.
         """
 
         settings = WorkOSProviderSettings.model_validate(
@@ -220,7 +224,6 @@ class WorkOSProvider(OAuthProxy):
         if not authkit_domain_str.startswith(("http://", "https://")):
             authkit_domain_str = f"https://{authkit_domain_str}"
         authkit_domain_final = authkit_domain_str.rstrip("/")
-        redirect_path_final = settings.redirect_path or "/auth/callback"
         timeout_seconds_final = settings.timeout_seconds or 10
         scopes_final = settings.required_scopes or []
         allowed_client_redirect_uris_final = settings.allowed_client_redirect_uris
@@ -245,9 +248,10 @@ class WorkOSProvider(OAuthProxy):
             upstream_client_secret=client_secret_str,
             token_verifier=token_verifier,
             base_url=settings.base_url,
-            redirect_path=redirect_path_final,
+            redirect_path=settings.redirect_path,
             issuer_url=settings.base_url,
             allowed_client_redirect_uris=allowed_client_redirect_uris_final,
+            client_storage=client_storage,
         )
 
         logger.info(

fastmcp/server/context.py

@@ -5,7 +5,7 @@ import copy
 import inspect
 import warnings
 import weakref
-from collections.abc import Generator, Mapping
+from collections.abc import Generator, Mapping, Sequence
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
 from dataclasses import dataclass
@@ -17,9 +17,10 @@ from mcp.server.lowlevel.helper_types import ReadResourceContents
 from mcp.server.lowlevel.server import request_ctx
 from mcp.shared.context import RequestContext
 from mcp.types import (
+    AudioContent,
     ClientCapabilities,
-    ContentBlock,
     CreateMessageResult,
+    ImageContent,
     IncludeContext,
     ModelHint,
     ModelPreferences,
@@ -359,13 +360,13 @@ class Context:
 
     async def sample(
         self,
-        messages: str | list[str | SamplingMessage],
+        messages: str | Sequence[str | SamplingMessage],
         system_prompt: str | None = None,
         include_context: IncludeContext | None = None,
         temperature: float | None = None,
         max_tokens: int | None = None,
         model_preferences: ModelPreferences | str | list[str] | None = None,
-    ) -> ContentBlock:
+    ) -> TextContent | ImageContent | AudioContent:
         """
         Send a sampling request to the client and await the response.
 
@@ -383,7 +384,7 @@ class Context:
                     content=TextContent(text=messages, type="text"), role="user"
                 )
             ]
-        elif isinstance(messages, list):
+        elif isinstance(messages, Sequence):
             sampling_messages = [
                 SamplingMessage(content=TextContent(text=m, type="text"), role="user")
                 if isinstance(m, str)
@@ -573,7 +574,7 @@ class Context:
             warnings.warn(
                 "Context.get_http_request() is deprecated and will be removed in a future version. "
                 "Use get_http_request() from fastmcp.server.dependencies instead. "
-                "See https://gofastmcp.com/patterns/http-requests for more details.",
+                "See https://gofastmcp.com/servers/context#http-requests for more details.",
                 DeprecationWarning,
                 stacklevel=2,
             )

fastmcp/server/http.py

@@ -113,7 +113,7 @@ def create_base_app(
         A Starlette application
     """
     # Always add RequestContextMiddleware as the outermost middleware
-    middleware.append(Middleware(RequestContextMiddleware))
+    middleware.insert(0, Middleware(RequestContextMiddleware))
 
     return StarletteWithLifespan(
         routes=routes,