π The fast, Pythonic way to build MCP servers and clients.
Return 401 for invalid_grant token errors per MCP spec (#2800)
Jeremiah Lowin10fb217f732f
diff --git a/src/fastmcp/server/auth/auth.py b/src/fastmcp/server/auth/auth.pyindex c3bbd1b17..95f1ad3a0 100644--- a/src/fastmcp/server/auth/auth.py+++ b/src/fastmcp/server/auth/auth.py@@ -47,19 +47,19 @@ class AccessToken(_SDKAccessToken):class TokenHandler(_SDKTokenHandler):- """TokenHandler that returns OAuth 2.1 compliant error responses.+ """TokenHandler that returns MCP-compliant error responses.- The MCP SDK returns `unauthorized_client` for client authentication failures.- However, per RFC 6749 Section 5.2, authentication failures should return- `invalid_client` with HTTP 401, not `unauthorized_client`.+ This handler addresses two SDK issues:- This distinction matters: `unauthorized_client` means "client exists but- can't do this", while `invalid_client` means "client doesn't exist or- credentials are wrong". Claude's OAuth client uses this to decide whether- to re-register.+ 1. Error code: The SDK returns `unauthorized_client` for client authentication+ failures, but RFC 6749 Section 5.2 requires `invalid_client` with HTTP 401.+ This distinction matters for client re-registration behavior.- This handler transforms 401 responses with `unauthorized_client` to use- `invalid_client` instead, making the error semantics correct per OAuth spec.+ 2. Status code: The SDK returns HTTP 400 for all token errors including+ `invalid_grant` (expired/invalid tokens). However, the MCP spec requires:+ "Invalid or expired tokens MUST receive a HTTP 401 response."++ This handler transforms responses to be compliant with both OAuth 2.1 and MCP specs."""async def handle(self, request: Any):@@ -85,6 +85,26 @@ class TokenHandler(_SDKTokenHandler):except (json.JSONDecodeError, AttributeError):pass # Not JSON or unexpected format, return as-is+ # Transform 400 invalid_grant -> 401 for expired/invalid tokens+ # Per MCP spec: "Invalid or expired tokens MUST receive a HTTP 401 response."+ if response.status_code == 400:+ try:+ body = json.loads(response.body)+ if body.get("error") == "invalid_grant":+ return PydanticJSONResponse(+ content=TokenErrorResponse(+ error="invalid_grant",+ error_description=body.get("error_description"),+ ),+ status_code=401,+ headers={+ "Cache-Control": "no-store",+ "Pragma": "no-cache",+ },+ )+ except (json.JSONDecodeError, AttributeError):+ pass # Not JSON or unexpected format, return as-is+return responsediff --git a/tests/server/auth/test_oauth_proxy.py b/tests/server/auth/test_oauth_proxy.pyindex 2ea80a164..631bd61cc 100644--- a/tests/server/auth/test_oauth_proxy.py+++ b/tests/server/auth/test_oauth_proxy.py@@ -1303,24 +1303,60 @@ class TestTokenHandlerErrorTransformation:assert response.status_code == 400assert b'"error":"unauthorized_client"' in response.body- def test_does_not_transform_other_errors(self):- """Test that other error types pass through unchanged."""+ async def test_transforms_invalid_grant_to_401(self):+ """Test that invalid_grant errors return 401 per MCP spec.++ Per MCP spec: "Invalid or expired tokens MUST receive a HTTP 401 response."+ The SDK incorrectly returns 400 for all TokenErrorResponse including invalid_grant.+ """+ from unittest.mock import AsyncMock, patch++ from mcp.server.auth.handlers.token import TokenHandler as SDKTokenHandler++ from fastmcp.server.auth.auth import TokenHandler++ handler = TokenHandler(provider=Mock(), client_authenticator=Mock())++ # Create a mock 400 response like the SDK returns for invalid_grant+ mock_response = Mock()+ mock_response.status_code = 400+ mock_response.body = (+ b'{"error":"invalid_grant","error_description":"refresh token has expired"}'+ )++ # Patch the parent class's handle() to return our mock response+ with patch.object(+ SDKTokenHandler,+ "handle",+ new_callable=AsyncMock,+ return_value=mock_response,+ ):+ response = await handler.handle(Mock())++ # Should transform to MCP-compliant 401 response+ assert response.status_code == 401+ assert b'"error":"invalid_grant"' in response.body+ assert b'"error_description":"refresh token has expired"' in response.body++ def test_does_not_transform_other_400_errors(self):+ """Test that non-invalid_grant 400 errors pass through unchanged."""from mcp.server.auth.handlers.token import TokenErrorResponsefrom fastmcp.server.auth.auth import TokenHandlerhandler = TokenHandler(provider=Mock(), client_authenticator=Mock())+ # Test with invalid_request error (should stay 400)error_response = TokenErrorResponse(- error="invalid_grant",- error_description="Authorization code has expired",+ error="invalid_request",+ error_description="Missing required parameter",)response = handler.response(error_response)- # Should pass through unchanged+ # Should pass through unchanged as 400assert response.status_code == 400- assert b'"error":"invalid_grant"' in response.body+ assert b'"error":"invalid_request"' in response.bodyclass TestErrorPageRendering: