@ttoss/http-server-mcp 0.13.8 → 0.14.0

package/README.md

@@ -169,7 +169,7 @@ const mcpRouter = createMcpRouter(mcpServer, {
 
 ### Custom verifier
 
-Pass an async `verifyToken` function for any other provider (Auth0, Keycloak, etc.):
+Pass an async `verifyToken` function for any provider — JWT-based or opaque. The contract is simply: resolve with an identity payload on success, or throw on failure.
 
 ```typescript
 import { createMcpRouter } from '@ttoss/http-server-mcp';
@@ -189,6 +189,25 @@ const mcpRouter = createMcpRouter(mcpServer, {
 });
 ```
 
+**Opaque token (database lookup):** `verifyToken` does not have to be JWT-based — a plain API-key lookup works equally well:
+
+```typescript
+const mcpRouter = createMcpRouter(mcpServer, {
+  auth: {
+    verifyToken: async (token) => {
+      // Look up the hashed token in your database
+      const record = await db.apiKeys.findByHash(sha256(token));
+      if (!record || record.revokedAt) {
+        throw new Error('Invalid API key');
+      }
+      return { sub: record.userId, scope: record.scopes.join(' ') };
+    },
+  },
+});
+```
+
+The router emits `401 Unauthorized` whenever `verifyToken` throws, regardless of whether you are using JWTs or opaque tokens.
+
 ### Accessing the verified identity
 
 Inside any tool handler, call `getIdentity()` to retrieve the verified JWT payload:
@@ -245,7 +264,9 @@ Cognito encodes scopes as a space-separated string in `payload.scope` (e.g. `"op
 
 ### OAuth Protected Resource Metadata
 
-For MCP clients that support OAuth auto-discovery, add `resourceServerUrl` and `authorizationServerUrl` to expose the `/.well-known/oauth-protected-resource` endpoint (RFC 9728):
+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.
+
+**With the built-in `auth` option** — add `resourceServerUrl` and `authorizationServerUrl`:
 
 ```typescript
 createMcpRouter(mcpServer, {
@@ -258,6 +279,42 @@ createMcpRouter(mcpServer, {
 });
 ```
 
+**With your own auth middleware** — use `createProtectedResourceMetadataMiddleware` as a standalone middleware, mounted _before_ your auth layer so discovery stays unauthenticated:
+
+```typescript
+import {
+  createProtectedResourceMetadataMiddleware,
+  getWwwAuthenticateHeader,
+} from '@ttoss/http-server-mcp';
+
+// Mount the discovery endpoint before your own auth middleware
+app.use(
+  createProtectedResourceMetadataMiddleware({
+    resource: 'https://mcp.example.com',
+    authorizationServers: ['https://api.example.com'],
+  })
+);
+
+// Your own auth middleware — emit the spec-compliant WWW-Authenticate header on 401s
+app.use(async (ctx, next) => {
+  const token = ctx.headers.authorization?.replace('Bearer ', '');
+  if (!token || !(await myVerify(token))) {
+    ctx.status = 401;
+    ctx.set(
+      'WWW-Authenticate',
+      getWwwAuthenticateHeader({ resource: 'https://mcp.example.com' })
+    );
+    ctx.body = 'Unauthorized';
+    return;
+  }
+  await next();
+});
+
+app.use(createMcpRouter(mcpServer).routes());
+```
+
+The `WWW-Authenticate: Bearer resource_metadata="…"` header is how MCP clients bootstrap OAuth discovery after their first unauthorized request.
+
 ## API Reference
 
 ### `createMcpRouter(server, options?)`
@@ -307,6 +364,27 @@ Asserts that the current request token contains all required scopes. Throws `Err
 
 - `required` (`string[]`) — Scope strings that must all be present in `payload.scope`
 
+### `createProtectedResourceMetadataMiddleware(args)`
+
+Creates a standalone Koa middleware that serves `GET /.well-known/oauth-protected-resource` (RFC 9728). Use this when you have your own auth middleware and don't want to tie the discovery endpoint to the built-in `auth` option.
+
+**Parameters:**
+
+- `args.resource` (`string`) — The protected resource's identifier URI (your MCP server URL)
+- `args.authorizationServers` (`string[]`) — Issuer URIs of the authorization servers that protect this resource
+
+**Returns:** `Koa.Middleware`
+
+### `getWwwAuthenticateHeader(args)`
+
+Returns the `WWW-Authenticate` header value for a 401 response, formatted per the MCP auth spec: `Bearer resource_metadata="<resource>/.well-known/oauth-protected-resource"`.
+
+**Parameters:**
+
+- `args.resource` (`string`) — The protected resource URL (trailing slash is stripped automatically)
+
+**Returns:** `string` — The full `WWW-Authenticate` header value
+
 ### `registerToolFromSchema(server, params)`
 
 Registers a tool using a **plain JSON Schema** object for `inputSchema` instead of a Zod shape.

package/dist/index.cjs

@@ -380,6 +380,62 @@ var registerToolFromSchema = (server, params) => {
     });
   }
 };
+/**
+* Returns the `WWW-Authenticate` header value for a 401 response on a
+* protected resource, following the MCP auth spec requirement that
+* unauthorized responses advertise the resource metadata URL so MCP
+* clients can bootstrap OAuth discovery.
+*
+* Use this in your own auth middleware when you are not using the built-in
+* `auth` option on `createMcpRouter`.
+*
+* @example
+* ```typescript
+* import { getWwwAuthenticateHeader } from '@ttoss/http-server-mcp';
+*
+* // Inside a Koa middleware
+* ctx.status = 401;
+* ctx.set('WWW-Authenticate', getWwwAuthenticateHeader({ resource: 'https://mcp.example.com' }));
+* ```
+*/
+var getWwwAuthenticateHeader = args => {
+  return `Bearer resource_metadata="${`${args.resource.replace(/\/$/, "")}/.well-known/oauth-protected-resource`}"`;
+};
+/**
+* Creates a standalone Koa middleware that serves
+* `GET /.well-known/oauth-protected-resource` (RFC 9728) without requiring
+* the built-in `auth` option on `createMcpRouter`.
+*
+* Mount this **before** your own auth middleware so the discovery endpoint
+* remains unauthenticated (MCP clients fetch it before they have a token).
+*
+* @example
+* ```typescript
+* import Koa from 'koa';
+* import { createProtectedResourceMetadataMiddleware } from '@ttoss/http-server-mcp';
+*
+* const app = new Koa();
+* app.use(
+*   createProtectedResourceMetadataMiddleware({
+*     resource: 'https://mcp.example.com',
+*     authorizationServers: ['https://api.example.com'],
+*   })
+* );
+* app.use(myOwnAuthMiddleware);
+* ```
+*/
+var createProtectedResourceMetadataMiddleware = args => {
+  return async (ctx, next) => {
+    if (ctx.method === "GET" && ctx.path === "/.well-known/oauth-protected-resource") {
+      ctx.body = {
+        resource: args.resource,
+        authorization_servers: args.authorizationServers
+      };
+      return;
+    }
+    await next();
+  };
+};
 
 //#endregion
 Object.defineProperty(exports, 'McpServer', {
@@ -391,7 +447,9 @@ Object.defineProperty(exports, 'McpServer', {
 exports.apiCall = apiCall;
 exports.checkScopes = checkScopes;
 exports.createMcpRouter = createMcpRouter;
+exports.createProtectedResourceMetadataMiddleware = createProtectedResourceMetadataMiddleware;
 exports.getIdentity = getIdentity;
+exports.getWwwAuthenticateHeader = getWwwAuthenticateHeader;
 exports.registerToolFromSchema = registerToolFromSchema;
 Object.defineProperty(exports, 'z', {
   enumerable: true,

package/dist/index.d.cts

@@ -1006,5 +1006,64 @@ interface RegisterToolFromSchemaParams {
  * ```
  */
 declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
+/**
+ * Returns the `WWW-Authenticate` header value for a 401 response on a
+ * protected resource, following the MCP auth spec requirement that
+ * unauthorized responses advertise the resource metadata URL so MCP
+ * clients can bootstrap OAuth discovery.
+ *
+ * Use this in your own auth middleware when you are not using the built-in
+ * `auth` option on `createMcpRouter`.
+ *
+ * @example
+ * ```typescript
+ * import { getWwwAuthenticateHeader } from '@ttoss/http-server-mcp';
+ *
+ * // Inside a Koa middleware
+ * ctx.status = 401;
+ * ctx.set('WWW-Authenticate', getWwwAuthenticateHeader({ resource: 'https://mcp.example.com' }));
+ * ```
+ */
+declare const getWwwAuthenticateHeader: (args: {
+  /**
+   * The resource server URL. The metadata URL is derived as
+   * `<resource>/.well-known/oauth-protected-resource` per RFC 9728.
+   */
+  resource: string;
+}) => string;
+/**
+ * Creates a standalone Koa middleware that serves
+ * `GET /.well-known/oauth-protected-resource` (RFC 9728) without requiring
+ * the built-in `auth` option on `createMcpRouter`.
+ *
+ * Mount this **before** your own auth middleware so the discovery endpoint
+ * remains unauthenticated (MCP clients fetch it before they have a token).
+ *
+ * @example
+ * ```typescript
+ * import Koa from 'koa';
+ * import { createProtectedResourceMetadataMiddleware } from '@ttoss/http-server-mcp';
+ *
+ * const app = new Koa();
+ * app.use(
+ *   createProtectedResourceMetadataMiddleware({
+ *     resource: 'https://mcp.example.com',
+ *     authorizationServers: ['https://api.example.com'],
+ *   })
+ * );
+ * app.use(myOwnAuthMiddleware);
+ * ```
+ */
+declare const createProtectedResourceMetadataMiddleware: (args: {
+  /**
+   * The protected resource's identifier URI (the MCP server URL).
+   */
+  resource: string;
+  /**
+   * List of authorization server issuer URIs that issue tokens for this
+   * resource.
+   */
+  authorizationServers: string[];
+}) => Application.Middleware;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, apiCall, checkScopes, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, apiCall, checkScopes, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };

package/dist/index.d.mts

@@ -1006,5 +1006,64 @@ interface RegisterToolFromSchemaParams {
  * ```
  */
 declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
+/**
+ * Returns the `WWW-Authenticate` header value for a 401 response on a
+ * protected resource, following the MCP auth spec requirement that
+ * unauthorized responses advertise the resource metadata URL so MCP
+ * clients can bootstrap OAuth discovery.
+ *
+ * Use this in your own auth middleware when you are not using the built-in
+ * `auth` option on `createMcpRouter`.
+ *
+ * @example
+ * ```typescript
+ * import { getWwwAuthenticateHeader } from '@ttoss/http-server-mcp';
+ *
+ * // Inside a Koa middleware
+ * ctx.status = 401;
+ * ctx.set('WWW-Authenticate', getWwwAuthenticateHeader({ resource: 'https://mcp.example.com' }));
+ * ```
+ */
+declare const getWwwAuthenticateHeader: (args: {
+  /**
+   * The resource server URL. The metadata URL is derived as
+   * `<resource>/.well-known/oauth-protected-resource` per RFC 9728.
+   */
+  resource: string;
+}) => string;
+/**
+ * Creates a standalone Koa middleware that serves
+ * `GET /.well-known/oauth-protected-resource` (RFC 9728) without requiring
+ * the built-in `auth` option on `createMcpRouter`.
+ *
+ * Mount this **before** your own auth middleware so the discovery endpoint
+ * remains unauthenticated (MCP clients fetch it before they have a token).
+ *
+ * @example
+ * ```typescript
+ * import Koa from 'koa';
+ * import { createProtectedResourceMetadataMiddleware } from '@ttoss/http-server-mcp';
+ *
+ * const app = new Koa();
+ * app.use(
+ *   createProtectedResourceMetadataMiddleware({
+ *     resource: 'https://mcp.example.com',
+ *     authorizationServers: ['https://api.example.com'],
+ *   })
+ * );
+ * app.use(myOwnAuthMiddleware);
+ * ```
+ */
+declare const createProtectedResourceMetadataMiddleware: (args: {
+  /**
+   * The protected resource's identifier URI (the MCP server URL).
+   */
+  resource: string;
+  /**
+   * List of authorization server issuer URIs that issue tokens for this
+   * resource.
+   */
+  authorizationServers: string[];
+}) => Application.Middleware;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, apiCall, checkScopes, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, apiCall, checkScopes, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };

package/dist/index.mjs

@@ -377,6 +377,62 @@ var registerToolFromSchema = (server, params) => {
     });
   }
 };
+/**
+* Returns the `WWW-Authenticate` header value for a 401 response on a
+* protected resource, following the MCP auth spec requirement that
+* unauthorized responses advertise the resource metadata URL so MCP
+* clients can bootstrap OAuth discovery.
+*
+* Use this in your own auth middleware when you are not using the built-in
+* `auth` option on `createMcpRouter`.
+*
+* @example
+* ```typescript
+* import { getWwwAuthenticateHeader } from '@ttoss/http-server-mcp';
+*
+* // Inside a Koa middleware
+* ctx.status = 401;
+* ctx.set('WWW-Authenticate', getWwwAuthenticateHeader({ resource: 'https://mcp.example.com' }));
+* ```
+*/
+var getWwwAuthenticateHeader = args => {
+  return `Bearer resource_metadata="${`${args.resource.replace(/\/$/, "")}/.well-known/oauth-protected-resource`}"`;
+};
+/**
+* Creates a standalone Koa middleware that serves
+* `GET /.well-known/oauth-protected-resource` (RFC 9728) without requiring
+* the built-in `auth` option on `createMcpRouter`.
+*
+* Mount this **before** your own auth middleware so the discovery endpoint
+* remains unauthenticated (MCP clients fetch it before they have a token).
+*
+* @example
+* ```typescript
+* import Koa from 'koa';
+* import { createProtectedResourceMetadataMiddleware } from '@ttoss/http-server-mcp';
+*
+* const app = new Koa();
+* app.use(
+*   createProtectedResourceMetadataMiddleware({
+*     resource: 'https://mcp.example.com',
+*     authorizationServers: ['https://api.example.com'],
+*   })
+* );
+* app.use(myOwnAuthMiddleware);
+* ```
+*/
+var createProtectedResourceMetadataMiddleware = args => {
+  return async (ctx, next) => {
+    if (ctx.method === "GET" && ctx.path === "/.well-known/oauth-protected-resource") {
+      ctx.body = {
+        resource: args.resource,
+        authorization_servers: args.authorizationServers
+      };
+      return;
+    }
+    await next();
+  };
+};
 
 //#endregion
-export { McpServer, apiCall, checkScopes, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { McpServer, apiCall, checkScopes, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.13.8",
+  "version": "0.14.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -35,8 +35,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
-    "@ttoss/auth-core": "^0.6.0",
-    "@ttoss/http-server": "^0.6.1"
+    "@ttoss/http-server": "^0.6.1",
+    "@ttoss/auth-core": "^0.6.0"
   },
   "devDependencies": {
     "@types/koa": "^3.0.3",