Research guide · MCP authorization
MCP OAuth 401/403 troubleshooting
MCP authorization failures often look like one OAuth problem even when they happen at different layers. A 401 can mean the client has not discovered the protected resource correctly or is presenting a bad token; a 403 can mean the token is valid but does not carry enough permission. Debug the discovery chain, resource binding and scope challenge separately before changing security policy.
Published 12 September 2026 · sources checked 12 September 2026
401
authorization required or token invalid
403
invalid scopes or insufficient permissions
RFC 9728
protected-resource discovery used by MCP authorization
First principle
The MCP server is a protected resource, not automatically the token issuer
In the MCP authorization model, the HTTP MCP server acts as an OAuth resource server. It validates access tokens. The authorization server handles user authorization and token issuance, and it may live on another origin. Protected Resource Metadata is the bridge that tells a client which authorization server protects a particular MCP resource.
That separation matters during debugging. If a client guesses authorization endpoints from the MCP hostname, skips the protected-resource document, or obtains a token for a neighboring API audience, browser authorization can appear successful while the MCP request still fails.
Diagnostic sequence
Eight checks from the failing MCP URL to the final operation
1
Reproduce the exact MCP request
Use the same MCP URL, transport and operation that fails. A token that works against a neighboring API or a root URL does not prove it is valid for the MCP resource path.
2
Read the 401 challenge before guessing
Inspect WWW-Authenticate. Current MCP authorization guidance requires clients to use Protected Resource Metadata and to follow resource_metadata from the challenge when it is present.
3
Fetch and validate Protected Resource Metadata
Confirm the metadata document returns the expected resource identifier and at least one authorization server. If the MCP resource has a path, do not assume the metadata lives only at the origin root.
4
Verify the authorization-server discovery chain
Fetch the authorization server metadata from the issuer advertised by the protected resource. Keep resource server and authorization server roles separate; they can be hosted on different origins.
5
Bind the authorization request to the right resource
Where RFC 8707 resource indicators are used, request authorization for the MCP protected resource rather than a generic neighboring API. invalid_target is a signal to inspect that resource value, not to disable audience checks.
6
Check token audience and expiry locally
For JWT access tokens, inspect non-secret claims locally and verify the intended audience/resource, issuer and expiry against server policy. Do not paste live bearer tokens into public debuggers, tickets or support threads.
7
Treat 403 as a permission problem
Current MCP guidance uses 403 for invalid scopes or insufficient permissions. If WWW-Authenticate says insufficient_scope, request only the challenged scopes and repeat authorization instead of blindly retrying the same token.
8
Retest the MCP operation, not just OAuth
A browser callback or token response is an intermediate success. Finish by calling initialize or the exact tool/resource operation and verify that the server accepts the token and required scope.
401 path
Start with WWW-Authenticate and resource_metadata
RFC 9728 lets a protected resource return a resource_metadata URL in WWW-Authenticate. Current MCP authorization guidance says clients must use that URL when present and otherwise fall back to the well-known Protected Resource Metadata locations. This is especially important for MCP endpoints mounted below a path such as /mcp or /v1/mcp.
403 path
A valid token can still be too weak
MCP's current authorization guidance distinguishes invalid-token failures from insufficient permission. For runtime scope step-up, a server should return 403 with error="insufficient_scope" plus the scopes needed for the operation. Reauthorize for the challenged permission instead of looping the same token.
Path-aware metadata
A root well-known URL is not always the right protected-resource document
RFC 9728 supports resource identifiers that include paths. For a resource such as https://example.com/mcp, the path-aware metadata location can be https://example.com/.well-known/oauth-protected-resource/mcp. The safest client behavior is to use the exact resource_metadata URL from the challenge when supplied and validate that the returned resource identifier matches the protected resource.
This is not theoretical interoperability trivia. Public MCP integration reports have shown clients failing when they ignore the challenge URL and probe only the root well-known path, and servers failing when they omit RFC 9728 discovery despite otherwise working OAuth endpoints.
Resource indicators
invalid_target is a resource-binding clue
RFC 8707 defines the OAuth resource parameter so a client can identify the protected resource for which it wants access. It also defines invalid_target when the requested resource is invalid, missing, unknown or malformed, or when the resource/scope combination is unacceptable.
If that error appears during MCP authorization, compare the canonical MCP resource identifier, the resource value in Protected Resource Metadata, the resource indicator sent to the authorization or token endpoint, and the audience the resource server expects. Do not work around the failure by accepting tokens minted for arbitrary audiences.
Scope step-up
OAuth login succeeded, but initialize still returns 403
Treat browser authorization and MCP operation authorization as two different checkpoints. A client can complete the callback, store a valid token and then receive 403 when initialize or a tool invocation needs a scope the token does not contain.
A recent Codex MCP report reproduces exactly that pattern: OAuth succeeds, then the remote documentation server returns 403 during initialize. Current MCP guidance defines scope-challenge handling so clients can inspect the WWW-Authenticate response and request the minimum additional scopes rather than hiding the HTTP error or retrying indefinitely.
Security boundary
Do not fix OAuth interoperability by weakening token checks
Resource and audience validation prevent a token issued for one API from being replayed against another. Preserve that boundary while debugging. Validate issuer, audience/resource, expiry and scope according to your authorization-server policy, and keep production credentials out of screenshots, URLs, analytics, public issue bodies and third-party token-inspection sites.
Also keep error handling bounded. A 401 should trigger discovery or reauthorization only when the challenge supports it; a 403 should trigger scope step-up only when the server actually identifies insufficient scope. Repeating the same request with the same token is not a repair strategy.
Next checks
From OAuth debugging to a trustworthy MCP connection
Verify an MCP server before connecting
Publisher, package, endpoint, tool surface, permissions and runtime checks after transport/auth works.
Make an MCP server discoverable
Registry publication, domain authentication and runtime proof for publishers.
Monetize an MCP server
Keep authentication, authorization and payment challenges as separate controls.
Inspect zFinia machine services
Human-readable catalogue with routes into the live OpenAPI and MCP surfaces.
Source note
This guide uses the current MCP authorization specification together with RFC 9728 and RFC 8707, then checks those rules against current public interoperability reports. Public issue reports demonstrate real failure modes but are not themselves protocol authority; the MCP specification and referenced RFCs control normative behavior.