An unauthenticated MCP request should return 401 Unauthorized with a Bearer challenge whose resource_metadata value points to protected-resource metadata. If that pointer is absent or unreachable, later OAuth settings cannot repair discovery.
Capture the first 401
Send an unauthenticated request to the MCP resource and save the response headers. You are looking for a Bearer challenge that points the client toward protected-resource metadata. Do not begin at the authorization server dashboard; begin where the client failed.
Open the protected-resource document
Fetch the advertised metadata URL directly. Confirm that its resource identifier describes the MCP endpoint you called and that its authorization server list contains the issuer you intend to use.
{
"resource": "https://api.example.com/mcp",
"authorization_servers": [
"https://login.example.com"
],
"scopes_supported": ["mcp:tools"]
}
Follow the issuer
Open the authorization-server metadata and compare issuer, authorization endpoint and token endpoint origins. Redirects and proxy hostnames often produce the subtle mismatch: every document loads, but the identifiers disagree.
Read the chain as five separate checks
| Checkpoint | Evidence | Common failure |
|---|---|---|
| Challenge | WWW-Authenticate | Missing pointer |
| Resource | resource | Host mismatch |
| Issuer | authorization_servers | Wrong tenant |
| Client flow | PKCE methods | S256 unavailable |
| Token | Audience, scope | Wrong resource |
Check what the client can actually do
For a public client, require PKCE with S256. Confirm the requested scope is both advertised and accepted. A token minted for the wrong resource or audience may be perfectly valid and still receive 401 from the MCP server.
Do not paste client secrets or live tokens into a validator. Metadata URLs and redacted documents are enough for this check.
Use the chain view
Enter the resource URL and metadata in MCP OAuth Lab. Work from the first broken edge. Fixing later fields while the resource-to-issuer link is wrong only creates noise.
Symptom-to-fix matrix
The client never opens a browser
Inspect the initial 401. The client probably never discovered the authorization server because the metadata pointer is missing, malformed, or blocked.
Login succeeds, then the call still returns 401
Compare token audience, issuer, expiry, and granted scopes with the resource metadata. Authentication may have succeeded for the wrong resource.
It works locally but fails behind a proxy
Compare externally visible URLs with generated values. Forwarded host and protocol handling often advertises an internal hostname or http URL.
Safe debugging checklist
- Save headers and public metadata, not live tokens.
- Resolve the earliest failing URL first.
- Compare identifiers exactly.
- Require PKCE S256 for public clients.
- Retry after correcting cached metadata.
Related MCP tools
If client configuration is wrong, use the Claude-to-Codex conversion guide. Before publishing, validate the listing with the server.json Registry guide.
Expected result
The unauthenticated challenge leads to the correct resource document, that document names the correct issuer, and a PKCE authorization produces a token accepted for the MCP resource.
Trace the OAuth metadata →