Resource server does not implement OAuth 2.0 Protected Resource Metadata.

If your server is the MCP Python SDK and you passed token_verifier= with an AuthSettings whose resource_server_url is None

1. 1 resource_server_url is a required field on AuthSettings, but it accepts None, and nothing validates that you supplied a URL. RequireAuthMiddleware appends resource_metadata="…" to the challenge only when its resource_metadata_url argument is set, and the server only passes that argument when settings.auth.resource_server_url is present. Pass None and the 401 goes out as WWW-Authenticate: Bearer error="invalid_token", error_description="Authentication required" — right status, no pointer.
2. 2 The same setting mounts the document. create_protected_resource_routes is registered only when resource_server_url is set, so the client's well-known fallback 404s as well and discovery has nowhere left to go.
3. 3 Set resource_server_url to the public URL of the MCP endpoint itself, not the origin. build_resource_metadata_url inserts the well-known segment between host and path, so https://api.example.com/mcp publishes at https://api.example.com/.well-known/oauth-protected-resource/mcp.
4. 4 That value also becomes resource in the document, and the client checks it against the URL it dialed — same origin, and a path prefix of that URL. Behind a TLS-terminating proxy this has to be the external https:// URL, or you trade this error for the mismatch variant.

# mcp 2.x, which is a release candidate at the time of writing. On the
# 1.x stable line the class is FastMCP; the AuthSettings fields below are
# the same.
from mcp.server import MCPServer
from mcp.server.auth.settings import AuthSettings
from pydantic import AnyHttpUrl

mcp = MCPServer(
    "Notes",
    token_verifier=MyTokenVerifier(),
    auth=AuthSettings(
        issuer_url=AnyHttpUrl("https://auth.example.com"),
        # Omit this, or pass None: 401 with no resource_metadata, and no
        # well-known route mounted.
        resource_server_url=AnyHttpUrl("https://api.example.com/mcp"),
        required_scopes=["notes:read"],
    ),
)

If your server gates the route with requireBearerAuth and omits resourceMetadataUrl

1. 1 resourceMetadataUrl is optional in BearerAuthOptions. The SDK's challenge builder adds error and error_description unconditionally, scope when requiredScopes is non-empty, and resource_metadata only when that URL is set.
2. 2 Build the URL with getOAuthProtectedResourceMetadataUrl(new URL('https://api.example.com/mcp')) and pass it to requireBearerAuth. The Express middleware and the web-standard fetch gate share one core, so this is the same fix on Workers, Deno, Bun and Hono.
3. 3 Serve what the challenge points at: mcpAuthMetadataRouter({ oauthMetadata, resourceServerUrl }) mounts /.well-known/oauth-protected-resource/mcp plus a mirror of the authorization server metadata. On a fetch-handler host use oauthMetadataResponse from @modelcontextprotocol/server.
4. 4 The same challenge is emitted on 403 insufficient_scope, so setting resourceMetadataUrl once also fixes scope step-up.

// @modelcontextprotocol/express and /server are the 2.x split packages,
// in beta at the time of writing. On stable @modelcontextprotocol/sdk
// (1.x) the same three exports live under the /server/auth path.
import {
  getOAuthProtectedResourceMetadataUrl,
  mcpAuthMetadataRouter,
  requireBearerAuth
} from '@modelcontextprotocol/express';

const mcpServerUrl = new URL('https://api.example.com/mcp');

const auth = requireBearerAuth({
  verifier,
  requiredScopes: ['mcp'],
  // Omit this and the 401 challenge carries no resource_metadata.
  resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpServerUrl)
});

app.use(mcpAuthMetadataRouter({ oauthMetadata, resourceServerUrl: mcpServerUrl }));
app.all('/mcp', auth, (req, res) => void node(req, res, req.body));

If you pass a bare verifier as FastMCP's auth= — JWTVerifier, IntrospectionTokenVerifier, StaticTokenVerifier, DebugTokenVerifier

1. 1 This is documented behaviour, not a bug. FastMCP's token-verification docs: "TokenVerifier focuses exclusively on token validation without providing OAuth discovery metadata" and "Token verification operates somewhat outside the formal MCP authentication flow, which expects OAuth-style discovery."
2. 2 Wrap the verifier in RemoteAuthProvider with authorization_servers and base_url. That is the piece that adds discovery: "The core discovery endpoint is /.well-known/oauth-protected-resource, which tells clients that your server requires OAuth authentication and identifies the authorization servers you trust."
3. 3 Keep the bare verifier only where every client is provisioned with a token out of band — internal services, a fixed set of agents. It works; it just cannot bootstrap a client that has never seen your server, which is what you are hitting.
4. 4 base_url is what the published resource is derived from, so it has to be the externally reachable URL of the server, not a container-local one.

from fastmcp import FastMCP
from fastmcp.server.auth import RemoteAuthProvider
from fastmcp.server.auth.providers.jwt import JWTVerifier
from pydantic import AnyHttpUrl

token_verifier = JWTVerifier(
    jwks_uri="https://auth.example.com/.well-known/jwks.json",
    issuer="https://auth.example.com",
    audience="mcp-production-api",
)

# auth=token_verifier alone publishes no discovery metadata.
auth = RemoteAuthProvider(
    token_verifier=token_verifier,
    authorization_servers=[AnyHttpUrl("https://auth.example.com")],
    base_url="https://api.example.com",
)

mcp = FastMCP(name="Protected API", auth=auth)

If a Lambda or Cognito authorizer on a REST API answers the 401 before your integration runs

1. 1 API Gateway writes that response itself: "If API Gateway fails to process an incoming request, it returns to the client an error response without forwarding the request to the integration backend." Your MCP server never executes, so no header it would have set exists.
2. 2 The response type is UNAUTHORIZED, default status 401 — "The gateway response when the custom or Amazon Cognito authorizer failed to authenticate the caller." Customize it and map a literal WWW-Authenticate value, single-quoted as parameter mappings require.
3. 3 ACCESS_DENIED (403) is the sibling used for authorization failure. Set it too if you emit insufficient_scope challenges.
4. 4 Expose the metadata document on a route with no authorizer attached. If /.well-known/oauth-protected-resource/... is behind the same authorizer, the client's fallback probe gets a 401 and discovery still fails.
5. 5 Gateway response customization is REST-API only — the AWS reference for responseParameters says "Supported only for REST APIs." On an HTTP API you have to emit the challenge from a proxy integration or from a component in front of API Gateway.

"x-amazon-apigateway-gateway-responses": {
  "UNAUTHORIZED": {
    "statusCode": "401",
    "responseParameters": {
      "gatewayresponse.header.WWW-Authenticate": "'Bearer resource_metadata=\"https://api.example.com/.well-known/oauth-protected-resource/mcp\", scope=\"mcp\"'"
    },
    "responseTemplates": {
      "application/json": "{\"error\":\"invalid_token\"}"
    }
  }
}

If ingress-nginx fronts the server and 401 is listed in custom-http-errors

1. 1 Listing a status code there turns on interception — "Setting at least one code also enables proxy_intercept_errors which are required to process error_page." The client then receives the default backend's response, and "NGINX does not change the response from the custom default backend" — your challenge is gone with the rest of your 401.
2. 2 Remove 401 (and 403, if you use scope challenges) from the ConfigMap custom-http-errors, or override it on the MCP ingress with the nginx.ingress.kubernetes.io/custom-http-errors annotation, which "will set NGINX proxy-intercept-errors, but only for the NGINX location associated with this ingress." The annotation takes a comma-separated list of codes and its value replaces the global list for that host and path, so list the codes you do want intercepted and leave 401 out. An empty annotation value is not a way to say "none": the parser rejects it as invalid content and the global list still applies.
3. 3 Check hide-headers in the same ConfigMap too — it drops named headers from the upstream response before the client sees them.
4. 4 If you must keep custom error pages, the default backend has to emit the challenge itself. NGINX hands it X-Code and X-Original-URI, and "the custom backend is expected to return the correct HTTP status code instead of 200."

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mcp
  annotations:
    # Replaces the global custom-http-errors list for this host and path.
    # 401 and 403 are absent, so they are not intercepted here and the
    # WWW-Authenticate header reaches the client intact.
    nginx.ingress.kubernetes.io/custom-http-errors: "404,503"

If Container Apps built-in authentication (Easy Auth) is returning the 401 for you

1. 1 Container Apps Easy Auth with unauthenticatedClientAction: Return401 answers www-authenticate: Bearer realm="<app>.<region>.azurecontainerapps.io" and nothing else — no resource_metadata. It also answers /.well-known/oauth-protected-resource itself with 401, so the client's fallback probe never reaches your container and both discovery paths are closed.
2. 2 There is no Container Apps setting that fixes this today. A Microsoft collaborator has confirmed the gap on an open issue in the Container Apps repo; the same issue reports that WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES, the App Service setting that does it, appears to be silently ignored on the Container Apps sidecar, and asks Microsoft to confirm whether it is meant to work there at all.
3. 3 App Service and Functions have the documented counterpart: set the WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES app setting to a comma-separated list of your application's scopes and App Service Authentication hosts the protected resource metadata. Microsoft labels PRM support preview.
4. 4 On Container Apps, exclude the MCP route and /.well-known/oauth-protected-resource from Easy Auth and emit the challenge and the document from your own code, or move the server to App Service.

# What Container Apps Easy Auth returns on the discovery path today:
curl -isS https://<app>.<region>.azurecontainerapps.io/.well-known/oauth-protected-resource

# HTTP/2 401
# www-authenticate: Bearer realm="<app>.<region>.azurecontainerapps.io"
#
# No resource_metadata in the challenge, and the document itself is gated,
# so neither discovery mechanism can succeed while Easy Auth owns the route.

Something else

Whatever component you are running, the fix has one of two shapes. Either make the 401 carry resource_metadata="…" pointing at a document you actually serve, or serve /.well-known/oauth-protected-resource/<path> and let the client's fallback probe find it — the MCP authorization spec (revision 2025-11-25) accepts either mechanism and requires clients to support both. Then find the last hop that touched the response: run the curl above against the server directly, then again through each proxy, ingress or platform gate in front of it, and change the layer where the header disappeared rather than the MCP handler. Whichever component publishes the document, its resource value has to be the external URL clients dial — host and path — or RFC 9728 requires them to discard it.