Skip to content

Implement MCP well-known URI fallback for Protected Resource Metadata discovery #2526

@theJC

Description

@theJC

ToolHive does not fully implement the MCP specification's Protected Resource Metadata Discovery Requirements. The MCP specification requires clients to support two discovery mechanisms for detecting authentication requirements, but ToolHive currently only implements one.

Current Behavior

ToolHive only checks for authentication requirements via the WWW-Authenticate header in 401 responses. When a server returns 401 without this header, ToolHive assumes no authentication is required and connection attempts fail.

Expected Behavior (Per MCP Specification)

According to the MCP Authorization Specification, clients MUST support both discovery mechanisms:

  1. WWW-Authenticate Header (currently implemented ✅)
  2. Well-Known URI Fallback (NOT implemented ❌)

When no WWW-Authenticate header is present, clients must attempt to discover metadata via well-known URIs in this priority order:

  1. Endpoint-specific: https://example.com/.well-known/oauth-protected-resource/<endpoint-path>
  2. Root-level: https://example.com/.well-known/oauth-protected-resource

Impact

This gap prevents ToolHive from working with MCP-compliant servers that implement RFC 9728 well-known URI discovery but don't send WWW-Authenticate headers. These servers are following the MCP specification correctly, but ToolHive cannot authenticate with them.

Example: Servers that serve resource metadata at /.well-known/oauth-protected-resource per RFC 9728 Section 3 are currently unsupported.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions