#10236·dspy

Define a DSPy result contract for mixed MCP content blocks

Author: isaacbmillerCreated Aug 18, 2026Updated Sep 10, 2026

Problem

DSPy's MCP result converter currently separates text from non-text content and returns text whenever any text block exists. For a mixed MCP result, that can omit images, audio, embedded resources, or resource links from the returned value.

This is independent of the structured JSON selection added in #10235: MCP content is the model-facing sequence of content blocks, while structuredContent is a separate machine-readable value. Selecting exact structured content does not define how mixed content blocks should be preserved or presented.

Scope for a follow-up PR

Define an explicit, backward-compatible contract for mixed MCP content results. The design should decide:

  • whether and how to preserve the original block order;
  • whether callers opt into raw content blocks or receive a DSPy-native representation;
  • how mixed content should be exposed to model-facing workflows;
  • how URLs, embedded resources, and other untrusted server data cross DSPy's tool boundary;
  • what fallback applies across supported MCP SDK versions.

The default text-only behavior should not change accidentally. Tests should cover every supported non-text block type, text/non-text combinations, ordering, and error results.

Context

  • #10188 added MCP v2 transport compatibility without changing result semantics.
  • #10235 proposes opt-in exact structuredContent and deliberately leaves mixed content blocks out of scope.