fastmcp 2.12.5__py3-none-any.whl → 2.14.0__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
@@ -36,6 +51,13 @@ from fastmcp.client.sampling import (
     SamplingHandler,
     create_sampling_callback,
 )
+from fastmcp.client.tasks import (
+    PromptTask,
+    ResourceTask,
+    TaskNotificationHandler,
+    ToolTask,
+    _task_capable_initialize,
+)
 from fastmcp.exceptions import ToolError
 from fastmcp.mcp_config import MCPConfig
 from fastmcp.server import FastMCP
@@ -61,15 +83,15 @@ from .transports import (
 
 __all__ = [
     "Client",
-    "SessionKwargs",
-    "RootsHandler",
-    "RootsList",
-    "LogHandler",
-    "MessageHandler",
     "ClientSamplingHandler",
-    "SamplingHandler",
     "ElicitationHandler",
+    "LogHandler",
+    "MessageHandler",
     "ProgressHandler",
+    "RootsHandler",
+    "RootsList",
+    "SamplingHandler",
+    "SessionKwargs",
 ]
 
 logger = get_logger(__name__)
@@ -94,6 +116,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.
@@ -155,38 +188,38 @@ class Client(Generic[ClientTransportT]):
     """
 
     @overload
-    def __init__(self: Client[T], transport: T, *args, **kwargs) -> None: ...
+    def __init__(self: Client[T], transport: T, *args: Any, **kwargs: Any) -> None: ...
 
     @overload
     def __init__(
         self: Client[SSETransport | StreamableHttpTransport],
         transport: AnyUrl,
-        *args,
-        **kwargs,
+        *args: Any,
+        **kwargs: Any,
     ) -> None: ...
 
     @overload
     def __init__(
         self: Client[FastMCPTransport],
         transport: FastMCP | FastMCP1Server,
-        *args,
-        **kwargs,
+        *args: Any,
+        **kwargs: Any,
     ) -> None: ...
 
     @overload
     def __init__(
         self: Client[PythonStdioTransport | NodeStdioTransport],
         transport: Path,
-        *args,
-        **kwargs,
+        *args: Any,
+        **kwargs: Any,
     ) -> None: ...
 
     @overload
     def __init__(
         self: Client[MCPConfigTransport],
         transport: MCPConfig | dict[str, Any],
-        *args,
-        **kwargs,
+        *args: Any,
+        **kwargs: Any,
     ) -> None: ...
 
     @overload
@@ -198,8 +231,8 @@ class Client(Generic[ClientTransportT]):
             | StreamableHttpTransport
         ],
         transport: str,
-        *args,
-        **kwargs,
+        *args: Any,
+        **kwargs: Any,
     ) -> None: ...
 
     def __init__(
@@ -222,6 +255,7 @@ class Client(Generic[ClientTransportT]):
         message_handler: MessageHandlerT | MessageHandler | None = None,
         progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
+        auto_initialize: bool = True,
         init_timeout: datetime.timedelta | float | int | None = None,
         client_info: mcp.types.Implementation | None = None,
         auth: httpx.Auth | Literal["oauth"] | str | None = None,
@@ -240,6 +274,7 @@ class Client(Generic[ClientTransportT]):
 
         self._progress_handler = progress_handler
 
+        # Convert timeout to timedelta if needed
         if isinstance(timeout, int | float):
             timeout = datetime.timedelta(seconds=float(timeout))
 
@@ -254,12 +289,14 @@ class Client(Generic[ClientTransportT]):
             init_timeout = float(init_timeout)
         self._init_timeout = init_timeout
 
+        self.auto_initialize = auto_initialize
+
         self._session_kwargs: SessionKwargs = {
             "sampling_callback": None,
             "list_roots_callback": None,
             "logging_callback": create_log_callback(log_handler),
-            "message_handler": message_handler,
-            "read_timeout_seconds": timeout,
+            "message_handler": message_handler or TaskNotificationHandler(self),
+            "read_timeout_seconds": timeout,  # ty: ignore[invalid-argument-type]
             "client_info": client_info,
         }
 
@@ -279,6 +316,15 @@ 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]
+        ] = {}
+
     @property
     def session(self) -> ClientSession:
         """Get the current active session. Raises RuntimeError if not connected."""
@@ -290,12 +336,8 @@ class Client(Generic[ClientTransportT]):
         return self._session_state.session
 
     @property
-    def initialize_result(self) -> mcp.types.InitializeResult:
+    def initialize_result(self) -> mcp.types.InitializeResult | None:
         """Get the result of the initialization request."""
-        if self._session_state.initialize_result is None:
-            raise RuntimeError(
-                "Client is not connected. Use the 'async with client:' context manager first."
-            )
         return self._session_state.initialize_result
 
     def set_roots(self, roots: RootsList | RootsHandler) -> None:
@@ -355,26 +397,84 @@ 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:
-                    with anyio.fail_after(self._init_timeout):
-                        self._session_state.initialize_result = (
-                            await self._session_state.session.initialize()
-                        )
+                    if self.auto_initialize:
+                        await self.initialize()
                     yield
-                except anyio.ClosedResourceError:
-                    raise RuntimeError("Server session was closed unexpectedly")
-                except TimeoutError:
-                    raise RuntimeError("Failed to initialize server session")
+                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
 
+    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 _task_capable_initialize(
+                    self.session
+                )
+
+                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):
         """
@@ -414,7 +514,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,6 +588,28 @@ 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()
@@ -596,12 +719,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,
@@ -614,24 +738,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
-    ) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]:
+        self,
+        uri: AnyUrl | str,
+        *,
+        task: Literal[False] = False,
+    ) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]: ...
+
+    @overload
+    async def read_resource(
+        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
@@ -642,6 +815,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):
@@ -685,13 +914,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,
@@ -715,30 +948,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(
@@ -831,6 +1172,7 @@ class Client(Generic[ClientTransportT]):
         arguments: dict[str, Any],
         progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> mcp.types.CallToolResult:
         """Send a tools/call request and return the complete MCP protocol result.
 
@@ -842,6 +1184,10 @@ class Client(Generic[ClientTransportT]):
             arguments (dict[str, Any]): Arguments to pass to the tool.
             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.
+            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.
 
         Returns:
             mcp.types.CallToolResult: The complete response object from the protocol,
@@ -852,53 +1198,52 @@ class Client(Generic[ClientTransportT]):
         """
         logger.debug(f"[{self.name}] called call_tool: {name}")
 
+        # Convert timeout to timedelta if needed
         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,
-            progress_callback=progress_handler or self._progress_handler,
-        )
+
+        # 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 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,
+    async def _parse_call_tool_result(
+        self, name: str, result: mcp.types.CallToolResult, raise_on_error: bool = False
     ) -> CallToolResult:
-        """Call a tool on the server.
-
-        Unlike call_tool_mcp, this method raises a ToolError if the tool call results in an error.
+        """Parse an mcp.types.CallToolResult into our CallToolResult dataclass.
 
         Args:
-            name (str): The name of the tool to call.
-            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.
+            name: Tool name (for schema lookup)
+            result: Raw MCP protocol result
+            raise_on_error: Whether to raise ToolError on errors
 
         Returns:
-            CallToolResult:
-                The content returned by the tool. 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
-                unstructured outputs, use call_tool_mcp instead and access the
-                raw result object.
-
-        Raises:
-            ToolError: If the tool call results in an error.
-            RuntimeError: If called while the client is not connected.
+            CallToolResult: Parsed result with structured data
         """
-        result = await self.call_tool_mcp(
-            name=name,
-            arguments=arguments or {},
-            timeout=timeout,
-            progress_handler=progress_handler,
-        )
         data = None
         if result.isError and raise_on_error:
             msg = cast(mcp.types.TextContent, result.content[0]).text
@@ -928,10 +1273,275 @@ class Client(Generic[ClientTransportT]):
         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,
+        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.
+
+        Args:
+            name (str): The name of the tool to call.
+            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 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 | 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
+                unstructured outputs, use call_tool_mcp instead and access the
+                raw result object.
+
+        Raises:
+            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 {},
+            timeout=timeout,
+            progress_handler=progress_handler,
+            meta=meta,
+        )
+        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:
+                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 {"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
     def generate_name(cls, name: str | None = None) -> str:
         class_name = cls.__name__
@@ -939,11 +1549,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
-    data: Any = None
-    is_error: bool = False