feat: mcp lazy load debug bindings

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: edis-uipath

src/uipath_langchain/agent/tools/mcp/claude.md

@@ -41,7 +41,7 @@ from .mcp_tool import (
 
 `McpClient` implements `UiPathDisposableProtocol` and manages the lifecycle of MCP connections for tool invocations with **two distinct initialization phases**:
 
-1. **Client Initialization** (first call): Full stack creation
+1. **Client Initialization** (first call): Retrieves MCP server URL via SDK, then full stack creation
 2. **Session Reinitialization** (on 404): Lightweight, reuses existing client
 
 ```
@@ -50,11 +50,15 @@ from .mcp_tool import (
 ├─────────────────────────────────────────────────────────────┤
 │  Configuration (immutable after __init__)                   │
 │  ─────────────────────────────────────────                  │
-│  _url: str                                                  │
-│  _headers: dict[str, str]                                   │
+│  _config: AgentMcpResourceConfig  # Contains slug, folder   │
 │  _timeout: httpx.Timeout                                    │
 │  _max_retries: int                                          │
 ├─────────────────────────────────────────────────────────────┤
+│  Lazy-Resolved State (set during _initialize_client)        │
+│  ───────────────────────────────────────────────────        │
+│  _url: str | None          # Retrieved from SDK             │
+│  _headers: dict[str, str]  # Auth header from SDK           │
+├─────────────────────────────────────────────────────────────┤
 │  Synchronization                                            │
 │  ───────────────                                            │
 │  _lock: asyncio.Lock     # Protects both init phases        │
@@ -82,7 +86,7 @@ from .mcp_tool import (
 ├─────────────────────────────────────────────────────────────┤
 │  Private Methods                                            │
 │  ───────────────                                            │
-│  - _initialize_client() -> None    # Full init (once)       │
+│  - _initialize_client() -> None    # SDK + full init (once) │
 │  - _initialize_session() -> None   # MCP handshake only     │
 │  - _ensure_session() -> ClientSession                       │
 │  - _reinitialize_session() -> None                          │
@@ -105,8 +109,8 @@ async def create_mcp_tools_from_agent(
     Iterates over all MCP resources in the agent definition and creates tools
     for each enabled MCP server. Each MCP server gets its own McpClient instance.
 
-    The UiPath SDK is lazily initialized inside this function using environment
-    variables (UIPATH_URL, UIPATH_ACCESS_TOKEN).
+    The MCP server URL is loaded lazily on first tool call via the UiPath SDK,
+    using environment variables (UIPATH_URL, UIPATH_ACCESS_TOKEN).
 
     Returns:
         A tuple of (tools, mcp_clients) where:
@@ -143,6 +147,11 @@ The key design principle is separating **client initialization** from **session
 ```
 Phase 1: Client Initialization (expensive, done once)
 ──────────────────────────────────────────────────────
+┌─────────────────┐
+│ UiPath SDK      │ ─── Retrieves MCP server URL
+│ mcp.retrieve()  │     and auth token (Bearer)
+└─────────────────┘
+
 ┌─────────────────┐
 │ httpx.AsyncClient │ ─┐
 └─────────────────┘   │
@@ -179,8 +188,9 @@ Phase 2: Session Initialization (lightweight, can repeat)
            │ Initializing │
            │ (Phase 1)    │
            └──────┬───────┘
-                  │ creates HTTP client, streams, session
-                  │ then calls _initialize_session()
+                  │ 1. UiPath SDK retrieves MCP URL
+                  │ 2. creates HTTP client, streams, session
+                  │ 3. calls _initialize_session()
                   ▼
            ┌──────────────┐
            │   Session    │
@@ -251,7 +261,42 @@ The following error codes trigger automatic session reinitialization:
 
 ## Key Implementation Details
 
-### 1. HTTP Client Configuration
+### 1. Lazy SDK Loading
+
+The MCP server URL and authorization headers are loaded lazily on first tool call:
+
+```python
+async def _initialize_client(self) -> None:
+    # Lazy import to improve cold start time
+    from uipath.platform import UiPath
+
+    # Retrieve MCP server URL from SDK
+    sdk = UiPath()
+    mcp_server = await sdk.mcp.retrieve_async(
+        slug=self._config.slug, folder_path=self._config.folder_path
+    )
+
+    if mcp_server.mcp_url is None:
+        raise ValueError(f"MCP server '{self._config.slug}' has no URL configured")
+
+    self._url = mcp_server.mcp_url
+    self._headers = {"Authorization": f"Bearer {sdk._config.secret}"}
+```
+
+**Why lazy loading is required:**
+
+The `uipath debug` command loads resource bindings (which can override MCP server URLs)
+**after** the LangGraph agent graph is built. This means bindings are only available at
+execution time, not at graph construction time. By deferring the SDK call to the first
+tool invocation, we ensure the bindings are properly loaded and applied.
+
+**Benefits:**
+- Bindings are correctly applied (loaded after graph construction)
+- No SDK calls during tool creation (only during first use)
+- Faster agent startup time
+- Errors surface only when tools are actually used
+
+### 2. HTTP Client Configuration
 
 The HTTP client MUST use `get_httpx_client_kwargs()` for proper SSL/proxy configuration:
 
@@ -268,7 +313,7 @@ self._http_client = await self._stack.enter_async_context(
 )
 ```
 
-### 2. Single Lock for Both Phases
+### 3. Single Lock for Both Phases
 
 One `asyncio.Lock` protects both client initialization and session reinitialization:
 
@@ -289,7 +334,7 @@ async def _reinitialize_session(self) -> None:
             await self._initialize_session()  # Lightweight!
 ```
 
-### 3. No `with` Statement for AsyncExitStack
+### 4. No `with` Statement for AsyncExitStack
 
 Manual lifecycle management:
 
@@ -305,7 +350,7 @@ async with AsyncExitStack() as stack:
     ...  # Stack closes here!
 ```
 
-### 4. Reinitialization Reuses Client
+### 5. Reinitialization Reuses Client
 
 The key optimization - on 404, only `_initialize_session()` is called:
 

src/uipath_langchain/agent/tools/mcp/mcp_client.py

@@ -7,7 +7,7 @@
 import asyncio
 import logging
 from contextlib import AsyncExitStack
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import httpx
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
@@ -22,6 +22,9 @@
 from uipath._utils._ssl_context import get_httpx_client_kwargs
 from uipath.runtime.base import UiPathDisposableProtocol
 
+if TYPE_CHECKING:
+    from uipath.agent.models.agent import AgentMcpResourceConfig
+
 logger = logging.getLogger(__name__)
 
 
@@ -31,7 +34,8 @@ class McpClient(UiPathDisposableProtocol):
     This class handles the lifecycle of MCP connections with two distinct phases:
 
     1. **Client Initialization** (first call):
-       - Creates HTTP client
+       - Instantiates UiPath SDK to retrieve MCP server URL
+       - Creates HTTP client with authorization headers
        - Establishes streamable HTTP connection
        - Creates ClientSession
        - Calls session.initialize() to get session ID
@@ -48,24 +52,28 @@ class McpClient(UiPathDisposableProtocol):
 
     def __init__(
         self,
-        url: str,
-        headers: dict[str, str] | None = None,
+        config: "AgentMcpResourceConfig",
         timeout: httpx.Timeout | None = None,
         max_retries: int = 1,
     ) -> None:
         """Initialize the MCP tool session.
 
+        The MCP server URL and authorization headers are retrieved lazily
+        from the UiPath SDK on first use, using the config's slug and folder_path.
+
         Args:
-            url: The MCP server endpoint URL.
-            headers: Optional headers to include in HTTP requests.
+            config: The MCP resource configuration containing slug and folder_path.
             timeout: Optional timeout configuration for HTTP requests.
             max_retries: Maximum number of retries on session disconnect errors.
         """
-        self._url = url
-        self._headers = headers or {}
+        self._config = config
         self._timeout = timeout or httpx.Timeout(600)
         self._max_retries = max_retries
 
+        # URL and headers are resolved lazily from SDK
+        self._url: str | None = None
+        self._headers: dict[str, str] = {}
+
         # Lock for both client initialization and session reinitialization
         self._lock = asyncio.Lock()
 
@@ -97,13 +105,36 @@ async def _initialize_client(self) -> None:
         """Initialize the HTTP client and streamable connection.
 
         This is called once on first use. Creates:
-        - httpx.AsyncClient
+        - UiPath SDK instance to retrieve MCP server URL
+        - httpx.AsyncClient with authorization headers
         - Streamable HTTP connection (read/write streams)
         - ClientSession
 
         Then calls _initialize_session() to complete the MCP handshake.
         """
-        logger.debug("Initializing MCP client")
+        logger.debug(
+            f"Initializing MCP client for '{self._config.slug}' "
+            f"in folder '{self._config.folder_path}'"
+        )
+
+        # Lazy import to improve cold start time
+        from uipath.platform import UiPath
+
+        # Retrieve MCP server URL from SDK
+        sdk = UiPath()
+        mcp_server = await sdk.mcp.retrieve_async(
+            slug=self._config.slug, folder_path=self._config.folder_path
+        )
+
+        if mcp_server.mcp_url is None:
+            raise ValueError(
+                f"MCP server '{self._config.slug}' has no URL configured"
+            )
+
+        self._url = mcp_server.mcp_url
+        self._headers = {"Authorization": f"Bearer {sdk._config.secret}"}
+
+        logger.debug(f"Retrieved MCP server URL: {self._url}")
 
         # Create exit stack for resource management
         self._stack = AsyncExitStack()

src/uipath_langchain/agent/tools/mcp/mcp_tool.py

@@ -15,8 +15,6 @@
     LowCodeAgentDefinition,
 )
 from uipath.eval.mocks import mockable
-from uipath.platform import UiPath
-from uipath.platform.orchestrator.mcp import McpServer
 
 from uipath_langchain.agent.tools.base_uipath_structured_tool import (
     BaseUiPathStructuredTool,
@@ -177,8 +175,8 @@ async def create_mcp_tools_from_agent(
     Iterates over all MCP resources in the agent definition and creates tools
     for each enabled MCP server. Each MCP server gets its own McpClient instance.
 
-    The UiPath SDK is lazily initialized inside this function using environment
-    variables (UIPATH_URL, UIPATH_ACCESS_TOKEN).
+    The MCP server URL is loaded lazily on first tool call via the UiPath SDK,
+    using environment variables (UIPATH_URL, UIPATH_ACCESS_TOKEN).
 
     Args:
         agent: The agent definition containing MCP resources.
@@ -194,7 +192,6 @@ async def create_mcp_tools_from_agent(
     """
     tools: list[BaseTool] = []
     clients: list[McpClient] = []
-    sdk: UiPath = UiPath()  # Lazy initialization of SDK
 
     for resource in agent.resources:
         if not isinstance(resource, AgentMcpResourceConfig):
@@ -206,16 +203,8 @@ async def create_mcp_tools_from_agent(
 
         logger.info(f"Creating MCP tools for resource '{resource.name}'")
 
-        mcpServer: McpServer = await sdk.mcp.retrieve_async(
-            slug=resource.slug, folder_path=resource.folder_path
-        )
-        if mcpServer.mcp_url is None:
-            raise ValueError(f"MCP server '{resource.slug}' has no URL configured")
-
-        mcpClient = McpClient(
-            mcpServer.mcp_url,
-            headers={"Authorization": f"Bearer {sdk._config.secret}"},
-        )
+        # McpClient will lazily load the MCP server URL on first tool call
+        mcpClient = McpClient(config=resource)
         clients.append(mcpClient)
 
         resource_tools = await create_mcp_tools_from_metadata_for_mcp_server(