MCP structuredContent: Claude Code Drops Your Text Blocks

This report details how Claude Code, Anthropic's coding assistant, interacts with the Model Context Protocol (MCP) when requesting tool results. MCP allows an AI application like Claude Code to call tools on a server while hiding certain result details from the model. The report examines how Claude Code handles structuredContent and text blocks in tool responses.

The specifications state that tools returning structured content should also provide the serialized JSON in a TextContent block for backwards compatibility. However, the server's text and JSON were not equivalent, with the text containing framing information not present in the JSON. Claude Code treated the JSON as the result and dropped the accompanying text.

Three methods were used to confirm this behavior: examining Claude Code's minified client code, reviewing the raw claude-p stream from an evaluation run, and checking the deployed server through a production connection. All three sources indicated that Claude Code received and used only the JSON data, discarding the text.

When analyzing the observed tool results, it was found that Claude Code dropped not only the framing text but also messages with IDs, authors, timestamps, and URLs. However, data such as citations and injection cases still reached the model. The issue persisted despite the eval showing the successful delivery of the model's requested tool result.

Further investigation revealed that the issue arose from Claude Code's handling of the text block. The code filtered out any text blocks of type "text" and replaced them with the JSON content. This behavior, while not explicitly documented, was observed in Claude Code's implementation.

To address the issue, a note field was added to the structuredContent, which stripped out unwanted lines from the text block. This ensured that important data, such as citations and message details, still reached the model. The modified reply() function kept the text block for hosts that read it and wrote the same framing information into structuredContent, allowing for seamless handling of both text and structuredContent.

In summary, Claude Code's treatment of structuredContent and text blocks in tool results can lead to important data being hidden from the model. By understanding this behavior and implementing a note field to filter out unwanted text lines, developers can ensure that all necessary information is passed to the model, improving the accuracy and effectiveness of tool interactions.