Clarify subject docstrings and add Context.claims

- Reword AccessToken.subject's client_credentials note to match RFC 9068
  §2.2 (sub may identify the client itself rather than being unset).
- Add Context.claims so handlers can read iss/act/etc without importing
  get_access_token and handling the raw token model.
- Document that Context.client_id reads MCP request _meta, not the OAuth
  client_id, so it isn't mistaken for the pair to Context.subject.

Author: maxisbey

src/mcp/server/auth/provider.py

@@ -47,7 +47,9 @@ class AccessToken(BaseModel):
     `sub` from a JWT (RFC 9068) or introspection response (RFC 7662). Token
     verifiers should populate this whenever an end-user is involved so request
     handlers and transports can distinguish users that share an OAuth client.
-    Conventionally unset for `client_credentials` tokens."""
+    For `client_credentials` grants there is no end-user; `sub` may then
+    identify the client itself (RFC 9068 §2.2) or be absent, depending on the
+    authorization server."""
     claims: dict[str, Any] | None = None
     """Additional verified claims (e.g. `iss`, `act`) for request handlers."""
 

src/mcp/server/mcpserver/context.py

@@ -211,7 +211,15 @@ async def log(
 
     @property
     def client_id(self) -> str | None:
-        """Get the client ID if available."""
+        """Get the client ID if available.
+
+        Note: this reads from the MCP request's `_meta` params, not from the
+        OAuth bearer token. It is unrelated to `subject` and `claims` below,
+        which come from the authenticated `AccessToken`. For the OAuth
+        `client_id`, use `get_access_token().client_id`.
+
+        TODO(maxisbey): see if this is needed otherwise remove
+        """
         return self.request_context.meta.get("client_id") if self.request_context.meta else None  # pragma: no cover
 
     @property
@@ -225,6 +233,18 @@ def subject(self) -> str | None:
         token = get_access_token()
         return token.subject if token is not None else None
 
+    @property
+    def claims(self) -> dict[str, Any] | None:
+        """Additional verified claims from the bearer token, if any.
+
+        Returns `AccessToken.claims` for the current request so handlers can
+        read values like `iss` or `act` without importing `get_access_token`
+        and handling the raw token directly. `None` when unauthenticated or
+        when the token verifier did not populate claims.
+        """
+        token = get_access_token()
+        return token.claims if token is not None else None
+
     @property
     def request_id(self) -> str:
         """Get the unique ID for this request."""

tests/server/mcpserver/auth/test_context_subject.py

@@ -1,4 +1,4 @@
-"""Context.subject reads the resource owner from the request's access token."""
+"""Context.subject and Context.claims read from the request's access token."""
 
 from mcp.server.auth.middleware.auth_context import auth_context_var
 from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
@@ -40,3 +40,27 @@ def test_subject_tracks_current_auth_context():
         auth_context_var.reset(cv_token)
 
     assert ctx.subject is None
+
+
+def test_claims_is_none_when_unauthenticated():
+    assert Context().claims is None
+
+
+def test_claims_is_none_when_token_has_no_claims():
+    user = AuthenticatedUser(AccessToken(token="t", client_id="c", scopes=[]))
+    cv_token = auth_context_var.set(user)
+    try:
+        assert Context().claims is None
+    finally:
+        auth_context_var.reset(cv_token)
+
+
+def test_claims_reads_from_access_token():
+    user = AuthenticatedUser(
+        AccessToken(token="t", client_id="c", scopes=[], claims={"iss": "https://auth.example.com"})
+    )
+    cv_token = auth_context_var.set(user)
+    try:
+        assert Context().claims == {"iss": "https://auth.example.com"}
+    finally:
+        auth_context_var.reset(cv_token)