Clarify client handling of structuredContent vs content fields

Open
#1,411 2 comments 1 reaction 1 assignee View on GitHub

@dsp-ant is already working on this.

Since Sep 1, 2025.

Assessment

This issue has not been assessed yet.

Description

bug

Summary

There is confusion and inconsistency in how MCP clients should handle structuredContent vs regular content fields in tool responses. This is causing fragmentation where different clients behave differently with the same servers.

Problem Details

From Discord discussion:

  1. Inconsistent client support: Only Cursor currently supports structuredContent, while other clients (CC/Windsurf) ignore it
  2. Different server responses: Some servers return different data in structuredContent vs content instead of treating content as a backwards-compatible stringified version
  3. Untested outputs: Because only one client supports it, structuredContent outputs are poorly tested and of lower quality
  4. Unclear specification: The spec doesn't clearly define:
    • How clients MUST handle structuredContent when present
    • Whether content should always be a stringified version of structuredContent
    • The exact backwards compatibility requirements

Current Behavior

Different clients handle this differently:

  • Cursor: Uses structuredContent when available, stringifies it to content
  • Most other clients: Ignore structuredContent entirely
  • This leads to servers performing differently across different clients

Expected Behavior

The specification should clearly define:

  1. How clients MUST handle structuredContent when present
  2. The relationship between structuredContent and content fields
  3. Backwards compatibility requirements for servers
  4. Whether clients that support structuredContent should prefer it over content

Proposed Solution

Update the specification to be more explicit about:

  • Client requirements for handling structuredContent
  • Server requirements for populating both fields consistently
  • The intended fallback behavior for backwards compatibility

References

cc: @dsp-ant

Dominant language
TypeScript
Stars
9.3k
Forks
1.8k
Avg merge
1d 12h
Merged PRs (30d)
25

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from modelcontextprotocol/modelcontextprotocol

All issues in modelcontextprotocol/modelcontextprotocol

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.