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 to ClientSession.call_tool()
• 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 modelcontextprotocol/python-sdk#1509 and supports multi-tenant scenarios where different requests require different authentication tokens or contextual headers.

Future work (as part of this PR) will extend extra_headers support to other ClientSession methods (get_prompt, read_resource, etc.) based on maintainer feedback.

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)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to change)
• [ ] Documentation update

Checklist

• [x] I have read the MCP Documentation
• [x] My code follows the repository's style guidelines
• [x] New and existing tests pass locally
• [x] I have added appropriate error handling
• [x] 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.