modelcontextprotocol / modelcontextprotocol/python-sdk

Implement consistent structuredContent handling per specification clarification

Open
#1,332 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug enhancement needs decision P3 pending SEP approval
Dominant language
Python
Stars
24.3k
Forks
4k
Avg merge
1d 1h
Merged PRs (30d)
31

Description

Summary

Following the specification issue modelcontextprotocol/specification#1411, the Python SDK needs to ensure consistent handling of structuredContent vs content fields in tool responses.

Problem

Currently there's inconsistency across MCP implementations:

  • Some clients use structuredContent when available (e.g., Cursor)
  • Others ignore it entirely
  • This leads to different behavior with the same servers

Current SDK Behavior

The Python SDK needs to be reviewed to ensure it properly handles the relationship between structuredContent and content fields.

Required Changes

Once modelcontextprotocol/specification#1411 is resolved, update the SDK to:

  1. Implement the specified client behavior for structuredContent
  2. Ensure proper fallback to content when needed
  3. Validate that servers populate both fields consistently
  4. Add tests to verify the correct behavior
  5. Ensure consistency with the TypeScript SDK implementation

References

cc: @dsp-ant

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.

Research direction

Read specification issue modelcontextprotocol/specification#1411 and the linked TypeScript SDK issue first; they define the behavior this Python SDK must match. Then locate the Python client and server response handling and add tests for the clarified structuredContent behavior. Done means implementing the specified fallback, validating consistent server fields, and matching the TypeScript SDK.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, typescript
Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.