chuk-tool-processor 0.7.0__py3-none-any.whl → 0.10__py3-none-any.whl

chuk_tool_processor/logging/__init__.py

@@ -19,14 +19,11 @@ import sys
 
 
 # Auto-initialize shutdown error suppression when logging package is imported
-def _initialize_shutdown_fixes():
+def _initialize_shutdown_fixes() -> None:
     """Initialize shutdown error suppression when the package is imported."""
-    try:
-        from .context import _setup_shutdown_error_suppression
-
-        _setup_shutdown_error_suppression()
-    except ImportError:
-        pass
+    # Note: _setup_shutdown_error_suppression removed as it's no longer needed
+    # Keeping this function as a no-op for backward compatibility
+    pass
 
 
 # Initialize when package is imported
@@ -64,7 +61,7 @@ __all__ = [
 async def setup_logging(
     level: int = logging.INFO,
     structured: bool = True,
-    log_file: str = None,
+    log_file: str | None = None,
 ) -> None:
     """
     Set up the logging system.

chuk_tool_processor/logging/context.py

@@ -77,11 +77,8 @@ class LibraryLoggingManager:
         self._initialized = False
         self._lock = threading.Lock()
 
-    def initialize(self):
+    def initialize(self) -> None:
         """Initialize clean shutdown behavior for the library."""
-        if self._initialized:
-            return
-
         with self._lock:
             if self._initialized:
                 return
@@ -299,7 +296,7 @@ class StructuredAdapter(logging.LoggerAdapter):
         return msg, kwargs
 
     # ----------------------- convenience wrappers ------------------------ #
-    def _forward(self, method_name: str, msg, *args, **kwargs):
+    def _forward(self, method_name: str, msg: str, *args: Any, **kwargs: Any) -> None:
         """Common helper: process + forward to `self.logger.<method_name>`."""
         msg, kwargs = self.process(msg, kwargs)
         getattr(self.logger, method_name)(msg, *args, **kwargs)

chuk_tool_processor/mcp/__init__.py

@@ -9,6 +9,7 @@ Updated to support the latest MCP transports:
 """
 
 from chuk_tool_processor.mcp.mcp_tool import MCPTool
+from chuk_tool_processor.mcp.models import MCPServerConfig, MCPTransport
 from chuk_tool_processor.mcp.register_mcp_tools import register_mcp_tools
 from chuk_tool_processor.mcp.setup_mcp_http_streamable import setup_mcp_http_streamable
 from chuk_tool_processor.mcp.setup_mcp_sse import setup_mcp_sse
@@ -23,6 +24,8 @@ __all__ = [
     "HTTPStreamableTransport",
     "StreamManager",
     "MCPTool",
+    "MCPServerConfig",
+    "MCPTransport",
     "register_mcp_tools",
     "setup_mcp_stdio",
     "setup_mcp_sse",

chuk_tool_processor/mcp/mcp_tool.py

@@ -237,7 +237,12 @@ class MCPTool:
                 await self._record_failure()
 
                 if attempt == max_attempts - 1:
-                    return {"error": error_msg, "tool_name": self.tool_name, "available": False, "reason": "timeout"}
+                    return {
+                        "error": error_msg,
+                        "tool_name": self.tool_name,
+                        "available": False,
+                        "reason": "timeout",
+                    }
 
             except Exception as e:
                 error_str = str(e)
@@ -260,12 +265,12 @@ class MCPTool:
                     await asyncio.sleep(backoff)
                     backoff = min(backoff * self.recovery_config.backoff_multiplier, self.recovery_config.max_backoff)
 
-        # Should never reach here
+        # Should never reach here, but return error if we do
         return {
             "error": f"Tool '{self.tool_name}' failed after all attempts",
             "tool_name": self.tool_name,
             "available": False,
-            "reason": "exhausted_retries",
+            "reason": "execution_failed",
         }
 
     async def _execute_with_timeout(self, timeout: float, **kwargs: Any) -> Any:

chuk_tool_processor/mcp/models.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python
+# chuk_tool_processor/mcp/models.py
+"""
+Pydantic models for MCP server configurations.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class MCPTransport(str, Enum):
+    """Supported MCP transport types."""
+
+    STDIO = "stdio"
+    SSE = "sse"
+    HTTP = "http"
+
+
+class MCPServerConfig(BaseModel):
+    """Unified configuration for MCP servers (all transport types)."""
+
+    name: str = Field(description="Server identifier name")
+    transport: MCPTransport = Field(default=MCPTransport.STDIO, description="Transport protocol")
+
+    # STDIO fields
+    command: str | None = Field(default=None, description="Command to execute (stdio only)")
+    args: list[str] = Field(default_factory=list, description="Command arguments (stdio only)")
+    env: dict[str, str] | None = Field(default=None, description="Environment variables (stdio only)")
+
+    # SSE/HTTP fields
+    url: str | None = Field(default=None, description="Server URL (sse/http)")
+    headers: dict[str, str] = Field(default_factory=dict, description="HTTP headers (sse/http)")
+    timeout: float = Field(default=10.0, description="Connection timeout in seconds")
+    sse_read_timeout: float = Field(default=300.0, description="SSE read timeout in seconds (sse only)")
+    api_key: str | None = Field(default=None, description="API key extracted from Authorization header")
+    session_id: str | None = Field(default=None, description="Session ID for HTTP transport")
+
+    @model_validator(mode="after")
+    def validate_transport_fields(self) -> MCPServerConfig:
+        """Validate required fields based on transport type."""
+        if self.transport == MCPTransport.STDIO:
+            if not self.command:
+                raise ValueError("command is required for stdio transport")
+        else:
+            # SSE/HTTP
+            if not self.url:
+                raise ValueError(f"url is required for {self.transport} transport")
+            # Extract API key from Authorization header if present
+            if not self.api_key and self.headers:
+                auth_header = self.headers.get("Authorization", "")
+                if "Bearer " in auth_header:
+                    self.api_key = auth_header.split("Bearer ")[-1]
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for internal use."""
+        if self.transport == MCPTransport.STDIO:
+            result = {
+                "name": self.name,
+                "command": self.command,
+                "args": self.args,
+            }
+            if self.env:
+                result["env"] = self.env
+            return result
+        else:
+            # SSE/HTTP
+            result = {
+                "name": self.name,
+                "url": self.url,
+                "headers": self.headers,
+                "timeout": self.timeout,
+            }
+            if self.transport == MCPTransport.SSE:
+                result["sse_read_timeout"] = self.sse_read_timeout
+            if self.api_key:
+                result["api_key"] = self.api_key
+            if self.session_id:
+                result["session_id"] = self.session_id
+            return result
+
+
+__all__ = ["MCPServerConfig", "MCPTransport"]

chuk_tool_processor/mcp/setup_mcp_http_streamable.py

@@ -41,8 +41,8 @@ async def setup_mcp_http_streamable(
     enable_rate_limiting: bool = False,
     global_rate_limit: int | None = None,
     tool_rate_limits: dict[str, tuple] | None = None,
-    enable_retries: bool = False,  # CHANGED: Disabled to allow OAuth refresh to work properly
-    max_retries: int = 0,  # CHANGED: 0 retries for HTTP (OAuth refresh happens at transport level)
+    enable_retries: bool = True,  # CHANGED: Enabled with OAuth errors excluded
+    max_retries: int = 2,  # Retry non-OAuth errors (OAuth handled at transport level)
     namespace: str = "http",
     oauth_refresh_callback: any | None = None,  # NEW: OAuth token refresh callback
 ) -> tuple[ToolProcessor, StreamManager]:
@@ -102,6 +102,41 @@ async def setup_mcp_http_streamable(
     registered = await register_mcp_tools(stream_manager, namespace=namespace)
 
     # 3️⃣  build a processor instance configured to your taste
+    # IMPORTANT: Retries are enabled but OAuth errors are excluded
+    # OAuth refresh happens at transport level with automatic retry
+
+    # Import RetryConfig to configure OAuth error exclusion
+    from chuk_tool_processor.execution.wrappers.retry import RetryConfig
+
+    # Define OAuth error patterns that should NOT be retried at this level
+    # These will be handled by the transport layer's OAuth refresh mechanism
+    # Based on RFC 6750 (Bearer Token Usage) and MCP OAuth spec
+    oauth_error_patterns = [
+        # RFC 6750 Section 3.1 - Standard Bearer token errors
+        "invalid_token",  # Token expired, revoked, malformed, or invalid
+        "insufficient_scope",  # Request requires higher privileges (403 Forbidden)
+        # OAuth 2.1 token refresh errors
+        "invalid_grant",  # Refresh token errors
+        # MCP spec - OAuth validation failures (401 Unauthorized)
+        "oauth validation",
+        "unauthorized",
+        # Common OAuth error descriptions
+        "expired token",
+        "token expired",
+        "authentication failed",
+        "invalid access token",
+    ]
+
+    # Create retry config that skips OAuth errors
+    retry_config = (
+        RetryConfig(
+            max_retries=max_retries,
+            skip_retry_on_error_substrings=oauth_error_patterns,
+        )
+        if enable_retries
+        else None
+    )
+
     processor = ToolProcessor(
         default_timeout=default_timeout,
         max_concurrency=max_concurrency,
@@ -112,6 +147,7 @@ async def setup_mcp_http_streamable(
         tool_rate_limits=tool_rate_limits,
         enable_retries=enable_retries,
         max_retries=max_retries,
+        retry_config=retry_config,  # NEW: Pass OAuth-aware retry config
     )
 
     logger.debug(

chuk_tool_processor/mcp/setup_mcp_sse.py

@@ -37,8 +37,8 @@ async def setup_mcp_sse(  # noqa: C901 - long but just a config facade
     enable_rate_limiting: bool = False,
     global_rate_limit: int | None = None,
     tool_rate_limits: dict[str, tuple] | None = None,
-    enable_retries: bool = False,  # CHANGED: Disabled to allow OAuth refresh to work properly
-    max_retries: int = 0,  # CHANGED: 0 retries for SSE (OAuth refresh happens at transport level)
+    enable_retries: bool = True,  # CHANGED: Enabled with OAuth errors excluded
+    max_retries: int = 2,  # Retry non-OAuth errors (OAuth handled at transport level)
     namespace: str = "sse",
     oauth_refresh_callback: any | None = None,  # NEW: OAuth token refresh callback
 ) -> tuple[ToolProcessor, StreamManager]:
@@ -81,6 +81,41 @@ async def setup_mcp_sse(  # noqa: C901 - long but just a config facade
     registered = await register_mcp_tools(stream_manager, namespace=namespace)
 
     # 3️⃣  build a processor instance configured to your taste
+    # IMPORTANT: Retries are enabled but OAuth errors are excluded
+    # OAuth refresh happens at transport level with automatic retry
+
+    # Import RetryConfig to configure OAuth error exclusion
+    from chuk_tool_processor.execution.wrappers.retry import RetryConfig
+
+    # Define OAuth error patterns that should NOT be retried at this level
+    # These will be handled by the transport layer's OAuth refresh mechanism
+    # Based on RFC 6750 (Bearer Token Usage) and MCP OAuth spec
+    oauth_error_patterns = [
+        # RFC 6750 Section 3.1 - Standard Bearer token errors
+        "invalid_token",  # Token expired, revoked, malformed, or invalid
+        "insufficient_scope",  # Request requires higher privileges (403 Forbidden)
+        # OAuth 2.1 token refresh errors
+        "invalid_grant",  # Refresh token errors
+        # MCP spec - OAuth validation failures (401 Unauthorized)
+        "oauth validation",
+        "unauthorized",
+        # Common OAuth error descriptions
+        "expired token",
+        "token expired",
+        "authentication failed",
+        "invalid access token",
+    ]
+
+    # Create retry config that skips OAuth errors
+    retry_config = (
+        RetryConfig(
+            max_retries=max_retries,
+            skip_retry_on_error_substrings=oauth_error_patterns,
+        )
+        if enable_retries
+        else None
+    )
+
     processor = ToolProcessor(
         default_timeout=default_timeout,
         max_concurrency=max_concurrency,
@@ -91,6 +126,7 @@ async def setup_mcp_sse(  # noqa: C901 - long but just a config facade
         tool_rate_limits=tool_rate_limits,
         enable_retries=enable_retries,
         max_retries=max_retries,
+        retry_config=retry_config,  # NEW: Pass OAuth-aware retry config
     )
 
     logger.debug(

chuk_tool_processor/mcp/setup_mcp_stdio.py

@@ -13,11 +13,16 @@ It:
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Any
+
 from chuk_tool_processor.core.processor import ToolProcessor
 from chuk_tool_processor.logging import get_logger
 from chuk_tool_processor.mcp.register_mcp_tools import register_mcp_tools
 from chuk_tool_processor.mcp.stream_manager import StreamManager
 
+if TYPE_CHECKING:
+    from chuk_tool_processor.mcp.models import MCPServerConfig
+
 logger = get_logger("chuk_tool_processor.mcp.setup_stdio")
 
 
@@ -26,8 +31,8 @@ logger = get_logger("chuk_tool_processor.mcp.setup_stdio")
 # --------------------------------------------------------------------------- #
 async def setup_mcp_stdio(  # noqa: C901 - long but just a config facade
     *,
-    config_file: str,
-    servers: list[str],
+    config_file: str | None = None,  # NOW OPTIONAL - for backward compatibility
+    servers: list[str] | list[dict[str, Any]] | list[MCPServerConfig],  # Can be server names, dicts, OR Pydantic models
     server_names: dict[int, str] | None = None,
     default_timeout: float = 10.0,
     initialization_timeout: float = 60.0,
@@ -45,17 +50,92 @@ async def setup_mcp_stdio(  # noqa: C901 - long but just a config facade
     Initialise stdio-transport MCP + a :class:`ToolProcessor`.
 
     Call with ``await`` from your async context.
+
+    Args:
+        config_file: Optional config file path (legacy mode)
+        servers: Can be:
+            - List of server names (legacy, requires config_file)
+            - List of server config dicts (new DX)
+            - List of MCPServerConfig Pydantic models (best DX)
+        server_names: Optional server name mapping
+        default_timeout: Default timeout for operations
+        initialization_timeout: Timeout for initialization
+        max_concurrency: Maximum concurrent operations
+        enable_caching: Enable result caching
+        cache_ttl: Cache time-to-live
+        enable_rate_limiting: Enable rate limiting
+        global_rate_limit: Global rate limit
+        tool_rate_limits: Per-tool rate limits
+        enable_retries: Enable retries
+        max_retries: Maximum retry attempts
+        namespace: Tool namespace
+
+    Returns:
+        Tuple of (ToolProcessor, StreamManager)
+
+    Examples:
+        # Best DX (Pydantic models):
+        from chuk_tool_processor.mcp import MCPServerConfig, MCPTransport
+
+        processor, manager = await setup_mcp_stdio(
+            servers=[
+                MCPServerConfig(
+                    name="echo",
+                    transport=MCPTransport.STDIO,
+                    command="uvx",
+                    args=["chuk-mcp-echo", "stdio"],
+                ),
+            ],
+            namespace="tools",
+        )
+
+        # New DX (dicts, no config file):
+        processor, manager = await setup_mcp_stdio(
+            servers=[
+                {"name": "echo", "command": "uvx", "args": ["chuk-mcp-echo", "stdio"]},
+            ],
+            namespace="tools",
+        )
+
+        # Legacy (with config file):
+        processor, manager = await setup_mcp_stdio(
+            config_file="mcp_config.json",
+            servers=["echo"],
+            namespace="tools",
+        )
     """
-    # 1️⃣  create & connect the stream-manager
-    # FIXED: Pass the default_timeout parameter to StreamManager.create
-    stream_manager = await StreamManager.create(
-        config_file=config_file,
-        servers=servers,
-        server_names=server_names,
-        transport_type="stdio",
-        default_timeout=default_timeout,  # 🔧 ADD THIS LINE
-        initialization_timeout=initialization_timeout,
-    )
+    # Import here to avoid circular dependency at module level
+    from chuk_tool_processor.mcp.models import MCPServerConfig as MCPServerConfigModel
+
+    # Check what format the servers are in
+    if servers and isinstance(servers[0], str):
+        # LEGACY: servers are names, config_file is required
+        if config_file is None:
+            raise ValueError("config_file is required when servers is a list of strings")
+
+        stream_manager = await StreamManager.create(
+            config_file=config_file,
+            servers=servers,  # type: ignore[arg-type]
+            server_names=server_names,
+            transport_type="stdio",
+            default_timeout=default_timeout,
+            initialization_timeout=initialization_timeout,
+        )
+    else:
+        # NEW DX: servers are config dicts or Pydantic models
+        # Convert Pydantic models to dicts if needed
+        server_dicts: list[dict[str, Any]]
+        if servers and isinstance(servers[0], MCPServerConfigModel):
+            server_dicts = [s.to_dict() for s in servers]  # type: ignore[union-attr]
+        else:
+            server_dicts = servers  # type: ignore[assignment]
+
+        stream_manager = await StreamManager.create_with_stdio(
+            servers=server_dicts,
+            server_names=server_names,
+            default_timeout=default_timeout,
+            initialization_timeout=initialization_timeout,
+        )
 
     # 2️⃣  pull the remote tool list and register each one locally
     registered = await register_mcp_tools(stream_manager, namespace=namespace)

chuk_tool_processor/mcp/stream_manager.py

@@ -96,6 +96,24 @@ class StreamManager:
         )
         return inst
 
+    @classmethod
+    async def create_with_stdio(
+        cls,
+        servers: list[dict[str, Any]],
+        server_names: dict[int, str] | None = None,
+        default_timeout: float = 30.0,
+        initialization_timeout: float = 60.0,
+    ) -> StreamManager:
+        """Create StreamManager with STDIO transport and timeout protection (no config file needed)."""
+        inst = cls()
+        await inst.initialize_with_stdio(
+            servers,
+            server_names,
+            default_timeout=default_timeout,
+            initialization_timeout=initialization_timeout,
+        )
+        return inst
+
     @classmethod
     async def create_with_http_streamable(
         cls,
@@ -176,17 +194,24 @@ class StreamManager:
             for idx, server_name in enumerate(servers):
                 try:
                     if transport_type == "stdio":
-                        params = await load_config(config_file, server_name)
+                        params, server_timeout = await load_config(config_file, server_name)
+                        # Use per-server timeout if specified, otherwise use global default
+                        effective_timeout = server_timeout if server_timeout is not None else default_timeout
+                        logger.info(
+                            f"Server '{server_name}' using timeout: {effective_timeout}s (per-server: {server_timeout}, default: {default_timeout})"
+                        )
                         # Use initialization_timeout for connection_timeout since subprocess
                         # launch can take time (e.g., uvx downloading packages)
                         transport: MCPBaseTransport = StdioTransport(
-                            params, connection_timeout=initialization_timeout, default_timeout=default_timeout
+                            params, connection_timeout=initialization_timeout, default_timeout=effective_timeout
                         )
                     elif transport_type == "sse":
                         logger.debug(
                             "Using SSE transport in initialize() - consider using initialize_with_sse() instead"
                         )
-                        params = await load_config(config_file, server_name)
+                        params, server_timeout = await load_config(config_file, server_name)
+                        # Use per-server timeout if specified, otherwise use global default
+                        effective_timeout = server_timeout if server_timeout is not None else default_timeout
 
                         if isinstance(params, dict) and "url" in params:
                             sse_url = params["url"]
@@ -199,7 +224,7 @@ class StreamManager:
                             logger.debug("No URL configured for SSE transport, using default: %s", sse_url)
 
                         # Build SSE transport with optional headers
-                        transport_params = {"url": sse_url, "api_key": api_key, "default_timeout": default_timeout}
+                        transport_params = {"url": sse_url, "api_key": api_key, "default_timeout": effective_timeout}
                         if headers:
                             transport_params["headers"] = headers
 
@@ -209,7 +234,9 @@ class StreamManager:
                         logger.debug(
                             "Using HTTP Streamable transport in initialize() - consider using initialize_with_http_streamable() instead"
                         )
-                        params = await load_config(config_file, server_name)
+                        params, server_timeout = await load_config(config_file, server_name)
+                        # Use per-server timeout if specified, otherwise use global default
+                        effective_timeout = server_timeout if server_timeout is not None else default_timeout
 
                         if isinstance(params, dict) and "url" in params:
                             http_url = params["url"]
@@ -227,7 +254,7 @@ class StreamManager:
                         transport_params = {
                             "url": http_url,
                             "api_key": api_key,
-                            "default_timeout": default_timeout,
+                            "default_timeout": effective_timeout,
                             "session_id": session_id,
                         }
                         # Note: headers not added until HTTPStreamableTransport supports them
@@ -364,6 +391,82 @@ class StreamManager:
                 len(self.all_tools),
             )
 
+    async def initialize_with_stdio(
+        self,
+        servers: list[dict[str, Any]],
+        server_names: dict[int, str] | None = None,
+        default_timeout: float = 30.0,
+        initialization_timeout: float = 60.0,
+    ) -> None:
+        """Initialize with STDIO transport directly from server configs (no config file needed)."""
+        if self._closed:
+            raise RuntimeError("Cannot initialize a closed StreamManager")
+
+        async with self._lock:
+            self.server_names = server_names or {}
+
+            for idx, cfg in enumerate(servers):
+                name = cfg.get("name")
+                command = cfg.get("command")
+                args = cfg.get("args", [])
+                env = cfg.get("env")
+
+                if not (name and command):
+                    logger.error("Bad STDIO server config (missing name or command): %s", cfg)
+                    continue
+
+                try:
+                    # Build STDIO transport parameters
+                    transport_params = {
+                        "command": command,
+                        "args": args,
+                    }
+                    if env:
+                        transport_params["env"] = env
+
+                    logger.debug("STDIO %s: command=%s, args=%s", name, command, args)
+
+                    transport = StdioTransport(
+                        transport_params, connection_timeout=initialization_timeout, default_timeout=default_timeout
+                    )
+
+                    try:
+                        if not await asyncio.wait_for(transport.initialize(), timeout=initialization_timeout):
+                            logger.warning("Failed to init STDIO %s", name)
+                            continue
+                    except TimeoutError:
+                        logger.error("Timeout initialising STDIO %s (timeout=%ss)", name, initialization_timeout)
+                        continue
+
+                    self.transports[name] = transport
+
+                    # Ping and get tools with timeout protection
+                    status = (
+                        "Up"
+                        if await asyncio.wait_for(transport.send_ping(), timeout=self.timeout_config.operation)
+                        else "Down"
+                    )
+                    tools = await asyncio.wait_for(transport.get_tools(), timeout=self.timeout_config.operation)
+
+                    for t in tools:
+                        tname = t.get("name")
+                        if tname:
+                            self.tool_to_server_map[tname] = name
+                    self.all_tools.extend(tools)
+
+                    self.server_info.append({"id": idx, "name": name, "tools": len(tools), "status": status})
+                    logger.debug("Initialised STDIO %s - %d tool(s)", name, len(tools))
+                except TimeoutError:
+                    logger.error("Timeout initialising STDIO %s", name)
+                except Exception as exc:
+                    logger.error("Error initialising STDIO %s: %s", name, exc)
+
+            logger.debug(
+                "StreamManager ready - %d STDIO server(s), %d tool(s)",
+                len(self.transports),
+                len(self.all_tools),
+            )
+
     async def initialize_with_http_streamable(
         self,
         servers: list[dict[str, str]],

chuk_tool_processor/mcp/transport/http_streamable_transport.py

@@ -239,13 +239,13 @@ class HTTPStreamableTransport(MCPBaseTransport):
             await self._cleanup()
             if self.enable_metrics and self._metrics:
                 self._metrics.connection_errors += 1
-            return False
+            raise  # Re-raise for OAuth error detection in mcp-cli
         except Exception as e:
             logger.error("Error initializing HTTP Streamable transport: %s", e, exc_info=True)
             await self._cleanup()
             if self.enable_metrics and self._metrics:
                 self._metrics.connection_errors += 1
-            return False
+            raise  # Re-raise for OAuth error detection in mcp-cli
 
     async def _attempt_recovery(self) -> bool:
         """Attempt to recover from connection issues (NEW - like SSE resilience)."""
@@ -519,16 +519,29 @@ class HTTPStreamableTransport(MCPBaseTransport):
         self._metrics.update_call_metrics(response_time, success)
 
     def _is_oauth_error(self, error_msg: str) -> bool:
-        """Detect if error is OAuth-related (NEW)."""
+        """
+        Detect if error is OAuth-related per RFC 6750 and MCP OAuth spec.
+
+        Checks for:
+        - RFC 6750 Section 3.1 Bearer token errors (invalid_token, insufficient_scope)
+        - OAuth 2.1 token refresh errors (invalid_grant)
+        - MCP spec OAuth validation failures (401/403 responses)
+        """
         if not error_msg:
             return False
 
         error_lower = error_msg.lower()
         oauth_indicators = [
-            "invalid_token",
-            "expired token",
+            # RFC 6750 Section 3.1 - Standard Bearer token errors
+            "invalid_token",  # Token expired, revoked, malformed, or invalid
+            "insufficient_scope",  # Request requires higher privileges (403 Forbidden)
+            # OAuth 2.1 token refresh errors
+            "invalid_grant",  # Refresh token errors
+            # MCP spec - OAuth validation failures (401 Unauthorized)
             "oauth validation",
             "unauthorized",
+            # Common OAuth error descriptions
+            "expired token",
             "token expired",
             "authentication failed",
             "invalid access token",