agno 2.2.10__py3-none-any.whl → 2.2.11__py3-none-any.whl

agno/agent/agent.py

@@ -5763,6 +5763,9 @@ class Agent:
                 raise ValueError("Db not initialized")
             return self.db.get_session(session_id=session_id, session_type=session_type)  # type: ignore
         except Exception as e:
+            import traceback
+
+            traceback.print_exc(limit=3)
             log_warning(f"Error getting session from db: {e}")
             return None
 
@@ -5773,8 +5776,11 @@ class Agent:
         try:
             if not self.db:
                 raise ValueError("Db not initialized")
-            return await self.db.get_session(session_id=session_id, session_type=SessionType.AGENT)  # type: ignore
+            return await self.db.get_session(session_id=session_id, session_type=session_type)  # type: ignore
         except Exception as e:
+            import traceback
+
+            traceback.print_exc(limit=3)
             log_warning(f"Error getting session from db: {e}")
             return None
 
@@ -5786,6 +5792,9 @@ class Agent:
                 raise ValueError("Db not initialized")
             return self.db.upsert_session(session=session)  # type: ignore
         except Exception as e:
+            import traceback
+
+            traceback.print_exc(limit=3)
             log_warning(f"Error upserting session into db: {e}")
             return None
 
@@ -5796,6 +5805,9 @@ class Agent:
                 raise ValueError("Db not initialized")
             return await self.db.upsert_session(session=session)  # type: ignore
         except Exception as e:
+            import traceback
+
+            traceback.print_exc(limit=3)
             log_warning(f"Error upserting session into db: {e}")
             return None
 

agno/db/dynamo/utils.py

@@ -343,7 +343,7 @@ def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
     ]
     all_user_ids = set()
     for session_type, sessions_count_key, runs_count_key in session_types:
-        sessions = sessions_data.get(session_type, [])
+        sessions = sessions_data.get(session_type, []) or []
         metrics[sessions_count_key] = len(sessions)
         for session in sessions:
             if session.get("user_id"):

agno/db/firestore/utils.py

@@ -194,7 +194,7 @@ def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
     all_user_ids = set()
 
     for session_type, sessions_count_key, runs_count_key in session_types:
-        sessions = sessions_data.get(session_type, [])
+        sessions = sessions_data.get(session_type, []) or []
         metrics[sessions_count_key] = len(sessions)
 
         for session in sessions:

agno/db/gcs_json/utils.py

@@ -78,7 +78,7 @@ def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
     all_user_ids = set()
 
     for session_type, sessions_count_key, runs_count_key in session_types:
-        sessions = sessions_data.get(session_type, [])
+        sessions = sessions_data.get(session_type, []) or []
         metrics[sessions_count_key] = len(sessions)
 
         for session in sessions:

agno/db/in_memory/utils.py

@@ -78,7 +78,7 @@ def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
     all_user_ids = set()
 
     for session_type, sessions_count_key, runs_count_key in session_types:
-        sessions = sessions_data.get(session_type, [])
+        sessions = sessions_data.get(session_type, []) or []
         metrics[sessions_count_key] = len(sessions)
 
         for session in sessions:

agno/db/json/utils.py

@@ -78,7 +78,7 @@ def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
     all_user_ids = set()
 
     for session_type, sessions_count_key, runs_count_key in session_types:
-        sessions = sessions_data.get(session_type, [])
+        sessions = sessions_data.get(session_type, []) or []
         metrics[sessions_count_key] = len(sessions)
 
         for session in sessions:

agno/db/mongo/utils.py

@@ -89,14 +89,14 @@ def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
     all_user_ids = set()
 
     for session_type, sessions_count_key, runs_count_key in session_types:
-        sessions = sessions_data.get(session_type, [])
+        sessions = sessions_data.get(session_type, []) or []
         metrics[sessions_count_key] = len(sessions)
 
         for session in sessions:
             if session.get("user_id"):
                 all_user_ids.add(session["user_id"])
-            runs = session.get("runs", []) or []
-            metrics[runs_count_key] += len(sessions)
+            runs = session.get("runs", [])
+            metrics[runs_count_key] += len(runs)
 
             if runs := session.get("runs", []):
                 if isinstance(runs, str):

agno/db/mysql/utils.py

@@ -205,7 +205,7 @@ def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
     all_user_ids = set()
 
     for session_type, sessions_count_key, runs_count_key in session_types:
-        sessions = sessions_data.get(session_type, [])
+        sessions = sessions_data.get(session_type, []) or []
         metrics[sessions_count_key] = len(sessions)
 
         for session in sessions:

agno/db/postgres/utils.py

@@ -292,7 +292,7 @@ def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
     all_user_ids = set()
 
     for session_type, sessions_count_key, runs_count_key in session_types:
-        sessions = sessions_data.get(session_type, [])
+        sessions = sessions_data.get(session_type, []) or []
         metrics[sessions_count_key] = len(sessions)
 
         for session in sessions:

agno/db/redis/utils.py

@@ -200,7 +200,7 @@ def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
     all_user_ids = set()
 
     for session_type, sessions_count_key, runs_count_key in session_types:
-        sessions = sessions_data.get(session_type, [])
+        sessions = sessions_data.get(session_type, []) or []
         metrics[sessions_count_key] = len(sessions)
 
         for session in sessions:

agno/db/singlestore/utils.py

@@ -234,7 +234,7 @@ def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
     all_user_ids = set()
 
     for session_type, sessions_count_key, runs_count_key in session_types:
-        sessions = sessions_data.get(session_type, [])
+        sessions = sessions_data.get(session_type, []) or []
         metrics[sessions_count_key] = len(sessions)
 
         for session in sessions:

agno/db/sqlite/utils.py

@@ -270,7 +270,7 @@ def calculate_date_metrics(date_to_process: date, sessions_data: dict) -> dict:
     all_user_ids = set()
 
     for session_type, sessions_count_key, runs_count_key in session_types:
-        sessions = sessions_data.get(session_type, [])
+        sessions = sessions_data.get(session_type, []) or []
         metrics[sessions_count_key] = len(sessions)
 
         for session in sessions:

agno/knowledge/chunking/agentic.py

@@ -20,13 +20,12 @@ class AgenticChunking(ChunkingStrategy):
             except Exception:
                 raise ValueError("`openai` isn't installed. Please install it with `pip install openai`")
             model = OpenAIChat(DEFAULT_OPENAI_MODEL_ID)
-
-        self.max_chunk_size = max_chunk_size
+        self.chunk_size = max_chunk_size
         self.model = model
 
     def chunk(self, document: Document) -> List[Document]:
         """Split text into chunks using LLM to determine natural breakpoints based on context"""
-        if len(document.content) <= self.max_chunk_size:
+        if len(document.content) <= self.chunk_size:
             return [document]
 
         chunks: List[Document] = []
@@ -35,22 +34,22 @@ class AgenticChunking(ChunkingStrategy):
         chunk_number = 1
 
         while remaining_text:
-            # Ask model to find a good breakpoint within max_chunk_size
-            prompt = f"""Analyze this text and determine a natural breakpoint within the first {self.max_chunk_size} characters.
+            # Ask model to find a good breakpoint within chunk_size
+            prompt = f"""Analyze this text and determine a natural breakpoint within the first {self.chunk_size} characters.
             Consider semantic completeness, paragraph boundaries, and topic transitions.
             Return only the character position number of where to break the text:
 
-            {remaining_text[: self.max_chunk_size]}"""
+            {remaining_text[: self.chunk_size]}"""
 
             try:
                 response = self.model.response([Message(role="user", content=prompt)])
                 if response and response.content:
-                    break_point = min(int(response.content.strip()), self.max_chunk_size)
+                    break_point = min(int(response.content.strip()), self.chunk_size)
                 else:
-                    break_point = self.max_chunk_size
+                    break_point = self.chunk_size
             except Exception:
                 # Fallback to max size if model fails
-                break_point = self.max_chunk_size
+                break_point = self.chunk_size
 
             # Extract chunk and update remaining text
             chunk = remaining_text[:break_point].strip()

agno/knowledge/chunking/strategy.py

@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 from enum import Enum
-from typing import List
+from typing import List, Optional
 
 from agno.knowledge.document.base import Document
 
@@ -60,7 +60,13 @@ class ChunkingStrategyFactory:
     """Factory for creating chunking strategy instances."""
 
     @classmethod
-    def create_strategy(cls, strategy_type: ChunkingStrategyType, **kwargs) -> ChunkingStrategy:
+    def create_strategy(
+        cls,
+        strategy_type: ChunkingStrategyType,
+        chunk_size: Optional[int] = None,
+        overlap: Optional[int] = None,
+        **kwargs,
+    ) -> ChunkingStrategy:
         """Create an instance of the chunking strategy with the given parameters."""
         strategy_map = {
             ChunkingStrategyType.AGENTIC_CHUNKER: cls._create_agentic_chunking,
@@ -71,51 +77,89 @@ class ChunkingStrategyFactory:
             ChunkingStrategyType.ROW_CHUNKER: cls._create_row_chunking,
             ChunkingStrategyType.MARKDOWN_CHUNKER: cls._create_markdown_chunking,
         }
-        return strategy_map[strategy_type](**kwargs)
+        return strategy_map[strategy_type](chunk_size=chunk_size, overlap=overlap, **kwargs)
 
     @classmethod
-    def _create_agentic_chunking(cls, **kwargs) -> ChunkingStrategy:
+    def _create_agentic_chunking(
+        cls, chunk_size: Optional[int] = None, overlap: Optional[int] = None, **kwargs
+    ) -> ChunkingStrategy:
         from agno.knowledge.chunking.agentic import AgenticChunking
 
-        # Map chunk_size to max_chunk_size for AgenticChunking
-        if "chunk_size" in kwargs and "max_chunk_size" not in kwargs:
-            kwargs["max_chunk_size"] = kwargs.pop("chunk_size")
+        # AgenticChunking accepts max_chunk_size (not chunk_size) and no overlap
+        if chunk_size is not None:
+            kwargs["max_chunk_size"] = chunk_size
+        # Remove overlap since AgenticChunking doesn't support it
         return AgenticChunking(**kwargs)
 
     @classmethod
-    def _create_document_chunking(cls, **kwargs) -> ChunkingStrategy:
+    def _create_document_chunking(
+        cls, chunk_size: Optional[int] = None, overlap: Optional[int] = None, **kwargs
+    ) -> ChunkingStrategy:
         from agno.knowledge.chunking.document import DocumentChunking
 
+        # DocumentChunking accepts both chunk_size and overlap
+        if chunk_size is not None:
+            kwargs["chunk_size"] = chunk_size
+        if overlap is not None:
+            kwargs["overlap"] = overlap
         return DocumentChunking(**kwargs)
 
     @classmethod
-    def _create_recursive_chunking(cls, **kwargs) -> ChunkingStrategy:
+    def _create_recursive_chunking(
+        cls, chunk_size: Optional[int] = None, overlap: Optional[int] = None, **kwargs
+    ) -> ChunkingStrategy:
         from agno.knowledge.chunking.recursive import RecursiveChunking
 
+        # RecursiveChunking accepts both chunk_size and overlap
+        if chunk_size is not None:
+            kwargs["chunk_size"] = chunk_size
+        if overlap is not None:
+            kwargs["overlap"] = overlap
         return RecursiveChunking(**kwargs)
 
     @classmethod
-    def _create_semantic_chunking(cls, **kwargs) -> ChunkingStrategy:
+    def _create_semantic_chunking(
+        cls, chunk_size: Optional[int] = None, overlap: Optional[int] = None, **kwargs
+    ) -> ChunkingStrategy:
         from agno.knowledge.chunking.semantic import SemanticChunking
 
+        # SemanticChunking accepts chunk_size but not overlap
+        if chunk_size is not None:
+            kwargs["chunk_size"] = chunk_size
+        # Remove overlap since SemanticChunking doesn't support it
         return SemanticChunking(**kwargs)
 
     @classmethod
-    def _create_fixed_chunking(cls, **kwargs) -> ChunkingStrategy:
+    def _create_fixed_chunking(
+        cls, chunk_size: Optional[int] = None, overlap: Optional[int] = None, **kwargs
+    ) -> ChunkingStrategy:
         from agno.knowledge.chunking.fixed import FixedSizeChunking
 
+        # FixedSizeChunking accepts both chunk_size and overlap
+        if chunk_size is not None:
+            kwargs["chunk_size"] = chunk_size
+        if overlap is not None:
+            kwargs["overlap"] = overlap
         return FixedSizeChunking(**kwargs)
 
     @classmethod
-    def _create_row_chunking(cls, **kwargs) -> ChunkingStrategy:
+    def _create_row_chunking(
+        cls, chunk_size: Optional[int] = None, overlap: Optional[int] = None, **kwargs
+    ) -> ChunkingStrategy:
         from agno.knowledge.chunking.row import RowChunking
 
-        # Remove chunk_size if present since RowChunking doesn't use it
-        kwargs.pop("chunk_size", None)
+        # RowChunking doesn't accept chunk_size or overlap, only skip_header and clean_rows
         return RowChunking(**kwargs)
 
     @classmethod
-    def _create_markdown_chunking(cls, **kwargs) -> ChunkingStrategy:
+    def _create_markdown_chunking(
+        cls, chunk_size: Optional[int] = None, overlap: Optional[int] = None, **kwargs
+    ) -> ChunkingStrategy:
         from agno.knowledge.chunking.markdown import MarkdownChunking
 
+        # MarkdownChunking accepts both chunk_size and overlap
+        if chunk_size is not None:
+            kwargs["chunk_size"] = chunk_size
+        if overlap is not None:
+            kwargs["overlap"] = overlap
         return MarkdownChunking(**kwargs)

agno/knowledge/embedder/sentence_transformer.py

@@ -25,10 +25,14 @@ class SentenceTransformerEmbedder(Embedder):
     prompt: Optional[str] = None
     normalize_embeddings: bool = False
 
-    def get_embedding(self, text: Union[str, List[str]]) -> List[float]:
-        if not self.sentence_transformer_client:
+    def __post_init__(self):
+        # Initialize the SentenceTransformer model eagerly to avoid race conditions in async contexts
+        if self.sentence_transformer_client is None:
             self.sentence_transformer_client = SentenceTransformer(model_name_or_path=self.id)
 
+    def get_embedding(self, text: Union[str, List[str]]) -> List[float]:
+        if self.sentence_transformer_client is None:
+            raise RuntimeError("SentenceTransformer model not initialized")
         model = self.sentence_transformer_client
         embedding = model.encode(text, prompt=self.prompt, normalize_embeddings=self.normalize_embeddings)
         try:

agno/knowledge/reader/base.py

@@ -44,11 +44,15 @@ class Reader:
         self.max_results = max_results
         self.encoding = encoding
 
-    def set_chunking_strategy_from_string(self, strategy_name: str, **kwargs) -> None:
+    def set_chunking_strategy_from_string(
+        self, strategy_name: str, chunk_size: Optional[int] = None, overlap: Optional[int] = None, **kwargs
+    ) -> None:
         """Set the chunking strategy from a string name."""
         try:
             strategy_type = ChunkingStrategyType.from_string(strategy_name)
-            self.chunking_strategy = ChunkingStrategyFactory.create_strategy(strategy_type, **kwargs)
+            self.chunking_strategy = ChunkingStrategyFactory.create_strategy(
+                strategy_type, chunk_size=chunk_size, overlap=overlap, **kwargs
+            )
         except ValueError as e:
             raise ValueError(f"Failed to set chunking strategy: {e}")
 

agno/knowledge/utils.py

@@ -129,12 +129,32 @@ def get_chunker_info(chunker_key: str) -> Dict:
             class_name = chunker_class.__name__
             docstring = chunker_class.__doc__ or f"{class_name} chunking strategy"
 
+            # Check class __init__ signature for chunk_size and overlap parameters
+            metadata = {}
+            import inspect
+
+            try:
+                sig = inspect.signature(chunker_class.__init__)
+                param_names = set(sig.parameters.keys())
+
+                # If class has chunk_size or max_chunk_size parameter, set default chunk_size
+                if "chunk_size" in param_names or "max_chunk_size" in param_names:
+                    metadata["chunk_size"] = 5000
+
+                # If class has overlap parameter, set default overlap
+                if "overlap" in param_names:
+                    metadata["chunk_overlap"] = 0
+            except Exception:
+                # If we can't inspect, skip metadata
+                pass
+
             return {
                 "key": chunker_key,
                 "class_name": class_name,
                 "name": chunker_key,
                 "description": docstring.strip(),
                 "strategy_type": strategy_type.value,
+                "metadata": metadata,
             }
         except ValueError:
             raise ValueError(f"Unknown chunker key: {chunker_key}")

agno/models/anthropic/claude.py

@@ -45,6 +45,8 @@ except ImportError as e:
 # Import Beta types
 try:
     from anthropic.types.beta import BetaRawContentBlockDeltaEvent, BetaTextDelta
+    from anthropic.types.beta.beta_message import BetaMessage
+    from anthropic.types.beta.beta_usage import BetaUsage
 except ImportError as e:
     raise ImportError(
         "`anthropic` not installed or missing beta components. Please install with `pip install anthropic`"
@@ -84,13 +86,14 @@ class Claude(Model):
     cache_system_prompt: Optional[bool] = False
     extended_cache_time: Optional[bool] = False
     request_params: Optional[Dict[str, Any]] = None
-    mcp_servers: Optional[List[MCPServerConfiguration]] = None
 
-    # Skills configuration
+    # Anthropic beta and experimental features
+    betas: Optional[List[str]] = None  # Enables specific experimental or newly released features.
+    context_management: Optional[Dict[str, Any]] = None
+    mcp_servers: Optional[List[MCPServerConfiguration]] = None
     skills: Optional[List[Dict[str, str]]] = (
         None  # e.g., [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
     )
-    betas: Optional[List[str]] = None  # Enables specific experimental or newly released features.
 
     # Client parameters
     api_key: Optional[str] = None
@@ -129,6 +132,15 @@ class Claude(Model):
             client_params["default_headers"] = self.default_headers
         return client_params
 
+    def _has_beta_features(self) -> bool:
+        """Check if the model has any Anthropic beta features enabled."""
+        return (
+            self.mcp_servers is not None
+            or self.context_management is not None
+            or self.skills is not None
+            or self.betas is not None
+        )
+
     def get_client(self) -> AnthropicClient:
         """
         Returns an instance of the Anthropic client.
@@ -208,6 +220,10 @@ class Claude(Model):
             _request_params["top_p"] = self.top_p
         if self.top_k:
             _request_params["top_k"] = self.top_k
+        if self.betas:
+            _request_params["betas"] = self.betas
+        if self.context_management:
+            _request_params["context_management"] = self.context_management
         if self.mcp_servers:
             _request_params["mcp_servers"] = [
                 {k: v for k, v in asdict(server).items() if v is not None} for server in self.mcp_servers
@@ -279,7 +295,7 @@ class Claude(Model):
             chat_messages, system_message = format_messages(messages)
             request_kwargs = self._prepare_request_kwargs(system_message, tools)
 
-            if self.mcp_servers is not None or self.skills is not None:
+            if self._has_beta_features():
                 assistant_message.metrics.start_timer()
                 provider_response = self.get_client().beta.messages.create(
                     model=self.id,
@@ -346,7 +362,8 @@ class Claude(Model):
             if run_response and run_response.metrics:
                 run_response.metrics.set_time_to_first_token()
 
-            if self.mcp_servers is not None or self.skills is not None:
+            # Beta features
+            if self._has_beta_features():
                 assistant_message.metrics.start_timer()
                 with self.get_client().beta.messages.stream(
                     model=self.id,
@@ -401,7 +418,8 @@ class Claude(Model):
             chat_messages, system_message = format_messages(messages)
             request_kwargs = self._prepare_request_kwargs(system_message, tools)
 
-            if self.mcp_servers is not None or self.skills is not None:
+            # Beta features
+            if self._has_beta_features():
                 assistant_message.metrics.start_timer()
                 provider_response = await self.get_async_client().beta.messages.create(
                     model=self.id,
@@ -465,7 +483,7 @@ class Claude(Model):
             chat_messages, system_message = format_messages(messages)
             request_kwargs = self._prepare_request_kwargs(system_message, tools)
 
-            if self.mcp_servers is not None or self.skills is not None:
+            if self._has_beta_features():
                 assistant_message.metrics.start_timer()
                 async with self.get_async_client().beta.messages.stream(
                     model=self.id,
@@ -507,7 +525,7 @@ class Claude(Model):
             return tool_call_prompt
         return None
 
-    def _parse_provider_response(self, response: AnthropicMessage, **kwargs) -> ModelResponse:
+    def _parse_provider_response(self, response: Union[AnthropicMessage, BetaMessage], **kwargs) -> ModelResponse:
         """
         Parse the Claude response into a ModelResponse.
 
@@ -582,6 +600,14 @@ class Claude(Model):
         if response.usage is not None:
             model_response.response_usage = self._get_metrics(response.usage)
 
+        # Capture context management information if present
+        if self.context_management is not None and hasattr(response, "context_management"):
+            if response.context_management is not None:  # type: ignore
+                model_response.provider_data = model_response.provider_data or {}
+                if hasattr(response.context_management, "model_dump"):
+                    model_response.provider_data["context_management"] = response.context_management.model_dump()  # type: ignore
+                else:
+                    model_response.provider_data["context_management"] = response.context_management  # type: ignore
         # Extract file IDs if skills are enabled
         if self.skills and response.content:
             file_ids: List[str] = []
@@ -676,6 +702,16 @@ class Claude(Model):
                             DocumentCitation(document_title=citation.document_title, cited_text=citation.cited_text)
                         )
 
+            # Capture context management information if present
+            if self.context_management is not None and hasattr(response.message, "context_management"):  # type: ignore
+                context_mgmt = response.message.context_management  # type: ignore
+                if context_mgmt is not None:
+                    model_response.provider_data = model_response.provider_data or {}
+                    if hasattr(context_mgmt, "model_dump"):
+                        model_response.provider_data["context_management"] = context_mgmt.model_dump()
+                    else:
+                        model_response.provider_data["context_management"] = context_mgmt
+
         if hasattr(response, "message") and hasattr(response.message, "usage") and response.message.usage is not None:  # type: ignore
             model_response.response_usage = self._get_metrics(response.message.usage)  # type: ignore
 
@@ -692,7 +728,7 @@ class Claude(Model):
 
         return model_response
 
-    def _get_metrics(self, response_usage: Union[Usage, MessageDeltaUsage]) -> Metrics:
+    def _get_metrics(self, response_usage: Union[Usage, MessageDeltaUsage, BetaUsage]) -> Metrics:
         """
         Parse the given Anthropic-specific usage into an Agno Metrics object.
 

agno/models/base.py

@@ -692,6 +692,8 @@ class Model(ABC):
             if model_response.extra is None:
                 model_response.extra = {}
             model_response.extra.update(provider_response.extra)
+        if provider_response.provider_data is not None:
+            model_response.provider_data = provider_response.provider_data
 
     async def _aprocess_model_response(
         self,
@@ -745,6 +747,8 @@ class Model(ABC):
             if model_response.extra is None:
                 model_response.extra = {}
             model_response.extra.update(provider_response.extra)
+        if provider_response.provider_data is not None:
+            model_response.provider_data = provider_response.provider_data
 
     def _populate_assistant_message(
         self,

agno/os/app.py

@@ -232,6 +232,12 @@ class AgentOS:
         self._initialize_workflows()
         self._auto_discover_databases()
         self._auto_discover_knowledge_instances()
+
+        if self.enable_mcp_server:
+            from agno.os.mcp import get_mcp_server
+
+            self._mcp_app = get_mcp_server(self)
+
         self._reprovision_routers(app=app)
 
     def _reprovision_routers(self, app: FastAPI) -> None:
@@ -248,7 +254,9 @@ class AgentOS:
         app.router.routes = [
             route
             for route in app.router.routes
-            if hasattr(route, "path") and route.path in ["/docs", "/redoc", "/openapi.json", "/docs/oauth2-redirect"]  # type: ignore
+            if hasattr(route, "path")
+            and route.path in ["/docs", "/redoc", "/openapi.json", "/docs/oauth2-redirect"]
+            or route.path.startswith("/mcp")  # type: ignore
         ]
 
         # Add the built-in routes
@@ -258,13 +266,17 @@ class AgentOS:
         for router in updated_routers:
             self._add_router(app, router)
 
+        # Mount MCP if needed
+        if self.enable_mcp_server and self._mcp_app:
+            app.mount("/", self._mcp_app)
+
     def _add_built_in_routes(self, app: FastAPI) -> None:
         """Add all AgentOSbuilt-in routes to the given app."""
         # Add the home router if MCP server is not enabled
         if not self.enable_mcp_server:
             self._add_router(app, get_home_router(self))
 
-        self._add_router(app, get_health_router())
+        self._add_router(app, get_health_router(health_endpoint="/health"))
         self._add_router(app, get_base_router(self, settings=self.settings))
         self._add_router(app, get_websocket_router(self, settings=self.settings))
 
@@ -381,20 +393,24 @@ class AgentOS:
             # Collect all lifespans that need to be combined
             lifespans = []
 
+            # The user provided lifespan
+            if self.lifespan:
+                # Wrap the user lifespan with agent_os parameter
+                wrapped_lifespan = self._add_agent_os_to_lifespan_function(self.lifespan)
+                lifespans.append(wrapped_lifespan)
+
+            # The provided app's existing lifespan
             if fastapi_app.router.lifespan_context:
                 lifespans.append(fastapi_app.router.lifespan_context)
 
+            # The MCP tools lifespan
             if self.mcp_tools:
                 lifespans.append(partial(mcp_lifespan, mcp_tools=self.mcp_tools))
 
+            # The /mcp server lifespan
             if self.enable_mcp_server and self._mcp_app:
                 lifespans.append(self._mcp_app.lifespan)
 
-            if self.lifespan:
-                # Wrap the user lifespan with agent_os parameter
-                wrapped_lifespan = self._add_agent_os_to_lifespan_function(self.lifespan)
-                lifespans.append(wrapped_lifespan)
-
             # Combine lifespans and set them in the app
             if lifespans:
                 fastapi_app.router.lifespan_context = _combine_app_lifespans(lifespans)