Merge pull request #2113 from modelcontextprotocol/v2/fix/2071-oauth-resource-metadata

fix(auth): pass the challenge's resource_metadata URL to SDK auth()

AGENTS.md

@@ -61,7 +61,19 @@ v2/main/
 ├── core/                               # Shared core code (no package.json — consumed via the `@inspector/core` vite alias)
 │   ├── auth/                           # OAuth: providers, discovery, OAuthStorage + persist backends;
 │   │                                   #   mid-session recovery (challenge.ts WWW-Authenticate
-│   │                                   #   parsing, scopes.ts SEP-2350 scope union, oauthUx.ts
+│   │                                   #   parsing — including the RFC 9728
+│   │                                   #   `resource_metadata` URL, carried on
+│   │                                   #   AuthChallenge as a STRING because the
+│   │                                   #   web client's challenge crosses the
+│   │                                   #   remote-backend boundary as JSON, and
+│   │                                   #   converted to a URL at the OAuth
+│   │                                   #   boundary by challengeResourceMetadataUrl
+│   │                                   #   (malformed values ignored, matching the
+│   │                                   #   SDK's own parser) so discovery targets
+│   │                                   #   the advertised document rather than a
+│   │                                   #   location derived from the MCP server
+│   │                                   #   URL — #2071;
+│   │                                   #   scopes.ts SEP-2350 scope union, oauthUx.ts
 │   │                                   #   shared copy, mcpAuth.ts force-reauthorization,
 │   │                                   #   issuerBinding.ts SEP-2352 callback-leg failure
 │   │                                   #   classification — separates a recoverable

README.md

@@ -154,6 +154,7 @@ Each config below is a ready-made server for exercising one feature by hand. Loa
 | `nullable-fields-http.json`               | Tools tab: nullable (`anyOf` + `null`) arguments   | [#1928](https://github.com/modelcontextprotocol/inspector/issues/1928) |
 | `rfc6570-templates-http.json`             | Resources tab: RFC 6570 resource-template expansion | [#1919](https://github.com/modelcontextprotocol/inspector/issues/1919) |
 | `advertised-extensions-http.json`         | Tool registration gated on advertised extensions    | [#1739](https://github.com/modelcontextprotocol/inspector/issues/1739) |
+| `oauth-custom-resource-metadata-http.json` **(legacy era)** | OAuth discovery driven by the challenge's `resource_metadata` | [#2071](https://github.com/modelcontextprotocol/inspector/issues/2071) |
 | `logging-{legacy,modern}-http.json`       | Logging, both eras                                  | [#1629](https://github.com/modelcontextprotocol/inspector/issues/1629) |
 | `subscriptions-{legacy,modern}-http.json` | Resource subscriptions, both eras                   | [#1630](https://github.com/modelcontextprotocol/inspector/issues/1630) |
 | `tasks-{legacy,modern}-http.json`         | Tasks, both eras                                    | [#1631](https://github.com/modelcontextprotocol/inspector/issues/1631) |
@@ -327,6 +328,23 @@ Requiredness is a property of the **expression**, not the variable: RFC 6570 dro
 
 This is the debugging knob for a server legitimately changing tool registration based on what the client advertises. Legacy stateful leg only — the modern per-request leg has no persistent `oninitialized`.
 
+#### OAuth `resource_metadata` at a non-default path
+
+`oauth-custom-resource-metadata-http.json` is an OAuth-protected server (combined AS + resource, DCR enabled) that serves its RFC 9728 protected-resource metadata document **only** from `/custom/protected-resource`, and advertises it on every 401:
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="http://127.0.0.1:8082/custom/protected-resource"
+```
+
+The default `/.well-known/oauth-protected-resource` route is deliberately left unserved, so a client that ignores the advertised URL cannot discover the document at all. Plain streamable-HTTP — connect with the **default (legacy)** protocol era.
+
+Add the server, click **Connect**, and watch the Inspector's first protected-resource metadata request in the Network tab: it must go to `/custom/protected-resource`. On the broken build the challenge's `resource_metadata` was parsed and then dropped before the SDK's `auth()` ever saw it ([#2071](https://github.com/modelcontextprotocol/inspector/issues/2071)), so discovery probed locations derived from the MCP server URL, 404'd, and authorization failed for any server that puts the document somewhere other than the well-known path.
+
+The same server is worth running against `--cli` / `--tui`, which reach it by a different route: with no stored token in the legacy era the Inspector connects with no auth provider (so the SDK cannot open a browser before the callback server is listening), the 401 surfaces as the SDK's headerless `UnauthorizedError`, and the client calls `authenticate()` with no challenge in hand. The transport therefore *observes* every 401/403 passively, so the advertised URL is still available on that path.
+
+The value now rides the normalized `AuthChallenge` as a string — it has to be serializable, because the web client's challenge crosses the remote-backend boundary as JSON — and is converted to a `URL` at the OAuth boundary, where it is handed to `auth()` as `resourceMetadataUrl` and to the CIMD pre-registration probe, which runs *before* `auth()` and would otherwise do its own default-location discovery. A malformed value is ignored rather than surfaced, matching the SDK's own `WWW-Authenticate` parser: discovery falls back to the default locations instead of failing the whole authorization on a bad header. The callback leg needs nothing extra — SDK `auth()` persists the URL in its discovery state, so it survives both the web full-page redirect and the CLI/TUI loopback callback.
+
 #### Logging, both eras
 
 `logging-legacy-http.json` and `logging-modern-http.json` both serve `logging: true` plus a `send_notification` tool that emits a `notifications/message` at a chosen level. The legacy one is a plain streamable-HTTP server; the modern one sets `transport.modern: true`.

clients/web/src/test/core/auth/challenge.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from "vitest";
 import {
   AuthChallengeError,
+  challengeResourceMetadataUrl,
   AuthRecoveryRequiredError,
   findNestedAuthError,
   isAuthChallengeError,
@@ -286,6 +287,58 @@ describe("parseAuthChallengeFromError", () => {
   });
 });
 
+describe("resource_metadata (RFC 9728) preservation — #2071", () => {
+  const METADATA_URL = "http://127.0.0.1:3001/custom/protected-resource";
+  const HEADER = `Bearer resource_metadata="${METADATA_URL}"`;
+
+  it("keeps the advertised URL when parsing a response challenge", () => {
+    const response = new Response(null, {
+      status: 401,
+      headers: { "WWW-Authenticate": HEADER },
+    });
+
+    expect(parseAuthChallengeFromResponse(response)).toEqual({
+      reason: "token_expired",
+      resourceMetadataUrl: METADATA_URL,
+      raw: { httpStatus: 401, wwwAuthenticate: HEADER },
+    });
+  });
+
+  it("keeps the advertised URL when parsing an error challenge", () => {
+    expect(
+      parseAuthChallengeFromError({ status: 401, wwwAuthenticate: HEADER }),
+    ).toMatchObject({ resourceMetadataUrl: METADATA_URL });
+  });
+
+  it("omits the field entirely when the challenge does not advertise one", () => {
+    const response = new Response(null, {
+      status: 401,
+      headers: { "WWW-Authenticate": "Bearer" },
+    });
+
+    expect(parseAuthChallengeFromResponse(response)).not.toHaveProperty(
+      "resourceMetadataUrl",
+    );
+  });
+
+  it("converts the stored string to a URL at the OAuth boundary", () => {
+    expect(
+      challengeResourceMetadataUrl({ resourceMetadataUrl: METADATA_URL })?.href,
+    ).toBe(METADATA_URL);
+  });
+
+  it.each([
+    ["absent", undefined],
+    ["empty", ""],
+    ["whitespace", "   "],
+    ["not a URL", "not-a-url"],
+  ])("ignores a %s resource_metadata value", (_label, value) => {
+    expect(
+      challengeResourceMetadataUrl({ resourceMetadataUrl: value }),
+    ).toBeUndefined();
+  });
+});
+
 describe("isAuthChallengeError", () => {
   it("detects AuthChallengeError instances", () => {
     const err = new AuthChallengeError({ reason: "token_expired" }, 401);

clients/web/src/test/core/auth/cimd.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
 import type { OAuthStorage } from "@inspector/core/auth/storage.js";
 import { BaseOAuthClientProvider } from "@inspector/core/auth/providers.js";
 import { ensureCimdClientRegistration } from "@inspector/core/auth/cimd.js";
@@ -31,6 +31,10 @@ describe("ensureCimdClientRegistration", () => {
     } as unknown as OAuthStorage;
   });
 
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
   it("pre-registers URL-based client id when AS supports CIMD", async () => {
     const fetchFn = vi.fn(async (input: RequestInfo | URL) => {
       const url = String(input);
@@ -97,6 +101,63 @@ describe("ensureCimdClientRegistration", () => {
     expect(storage.saveClientInformation).not.toHaveBeenCalled();
   });
 
+  it("discovers protected-resource metadata at the challenge-advertised URL (#2071)", async () => {
+    const metadataUrl = new URL(
+      "http://127.0.0.1:9999/custom/protected-resource",
+    );
+    // Both discovery legs must run through the configured fetch — on web that
+    // is the backend proxy, so a leg that fell back to the global would fail
+    // on CORS and be swallowed.
+    const fetchFn = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url === metadataUrl.href) {
+        return new Response(
+          JSON.stringify({
+            resource: SERVER_URL,
+            authorization_servers: ["http://127.0.0.1:9999"],
+          }),
+        );
+      }
+      if (url.includes("/.well-known/oauth-authorization-server")) {
+        return new Response(
+          JSON.stringify({
+            issuer: "http://127.0.0.1:9999",
+            authorization_endpoint: "http://127.0.0.1:9999/oauth/authorize",
+            token_endpoint: "http://127.0.0.1:9999/oauth/token",
+            response_types_supported: ["code"],
+            client_id_metadata_document_supported: true,
+          }),
+        );
+      }
+      return new Response(null, { status: 404 });
+    });
+    // Nothing may reach the network directly; a call here means a leg fell
+    // back to the global fetch.
+    const globalFetch = vi.fn();
+    vi.stubGlobal("fetch", globalFetch);
+
+    await ensureCimdClientRegistration({
+      serverUrl: SERVER_URL,
+      provider: createProvider(storage),
+      fetchFn,
+      resourceMetadataUrl: metadataUrl,
+    });
+
+    expect(globalFetch).not.toHaveBeenCalled();
+    const requested = fetchFn.mock.calls.map(([input]) => String(input));
+    expect(requested).toContain(metadataUrl.href);
+    expect(
+      requested.filter((url) =>
+        url.includes("/.well-known/oauth-protected-resource"),
+      ),
+    ).toEqual([]);
+    expect(storage.saveClientInformation).toHaveBeenCalledWith(
+      SERVER_URL,
+      { client_id: METADATA_URL },
+      { registrationKind: "cimd" },
+    );
+  });
+
   it("no-ops when client information is already stored", async () => {
     storage.getClientInformation = vi.fn(async () => ({
       client_id: "existing-client",

clients/web/src/test/core/mcp/node/authChallengeFetch.test.ts

@@ -1,5 +1,8 @@
 import { describe, it, expect, vi } from "vitest";
-import { createAuthChallengeInterceptFetch } from "@inspector/core/mcp/node/authChallengeFetch.js";
+import {
+  createAuthChallengeInterceptFetch,
+  createAuthChallengeObserverFetch,
+} from "@inspector/core/mcp/node/authChallengeFetch.js";
 import { AuthChallengeError } from "@inspector/core/auth/challenge.js";
 
 describe("createAuthChallengeInterceptFetch", () => {
@@ -84,3 +87,63 @@ describe("createAuthChallengeInterceptFetch", () => {
     );
   });
 });
+
+describe("createAuthChallengeObserverFetch", () => {
+  const METADATA_URL = "http://127.0.0.1:3001/custom/protected-resource";
+
+  it("reports a challenge without altering the response or its body", async () => {
+    const baseFetch = vi.fn(
+      async () =>
+        new Response("payload", {
+          status: 401,
+          headers: {
+            "WWW-Authenticate": `Bearer resource_metadata="${METADATA_URL}"`,
+          },
+        }),
+    );
+    const onChallenge = vi.fn();
+    const fetchFn = createAuthChallengeObserverFetch(baseFetch, onChallenge);
+
+    const res = await fetchFn("https://example.com/mcp");
+
+    expect(res.status).toBe(401);
+    // The body must survive for the transport (or the interceptor above).
+    expect(await res.text()).toBe("payload");
+    expect(onChallenge).toHaveBeenCalledWith(
+      expect.objectContaining({ resourceMetadataUrl: METADATA_URL }),
+    );
+  });
+
+  it("reports a 403 challenge too", async () => {
+    const baseFetch = vi.fn(
+      async () =>
+        new Response(null, {
+          status: 403,
+          headers: { "WWW-Authenticate": 'Bearer error="insufficient_scope"' },
+        }),
+    );
+    const onChallenge = vi.fn();
+
+    await createAuthChallengeObserverFetch(
+      baseFetch,
+      onChallenge,
+    )("https://example.com/mcp");
+
+    expect(onChallenge).toHaveBeenCalledWith(
+      expect.objectContaining({ reason: "insufficient_scope" }),
+    );
+  });
+
+  it("stays silent on a non-challenge response", async () => {
+    const baseFetch = vi.fn(async () => new Response("ok", { status: 200 }));
+    const onChallenge = vi.fn();
+
+    const res = await createAuthChallengeObserverFetch(
+      baseFetch,
+      onChallenge,
+    )("https://example.com/mcp");
+
+    expect(res.status).toBe(200);
+    expect(onChallenge).not.toHaveBeenCalled();
+  });
+});

clients/web/src/test/core/mcp/oauthManager.test.ts

@@ -1768,6 +1768,153 @@ describe("OAuthManager", () => {
     });
   });
 
+  describe("resource_metadata forwarding (RFC 9728) — #2071", () => {
+    const METADATA_URL = "http://127.0.0.1:3001/custom/protected-resource";
+
+    it("forwards the advertised metadata URL to auth() as a URL", async () => {
+      mockedMcpAuth.mockResolvedValue("AUTHORIZED");
+      const manager = new OAuthManager(createMockParams());
+
+      await manager.handleAuthChallenge({
+        reason: "token_expired",
+        resourceMetadataUrl: METADATA_URL,
+      });
+
+      expect(mockedMcpAuth).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({
+          resourceMetadataUrl: new URL(METADATA_URL),
+        }),
+      );
+    });
+
+    it("leaves the metadata URL undefined when the challenge advertises none", async () => {
+      mockedMcpAuth.mockResolvedValue("AUTHORIZED");
+      const manager = new OAuthManager(createMockParams());
+
+      await manager.handleAuthChallenge({ reason: "token_expired" });
+
+      expect(mockedMcpAuth).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ resourceMetadataUrl: undefined }),
+      );
+    });
+
+    it("ignores a malformed metadata URL rather than failing authorization", async () => {
+      mockedMcpAuth.mockResolvedValue("AUTHORIZED");
+      const manager = new OAuthManager(createMockParams());
+
+      const outcome = await manager.handleAuthChallenge({
+        reason: "token_expired",
+        resourceMetadataUrl: "not-a-url",
+      });
+
+      expect(outcome).toEqual({ kind: "satisfied" });
+      expect(mockedMcpAuth).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ resourceMetadataUrl: undefined }),
+      );
+    });
+
+    it("uses the last observed challenge on the plain authenticate() path", async () => {
+      // The legacy first-authorization path: no challenge is passed in, so the
+      // one the transport observed is the only source (#2071).
+      mockedMcpAuth.mockResolvedValue("REDIRECT");
+      const params = createMockParams();
+      const manager = new OAuthManager(params);
+      const captureSpy = vi
+        .spyOn(
+          (await import("@inspector/core/auth/providers.js"))
+            .BaseOAuthClientProvider.prototype,
+          "getCapturedAuthUrl",
+        )
+        .mockReturnValue(new URL("https://auth.example.com/authorize?state=x"));
+
+      manager.noteObservedAuthChallenge({
+        reason: "unauthorized",
+        resourceMetadataUrl: METADATA_URL,
+      });
+      await manager.authenticate();
+
+      expect(mockedMcpAuth).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({
+          resourceMetadataUrl: new URL(METADATA_URL),
+        }),
+      );
+      captureSpy.mockRestore();
+    });
+
+    it("clears the observed URL when a later challenge advertises none", async () => {
+      mockedMcpAuth.mockResolvedValue("REDIRECT");
+      const params = createMockParams();
+      const manager = new OAuthManager(params);
+      const captureSpy = vi
+        .spyOn(
+          (await import("@inspector/core/auth/providers.js"))
+            .BaseOAuthClientProvider.prototype,
+          "getCapturedAuthUrl",
+        )
+        .mockReturnValue(new URL("https://auth.example.com/authorize?state=x"));
+
+      manager.noteObservedAuthChallenge({
+        reason: "unauthorized",
+        resourceMetadataUrl: METADATA_URL,
+      });
+      manager.noteObservedAuthChallenge({ reason: "unauthorized" });
+      await manager.authenticate();
+
+      expect(mockedMcpAuth).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ resourceMetadataUrl: undefined }),
+      );
+      captureSpy.mockRestore();
+    });
+
+    it("forwards it on the forced step-up reauthorization leg too", async () => {
+      mockedMcpAuth.mockResolvedValue("AUTHORIZED");
+      const params = createMockParams();
+      const noScopeTokens = {
+        access_token: "a",
+        token_type: "Bearer",
+        scope: "",
+      };
+      const midScopeTokens = {
+        access_token: "b",
+        token_type: "Bearer",
+        scope: "newscope",
+      };
+      const grantedTokens = {
+        access_token: "d",
+        token_type: "Bearer",
+        scope: "granted:scope",
+      };
+      storageOf(params)
+        .getTokens.mockResolvedValueOnce(undefined)
+        .mockResolvedValueOnce(undefined)
+        .mockResolvedValueOnce(noScopeTokens)
+        .mockResolvedValueOnce(noScopeTokens)
+        .mockResolvedValueOnce(midScopeTokens)
+        .mockResolvedValueOnce(grantedTokens);
+      const manager = new OAuthManager(params);
+
+      await manager.handleAuthChallenge({
+        reason: "insufficient_scope",
+        resourceMetadataUrl: METADATA_URL,
+      });
+
+      expect(mockedMcpAuth).toHaveBeenCalledTimes(2);
+      expect(mockedMcpAuth).toHaveBeenNthCalledWith(
+        2,
+        expect.anything(),
+        expect.objectContaining({
+          forceReauthorization: true,
+          resourceMetadataUrl: new URL(METADATA_URL),
+        }),
+      );
+    });
+  });
+
   describe("handleAuthChallenge (additional branch coverage)", () => {
     it("resolves via the second satisfaction check inside the mutex", async () => {
       const params = createMockParams();

clients/web/src/test/integration/mcp/oauth-resource-metadata-challenge.test.ts

@@ -0,0 +1,266 @@
+/**
+ * RFC 9728 `resource_metadata` end-to-end, against a real OAuth test server
+ * whose protected-resource metadata document lives at a non-default path and
+ * whose well-known locations deliberately 404 (#2071).
+ *
+ * The unit tests prove the URL is parsed and handed to `mcpAuth()`. This file
+ * proves the two halves that only a real server can: that the challenge the
+ * server actually emits parses into `AuthChallenge.resourceMetadataUrl`, and
+ * that SDK discovery genuinely cannot find the document without it — so the
+ * plumbing is load-bearing rather than merely present.
+ */
+
+import { describe, it, expect, beforeAll, afterAll, vi } from "vitest";
+import { createServer } from "node:http";
+import { fileURLToPath } from "node:url";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discoverOAuthProtectedResourceMetadata } from "@modelcontextprotocol/client";
+import {
+  TestServerHttp,
+  getDefaultServerConfig,
+  createOAuthTestServerConfig,
+  isOriginRelativePath,
+  loadConfig,
+  resolveConfig,
+  waitForOAuthWellKnown,
+} from "@modelcontextprotocol/inspector-test-server";
+import {
+  challengeResourceMetadataUrl,
+  parseAuthChallengeFromResponse,
+} from "@inspector/core/auth/challenge.js";
+import type { AuthChallenge } from "@inspector/core/auth/challenge.js";
+import { InspectorClient } from "@inspector/core/mcp/inspectorClient.js";
+import { createTransportNode } from "@inspector/core/mcp/node/transport.js";
+import {
+  ConsoleNavigation,
+  type RedirectUrlProvider,
+} from "@inspector/core/auth/providers.js";
+import { NodeOAuthStorage } from "@inspector/core/auth/node/storage-node.js";
+
+const METADATA_PATH = "/custom/protected-resource";
+const STATIC_CLIENT_ID = "test-2071-resource-metadata";
+const STATIC_CLIENT_SECRET = "test-2071-secret";
+const REDIRECT_URL = "http://localhost:3000/oauth/callback";
+/** Fixed, since this one is asserted against a server of its own. */
+const METADATA_URL_LITERAL = "http://127.0.0.1:3001/custom/protected-resource";
+
+describe("OAuth challenge resource_metadata (RFC 9728)", () => {
+  let mcpServer: TestServerHttp | null = null;
+  let serverUrl = "";
+  let storageDir = "";
+
+  beforeAll(async () => {
+    mcpServer = new TestServerHttp({
+      ...getDefaultServerConfig(),
+      serverType: "streamable-http" as const,
+      ...createOAuthTestServerConfig({
+        requireAuth: true,
+        resourceMetadataPath: METADATA_PATH,
+        // Static rather than DCR: this suite is about *where the metadata
+        // document is found*, so registration should not be a second thing
+        // that can fail.
+        staticClients: [
+          {
+            clientId: STATIC_CLIENT_ID,
+            clientSecret: STATIC_CLIENT_SECRET,
+            redirectUris: [REDIRECT_URL],
+          },
+        ],
+      }),
+    });
+    const port = await mcpServer.start();
+    serverUrl = `http://localhost:${port}`;
+    storageDir = mkdtempSync(join(tmpdir(), "mcp-inspector-2071-"));
+    await waitForOAuthWellKnown(serverUrl);
+  }, 30_000);
+
+  afterAll(async () => {
+    await mcpServer?.stop();
+    mcpServer = null;
+    if (storageDir) {
+      rmSync(storageDir, { recursive: true, force: true });
+      storageDir = "";
+    }
+  }, 30_000);
+
+  it("advertises the non-default metadata URL on the 401 challenge", async () => {
+    const response = await fetch(`${serverUrl}/mcp`, { method: "POST" });
+
+    expect(response.status).toBe(401);
+    const challenge = parseAuthChallengeFromResponse(response);
+    expect(challenge?.resourceMetadataUrl).toBe(`${serverUrl}${METADATA_PATH}`);
+    expect(challengeResourceMetadataUrl(challenge!)?.href).toBe(
+      `${serverUrl}${METADATA_PATH}`,
+    );
+  });
+
+  it("serves the metadata document only from the advertised path", async () => {
+    const advertised = await fetch(`${serverUrl}${METADATA_PATH}`);
+    expect(advertised.status).toBe(200);
+    await expect(advertised.json()).resolves.toMatchObject({
+      authorization_servers: [serverUrl],
+    });
+
+    const wellKnown = await fetch(
+      `${serverUrl}/.well-known/oauth-protected-resource`,
+    );
+    expect(wellKnown.status).toBe(404);
+  });
+
+  it("SDK discovery resolves with the advertised URL and fails without it", async () => {
+    await expect(
+      discoverOAuthProtectedResourceMetadata(serverUrl, {
+        resourceMetadataUrl: new URL(`${serverUrl}${METADATA_PATH}`),
+      }),
+    ).resolves.toMatchObject({ authorization_servers: [serverUrl] });
+
+    // The pre-fix behavior: discovery derived from the MCP server URL alone.
+    await expect(
+      discoverOAuthProtectedResourceMetadata(serverUrl),
+    ).rejects.toThrow();
+  });
+
+  it("drives first-time legacy authorization off the advertised URL (#2071)", async () => {
+    // The gap the challenge-driven plumbing alone does not close: with no
+    // stored token in the default legacy era, `InspectorClient` builds the
+    // transport with no `authProvider` and no challenge interception, so the
+    // 401 reaches the client as the SDK's headerless `UnauthorizedError` and
+    // the CLI/TUI runner calls `authenticate()` with nothing in hand. The
+    // observed-challenge path is what carries the URL across that gap.
+    const requested: string[] = [];
+    const spyFetch: typeof fetch = async (input, init) => {
+      requested.push(input instanceof Request ? input.url : String(input));
+      return fetch(input, init);
+    };
+
+    const redirectUrlProvider: RedirectUrlProvider = {
+      getRedirectUrl: () => REDIRECT_URL,
+    };
+
+    const client = new InspectorClient(
+      { type: "streamable-http", url: `${serverUrl}/mcp` },
+      {
+        environment: {
+          transport: createTransportNode,
+          fetch: spyFetch,
+          oauth: {
+            // A fresh path per run. SDK `auth()` persists its discovery
+            // state — the advertised metadata URL included — so a reused file
+            // would let a watch-mode rerun satisfy discovery from the cache
+            // and pass even with the observer plumbing removed (Copilot).
+            storage: new NodeOAuthStorage(join(storageDir, "oauth.json")),
+            navigation: new ConsoleNavigation(),
+            redirectUrlProvider,
+          },
+        },
+        oauth: {
+          clientId: STATIC_CLIENT_ID,
+          clientSecret: STATIC_CLIENT_SECRET,
+          scope: "mcp",
+        },
+      },
+    );
+
+    await expect(client.connect()).rejects.toThrow();
+
+    // Reaching an authorization URL at all means discovery resolved — which it
+    // can only have done through the advertised path, since the well-known one
+    // 404s on this server.
+    const authUrl = await client.authenticate();
+    expect(authUrl?.href).toContain("/oauth/authorize");
+
+    expect(requested).toContain(`${serverUrl}${METADATA_PATH}`);
+    expect(
+      requested.filter((url) =>
+        url.includes("/.well-known/oauth-protected-resource"),
+      ),
+    ).toEqual([]);
+
+    await client.disconnect();
+  }, 30_000);
+
+  it("observes the SSE challenge through a caller-supplied eventSourceInit.fetch", async () => {
+    // That explicit fetch is deliberately not proxy- or intercept-wrapped, so
+    // it used to bypass the observer entirely and a first-time legacy SSE
+    // authorization lost the advertised URL the same way (Copilot).
+    const sseServer = createServer((_req, res) => {
+      res.writeHead(401, {
+        "WWW-Authenticate": `Bearer resource_metadata="${METADATA_URL_LITERAL}"`,
+      });
+      res.end();
+    });
+    await new Promise<void>((resolve) => sseServer.listen(0, resolve));
+    const address = sseServer.address();
+    /* v8 ignore next 3 -- listen(0) on a TCP socket always yields an AddressInfo */
+    if (address === null || typeof address === "string") {
+      throw new Error("expected a TCP address");
+    }
+
+    const explicitFetch = vi.fn<typeof fetch>((input, init) =>
+      fetch(input, init),
+    );
+    const observed: AuthChallenge[] = [];
+
+    try {
+      const { transport } = createTransportNode(
+        {
+          type: "sse",
+          url: `http://127.0.0.1:${address.port}/sse`,
+          eventSourceInit: { fetch: explicitFetch },
+        },
+        {
+          onAuthChallengeObserved: (challenge) => observed.push(challenge),
+        },
+      );
+
+      await expect(transport.start()).rejects.toThrow();
+      await transport.close().catch(() => {});
+    } finally {
+      await new Promise<void>((resolve) => sseServer.close(() => resolve()));
+    }
+
+    expect(explicitFetch).toHaveBeenCalled();
+    expect(observed).toContainEqual(
+      expect.objectContaining({ resourceMetadataUrl: METADATA_URL_LITERAL }),
+    );
+  }, 30_000);
+
+  it("keeps the showcase config valid and carrying the custom path", () => {
+    const configPath = fileURLToPath(
+      new URL(
+        "../../../../../../test-servers/configs/oauth-custom-resource-metadata-http.json",
+        import.meta.url,
+      ),
+    );
+
+    // loadConfig validates as it parses, so this is the regression test for
+    // the checked-in showcase config as much as for the new field.
+    expect(resolveConfig(loadConfig(configPath)).oauth).toMatchObject({
+      enabled: true,
+      resourceMetadataPath: METADATA_PATH,
+    });
+  });
+
+  it.each([
+    ["/custom/protected-resource", true],
+    ["/a", true],
+    // Both re-point the origin when resolved against the request base while
+    // Express still registers the route locally, so the server would advertise
+    // a document it does not serve (Copilot).
+    ["//other-host/doc", false],
+    ["/\\other-host/doc", false],
+    ["https://other-host/doc", false],
+    ["custom/protected-resource", false],
+    ["/has a space", false],
+    // `href` preserves both, so these pass an origin+href comparison — but
+    // Express matches on the path alone and a fragment never reaches the
+    // server, so the advertised URL could not resolve to the route.
+    ["/doc?version=1", false],
+    ["/doc#section", false],
+    ["", false],
+  ])("origin-relative path check: %j -> %s", (value, expected) => {
+    expect(isOriginRelativePath(value)).toBe(expected);
+  });
+});

core/auth/challenge.ts

@@ -26,6 +26,17 @@ export interface AuthChallenge {
   /** Resource authorization server audience when known. */
   audience?: string;
 
+  /**
+   * RFC 9728 `resource_metadata` advertised by the `WWW-Authenticate` challenge.
+   *
+   * Kept as a string so the challenge stays serializable — it crosses the web
+   * client's remote-backend boundary as JSON. Converted to a `URL` (and
+   * discarded if malformed) at the OAuth boundary, where it is handed to the
+   * SDK as `resourceMetadataUrl` so protected-resource discovery targets the
+   * advertised document instead of a location derived from the MCP server URL.
+   */
+  resourceMetadataUrl?: string;
+
   /** Optional human-readable detail from server or SDK (for UI, not parsing). */
   message?: string;
 
@@ -193,6 +204,30 @@ export function parseWwwAuthenticateBearer(
   };
 }
 
+/**
+ * Convert a challenge's advertised RFC 9728 `resource_metadata` value into the
+ * `URL` the SDK's `auth()` takes as `resourceMetadataUrl`.
+ *
+ * A malformed value is ignored rather than surfaced, matching the SDK's own
+ * `WWW-Authenticate` parser (`extractWWWAuthenticateParams`), which drops a
+ * value `new URL()` rejects. Discovery then falls back to the default
+ * RFC 9728 locations derived from the MCP server URL — the pre-existing
+ * behavior — instead of failing the whole authorization on a bad header.
+ */
+export function challengeResourceMetadataUrl(
+  challenge: Pick<AuthChallenge, "resourceMetadataUrl">,
+): URL | undefined {
+  const value = challenge.resourceMetadataUrl?.trim();
+  if (!value) {
+    return undefined;
+  }
+  try {
+    return new URL(value);
+  } catch {
+    return undefined;
+  }
+}
+
 /** Split an OAuth scope string into individual scopes (space-separated). */
 export function parseScopeString(scope: string | undefined): string[] {
   if (!scope?.trim()) {
@@ -275,6 +310,9 @@ export function parseAuthChallengeFromResponse(
   return {
     reason: reasonFromHttpResponse(status, bearer),
     ...(requiredScopes.length > 0 ? { requiredScopes } : {}),
+    ...(bearer.resourceMetadata
+      ? { resourceMetadataUrl: bearer.resourceMetadata }
+      : {}),
     ...(bearer.errorDescription ? { message: bearer.errorDescription } : {}),
     ...(context ? { context } : {}),
     raw: {
@@ -337,6 +375,9 @@ export function parseAuthChallengeFromError(
   return {
     reason: reasonFromHttpResponse(status, bearer),
     ...(requiredScopes.length > 0 ? { requiredScopes } : {}),
+    ...(bearer.resourceMetadata
+      ? { resourceMetadataUrl: bearer.resourceMetadata }
+      : {}),
     ...(context ? { context } : {}),
     raw: {
       httpStatus: status,

core/auth/cimd.ts

@@ -14,11 +14,18 @@ import type { BaseOAuthClientProvider } from "./providers.js";
  * accepts an already-stored `client_id` (including `http://` URLs used by local
  * dev/test metadata servers). Production CIMD metadata documents should still
  * use HTTPS per SEP-991.
+ *
+ * `resourceMetadataUrl` is the RFC 9728 document advertised by the
+ * `WWW-Authenticate` challenge, when the caller has one. It matters here and
+ * not only in `auth()`: this runs *before* SDK `auth()`, so without it the
+ * pre-registration probe would do its own default-location discovery and miss
+ * a document served from a non-default path (#2071).
  */
 export async function ensureCimdClientRegistration(params: {
   serverUrl: string;
   provider: BaseOAuthClientProvider;
   fetchFn?: typeof fetch;
+  resourceMetadataUrl?: URL;
 }): Promise<void> {
   const clientMetadataUrl = params.provider.clientMetadataUrl?.trim();
   if (!clientMetadataUrl) return;
@@ -30,6 +37,13 @@ export async function ensureCimdClientRegistration(params: {
   try {
     resourceMetadata = await discoverOAuthProtectedResourceMetadata(
       params.serverUrl,
+      { resourceMetadataUrl: params.resourceMetadataUrl },
+      // The same fetch the AS-metadata leg below uses. On web that is
+      // `createRemoteFetch`, which proxies through the backend to sidestep
+      // CORS — on the global `fetch` this leg would fail in the browser, be
+      // swallowed by the catch, and leave CIMD probing the wrong
+      // authorization server (Copilot).
+      params.fetchFn,
     );
   } catch {
     resourceMetadata = undefined;

core/mcp/inspectorClient.ts

@@ -2025,6 +2025,16 @@ export class InspectorClient extends InspectorClientEventTarget {
         ...(this.serverSettings && { settings: this.serverSettings }),
       };
       if (this.isHttpOAuthConfig() && oauthManager) {
+        // Record every 401/403 the transport sees, whatever else happens to
+        // it. The legacy first-authorization path deliberately runs with no
+        // authProvider and no challenge interception (see below), so the SDK
+        // raises a headerless `UnauthorizedError` and the client calls
+        // `authenticate()` with nothing in hand — this is the only place the
+        // challenge's RFC 9728 `resource_metadata` still exists (#2071).
+        const manager = oauthManager;
+        transportOptions.onAuthChallengeObserved = (challenge) => {
+          manager.noteObservedAuthChallenge(challenge);
+        };
         if (oauthManager.isEnterpriseManaged()) {
           await oauthManager.trySilentEnterpriseManagedAuth();
           const provider = await oauthManager.createOAuthProviderForTransport();

core/mcp/node/authChallengeFetch.ts

@@ -2,6 +2,7 @@ import {
   AuthChallengeError,
   parseAuthChallengeFromResponse,
 } from "../../auth/challenge.js";
+import type { AuthChallenge } from "../../auth/challenge.js";
 
 /**
  * Wrap fetch so MCP HTTP 401/403 responses become {@link AuthChallengeError}
@@ -33,3 +34,37 @@ export function createAuthChallengeInterceptFetch(
     );
   };
 }
+
+/**
+ * Wrap fetch so every MCP HTTP 401/403 is *reported* — control flow untouched,
+ * response returned as-is.
+ *
+ * This is the passive sibling of {@link createAuthChallengeInterceptFetch},
+ * and it exists for the one case that one cannot cover: a first-time
+ * authorization in the default legacy era. There, `InspectorClient`
+ * deliberately builds the transport with no `authProvider` (so the SDK does
+ * not open a browser before the callback server is listening) and therefore
+ * leaves interception off, so the CLI/TUI runner catches a plain
+ * `UnauthorizedError` and calls `authenticate()` itself. That SDK error
+ * carries no headers, so the challenge's RFC 9728 `resource_metadata` would be
+ * lost before discovery ever starts (#2071) — the observer keeps it.
+ *
+ * Only the status line and headers are read; the body is left untouched for
+ * the transport (or the interceptor layered above this one) to consume.
+ */
+export function createAuthChallengeObserverFetch(
+  baseFetch: typeof fetch,
+  onChallenge: (challenge: AuthChallenge) => void,
+): typeof fetch {
+  return async (input, init) => {
+    const response = await baseFetch(input, init);
+    if (response.status === 401 || response.status === 403) {
+      const challenge = parseAuthChallengeFromResponse(response);
+      /* v8 ignore next 3 -- parseAuthChallengeFromResponse only returns undefined for non-401/403, which the status guard above already excludes */
+      if (challenge) {
+        onChallenge(challenge);
+      }
+    }
+    return response;
+  };
+}

core/mcp/node/transport.ts

@@ -12,7 +12,10 @@ import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
 import { SSEClientTransport } from "@modelcontextprotocol/client";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
 import { createFetchTracker } from "../fetchTracking.js";
-import { createAuthChallengeInterceptFetch } from "./authChallengeFetch.js";
+import {
+  createAuthChallengeInterceptFetch,
+  createAuthChallengeObserverFetch,
+} from "./authChallengeFetch.js";
 import { createProxyFetch } from "./proxyFetch.js";
 
 /**
@@ -49,6 +52,7 @@ export function createTransportNode(
     authProvider,
     settings,
     interceptAuthChallenges = false,
+    onAuthChallengeObserved,
   } = options;
 
   // `optionsFetchFn` is the caller's whole fetch stack and already sits on top of
@@ -57,9 +61,18 @@ export function createTransportNode(
   // that. The fallback is for the one caller that supplies nothing: the web
   // backend (`core/mcp/remote/node/server.ts`), which calls this directly.
   const baseFetch = optionsFetchFn ?? createProxyFetch() ?? globalThis.fetch;
+  // Purely passive, so — unlike proxying and interception — it is safe to
+  // apply to any fetch, including a caller's explicit one.
+  const withChallengeObserver = (inner: typeof fetch): typeof fetch =>
+    onAuthChallengeObserved
+      ? createAuthChallengeObserverFetch(inner, onAuthChallengeObserved)
+      : inner;
+  // The observer sits *under* the interceptor so it still reports the
+  // challenge on the path where interception throws — and, more to the point,
+  // on the legacy first-auth path where interception is off entirely.
   const fetchWithOptionalAuthIntercept = interceptAuthChallenges
-    ? createAuthChallengeInterceptFetch(baseFetch)
+    ? createAuthChallengeInterceptFetch(withChallengeObserver(baseFetch))
-    : baseFetch;
+    : withChallengeObserver(baseFetch);
 
   if (serverType === "stdio") {
     const stdioConfig = config as StdioServerConfig;
@@ -92,9 +105,15 @@ export function createTransportNode(
     // A caller-supplied eventSourceInit.fetch wins as-is (explicit fetch is not
     // re-wrapped for proxying); the default path uses fetchWithOptionalAuthIntercept
     // (the proxy-aware baseFetch plus the optional auth-challenge intercept).
-    const sseFetch =
+    // The challenge observer is applied either way: it is passive, and without
-      (sseConfig.eventSourceInit?.fetch as typeof fetch) ||
+    // it a first-time legacy SSE authorization through an explicit fetch would
-      fetchWithOptionalAuthIntercept;
+    // lose the challenge's `resource_metadata` the same way (Copilot).
+    const configuredSseFetch = sseConfig.eventSourceInit?.fetch as
+      | typeof fetch
+      | undefined;
+    const sseFetch = configuredSseFetch
+      ? withChallengeObserver(configuredSseFetch)
+      : fetchWithOptionalAuthIntercept;
     const trackedFetch = onFetchRequest
       ? createFetchTracker(sseFetch, {
           trackRequest: onFetchRequest,

core/mcp/oauthManager.ts

@@ -39,6 +39,7 @@ import type {
   HandleAuthChallengeOptions,
 } from "../auth/challenge.js";
 import {
+  challengeResourceMetadataUrl,
   parseScopeString,
   unionAuthorizationScopes,
 } from "../auth/challenge.js";
@@ -81,6 +82,12 @@ export class OAuthManager {
   private oauthFlowState: OAuthFlowState | null = null;
   /** SEP-2350 union scope pending until interactive step-up completes. */
   private pendingAuthorizationScope: string | undefined;
+
+  /**
+   * The RFC 9728 metadata URL from the last 401/403 the transport observed.
+   * See {@link noteObservedAuthChallenge}.
+   */
+  private observedResourceMetadataUrl: URL | undefined;
   private authChallengeMutex: Promise<void> = Promise.resolve();
 
   constructor(params: OAuthManagerParams) {
@@ -262,6 +269,20 @@ export class OAuthManager {
     return authorizationUrl;
   }
 
+  /**
+   * Record a challenge the transport saw but did not raise as one.
+   *
+   * The legacy first-authorization path connects with no `authProvider` and no
+   * challenge interception, so the client calls {@link authenticate} off a
+   * headerless SDK `UnauthorizedError` — this is what carries the advertised
+   * RFC 9728 metadata URL across that gap (#2071). Latest-wins: every
+   * challenge comes from the same server, so the most recent one is what that
+   * server currently says, including when it says nothing.
+   */
+  noteObservedAuthChallenge(challenge: AuthChallenge): void {
+    this.observedResourceMetadataUrl = challengeResourceMetadataUrl(challenge);
+  }
+
   async authenticate(): Promise<URL | undefined> {
     if (this.isEnterpriseManaged()) {
       return this.authenticateEnterpriseManaged();
@@ -272,16 +293,23 @@ export class OAuthManager {
 
     provider.clearCapturedAuthUrl();
 
+    // No challenge is passed to this entry point — it is reached from a plain
+    // unauthorized error — so the last one the transport observed is the only
+    // source for the advertised metadata URL.
+    const resourceMetadataUrl = this.observedResourceMetadataUrl;
+
     await ensureCimdClientRegistration({
       serverUrl,
       provider,
       fetchFn: this.params.effectiveAuthFetch,
+      resourceMetadataUrl,
     });
 
     const result = await mcpAuth(provider, {
       serverUrl,
       scope: provider.scope,
       fetchFn: this.params.effectiveAuthFetch,
+      resourceMetadataUrl,
     });
 
     if (result === "AUTHORIZED") {
@@ -733,10 +761,17 @@ export class OAuthManager {
 
     provider.clearCapturedAuthUrl();
 
+    // RFC 9728: honor the metadata document the challenge advertised rather
+    // than probing the default locations derived from the MCP server URL
+    // (#2071). The SDK persists it in its discovery state, so the callback leg
+    // recovers it without our passing it again.
+    const resourceMetadataUrl = challengeResourceMetadataUrl(enriched);
+
     await ensureCimdClientRegistration({
       serverUrl,
       provider,
       fetchFn: this.params.effectiveAuthFetch,
+      resourceMetadataUrl,
     });
 
     const scopeForAuth =
@@ -754,6 +789,7 @@ export class OAuthManager {
         serverUrl,
         scope: scopeForAuth,
         fetchFn: this.params.effectiveAuthFetch,
+        resourceMetadataUrl,
         ...(enriched.reason === "insufficient_scope" && {
           forceReauthorization: isStrictScopeSuperset(
             scopeForAuth,
@@ -883,6 +919,7 @@ export class OAuthManager {
         serverUrl,
         scope: scopeForAuth,
         fetchFn: this.params.effectiveAuthFetch,
+        resourceMetadataUrl: challengeResourceMetadataUrl(enriched),
         forceReauthorization: true,
       });
     } finally {

core/mcp/types.ts

@@ -38,6 +38,7 @@ import type {
   RedirectUrlProvider,
 } from "../auth/providers.js";
 import type { OAuthStorage } from "../auth/storage.js";
+import type { AuthChallenge } from "../auth/challenge.js";
 
 // Stdio transport config
 export interface StdioServerConfig {
@@ -903,6 +904,15 @@ export interface CreateTransportOptions {
    * become {@link AuthChallengeError} before the SDK calls `auth()` on a frozen provider.
    */
   interceptAuthChallenges?: boolean;
+
+  /**
+   * Called for every HTTP 401/403 the transport sees, without altering control
+   * flow. Unlike {@link interceptAuthChallenges} this never throws, so it also
+   * covers the legacy first-time-authorization path where interception is
+   * deliberately off and the SDK's headerless `UnauthorizedError` would
+   * otherwise lose the challenge's `resource_metadata` (#2071).
+   */
+  onAuthChallengeObserved?: (challenge: AuthChallenge) => void;
 }
 
 export interface CreateTransportResult {

test-servers/configs/oauth-custom-resource-metadata-http.json

@@ -0,0 +1,19 @@
+{
+  "serverInfo": {
+    "name": "oauth-custom-resource-metadata",
+    "version": "1.0.0"
+  },
+  "tools": [{ "preset": "echo" }],
+  "oauth": {
+    "enabled": true,
+    "mode": "combined",
+    "requireAuth": true,
+    "resourceMetadataPath": "/custom/protected-resource",
+    "scopesSupported": ["mcp"],
+    "supportDCR": true
+  },
+  "transport": {
+    "type": "streamable-http",
+    "port": 8082
+  }
+}

test-servers/src/composable-test-server.ts

@@ -573,6 +573,19 @@ export interface ServerConfig {
      */
     resource?: string;
 
+    /**
+     * Serve the RFC 9728 protected-resource metadata document from this
+     * non-default path *instead of* `/.well-known/oauth-protected-resource`,
+     * and advertise it via `WWW-Authenticate: Bearer resource_metadata="…"`
+     * on every 401.
+     *
+     * The default well-known routes are deliberately left unserved, so a
+     * client that ignores the advertised URL cannot discover the document at
+     * all — which is what makes this a regression test for #2071 rather than
+     * a path that merely happens to work.
+     */
+    resourceMetadataPath?: string;
+
     /**
      * OAuth authorization server issuer URL (combined mode AS metadata).
      * If not provided, defaults to the test server's base URL.

test-servers/src/load-config.ts

@@ -6,6 +6,7 @@
 import { readFileSync } from "fs";
 import path from "path";
 import YAML from "yaml";
+import { isOriginRelativePath } from "./test-server-oauth.js";
 
 export interface PresetRef {
   preset: string;
@@ -19,6 +20,8 @@ export interface ConfigFileOAuth {
   mode?: "combined" | "protected-resource";
   authorizationServers?: string[];
   resource?: string;
+  /** Serve RFC 9728 metadata from this path and advertise it on 401 (#2071). */
+  resourceMetadataPath?: string;
   issuerUrl?: string;
   accessTokenIssuers?: string[];
   jwksUri?: string;
@@ -200,6 +203,12 @@ function validateConfig(
         }
       }
     }
+    const metadataPath = oauth.resourceMetadataPath;
+    if (metadataPath !== undefined && !isOriginRelativePath(metadataPath)) {
+      throw new Error(
+        `Invalid config in ${filePath}: oauth.resourceMetadataPath must be an origin-relative path (e.g. "/custom/protected-resource") — a value such as "//host/doc" would advertise a document the server does not serve`,
+      );
+    }
     if (transportType === "stdio" && oauth.enabled === true) {
       throw new Error(
         `Invalid config in ${filePath}: oauth requires streamable-http or sse transport`,

test-servers/src/test-server-fixtures.ts

@@ -2910,6 +2910,11 @@ export function createOAuthTestServerConfig(options: {
   supportCIMD?: boolean;
   tokenExpirationSeconds?: number;
   supportRefreshTokens?: boolean;
+  /**
+   * Move the RFC 9728 metadata document off the well-known path and advertise
+   * it via `WWW-Authenticate: Bearer resource_metadata="…"` (#2071).
+   */
+  resourceMetadataPath?: string;
 }): Partial<ServerConfig> {
   return {
     oauth: {
@@ -2917,6 +2922,12 @@ export function createOAuthTestServerConfig(options: {
       mode: "combined",
       requireAuth: options.requireAuth ?? false,
       scopesSupported: options.scopesSupported ?? ["mcp"],
+      // `!== undefined`, not truthiness: an explicitly supplied `""` is
+      // invalid, and dropping it here would silently fall back to the
+      // well-known route instead of reporting the bad fixture (Copilot).
+      ...(options.resourceMetadataPath !== undefined
+        ? { resourceMetadataPath: options.resourceMetadataPath }
+        : {}),
       staticClients: options.staticClients,
       supportDCR: options.supportDCR ?? false,
       supportCIMD: options.supportCIMD ?? false,

test-servers/src/test-server-oauth.ts

@@ -27,6 +27,79 @@ export function getOAuthMode(
   return config.mode ?? "combined";
 }
 
+const PATH_VALIDATION_BASE = "http://config.invalid";
+
+/**
+ * True for a path that resolves under its own origin — the only shape safe to
+ * use as both an Express route and a `resource_metadata` value.
+ *
+ * A leading-slash check is not enough: `//other-host/doc` and `/\other-host/doc`
+ * both re-point the origin when resolved against the request base (the URL
+ * parser folds a backslash into a slash for special schemes), while Express
+ * still registers the route locally — so the server would advertise a document
+ * it does not serve (Copilot). Comparing the resolved href against the literal
+ * also rejects anything the parser would rewrite (spaces, unescaped
+ * characters), which an Express route would not match either.
+ *
+ * A query or fragment is rejected for the same reason from the other
+ * direction: `href` preserves both, so `/doc?v=1` and `/doc#s` would pass the
+ * comparison above, yet Express matches on the path alone (and treats `?` as a
+ * pattern character) and a fragment is never sent on the wire at all — so the
+ * advertised URL could not reach the registered route (Copilot).
+ */
+export function isOriginRelativePath(value: unknown): value is string {
+  if (typeof value !== "string" || !value.startsWith("/")) {
+    return false;
+  }
+  try {
+    const resolved = new URL(value, PATH_VALIDATION_BASE);
+    return (
+      resolved.origin === PATH_VALIDATION_BASE &&
+      resolved.search === "" &&
+      resolved.hash === "" &&
+      resolved.href === `${PATH_VALIDATION_BASE}${value}`
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The configured metadata path, validated. Throws at server-setup time rather
+ * than serving a route that contradicts the challenge — the JSON-config path
+ * is validated earlier by `load-config`, so this covers a `ServerConfig`
+ * built programmatically.
+ */
+function resourceMetadataPath(config: OAuthConfig): string | undefined {
+  const path = config.resourceMetadataPath;
+  if (path === undefined) {
+    return undefined;
+  }
+  if (!isOriginRelativePath(path)) {
+    throw new Error(
+      `oauth.resourceMetadataPath must be an origin-relative path (got ${JSON.stringify(path)})`,
+    );
+  }
+  return path;
+}
+
+/**
+ * The `WWW-Authenticate` challenge sent with every 401.
+ *
+ * RFC 9728 §5.1: a resource server advertises where its protected-resource
+ * metadata lives via the `resource_metadata` parameter. Only emitted when the
+ * config moves that document off the well-known path — otherwise the bare
+ * `Bearer` challenge keeps the existing fixtures byte-identical.
+ */
+function bearerChallenge(config: OAuthConfig, req: Request): string {
+  const path = resourceMetadataPath(config);
+  if (!path) {
+    return "Bearer";
+  }
+  const requestBaseUrl = `${req.protocol}://${req.get("host")}`;
+  return `Bearer resource_metadata="${new URL(path, requestBaseUrl).href}"`;
+}
+
 /**
  * Set up OAuth routes on an Express application
  * This adds all OAuth endpoints (authorization, token, metadata, etc.)
@@ -76,7 +149,7 @@ export function createBearerTokenMiddleware(
       // For streamable-http, the SDK checks response status and throws StreamableHTTPError with code 401
       res.status(401);
       res.setHeader("Content-Type", "application/json");
-      res.setHeader("WWW-Authenticate", "Bearer");
+      res.setHeader("WWW-Authenticate", bearerChallenge(config, req));
       // Return a JSON-RPC error response format that the SDK will recognize
       res.json({
         jsonrpc: "2.0",
@@ -113,7 +186,7 @@ export function createBearerTokenMiddleware(
       // Return 401 - the SDK's transport should detect this and throw an error
       res.status(401);
       res.setHeader("Content-Type", "application/json");
-      res.setHeader("WWW-Authenticate", "Bearer");
+      res.setHeader("WWW-Authenticate", bearerChallenge(config, req));
       // Return a JSON-RPC error response format that the SDK will recognize
       res.json({
         jsonrpc: "2.0",
@@ -184,9 +257,12 @@ function setupMetadataEndpoints(
     );
   }
 
-  // OAuth Protected Resource Metadata
+  // OAuth Protected Resource Metadata. `resourceMetadataPath` moves the
+  // document off the well-known path entirely (rather than serving both), so
+  // a client that ignores the advertised `resource_metadata` URL gets a 404
+  // — see the field's doc comment.
   app.get(
-    "/.well-known/oauth-protected-resource",
+    resourceMetadataPath(config) ?? "/.well-known/oauth-protected-resource",
     (req: Request, res: Response) => {
       const requestBaseUrl = `${req.protocol}://${req.get("host")}`;
       const resourceUrl = config.resource ?? new URL("/", requestBaseUrl).href;