modelcontextprotocol / modelcontextprotocol/typescript-sdk
Auth metadata discovery: fallback only triggers on 404, misses 401/403
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 13.4k
- Forks
- 2.2k
- Avg merge
- 3d 15h
- Merged PRs (30d)
- 4
Description
Bug Description
In the OAuth metadata discovery code (discoverOAuthProtectedResourceMetadata / discoverAuthorizationServerMetadata in client/auth.ts), the client tries the path-inserted well-known URL first, then falls back to the root well-known URL — but the fallback only triggers on HTTP 404.
Servers behind CDNs / bot protection often answer unknown paths with 401 or 403 instead of 404. In those cases discovery hard-fails even though the root metadata document exists and returns 200.
Steps to Reproduce
Repro A (Retool): resource https://hashnote.retool.com/mcp
GET https://hashnote.retool.com/.well-known/oauth-protected-resource/mcp→ 401GET https://hashnote.retool.com/.well-known/oauth-protected-resource→ 200- Client throws "HTTP 401 trying to load well-known OAuth metadata" instead of falling back.
Repro B (Superhuman): resource https://docs.superhuman.com/apis/mcp
GET https://id.superhuman.com/.well-known/oauth-authorization-server/apis/mcp→ 403GET https://id.superhuman.com/.well-known/oauth-authorization-server→ 200- Same hard-fail ("HTTP 403 trying to load well-known OAuth metadata").
Expected Behavior
The fallback should trigger on any 4xx (or at least 401/403 in addition to 404).
Actual Behavior
Discovery throws on 401/403 instead of trying the root well-known URL.
Environment
- Discovered via mcp-hub 4.2.1 (npm, node 24, macOS) in front of remote OAuth MCP servers.
- Local workaround confirmed: relaxing the fallback predicate from
status === 404to include 401/403 fixes both servers.
Related
Possibly related to #1946 (401 with non-Bearer WWW-Authenticate) and #2126 (non-JSON 200 fallback) — this report is about plain 401/403 statuses where the root document is valid.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in client/auth.ts at discoverOAuthProtectedResourceMetadata and discoverAuthorizationServerMetadata, where the path-inserted well-known URL is attempted before the root URL. Inspect the fallback condition and verify it handles the 401 and 403 responses described in the Retool and Superhuman reproductions. Done means discovery falls back to the root metadata URL and succeeds when that response is 200.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- authentication
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 82/100