fastmcp 2.13.0.2__py3-none-any.whl → 2.13.1__py3-none-any.whl

fastmcp/server/auth/providers/descope.py

@@ -102,7 +102,7 @@ class DescopeProvider(RemoteAuthProvider):
         )
 
         self.project_id = settings.project_id
-        self.base_url = str(settings.base_url).rstrip("/")
+        self.base_url = AnyHttpUrl(str(settings.base_url).rstrip("/"))
         self.descope_base_url = str(settings.descope_base_url).rstrip("/")
 
         # Create default JWT verifier if none provided

fastmcp/server/auth/providers/in_memory.py

@@ -66,6 +66,22 @@ class InMemoryOAuthProvider(OAuthProvider):
         return self.clients.get(client_id)
 
     async def register_client(self, client_info: OAuthClientInformationFull) -> None:
+        # Validate scopes against valid_scopes if configured (matches MCP SDK behavior)
+        if (
+            client_info.scope is not None
+            and self.client_registration_options is not None
+            and self.client_registration_options.valid_scopes is not None
+        ):
+            requested_scopes = set(client_info.scope.split())
+            valid_scopes = set(self.client_registration_options.valid_scopes)
+            invalid_scopes = requested_scopes - valid_scopes
+            if invalid_scopes:
+                raise ValueError(
+                    f"Requested scopes are not valid: {', '.join(invalid_scopes)}"
+                )
+
+        if client_info.client_id is None:
+            raise ValueError("client_id is required for client registration")
         if client_info.client_id in self.clients:
             # As per RFC 7591, if client_id is already known, it's an update.
             # For this simple provider, we'll treat it as re-registration.
@@ -91,7 +107,7 @@ class InMemoryOAuthProvider(OAuthProvider):
             # OAuthClientInformationFull should have a method like validate_redirect_uri
             # For this test provider, we assume it's valid if it matches one in client_info
             # The AuthorizationHandler already does robust validation using client.validate_redirect_uri
-            if params.redirect_uri not in client.redirect_uris:
+            if client.redirect_uris and params.redirect_uri not in client.redirect_uris:
                 # This check might be too simplistic if redirect_uris can be patterns
                 # or if params.redirect_uri is None and client has a default.
                 # However, the AuthorizationHandler handles the primary validation.
@@ -110,6 +126,10 @@ class InMemoryOAuthProvider(OAuthProvider):
             client_allowed_scopes = set(client.scope.split())
             scopes_list = [s for s in scopes_list if s in client_allowed_scopes]
 
+        if client.client_id is None:
+            raise AuthorizeError(
+                error="invalid_client", error_description="Client ID is required"
+            )
         auth_code = AuthorizationCode(
             code=auth_code_value,
             client_id=client.client_id,
@@ -166,6 +186,8 @@ class InMemoryOAuthProvider(OAuthProvider):
                 time.time() + DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS
             )
 
+        if client.client_id is None:
+            raise TokenError("invalid_client", "Client ID is required")
         self.access_tokens[access_token_value] = AccessToken(
             token=access_token_value,
             client_id=client.client_id,
@@ -236,6 +258,8 @@ class InMemoryOAuthProvider(OAuthProvider):
                 time.time() + DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS
             )
 
+        if client.client_id is None:
+            raise TokenError("invalid_client", "Client ID is required")
         self.access_tokens[new_access_token_value] = AccessToken(
             token=new_access_token_value,
             client_id=client.client_id,

fastmcp/server/auth/providers/jwt.py

@@ -150,7 +150,7 @@ class JWTVerifierSettings(BaseSettings):
 
     public_key: str | None = None
     jwks_uri: str | None = None
-    issuer: str | None = None
+    issuer: str | list[str] | None = None
     algorithm: str | None = None
     audience: str | list[str] | None = None
     required_scopes: list[str] | None = None
@@ -186,26 +186,26 @@ class JWTVerifier(TokenVerifier):
         *,
         public_key: str | NotSetT | None = NotSet,
         jwks_uri: str | NotSetT | None = NotSet,
-        issuer: str | NotSetT | None = NotSet,
+        issuer: str | list[str] | NotSetT | None = NotSet,
         audience: str | list[str] | NotSetT | None = NotSet,
         algorithm: str | NotSetT | None = NotSet,
         required_scopes: list[str] | NotSetT | None = NotSet,
         base_url: AnyHttpUrl | str | NotSetT | None = NotSet,
     ):
         """
-        Initialize the JWT token verifier.
-
-        Args:
-            public_key: For asymmetric algorithms (RS256, ES256, etc.): PEM-encoded public key.
-                       For symmetric algorithms (HS256, HS384, HS512): The shared secret string.
-            jwks_uri: URI to fetch JSON Web Key Set (only for asymmetric algorithms)
-            issuer: Expected issuer claim
-            audience: Expected audience claim(s)
-            algorithm: JWT signing algorithm. Supported algorithms:
-                      - Asymmetric: RS256/384/512, ES256/384/512, PS256/384/512 (default: RS256)
-                      - Symmetric: HS256, HS384, HS512
-            required_scopes: Required scopes for all tokens
-            base_url: Base URL for TokenVerifier protocol
+        Initialize a JWTVerifier configured to validate JWTs using either a static key or a JWKS endpoint.
+
+        Parameters:
+            public_key (str | NotSetT | None): PEM-encoded public key for asymmetric algorithms or shared secret for symmetric algorithms.
+            jwks_uri (str | NotSetT | None): URI to fetch a JSON Web Key Set; used when verifying tokens with remote JWKS.
+            issuer (str | list[str] | NotSetT | None): Expected issuer claim value or list of allowed issuer values.
+            audience (str | list[str] | NotSetT | None): Expected audience claim value or list of allowed audience values.
+            algorithm (str | NotSetT | None): JWT signing algorithm to accept (default: "RS256"). Supported: HS256/384/512, RS256/384/512, ES256/384/512, PS256/384/512.
+            required_scopes (list[str] | NotSetT | None): Scopes that must be present in validated tokens.
+            base_url (AnyHttpUrl | str | NotSetT | None): Base URL passed to the parent TokenVerifier.
+
+        Raises:
+            ValueError: If neither or both of `public_key` and `jwks_uri` are provided, or if `algorithm` is unsupported.
         """
         settings = JWTVerifierSettings.model_validate(
             {
@@ -366,13 +366,13 @@ class JWTVerifier(TokenVerifier):
 
     async def load_access_token(self, token: str) -> AccessToken | None:
         """
-        Validates the provided JWT bearer token.
+        Validate a JWT bearer token and return an AccessToken when the token is valid.
 
-        Args:
-            token: The JWT token string to validate
+        Parameters:
+            token (str): The JWT bearer token string to validate.
 
         Returns:
-            AccessToken object if valid, None if invalid or expired
+            AccessToken | None: An AccessToken populated from token claims if the token is valid; `None` if the token is expired, has an invalid signature or format, fails issuer/audience/scope validation, or any other validation error occurs.
         """
         try:
             # Get verification key (static or from JWKS)
@@ -400,13 +400,25 @@ class JWTVerifier(TokenVerifier):
 
             # Validate issuer - note we use issuer instead of issuer_url here because
             # issuer is optional, allowing users to make this check optional
-            if self.issuer and claims.get("iss") != self.issuer:
-                self.logger.debug(
-                    "Token validation failed: issuer mismatch for client %s",
-                    client_id,
-                )
-                self.logger.info("Bearer token rejected for client %s", client_id)
-                return None
+            if self.issuer:
+                iss = claims.get("iss")
+
+                # Handle different combinations of issuer types
+                issuer_valid = False
+                if isinstance(self.issuer, list):
+                    # self.issuer is a list - check if token issuer matches any expected issuer
+                    issuer_valid = iss in self.issuer
+                else:
+                    # self.issuer is a string - check for equality
+                    issuer_valid = iss == self.issuer
+
+                if not issuer_valid:
+                    self.logger.debug(
+                        "Token validation failed: issuer mismatch for client %s",
+                        client_id,
+                    )
+                    self.logger.info("Bearer token rejected for client %s", client_id)
+                    return None
 
             # Validate audience if configured
             if self.audience:

fastmcp/server/auth/providers/oci.py

@@ -0,0 +1,233 @@
+"""OCI OIDC provider for FastMCP.
+
+The pull request for the provider is submitted to fastmcp.
+
+This module provides OIDC Implementation to integrate MCP servers with OCI.
+You only need OCI Identity Domain's discovery URL, client ID, client secret, and base URL.
+
+Post Authentication, you get OCI IAM domain access token. That is not authorized to invoke OCI control plane.
+You need to exchange the IAM domain access token for OCI UPST token to invoke OCI control plane APIs.
+The sample code below has get_oci_signer function that returns OCI TokenExchangeSigner object.
+You can use the signer object to create OCI service object.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.oci import OCIProvider
+    from fastmcp.server.dependencies import get_access_token
+    from fastmcp.utilities.logging import get_logger
+
+    import os
+
+    # Load configuration from environment
+    FASTMCP_SERVER_AUTH_OCI_CONFIG_URL = os.environ["FASTMCP_SERVER_AUTH_OCI_CONFIG_URL"]
+    FASTMCP_SERVER_AUTH_OCI_CLIENT_ID = os.environ["FASTMCP_SERVER_AUTH_OCI_CLIENT_ID"]
+    FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET = os.environ["FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET"]
+    FASTMCP_SERVER_AUTH_OCI_IAM_GUID = os.environ["FASTMCP_SERVER_AUTH_OCI_IAM_GUID"]
+
+    import oci
+    from oci.auth.signers import TokenExchangeSigner
+
+    logger = get_logger(__name__)
+
+    # Simple OCI OIDC protection
+    auth = OCIProvider(
+        config_url=FASTMCP_SERVER_AUTH_OCI_CONFIG_URL, #config URL is the OCI IAM Domain OIDC discovery URL.
+        client_id=FASTMCP_SERVER_AUTH_OCI_CLIENT_ID, #This is same as the client ID configured for the OCI IAM Domain Integrated Application
+        client_secret=FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET, #This is same as the client secret configured for the OCI IAM Domain Integrated Application
+        required_scopes=["openid", "profile", "email"],
+        redirect_path="/auth/callback",
+        base_url="http://localhost:8000",
+    )
+
+    # NOTE: For production use, replace this with a thread-safe cache implementation
+    # such as threading.Lock-protected dict or a proper caching library
+    _global_token_cache = {} #In memory cache for OCI session token signer
+
+    def get_oci_signer() -> TokenExchangeSigner:
+
+        authntoken = get_access_token()
+        tokenID = authntoken.claims.get("jti")
+        token = authntoken.token
+
+        #Check if the signer exists for the token ID in memory cache
+        cached_signer = _global_token_cache.get(tokenID)
+        logger.debug(f"Global cached signer: {cached_signer}")
+        if cached_signer:
+            logger.debug(f"Using globally cached signer for token ID: {tokenID}")
+            return cached_signer
+
+        #If the signer is not yet created for the token then create new OCI signer object
+        logger.debug(f"Creating new signer for token ID: {tokenID}")
+        signer = TokenExchangeSigner(
+            jwt_or_func=token,
+            oci_domain_id=FASTMCP_SERVER_AUTH_OCI_IAM_GUID.split(".")[0],   #This is same as IAM GUID configured for the OCI IAM Domain
+            client_id=FASTMCP_SERVER_AUTH_OCI_CLIENT_ID, #This is same as the client ID configured for the OCI IAM Domain Integrated Application
+            client_secret=FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET #This is same as the client secret configured for the OCI IAM Domain Integrated Application
+        )
+        logger.debug(f"Signer {signer} created for token ID: {tokenID}")
+
+        #Cache the signer object in memory cache
+        _global_token_cache[tokenID] = signer
+        logger.debug(f"Signer cached for token ID: {tokenID}")
+
+        return signer
+
+    mcp = FastMCP("My Protected Server", auth=auth)
+    ```
+"""
+
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from fastmcp.server.auth.oidc_proxy import OIDCProxy
+from fastmcp.settings import ENV_FILE
+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 OCIProviderSettings(BaseSettings):
+    """Settings for OCI IAM domain OIDC provider."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_SERVER_AUTH_OCI_",
+        env_file=ENV_FILE,
+        extra="ignore",
+    )
+
+    config_url: AnyHttpUrl | None = None
+    client_id: str | None = None
+    client_secret: SecretStr | None = None
+    audience: str | None = None
+    base_url: AnyHttpUrl | None = None
+    issuer_url: AnyHttpUrl | None = None
+    redirect_path: str | None = None
+    required_scopes: list[str] | None = None
+    allowed_client_redirect_uris: list[str] | None = None
+    jwt_signing_key: str | bytes | None = None
+
+    @field_validator("required_scopes", mode="before")
+    @classmethod
+    def _parse_scopes(cls, v):
+        return parse_scopes(v)
+
+
+class OCIProvider(OIDCProxy):
+    """An OCI IAM Domain provider implementation for FastMCP.
+
+    This provider is a complete OCI integration that's ready to use with
+    just the configuration URL, client ID, client secret, and base URL.
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.oci import OCIProvider
+
+        # Simple OCI OIDC protection
+        auth = OCIProvider(
+            config_url=FASTMCP_SERVER_AUTH_OCI_CONFIG_URL, #config URL is the OCI IAM Domain OIDC discovery URL.
+            client_id=FASTMCP_SERVER_AUTH_OCI_CLIENT_ID, #This is same as the client ID configured for the OCI IAM Domain Integrated Application
+            client_secret=FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET, #This is same as the client secret configured for the OCI IAM Domain Integrated Application
+            base_url="http://localhost:8000",
+            required_scopes=["openid", "profile", "email"],
+            redirect_path="/auth/callback",
+        )
+
+        mcp = FastMCP("My Protected Server", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        config_url: AnyHttpUrl | str | NotSetT = NotSet,
+        client_id: str | NotSetT = NotSet,
+        client_secret: str | NotSetT = NotSet,
+        audience: str | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        issuer_url: AnyHttpUrl | str | NotSetT = NotSet,
+        required_scopes: list[str] | NotSetT = NotSet,
+        redirect_path: str | NotSetT = NotSet,
+        allowed_client_redirect_uris: list[str] | NotSetT = NotSet,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | NotSetT = NotSet,
+        require_authorization_consent: bool = True,
+    ) -> None:
+        """Initialize OCI OIDC provider.
+
+        Args:
+            config_url: OCI OIDC Discovery URL
+            client_id: OCI IAM Domain Integrated Application client id
+            client_secret: OCI Integrated Application client secret
+            audience: OCI API audience (optional)
+            base_url: Public URL where OIDC endpoints will be accessible (includes any mount path)
+            issuer_url: Issuer URL for OCI IAM Domain metadata. This will override issuer URL from the discovery URL.
+            required_scopes: Required OCI scopes (defaults to ["openid"])
+            redirect_path: Redirect path configured in OCI IAM Domain Integrated Application. The default is "/auth/callback".
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+        """
+
+        overrides = {
+            k: v
+            for k, v in {
+                "config_url": config_url,
+                "client_id": client_id,
+                "client_secret": client_secret,
+                "audience": audience,
+                "base_url": base_url,
+                "issuer_url": issuer_url,
+                "required_scopes": required_scopes,
+                "redirect_path": redirect_path,
+                "allowed_client_redirect_uris": allowed_client_redirect_uris,
+                "jwt_signing_key": jwt_signing_key,
+            }.items()
+            if v is not NotSet
+        }
+        settings = OCIProviderSettings(**overrides)
+
+        if not settings.config_url:
+            raise ValueError(
+                "config_url is required - set via parameter or FASTMCP_SERVER_AUTH_OCI_CONFIG_URL"
+            )
+
+        if not settings.client_id:
+            raise ValueError(
+                "client_id is required - set via parameter or FASTMCP_SERVER_AUTH_OCI_CLIENT_ID"
+            )
+
+        if not settings.client_secret:
+            raise ValueError(
+                "client_secret is required - set via parameter or FASTMCP_SERVER_AUTH_OCI_CLIENT_SECRET"
+            )
+
+        if not settings.base_url:
+            raise ValueError(
+                "base_url is required - set via parameter or FASTMCP_SERVER_AUTH_OCI_BASE_URL"
+            )
+
+        oci_required_scopes = settings.required_scopes or ["openid"]
+
+        super().__init__(
+            config_url=settings.config_url,
+            client_id=settings.client_id,
+            client_secret=settings.client_secret.get_secret_value(),
+            audience=settings.audience,
+            base_url=settings.base_url,
+            issuer_url=settings.issuer_url,
+            redirect_path=settings.redirect_path,
+            required_scopes=oci_required_scopes,
+            allowed_client_redirect_uris=settings.allowed_client_redirect_uris,
+            client_storage=client_storage,
+            jwt_signing_key=settings.jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+        )
+
+        logger.debug(
+            "Initialized OCI OAuth provider for client %s with scopes: %s",
+            settings.client_id,
+            oci_required_scopes,
+        )

fastmcp/server/auth/providers/supabase.py

@@ -7,6 +7,8 @@ for seamless MCP client authentication.
 
 from __future__ import annotations
 
+from typing import Literal
+
 import httpx
 from pydantic import AnyHttpUrl, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -32,6 +34,7 @@ class SupabaseProviderSettings(BaseSettings):
 
     project_url: AnyHttpUrl
     base_url: AnyHttpUrl
+    algorithm: Literal["HS256", "RS256", "ES256"] = "ES256"
     required_scopes: list[str] | None = None
 
     @field_validator("required_scopes", mode="before")
@@ -52,13 +55,19 @@ class SupabaseProvider(RemoteAuthProvider):
     1. Supabase Project Setup:
        - Create a Supabase project at https://supabase.com
        - Note your project URL (e.g., "https://abc123.supabase.co")
-       - For projects created after May 1st, 2025, asymmetric RS256 keys are used by default
-       - For older projects, consider migrating to asymmetric keys for better security
+       - Configure your JWT algorithm in Supabase Auth settings (HS256, RS256, or ES256)
+       - Asymmetric keys (RS256/ES256) are recommended for production
 
     2. JWT Verification:
        - FastMCP verifies JWTs using the JWKS endpoint at {project_url}/auth/v1/.well-known/jwks.json
        - JWTs are issued by {project_url}/auth/v1
        - Tokens are cached for up to 10 minutes by Supabase's edge servers
+       - Algorithm must match your Supabase Auth configuration
+
+    3. Authorization:
+       - Supabase uses Row Level Security (RLS) policies for database authorization
+       - OAuth-level scopes are an upcoming feature in Supabase Auth
+       - Both approaches will be supported once scope handling is available
 
     For detailed setup instructions, see:
     https://supabase.com/docs/guides/auth/jwts
@@ -71,6 +80,7 @@ class SupabaseProvider(RemoteAuthProvider):
         supabase_auth = SupabaseProvider(
             project_url="https://abc123.supabase.co",
             base_url="https://your-fastmcp-server.com",
+            algorithm="ES256",  # Match your Supabase Auth configuration
         )
 
         # Use with FastMCP
@@ -83,6 +93,7 @@ class SupabaseProvider(RemoteAuthProvider):
         *,
         project_url: AnyHttpUrl | str | NotSetT = NotSet,
         base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        algorithm: Literal["HS256", "RS256", "ES256"] | NotSetT = NotSet,
         required_scopes: list[str] | NotSetT | None = NotSet,
         token_verifier: TokenVerifier | None = None,
     ):
@@ -91,7 +102,11 @@ class SupabaseProvider(RemoteAuthProvider):
         Args:
             project_url: Your Supabase project URL (e.g., "https://abc123.supabase.co")
             base_url: Public URL of this FastMCP server
-            required_scopes: Optional list of scopes to require for all requests
+            algorithm: JWT signing algorithm (HS256, RS256, or ES256). Must match your
+                Supabase Auth configuration. Defaults to ES256.
+            required_scopes: Optional list of scopes to require for all requests.
+                Note: Supabase currently uses RLS policies for authorization. OAuth-level
+                scopes are an upcoming feature.
             token_verifier: Optional token verifier. If None, creates JWT verifier for Supabase
         """
         settings = SupabaseProviderSettings.model_validate(
@@ -100,6 +115,7 @@ class SupabaseProvider(RemoteAuthProvider):
                 for k, v in {
                     "project_url": project_url,
                     "base_url": base_url,
+                    "algorithm": algorithm,
                     "required_scopes": required_scopes,
                 }.items()
                 if v is not NotSet
@@ -107,14 +123,14 @@ class SupabaseProvider(RemoteAuthProvider):
         )
 
         self.project_url = str(settings.project_url).rstrip("/")
-        self.base_url = str(settings.base_url).rstrip("/")
+        self.base_url = AnyHttpUrl(str(settings.base_url).rstrip("/"))
 
         # Create default JWT verifier if none provided
         if token_verifier is None:
             token_verifier = JWTVerifier(
                 jwks_uri=f"{self.project_url}/auth/v1/.well-known/jwks.json",
                 issuer=f"{self.project_url}/auth/v1",
-                algorithm="ES256",  # Supabase uses ES256 for asymmetric keys
+                algorithm=settings.algorithm,
                 required_scopes=settings.required_scopes,
             )
 

fastmcp/server/auth/providers/workos.py

@@ -362,7 +362,7 @@ class AuthKitProvider(RemoteAuthProvider):
         )
 
         self.authkit_domain = str(settings.authkit_domain).rstrip("/")
-        self.base_url = str(settings.base_url).rstrip("/")
+        self.base_url = AnyHttpUrl(str(settings.base_url).rstrip("/"))
 
         # Create default JWT verifier if none provided
         if token_verifier is None:

fastmcp/server/context.py

@@ -181,15 +181,33 @@ class Context:
             _current_context.reset(token)
 
     @property
-    def request_context(self) -> RequestContext[ServerSession, Any, Request]:
+    def request_context(self) -> RequestContext[ServerSession, Any, Request] | None:
         """Access to the underlying request context.
 
-        If called outside of a request context, this will raise a ValueError.
+        Returns None when the MCP session has not been established yet.
+        Returns the full RequestContext once the MCP session is available.
+
+        For HTTP request access in middleware, use `get_http_request()` from fastmcp.server.dependencies,
+        which works whether or not the MCP session is available.
+
+        Example in middleware:
+        ```python
+        async def on_request(self, context, call_next):
+            ctx = context.fastmcp_context
+            if ctx.request_context:
+                # MCP session available - can access session_id, request_id, etc.
+                session_id = ctx.session_id
+            else:
+                # MCP session not available yet - use HTTP helpers
+                from fastmcp.server.dependencies import get_http_request
+                request = get_http_request()
+            return await call_next(context)
+        ```
         """
         try:
             return request_ctx.get()
-        except LookupError as e:
-            raise ValueError("Context is not available outside of a request") from e
+        except LookupError:
+            return None
 
     async def report_progress(
         self, progress: float, total: float | None = None, message: str | None = None
@@ -203,7 +221,7 @@ class Context:
 
         progress_token = (
             self.request_context.meta.progressToken
-            if self.request_context.meta
+            if self.request_context and self.request_context.meta
             else None
         )
 
@@ -292,13 +310,21 @@ class Context:
         """Get the client ID if available."""
         return (
             getattr(self.request_context.meta, "client_id", None)
-            if self.request_context.meta
+            if self.request_context and self.request_context.meta
             else None
         )
 
     @property
     def request_id(self) -> str:
-        """Get the unique ID for this request."""
+        """Get the unique ID for this request.
+
+        Raises RuntimeError if MCP request context is not available.
+        """
+        if self.request_context is None:
+            raise RuntimeError(
+                "request_id is not available because the MCP session has not been established yet. "
+                "Check `context.request_context` for None before accessing this attribute."
+            )
         return str(self.request_context.request_id)
 
     @property
@@ -313,6 +339,9 @@ class Context:
             The session ID for StreamableHTTP transports, or a generated ID
             for other transports.
 
+        Raises:
+            RuntimeError if MCP request context is not available.
+
         Example:
             ```python
             @server.tool
@@ -323,6 +352,11 @@ class Context:
             ```
         """
         request_ctx = self.request_context
+        if request_ctx is None:
+            raise RuntimeError(
+                "session_id is not available because the MCP session has not been established yet. "
+                "Check `context.request_context` for None before accessing this attribute."
+            )
         session = request_ctx.session
 
         # Try to get the session ID from the session attributes
@@ -347,7 +381,15 @@ class Context:
 
     @property
     def session(self) -> ServerSession:
-        """Access to the underlying session for advanced usage."""
+        """Access to the underlying session for advanced usage.
+
+        Raises RuntimeError if MCP request context is not available.
+        """
+        if self.request_context is None:
+            raise RuntimeError(
+                "session is not available because the MCP session has not been established yet. "
+                "Check `context.request_context` for None before accessing this attribute."
+            )
         return self.request_context.session
 
     # Convenience methods for common log levels

fastmcp/server/dependencies.py

@@ -9,9 +9,11 @@ from mcp.server.auth.middleware.auth_context import (
 from mcp.server.auth.provider import (
     AccessToken as _SDKAccessToken,
 )
+from mcp.server.lowlevel.server import request_ctx
 from starlette.requests import Request
 
 from fastmcp.server.auth import AccessToken
+from fastmcp.server.http import _current_http_request
 
 if TYPE_CHECKING:
     from fastmcp.server.context import Context
@@ -41,12 +43,16 @@ def get_context() -> Context:
 
 
 def get_http_request() -> Request:
-    from mcp.server.lowlevel.server import request_ctx
-
+    # Try MCP SDK's request_ctx first (set during normal MCP request handling)
     request = None
     with contextlib.suppress(LookupError):
         request = request_ctx.get().request
 
+    # Fallback to FastMCP's HTTP context variable
+    # This is needed during `on_initialize` middleware where request_ctx isn't set yet
+    if request is None:
+        request = _current_http_request.get()
+
     if request is None:
         raise RuntimeError("No active HTTP request found.")
     return request

fastmcp/server/middleware/caching.py

@@ -63,14 +63,21 @@ class CachableReadResourceContents(BaseModel):
 class CachableToolResult(BaseModel):
     content: list[mcp.types.ContentBlock]
     structured_content: dict[str, Any] | None
+    meta: dict[str, Any] | None
 
     @classmethod
     def wrap(cls, value: ToolResult) -> Self:
-        return cls(content=value.content, structured_content=value.structured_content)
+        return cls(
+            content=value.content,
+            structured_content=value.structured_content,
+            meta=value.meta,
+        )
 
     def unwrap(self) -> ToolResult:
         return ToolResult(
-            content=self.content, structured_content=self.structured_content
+            content=self.content,
+            structured_content=self.structured_content,
+            meta=self.meta,
         )