---
title: "Resource server does not implement OAuth 2.0 Protected Resource Metadata"
description: "Your MCP server returns 401 but carries no resource_metadata pointer, so discovery never starts. The cause and fix in each SDK and gateway."
canonicalUrl: "https://zuplo.com/learn/mcp/errors/401-without-www-authenticate"
pageType: "mcp-error"
errorString: "Resource server does not implement OAuth 2.0 Protected Resource Metadata."
lastVerified: "2026-07-27"
specVersion: "2026-07-28"
---

# `Resource server does not implement OAuth 2.0 Protected Resource Metadata.`

> Your server answers `401` correctly, but the response carries no pointer to protected resource metadata, so the client cannot discover the authorization server and the OAuth flow never starts.

_MCP specification 2026-07-28._

## Is this you?

Two requests, no credentials. Read the raw challenge line, then fetch the document that challenge must name. This separates "the pointer is missing" from "the pointer is there and something later broke".

```bash
# 1. The challenge. Read the WWW-Authenticate line verbatim.
curl -sS -D - -o /dev/null -X POST https://your-server.example.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 2. The document a client probes when the header omits it.
curl -isS https://your-server.example.com/.well-known/oauth-protected-resource/mcp
```

**This error** — A 401 with no `WWW-Authenticate` at all, or one that stops at `Bearer realm="…"` or `Bearer error="invalid_token"` with no `resource_metadata`, while the second request 404s. If the well-known request answers 401 instead of 200, something in front of the server is intercepting the discovery path too. A 200 whose `resource` is not the URL you dialed is the same failure one step later — RFC 9728 requires the client to discard that document, and both reference SDKs reject any `resource` that is not the same origin and a path prefix of the URL they requested.

**Working** — `HTTP/1.1 401` carrying `WWW-Authenticate: Bearer error="invalid_token", error_description="Authentication required", scope="mcp:read", resource_metadata="https://your-server.example.com/.well-known/oauth-protected-resource/mcp"`, and a `200 application/json` from the second request whose `resource` is exactly `https://your-server.example.com/mcp` — the URL a client dials — and whose `authorization_servers` names at least one server. A 401 with no header is also fine as long as that document is served: a conformant client falls back to the well-known probe. If this is what you see, this isn't your problem.

**Clients also report this as:**

- `Could not fetch resource metadata`
- `No authorization_servers found in resource metadata <url> - Is this resource metadata configured correctly?`
- `Protected resource <advertised> does not match expected <dialed>`
- `Failed to start OAuth flow for <server>: SDK auth failed: Protected resource <advertised> does not match expected <dialed> (or origin)`

## Fix it

**In short.** Make the `401` carry `resource_metadata="…"` and serve the document it points at: that is `resource_server_url` on `AuthSettings` in the MCP Python SDK, `resourceMetadataUrl` on `requireBearerAuth` plus `mcpAuthMetadataRouter` in the TypeScript SDK, and the verifier wrapped in `RemoteAuthProvider` in FastMCP. That document's `resource` has to be the external URL clients dial, host and path included, because RFC 9728 requires a client to discard metadata whose `resource` does not match. If your code already sets the header, something in front of the server is replacing the `401` on the way out, and that is the layer to fix.

Where is the 401 coming from?

### MCP Python SDK

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

1. Check `resource_server_url` on `AuthSettings` first. It is a required field, 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 passes that argument only 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. Expect the fallback to fail too. 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 probe 404s as well and discovery has nowhere left to go.
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. Use the external `https://` URL behind a TLS-terminating proxy, or you trade this error for the mismatch variant. 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.

```python
# mcp 2.x — the current release since 2026-07-28, and what
# `pip install mcp` now gives you. On the 1.x maintenance line the class
# is FastMCP; the AuthSettings fields here 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"],
    ),
)
```

[MCP Python SDK: Authorization](https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/run/authorization.md)

### MCP TypeScript SDK

If your server gates the route with `requireBearerAuth` and omits `resourceMetadataUrl`

1. Check whether `resourceMetadataUrl` is set at all — it 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. 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. 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. Expect one fix to cover two cases: the same challenge goes out on `403 insufficient_scope`, so setting `resourceMetadataUrl` once also fixes scope step-up.

```ts
// @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));
```

[MCP TypeScript SDK: Require authorization](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/serving/authorization.md)

### FastMCP

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

1. Read this as documented behavior, 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. 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. 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 cannot bootstrap a client that has never seen your server, which is what you're hitting.
4. Set `base_url` to the externally reachable URL of the server, not a container-local one. The published `resource` is derived from it.

```python
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)
```

[FastMCP: Remote OAuth](https://gofastmcp.com/servers/auth/remote-oauth)

### AWS API Gateway (REST)

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

1. Stop looking in your server. 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. Customize the `UNAUTHORIZED` gateway response — default status 401, "The gateway response when the custom or Amazon Cognito authorizer failed to authenticate the caller" — and map a literal `WWW-Authenticate` value, single-quoted as parameter mappings require.
3. Set `ACCESS_DENIED` (403) too if you emit `insufficient_scope` challenges. It is the sibling response type for authorization failure.
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. Check which API type you have. Gateway response customization is REST-API only — the AWS reference for `responseParameters` says "Supported only for REST APIs" — so on an HTTP API, emit the challenge from a proxy integration or from a component in front of API Gateway.

```json
"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\"}"
    }
  }
}
```

[API Gateway: gateway response types](https://docs.aws.amazon.com/apigateway/latest/developerguide/supported-gateway-response-types.html)

### ingress-nginx

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

1. Understand what listing a code does: it 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", so your challenge is gone with the rest of your 401.
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. Check `hide-headers` in the same ConfigMap too — it drops named headers from the upstream response before the client sees them.
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."

```yaml
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"
```

[ingress-nginx: custom errors](https://kubernetes.github.io/ingress-nginx/user-guide/custom-errors/)

### Azure Container Apps

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

1. Expect both discovery paths to be closed. Container Apps Easy Auth with `unauthenticatedClientAction: Return401` answers `www-authenticate: Bearer realm="APP.REGION.azurecontainerapps.io"` and nothing else — no `resource_metadata` — and it answers `/.well-known/oauth-protected-resource` itself with 401, so the client's fallback probe never reaches your container.
2. Don't go looking for a Container Apps setting: there isn't one. A Microsoft collaborator has confirmed the gap on an open issue in the Container Apps repo, and 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.
3. On App Service or Functions, 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. 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.

```bash
# 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.
```

[microsoft/azure-container-apps#1736](https://github.com/microsoft/azure-container-apps/issues/1736)

### Something else

The fix has one of two shapes: 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 specification (revision 2025-11-25) accepts either mechanism and requires clients to support both. Then find the last hop that touched the response: re-run that `curl` 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` has to be the external URL clients dial, host and path, or RFC 9728 requires them to discard it.

## Why it happens

A client that gets a `401` does not guess where to authenticate: it reads `resource_metadata` out of the `WWW-Authenticate` challenge, fetches that RFC 9728 document, and follows `authorization_servers` to the authorization server.

With no pointer it probes `/.well-known/oauth-protected-resource/<path>` and then the root, and if neither is served, discovery is over — the client reports a metadata or connection error rather than prompting anyone to log in.

The pointer is optional in both reference SDKs, and omitting it drops the parameter from the challenge with no warning. The other case is a header your code did set, replaced by something in front of the server.

### The exchange

The MCP client posts to the server unauthenticated and gets a 401 whose WWW-Authenticate challenge carries no resource_metadata parameter. The client falls back to probing the well-known protected resource metadata path, that returns 404, and discovery ends there — the authorization server is never contacted.

**Participants:** MCP client, MCP server, Authorization server

1. **MCP client → MCP server** — `POST /mcp` — `no Authorization header`
2. **MCP server → MCP client** — `401 Unauthorized` — `Bearer error="invalid_token"` _(response)_
3. **MCP client → MCP server** — `GET well-known fallback` — `/.well-known/oauth-protected-resource/mcp`
4. **MCP server → MCP client** — `404 Not Found` — `no metadata document mounted` _(response; this step fails — the flow stops here)_

Notes:

- **Step 2** — The challenge is a valid 401 and machine-readable, but it carries no resource_metadata parameter, so the client has no metadata URL to follow.
- **Steps 3–4** — With nothing in the header, a conformant client probes the path-based well-known URI and then the root. Neither is served, so discovery ends here and the authorization server is never named.

## Next steps to production

Getting that one parameter right is what lets a client connect at all; everything asked next is about the rest of the chain, and about what the client can do once it is in.

- **Which other discovery documents does a client expect from us?** — `RFC 9728 protected resource metadata` — The whole chain — and a gateway serves it as one unit: the challenge points at protected resource metadata, which points at authorization server metadata, which the client then uses to register and to request scopes.
- **The client authenticated. Which of our tools can it call?** — `mcp-capability-filter-inbound` — Only the ones you allowlist on the route — authenticating got it in the door, nothing more. Everything unlisted is blocked with `MethodNotFound` before the request reaches your server.
- **Which caller is this, next time a request looks wrong?** — `capability_invocation` — Each tool call resolves to a caller, a capability, and an outcome with a named reason code, rather than to a status line in an access log.
- **Can this token be replayed against our other MCP route?** — `RFC 8707 resource indicators` — No. A gateway-issued token is bound to one route's canonical resource URI, so a token minted for one route is rejected at another.

All of these attach to one MCP route's `policies.inbound` — the same policy engine on the way in and on the way out. Your MCP server keeps the code and the authentication it has today. See [Zuplo MCP Gateway](/mcp-gateway).

## Keep reading

- **Similar error** — [`Your MCP server returns a login page or 403 instead of 401`](/learn/mcp/errors/302-redirect-instead-of-401) — A gate in front of your MCP server is enforcing login built for humans in browsers, so an unauthenticated client gets a login page, a redirect, or a bare `403` instead of the `401` that would tell it where to authenticate.
- **Similar error** — [`Dynamic Client Registration not supported`](/learn/mcp/errors/dynamic-client-registration-not-supported) — The MCP client reached your authorization server's metadata and found no way to obtain a client ID — no registration endpoint, no Client ID Metadata Document support, and none configured in the client — so it stopped before the OAuth flow began.
- **Similar error** — [`MCP headers config ignored when server has OAuth discovery`](/learn/mcp/errors/configured-headers-ignored-when-oauth-discovery-present) — Your credential never reaches the wire: the client found OAuth discovery metadata on the server first and started the OAuth flow instead of sending the header you configured.
- **Error reference** — [every documented MCP error](/learn/mcp/errors)
