@ttoss/http-server-mcp 0.26.0 → 0.26.2

package/README.md

@@ -305,6 +305,17 @@ const mcpRouter = createMcpRouter(mcpServer, {
 
 MCP clients (Claude, Cursor, etc.) fetch `/.well-known/oauth-protected-resource` to discover which authorization server issues tokens for your MCP server. The endpoint must be **unauthenticated** — MCP clients call it before they have a token.
 
+The document is served at **two** locations, both unauthenticated:
+
+| Location                                      | Who fetches it                                                                                                                                                     |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/.well-known/oauth-protected-resource`       | Clients following the `resource_metadata` value in the `WWW-Authenticate` header                                                                                   |
+| `/.well-known/oauth-protected-resource<path>` | Clients applying RFC 9728 §3.1, which derives the URL from the resource identifier's path — e.g. `/.well-known/oauth-protected-resource/mcp` for the default mount |
+
+Serving only the root location makes a spec-following client fail discovery outright. When `path` is `'/'` the derivation produces the root itself, so only one route is registered.
+
+Both the locations and the document come from `protectedResourceMetadataPaths` / `protectedResourceMetadataDocument` in [`@ttoss/auth-core`](https://ttoss.dev/docs/modules/packages/auth-core), which every package here shares — so this router, `oauthServer`, `createProtectedResourceMetadataMiddleware`, and `getWwwAuthenticateHeader` cannot disagree about where the document lives.
+
 **With the built-in `auth` option** — add `resourceServerUrl` and `authorizationServerUrl`:
 
 ```typescript
@@ -361,25 +372,23 @@ The `WWW-Authenticate: Bearer resource_metadata="…"` header is how MCP clients
 The two behaviors the [MCP authorization spec](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/authorization/) requires for client bootstrapping are built into the `auth` option, so you no longer need the hand-rolled middleware shown above:
 
 - **`publicMethods`** — JSON-RPC methods that bypass verification, read from the request body's `method` field. Defaults to `['initialize', 'tools/list']` so clients can discover the server before authenticating. Pass `[]` to require a token for every method, or a custom list to change the exempt set. Leaving it unset serves the full tool catalogue — every tool name, description, and input schema — to unauthenticated callers, and logs a one-time warning explaining that and how to close it. Set `publicMethods` explicitly (even to the same default) to silence the warning.
-- **`resourceMetadataUrl`** — when set, a `401` responds with `WWW-Authenticate: Bearer resource_metadata="<resourceMetadataUrl>"` (RFC 9728) instead of a bare `Bearer`, pointing MCP clients at the protected-resource metadata document. When omitted, the header falls back to `Bearer`.
+- **`resourceMetadataUrl`** — the URL a `401` advertises as `WWW-Authenticate: Bearer resource_metadata="<url>"` (RFC 9728) instead of a bare `Bearer`, pointing MCP clients at the protected-resource metadata document. **You normally do not set it**: when the document is served — i.e. both `resourceServerUrl` and `authorizationServerUrl` are configured — it defaults to the RFC 9728 location this router serves it at, so the header and the routes cannot drift apart. When the document is not served, the header stays a bare `Bearer` rather than naming a location with no route. The field exists for the one configuration where this router deliberately does not serve the document — an `oauthServer()` in the same deployment already answers that path, so this router is mounted without `resourceServerUrl`/`authorizationServerUrl` to avoid two routers on one path, and has nothing to derive from. Compute the value with `protectedResourceMetadataUrl` from [`@ttoss/auth-core`](https://ttoss.dev/docs/modules/packages/auth-core) rather than typing it, so both halves apply the same §3.1 rule.
 
 ```typescript
 createMcpRouter(mcpServer, {
   auth: {
     cognitoUserPool: { userPoolId: '...', clientId: '...' },
-    // Serve the metadata document (unauthenticated)...
+    // Serves the metadata document (unauthenticated) and points 401s at it
+    // for auto-discovery — resourceMetadataUrl is derived from these two.
     resourceServerUrl: 'https://mcp.example.com',
     authorizationServerUrl:
       'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxx',
-    // ...and point 401s at it for auto-discovery.
-    resourceMetadataUrl:
-      'https://mcp.example.com/.well-known/oauth-protected-resource',
     // publicMethods defaults to ['initialize', 'tools/list'].
   },
 });
 ```
 
-Both fields are optional. Omitting `resourceMetadataUrl` keeps the bare `Bearer` header, and the `publicMethods` default matches what MCP clients expect for discovery.
+Every field is optional, and the `publicMethods` default matches what MCP clients expect for discovery.
 
 ### Supporting clients that connect to the bare origin
 
@@ -399,7 +408,7 @@ createMcpRouter(mcpServer, {
 });
 ```
 
-The discovery endpoint (`/.well-known/oauth-protected-resource`) remains publicly accessible even when `aliases` includes `'/'`.
+The discovery endpoints (both locations above) remain publicly accessible even when `aliases` includes `'/'`. Aliases themselves get no derived location — the metadata `resource` always names the primary `path`.
 
 ## Gated Tool Registrar
 
@@ -492,9 +501,9 @@ Creates a Koa router configured to handle MCP protocol requests.
     - `auth.cognitoUserPool` — Cognito user pool config (`userPoolId`, `clientId`, `tokenUse`)
     - `auth.verifyToken` — Custom async token verifier `(token: string) => Promise<unknown>`
     - `auth.requiredScopes` — Router-level scope guard; returns 403 if any scope is missing
-    - `auth.resourceServerUrl` + `auth.authorizationServerUrl` — Enable `/.well-known/oauth-protected-resource`; the metadata `resource` is set to `resourceServerUrl + path` so clients following `resource` land on the actual MCP endpoint
+    - `auth.resourceServerUrl` + `auth.authorizationServerUrl` — Enable the protected-resource metadata document, served at both `/.well-known/oauth-protected-resource` and the RFC 9728 path-derived `/.well-known/oauth-protected-resource<path>`; the metadata `resource` is set to `resourceServerUrl + path` so clients following `resource` land on the actual MCP endpoint
     - `auth.publicMethods` — JSON-RPC methods that bypass verification (default `['initialize', 'tools/list']`)
-    - `auth.resourceMetadataUrl` — Emit RFC 9728 `WWW-Authenticate: Bearer resource_metadata="…"` on 401
+    - `auth.resourceMetadataUrl` — URL advertised in the RFC 9728 `WWW-Authenticate: Bearer resource_metadata="…"` header on a 401. Defaults to the location derived from `resourceServerUrl` + `path` (the one this router serves), so the header cannot drift from the routes; set it only when a separate `oauthServer()` serves the document and this router is mounted without `resourceServerUrl`/`authorizationServerUrl`
     - `auth.resourceIndicator` — Expected `aud` value(s) (RFC 8707); rejects tokens minted for a different resource. See [Resource indicator validation](#resource-indicator-validation-rfc-8707)
 
 **Returns:** `Router` — Koa router instance

package/dist/index.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, {
   value: 'Module'
 });
+let _ttoss_auth_core = require("@ttoss/auth-core");
 let _ttoss_auth_core_amazon_cognito = require("@ttoss/auth-core/amazon-cognito");
 let _ttoss_http_server = require("@ttoss/http-server");
 let _ttoss_http_server_auth = require("@ttoss/http-server-auth");
@@ -531,6 +532,21 @@ var createMcpRouter = (server, options = {}) => {
   let authCheck;
   if (auth) {
     const verifyToken = buildVerifyToken(auth);
+    const base = auth.resourceServerUrl?.replace(/\/$/, "");
+    const resourceUrl = base === void 0 || path === "/" ? base : `${base}${path}`;
+    const metadata = resourceUrl !== void 0 && auth.authorizationServerUrl !== void 0 ? {
+      document: (0, _ttoss_auth_core.protectedResourceMetadataDocument)({
+        resource: resourceUrl,
+        authorizationServers: [auth.authorizationServerUrl]
+      }),
+      paths: (0, _ttoss_auth_core.protectedResourceMetadataPaths)({
+        resource: resourceUrl
+      }),
+      url: (0, _ttoss_auth_core.protectedResourceMetadataUrl)({
+        resource: resourceUrl
+      })
+    } : void 0;
+    const resourceMetadataUrl = auth.resourceMetadataUrl ?? metadata?.url;
     if (auth.publicMethods === void 0) console.warn(`[@ttoss/http-server-mcp] "auth" is configured but "publicMethods" was not set, so it defaults to ${JSON.stringify(DEFAULT_PUBLIC_METHODS)}. This means "tools/list" — the full tool catalogue, including names, descriptions, and input schemas — is served to unauthenticated callers. To require a token for "tools/list" too, set publicMethods: ['initialize']. To keep the current behaviour and silence this warning, set publicMethods: ${JSON.stringify(DEFAULT_PUBLIC_METHODS)} explicitly.`);
     const publicMethods = new Set(auth.publicMethods ?? DEFAULT_PUBLIC_METHODS);
     const verify = (0, _ttoss_http_server_auth.authMiddleware)({
@@ -541,7 +557,7 @@ var createMcpRouter = (server, options = {}) => {
         },
         requiredScopes: auth.requiredScopes
       },
-      resourceMetadataUrl: auth.resourceMetadataUrl
+      resourceMetadataUrl
     });
     authCheck = async (ctx, next) => {
       const method = ctx.request.body?.method;
@@ -551,16 +567,9 @@ var createMcpRouter = (server, options = {}) => {
       }
       await verify(ctx, next);
     };
-    if (auth.resourceServerUrl && auth.authorizationServerUrl) {
-      const base = auth.resourceServerUrl.replace(/\/$/, "");
-      const resourceUrl = path === "/" ? base : `${base}${path}`;
-      router.get("/.well-known/oauth-protected-resource", ctx => {
-        ctx.body = {
-          resource: resourceUrl,
-          authorization_servers: [auth.authorizationServerUrl]
-        };
-      });
-    }
+    if (metadata) for (const metadataPath of metadata.paths) router.get(metadataPath, ctx => {
+      ctx.body = metadata.document;
+    });
   }
   const handleWithContext = async (ctx, body) => {
     const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};

package/dist/index.d.cts

@@ -900,8 +900,37 @@ interface McpAuthOptions {
    */
   publicMethods?: string[];
   /**
-   * When set, a `401` carries `WWW-Authenticate: Bearer resource_metadata="…"`
-   * (RFC 9728) so MCP clients can discover the authorization server.
+   * URL advertised in `WWW-Authenticate: Bearer resource_metadata="…"`
+   * (RFC 9728) on a `401`, so MCP clients can discover the authorization
+   * server.
+   *
+   * Defaults to the location derived from `resourceServerUrl` + `path` — the
+   * same location this router serves the document at — so the header cannot
+   * drift from the routes. The default applies only when the document is
+   * actually served (both `resourceServerUrl` and `authorizationServerUrl`
+   * set); otherwise the header stays a bare `Bearer` rather than advertising a
+   * location with no route.
+   *
+   * **Leave it unset when this router serves the document.** It exists for the
+   * one configuration where that is deliberately not the case: an
+   * authorization server in the same deployment (`oauthServer({ resource })`)
+   * already answers `/.well-known/oauth-protected-resource`, so mounting this
+   * router with `resourceServerUrl` + `authorizationServerUrl` too would put
+   * two routers on one path. Omit both there and set this instead — without
+   * it the `401` is a bare `Bearer`, which never starts a client's discovery.
+   *
+   * Derive the value rather than typing it: `protectedResourceMetadataUrl`
+   * from `@ttoss/auth-core` applies the same RFC 9728 §3.1 rule the serving
+   * side does. A hand-written value that names a location nothing serves
+   * fails discovery silently.
+   *
+   * @example
+   * ```typescript
+   * // Only when oauthServer (not this router) serves the document.
+   * resourceMetadataUrl: protectedResourceMetadataUrl({
+   *   resource: 'https://mcp.example.com/mcp',
+   * }),
+   * ```
    */
   resourceMetadataUrl?: string;
   /**

package/dist/index.d.mts

@@ -901,8 +901,37 @@ interface McpAuthOptions {
    */
   publicMethods?: string[];
   /**
-   * When set, a `401` carries `WWW-Authenticate: Bearer resource_metadata="…"`
-   * (RFC 9728) so MCP clients can discover the authorization server.
+   * URL advertised in `WWW-Authenticate: Bearer resource_metadata="…"`
+   * (RFC 9728) on a `401`, so MCP clients can discover the authorization
+   * server.
+   *
+   * Defaults to the location derived from `resourceServerUrl` + `path` — the
+   * same location this router serves the document at — so the header cannot
+   * drift from the routes. The default applies only when the document is
+   * actually served (both `resourceServerUrl` and `authorizationServerUrl`
+   * set); otherwise the header stays a bare `Bearer` rather than advertising a
+   * location with no route.
+   *
+   * **Leave it unset when this router serves the document.** It exists for the
+   * one configuration where that is deliberately not the case: an
+   * authorization server in the same deployment (`oauthServer({ resource })`)
+   * already answers `/.well-known/oauth-protected-resource`, so mounting this
+   * router with `resourceServerUrl` + `authorizationServerUrl` too would put
+   * two routers on one path. Omit both there and set this instead — without
+   * it the `401` is a bare `Bearer`, which never starts a client's discovery.
+   *
+   * Derive the value rather than typing it: `protectedResourceMetadataUrl`
+   * from `@ttoss/auth-core` applies the same RFC 9728 §3.1 rule the serving
+   * side does. A hand-written value that names a location nothing serves
+   * fails discovery silently.
+   *
+   * @example
+   * ```typescript
+   * // Only when oauthServer (not this router) serves the document.
+   * resourceMetadataUrl: protectedResourceMetadataUrl({
+   *   resource: 'https://mcp.example.com/mcp',
+   * }),
+   * ```
    */
   resourceMetadataUrl?: string;
   /**

package/dist/index.mjs

@@ -1,4 +1,5 @@
 /** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { protectedResourceMetadataDocument, protectedResourceMetadataPaths, protectedResourceMetadataUrl } from "@ttoss/auth-core";
 import { CognitoJwtVerifier } from "@ttoss/auth-core/amazon-cognito";
 import { Router } from "@ttoss/http-server";
 import { authMiddleware } from "@ttoss/http-server-auth";
@@ -528,6 +529,21 @@ var createMcpRouter = (server, options = {}) => {
   let authCheck;
   if (auth) {
     const verifyToken = buildVerifyToken(auth);
+    const base = auth.resourceServerUrl?.replace(/\/$/, "");
+    const resourceUrl = base === void 0 || path === "/" ? base : `${base}${path}`;
+    const metadata = resourceUrl !== void 0 && auth.authorizationServerUrl !== void 0 ? {
+      document: protectedResourceMetadataDocument({
+        resource: resourceUrl,
+        authorizationServers: [auth.authorizationServerUrl]
+      }),
+      paths: protectedResourceMetadataPaths({
+        resource: resourceUrl
+      }),
+      url: protectedResourceMetadataUrl({
+        resource: resourceUrl
+      })
+    } : void 0;
+    const resourceMetadataUrl = auth.resourceMetadataUrl ?? metadata?.url;
     if (auth.publicMethods === void 0) console.warn(`[@ttoss/http-server-mcp] "auth" is configured but "publicMethods" was not set, so it defaults to ${JSON.stringify(DEFAULT_PUBLIC_METHODS)}. This means "tools/list" — the full tool catalogue, including names, descriptions, and input schemas — is served to unauthenticated callers. To require a token for "tools/list" too, set publicMethods: ['initialize']. To keep the current behaviour and silence this warning, set publicMethods: ${JSON.stringify(DEFAULT_PUBLIC_METHODS)} explicitly.`);
     const publicMethods = new Set(auth.publicMethods ?? DEFAULT_PUBLIC_METHODS);
     const verify = authMiddleware({
@@ -538,7 +554,7 @@ var createMcpRouter = (server, options = {}) => {
         },
         requiredScopes: auth.requiredScopes
       },
-      resourceMetadataUrl: auth.resourceMetadataUrl
+      resourceMetadataUrl
     });
     authCheck = async (ctx, next) => {
       const method = ctx.request.body?.method;
@@ -548,16 +564,9 @@ var createMcpRouter = (server, options = {}) => {
       }
       await verify(ctx, next);
     };
-    if (auth.resourceServerUrl && auth.authorizationServerUrl) {
-      const base = auth.resourceServerUrl.replace(/\/$/, "");
-      const resourceUrl = path === "/" ? base : `${base}${path}`;
-      router.get("/.well-known/oauth-protected-resource", ctx => {
-        ctx.body = {
-          resource: resourceUrl,
-          authorization_servers: [auth.authorizationServerUrl]
-        };
-      });
-    }
+    if (metadata) for (const metadataPath of metadata.paths) router.get(metadataPath, ctx => {
+      ctx.body = metadata.document;
+    });
   }
   const handleWithContext = async (ctx, body) => {
     const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -36,9 +36,9 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.4.3",
-    "@ttoss/http-server": "^0.8.1",
-    "@ttoss/http-server-auth": "^0.6.3",
-    "@ttoss/auth-core": "^0.14.0"
+    "@ttoss/auth-core": "^0.14.1",
+    "@ttoss/http-server-auth": "^0.6.4",
+    "@ttoss/http-server": "^0.8.1"
   },
   "devDependencies": {
     "@types/koa": "^3.0.3",