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

mcp_use/__init__.py

@@ -7,12 +7,16 @@ to MCP tools through existing LangChain adapters.
 
 from importlib.metadata import version
 
-from . import observability
+# Import logging FIRST to ensure it's configured before other modules
+# This MUST happen before importing observability to ensure loggers are configured
+from .logging import MCP_USE_DEBUG, Logger, logger  # isort: skip
+
+# Now import other modules - observability must come after logging
+from . import observability  # noqa: E402
 from .agents.mcpagent import MCPAgent
 from .client import MCPClient
 from .config import load_config_file
 from .connectors import BaseConnector, HttpConnector, StdioConnector, WebSocketConnector
-from .logging import MCP_USE_DEBUG, Logger, logger
 from .session import MCPSession
 
 __version__ = version("mcp-use")

mcp_use/adapters/langchain_adapter.py

@@ -39,7 +39,7 @@ class LangChainAdapter(BaseAdapter):
         self._connector_tool_map: dict[BaseConnector, list[BaseTool]] = {}
 
     def fix_schema(self, schema: dict) -> dict:
-        """Convert JSON Schema 'type': ['string', 'null'] to 'anyOf' format.
+        """Convert JSON Schema 'type': ['string', 'null'] to 'anyOf' format and fix enum handling.
 
         Args:
             schema: The JSON schema to fix.
@@ -51,6 +51,11 @@ class LangChainAdapter(BaseAdapter):
             if "type" in schema and isinstance(schema["type"], list):
                 schema["anyOf"] = [{"type": t} for t in schema["type"]]
                 del schema["type"]  # Remove 'type' and standardize to 'anyOf'
+
+            # Fix enum handling - ensure enum fields are properly typed as strings
+            if "enum" in schema and "type" not in schema:
+                schema["type"] = "string"
+
             for key, value in schema.items():
                 schema[key] = self.fix_schema(value)  # Apply recursively
         return schema
@@ -71,11 +76,8 @@ class LangChainAdapter(BaseAdapter):
         if tool_result.isError:
             raise ToolException(f"Tool execution failed: {tool_result.content}")
 
-        if not tool_result.content:
-            raise ToolException("Tool execution returned no content")
-
         decoded_result = ""
-        for item in tool_result.content:
+        for item in tool_result.content or []:
             match item.type:
                 case "text":
                     item: TextContent

mcp_use/agents/mcpagent.py

@@ -30,7 +30,11 @@ from mcp_use.telemetry.utils import extract_model_info
 
 from ..adapters.langchain_adapter import LangChainAdapter
 from ..logging import logger
+from ..managers.base import BaseServerManager
 from ..managers.server_manager import ServerManager
+
+# Import observability manager
+from ..observability import ObservabilityManager
 from .prompts.system_prompt_builder import create_system_message
 from .prompts.templates import DEFAULT_SYSTEM_PROMPT_TEMPLATE, SERVER_MANAGER_SYSTEM_PROMPT_TEMPLATE
 from .remote import RemoteAgent
@@ -62,10 +66,15 @@ class MCPAgent:
         disallowed_tools: list[str] | None = None,
         tools_used_names: list[str] | None = None,
         use_server_manager: bool = False,
+        server_manager: BaseServerManager | None = None,
         verbose: bool = False,
         agent_id: str | None = None,
         api_key: str | None = None,
         base_url: str = "https://cloud.mcp-use.com",
+        callbacks: list | None = None,
+        chat_id: str | None = None,
+        retry_on_error: bool = True,
+        max_retries_per_step: int = 2,
     ):
         """Initialize a new MCPAgent instance.
 
@@ -84,10 +93,13 @@ class MCPAgent:
             agent_id: Remote agent ID for remote execution. If provided, creates a remote agent.
             api_key: API key for remote execution. If None, checks MCP_USE_API_KEY env var.
             base_url: Base URL for remote API calls.
+            callbacks: List of LangChain callbacks to use. If None and Langfuse is configured, uses langfuse_handler.
+            retry_on_error: Whether to retry tool calls that fail due to validation errors.
+            max_retries_per_step: Maximum number of retries for validation errors per step.
         """
         # Handle remote execution
         if agent_id is not None:
-            self._remote_agent = RemoteAgent(agent_id=agent_id, api_key=api_key, base_url=base_url)
+            self._remote_agent = RemoteAgent(agent_id=agent_id, api_key=api_key, base_url=base_url, chat_id=chat_id)
             self._is_remote = True
             return
 
@@ -109,13 +121,20 @@ class MCPAgent:
         self.disallowed_tools = disallowed_tools or []
         self.tools_used_names = tools_used_names or []
         self.use_server_manager = use_server_manager
+        self.server_manager = server_manager
         self.verbose = verbose
+        self.retry_on_error = retry_on_error
+        self.max_retries_per_step = max_retries_per_step
         # System prompt configuration
         self.system_prompt = system_prompt  # User-provided full prompt override
         # User can provide a template override, otherwise use the imported default
         self.system_prompt_template_override = system_prompt_template
         self.additional_instructions = additional_instructions
 
+        # Set up observability callbacks using the ObservabilityManager
+        self.observability_manager = ObservabilityManager(custom_callbacks=callbacks)
+        self.callbacks = self.observability_manager.get_callbacks()
+
         # Either client or connector must be provided
         if not client and len(self.connectors) == 0:
             raise ValueError("Either client or connector must be provided")
@@ -126,9 +145,7 @@ class MCPAgent:
         # Initialize telemetry
         self.telemetry = Telemetry()
 
-        # Initialize server manager if requested
-        self.server_manager = None
-        if self.use_server_manager:
+        if self.use_server_manager and self.server_manager is None:
             if not self.client:
                 raise ValueError("Client must be provided when using server manager")
             self.server_manager = ServerManager(self.client, self.adapter)
@@ -246,9 +263,15 @@ class MCPAgent:
         # Use the standard create_tool_calling_agent
         agent = create_tool_calling_agent(llm=self.llm, tools=self._tools, prompt=prompt)
 
-        # Use the standard AgentExecutor
-        executor = AgentExecutor(agent=agent, tools=self._tools, max_iterations=self.max_steps, verbose=self.verbose)
-        logger.debug(f"Created agent executor with max_iterations={self.max_steps}")
+        # Use the standard AgentExecutor with callbacks
+        executor = AgentExecutor(
+            agent=agent,
+            tools=self._tools,
+            max_iterations=self.max_steps,
+            verbose=self.verbose,
+            callbacks=self.callbacks,
+        )
+        logger.debug(f"Created agent executor with max_iterations={self.max_steps} and {len(self.callbacks)} callbacks")
         return executor
 
     def get_conversation_history(self) -> list[BaseMessage]:
@@ -469,6 +492,26 @@ class MCPAgent:
 
             logger.info(f"🏁 Starting agent execution with max_steps={steps}")
 
+            # Track whether agent finished successfully vs reached max iterations
+            agent_finished_successfully = False
+            result = None
+
+            # Create a run manager with our callbacks if we have any - ONCE for the entire execution
+            run_manager = None
+            if self.callbacks:
+                # Create an async callback manager with our callbacks
+                from langchain_core.callbacks.manager import AsyncCallbackManager
+
+                callback_manager = AsyncCallbackManager.configure(
+                    inheritable_callbacks=self.callbacks,
+                    local_callbacks=self.callbacks,
+                )
+                # Create a run manager for this chain execution
+                run_manager = await callback_manager.on_chain_start(
+                    {"name": "MCPAgent (mcp-use)"},
+                    inputs,
+                )
+
             for step_num in range(steps):
                 steps_taken = step_num + 1
                 # --- Check for tool updates if using server manager ---
@@ -498,20 +541,52 @@ class MCPAgent:
 
                 # --- Plan and execute the next step ---
                 try:
-                    # Use the internal _atake_next_step which handles planning and execution
-                    # This requires providing the necessary context like maps and intermediate steps
-                    next_step_output = await self._agent_executor._atake_next_step(
-                        name_to_tool_map=name_to_tool_map,
-                        color_mapping=color_mapping,
-                        inputs=inputs,
-                        intermediate_steps=intermediate_steps,
-                        run_manager=None,
-                    )
+                    retry_count = 0
+                    next_step_output = None
+
+                    while retry_count <= self.max_retries_per_step:
+                        try:
+                            # Use the internal _atake_next_step which handles planning and execution
+                            # This requires providing the necessary context like maps and intermediate steps
+                            next_step_output = await self._agent_executor._atake_next_step(
+                                name_to_tool_map=name_to_tool_map,
+                                color_mapping=color_mapping,
+                                inputs=inputs,
+                                intermediate_steps=intermediate_steps,
+                                run_manager=run_manager,
+                            )
+
+                            # If we get here, the step succeeded, break out of retry loop
+                            break
+
+                        except Exception as e:
+                            if not self.retry_on_error or retry_count >= self.max_retries_per_step:
+                                logger.error(f"❌ Validation error during step {step_num + 1}: {e}")
+                                result = f"Agent stopped due to a validation error: {str(e)}"
+                                success = False
+                                yield result
+                                return
+
+                            retry_count += 1
+                            logger.warning(
+                                f"⚠️ Validation error, retrying ({retry_count}/{self.max_retries_per_step}): {e}"
+                            )
+
+                            # Create concise feedback for the LLM about the validation error
+                            error_message = f"Error: {str(e)}"
+                            inputs["input"] = error_message
+
+                            # Continue to next iteration of retry loop
+                            continue
 
                     # Process the output
                     if isinstance(next_step_output, AgentFinish):
                         logger.info(f"✅ Agent finished at step {step_num + 1}")
+                        agent_finished_successfully = True
                         result = next_step_output.return_values.get("output", "No output generated")
+                        # End the chain if we have a run manager
+                        if run_manager:
+                            await run_manager.on_chain_end({"output": result})
 
                         # If structured output is requested, attempt to create it
                         if output_schema and structured_llm:
@@ -563,6 +638,12 @@ class MCPAgent:
                     for agent_step in next_step_output:
                         yield agent_step
                         action, observation = agent_step
+                        reasoning = getattr(action, "log", "")
+                        if reasoning:
+                            reasoning_str = reasoning.replace("\n", " ")
+                            if len(reasoning_str) > 300:
+                                reasoning_str = reasoning_str[:297] + "..."
+                            logger.info(f"💭 Reasoning: {reasoning_str}")
                         tool_name = action.tool
                         self.tools_used_names.append(tool_name)
                         tool_input_str = str(action.tool_input)
@@ -583,25 +664,39 @@ class MCPAgent:
                         tool_return = self._agent_executor._get_tool_return(last_step)
                         if tool_return is not None:
                             logger.info(f"🏆 Tool returned directly at step {step_num + 1}")
+                            agent_finished_successfully = True
                             result = tool_return.return_values.get("output", "No output generated")
                             break
 
                 except OutputParserException as e:
                     logger.error(f"❌ Output parsing error during step {step_num + 1}: {e}")
                     result = f"Agent stopped due to a parsing error: {str(e)}"
+                    if run_manager:
+                        await run_manager.on_chain_error(e)
                     break
                 except Exception as e:
                     logger.error(f"❌ Error during agent execution step {step_num + 1}: {e}")
                     import traceback
 
                     traceback.print_exc()
+                    # End the chain with error if we have a run manager
+                    if run_manager:
+                        await run_manager.on_chain_error(e)
                     result = f"Agent stopped due to an error: {str(e)}"
                     break
 
             # --- Loop finished ---
             if not result:
-                logger.warning(f"⚠️ Agent stopped after reaching max iterations ({steps})")
-                result = f"Agent stopped after reaching the maximum number of steps ({steps})."
+                if agent_finished_successfully:
+                    # Agent finished successfully but returned empty output
+                    result = "Agent completed the task successfully."
+                    logger.info("✅ Agent finished successfully with empty output")
+                else:
+                    # Agent actually reached max iterations
+                    logger.warning(f"⚠️ Agent stopped after reaching max iterations ({steps})")
+                    result = f"Agent stopped after reaching the maximum number of steps ({steps})."
+                    if run_manager:
+                        await run_manager.on_chain_end({"output": result})
 
             # If structured output was requested but not achieved, attempt one final time
             if output_schema and structured_llm and not success:
@@ -738,7 +833,8 @@ class MCPAgent:
         """
         # Delegate to remote agent if in remote mode
         if self._is_remote and self._remote_agent:
-            return await self._remote_agent.run(query, max_steps, manage_connector, external_history, output_schema)
+            result = await self._remote_agent.run(query, max_steps, external_history, output_schema)
+            return result
 
         success = True
         start_time = time.time()

mcp_use/agents/prompts/templates.py

@@ -5,16 +5,7 @@ You have access to the following tools:
 
 {tool_descriptions}
 
-Use the following format:
-
-Question: the input question you must answer
-Thought: you should always think about what to do
-Action: the action to take, should be one of the available tools
-Action Input: the input to the action
-Observation: the result of the action
-... (this Thought/Action/Action Input/Observation can repeat N times)
-Thought: I now know the final answer
-Final Answer: the final answer to the original input question"""
+Use these tools to help answer questions and complete tasks as needed."""
 
 
 SERVER_MANAGER_SYSTEM_PROMPT_TEMPLATE = """You are a helpful assistant designed

mcp_use/agents/remote.py

@@ -5,6 +5,7 @@ Remote agent implementation for executing agents via API.
 import json
 import os
 from typing import Any, TypeVar
+from uuid import UUID
 
 import httpx
 from langchain.schema import BaseMessage
@@ -15,25 +16,52 @@ from ..logging import logger
 T = TypeVar("T", bound=BaseModel)
 
 # API endpoint constants
-API_CHATS_ENDPOINT = "/api/v1/chats"
+API_CHATS_ENDPOINT = "/api/v1/chats/get-or-create"
 API_CHAT_EXECUTE_ENDPOINT = "/api/v1/chats/{chat_id}/execute"
 API_CHAT_DELETE_ENDPOINT = "/api/v1/chats/{chat_id}"
 
+UUID_ERROR_MESSAGE = """A UUID is a 36 character string of the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \n
+Example: 123e4567-e89b-12d3-a456-426614174000
+To generate a UUID, you can use the following command:
+import uuid
+
+# Generate a random UUID
+my_uuid = uuid.uuid4()
+print(my_uuid)
+"""
+
 
 class RemoteAgent:
     """Agent that executes remotely via API."""
 
-    def __init__(self, agent_id: str, api_key: str | None = None, base_url: str = "https://cloud.mcp-use.com"):
+    def __init__(
+        self,
+        agent_id: str,
+        chat_id: str | None = None,
+        api_key: str | None = None,
+        base_url: str = "https://cloud.mcp-use.com",
+    ):
         """Initialize remote agent.
 
         Args:
             agent_id: The ID of the remote agent to execute
+            chat_id: The ID of the chat session to use. If None, a new chat session will be created.
             api_key: API key for authentication. If None, will check MCP_USE_API_KEY env var
             base_url: Base URL for the remote API
         """
+
+        if chat_id is not None:
+            try:
+                chat_id = str(UUID(chat_id))
+            except ValueError as e:
+                raise ValueError(
+                    f"Invalid chat ID: {chat_id}, make sure to provide a valid UUID.\n{UUID_ERROR_MESSAGE}"
+                ) from e
+
         self.agent_id = agent_id
+        self.chat_id = chat_id
+        self._session_established = False
         self.base_url = base_url
-        self._chat_id = None  # Persistent chat session
 
         # Handle API key validation
         if api_key is None:
@@ -109,16 +137,14 @@ class RemoteAgent:
                 return output_schema.model_validate({"content": str(result_data)})
             raise
 
-    async def _create_chat_session(self, query: str) -> str:
-        """Create a persistent chat session for the agent.
-        Args:
-            query: The initial query (not used in title anymore)
+    async def _upsert_chat_session(self) -> str:
+        """Create or resume a persistent chat session for the agent via upsert.
+
         Returns:
-            The chat ID of the created session
-        Raises:
-            RuntimeError: If chat creation fails
+            The chat session ID
         """
         chat_payload = {
+            "id": self.chat_id,  # Include chat_id for resuming or None for creating
             "title": f"Remote Agent Session - {self.agent_id}",
             "agent_id": self.agent_id,
             "type": "agent_execution",
@@ -127,7 +153,7 @@ class RemoteAgent:
         headers = {"Content-Type": "application/json", "x-api-key": self.api_key}
         chat_url = f"{self.base_url}{API_CHATS_ENDPOINT}"
 
-        logger.info(f"📝 Creating chat session for agent {self.agent_id}")
+        logger.info(f"📝 Upserting chat session for agent {self.agent_id}")
 
         try:
             chat_response = await self._client.post(chat_url, json=chat_payload, headers=headers)
@@ -135,7 +161,11 @@ class RemoteAgent:
 
             chat_data = chat_response.json()
             chat_id = chat_data["id"]
-            logger.info(f"✅ Chat session created: {chat_id}")
+            if chat_response.status_code == 201:
+                logger.info(f"✅ New chat session created: {chat_id}")
+            else:
+                logger.info(f"✅ Resumed chat session: {chat_id}")
+
             return chat_id
 
         except httpx.HTTPStatusError as e:
@@ -156,7 +186,6 @@ class RemoteAgent:
         self,
         query: str,
         max_steps: int | None = None,
-        manage_connector: bool = True,
         external_history: list[BaseMessage] | None = None,
         output_schema: type[T] | None = None,
     ) -> str | T:
@@ -165,8 +194,7 @@ class RemoteAgent:
         Args:
             query: The query to execute
             max_steps: Maximum number of steps (default: 10)
-            manage_connector: Ignored for remote execution
-            external_history: Ignored for remote execution (not supported yet)
+            external_history: External history (not supported yet for remote execution)
             output_schema: Optional Pydantic model for structured output
 
         Returns:
@@ -178,11 +206,14 @@ class RemoteAgent:
         try:
             logger.info(f"🌐 Executing query on remote agent {self.agent_id}")
 
-            # Step 1: Create a chat session for this agent (only if we don't have one)
-            if self._chat_id is None:
-                self._chat_id = await self._create_chat_session(query)
+            # Step 1: Ensure chat session exists on the backend by upserting.
+            # This happens once per agent instance.
+            if not self._session_established:
+                logger.info(f"🔧 Establishing chat session for agent {self.agent_id}")
+                self.chat_id = await self._upsert_chat_session()
+                self._session_established = True
 
-            chat_id = self._chat_id
+            chat_id = self.chat_id
 
             # Step 2: Execute the agent within the chat context
             execution_payload = {"query": query, "max_steps": max_steps or 10}

mcp_use/auth/__init__.py

@@ -0,0 +1,6 @@
+"""Authentication support for MCP clients."""
+
+from .bearer import BearerAuth
+from .oauth import OAuth
+
+__all__ = ["BearerAuth", "OAuth"]

mcp_use/auth/bearer.py

@@ -0,0 +1,17 @@
+"""Bearer token authentication support."""
+
+from collections.abc import Generator
+
+import httpx
+from pydantic import BaseModel, SecretStr
+
+
+class BearerAuth(httpx.Auth, BaseModel):
+    """Bearer token authentication for HTTP requests."""
+
+    token: SecretStr
+
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
+        """Apply bearer token authentication to the request."""
+        request.headers["Authorization"] = f"Bearer {self.token.get_secret_value()}"
+        yield request