camel-ai 0.2.59__py3-none-any.whl → 0.2.82__py3-none-any.whl

camel/toolkits/mcp_toolkit.py

@@ -1,4 +1,4 @@
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -10,491 +10,221 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
-import inspect
+# ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
+
 import json
 import os
-import shlex
-from contextlib import AsyncExitStack, asynccontextmanager
-from datetime import timedelta
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    AsyncGenerator,
-    Callable,
-    Dict,
-    List,
-    Optional,
-    Set,
-    Union,
-    cast,
-)
-from urllib.parse import urlparse
+import warnings
+from contextlib import AsyncExitStack
+from typing import Any, Dict, List, Optional
 
-if TYPE_CHECKING:
-    from mcp import ClientSession, ListToolsResult, Tool
+from typing_extensions import TypeGuard
 
 from camel.logger import get_logger
-from camel.toolkits import BaseToolkit, FunctionTool
+from camel.toolkits.base import BaseToolkit
+from camel.toolkits.function_tool import FunctionTool
+from camel.utils.commons import run_async
+from camel.utils.mcp_client import MCPClient, create_mcp_client
 
 logger = get_logger(__name__)
 
+# Suppress parameter description warnings for MCP tools
+warnings.filterwarnings(
+    "ignore", message="Parameter description is missing", category=UserWarning
+)
 
-class MCPClient(BaseToolkit):
-    r"""Internal class that provides an abstraction layer to interact with
-    external tools using the Model Context Protocol (MCP). It supports three
-    modes of connection:
 
-    1. stdio mode: Connects via standard input/output streams for local
-       command-line interactions.
+class MCPConnectionError(Exception):
+    r"""Raised when MCP connection fails."""
 
-    2. SSE mode (HTTP Server-Sent Events): Connects via HTTP for persistent,
-       event-based interactions.
+    pass
 
-    3. streamable-http mode: Connects via HTTP for persistent, streamable
-        interactions.
 
-    Connection Lifecycle:
-        There are three ways to manage the connection lifecycle:
+class MCPToolError(Exception):
+    r"""Raised when MCP tool execution fails."""
 
-        1. Using the async context manager:
-           ```python
-           async with MCPClient(command_or_url="...") as client:
-               # Client is connected here
-               result = await client.some_tool()
-           # Client is automatically disconnected here
-           ```
+    pass
 
-        2. Using the factory method:
-           ```python
-           client = await MCPClient.create(command_or_url="...")
-           # Client is connected here
-           result = await client.some_tool()
-           # Don't forget to disconnect when done!
-           await client.disconnect()
-           ```
 
-        3. Using explicit connect/disconnect:
-           ```python
-           client = MCPClient(command_or_url="...")
-           await client.connect()
-           # Client is connected here
-           result = await client.some_tool()
-           # Don't forget to disconnect when done!
-           await client.disconnect()
-           ```
+_EMPTY_SCHEMA = {
+    "additionalProperties": False,
+    "type": "object",
+    "properties": {},
+    "required": [],
+}
 
 
-    Attributes:
-        command_or_url (str): URL for SSE mode or command executable for stdio
-            mode. (default: :obj:`None`)
-        args (List[str]): List of command-line arguments if stdio mode is used.
-            (default: :obj:`None`)
-        env (Dict[str, str]): Environment variables for the stdio mode command.
-            (default: :obj:`None`)
-        timeout (Optional[float]): Connection timeout.
-            (default: :obj:`None`)
-        headers (Dict[str, str]): Headers for the HTTP request.
-            (default: :obj:`None`)
-        strict (Optional[bool]): Whether to enforce strict mode for the
-            function call. (default: :obj:`False`)
+def ensure_strict_json_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    r"""Mutates the given JSON schema to ensure it conforms to the
+    `strict` standard that the OpenAI API expects.
     """
+    if schema == {}:
+        return _EMPTY_SCHEMA
+    return _ensure_strict_json_schema(schema, path=(), root=schema)
+
+
+def _ensure_strict_json_schema(
+    json_schema: object,
+    *,
+    path: tuple[str, ...],
+    root: dict[str, object],
+) -> dict[str, Any]:
+    if not is_dict(json_schema):
+        raise TypeError(
+            f"Expected {json_schema} to be a dictionary; path={path}"
+        )
 
-    def __init__(
-        self,
-        command_or_url: str,
-        args: Optional[List[str]] = None,
-        env: Optional[Dict[str, str]] = None,
-        timeout: Optional[float] = None,
-        headers: Optional[Dict[str, str]] = None,
-        strict: Optional[bool] = False,
-    ):
-        from mcp import Tool
-
-        super().__init__(timeout=timeout)
-
-        self.command_or_url = command_or_url
-        self.args = args or []
-        self.env = env or {}
-        self.headers = headers or {}
-        self.strict = strict
-
-        self._mcp_tools: List[Tool] = []
-        self._session: Optional['ClientSession'] = None
-        self._exit_stack = AsyncExitStack()
-        self._is_connected = False
-
-    async def connect(self):
-        r"""Explicitly connect to the MCP server.
-
-        Returns:
-            MCPClient: The client used to connect to the server.
-        """
-        from mcp.client.session import ClientSession
-        from mcp.client.sse import sse_client
-        from mcp.client.stdio import StdioServerParameters, stdio_client
-
-        if self._is_connected:
-            logger.warning("Server is already connected")
-            return self
-
-        try:
-            if urlparse(self.command_or_url).scheme in ("http", "https"):
-                (
-                    read_stream,
-                    write_stream,
-                ) = await self._exit_stack.enter_async_context(
-                    sse_client(
-                        self.command_or_url,
-                        headers=self.headers,
-                        timeout=self.timeout,
-                    )
-                )
-            else:
-                command = self.command_or_url
-                arguments = self.args
-                if not self.args:
-                    argv = shlex.split(command)
-                    if not argv:
-                        raise ValueError("Command is empty")
-
-                    command = argv[0]
-                    arguments = argv[1:]
-
-                if os.name == "nt" and command.lower() == "npx":
-                    command = "npx.cmd"
-
-                server_parameters = StdioServerParameters(
-                    command=command, args=arguments, env=self.env
-                )
-                (
-                    read_stream,
-                    write_stream,
-                ) = await self._exit_stack.enter_async_context(
-                    stdio_client(server_parameters)
-                )
-
-            self._session = await self._exit_stack.enter_async_context(
-                ClientSession(
-                    read_stream,
-                    write_stream,
-                    timedelta(seconds=self.timeout) if self.timeout else None,
-                )
+    defs = json_schema.get("$defs")
+    if is_dict(defs):
+        for def_name, def_schema in defs.items():
+            _ensure_strict_json_schema(
+                def_schema, path=(*path, "$defs", def_name), root=root
             )
-            await self._session.initialize()
-            list_tools_result = await self.list_mcp_tools()
-            self._mcp_tools = list_tools_result.tools
-            self._is_connected = True
-            return self
-        except Exception as e:
-            # Ensure resources are cleaned up on connection failure
-            await self.disconnect()
-            logger.error(f"Failed to connect to MCP server: {e}")
-            raise e
 
-    async def disconnect(self):
-        r"""Explicitly disconnect from the MCP server."""
-        # If the server is not connected, do nothing
-        if not self._is_connected:
-            return
-        self._is_connected = False
-        await self._exit_stack.aclose()
-        # Reset the exit stack and session for future reuse purposes
-        self._exit_stack = AsyncExitStack()
-        self._session = None
-
-    @asynccontextmanager
-    async def connection(self):
-        r"""Async context manager for establishing and managing the connection
-        with the MCP server. Automatically selects SSE or stdio mode based
-        on the provided `command_or_url`.
-
-        Yields:
-            MCPClient: Instance with active connection ready for tool
-                interaction.
-        """
-        try:
-            await self.connect()
-            yield self
-        finally:
-            await self.disconnect()
-
-    async def list_mcp_tools(self) -> Union[str, "ListToolsResult"]:
-        r"""Retrieves the list of available tools from the connected MCP
-        server.
-
-        Returns:
-            ListToolsResult: Result containing available MCP tools.
-        """
-        if not self._session:
-            return "MCP Client is not connected. Call `connection()` first."
-        try:
-            return await self._session.list_tools()
-        except Exception as e:
-            logger.exception("Failed to list MCP tools")
-            raise e
-
-    def generate_function_from_mcp_tool(self, mcp_tool: "Tool") -> Callable:
-        r"""Dynamically generates a Python callable function corresponding to
-        a given MCP tool.
+    definitions = json_schema.get("definitions")
+    if is_dict(definitions):
+        for definition_name, definition_schema in definitions.items():
+            _ensure_strict_json_schema(
+                definition_schema,
+                path=(*path, "definitions", definition_name),
+                root=root,
+            )
 
-        Args:
-            mcp_tool (Tool): The MCP tool definition received from the MCP
-                server.
+    typ = json_schema.get("type")
+    if typ == "object" and "additionalProperties" not in json_schema:
+        json_schema["additionalProperties"] = False
+    elif (
+        typ == "object"
+        and "additionalProperties" in json_schema
+        and json_schema["additionalProperties"]
+    ):
+        raise ValueError(
+            "additionalProperties should not be set for object types. This "
+            "could be because you're using an older version of Pydantic, or "
+            "because you configured additional properties to be allowed. If "
+            "you really need this, update the function or output tool "
+            "to not use a strict schema."
+        )
 
-        Returns:
-            Callable: A dynamically created async Python function that wraps
-                the MCP tool.
-        """
-        func_name = mcp_tool.name
-        func_desc = mcp_tool.description or "No description provided."
-        parameters_schema = mcp_tool.inputSchema.get("properties", {})
-        required_params = mcp_tool.inputSchema.get("required", [])
-
-        type_map = {
-            "string": str,
-            "integer": int,
-            "number": float,
-            "boolean": bool,
-            "array": list,
-            "object": dict,
+    # object types
+    # { 'type': 'object', 'properties': { 'a':  {...} } }
+    properties = json_schema.get("properties")
+    if is_dict(properties):
+        json_schema["required"] = list(properties.keys())
+        json_schema["properties"] = {
+            key: _ensure_strict_json_schema(
+                prop_schema, path=(*path, "properties", key), root=root
+            )
+            for key, prop_schema in properties.items()
         }
-        annotations = {}  # used to type hints
-        defaults: Dict[str, Any] = {}  # store default values
-
-        func_params = []
-        for param_name, param_schema in parameters_schema.items():
-            param_type = param_schema.get("type", "Any")
-            param_type = type_map.get(param_type, Any)
-
-            annotations[param_name] = param_type
-            if param_name not in required_params:
-                defaults[param_name] = None
 
-            func_params.append(param_name)
-
-        async def dynamic_function(**kwargs) -> str:
-            r"""Auto-generated function for MCP Tool interaction.
-
-            Args:
-                kwargs: Keyword arguments corresponding to MCP tool parameters.
-
-            Returns:
-                str: The textual result returned by the MCP tool.
-            """
-            from mcp.types import CallToolResult
+    # arrays
+    # { 'type': 'array', 'items': {...} }
+    items = json_schema.get("items")
+    if is_dict(items):
+        json_schema["items"] = _ensure_strict_json_schema(
+            items, path=(*path, "items"), root=root
+        )
 
-            missing_params: Set[str] = set(required_params) - set(
-                kwargs.keys()
+    # unions
+    any_of = json_schema.get("anyOf")
+    if is_list(any_of):
+        json_schema["anyOf"] = [
+            _ensure_strict_json_schema(
+                variant, path=(*path, "anyOf", str(i)), root=root
             )
-            if missing_params:
-                logger.warning(
-                    f"Missing required parameters: {missing_params}"
-                )
-                return "Missing required parameters."
-
-            if not self._session:
-                logger.error(
-                    "MCP Client is not connected. Call `connection()` first."
-                )
-                raise RuntimeError(
-                    "MCP Client is not connected. Call `connection()` first."
-                )
-
-            try:
-                result: CallToolResult = await self._session.call_tool(
-                    func_name, kwargs
-                )
-            except Exception as e:
-                logger.error(f"Failed to call MCP tool '{func_name}': {e!s}")
-                raise e
-
-            if not result.content or len(result.content) == 0:
-                return "No data available for this request."
+            for i, variant in enumerate(any_of)
+        ]
 
-            # Handle different content types
-            try:
-                content = result.content[0]
-                if content.type == "text":
-                    return content.text
-                elif content.type == "image":
-                    # Return image URL or data URI if available
-                    if hasattr(content, "url") and content.url:
-                        return f"Image available at: {content.url}"
-                    return "Image content received (data URI not shown)"
-                elif content.type == "embedded_resource":
-                    # Return resource information if available
-                    if hasattr(content, "name") and content.name:
-                        return f"Embedded resource: {content.name}"
-                    return "Embedded resource received"
-                else:
-                    msg = f"Received content of type '{content.type}'"
-                    return f"{msg} which is not fully supported yet."
-            except (IndexError, AttributeError) as e:
-                logger.error(
-                    f"Error processing content from MCP tool response: {e!s}"
+    # intersections
+    all_of = json_schema.get("allOf")
+    if is_list(all_of):
+        if len(all_of) == 1:
+            json_schema.update(
+                _ensure_strict_json_schema(
+                    all_of[0], path=(*path, "allOf", "0"), root=root
                 )
-                raise e
-
-        dynamic_function.__name__ = func_name
-        dynamic_function.__doc__ = func_desc
-        dynamic_function.__annotations__ = annotations
-
-        sig = inspect.Signature(
-            parameters=[
-                inspect.Parameter(
-                    name=param,
-                    kind=inspect.Parameter.KEYWORD_ONLY,
-                    default=defaults.get(param, inspect.Parameter.empty),
-                    annotation=annotations[param],
+            )
+            json_schema.pop("allOf")
+        else:
+            json_schema["allOf"] = [
+                _ensure_strict_json_schema(
+                    entry, path=(*path, "allOf", str(i)), root=root
                 )
-                for param in func_params
+                for i, entry in enumerate(all_of)
             ]
-        )
-        dynamic_function.__signature__ = sig  # type: ignore[attr-defined]
-
-        return dynamic_function
-
-    def _build_tool_schema(self, mcp_tool: "Tool") -> Dict[str, Any]:
-        input_schema = mcp_tool.inputSchema
-        properties = input_schema.get("properties", {})
-        required = input_schema.get("required", [])
-
-        parameters = {
-            "type": "object",
-            "properties": properties,
-            "required": required,
-            "additionalProperties": False,
-        }
-
-        return {
-            "type": "function",
-            "function": {
-                "name": mcp_tool.name,
-                "description": mcp_tool.description
-                or "No description provided.",
-                "strict": self.strict,
-                "parameters": parameters,
-            },
-        }
-
-    def get_tools(self) -> List[FunctionTool]:
-        r"""Returns a list of FunctionTool objects representing the
-        functions in the toolkit. Each function is dynamically generated
-        based on the MCP tool definitions received from the server.
 
-        Returns:
-            List[FunctionTool]: A list of FunctionTool objects
-                representing the functions in the toolkit.
-        """
-        return [
-            FunctionTool(
-                self.generate_function_from_mcp_tool(mcp_tool),
-                openai_tool_schema=self._build_tool_schema(mcp_tool),
+    # strip `None` defaults as there's no meaningful distinction here
+    # the schema will still be `nullable` and the model will default
+    # to using `None` anyway
+    if json_schema.get("default", None) is None:
+        json_schema.pop("default", None)
+
+    # we can't use `$ref`s if there are also other properties defined, e.g.
+    # `{"$ref": "...", "description": "my description"}`
+    #
+    # so we unravel the ref
+    # `{"type": "string", "description": "my description"}`
+    ref = json_schema.get("$ref")
+    if ref and has_more_than_n_keys(json_schema, 1):
+        assert isinstance(ref, str), f"Received non-string $ref - {ref}"
+
+        resolved = resolve_ref(root=root, ref=ref)
+        if not is_dict(resolved):
+            raise ValueError(
+                f"Expected `$ref: {ref}` to resolved to a dictionary but got "
+                f"{resolved}"
             )
-            for mcp_tool in self._mcp_tools
-        ]
-
-    def get_text_tools(self) -> str:
-        r"""Returns a string containing the descriptions of the tools
-        in the toolkit.
-
-        Returns:
-            str: A string containing the descriptions of the tools
-                in the toolkit.
-        """
-        return "\n".join(
-            f"tool_name: {tool.name}\n"
-            + f"description: {tool.description or 'No description'}\n"
-            + f"input Schema: {tool.inputSchema}\n"
-            for tool in self._mcp_tools
-        )
-
-    async def call_tool(
-        self, tool_name: str, tool_args: Dict[str, Any]
-    ) -> Any:
-        r"""Calls the specified tool with the provided arguments.
 
-        Args:
-            tool_name (str): Name of the tool to call.
-            tool_args (Dict[str, Any]): Arguments to pass to the tool
-                (default: :obj:`{}`).
+        # properties from the json schema take priority
+        # over the ones on the `$ref`
+        json_schema.update({**resolved, **json_schema})
+        json_schema.pop("$ref")
+        # Since the schema expanded from `$ref` might not
+        # have `additionalProperties: false` applied
+        # we call `_ensure_strict_json_schema` again to fix the inlined
+        # schema and ensure it's valid
+        return _ensure_strict_json_schema(json_schema, path=path, root=root)
 
-        Returns:
-            Any: The result of the tool call.
-        """
-        if self._session is None:
-            raise RuntimeError("Session is not initialized.")
+    return json_schema
 
-        return await self._session.call_tool(tool_name, tool_args)
 
-    @property
-    def session(self) -> Optional["ClientSession"]:
-        return self._session
+def resolve_ref(*, root: dict[str, object], ref: str) -> object:
+    if not ref.startswith("#/"):
+        raise ValueError(
+            f"Unexpected $ref format {ref!r}; Does not start with #/"
+        )
 
-    @classmethod
-    async def create(
-        cls,
-        command_or_url: str,
-        args: Optional[List[str]] = None,
-        env: Optional[Dict[str, str]] = None,
-        timeout: Optional[float] = None,
-        headers: Optional[Dict[str, str]] = None,
-    ) -> "MCPClient":
-        r"""Factory method that creates and connects to the MCP server.
+    path = ref[2:].split("/")
+    resolved = root
+    for key in path:
+        value = resolved[key]
+        assert is_dict(value), (
+            f"encountered non-dictionary entry while resolving {ref} - "
+            f"{resolved}"
+        )
+        resolved = value
 
-        This async factory method ensures the connection to the MCP server is
-        established before the client object is fully constructed.
+    return resolved
 
-        Args:
-            command_or_url (str): URL for SSE mode or command executable
-                for stdio mode.
-            args (Optional[List[str]]): List of command-line arguments if
-                stdio mode is used. (default: :obj:`None`)
-            env (Optional[Dict[str, str]]): Environment variables for
-                the stdio mode command. (default: :obj:`None`)
-            timeout (Optional[float]): Connection timeout.
-                (default: :obj:`None`)
-            headers (Optional[Dict[str, str]]): Headers for the HTTP request.
-                (default: :obj:`None`)
 
-        Returns:
-            MCPClient: A fully initialized and connected MCPClient instance.
+def is_dict(obj: object) -> TypeGuard[dict[str, object]]:
+    # just pretend that we know there are only `str` keys
+    # as that check is not worth the performance cost
+    return isinstance(obj, dict)
 
-        Raises:
-            RuntimeError: If connection to the MCP server fails.
-        """
-        client = cls(
-            command_or_url=command_or_url,
-            args=args,
-            env=env,
-            timeout=timeout,
-            headers=headers,
-        )
-        try:
-            await client.connect()
-            return client
-        except Exception as e:
-            # Ensure cleanup on initialization failure
-            await client.disconnect()
-            logger.error(f"Failed to initialize MCPClient: {e}")
-            raise RuntimeError(f"Failed to initialize MCPClient: {e}") from e
 
-    async def __aenter__(self) -> "MCPClient":
-        r"""Async context manager entry point. Automatically connects to the
-        MCP server when used in an async with statement.
+def is_list(obj: object) -> TypeGuard[list[object]]:
+    return isinstance(obj, list)
 
-        Returns:
-            MCPClient: Self with active connection.
-        """
-        await self.connect()
-        return self
 
-    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
-        r"""Async context manager exit point. Automatically disconnects from
-        the MCP server when exiting an async with statement.
-        """
-        await self.disconnect()
+def has_more_than_n_keys(obj: dict[str, object], n: int) -> bool:
+    i = 0
+    for _ in obj.keys():
+        i += 1
+        if i > n:
+            return True
+    return False
 
 
 class MCPToolkit(BaseToolkit):
@@ -503,56 +233,69 @@ class MCPToolkit(BaseToolkit):
 
     This class handles the lifecycle of multiple MCP server connections and
     offers a centralized configuration mechanism for both local and remote
-    MCP services.
+    MCP services. The toolkit manages multiple :obj:`MCPClient` instances and
+    aggregates their tools into a unified interface compatible with the CAMEL
+    framework.
 
     Connection Lifecycle:
         There are three ways to manage the connection lifecycle:
 
-        1. Using the async context manager:
-           ```python
-           async with MCPToolkit(config_path="config.json") as toolkit:
-               # Toolkit is connected here
-               tools = toolkit.get_tools()
-           # Toolkit is automatically disconnected here
-           ```
+        1. Using the async context manager (recommended):
+
+           .. code-block:: python
+
+               async with MCPToolkit(config_path="config.json") as toolkit:
+                   # Toolkit is connected here
+                   tools = toolkit.get_tools()
+               # Toolkit is automatically disconnected here
 
         2. Using the factory method:
-           ```python
-           toolkit = await MCPToolkit.create(config_path="config.json")
-           # Toolkit is connected here
-           tools = toolkit.get_tools()
-           # Don't forget to disconnect when done!
-           await toolkit.disconnect()
-           ```
+
+           .. code-block:: python
+
+               toolkit = await MCPToolkit.create(config_path="config.json")
+               # Toolkit is connected here
+               tools = toolkit.get_tools()
+               # Don't forget to disconnect when done!
+               await toolkit.disconnect()
 
         3. Using explicit connect/disconnect:
-           ```python
-           toolkit = MCPToolkit(config_path="config.json")
-           await toolkit.connect()
-           # Toolkit is connected here
-           tools = toolkit.get_tools()
-           # Don't forget to disconnect when done!
-           await toolkit.disconnect()
-           ```
+
+           .. code-block:: python
+
+               toolkit = MCPToolkit(config_path="config.json")
+               await toolkit.connect()
+               # Toolkit is connected here
+               tools = toolkit.get_tools()
+               # Don't forget to disconnect when done!
+               await toolkit.disconnect()
+
+    Note:
+        Both MCPClient and MCPToolkit now use the same async context manager
+        pattern for consistent connection management. MCPToolkit automatically
+        manages multiple MCPClient instances using AsyncExitStack.
 
     Args:
-        servers (Optional[List[MCPClient]]): List of MCPClient
+        clients (Optional[List[MCPClient]], optional): List of :obj:`MCPClient`
             instances to manage. (default: :obj:`None`)
-        config_path (Optional[str]): Path to a JSON configuration file
-            defining MCP servers. (default: :obj:`None`)
-        config_dict (Optional[Dict[str, Any]]): Dictionary containing MCP
-            server configurations in the same format as the config file.
+        config_path (Optional[str], optional): Path to a JSON configuration
+            file defining MCP servers. The file should contain server
+            configurations in the standard MCP format. (default: :obj:`None`)
+        config_dict (Optional[Dict[str, Any]], optional): Dictionary containing
+            MCP server configurations in the same format as the config file.
+            This allows for programmatic configuration without file I/O.
+            (default: :obj:`None`)
+        timeout (Optional[float], optional): Timeout for connection attempts
+            in seconds. This timeout applies to individual client connections.
             (default: :obj:`None`)
-        strict (Optional[bool]): Whether to enforce strict mode for the
-            function call. (default: :obj:`False`)
 
     Note:
-        Either `servers`, `config_path`, or `config_dict` must be provided.
-        If multiple are provided, servers from all sources will be combined.
+        At least one of :obj:`clients`, :obj:`config_path`, or
+        :obj:`config_dict` must be provided. If multiple sources are provided,
+        clients from all sources will be combined.
 
-        For web servers in the config, you can specify authorization
-        headers using the "headers" field to connect to protected MCP server
-        endpoints.
+        For web servers in the config, you can specify authorization headers
+        using the "headers" field to connect to protected MCP server endpoints.
 
         Example configuration:
 
@@ -560,6 +303,11 @@ class MCPToolkit(BaseToolkit):
 
             {
               "mcpServers": {
+                "filesystem": {
+                  "command": "npx",
+                  "args": ["-y", "@modelcontextprotocol/server-filesystem",
+                           "/path"]
+                },
                 "protected-server": {
                   "url": "https://example.com/mcp",
                   "timeout": 30,
@@ -572,189 +320,682 @@ class MCPToolkit(BaseToolkit):
             }
 
     Attributes:
-        servers (List[MCPClient]): List of MCPClient instances being managed.
+        clients (List[MCPClient]): List of :obj:`MCPClient` instances being
+            managed by this toolkit.
+
+    Raises:
+        ValueError: If no configuration sources are provided or if the
+            configuration is invalid.
+        MCPConnectionError: If connection to any MCP server fails during
+            initialization.
     """
 
     def __init__(
         self,
-        servers: Optional[List[MCPClient]] = None,
+        clients: Optional[List[MCPClient]] = None,
         config_path: Optional[str] = None,
         config_dict: Optional[Dict[str, Any]] = None,
-        strict: Optional[bool] = False,
+        timeout: Optional[float] = None,
     ):
-        super().__init__()
+        # Call parent constructor first
+        super().__init__(timeout=timeout)
 
+        # Validate input parameters
         sources_provided = sum(
-            1 for src in [servers, config_path, config_dict] if src is not None
+            1 for src in [clients, config_path, config_dict] if src is not None
         )
-        if sources_provided > 1:
-            logger.warning(
-                "Multiple configuration sources provided "
-                f"({sources_provided}). Servers from all sources "
-                "will be combined."
+        if sources_provided == 0:
+            error_msg = (
+                "At least one of clients, config_path, or "
+                "config_dict must be provided"
             )
+            raise ValueError(error_msg)
 
-        self.servers: List[MCPClient] = servers or []
+        self.clients: List[MCPClient] = clients or []
+        self._is_connected = False
+        self._exit_stack: Optional[AsyncExitStack] = None
 
+        # Load clients from config sources
         if config_path:
-            self.servers.extend(
-                self._load_servers_from_config(config_path, strict)
-            )
+            self.clients.extend(self._load_clients_from_config(config_path))
 
         if config_dict:
-            self.servers.extend(self._load_servers_from_dict(config_dict))
+            self.clients.extend(self._load_clients_from_dict(config_dict))
 
-        self._connected = False
+        if not self.clients:
+            raise ValueError("No valid MCP clients could be created")
 
-    def _load_servers_from_config(
-        self, config_path: str, strict: Optional[bool] = False
-    ) -> List[MCPClient]:
-        r"""Loads MCP server configurations from a JSON file.
+    async def connect(self) -> "MCPToolkit":
+        r"""Connect to all MCP servers using AsyncExitStack.
 
-        Args:
-            config_path (str): Path to the JSON configuration file.
-            strict (bool): Whether to enforce strict mode for the
-                function call. (default: :obj:`False`)
+        Establishes connections to all configured MCP servers sequentially.
+        Uses :obj:`AsyncExitStack` to manage the lifecycle of all connections,
+        ensuring proper cleanup on exit or error.
 
         Returns:
-            List[MCPClient]: List of configured MCPClient instances.
+            MCPToolkit: Returns :obj:`self` for method chaining, allowing for
+                fluent interface usage.
+
+        Raises:
+            MCPConnectionError: If connection to any MCP server fails. The
+                error message will include details about which client failed
+                to connect and the underlying error reason.
+
+        Warning:
+            If any client fails to connect, all previously established
+            connections will be automatically cleaned up before raising
+            the exception.
+
+        Example:
+            .. code-block:: python
+
+                toolkit = MCPToolkit(config_dict=config)
+                try:
+                    await toolkit.connect()
+                    # Use the toolkit
+                    tools = toolkit.get_tools()
+                finally:
+                    await toolkit.disconnect()
         """
+        if self._is_connected:
+            logger.warning("MCPToolkit is already connected")
+            return self
+
+        self._exit_stack = AsyncExitStack()
+
         try:
-            with open(config_path, "r", encoding="utf-8") as f:
-                try:
-                    data = json.load(f)
-                except json.JSONDecodeError as e:
-                    logger.warning(
-                        f"Invalid JSON in config file '{config_path}': {e!s}"
-                    )
-                    raise e
-        except FileNotFoundError as e:
-            logger.warning(f"Config file not found: '{config_path}'")
-            raise e
+            # Apply timeout to the entire connection process
+            import asyncio
 
-        return self._load_servers_from_dict(config=data, strict=strict)
+            timeout_seconds = self.timeout or 30.0
+            await asyncio.wait_for(
+                self._connect_all_clients(), timeout=timeout_seconds
+            )
 
-    def _load_servers_from_dict(
-        self, config: Dict[str, Any], strict: Optional[bool] = False
-    ) -> List[MCPClient]:
-        r"""Loads MCP server configurations from a dictionary.
+            self._is_connected = True
+            msg = f"Successfully connected to {len(self.clients)} MCP servers"
+            logger.info(msg)
+            return self
 
-        Args:
-            config (Dict[str, Any]): Dictionary containing server
-                configurations.
-            strict (bool): Whether to enforce strict mode for the
-                function call. (default: :obj:`False`)
+        except (asyncio.TimeoutError, asyncio.CancelledError):
+            self._is_connected = False
+            if self._exit_stack:
+                await self._exit_stack.aclose()
+                self._exit_stack = None
+
+            timeout_seconds = self.timeout or 30.0
+            error_msg = (
+                f"Connection timeout after {timeout_seconds}s. "
+                f"One or more MCP servers are not responding. "
+                f"Please check if the servers are running and accessible."
+            )
+            logger.error(error_msg)
+            raise MCPConnectionError(error_msg)
+
+        except Exception:
+            self._is_connected = False
+            if self._exit_stack:
+                await self._exit_stack.aclose()
+                self._exit_stack = None
+            raise
+
+    async def _connect_all_clients(self):
+        r"""Connect to all clients sequentially."""
+        # Connect to all clients using AsyncExitStack
+        for i, client in enumerate(self.clients):
+            try:
+                # Use MCPClient directly as async context manager
+                await self._exit_stack.enter_async_context(client)
+                msg = f"Connected to client {i+1}/{len(self.clients)}"
+                logger.debug(msg)
+            except Exception as e:
+                logger.error(f"Failed to connect to client {i+1}: {e}")
+                # AsyncExitStack will cleanup already connected clients
+                await self._exit_stack.aclose()
+                self._exit_stack = None
+                error_msg = f"Failed to connect to client {i+1}: {e}"
+                raise MCPConnectionError(error_msg) from e
+
+    async def disconnect(self):
+        r"""Disconnect from all MCP servers."""
+        if not self._is_connected:
+            return
+
+        if self._exit_stack:
+            try:
+                await self._exit_stack.aclose()
+            except Exception as e:
+                logger.warning(f"Error during disconnect: {e}")
+            finally:
+                self._exit_stack = None
+
+        self._is_connected = False
+        logger.debug("Disconnected from all MCP servers")
+
+    @property
+    def is_connected(self) -> bool:
+        r"""Check if toolkit is connected.
 
         Returns:
-            List[MCPClient]: List of configured MCPClient instances.
+            bool: True if the toolkit is connected to all MCP servers,
+                False otherwise.
         """
-        all_servers = []
+        if not self._is_connected:
+            return False
 
-        mcp_servers = config.get("mcpServers", {})
-        if not isinstance(mcp_servers, dict):
-            logger.warning("'mcpServers' is not a dictionary, skipping...")
-            mcp_servers = {}
+        # Check if all clients are connected
+        return all(client.is_connected() for client in self.clients)
 
-        for name, cfg in mcp_servers.items():
-            if not isinstance(cfg, dict):
-                logger.warning(
-                    f"Configuration for server '{name}' must be a dictionary"
-                )
-                continue
+    def connect_sync(self):
+        r"""Synchronously connect to all MCP servers."""
+        return run_async(self.connect)()
 
-            if "command" not in cfg and "url" not in cfg:
-                logger.warning(
-                    f"Missing required 'command' or 'url' field for server "
-                    f"'{name}'"
-                )
-                continue
+    def disconnect_sync(self):
+        r"""Synchronously disconnect from all MCP servers."""
+        return run_async(self.disconnect)()
 
-            # Include headers if provided in the configuration
-            headers = cfg.get("headers", {})
-
-            cmd_or_url = cast(str, cfg.get("command") or cfg.get("url"))
-            server = MCPClient(
-                command_or_url=cmd_or_url,
-                args=cfg.get("args", []),
-                env={**os.environ, **cfg.get("env", {})},
-                timeout=cfg.get("timeout", None),
-                headers=headers,
-                strict=strict,
-            )
-            all_servers.append(server)
+    async def __aenter__(self) -> "MCPToolkit":
+        r"""Async context manager entry point.
+
+        Usage:
+            async with MCPToolkit(config_dict=config) as toolkit:
+                tools = toolkit.get_tools()
+        """
+        await self.connect()
+        return self
+
+    def __enter__(self) -> "MCPToolkit":
+        r"""Synchronously enter the async context manager."""
+        return run_async(self.__aenter__)()
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        r"""Async context manager exit point."""
+        await self.disconnect()
+        return None
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        r"""Synchronously exit the async context manager."""
+        return run_async(self.__aexit__)(exc_type, exc_val, exc_tb)
 
-        return all_servers
+    @classmethod
+    async def create(
+        cls,
+        clients: Optional[List[MCPClient]] = None,
+        config_path: Optional[str] = None,
+        config_dict: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+    ) -> "MCPToolkit":
+        r"""Factory method that creates and connects to all MCP servers.
+
+        Creates a new :obj:`MCPToolkit` instance and automatically establishes
+        connections to all configured MCP servers. This is a convenience method
+        that combines instantiation and connection in a single call.
 
-    async def connect(self):
-        r"""Explicitly connect to all MCP servers.
+        Args:
+            clients (Optional[List[MCPClient]], optional): List of
+                :obj:`MCPClient` instances to manage. (default: :obj:`None`)
+            config_path (Optional[str], optional): Path to a JSON configuration
+                file defining MCP servers. (default: :obj:`None`)
+            config_dict (Optional[Dict[str, Any]], optional): Dictionary
+                containing MCP server configurations in the same format as the
+                config file. (default: :obj:`None`)
+            timeout (Optional[float], optional): Timeout for connection
+                attempts in seconds. (default: :obj:`None`)
 
         Returns:
-            MCPToolkit: The connected toolkit instance
+            MCPToolkit: A fully initialized and connected :obj:`MCPToolkit`
+                instance with all servers ready for use.
+
+        Raises:
+            MCPConnectionError: If connection to any MCP server fails during
+                initialization. All successfully connected servers will be
+                properly disconnected before raising the exception.
+            ValueError: If no configuration sources are provided or if the
+                configuration is invalid.
+
+        Example:
+            .. code-block:: python
+
+                # Create and connect in one step
+                toolkit = await MCPToolkit.create(config_path="servers.json")
+                try:
+                    tools = toolkit.get_tools()
+                    # Use the toolkit...
+                finally:
+                    await toolkit.disconnect()
         """
-        if self._connected:
-            logger.warning("MCPToolkit is already connected")
-            return self
+        toolkit = cls(
+            clients=clients,
+            config_path=config_path,
+            config_dict=config_dict,
+            timeout=timeout,
+        )
+        try:
+            await toolkit.connect()
+            return toolkit
+        except Exception as e:
+            # Ensure cleanup on initialization failure
+            await toolkit.disconnect()
+            logger.error(f"Failed to initialize MCPToolkit: {e}")
+            raise MCPConnectionError(
+                f"Failed to initialize MCPToolkit: {e}"
+            ) from e
+
+    @classmethod
+    def create_sync(
+        cls,
+        clients: Optional[List[MCPClient]] = None,
+        config_path: Optional[str] = None,
+        config_dict: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+    ) -> "MCPToolkit":
+        r"""Synchronously create and connect to all MCP servers."""
+        return run_async(cls.create)(
+            clients, config_path, config_dict, timeout
+        )
+
+    def _load_clients_from_config(self, config_path: str) -> List[MCPClient]:
+        r"""Load clients from configuration file."""
+        if not os.path.exists(config_path):
+            raise FileNotFoundError(f"Config file not found: '{config_path}'")
 
         try:
-            # Sequentially connect to each server
-            for server in self.servers:
-                await server.connect()
-            self._connected = True
-            return self
+            with open(config_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except json.JSONDecodeError as e:
+            error_msg = f"Invalid JSON in config file '{config_path}': {e}"
+            raise ValueError(error_msg) from e
         except Exception as e:
-            # Ensure resources are cleaned up on connection failure
-            await self.disconnect()
-            logger.error(f"Failed to connect to one or more MCP servers: {e}")
-            raise e
+            error_msg = f"Error reading config file '{config_path}': {e}"
+            raise IOError(error_msg) from e
 
-    async def disconnect(self):
-        r"""Explicitly disconnect from all MCP servers."""
-        if not self._connected:
-            return
+        return self._load_clients_from_dict(data)
+
+    def _load_clients_from_dict(
+        self, config: Dict[str, Any]
+    ) -> List[MCPClient]:
+        r"""Load clients from configuration dictionary."""
+        if not isinstance(config, dict):
+            raise ValueError("Config must be a dictionary")
+
+        mcp_servers = config.get("mcpServers", {})
+        if not isinstance(mcp_servers, dict):
+            raise ValueError("'mcpServers' must be a dictionary")
+
+        clients = []
+
+        for name, cfg in mcp_servers.items():
+            try:
+                if "timeout" not in cfg and self.timeout is not None:
+                    cfg["timeout"] = self.timeout
+
+                client = self._create_client_from_config(name, cfg)
+                clients.append(client)
+            except Exception as e:
+                logger.error(f"Failed to create client for '{name}': {e}")
+                error_msg = f"Invalid configuration for server '{name}': {e}"
+                raise ValueError(error_msg) from e
 
-        for server in self.servers:
-            await server.disconnect()
-        self._connected = False
+        return clients
 
-    @asynccontextmanager
-    async def connection(self) -> AsyncGenerator["MCPToolkit", None]:
-        r"""Async context manager that simultaneously establishes connections
-        to all managed MCP server instances.
+    def _create_client_from_config(
+        self, name: str, cfg: Dict[str, Any]
+    ) -> MCPClient:
+        r"""Create a single MCP client from configuration."""
+        if not isinstance(cfg, dict):
+            error_msg = f"Configuration for server '{name}' must be a dict"
+            raise ValueError(error_msg)
+
+        try:
+            # Use the new mcp_client factory function
+            # Pass timeout from toolkit if available
+            kwargs = {}
+            if hasattr(self, "timeout") and self.timeout is not None:
+                kwargs["timeout"] = self.timeout
 
-        Yields:
-            MCPToolkit: Self with all servers connected.
+            client = create_mcp_client(cfg, **kwargs)
+            return client
+        except Exception as e:
+            error_msg = f"Failed to create client for server '{name}': {e}"
+            raise ValueError(error_msg) from e
+
+    def _ensure_strict_tool_schema(self, tool: FunctionTool) -> FunctionTool:
+        r"""Ensure a tool has a strict schema compatible with
+        OpenAI's requirements.
+
+        Strategy:
+        - Ensure parameters exist with at least an empty properties object
+            (OpenAI requirement).
+        - Try converting parameters to strict using ensure_strict_json_schema.
+        - If conversion fails, mark function.strict = False and
+            keep best-effort parameters.
         """
         try:
-            await self.connect()
-            yield self
-        finally:
-            await self.disconnect()
+            schema = tool.get_openai_tool_schema()
+
+            def _has_strict_mode_incompatible_features(json_schema):
+                r"""Check if schema has features incompatible
+                with OpenAI strict mode."""
+
+                def _check_incompatible(obj, path=""):
+                    if not isinstance(obj, dict):
+                        return False
+
+                    # Check for allOf in array items (known to cause issues)
+                    if "items" in obj and isinstance(obj["items"], dict):
+                        items_schema = obj["items"]
+                        if "allOf" in items_schema:
+                            logger.debug(
+                                f"Found allOf in array items at {path}"
+                            )
+                            return True
+                        # Recursively check items schema
+                        if _check_incompatible(items_schema, f"{path}.items"):
+                            return True
+
+                    # Check for other potentially problematic patterns
+                    # anyOf/oneOf in certain contexts can also cause issues
+                    if (
+                        "anyOf" in obj and len(obj["anyOf"]) > 10
+                    ):  # Large unions can be problematic
+                        return True
+
+                    # Recursively check nested objects
+                    for key in [
+                        "properties",
+                        "additionalProperties",
+                        "patternProperties",
+                    ]:
+                        if key in obj and isinstance(obj[key], dict):
+                            if key == "properties":
+                                for prop_name, prop_schema in obj[key].items():
+                                    if isinstance(
+                                        prop_schema, dict
+                                    ) and _check_incompatible(
+                                        prop_schema,
+                                        f"{path}.{key}.{prop_name}",
+                                    ):
+                                        return True
+                            elif _check_incompatible(
+                                obj[key], f"{path}.{key}"
+                            ):
+                                return True
+
+                    # Check arrays and unions
+                    for key in ["allOf", "anyOf", "oneOf"]:
+                        if key in obj and isinstance(obj[key], list):
+                            for i, item in enumerate(obj[key]):
+                                if isinstance(
+                                    item, dict
+                                ) and _check_incompatible(
+                                    item, f"{path}.{key}[{i}]"
+                                ):
+                                    return True
+
+                    return False
+
+                return _check_incompatible(json_schema)
+
+            # Apply sanitization if available
+            if "function" in schema:
+                try:
+                    from camel.toolkits.function_tool import (
+                        sanitize_and_enforce_required,
+                    )
 
-    def is_connected(self) -> bool:
-        r"""Checks if all the managed servers are connected.
+                    schema = sanitize_and_enforce_required(schema)
+                except ImportError:
+                    logger.debug("sanitize_and_enforce_required not available")
+
+                parameters = schema["function"].get("parameters", {})
+                if not parameters:
+                    # Empty parameters - use minimal valid schema
+                    parameters = {
+                        "type": "object",
+                        "properties": {},
+                        "additionalProperties": False,
+                    }
+                    schema["function"]["parameters"] = parameters
+
+                # MCP spec doesn't require 'properties', but OpenAI spec does
+                if (
+                    parameters.get("type") == "object"
+                    and "properties" not in parameters
+                ):
+                    parameters["properties"] = {}
 
-        Returns:
-            bool: True if connected, False otherwise.
-        """
-        return self._connected
+                try:
+                    # _check_schema_limits(parameters)
+
+                    # Check for OpenAI strict mode incompatible features
+                    if _has_strict_mode_incompatible_features(parameters):
+                        raise ValueError(
+                            "Schema contains features "
+                            "incompatible with strict mode"
+                        )
+
+                    strict_params = ensure_strict_json_schema(parameters)
+                    schema["function"]["parameters"] = strict_params
+                    schema["function"]["strict"] = True
+                except Exception as e:
+                    # Fallback to non-strict mode on any failure
+                    schema["function"]["strict"] = False
+                    logger.warning(
+                        f"Tool '{tool.get_function_name()}' "
+                        f"cannot use strict mode: {e}"
+                    )
+
+            tool.set_openai_tool_schema(schema)
+
+        except Exception as e:
+            # Final fallback - ensure tool still works
+            try:
+                current_schema = tool.get_openai_tool_schema()
+                if "function" in current_schema:
+                    current_schema["function"]["strict"] = False
+                tool.set_openai_tool_schema(current_schema)
+                logger.warning(
+                    f"Error processing schema for tool "
+                    f"'{tool.get_function_name()}': {str(e)[:100]}. "
+                    f"Using non-strict mode."
+                )
+            except Exception as inner_e:
+                logger.error(
+                    f"Critical error processing tool "
+                    f"'{tool.get_function_name()}': {inner_e}. "
+                    f"Tool may not function correctly."
+                )
+
+        return tool
 
     def get_tools(self) -> List[FunctionTool]:
-        r"""Aggregates all tools from the managed MCP server instances.
+        r"""Aggregates all tools from the managed MCP client instances.
+
+        Collects and combines tools from all connected MCP clients into a
+        single unified list. Each tool is converted to a CAMEL-compatible
+        :obj:`FunctionTool` that can be used with CAMEL agents. All tools
+        are ensured to have strict schemas compatible with OpenAI's
+        requirements.
 
         Returns:
-            List[FunctionTool]: Combined list of all available function tools.
+            List[FunctionTool]: Combined list of all available function tools
+                from all connected MCP servers with strict schemas. Returns an
+                empty list if no clients are connected or if no tools are
+                available.
+
+        Note:
+            This method can be called even when the toolkit is not connected,
+            but it will log a warning and may return incomplete results.
+            For best results, ensure the toolkit is connected before calling
+            this method.
+
+        Example:
+            .. code-block:: python
+
+                async with MCPToolkit(config_dict=config) as toolkit:
+                    tools = toolkit.get_tools()
+                    print(f"Available tools: {len(tools)}")
+                    for tool in tools:
+                        print(f"  - {tool.func.__name__}")
         """
+        if not self.is_connected:
+            logger.warning(
+                "MCPToolkit is not connected. "
+                "Tools may not be available until connected."
+            )
+
         all_tools = []
-        for server in self.servers:
-            all_tools.extend(server.get_tools())
+        seen_names: set[str] = set()
+        for i, client in enumerate(self.clients):
+            try:
+                client_tools = client.get_tools()
+
+                # Ensure all tools have strict schemas
+                strict_tools = []
+                for tool in client_tools:
+                    strict_tool = self._ensure_strict_tool_schema(tool)
+                    name = strict_tool.get_function_name()
+                    if name in seen_names:
+                        logger.warning(
+                            f"Duplicate tool name detected and "
+                            f"skipped: '{name}' from client {i+1}"
+                        )
+                        continue
+                    seen_names.add(name)
+                    strict_tools.append(strict_tool)
+
+                all_tools.extend(strict_tools)
+                logger.debug(
+                    f"Client {i+1} contributed {len(strict_tools)} "
+                    f"tools (strict mode enabled)"
+                )
+            except Exception as e:
+                logger.error(f"Failed to get tools from client {i+1}: {e}")
+
+        logger.info(
+            f"Total tools available: {len(all_tools)} (all with strict "
+            f"schemas)"
+        )
         return all_tools
 
     def get_text_tools(self) -> str:
-        r"""Returns a string containing the descriptions of the tools
-        in the toolkit.
+        r"""Returns a string containing the descriptions of the tools.
+
+        Returns:
+            str: A string containing the descriptions of all tools.
+        """
+        if not self.is_connected:
+            logger.warning(
+                "MCPToolkit is not connected. "
+                "Tool descriptions may not be available until connected."
+            )
+
+        tool_descriptions = []
+        for i, client in enumerate(self.clients):
+            try:
+                client_tools_text = client.get_text_tools()
+                if client_tools_text:
+                    tool_descriptions.append(
+                        f"=== Client {i+1} Tools ===\n{client_tools_text}"
+                    )
+            except Exception as e:
+                logger.error(
+                    f"Failed to get tool descriptions from client {i+1}: {e}"
+                )
+
+        return "\n\n".join(tool_descriptions)
+
+    async def call_tool(
+        self, tool_name: str, tool_args: Dict[str, Any]
+    ) -> Any:
+        r"""Call a tool by name across all managed clients.
+
+        Searches for and executes a tool with the specified name across all
+        connected MCP clients. The method will try each client in sequence
+        until the tool is found and successfully executed.
+
+        Args:
+            tool_name (str): Name of the tool to call. Must match a tool name
+                available from one of the connected MCP servers.
+            tool_args (Dict[str, Any]): Arguments to pass to the tool. The
+                argument names and types must match the tool's expected
+                parameters.
+
+        Returns:
+            Any: The result of the tool call. The type and structure depend
+                on the specific tool being called.
+
+        Raises:
+            MCPConnectionError: If the toolkit is not connected to any MCP
+                servers.
+            MCPToolError: If the tool is not found in any client, or if all
+                attempts to call the tool fail. The error message will include
+                details about the last failure encountered.
+
+        Example:
+            .. code-block:: python
+
+                async with MCPToolkit(config_dict=config) as toolkit:
+                    # Call a file reading tool
+                    result = await toolkit.call_tool(
+                        "read_file",
+                        {"path": "/tmp/example.txt"}
+                    )
+                    print(f"File contents: {result}")
+        """
+        if not self.is_connected:
+            raise MCPConnectionError(
+                "MCPToolkit is not connected. Call connect() first."
+            )
+
+        # Try to find and call the tool from any client
+        last_error = None
+        for i, client in enumerate(self.clients):
+            try:
+                # Check if this client has the tool
+                tools = client.get_tools()
+                tool_names = [tool.func.__name__ for tool in tools]
+
+                if tool_name in tool_names:
+                    result = await client.call_tool(tool_name, tool_args)
+                    logger.debug(
+                        f"Tool '{tool_name}' called successfully "
+                        f"on client {i+1}"
+                    )
+                    return result
+            except Exception as e:
+                last_error = e
+                logger.debug(f"Tool '{tool_name}' failed on client {i+1}: {e}")
+                continue
+
+        # If we get here, the tool wasn't found or all calls failed
+        if last_error:
+            raise MCPToolError(
+                f"Tool '{tool_name}' failed on all clients. "
+                f"Last error: {last_error}"
+            ) from last_error
+        else:
+            raise MCPToolError(f"Tool '{tool_name}' not found in any client")
+
+    def call_tool_sync(self, tool_name: str, tool_args: Dict[str, Any]) -> Any:
+        r"""Synchronously call a tool."""
+        return run_async(self.call_tool)(tool_name, tool_args)
+
+    def list_available_tools(self) -> Dict[str, List[str]]:
+        r"""List all available tools organized by client.
 
         Returns:
-            str: A string containing the descriptions of the tools
-                in the toolkit.
+            Dict[str, List[str]]: Dictionary mapping client indices to tool
+                names.
         """
-        return "\n".join(server.get_text_tools() for server in self.servers)
+        available_tools = {}
+        for i, client in enumerate(self.clients):
+            try:
+                tools = client.get_tools()
+                tool_names = [tool.func.__name__ for tool in tools]
+                available_tools[f"client_{i+1}"] = tool_names
+            except Exception as e:
+                logger.error(f"Failed to list tools from client {i+1}: {e}")
+                available_tools[f"client_{i+1}"] = []
+
+        return available_tools