refactor: integrate token exchange into unified get_client() pattern

Resolves the token exchange implementation gap where get_session_client()
was implemented but never used by tools. Unifies token acquisition into a
single async get_client() method that handles both pass-through and token
exchange modes transparently.

Core Changes:
- Make get_client() async and merge token exchange logic into it
- Remove scopes parameter from token exchange (Nextcloud doesn't support OAuth scopes)
- Update all 8 tool modules to use await get_client(ctx)
- Fix provisioning decorator to skip checks in BasicAuth mode

Token Acquisition Modes:
1. BasicAuth: Returns shared client (no token operations)
2. OAuth pass-through (default): Verifies and passes Flow 1 token to Nextcloud
3. OAuth token exchange (opt-in): Exchanges Flow 1 token for ephemeral token via RFC 8693

Key Architectural Clarifications:
- Progressive Consent (Flow 1/2) = Authorization architecture
- Token Exchange = Token acquisition pattern during tool execution
- Refresh tokens from Flow 2 are NEVER used for tool calls (only background jobs)
- Nextcloud scopes are "soft-scopes" enforced by MCP server, not IdP

Documentation Updates:
- ADR-004: Added comprehensive token acquisition patterns section
- CRITICAL-TOKEN-EXCHANGE-PATTERN.md: Updated to reflect implementation status
- CLAUDE.md: Updated architectural patterns with async get_client()

Testing:
- All 36 unit tests passing
- All 4 smoke tests passing (BasicAuth mode)
- Linting issues fixed (ruff)

Configuration:
ENABLE_TOKEN_EXCHANGE=false (default) - pass-through mode
ENABLE_TOKEN_EXCHANGE=true (opt-in) - token exchange mode

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

nextcloud_mcp_server/auth/context_helper.py

@@ -6,6 +6,8 @@ from mcp.server.auth.provider import AccessToken
 from mcp.server.fastmcp import Context
 
 from ..client import NextcloudClient
+from ..config import get_settings
+from .token_exchange import exchange_token_for_delegation
 
 logger = logging.getLogger(__name__)
 
@@ -63,3 +65,85 @@ def get_client_from_context(ctx: Context, base_url: str) -> NextcloudClient:
         logger.error(f"Failed to extract OAuth context: {e}")
         logger.error("This may indicate the server is not running in OAuth mode")
         raise
+
+
+async def get_session_client_from_context(
+    ctx: Context, base_url: str
+) -> NextcloudClient:
+    """
+    Create NextcloudClient using RFC 8693 token exchange for session operations.
+
+    This implements the token exchange pattern where:
+    1. Extract Flow 1 token from context (aud: "mcp-server")
+    2. Exchange it for ephemeral Nextcloud token via RFC 8693
+    3. Create client with delegated token (NOT stored)
+
+    Note: Nextcloud doesn't support OAuth scopes natively. Scopes are enforced
+    by the MCP server via @require_scopes decorator, not by the IdP. Therefore,
+    we don't pass scopes to the token exchange - the MCP server already validated
+    permissions before calling this function.
+
+    Args:
+        ctx: MCP request context containing session info
+        base_url: Nextcloud base URL
+
+    Returns:
+        NextcloudClient configured with ephemeral delegated token
+
+    Raises:
+        AttributeError: If context doesn't contain expected OAuth session data
+        RuntimeError: If token exchange fails
+    """
+    settings = get_settings()
+
+    # Check if token exchange is enabled
+    if not settings.enable_token_exchange:
+        logger.info("Token exchange disabled, falling back to standard OAuth flow")
+        return get_client_from_context(ctx, base_url)
+
+    try:
+        # Extract Flow 1 token from context
+        if hasattr(ctx.request_context.request, "user") and hasattr(
+            ctx.request_context.request.user, "access_token"
+        ):
+            access_token: AccessToken = ctx.request_context.request.user.access_token
+            flow1_token = access_token.token
+            username = access_token.resource  # Username stored during verification
+            logger.debug(f"Retrieved Flow 1 token for user: {username}")
+        else:
+            logger.error("No Flow 1 token found in request context")
+            raise AttributeError("No access token found in OAuth request context")
+
+        if not username:
+            logger.error("No username found in access token resource field")
+            raise ValueError("Username not available in OAuth token context")
+
+        logger.info("Exchanging Flow 1 token for ephemeral Nextcloud token")
+
+        # Perform RFC 8693 token exchange
+        # Note: We don't pass scopes since Nextcloud doesn't enforce them.
+        # The MCP server's @require_scopes decorator handles authorization.
+        delegated_token, expires_in = await exchange_token_for_delegation(
+            flow1_token=flow1_token,
+            requested_scopes=None,  # Nextcloud doesn't support scopes
+            requested_audience="nextcloud",
+        )
+
+        logger.info(
+            f"Token exchange successful. Ephemeral token expires in {expires_in}s"
+        )
+
+        # Create client with ephemeral delegated token
+        # This token is NOT stored and will be discarded after use
+        return NextcloudClient.from_token(
+            base_url=base_url, token=delegated_token, username=username
+        )
+
+    except AttributeError as e:
+        logger.error(f"Failed to extract OAuth context: {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Token exchange failed: {e}")
+        # Fall back to standard OAuth flow if token exchange fails
+        logger.info("Falling back to standard OAuth flow")
+        return get_client_from_context(ctx, base_url)

nextcloud_mcp_server/auth/provisioning_decorator.py

@@ -55,6 +55,15 @@ def require_provisioning(func: Callable) -> Callable:
                 )
             )
 
+        # Check if we're in BasicAuth mode - if so, skip provisioning check
+        # In BasicAuth mode, there's no OAuth and no provisioning needed
+        lifespan_ctx = ctx.request_context.lifespan_context
+        if hasattr(lifespan_ctx, "client"):
+            # BasicAuth mode - no provisioning needed, just proceed
+            logger.debug("BasicAuth mode detected - skipping provisioning check")
+            return await func(*args, **kwargs)
+
+        # OAuth mode - check provisioning
         # Get user_id from authorization token
         user_id = None
         if hasattr(ctx, "authorization") and ctx.authorization:

nextcloud_mcp_server/auth/token_broker.py

@@ -11,6 +11,7 @@ The Token Broker provides:
 - Short-lived token caching (5-minute TTL)
 - Master refresh token rotation
 - Audience-specific token validation
+- Session vs background token separation (RFC 8693)
 """
 
 import asyncio
@@ -23,6 +24,7 @@ import jwt
 from cryptography.fernet import Fernet
 
 from nextcloud_mcp_server.auth.refresh_token_storage import RefreshTokenStorage
+from nextcloud_mcp_server.auth.token_exchange import exchange_token_for_delegation
 
 logger = logging.getLogger(__name__)
 
@@ -150,6 +152,10 @@ class TokenBrokerService:
         """
         Get a valid Nextcloud access token for the user.
 
+        DEPRECATED: This method uses the old pattern of stored refresh tokens
+        for all operations. Use get_session_token() or get_background_token()
+        instead for proper session/background separation.
+
         This method:
         1. Checks the cache for a valid token
         2. If not cached, checks for stored refresh token
@@ -192,10 +198,119 @@ class TokenBrokerService:
             await self.cache.invalidate(user_id)
             return None
 
+    async def get_session_token(
+        self,
+        flow1_token: str,
+        required_scopes: list[str],
+        requested_audience: str = "nextcloud",
+    ) -> Optional[str]:
+        """
+        Get ephemeral token for MCP session operations (on-demand).
+
+        This implements the correct Progressive Consent pattern where:
+        1. Client provides Flow 1 token (aud: "mcp-server")
+        2. Server exchanges it for ephemeral Nextcloud token
+        3. Token is NOT stored, only used for current operation
+
+        Key properties:
+        - On-demand generation during tool execution
+        - Ephemeral (not stored, discarded after use)
+        - Limited scopes (only what tool needs)
+        - Short-lived (5 minutes)
+
+        Args:
+            flow1_token: The MCP session token (aud: "mcp-server")
+            required_scopes: Minimal scopes needed for this operation
+            requested_audience: Target audience (usually "nextcloud")
+
+        Returns:
+            Ephemeral Nextcloud access token or None if exchange fails
+        """
+        try:
+            # Perform RFC 8693 token exchange
+            delegated_token, expires_in = await exchange_token_for_delegation(
+                flow1_token=flow1_token,
+                requested_scopes=required_scopes,
+                requested_audience=requested_audience,
+            )
+
+            # NOTE: We intentionally do NOT cache session tokens
+            # They are ephemeral and should be discarded after use
+            logger.info(
+                f"Generated ephemeral session token with scopes: {required_scopes}, "
+                f"expires in {expires_in}s"
+            )
+
+            return delegated_token
+
+        except Exception as e:
+            logger.error(f"Failed to get session token: {e}")
+            return None
+
+    async def get_background_token(
+        self, user_id: str, required_scopes: list[str]
+    ) -> Optional[str]:
+        """
+        Get token for background job operations (uses stored refresh token).
+
+        This is for background/offline operations that run without user interaction.
+        Uses the stored refresh token from Flow 2 provisioning.
+
+        Key properties:
+        - Uses stored refresh token from Flow 2
+        - Different scopes than session tokens
+        - Longer-lived for background operations
+        - Can be cached for efficiency
+
+        Args:
+            user_id: The user identifier
+            required_scopes: Scopes needed for background operation
+
+        Returns:
+            Nextcloud access token for background operations or None if not provisioned
+        """
+        # Check cache first (background tokens can be cached)
+        cache_key = f"{user_id}:background:{','.join(sorted(required_scopes))}"
+        cached_token = await self.cache.get(cache_key)
+        if cached_token:
+            return cached_token
+
+        # Get stored refresh token
+        refresh_data = await self.storage.get_refresh_token(user_id)
+        if not refresh_data:
+            logger.info(f"No refresh token found for user {user_id}")
+            return None
+
+        try:
+            # Decrypt refresh token
+            encrypted_token = refresh_data["refresh_token"]
+            refresh_token = self.fernet.decrypt(encrypted_token.encode()).decode()
+
+            # Get token with specific scopes for background operation
+            access_token, expires_in = await self._refresh_access_token_with_scopes(
+                refresh_token, required_scopes
+            )
+
+            # Cache the background token
+            await self.cache.set(cache_key, access_token, expires_in)
+
+            logger.info(
+                f"Generated background token for user {user_id} with scopes: {required_scopes}"
+            )
+
+            return access_token
+
+        except Exception as e:
+            logger.error(f"Failed to get background token for user {user_id}: {e}")
+            await self.cache.invalidate(cache_key)
+            return None
+
     async def _refresh_access_token(self, refresh_token: str) -> Tuple[str, int]:
         """
         Exchange refresh token for new access token.
 
+        DEPRECATED: Use _refresh_access_token_with_scopes() for scope-specific requests.
+
         Args:
             refresh_token: The refresh token
 
@@ -236,6 +351,60 @@ class TokenBrokerService:
         logger.info(f"Refreshed access token (expires in {expires_in}s)")
         return access_token, expires_in
 
+    async def _refresh_access_token_with_scopes(
+        self, refresh_token: str, required_scopes: list[str]
+    ) -> Tuple[str, int]:
+        """
+        Exchange refresh token for new access token with specific scopes.
+
+        This method implements scope downscoping for least privilege.
+
+        Args:
+            refresh_token: The refresh token
+            required_scopes: Minimal scopes needed for this operation
+
+        Returns:
+            Tuple of (access_token, expires_in_seconds)
+        """
+        config = await self._get_oidc_config()
+        token_endpoint = config["token_endpoint"]
+
+        client = await self._get_http_client()
+
+        # Always include basic OpenID scopes
+        scopes = list(set(["openid", "profile", "email"] + required_scopes))
+
+        # Request new access token with specific scopes
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "scope": " ".join(scopes),
+        }
+
+        response = await client.post(
+            token_endpoint,
+            data=data,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+
+        if response.status_code != 200:
+            logger.error(
+                f"Token refresh with scopes failed: {response.status_code} - {response.text}"
+            )
+            raise Exception(f"Token refresh failed: {response.status_code}")
+
+        token_data = response.json()
+        access_token = token_data["access_token"]
+        expires_in = token_data.get("expires_in", 3600)  # Default 1 hour
+
+        # Validate audience
+        await self._validate_token_audience(access_token, "nextcloud")
+
+        logger.info(
+            f"Refreshed access token with scopes {scopes} (expires in {expires_in}s)"
+        )
+        return access_token, expires_in
+
     async def _validate_token_audience(self, token: str, expected_audience: str):
         """
         Validate that token has correct audience claim.

nextcloud_mcp_server/auth/token_exchange.py

@@ -0,0 +1,445 @@
+"""RFC 8693 Token Exchange implementation for ADR-004 Progressive Consent.
+
+This module implements the token exchange pattern to convert Flow 1 MCP tokens
+(aud: "mcp-server") into ephemeral delegated Nextcloud tokens (aud: "nextcloud")
+for session operations.
+
+Key Properties:
+- On-demand generation during tool execution
+- Ephemeral tokens (NOT stored, discarded after use)
+- Limited scopes (only what tool needs)
+- Short-lived (5 minutes default)
+"""
+
+import logging
+import time
+from typing import Any, Dict, Optional, Tuple
+from urllib.parse import urljoin
+
+import httpx
+import jwt
+
+from ..config import get_settings
+from .refresh_token_storage import RefreshTokenStorage
+
+logger = logging.getLogger(__name__)
+
+
+class TokenExchangeService:
+    """Implements RFC 8693 OAuth 2.0 Token Exchange."""
+
+    # RFC 8693 Token Type Identifiers
+    TOKEN_TYPE_ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token"
+    TOKEN_TYPE_JWT = "urn:ietf:params:oauth:token-type:jwt"
+    TOKEN_TYPE_ID_TOKEN = "urn:ietf:params:oauth:token-type:id_token"
+
+    def __init__(
+        self,
+        oidc_discovery_url: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        nextcloud_host: Optional[str] = None,
+    ):
+        """Initialize token exchange service.
+
+        Args:
+            oidc_discovery_url: OIDC discovery endpoint URL
+            client_id: OAuth client ID for token exchange
+            client_secret: OAuth client secret
+            nextcloud_host: Nextcloud instance URL
+        """
+        settings = get_settings()
+        self.oidc_discovery_url = oidc_discovery_url or settings.oidc_discovery_url
+        self.client_id = client_id or settings.oidc_client_id
+        self.client_secret = client_secret or settings.oidc_client_secret
+        self.nextcloud_host = nextcloud_host or settings.nextcloud_host
+
+        self._token_endpoint: Optional[str] = None
+        self._jwks_uri: Optional[str] = None
+        self._discovery_cache: Optional[Dict[str, Any]] = None
+        self._discovery_cache_time: float = 0
+        self._discovery_cache_ttl: float = 3600  # 1 hour
+
+        # Initialize storage for checking provisioning
+        self.storage = RefreshTokenStorage()
+
+        # Create HTTP client
+        self.http_client = httpx.AsyncClient(
+            timeout=30.0,
+            follow_redirects=True,
+        )
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        await self.storage.initialize()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()
+
+    async def close(self):
+        """Close HTTP client and storage."""
+        await self.http_client.aclose()
+        # RefreshTokenStorage doesn't have a close method
+
+    async def _discover_endpoints(self) -> Dict[str, Any]:
+        """Discover OIDC endpoints from discovery URL.
+
+        Returns:
+            Discovery document containing endpoint URLs
+        """
+        # Check cache
+        if (
+            self._discovery_cache
+            and (time.time() - self._discovery_cache_time) < self._discovery_cache_ttl
+        ):
+            return self._discovery_cache
+
+        if not self.oidc_discovery_url:
+            # Fallback to Nextcloud OIDC if no discovery URL
+            self.oidc_discovery_url = urljoin(
+                self.nextcloud_host, "/.well-known/openid-configuration"
+            )
+
+        try:
+            response = await self.http_client.get(self.oidc_discovery_url)
+            response.raise_for_status()
+
+            self._discovery_cache = response.json()
+            self._discovery_cache_time = time.time()
+
+            # Cache frequently used endpoints
+            self._token_endpoint = self._discovery_cache.get("token_endpoint")
+            self._jwks_uri = self._discovery_cache.get("jwks_uri")
+
+            return self._discovery_cache
+
+        except Exception as e:
+            logger.error(f"Failed to discover OIDC endpoints: {e}")
+            raise
+
+    async def exchange_token_for_delegation(
+        self,
+        flow1_token: str,
+        requested_scopes: list[str],
+        requested_audience: str = "nextcloud",
+    ) -> Tuple[str, int]:
+        """Exchange Flow 1 MCP token for delegated Nextcloud token.
+
+        This implements RFC 8693 Token Exchange for on-behalf-of delegation.
+
+        Args:
+            flow1_token: The MCP session token (aud: "mcp-server")
+            requested_scopes: Scopes needed for this operation
+            requested_audience: Target audience (usually "nextcloud")
+
+        Returns:
+            Tuple of (delegated_token, expires_in)
+
+        Raises:
+            ValueError: If token validation fails
+            RuntimeError: If provisioning not completed or exchange fails
+        """
+        # 1. Validate Flow 1 token audience
+        await self._validate_flow1_token(flow1_token)
+
+        # 2. Extract user ID from token
+        user_id = self._extract_user_id(flow1_token)
+
+        # 3. Check user has provisioned Nextcloud access (Flow 2)
+        if not await self._check_provisioning(user_id):
+            raise RuntimeError(
+                "Nextcloud access not provisioned. "
+                "User must complete Flow 2 provisioning first."
+            )
+
+        # 4. Get stored refresh token for user (from Flow 2)
+        refresh_token = await self._get_user_refresh_token(user_id)
+        if not refresh_token:
+            raise RuntimeError(
+                "No refresh token found. User must complete provisioning."
+            )
+
+        # 5. Perform token exchange with IdP
+        delegated_token, expires_in = await self._perform_token_exchange(
+            subject_token=flow1_token,
+            refresh_token=refresh_token,
+            requested_scopes=requested_scopes,
+            requested_audience=requested_audience,
+        )
+
+        # 6. Log the exchange for audit trail
+        logger.info(
+            f"Token exchange completed for user {user_id}: "
+            f"scopes={requested_scopes}, audience={requested_audience}, "
+            f"expires_in={expires_in}s"
+        )
+
+        return delegated_token, expires_in
+
+    async def _validate_flow1_token(self, token: str):
+        """Validate that token has correct audience for MCP server.
+
+        Args:
+            token: JWT token to validate
+
+        Raises:
+            ValueError: If token is invalid or has wrong audience
+        """
+        try:
+            # Decode without verification first to check audience
+            # In production, should verify signature against JWKS
+            payload = jwt.decode(token, options={"verify_signature": False})
+
+            # Check audience
+            audience = payload.get("aud", [])
+            if isinstance(audience, str):
+                audience = [audience]
+
+            if "mcp-server" not in audience:
+                raise ValueError(
+                    f"Invalid token audience. Expected 'mcp-server', got {audience}"
+                )
+
+            # Check expiration
+            exp = payload.get("exp", 0)
+            if exp < time.time():
+                raise ValueError("Token has expired")
+
+        except jwt.DecodeError as e:
+            raise ValueError(f"Invalid JWT token: {e}")
+
+    def _extract_user_id(self, token: str) -> str:
+        """Extract user ID from JWT token.
+
+        Args:
+            token: JWT token
+
+        Returns:
+            User ID from token
+        """
+        try:
+            payload = jwt.decode(token, options={"verify_signature": False})
+
+            # Try standard claims in order of preference
+            user_id = (
+                payload.get("sub")
+                or payload.get("preferred_username")
+                or payload.get("email")
+                or payload.get("name")
+            )
+
+            if not user_id:
+                raise ValueError("No user identifier in token")
+
+            return user_id
+
+        except jwt.DecodeError as e:
+            raise ValueError(f"Failed to extract user ID: {e}")
+
+    async def _check_provisioning(self, user_id: str) -> bool:
+        """Check if user has completed Flow 2 provisioning.
+
+        Args:
+            user_id: User identifier
+
+        Returns:
+            True if provisioned, False otherwise
+        """
+        token_data = await self.storage.get_refresh_token(user_id)
+        return token_data is not None
+
+    async def _get_user_refresh_token(self, user_id: str) -> Optional[str]:
+        """Get stored refresh token for user from Flow 2 provisioning.
+
+        Args:
+            user_id: User identifier
+
+        Returns:
+            Refresh token if found, None otherwise
+        """
+        token_data = await self.storage.get_refresh_token(user_id)
+        if token_data:
+            return token_data.get("refresh_token")
+        return None
+
+    async def _perform_token_exchange(
+        self,
+        subject_token: str,
+        refresh_token: str,
+        requested_scopes: list[str],
+        requested_audience: str,
+    ) -> Tuple[str, int]:
+        """Perform RFC 8693 token exchange with IdP.
+
+        Args:
+            subject_token: The token being exchanged (Flow 1 token)
+            refresh_token: User's stored refresh token for delegation
+            requested_scopes: Minimal scopes for this operation
+            requested_audience: Target audience
+
+        Returns:
+            Tuple of (access_token, expires_in)
+        """
+        # Discover token endpoint
+        discovery = await self._discover_endpoints()
+        token_endpoint = discovery.get("token_endpoint")
+
+        if not token_endpoint:
+            raise RuntimeError("No token endpoint found in discovery")
+
+        # Build token exchange request per RFC 8693
+        data = {
+            # Token exchange grant type
+            "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+            # The token we're exchanging (Flow 1 MCP token)
+            "subject_token": subject_token,
+            "subject_token_type": self.TOKEN_TYPE_ACCESS_TOKEN,
+            # Use refresh token as actor token (proves we have delegation rights)
+            "actor_token": refresh_token,
+            "actor_token_type": self.TOKEN_TYPE_ACCESS_TOKEN,
+            # Requested token properties
+            "requested_token_type": self.TOKEN_TYPE_ACCESS_TOKEN,
+            "audience": requested_audience,
+            "scope": " ".join(requested_scopes),
+        }
+
+        # Add client credentials if configured
+        if self.client_id and self.client_secret:
+            data["client_id"] = self.client_id
+            data["client_secret"] = self.client_secret
+
+        try:
+            # Attempt RFC 8693 token exchange
+            response = await self.http_client.post(
+                token_endpoint,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+
+            if response.status_code == 400:
+                # Token exchange might not be supported, fall back to refresh grant
+                logger.info(
+                    "Token exchange not supported, falling back to refresh grant"
+                )
+                return await self._fallback_refresh_grant(
+                    refresh_token=refresh_token,
+                    requested_scopes=requested_scopes,
+                    token_endpoint=token_endpoint,
+                )
+
+            response.raise_for_status()
+            result = response.json()
+
+            access_token = result.get("access_token")
+            expires_in = result.get("expires_in", 300)  # Default 5 minutes
+
+            if not access_token:
+                raise RuntimeError("No access token in exchange response")
+
+            return access_token, expires_in
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Token exchange failed: {e.response.text}")
+            raise RuntimeError(f"Token exchange failed: {e}")
+        except Exception as e:
+            logger.error(f"Token exchange error: {e}")
+            raise
+
+    async def _fallback_refresh_grant(
+        self, refresh_token: str, requested_scopes: list[str], token_endpoint: str
+    ) -> Tuple[str, int]:
+        """Fallback to standard refresh token grant if token exchange not supported.
+
+        This is less secure than token exchange but provides compatibility.
+
+        Args:
+            refresh_token: User's stored refresh token
+            requested_scopes: Minimal scopes for this operation
+            token_endpoint: Token endpoint URL
+
+        Returns:
+            Tuple of (access_token, expires_in)
+        """
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "scope": " ".join(requested_scopes),  # Request minimal scopes
+        }
+
+        # Add client credentials if configured
+        if self.client_id and self.client_secret:
+            data["client_id"] = self.client_id
+            data["client_secret"] = self.client_secret
+
+        try:
+            response = await self.http_client.post(
+                token_endpoint,
+                data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+            response.raise_for_status()
+
+            result = response.json()
+
+            access_token = result.get("access_token")
+            expires_in = result.get("expires_in", 300)  # Default 5 minutes
+
+            if not access_token:
+                raise RuntimeError("No access token in refresh response")
+
+            # Log that we're using fallback
+            logger.warning(
+                f"Using refresh grant fallback for token exchange. "
+                f"Scopes: {requested_scopes}"
+            )
+
+            return access_token, expires_in
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Refresh grant failed: {e.response.text}")
+            raise RuntimeError(f"Refresh grant failed: {e}")
+        except Exception as e:
+            logger.error(f"Refresh grant error: {e}")
+            raise
+
+
+# Singleton instance
+_token_exchange_service: Optional[TokenExchangeService] = None
+
+
+async def get_token_exchange_service() -> TokenExchangeService:
+    """Get or create the singleton token exchange service.
+
+    Returns:
+        TokenExchangeService instance
+    """
+    global _token_exchange_service
+
+    if _token_exchange_service is None:
+        _token_exchange_service = TokenExchangeService()
+        await _token_exchange_service.storage.initialize()
+
+    return _token_exchange_service
+
+
+async def exchange_token_for_delegation(
+    flow1_token: str, requested_scopes: list[str], requested_audience: str = "nextcloud"
+) -> Tuple[str, int]:
+    """Convenience function to exchange tokens.
+
+    Args:
+        flow1_token: The MCP session token (aud: "mcp-server")
+        requested_scopes: Scopes needed for this operation
+        requested_audience: Target audience (usually "nextcloud")
+
+    Returns:
+        Tuple of (delegated_token, expires_in)
+    """
+    service = await get_token_exchange_service()
+    return await service.exchange_token_for_delegation(
+        flow1_token=flow1_token,
+        requested_scopes=requested_scopes,
+        requested_audience=requested_audience,
+    )

nextcloud_mcp_server/config.py

@@ -1,6 +1,7 @@
 import logging.config
 import os
-from typing import Any
+from dataclasses import dataclass
+from typing import Any, Optional
 
 LOGGING_CONFIG = {
     "version": 1,
@@ -118,3 +119,58 @@ def get_document_processor_config() -> dict[str, Any]:
             }
 
     return config
+
+
+@dataclass
+class Settings:
+    """Application settings from environment variables."""
+
+    # OAuth/OIDC settings
+    oidc_discovery_url: Optional[str] = None
+    oidc_client_id: Optional[str] = None
+    oidc_client_secret: Optional[str] = None
+
+    # Nextcloud settings
+    nextcloud_host: Optional[str] = None
+    nextcloud_username: Optional[str] = None
+    nextcloud_password: Optional[str] = None
+
+    # Progressive Consent settings
+    enable_progressive_consent: bool = False
+    enable_token_exchange: bool = False
+    enable_offline_access: bool = False
+
+    # Token settings
+    token_encryption_key: Optional[str] = None
+    token_storage_db: Optional[str] = None
+
+
+def get_settings() -> Settings:
+    """Get application settings from environment variables.
+
+    Returns:
+        Settings object with configuration values
+    """
+    return Settings(
+        # OAuth/OIDC settings
+        oidc_discovery_url=os.getenv("OIDC_DISCOVERY_URL"),
+        oidc_client_id=os.getenv("OIDC_CLIENT_ID"),
+        oidc_client_secret=os.getenv("OIDC_CLIENT_SECRET"),
+        # Nextcloud settings
+        nextcloud_host=os.getenv("NEXTCLOUD_HOST"),
+        nextcloud_username=os.getenv("NEXTCLOUD_USERNAME"),
+        nextcloud_password=os.getenv("NEXTCLOUD_PASSWORD"),
+        # Progressive Consent settings
+        enable_progressive_consent=(
+            os.getenv("ENABLE_PROGRESSIVE_CONSENT", "false").lower() == "true"
+        ),
+        enable_token_exchange=(
+            os.getenv("ENABLE_TOKEN_EXCHANGE", "false").lower() == "true"
+        ),
+        enable_offline_access=(
+            os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() == "true"
+        ),
+        # Token settings
+        token_encryption_key=os.getenv("TOKEN_ENCRYPTION_KEY"),
+        token_storage_db=os.getenv("TOKEN_STORAGE_DB", "/tmp/tokens.db"),
+    )

nextcloud_mcp_server/context.py

@@ -3,14 +3,22 @@
 from mcp.server.fastmcp import Context
 
 from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.config import get_settings
 
 
-def get_client(ctx: Context) -> NextcloudClient:
+async def get_client(ctx: Context) -> NextcloudClient:
     """
     Get the appropriate Nextcloud client based on authentication mode.
 
-    In BasicAuth mode, returns the shared client from lifespan context.
-    In OAuth mode, creates a new client per-request using the OAuth context.
+    This function handles three modes:
+    1. BasicAuth mode: Returns shared client from lifespan context
+    2. OAuth pass-through mode (ENABLE_TOKEN_EXCHANGE=false, default):
+       Verifies Flow 1 token and passes it to Nextcloud
+    3. OAuth token exchange mode (ENABLE_TOKEN_EXCHANGE=true):
+       Exchanges Flow 1 token for ephemeral Nextcloud token via RFC 8693
+
+    Note: Nextcloud doesn't support OAuth scopes natively. Scopes are enforced
+    by the MCP server via @require_scopes decorator, not by the IdP.
 
     This function automatically detects the authentication mode by checking
     the type of the lifespan context.
@@ -28,21 +36,34 @@ def get_client(ctx: Context) -> NextcloudClient:
         ```python
         @mcp.tool()
         async def my_tool(ctx: Context):
-            client = get_client(ctx)
+            client = await get_client(ctx)
             return await client.capabilities()
         ```
     """
+    settings = get_settings()
     lifespan_ctx = ctx.request_context.lifespan_context
 
-    # Try BasicAuth mode first (has 'client' attribute)
+    # BasicAuth mode - use shared client (no token exchange)
     if hasattr(lifespan_ctx, "client"):
         return lifespan_ctx.client
 
     # OAuth mode (has 'nextcloud_host' attribute)
     if hasattr(lifespan_ctx, "nextcloud_host"):
-        from nextcloud_mcp_server.auth import get_client_from_context
+        # Check if token exchange is enabled
+        if settings.enable_token_exchange:
+            from nextcloud_mcp_server.auth.context_helper import (
+                get_session_client_from_context,
+            )
 
-        return get_client_from_context(ctx, lifespan_ctx.nextcloud_host)
+            # Token exchange mode: Exchange Flow 1 token for ephemeral Nextcloud token
+            return await get_session_client_from_context(
+                ctx, lifespan_ctx.nextcloud_host
+            )
+        else:
+            # Pass-through mode (default): Verify and pass Flow 1 token to Nextcloud
+            from nextcloud_mcp_server.auth import get_client_from_context
+
+            return get_client_from_context(ctx, lifespan_ctx.nextcloud_host)
 
     # Unknown context type
     raise AttributeError(

nextcloud_mcp_server/server/calendar.py

@@ -22,7 +22,7 @@ def configure_calendar_tools(mcp: FastMCP):
     @require_scopes("calendar:read")
     async def nc_calendar_list_calendars(ctx: Context) -> ListCalendarsResponse:
         """List all available calendars for the user"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         calendars_data = await client.calendar.list_calendars()
 
         calendars = [Calendar(**cal_data) for cal_data in calendars_data]
@@ -79,7 +79,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Dict with event creation result
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         event_data = {
             "title": title,
@@ -139,7 +139,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             List of events matching the filters
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         # Convert YYYY-MM-DD format dates to datetime objects
         start_datetime = None
@@ -214,7 +214,7 @@ def configure_calendar_tools(mcp: FastMCP):
         ctx: Context,
     ):
         """Get detailed information about a specific event"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         event_data, etag = await client.calendar.get_event(calendar_name, event_uid)
         return event_data
 
@@ -248,7 +248,7 @@ def configure_calendar_tools(mcp: FastMCP):
         etag: str = "",
     ):
         """Update any aspect of an existing event"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         # Build update data with only non-None values
         event_data = {}
@@ -299,7 +299,7 @@ def configure_calendar_tools(mcp: FastMCP):
         ctx: Context,
     ):
         """Delete a calendar event"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.calendar.delete_event(calendar_name, event_uid)
 
     @mcp.tool()
@@ -342,7 +342,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Dict with meeting creation result
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         # Combine date and time for start_datetime
         start_datetime = f"{date}T{time}:00"
@@ -377,7 +377,7 @@ def configure_calendar_tools(mcp: FastMCP):
         limit: int = 10,
     ):
         """Get upcoming events in next N days"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         now = dt.datetime.now()
         end_datetime = now + dt.timedelta(days=days_ahead)
@@ -447,7 +447,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             List of available time slots with start/end times and duration
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         # Parse attendees
         attendee_list = []
@@ -549,7 +549,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Summary of operation results including counts and details
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         if operation not in ["update", "delete", "move"]:
             raise ValueError("Operation must be 'update', 'delete', or 'move'")
@@ -772,7 +772,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Result of the calendar management operation
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         if action == "list":
             return await client.calendar.list_calendars()
@@ -839,7 +839,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             List of todos matching the filters
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         # Build filters dictionary
         filters = {}
@@ -890,7 +890,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Dict with todo creation result
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         todo_data = {
             "summary": summary,
@@ -939,7 +939,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Dict with todo update result
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         # Build update data with only non-None values
         todo_data = {}
@@ -981,7 +981,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Dict with deletion status
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.calendar.delete_todo(calendar_name, todo_uid)
 
     @mcp.tool()
@@ -1005,7 +1005,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             List of todos matching the filters from all calendars
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         # Build filters dictionary
         filters = {}

nextcloud_mcp_server/server/contacts.py

@@ -14,14 +14,14 @@ def configure_contacts_tools(mcp: FastMCP):
     @require_scopes("contacts:read")
     async def nc_contacts_list_addressbooks(ctx: Context):
         """List all addressbooks for the user."""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.contacts.list_addressbooks()
 
     @mcp.tool()
     @require_scopes("contacts:read")
     async def nc_contacts_list_contacts(ctx: Context, *, addressbook: str):
         """List all contacts in the specified addressbook."""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.contacts.list_contacts(addressbook=addressbook)
 
     @mcp.tool()
@@ -35,7 +35,7 @@ def configure_contacts_tools(mcp: FastMCP):
             name: The name of the addressbook.
             display_name: The display name of the addressbook.
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.contacts.create_addressbook(
             name=name, display_name=display_name
         )
@@ -44,7 +44,7 @@ def configure_contacts_tools(mcp: FastMCP):
     @require_scopes("contacts:write")
     async def nc_contacts_delete_addressbook(ctx: Context, *, name: str):
         """Delete an addressbook."""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.contacts.delete_addressbook(name=name)
 
     @mcp.tool()
@@ -59,7 +59,7 @@ def configure_contacts_tools(mcp: FastMCP):
             uid: The unique ID for the contact.
             contact_data: A dictionary with the contact's details, e.g. {"fn": "John Doe", "email": "john.doe@example.com"}.
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.contacts.create_contact(
             addressbook=addressbook, uid=uid, contact_data=contact_data
         )
@@ -68,7 +68,7 @@ def configure_contacts_tools(mcp: FastMCP):
     @require_scopes("contacts:write")
     async def nc_contacts_delete_contact(ctx: Context, *, addressbook: str, uid: str):
         """Delete a contact."""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.contacts.delete_contact(addressbook=addressbook, uid=uid)
 
     @mcp.tool()
@@ -84,7 +84,7 @@ def configure_contacts_tools(mcp: FastMCP):
             contact_data: A dictionary with the contact's updated details, e.g. {"fn": "Jane Doe", "email": "jane.doe@example.com"}.
             etag: Optional ETag for optimistic concurrency control.
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.contacts.update_contact(
             addressbook=addressbook, uid=uid, contact_data=contact_data, etag=etag
         )

nextcloud_mcp_server/server/cookbook.py

@@ -33,7 +33,7 @@ def configure_cookbook_tools(mcp: FastMCP):
     async def cookbook_get_version():
         """Get the Cookbook app and API version"""
         ctx: Context = mcp.get_context()
-        client = get_client(ctx)
+        client = await get_client(ctx)
         version_data = await client.cookbook.get_version()
         return Version(**version_data)
 
@@ -41,7 +41,7 @@ def configure_cookbook_tools(mcp: FastMCP):
     async def cookbook_get_config():
         """Get the Cookbook app configuration"""
         ctx: Context = mcp.get_context()
-        client = get_client(ctx)
+        client = await get_client(ctx)
         config_data = await client.cookbook.get_config()
         return CookbookConfig(**config_data)
 
@@ -49,7 +49,7 @@ def configure_cookbook_tools(mcp: FastMCP):
     async def nc_cookbook_get_recipe_resource(recipe_id: int):
         """Get a recipe by ID using resource URI"""
         ctx: Context = mcp.get_context()
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             recipe_data = await client.cookbook.get_recipe(recipe_id)
             return Recipe(**recipe_data)
@@ -77,7 +77,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
         This extracts recipe data from websites that use schema.org Recipe markup.
         Many popular recipe sites support this standard."""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             recipe_data = await client.cookbook.import_recipe(url)
             recipe = Recipe(**recipe_data)
@@ -131,7 +131,7 @@ def configure_cookbook_tools(mcp: FastMCP):
     @require_scopes("cookbook:read")
     async def nc_cookbook_list_recipes(ctx: Context) -> ListRecipesResponse:
         """Get all recipes in the database"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             recipes_data = await client.cookbook.list_recipes()
             recipes = [RecipeStub(**r) for r in recipes_data]
@@ -156,7 +156,7 @@ def configure_cookbook_tools(mcp: FastMCP):
     @require_scopes("cookbook:read")
     async def nc_cookbook_get_recipe(recipe_id: int, ctx: Context) -> Recipe:
         """Get a specific recipe by its ID"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             recipe_data = await client.cookbook.get_recipe(recipe_id)
             return Recipe(**recipe_data)
@@ -199,7 +199,7 @@ def configure_cookbook_tools(mcp: FastMCP):
         Optional: All other recipe fields following schema.org/Recipe format.
 
         Times should be in ISO8601 duration format (e.g., 'PT30M' for 30 minutes)."""
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         recipe_data = {"name": name}
         if description:
@@ -276,7 +276,7 @@ def configure_cookbook_tools(mcp: FastMCP):
         """Update an existing recipe.
 
         Provide only the fields you want to update. Unspecified fields remain unchanged."""
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         # First get the current recipe
         try:
@@ -352,7 +352,7 @@ def configure_cookbook_tools(mcp: FastMCP):
     ) -> DeleteRecipeResponse:
         """Delete a recipe permanently"""
         logger.info("Deleting recipe %s", recipe_id)
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             message = await client.cookbook.delete_recipe(recipe_id)
             return DeleteRecipeResponse(
@@ -386,7 +386,7 @@ def configure_cookbook_tools(mcp: FastMCP):
         query: str, ctx: Context
     ) -> SearchRecipesResponse:
         """Search for recipes by keywords, tags, and categories"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             recipes_data = await client.cookbook.search_recipes(query)
             recipes = [RecipeStub(**r) for r in recipes_data]
@@ -422,7 +422,7 @@ def configure_cookbook_tools(mcp: FastMCP):
         """Get all known categories.
 
         Note: A category name of '*' indicates recipes with no category."""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             categories_data = await client.cookbook.list_categories()
             categories = [Category(**c) for c in categories_data]
@@ -451,7 +451,7 @@ def configure_cookbook_tools(mcp: FastMCP):
         """Get all recipes in a specific category.
 
         Use '_' as the category name to get recipes with no category."""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             recipes_data = await client.cookbook.get_recipes_in_category(category)
             recipes = [RecipeStub(**r) for r in recipes_data]
@@ -483,7 +483,7 @@ def configure_cookbook_tools(mcp: FastMCP):
     @require_scopes("cookbook:read")
     async def nc_cookbook_list_keywords(ctx: Context) -> ListKeywordsResponse:
         """Get all known keywords/tags"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             keywords_data = await client.cookbook.list_keywords()
             keywords = [Keyword(**k) for k in keywords_data]
@@ -510,7 +510,7 @@ def configure_cookbook_tools(mcp: FastMCP):
         keywords: list[str], ctx: Context
     ) -> ListRecipesResponse:
         """Get all recipes that have specific keywords/tags"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             recipes_data = await client.cookbook.get_recipes_with_keywords(keywords)
             recipes = [RecipeStub(**r) for r in recipes_data]
@@ -552,7 +552,7 @@ def configure_cookbook_tools(mcp: FastMCP):
             folder: Recipe folder path in user's files
             update_interval: Automatic rescan interval in minutes
             print_image: Whether to print images with recipes"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         config_data = {}
         if folder is not None:
@@ -587,7 +587,7 @@ def configure_cookbook_tools(mcp: FastMCP):
         """Trigger a rescan of all recipes into the caching database.
 
         This rebuilds the search index and should be used after manual file changes."""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             message = await client.cookbook.reindex()
             return ReindexResponse(status_code=200, message=message)

nextcloud_mcp_server/server/deck.py

@@ -31,7 +31,7 @@ def configure_deck_tools(mcp: FastMCP):
         """List all Nextcloud Deck boards"""
         ctx: Context = mcp.get_context()
         await ctx.warning("This message is deprecated, use the deck_get_board instead")
-        client = get_client(ctx)
+        client = await get_client(ctx)
         boards = await client.deck.get_boards()
         return [board.model_dump() for board in boards]
 
@@ -42,7 +42,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_board tool instead"
         )
-        client = get_client(ctx)
+        client = await get_client(ctx)
         board = await client.deck.get_board(board_id)
         return board.model_dump()
 
@@ -53,7 +53,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_stacks tool instead"
         )
-        client = get_client(ctx)
+        client = await get_client(ctx)
         stacks = await client.deck.get_stacks(board_id)
         return [stack.model_dump() for stack in stacks]
 
@@ -64,7 +64,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_stack tool instead"
         )
-        client = get_client(ctx)
+        client = await get_client(ctx)
         stack = await client.deck.get_stack(board_id, stack_id)
         return stack.model_dump()
 
@@ -75,7 +75,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_cards tool instead"
         )
-        client = get_client(ctx)
+        client = await get_client(ctx)
         stack = await client.deck.get_stack(board_id, stack_id)
         if stack.cards:
             return [card.model_dump() for card in stack.cards]
@@ -88,7 +88,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_card tool instead"
         )
-        client = get_client(ctx)
+        client = await get_client(ctx)
         card = await client.deck.get_card(board_id, stack_id, card_id)
         return card.model_dump()
 
@@ -99,7 +99,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_labels tool instead"
         )
-        client = get_client(ctx)
+        client = await get_client(ctx)
         board = await client.deck.get_board(board_id)
         return [label.model_dump() for label in board.labels]
 
@@ -110,7 +110,7 @@ def configure_deck_tools(mcp: FastMCP):
         await ctx.warning(
             "This resource is deprecated, use the deck_get_label tool instead"
         )
-        client = get_client(ctx)
+        client = await get_client(ctx)
         label = await client.deck.get_label(board_id, label_id)
         return label.model_dump()
 
@@ -120,7 +120,7 @@ def configure_deck_tools(mcp: FastMCP):
     @require_scopes("deck:read")
     async def deck_get_boards(ctx: Context) -> list[DeckBoard]:
         """Get all Nextcloud Deck boards"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         boards = await client.deck.get_boards()
         return boards
 
@@ -128,7 +128,7 @@ def configure_deck_tools(mcp: FastMCP):
     @require_scopes("deck:read")
     async def deck_get_board(ctx: Context, board_id: int) -> DeckBoard:
         """Get details of a specific Nextcloud Deck board"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         board = await client.deck.get_board(board_id)
         return board
 
@@ -136,7 +136,7 @@ def configure_deck_tools(mcp: FastMCP):
     @require_scopes("deck:read")
     async def deck_get_stacks(ctx: Context, board_id: int) -> list[DeckStack]:
         """Get all stacks in a Nextcloud Deck board"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         stacks = await client.deck.get_stacks(board_id)
         return stacks
 
@@ -144,7 +144,7 @@ def configure_deck_tools(mcp: FastMCP):
     @require_scopes("deck:read")
     async def deck_get_stack(ctx: Context, board_id: int, stack_id: int) -> DeckStack:
         """Get details of a specific Nextcloud Deck stack"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         stack = await client.deck.get_stack(board_id, stack_id)
         return stack
 
@@ -154,7 +154,7 @@ def configure_deck_tools(mcp: FastMCP):
         ctx: Context, board_id: int, stack_id: int
     ) -> list[DeckCard]:
         """Get all cards in a Nextcloud Deck stack"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         stack = await client.deck.get_stack(board_id, stack_id)
         if stack.cards:
             return stack.cards
@@ -166,7 +166,7 @@ def configure_deck_tools(mcp: FastMCP):
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> DeckCard:
         """Get details of a specific Nextcloud Deck card"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         card = await client.deck.get_card(board_id, stack_id, card_id)
         return card
 
@@ -174,7 +174,7 @@ def configure_deck_tools(mcp: FastMCP):
     @require_scopes("deck:read")
     async def deck_get_labels(ctx: Context, board_id: int) -> list[DeckLabel]:
         """Get all labels in a Nextcloud Deck board"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         board = await client.deck.get_board(board_id)
         return board.labels
 
@@ -182,7 +182,7 @@ def configure_deck_tools(mcp: FastMCP):
     @require_scopes("deck:read")
     async def deck_get_label(ctx: Context, board_id: int, label_id: int) -> DeckLabel:
         """Get details of a specific Nextcloud Deck label"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         label = await client.deck.get_label(board_id, label_id)
         return label
 
@@ -199,7 +199,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: The title of the new board
             color: The hexadecimal color of the new board (e.g. FF0000)
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         board = await client.deck.create_board(title, color)
         return CreateBoardResponse(id=board.id, title=board.title, color=board.color)
 
@@ -217,7 +217,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: The title of the new stack
             order: Order for sorting the stacks
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         stack = await client.deck.create_stack(board_id, title, order)
         return CreateStackResponse(id=stack.id, title=stack.title, order=stack.order)
 
@@ -238,7 +238,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: New title for the stack
             order: New order for the stack
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.update_stack(board_id, stack_id, title, order)
         return StackOperationResponse(
             success=True,
@@ -258,7 +258,7 @@ def configure_deck_tools(mcp: FastMCP):
             board_id: The ID of the board
             stack_id: The ID of the stack
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.delete_stack(board_id, stack_id)
         return StackOperationResponse(
             success=True,
@@ -291,7 +291,7 @@ def configure_deck_tools(mcp: FastMCP):
             description: Description of the card
             duedate: Due date of the card (ISO-8601 format)
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         card = await client.deck.create_card(
             board_id, stack_id, title, type, order, description, duedate
         )
@@ -333,7 +333,7 @@ def configure_deck_tools(mcp: FastMCP):
             archived: Whether the card should be archived
             done: Completion date for the card (ISO-8601 format)
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.update_card(
             board_id,
             stack_id,
@@ -367,7 +367,7 @@ def configure_deck_tools(mcp: FastMCP):
             stack_id: The ID of the stack
             card_id: The ID of the card
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.delete_card(board_id, stack_id, card_id)
         return CardOperationResponse(
             success=True,
@@ -389,7 +389,7 @@ def configure_deck_tools(mcp: FastMCP):
             stack_id: The ID of the stack
             card_id: The ID of the card
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.archive_card(board_id, stack_id, card_id)
         return CardOperationResponse(
             success=True,
@@ -411,7 +411,7 @@ def configure_deck_tools(mcp: FastMCP):
             stack_id: The ID of the stack
             card_id: The ID of the card
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.unarchive_card(board_id, stack_id, card_id)
         return CardOperationResponse(
             success=True,
@@ -440,7 +440,7 @@ def configure_deck_tools(mcp: FastMCP):
             order: New position in the target stack
             target_stack_id: The ID of the target stack
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.reorder_card(
             board_id, stack_id, card_id, order, target_stack_id
         )
@@ -465,7 +465,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: The title of the new label
             color: The color of the new label (hex format without #)
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         label = await client.deck.create_label(board_id, title, color)
         return CreateLabelResponse(id=label.id, title=label.title, color=label.color)
 
@@ -486,7 +486,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: New title for the label
             color: New color for the label (hex format without #)
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.update_label(board_id, label_id, title, color)
         return LabelOperationResponse(
             success=True,
@@ -506,7 +506,7 @@ def configure_deck_tools(mcp: FastMCP):
             board_id: The ID of the board
             label_id: The ID of the label
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.delete_label(board_id, label_id)
         return LabelOperationResponse(
             success=True,
@@ -529,7 +529,7 @@ def configure_deck_tools(mcp: FastMCP):
             card_id: The ID of the card
             label_id: The ID of the label to assign
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.assign_label_to_card(board_id, stack_id, card_id, label_id)
         return CardOperationResponse(
             success=True,
@@ -552,7 +552,7 @@ def configure_deck_tools(mcp: FastMCP):
             card_id: The ID of the card
             label_id: The ID of the label to remove
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.remove_label_from_card(board_id, stack_id, card_id, label_id)
         return CardOperationResponse(
             success=True,
@@ -576,7 +576,7 @@ def configure_deck_tools(mcp: FastMCP):
             card_id: The ID of the card
             user_id: The user ID to assign
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.assign_user_to_card(board_id, stack_id, card_id, user_id)
         return CardOperationResponse(
             success=True,
@@ -599,7 +599,7 @@ def configure_deck_tools(mcp: FastMCP):
             card_id: The ID of the card
             user_id: The user ID to unassign
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.deck.unassign_user_from_card(board_id, stack_id, card_id, user_id)
         return CardOperationResponse(
             success=True,

nextcloud_mcp_server/server/notes.py

@@ -29,7 +29,7 @@ def configure_notes_tools(mcp: FastMCP):
         ctx: Context = (
             mcp.get_context()
         )  # https://github.com/modelcontextprotocol/python-sdk/issues/244
-        client = get_client(ctx)
+        client = await get_client(ctx)
         settings_data = await client.notes.get_settings()
         return NotesSettings(**settings_data)
 
@@ -37,7 +37,7 @@ def configure_notes_tools(mcp: FastMCP):
     async def nc_notes_get_attachment_resource(note_id: int, attachment_filename: str):
         """Get a specific attachment from a note"""
         ctx: Context = mcp.get_context()
-        client = get_client(ctx)
+        client = await get_client(ctx)
         # Assuming a method get_note_attachment exists in the client
         # This method should return the raw content and determine the mime type
         content, mime_type = await client.webdav.get_note_attachment(
@@ -59,7 +59,7 @@ def configure_notes_tools(mcp: FastMCP):
         """Get user note using note id"""
 
         ctx: Context = mcp.get_context()
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             note_data = await client.notes.get_note(note_id)
             return Note(**note_data)
@@ -92,7 +92,7 @@ def configure_notes_tools(mcp: FastMCP):
         title: str, content: str, category: str, ctx: Context
     ) -> CreateNoteResponse:
         """Create a new note (requires notes:write scope)"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             note_data = await client.notes.create_note(
                 title=title,
@@ -149,7 +149,7 @@ def configure_notes_tools(mcp: FastMCP):
         If the note has been modified by someone else since you retrieved it,
         the update will fail with a 412 error."""
         logger.info("Updating note %s", note_id)
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             note_data = await client.notes.update(
                 note_id=note_id,
@@ -206,7 +206,7 @@ def configure_notes_tools(mcp: FastMCP):
         between the note and what will be appended."""
 
         logger.info("Appending content to note %s", note_id)
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             note_data = await client.notes.append_content(
                 note_id=note_id, content=content
@@ -252,7 +252,7 @@ def configure_notes_tools(mcp: FastMCP):
     @require_provisioning
     async def nc_notes_search_notes(query: str, ctx: Context) -> SearchNotesResponse:
         """Search notes by title or content, returning only id, title, and category (requires notes:read scope)."""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             search_results_raw = await client.notes_search_notes(query=query)
 
@@ -298,7 +298,7 @@ def configure_notes_tools(mcp: FastMCP):
     @require_scopes("notes:read")
     async def nc_notes_get_note(note_id: int, ctx: Context) -> Note:
         """Get a specific note by its ID (requires notes:read scope)"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             note_data = await client.notes.get_note(note_id)
             return Note(**note_data)
@@ -329,7 +329,7 @@ def configure_notes_tools(mcp: FastMCP):
         note_id: int, attachment_filename: str, ctx: Context
     ) -> dict[str, str]:
         """Get a specific attachment from a note"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             content, mime_type = await client.webdav.get_note_attachment(
                 note_id=note_id, filename=attachment_filename
@@ -374,7 +374,7 @@ def configure_notes_tools(mcp: FastMCP):
     async def nc_notes_delete_note(note_id: int, ctx: Context) -> DeleteNoteResponse:
         """Delete a note permanently"""
         logger.info("Deleting note %s", note_id)
-        client = get_client(ctx)
+        client = await get_client(ctx)
         try:
             await client.notes.delete_note(note_id)
             return DeleteNoteResponse(

nextcloud_mcp_server/server/sharing.py

@@ -45,7 +45,7 @@ def configure_sharing_tools(mcp: FastMCP):
         Returns:
             JSON string with share information including share ID
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         share_data = await client.sharing.create_share(
             path=path,
             share_with=share_with,
@@ -67,7 +67,7 @@ def configure_sharing_tools(mcp: FastMCP):
         Returns:
             JSON string confirming deletion
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         await client.sharing.delete_share(share_id)
         return json.dumps(
             {"success": True, "message": f"Share {share_id} deleted"}, indent=2
@@ -87,7 +87,7 @@ def configure_sharing_tools(mcp: FastMCP):
         Returns:
             JSON string with share information
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         share_data = await client.sharing.get_share(share_id)
         return json.dumps(share_data, indent=2)
 
@@ -106,7 +106,7 @@ def configure_sharing_tools(mcp: FastMCP):
         Returns:
             JSON string with list of shares
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         shares = await client.sharing.list_shares(
             path=path, shared_with_me=shared_with_me
         )
@@ -133,7 +133,7 @@ def configure_sharing_tools(mcp: FastMCP):
         Returns:
             JSON string with updated share information
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         share_data = await client.sharing.update_share(
             share_id=share_id, permissions=permissions
         )

nextcloud_mcp_server/server/tables.py

@@ -14,14 +14,14 @@ def configure_tables_tools(mcp: FastMCP):
     @require_scopes("tables:read")
     async def nc_tables_list_tables(ctx: Context):
         """List all tables available to the user"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.tables.list_tables()
 
     @mcp.tool()
     @require_scopes("tables:read")
     async def nc_tables_get_schema(table_id: int, ctx: Context):
         """Get the schema/structure of a specific table including columns and views"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.tables.get_table_schema(table_id)
 
     @mcp.tool()
@@ -33,7 +33,7 @@ def configure_tables_tools(mcp: FastMCP):
         offset: int | None = None,
     ):
         """Read rows from a table with optional pagination"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.tables.get_table_rows(table_id, limit, offset)
 
     @mcp.tool()
@@ -43,7 +43,7 @@ def configure_tables_tools(mcp: FastMCP):
 
         Data should be a dictionary mapping column IDs to values, e.g. {1: "text", 2: 42}
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.tables.create_row(table_id, data)
 
     @mcp.tool()
@@ -53,12 +53,12 @@ def configure_tables_tools(mcp: FastMCP):
 
         Data should be a dictionary mapping column IDs to new values, e.g. {1: "new text", 2: 99}
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.tables.update_row(row_id, data)
 
     @mcp.tool()
     @require_scopes("tables:write")
     async def nc_tables_delete_row(row_id: int, ctx: Context):
         """Delete a row from a table"""
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.tables.delete_row(row_id)

nextcloud_mcp_server/server/webdav.py

@@ -28,7 +28,7 @@ def configure_webdav_tools(mcp: FastMCP):
         Returns:
             DirectoryListing with files, total_count, directories_count, files_count, and total_size
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         items = await client.webdav.list_directory(path)
 
         # Convert to FileInfo models
@@ -76,7 +76,7 @@ def configure_webdav_tools(mcp: FastMCP):
             result = await nc_webdav_read_file("Images/photo.jpg")
             logger.info(result['encoding'])  # 'base64'
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         content, content_type = await client.webdav.read_file(path)
 
         # Check if this is a parseable document (PDF, DOCX, etc.)
@@ -143,7 +143,7 @@ def configure_webdav_tools(mcp: FastMCP):
         Returns:
             Dict with status_code indicating success
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         # Handle base64 encoded content
         if content_type and "base64" in content_type.lower():
@@ -167,7 +167,7 @@ def configure_webdav_tools(mcp: FastMCP):
         Returns:
             Dict with status_code (201 for created, 405 if already exists)
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.webdav.create_directory(path)
 
     @mcp.tool()
@@ -181,7 +181,7 @@ def configure_webdav_tools(mcp: FastMCP):
         Returns:
             Dict with status_code indicating result (404 if not found)
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.webdav.delete_resource(path)
 
     @mcp.tool()
@@ -199,7 +199,7 @@ def configure_webdav_tools(mcp: FastMCP):
         Returns:
             Dict with status_code indicating result (404 if source not found, 412 if destination exists and overwrite is False)
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.webdav.move_resource(
             source_path, destination_path, overwrite
         )
@@ -219,7 +219,7 @@ def configure_webdav_tools(mcp: FastMCP):
         Returns:
             Dict with status_code indicating result (404 if source not found, 412 if destination exists and overwrite is False)
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         return await client.webdav.copy_resource(
             source_path, destination_path, overwrite
         )
@@ -249,7 +249,7 @@ def configure_webdav_tools(mcp: FastMCP):
         Returns:
             SearchFilesResponse with list of matching files
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
 
         # Build where conditions based on filters
         conditions = []
@@ -355,7 +355,7 @@ def configure_webdav_tools(mcp: FastMCP):
         Returns:
             SearchFilesResponse with list of matching files
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         results = await client.webdav.find_by_name(
             pattern=pattern, scope=scope, limit=limit
         )
@@ -382,7 +382,7 @@ def configure_webdav_tools(mcp: FastMCP):
         Returns:
             SearchFilesResponse with list of matching files
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         results = await client.webdav.find_by_type(
             mime_type=mime_type, scope=scope, limit=limit
         )
@@ -408,7 +408,7 @@ def configure_webdav_tools(mcp: FastMCP):
         Returns:
             SearchFilesResponse with list of favorite files
         """
-        client = get_client(ctx)
+        client = await get_client(ctx)
         results = await client.webdav.list_favorites(scope=scope, limit=limit)
         file_infos = [FileInfo(**result) for result in results]
         return SearchFilesResponse(