fastmcp 2.12.5__py3-none-any.whl → 2.13.0rc2__py3-none-any.whl

fastmcp/server/auth/providers/supabase.py

@@ -0,0 +1,172 @@
+"""Supabase authentication provider for FastMCP.
+
+This module provides SupabaseProvider - a complete authentication solution that integrates
+with Supabase Auth's JWT verification, supporting Dynamic Client Registration (DCR)
+for seamless MCP client authentication.
+"""
+
+from __future__ import annotations
+
+import httpx
+from pydantic import AnyHttpUrl, field_validator
+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.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 SupabaseProviderSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_SERVER_AUTH_SUPABASE_",
+        env_file=ENV_FILE,
+        extra="ignore",
+    )
+
+    project_url: AnyHttpUrl
+    base_url: AnyHttpUrl
+    required_scopes: list[str] | None = None
+
+    @field_validator("required_scopes", mode="before")
+    @classmethod
+    def _parse_scopes(cls, v):
+        return parse_scopes(v)
+
+
+class SupabaseProvider(RemoteAuthProvider):
+    """Supabase metadata provider for DCR (Dynamic Client Registration).
+
+    This provider implements Supabase Auth integration using metadata forwarding.
+    This approach allows Supabase to handle the OAuth flow directly while FastMCP acts
+    as a resource server, verifying JWTs issued by Supabase Auth.
+
+    IMPORTANT SETUP REQUIREMENTS:
+
+    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
+
+    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
+
+    For detailed setup instructions, see:
+    https://supabase.com/docs/guides/auth/jwts
+
+    Example:
+        ```python
+        from fastmcp.server.auth.providers.supabase import SupabaseProvider
+
+        # Create Supabase metadata provider (JWT verifier created automatically)
+        supabase_auth = SupabaseProvider(
+            project_url="https://abc123.supabase.co",
+            base_url="https://your-fastmcp-server.com",
+        )
+
+        # Use with FastMCP
+        mcp = FastMCP("My App", auth=supabase_auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        project_url: AnyHttpUrl | str | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        required_scopes: list[str] | None | NotSetT = NotSet,
+        token_verifier: TokenVerifier | None = None,
+    ):
+        """Initialize Supabase metadata provider.
+
+        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
+            token_verifier: Optional token verifier. If None, creates JWT verifier for Supabase
+        """
+        settings = SupabaseProviderSettings.model_validate(
+            {
+                k: v
+                for k, v in {
+                    "project_url": project_url,
+                    "base_url": base_url,
+                    "required_scopes": required_scopes,
+                }.items()
+                if v is not NotSet
+            }
+        )
+
+        self.project_url = str(settings.project_url).rstrip("/")
+        self.base_url = 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
+                required_scopes=settings.required_scopes,
+            )
+
+        # Initialize RemoteAuthProvider with Supabase as the authorization server
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl(f"{self.project_url}/auth/v1")],
+            base_url=self.base_url,
+        )
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get OAuth routes including Supabase authorization server metadata forwarding.
+
+        This returns the standard protected resource routes plus an authorization server
+        metadata endpoint that forwards Supabase'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)
+
+        async def oauth_authorization_server_metadata(request):
+            """Forward Supabase OAuth authorization server metadata with FastMCP customizations."""
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(
+                        f"{self.project_url}/auth/v1/.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 Supabase metadata: {e}",
+                    },
+                    status_code=500,
+                )
+
+        # Add Supabase 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/workos.py

@@ -10,9 +10,8 @@ Choose based on your WorkOS setup and authentication requirements.
 
 from __future__ import annotations
 
-from typing import Any
-
 import httpx
+from key_value.aio.protocols import AsyncKeyValue
 from pydantic import AnyHttpUrl, SecretStr, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from starlette.responses import JSONResponse
@@ -21,9 +20,9 @@ from starlette.routing import Route
 from fastmcp.server.auth import AccessToken, RemoteAuthProvider, TokenVerifier
 from fastmcp.server.auth.oauth_proxy import OAuthProxy
 from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.settings import ENV_FILE
 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__)
@@ -34,7 +33,7 @@ class WorkOSProviderSettings(BaseSettings):
 
     model_config = SettingsConfigDict(
         env_prefix="FASTMCP_SERVER_AUTH_WORKOS_",
-        env_file=".env",
+        env_file=ENV_FILE,
         extra="ignore",
     )
 
@@ -42,6 +41,7 @@ class WorkOSProviderSettings(BaseSettings):
     client_secret: SecretStr | None = None
     authkit_domain: str | None = None  # e.g., "https://your-app.authkit.app"
     base_url: AnyHttpUrl | str | None = None
+    issuer_url: AnyHttpUrl | str | None = None
     redirect_path: str | None = None
     required_scopes: list[str] | None = None
     timeout_seconds: int | None = None
@@ -166,11 +166,12 @@ class WorkOSProvider(OAuthProxy):
         client_secret: str | NotSetT = NotSet,
         authkit_domain: str | NotSetT = NotSet,
         base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        issuer_url: AnyHttpUrl | str | NotSetT = NotSet,
         redirect_path: str | NotSetT = NotSet,
         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,
+        client_storage: AsyncKeyValue | None = None,
     ):
         """Initialize WorkOS OAuth provider.
 
@@ -178,14 +179,15 @@ class WorkOSProvider(OAuthProxy):
             client_id: WorkOS client ID
             client_secret: WorkOS client secret
             authkit_domain: Your WorkOS AuthKit domain (e.g., "https://your-app.authkit.app")
-            base_url: Public URL of your FastMCP server (for OAuth callbacks)
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
             redirect_path: Redirect path configured in WorkOS (defaults to "/auth/callback")
             required_scopes: Required OAuth scopes (no default)
             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.
+            client_storage: An AsyncKeyValue-compatible store for client registrations, registrations are stored in memory if not provided
         """
 
         settings = WorkOSProviderSettings.model_validate(
@@ -196,6 +198,7 @@ class WorkOSProvider(OAuthProxy):
                     "client_secret": client_secret,
                     "authkit_domain": authkit_domain,
                     "base_url": base_url,
+                    "issuer_url": issuer_url,
                     "redirect_path": redirect_path,
                     "required_scopes": required_scopes,
                     "timeout_seconds": timeout_seconds,
@@ -249,12 +252,13 @@ class WorkOSProvider(OAuthProxy):
             token_verifier=token_verifier,
             base_url=settings.base_url,
             redirect_path=settings.redirect_path,
-            issuer_url=settings.base_url,
+            issuer_url=settings.issuer_url
+            or settings.base_url,  # Default to base_url if not specified
             allowed_client_redirect_uris=allowed_client_redirect_uris_final,
             client_storage=client_storage,
         )
 
-        logger.info(
+        logger.debug(
             "Initialized WorkOS OAuth provider for client %s with AuthKit domain %s",
             settings.client_id,
             authkit_domain_final,
@@ -264,7 +268,7 @@ class WorkOSProvider(OAuthProxy):
 class AuthKitProviderSettings(BaseSettings):
     model_config = SettingsConfigDict(
         env_prefix="FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_",
-        env_file=".env",
+        env_file=ENV_FILE,
         extra="ignore",
     )
 
@@ -364,7 +368,6 @@ class AuthKitProvider(RemoteAuthProvider):
     def get_routes(
         self,
         mcp_path: str | None = None,
-        mcp_endpoint: Any | None = None,
     ) -> list[Route]:
         """Get OAuth routes including AuthKit authorization server metadata forwarding.
 
@@ -373,10 +376,10 @@ class AuthKitProvider(RemoteAuthProvider):
 
         Args:
             mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
-            mcp_endpoint: The MCP endpoint handler to protect with auth
+                This is used to advertise the resource URL in metadata.
         """
         # Get the standard protected resource routes from RemoteAuthProvider
-        routes = super().get_routes(mcp_path, mcp_endpoint)
+        routes = super().get_routes(mcp_path)
 
         async def oauth_authorization_server_metadata(request):
             """Forward AuthKit OAuth authorization server metadata with FastMCP customizations."""

fastmcp/server/context.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-import asyncio
 import copy
 import inspect
+import logging
 import warnings
 import weakref
 from collections.abc import Generator, Mapping, Sequence
@@ -10,8 +10,10 @@ from contextlib import contextmanager
 from contextvars import ContextVar, Token
 from dataclasses import dataclass
 from enum import Enum
+from logging import Logger
 from typing import Any, Literal, cast, get_origin, overload
 
+import anyio
 from mcp import LoggingLevel, ServerSession
 from mcp.server.lowlevel.helper_types import ReadResourceContents
 from mcp.server.lowlevel.server import request_ctx
@@ -44,14 +46,21 @@ from fastmcp.server.elicitation import (
     get_elicitation_schema,
 )
 from fastmcp.server.server import FastMCP
-from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.logging import _clamp_logger, get_logger
 from fastmcp.utilities.types import get_cached_typeadapter
 
-logger = get_logger(__name__)
+logger: Logger = get_logger(name=__name__)
+to_client_logger: Logger = logger.getChild(suffix="to_client")
+
+# Convert all levels of server -> client messages to debug level
+# This clamp can be undone at runtime by calling `_unclamp_logger` or calling
+# `_clamp_logger` with a different max level.
+_clamp_logger(logger=to_client_logger, max_level="DEBUG")
+
 
 T = TypeVar("T", default=Any)
 _current_context: ContextVar[Context | None] = ContextVar("context", default=None)  # type: ignore[assignment]
-_flush_lock = asyncio.Lock()
+_flush_lock = anyio.Lock()
 
 
 @dataclass
@@ -66,6 +75,18 @@ class LogData:
     extra: Mapping[str, Any] | None = None
 
 
+_mcp_level_to_python_level = {
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "notice": logging.INFO,
+    "warning": logging.WARNING,
+    "error": logging.ERROR,
+    "critical": logging.CRITICAL,
+    "alert": logging.CRITICAL,
+    "emergency": logging.CRITICAL,
+}
+
+
 @contextmanager
 def set_context(context: Context) -> Generator[Context, None, None]:
     token = _current_context.set(context)
@@ -205,7 +226,7 @@ class Context:
         """
         if self.fastmcp is None:
             raise ValueError("Context is not available outside of a request")
-        return await self.fastmcp._mcp_read_resource(uri)
+        return await self.fastmcp._read_resource_mcp(uri)
 
     async def log(
         self,
@@ -216,6 +237,8 @@ class Context:
     ) -> None:
         """Send a log message to the client.
 
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`.
+
         Args:
             message: Log message
             level: Optional log level. One of "debug", "info", "notice", "warning", "error", "critical",
@@ -223,13 +246,13 @@ class Context:
             logger_name: Optional logger name
             extra: Optional mapping for additional arguments
         """
-        if level is None:
-            level = "info"
         data = LogData(msg=message, extra=extra)
-        await self.session.send_log_message(
-            level=level,
+
+        await _log_to_server_and_client(
             data=data,
-            logger=logger_name,
+            session=self.session,
+            level=level or "info",
+            logger_name=logger_name,
             related_request_id=self.request_id,
         )
 
@@ -303,9 +326,14 @@ class Context:
         logger_name: str | None = None,
         extra: Mapping[str, Any] | None = None,
     ) -> None:
-        """Send a debug log message."""
+        """Send a `DEBUG`-level message to the connected MCP Client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`."""
         await self.log(
-            level="debug", message=message, logger_name=logger_name, extra=extra
+            level="debug",
+            message=message,
+            logger_name=logger_name,
+            extra=extra,
         )
 
     async def info(
@@ -314,9 +342,14 @@ class Context:
         logger_name: str | None = None,
         extra: Mapping[str, Any] | None = None,
     ) -> None:
-        """Send an info log message."""
+        """Send a `INFO`-level message to the connected MCP Client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`."""
         await self.log(
-            level="info", message=message, logger_name=logger_name, extra=extra
+            level="info",
+            message=message,
+            logger_name=logger_name,
+            extra=extra,
         )
 
     async def warning(
@@ -325,9 +358,14 @@ class Context:
         logger_name: str | None = None,
         extra: Mapping[str, Any] | None = None,
     ) -> None:
-        """Send a warning log message."""
+        """Send a `WARNING`-level message to the connected MCP Client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`."""
         await self.log(
-            level="warning", message=message, logger_name=logger_name, extra=extra
+            level="warning",
+            message=message,
+            logger_name=logger_name,
+            extra=extra,
         )
 
     async def error(
@@ -336,9 +374,14 @@ class Context:
         logger_name: str | None = None,
         extra: Mapping[str, Any] | None = None,
     ) -> None:
-        """Send an error log message."""
+        """Send a `ERROR`-level message to the connected MCP Client.
+
+        Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`."""
         await self.log(
-            level="error", message=message, logger_name=logger_name, extra=extra
+            level="error",
+            message=message,
+            logger_name=logger_name,
+            extra=extra,
         )
 
     async def list_roots(self) -> list[Root]:
@@ -592,30 +635,14 @@ class Context:
     def _queue_tool_list_changed(self) -> None:
         """Queue a tool list changed notification."""
         self._notification_queue.add("notifications/tools/list_changed")
-        self._try_flush_notifications()
 
     def _queue_resource_list_changed(self) -> None:
         """Queue a resource list changed notification."""
         self._notification_queue.add("notifications/resources/list_changed")
-        self._try_flush_notifications()
 
     def _queue_prompt_list_changed(self) -> None:
         """Queue a prompt list changed notification."""
         self._notification_queue.add("notifications/prompts/list_changed")
-        self._try_flush_notifications()
-
-    def _try_flush_notifications(self) -> None:
-        """Synchronous method that attempts to flush notifications if we're in an async context."""
-        try:
-            # Check if we're in an async context
-            loop = asyncio.get_running_loop()
-            if loop and not loop.is_running():
-                return
-            # Schedule flush as a task (fire-and-forget)
-            asyncio.create_task(self._flush_notifications())
-        except RuntimeError:
-            # No event loop - will flush later
-            pass
 
     async def _flush_notifications(self) -> None:
         """Send all queued notifications."""
@@ -675,3 +702,31 @@ def _parse_model_preferences(
         raise ValueError(
             "model_preferences must be one of: ModelPreferences, str, list[str], or None."
         )
+
+
+async def _log_to_server_and_client(
+    data: LogData,
+    session: ServerSession,
+    level: LoggingLevel,
+    logger_name: str | None = None,
+    related_request_id: str | None = None,
+) -> None:
+    """Log a message to the server and client."""
+
+    msg_prefix = f"Sending {level.upper()} to client"
+
+    if logger_name:
+        msg_prefix += f" ({logger_name})"
+
+    to_client_logger.log(
+        level=_mcp_level_to_python_level[level],
+        msg=f"{msg_prefix}: {data.msg}",
+        extra=data.extra,
+    )
+
+    await session.send_log_message(
+        level=level,
+        data=data,
+        logger=logger_name,
+        related_request_id=related_request_id,
+    )

fastmcp/server/http.py

@@ -6,9 +6,12 @@ from contextvars import ContextVar
 from typing import TYPE_CHECKING
 
 from mcp.server.auth.middleware.bearer_auth import RequireAuthMiddleware
+from mcp.server.auth.routes import build_resource_metadata_url
 from mcp.server.lowlevel.server import LifespanResultT
 from mcp.server.sse import SseServerTransport
-from mcp.server.streamable_http import EventStore
+from mcp.server.streamable_http import (
+    EventStore,
+)
 from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
 from starlette.applications import Starlette
 from starlette.middleware import Middleware
@@ -167,23 +170,38 @@ def create_sse_app(
         # Get auth middleware from the provider
         auth_middleware = auth.get_middleware()
 
-        # Get auth routes including protected MCP endpoint
-        auth_routes = auth.get_routes(
-            mcp_path=sse_path,
-            mcp_endpoint=handle_sse,
-        )
-
+        # Get auth provider's own routes (OAuth endpoints, metadata, etc)
+        auth_routes = auth.get_routes(mcp_path=sse_path)
         server_routes.extend(auth_routes)
         server_middleware.extend(auth_middleware)
 
-        # Manually wrap the SSE message endpoint with RequireAuthMiddleware
+        # Build RFC 9728-compliant metadata URL
+        resource_url = auth._get_resource_url(sse_path)
+        resource_metadata_url = (
+            build_resource_metadata_url(resource_url) if resource_url else None
+        )
+
+        # Create protected SSE endpoint route
+        server_routes.append(
+            Route(
+                sse_path,
+                endpoint=RequireAuthMiddleware(
+                    handle_sse,
+                    auth.required_scopes,
+                    resource_metadata_url,
+                ),
+                methods=["GET"],
+            )
+        )
+
+        # Wrap the SSE message endpoint with RequireAuthMiddleware
         server_routes.append(
             Mount(
                 message_path,
                 app=RequireAuthMiddleware(
                     sse.handle_post_message,
                     auth.required_scopes,
-                    auth._get_resource_url("/.well-known/oauth-protected-resource"),
+                    resource_metadata_url,
                 ),
             )
         )
@@ -215,11 +233,17 @@ def create_sse_app(
     if middleware:
         server_middleware.extend(middleware)
 
+    @asynccontextmanager
+    async def lifespan(app: Starlette) -> AsyncGenerator[None, None]:
+        async with server._lifespan_manager():
+            yield
+
     # Create and return the app
     app = create_base_app(
         routes=server_routes,
         middleware=server_middleware,
         debug=debug,
+        lifespan=lifespan,
     )
     # Store the FastMCP server instance on the Starlette app state
     app.state.fastmcp_server = server
@@ -274,14 +298,29 @@ def create_streamable_http_app(
         # Get auth middleware from the provider
         auth_middleware = auth.get_middleware()
 
-        # Get auth routes including protected MCP endpoint
-        auth_routes = auth.get_routes(
-            mcp_path=streamable_http_path,
-            mcp_endpoint=streamable_http_app,
-        )
-
+        # Get auth provider's own routes (OAuth endpoints, metadata, etc)
+        auth_routes = auth.get_routes(mcp_path=streamable_http_path)
         server_routes.extend(auth_routes)
         server_middleware.extend(auth_middleware)
+
+        # Build RFC 9728-compliant metadata URL
+        resource_url = auth._get_resource_url(streamable_http_path)
+        resource_metadata_url = (
+            build_resource_metadata_url(resource_url) if resource_url else None
+        )
+
+        # Create protected HTTP endpoint route
+        server_routes.append(
+            Route(
+                streamable_http_path,
+                endpoint=RequireAuthMiddleware(
+                    streamable_http_app,
+                    auth.required_scopes,
+                    resource_metadata_url,
+                ),
+                methods=["GET", "POST", "DELETE"],
+            )
+        )
     else:
         # No auth required
         server_routes.append(
@@ -303,8 +342,9 @@ def create_streamable_http_app(
     # Create a lifespan manager to start and stop the session manager
     @asynccontextmanager
     async def lifespan(app: Starlette) -> AsyncGenerator[None, None]:
-        async with session_manager.run():
-            yield
+        async with server._lifespan_manager():
+            async with session_manager.run():
+                yield
 
     # Create and return the app with lifespan
     app = create_base_app(