Improve OAuth error messages with custom handlers and middleware #2221
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
OAuth Proxy authentication errors now show styled HTML error pages in browsers instead of raw JSON, with content negotiation for API clients. Enhanced error messages explain common causes (ephemeral storage, server restarts) and provide clear remediation steps. Changes: - Created enhanced authorization handler that extends SDK's AuthorizationHandler - Created enhanced auth middleware that extends SDK's RequireAuthMiddleware - HTML error pages use server branding (icon, name) from FastMCP instance - Added comprehensive troubleshooting section to OAuth Proxy docs - Added FAQ entry linking to detailed troubleshooting
Tests cover: - HTML error pages for browser requests with server branding - Enhanced JSON responses with registration endpoint hints - Content negotiation between HTML and JSON - Enhanced middleware error messages for invalid_token - WWW-Authenticate header format consistency with SDK
marvin-context-protocol
bot
added
enhancement
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
OAuth error messages are now clearer and more actionable by introducing custom authorization handlers and authentication middleware that wrap the MCP SDK defaults.
When clients encounter authentication errors (unregistered client ID, invalid tokens), they now receive:
Browser users: Styled HTML error pages with step-by-step recovery instructions
API clients: JSON responses with helpful context and registration endpoint hints
Example JSON error:
{ "error": "invalid_request", "error_description": "Client ID 'xxx' is not registered with this server. MCP clients should automatically re-register...", "registration_endpoint": "https://server.com/register" }The implementations use content negotiation to serve appropriate formats and maintain full OAuth 2.1 compliance.