Menu

MCP authorization in practice: 401, WWW-Authenticate and protected resource metadata

2026-10-30MCP Checkup

Authorization is optional in MCP. If your server uses it, the hard part for a client isn't the token. It's finding out where to get one. A client that has never seen your server knows one thing: your URL. Everything it needs to start signing in has to come from that URL, without credentials: a 401, one header, and two JSON documents.

This guide walks that chain the way the spec describes it, lists the ways it breaks, and gives a curl command for each step. None of the commands needs a token. Replace https://your-server.example.com/mcp with your endpoint.

What the spec asks of a protected server

The rules below are from the current revision, 2026-07-28, and 2025-11-25 says the same unless noted.

  • They apply to HTTP transports. A server on stdio should take credentials from the environment instead.
  • Your MCP server acts as an OAuth 2.1 resource server. It must implement OAuth 2.0 Protected Resource Metadata (RFC 9728), and that document must list at least one authorization server in authorization_servers.
  • It must tell clients where that document is, in at least one of two ways: a resource_metadata parameter in the WWW-Authenticate header of its 401 responses, or the document at a well-known URI. Clients must support both.
  • The authorization server must publish OAuth 2.0 Authorization Server Metadata (RFC 8414) or OpenID Connect Discovery 1.0. Clients must try both.
  • Clients send the token as Authorization: Bearer <token> on every request, never in the query string. Your server must check that the token was issued for it, answer invalid or expired tokens with 401, and must not accept or forward tokens meant for anything else.

Earlier revisions differ in ways that matter:

  • 2025-06-18 made the header mandatory: a server returning 401 had to name its metadata URL in WWW-Authenticate. It defined no well-known fallback for clients, and listed only RFC 8414 for the authorization server, not OpenID Connect Discovery.
  • 2025-03-26 had no protected resource metadata at all. The client looked for authorization server metadata on the MCP server's own host and fell back to default paths such as /authorize. A server still set up that way gives a client on any later revision no way to find its authorization server from the URL alone.
  • 2026-07-28 spells out that clients must reject authorization server metadata whose issuer doesn't match, adds checks on the iss parameter (RFC 9207), and deprecates Dynamic Client Registration in favour of Client ID Metadata Documents.

Step 1: the 401

A client starts with an ordinary MCP request and no token. A protected server answers like this:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://your-server.example.com/.well-known/oauth-protected-resource/mcp", scope="files:read"

Each part has a job:

  • 401 with a WWW-Authenticate header. HTTP itself requires this pairing: a server that sends a 401 must send at least one challenge with it (RFC 9110, section 15.5.2). A bare 401 breaks HTTP, whatever MCP revision you follow.
  • Bearer is the scheme from RFC 6750.
  • resource_metadata is the URL of your protected resource metadata (RFC 9728, section 5.1). When it is present, clients use it instead of guessing well-known URLs.
  • scope is optional, but since 2025-11-25 the spec says servers should send it. Clients treat it as the scopes to ask for first. Without it, they fall back to scopes_supported in your metadata.
  • No error parameter. When a request carried no credentials at all, RFC 6750 says the server should not include an error code. error="invalid_token" is for a token that was sent and failed.

Later, when a client presents a token that lacks a scope it needs, the answer is a 403 with error="insufficient_scope", the scope the operation needs, and resource_metadata again (2025-11-25, 2026-07-28).

Check what your server sends:

MCP_URL=https://your-server.example.com/mcp
curl -sS -o /dev/null -D headers.txt "$MCP_URL" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"curl-test","version":"0.1"},"io.modelcontextprotocol/clientCapabilities":{}}}}'
grep -iE '^HTTP/|^www-authenticate|^location|^content-type' headers.txt

For a server on an earlier revision, send an initialize request instead. If the reply is 200, that method doesn't require a token on your server; repeat with one that does.

Step 2: the protected resource metadata

Take the URL out of the header and fetch it:

PRM_URL=$(tr -d '\r' < headers.txt | grep -i '^www-authenticate:' \
  | sed -n 's/.*resource_metadata="\([^"]*\)".*/\1/p')
echo "$PRM_URL"
curl -sS -i "$PRM_URL"

RFC 9728 requires a 200 with Content-Type: application/json, and a JSON object like this one:

{
  "resource": "https://your-server.example.com/mcp",
  "authorization_servers": ["https://auth.your-server.example.com"],
  "scopes_supported": ["files:read", "files:write"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Example Files"
}
Field RFC 9728 What MCP adds
resource Required Your server's canonical URI: lowercase scheme and host, no fragment, and preferably no trailing slash
authorization_servers Optional Required, with at least one issuer
scopes_supported Recommended Used when the 401 has no scope; since 2025-11-25 it is meant to be the minimal set for basic use
bearer_methods_supported Optional MCP clients send the token in the header only
resource_name Recommended A name a client can show to the person signing in

The resource value carries the strictest rule. RFC 9728 (section 3.3) says that when a client found the document through resource_metadata, resource must be identical to the URL the client sent its request to. When the client found it at a well-known URI, resource must be identical to the identifier that URI was built from. If the values differ, the client must not use the document. Compare yours:

curl -sS "$PRM_URL" | jq --arg url "$MCP_URL" \
  '{resource_matches: (.resource == $url), resource, authorization_servers, scopes_supported}'

Step 3: without the header, the well-known URIs

Since 2025-11-25, a server may leave resource_metadata out and rely on the well-known URI, and clients must look for it. RFC 9728 builds that URL by inserting /.well-known/oauth-protected-resource between the host and the path. The MCP spec has clients try two places, in this order:

for u in https://your-server.example.com/.well-known/oauth-protected-resource/mcp \
         https://your-server.example.com/.well-known/oauth-protected-resource; do
  curl -sS -o /dev/null -w "%{http_code} %{content_type}  $u\n" "$u"
done

Publishing at the first location as well as naming it in the header means a client finds the document either way. A common slip is to append the suffix to the path instead, as in /mcp/.well-known/oauth-protected-resource. The RFC inserts it after the host, and the spec never sends clients to the appended form.

Step 4: the authorization server's metadata

Each entry in authorization_servers is an issuer identifier (RFC 8414). The client builds well-known URLs from it and tries them in a fixed order (2025-11-25, 2026-07-28). For an issuer with a path, such as https://auth.example.com/tenant1:

  1. https://auth.example.com/.well-known/oauth-authorization-server/tenant1
  2. https://auth.example.com/.well-known/openid-configuration/tenant1
  3. https://auth.example.com/tenant1/.well-known/openid-configuration

For an issuer without a path, only the first two forms apply, without the suffix. This loop tries them for the first issuer in your document:

AS=$(curl -sS "$PRM_URL" | jq -r '.authorization_servers[0]')
origin=$(printf '%s' "$AS" | sed -E 's#^(https?://[^/]+).*#\1#')
as_path=$(printf '%s' "$AS" | sed -E 's#^https?://[^/]+##; s#/$##')
for u in "$origin/.well-known/oauth-authorization-server$as_path" \
         "$origin/.well-known/openid-configuration$as_path" \
         ${as_path:+"$origin$as_path/.well-known/openid-configuration"}; do
  printf '%s  %s\n' "$(curl -sS -o /dev/null -w '%{http_code}' "$u")" "$u"
done

Set AS_META_URL to the first URL that returned 200, then look at the fields a client depends on:

curl -sS "$AS_META_URL" | jq --arg as "$AS" '{issuer_matches: (.issuer == $as), issuer,
  authorization_endpoint, token_endpoint, code_challenge_methods_supported,
  client_id_metadata_document_supported, registration_endpoint}'

What to look for:

  • issuer identical to the entry in authorization_servers. RFC 8414 (section 3.3) says a client must not use the metadata otherwise, and 2026-07-28 repeats the rule. A trailing slash on one side and not the other is enough to fail it.
  • code_challenge_methods_supported present and including S256. It is how a client confirms PKCE support. If the field is missing, MCP clients must refuse to proceed (2025-11-25, 2026-07-28).
  • authorization_endpoint and token_endpoint on https. The spec requires every authorization server endpoint to be served over HTTPS.
  • A way to register. client_id_metadata_document_supported: true for Client ID Metadata Documents, a registration_endpoint for Dynamic Client Registration, or client IDs you hand out in advance.

Common misconfigurations

A 401 with no WWW-Authenticate header. It breaks HTTP. A client following 2025-06-18 has nowhere to go next. One following 2025-11-25 or later falls back to the well-known URIs, so it works only if the document is there. In our directory: of the 5,924 servers we checked in the week to October 26, 2026, at least 1,999 answered an unauthenticated request with a 401, and 33 of those sent it with no WWW-Authenticate header at all.

A challenge without resource_metadata, such as Bearer realm="api". Valid HTTP, but not enough under 2025-06-18, and under later revisions it leaves the client the same fallback. In our directory: 131 of those servers.

A metadata URL that doesn't return metadata. A 404, the site's HTML homepage from a catch-all route, or a redirect to a login page. RFC 9728 asks for 200 and JSON, and nothing else gives the client what it needs. In our directory: 4 servers named a metadata URL that answered with an HTTP error; none answered with something that wasn't a JSON object.

A resource that doesn't match the endpoint. Typical causes: http where clients use https, an internal hostname leaking out from behind a proxy (http://localhost:8080/mcp), the bare origin when clients call /mcp, or a stray trailing slash. The client must discard the document.

An empty authorization_servers, or none at all. RFC 9728 allows that; MCP doesn't.

Authorization server metadata at none of the URLs clients try, or with an issuer that differs from the entry in authorization_servers. Either way, the client has no usable metadata and can't start the sign-in.

A login page instead of a 401. A 302 to /login, or a 200 with an HTML sign-in form. The client was speaking JSON-RPC. Streamable HTTP requires the reply to a request to be application/json or text/event-stream, and an HTML page has no challenge in it to read.

Redirects on the MCP endpoint. After a 301 or 302, curl and the browser fetch both turn a POST into a GET and drop the body. After a redirect to another origin (a different scheme, host or port), both drop the Authorization header. A 307 or 308 keeps the method, but the cross-origin rule still applies. Give clients the final URL rather than relying on a redirect.

What you can check without credentials, and what you can't

Steps 1 to 4 are public by design. The discovery chain exists for a client that has nothing yet, so a check that sends no credentials sees exactly what a new client sees. That covers the 401 and its header, the metadata document and its resource, the well-known locations, and the authorization server's metadata.

The rest needs a token, so test it yourself with an account of your own:

  • an expired or malformed token gets 401 with error="invalid_token";
  • a token issued for a different audience is refused;
  • a token missing a scope gets 403 with error="insufficient_scope" and the scope required;
  • if your tool list depends on the token's scopes, which 2026-07-28 allows, each scope sees the right list;
  • your server never forwards a client's token to the APIs it calls.

Checklist

Step What to check
Challenge An unauthenticated request gets 401, not 200, a redirect or an HTML page
Header WWW-Authenticate: Bearer with resource_metadata, and scope
Metadata The resource_metadata URL returns 200 with JSON
Resource resource is identical to the endpoint URL clients use
Servers authorization_servers lists at least one issuer
Well-known The same document at /.well-known/oauth-protected-resource plus your path
AS metadata Found at one of the URLs clients try; every endpoint on HTTPS
Issuer issuer matches the authorization_servers entry character for character
PKCE code_challenge_methods_supported includes S256
Endpoint The MCP URL answers without a redirect
With a token Invalid → 401; wrong audience → refused; missing scope → 403 insufficient_scope

Every unauthenticated step above is what a new client does first. To see them the way an outside agent meets them, with no credentials sent at all, paste your address at mcpcheckup.com.