René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"agentgateway.call_mcp_tool flattens CallToolResult to str, dropping structuredContent and other MCP fields","articleBody":"### Describe the Bug\n\n`sap_cloud_sdk.agentgateway.AgentGatewayClient.call_mcp_tool` is typed `-\u003e str` and both internal flow paths (`_customer.py::call_mcp_tool_customer` and `_lob.py::call_mcp_tool_lob`) discard almost everything on the returned MCP `CallToolResult` before crossing the SDK boundary:\n\n```python\n# src/sap_cloud_sdk/agentgateway/_customer.py (main branch, lines 571-576)\n# Same shape in _lob.py at lines 480-484.\nresult = await session.call_tool(tool.name, kwargs)\nif not result.content:\n    logger.warning(\"Tool '%s' returned empty content\", tool.name)\n    return \"\"\nfirst = result.content[0]\nreturn str(getattr(first, \"text\", \"\"))\n```\n\nDropped fields:\n\n- `structuredContent` — the MCP-native channel for schema-typed structured tool output. Servers set this alongside `content` so consumers can distinguish human-readable text from typed data.\n- `content[1:]` — every content block after the first (multi-block responses lose everything but block 0).\n- `isError` — success and error results are both returned as `str`, indistinguishable at the type level.\n- `_meta` — arbitrary MCP metadata.\n\nThe reference converter `converters.py::mcp_tool_to_langchain` builds a LangChain `StructuredTool` whose coroutine returns this flattened `str` directly to LangChain, so downstream consumers using the reference converter also lose these fields.\n\n**Why it matters:** `langchain_mcp_adapters` (a sibling library in the LangChain ecosystem) preserves `structuredContent` on the LangChain side by wrapping it into `MCPToolArtifact` on `ToolMessage.artifact` via `response_format=\"content_and_artifact\"`. Consumers that go through `sap_cloud_sdk.agentgateway` for its auth / mTLS / destination-resolution / tenant-routing plumbing pay for it by losing the structured channel. Concrete downstream impacts:\n\n- Agents emitting structured tool payloads as A2A `Part(root=DataPart(...))` cannot recover `structuredContent` from a `str` return. The workaround is to `json.loads` the returned string, which only succeeds when the MCP server happens to duplicate its structured payload into `content[0].text`.\n- Any MCP tool that returns multiple `content` blocks (text + image, or multiple text blocks) is truncated to block 0.\n- Callers cannot check `isError` at the type level — success and error results have the same return type.\n\n### Steps to Reproduce\n\n1. Configure an MCP server that returns a `CallToolResult` with both `content` (text) and `structuredContent` (dict) populated. This is the standard MCP shape for schema-typed tool output.\n2. Invoke via `agent_gateway_client.call_mcp_tool(tool, ...)`.\n3. Observe that the return value is `str` — the first content block's `text`. `structuredContent`, `content[1:]`, `isError`, and `_meta` are unrecoverable from the return.\n\n### Expected Behavior\n\n`call_mcp_tool` (or an equivalent method exposed by the SDK) allows consumers to access the full `CallToolResult`, preserving `content`, `structuredContent`, `isError`, and `_meta`. This lets consumers implement the same `content_and_artifact` split that `langchain_mcp_adapters` provides for the direct-MCP path.\n\nTwo possible shapes for the fix (maintainers know the compatibility surface best):\n\n**Option A — additive, non-breaking.** Add a new method returning the raw `CallToolResult`, keep the existing `call_mcp_tool` unchanged:\n\n```python\nasync def call_mcp_tool_raw(\n    self,\n    tool: MCPTool,\n    user_token: str | Callable[[], str] | None = None,\n    app_tid: str | None = None,\n    **kwargs,\n) -\u003e mcp.types.CallToolResult:\n    ...\n```\n\nUpdate `converters.py::mcp_tool_to_langchain` (or ship a second reference converter) to call `call_mcp_tool_raw` and build a `StructuredTool` with `response_format=\"content_and_artifact\"`, matching the `langchain_mcp_adapters` shape.\n\n**Option B — breaking, cleaner long-term.** Change `call_mcp_tool` to return `CallToolResult`; update the reference converter accordingly. Requires a major version bump and a migration note.\n\nOption A seems preferable given `call_mcp_tool` is a documented public API with a stable signature and existing consumers would need to migrate.\n\n### Used Versions\n\n- Python version: `3.14.3` (bug is Python-version-independent — logic is in the SDK)\n- SAP Cloud SDK for Python version: `0.29.1` observed. Verified the same flattening logic is still on `main` at time of filing: [`agw_client.py:485`](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/agentgateway/agw_client.py#L485) declares `-\u003e str`, and [`_customer.py:571-576`](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/agentgateway/_customer.py#L571) / [`_lob.py:480-484`](https://github.com/SAP/cloud-sdk-python/blob/main/src/sap_cloud_sdk/agentgateway/_lob.py#L480) contain the flatten-to-`content[0].text` code.\n- Framework version: `langchain-mcp-adapters==0.2.2` (for cross-reference with the sibling library's `_convert_call_tool_result` behavior)\n\n### Code Examples\n\n```python\n# Consumer-side workaround currently in use — reconstructs a partial\n# CallToolResult by parsing the flattened string. Works when the MCP\n# server duplicates its payload into content[0].text; loses information\n# when it doesn't.\nraw_string = await agw_client.call_mcp_tool(tool, ...)\ntry:\n    parsed = json.loads(raw_string)\n    structured = parsed if isinstance(parsed, dict) else None\nexcept json.JSONDecodeError:\n    structured = None\n\nresult = CallToolResult(\n    content=[TextContent(type=\"text\", text=raw_string)],\n    structuredContent=structured,\n    isError=False,   # Cannot actually determine — SDK dropped it\n)\n```\n\n### Affected Development Phase\n\nDevelopment\n\n### Impact\n\nImpaired\n\n### Related\n\n- MCP protocol spec on `CallToolResult` / `structuredContent`: https://modelcontextprotocol.io/specification/\n- `langchain_mcp_adapters._convert_call_tool_result` — how the sibling library preserves the split: https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py\n","author":{"url":"https://github.com/patrickmlr","@type":"Person","name":"patrickmlr"},"datePublished":"2026-07-08T10:01:21.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/214/cloud-sdk-python/issues/214"}