modelcontextprotocol / modelcontextprotocol/typescript-sdk

Auth metadata discovery: fallback only triggers on 404, misses 401/403

Open Beginner friendly
#2,783 1 comment 0 reactions 0 assignees View on GitHub

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

  1. GET https://hashnote.retool.com/.well-known/oauth-protected-resource/mcp → 401
  2. GET https://hashnote.retool.com/.well-known/oauth-protected-resource → 200
  3. 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

  1. GET https://id.superhuman.com/.well-known/oauth-authorization-server/apis/mcp → 403
  2. GET https://id.superhuman.com/.well-known/oauth-authorization-server → 200
  3. 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 === 404 to 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.