Send SEP-2243 Mcp-Method/Mcp-Name headers from the StreamableHTTP client

Per SEP-2243, MCP clients should send routing headers on POST requests so
spec-compliant servers and intermediaries can route without parsing the
JSON-RPC body. The StreamableHTTP client did not send them.

Add Mcp-Method (the JSON-RPC method, for requests and notifications) and
Mcp-Name (params.name for tools and prompts, else params.uri for resources)
to outgoing POST headers. Responses and errors, which have no method, send
neither.

Fixes #2715

Author: vidigoat

src/mcp/client/streamable_http.py

@@ -43,13 +43,37 @@
 
 MCP_SESSION_ID = "mcp-session-id"
 MCP_PROTOCOL_VERSION = "mcp-protocol-version"
+MCP_METHOD = "mcp-method"
+MCP_NAME = "mcp-name"
 LAST_EVENT_ID = "last-event-id"
 
 # Reconnection defaults
 DEFAULT_RECONNECTION_DELAY_MS = 1000  # 1 second fallback when server doesn't provide retry
 MAX_RECONNECTION_ATTEMPTS = 2  # Max retry attempts before giving up
 
 
+def _set_mcp_request_headers(headers: dict[str, str], message: JSONRPCMessage) -> None:
+    """Add SEP-2243 routing headers for an outgoing POST message.
+
+    ``Mcp-Method`` carries the JSON-RPC method for requests and notifications.
+    ``Mcp-Name`` carries the target ``params.name`` (tools, prompts) or, when
+    that is absent, ``params.uri`` (resources). JSON-RPC responses and errors,
+    which have no method, receive neither header.
+
+    See https://modelcontextprotocol.io/specification (SEP-2243).
+    """
+    if not isinstance(message, JSONRPCRequest | JSONRPCNotification):
+        return
+    headers[MCP_METHOD] = message.method
+    params = message.params
+    if params is None:
+        return
+    name = params.get("name")
+    mcp_name = name if isinstance(name, str) else params.get("uri")
+    if isinstance(mcp_name, str):
+        headers[MCP_NAME] = mcp_name
+
+
 class StreamableHTTPError(Exception):
     """Base exception for StreamableHTTP transport errors."""
 
@@ -255,6 +279,7 @@ async def _handle_post_request(self, ctx: RequestContext) -> None:
         """Handle a POST request with response processing."""
         headers = self._prepare_headers()
         message = ctx.session_message.message
+        _set_mcp_request_headers(headers, message)
         is_initialization = self._is_initialization_request(message)
 
         async with ctx.client.stream(

tests/shared/test_streamable_http.py

@@ -29,7 +29,11 @@
 
 from mcp import MCPError, types
 from mcp.client.session import ClientSession
-from mcp.client.streamable_http import StreamableHTTPTransport, streamable_http_client
+from mcp.client.streamable_http import (
+    StreamableHTTPTransport,
+    _set_mcp_request_headers,
+    streamable_http_client,
+)
 from mcp.server import Server, ServerRequestContext
 from mcp.server.streamable_http import (
     MCP_PROTOCOL_VERSION_HEADER,
@@ -2318,3 +2322,49 @@ async def test_streamable_http_client_preserves_custom_with_mcp_headers(
 
                 assert "content-type" in headers_data
                 assert headers_data["content-type"] == "application/json"
+
+
+@pytest.mark.parametrize(
+    ("message", "expected"),
+    [
+        # Request with params.name (tools/prompts) -> Mcp-Name is the name.
+        (
+            types.JSONRPCRequest(jsonrpc="2.0", id=1, method="tools/call", params={"name": "read_file"}),
+            {"mcp-method": "tools/call", "mcp-name": "read_file"},
+        ),
+        # Request with params.uri but no name (resources) -> Mcp-Name is the uri.
+        (
+            types.JSONRPCRequest(jsonrpc="2.0", id=2, method="resources/read", params={"uri": "file:///README.md"}),
+            {"mcp-method": "resources/read", "mcp-name": "file:///README.md"},
+        ),
+        # Request without params -> only Mcp-Method.
+        (
+            types.JSONRPCRequest(jsonrpc="2.0", id=3, method="initialize", params=None),
+            {"mcp-method": "initialize"},
+        ),
+        # Request whose name is not a string and has no uri -> only Mcp-Method.
+        (
+            types.JSONRPCRequest(jsonrpc="2.0", id=4, method="tools/call", params={"name": 123}),
+            {"mcp-method": "tools/call"},
+        ),
+        # Notification -> Mcp-Method, never Mcp-Name.
+        (
+            types.JSONRPCNotification(jsonrpc="2.0", method="notifications/initialized"),
+            {"mcp-method": "notifications/initialized"},
+        ),
+        # Response and error have no method -> no MCP routing headers.
+        (
+            types.JSONRPCResponse(jsonrpc="2.0", id=5, result={}),
+            {},
+        ),
+        (
+            types.JSONRPCError(jsonrpc="2.0", id=6, error=types.ErrorData(code=types.INTERNAL_ERROR, message="boom")),
+            {},
+        ),
+    ],
+)
+def test_set_mcp_request_headers(message: types.JSONRPCMessage, expected: dict[str, str]) -> None:
+    """SEP-2243: POST messages carry Mcp-Method, and Mcp-Name when a target is present."""
+    headers: dict[str, str] = {}
+    _set_mcp_request_headers(headers, message)
+    assert headers == expected