Authorization server metadata won't load

If this is a warning in VS Code's MCP output channel and the server then keeps asking to register a client

1. 1 Read it as a warning, because that is what it is. VS Code logs Error populating auth server metadata for <issuer>: …, then Using default auth metadata, and continues with endpoints it invents from the MCP server's origin — /authorize, /token, and /register on that origin. Nothing serves those, so what the user reports is a repeating dynamic client registration prompt rather than a discovery failure. An open VS Code issue shows exactly that sequence for a server whose only auth is a static header.
2. 2 Find which issuer it probed a few lines earlier. Using auth server metadata url: <url> means the protected resource document supplied it. No authorization_servers found in resource metadata <url> or Could not fetch resource metadata: … means it did not — and VS Code then substitutes the MCP server's own origin as the issuer, which is why the probes go to your server rather than to your identity provider.
3. 3 Each attempt gets its own Error fetching authorization server metadata: line naming the URL and the status it returned, so the log already tells you which of the three forms was tried and what came back. Nothing in mcp.json changes this: the fix is on whichever side owns the issuer.
4. 4 Don't expect headers you configured on the server entry to reach the discovery request. VS Code attaches them only when the metadata URL is on the MCP server's own origin — the fallback case. When the protected resource document named a separate issuer, that request goes out with Accept: application/json and nothing else.

2026-06-09 20:01:30.603 [warning] Could not fetch resource metadata: AggregateError: Failed to fetch resource metadata from all attempted URLs
2026-06-09 20:01:30.891 [warning] Error populating auth server metadata for https://mydomain.com: AggregateError: Failed to fetch authorization server metadata from all attempted URLs
2026-06-09 20:01:30.892 [info] Using default auth metadata
2026-06-09 20:01:49.944 [info] Received 401 status with Authorization header, retrying with new auth registration.

If your server is the MCP TypeScript SDK and clients are probing a host you did not expect

1. 1 Look at oauthMetadata.issuer, not at authorization_servers, which you don't author. buildOAuthProtectedResourceMetadata sets authorization_servers: [options.oauthMetadata.issuer], so whatever string sits in oauthMetadata.issuer is the URL every client builds its three probes from — a placeholder, a service name that only resolves inside your network, or a development localhost all send the whole ladder somewhere a user's machine cannot reach.
2. 2 Know what your own origin already serves: /.well-known/oauth-authorization-server, handing back oauthMetadata verbatim — mcpAuthMetadataRouter mounts it on Express, oauthMetadataResponse answers it from a fetch handler. The SDK's own comment gives the reason: "so legacy clients that probe the resource origin still discover the AS." That route is reached only by a client that fell back to your origin; a client that read your authorization_servers goes to the issuer instead.
3. 3 Pick which of the two you want to be true. Point issuer at the identity provider and let clients fetch from there. Or fill oauthMetadata with the document you fetched from the provider, so your own well-known route is a real answer for the clients that land on it.
4. 4 Allow the cross-origin fetch that browser-resident clients make. The SDK's metadata responses carry Access-Control-Allow-Origin: * because "Metadata documents must be fetchable from web-based MCP clients on any origin"; your provider's endpoint has to as well, or that class of client sees nothing there. On the client side fetchWithCorsRetry retries once without the MCP-Protocol-Version header and then returns undefined, which moves quietly to the next URL rather than raising anything you can read.

// @modelcontextprotocol/express and /server are the 2.x split packages.
// On stable @modelcontextprotocol/sdk (1.x) the same exports live under
// the /server/auth path.
import { mcpAuthMetadataRouter } from '@modelcontextprotocol/express';

// This string becomes authorization_servers[0]. Every well-known URL a
// client probes is built from it, so it has to be the issuer as the
// provider itself publishes it — externally resolvable, trailing slash
// included or omitted to match.
const oauthMetadata = await (
  await fetch('https://auth.example.com/tenant1/.well-known/openid-configuration')
).json();

app.use(
  mcpAuthMetadataRouter({
    oauthMetadata,
    resourceServerUrl: new URL('https://api.example.com/mcp')
  })
);

If your server is the MCP Python SDK

1. 1 Stop looking for a route you forgot to mount: there isn't one. issuer_url on AuthSettings is documented as "OAuth authorization server URL that issues tokens for this resource server", and it is the value that lands in authorization_servers. The SDK's authorization guide is explicit about where its responsibility ends: it publishes protected resource metadata and the 401 that points at it, and "That is the entire discovery story." No authorization server metadata document is served from your app.
2. 2 Check the string, then check that the host answers. validate_issuer_url rejects a fragment, a query string, and any non-HTTPS scheme outside loopback at startup, so those never get this far. What it can't check is reachability, or whether the provider serves a document at a URL a client will construct.
3. 3 Get the string exactly right, trailing slash included. AuthSettings sets url_preserve_empty_path=True for that reason, with the SDK's own comment stating it: "RFC 8414/9207 issuer comparison is exact string comparison, so a spurious trailing slash would break it." A slash you did not intend changes both the URLs the client builds and the echo check it applies to what comes back.
4. 4 Behind a proxy or in a container, set issuer_url to the provider's external URL. A client resolves it from the user's machine, not from inside your network.

# mcp 2.x. On the 1.x stable line the class is FastMCP; these AuthSettings
# fields 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(
        # Published as authorization_servers[0]. The client builds every
        # well-known probe from this exact string.
        issuer_url=AnyHttpUrl("https://auth.example.com/tenant1"),
        resource_server_url=AnyHttpUrl("https://api.example.com/mcp"),
        required_scopes=["notes:read"],
    ),
)

If your server is FastMCP with a RemoteAuthProvider

1. 1 Start from what each side serves. authorization_servers is the list clients probe — FastMCP's docs put it as "tells MCP clients which identity providers you trust" — and the server itself serves one document: "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." Authorization server metadata is not on that list, so the client goes to the provider for it.
2. 2 Where the provider won't serve a document a client can reach, forward it. FastMCP documents this as a supported pattern rather than a workaround: override get_routes, call super().get_routes(), and append a route that returns the provider's document. The docs describe it as "providing authorization server metadata forwarding, which allows MCP clients to discover your identity provider's capabilities through your MCP server rather than contacting the identity provider directly."
3. 3 Point authorization_servers at your own base URL if you forward, because forwarding helps only clients that probe your origin. A client reads authorization_servers first, so if that still names the provider, your forwarded route is never requested. Either put your own base URL in authorization_servers, or fix the provider-side URL and leave forwarding out of it.
4. 4 Set base_url to the server's base, not the MCP endpoint: the docs say that for a server reachable at https://api.yourcompany.com/mcp, use https://api.yourcompany.com. It has to be externally reachable, because it is what identifies the resource in the document clients read first.

import httpx
from starlette.responses import JSONResponse
from starlette.routing import Route

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


class CompanyAuthProvider(RemoteAuthProvider):
    def __init__(self):
        super().__init__(
            token_verifier=JWTVerifier(
                jwks_uri="https://auth.yourcompany.com/.well-known/jwks.json",
                issuer="https://auth.yourcompany.com",
                audience="mcp-production-api",
            ),
            authorization_servers=[AnyHttpUrl("https://auth.yourcompany.com")],
            base_url="https://api.yourcompany.com",
        )

    def get_routes(self) -> list[Route]:
        routes = super().get_routes()

        async def authorization_server_metadata(request):
            async with httpx.AsyncClient() as client:
                response = await client.get(
                    "https://auth.yourcompany.com/.well-known/oauth-authorization-server"
                )
                response.raise_for_status()
                return JSONResponse(response.json())

        routes.append(
            Route(
                "/.well-known/oauth-authorization-server",
                authorization_server_metadata,
            )
        )
        return routes


mcp = FastMCP(name="Company API", auth=CompanyAuthProvider())

If the issuer in authorization_servers is a Keycloak realm, or any provider whose issuer URL carries a path

1. 1 Expect two failures before one success. A realm issuer always has a path — https://keycloak.example.com/realms/{realm-name} — and Keycloak documents exactly one discovery endpoint for it, /realms/{realm-name}/.well-known/openid-configuration. That is the path-appended OpenID Connect form, the third and last URL a client tries; the two path-insertion forms ahead of it are not endpoints Keycloak documents. That is expected behavior, not a misconfiguration.
2. 2 Use that to detect a client that stops early. A filed case: Bifrost's MCP OAuth client tries the two path-insertion forms and the two bare-origin forms and never the path-appended one, so an issuer with a path fails there while the document sits at a URL the client never requested. The report was filed against Replit's issuer https://replit.com/oidc; Replit has since added the RFC 8414 path-insertion URL, so it no longer reproduces there. A Keycloak realm still does, because the path-appended form is the only one Keycloak documents.
3. 3 Confirm the realm URL you published matches the realm's own issuer character for character. Keycloak echoes its configured hostname in that document, and RFC 8414 §3.3 makes a client discard metadata whose issuer differs from the identifier it used to build the URL — so a realm behind a proxy on a different hostname fails the check even once the fetch succeeds.
4. 4 If the client is the component you can't change, serve the document from somewhere the client will look: forward it from your MCP server's origin, or put an authorization server in front of the route that publishes its own metadata at the first URL in the ladder.

If you'd rather not depend on every MCP client agreeing with your provider's well-known layout

1. 1 Let the gateway publish both documents. For its MCP routes it is both the OAuth 2.1 resource server and the authorization server: RFC 9728 protected resource metadata at /.well-known/oauth-protected-resource/{routePath}, and RFC 8414 authorization server metadata at /.well-known/oauth-authorization-server gateway-wide and at /.well-known/oauth-authorization-server/{routePath} per route, which rebinds issuer. The per-route form is the RFC 8414 path-insertion URL, which is the first entry in the ladder — so a client's first probe is the one that answers.
2. 2 Keep your own identity provider. mcp-oauth-inbound delegates browser login to an OIDC provider you configure and then issues the gateway's own bearer token, so the provider's well-known layout stops being something every MCP client has to agree with — only the gateway talks to it.
3. 3 Expect the well-known endpoints to answer with Access-Control-Allow-Origin: *, which is what browser-resident clients need to read them cross-origin at all — the failure mode that produces no status code to read on the client side.
4. 4 Check one documented caveat before you rely on this: the gateway derives its issuer from the incoming request origin, honoring Host and then X-Forwarded-Host. Front it with a custom domain whose proxy strips or rewrites those and it advertises an issuer that doesn't match the URL the client connected to — the same rejection, one layer further along.

Something else

Whatever the components are, this error has one shape: a URL was built and nothing usable came back, and only two things can be changed. Change the issuer, so the URLs a client builds land where the document already is. Or change what answers those URLs, by serving the document from a place a client will ask. Run that curl to decide which, and read the status codes rather than the client's message: three 404s mean the issuer is pointing somewhere with no metadata, one 200 that a client still rejected means the document is there and its issuer does not echo, and a 200 text/html or a 415 means something in front of the provider is answering instead of the provider. Don't treat a provider as broken for serving only one of the two mechanisms — the 2026-07-28 specification requires an authorization server to provide at least one of RFC 8414 or OpenID Connect Discovery, and puts the burden of supporting both on the client.