fix: complete the spec's CORS header set on discovery responses

The extension spec's CORS section requires
'Access-Control-Allow-Headers: Content-Type, If-None-Match' and
'Access-Control-Expose-Headers: ETag' on hosted card and catalog
endpoints; the served responses allowed only Content-Type and exposed
nothing, which would stop a browser-based client from reading the ETag
or sending If-None-Match for a cross-origin 304 revalidation. Both the
explicit discovery_response headers and the CORSMiddleware preflight
config now emit the full set, with tests asserting the headers on the
card response and on a browser preflight requesting If-None-Match.

Author: claude

src/mcp/server/experimental/server_card.py

@@ -49,7 +49,8 @@
 _CORS_HEADERS = {
     "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET",
-    "Access-Control-Allow-Headers": "Content-Type",
+    "Access-Control-Allow-Headers": "Content-Type, If-None-Match",
+    "Access-Control-Expose-Headers": "ETag",
 }
 
 
@@ -102,14 +103,15 @@ def _cors_endpoint(handler: Callable[[Request], Awaitable[Response]]) -> ASGIApp
     The middleware short-circuits real browser preflights (OPTIONS with an
     `Origin` and a requested method), answering with `GET` as the only allowed
     method; Starlette also advertises the CORS-safelisted request headers
-    beside `Content-Type` there, a valid superset of the spec's example. A
-    bare OPTIONS still reaches `discovery_response`.
+    beside `Content-Type` and `If-None-Match` there, a valid superset of the
+    spec's example. A bare OPTIONS still reaches `discovery_response`.
     """
     return CORSMiddleware(
         app=request_response(handler),
         allow_origins=["*"],
         allow_methods=["GET"],
-        allow_headers=["Content-Type"],
+        allow_headers=["Content-Type", "If-None-Match"],
+        expose_headers=["ETag"],
     )
 
 

tests/docs_src/test_server_cards.py

@@ -52,7 +52,8 @@ async def test_mount_discovery_serves_both_endpoints_with_the_spec_headers() ->
     assert card_response.headers["content-type"] == "application/mcp-server-card+json"
     assert card_response.headers["access-control-allow-origin"] == "*"
     assert card_response.headers["access-control-allow-methods"] == "GET"
-    assert card_response.headers["access-control-allow-headers"] == "Content-Type"
+    assert card_response.headers["access-control-allow-headers"] == "Content-Type, If-None-Match"
+    assert card_response.headers["access-control-expose-headers"] == "ETag"
     assert card_response.headers["cache-control"] == "public, max-age=3600"
     assert catalog_response.headers["content-type"] == "application/ai-catalog+json"
     assert (revalidated.status_code, revalidated.content) == (304, b"")

tests/server/experimental/test_server_card.py

@@ -62,14 +62,16 @@ async def test_card_is_served_with_its_media_type_at_the_reserved_path() -> None
     assert ServerCard.model_validate_json(response.content) == card
 
 
-async def test_card_responses_carry_the_three_cors_headers() -> None:
-    """Spec-mandated MUST: `Access-Control-Allow-Origin: *`, `-Methods: GET` and
-    `-Headers: Content-Type` on the card response."""
+async def test_card_responses_carry_the_four_cors_headers() -> None:
+    """Spec-mandated MUST: `Access-Control-Allow-Origin: *`, `-Methods: GET`,
+    `-Headers: Content-Type, If-None-Match` and `Access-Control-Expose-Headers: ETag`
+    on the card response, so browser clients can revalidate cross-origin."""
     async with _client_for(Starlette(routes=create_server_card_routes(_card()))) as client:
         response = await client.get("/mcp/server-card")
     assert response.headers["access-control-allow-origin"] == "*"
     assert response.headers["access-control-allow-methods"] == "GET"
-    assert response.headers["access-control-allow-headers"] == "Content-Type"
+    assert response.headers["access-control-allow-headers"] == "Content-Type, If-None-Match"
+    assert response.headers["access-control-expose-headers"] == "ETag"
 
 
 async def test_card_responses_carry_the_default_cache_control() -> None:
@@ -90,17 +92,23 @@ async def test_options_preflight_returns_the_cors_headers_and_no_body() -> None:
 
 
 async def test_browser_preflight_through_the_cors_middleware_is_allowed() -> None:
-    """Spec-mandated: a real browser preflight (Origin plus requested method) succeeds
-    and advertises GET as the only allowed method, so web-based hosts can fetch the card
-    cross-origin. Starlette answers this one, not `discovery_response`."""
+    """Spec-mandated: a real browser preflight (Origin plus requested method) succeeds,
+    advertises GET as the only allowed method and allows the `If-None-Match` request
+    header, so web-based hosts can fetch and revalidate the card cross-origin.
+    Starlette answers this one, not `discovery_response`."""
     async with _client_for(Starlette(routes=create_server_card_routes(_card()))) as client:
         response = await client.options(
             "/mcp/server-card",
-            headers={"Origin": "https://host.example.org", "Access-Control-Request-Method": "GET"},
+            headers={
+                "Origin": "https://host.example.org",
+                "Access-Control-Request-Method": "GET",
+                "Access-Control-Request-Headers": "if-none-match",
+            },
         )
     assert response.status_code == 200
     assert response.headers["access-control-allow-origin"] == "*"
     assert response.headers["access-control-allow-methods"] == "GET"
+    assert "if-none-match" in response.headers["access-control-allow-headers"].lower()
 
 
 # -- ETag / If-None-Match ----------------------------------------------------------------