Preserve MCP embedded text resources and resource_link blocks in tool results

[psaswata]

Summary

MCP tool results containing an embedded text resource are flattened into ordinary model-visible text by convertMcpCallToolResult. The original resource URI, MIME type, annotations, metadata, content-block identity, and ordering are not exposed losslessly to SDK consumers. MCP resource_link blocks are not handled by the conversion and disappear entirely.

The model can still read resource.text, but hosts consuming tool.execution_complete cannot present the result as a native resource or link because the structured MCP information is no longer available.

Reproduction

Configure an MCP server whose tool returns:

{
  "content": [
    {
      "type": "text",
      "text": "Generated the requested artifact."
    },
    {
      "type": "resource",
      "resource": {
        "uri": "file:///generated/main.bicep",
        "mimeType": "text/plain",
        "text": "targetScope = 'subscription'\n"
      },
      "annotations": {
        "audience": ["user", "assistant"],
        "priority": 1
      }
    },
    {
      "type": "resource_link",
      "uri": "file:///generated/main.bicep",
      "name": "main.bicep",
      "title": "Generated Bicep template",
      "mimeType": "text/plain"
    }
  ],
  "isError": false
}

Invoke the tool through a Copilot SDK session and inspect the resulting tool completion event.

Actual behavior

The Node SDK implementation currently handles the embedded resource as:

case "resource": {
    if (block.resource?.text) {
        textParts.push(block.resource.text);
    }
    if (block.resource?.blob) {
        binaryResults.push(...);
    }
    break;
}

and returns the accumulated value through:

textResultForLlm: textParts.join("\n")

Source:

copilot-sdk/nodejs/src/types.ts

Lines 624 to 675 in 8045fb7

	export function convertMcpCallToolResult(callResult: McpCallToolResult): ToolResultObject {
	const textParts: string[] = [];
	const binaryResults: ToolBinaryResult[] = [];
	for (const block of callResult.content) {
	switch (block.type) {
	case "text":
	// Guard against malformed input where text field is missing at runtime
	if (typeof block.text === "string") {
	textParts.push(block.text);
	}
	break;
	case "image":
	if (
	typeof block.data === "string" &&
	block.data &&
	typeof block.mimeType === "string"
	) {
	binaryResults.push({
	data: block.data,
	mimeType: block.mimeType,
	type: "image",
	});
	}
	break;
	case "resource": {
	// Use optional chaining: resource field may be absent in malformed input
	if (block.resource?.text) {
	textParts.push(block.resource.text);
	}
	if (block.resource?.blob) {
	const mimeType = block.resource.mimeType;
	binaryResults.push({
	data: block.resource.blob,
	mimeType:
	typeof mimeType === "string" && mimeType
	? mimeType
	: "application/octet-stream",
	type: "resource",
	description: block.resource.uri,
	});
	}
	break;
	}
	}
	}
	return {
	textResultForLlm: textParts.join("\n"),
	resultType: callResult.isError ? "failure" : "success",
	...(binaryResults.length > 0 ? { binaryResultsForLlm: binaryResults } : {}),
	};

Consequences:

• resource.text remains available to the model, but is indistinguishable from an ordinary MCP text block.
• The original URI, MIME type, annotations, metadata, and resource-block identity are unavailable to SDK consumers.
• The original ordering and association between the text response, embedded resource, and resource link cannot be reconstructed reliably.
• There is no resource_link case, so that block is absent from the converted result.

For example, a downstream host such as VS Code Agent Host receives enough information to show ordinary text, but not enough information to translate the result into its typed resource representation.

Expected behavior

The SDK should continue providing a convenient combined text value for the model, while also exposing a lossless typed representation of the original MCP CallToolResult, including:

• Ordered content blocks.
• Embedded text resources with URI, MIME type, text, annotations, and metadata.
• Embedded binary resources.
• Resource links with their URI and descriptive metadata.
• Structured content and result metadata.

This could be provided through typed entries in ToolExecutionCompleteResult.contents, a separate raw/typed MCP result field, or another lossless SDK representation.

Why this matters

This is not only a rendering concern. Once the conversion removes the resource identity and link information, an SDK host cannot:

• Present generated documents as native files or attachments.
• Offer an actionable resource link.
• Preserve audience or priority annotations.
• Route content according to MIME type.
• Translate the result into another typed host protocol.

The current behavior is similar to earlier typed-result fidelity issues such as:

• Built in shell tool does not emit terminal content with exitCode on tool.execution_complete #1803, where terminal completion information was flattened into text instead of emitted as typed terminal content.
• SDK 0.3.0 does not support images in tool results' binaryResultsForLlm #1298 and Binary tool results not passed to ExternalToolTextResultForLlm #1644, where binary tool results were not preserved through the SDK path.

Observed scenario

This was identified while testing an MCP server that returns generated artifacts as paired embedded text resources and resource links. The same MCP response renders as native resource output in a direct MCP client, while the Copilot SDK path retains the artifact text but loses the resource presentation and link metadata.

The server-side implementation under test is public:

microsoft/mcp#3845

Suggested acceptance criteria

1. An MCP response containing text, an embedded text resource, and a resource link remains available to the model.
2. SDK consumers can inspect all three original content blocks in order.
3. URI, MIME type, annotations, metadata, and resource-link fields are preserved.
4. Existing image/binary-result behavior remains unchanged.
5. The behavior is covered by a conversion test for convertMcpCallToolResult.

[psaswata]

Downstream tracking is now open:

• VS Code Agent Host mapping and rendering: Agent Host should preserve and render MCP embedded resources and resource links microsoft/vscode#340232
• AHP resource-result fidelity: Support lossless MCP embedded resources and resource links in AHP tool results microsoft/agent-host-protocol#504