MCP Authorisation Errors Troubleshooting Guide

When a remote MCP server rejects an agent, the visible symptom is usually a vague "unauthorised" or a loop of browser sign-ins, while the real fault sits in one of six hops between the client, the MCP server and the authorisation server. The MCP authorisation specification builds on OAuth 2.1, Protected Resource Metadata (RFC 9728), Resource Indicators (RFC 8707) and Bearer token rules (RFC 6750), and each layer has its own error. This guide is a symptom-led diagnostic reference for engineers who build or operate MCP servers, clients and gateways. It maps each symptom to its likely causes, tells you where to look, and gives fixes that keep audience binding and least privilege intact. The specification itself is explained in the MCP Authorisation Specification Guide, which this page does not repeat. Requirements were checked against the 2025-11-25 revision of the specification on 11 November 2026.

Key takeaways

• 401 and 403 mean different things. The specification requires 401 for missing, invalid or expired tokens and 403 for insufficient scope or permission; 400 is for malformed authorisation requests. A server that blurs them breaks client recovery.
• Discovery failures look like authentication failures. If the client cannot find Protected Resource Metadata, or the metadata's resource value does not match the URL it called, it must stop, and users see a generic sign-in error.
• Audience mismatch is the most important error to keep. Servers must reject tokens not issued for them. Never "fix" an audience error by accepting any token from the issuer.
• Scope loops need retry limits. A 403 insufficient_scope should trigger at most a few step-up attempts; endless re-consent prompts mean the server's challenge or the authorisation server's scope policy is wrong.
• Local servers are different. The specification says STDIO transports should not follow this flow and take credentials from the environment, so a local server "auth error" is usually a missing or wrong environment credential.

Where MCP authorisation can fail

For HTTP transports the flow has six hops. Every error you will see belongs to one of them.

Work forwards from hop 1. The commonest wasted effort is reconfiguring the authorisation server (hop 5) when the MCP server never emitted a usable challenge (hop 1) or published metadata at the wrong path (hop 2).

Error and status reference

Bearer error codes come from RFC 6750 Section 3.1; OAuth endpoint errors from OAuth 2.1 and RFC 8707; MCP-specific status rules from the specification's Error Handling section.

Related OAuth endpoint errors are diagnosed in depth in the OAuth invalid_grant Error Troubleshooting Guide and the OAuth invalid_client and unauthorized_client Troubleshooting Guide.

Symptom 1: the client never starts sign-in

Likely causes, most to least common:

1. No usable challenge: the server returns 401 without resource_metadata and does not serve the well-known document either. The specification requires one of the two. Check with a plain unauthenticated request and inspect the WWW-Authenticate header.
2. Wrong status: the server returns 403 or 500 for a missing token. Clients key the discovery flow on 401, so they never begin.
3. Infrastructure rewriting: an API gateway, WAF or CDN replaces the 401 body and drops WWW-Authenticate, or the CORS policy does not expose the header to a browser-based client.
4. Transport confusion: the server is local (STDIO) and expects a credential in an environment variable; there is no OAuth flow to start.

Fix: return 401 with WWW-Authenticate: Bearer resource_metadata="https://host/.well-known/oauth-protected-resource/mcp" and a scope parameter, serve the same document at the well-known path, and allow the header through every proxy layer.

Symptom 2: metadata or discovery errors

Protected Resource Metadata

RFC 9728 inserts /.well-known/oauth-protected-resource between the host and any path. For an MCP endpoint at https://example.com/public/mcp the path form is https://example.com/.well-known/oauth-protected-resource/public/mcp; clients fall back to the root form /.well-known/oauth-protected-resource. Two rules cause most failures:

• Resource must match: the document's resource value must exactly match the identifier used to build the URL, and when the URL came from a challenge it must match the URL the client called. A document that says https://example.com for a server at /public/mcp, or uses http, is rejected.
• At least one authorisation server: the MCP specification requires authorization_servers with at least one entry.

Authorisation server metadata

For an issuer with a path such as https://auth.example.com/tenant1, clients must try, in order, /.well-known/oauth-authorization-server/tenant1, /.well-known/openid-configuration/tenant1, then /tenant1/.well-known/openid-configuration. Many identity providers serve only the last form, so a client that stops at the first 404 is non-compliant; a provider that serves none of them cannot be used.

PKCE gate: clients must refuse to continue if code_challenge_methods_supported is absent from the metadata, and authorisation servers using OpenID discovery must include it. If an otherwise working identity provider is rejected, check this field first.

Symptom 3: registration and redirect errors

Do not relax exact redirect matching to make a client work. The specification notes that a localhost redirect cannot prove which application is listening, which is why servers should warn on localhost-only clients and show the redirect host to the user.

Symptom 4: sign-in succeeds, then 401 invalid_token

This is the classic audience or validation failure. Decode the access token (if it is a JWT) in a local tool, never an online decoder, and compare:

• aud: must identify this MCP server. The client must send resource with the canonical server URI in both the authorisation and token requests. The specification prefers no trailing slash, lowercase scheme and host, and the most specific URI (for example https://mcp.example.com/mcp). A token minted for https://mcp.example.com may fail at a server that expects the /mcp form, or the reverse.
• iss: must be an issuer the server trusts, with keys in its cached JWKS. After the authorisation server rotates signing keys, servers with stale caches reject every new token. See the JSON Web Key Sets (JWKS) and Signing Key Rotation Guide.
• exp, nbf, iat: check clock skew between server and issuer. Long agent tasks often outlive short access tokens; the client must refresh. For public clients the authorisation server must rotate refresh tokens, so a client that keeps using an old refresh token gets invalid_grant.
• Header placement: the token must be in Authorization: Bearer on every HTTP request in the session and never in the query string.

Generic token claim failures are covered in the JWT Validation Errors Troubleshooting Guide.

Symptom 5: 403 insufficient_scope and consent loops

The server should answer a runtime shortfall with 403 and WWW-Authenticate: Bearer error="insufficient_scope", scope="...", resource_metadata="...". The client should treat the challenged scopes as authoritative, re-authorise, and retry only a few times. Loops have three usual causes:

1. Server drops granted scopes: the challenge lists only the new scope, so the new token loses the old one and the next tool call fails. The specification recommends including existing relevant scopes plus the new ones.
2. Policy denies silently: the authorisation server issues a token without the requested scope because the user lacks entitlement. The client asks again, gets the same token, and loops. Make the authorisation server return an error or the client compare granted with requested scopes.
3. Machine clients: a client_credentials client cannot get user consent; the specification allows it to abort. Treat the 403 as a configuration task, not a retry.

Gateways, proxies and token passthrough

An MCP server that calls upstream APIs must act as a separate OAuth client to them. The specification states the server must not pass through the token it received. Errors that appear only on upstream calls (an upstream 401 relayed to the agent) usually mean the server is forwarding the client's token, which the upstream rightly rejects because it was issued for the MCP server. The fix is a token exchange or a separate upstream credential, never widening the upstream's audience check. See the Confused Deputy in AI Agents Guide. Gateways add their own hop: check that the gateway preserves WWW-Authenticate, does not cache 401 responses, and that the canonical URI clients see is the one the authorisation server binds tokens to. The LiteLLM MCP auth bypass shows how weak token checks at a gateway expose every credential behind it.

Testing fixes and rolling back

1. Reproduce with a scripted client: send an unauthenticated request, record the challenge, fetch both metadata documents and record each response. This isolates hops 1 to 3 without a browser.
2. Use a test tenant: change scope policy, registration settings or audience configuration in a non-production authorisation server tenant first.
3. Change one hop at a time: and re-run the scripted client after each change.
4. Canary the server change: roll new challenge headers or audience rules to one instance behind the gateway and watch 401 and 403 rates.
5. Roll back on rate spikes: keep the previous metadata documents and validation configuration versioned so they can be restored quickly; never roll back by disabling validation.

Detection and measurement

Authorisation errors are also an attack signal: replayed tokens, tokens for other resources and scope probing all surface as 401 and 403.

• Log at the MCP server: status, Bearer error code, token iss, aud, client ID, subject, requested tool and the scopes required versus present. Never log the token itself.
• Log at the authorisation server: registration events, invalid_target, invalid_grant on refresh, and new CIMD client domains.
• Watch for: tokens with a foreign audience (possible reuse of a stolen token, ATT&CK T1550.001 Application Access Token), bursts of 403 across many tools from one client, and new client IDs registering redirect URIs on unfamiliar hosts.

Common failure patterns

• Accepting any token from the issuer: removing the audience check to end 401s turns the server into a target for tokens stolen from other services.
• Trailing slash drift: the client, metadata and authorisation server disagree on https://host/mcp versus https://host/mcp/.
• Returning 403 for missing tokens: clients never start discovery.
• Granting every scope to stop prompts: scopes_supported should be the minimal set, with more requested by challenge.
• Token passthrough: upstream failures are "fixed" by loosening the upstream, creating a confused deputy.
• Treating a local server as remote: engineers build an OAuth flow for a STDIO server that should simply read a scoped credential from its environment.

Framework mapping

Practitioner checklist

• Return 401 with resource_metadata and scope for missing or invalid tokens, 403 with insufficient_scope for missing privileges.
• Serve Protected Resource Metadata at the path-inserted well-known URI with an exact resource match.
• Confirm the authorisation server publishes code_challenge_methods_supported and is discoverable by one of the three URIs.
• Fix one canonical URI for each server and use it in client config, metadata and audience rules.
• Validate aud, iss, signature and time on every request; keep JWKS caches refreshable.
• Include existing scopes in step-up challenges and cap client retries.
• Never pass the client's token upstream.
• Log error codes and claims, not tokens, and alert on foreign-audience tokens.

Standards and references

• Model Context Protocol: Authorization (2025-11-25)
• IETF: RFC 9728 OAuth 2.0 Protected Resource Metadata
• IETF: RFC 6750 OAuth 2.0 Bearer Token Usage
• IETF: RFC 8707 Resource Indicators for OAuth 2.0
• IETF: The OAuth 2.1 Authorization Framework (Internet-Draft)
• MITRE ATT&CK: T1550.001 Application Access Token

Related NHI Mgmt Group resources: MCP Authorisation Specification Guide, MCP Security Guide, MCP Gateway and MCP Server Governance Guide, Local MCP Server Security Guide, MCP Incident Response Playbook.