fix(mcp/http): advertise Bearer scheme on 401 (RFC 6750)#22
Merged
Conversation
Without `WWW-Authenticate: Bearer realm="..."` on 401 responses, MCP clients like `mcp-remote` fall back to OAuth discovery, probe `/.well-known/oauth-authorization-server`, hit a 404 with plain-text "Not Found", and surface a misleading JSON parse error to the user. We use static API-key auth, not OAuth. Advertising the bearer scheme tells spec-compliant clients to send the static Bearer token they already have and skip OAuth discovery entirely. Applied on both the SSE and Streamable HTTP 401 paths. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
WWW-Authenticate: Bearer realm="zernio-mcp"on 401, MCP clients likemcp-remoteinterpret the 401 as "OAuth required" and probe/.well-known/oauth-authorization-server. That 404s with plain-text "Not Found" and surfaces to the user asHTTP 404: Invalid OAuth error response: SyntaxError: Unexpected token 'N', 'Not Found' is not valid JSON.handle_sse) and the Streamable HTTP wrapper (_send_json_error, used byStreamableHTTPAuthHandler).Why this surfaced
A Windows user (Claude Desktop +
mcp-remote) reportedHTTP 404: Invalid OAuth error responseeven after pasting our documentedmcp-remoteconfig. The root cause was a missing Authorization header (env-var indirection broken on Windows), but the 404 came from thisWWW-Authenticategap. Fixing it means even malformed bearer setups fail cleanly with the "Missing API key" JSON we already return, instead of leading clients into an OAuth-discovery dead end.Test plan
curl -i https://mcp.zernio.com/mcpreturns401withWWW-Authenticate: Bearer realm="zernio-mcp"curl -i https://mcp.zernio.com/ssereturns the samecurl -i -H 'Authorization: Bearer not-a-real-key' https://mcp.zernio.com/mcpreturns401 {"error":"Invalid API key"}with the same headernpx mcp-remote@latest https://mcp.zernio.com/mcp --header "Authorization: Bearer sk_<real_key>"connects and lists tools without OAuth-discovery noise🤖 Generated with Claude Code