cade-cli 0.3.3__py3-none-any.whl

cadecoder/tools/manager.py

@@ -0,0 +1,1635 @@
+"""Unified tool management system supporting local, remote, and MCP tools."""
+
+import asyncio
+import inspect
+import json
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from enum import Enum
+from pathlib import Path
+from typing import Annotated, Any, get_args, get_origin
+
+import httpx
+from arcadepy import AsyncArcade
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from cadecoder.core.config import get_config
+from cadecoder.core.logging import log
+
+# Type aliases
+JsonToolSchema = dict[str, Any]
+
+# Console for output
+console = Console(stderr=True)
+
+
+# =============================================================================
+# MCP Server Configuration
+# =============================================================================
+
+
+class MCPAuthType(str, Enum):
+    """Authentication types for MCP servers."""
+
+    NONE = "none"
+    BEARER = "bearer"  # Static bearer token
+    API_KEY = "api_key"  # Static API key
+    OAUTH = "oauth"  # Full OAuth 2.1 flow (MCP spec compliant)
+
+
+@dataclass
+class MCPOAuthTokens:
+    """OAuth tokens for an MCP server."""
+
+    access_token: str
+    token_type: str = "Bearer"
+    refresh_token: str | None = None
+    expires_at: datetime | None = None
+    scope: str | None = None
+
+    def is_expired(self) -> bool:
+        """Check if access token is expired."""
+        if self.expires_at is None:
+            return False
+        return datetime.now() >= self.expires_at
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "access_token": self.access_token,
+            "token_type": self.token_type,
+            "refresh_token": self.refresh_token,
+            "expires_at": self.expires_at.isoformat() if self.expires_at else None,
+            "scope": self.scope,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MCPOAuthTokens":
+        """Create from dictionary."""
+        expires_at = None
+        if data.get("expires_at"):
+            expires_at = datetime.fromisoformat(data["expires_at"])
+        return cls(
+            access_token=data["access_token"],
+            token_type=data.get("token_type", "Bearer"),
+            refresh_token=data.get("refresh_token"),
+            expires_at=expires_at,
+            scope=data.get("scope"),
+        )
+
+
+@dataclass
+class MCPServerConfig:
+    """Configuration for an MCP server connection."""
+
+    name: str
+    url: str
+    auth_type: MCPAuthType = MCPAuthType.NONE
+    auth_value: str | None = None  # For bearer/api_key
+    enabled: bool = True
+    last_connected: datetime | None = None
+    tool_count: int = 0
+    # OAuth-specific fields
+    oauth_tokens: MCPOAuthTokens | None = None
+    oauth_authorization_server: str | None = None
+    oauth_client_id: str | None = None
+    oauth_scopes: list[str] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "name": self.name,
+            "url": self.url,
+            "auth_type": self.auth_type.value,
+            "auth_value": self.auth_value,
+            "enabled": self.enabled,
+            "last_connected": (self.last_connected.isoformat() if self.last_connected else None),
+            "tool_count": self.tool_count,
+            "oauth_tokens": self.oauth_tokens.to_dict() if self.oauth_tokens else None,
+            "oauth_authorization_server": self.oauth_authorization_server,
+            "oauth_client_id": self.oauth_client_id,
+            "oauth_scopes": self.oauth_scopes,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MCPServerConfig":
+        """Create from dictionary."""
+        last_connected = None
+        if data.get("last_connected"):
+            last_connected = datetime.fromisoformat(data["last_connected"])
+
+        oauth_tokens = None
+        if data.get("oauth_tokens"):
+            oauth_tokens = MCPOAuthTokens.from_dict(data["oauth_tokens"])
+
+        return cls(
+            name=data["name"],
+            url=data["url"],
+            auth_type=MCPAuthType(data.get("auth_type", "none")),
+            auth_value=data.get("auth_value"),
+            enabled=data.get("enabled", True),
+            last_connected=last_connected,
+            tool_count=data.get("tool_count", 0),
+            oauth_tokens=oauth_tokens,
+            oauth_authorization_server=data.get("oauth_authorization_server"),
+            oauth_client_id=data.get("oauth_client_id"),
+            oauth_scopes=data.get("oauth_scopes"),
+        )
+
+
+class MCPServerStore:
+    """Persistent storage for MCP server configurations."""
+
+    def __init__(self, config_dir: Path | None = None) -> None:
+        if config_dir is None:
+            config_dir = Path(get_config().app_dir)
+        self.config_dir = config_dir
+        self.config_file = config_dir / "mcp_servers.json"
+        self._servers: dict[str, MCPServerConfig] = {}
+        self._load()
+
+    def _load(self) -> None:
+        """Load servers from disk."""
+        if not self.config_file.exists():
+            return
+
+        try:
+            with open(self.config_file, encoding="utf-8") as f:
+                data = json.load(f)
+
+            for server_data in data.get("servers", []):
+                server = MCPServerConfig.from_dict(server_data)
+                self._servers[server.name] = server
+
+            log.debug(f"Loaded {len(self._servers)} MCP server configs")
+        except Exception as e:
+            log.warning(f"Failed to load MCP server configs: {e}")
+
+    def _save(self) -> None:
+        """Save servers to disk."""
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+
+        try:
+            data = {
+                "servers": [s.to_dict() for s in self._servers.values()],
+                "updated_at": datetime.now().isoformat(),
+            }
+            with open(self.config_file, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+        except Exception as e:
+            log.warning(f"Failed to save MCP server configs: {e}")
+
+    def add(self, server: MCPServerConfig) -> None:
+        """Add or update a server configuration."""
+        self._servers[server.name] = server
+        self._save()
+
+    def remove(self, name: str) -> bool:
+        """Remove a server configuration."""
+        if name in self._servers:
+            del self._servers[name]
+            self._save()
+            return True
+        return False
+
+    def get(self, name: str) -> MCPServerConfig | None:
+        """Get a server configuration by name."""
+        return self._servers.get(name)
+
+    def list_all(self) -> list[MCPServerConfig]:
+        """List all server configurations."""
+        return list(self._servers.values())
+
+    def list_enabled(self) -> list[MCPServerConfig]:
+        """List enabled server configurations."""
+        return [s for s in self._servers.values() if s.enabled]
+
+    def update_status(self, name: str, connected: bool, tool_count: int = 0) -> None:
+        """Update server connection status."""
+        if name in self._servers:
+            if connected:
+                self._servers[name].last_connected = datetime.now()
+                self._servers[name].tool_count = tool_count
+            self._save()
+
+
+class ToolAuthorizationRequired(Exception):
+    """Exception raised when a tool requires user authorization."""
+
+    def __init__(self, tool_name: str, authorization_url: str | None = None):
+        self.tool_name = tool_name
+        self.authorization_url = authorization_url
+
+        if authorization_url:
+            message = (
+                f"Authorization required for '{tool_name}'.\n\n"
+                f"Please authorize by clicking this link:\n{authorization_url}\n\n"
+                f"After authorizing, let me know and I'll retry the operation."
+            )
+        else:
+            message = (
+                f"Authorization required for '{tool_name}'.\n\n"
+                f"Please authorize this tool in your Arcade account."
+            )
+
+        super().__init__(message)
+
+
+class ToolManager(ABC):
+    """Base interface for tool management."""
+
+    @abstractmethod
+    async def get_tools(self) -> list[dict[str, Any]]:
+        """Get all available tools as jsonschemas."""
+        pass
+
+    @abstractmethod
+    async def execute(self, name: str, inputs: dict[str, Any]) -> Any:
+        """Execute a tool by name with inputs."""
+        pass
+
+
+# =============================================================================
+# MCP OAuth 2.1 Support (RFC 9728, RFC 8414)
+# =============================================================================
+
+
+class MCPOAuthHandler:
+    """Handles OAuth 2.1 authorization for MCP servers per MCP spec."""
+
+    def __init__(self, server_config: MCPServerConfig) -> None:
+        self.config = server_config
+        self._client: httpx.AsyncClient | None = None
+
+    async def _ensure_client(self) -> httpx.AsyncClient:
+        """Ensure HTTP client exists."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=httpx.Timeout(30.0))
+        return self._client
+
+    def parse_www_authenticate(self, header: str) -> dict[str, str]:
+        """Parse WWW-Authenticate header to extract OAuth parameters.
+
+        Per MCP spec, extracts: resource_metadata, scope, error, error_description
+        """
+        params: dict[str, str] = {}
+        # Remove "Bearer " prefix if present
+        if header.lower().startswith("bearer "):
+            header = header[7:]
+
+        # Parse key="value" pairs
+        import re
+
+        pattern = r'(\w+)="([^"]*)"'
+        for match in re.finditer(pattern, header):
+            params[match.group(1)] = match.group(2)
+
+        return params
+
+    async def discover_from_401(self, response: httpx.Response) -> tuple[str | None, str | None]:
+        """Discover authorization server from 401 response.
+
+        Returns: (resource_metadata_url, required_scope)
+        """
+        www_auth = response.headers.get("WWW-Authenticate", "")
+        params = self.parse_www_authenticate(www_auth)
+
+        resource_metadata_url = params.get("resource_metadata")
+        scope = params.get("scope")
+
+        return resource_metadata_url, scope
+
+    async def fetch_protected_resource_metadata(
+        self, metadata_url: str | None = None
+    ) -> dict[str, Any] | None:
+        """Fetch Protected Resource Metadata per RFC 9728.
+
+        Tries:
+        1. Provided metadata_url (from WWW-Authenticate)
+        2. Well-known URI with path: /.well-known/oauth-protected-resource/<path>
+        3. Well-known URI at root: /.well-known/oauth-protected-resource
+        """
+        client = await self._ensure_client()
+        from urllib.parse import urlparse
+
+        parsed = urlparse(self.config.url)
+        base = f"{parsed.scheme}://{parsed.netloc}"
+
+        urls_to_try = []
+        if metadata_url:
+            urls_to_try.append(metadata_url)
+
+        # Well-known with path
+        if parsed.path and parsed.path != "/":
+            path = parsed.path.rstrip("/")
+            urls_to_try.append(f"{base}/.well-known/oauth-protected-resource{path}")
+
+        # Well-known at root
+        urls_to_try.append(f"{base}/.well-known/oauth-protected-resource")
+
+        for url in urls_to_try:
+            try:
+                resp = await client.get(url)
+                if resp.status_code == 200:
+                    return resp.json()
+            except Exception:
+                continue
+
+        return None
+
+    async def fetch_authorization_server_metadata(self, issuer: str) -> dict[str, Any] | None:
+        """Fetch Authorization Server Metadata per RFC 8414.
+
+        Tries both OAuth 2.0 and OpenID Connect discovery endpoints.
+        """
+        client = await self._ensure_client()
+        from urllib.parse import urlparse
+
+        parsed = urlparse(issuer)
+        base = f"{parsed.scheme}://{parsed.netloc}"
+        path = parsed.path.rstrip("/") if parsed.path else ""
+
+        # Priority order per MCP spec
+        urls_to_try = []
+        if path:
+            # With path component
+            urls_to_try.extend(
+                [
+                    f"{base}/.well-known/oauth-authorization-server{path}",
+                    f"{base}/.well-known/openid-configuration{path}",
+                    f"{base}{path}/.well-known/openid-configuration",
+                ]
+            )
+        else:
+            # Without path
+            urls_to_try.extend(
+                [
+                    f"{base}/.well-known/oauth-authorization-server",
+                    f"{base}/.well-known/openid-configuration",
+                ]
+            )
+
+        for url in urls_to_try:
+            try:
+                resp = await client.get(url)
+                if resp.status_code == 200:
+                    metadata = resp.json()
+                    # Verify PKCE support (required by MCP spec)
+                    if "code_challenge_methods_supported" not in metadata:
+                        log.warning(f"Auth server {url} doesn't advertise PKCE support")
+                    return metadata
+            except Exception:
+                continue
+
+        return None
+
+    def generate_pkce(self) -> tuple[str, str]:
+        """Generate PKCE code_verifier and code_challenge (S256)."""
+        import base64
+        import hashlib
+        import secrets
+
+        # Generate code_verifier (43-128 chars)
+        code_verifier = secrets.token_urlsafe(32)
+
+        # Generate code_challenge using S256
+        digest = hashlib.sha256(code_verifier.encode()).digest()
+        code_challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+
+        return code_verifier, code_challenge
+
+    async def start_oauth_flow(
+        self,
+        auth_server_metadata: dict[str, Any],
+        scope: str | None = None,
+        client_id: str | None = None,
+    ) -> tuple[str, str, str]:
+        """Start OAuth authorization flow.
+
+        Returns: (authorization_url, code_verifier, state)
+        """
+        import secrets
+        from urllib.parse import urlencode
+
+        auth_endpoint = auth_server_metadata.get("authorization_endpoint")
+        if not auth_endpoint:
+            raise Exception("No authorization_endpoint in auth server metadata")
+
+        code_verifier, code_challenge = self.generate_pkce()
+        state = secrets.token_urlsafe(16)
+
+        # Use client_id or generate one
+        if not client_id:
+            client_id = self.config.oauth_client_id or f"cade-mcp-{self.config.name}"
+
+        # Determine scope
+        if not scope:
+            scope = " ".join(self.config.oauth_scopes or [])
+            if not scope:
+                # Use scopes_supported from metadata
+                supported = auth_server_metadata.get("scopes_supported", [])
+                scope = " ".join(supported) if supported else ""
+
+        params = {
+            "response_type": "code",
+            "client_id": client_id,
+            "redirect_uri": "http://127.0.0.1:9876/callback",
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+            "state": state,
+            "resource": self.config.url,  # RFC 8707 resource indicator
+        }
+        if scope:
+            params["scope"] = scope
+
+        auth_url = f"{auth_endpoint}?{urlencode(params)}"
+        return auth_url, code_verifier, state
+
+    async def exchange_code_for_tokens(
+        self,
+        auth_server_metadata: dict[str, Any],
+        code: str,
+        code_verifier: str,
+        client_id: str | None = None,
+    ) -> MCPOAuthTokens:
+        """Exchange authorization code for tokens."""
+        client = await self._ensure_client()
+
+        token_endpoint = auth_server_metadata.get("token_endpoint")
+        if not token_endpoint:
+            raise Exception("No token_endpoint in auth server metadata")
+
+        if not client_id:
+            client_id = self.config.oauth_client_id or f"cade-mcp-{self.config.name}"
+
+        data = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": "http://127.0.0.1:9876/callback",
+            "client_id": client_id,
+            "code_verifier": code_verifier,
+            "resource": self.config.url,
+        }
+
+        resp = await client.post(
+            token_endpoint,
+            data=data,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+
+        if resp.status_code != 200:
+            raise Exception(f"Token exchange failed: {resp.text}")
+
+        token_data = resp.json()
+        expires_at = None
+        if "expires_in" in token_data:
+            expires_at = datetime.now() + timedelta(seconds=token_data["expires_in"])
+
+        return MCPOAuthTokens(
+            access_token=token_data["access_token"],
+            token_type=token_data.get("token_type", "Bearer"),
+            refresh_token=token_data.get("refresh_token"),
+            expires_at=expires_at,
+            scope=token_data.get("scope"),
+        )
+
+    async def refresh_tokens(
+        self,
+        auth_server_metadata: dict[str, Any],
+        refresh_token: str,
+        client_id: str | None = None,
+    ) -> MCPOAuthTokens:
+        """Refresh access token using refresh token."""
+        client = await self._ensure_client()
+
+        token_endpoint = auth_server_metadata.get("token_endpoint")
+        if not token_endpoint:
+            raise Exception("No token_endpoint in auth server metadata")
+
+        if not client_id:
+            client_id = self.config.oauth_client_id or f"cade-mcp-{self.config.name}"
+
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": client_id,
+            "resource": self.config.url,
+        }
+
+        resp = await client.post(
+            token_endpoint,
+            data=data,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+
+        if resp.status_code != 200:
+            raise Exception(f"Token refresh failed: {resp.text}")
+
+        token_data = resp.json()
+        expires_at = None
+        if "expires_in" in token_data:
+            expires_at = datetime.now() + timedelta(seconds=token_data["expires_in"])
+
+        return MCPOAuthTokens(
+            access_token=token_data["access_token"],
+            token_type=token_data.get("token_type", "Bearer"),
+            refresh_token=token_data.get("refresh_token", refresh_token),
+            expires_at=expires_at,
+            scope=token_data.get("scope"),
+        )
+
+    async def close(self) -> None:
+        """Close HTTP client."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+
+# =============================================================================
+# MCP Tool Manager (HTTP Streamable JSON-RPC)
+# =============================================================================
+
+
+class MCPToolManager(ToolManager):
+    """Manages tools from MCP servers over HTTP (JSON-RPC streamable transport)."""
+
+    def __init__(
+        self,
+        server_config: MCPServerConfig,
+        server_store: "MCPServerStore | None" = None,
+    ) -> None:
+        self.config = server_config
+        self._server_store = server_store
+        self._tools_cache: list[dict[str, Any]] | None = None
+        self._initialized = False
+        self._client: httpx.AsyncClient | None = None
+        self._session_id: str | None = None
+        self._oauth_handler = MCPOAuthHandler(server_config)
+        self._auth_server_metadata: dict[str, Any] | None = None
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get HTTP headers including authentication and session ID."""
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        }
+
+        # Include MCP session ID if we have one (required for HTTP transport)
+        if self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+
+        # Handle different auth types
+        if self.config.auth_type == MCPAuthType.BEARER and self.config.auth_value:
+            headers["Authorization"] = f"Bearer {self.config.auth_value}"
+        elif self.config.auth_type == MCPAuthType.API_KEY and self.config.auth_value:
+            headers["X-API-Key"] = self.config.auth_value
+        elif self.config.auth_type == MCPAuthType.OAUTH and self.config.oauth_tokens:
+            # Use OAuth token
+            token = self.config.oauth_tokens
+            headers["Authorization"] = f"{token.token_type} {token.access_token}"
+
+        return headers
+
+    async def _ensure_client(self) -> httpx.AsyncClient:
+        """Ensure HTTP client is created with current auth headers."""
+        # Only recreate if no client exists or if we need to refresh tokens
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                timeout=httpx.Timeout(60.0, connect=10.0),
+            )
+        return self._client
+
+    async def _maybe_refresh_oauth_token(self) -> bool:
+        """Refresh OAuth token if expired. Returns True if refreshed."""
+        if self.config.auth_type != MCPAuthType.OAUTH:
+            return False
+
+        tokens = self.config.oauth_tokens
+        if not tokens or not tokens.is_expired():
+            return False
+
+        if not tokens.refresh_token:
+            return False
+
+        if not self._auth_server_metadata:
+            # Try to fetch it
+            rs_meta = await self._oauth_handler.fetch_protected_resource_metadata()
+            if rs_meta:
+                auth_servers = rs_meta.get("authorization_servers", [])
+                if auth_servers:
+                    self._auth_server_metadata = (
+                        await self._oauth_handler.fetch_authorization_server_metadata(
+                            auth_servers[0]
+                        )
+                    )
+
+        if not self._auth_server_metadata:
+            return False
+
+        try:
+            new_tokens = await self._oauth_handler.refresh_tokens(
+                self._auth_server_metadata,
+                tokens.refresh_token,
+                self.config.oauth_client_id,
+            )
+            self.config.oauth_tokens = new_tokens
+
+            # Persist updated tokens
+            if self._server_store:
+                self._server_store.add(self.config)
+
+            log.info(f"Refreshed OAuth token for MCP server '{self.config.name}'")
+            return True
+        except Exception as e:
+            log.warning(f"Failed to refresh OAuth token: {e}")
+            return False
+
+    async def _handle_401_response(self, response: httpx.Response) -> str | None:
+        """Handle 401 response per MCP OAuth spec.
+
+        Returns authorization URL if OAuth flow should be initiated.
+        """
+        # Parse WWW-Authenticate header
+        metadata_url, scope = await self._oauth_handler.discover_from_401(response)
+
+        # Fetch Protected Resource Metadata
+        rs_metadata = await self._oauth_handler.fetch_protected_resource_metadata(metadata_url)
+        if not rs_metadata:
+            return None
+
+        # Get authorization server
+        auth_servers = rs_metadata.get("authorization_servers", [])
+        if not auth_servers:
+            return None
+
+        # Fetch Authorization Server Metadata
+        as_metadata = await self._oauth_handler.fetch_authorization_server_metadata(auth_servers[0])
+        if not as_metadata:
+            return None
+
+        self._auth_server_metadata = as_metadata
+        self.config.oauth_authorization_server = auth_servers[0]
+
+        # Generate authorization URL
+        auth_url, code_verifier, state = await self._oauth_handler.start_oauth_flow(
+            as_metadata, scope, self.config.oauth_client_id
+        )
+
+        # Store PKCE verifier for later token exchange (temporary)
+        self._pending_code_verifier = code_verifier
+        self._pending_state = state
+
+        return auth_url
+
+    async def _send_notification(self, method: str) -> None:
+        """Send a JSON-RPC notification (no response expected).
+
+        Per MCP spec, notifications don't have an 'id' and don't expect a response.
+        Used for 'notifications/initialized' and similar methods.
+        """
+        client = await self._ensure_client()
+
+        # Notifications don't have an 'id' field
+        payload: dict[str, Any] = {
+            "jsonrpc": "2.0",
+            "method": method,
+        }
+
+        headers = self._get_headers()
+        try:
+            response = await client.post(self.config.url, json=payload, headers=headers)
+            # We don't expect a meaningful response for notifications
+            # Some servers return 202 Accepted, others return 200
+            if response.status_code not in (200, 202, 204):
+                log.warning(
+                    f"MCP notification '{method}' got unexpected status: {response.status_code}"
+                )
+        except Exception as e:
+            log.warning(f"MCP notification '{method}' failed: {e}")
+
+    async def _send_request(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        """Send a JSON-RPC request to the MCP server.
+
+        Handles MCP HTTP transport session management by capturing and including
+        the Mcp-Session-Id header across requests.
+        """
+        # Refresh token if needed
+        await self._maybe_refresh_oauth_token()
+
+        client = await self._ensure_client()
+
+        request_id = str(uuid.uuid4())
+        payload: dict[str, Any] = {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "method": method,
+        }
+        if params:
+            payload["params"] = params
+
+        try:
+            # Include current headers (with session ID if available)
+            headers = self._get_headers()
+            response = await client.post(self.config.url, json=payload, headers=headers)
+
+            # Capture session ID from response for subsequent requests
+            # Per MCP HTTP transport spec, server sends Mcp-Session-Id header
+            if "mcp-session-id" in response.headers:
+                self._session_id = response.headers["mcp-session-id"]
+                log.debug(
+                    f"Captured MCP session ID for '{self.config.name}': {self._session_id[:8]}..."
+                )
+
+            # Handle 401 - OAuth discovery
+            if response.status_code == 401:
+                auth_url = await self._handle_401_response(response)
+                raise ToolAuthorizationRequired(
+                    f"MCP:{self.config.name}",
+                    authorization_url=auth_url,
+                )
+
+            # Handle 403 - Insufficient scope
+            if response.status_code == 403:
+                www_auth = response.headers.get("WWW-Authenticate", "")
+                auth_params = self._oauth_handler.parse_www_authenticate(www_auth)
+                if auth_params.get("error") == "insufficient_scope":
+                    raise ToolAuthorizationRequired(
+                        f"MCP:{self.config.name}",
+                        authorization_url=None,
+                    )
+
+            response.raise_for_status()
+
+            # Handle SSE or direct JSON response
+            content_type = response.headers.get("content-type", "")
+
+            if "text/event-stream" in content_type:
+                # Parse SSE response
+                return await self._parse_sse_response(response, request_id)
+            else:
+                # Direct JSON response
+                result = response.json()
+                if "error" in result:
+                    raise Exception(f"MCP error: {result['error'].get('message', 'Unknown error')}")
+                return result.get("result")
+
+        except httpx.HTTPStatusError as e:
+            raise Exception(f"MCP HTTP error: {e}")
+        except ToolAuthorizationRequired:
+            raise
+        except Exception as e:
+            log.error(f"MCP request failed for {self.config.name}: {e}")
+            raise
+
+    async def _parse_sse_response(self, response: httpx.Response, request_id: str) -> Any:
+        """Parse Server-Sent Events response."""
+        result = None
+        async for line in response.aiter_lines():
+            if line.startswith("data: "):
+                data = line[6:]
+                if data.strip():
+                    try:
+                        event = json.loads(data)
+                        if event.get("id") == request_id:
+                            if "error" in event:
+                                raise Exception(f"MCP error: {event['error'].get('message')}")
+                            result = event.get("result")
+                    except json.JSONDecodeError:
+                        continue
+        return result
+
+    async def initialize(self) -> bool:
+        """Initialize connection to MCP server.
+
+        Follows MCP protocol:
+        1. Send 'initialize' request
+        2. Receive server capabilities
+        3. Send 'notifications/initialized' notification
+        """
+        if self._initialized:
+            return True
+
+        try:
+            result = await self._send_request(
+                "initialize",
+                {
+                    "protocolVersion": "2024-11-05",
+                    "capabilities": {"tools": {}},
+                    "clientInfo": {"name": "cade", "version": "1.0.0"},
+                },
+            )
+
+            if result:
+                self._initialized = True
+                # Send initialized notification (no response expected)
+                await self._send_notification("notifications/initialized")
+                log.info(f"MCP server '{self.config.name}' initialized")
+                return True
+
+            return False
+
+        except Exception as e:
+            log.error(f"Failed to initialize MCP server '{self.config.name}': {e}")
+            return False
+
+    async def get_tools(self) -> list[dict[str, Any]]:
+        """Get available tools from the MCP server."""
+        if self._tools_cache is not None:
+            return self._tools_cache
+
+        if not self._initialized:
+            success = await self.initialize()
+            if not success:
+                return []
+
+        try:
+            result = await self._send_request("tools/list")
+
+            if not result or "tools" not in result:
+                return []
+
+            # Convert MCP tool format to OpenAI function format
+            self._tools_cache = []
+            for mcp_tool in result["tools"]:
+                openai_tool = self._convert_mcp_to_openai(mcp_tool)
+                self._tools_cache.append(openai_tool)
+
+            log.info(f"Loaded {len(self._tools_cache)} tools from MCP server '{self.config.name}'")
+            return self._tools_cache
+
+        except Exception as e:
+            log.error(f"Failed to list tools from MCP '{self.config.name}': {e}")
+            return []
+
+    def _convert_mcp_to_openai(self, mcp_tool: dict[str, Any]) -> dict[str, Any]:
+        """Convert MCP tool schema to OpenAI function schema.
+
+        Uses the original tool name from the MCP server without modification.
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": mcp_tool["name"],
+                "description": mcp_tool.get("description", ""),
+                "parameters": mcp_tool.get("inputSchema", {"type": "object", "properties": {}}),
+            },
+        }
+
+    async def execute(self, name: str, inputs: dict[str, Any]) -> Any:
+        """Execute a tool on the MCP server."""
+        if not self._initialized:
+            success = await self.initialize()
+            if not success:
+                raise Exception(f"MCP server '{self.config.name}' not initialized")
+
+        try:
+            result = await self._send_request(
+                "tools/call",
+                {"name": name, "arguments": inputs},
+            )
+
+            if result and "content" in result:
+                # Extract text content from MCP response
+                content_items = result["content"]
+                text_parts = []
+                for item in content_items:
+                    if item.get("type") == "text":
+                        text_parts.append(item.get("text", ""))
+                return "\n".join(text_parts) if text_parts else result
+
+            return result
+
+        except Exception as e:
+            log.error(f"MCP tool execution failed for '{name}': {e}")
+            raise Exception(f"Failed to execute MCP tool '{name}': {e}")
+
+    async def check_status(self) -> tuple[bool, str]:
+        """Check if MCP server is reachable and properly initialize the session.
+
+        This performs a full initialization so the session is ready for tool listing.
+        Calling get_tools() after a successful check_status() will work correctly.
+        """
+        try:
+            # Reset state for fresh check
+            self._initialized = False
+            self._session_id = None
+
+            # Use the proper initialize flow
+            success = await self.initialize()
+            if success:
+                return True, "Connected"
+            else:
+                return False, "Initialization failed"
+
+        except httpx.ConnectError:
+            return False, "Connection failed"
+        except ToolAuthorizationRequired:
+            return False, "Authentication required"
+        except Exception as e:
+            return False, str(e)[:50]
+
+    async def complete_oauth_flow(self, authorization_code: str) -> bool:
+        """Complete OAuth flow by exchanging authorization code for tokens.
+
+        Call this after user has authorized and callback received the code.
+        """
+        if not self._auth_server_metadata:
+            log.error("No auth server metadata - cannot complete OAuth flow")
+            return False
+
+        if not hasattr(self, "_pending_code_verifier"):
+            log.error("No pending PKCE verifier - OAuth flow not started")
+            return False
+
+        try:
+            tokens = await self._oauth_handler.exchange_code_for_tokens(
+                self._auth_server_metadata,
+                authorization_code,
+                self._pending_code_verifier,
+                self.config.oauth_client_id,
+            )
+
+            # Update config with tokens
+            self.config.auth_type = MCPAuthType.OAUTH
+            self.config.oauth_tokens = tokens
+
+            # Persist
+            if self._server_store:
+                self._server_store.add(self.config)
+
+            # Clean up pending state
+            del self._pending_code_verifier
+            if hasattr(self, "_pending_state"):
+                del self._pending_state
+
+            # Reset client to use new tokens
+            if self._client:
+                await self._client.aclose()
+                self._client = None
+
+            log.info(f"OAuth flow completed for MCP server '{self.config.name}'")
+            return True
+
+        except Exception as e:
+            log.error(f"Failed to complete OAuth flow: {e}")
+            return False
+
+    async def close(self) -> None:
+        """Close the HTTP client and reset session state."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+        self._session_id = None
+        self._initialized = False
+        await self._oauth_handler.close()
+
+
+class CacheEntry:
+    """Cache entry for tool schemas with expiration."""
+
+    def __init__(self, tool_name: str, tool_schema: dict[str, Any], last_updated: datetime) -> None:
+        self.tool_name = tool_name
+        self.tool_schema = tool_schema
+        self.last_updated = last_updated
+
+    def is_expired(self, max_age: timedelta) -> bool:
+        """Check if cache entry has expired."""
+        return datetime.now() - self.last_updated > max_age
+
+    def update(self, tool_schema: dict[str, Any]) -> None:
+        self.tool_schema = tool_schema
+        self.last_updated = datetime.now()
+
+
+class ToolCache:
+    """Cache for tool schemas with TTL support and persistent storage."""
+
+    def __init__(
+        self,
+        max_age: timedelta = timedelta(hours=24),
+        cache_dir: Path | None = None,
+    ) -> None:
+        self._tools_cache: dict[str, CacheEntry] = {}
+        self.max_age = max_age
+
+        if cache_dir is None:
+            app_dir = Path(get_config().app_dir)
+            cache_dir = app_dir / "tool_cache"
+        self.cache_dir = cache_dir
+        self.cache_file = self.cache_dir / "remote_tools.json"
+
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self._load_from_disk()
+
+    def _load_from_disk(self) -> None:
+        """Load cached tools from disk."""
+        if not self.cache_file.exists():
+            return
+
+        try:
+            with open(self.cache_file, encoding="utf-8") as f:
+                data = json.load(f)
+
+            for tool_name, entry_data in data.get("tools", {}).items():
+                last_updated = datetime.fromisoformat(entry_data["last_updated"])
+                tool_schema = entry_data["tool_schema"]
+                entry = CacheEntry(tool_name, tool_schema, last_updated)
+                if not entry.is_expired(self.max_age):
+                    self._tools_cache[tool_name] = entry
+
+            log.debug(f"Loaded {len(self._tools_cache)} tools from persistent cache")
+        except Exception as e:
+            log.warning(f"Failed to load tool cache from disk: {e}")
+
+    def _save_to_disk(self) -> None:
+        """Save cached tools to disk."""
+        try:
+            data = {
+                "tools": {
+                    tool_name: {
+                        "tool_schema": entry.tool_schema,
+                        "last_updated": entry.last_updated.isoformat(),
+                    }
+                    for tool_name, entry in self._tools_cache.items()
+                },
+                "updated_at": datetime.now().isoformat(),
+            }
+
+            with open(self.cache_file, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+        except Exception as e:
+            log.warning(f"Failed to save tool cache to disk: {e}")
+
+    def get_tools(
+        self, tools: list[str] | None = None, toolkits: list[str] | None = None
+    ) -> list[dict[str, Any]]:
+        """Get cached tools filtered by names or toolkits."""
+        if tools:
+            return [
+                entry.tool_schema
+                for entry in self._tools_cache.values()
+                if entry.tool_name in tools and not entry.is_expired(self.max_age)
+            ]
+        if toolkits:
+            # Filter by toolkit prefix
+            toolkit_lower = {t.lower() for t in toolkits}
+            return [
+                entry.tool_schema
+                for entry in self._tools_cache.values()
+                if not entry.is_expired(self.max_age)
+                and any(
+                    entry.tool_name.lower().startswith(f"{tk}_")
+                    or entry.tool_name.lower().startswith(f"{tk}.")
+                    for tk in toolkit_lower
+                )
+            ]
+        return [
+            entry.tool_schema
+            for entry in self._tools_cache.values()
+            if not entry.is_expired(self.max_age)
+        ]
+
+    def update_tools(self, tool_name: str, tool_schema: dict[str, Any], save: bool = False):
+        """Update or add a tool to the cache."""
+        self._tools_cache[tool_name] = CacheEntry(tool_name, tool_schema, datetime.now())
+        if save:
+            self._save_to_disk()
+
+    def save(self):
+        """Save all cached tools to disk."""
+        self._save_to_disk()
+
+    def has_valid_cache(self) -> bool:
+        """Check if cache has any valid (non-expired) entries."""
+        return any(not entry.is_expired(self.max_age) for entry in self._tools_cache.values())
+
+
+class LocalToolManager(ToolManager):
+    """Manages local tool execution."""
+
+    def __init__(self) -> None:
+        self._tools_cache: list[JsonToolSchema] | None = None
+        self._tool_funcs: dict[str, Any] = {}
+        self._interactive_tools: set[str] = set()
+
+    async def get_tools(self) -> list[dict[str, Any]]:
+        """Get all available local tools as jsonschemas."""
+        if self._tools_cache is None:
+            from cadecoder.tools.builtin import get_all_tools
+
+            tools = get_all_tools()
+            self._tools_cache = []
+
+            for tool in tools:
+                tool_name = getattr(tool, "__tool_name__", getattr(tool, "__name__", "unknown"))
+
+                # Cache the function for execution
+                self._tool_funcs[tool_name] = tool
+
+                schema = {
+                    "type": "function",
+                    "function": {
+                        "name": tool_name,
+                        "description": getattr(tool, "__tool_description__", ""),
+                    },
+                }
+
+                if getattr(tool, "__interactive__", False):
+                    self._interactive_tools.add(tool_name)
+
+                # Build parameters schema from function signature
+                sig = inspect.signature(tool)
+                parameters = {"type": "object", "properties": {}, "required": []}
+
+                for param_name, param in sig.parameters.items():
+                    if param_name == "context":
+                        continue
+
+                    param_type = "string"
+                    param_desc = f"Parameter {param_name}"
+
+                    if param.annotation != inspect.Parameter.empty:
+                        if get_origin(param.annotation) is Annotated:
+                            args = get_args(param.annotation)
+                            if len(args) >= 2:
+                                actual_type = args[0]
+                                param_desc = args[1]
+
+                                if actual_type is str:
+                                    param_type = "string"
+                                elif actual_type is int:
+                                    param_type = "integer"
+                                elif actual_type is float:
+                                    param_type = "number"
+                                elif actual_type is bool:
+                                    param_type = "boolean"
+                                elif actual_type is list or get_origin(actual_type) is list:
+                                    param_type = "array"
+                                elif actual_type is dict:
+                                    param_type = "object"
+
+                    parameters["properties"][param_name] = {
+                        "type": param_type,
+                        "description": param_desc,
+                    }
+
+                    if param.default == inspect.Parameter.empty:
+                        parameters["required"].append(param_name)
+
+                if parameters["properties"]:
+                    schema["function"]["parameters"] = parameters
+
+                self._tools_cache.append(schema)
+
+        return self._tools_cache
+
+    async def execute(self, name: str, inputs: dict[str, Any]) -> Any:
+        """Execute a local tool by name with inputs."""
+        # Ensure tools are loaded
+        await self.get_tools()
+
+        tool_func = self._tool_funcs.get(name)
+        if not tool_func:
+            raise Exception(f"Tool '{name}' not found")
+
+        # Create minimal context
+        from arcade_tdk import ToolContext
+
+        context = ToolContext(user_id="local_user")  # type: ignore[call-arg]
+
+        # Execute (handle async and sync)
+        if inspect.iscoroutinefunction(tool_func):
+            result = await tool_func(context, **inputs)
+        else:
+            result = tool_func(context, **inputs)
+
+        return result
+
+    def is_interactive_tool(self, name: str) -> bool:
+        """Check if the named tool requires exclusive terminal access."""
+        return name in self._interactive_tools
+
+
+def _extract_toolkit_names_from_tools(tool_names: list[str]) -> set[str]:
+    """Extract toolkit names from tool names."""
+    toolkits = set()
+    for tool_name in tool_names:
+        if "_" in tool_name:
+            toolkit = tool_name.split("_")[0].lower()
+            toolkits.add(toolkit)
+        elif "." in tool_name:
+            toolkit = tool_name.split(".")[0].lower()
+            toolkits.add(toolkit)
+    return toolkits
+
+
+class RemoteToolManager(ToolManager):
+    """Manages remote Arcade tool execution using arcadepy."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        user_email: str | None = None,
+    ):
+        log.info(f"Initializing RemoteToolManager with user_email: {user_email}")
+        cfg = get_config()
+        self.arcade_client = AsyncArcade(
+            api_key=api_key or cfg.api_key,
+            base_url=base_url or cfg.base_url,
+        )
+        self._default_user_id = user_email or cfg.user_email
+        self._tools_cache = ToolCache()
+        self._all_tools_fetched = False
+        self._fetching_lock = False
+
+    async def get_tools(
+        self, tools: list[str] | None = None, toolkits: list[str] | None = None
+    ) -> list[dict[str, Any]]:
+        """Get available tools from Arcade Cloud."""
+        try:
+            toolkit_names_from_tools = set()
+            if tools:
+                toolkit_names_from_tools = _extract_toolkit_names_from_tools(tools)
+
+            all_toolkit_names = set()
+            if toolkits:
+                all_toolkit_names.update(t.lower() for t in toolkits)
+            all_toolkit_names.update(toolkit_names_from_tools)
+
+            (list(all_toolkit_names) if all_toolkit_names else (toolkits or []))
+
+            if self._all_tools_fetched or self._tools_cache.has_valid_cache():
+                cached_tools = self._filter_tools_from_cache(tools, toolkits)
+                if cached_tools:
+                    log.debug(f"Using {len(cached_tools)} cached tools")
+                    return cached_tools
+
+            if self._fetching_lock:
+                await asyncio.sleep(0.1)
+                return await self.get_tools(tools, toolkits)
+
+            self._fetching_lock = True
+
+            try:
+                with console.status("[cyan]Updating tools...", spinner="dots"):
+                    log.info("Fetching remote tools from Arcade API")
+
+                    all_items: list[dict[str, Any]] = []
+                    offset = 0
+                    limit = 100
+                    total_fetched = 0
+
+                    while True:
+                        tools_response = await self.arcade_client.tools.formatted.list(
+                            limit=limit,
+                            offset=offset,
+                            format="openai",
+                            user_id=self._default_user_id,
+                        )
+
+                        items = getattr(tools_response, "items", [])
+                        if not items:
+                            break
+
+                        all_items.extend(items)
+                        total_fetched += len(items)
+
+                        total_count = getattr(tools_response, "total_count", 0)
+                        if total_fetched >= total_count or len(items) < limit:
+                            break
+
+                        offset += limit
+
+                    log.info(f"Fetched {total_fetched} total tools from Arcade API")
+
+                    for tool in all_items:
+                        tool_name = self._extract_tool_name(tool)
+                        if tool_name:
+                            self._tools_cache.update_tools(tool_name, tool, save=False)
+
+                    self._tools_cache.save()
+                    self._all_tools_fetched = True
+
+            finally:
+                self._fetching_lock = False
+
+            return self._filter_tools_from_cache(tools, toolkits)
+
+        except Exception as e:
+            log.error(f"Failed to fetch remote tools: {e}", exc_info=True)
+            return []
+
+    def _extract_tool_name(self, tool: dict[str, Any]) -> str | None:
+        """Extract tool name from tool schema."""
+        if isinstance(tool, dict):
+            return tool.get("function", {}).get("name", "")
+        return None
+
+    def _filter_tools_from_cache(
+        self, tools: list[str] | None = None, toolkits: list[str] | None = None
+    ) -> list[dict[str, Any]]:
+        """Filter tools from cache based on tool names and toolkits."""
+        all_cached = self._tools_cache.get_tools()
+
+        if not all_cached:
+            return []
+
+        if not tools and not toolkits:
+            return all_cached
+
+        filtered_tools: list[dict[str, Any]] = []
+        toolkit_lower = [t.lower() for t in (toolkits or [])]
+        tool_names_set = set(tools or [])
+
+        for tool in all_cached:
+            tool_name = self._extract_tool_name(tool)
+            if not tool_name:
+                continue
+
+            tool_name_lower = tool_name.lower()
+
+            if tool_names_set and tool_name in tool_names_set:
+                filtered_tools.append(tool)
+                continue
+
+            if toolkit_lower:
+                if any(
+                    tool_name_lower.startswith(f"{tk}_") or tool_name_lower.startswith(f"{tk}.")
+                    for tk in toolkit_lower
+                ):
+                    filtered_tools.append(tool)
+
+        return filtered_tools
+
+    async def execute(
+        self,
+        name: str,
+        inputs: dict[str, Any],
+        user_id: str | None = None,
+        timeout: float = 120.0,
+    ) -> Any:
+        """Execute a remote tool via Arcade Cloud."""
+        try:
+            result = await asyncio.wait_for(
+                self.arcade_client.tools.execute(
+                    tool_name=name,
+                    input=inputs,
+                    user_id=user_id or self._default_user_id,
+                ),
+                timeout=timeout,
+            )
+
+            if result.output and result.output.authorization:
+                auth_response = result.output.authorization
+                if auth_response.status in ("not_started", "pending"):
+                    await self._handle_authorization_and_retry(name, inputs, user_id, auth_response)
+                    result = await asyncio.wait_for(
+                        self.arcade_client.tools.execute(
+                            tool_name=name,
+                            input=inputs,
+                            user_id=user_id or self._default_user_id,
+                        ),
+                        timeout=timeout,
+                    )
+
+            if result.output and result.output.error:
+                error = result.output.error
+                raise Exception(f"Tool execution failed: {error.message}")
+
+            return result.output.value if result.output else result
+
+        except Exception as e:
+            error_str = str(e)
+
+            if "403" in error_str and "authorization required" in error_str.lower():
+                try:
+                    auth_response = await self.arcade_client.tools.authorize(
+                        tool_name=name,
+                        user_id=user_id or self._default_user_id,
+                    )
+
+                    await self._handle_authorization_and_retry(name, inputs, user_id, auth_response)
+
+                    result = await self.arcade_client.tools.execute(
+                        tool_name=name,
+                        input=inputs,
+                        user_id=user_id or self._default_user_id,
+                    )
+
+                    if result.output and result.output.error:
+                        error = result.output.error
+                        raise Exception(f"Tool execution failed: {error.message}")
+
+                    return result.output.value if result.output else result
+
+                except Exception as retry_error:
+                    log.error(f"Failed to authorize and retry tool '{name}': {retry_error}")
+                    raise
+
+            log.error(f"Remote tool execution error for '{name}': {e}")
+            raise Exception(f"Failed to execute remote tool '{name}': {str(e)}")
+
+    async def _handle_authorization_and_retry(
+        self,
+        tool_name: str,
+        inputs: dict[str, Any],
+        user_id: str | None,
+        auth_response: Any,
+    ) -> None:
+        """Handle authorization flow."""
+        if auth_response.url:
+            content = Text()
+            content.append(f"Authorization required for '{tool_name}'.\n\n", style="bold yellow")
+            content.append("Click this link to authorize:\n", style="white")
+            content.append(auth_response.url, style="bold cyan underline")
+            content.append("\n\nWaiting for authorization to complete...", style="white dim")
+
+            panel = Panel(
+                content,
+                title="[bold yellow]⚠ Authorization Required[/bold yellow]",
+                title_align="left",
+                border_style="yellow",
+                padding=(0, 1),
+                width=110,
+            )
+            console.print(panel)
+
+            log.info(f"Waiting for authorization to complete for tool '{tool_name}'...")
+            completed_auth = await self.arcade_client.auth.wait_for_completion(auth_response)
+
+            if completed_auth.status == "completed":
+                console.print(f"[green]✓[/green] Authorization completed for '{tool_name}'")
+                log.info(f"Authorization completed for tool '{tool_name}'")
+            else:
+                raise Exception(
+                    f"Authorization failed for '{tool_name}': status={completed_auth.status}"
+                )
+        else:
+            raise Exception(f"Authorization required for '{tool_name}' but no URL provided")
+
+
+class CompositeToolManager(ToolManager):
+    """Manages local, remote (Arcade), and MCP tools simultaneously."""
+
+    def __init__(
+        self,
+        local_manager: LocalToolManager | None = None,
+        remote_manager: RemoteToolManager | None = None,
+        enable_mcp: bool = True,
+    ):
+        self.local_manager = local_manager or LocalToolManager()
+        self.remote_manager = remote_manager or RemoteToolManager(
+            user_email=get_config().user_email,
+        )
+        self._tool_source_map: dict[str, str] = {}
+        self._mcp_tool_to_manager: dict[str, MCPToolManager] = {}
+        self._tools_cache = ToolCache()
+        self._mcp_managers: list[MCPToolManager] = []
+        self._enable_mcp = enable_mcp
+
+        tool_cfg = get_config().tool_settings
+        self._default_remote_tool: list[str] = tool_cfg.included_tools.copy()
+        self._default_remote_toolkit: list[str] = tool_cfg.included_toolkits.copy()
+
+        # Load MCP servers if enabled
+        if enable_mcp:
+            self._mcp_store = MCPServerStore()
+            for server_config in self._mcp_store.list_enabled():
+                mcp_manager = MCPToolManager(server_config)
+                self._mcp_managers.append(mcp_manager)
+
+    async def get_tools(self) -> list[dict[str, Any]]:
+        """Get all available tools from local, remote, and MCP sources."""
+        all_tools = []
+
+        # Local tools
+        try:
+            local_tools = await self.local_manager.get_tools()
+            for tool in local_tools:
+                tool_name = tool.get("function", {}).get("name", "unknown")
+                self._tool_source_map[tool_name] = "local"
+                all_tools.append(tool)
+            log.info(f"Loaded {len(local_tools)} local tools")
+        except Exception as e:
+            log.error(f"Failed to load local tools: {e}")
+
+        # Remote (Arcade) tools
+        if self.remote_manager:
+            try:
+                remote_tools = await self.remote_manager.get_tools(
+                    tools=self._default_remote_tool,
+                    toolkits=self._default_remote_toolkit,
+                )
+                for tool in remote_tools:
+                    self._tools_cache.update_tools(
+                        tool.get("function", {}).get("name", "unknown"), tool
+                    )
+
+                for tool in remote_tools:
+                    tool_name = tool.get("function", {}).get("name", "unknown")
+                    desc = tool["function"].get("description", "")
+                    tool["function"]["description"] = f"[Arcade Cloud] {desc}"
+                    self._tool_source_map[tool_name] = "remote"
+                    all_tools.append(tool)
+                log.info(f"Loaded {len(remote_tools)} remote tools from Arcade Cloud")
+            except Exception as e:
+                log.error(f"Failed to load remote tools: {e}")
+
+        # MCP tools
+        mcp_tool_count = 0
+        for mcp_manager in self._mcp_managers:
+            try:
+                mcp_tools = await mcp_manager.get_tools()
+                for tool in mcp_tools:
+                    tool_name = tool.get("function", {}).get("name", "unknown")
+                    self._tool_source_map[tool_name] = "mcp"
+                    self._mcp_tool_to_manager[tool_name] = mcp_manager
+                    all_tools.append(tool)
+                mcp_tool_count += len(mcp_tools)
+
+                # Update server status
+                if self._enable_mcp and hasattr(self, "_mcp_store"):
+                    self._mcp_store.update_status(mcp_manager.config.name, True, len(mcp_tools))
+            except Exception as e:
+                log.error(f"Failed to load tools from MCP '{mcp_manager.config.name}': {e}")
+
+        if mcp_tool_count > 0:
+            log.info(f"Loaded {mcp_tool_count} tools from MCP servers")
+
+        # Summary
+        sources = list(self._tool_source_map.values())
+        local_count = sources.count("local")
+        remote_count = sources.count("remote")
+        mcp_count = sources.count("mcp")
+        log.info(
+            f"Total tools: {len(all_tools)} "
+            f"(Local: {local_count}, Arcade: {remote_count}, MCP: {mcp_count})"
+        )
+        return all_tools
+
+    async def execute(self, name: str, inputs: dict[str, Any]) -> Any:
+        """Execute a tool by routing to the appropriate manager."""
+        source = self._tool_source_map.get(name)
+
+        if source == "local":
+            log.debug(f"Executing local tool: {name}")
+            return await self.local_manager.execute(name, inputs)
+        elif source == "remote" and self.remote_manager:
+            log.debug(f"Executing remote tool: {name}")
+            return await self.remote_manager.execute(name, inputs, user_id=get_config().user_email)
+        elif source == "mcp":
+            mcp_manager = self._mcp_tool_to_manager.get(name)
+            if mcp_manager:
+                log.debug(f"Executing MCP tool: {name}")
+                return await mcp_manager.execute(name, inputs)
+            raise Exception(f"MCP manager not found for tool '{name}'")
+        else:
+            raise Exception(f"Tool '{name}' not found in local, remote, or MCP tools")
+
+    def is_interactive_tool(self, name: str) -> bool:
+        """Determine whether a tool is interactive based on its source."""
+        source = self._tool_source_map.get(name)
+        if source == "local" and hasattr(self.local_manager, "is_interactive_tool"):
+            return bool(self.local_manager.is_interactive_tool(name))
+        return False
+
+    def get_tool_source(self, name: str) -> str | None:
+        """Get the source type for a tool."""
+        return self._tool_source_map.get(name)
+
+    def get_all_tool_info(self) -> list[dict[str, Any]]:
+        """Get info about all tools including their source."""
+        tool_info = []
+        for name, source in self._tool_source_map.items():
+            info = {"name": name, "source": source}
+            if source == "mcp" and name in self._mcp_tool_to_manager:
+                info["server"] = self._mcp_tool_to_manager[name].config.name
+            tool_info.append(info)
+        return tool_info
+
+    async def close(self) -> None:
+        """Close all MCP connections."""
+        for mcp_manager in self._mcp_managers:
+            await mcp_manager.close()
+
+
+__all__ = [
+    "ToolManager",
+    "LocalToolManager",
+    "RemoteToolManager",
+    "MCPToolManager",
+    "MCPOAuthHandler",
+    "CompositeToolManager",
+    "ToolCache",
+    "CacheEntry",
+    "ToolAuthorizationRequired",
+    "MCPServerConfig",
+    "MCPServerStore",
+    "MCPAuthType",
+    "MCPOAuthTokens",
+]