From 18eb9d1f3209f3af9cc9ac85114c49630e4db482 Mon Sep 17 00:00:00 2001 From: george larson Date: Fri, 28 Aug 2026 14:41:30 -0400 Subject: [PATCH] docs(sdk): describe structured MCP results Co-authored-by: openhands --- sdk/arch/mcp.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/sdk/arch/mcp.mdx b/sdk/arch/mcp.mdx index 804437127..41d9fa455 100644 --- a/sdk/arch/mcp.mdx +++ b/sdk/arch/mcp.mdx @@ -273,6 +273,18 @@ flowchart TB 6. **Observation Creation:** Wrap in `MCPToolObservation` 7. **Error Handling:** Catch exceptions, return error observations +MCP tools can return two kinds of data beyond their text and image content: +`structuredContent`, machine-readable result data for clients that render or +process it, and result `_meta`, protocol metadata about the call. +`MCPToolObservation` preserves both in the `structured_content` and +`result_meta` fields. They serialize with the observation, so API and websocket +clients receive them, but they are not sent to the model. + +Masking follows the same rules as text output: when a conversation is attached, +registered secrets inside these fields are replaced before the observation is +persisted or delivered, walking nested keys and values. If a field cannot be +masked safely, it is dropped rather than delivered unmasked. + ### MCPToolExecutor Executors bridge SDK actions to MCP calls: