docs(server/auth): document that resourceServerUrl and resourceMetadataUrl are needed for MCP-compliant discovery

packages/server-legacy/src/auth/router.ts

@@ -57,6 +57,14 @@ export type AuthRouterOptions = {
     /**
      * The URL of the protected resource (RS) whose metadata we advertise.
      * If not provided, falls back to `baseUrl` and then to `issuerUrl` (AS=RS).
+     *
+     * Pass the MCP endpoint URL itself (e.g. `https://api.example.com/mcp`), not just the
+     * origin. RFC 9728 §3 places the metadata at
+     * `/.well-known/oauth-protected-resource/<path>` and §3.3 requires its `resource` to be
+     * identical to the resource the client connected to. The `baseUrl` fallback therefore only
+     * yields a compliant document when the MCP endpoint is served at the origin root; clients
+     * that enforce §3.3 (Gemini CLI, Antigravity CLI) reject `resource: https://host/` when they
+     * connected to `https://host/mcp`, while the reference SDK client happens to accept it.
      */
     resourceServerUrl?: URL;
 

packages/server/src/server/middleware/bearerAuth.ts

@@ -44,9 +44,14 @@ export interface BearerAuthOptions {
     requiredScopes?: string[];
 
     /**
-     * Optional Protected Resource Metadata URL to advertise in the
-     * `WWW-Authenticate` header on 401/403 responses, per
-     * {@link https://datatracker.ietf.org/doc/html/rfc9728 | RFC 9728}.
+     * Protected Resource Metadata URL to advertise in the `WWW-Authenticate`
+     * header on 401/403 responses, per
+     * {@link https://datatracker.ietf.org/doc/html/rfc9728 | RFC 9728} §5.1.
+     *
+     * The MCP authorization spec requires MCP servers to send it, so pass it for
+     * any protected MCP endpoint. When omitted, clients must guess the well-known
+     * location and strict clients can fail discovery; leave it out only for
+     * non-MCP or legacy deployments.
      *
      * Typically built with `getOAuthProtectedResourceMetadataUrl`, exported
      * from this package.