Skip to content

Conversation

@damianoneill
Copy link

@damianoneill damianoneill commented Oct 26, 2025

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 #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)
  • 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 damianoneill marked this pull request as draft October 26, 2025 10:37
@damianoneill damianoneill changed the title feat: add per-request HTTP headers support for call_tool() feat: add per-request HTTP headers support for client session methods Oct 26, 2025
@damianoneill damianoneill force-pushed the feature/per-request-headers branch from c595101 to abce375 Compare October 29, 2025 10:59
@damianoneill damianoneill marked this pull request as ready for review October 29, 2025 11:06
@damianoneill
Copy link
Author

@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
Copy link

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

Implements per-request headers functionality across all
ClientSession methods to enable multi-tenant authentication, request
tracing, A/B testing, and debugging while maintaining a single
persistent connection.

Technical Implementation:
- Headers are passed through ClientMessageMetadata to transport layer
- Per-request headers take precedence over connection-level headers
- All methods follow consistent extra_headers: dict[str, str] | None = None pattern

Addresses: modelcontextprotocol#1509
@damianoneill damianoneill force-pushed the feature/per-request-headers branch 2 times, most recently from 7068536 to 0e86471 Compare November 29, 2025 19:06
- Add test_streamablehttp_client_tool_invocation_with_extra_headers for POST requests
- Add test_streamablehttp_client_resumption_with_extra_headers for resumption with extra headers
- Refactor common resumption setup code into _setup_resumption_test helper
- Achieve 100% coverage for streamable_http.py
@damianoneill damianoneill force-pushed the feature/per-request-headers branch from 0e86471 to c17841e Compare November 29, 2025 19:09
@damianoneill
Copy link
Author

@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
Copy link
Author

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants