agent-framework-declarative 1.4.0__tar.gz → 1.5.0__tar.gz

{agent_framework_declarative-1.4.0 → agent_framework_declarative-1.5.0}/PKG-INFO

@@ -1,21 +1,20 @@
 Metadata-Version: 2.5
 Name: agent-framework-declarative
-Version: 1.4.0
+Version: 1.5.0
 Summary: Declarative specification support for Microsoft Agent Framework.
 Author-email: Microsoft <af-support@microsoft.com>
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: agent-framework-core>=1.23.0,<2
+Requires-Dist: agent-framework-core>=1.25.0,<2
 Requires-Dist: httpx>=0.27,<0.29
 Requires-Dist: httpx2>=2.0.0,<3
 Requires-Dist: powerfx>=0.0.32,<0.0.35; python_version < '3.14'
@@ -34,7 +33,7 @@ Please install this package via pip:
 pip install agent-framework-declarative
 ```
 
-The package currently advertises Python 3.10–3.13 support. Python 3.14 and
+The package currently advertises Python 3.11–3.13 support. Python 3.14 and
 3.15 can install the package, but Power Fx expressions are unavailable because
 the `powerfx` dependency requires a `pythonnet` build that does not support
 those Python versions.
@@ -100,23 +99,42 @@ on HTTPX internals. Compatibility tests cover HTTPX 0.27.0 and 0.28.1.
 
 ## MCP handler session lifetime
 
-`DefaultMCPToolHandler()` reuses MCP sessions through a bounded LRU cache.
-When configured with `client_provider`, it instead invokes the provider and
-creates a fresh MCP tool/session for every invocation, including `tools/list`.
-Sessions are never reused in this mode, even if the provider returns `None`
-or the same `httpx.AsyncClient` instance.
+**Security fix:** `DefaultMCPToolHandler` creates and closes a fresh MCP
+tool/session for every invocation, including `tools/list`. Independently
+constructed workflows may safely share a handler without sharing MCP protocol
+state, even with identical endpoint and header configuration. There is no
+initialized-client or discovery cache.
 
 Each invocation closes its tool/session on success, failure, or cancellation.
-Internally created fallback HTTP clients are also closed; caller-supplied HTTP
-clients remain caller-owned and are never closed by the handler. Calling
-`aclose()` rejects new invocations and waits for active provider-backed
-invocations to finish cleaning up. Calling it from an active invocation's
-context (including provider callbacks, inherited child tasks, and cleanup)
-raises `RuntimeError` before changing handler state, rather than waiting on
-itself. Close the handler outside that context or after the invocation completes.
-
-This intentionally incurs connection and initialization overhead and does not
-retain server session state between provider-backed invocations. Applications
-that require shared session ownership must implement an explicitly scoped
-custom `MCPToolHandler`; there is no provider-backed session-cache opt-in.
+Internally created HTTP clients are also closed. The optional `client_provider`
+is called once per invocation and may return a reusable `httpx.AsyncClient`
+to share an HTTP connection pool, not an MCP session. Returned clients are
+borrowed and never closed by the handler. Returning `None` selects an internally
+owned client.
+
+Provider, connection, discovery, and transport failures raise exceptions and fail
+the workflow action, including after approval. Remote tool error responses still
+produce `MCPToolResult(is_error=True)` and populate `output.result` with an error
+string. Custom handlers should return error results only for tool-level errors;
+raised exceptions are not converted into workflow results.
+
+The legacy `cache_max_size` parameter is accepted for compatibility, but is
+deprecated and ignored. Passing any non-`None` value emits `DeprecationWarning`;
+the value is not validated. Omitting it or passing `None` emits no warning.
+It cannot restore session caching or sharing.
+
+The handler no longer implements `aclose()` or an async context manager.
+Replace `async with DefaultMCPToolHandler() as handler:`
+with `handler = DefaultMCPToolHandler()` and remove handler shutdown calls.
+Continue to manage caller-owned HTTP clients with their own context manager.
+Hosts must cancel and await active invocations before closing borrowed clients;
+admission limits and deadlines also belong to the host.
+
+This intentionally adds connection and initialization overhead. Implicit
+server-side state does not persist across tool calls, approval waits, or
+checkpoint resumes. Workflow checkpoints and approval verification are
+unchanged; no request-scope migration flag is required. Applications that need
+MCP session continuity must provide an explicitly scoped custom `MCPToolHandler`
+or pass explicit remote state handles as tool arguments. See the
+[decision record](../../../docs/decisions/0053-python-invocation-owned-mcp-sessions.md).
 

{agent_framework_declarative-1.4.0 → agent_framework_declarative-1.5.0}/README.md

@@ -6,7 +6,7 @@ Please install this package via pip:
 pip install agent-framework-declarative
 ```
 
-The package currently advertises Python 3.10–3.13 support. Python 3.14 and
+The package currently advertises Python 3.11–3.13 support. Python 3.14 and
 3.15 can install the package, but Power Fx expressions are unavailable because
 the `powerfx` dependency requires a `pythonnet` build that does not support
 those Python versions.
@@ -72,22 +72,41 @@ on HTTPX internals. Compatibility tests cover HTTPX 0.27.0 and 0.28.1.
 
 ## MCP handler session lifetime
 
-`DefaultMCPToolHandler()` reuses MCP sessions through a bounded LRU cache.
-When configured with `client_provider`, it instead invokes the provider and
-creates a fresh MCP tool/session for every invocation, including `tools/list`.
-Sessions are never reused in this mode, even if the provider returns `None`
-or the same `httpx.AsyncClient` instance.
+**Security fix:** `DefaultMCPToolHandler` creates and closes a fresh MCP
+tool/session for every invocation, including `tools/list`. Independently
+constructed workflows may safely share a handler without sharing MCP protocol
+state, even with identical endpoint and header configuration. There is no
+initialized-client or discovery cache.
 
 Each invocation closes its tool/session on success, failure, or cancellation.
-Internally created fallback HTTP clients are also closed; caller-supplied HTTP
-clients remain caller-owned and are never closed by the handler. Calling
-`aclose()` rejects new invocations and waits for active provider-backed
-invocations to finish cleaning up. Calling it from an active invocation's
-context (including provider callbacks, inherited child tasks, and cleanup)
-raises `RuntimeError` before changing handler state, rather than waiting on
-itself. Close the handler outside that context or after the invocation completes.
-
-This intentionally incurs connection and initialization overhead and does not
-retain server session state between provider-backed invocations. Applications
-that require shared session ownership must implement an explicitly scoped
-custom `MCPToolHandler`; there is no provider-backed session-cache opt-in.
+Internally created HTTP clients are also closed. The optional `client_provider`
+is called once per invocation and may return a reusable `httpx.AsyncClient`
+to share an HTTP connection pool, not an MCP session. Returned clients are
+borrowed and never closed by the handler. Returning `None` selects an internally
+owned client.
+
+Provider, connection, discovery, and transport failures raise exceptions and fail
+the workflow action, including after approval. Remote tool error responses still
+produce `MCPToolResult(is_error=True)` and populate `output.result` with an error
+string. Custom handlers should return error results only for tool-level errors;
+raised exceptions are not converted into workflow results.
+
+The legacy `cache_max_size` parameter is accepted for compatibility, but is
+deprecated and ignored. Passing any non-`None` value emits `DeprecationWarning`;
+the value is not validated. Omitting it or passing `None` emits no warning.
+It cannot restore session caching or sharing.
+
+The handler no longer implements `aclose()` or an async context manager.
+Replace `async with DefaultMCPToolHandler() as handler:`
+with `handler = DefaultMCPToolHandler()` and remove handler shutdown calls.
+Continue to manage caller-owned HTTP clients with their own context manager.
+Hosts must cancel and await active invocations before closing borrowed clients;
+admission limits and deadlines also belong to the host.
+
+This intentionally adds connection and initialization overhead. Implicit
+server-side state does not persist across tool calls, approval waits, or
+checkpoint resumes. Workflow checkpoints and approval verification are
+unchanged; no request-scope migration flag is required. Applications that need
+MCP session continuity must provide an explicitly scoped custom `MCPToolHandler`
+or pass explicit remote state handles as tool arguments. See the
+[decision record](../../../docs/decisions/0053-python-invocation-owned-mcp-sessions.md).

{agent_framework_declarative-1.4.0 → agent_framework_declarative-1.5.0}/agent_framework_declarative/_loader.py

@@ -3,10 +3,9 @@
 from __future__ import annotations
 
 import asyncio
-import sys
 from collections.abc import Callable, Mapping
 from pathlib import Path
-from typing import Any, cast
+from typing import Any, TypedDict, cast
 
 import yaml
 from agent_framework import (
@@ -44,11 +43,6 @@ from ._models import (
     agent_schema_dispatch,
 )
 
-if sys.version_info >= (3, 11):
-    from typing import TypedDict  # pragma: no cover
-else:
-    from typing_extensions import TypedDict  # pragma: no cover
-
 
 @experimental(feature_id=ExperimentalFeature.DECLARATIVE_AGENTS)
 class ProviderTypeMapping(TypedDict, total=True):
@@ -743,8 +737,9 @@ class AgentFactory:
         additional_properties = options.additionalProperties.copy()
         if (chat_tool_mode := additional_properties.pop("chatToolMode", None)) is not None:
             chat_options["tool_choice"] = chat_tool_mode
-        if additional_properties:
-            chat_options["additional_chat_options"] = additional_properties
+        # Pass the rest through as regular options; the typed fields above win on conflicts.
+        for key, value in additional_properties.items():
+            chat_options.setdefault(key, value)
         return chat_options
 
     def _parse_tools(self, tools: list[Tool] | None) -> list[AFFunctionTool | dict[str, Any]] | None:

{agent_framework_declarative-1.4.0 → agent_framework_declarative-1.5.0}/agent_framework_declarative/_workflows/_declarative_base.py

@@ -29,14 +29,13 @@ import locale
 import logging
 import os
 import re
-import sys
 import uuid
 from collections.abc import Iterator, Mapping
 from dataclasses import dataclass, field
 from decimal import Decimal as _Decimal
 from enum import Enum
 from types import MappingProxyType
-from typing import Any, Literal, cast
+from typing import Any, Literal, TypedDict, cast
 
 from agent_framework import (
     Executor,
@@ -60,11 +59,6 @@ except (ImportError, RuntimeError):
     # RuntimeError: .NET runtime not available or misconfigured
     Engine = None
 
-if sys.version_info >= (3, 11):
-    from typing import TypedDict  # pragma: no cover
-else:
-    from typing_extensions import TypedDict  # pragma: no cover
-
 
 logger = logging.getLogger(__name__)
 

{agent_framework_declarative-1.4.0 → agent_framework_declarative-1.5.0}/agent_framework_declarative/_workflows/_executors_mcp.py

@@ -23,6 +23,8 @@ Security notes:
   authors must trust the MCP server they invoke.
 """
 
+from __future__ import annotations
+
 import hmac
 import json
 import logging
@@ -32,7 +34,6 @@ from collections.abc import Mapping
 from dataclasses import dataclass, field
 from typing import Any
 
-import httpx2 as httpx
 from agent_framework import (
     Content,
     Message,
@@ -40,7 +41,6 @@ from agent_framework import (
     handler,
     response_handler,
 )
-from agent_framework.exceptions import ToolExecutionException
 
 from ._declarative_base import (
     ActionComplete,
@@ -177,6 +177,8 @@ class InvokeMcpToolActionExecutor(DeclarativeActionExecutor):
     - On error returned by the handler (``is_error=True``): assigns
       ``"Error: <message>"`` to ``output.result`` and completes normally
       (parity with .NET ``AssignErrorAsync``).
+    - Setup, transport, and protocol exceptions propagate and fail the action,
+      including when resuming an approved invocation.
 
     .. note::
 
@@ -243,7 +245,7 @@ class InvokeMcpToolActionExecutor(DeclarativeActionExecutor):
             )
             return
 
-        result = await self._invoke_with_narrow_catch(invocation)
+        result = await self._mcp_tool_handler.invoke_tool(invocation)
         await self._process_result(
             ctx=ctx,
             state=state,
@@ -357,7 +359,7 @@ class InvokeMcpToolActionExecutor(DeclarativeActionExecutor):
                 )
                 await self._request_approval(invocation, dict(metadata), ctx)
                 return
-        result = await self._invoke_with_narrow_catch(invocation)
+        result = await self._mcp_tool_handler.invoke_tool(invocation)
         await self._process_result(
             ctx=ctx,
             state=state,
@@ -472,49 +474,6 @@ class InvokeMcpToolActionExecutor(DeclarativeActionExecutor):
             return evaluated.strip().lower() in {"true", "1", "yes"}
         return bool(evaluated)
 
-    # ----- Invocation + error handling ----------------------------------------
-
-    async def _invoke_with_narrow_catch(self, invocation: MCPToolInvocation) -> MCPToolResult:
-        """Invoke the handler with a narrow exception catch.
-
-        Only known transport / tool exceptions are normalised to an error
-        result. Programmer bugs (TypeError, ValueError from misuse, etc.)
-        propagate so they fail loudly.
-
-        ``asyncio.CancelledError`` is a ``BaseException``, not ``Exception``,
-        so it is not caught here and propagates unchanged for workflow
-        cancellation.
-        """
-        try:
-            return await self._mcp_tool_handler.invoke_tool(invocation)
-        except ToolExecutionException as exc:
-            message = str(exc) or type(exc).__name__
-            return MCPToolResult(
-                outputs=[Content.from_text(f"Error: {message}")],
-                is_error=True,
-                error_message=message,
-            )
-        except httpx.HTTPError as exc:
-            message = f"{type(exc).__name__}: {exc}" if str(exc) else type(exc).__name__
-            return MCPToolResult(
-                outputs=[Content.from_text(f"Error: {message}")],
-                is_error=True,
-                error_message=message,
-            )
-        except Exception as exc:
-            try:
-                from mcp.shared.exceptions import MCPError
-            except ImportError:  # pragma: no cover - mcp is a hard dep
-                raise
-            if isinstance(exc, MCPError):
-                message = str(exc) or type(exc).__name__
-                return MCPToolResult(
-                    outputs=[Content.from_text(f"Error: {message}")],
-                    is_error=True,
-                    error_message=message,
-                )
-            raise
-
     # ----- Result handling -----------------------------------------------------
 
     async def _process_result(

{agent_framework_declarative-1.4.0 → agent_framework_declarative-1.5.0}/agent_framework_declarative/_workflows/_executors_tools.py

@@ -243,6 +243,27 @@ class BaseToolExecutor(DeclarativeActionExecutor):
 
         return None
 
+    def _registered_tool_requires_approval(
+        self,
+        function_name: str,
+        ctx: WorkflowContext[Any, Any],
+    ) -> bool:
+        """Check whether the registered tool requires approval on every invocation.
+
+        A tool registered with ``approval_mode="always_require"`` must not run
+        without approval, even when the action omits ``requireApproval`` or sets
+        it to false.
+
+        Args:
+            function_name: Name of the function
+            ctx: Workflow context
+
+        Returns:
+            True if the registered tool requires approval, False otherwise
+        """
+        tool = self._get_tool(function_name, ctx)
+        return getattr(tool, "approval_mode", None) == "always_require"
+
     def _get_output_config(self) -> tuple[str | None, str | None, Any]:
         """Parse output bindings and the unevaluated autoSend setting.
 
@@ -433,7 +454,8 @@ class BaseToolExecutor(DeclarativeActionExecutor):
     ) -> None:
         """Handle the tool invocation with optional approval flow.
 
-        When requireApproval=true:
+        When requireApproval=true, or the registered tool has
+        approval_mode="always_require":
         1. Saves invocation state to State (keyed by executor ID)
         2. Emits ToolApprovalRequest via ctx.request_info()
         3. Workflow yields (returns without ActionComplete)
@@ -477,10 +499,11 @@ class BaseToolExecutor(DeclarativeActionExecutor):
             for key, value in arguments_def.items():  # type: ignore[reportUnknownVariableType]
                 arguments[key] = state.eval_if_expression(value)
 
-        # Check if approval is required
+        # Check if approval is required. The action's requireApproval cannot
+        # override a registered tool's approval_mode="always_require".
         require_approval = self._action_def.get("requireApproval", False)
 
-        if require_approval:
+        if require_approval or self._registered_tool_requires_approval(function_name, ctx):
             # Emit approval request - the request payload is the source of
             # truth for resumed invocation; no side-channel state is written.
             request_id = str(uuid.uuid4())

agent_framework_declarative-1.5.0/agent_framework_declarative/_workflows/_mcp_handler.py

@@ -0,0 +1,254 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""MCP tool handlers for declarative workflows.
+
+The default handler owns a separate MCP protocol session for each invocation.
+Custom handlers may implement explicitly scoped session continuity or additional
+transport policy. Neither the default handler nor this protocol filters URLs:
+hosts must enforce their own destination allowlists and trust the MCP servers
+whose outputs enter workflow conversations.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import warnings
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, ClassVar, Protocol, runtime_checkable
+
+import httpx2 as httpx
+
+if TYPE_CHECKING:
+    from agent_framework import Content, MCPStreamableHTTPTool
+
+__all__ = [
+    "ClientProvider",
+    "DefaultMCPToolHandler",
+    "MCPToolHandler",
+    "MCPToolInvocation",
+    "MCPToolResult",
+]
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MCPToolInvocation:
+    """Evaluated input for an MCP tool call.
+
+    ``server_url`` identifies the server and ``server_label`` names its client.
+    ``tool_name`` is either a remote tool or the reserved ``tools/list`` operation.
+    ``arguments`` contains JSON-serialisable tool arguments; ``headers`` contains
+    evaluated outbound headers. ``connection_name`` is available to custom
+    handlers and client providers that resolve host-owned connections.
+    """
+
+    server_url: str
+    tool_name: str
+    server_label: str | None = None
+    arguments: dict[str, Any] = field(default_factory=dict)  # type: ignore[reportUnknownVariableType]
+    headers: dict[str, str] = field(default_factory=dict)  # type: ignore[reportUnknownVariableType]
+    connection_name: str | None = None
+
+
+@dataclass
+class MCPToolResult:
+    """Parsed MCP output, or a remote tool error the workflow can store in its result."""
+
+    outputs: list[Content] = field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+    is_error: bool = False
+    error_message: str | None = None
+
+
+@runtime_checkable
+class MCPToolHandler(Protocol):
+    """Transport contract for declarative ``InvokeMcpTool`` actions.
+
+    Implementations must support concurrent calls from independent workflows.
+    They own destination validation, authentication, retries, and any explicitly
+    scoped protocol-session continuity. Lifecycle methods are not part of this
+    protocol.
+    """
+
+    async def invoke_tool(self, invocation: MCPToolInvocation) -> MCPToolResult:
+        """Return tool output or a remote tool error; propagate setup and transport failures."""
+        ...
+
+
+ClientProvider = Callable[[MCPToolInvocation], Awaitable["httpx.AsyncClient | None"]]
+
+
+class DefaultMCPToolHandler:
+    """Invoke MCP tools with a separate protocol client for every call.
+
+    Every invocation, including ``tools/list``, connects and closes its own
+    :class:`agent_framework.MCPStreamableHTTPTool`. No initialized clients,
+    session state, credentials, or discovery inventories are cached here.
+
+    The optional ``client_provider`` is called for every invocation. Its HTTP
+    client is borrowed and never closed by this handler, so the host may reuse
+    HTTP connection pools without sharing MCP sessions. Returning ``None`` uses
+    an internally owned HTTP client that is closed with the invocation.
+
+    The handler owns no shared disposable resources and has no shutdown method.
+    Hosts must cancel and await active invocations before closing borrowed HTTP
+    clients. Admission limits and invocation deadlines are also host-owned.
+    Implicit server-side state does not survive later calls, approval waits, or
+    checkpoint resumes. Use a custom scoped handler or explicit remote state
+    handles when continuity is required.
+
+    This handler performs no URL filtering or SSRF protection.
+
+    Keyword Args:
+        client_provider: Optional per-invocation provider of a borrowed HTTP client.
+        cache_max_size: Deprecated compatibility parameter. Non-``None`` values
+            emit a warning but are ignored; sessions are never cached.
+        max_discovery_pages: Maximum pages accepted per tool catalog fetch.
+            Defaults to 100; ``None`` disables the limit.
+        max_discovery_items: Maximum tools accepted per tool catalog fetch.
+            Defaults to 1,000; ``None`` disables the limit.
+    """
+
+    LIST_TOOLS_TOOL_NAME: ClassVar[str] = "tools/list"
+    """Reserved operation returning a JSON catalog with a ``tools`` array.
+
+    Each item contains ``name``, ``description``, ``inputSchema``, and
+    ``outputSchema`` in that order. The catalog is paginated within one
+    invocation, not retained for subsequent calls.
+    """
+
+    def __init__(
+        self,
+        *,
+        client_provider: ClientProvider | None = None,
+        cache_max_size: int | None = None,
+        max_discovery_pages: int | None = 100,
+        max_discovery_items: int | None = 1_000,
+    ) -> None:
+        if cache_max_size is not None:
+            warnings.warn(
+                "cache_max_size is deprecated and has no effect. Each invocation uses a new MCP session.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if max_discovery_pages is not None and max_discovery_pages <= 0:
+            raise ValueError("max_discovery_pages must be positive or None.")
+        if max_discovery_items is not None and max_discovery_items <= 0:
+            raise ValueError("max_discovery_items must be positive or None.")
+        self._client_provider = client_provider
+        self._max_discovery_pages = max_discovery_pages
+        self._max_discovery_items = max_discovery_items
+
+    async def invoke_tool(self, invocation: MCPToolInvocation) -> MCPToolResult:
+        """Connect, dispatch, and finish protocol cleanup before returning."""
+        from agent_framework import MCPStreamableHTTPTool
+
+        if invocation.tool_name == self.LIST_TOOLS_TOOL_NAME and invocation.arguments:
+            message = f"The reserved MCP '{self.LIST_TOOLS_TOOL_NAME}' operation does not accept tool arguments."
+            raise ValueError(message)
+
+        tool: MCPStreamableHTTPTool | None = None
+        try:
+            client = await self._client_provider(invocation) if self._client_provider is not None else None
+            tool = MCPStreamableHTTPTool(
+                name=invocation.server_label or "McpClient",
+                url=invocation.server_url,
+                load_prompts=False,
+                http_client=client,
+                static_headers=dict(invocation.headers),
+                max_discovery_pages=self._max_discovery_pages,
+                max_discovery_items=self._max_discovery_items,
+            )
+            await tool.connect()
+            return await self._invoke_connected_tool(tool, invocation)
+        finally:
+            if tool is not None:
+                await self._close_tool(tool)
+
+    async def _invoke_connected_tool(self, tool: MCPStreamableHTTPTool, invocation: MCPToolInvocation) -> MCPToolResult:
+        from agent_framework import Content
+        from agent_framework.exceptions import ToolExecutionException
+
+        if invocation.tool_name == self.LIST_TOOLS_TOOL_NAME:
+            return await self._invoke_list_tools(tool)
+        try:
+            raw = await tool.call_tool(invocation.tool_name, **invocation.arguments)
+        except ToolExecutionException as exc:
+            # Core chains protocol/transport failures, unlike remote is_error responses.
+            if exc.__cause__ is not None:
+                raise
+            logger.info(
+                "DefaultMCPToolHandler: tool '%s' on '%s' raised ToolExecutionException",
+                invocation.tool_name,
+                invocation.server_url,
+            )
+            message = str(exc) or type(exc).__name__
+            return MCPToolResult(outputs=[Content.from_text(f"Error: {message}")], is_error=True, error_message=message)
+
+        outputs = [Content.from_text(raw)] if isinstance(raw, str) else list(raw)
+        return MCPToolResult(outputs=outputs)
+
+    @staticmethod
+    async def _invoke_list_tools(tool: MCPStreamableHTTPTool) -> MCPToolResult:
+        """Preserve the catalog shape and pagination used by workflow expressions."""
+        from agent_framework import Content
+        from mcp import types as mcp_types
+
+        require_connection: Any = getattr(tool, "_require_connection", None)
+        connection: Any | None = None
+        session: Any | None = None
+        if callable(require_connection):
+            connection = require_connection()
+        else:
+            session = getattr(tool, "session", None)
+
+        if connection is None and session is None:
+            raise RuntimeError("MCP session is not connected; cannot list tools.")
+
+        collected: list[Any] = []
+        params: mcp_types.PaginatedRequestParams | None = None
+        while True:
+            if connection is not None:
+                tool_list = await connection.list_tools_page(params)
+            elif session is not None:
+                tool_list = await session.list_tools(params=params)
+            else:  # pragma: no cover - guarded before entering the loop
+                raise RuntimeError("MCP connection became unavailable while listing tools.")
+            collected.extend(tool_list.tools)
+            next_cursor = getattr(tool_list, "next_cursor", getattr(tool_list, "nextCursor", None))
+            if not next_cursor:
+                break
+            params = mcp_types.PaginatedRequestParams(cursor=next_cursor)
+
+        payload = {
+            "tools": [
+                {
+                    "name": item.name,
+                    "description": item.description,
+                    "inputSchema": getattr(item, "input_schema", getattr(item, "inputSchema", None)),
+                    "outputSchema": getattr(item, "output_schema", getattr(item, "outputSchema", None)),
+                }
+                for item in collected
+            ]
+        }
+        return MCPToolResult(outputs=[Content.from_text(json.dumps(payload, indent=2, allow_nan=False))])
+
+    @staticmethod
+    async def _close_tool(tool: MCPStreamableHTTPTool) -> None:
+        # The tool owns its SDK lifecycle task and any internally allocated HTTP client.
+        cleanup = asyncio.create_task(tool.close())
+        cancelled = False
+        try:
+            while not cleanup.done():
+                try:
+                    await asyncio.shield(cleanup)
+                except asyncio.CancelledError:
+                    cancelled = True
+            cleanup.result()
+        except Exception:
+            logger.warning("DefaultMCPToolHandler: error closing invocation MCP client", exc_info=True)
+        if cancelled:
+            raise asyncio.CancelledError