refactor: Remove header mutation in streamable_http_client

Remove client.headers.update() call that was unnecessarily mutating
user-provided httpx.AsyncClient instances. The mutation was defensive
but unnecessary since:

1. All transport methods pass headers explicitly to httpx requests
2. httpx merges request headers with client defaults, with request
   headers taking precedence
3. HTTP requests are identical with or without the mutation
4. Not mutating respects user's client object integrity

Add comprehensive test coverage for header behavior:
- Verify client headers are not mutated after use
- Verify MCP protocol headers override httpx defaults in requests
- Verify custom and MCP headers coexist correctly in requests

All existing tests pass, confirming no behavior change to actual
HTTP requests.

Author: felixweinberger

src/mcp/client/streamable_http.py

@@ -622,9 +622,6 @@ async def streamable_http_client(
     # Create transport with extracted configuration
     transport = StreamableHTTPTransport(url, headers_dict, timeout, sse_read_timeout, auth)
 
-    # Sync client headers with transport's merged headers (includes MCP protocol requirements)
-    client.headers.update(transport.request_headers)
-
     async with anyio.create_task_group() as tg:
         try:
             logger.debug(f"Connecting to StreamableHTTP endpoint: {url}")

tests/shared/test_streamable_http.py

@@ -1891,7 +1891,7 @@ async def test_close_sse_stream_callback_not_provided_for_old_protocol_version()
 
 
 @pytest.mark.anyio
-async def test_streamablehttp_client_receives_priming_event(
+async def test_streamable_http_client_receives_priming_event(
     event_server: tuple[SimpleEventStore, str],
 ) -> None:
     """Client should receive priming event (resumption token update) on POST SSE stream."""
@@ -1902,7 +1902,7 @@ async def test_streamablehttp_client_receives_priming_event(
     async def on_resumption_token_update(token: str) -> None:
         captured_resumption_tokens.append(token)
 
-    async with streamablehttp_client(f"{server_url}/mcp") as (
+    async with streamable_http_client(f"{server_url}/mcp") as (
         read_stream,
         write_stream,
         _,
@@ -1943,7 +1943,7 @@ async def test_server_close_sse_stream_via_context(
     """Server tool can call ctx.close_sse_stream() to close connection."""
     _, server_url = event_server
 
-    async with streamablehttp_client(f"{server_url}/mcp") as (
+    async with streamable_http_client(f"{server_url}/mcp") as (
         read_stream,
         write_stream,
         _,
@@ -1964,7 +1964,7 @@ async def test_server_close_sse_stream_via_context(
 
 
 @pytest.mark.anyio
-async def test_streamablehttp_client_auto_reconnects(
+async def test_streamable_http_client_auto_reconnects(
     event_server: tuple[SimpleEventStore, str],
 ) -> None:
     """Client should auto-reconnect with Last-Event-ID when server closes after priming event."""
@@ -1980,7 +1980,7 @@ async def message_handler(
             if isinstance(message.root, types.LoggingMessageNotification):  # pragma: no branch
                 captured_notifications.append(str(message.root.params.data))
 
-    async with streamablehttp_client(f"{server_url}/mcp") as (
+    async with streamable_http_client(f"{server_url}/mcp") as (
         read_stream,
         write_stream,
         _,
@@ -2009,13 +2009,13 @@ async def message_handler(
 
 
 @pytest.mark.anyio
-async def test_streamablehttp_client_respects_retry_interval(
+async def test_streamable_http_client_respects_retry_interval(
     event_server: tuple[SimpleEventStore, str],
 ) -> None:
     """Client MUST respect retry field, waiting specified ms before reconnecting."""
     _, server_url = event_server
 
-    async with streamablehttp_client(f"{server_url}/mcp") as (
+    async with streamable_http_client(f"{server_url}/mcp") as (
         read_stream,
         write_stream,
         _,
@@ -2040,7 +2040,7 @@ async def test_streamablehttp_client_respects_retry_interval(
 
 
 @pytest.mark.anyio
-async def test_streamablehttp_sse_polling_full_cycle(
+async def test_streamable_http_sse_polling_full_cycle(
     event_server: tuple[SimpleEventStore, str],
 ) -> None:
     """End-to-end test: server closes stream, client reconnects, receives all events."""
@@ -2056,7 +2056,7 @@ async def message_handler(
             if isinstance(message.root, types.LoggingMessageNotification):  # pragma: no branch
                 all_notifications.append(str(message.root.params.data))
 
-    async with streamablehttp_client(f"{server_url}/mcp") as (
+    async with streamable_http_client(f"{server_url}/mcp") as (
         read_stream,
         write_stream,
         _,
@@ -2088,7 +2088,7 @@ async def message_handler(
 
 
 @pytest.mark.anyio
-async def test_streamablehttp_events_replayed_after_disconnect(
+async def test_streamable_http_events_replayed_after_disconnect(
     event_server: tuple[SimpleEventStore, str],
 ) -> None:
     """Events sent while client is disconnected should be replayed on reconnect."""
@@ -2104,7 +2104,7 @@ async def message_handler(
             if isinstance(message.root, types.LoggingMessageNotification):  # pragma: no branch
                 notification_data.append(str(message.root.params.data))
 
-    async with streamablehttp_client(f"{server_url}/mcp") as (
+    async with streamable_http_client(f"{server_url}/mcp") as (
         read_stream,
         write_stream,
         _,
@@ -2136,7 +2136,7 @@ async def message_handler(
 
 
 @pytest.mark.anyio
-async def test_streamablehttp_multiple_reconnections(
+async def test_streamable_http_multiple_reconnections(
     event_server: tuple[SimpleEventStore, str],
 ):
     """Verify multiple close_sse_stream() calls each trigger a client reconnect.
@@ -2156,7 +2156,7 @@ async def test_streamablehttp_multiple_reconnections(
     async def on_resumption_token(token: str) -> None:
         resumption_tokens.append(token)
 
-    async with streamablehttp_client(f"{server_url}/mcp") as (read_stream, write_stream, _):
+    async with streamable_http_client(f"{server_url}/mcp") as (read_stream, write_stream, _):
         async with ClientSession(read_stream, write_stream) as session:
             await session.initialize()
 
@@ -2216,7 +2216,7 @@ async def message_handler(
             if isinstance(message.root, types.ResourceUpdatedNotification):  # pragma: no branch
                 received_notifications.append(str(message.root.params.uri))
 
-    async with streamablehttp_client(f"{server_url}/mcp") as (
+    async with streamable_http_client(f"{server_url}/mcp") as (
         read_stream,
         write_stream,
         _,
@@ -2247,3 +2247,112 @@ async def message_handler(
             assert "http://notification_2/" in received_notifications, (
                 f"Should receive notification 2 after reconnect, got: {received_notifications}"
             )
+
+
+@pytest.mark.anyio
+async def test_streamable_http_client_does_not_mutate_provided_client(
+    basic_server: None, basic_server_url: str
+) -> None:
+    """Test that streamable_http_client does not mutate the provided httpx client's headers."""
+    # Create a client with custom headers
+    original_headers = {
+        "X-Custom-Header": "custom-value",
+        "Authorization": "Bearer test-token",
+    }
+
+    async with httpx.AsyncClient(headers=original_headers, follow_redirects=True) as custom_client:
+        # Use the client with streamable_http_client
+        async with streamable_http_client(f"{basic_server_url}/mcp", http_client=custom_client) as (
+            read_stream,
+            write_stream,
+            _,
+        ):
+            async with ClientSession(read_stream, write_stream) as session:
+                result = await session.initialize()
+                assert isinstance(result, InitializeResult)
+
+        # Verify client headers were not mutated with MCP protocol headers
+        # If accept header exists, it should still be httpx default, not MCP's
+        if "accept" in custom_client.headers:  # pragma: no branch
+            assert custom_client.headers.get("accept") == "*/*"
+        # MCP content-type should not have been added
+        assert custom_client.headers.get("content-type") != "application/json"
+
+        # Verify custom headers are still present and unchanged
+        assert custom_client.headers.get("X-Custom-Header") == "custom-value"
+        assert custom_client.headers.get("Authorization") == "Bearer test-token"
+
+
+@pytest.mark.anyio
+async def test_streamable_http_client_mcp_headers_override_defaults(
+    context_aware_server: None, basic_server_url: str
+) -> None:
+    """Test that MCP protocol headers override httpx.AsyncClient default headers."""
+    # httpx.AsyncClient has default "accept: */*" header
+    # We need to verify that our MCP accept header overrides it in actual requests
+
+    async with httpx.AsyncClient(follow_redirects=True) as client:
+        # Verify client has default accept header
+        assert client.headers.get("accept") == "*/*"
+
+        async with streamable_http_client(f"{basic_server_url}/mcp", http_client=client) as (
+            read_stream,
+            write_stream,
+            _,
+        ):
+            async with ClientSession(read_stream, write_stream) as session:
+                await session.initialize()
+
+                # Use echo_headers tool to see what headers the server actually received
+                tool_result = await session.call_tool("echo_headers", {})
+                assert len(tool_result.content) == 1
+                assert isinstance(tool_result.content[0], TextContent)
+                headers_data = json.loads(tool_result.content[0].text)
+
+                # Verify MCP protocol headers were sent (not httpx defaults)
+                assert "accept" in headers_data
+                assert "application/json" in headers_data["accept"]
+                assert "text/event-stream" in headers_data["accept"]
+
+                assert "content-type" in headers_data
+                assert headers_data["content-type"] == "application/json"
+
+
+@pytest.mark.anyio
+async def test_streamable_http_client_preserves_custom_with_mcp_headers(
+    context_aware_server: None, basic_server_url: str
+) -> None:
+    """Test that both custom headers and MCP protocol headers are sent in requests."""
+    custom_headers = {
+        "X-Custom-Header": "custom-value",
+        "X-Request-Id": "req-123",
+        "Authorization": "Bearer test-token",
+    }
+
+    async with httpx.AsyncClient(headers=custom_headers, follow_redirects=True) as client:
+        async with streamable_http_client(f"{basic_server_url}/mcp", http_client=client) as (
+            read_stream,
+            write_stream,
+            _,
+        ):
+            async with ClientSession(read_stream, write_stream) as session:
+                await session.initialize()
+
+                # Use echo_headers tool to verify both custom and MCP headers are present
+                tool_result = await session.call_tool("echo_headers", {})
+                assert len(tool_result.content) == 1
+                assert isinstance(tool_result.content[0], TextContent)
+                headers_data = json.loads(tool_result.content[0].text)
+
+                # Verify custom headers are present
+                assert headers_data.get("x-custom-header") == "custom-value"
+                assert headers_data.get("x-request-id") == "req-123"
+                assert headers_data.get("authorization") == "Bearer test-token"
+
+                # Verify MCP protocol headers are also present
+                assert "accept" in headers_data
+                assert "application/json" in headers_data["accept"]
+                assert "text/event-stream" in headers_data["accept"]
+
+                assert "content-type" in headers_data
+                assert headers_data["content-type"] == "application/json"