camel-ai 0.2.61__py3-none-any.whl → 0.2.62__py3-none-any.whl

camel/toolkits/mcp_toolkit.py

@@ -11,868 +11,604 @@
 # 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
+
 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
-
-if TYPE_CHECKING:
-    from mcp import ClientSession, ListToolsResult, Tool
-
+from contextlib import AsyncExitStack
+from typing import Any, Dict, List, Optional
 
 from camel.logger import get_logger
 from camel.toolkits import BaseToolkit, FunctionTool
 from camel.utils.commons import run_async
+from camel.utils.mcp_client import MCPClient, create_mcp_client
 
 logger = get_logger(__name__)
 
 
-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:
+class MCPConnectionError(Exception):
+    r"""Raised when MCP connection fails."""
+
+    pass
 
-    1. stdio mode: Connects via standard input/output streams for local
-       command-line interactions.
 
-    2. SSE mode (HTTP Server-Sent Events): Connects via HTTP for persistent,
-       event-based interactions.
+class MCPToolError(Exception):
+    r"""Raised when MCP tool execution fails."""
 
-    3. streamable-http mode: Connects via HTTP for persistent, streamable
-        interactions.
+    pass
+
+
+class MCPToolkit(BaseToolkit):
+    r"""MCPToolkit provides a unified interface for managing multiple
+    MCP server connections and their tools.
+
+    This class handles the lifecycle of multiple MCP server connections and
+    offers a centralized configuration mechanism for both local and remote
+    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 MCPClient(command_or_url="...") as client:
-               # Client is connected here
-               result = await client.some_tool()
-           # Client 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
-           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()
-           ```
+
+           .. 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
-           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()
-           ```
 
-    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.
+           .. 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:
+        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. 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`)
-        mode (Optional[str]): Connection mode. Can be "sse" for Server-Sent
-            Events, "streamable-http" for streaming HTTP,
-            or None for stdio mode.
+        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:
+        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.
+
+        Example configuration:
+
+        .. code-block:: json
+
+            {
+              "mcpServers": {
+                "filesystem": {
+                  "command": "npx",
+                  "args": ["-y", "@modelcontextprotocol/server-filesystem",
+                           "/path"]
+                },
+                "protected-server": {
+                  "url": "https://example.com/mcp",
+                  "timeout": 30,
+                  "headers": {
+                    "Authorization": "Bearer YOUR_TOKEN",
+                    "X-API-Key": "YOUR_API_KEY"
+                  }
+                }
+              }
+            }
+
+    Attributes:
+        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,
-        command_or_url: str,
-        args: Optional[List[str]] = None,
-        env: Optional[Dict[str, str]] = None,
+        clients: Optional[List[MCPClient]] = None,
+        config_path: Optional[str] = None,
+        config_dict: Optional[Dict[str, Any]] = None,
         timeout: Optional[float] = None,
-        headers: Optional[Dict[str, str]] = None,
-        mode: Optional[str] = None,
-        strict: Optional[bool] = False,
     ):
-        from mcp import Tool
-
+        # Call parent constructor first
         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.mode = mode
+        # Validate input parameters
+        sources_provided = sum(
+            1 for src in [clients, config_path, config_dict] if src is not None
+        )
+        if sources_provided == 0:
+            error_msg = (
+                "At least one of clients, config_path, or "
+                "config_dict must be provided"
+            )
+            raise ValueError(error_msg)
 
-        self._mcp_tools: List[Tool] = []
-        self._session: Optional['ClientSession'] = None
-        self._exit_stack = AsyncExitStack()
+        self.clients: List[MCPClient] = clients or []
         self._is_connected = False
+        self._exit_stack: Optional[AsyncExitStack] = None
 
-    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
-        from mcp.client.streamable_http import streamablehttp_client
+        # Load clients from config sources
+        if config_path:
+            self.clients.extend(self._load_clients_from_config(config_path))
 
-        if self._is_connected:
-            logger.warning("Server is already connected")
-            return self
+        if config_dict:
+            self.clients.extend(self._load_clients_from_dict(config_dict))
 
-        try:
-            if urlparse(self.command_or_url).scheme in ("http", "https"):
-                if self.mode == "sse" or self.mode is None:
-                    (
-                        read_stream,
-                        write_stream,
-                    ) = await self._exit_stack.enter_async_context(
-                        sse_client(
-                            self.command_or_url,
-                            headers=self.headers,
-                            timeout=self.timeout,
-                        )
-                    )
-                elif self.mode == "streamable-http":
-                    try:
-                        (
-                            read_stream,
-                            write_stream,
-                            _,
-                        ) = await self._exit_stack.enter_async_context(
-                            streamablehttp_client(
-                                self.command_or_url,
-                                headers=self.headers,
-                                timeout=timedelta(seconds=self.timeout),
-                            )
-                        )
-                    except Exception as e:
-                        # Handle anyio task group errors
-                        logger.error(f"Streamable HTTP client error: {e}")
-                else:
-                    raise ValueError(
-                        f"Invalid mode '{self.mode}' for HTTP URL"
-                    )
-            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)
-                )
+        if not self.clients:
+            raise ValueError("No valid MCP clients could be created")
 
-            self._session = await self._exit_stack.enter_async_context(
-                ClientSession(
-                    read_stream,
-                    write_stream,
-                    timedelta(seconds=self.timeout) if self.timeout else None,
-                )
-            )
-            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 connect(self) -> "MCPToolkit":
+        r"""Connect to all MCP servers using AsyncExitStack.
 
-    def connect_sync(self):
-        r"""Synchronously connect to the MCP server."""
-        return run_async(self.connect)()
+        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.
 
-    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
+        Returns:
+            MCPToolkit: Returns :obj:`self` for method chaining, allowing for
+                fluent interface usage.
 
-        try:
-            await self._exit_stack.aclose()
-        except Exception as e:
-            logger.warning(f"{e}")
-        finally:
-            self._exit_stack = AsyncExitStack()
-            self._session = None
+        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.
 
-    def disconnect_sync(self):
-        r"""Synchronously disconnect from the MCP server."""
-        return run_async(self.disconnect)()
+        Warning:
+            If any client fails to connect, all previously established
+            connections will be automatically cleaned up before raising
+            the exception.
 
-    @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`.
+        Example:
+            .. code-block:: python
 
-        Yields:
-            MCPClient: Instance with active connection ready for tool
-                interaction.
+                toolkit = MCPToolkit(config_dict=config)
+                try:
+                    await toolkit.connect()
+                    # Use the toolkit
+                    tools = toolkit.get_tools()
+                finally:
+                    await toolkit.disconnect()
         """
-        try:
-            await self.connect()
-            yield self
-        finally:
-            try:
-                await self.disconnect()
-            except Exception as e:
-                logger.warning(f"Error: {e}")
-
-    def connection_sync(self):
-        r"""Synchronously connect to the MCP server."""
-        return run_async(self.connection)()
+        if self._is_connected:
+            logger.warning("MCPToolkit is already connected")
+            return self
 
-    async def list_mcp_tools(self) -> Union[str, "ListToolsResult"]:
-        r"""Retrieves the list of available tools from the connected MCP
-        server.
+        self._exit_stack = AsyncExitStack()
 
-        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 list_mcp_tools_sync(self) -> Union[str, "ListToolsResult"]:
-        r"""Synchronously list the available tools from the connected MCP
-        server."""
-        return run_async(self.list_mcp_tools)()
-
-    def generate_function_from_mcp_tool(self, mcp_tool: "Tool") -> Callable:
-        r"""Dynamically generates a Python callable function corresponding to
-        a given MCP tool.
+            # 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 handle cleanup of already connected
+                    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
 
-        Args:
-            mcp_tool (Tool): The MCP tool definition received from the MCP
-                server.
+            self._is_connected = True
+            msg = f"Successfully connected to {len(self.clients)} MCP servers"
+            logger.info(msg)
+            return self
 
-        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,
-        }
-        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
-
-            missing_params: Set[str] = set(required_params) - set(
-                kwargs.keys()
-            )
-            if missing_params:
-                logger.warning(
-                    f"Missing required parameters: {missing_params}"
-                )
-                return "Missing required parameters."
+        except Exception:
+            self._is_connected = False
+            if self._exit_stack:
+                await self._exit_stack.aclose()
+                self._exit_stack = None
+            raise
 
-            if not self._session:
-                logger.error(
-                    "MCP Client is not connected. Call `connection()` first."
-                )
-                raise RuntimeError(
-                    "MCP Client is not connected. Call `connection()` first."
-                )
+    async def disconnect(self):
+        r"""Disconnect from all MCP servers."""
+        if not self._is_connected:
+            return
 
+        if self._exit_stack:
             try:
-                result: CallToolResult = await self._session.call_tool(
-                    func_name, kwargs
-                )
+                await self._exit_stack.aclose()
             except Exception as e:
-                logger.error(f"Failed to call MCP tool '{func_name}': {e!s}")
-                raise e
+                logger.warning(f"Error during disconnect: {e}")
+            finally:
+                self._exit_stack = None
 
-            if not result.content or len(result.content) == 0:
-                return "No data available for this request."
-
-            # 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}"
-                )
-                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],
-                )
-                for param in func_params
-            ]
-        )
-        dynamic_function.__signature__ = sig  # type: ignore[attr-defined]
-
-        return dynamic_function
-
-    def generate_function_from_mcp_tool_sync(self, mcp_tool: "Tool") -> Any:
-        r"""Synchronously generate a function from an MCP tool."""
-        return run_async(self.generate_function_from_mcp_tool)(mcp_tool)
-
-    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,
-            },
-        }
+        self._is_connected = False
+        logger.debug("Disconnected from all MCP servers")
 
-    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.
+    @property
+    def is_connected(self) -> bool:
+        r"""Check if toolkit is connected.
 
         Returns:
-            List[FunctionTool]: A list of FunctionTool objects
-                representing the functions in the toolkit.
+            bool: True if the toolkit is connected to all MCP servers,
+                False otherwise.
         """
-        return [
-            FunctionTool(
-                self.generate_function_from_mcp_tool(mcp_tool),
-                openai_tool_schema=self._build_tool_schema(mcp_tool),
-            )
-            for mcp_tool in self._mcp_tools
-        ]
+        if not self._is_connected:
+            return False
 
-    def get_text_tools(self) -> str:
-        r"""Returns a string containing the descriptions of the tools
-        in the toolkit.
+        # Check if all clients are connected
+        return all(client.is_connected() for client in self.clients)
 
-        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
-        )
+    def connect_sync(self):
+        r"""Synchronously connect to all MCP servers."""
+        return run_async(self.connect)()
 
-    async def call_tool(
-        self, tool_name: str, tool_args: Dict[str, Any]
-    ) -> Any:
-        r"""Calls the specified tool with the provided arguments.
+    def disconnect_sync(self):
+        r"""Synchronously disconnect from all MCP servers."""
+        return run_async(self.disconnect)()
 
-        Args:
-            tool_name (str): Name of the tool to call.
-            tool_args (Dict[str, Any]): Arguments to pass to the tool
-                (default: :obj:`{}`).
+    async def __aenter__(self) -> "MCPToolkit":
+        r"""Async context manager entry point.
 
-        Returns:
-            Any: The result of the tool call.
+        Usage:
+            async with MCPToolkit(config_dict=config) as toolkit:
+                tools = toolkit.get_tools()
         """
-        if self._session is None:
-            raise RuntimeError("Session is not initialized.")
+        await self.connect()
+        return self
 
-        return await self._session.call_tool(tool_name, tool_args)
+    def __enter__(self) -> "MCPToolkit":
+        r"""Synchronously enter the async context manager."""
+        return run_async(self.__aenter__)()
 
-    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)
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        r"""Async context manager exit point."""
+        await self.disconnect()
+        return None
 
-    @property
-    def session(self) -> Optional["ClientSession"]:
-        return self._session
+    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)
 
     @classmethod
     async def create(
         cls,
-        command_or_url: str,
-        args: Optional[List[str]] = None,
-        env: Optional[Dict[str, str]] = None,
+        clients: Optional[List[MCPClient]] = None,
+        config_path: Optional[str] = None,
+        config_dict: Optional[Dict[str, Any]] = None,
         timeout: Optional[float] = None,
-        headers: Optional[Dict[str, str]] = None,
-        mode: Optional[str] = None,
-    ) -> "MCPClient":
-        r"""Factory method that creates and connects to the MCP server.
+    ) -> "MCPToolkit":
+        r"""Factory method that creates and connects to all MCP servers.
 
-        This async factory method ensures the connection to the MCP server is
-        established before the client object is fully constructed.
+        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.
 
         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`)
-            mode (Optional[str]): Connection mode. Can be "sse" for
-                Server-Sent Events, "streamable-http" for
-                streaming HTTP, or None for stdio mode.
-                (default: :obj:`None`)
+            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:
-            MCPClient: A fully initialized and connected MCPClient instance.
+            MCPToolkit: A fully initialized and connected :obj:`MCPToolkit`
+                instance with all servers ready for use.
 
         Raises:
-            RuntimeError: If connection to the MCP server fails.
+            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()
         """
-        client = cls(
-            command_or_url=command_or_url,
-            args=args,
-            env=env,
+        toolkit = cls(
+            clients=clients,
+            config_path=config_path,
+            config_dict=config_dict,
             timeout=timeout,
-            headers=headers,
-            mode=mode,
         )
         try:
-            await client.connect()
-            return client
+            await toolkit.connect()
+            return toolkit
         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
+            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(
-        self,
-        command_or_url: str,
-        args: Optional[List[str]] = None,
-        env: Optional[Dict[str, str]] = None,
+        cls,
+        clients: Optional[List[MCPClient]] = None,
+        config_path: Optional[str] = None,
+        config_dict: Optional[Dict[str, Any]] = None,
         timeout: Optional[float] = None,
-        headers: Optional[Dict[str, str]] = None,
-        mode: Optional[str] = None,
-    ) -> "MCPClient":
-        r"""Synchronously create and connect to the MCP server."""
-        return run_async(self.create)(
-            command_or_url, args, env, timeout, headers, mode
+    ) -> "MCPToolkit":
+        r"""Synchronously create and connect to all MCP servers."""
+        return run_async(cls.create)(
+            clients, config_path, config_dict, timeout
         )
 
-    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 _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}'")
 
-        Returns:
-            MCPClient: Self with active connection.
-        """
-        await self.connect()
-        return self
-
-    def __enter__(self) -> "MCPClient":
-        r"""Synchronously enter the async context manager."""
-        return run_async(self.__aenter__)()
-
-    async def __aexit__(self) -> None:
-        r"""Async context manager exit point. Automatically disconnects from
-        the MCP server when exiting an async with statement.
-
-        Returns:
-            None
-        """
-        await self.disconnect()
-
-    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
-        r"""Synchronously exit the async context manager.
-
-        Args:
-            exc_type (Optional[Type[Exception]]): The type of exception that
-                occurred during the execution of the with statement.
-            exc_val (Optional[Exception]): The exception that occurred during
-                the execution of the with statement.
-            exc_tb (Optional[TracebackType]): The traceback of the exception
-                that occurred during the execution of the with statement.
-
-        Returns:
-            None
-        """
-        return run_async(self.__aexit__)()
-
-
-class MCPToolkit(BaseToolkit):
-    r"""MCPToolkit provides a unified interface for managing multiple
-    MCP server connections and their tools.
-
-    This class handles the lifecycle of multiple MCP server connections and
-    offers a centralized configuration mechanism for both local and remote
-    MCP services.
-
-    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
-           ```
-
-        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()
-           ```
-
-        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()
-           ```
-
-    Args:
-        servers (Optional[List[MCPClient]]): List of 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.
-            (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.
-
-        For web servers in the config, you can specify authorization
-        headers using the "headers" field to connect to protected MCP server
-        endpoints.
-
-        Example configuration:
-
-        .. code-block:: json
-
-            {
-              "mcpServers": {
-                "protected-server": {
-                  "url": "https://example.com/mcp",
-                  "timeout": 30,
-                  "headers": {
-                    "Authorization": "Bearer YOUR_TOKEN",
-                    "X-API-Key": "YOUR_API_KEY"
-                  }
-                }
-              }
-            }
-
-    Attributes:
-        servers (List[MCPClient]): List of MCPClient instances being managed.
-    """
+        try:
+            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:
+            error_msg = f"Error reading config file '{config_path}': {e}"
+            raise IOError(error_msg) from e
 
-    def __init__(
-        self,
-        servers: Optional[List[MCPClient]] = None,
-        config_path: Optional[str] = None,
-        config_dict: Optional[Dict[str, Any]] = None,
-        strict: Optional[bool] = False,
-    ):
-        super().__init__()
+        return self._load_clients_from_dict(data)
 
-        sources_provided = sum(
-            1 for src in [servers, 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."
-            )
+    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")
 
-        self.servers: List[MCPClient] = servers or []
+        mcp_servers = config.get("mcpServers", {})
+        if not isinstance(mcp_servers, dict):
+            raise ValueError("'mcpServers' must be a dictionary")
 
-        if config_path:
-            self.servers.extend(
-                self._load_servers_from_config(config_path, strict)
-            )
+        clients = []
 
-        if config_dict:
-            self.servers.extend(self._load_servers_from_dict(config_dict))
+        for name, cfg in mcp_servers.items():
+            try:
+                if "timeout" not in cfg and self.timeout is not None:
+                    cfg["timeout"] = self.timeout
 
-        self._connected = False
+                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
 
-    def _load_servers_from_config(
-        self, config_path: str, strict: Optional[bool] = False
-    ) -> List[MCPClient]:
-        r"""Loads MCP server configurations from a JSON file.
+        return clients
 
-        Args:
-            config_path (str): Path to the JSON configuration file.
-            strict (bool): Whether to enforce strict mode for the
-                function call. (default: :obj:`False`)
+    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)
 
-        Returns:
-            List[MCPClient]: List of configured MCPClient instances.
-        """
         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
+            # 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
 
-        return self._load_servers_from_dict(config=data, strict=strict)
+            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 _load_servers_from_dict(
-        self, config: Dict[str, Any], strict: Optional[bool] = False
-    ) -> List[MCPClient]:
-        r"""Loads MCP server configurations from a dictionary.
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Aggregates all tools from the managed MCP client instances.
 
-        Args:
-            config (Dict[str, Any]): Dictionary containing server
-                configurations.
-            strict (bool): Whether to enforce strict mode for the
-                function call. (default: :obj:`False`)
+        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.
 
         Returns:
-            List[MCPClient]: List of configured MCPClient instances.
+            List[FunctionTool]: Combined list of all available function tools
+                from all connected MCP servers. 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__}")
         """
-        all_servers = []
-
-        mcp_servers = config.get("mcpServers", {})
-        if not isinstance(mcp_servers, dict):
-            logger.warning("'mcpServers' is not a dictionary, skipping...")
-            mcp_servers = {}
-
-        for name, cfg in mcp_servers.items():
-            if not isinstance(cfg, dict):
-                logger.warning(
-                    f"Configuration for server '{name}' must be a dictionary"
-                )
-                continue
+        if not self.is_connected:
+            logger.warning(
+                "MCPToolkit is not connected. "
+                "Tools may not be available until connected."
+            )
 
-            if "command" not in cfg and "url" not in cfg:
-                logger.warning(
-                    f"Missing required 'command' or 'url' field for server "
-                    f"'{name}'"
+        all_tools = []
+        for i, client in enumerate(self.clients):
+            try:
+                client_tools = client.get_tools()
+                all_tools.extend(client_tools)
+                logger.debug(
+                    f"Client {i+1} contributed {len(client_tools)} tools"
                 )
-                continue
-
-            # 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,
-                mode=cfg.get("mode", None),
-                strict=strict,
-            )
-            all_servers.append(server)
+            except Exception as e:
+                logger.error(f"Failed to get tools from client {i+1}: {e}")
 
-        return all_servers
+        logger.info(f"Total tools available: {len(all_tools)}")
+        return all_tools
 
-    async def connect(self):
-        r"""Explicitly connect to all MCP servers.
+    def get_text_tools(self) -> str:
+        r"""Returns a string containing the descriptions of the tools.
 
         Returns:
-            MCPToolkit: The connected toolkit instance
+            str: A string containing the descriptions of all tools.
         """
-        if self._connected:
-            logger.warning("MCPToolkit is already connected")
-            return self
+        if not self.is_connected:
+            logger.warning(
+                "MCPToolkit is not connected. "
+                "Tool descriptions may not be available until connected."
+            )
 
-        try:
-            # Sequentially connect to each server
-            for server in self.servers:
-                await server.connect()
-            self._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 one or more MCP servers: {e}")
-            raise e
+        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}"
+                )
 
-    def connect_sync(self):
-        r"""Synchronously connect to all MCP servers."""
-        return run_async(self.connect)()
+        return "\n\n".join(tool_descriptions)
 
-    async def disconnect(self):
-        r"""Explicitly disconnect from all MCP servers."""
-        if not self._connected:
-            return
+    async def call_tool(
+        self, tool_name: str, tool_args: Dict[str, Any]
+    ) -> Any:
+        r"""Call a tool by name across all managed clients.
 
-        for server in self.servers:
-            await server.disconnect()
-        self._connected = False
+        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.
 
-    def disconnect_sync(self):
-        r"""Synchronously disconnect from all MCP servers."""
-        return run_async(self.disconnect)()
+        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.
 
-    @asynccontextmanager
-    async def connection(self) -> AsyncGenerator["MCPToolkit", None]:
-        r"""Async context manager that simultaneously establishes connections
-        to all managed MCP server instances.
+        Returns:
+            Any: The result of the tool call. The type and structure depend
+                on the specific tool being called.
 
-        Yields:
-            MCPToolkit: Self with all servers connected.
+        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}")
         """
-        try:
-            await self.connect()
-            yield self
-        finally:
-            await self.disconnect()
+        if not self.is_connected:
+            raise MCPConnectionError(
+                "MCPToolkit is not connected. Call connect() first."
+            )
 
-    def connection_sync(self):
-        r"""Synchronously connect to all MCP servers."""
-        return run_async(self.connection)()
+        # 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
 
-    def is_connected(self) -> bool:
-        r"""Checks if all the managed servers are connected.
+        # 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")
 
-        Returns:
-            bool: True if connected, False otherwise.
-        """
-        return self._connected
+    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 get_tools(self) -> List[FunctionTool]:
-        r"""Aggregates all tools from the managed MCP server instances.
+    def list_available_tools(self) -> Dict[str, List[str]]:
+        r"""List all available tools organized by client.
 
         Returns:
-            List[FunctionTool]: Combined list of all available function tools.
+            Dict[str, List[str]]: Dictionary mapping client indices to tool
+                names.
         """
-        all_tools = []
-        for server in self.servers:
-            all_tools.extend(server.get_tools())
-        return all_tools
-
-    def get_text_tools(self) -> str:
-        r"""Returns a string containing the descriptions of the tools
-        in the toolkit.
+        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}"] = []
 
-        Returns:
-            str: A string containing the descriptions of the tools
-                in the toolkit.
-        """
-        return "\n".join(server.get_text_tools() for server in self.servers)
+        return available_tools