createmcps.com

Error

MCP error: Protected Resource Metadata missing or invalid

Against MCP 2026-07-28 · verified 10 August 2026

The 401 points a client at a metadata document, and the document is not there. The client has nowhere to go next: it cannot discover the authorization server, so it cannot get a token, so it cannot retry.

The error

Protected Resource Metadata not served or not valid JSON
How often we see this:

1 of the 16 real MCP servers we probed on 2026-08-11 tripped MCP-AUT-002. That is a snapshot of hand-picked public servers, not a random sample of the ecosystem — it shows the failure is common in practice, not that a given percentage of all servers have it.

What causes it

MCP authorization is built on OAuth 2.1's Protected Resource Metadata (RFC 9728). The 401's `resource_metadata` parameter names a URL; the client fetches it to learn which authorization server issues tokens for this resource, and what the resource's canonical URI is.

Three things break it, and they look identical to a client: the document is not served at all (404), it is served but is not valid JSON (an HTML error page is the usual culprit), or it is served from a path the 401 does not actually point at. In all three cases the client has a token-less dead end.

A related and easily missed failure is the document being present but missing its `resource` field — the canonical URI the client must request a token FOR. Without it the client cannot construct a correct token request even though it found the document.

How to fix it

The fix

Serve the document at the well-known pathThe conventional location is `/.well-known/oauth-protected-resource`, served as `application/json` with permissive CORS — clients fetch it from browsers as well as servers.
A minimal Protected Resource Metadata document
{
  "resource": "https://mcp.example.com/mcp",
  "authorization_servers": ["https://auth.example.com"],
  "scopes_supported": ["mcp:tools", "mcp:resources"],
  "bearer_methods_supported": ["header"]
}

The fix

Make the 401 point at exactly that URLThe `resource_metadata` parameter must be the absolute URL of the document you actually serve. A relative path, or one that redirects, is where this most often goes wrong in production behind a proxy.

The fix

Include the resource field, and make it canonical`resource` is the identifier a client asks the authorization server for a token for. It must be the canonical URI of this MCP endpoint, and it must match what the authorization server expects in the token's audience — a mismatch produces tokens that are valid but rejected.

The fix

Check it returns JSON, not your error pageFetch it with no credentials and confirm the content type and the body. A framework that renders a styled 404 page will return 200-with-HTML through some proxies, which parses as neither a document nor an obvious failure.

Rules involved

Each of these is checked against a live server, and each links to the exact sentence of the specification it comes from.

RuleWhat we checkLevelIf it fails
MCP-AUT-002RFC 9728 Protected Resource Metadata is served and validMUSTfail
MCP-AUT-003PRM resource equals the canonical server URIMUSTfail
MCP-AUT-001Unauthenticated request returns 401 with WWW-Authenticate resource_metadataMUSTfail

FAQ

Frequently asked

Where should an MCP server serve Protected Resource Metadata?

At /.well-known/oauth-protected-resource, as application/json, reachable without authentication and with CORS allowed. The exact URL is whatever your 401's resource_metadata parameter names — the two must agree.

What must the document contain?

At minimum a resource field holding the canonical URI of the MCP endpoint, and an authorization_servers array naming the issuer. scopes_supported and bearer_methods_supported should be present too; without scopes_supported a client cannot tell what it may ask for.

Why does my client fail even though the metadata document exists?

Most often because it has no resource field, so the client cannot tell the authorization server which resource the token is for; or because the resource value does not match the audience the authorization server stamps into tokens, which produces tokens that verify but are refused.

Check this against your own server

Point the validator at a live MCP server and it reports every rule on this page as pass, warn or fail — each linked to the exact spec sentence it comes from.

Validate a server →