Enhancement: enhance resource metadata discovery URLs for mounted starlette app

[abneetwats24]

Summary: Add a discovery client and related support for mounted application resource metadata to enable discovery of mounted app resources by clients. This change implements the client-side helper utilities and wiring needed to query and surface metadata for mounted app resources, plus accompanying tests and examples demonstrating usage.

Motivation and Context

• Motivation: Consumers of the SDK need a reliable way to discover metadata for mounted application resources so they can enumerate, inspect, and interact with resources provided by mounted apps. Previously this metadata was not discoverable through the client surface in a consistent way, which made building integrations and tooling harder.
• Context: This change implements a discovery client and related helpers that expose mounted app resource metadata in a consistent, typed form. It is driven by the feature work tracked in issue OAuthClientProvider add prefix url for MCP Starlette Mounted endpoints to correctly route .well-known metadata discovery #1751.

How Has This Been Tested?

• Unit tests: Updated unit tests covering the new discovery client behavior, response parsing, and error handling.
• CI: Updated tests are compatible with the existing CI; all tests pass locally prior to this PR.

Breaking Changes

• Breaking changes: None — this is an additive change. Existing client APIs are preserved; the discovery client and helpers are new additions and do not change existing method signatures or runtime behavior for current consumers.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

• Related issue: OAuthClientProvider add prefix url for MCP Starlette Mounted endpoints to correctly route .well-known metadata discovery #1751
• Implementation notes: The change adds a small, focused client API for discovery and keeps response models typed and validated to help downstream code rely on stable shapes. Error cases are surfaced as specific exceptions to make retry and fallback strategies easier for integrators.

[maxisbey]

Thanks for the PR! I don't think this is the right fix though - the issue is actually on the server side, not the client.

Per RFC 9728, the .well-known URI should be inserted between the host and the path - so for https://example.com/hr-policy/mcp the metadata should be at https://example.com/.well-known/oauth-protected-resource/hr-policy/mcp, not https://example.com/hr-policy/.well-known/oauth-protected-resource.

The problem is that when you mount a Starlette app, it prefixes all routes including the .well-known ones, which puts them in the wrong place. That's a server-side issue we'd need to fix there rather than having the client guess at non-spec-compliant URLs.

Going to close this but happy to discuss further on #1751 if you want to explore server-side fixes!

_{AI Disclaimer}