Stamp and validate Mcp-Name on tasks/* requests (SEP-2663 routing headers)

SEP-2663 mandates Mcp-Name: <taskId> on tasks/get, tasks/update, and
tasks/cancel Streamable HTTP POSTs. Adding the three methods to
NAME_BEARING_METHODS covers both ends at once: the client's modern
header stamp emits the header automatically and the server's validation
ladder rejects a mismatched or absent value. On a server without the
tasks extension a header-bearing tasks/* request still reaches -32601
method dispatch, while a headerless one fails the header rung first,
consistent with the SEP-2243 header rules; a test pins the ordering.

Author: maxisbey

src/mcp/shared/inbound.py

@@ -61,7 +61,7 @@
 """Canonical lowercase name of the HTTP header carrying the JSON-RPC method."""
 
 MCP_NAME_HEADER: Final = "mcp-name"
-"""Canonical lowercase name of the HTTP header carrying the resource name (tool/prompt/resource URI)."""
+"""Canonical lowercase name of the HTTP header carrying the resource name (tool/prompt name, resource URI, task id)."""
 
 X_MCP_HEADER_KEY: Final = "x-mcp-header"
 """JSON-Schema property annotation that designates an `Mcp-Param-*` HTTP header."""
@@ -71,9 +71,16 @@
         "tools/call": "name",
         "prompts/get": "name",
         "resources/read": "uri",
+        "tasks/get": "taskId",
+        "tasks/update": "taskId",
+        "tasks/cancel": "taskId",
     }
 )
-"""Method → params key whose value is mirrored as the `Mcp-Name` HTTP header.
+"""Method → wire params key whose value is mirrored as the `Mcp-Name` HTTP header.
+
+The first three rows are SEP-2243; the `tasks/*` rows are SEP-2663 §Streamable
+HTTP: Routing Headers, which mandates `Mcp-Name: <taskId>` so intermediaries can
+route task requests to the server instance holding the task's state.
 
 Shared by client emit (which header to send) and server validate (which body
 field to compare against), so both ends agree on the field by construction.

tests/server/test_streamable_http_modern.py

@@ -316,6 +316,27 @@ async def test_handle_modern_request_rejects_mismatched_name_header_with_400_and
     assert response.json()["error"]["code"] == HEADER_MISMATCH
 
 
+async def test_tasks_request_without_tasks_extension_fails_header_rung_before_method_dispatch() -> None:
+    """Pins the SEP-2243 rung ordering for the SEP-2663 routing headers: `tasks/get` is
+    name-bearing (`Mcp-Name` MUST carry `params.taskId` per SEP-2663 §Streamable HTTP: Routing
+    Headers), and the header rung runs before method dispatch. On a server WITHOUT the tasks
+    extension, a request whose `Mcp-Name` agrees with the body reaches dispatch and is answered
+    METHOD_NOT_FOUND at HTTP 404; one with `Mcp-Name` absent is rejected HEADER_MISMATCH at
+    HTTP 400 without dispatch ever seeing the method."""
+    body = _list_tools_body()
+    body["method"] = "tasks/get"
+    body["params"]["taskId"] = "task-123"
+    async with _asgi_client(Server("test")) as http:
+        with_name = await http.post(
+            "/mcp", json=body, headers={MCP_METHOD_HEADER: "tasks/get", MCP_NAME_HEADER: "task-123"}
+        )
+        without_name = await http.post("/mcp", json=body, headers={MCP_METHOD_HEADER: "tasks/get"})
+    assert with_name.status_code == 404
+    assert with_name.json()["error"]["code"] == METHOD_NOT_FOUND
+    assert without_name.status_code == 400
+    assert without_name.json()["error"]["code"] == HEADER_MISMATCH
+
+
 # --- SSE response mode ---------------------------------------------------------
 
 

tests/server/test_tasks.py

@@ -6,14 +6,19 @@
 envelope have non-spec shapes, so the raw wire dict is read with a permissive
 `dict` result type. Determinism comes from an injected fixed `clock`; task ids
 are random `task_<token>` bearer capabilities, so they are captured and reused
-for identity rather than snapshotted.
+for identity rather than snapshotted. The one exception to the in-memory rule is
+the SEP-2663 routing-header test, which drives the in-process HTTP bridge because
+the `Mcp-Name` header only exists at the HTTP seam.
 """
 
+import json
 from collections.abc import Awaitable, Callable
 from datetime import datetime, timedelta, timezone
 from types import SimpleNamespace
 from typing import Any, Literal, cast
 
+import anyio
+import httpx
 import mcp_types as types
 import pytest
 from inline_snapshot import snapshot
@@ -28,6 +33,7 @@
 from pydantic import BaseModel, TypeAdapter
 
 from mcp.client.client import Client
+from mcp.client.streamable_http import streamable_http_client
 from mcp.server.context import CallNext, HandlerResult, ServerRequestContext
 from mcp.server.extension import Extension
 from mcp.server.mcpserver import MCPServer
@@ -45,6 +51,7 @@
 )
 from mcp.shared.exceptions import MCPError
 from mcp.shared.tasks import CancelTaskRequest, GetTaskRequest, GetTaskResult, UpdateTaskRequest
+from tests.interaction._connect import BASE_URL, mounted_app
 
 pytestmark = pytest.mark.anyio
 
@@ -639,6 +646,49 @@ async def test_tasks_result_method_is_method_not_found() -> None:
     assert exc_info.value.code == METHOD_NOT_FOUND
 
 
+async def test_tasks_requests_over_streamable_http_carry_mcp_name_routing_header() -> None:
+    """SEP-2663 §Streamable HTTP: Routing Headers: when `tasks/get`, `tasks/update`, or
+    `tasks/cancel` is sent over Streamable HTTP, "the client MUST set the `Mcp-Name` header
+    (defined by SEP-2243) to the value of `params.taskId`" so intermediaries can route the
+    request to the instance holding the task's state.
+
+    The session's modern stamp reads `NAME_BEARING_METHODS`, so the typed `tasks/*` wrappers
+    sent through `client.session.send_request` are stamped with no tasks-specific client code.
+    Asserted at the wire via the `mounted_app` request hook because the client never exposes
+    outgoing headers; each call also round-trips successfully, so the stamped value passes the
+    server's header-mismatch rung end to end."""
+    posts: list[httpx.Request] = []
+
+    async def on_request(request: httpx.Request) -> None:
+        posts.append(request)
+
+    captured: list[str] = []
+    with anyio.fail_after(5):
+        async with (
+            mounted_app(_tasks_server(), on_request=on_request) as (http, _),
+            Client(
+                streamable_http_client(f"{BASE_URL}/mcp", http_client=http),
+                extensions={EXTENSION_ID: {}},
+            ) as client,
+        ):
+            created = await _augmented_call(client)
+            assert isinstance(created["taskId"], str)
+            captured.append(created["taskId"])
+            await _get_task(client, created["taskId"])
+            await _update_task(client, created["taskId"])
+            await _cancel_task(client, created["taskId"])
+
+    task_id = captured[0]
+    observed = [(json.loads(request.content)["method"], request.headers.get("mcp-name")) for request in posts]
+    assert observed == [
+        ("server/discover", None),
+        ("tools/call", "echo"),
+        ("tasks/get", task_id),
+        ("tasks/update", task_id),
+        ("tasks/cancel", task_id),
+    ]
+
+
 @pytest.mark.parametrize("method", ["get", "update", "cancel"])
 async def test_tasks_methods_from_non_declaring_client_are_missing_required_capability(method: str) -> None:
     """SEP-2663: every `tasks/*` call from a modern client that did not declare the

tests/shared/test_inbound.py

@@ -202,6 +202,19 @@ def test_header_rung_rejects_missing_method_header() -> None:
     assert_rejected(classify_inbound_request(body, headers=headers), HEADER_MISMATCH)
 
 
+@pytest.mark.parametrize(
+    ("method", "name_key"),
+    [(m, k) for m, k in NAME_BEARING_METHODS.items()],
+)
+def test_header_rung_passes_matching_name_header_for_name_bearing_methods(method: str, name_key: str) -> None:
+    """Spec-mandated: an `Mcp-Name` header equal to the named body param passes rung 3 for every
+    name-bearing method — SEP-2243 for `tools/call`/`prompts/get`/`resources/read`, SEP-2663
+    §Streamable HTTP: Routing Headers for `tasks/*` (`Mcp-Name` MUST carry `params.taskId`)."""
+    body = envelope(method, extra_params={name_key: "expected"})
+    result = classify_inbound_request(body, headers=matching_headers(body))
+    assert isinstance(result, InboundModernRoute)
+
+
 @pytest.mark.parametrize(
     ("method", "name_key"),
     [(m, k) for m, k in NAME_BEARING_METHODS.items()],
@@ -340,8 +353,18 @@ def test_decode_header_value_returns_none_for_malformed_sentinel(bad: str) -> No
 
 
 def test_name_bearing_methods_table_matches_spec() -> None:
-    """Spec-mandated: pins the method → name-param table the client emit and server validate share."""
-    assert NAME_BEARING_METHODS == {"tools/call": "name", "prompts/get": "name", "resources/read": "uri"}
+    """Spec-mandated: pins the method → name-param table the client emit and server validate share.
+
+    The first three rows are SEP-2243; the `tasks/*` rows are SEP-2663 §Streamable HTTP: Routing
+    Headers ("the client MUST set the `Mcp-Name` header ... to the value of `params.taskId`")."""
+    assert NAME_BEARING_METHODS == {
+        "tools/call": "name",
+        "prompts/get": "name",
+        "resources/read": "uri",
+        "tasks/get": "taskId",
+        "tasks/update": "taskId",
+        "tasks/cancel": "taskId",
+    }
 
 
 # --- find_invalid_x_mcp_header -------------------------------------------------