mcp-use 1.3.9__py3-none-any.whl → 1.3.11__py3-none-any.whl

mcp_use/connectors/http.py

@@ -5,10 +5,17 @@ This module provides a connector for communicating with MCP implementations
 through HTTP APIs with SSE or Streamable HTTP for transport.
 """
 
+from typing import Any
+
 import httpx
 from mcp import ClientSession
 from mcp.client.session import ElicitationFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
+from mcp.shared.exceptions import McpError
+
+from mcp_use.auth.oauth import OAuthClientProvider
 
+from ..auth import BearerAuth, OAuth
+from ..exceptions import OAuthAuthenticationError, OAuthDiscoveryError
 from ..logging import logger
 from ..task_managers import SseConnectionManager, StreamableHttpConnectionManager
 from .base import BaseConnector
@@ -24,10 +31,10 @@ class HttpConnector(BaseConnector):
     def __init__(
         self,
         base_url: str,
-        auth_token: str | None = None,
         headers: dict[str, str] | None = None,
         timeout: float = 5,
         sse_read_timeout: float = 60 * 5,
+        auth: str | dict[str, Any] | httpx.Auth | None = None,
         sampling_callback: SamplingFnT | None = None,
         elicitation_callback: ElicitationFnT | None = None,
         message_handler: MessageHandlerFnT | None = None,
@@ -37,10 +44,13 @@ class HttpConnector(BaseConnector):
 
         Args:
             base_url: The base URL of the MCP HTTP API.
-            auth_token: Optional authentication token.
             headers: Optional additional headers.
             timeout: Timeout for HTTP operations in seconds.
             sse_read_timeout: Timeout for SSE read operations in seconds.
+            auth: Authentication method - can be:
+                - A string token: Use Bearer token authentication
+                - A dict with OAuth config: {"client_id": "...", "client_secret": "...", "scope": "..."}
+                - An httpx.Auth object: Use custom authentication
             sampling_callback: Optional sampling callback.
             elicitation_callback: Optional elicitation callback.
         """
@@ -51,12 +61,57 @@ class HttpConnector(BaseConnector):
             logging_callback=logging_callback,
         )
         self.base_url = base_url.rstrip("/")
-        self.auth_token = auth_token
         self.headers = headers or {}
-        if auth_token:
-            self.headers["Authorization"] = f"Bearer {auth_token}"
         self.timeout = timeout
         self.sse_read_timeout = sse_read_timeout
+        self._auth: httpx.Auth | None = None
+        self._oauth: OAuth | None = None
+
+        # Handle authentication
+        if auth is not None:
+            self._set_auth(auth)
+
+    def _set_auth(self, auth: str | dict[str, Any] | httpx.Auth) -> None:
+        """Set authentication method.
+
+        Args:
+            auth: Authentication method - can be:
+                - A string token: Use Bearer token authentication
+                - A dict with OAuth config: {"client_id": "...", "client_secret": "...", "scope": "..."}
+                - An httpx.Auth object: Use custom authentication
+        """
+        if isinstance(auth, str):
+            # Treat as bearer token
+            self._auth = BearerAuth(token=auth)
+            self.headers["Authorization"] = f"Bearer {auth}"
+        elif isinstance(auth, dict):
+            # Check if this is an OAuth provider configuration
+            if "oauth_provider" in auth:
+                oauth_provider = auth["oauth_provider"]
+                if isinstance(oauth_provider, dict):
+                    oauth_provider = OAuthClientProvider(**oauth_provider)
+                self._oauth = OAuth(
+                    self.base_url,
+                    scope=auth.get("scope"),
+                    client_id=auth.get("client_id"),
+                    client_secret=auth.get("client_secret"),
+                    callback_port=auth.get("callback_port"),
+                    oauth_provider=oauth_provider,
+                )
+                self._oauth_config = auth
+            else:
+                self._oauth = OAuth(
+                    self.base_url,
+                    scope=auth.get("scope"),
+                    client_id=auth.get("client_id"),
+                    client_secret=auth.get("client_secret"),
+                    callback_port=auth.get("callback_port"),
+                )
+                self._oauth_config = auth
+        elif isinstance(auth, httpx.Auth):
+            self._auth = auth
+        else:
+            raise ValueError(f"Invalid auth type: {type(auth)}")
 
     async def connect(self) -> None:
         """Establish a connection to the MCP implementation."""
@@ -64,6 +119,29 @@ class HttpConnector(BaseConnector):
             logger.debug("Already connected to MCP implementation")
             return
 
+        # Handle OAuth if needed
+        if self._oauth:
+            try:
+                # Create a temporary client for OAuth metadata discovery
+                async with httpx.AsyncClient() as client:
+                    bearer_auth = await self._oauth.initialize(client)
+                    if not bearer_auth:
+                        # Need to perform OAuth flow
+                        logger.info("OAuth authentication required")
+                        bearer_auth = await self._oauth.authenticate()
+
+                    # Update auth and headers
+                    self._auth = bearer_auth
+                    self.headers["Authorization"] = f"Bearer {bearer_auth.token.get_secret_value()}"
+            except OAuthDiscoveryError:
+                # OAuth discovery failed - it means server doesn't support OAuth default urls
+                logger.debug("OAuth discovery failed, continuing without initialization.")
+                self._oauth = None
+                self._auth = None
+            except OAuthAuthenticationError as e:
+                logger.error(f"OAuth initialization failed: {e}")
+                raise
+
         # Try streamable HTTP first (new transport), fall back to SSE (old transport)
         # This implements backwards compatibility per MCP specification
         self.transport_type = None
@@ -73,7 +151,7 @@ class HttpConnector(BaseConnector):
             # First, try the new streamable HTTP transport
             logger.debug(f"Attempting streamable HTTP connection to: {self.base_url}")
             connection_manager = StreamableHttpConnectionManager(
-                self.base_url, self.headers, self.timeout, self.sse_read_timeout
+                self.base_url, self.headers, self.timeout, self.sse_read_timeout, auth=self._auth
             )
 
             # Test if this is a streamable HTTP server by attempting initialization
@@ -94,9 +172,9 @@ class HttpConnector(BaseConnector):
             try:
                 # Try to initialize - this is where streamable HTTP vs SSE difference should show up
                 result = await test_client.initialize()
+                logger.debug(f"Streamable HTTP initialization result: {result}")
 
                 # If we get here, streamable HTTP works
-
                 self.client_session = test_client
                 self.transport_type = "streamable HTTP"
                 self._initialized = True  # Mark as initialized since we just called initialize()
@@ -125,14 +203,28 @@ class HttpConnector(BaseConnector):
                 else:
                     self._prompts = []
 
-            except Exception as init_error:
+            # Only McpError is raised from client's initialization because
+            # exceptions are handled internally.
+            except McpError as mcp_error:
+                logger.error("MCP protocol error during initialization: %s", mcp_error.error)
                 # Clean up the test client
+                try:
+                    await test_client.__aexit__(None, None, None)
+                except Exception:
+                    pass
+                raise mcp_error
+
+            except Exception as init_error:
+                # This catches non-McpError exceptions, like a direct httpx timeout
+                # but in the most cases this won't happen. It's for safety.
                 try:
                     await test_client.__aexit__(None, None, None)
                 except Exception:
                     pass
                 raise init_error
 
+        # Exception from the inner try is propagated here and in
+        # the most cases is an McpError, so checking instances is useless
         except Exception as streamable_error:
             logger.debug(f"Streamable HTTP failed: {streamable_error}")
 
@@ -143,24 +235,17 @@ class HttpConnector(BaseConnector):
                 except Exception:
                     pass
 
-            # Check if this is a 4xx error that indicates we should try SSE fallback
-            should_fallback = False
-            if isinstance(streamable_error, httpx.HTTPStatusError):
-                if streamable_error.response.status_code in [404, 405]:
-                    should_fallback = True
-            elif "405 Method Not Allowed" in str(streamable_error) or "404 Not Found" in str(streamable_error):
-                should_fallback = True
-            else:
-                # For other errors, still try fallback but they might indicate
-                # real connectivity issues
-                should_fallback = True
+            # It doesn't make sense to check error types. Because client
+            # always return a McpError, if he can't reach the server
+            # because it's offline, or if it has an auth problem.
+            should_fallback = True
 
             if should_fallback:
                 try:
                     # Fall back to the old SSE transport
                     logger.debug(f"Attempting SSE fallback connection to: {self.base_url}")
                     connection_manager = SseConnectionManager(
-                        self.base_url, self.headers, self.timeout, self.sse_read_timeout
+                        self.base_url, self.headers, self.timeout, self.sse_read_timeout, auth=self._auth
                     )
 
                     read_stream, write_stream = await connection_manager.start()
@@ -178,7 +263,18 @@ class HttpConnector(BaseConnector):
                     await self.client_session.__aenter__()
                     self.transport_type = "SSE"
 
-                except Exception as sse_error:
+                except* Exception as sse_error:
+                    # Get the exception from the ExceptionGroup, and here we will get the correct type.
+                    sse_error = sse_error.exceptions[0]
+                    if isinstance(sse_error, httpx.HTTPStatusError) and sse_error.response.status_code in [
+                        401,
+                        403,
+                        407,
+                    ]:
+                        raise OAuthAuthenticationError(
+                            f"Server requires authentication (HTTP {sse_error.response.status_code}) "
+                            "but auth failed. Please provide auth configuration manually."
+                        ) from sse_error
                     logger.error(
                         f"Both transport methods failed. Streamable HTTP: {streamable_error}, SSE: {sse_error}"
                     )

mcp_use/connectors/websocket.py

@@ -10,6 +10,7 @@ import json
 import uuid
 from typing import Any
 
+import httpx
 from mcp.types import Tool
 from websockets import ClientConnection
 
@@ -28,21 +29,29 @@ class WebSocketConnector(BaseConnector):
     def __init__(
         self,
         url: str,
-        auth_token: str | None = None,
         headers: dict[str, str] | None = None,
+        auth: str | dict[str, Any] | httpx.Auth | None = None,
     ):
         """Initialize a new WebSocket connector.
 
         Args:
             url: The WebSocket URL to connect to.
-            auth_token: Optional authentication token.
             headers: Optional additional headers.
+            auth: Authentication method - can be:
+                - A string token: Use Bearer token authentication
+                - A dict: Not supported for WebSocket (will log warning)
+                - An httpx.Auth object: Not supported for WebSocket (will log warning)
         """
         self.url = url
-        self.auth_token = auth_token
         self.headers = headers or {}
-        if auth_token:
-            self.headers["Authorization"] = f"Bearer {auth_token}"
+
+        # Handle authentication - WebSocket only supports bearer tokens
+        # An auth field it's not needed
+        if auth is not None:
+            if isinstance(auth, str):
+                self.headers["Authorization"] = f"Bearer {auth}"
+            else:
+                logger.warning("WebSocket connector only supports bearer token authentication")
 
         self.ws: ClientConnection | None = None
         self._connection_manager: ConnectionManager | None = None

mcp_use/exceptions.py

@@ -0,0 +1,31 @@
+"""MCP-use exceptions."""
+
+
+class MCPError(Exception):
+    """Base exception for MCP-use."""
+
+    pass
+
+
+class OAuthDiscoveryError(MCPError):
+    """OAuth discovery auth metadata error"""
+
+    pass
+
+
+class OAuthAuthenticationError(MCPError):
+    """OAuth authentication-related errors"""
+
+    pass
+
+
+class ConnectionError(MCPError):
+    """Connection-related errors."""
+
+    pass
+
+
+class ConfigurationError(MCPError):
+    """Configuration-related errors."""
+
+    pass

mcp_use/logging.py

@@ -80,6 +80,9 @@ class Logger:
 
         root_logger.setLevel(level)
 
+        # Set propagate to True to ensure child loggers inherit settings
+        root_logger.propagate = True
+
         # Clear existing handlers
         for handler in root_logger.handlers[:]:
             root_logger.removeHandler(handler)
@@ -91,6 +94,7 @@ class Logger:
         if log_to_console:
             console_handler = logging.StreamHandler(sys.stdout)
             console_handler.setFormatter(formatter)
+            console_handler.setLevel(level)  # Ensure handler respects the level
             root_logger.addHandler(console_handler)
 
         # Add file handler if requested
@@ -102,6 +106,7 @@ class Logger:
 
             file_handler = logging.FileHandler(log_to_file)
             file_handler.setFormatter(formatter)
+            file_handler.setLevel(level)  # Ensure handler respects the level
             root_logger.addHandler(file_handler)
 
     @classmethod
@@ -114,24 +119,34 @@ class Logger:
         global MCP_USE_DEBUG
         MCP_USE_DEBUG = debug_level
 
-        # Update log level for existing loggers
+        # Determine the target level
         if debug_level == 2:
-            for logger in cls._loggers.values():
-                logger.setLevel(logging.DEBUG)
-                langchain_set_debug(True)
+            target_level = logging.DEBUG
+            langchain_set_debug(True)
         elif debug_level == 1:
-            for logger in cls._loggers.values():
-                logger.setLevel(logging.INFO)
-                langchain_set_debug(False)
+            target_level = logging.INFO
+            langchain_set_debug(False)
         else:
-            # Reset to default (WARNING)
-            for logger in cls._loggers.values():
-                logger.setLevel(logging.WARNING)
-                langchain_set_debug(False)
+            target_level = logging.WARNING
+            langchain_set_debug(False)
+
+        # Update log level for existing loggers in our registry
+        for logger in cls._loggers.values():
+            logger.setLevel(target_level)
+            # Also update handler levels
+            for handler in logger.handlers:
+                handler.setLevel(target_level)
+
+        # Also update all mcp_use child loggers that might exist
+        # This ensures loggers created with logging.getLogger() are also updated
+        base_logger = logging.getLogger("mcp_use")
+        base_logger.setLevel(target_level)
+        for handler in base_logger.handlers:
+            handler.setLevel(target_level)
 
 
 # Check environment variable for debug flag
-debug_env = os.environ.get("DEBUG", "").lower()
+debug_env = os.environ.get("MCP_USE_DEBUG", "").lower() or os.environ.get("DEBUG", "").lower()
 if debug_env == "2":
     MCP_USE_DEBUG = 2
 elif debug_env == "1":

mcp_use/managers/base.py

@@ -0,0 +1,36 @@
+from abc import ABC, abstractmethod
+
+from langchain_core.tools import BaseTool
+
+
+class BaseServerManager(ABC):
+    """Abstract base class for server managers.
+
+    This class defines the interface for server managers that can be used with MCPAgent.
+    Custom server managers should inherit from this class and implement the required methods.
+    """
+
+    @abstractmethod
+    async def initialize(self) -> None:
+        """Initialize the server manager."""
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def tools(self) -> list[BaseTool]:
+        """Get all server management tools and tools from the active server.
+
+        Returns:
+            list of LangChain tools for server management plus tools from active server
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def has_tool_changes(self, current_tool_names: set[str]) -> bool:
+        """Check if the available tools have changed.
+        Args:
+            current_tool_names: Set of currently known tool names
+        Returns:
+            True if tools have changed, False otherwise
+        """
+        raise NotImplementedError

mcp_use/managers/server_manager.py

@@ -4,10 +4,11 @@ from mcp_use.client import MCPClient
 from mcp_use.logging import logger
 
 from ..adapters.base import BaseAdapter
+from .base import BaseServerManager
 from .tools import ConnectServerTool, DisconnectServerTool, GetActiveServerTool, ListServersTool, SearchToolsTool
 
 
-class ServerManager:
+class ServerManager(BaseServerManager):
     """Manages MCP servers and provides tools for server selection and management.
 
     This class allows an agent to discover and select which MCP server to use,

mcp_use/observability/__init__.py

@@ -4,5 +4,6 @@ from dotenv import load_dotenv
 load_dotenv()
 
 from . import laminar, langfuse  # noqa
+from .callbacks_manager import ObservabilityManager, get_default_manager, create_manager  # noqa
 
-__all__ = ["laminar", "langfuse"]
+__all__ = ["laminar", "langfuse", "ObservabilityManager", "get_default_manager", "create_manager"]

mcp_use/observability/callbacks_manager.py

@@ -0,0 +1,162 @@
+"""
+Observability callbacks manager for MCP-use.
+
+This module provides a centralized manager for handling observability callbacks
+from various platforms (Langfuse, Laminar, etc.) in a clean and extensible way.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class ObservabilityManager:
+    """
+    Manages observability callbacks for MCP agents.
+
+    This class provides a centralized way to collect and manage callbacks
+    from various observability platforms (Langfuse, Laminar, etc.).
+    """
+
+    def __init__(self, custom_callbacks: list | None = None):
+        """
+        Initialize the ObservabilityManager.
+
+        Args:
+            custom_callbacks: Optional list of custom callbacks to use instead of defaults.
+        """
+        self.custom_callbacks = custom_callbacks
+        self._available_handlers = []
+        self._handler_names = []
+        self._initialized = False
+
+    def _collect_available_handlers(self) -> None:
+        """Collect all available observability handlers from configured platforms."""
+        if self._initialized:
+            return
+
+        # Import handlers lazily to avoid circular imports
+        try:
+            from .langfuse import langfuse_handler
+
+            if langfuse_handler is not None:
+                self._available_handlers.append(langfuse_handler)
+                self._handler_names.append("Langfuse")
+                logger.debug("ObservabilityManager: Langfuse handler available")
+        except ImportError:
+            logger.debug("ObservabilityManager: Langfuse module not available")
+
+        try:
+            from .laminar import laminar_initialized
+
+            if laminar_initialized:
+                # Laminar is initialized with automatic instrumentation only
+                self._handler_names.append("Laminar (auto-instrumentation)")
+                logger.debug("ObservabilityManager: Laminar auto-instrumentation active")
+        except ImportError:
+            logger.debug("ObservabilityManager: Laminar module not available")
+
+        # Future: Add more platforms here...
+
+        self._initialized = True
+
+    def get_callbacks(self) -> list:
+        """
+        Get the list of callbacks to use.
+
+        Returns:
+            List of callbacks - either custom callbacks if provided,
+            or all available observability handlers.
+        """
+        # If custom callbacks were provided, use those
+        if self.custom_callbacks is not None:
+            logger.debug(f"ObservabilityManager: Using {len(self.custom_callbacks)} custom callbacks")
+            return self.custom_callbacks
+
+        # Otherwise, collect and return all available handlers
+        self._collect_available_handlers()
+
+        if self._available_handlers:
+            logger.debug(f"ObservabilityManager: Using {len(self._available_handlers)} handlers")
+        else:
+            logger.debug("ObservabilityManager: No callbacks configured")
+
+        return self._available_handlers
+
+    def get_handler_names(self) -> list[str]:
+        """
+        Get the names of available handlers.
+
+        Returns:
+            List of handler names (e.g., ["Langfuse", "Laminar"])
+        """
+        if self.custom_callbacks is not None:
+            # For custom callbacks, try to get their class names
+            return [type(cb).__name__ for cb in self.custom_callbacks]
+
+        self._collect_available_handlers()
+        return self._handler_names
+
+    def has_callbacks(self) -> bool:
+        """
+        Check if any callbacks are available.
+
+        Returns:
+            True if callbacks are available, False otherwise.
+        """
+        callbacks = self.get_callbacks()
+        return len(callbacks) > 0
+
+    def add_callback(self, callback) -> None:
+        """
+        Add a callback to the custom callbacks list.
+
+        Args:
+            callback: The callback to add.
+        """
+        if self.custom_callbacks is None:
+            self.custom_callbacks = []
+        self.custom_callbacks.append(callback)
+        logger.debug(f"ObservabilityManager: Added custom callback: {type(callback).__name__}")
+
+    def clear_callbacks(self) -> None:
+        """Clear all custom callbacks."""
+        self.custom_callbacks = []
+        logger.debug("ObservabilityManager: Cleared all custom callbacks")
+
+    def __repr__(self) -> str:
+        """String representation of the ObservabilityManager."""
+        handler_names = self.get_handler_names()
+        if handler_names:
+            return f"ObservabilityManager(handlers={handler_names})"
+        return "ObservabilityManager(no handlers)"
+
+
+# Singleton instance for easy access
+_default_manager = None
+
+
+def get_default_manager() -> ObservabilityManager:
+    """
+    Get the default ObservabilityManager instance.
+
+    Returns:
+        The default ObservabilityManager instance (singleton).
+    """
+    global _default_manager
+    if _default_manager is None:
+        _default_manager = ObservabilityManager()
+    return _default_manager
+
+
+def create_manager(custom_callbacks: list | None = None) -> ObservabilityManager:
+    """
+    Create a new ObservabilityManager instance.
+
+    Args:
+        custom_callbacks: Optional list of custom callbacks.
+
+    Returns:
+        A new ObservabilityManager instance.
+    """
+    return ObservabilityManager(custom_callbacks=custom_callbacks)

mcp_use/observability/laminar.py

@@ -1,3 +1,9 @@
+"""
+Laminar observability integration for MCP-use.
+
+This module provides automatic instrumentation for Laminar AI observability platform.
+"""
+
 import logging
 import os
 
@@ -6,6 +12,9 @@ logger = logging.getLogger(__name__)
 # Check if Laminar is disabled via environment variable
 _laminar_disabled = os.getenv("MCP_USE_LAMINAR", "").lower() == "false"
 
+# Track if Laminar is initialized for other modules to check
+laminar_initialized = False
+
 # Only initialize if not disabled and API key is present
 if _laminar_disabled:
     logger.debug("Laminar tracing disabled via MCP_USE_LAMINAR environment variable")
@@ -13,9 +22,21 @@ elif not os.getenv("LAMINAR_PROJECT_API_KEY"):
     logger.debug("Laminar API key not found - tracing disabled. Set LAMINAR_PROJECT_API_KEY to enable")
 else:
     try:
-        from lmnr import Laminar
+        from lmnr import Instruments, Laminar
+
+        # Initialize Laminar with LangChain instrumentation
+        logger.debug("Laminar: Initializing automatic instrumentation for LangChain")
+
+        # Initialize with specific instruments
+        instruments = {Instruments.LANGCHAIN, Instruments.OPENAI}
+        logger.debug(f"Laminar: Enabling instruments: {[i.name for i in instruments]}")
+
+        Laminar.initialize(project_api_key=os.getenv("LAMINAR_PROJECT_API_KEY"), instruments=instruments)
+
+        laminar_initialized = True
+        logger.debug("Laminar observability initialized successfully with LangChain instrumentation")
 
-        Laminar.initialize(project_api_key=os.getenv("LAMINAR_PROJECT_API_KEY"))
-        logger.debug("Laminar observability initialized successfully")
     except ImportError:
         logger.debug("Laminar package not installed - tracing disabled. Install with: pip install lmnr")
+    except Exception as e:
+        logger.error(f"Failed to initialize Laminar: {e}")