Refactor MCP session management and update error handling

- Introduced a new module `_mcp_session.py` to encapsulate MCP session management logic.
- Added `invoke_mcp_tool` function to handle tool invocation with improved error handling.
- Updated test cases in `test_lob.py` to reflect changes in error messages and patching for MCP session.
- Updated package version to 0.26.1 in `uv.lock`.

Author: KoblerS

src/sap_cloud_sdk/agentgateway/__init__.py

@@ -57,6 +57,7 @@
 from sap_cloud_sdk.agentgateway.agw_client import create_client, AgentGatewayClient
 from sap_cloud_sdk.agentgateway.exceptions import (
     AgentGatewaySDKError,
+    AgentGatewayServerError,
     MCPServerNotFoundError,
 )
 
@@ -73,5 +74,6 @@
     "MCPTool",
     # Exceptions
     "AgentGatewaySDKError",
+    "AgentGatewayServerError",
     "MCPServerNotFoundError",
 ]

src/sap_cloud_sdk/agentgateway/_customer.py

@@ -24,6 +24,7 @@
     IntegrationDependency,
     MCPTool,
 )
+from sap_cloud_sdk.agentgateway._mcp_session import invoke_mcp_tool
 from sap_cloud_sdk.agentgateway._token_cache import _TokenCache
 from sap_cloud_sdk.agentgateway.exceptions import AgentGatewaySDKError
 
@@ -64,6 +65,7 @@ class _CredentialFields:
     GATEWAY_URL = "gatewayUrl"
     INTEGRATION_DEPENDENCIES = "integrationDependencies"
     ORD_ID = "ordId"
+    DATA = "data"
     GLOBAL_TENANT_ID = "globalTenantId"
 
 
@@ -151,7 +153,10 @@ def load_customer_credentials(path: str) -> CustomerCredentials:
         integration_deps = [
             IntegrationDependency(
                 ord_id=dep[_CredentialFields.ORD_ID],
-                global_tenant_id=dep[_CredentialFields.GLOBAL_TENANT_ID],
+                global_tenant_id=(
+                    dep.get(_CredentialFields.GLOBAL_TENANT_ID)
+                    or dep[_CredentialFields.DATA][_CredentialFields.GLOBAL_TENANT_ID]
+                ),
             )
             for dep in data[_CredentialFields.INTEGRATION_DEPENDENCIES]
         ]
@@ -256,11 +261,6 @@ def _request_token_mtls(
         "resource": _AGW_RESOURCE_URN,
     }
 
-    # TODO: app_tid requirement is still being clarified with the IBD team.
-    # This parameter may be removed if it turns out to be unnecessary.
-    if app_tid:
-        data["app_tid"] = app_tid
-
     if extra_data:
         data.update(extra_data)
 
@@ -565,26 +565,4 @@ async def call_mcp_tool_customer(
         Tool execution result as string.
     """
     logger.info("Calling tool '%s' on server '%s'", tool.name, tool.server_name)
-
-    async with httpx.AsyncClient(
-        headers={
-            "Authorization": f"Bearer {auth_token}",
-            "x-correlation-id": str(uuid.uuid4()),
-        },
-        timeout=timeout,
-    ) as http_client:
-        async with streamable_http_client(tool.url, http_client=http_client) as (
-            read,
-            write,
-            _,
-        ):
-            async with ClientSession(read, write) as session:
-                await session.initialize()
-                result = await session.call_tool(tool.name, kwargs)
-
-                if not result.content:
-                    logger.warning("Tool '%s' returned empty content", tool.name)
-                    return ""
-
-                first = result.content[0]
-                return str(getattr(first, "text", ""))
+    return await invoke_mcp_tool(tool, auth_token, timeout, **kwargs)

src/sap_cloud_sdk/agentgateway/_lob.py

@@ -23,6 +23,7 @@
 )
 
 from sap_cloud_sdk.agentgateway._models import MCPTool
+from sap_cloud_sdk.agentgateway._mcp_session import invoke_mcp_tool
 from sap_cloud_sdk.agentgateway._token_cache import _GatewayUrlCache, _TokenCache
 from sap_cloud_sdk.agentgateway.exceptions import MCPServerNotFoundError
 
@@ -148,19 +149,7 @@ def get_ias_fragment_name(tenant_subdomain: str) -> str:
     Raises:
         MCPServerNotFoundError: If no IAS fragment is found.
     """
-    client = create_fragment_client(instance=_DESTINATION_INSTANCE)
-    fragments = client.list_instance_fragments(
-        filter=ListOptions(
-            filter_labels=[Label(key=_LABEL_KEY, values=[_IAS_LABEL_VALUE])]
-        ),
-        tenant=tenant_subdomain,
-    )
-    if not fragments:
-        raise MCPServerNotFoundError(
-            f"No IAS fragment found (label {_LABEL_KEY}={_IAS_LABEL_VALUE}) "
-            f"for tenant '{tenant_subdomain}'"
-        )
-    return fragments[0].name
+    return _get_labeled_fragment_name(tenant_subdomain, _IAS_LABEL_VALUE)
 
 
 def get_ias_user_fragment_name(tenant_subdomain: str) -> str:
@@ -178,16 +167,25 @@ def get_ias_user_fragment_name(tenant_subdomain: str) -> str:
     Raises:
         MCPServerNotFoundError: If no IAS user fragment is found.
     """
+    return _get_labeled_fragment_name(tenant_subdomain, _IAS_USER_LABEL_VALUE)
+
+
+def _get_labeled_fragment_name(tenant_subdomain: str, label_value: str) -> str:
+    """Return the name of the first fragment matching a managed-runtime label.
+
+    Raises:
+        MCPServerNotFoundError: If no matching fragment is found.
+    """
     client = create_fragment_client(instance=_DESTINATION_INSTANCE)
     fragments = client.list_instance_fragments(
         filter=ListOptions(
-            filter_labels=[Label(key=_LABEL_KEY, values=[_IAS_USER_LABEL_VALUE])]
+            filter_labels=[Label(key=_LABEL_KEY, values=[label_value])]
         ),
         tenant=tenant_subdomain,
     )
     if not fragments:
         raise MCPServerNotFoundError(
-            f"No IAS user fragment found (label {_LABEL_KEY}={_IAS_USER_LABEL_VALUE}) "
+            f"No fragment found (label {_LABEL_KEY}={label_value}) "
             f"for tenant '{tenant_subdomain}'"
         )
     return fragments[0].name
@@ -462,23 +460,4 @@ async def call_mcp_tool_lob(
     Returns:
         Tool execution result as string.
     """
-    async with httpx.AsyncClient(
-        headers={
-            "Authorization": f"Bearer {user_auth_token}",
-            "x-correlation-id": str(uuid.uuid4()),
-        },
-        timeout=timeout,
-    ) as http_client:
-        async with streamable_http_client(tool.url, http_client=http_client) as (
-            read,
-            write,
-            _,
-        ):
-            async with ClientSession(read, write) as session:
-                await session.initialize()
-                result = await session.call_tool(tool.name, kwargs)
-                if not result.content:
-                    logger.warning("Tool '%s' returned empty content", tool.name)
-                    return ""
-                first = result.content[0]
-                return str(getattr(first, "text", ""))
+    return await invoke_mcp_tool(tool, user_auth_token, timeout, **kwargs)

src/sap_cloud_sdk/agentgateway/_mcp_session.py

@@ -0,0 +1,71 @@
+"""Shared helpers for MCP session management."""
+
+import uuid
+
+import httpx
+from mcp import ClientSession, McpError
+from mcp.client.streamable_http import streamable_http_client
+
+from sap_cloud_sdk.agentgateway._models import MCPTool
+from sap_cloud_sdk.agentgateway.exceptions import AgentGatewayServerError
+
+
+async def invoke_mcp_tool(tool: MCPTool, auth_token: str, timeout: float, **kwargs) -> str:
+    """Open an MCP session, call a tool, and return its text result.
+
+    Handles McpError from both initialize() and call_tool(), and checks
+    result.isError, raising AgentGatewayServerError in all three cases.
+
+    Args:
+        tool: MCPTool to invoke.
+        auth_token: Raw bearer token for the Authorization header.
+        timeout: HTTP timeout in seconds.
+        **kwargs: Tool input parameters forwarded to call_tool().
+
+    Returns:
+        Tool result as a string, or "" if the response has no content.
+
+    Raises:
+        AgentGatewayServerError: If the server returns any kind of error.
+    """
+    async with httpx.AsyncClient(
+        headers={
+            "Authorization": f"Bearer {auth_token}",
+            "x-correlation-id": str(uuid.uuid4()),
+        },
+        timeout=timeout,
+    ) as http_client:
+        async with streamable_http_client(tool.url, http_client=http_client) as (
+            read,
+            write,
+            _,
+        ):
+            async with ClientSession(read, write) as session:
+                try:
+                    await session.initialize()
+                except McpError as e:
+                    raise AgentGatewayServerError(
+                        f"Agent Gateway rejected MCP session for tool '{tool.name}': {e.error.message}",
+                        error_code=e.error.code,
+                    ) from e
+                try:
+                    result = await session.call_tool(tool.name, kwargs)
+                except McpError as e:
+                    raise AgentGatewayServerError(
+                        f"Agent Gateway returned error for tool '{tool.name}': {e.error.message}",
+                        error_code=e.error.code,
+                    ) from e
+                if result.isError:
+                    raise AgentGatewayServerError(
+                        f"Tool '{tool.name}' returned an error: {_error_text(result.content)}"
+                    )
+                if not result.content:
+                    return ""
+                return str(getattr(result.content[0], "text", ""))
+
+
+def _error_text(content: list) -> str:
+    """Extract a human-readable message from MCP error content blocks."""
+    texts = [getattr(block, "text", None) for block in content]
+    message = " ".join(t for t in texts if t)
+    return message or "unknown error"

src/sap_cloud_sdk/agentgateway/agw_client.py

@@ -361,7 +361,6 @@ async def list_mcp_tools(
             )
 
         except AgentGatewaySDKError:
-            # Re-raise SDK errors as-is
             raise
         except Exception as e:
             logger.exception("Unexpected error during tool discovery")

src/sap_cloud_sdk/agentgateway/exceptions.py

@@ -22,3 +22,22 @@ class MCPServerNotFoundError(AgentGatewaySDKError):
     """
 
     pass
+
+
+class AgentGatewayServerError(AgentGatewaySDKError):
+    """Raised when the Agent Gateway server returns an error response.
+
+    This error occurs when:
+    - The MCP server card is not found in the registry
+    - The server returns a JSON-RPC error (e.g. code -32600)
+    - A tool invocation returns an error result (isError=True)
+
+    Attributes:
+        error_code: JSON-RPC error code, if available.
+        server_message: The raw error message from the server.
+    """
+
+    def __init__(self, message: str, error_code: int | None = None):
+        super().__init__(message)
+        self.error_code = error_code
+        self.server_message = message