Return None from Context.headers when the request object has no headers

A custom request type on the request context is not required to expose
headers; reading them through a blind cast raised AttributeError. Use
getattr with a None fallback and drop the now-unused protocol.

Author: maxisbey

src/mcp/server/mcpserver/context.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Iterable, Mapping
-from typing import TYPE_CHECKING, Any, Generic, Protocol, cast
+from typing import TYPE_CHECKING, Any, Generic, cast
 
 from mcp_types import ClientCapabilities, InputResponseRequestParams, InputResponses, LoggingLevel
 from pydantic import AnyUrl, BaseModel
@@ -22,11 +22,6 @@
     from mcp.server.mcpserver.server import MCPServer
 
 
-class _HasHeaders(Protocol):
-    @property
-    def headers(self) -> Mapping[str, str]: ...
-
-
 class Context(BaseModel, Generic[LifespanContextT, RequestT]):
     """Context object providing access to MCP capabilities.
 
@@ -226,12 +221,11 @@ def client_id(self) -> str | None:
     def headers(self) -> Mapping[str, str] | None:
         """Request headers carried by this message, when the transport has them.
 
-        Populated by HTTP-based transports; `None` on stdio.
+        Populated by HTTP-based transports; `None` on stdio or when the
+        transport's request object carries no headers. Headers are
+        client-supplied input - never treat one as an identity assertion.
         """
-        request = self.request_context.request
-        if request is None:
-            return None
-        return cast("_HasHeaders", request).headers
+        return cast("Mapping[str, str] | None", getattr(self.request_context.request, "headers", None))
 
     @property
     def request_id(self) -> str:

tests/server/mcpserver/test_server.py

@@ -1823,6 +1823,12 @@ def test_context_headers_is_none_without_request():
     assert ctx.headers is None
 
 
+def test_context_headers_is_none_when_request_carries_no_headers():
+    """A transport may attach a custom request object that has no headers attribute."""
+    ctx = Context(request_context=_request_context(object()), mcp_server=MagicMock())
+    assert ctx.headers is None
+
+
 async def test_read_resource_template_error():
     """Template-creation failure must surface as INTERNAL_ERROR, not INVALID_PARAMS (not-found)."""
     mcp = MCPServer()