fastmcp 2.13.3__py3-none-any.whl → 2.14.1__py3-none-any.whl

fastmcp/client/client.py

@@ -4,6 +4,8 @@ import asyncio
 import copy
 import datetime
 import secrets
+import uuid
+import weakref
 from contextlib import AsyncExitStack, asynccontextmanager
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -14,7 +16,20 @@ import httpx
 import mcp.types
 import pydantic_core
 from exceptiongroup import catch
-from mcp import ClientSession
+from mcp import ClientSession, McpError
+from mcp.types import (
+    CancelTaskRequest,
+    CancelTaskRequestParams,
+    GetTaskPayloadRequest,
+    GetTaskPayloadRequestParams,
+    GetTaskPayloadResult,
+    GetTaskRequest,
+    GetTaskRequestParams,
+    GetTaskResult,
+    ListTasksRequest,
+    PaginatedRequestParams,
+    TaskStatusNotification,
+)
 from pydantic import AnyUrl
 
 import fastmcp
@@ -32,10 +47,15 @@ from fastmcp.client.roots import (
     create_roots_callback,
 )
 from fastmcp.client.sampling import (
-    ClientSamplingHandler,
     SamplingHandler,
     create_sampling_callback,
 )
+from fastmcp.client.tasks import (
+    PromptTask,
+    ResourceTask,
+    TaskNotificationHandler,
+    ToolTask,
+)
 from fastmcp.exceptions import ToolError
 from fastmcp.mcp_config import MCPConfig
 from fastmcp.server import FastMCP
@@ -61,7 +81,6 @@ from .transports import (
 
 __all__ = [
     "Client",
-    "ClientSamplingHandler",
     "ElicitationHandler",
     "LogHandler",
     "MessageHandler",
@@ -77,16 +96,6 @@ logger = get_logger(__name__)
 T = TypeVar("T", bound="ClientTransport")
 
 
-def _timeout_to_seconds(
-    timeout: datetime.timedelta | float | int | None,
-) -> float | None:
-    if timeout is None:
-        return None
-    if isinstance(timeout, datetime.timedelta):
-        return timeout.total_seconds()
-    return float(timeout)
-
-
 @dataclass
 class ClientSessionState:
     """Holds all session-related state for a Client instance.
@@ -104,6 +113,17 @@ class ClientSessionState:
     initialize_result: mcp.types.InitializeResult | None = None
 
 
+@dataclass
+class CallToolResult:
+    """Parsed result from a tool call."""
+
+    content: list[mcp.types.ContentBlock]
+    structured_content: dict[str, Any] | None
+    meta: dict[str, Any] | None
+    data: Any = None
+    is_error: bool = False
+
+
 class Client(Generic[ClientTransportT]):
     """
     MCP client that delegates connection management to a Transport instance.
@@ -226,7 +246,8 @@ class Client(Generic[ClientTransportT]):
         ),
         name: str | None = None,
         roots: RootsList | RootsHandler | None = None,
-        sampling_handler: ClientSamplingHandler | None = None,
+        sampling_handler: SamplingHandler | None = None,
+        sampling_capabilities: mcp.types.SamplingCapability | None = None,
         elicitation_handler: ElicitationHandler | None = None,
         log_handler: LogHandler | None = None,
         message_handler: MessageHandlerT | MessageHandler | None = None,
@@ -258,7 +279,13 @@ class Client(Generic[ClientTransportT]):
         # handle init handshake timeout
         if init_timeout is None:
             init_timeout = fastmcp.settings.client_init_timeout
-        self._init_timeout = _timeout_to_seconds(init_timeout)
+        if isinstance(init_timeout, datetime.timedelta):
+            init_timeout = init_timeout.total_seconds()
+        elif not init_timeout:
+            init_timeout = None
+        else:
+            init_timeout = float(init_timeout)
+        self._init_timeout = init_timeout
 
         self.auto_initialize = auto_initialize
 
@@ -266,7 +293,7 @@ class Client(Generic[ClientTransportT]):
             "sampling_callback": None,
             "list_roots_callback": None,
             "logging_callback": create_log_callback(log_handler),
-            "message_handler": message_handler,
+            "message_handler": message_handler or TaskNotificationHandler(self),
             "read_timeout_seconds": timeout,  # ty: ignore[invalid-argument-type]
             "client_info": client_info,
         }
@@ -278,6 +305,14 @@ class Client(Generic[ClientTransportT]):
             self._session_kwargs["sampling_callback"] = create_sampling_callback(
                 sampling_handler
             )
+            # Default to tools-enabled capabilities unless explicitly overridden
+            self._session_kwargs["sampling_capabilities"] = (
+                sampling_capabilities
+                if sampling_capabilities is not None
+                else mcp.types.SamplingCapability(
+                    tools=mcp.types.SamplingToolsCapability()
+                )
+            )
 
         if elicitation_handler is not None:
             self._session_kwargs["elicitation_callback"] = create_elicitation_callback(
@@ -287,6 +322,29 @@ class Client(Generic[ClientTransportT]):
         # Session context management - see class docstring for detailed explanation
         self._session_state = ClientSessionState()
 
+        # Track task IDs submitted by this client (for list_tasks support)
+        self._submitted_task_ids: set[str] = set()
+
+        # Registry for routing notifications/tasks/status to Task objects
+
+        self._task_registry: dict[
+            str, weakref.ref[ToolTask | PromptTask | ResourceTask]
+        ] = {}
+
+    def _reset_session_state(self, full: bool = False) -> None:
+        """Reset session state after disconnect or cancellation.
+
+        Args:
+            full: If True, also resets session_task and nesting_counter.
+                  Use full=True for cancellation cleanup where the session
+                  task was started but never completed normally.
+        """
+        self._session_state.session = None
+        self._session_state.initialize_result = None
+        if full:
+            self._session_state.session_task = None
+            self._session_state.nesting_counter = 0
+
     @property
     def session(self) -> ClientSession:
         """Get the current active session. Raises RuntimeError if not connected."""
@@ -306,11 +364,21 @@ class Client(Generic[ClientTransportT]):
         """Set the roots for the client. This does not automatically call `send_roots_list_changed`."""
         self._session_kwargs["list_roots_callback"] = create_roots_callback(roots)
 
-    def set_sampling_callback(self, sampling_callback: ClientSamplingHandler) -> None:
+    def set_sampling_callback(
+        self,
+        sampling_callback: SamplingHandler,
+        sampling_capabilities: mcp.types.SamplingCapability | None = None,
+    ) -> None:
         """Set the sampling callback for the client."""
         self._session_kwargs["sampling_callback"] = create_sampling_callback(
             sampling_callback
         )
+        # Default to tools-enabled capabilities unless explicitly overridden
+        self._session_kwargs["sampling_capabilities"] = (
+            sampling_capabilities
+            if sampling_capabilities is not None
+            else mcp.types.SamplingCapability(tools=mcp.types.SamplingToolsCapability())
+        )
 
     def set_elicitation_callback(
         self, elicitation_callback: ElicitationHandler
@@ -359,7 +427,7 @@ class Client(Generic[ClientTransportT]):
                 **self._session_kwargs
             ) as session:
                 self._session_state.session = session
-                # Initialize the session
+                # Initialize the session if auto_initialize is enabled
                 try:
                     if self.auto_initialize:
                         await self.initialize()
@@ -367,14 +435,72 @@ class Client(Generic[ClientTransportT]):
                 except anyio.ClosedResourceError as e:
                     raise RuntimeError("Server session was closed unexpectedly") from e
                 finally:
-                    self._session_state.session = None
-                    self._session_state.initialize_result = None
+                    self._reset_session_state()
+
+    async def initialize(
+        self,
+        timeout: datetime.timedelta | float | int | None = None,
+    ) -> mcp.types.InitializeResult:
+        """Send an initialize request to the server.
+
+        This method performs the MCP initialization handshake with the server,
+        exchanging capabilities and server information. It is idempotent - calling
+        it multiple times returns the cached result from the first call.
+
+        The initialization happens automatically when entering the client context
+        manager unless `auto_initialize=False` was set during client construction.
+        Manual calls to this method are only needed when auto-initialization is disabled.
+
+        Args:
+            timeout: Optional timeout for the initialization request (seconds or timedelta).
+                If None, uses the client's init_timeout setting.
+
+        Returns:
+            InitializeResult: The server's initialization response containing server info,
+                capabilities, protocol version, and optional instructions.
+
+        Raises:
+            RuntimeError: If the client is not connected or initialization times out.
+
+        Example:
+            ```python
+            # With auto-initialization disabled
+            client = Client(server, auto_initialize=False)
+            async with client:
+                result = await client.initialize()
+                print(f"Server: {result.serverInfo.name}")
+                print(f"Instructions: {result.instructions}")
+            ```
+        """
+
+        if self.initialize_result is not None:
+            return self.initialize_result
+
+        if timeout is None:
+            timeout = self._init_timeout
+
+        # Convert timeout if needed
+        if isinstance(timeout, datetime.timedelta):
+            timeout = timeout.total_seconds()
+        elif timeout is not None:
+            timeout = float(timeout)
+
+        try:
+            with anyio.fail_after(timeout):
+                self._session_state.initialize_result = await self.session.initialize()
+                return self._session_state.initialize_result
+        except TimeoutError as e:
+            raise RuntimeError("Failed to initialize server session") from e
 
     async def __aenter__(self):
         return await self._connect()
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
-        await self._disconnect()
+        # Use a timeout to prevent hanging during cleanup if the connection is in a bad
+        # state (e.g., rate-limited). The MCP SDK's transport may try to terminate the
+        # session which can hang if the server is unresponsive.
+        with anyio.move_on_after(5):
+            await self._disconnect()
 
     async def _connect(self):
         """
@@ -406,7 +532,48 @@ class Client(Generic[ClientTransportT]):
                 self._session_state.session_task = asyncio.create_task(
                     self._session_runner()
                 )
-                await self._session_state.ready_event.wait()
+                try:
+                    await self._session_state.ready_event.wait()
+                except asyncio.CancelledError:
+                    # Cancellation during initial connection startup can leave the
+                    # background session task running because __aexit__ is never invoked
+                    # when __aenter__ is cancelled. Since we hold the session lock here
+                    # and we know we started the session task, it's safe to tear it down
+                    # without impacting other active contexts.
+                    #
+                    # Note: session_task is an asyncio.Task (not anyio) because it needs
+                    # to outlive individual context manager scopes - anyio's structured
+                    # concurrency doesn't allow tasks to escape their task group.
+                    session_task = self._session_state.session_task
+                    if session_task is not None:
+                        # Request a graceful stop if the runner has already reached
+                        # its stop_event wait.
+                        self._session_state.stop_event.set()
+                        session_task.cancel()
+                        with anyio.CancelScope(shield=True):
+                            with anyio.move_on_after(3):
+                                try:
+                                    await session_task
+                                except asyncio.CancelledError:
+                                    pass
+                                except Exception as e:
+                                    logger.debug(
+                                        f"Error during cancelled session cleanup: {e}"
+                                    )
+
+                    # Reset session state so future callers can reconnect cleanly.
+                    self._reset_session_state(full=True)
+
+                    with anyio.CancelScope(shield=True):
+                        with anyio.move_on_after(3):
+                            try:
+                                await self.transport.close()
+                            except Exception as e:
+                                logger.debug(
+                                    f"Error closing transport after cancellation: {e}"
+                                )
+
+                    raise
 
                 if self._session_state.session_task.done():
                     exception = self._session_state.session_task.exception()
@@ -414,7 +581,8 @@ class Client(Generic[ClientTransportT]):
                         raise RuntimeError(
                             "Session task completed without exception but connection failed"
                         )
-                    if isinstance(exception, httpx.HTTPStatusError):
+                    # Preserve specific exception types that clients may want to handle
+                    if isinstance(exception, httpx.HTTPStatusError | McpError):
                         raise exception
                     raise RuntimeError(
                         f"Client failed to connect: {exception}"
@@ -487,61 +655,34 @@ class Client(Generic[ClientTransportT]):
             # Ensure ready event is set even if context manager entry fails
             self._session_state.ready_event.set()
 
+    def _handle_task_status_notification(
+        self, notification: TaskStatusNotification
+    ) -> None:
+        """Route task status notification to appropriate Task object.
+
+        Called when notifications/tasks/status is received from server.
+        Updates Task object's cache and triggers events/callbacks.
+        """
+        # Extract task ID from notification params
+        task_id = notification.params.taskId
+        if not task_id:
+            return
+
+        # Look up task in registry (weakref)
+        task_ref = self._task_registry.get(task_id)
+        if task_ref:
+            task = task_ref()  # Dereference weakref
+            if task:
+                # Convert notification params to GetTaskResult (they share the same fields via Task)
+                status = GetTaskResult.model_validate(notification.params.model_dump())
+                task._handle_status_notification(status)
+
     async def close(self):
         await self._disconnect(force=True)
         await self.transport.close()
 
     # --- MCP Client Methods ---
 
-    async def initialize(
-        self,
-        timeout: datetime.timedelta | float | int | None = None,
-    ) -> mcp.types.InitializeResult:
-        """Send an initialize request to the server.
-
-        This method performs the MCP initialization handshake with the server,
-        exchanging capabilities and server information. It is idempotent - calling
-        it multiple times returns the cached result from the first call.
-
-        The initialization happens automatically when entering the client context
-        manager unless `auto_initialize=False` was set during client construction.
-        Manual calls to this method are only needed when auto-initialization is disabled.
-
-        Args:
-            timeout: Optional timeout for the initialization request (seconds or timedelta).
-                If None, uses the client's init_timeout setting.
-
-        Returns:
-            InitializeResult: The server's initialization response containing server info,
-                capabilities, protocol version, and optional instructions.
-
-        Raises:
-            RuntimeError: If the client is not connected or initialization times out.
-
-        Example:
-            ```python
-            # With auto-initialization disabled
-            client = Client(server, auto_initialize=False)
-            async with client:
-                result = await client.initialize()
-                print(f"Server: {result.serverInfo.name}")
-                print(f"Instructions: {result.instructions}")
-            ```
-        """
-
-        if self.initialize_result is not None:
-            return self.initialize_result
-
-        if timeout is None:
-            timeout = self._init_timeout
-        try:
-            with anyio.fail_after(_timeout_to_seconds(timeout)):
-                initialize_result = await self.session.initialize()
-                self._session_state.initialize_result = initialize_result
-                return initialize_result
-        except TimeoutError as e:
-            raise RuntimeError("Failed to initialize server session") from e
-
     async def ping(self) -> bool:
         """Send a ping request."""
         result = await self.session.send_ping()
@@ -645,12 +786,13 @@ class Client(Generic[ClientTransportT]):
         return result.resourceTemplates
 
     async def read_resource_mcp(
-        self, uri: AnyUrl | str
+        self, uri: AnyUrl | str, meta: dict[str, Any] | None = None
     ) -> mcp.types.ReadResourceResult:
         """Send a resources/read request and return the complete MCP protocol result.
 
         Args:
             uri (AnyUrl | str): The URI of the resource to read. Can be a string or an AnyUrl object.
+            meta (dict[str, Any] | None, optional): Request metadata (e.g., for SEP-1686 tasks). Defaults to None.
 
         Returns:
             mcp.types.ReadResourceResult: The complete response object from the protocol,
@@ -663,24 +805,73 @@ class Client(Generic[ClientTransportT]):
 
         if isinstance(uri, str):
             uri = AnyUrl(uri)  # Ensure AnyUrl
-        result = await self.session.read_resource(uri)
+
+        # If meta provided, use send_request for SEP-1686 task support
+        if meta:
+            task_dict = meta.get("modelcontextprotocol.io/task")
+            request = mcp.types.ReadResourceRequest(
+                params=mcp.types.ReadResourceRequestParams(
+                    uri=uri,
+                    task=mcp.types.TaskMetadata(**task_dict)
+                    if task_dict
+                    else None,  # SEP-1686: task as direct param (spec-compliant)
+                )
+            )
+            result = await self.session.send_request(
+                request=request,  # type: ignore[arg-type]
+                result_type=mcp.types.ReadResourceResult,
+            )
+        else:
+            result = await self.session.read_resource(uri)
         return result
 
+    @overload
+    async def read_resource(
+        self,
+        uri: AnyUrl | str,
+        *,
+        task: Literal[False] = False,
+    ) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]: ...
+
+    @overload
     async def read_resource(
-        self, uri: AnyUrl | str
-    ) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]:
+        self,
+        uri: AnyUrl | str,
+        *,
+        task: Literal[True],
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> ResourceTask: ...
+
+    async def read_resource(
+        self,
+        uri: AnyUrl | str,
+        *,
+        task: bool = False,
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> (
+        list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]
+        | ResourceTask
+    ):
         """Read the contents of a resource or resolved template.
 
         Args:
             uri (AnyUrl | str): The URI of the resource to read. Can be a string or an AnyUrl object.
+            task (bool): If True, execute as background task (SEP-1686). Defaults to False.
+            task_id (str | None): Optional client-provided task ID (auto-generated if not provided).
+            ttl (int): Time to keep results available in milliseconds (default 60s).
 
         Returns:
-            list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]: A list of content
-                objects, typically containing either text or binary data.
+            list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents] | ResourceTask:
+                A list of content objects if task=False, or a ResourceTask object if task=True.
 
         Raises:
             RuntimeError: If called while the client is not connected.
         """
+        if task:
+            return await self._read_resource_as_task(uri, task_id, ttl)
+
         if isinstance(uri, str):
             try:
                 uri = AnyUrl(uri)  # Ensure AnyUrl
@@ -691,6 +882,62 @@ class Client(Generic[ClientTransportT]):
         result = await self.read_resource_mcp(uri)
         return result.contents
 
+    async def _read_resource_as_task(
+        self,
+        uri: AnyUrl | str,
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> ResourceTask:
+        """Read a resource for background execution (SEP-1686).
+
+        Returns a ResourceTask object that handles both background and immediate execution.
+
+        Args:
+            uri: Resource URI to read
+            task_id: Optional client-provided task ID (ignored, for backward compatibility)
+            ttl: Time to keep results available in milliseconds (default 60s)
+
+        Returns:
+            ResourceTask: Future-like object for accessing task status and results
+        """
+        # Per SEP-1686 final spec: client sends only ttl, server generates taskId
+        # Read resource with task metadata (no taskId sent)
+        result = await self.read_resource_mcp(
+            uri=uri,
+            meta={
+                "modelcontextprotocol.io/task": {
+                    "ttl": ttl,
+                }
+            },
+        )
+
+        # Check if server accepted background execution
+        # If response includes task metadata with taskId, server accepted background mode
+        # If response includes returned_immediately=True, server declined and executed sync
+        task_meta = (result.meta or {}).get("modelcontextprotocol.io/task", {})
+        if task_meta.get("taskId"):
+            # Background execution accepted - extract server-generated taskId
+            server_task_id = task_meta["taskId"]
+            # Track this task ID for list_tasks()
+            self._submitted_task_ids.add(server_task_id)
+
+            # Create task object
+            task_obj = ResourceTask(
+                self, server_task_id, uri=str(uri), immediate_result=None
+            )
+
+            # Register for notification routing
+            self._task_registry[server_task_id] = weakref.ref(task_obj)  # type: ignore[assignment]
+
+            return task_obj
+        else:
+            # Server declined background execution (graceful degradation)
+            # Use a synthetic task ID for the immediate result
+            synthetic_task_id = task_id or str(uuid.uuid4())
+            return ResourceTask(
+                self, synthetic_task_id, uri=str(uri), immediate_result=result.contents
+            )
+
     # async def subscribe_resource(self, uri: AnyUrl | str) -> None:
     #     """Send a resources/subscribe request."""
     #     if isinstance(uri, str):
@@ -734,13 +981,17 @@ class Client(Generic[ClientTransportT]):
 
     # --- Prompt ---
     async def get_prompt_mcp(
-        self, name: str, arguments: dict[str, Any] | None = None
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> mcp.types.GetPromptResult:
         """Send a prompts/get request and return the complete MCP protocol result.
 
         Args:
             name (str): The name of the prompt to retrieve.
             arguments (dict[str, Any] | None, optional): Arguments to pass to the prompt. Defaults to None.
+            meta (dict[str, Any] | None, optional): Request metadata (e.g., for SEP-1686 tasks). Defaults to None.
 
         Returns:
             mcp.types.GetPromptResult: The complete response object from the protocol,
@@ -764,30 +1015,138 @@ class Client(Generic[ClientTransportT]):
                         "utf-8"
                     )
 
-        result = await self.session.get_prompt(
-            name=name, arguments=serialized_arguments
-        )
+        # If meta provided, use send_request for SEP-1686 task support
+        if meta:
+            task_dict = meta.get("modelcontextprotocol.io/task")
+            request = mcp.types.GetPromptRequest(
+                params=mcp.types.GetPromptRequestParams(
+                    name=name,
+                    arguments=serialized_arguments,
+                    task=mcp.types.TaskMetadata(**task_dict)
+                    if task_dict
+                    else None,  # SEP-1686: task as direct param (spec-compliant)
+                )
+            )
+            result = await self.session.send_request(
+                request=request,  # type: ignore[arg-type]
+                result_type=mcp.types.GetPromptResult,
+            )
+        else:
+            result = await self.session.get_prompt(
+                name=name, arguments=serialized_arguments
+            )
         return result
 
+    @overload
     async def get_prompt(
-        self, name: str, arguments: dict[str, Any] | None = None
-    ) -> mcp.types.GetPromptResult:
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        task: Literal[False] = False,
+    ) -> mcp.types.GetPromptResult: ...
+
+    @overload
+    async def get_prompt(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        task: Literal[True],
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> PromptTask: ...
+
+    async def get_prompt(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        task: bool = False,
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> mcp.types.GetPromptResult | PromptTask:
         """Retrieve a rendered prompt message list from the server.
 
         Args:
             name (str): The name of the prompt to retrieve.
             arguments (dict[str, Any] | None, optional): Arguments to pass to the prompt. Defaults to None.
+            task (bool): If True, execute as background task (SEP-1686). Defaults to False.
+            task_id (str | None): Optional client-provided task ID (auto-generated if not provided).
+            ttl (int): Time to keep results available in milliseconds (default 60s).
 
         Returns:
-            mcp.types.GetPromptResult: The complete response object from the protocol,
-                containing the prompt messages and any additional metadata.
+            mcp.types.GetPromptResult | PromptTask: The complete response object if task=False,
+                or a PromptTask object if task=True.
 
         Raises:
             RuntimeError: If called while the client is not connected.
         """
+        if task:
+            return await self._get_prompt_as_task(name, arguments, task_id, ttl)
+
         result = await self.get_prompt_mcp(name=name, arguments=arguments)
         return result
 
+    async def _get_prompt_as_task(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> PromptTask:
+        """Get a prompt for background execution (SEP-1686).
+
+        Returns a PromptTask object that handles both background and immediate execution.
+
+        Args:
+            name: Prompt name to get
+            arguments: Prompt arguments
+            task_id: Optional client-provided task ID (ignored, for backward compatibility)
+            ttl: Time to keep results available in milliseconds (default 60s)
+
+        Returns:
+            PromptTask: Future-like object for accessing task status and results
+        """
+        # Per SEP-1686 final spec: client sends only ttl, server generates taskId
+        # Call prompt with task metadata (no taskId sent)
+        result = await self.get_prompt_mcp(
+            name=name,
+            arguments=arguments or {},
+            meta={
+                "modelcontextprotocol.io/task": {
+                    "ttl": ttl,
+                }
+            },
+        )
+
+        # Check if server accepted background execution
+        # If response includes task metadata with taskId, server accepted background mode
+        # If response includes returned_immediately=True, server declined and executed sync
+        task_meta = (result.meta or {}).get("modelcontextprotocol.io/task", {})
+        if task_meta.get("taskId"):
+            # Background execution accepted - extract server-generated taskId
+            server_task_id = task_meta["taskId"]
+            # Track this task ID for list_tasks()
+            self._submitted_task_ids.add(server_task_id)
+
+            # Create task object
+            task_obj = PromptTask(
+                self, server_task_id, prompt_name=name, immediate_result=None
+            )
+
+            # Register for notification routing
+            self._task_registry[server_task_id] = weakref.ref(task_obj)  # type: ignore[assignment]
+
+            return task_obj
+        else:
+            # Server declined background execution (graceful degradation)
+            # Use a synthetic task ID for the immediate result
+            synthetic_task_id = task_id or str(uuid.uuid4())
+            return PromptTask(
+                self, synthetic_task_id, prompt_name=name, immediate_result=result
+            )
+
     # --- Completion ---
 
     async def complete_mcp(
@@ -910,24 +1269,123 @@ class Client(Generic[ClientTransportT]):
         if isinstance(timeout, int | float):
             timeout = datetime.timedelta(seconds=float(timeout))
 
-        result = await self.session.call_tool(
-            name=name,
-            arguments=arguments,
-            read_timeout_seconds=timeout,  # ty: ignore[invalid-argument-type]
-            progress_callback=progress_handler or self._progress_handler,
-            meta=meta,
-        )
+        # For task submissions, use send_request to bypass SDK validation
+        # Task acknowledgments don't have structured content, which would fail validation
+        if meta and "modelcontextprotocol.io/task" in meta:
+            task_dict = meta.get("modelcontextprotocol.io/task")
+            request = mcp.types.CallToolRequest(
+                params=mcp.types.CallToolRequestParams(
+                    name=name,
+                    arguments=arguments,
+                    task=mcp.types.TaskMetadata(**task_dict)
+                    if task_dict
+                    else None,  # SEP-1686: task as direct param (spec-compliant)
+                )
+            )
+            result = await self.session.send_request(
+                request=request,  # type: ignore[arg-type]
+                result_type=mcp.types.CallToolResult,
+                request_read_timeout_seconds=timeout,  # type: ignore[arg-type]
+                progress_callback=progress_handler or self._progress_handler,
+            )
+        else:
+            result = await self.session.call_tool(
+                name=name,
+                arguments=arguments,
+                read_timeout_seconds=timeout,  # ty: ignore[invalid-argument-type]
+                progress_callback=progress_handler or self._progress_handler,
+                meta=meta,
+            )
         return result
 
+    async def _parse_call_tool_result(
+        self, name: str, result: mcp.types.CallToolResult, raise_on_error: bool = False
+    ) -> CallToolResult:
+        """Parse an mcp.types.CallToolResult into our CallToolResult dataclass.
+
+        Args:
+            name: Tool name (for schema lookup)
+            result: Raw MCP protocol result
+            raise_on_error: Whether to raise ToolError on errors
+
+        Returns:
+            CallToolResult: Parsed result with structured data
+        """
+        data = None
+        if result.isError and raise_on_error:
+            msg = cast(mcp.types.TextContent, result.content[0]).text
+            raise ToolError(msg)
+        elif result.structuredContent:
+            try:
+                if name not in self.session._tool_output_schemas:
+                    await self.session.list_tools()
+                if name in self.session._tool_output_schemas:
+                    output_schema = self.session._tool_output_schemas.get(name)
+                    if output_schema:
+                        if output_schema.get("x-fastmcp-wrap-result"):
+                            output_schema = output_schema.get("properties", {}).get(
+                                "result"
+                            )
+                            structured_content = result.structuredContent.get("result")
+                        else:
+                            structured_content = result.structuredContent
+                        output_type = json_schema_to_type(output_schema)
+                        type_adapter = get_cached_typeadapter(output_type)
+                        data = type_adapter.validate_python(structured_content)
+                    else:
+                        data = result.structuredContent
+            except Exception as e:
+                logger.error(f"[{self.name}] Error parsing structured content: {e}")
+
+        return CallToolResult(
+            content=result.content,
+            structured_content=result.structuredContent,
+            meta=result.meta,
+            data=data,
+            is_error=result.isError,
+        )
+
+    @overload
     async def call_tool(
         self,
         name: str,
         arguments: dict[str, Any] | None = None,
+        *,
         timeout: datetime.timedelta | float | int | None = None,
         progress_handler: ProgressHandler | None = None,
         raise_on_error: bool = True,
         meta: dict[str, Any] | None = None,
-    ) -> CallToolResult:
+        task: Literal[False] = False,
+    ) -> CallToolResult: ...
+
+    @overload
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        timeout: datetime.timedelta | float | int | None = None,
+        progress_handler: ProgressHandler | None = None,
+        raise_on_error: bool = True,
+        meta: dict[str, Any] | None = None,
+        task: Literal[True],
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> ToolTask: ...
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        *,
+        timeout: datetime.timedelta | float | int | None = None,
+        progress_handler: ProgressHandler | None = None,
+        raise_on_error: bool = True,
+        meta: dict[str, Any] | None = None,
+        task: bool = False,
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> CallToolResult | ToolTask:
         """Call a tool on the server.
 
         Unlike call_tool_mcp, this method raises a ToolError if the tool call results in an error.
@@ -937,15 +1395,18 @@ class Client(Generic[ClientTransportT]):
             arguments (dict[str, Any] | None, optional): Arguments to pass to the tool. Defaults to None.
             timeout (datetime.timedelta | float | int | None, optional): The timeout for the tool call. Defaults to None.
             progress_handler (ProgressHandler | None, optional): The progress handler to use for the tool call. Defaults to None.
-            raise_on_error (bool, optional): Whether to raise a ToolError if the tool call results in an error. Defaults to True.
+            raise_on_error (bool, optional): Whether to raise an exception if the tool call results in an error. Defaults to True.
             meta (dict[str, Any] | None, optional): Additional metadata to include with the request.
                 This is useful for passing contextual information (like user IDs, trace IDs, or preferences)
                 that shouldn't be tool arguments but may influence server-side processing. The server
                 can access this via `context.request_context.meta`. Defaults to None.
+            task (bool): If True, execute as background task (SEP-1686). Defaults to False.
+            task_id (str | None): Optional client-provided task ID (auto-generated if not provided).
+            ttl (int): Time to keep results available in milliseconds (default 60s).
 
         Returns:
-            CallToolResult:
-                The content returned by the tool. If the tool returns structured
+            CallToolResult | ToolTask: The content returned by the tool if task=False,
+                or a ToolTask object if task=True. If the tool returns structured
                 outputs, they are returned as a dataclass (if an output schema
                 is available) or a dictionary; otherwise, a list of content
                 blocks is returned. Note: to receive both structured and
@@ -956,6 +1417,9 @@ class Client(Generic[ClientTransportT]):
             ToolError: If the tool call results in an error.
             RuntimeError: If called while the client is not connected.
         """
+        if task:
+            return await self._call_tool_as_task(name, arguments, task_id, ttl)
+
         result = await self.call_tool_mcp(
             name=name,
             arguments=arguments or {},
@@ -963,38 +1427,186 @@ class Client(Generic[ClientTransportT]):
             progress_handler=progress_handler,
             meta=meta,
         )
-        data = None
-        if result.isError and raise_on_error:
-            msg = cast(mcp.types.TextContent, result.content[0]).text
-            raise ToolError(msg)
-        elif result.structuredContent:
+        return await self._parse_call_tool_result(
+            name, result, raise_on_error=raise_on_error
+        )
+
+    async def _call_tool_as_task(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        task_id: str | None = None,
+        ttl: int = 60000,
+    ) -> ToolTask:
+        """Call a tool for background execution (SEP-1686).
+
+        Returns a ToolTask object that handles both background and immediate execution.
+        If the server accepts background execution, ToolTask will poll for results.
+        If the server declines (graceful degradation), ToolTask wraps the immediate result.
+
+        Args:
+            name: Tool name to call
+            arguments: Tool arguments
+            task_id: Optional client-provided task ID (ignored, for backward compatibility)
+            ttl: Time to keep results available in milliseconds (default 60s)
+
+        Returns:
+            ToolTask: Future-like object for accessing task status and results
+        """
+        # Per SEP-1686 final spec: client sends only ttl, server generates taskId
+        # Call tool with task metadata (no taskId sent)
+        result = await self.call_tool_mcp(
+            name=name,
+            arguments=arguments or {},
+            meta={
+                "modelcontextprotocol.io/task": {
+                    "ttl": ttl,
+                }
+            },
+        )
+
+        # Check if server accepted background execution
+        # If response includes task metadata with taskId, server accepted background mode
+        # If response includes returned_immediately=True, server declined and executed sync
+        task_meta = (result.meta or {}).get("modelcontextprotocol.io/task", {})
+        if task_meta.get("taskId"):
+            # Background execution accepted - extract server-generated taskId
+            server_task_id = task_meta["taskId"]
+            # Track this task ID for list_tasks()
+            self._submitted_task_ids.add(server_task_id)
+
+            # Create task object
+            task_obj = ToolTask(
+                self, server_task_id, tool_name=name, immediate_result=None
+            )
+
+            # Register for notification routing
+            self._task_registry[server_task_id] = weakref.ref(task_obj)  # type: ignore[assignment]
+
+            return task_obj
+        else:
+            # Server declined background execution (graceful degradation)
+            # or returned_immediately=True - executed synchronously
+            # Wrap the immediate result
+            parsed_result = await self._parse_call_tool_result(name, result)
+            # Use a synthetic task ID for the immediate result
+            synthetic_task_id = task_id or str(uuid.uuid4())
+            return ToolTask(
+                self, synthetic_task_id, tool_name=name, immediate_result=parsed_result
+            )
+
+    async def get_task_status(self, task_id: str) -> GetTaskResult:
+        """Query the status of a background task.
+
+        Sends a 'tasks/get' MCP protocol request over the existing transport.
+
+        Args:
+            task_id: The task ID returned from call_tool_as_task
+
+        Returns:
+            GetTaskResult: Status information including taskId, status, pollInterval, etc.
+
+        Raises:
+            RuntimeError: If client not connected
+        """
+        request = GetTaskRequest(params=GetTaskRequestParams(taskId=task_id))
+        return await self.session.send_request(
+            request=request,  # type: ignore[arg-type]
+            result_type=GetTaskResult,  # type: ignore[arg-type]
+        )
+
+    async def get_task_result(self, task_id: str) -> Any:
+        """Retrieve the raw result of a completed background task.
+
+        Sends a 'tasks/result' MCP protocol request over the existing transport.
+        Returns the raw result - callers should parse it appropriately.
+
+        Args:
+            task_id: The task ID returned from call_tool_as_task
+
+        Returns:
+            Any: The raw result (could be tool, prompt, or resource result)
+
+        Raises:
+            RuntimeError: If client not connected, task not found, or task failed
+        """
+        request = GetTaskPayloadRequest(
+            params=GetTaskPayloadRequestParams(taskId=task_id)
+        )
+        # Return raw result - Task classes handle type-specific parsing
+        result = await self.session.send_request(
+            request=request,  # type: ignore[arg-type]
+            result_type=GetTaskPayloadResult,  # type: ignore[arg-type]
+        )
+        # Return as dict for compatibility with Task class parsing
+        return result.model_dump(exclude_none=True, by_alias=True)
+
+    async def list_tasks(
+        self,
+        cursor: str | None = None,
+        limit: int = 50,
+    ) -> dict[str, Any]:
+        """List background tasks.
+
+        Sends a 'tasks/list' MCP protocol request to the server. If the server
+        returns an empty list (indicating client-side tracking), falls back to
+        querying status for locally tracked task IDs.
+
+        Args:
+            cursor: Optional pagination cursor
+            limit: Maximum number of tasks to return (default 50)
+
+        Returns:
+            dict: Response with structure:
+                - tasks: List of task status dicts with taskId, status, etc.
+                - nextCursor: Optional cursor for next page
+
+        Raises:
+            RuntimeError: If client not connected
+        """
+        # Send protocol request
+        params = PaginatedRequestParams(cursor=cursor, limit=limit)
+        request = ListTasksRequest(params=params)
+        server_response = await self.session.send_request(
+            request=request,  # type: ignore[invalid-argument-type]
+            result_type=mcp.types.ListTasksResult,
+        )
+
+        # If server returned tasks, use those
+        if server_response.tasks:
+            return server_response.model_dump(by_alias=True)
+
+        # Server returned empty - fall back to client-side tracking
+        tasks = []
+        for task_id in list(self._submitted_task_ids)[:limit]:
             try:
-                if name not in self.session._tool_output_schemas:
-                    await self.session.list_tools()
-                if name in self.session._tool_output_schemas:
-                    output_schema = self.session._tool_output_schemas.get(name)
-                    if output_schema:
-                        if output_schema.get("x-fastmcp-wrap-result"):
-                            output_schema = output_schema.get("properties", {}).get(
-                                "result"
-                            )
-                            structured_content = result.structuredContent.get("result")
-                        else:
-                            structured_content = result.structuredContent
-                        output_type = json_schema_to_type(output_schema)
-                        type_adapter = get_cached_typeadapter(output_type)
-                        data = type_adapter.validate_python(structured_content)
-                    else:
-                        data = result.structuredContent
-            except Exception as e:
-                logger.error(f"[{self.name}] Error parsing structured content: {e}")
+                status = await self.get_task_status(task_id)
+                tasks.append(status.model_dump(by_alias=True))
+            except Exception:
+                # Task may have expired or been deleted, skip it
+                continue
 
-        return CallToolResult(
-            content=result.content,
-            structured_content=result.structuredContent,
-            meta=result.meta,
-            data=data,
-            is_error=result.isError,
+        return {"tasks": tasks, "nextCursor": None}
+
+    async def cancel_task(self, task_id: str) -> mcp.types.CancelTaskResult:
+        """Cancel a task, transitioning it to cancelled state.
+
+        Sends a 'tasks/cancel' MCP protocol request. Task will halt execution
+        and transition to cancelled state.
+
+        Args:
+            task_id: The task ID to cancel
+
+        Returns:
+            CancelTaskResult: The task status showing cancelled state
+
+        Raises:
+            RuntimeError: If task doesn't exist
+        """
+        request = CancelTaskRequest(params=CancelTaskRequestParams(taskId=task_id))
+        return await self.session.send_request(
+            request=request,  # type: ignore[invalid-argument-type]
+            result_type=mcp.types.CancelTaskResult,
         )
 
     @classmethod
@@ -1004,12 +1616,3 @@ class Client(Generic[ClientTransportT]):
             return f"{class_name}-{secrets.token_hex(2)}"
         else:
             return f"{class_name}-{name}-{secrets.token_hex(2)}"
-
-
-@dataclass
-class CallToolResult:
-    content: list[mcp.types.ContentBlock]
-    structured_content: dict[str, Any] | None
-    meta: dict[str, Any] | None
-    data: Any = None
-    is_error: bool = False