fastmcp 2.10.6__py3-none-any.whl → 2.11.0__py3-none-any.whl

fastmcp/server/auth/providers/workos.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import httpx
+from mcp.server.auth.provider import (
+    AccessToken,
+)
+from pydantic import AnyHttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from starlette.responses import JSONResponse
+from starlette.routing import BaseRoute, Route
+
+from fastmcp.server.auth.auth import AuthProvider, TokenVerifier
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.server.auth.registry import register_provider
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import NotSet, NotSetT
+
+logger = get_logger(__name__)
+
+
+class AuthKitProviderSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    authkit_domain: AnyHttpUrl
+    base_url: AnyHttpUrl
+    required_scopes: list[str] | None = None
+
+
+@register_provider("AUTHKIT")
+class AuthKitProvider(AuthProvider):
+    """WorkOS AuthKit metadata provider for DCR (Dynamic Client Registration).
+
+    This provider implements WorkOS AuthKit integration using metadata forwarding
+    instead of OAuth proxying. This is the recommended approach for WorkOS DCR
+    as it allows WorkOS to handle the OAuth flow directly while FastMCP acts
+    as a resource server.
+
+    IMPORTANT SETUP REQUIREMENTS:
+
+    1. Enable Dynamic Client Registration in WorkOS Dashboard:
+       - Go to Applications → Configuration
+       - Toggle "Dynamic Client Registration" to enabled
+
+    2. Configure your FastMCP server URL as a callback:
+       - Add your server URL to the Redirects tab in WorkOS dashboard
+       - Example: https://your-fastmcp-server.com/oauth2/callback
+
+    For detailed setup instructions, see:
+    https://workos.com/docs/authkit/mcp/integrating/token-verification
+
+    Example:
+        ```python
+        from fastmcp.server.auth.providers.workos import AuthKitProvider
+
+        # Create WorkOS metadata provider (JWT verifier created automatically)
+        workos_auth = AuthKitProvider(
+            authkit_domain="https://your-workos-domain.authkit.app",
+            base_url="https://your-fastmcp-server.com",
+        )
+
+        # Use with FastMCP
+        mcp = FastMCP("My App", auth=workos_auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        authkit_domain: AnyHttpUrl | str | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        required_scopes: list[str] | None | NotSetT = NotSet,
+        token_verifier: TokenVerifier | None = None,
+    ):
+        """Initialize WorkOS metadata provider.
+
+        Args:
+            authkit_domain: Your WorkOS AuthKit domain (e.g., "https://your-app.authkit.app")
+            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 WorkOS
+        """
+        super().__init__()
+
+        settings = AuthKitProviderSettings.model_validate(
+            {
+                k: v
+                for k, v in {
+                    "authkit_domain": authkit_domain,
+                    "base_url": base_url,
+                    "required_scopes": required_scopes,
+                }.items()
+                if v is not NotSet
+            }
+        )
+
+        self.authkit_domain = str(settings.authkit_domain).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.authkit_domain}/oauth2/jwks",
+                issuer=self.authkit_domain,
+                algorithm="RS256",
+                required_scopes=settings.required_scopes,
+            )
+
+        self.token_verifier = token_verifier
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify a WorkOS token using the configured token verifier."""
+        return await self.token_verifier.verify_token(token)
+
+    def customize_auth_routes(self, routes: list[BaseRoute]) -> list[BaseRoute]:
+        """Add AuthKit metadata endpoints.
+
+        This adds:
+        - /.well-known/oauth-authorization-server (forwards AuthKit metadata)
+        - /.well-known/oauth-protected-resource (returns FastMCP resource info)
+        """
+
+        async def oauth_authorization_server_metadata(request):
+            """Forward AuthKit OAuth authorization server metadata with FastMCP customizations."""
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(
+                        f"{self.authkit_domain}/.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 AuthKit metadata: {e}",
+                    },
+                    status_code=500,
+                )
+
+        async def oauth_protected_resource_metadata(request):
+            """Return FastMCP resource server metadata."""
+            return JSONResponse(
+                {
+                    "resource": self.base_url,
+                    "authorization_servers": [self.authkit_domain],
+                    "bearer_methods_supported": ["header"],
+                }
+            )
+
+        routes.extend(
+            [
+                Route(
+                    "/.well-known/oauth-authorization-server",
+                    endpoint=oauth_authorization_server_metadata,
+                    methods=["GET"],
+                ),
+                Route(
+                    "/.well-known/oauth-protected-resource",
+                    endpoint=oauth_protected_resource_metadata,
+                    methods=["GET"],
+                ),
+            ]
+        )
+
+        return routes

fastmcp/server/auth/registry.py

@@ -0,0 +1,52 @@
+"""Provider registry for FastMCP auth providers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from fastmcp.server.auth.auth import AuthProvider
+
+# Type variable for auth providers
+T = TypeVar("T", bound="AuthProvider")
+
+
+# Provider Registry
+_PROVIDER_REGISTRY: dict[str, type[AuthProvider]] = {}
+
+
+def register_provider(name: str) -> Callable[[type[T]], type[T]]:
+    """Decorator to register an auth provider with a given name.
+
+    Args:
+        name: The name to register the provider under (e.g., 'AUTHKIT')
+
+    Returns:
+        The decorated class
+
+    Example:
+        @register_provider('AUTHKIT')
+        class AuthKitProvider(AuthProvider):
+            ...
+    """
+
+    def decorator(cls: type[T]) -> type[T]:
+        _PROVIDER_REGISTRY[name.upper()] = cls
+        return cls
+
+    return decorator
+
+
+def get_registered_provider(name: str) -> type[AuthProvider]:
+    """Get a registered provider by name.
+
+    Args:
+        name: The provider name (case-insensitive)
+
+    Returns:
+        The provider class if found, None otherwise
+    """
+    if name.upper() in _PROVIDER_REGISTRY:
+        return _PROVIDER_REGISTRY[name.upper()]
+    raise ValueError(f"Provider {name!r} has not been registered.")

fastmcp/server/context.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 import asyncio
+import copy
 import warnings
-from collections.abc import Generator
+from collections.abc import Generator, Mapping
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
 from dataclasses import dataclass
@@ -46,6 +47,18 @@ _current_context: ContextVar[Context | None] = ContextVar("context", default=Non
 _flush_lock = asyncio.Lock()
 
 
+@dataclass
+class LogData:
+    """Data object for passing log arguments to client-side handlers.
+
+    This provides an interface to match the Python standard library logging,
+    for compatibility with structured logging.
+    """
+
+    msg: str
+    extra: Mapping[str, Any] | None = None
+
+
 @contextmanager
 def set_context(context: Context) -> Generator[Context, None, None]:
     token = _current_context.set(context)
@@ -83,9 +96,19 @@ class Context:
         request_id = ctx.request_id
         client_id = ctx.client_id
 
+        # Manage state across the request
+        ctx.set_state("key", "value")
+        value = ctx.get_state("key")
+
         return str(x)
     ```
 
+    State Management:
+    Context objects maintain a state dictionary that can be used to store and share
+    data across middleware and tool calls within a request. When a new context
+    is created (nested contexts), it inherits a copy of its parent's state, ensuring
+    that modifications in child contexts don't affect parent contexts.
+
     The context parameter name can be anything as long as it's annotated with Context.
     The context is optional - tools that don't need it can omit the parameter.
 
@@ -95,9 +118,15 @@ class Context:
         self.fastmcp = fastmcp
         self._tokens: list[Token] = []
         self._notification_queue: set[str] = set()  # Dedupe notifications
+        self._state: dict[str, Any] = {}
 
     async def __aenter__(self) -> Context:
         """Enter the context manager and set this context as the current context."""
+        parent_context = _current_context.get(None)
+        if parent_context is not None:
+            # Inherit state from parent context
+            self._state = copy.deepcopy(parent_context._state)
+
         # Always set this context and save the token
         token = _current_context.set(self)
         self._tokens.append(token)
@@ -113,7 +142,7 @@ class Context:
             _current_context.reset(token)
 
     @property
-    def request_context(self) -> RequestContext:
+    def request_context(self) -> RequestContext[ServerSession, Any, Request]:
         """Access to the underlying request context.
 
         If called outside of a request context, this will raise a ValueError.
@@ -167,6 +196,7 @@ class Context:
         message: str,
         level: LoggingLevel | None = None,
         logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
     ) -> None:
         """Send a log message to the client.
 
@@ -175,12 +205,14 @@ class Context:
             level: Optional log level. One of "debug", "info", "notice", "warning", "error", "critical",
                 "alert", or "emergency". Default is "info".
             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,
-            data=message,
+            data=data,
             logger=logger_name,
             related_request_id=self.request_id,
         )
@@ -200,35 +232,48 @@ class Context:
         return str(self.request_context.request_id)
 
     @property
-    def session_id(self) -> str | None:
-        """Get the MCP session ID for HTTP transports.
+    def session_id(self) -> str:
+        """Get the MCP session ID for ALL transports.
 
         Returns the session ID that can be used as a key for session-based
         data storage (e.g., Redis) to share data between tool calls within
         the same client session.
 
         Returns:
-            The session ID for HTTP transports (SSE, StreamableHTTP), or None
-            for stdio and in-memory transports which don't use session IDs.
+            The session ID for StreamableHTTP transports, or a generated ID
+            for other transports.
 
         Example:
             ```python
             @server.tool
             def store_data(data: dict, ctx: Context) -> str:
-                if session_id := ctx.session_id:
-                    redis_client.set(f"session:{session_id}:data", json.dumps(data))
-                    return f"Data stored for session {session_id}"
-                return "No session ID available (stdio/memory transport)"
+                session_id = ctx.session_id
+                redis_client.set(f"session:{session_id}:data", json.dumps(data))
+                return f"Data stored for session {session_id}"
             ```
         """
-        try:
-            from fastmcp.server.dependencies import get_http_headers
+        request_ctx = self.request_context
+        session = request_ctx.session
 
-            headers = get_http_headers(include_all=True)
-            return headers.get("mcp-session-id")
-        except RuntimeError:
-            # No HTTP context available (stdio/in-memory transport)
-            return None
+        # Try to get the session ID from the session attributes
+        session_id = getattr(session, "_fastmcp_id", None)
+        if session_id is not None:
+            return session_id
+
+        # Try to get the session ID from the http request headers
+        request = request_ctx.request
+        if request:
+            session_id = request.headers.get("mcp-session-id")
+
+        # Generate a session ID if it doesn't exist.
+        if session_id is None:
+            from uuid import uuid4
+
+            session_id = str(uuid4())
+
+        # Save the session id to the session attributes
+        setattr(session, "_fastmcp_id", session_id)
+        return session_id
 
     @property
     def session(self) -> ServerSession:
@@ -236,21 +281,49 @@ class Context:
         return self.request_context.session
 
     # Convenience methods for common log levels
-    async def debug(self, message: str, logger_name: str | None = None) -> None:
+    async def debug(
+        self,
+        message: str,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
         """Send a debug log message."""
-        await self.log(level="debug", message=message, logger_name=logger_name)
+        await self.log(
+            level="debug", message=message, logger_name=logger_name, extra=extra
+        )
 
-    async def info(self, message: str, logger_name: str | None = None) -> None:
+    async def info(
+        self,
+        message: str,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
         """Send an info log message."""
-        await self.log(level="info", message=message, logger_name=logger_name)
+        await self.log(
+            level="info", message=message, logger_name=logger_name, extra=extra
+        )
 
-    async def warning(self, message: str, logger_name: str | None = None) -> None:
+    async def warning(
+        self,
+        message: str,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
         """Send a warning log message."""
-        await self.log(level="warning", message=message, logger_name=logger_name)
+        await self.log(
+            level="warning", message=message, logger_name=logger_name, extra=extra
+        )
 
-    async def error(self, message: str, logger_name: str | None = None) -> None:
+    async def error(
+        self,
+        message: str,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
         """Send an error log message."""
-        await self.log(level="error", message=message, logger_name=logger_name)
+        await self.log(
+            level="error", message=message, logger_name=logger_name, extra=extra
+        )
 
     async def list_roots(self) -> list[Root]:
         """List the roots available to the server, as indicated by the client."""
@@ -455,6 +528,14 @@ class Context:
 
         return fastmcp.server.dependencies.get_http_request()
 
+    def set_state(self, key: str, value: Any) -> None:
+        """Set a value in the context state."""
+        self._state[key] = value
+
+    def get_state(self, key: str) -> Any:
+        """Get a value from the context state. Returns None if the key is not found."""
+        return self._state.get(key)
+
     def _queue_tool_list_changed(self) -> None:
         """Queue a tool list changed notification."""
         self._notification_queue.add("notifications/tools/list_changed")

fastmcp/server/dependencies.py

@@ -37,9 +37,14 @@ def get_context() -> Context:
 
 
 def get_http_request() -> Request:
-    from fastmcp.server.http import _current_http_request
+    from mcp.server.lowlevel.server import request_ctx
+
+    request = None
+    try:
+        request = request_ctx.get().request
+    except LookupError:
+        pass
 
-    request = _current_http_request.get()
     if request is None:
         raise RuntimeError("No active HTTP request found.")
     return request
@@ -72,6 +77,8 @@ def get_http_headers(include_all: bool = False) -> dict[str, str]:
             "proxy-authenticate",
             "proxy-authorization",
             "proxy-connection",
+            # MCP-related headers
+            "mcp-session-id",
         }
         # (just in case)
         if not all(h.lower() == h for h in exclude_headers):

fastmcp/server/http.py

@@ -3,18 +3,20 @@ from __future__ import annotations
 from collections.abc import AsyncGenerator, Callable, Generator
 from contextlib import asynccontextmanager, contextmanager
 from contextvars import ContextVar
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
 from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
 from mcp.server.auth.middleware.bearer_auth import (
     BearerAuthBackend,
     RequireAuthMiddleware,
 )
+from mcp.server.auth.provider import TokenVerifier as TokenVerifierProtocol
 from mcp.server.auth.routes import create_auth_routes
 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_manager import StreamableHTTPSessionManager
+from pydantic import AnyHttpUrl
 from starlette.applications import Starlette
 from starlette.middleware import Middleware
 from starlette.middleware.authentication import AuthenticationMiddleware
@@ -23,7 +25,7 @@ from starlette.responses import Response
 from starlette.routing import BaseRoute, Mount, Route
 from starlette.types import Lifespan, Receive, Scope, Send
 
-from fastmcp.server.auth.auth import OAuthProvider
+from fastmcp.server.auth.auth import AuthProvider, OAuthProvider, TokenVerifier
 from fastmcp.utilities.logging import get_logger
 
 if TYPE_CHECKING:
@@ -70,39 +72,46 @@ class RequestContextMiddleware:
 
 
 def setup_auth_middleware_and_routes(
-    auth: OAuthProvider,
-) -> tuple[list[Middleware], list[BaseRoute], list[str]]:
+    auth: AuthProvider,
+) -> tuple[list[Middleware], list[Route], list[str]]:
     """Set up authentication middleware and routes if auth is enabled.
 
     Args:
-        auth: The OAuthProvider authorization server provider
+        auth: An AuthProvider for authentication (TokenVerifier or OAuthProvider)
 
     Returns:
         Tuple of (middleware, auth_routes, required_scopes)
     """
-    middleware: list[Middleware] = []
-    auth_routes: list[BaseRoute] = []
-    required_scopes: list[str] = []
-
-    middleware = [
+    middleware: list[Middleware] = [
         Middleware(
             AuthenticationMiddleware,
-            backend=BearerAuthBackend(auth),
+            backend=BearerAuthBackend(cast(TokenVerifierProtocol, auth)),
         ),
         Middleware(AuthContextMiddleware),
     ]
 
-    required_scopes = auth.required_scopes or []
-
-    auth_routes.extend(
-        create_auth_routes(
-            provider=auth,
-            issuer_url=auth.issuer_url,
-            service_documentation_url=auth.service_documentation_url,
-            client_registration_options=auth.client_registration_options,
-            revocation_options=auth.revocation_options,
+    auth_routes: list[Route] = []
+    required_scopes: list[str] = auth.required_scopes or []
+
+    # Check if it's an OAuthProvider (has OAuth server capability)
+    if isinstance(auth, OAuthProvider):
+        # OAuthProvider: create standard OAuth routes first
+        standard_routes = list(
+            create_auth_routes(
+                provider=auth,
+                issuer_url=auth.issuer_url,
+                service_documentation_url=auth.service_documentation_url,
+                client_registration_options=auth.client_registration_options,
+                revocation_options=auth.revocation_options,
+            )
         )
-    )
+
+        # Allow provider to customize routes (e.g., for proxy behavior or metadata endpoints)
+        auth_routes = auth.customize_auth_routes(standard_routes)
+    else:
+        # Simple AuthProvider or TokenVerifier: start with empty routes
+        # Allow provider to add custom routes (e.g., metadata endpoints)
+        auth_routes = auth.customize_auth_routes([])
 
     return middleware, auth_routes, required_scopes
 
@@ -139,7 +148,7 @@ def create_sse_app(
     server: FastMCP[LifespanResultT],
     message_path: str,
     sse_path: str,
-    auth: OAuthProvider | None = None,
+    auth: AuthProvider | None = None,
     debug: bool = False,
     routes: list[BaseRoute] | None = None,
     middleware: list[Middleware] | None = None,
@@ -150,7 +159,7 @@ def create_sse_app(
         server: The FastMCP server instance
         message_path: Path for SSE messages
         sse_path: Path for SSE connections
-        auth: Optional auth provider
+        auth: Optional authentication provider (AuthProvider)
         debug: Whether to enable debug mode
         routes: Optional list of custom routes
         middleware: Optional list of middleware
@@ -175,8 +184,6 @@ def create_sse_app(
         return Response()
 
     # Get auth middleware and routes
-
-    # Add SSE routes with or without auth
     if auth:
         auth_middleware, auth_routes, required_scopes = (
             setup_auth_middleware_and_routes(auth)
@@ -184,18 +191,32 @@ def create_sse_app(
 
         server_routes.extend(auth_routes)
         server_middleware.extend(auth_middleware)
+
+        # Determine resource_metadata_url for TokenVerifier
+        resource_metadata_url = None
+        if isinstance(auth, TokenVerifier) and auth.resource_server_url:
+            # Add .well-known path for RFC 9728 compliance
+            resource_metadata_url = AnyHttpUrl(
+                str(auth.resource_server_url).rstrip("/")
+                + "/.well-known/oauth-protected-resource"
+            )
+
         # Auth is enabled, wrap endpoints with RequireAuthMiddleware
         server_routes.append(
             Route(
                 sse_path,
-                endpoint=RequireAuthMiddleware(handle_sse, required_scopes),
+                endpoint=RequireAuthMiddleware(
+                    handle_sse, required_scopes, resource_metadata_url
+                ),
                 methods=["GET"],
             )
         )
         server_routes.append(
             Mount(
                 message_path,
-                app=RequireAuthMiddleware(sse.handle_post_message, required_scopes),
+                app=RequireAuthMiddleware(
+                    sse.handle_post_message, required_scopes, resource_metadata_url
+                ),
             )
         )
     else:
@@ -243,7 +264,7 @@ def create_streamable_http_app(
     server: FastMCP[LifespanResultT],
     streamable_http_path: str,
     event_store: EventStore | None = None,
-    auth: OAuthProvider | None = None,
+    auth: AuthProvider | None = None,
     json_response: bool = False,
     stateless_http: bool = False,
     debug: bool = False,
@@ -256,7 +277,7 @@ def create_streamable_http_app(
         server: The FastMCP server instance
         streamable_http_path: Path for StreamableHTTP connections
         event_store: Optional event store for session management
-        auth: Optional auth provider
+        auth: Optional authentication provider (AuthProvider)
         json_response: Whether to use JSON response format
         stateless_http: Whether to use stateless mode (new transport per request)
         debug: Whether to enable debug mode
@@ -314,11 +335,22 @@ def create_streamable_http_app(
         server_routes.extend(auth_routes)
         server_middleware.extend(auth_middleware)
 
+        # Determine resource_metadata_url for TokenVerifier
+        resource_metadata_url = None
+        if isinstance(auth, TokenVerifier) and auth.resource_server_url:
+            # Add .well-known path for RFC 9728 compliance
+            resource_metadata_url = AnyHttpUrl(
+                str(auth.resource_server_url).rstrip("/")
+                + "/.well-known/oauth-protected-resource"
+            )
+
         # Auth is enabled, wrap endpoint with RequireAuthMiddleware
         server_routes.append(
             Mount(
                 streamable_http_path,
-                app=RequireAuthMiddleware(handle_streamable_http, required_scopes),
+                app=RequireAuthMiddleware(
+                    handle_streamable_http, required_scopes, resource_metadata_url
+                ),
             )
         )
     else: