aminghadersohi opened a new pull request, #40309:
URL: https://github.com/apache/superset/pull/40309
### 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 `Accept` header: if it
contains `text/html` and does **not** contain `application/json` or
`text/event-stream`, a friendly 200 HTML page is returned instead. The page
explains:
- This is an MCP API endpoint, not a web page
- How to configure it in Claude Desktop, Claude Code, or Cursor
- What credentials are needed
All programmatic MCP clients (which always send `application/json` or
`text/event-stream`) are completely unaffected — they continue to receive the
existing JSON 401.
Implementation: `_json_auth_error_handler()` in
`superset/mcp_service/jwt_verifier.py` — the Starlette `on_error` callback for
`AuthenticationMiddleware` — already receives the `HTTPConnection` with
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
1. Start the MCP server: `superset run-mcp-server`
2. Open `http://localhost:5008/mcp/` in a browser — you should see the
friendly HTML page
3. `curl -H "Accept: application/json" http://localhost:5008/mcp/` — should
still return JSON 401
4. Run unit tests: `pytest
tests/unit_tests/mcp_service/test_jwt_verifier_browser_hello.py -v`
### ADDITIONAL INFORMATION
- [ ] Has associated issue:
- [ ] Required feature flags:
- [ ] Changes UI
- [ ] Includes DB Migration
- [x] Introduces new feature or API
- [ ] Removes existing feature or API
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
