massgen 0.0.3__py3-none-any.whl → 0.1.0__py3-none-any.whl

massgen/backend/docs/Gemini MCP Integration Analysis.md

@@ -0,0 +1,1050 @@
+ Gemini MCP Integration Analysis
+
+## Executive Summary
+
+Gemini uses MCP sessions as tools by passing an MCP client session directly to the Gemini SDK, which automatically manages the session and enables seamless tool calling with MCP servers
+
+Key features of the Gemini MCP integration include:
+
+- **Session-based tool execution**: MCP tools are exposed as sessions to the Gemini SDK, which handles tool calling automatically
+- **Robust error handling**: Circuit breaker patterns, exponential backoff retry logic, and graceful degradation
+- **Resource management**: Proper connection lifecycle management with async context managers
+- **Comprehensive monitoring**: Tool usage tracking, performance metrics, and detailed logging
+- **Fallback mechanisms**: Automatic fallback to builtin tools when MCP connections fail
+
+This approach provides a more streamlined user experience compared to manual tool calling, as the SDK handles the complexity of determining when and how to use tools based on the conversation context.
+
+## MCP Integration Architecture in Gemini Backend
+
+### Architecture Overview
+
+The Gemini backend implements a sophisticated layered architecture for MCP integration. The visual diagrams below illustrate:
+
+1. **Architecture Overview**: Complete system architecture showing all layers and data flow
+2. **Detailed Component Architecture**: Internal structure of key components
+3. **Session-Based Tool Calling Process**: Sequence diagram of tool execution flow
+4. **Circuit Breaker State Machine**: State transitions for fault tolerance
+5. **Error Handling Decision Tree**: Logic flow for different error scenarios
+6. **Data Flow Architecture**: End-to-end data flow from input to output
+
+These diagrams provide a comprehensive visual understanding of how MCP tools are integrated, configured, and executed within the Gemini backend:
+
+```mermaid
+graph TB
+    %% Configuration Flow
+    subgraph "Configuration Layer"
+        A1[YAML Configuration] --> A2[mcp_servers<br/>allowed_tools<br/>exclude_tools]
+        A3[Circuit Breaker<br/>Settings] --> A2
+    end
+
+    %% Backend Initialization
+    subgraph "Backend Layer"
+        B1[GeminiBackend<br/>__init__] --> B2[MCP Config<br/>Extraction]
+        B2 --> B3[Circuit Breaker<br/>Initialization]
+        B3 --> B4[MultiMCPClient<br/>Reference Setup]
+    end
+
+    %% MCP Integration Core
+    subgraph "MCP Integration Layer"
+        C1[_setup_mcp_tools<br/>Method] --> C2[Configuration<br/>Validation]
+        C2 --> C3[Server<br/>Normalization]
+        C3 --> C4[Circuit Breaker<br/>Filtering]
+        C4 --> C5[MultiMCPClient<br/>Connection]
+
+        C6[stream_with_tools<br/>Method] --> C7[MCP Client<br/>Health Check]
+        C7 --> C8[Active Sessions<br/>Retrieval]
+        C8 --> C9[Gemini SDK<br/>Integration]
+    end
+
+    %% External Components
+    subgraph "External Systems"
+        D1[MCP Servers<br/>stdio/streamable-http]
+        D2[Gemini API<br/>SDK]
+        D3[Circuit Breaker<br/>State Store]
+    end
+
+    %% Data Flow
+    A1 --> B1
+    B4 --> C1
+    C5 --> D1
+    C9 --> D2
+    B3 --> D3
+
+    %% Tool Execution Flow
+    subgraph "Tool Execution Flow"
+        E1[User Query] --> E2[Gemini SDK<br/>Analysis]
+        E2 --> E3{Requires<br/>MCP Tools?}
+        E3 -->|Yes| E4[Automatic Tool<br/>Selection]
+        E3 -->|No| E5[Direct Response]
+        E4 --> E6[Tool Execution<br/>via Sessions]
+        E6 --> E7[Result Integration]
+        E7 --> E8[Final Response<br/>to User]
+    end
+
+    %% Error Handling
+    subgraph "Error Handling & Resilience"
+        F1[Connection<br/>Failures] --> F2[Circuit Breaker<br/>Activation]
+        F2 --> F3[Server<br/>Filtering]
+        F3 --> F4[Retry Logic<br/>with Backoff]
+        F4 --> F5{Recovery<br/>Possible?}
+        F5 -->|Yes| F6[Reconnection<br/>Attempt]
+        F5 -->|No| F7[Fallback to<br/>Builtin Tools]
+        F7 --> F8[Graceful<br/>Degradation]
+    end
+
+    %% Monitoring & Metrics
+    subgraph "Monitoring Layer"
+        G1[Tool Usage<br/>Counters] --> G2[Performance<br/>Metrics]
+        G2 --> G3[Error Tracking<br/>and Logging]
+        G3 --> G4[Circuit Breaker<br/>Events]
+        G4 --> G5[Health<br/>Monitoring]
+    end
+
+    %% Connect layers
+    C1 -.-> E1
+    D1 -.-> E6
+    E6 -.-> C9
+    F1 -.-> C7
+    C5 -.-> G1
+
+    style A1 fill:#e1f5fe
+    style B1 fill:#f3e5f5
+    style C1 fill:#e8f5e8
+    style D1 fill:#fff3e0
+    style E1 fill:#fce4ec
+    style F1 fill:#ffebee
+    style G1 fill:#f9fbe7
+```
+
+### Detailed Component Architecture
+
+```mermaid
+graph TD
+    subgraph "GeminiBackend Class"
+        GB1[Configuration<br/>Management] --> GB2[MCP Client<br/>Lifecycle]
+        GB2 --> GB3[Tool Execution<br/>Coordination]
+        GB3 --> GB4[Error Handling<br/>& Recovery]
+        GB4 --> GB5[Resource<br/>Management]
+    end
+
+    subgraph "MultiMCPClient"
+        MC1[Server<br/>Discovery] --> MC2[Connection<br/>Management]
+        MC2 --> MC3[Session<br/>Handling]
+        MC3 --> MC4[Tool<br/>Registry]
+        MC4 --> MC5[Health<br/>Monitoring]
+    end
+
+    subgraph "Circuit Breaker System"
+        CB1[Failure<br/>Detection] --> CB2[State<br/>Management]
+        CB2 --> CB3[Recovery<br/>Logic]
+        CB3 --> CB4[Server<br/>Filtering]
+        CB4 --> CB5[Metrics<br/>Collection]
+    end
+
+    subgraph "Error Handler Components"
+        EH1[MCPErrorHandler] --> EH2[Error<br/>Classification]
+        EH2 --> EH3[Retry<br/>Decisions]
+        EH3 --> EH4[User<br/>Feedback]
+        EH4 --> EH5[Fallback<br/>Management]
+    end
+
+    subgraph "Backend Utils Integration"
+        BU1[MCPSetupManager] --> BU2[Server<br/>Normalization]
+        BU2 --> BU3[MCPExecutionManager]
+        BU3 --> BU4[MCPMessageManager]
+        BU4 --> BU5[MCPConfigHelper]
+    end
+
+    %% Data flow connections
+    GB1 --> MC1
+    GB2 --> MC2
+    GB3 --> MC3
+    GB4 --> CB1
+    CB2 --> MC5
+    EH1 --> GB4
+    BU1 --> GB1
+    BU3 --> GB3
+
+    %% Styling
+    classDef backend fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
+    classDef client fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
+    classDef circuit fill:#fff3e0,stroke:#f57c00,stroke-width:2px
+    classDef error fill:#ffebee,stroke:#d32f2f,stroke-width:2px
+    classDef utils fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
+
+    class GB1,GB2,GB3,GB4,GB5 backend
+    class MC1,MC2,MC3,MC4,MC5 client
+    class CB1,CB2,CB3,CB4,CB5 circuit
+    class EH1,EH2,EH3,EH4,EH5 error
+    class BU1,BU2,BU3,BU4,BU5 utils
+```
+
+### Session-Based Tool Calling Process
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant GB as GeminiBackend
+    participant MMC as MultiMCPClient
+    participant GS as Gemini SDK
+    participant MS as MCP Server
+    participant CB as Circuit Breaker
+
+    Note over U,CB: User Query Processing
+
+    U->>GB: User query with tool requirements
+    GB->>GB: Check MCP client initialization
+    alt MCP client not initialized
+        GB->>MMC: Create MultiMCPClient
+        MMC->>CB: Check server health
+        CB-->>MMC: Return healthy servers
+        MMC->>MS: Connect to MCP servers
+        MS-->>MMC: Connection established
+        MMC-->>GB: Client ready
+    end
+
+    GB->>MMC: Get active sessions
+    MMC-->>GB: Return active MCP sessions
+
+    Note over GB,GS: Session Integration with SDK
+
+    GB->>GS: Generate content with MCP sessions
+    GS->>GS: Analyze query and available tools
+    GS->>GS: Determine tool requirements
+
+    alt Tool required
+        GS->>MMC: Execute tool via session
+        MMC->>MS: Forward tool call
+        MS->>MS: Execute tool logic
+        MS-->>MMC: Return tool result
+        MMC-->>GS: Tool result
+        GS->>GS: Integrate result into response
+    end
+
+    GS-->>GB: Generated response
+    GB->>CB: Record success/failure
+    GB-->>U: Final response with tool results
+
+    Note over U,CB: Error Handling Path
+
+    alt Tool execution fails
+        MMC->>GB: Tool execution error
+        GB->>CB: Record failure
+        CB->>CB: Update circuit breaker state
+        GB->>GB: Activate fallback mechanism
+        GB->>GS: Retry with builtin tools
+        GS-->>GB: Fallback response
+        GB-->>U: Response with fallback content
+    end
+```
+
+### Circuit Breaker State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Closed: Initialization
+    Closed --> Open: Failure threshold reached
+    Open --> HalfOpen: Recovery timeout
+    HalfOpen --> Closed: Test request succeeds
+    HalfOpen --> Open: Test request fails
+
+    state Closed as "Closed State\n✅ All servers available\n✅ Normal operation"
+    state Open as "Open State\n❌ Server disabled\n❌ Requests blocked"
+    state HalfOpen as "Half-Open State\n⚠️ Testing recovery\n⚠️ Limited requests"
+```
+
+### Error Handling Decision Tree
+
+```mermaid
+flowchart TD
+    A[Error Occurred] --> B{Error Type?}
+    B -->|MCPConnectionError| C[Connection Issue]
+    B -->|MCPTimeoutError| D[Timeout Issue]
+    B -->|MCPServerError| E[Server Error]
+    B -->|MCPValidationError| F[Validation Error]
+    B -->|Other| G[Unknown Error]
+
+    C --> H{Retry Count < Max?}
+    D --> H
+    E --> I{Contains retry keywords?}
+    F --> J[Immediate Failure]
+    G --> K[Log and Re-raise]
+
+    H -->|Yes| L[Exponential Backoff]
+    H -->|No| M[Fallback to Builtin]
+    I -->|timeout,connection,network,temporary,unavailable,5xx| N[Retryable Server Error]
+    I -->|other| O[Non-retryable Server Error]
+
+    L --> P[Retry Connection]
+    M --> Q[Use Builtin Tools]
+    N --> H
+    O --> J
+
+    P --> R{Success?}
+    Q --> S[Generate Response]
+
+    R -->|Yes| T[Continue Normal Flow]
+    R -->|No| H
+
+    J --> U[Raise Exception]
+    S --> V[Return Response]
+
+    style A fill:#ffebee,stroke:#d32f2f
+    style Q fill:#e8f5e8,stroke:#2e7d32
+    style U fill:#ffebee,stroke:#d32f2f
+    style T fill:#e8f5e8,stroke:#2e7d32
+```
+
+### Data Flow Architecture
+
+```mermaid
+graph LR
+    subgraph "Input Sources"
+        Y1[YAML Config<br/>mcp_servers]
+        Y2[Environment<br/>Variables]
+        Y3[Runtime<br/>Parameters]
+    end
+
+    subgraph "Configuration Processing"
+        C1[MCPConfigValidator<br/>validate_backend_mcp_config]
+        C2[MCPSetupManager<br/>normalize_mcp_servers]
+        C3[MCPConfigHelper<br/>build_circuit_breaker_config]
+    end
+
+    subgraph "Backend Integration"
+        B1[GeminiBackend<br/>__init__]
+        B2[_setup_mcp_tools]
+        B3[stream_with_tools]
+        B4[Error Handlers]
+    end
+
+    subgraph "MCP Layer"
+        M1[MultiMCPClient<br/>create_and_connect]
+        M2[MCPClient<br/>Individual Servers]
+        M3[Active Sessions<br/>Tool Registry]
+    end
+
+    subgraph "Gemini SDK"
+        G1[generate_content_stream<br/>with sessions]
+        G2[Automatic Tool<br/>Detection]
+        G3[Tool Result<br/>Integration]
+    end
+
+    subgraph "Output"
+        O1[Stream Chunks<br/>to UI]
+        O2[Tool Results<br/>Integrated]
+        O3[Error Messages<br/>Fallback Content]
+    end
+
+    %% Data flow connections
+    Y1 --> C1
+    Y2 --> C1
+    Y3 --> B1
+
+    C1 --> C2
+    C2 --> C3
+    C3 --> B1
+
+    B1 --> B2
+    B2 --> M1
+    M1 --> M2
+    M2 --> M3
+
+    B3 --> G1
+    M3 -.-> G1
+    G1 --> G2
+    G2 --> G3
+
+    G3 --> O1
+    B4 --> O3
+    M2 -.-> O2
+
+    %% Styling
+    classDef input fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
+    classDef config fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
+    classDef backend fill:#fff3e0,stroke:#f57c00,stroke-width:2px
+    classDef mcp fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
+    classDef sdk fill:#fce4ec,stroke:#c2185b,stroke-width:2px
+    classDef output fill:#f9fbe7,stroke:#689f38,stroke-width:2px
+
+    class Y1,Y2,Y3 input
+    class C1,C2,C3 config
+    class B1,B2,B3,B4 backend
+    class M1,M2,M3 mcp
+    class G1,G2,G3 sdk
+    class O1,O2,O3 output
+```
+
+### Initialization and Configuration Handling
+
+The Gemini backend's MCP integration begins in the `__init__` method, where MCP-related configuration is extracted and validated:
+
+```python
+def __init__(self, api_key: Optional[str] = None, **kwargs):
+    # MCP integration setup
+    self.mcp_servers = kwargs.pop("mcp_servers", [])
+    self.allowed_tools = kwargs.pop("allowed_tools", None)
+    self.exclude_tools = kwargs.pop("exclude_tools", None)
+    self._mcp_client: Optional[MultiMCPClient] = None
+    self._mcp_initialized = False
+```
+
+The initialization process includes:
+
+1. **Configuration extraction**: MCP servers, tool filtering parameters, and circuit breaker settings
+2. **State initialization**: Client references, monitoring counters, and connection flags
+3. **Circuit breaker setup**: Optional circuit breaker initialization for fault tolerance
+4. **Validation preparation**: Setting up for later configuration validation
+
+### MCP Client Setup Through `_setup_mcp_tools()`
+
+The `_setup_mcp_tools()` method handles the complex process of establishing MCP connections:
+
+```python
+async def _setup_mcp_tools(self, agent_id: Optional[str] = None) -> None:
+    # Configuration validation
+    if MCPConfigValidator is not None:
+        validator = MCPConfigValidator()
+        validated_config = validator.validate_backend_mcp_config(backend_config)
+    
+    # Server normalization and filtering
+    normalized_servers = self._normalize_mcp_servers()
+    filtered_servers = self._apply_mcp_tools_circuit_breaker_filtering(normalized_servers)
+    
+    # Client creation with retry logic
+    self._mcp_client = await MultiMCPClient.create_and_connect(
+        filtered_servers,
+        timeout_seconds=30,
+        allowed_tools=allowed_tools,
+        exclude_tools=exclude_tools
+    )
+```
+
+Key aspects of the setup process:
+
+- **Validation**: Uses `MCPConfigValidator` to ensure configuration correctness
+- **Normalization**: Converts various server configuration formats to standardized dictionaries
+- **Circuit breaker filtering**: Removes servers that are currently failing based on circuit breaker state
+- **Connection establishment**: Creates and connects to MCP servers with timeout handling
+- **Success tracking**: Records successful connections for circuit breaker management
+
+### Session-Based Tool Execution in `stream_with_tools()`
+
+The core of the Gemini MCP integration lies in the session-based approach within `stream_with_tools()`:
+
+```python
+# Reuse active sessions from MultiMCPClient
+mcp_sessions = self._mcp_client.get_active_sessions()
+session_config = dict(config)
+session_config["tools"] = mcp_sessions
+
+# SDK handles automatic tool calling
+stream = await client.aio.models.generate_content_stream(
+    model=model_name, contents=full_content, config=session_config
+)
+```
+
+This approach differs significantly from manual tool calling:
+
+- **Automatic execution**: The Gemini SDK determines when tools are needed and calls them automatically
+- **Session reuse**: Active MCP sessions are passed directly to the SDK
+- **Transparent integration**: Tool results are seamlessly integrated into the response stream
+- **No manual parsing**: No need to parse tool calls or manage execution manually
+
+### Relationship with MultiMCPClient
+
+The Gemini backend relies heavily on the `MultiMCPClient` from `mcp_tools.client`:
+
+- **Connection management**: Handles multiple MCP server connections simultaneously
+- **Session provision**: Provides active sessions that can be used by the Gemini SDK
+- **Tool filtering**: Applies allowed/excluded tool filters at the client level
+- **Health monitoring**: Tracks connection status and provides server information
+
+## Specific mcp_tools Utilities Used
+
+### Used Utilities from backend_utils.py
+
+The Gemini backend leverages several utilities from the `mcp_tools.backend_utils` module:
+
+#### MCPSetupManager
+- **Purpose**: Server configuration normalization and validation
+- **Usage**: `normalize_mcp_servers()` method converts various server config formats
+- **Implementation**: Validates required fields and ensures consistent structure
+
+#### MCPExecutionManager
+- **Purpose**: Function execution with retry logic (used in fallback scenarios)
+- **Usage**: `execute_function_with_retry()` for manual tool calling when sessions fail
+- **Features**: Exponential backoff, circuit breaker integration, statistics tracking
+
+#### MCPErrorHandler
+- **Purpose**: Standardized error handling and classification
+- **Usage**: `get_error_details()`, `is_transient_error()`, `log_error()` methods
+- **Benefits**: Consistent error messaging and retry decision logic
+
+#### MCPCircuitBreakerManager
+- **Purpose**: Circuit breaker operations for fault tolerance
+- **Usage**: Server filtering, success/failure recording, event management
+- **Methods**: `apply_circuit_breaker_filtering()`, `record_success()`, `record_failure()`
+
+#### MCPMessageManager
+- **Purpose**: Message history management
+- **Usage**: `trim_message_history()` to prevent unbounded memory growth
+- **Implementation**: Preserves system messages while limiting total message count
+
+#### MCPConfigHelper
+- **Purpose**: Configuration validation and circuit breaker setup
+- **Usage**: `build_circuit_breaker_config()` for creating circuit breaker configurations
+- **Features**: Transport-type-specific configurations, validation support
+
+### Used Exceptions from exceptions.py
+
+The Gemini backend imports and handles all MCP exception types:
+
+- **MCPError**: Base exception for all MCP-related errors
+- **MCPConnectionError**: Connection establishment failures
+- **MCPTimeoutError**: Operation timeout errors
+- **MCPServerError**: Server-side errors and failures
+- **MCPValidationError**: Configuration and input validation errors
+- **MCPAuthenticationError**: Authentication and authorization failures
+- **MCPResourceError**: Resource availability and access errors
+
+
+### Circuit Breaker Integration
+
+The circuit breaker integration provides fault tolerance:
+
+```python
+# Initialization
+from ..mcp_tools.circuit_breaker import MCPCircuitBreaker
+mcp_tools_config = MCPConfigHelper.build_circuit_breaker_config("mcp_tools")
+self._mcp_tools_circuit_breaker = MCPCircuitBreaker(mcp_tools_config)
+
+# Usage
+filtered_servers = self._apply_mcp_tools_circuit_breaker_filtering(servers)
+await self._record_mcp_tools_success(connected_servers)
+await self._record_mcp_tools_failure(failed_servers, error_message)
+```
+
+## Configuration Flow
+
+### mcp_servers Parameter Handling
+
+The configuration flow begins with the `mcp_servers` parameter in the constructor:
+
+1. **Extraction**: Retrieved from kwargs during backend initialization
+2. **Storage**: Stored as instance variable for later use
+3. **Validation**: Passed through `MCPConfigValidator` if available
+4. **Normalization**: Converted to standardized format using `MCPSetupManager`
+
+### Configuration Validation Using MCPConfigValidator
+
+```python
+if MCPConfigValidator is not None:
+    validator = MCPConfigValidator()
+    validated_config = validator.validate_backend_mcp_config({
+        "mcp_servers": self.mcp_servers,
+        "allowed_tools": self.allowed_tools,
+        "exclude_tools": self.exclude_tools
+    })
+```
+
+The validation process:
+- **Schema validation**: Ensures required fields are present
+- **Type checking**: Validates data types and formats
+- **Security validation**: Checks security configurations
+- **Tool filtering validation**: Validates allowed/excluded tool lists
+
+### Server Normalization and Filtering
+
+Server configurations undergo multiple processing steps:
+
+1. **Normalization**: Convert various formats (dict, list) to standardized list of dictionaries
+2. **Required field validation**: Ensure 'type' and 'name' fields are present
+3. **Circuit breaker filtering**: Remove servers that are currently failing
+4. **Transport type separation**: Separate stdio/streamable-http from http servers
+
+### Tool Filtering with allowed_tools and exclude_tools
+
+Tool filtering is applied at multiple levels:
+
+- **Configuration level**: Specified in YAML configuration
+- **Validation level**: Validated by `MCPConfigValidator`
+- **Client level**: Applied when creating `MultiMCPClient`
+- **Session level**: Enforced when sessions are created
+
+## Session-Based vs Manual Tool Calling
+
+### Session-Based Approach
+
+The Gemini backend's session-based approach offers several advantages:
+
+**Automatic Tool Selection**:
+```python
+# Sessions are passed to SDK, which handles tool calling automatically
+session_config["tools"] = mcp_sessions
+stream = await client.aio.models.generate_content_stream(
+    model=model_name, contents=full_content, config=session_config
+)
+```
+
+**Benefits**:
+- No manual tool call parsing required
+- SDK determines optimal tool usage timing
+- Seamless integration of tool results into response
+- Reduced complexity in backend implementation
+
+### Automatic Tool Calling
+
+The Gemini SDK handles tool calling automatically:
+
+1. **Context analysis**: SDK analyzes conversation context to determine tool needs
+2. **Tool selection**: Chooses appropriate tools from available sessions
+3. **Execution**: Calls tools and integrates results
+4. **Response generation**: Incorporates tool results into final response
+
+### Fallback Mechanisms
+
+When MCP sessions fail, the system gracefully falls back:
+
+```python
+except (MCPConnectionError, MCPTimeoutError, MCPServerError, MCPError) as e:
+    # Emit user-friendly error message
+    async for chunk in self._handle_mcp_error_and_fallback(e):
+        yield chunk
+    
+    # Fallback to non-MCP streaming
+    manual_config = dict(config)
+    if all_tools:
+        manual_config["tools"] = all_tools
+```
+
+**Fallback sequence**:
+1. MCP session failure detected
+2. User notification via stream chunks
+3. Fallback to builtin tools (search, code execution)
+4. Continue with standard Gemini capabilities
+
+
+## Error Handling and Resilience
+
+### Circuit Breaker Implementation
+
+The circuit breaker prevents cascading failures:
+
+```python
+class MCPCircuitBreaker:
+    def should_skip_server(self, server_name: str) -> bool:
+        # Check if server should be skipped due to failures
+    
+    def record_success(self, server_name: str) -> None:
+        # Record successful operation
+    
+    def record_failure(self, server_name: str) -> None:
+        # Record failure and potentially open circuit
+```
+
+**Circuit breaker states**:
+- **Closed**: Normal operation, all servers available
+- **Open**: Server temporarily disabled due to failures
+- **Half-open**: Testing server recovery
+
+### Retry Logic
+
+Exponential backoff with jitter is implemented for connection attempts:
+
+```python
+for retry_count in range(1, max_mcp_retries + 1):
+    try:
+        # Connection attempt
+        await asyncio.sleep(0.5 * retry_count)  # Progressive backoff
+        self._mcp_client = await MultiMCPClient.create_and_connect(...)
+        break
+    except Exception as e:
+        # Handle retry logic
+```
+
+**Retry characteristics**:
+- Maximum 5 retry attempts
+- Progressive backoff (0.5s, 1.0s, 1.5s, 2.0s, 2.5s)
+- Circuit breaker integration
+- User feedback on retry attempts
+
+### Error Classification
+
+Different MCP error types receive different handling:
+
+- **MCPConnectionError**: Retryable, circuit breaker tracked
+- **MCPTimeoutError**: Retryable, may indicate server load
+- **MCPServerError**: Conditionally retryable based on error message keywords
+- **MCPAuthenticationError**: Non-retryable, immediate failure
+- **MCPValidationError**: Non-retryable, configuration issue
+
+### Graceful Degradation
+
+The system degrades gracefully when MCP tools fail:
+
+1. **Error detection**: Specific error types are identified
+2. **User notification**: Clear error messages via stream chunks
+3. **Fallback activation**: Switch to builtin tools or basic capabilities
+4. **Continued operation**: System remains functional without MCP tools
+
+### User Feedback
+
+Error communication through stream chunks provides real-time feedback:
+
+```python
+yield StreamChunk(
+    type="content",
+    content=f"\n⚠️  {user_message} ({error}); continuing without MCP tools\n",
+)
+```
+
+**Feedback characteristics**:
+- Real-time error notifications
+- User-friendly error messages
+- Clear indication of fallback behavior
+- No interruption of conversation flow
+
+## Tool Execution Flow
+
+### MCP Client Connection
+
+The connection process involves multiple steps:
+
+1. **Configuration validation**: Validate server configurations
+2. **Server normalization**: Convert to standard format
+3. **Circuit breaker filtering**: Remove failing servers
+4. **Connection establishment**: Create MultiMCPClient connections
+5. **Session retrieval**: Get active sessions for SDK use
+
+### Session Management
+
+Active sessions are managed through the MultiMCPClient:
+
+```python
+mcp_sessions = self._mcp_client.get_active_sessions()
+if not mcp_sessions:
+    raise RuntimeError("No active MCP sessions available")
+```
+
+**Session characteristics**:
+- Represent active MCP server connections
+- Contain tool definitions and capabilities
+- Can be passed directly to Gemini SDK
+- Automatically handle tool execution
+
+### Streaming Integration
+
+MCP tool results are integrated into the response stream:
+
+```python
+async for chunk in stream:
+    if hasattr(chunk, "text") and chunk.text:
+        chunk_text = chunk.text
+        full_content_text += chunk_text
+        yield StreamChunk(type="content", content=chunk_text)
+```
+
+**Integration features**:
+- Real-time streaming of tool results
+- Seamless integration with model responses
+- Automatic tool usage indicators
+- Comprehensive logging of tool activities
+
+### Tool Call Tracking
+
+Comprehensive monitoring tracks tool usage:
+
+```python
+# Track MCP tool usage attempt
+self._mcp_tool_calls_count += 1
+log_tool_call(agent_id, "mcp_session_tools", {
+    "session_count": len(mcp_sessions),
+    "call_number": self._mcp_tool_calls_count
+})
+```
+
+**Tracking metrics**:
+- Total tool calls attempted
+- Successful tool executions
+- Failed tool attempts
+- Connection retry counts
+
+### Success/Failure Recording
+
+Circuit breaker events are recorded for each operation:
+
+```python
+# Record success for connected servers
+await self._record_mcp_tools_success(connected_servers)
+
+# Record failure for circuit breaker
+await self._record_mcp_tools_failure(failed_servers, error_message)
+```
+
+## Resource Management
+
+### Connection Lifecycle
+
+MCP connections follow a structured lifecycle:
+
+**Setup in `__aenter__`**:
+```python
+async def __aenter__(self) -> "GeminiBackend":
+    await self._setup_mcp_tools(agent_id=self.agent_id)
+    return self
+```
+
+**Cleanup in `__aexit__`**:
+```python
+async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+    await self.cleanup_mcp()
+```
+
+### Client Cleanup
+
+Proper disconnection is handled in the `cleanup_mcp()` method:
+
+```python
+async def cleanup_mcp(self):
+    if self._mcp_client:
+        try:
+            await self._mcp_client.disconnect()
+            log_backend_activity("gemini", "MCP client disconnected", {})
+        except Exception as e:
+            self._mcp_error_details(e, "disconnect", log=True)
+        finally:
+            self._mcp_client = None
+            self._mcp_initialized = False
+```
+
+### Resource Tracking
+
+Connection state and tool usage are continuously monitored:
+
+- **Connection status**: Tracked through `_mcp_initialized` flag
+- **Active sessions**: Monitored via `MultiMCPClient.get_active_sessions()`
+- **Tool usage**: Counters for calls, successes, and failures
+- **Circuit breaker state**: Per-server failure tracking
+
+### Memory Management
+
+MCPMessageManager.trim_message_history() is called via gemini backend's _trim_message_history() wrapper method.
+
+Message history is trimmed to prevent unbounded growth:
+
+```python
+def _trim_message_history(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    max_items = getattr(self, '_max_mcp_message_history', 200)
+    return MCPMessageManager.trim_message_history(messages, max_items)
+```
+
+**Memory management features**:
+- Configurable message history limits
+- Preservation of system messages
+- Automatic trimming during execution
+- Prevention of memory leaks
+
+## Integration Points with MassGen Framework
+
+### Agent Configuration
+
+MCP configuration flows from YAML to backend:
+
+```yaml
+agents:
+  - id: "gemini_mcp_agent"
+    backend:
+      type: "gemini"
+      model: "gemini-2.5-flash"
+      mcp_servers:
+        - name: "weather"
+          type: "stdio"
+          command: "npx"
+          args: ["-y", "@fak111/weather-mcp"]
+```
+
+**Configuration flow**:
+1. YAML parsing by MassGen orchestrator
+2. Backend instantiation with mcp_servers parameter
+3. Configuration validation and normalization
+4. MCP client setup and connection
+
+### Logging Integration
+
+Comprehensive logging integrates with MassGen's logging system:
+
+```python
+log_backend_activity("gemini", "MCP sessions initialized", {}, agent_id=agent_id)
+log_tool_call(agent_id, "mcp_session_tools", tool_data, backend_name="gemini")
+log_stream_chunk("backend.gemini", "content", chunk_text, agent_id)
+```
+
+**Logging categories**:
+- Backend activity logging
+- Tool call logging
+- Stream chunk logging
+- Error and warning logging
+
+### UI Streaming
+
+MCP tool results are streamed to the display layer:
+
+```python
+yield StreamChunk(type="content", content="🔧 [MCP Tools] Session-based tools used\n")
+yield StreamChunk(type="tool_calls", tool_calls=tool_calls_detected)
+yield StreamChunk(type="complete_message", complete_message=complete_message)
+```
+
+**Streaming features**:
+- Real-time tool usage indicators
+- Tool call result streaming
+- Error message streaming
+- Complete message assembly
+
+### Orchestrator Coordination
+
+The orchestrator manages backend lifecycle:
+
+- **Initialization**: Backend creation with MCP configuration
+- **Context management**: Async context manager entry/exit
+- **Resource cleanup**: Automatic cleanup on completion
+- **Error handling**: Orchestrator-level error management
+
+## Performance and Monitoring
+
+### Tool Usage Tracking
+
+Comprehensive metrics track MCP tool performance:
+
+```python
+# Tool usage counters
+self._mcp_tool_calls_count = 0
+self._mcp_tool_failures = 0
+self._mcp_tool_successes = 0
+self._mcp_connection_retries = 0
+```
+
+**Tracked metrics**:
+- Total tool calls attempted
+- Successful tool executions
+- Failed tool attempts
+- Connection retry attempts
+
+### Connection Retry Tracking
+
+Connection attempts are monitored and logged:
+
+```python
+for retry_count in range(1, max_mcp_retries + 1):
+    self._mcp_connection_retries = retry_count
+    log_backend_activity("gemini", "MCP connection retry", {
+        "attempt": retry_count,
+        "max_retries": max_mcp_retries
+    })
+```
+
+### Cost Calculation
+
+MCP tool usage affects cost estimates:
+
+```python
+def calculate_cost(self, input_tokens: int, output_tokens: int, model: str) -> float:
+    # Base model costs
+    input_cost = (input_tokens / 1_000_000) * rate
+    output_cost = (output_tokens / 1_000_000) * rate
+    
+    # Tool usage costs (estimates)
+    tool_costs = 0.0
+    if self.search_count > 0:
+        tool_costs += self.search_count * 0.01
+    
+    return input_cost + output_cost + tool_costs
+```
+
+### Circuit Breaker Metrics
+
+Circuit breaker state provides failure tracking:
+
+- **Failure counts**: Per-server failure tracking
+- **Recovery timing**: Circuit breaker reset times
+- **Success rates**: Success/failure ratios
+- **Server availability**: Current server status
+
+## Configuration Examples
+
+### Single Server Setup (gemini_mcp_example.yaml)
+
+```yaml
+agents:
+  - id: "gemini2.5flash_mcp_weather"
+    backend:
+      type: "gemini"
+      model: "gemini-2.5-flash"
+      mcp_servers:
+        - name: "weather"
+          type: "stdio"
+          command: "npx"
+          args: ["-y", "@fak111/weather-mcp"]
+```
+
+**Configuration breakdown**:
+- **Single server**: One MCP server for weather information
+- **stdio transport**: Uses standard input/output for communication
+- **NPM package**: Weather MCP server from npm registry
+- **Simple setup**: Minimal configuration for basic MCP integration
+
+### Multi-Server Configuration (multimcp_gemini.yaml)
+
+```yaml
+mcp_servers:
+  - name: "airbnb_search"
+    type: "stdio"
+    command: "npx"
+    args: ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]
+    security:
+      level: "moderate"
+  - name: "brave_search"
+    type: "stdio"
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-brave-search"]
+    env:
+      BRAVE_API_KEY: "${BRAVE_API_KEY}"
+    security:
+      level: "moderate"
+```
+
+**Configuration features**:
+- **Multiple servers**: Airbnb search and Brave search integration
+- **Environment variables**: Secure API key handling
+- **Security levels**: Moderate security configuration
+- **Complex workflows**: Support for multi-tool research tasks
+
+### Environment Variable Handling
+
+Environment variables are securely managed:
+
+```yaml
+env:
+  BRAVE_API_KEY: "${BRAVE_API_KEY}"
+```
+
+**Security features**:
+- **Variable substitution**: Runtime environment variable resolution
+- **Secure storage**: API keys stored in environment, not configuration
+- **Validation**: Environment variable presence validation
+- **Error handling**: Clear errors for missing required variables
+
+### Security Configuration
+
+Security levels provide different protection levels:
+
+```yaml
+security:
+  level: "moderate"
+```
+
+**Security levels**:
+- **strict**: Maximum security, limited tool access
+- **moderate**: Balanced security and functionality
+- **permissive**: Minimal restrictions, maximum functionality