feat(mcp): return browser-friendly hello page for GET /mcp from browsers#40309
Draft
aminghadersohi wants to merge 4 commits into
Draft
feat(mcp): return browser-friendly hello page for GET /mcp from browsers#40309aminghadersohi wants to merge 4 commits into
aminghadersohi wants to merge 4 commits into
Conversation
When a browser opens the MCP endpoint (Accept: text/html without application/json or text/event-stream), return a 200 HTML page explaining what the endpoint is and how to configure it in Claude Desktop, Claude Code, or Cursor. API and SSE clients continue to receive the existing JSON 401 response unchanged. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
✅ Deploy Preview for superset-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #40309 +/- ##
==========================================
- Coverage 64.15% 64.10% -0.05%
==========================================
Files 2591 2591
Lines 138214 138357 +143
Branches 32056 32078 +22
==========================================
+ Hits 88671 88698 +27
- Misses 48013 48127 +114
- Partials 1530 1532 +2
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
…HEAD - Introduce MCPJWTVerifier(JWTVerifier) base class that registers _auth_error_handler as the Starlette on_error callback; previously the callback was only wired inside DetailedJWTVerifier (MCP_JWT_DEBUG_ERRORS=True), so the HTML page was never shown in the default configuration - mcp_config.py non-debug path now uses MCPJWTVerifier instead of bare JWTVerifier; DetailedJWTVerifier inherits MCPJWTVerifier - Add _prefers_browser_html() helper: checks method (GET/HEAD only) and Accept header (case-insensitive); prevents POST/OPTIONS with text/html from incorrectly receiving a 200 HTML response - Rename _json_auth_error_handler -> _auth_error_handler, return type narrowed to Response (Starlette base class, matching on_error signature) - Add tests: POST+text/html -> 401, HEAD+text/html -> 200, uppercase Accept Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The PR renamed _json_auth_error_handler to _auth_error_handler in jwt_verifier.py (to reflect that it now returns HTML for browsers rather than always JSON), but test_jwt_verifier.py still imported the old name, causing a collection-time ImportError that failed all unit tests.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
SUMMARY
When a user navigates to the MCP server URL in a browser, they currently see a raw JSON 401 error (
{"error": "invalid_token", "error_description": "Authentication failed"}). This confuses users who don't realize they need to configure an MCP client — they think the server is broken and file support tickets.This PR detects browser requests by inspecting the
Acceptheader: if it containstext/htmland does not containapplication/jsonortext/event-stream, a friendly 200 HTML page is returned instead. The page explains:All programmatic MCP clients (which always send
application/jsonortext/event-stream) are completely unaffected — they continue to receive the existing JSON 401.Implementation:
_json_auth_error_handler()insuperset/mcp_service/jwt_verifier.py— the Starletteon_errorcallback forAuthenticationMiddleware— already receives theHTTPConnectionwith headers, making this a minimal, surgical change.BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF
Before:
{"error": "invalid_token", "error_description": "Authentication failed"}(401)After: Clean HTML page with "Superset MCP Server" heading, explanation blurb, ready-to-paste JSON config block for MCP clients, and supported clients list.
TESTING INSTRUCTIONS
superset run-mcp-serverhttp://localhost:5008/mcp/in a browser — you should see the friendly HTML pagecurl -H "Accept: application/json" http://localhost:5008/mcp/— should still return JSON 401pytest tests/unit_tests/mcp_service/test_jwt_verifier_browser_hello.py -vADDITIONAL INFORMATION