feat: add per-request HTTP headers support for client session methods

[damianoneill]

Implements per-request headers functionality to enable various use cases such as multi-tenant authentication, request tracing, A/B testing, and debugging while maintaining a single persistent connection.

Changes:

• Add extra_headers parameter
• Extend ClientMessageMetadata to support extra_headers
• Update StreamableHTTPTransport to merge per-request headers
• Add tests
• Include usage examples and documentation
• Maintain full backward compatibility

This addresses GitHub issues #1509 and supports multi-tenant scenarios where different requests require different authentication tokens or contextual headers.

Motivation and Context

Disscussed in issue #1509

How Has This Been Tested?

UTs, commit provided for review, is approach is agreed will proceed with extensive real world testing before finalising this PR.

Breaking Changes

N/A

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[damianoneill]

@felixweinberger any feedback on this PR would be much appreciated. First time committing to the repo, I'm not sure what the correct process is for submission. Thanks in advance, Damian.

[juanmolle]

Is there any update on this PR, we are interesting in this patch

[damianoneill]

@juanmolle I've rebased to latest, this required adding new tests as coverage had dropped elsewhere, this is now complete.

The failing check looks like a pipeline problem, I have no way to trigger this again. Assume maintainer can do this during review.

[damianoneill]

@maxisbey @felixweinberger see comment above about failed check. I cannot re-run this check, its seems to be a flaky test outside of my code change.

[damianoneill]

@maxisbey I've rebased to latest

Same as before there is now another test failing tests\client\test_stdio.py not in code I've modified, test looks flaky, it passes on other python version runs.

                size_after_wait = os.path.getsize(marker_file)
>               assert size_after_wait > initial_size, "Child process should be writing"
E               AssertionError: Child process should be writing
E               assert 0 > 0

tests\client\test_stdio.py:310: AssertionError
--------------------------------------------------------------- Captured stdout call ----------------------------------------------------------------