shared: return None (not ValueError) for a non-ASCII base64 header

decode_header_value only caught binascii.Error, but base64.b64decode raises a
plain ValueError for a non-ASCII payload ("string argument should contain only
ASCII characters"). A raw Mcp-Name like `=?base64?\xe9?=` therefore escaped the
modern POST handler and turned into a 500 instead of the HEADER_MISMATCH
rejection the docstring promises. Same for Mcp-Param-* headers, which go
through the same function.

Catching ValueError covers both cases since binascii.Error subclasses it.

Checked with a small ASGI repro: the high-byte header now answers 400 /
-32020 like every other undecodable sentinel, and the fuzzer-shaped input no
longer reaches the server's error path.

Fixes #3817

Author: sunhouy

src/mcp/shared/inbound.py

@@ -176,7 +176,10 @@ def decode_header_value(value: str | None) -> str | None:
     payload = m.group("payload")
     try:
         decoded = base64.b64decode(payload, validate=True)
-    except binascii.Error:
+    except (binascii.Error, ValueError):
+        # b64decode raises binascii.Error for bad alphabet/padding but a plain
+        # ValueError for non-ASCII text ("string argument should contain only
+        # ASCII characters"), so a raw header with high bytes must be caught too.
         return None
     # Reject non-canonical base64 (e.g. non-zero trailing bits), which
     # `validate=True` tolerates; the encoder only ever emits canonical form.

tests/server/test_streamable_http_modern.py

@@ -444,6 +444,24 @@ async def test_handle_modern_request_rejects_mismatched_name_header_with_400_and
     assert response.json()["error"]["code"] == HEADER_MISMATCH
 
 
+async def test_handle_modern_request_rejects_non_ascii_base64_name_header_with_400() -> None:
+    """A `=?base64?...?=` payload holding raw high bytes is malformed, not a server fault: it must come
+    back as HEADER_MISMATCH, the same as any other undecodable sentinel, instead of escaping the
+    handler as a 500."""
+    body = _list_tools_body()
+    body["method"] = "tools/call"
+    body["params"]["name"] = "real"
+    body["params"]["arguments"] = {}
+    async with _asgi_client(Server("test")) as http:
+        response = await http.post(
+            "/mcp",
+            json=body,
+            headers=[(MCP_METHOD_HEADER, "tools/call"), (MCP_NAME_HEADER.encode(), b"=?base64?\xe9?=")],
+        )
+    assert response.status_code == 400
+    assert response.json()["error"]["code"] == HEADER_MISMATCH
+
+
 # --- SSE response mode ---------------------------------------------------------
 
 

tests/shared/test_inbound.py

@@ -422,7 +422,16 @@ def test_decode_header_value_passes_none_and_plain_through() -> None:
     assert decode_header_value("plain") == "plain"
 
 
-@pytest.mark.parametrize("bad", ["=?base64?not base64!?=", "=?base64?gA==?="])
+@pytest.mark.parametrize(
+    "bad",
+    [
+        "=?base64?not base64!?=",
+        "=?base64?gA==?=",
+        # Raw header bytes that are not ASCII at all: b64decode rejects these with
+        # ValueError rather than binascii.Error, and they used to escape as a 500.
+        "=?base64?\xe9?=",
+    ],
+)
 def test_decode_header_value_returns_none_for_malformed_sentinel(bad: str) -> None:
     """SDK-defined: a sentinel with bad base64 or bad UTF-8 decodes to `None`, so it can never match a body value."""
     assert decode_header_value(bad) is None