Failed to discover OAuth metadata: MCP fixes

Failed to discover OAuth metadata

Failed to discover OAuth metadata

Where it appears: Claude Code #19454 (opens in a new tab), filed January 20, 2026, names this error during Atlassian token refresh. It does not establish a failure in every current release. Discovery can fail before login or during renewed authorization; a previously successful connection does not prove today's discovery URL is reachable.

Likely causes, ranked by the report evidence

1. Unusable discovery URL or response. Cline #14625 (opens in a new tab) records authorization metadata returning 404. Check the status, content type and body at each requested URL; HTML from a login gateway is not metadata JSON.
2. Refresh or cached issuer configuration. The Claude Code report puts refresh first in its reproduction. Compare a fresh authorization with the failing stored connection. Success only after reconnecting suggests saved configuration or refresh state; it does not prove the server is fixed.
3. The document exists but cannot be read or validated. The authorization specification (opens in a new tab) requires discovery and issuer validation. Compare the advertised issuer with the JSON issuer; for a browser, inspect CORS and whether the challenge header is exposed.

These are qualitative priorities from the linked reports, not measured prevalence across all clients.

Fix for client users

Use the publisher's full remote endpoint. Capture the failing metadata request's URL, status and redacted response. Reconnect through the client's supported authentication controls and compare the new exchange with the old one. If a fresh login works but refresh fails later, include that distinction in the bug report. Repeating login cannot repair a metadata URL that returns 404.

Do not substitute a random issuer, disable issuer checks or share credentials. If metadata loads and the next error mentions registration, follow dynamic client registration. If the JSON resource differs from the endpoint, use the resource mismatch guide.

Fix for server authors

Publish protected-resource metadata for the public endpoint and point its authorization_servers to the actual issuer. Return a challenge such as this on an unauthenticated request:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp"

Follow the specification's path-aware discovery rules for issuers mounted below the origin. Ensure well-known routes reach the metadata handler through the public proxy and return JSON without a browser login or cookie. Verify both initial authorization and refresh against the same intended resource. This is identity-provider and routing configuration; changing a TypeScript or Python tool handler will not repair it.

Check with mcptest

Enter the full endpoint in Test your server, then inspect the OAuth discovery requests. The OAuth pre-login troubleshooting reference covers missing discovery and issuer mismatches. There is no transport diagnostic id specifically for this string. A browser-only failure may also expose missing CORS headers; that finding alone does not establish an issuer problem. Verify refresh separately after a successful login.