docs: fix docstrings across public API surface (#2095)

src/mcp/server/auth/handlers/revoke.py

@@ -15,7 +15,7 @@ from mcp.server.auth.provider import AccessToken, OAuthAuthorizationServerProvid
 
 
 class RevocationRequest(BaseModel):
-    """# See https://datatracker.ietf.org/doc/html/rfc7009#section-2.1"""
+    """See https://datatracker.ietf.org/doc/html/rfc7009#section-2.1"""
 
     token: str
     token_type_hint: Literal["access_token", "refresh_token"] | None = None

src/mcp/server/auth/middleware/client_auth.py

@@ -19,15 +19,17 @@ class AuthenticationError(Exception):
 class ClientAuthenticator:
     """ClientAuthenticator is a callable which validates requests from a client
     application, used to verify /token calls.
+
     If, during registration, the client requested to be issued a secret, the
     authenticator asserts that /token calls must be authenticated with
-    that same token.
+    that same secret.
+
     NOTE: clients can opt for no authentication during registration, in which case this
     logic is skipped.
     """
 
     def __init__(self, provider: OAuthAuthorizationServerProvider[Any, Any, Any]):
-        """Initialize the dependency.
+        """Initialize the authenticator.
 
         Args:
             provider: Provider to look up client information
@@ -83,7 +85,7 @@ class ClientAuthenticator:
 
         elif client.token_endpoint_auth_method == "client_secret_post":
             raw_form_data = form_data.get("client_secret")
-            # form_data.get() can return a UploadFile or None, so we need to check if it's a string
+            # form_data.get() can return an UploadFile or None, so we need to check if it's a string
             if isinstance(raw_form_data, str):
                 request_client_secret = str(raw_form_data)
 

src/mcp/server/auth/provider.py

@@ -131,8 +131,9 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
         """
 
     async def authorize(self, client: OAuthClientInformationFull, params: AuthorizationParams) -> str:
-        """Called as part of the /authorize endpoint, and returns a URL that the client
+        """Handle the /authorize endpoint and return a URL that the client
         will be redirected to.
+
         Many MCP implementations will redirect to a third-party provider to perform
         a second OAuth exchange with that provider. In this sort of setup, the client
         has an OAuth connection with the MCP server, and the MCP server has an OAuth
@@ -151,7 +152,7 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
         |            |
         +------------+
 
-        Implementations will need to define another handler on the MCP server return
+        Implementations will need to define another handler on the MCP server's return
         flow to perform the second redirect, and generate and store an authorization
         code as part of completing the OAuth authorization step.
 
@@ -182,7 +183,7 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
             authorization_code: The authorization code to get the challenge for.
 
         Returns:
-            The AuthorizationCode, or None if not found
+            The AuthorizationCode, or None if not found.
         """
         ...
 
@@ -199,7 +200,7 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
             The OAuth token, containing access and refresh tokens.
 
         Raises:
-            TokenError: If the request is invalid
+            TokenError: If the request is invalid.
         """
         ...
 
@@ -234,18 +235,18 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
             The OAuth token, containing access and refresh tokens.
 
         Raises:
-            TokenError: If the request is invalid
+            TokenError: If the request is invalid.
         """
         ...
 
     async def load_access_token(self, token: str) -> AccessTokenT | None:
-        """Loads an access token by its token.
+        """Loads an access token by its token string.
 
         Args:
             token: The access token to verify.
 
         Returns:
-            The AuthInfo, or None if the token is invalid.
+            The access token, or None if the token is invalid.
         """
 
     async def revoke_token(
@@ -261,7 +262,7 @@ class OAuthAuthorizationServerProvider(Protocol, Generic[AuthorizationCodeT, Ref
         provided.
 
         Args:
-            token: the token to revoke
+            token: The token to revoke.
         """
 
 

src/mcp/server/auth/routes.py

@@ -25,10 +25,10 @@ def validate_issuer_url(url: AnyHttpUrl):
     """Validate that the issuer URL meets OAuth 2.0 requirements.
 
     Args:
-        url: The issuer URL to validate
+        url: The issuer URL to validate.
 
     Raises:
-        ValueError: If the issuer URL is invalid
+        ValueError: If the issuer URL is invalid.
     """
 
     # RFC 8414 requires HTTPS, but we allow loopback/localhost HTTP for testing
@@ -213,6 +213,8 @@ def create_protected_resource_routes(
         resource_url: The URL of this resource server
         authorization_servers: List of authorization servers that can issue tokens
         scopes_supported: Optional list of scopes supported by this resource
+        resource_name: Optional human-readable name for this resource
+        resource_documentation: Optional URL to documentation for this resource
 
     Returns:
         List of Starlette routes for protected resource metadata