@ttoss/http-server-mcp 0.22.0 → 0.23.1

package/README.md

@@ -266,6 +266,41 @@ mcpServer.registerTool(
 
 Cognito encodes scopes as a space-separated string in `payload.scope` (e.g. `"openid mcp:access admin"`).
 
+### Resource indicator validation (RFC 8707)
+
+`requiredScopes` checks _what_ a token can do; `resourceIndicator` checks that the token was minted _for this server_ in the first place. Without it, a token issued by your authorization server for a different resource (another API, another MCP server) would still pass verification here as long as the signature checks out — the classic confused-deputy risk RFC 8707 exists to close.
+
+```typescript
+createMcpRouter(mcpServer, {
+  auth: {
+    cognitoUserPool: { userPoolId: '...', clientId: '...' },
+    resourceIndicator: 'https://mcp.example.com',
+  },
+});
+```
+
+The verified token's `aud` claim must include at least one of the configured values (a single string or an array of strings, for servers reachable under multiple hostnames), or the request receives `401 Unauthorized`. This applies uniformly regardless of the verification method — `cognitoUserPool`, a custom `verifyToken`, or `@ttoss/auth-core/oidc`'s `createOidcVerifier` below.
+
+### OIDC providers (Entra ID, Okta, Auth0, …)
+
+For any standards-compliant OIDC provider beyond Cognito, use `createOidcVerifier` from `@ttoss/auth-core/oidc`. It discovers the provider's signing keys from its `/.well-known/openid-configuration` document — no manual JWKS URL, no hand-rolled discovery:
+
+```typescript
+import { createOidcVerifier } from '@ttoss/auth-core/oidc';
+import { createMcpRouter } from '@ttoss/http-server-mcp';
+
+const mcpRouter = createMcpRouter(mcpServer, {
+  auth: {
+    verifyToken: createOidcVerifier({
+      issuer: 'https://login.microsoftonline.com/<tenant>/v2.0',
+    }),
+    resourceIndicator: 'https://mcp.example.com',
+  },
+});
+```
+
+`createOidcVerifier` deliberately does not validate `aud` itself — pass `resourceIndicator` alongside it, as shown, so audience validation stays consistent across every auth method this router supports. See the [`@ttoss/auth-core` README](https://ttoss.dev/docs/modules/packages/auth-core) for details on key caching and rotation.
+
 ### OAuth Protected Resource Metadata
 
 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.
@@ -460,6 +495,7 @@ Creates a Koa router configured to handle MCP protocol requests.
     - `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.publicMethods` — JSON-RPC methods that bypass verification (default `['initialize', 'tools/list']`)
     - `auth.resourceMetadataUrl` — Emit RFC 9728 `WWW-Authenticate: Bearer resource_metadata="…"` on 401
+    - `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

@@ -6,8 +6,8 @@ let _modelcontextprotocol_sdk_server_streamableHttp_js = require("@modelcontextp
 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");
-let zod = require("zod");
 let node_async_hooks = require("node:async_hooks");
+let zod = require("zod");
 let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
 
 //#region src/context.ts
@@ -24,6 +24,93 @@ var getIdentity = () => {
   return requestContextStore.getStore()?.identity;
 };
 
+//#endregion
+//#region src/registerToolFromSchema.ts
+var rawSchemaRegistryMap = /* @__PURE__ */new WeakMap();
+var patchedServerSet = /* @__PURE__ */new WeakSet();
+/**
+* Registers a tool on an MCP server using a **plain JSON Schema** object for
+* `inputSchema` instead of a Zod shape.
+*
+* This is useful when tool definitions are shared between the MCP server and an
+* AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
+* plain JSON Schema at runtime. Using this helper eliminates the lossy
+* JSON-Schema→Zod conversion that would otherwise be required.
+*
+* Internally the helper:
+* 1. Registers the tool via the standard `McpServer.registerTool` API using a
+*    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
+*    `tools/call` handler correctly routes requests and delivers raw args to
+*    your handler.
+* 2. Stores the original JSON Schema and patches the `tools/list` response
+*    handler so clients receive the verbatim JSON Schema over the wire.
+*
+* @param server - The `McpServer` instance to register the tool on.
+* @param params - Tool configuration including name, description, inputSchema,
+*   and handler.
+*
+* @example
+* ```typescript
+* import { registerToolFromSchema, McpServer } from '@ttoss/http-server-mcp';
+*
+* const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+*
+* registerToolFromSchema(server, {
+*   name: 'get-project',
+*   description: 'Get a project by ID',
+*   inputSchema: {
+*     type: 'object',
+*     properties: { id: { type: 'string', description: 'Project public ID' } },
+*     required: ['id'],
+*   },
+*   handler: async ({ id }) => ({
+*     content: [{ type: 'text', text: `Project: ${id}` }],
+*   }),
+* });
+* ```
+*/
+var registerToolFromSchema = (server, params) => {
+  const {
+    name,
+    description,
+    inputSchema = {
+      type: "object",
+      properties: {}
+    },
+    handler
+  } = params;
+  if (!rawSchemaRegistryMap.has(server)) rawSchemaRegistryMap.set(server, /* @__PURE__ */new Map());
+  rawSchemaRegistryMap.get(server).set(name, inputSchema);
+  server.registerTool(name, {
+    description,
+    inputSchema: zod.z.record(zod.z.string(), zod.z.unknown())
+  }, async args => {
+    return handler(args);
+  });
+  if (!patchedServerSet.has(server)) {
+    patchedServerSet.add(server);
+    const rawServer = server.server;
+    const origHandler = rawServer?._requestHandlers?.get("tools/list");
+    if (!origHandler && process.env.NODE_ENV !== "production") console.warn("[registerToolFromSchema] Could not patch tools/list — internal MCP SDK structure may have changed. The tool will still be callable, but tools/list may return a Zod-derived schema instead of the verbatim JSON Schema.");
+    if (origHandler) rawServer._requestHandlers.set("tools/list", async (rawRequest, extra) => {
+      const result = await origHandler(rawRequest, extra);
+      const schemas = rawSchemaRegistryMap.get(server);
+      if (!schemas) return result;
+      return {
+        ...result,
+        tools: result.tools.map(tool => {
+          const raw = schemas.get(tool.name);
+          if (raw !== void 0) return {
+            ...tool,
+            inputSchema: raw
+          };
+          return tool;
+        })
+      };
+    });
+  }
+};
+
 //#endregion
 //#region src/createGatedToolRegistrar.ts
 var toolError = message => {
@@ -145,19 +232,39 @@ var createGatedToolRegistrar = ({
 //#region src/index.ts
 /** MCP lifecycle/discovery methods reachable before a client authenticates. */
 var DEFAULT_PUBLIC_METHODS = ["initialize", "tools/list"];
+/**
+* Asserts that a verified token's `aud` claim includes at least one of the
+* expected resource indicator values. `aud` may be a single string or an
+* array of strings per the JWT spec (RFC 7519); both forms are checked.
+*/
+var assertResourceIndicator = (payload, resourceIndicator) => {
+  const expected = Array.isArray(resourceIndicator) ? resourceIndicator : [resourceIndicator];
+  const aud = payload?.aud;
+  if (!(typeof aud === "string" ? [aud] : Array.isArray(aud) ? aud : []).some(audience => {
+    return typeof audience === "string" && expected.includes(audience);
+  })) throw new Error(`Token audience does not include the expected resource indicator (expected one of: ${expected.join(", ")}).`);
+};
 /** Builds the token verifier from the MCP auth options. */
 var buildVerifyToken = auth => {
-  if (auth.cognitoUserPool) {
-    const verifier = _ttoss_auth_core_amazon_cognito.CognitoJwtVerifier.create({
-      tokenUse: "access",
-      ...auth.cognitoUserPool
-    });
-    return token => {
-      return verifier.verify(token);
-    };
-  }
-  if (auth.verifyToken) return auth.verifyToken;
-  throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
+  const verify = (() => {
+    if (auth.cognitoUserPool) {
+      const verifier = _ttoss_auth_core_amazon_cognito.CognitoJwtVerifier.create({
+        tokenUse: "access",
+        ...auth.cognitoUserPool
+      });
+      return token => {
+        return verifier.verify(token);
+      };
+    }
+    if (auth.verifyToken) return auth.verifyToken;
+    throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
+  })();
+  if (!auth.resourceIndicator) return verify;
+  return async token => {
+    const payload = await verify(token);
+    assertResourceIndicator(payload, auth.resourceIndicator);
+    return payload;
+  };
 };
 /**
 * Generic HTTP helper for use inside MCP tool handlers.
@@ -440,90 +547,6 @@ var createMcpRouter = (server, options = {}) => {
   }
   return router;
 };
-var rawSchemaRegistryMap = /* @__PURE__ */new WeakMap();
-var patchedServerSet = /* @__PURE__ */new WeakSet();
-/**
-* Registers a tool on an MCP server using a **plain JSON Schema** object for
-* `inputSchema` instead of a Zod shape.
-*
-* This is useful when tool definitions are shared between the MCP server and an
-* AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
-* plain JSON Schema at runtime. Using this helper eliminates the lossy
-* JSON-Schema→Zod conversion that would otherwise be required.
-*
-* Internally the helper:
-* 1. Registers the tool via the standard `McpServer.registerTool` API using a
-*    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
-*    `tools/call` handler correctly routes requests and delivers raw args to
-*    your handler.
-* 2. Stores the original JSON Schema and patches the `tools/list` response
-*    handler so clients receive the verbatim JSON Schema over the wire.
-*
-* @param server - The `McpServer` instance to register the tool on.
-* @param params - Tool configuration including name, description, inputSchema,
-*   and handler.
-*
-* @example
-* ```typescript
-* import { registerToolFromSchema, McpServer } from '@ttoss/http-server-mcp';
-*
-* const server = new McpServer({ name: 'my-server', version: '1.0.0' });
-*
-* registerToolFromSchema(server, {
-*   name: 'get-project',
-*   description: 'Get a project by ID',
-*   inputSchema: {
-*     type: 'object',
-*     properties: { id: { type: 'string', description: 'Project public ID' } },
-*     required: ['id'],
-*   },
-*   handler: async ({ id }) => ({
-*     content: [{ type: 'text', text: `Project: ${id}` }],
-*   }),
-* });
-* ```
-*/
-var registerToolFromSchema = (server, params) => {
-  const {
-    name,
-    description,
-    inputSchema = {
-      type: "object",
-      properties: {}
-    },
-    handler
-  } = params;
-  if (!rawSchemaRegistryMap.has(server)) rawSchemaRegistryMap.set(server, /* @__PURE__ */new Map());
-  rawSchemaRegistryMap.get(server).set(name, inputSchema);
-  server.registerTool(name, {
-    description,
-    inputSchema: zod.z.record(zod.z.string(), zod.z.unknown())
-  }, async args => {
-    return handler(args);
-  });
-  if (!patchedServerSet.has(server)) {
-    patchedServerSet.add(server);
-    const rawServer = server.server;
-    const origHandler = rawServer?._requestHandlers?.get("tools/list");
-    if (!origHandler && process.env.NODE_ENV !== "production") console.warn("[registerToolFromSchema] Could not patch tools/list — internal MCP SDK structure may have changed. The tool will still be callable, but tools/list may return a Zod-derived schema instead of the verbatim JSON Schema.");
-    if (origHandler) rawServer._requestHandlers.set("tools/list", async (rawRequest, extra) => {
-      const result = await origHandler(rawRequest, extra);
-      const schemas = rawSchemaRegistryMap.get(server);
-      if (!schemas) return result;
-      return {
-        ...result,
-        tools: result.tools.map(tool => {
-          const raw = schemas.get(tool.name);
-          if (raw !== void 0) return {
-            ...tool,
-            inputSchema: raw
-          };
-          return tool;
-        })
-      };
-    });
-  }
-};
 
 //#endregion
 Object.defineProperty(exports, 'McpServer', {

package/dist/index.d.cts

@@ -1,7 +1,6 @@
 
 /// <reference types="node" />
 import { McpServer, McpServer as McpServer$1 } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { Router } from "@ttoss/http-server";
 import accepts from "accepts";
 import { AsyncLocalStorage } from "async_hooks";
@@ -17,6 +16,7 @@ import compose from "koa-compose";
 import { ListenOptions, Socket } from "net";
 import { ParsedUrlQuery } from "querystring";
 import * as url from "url";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
 //#region ../../node_modules/.pnpm/@types+koa@3.0.3/node_modules/@types/koa/index.d.ts
@@ -676,6 +676,84 @@ declare namespace Application {
  */
 declare const getIdentity: <T = unknown>() => T | undefined;
 //#endregion
+//#region src/registerToolFromSchema.d.ts
+/**
+ * A plain JSON Schema object (draft-07 compatible) describing the shape of a
+ * tool's input. Used with {@link registerToolFromSchema} as an alternative to
+ * providing a Zod shape, enabling lossless round-trips for schemas that contain
+ * features not expressible in Zod v3 (`anyOf`, `$ref`, `pattern`, `allOf`, …).
+ */
+interface JsonObjectSchema {
+  type: 'object';
+  properties?: Record<string, unknown>;
+  required?: string[];
+  [key: string]: unknown;
+}
+/**
+ * Parameters accepted by {@link registerToolFromSchema}.
+ */
+interface RegisterToolFromSchemaParams {
+  /** Unique tool name. */
+  name: string;
+  /** Human-readable description shown to the AI client. */
+  description?: string;
+  /**
+   * Plain JSON Schema that describes the tool's input object.
+   * This schema is forwarded verbatim over the MCP wire protocol, so any
+   * JSON Schema feature (`anyOf`, `$ref`, `pattern`, …) is preserved without
+   * loss. Defaults to `{ type: 'object', properties: {} }` when omitted.
+   */
+  inputSchema?: JsonObjectSchema;
+  /**
+   * Tool handler invoked when the AI client calls the tool.
+   * Receives the raw request arguments as a plain object (no Zod validation is
+   * applied, so the shape matches whatever the client sends).
+   */
+  handler: (args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>;
+}
+/**
+ * Registers a tool on an MCP server using a **plain JSON Schema** object for
+ * `inputSchema` instead of a Zod shape.
+ *
+ * This is useful when tool definitions are shared between the MCP server and an
+ * AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
+ * plain JSON Schema at runtime. Using this helper eliminates the lossy
+ * JSON-Schema→Zod conversion that would otherwise be required.
+ *
+ * Internally the helper:
+ * 1. Registers the tool via the standard `McpServer.registerTool` API using a
+ *    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
+ *    `tools/call` handler correctly routes requests and delivers raw args to
+ *    your handler.
+ * 2. Stores the original JSON Schema and patches the `tools/list` response
+ *    handler so clients receive the verbatim JSON Schema over the wire.
+ *
+ * @param server - The `McpServer` instance to register the tool on.
+ * @param params - Tool configuration including name, description, inputSchema,
+ *   and handler.
+ *
+ * @example
+ * ```typescript
+ * import { registerToolFromSchema, McpServer } from '@ttoss/http-server-mcp';
+ *
+ * const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+ *
+ * registerToolFromSchema(server, {
+ *   name: 'get-project',
+ *   description: 'Get a project by ID',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: { id: { type: 'string', description: 'Project public ID' } },
+ *     required: ['id'],
+ *   },
+ *   handler: async ({ id }) => ({
+ *     content: [{ type: 'text', text: `Project: ${id}` }],
+ *   }),
+ * });
+ * ```
+ */
+declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
+//#endregion
 //#region src/createGatedToolRegistrar.d.ts
 /** Resolved identity for a gated tool call. */
 type ToolIdentity = {
@@ -816,6 +894,22 @@ interface McpAuthOptions {
   resourceServerUrl?: string;
   /** URL of the OAuth Authorization Server that issues tokens for this resource. */
   authorizationServerUrl?: string;
+  /**
+   * Expected audience — the resource indicator (RFC 8707) this MCP server
+   * identifies as. When set, the verified token's `aud` claim must include at
+   * least one of these values, or the request is rejected with `401`. Without
+   * this check, a token minted for a *different* resource but signed by the
+   * same authorization server would still be accepted here — the classic
+   * confused-deputy risk RFC 8707 exists to close.
+   *
+   * Applies uniformly regardless of whether verification is done via
+   * `cognitoUserPool`, a custom `verifyToken`, or `@ttoss/auth-core/oidc`'s
+   * `createOidcVerifier` (which intentionally leaves audience validation to
+   * the caller for this reason).
+   *
+   * @example 'https://mcp.example.com'
+   */
+  resourceIndicator?: string | string[];
 }
 /**
  * Options for a single `apiCall` request.
@@ -1039,81 +1133,5 @@ interface McpRouterOptions {
  * ```
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => Router<Application.DefaultState, Application.DefaultContext>;
-/**
- * A plain JSON Schema object (draft-07 compatible) describing the shape of a
- * tool's input. Used with {@link registerToolFromSchema} as an alternative to
- * providing a Zod shape, enabling lossless round-trips for schemas that contain
- * features not expressible in Zod v3 (`anyOf`, `$ref`, `pattern`, `allOf`, …).
- */
-interface JsonObjectSchema {
-  type: 'object';
-  properties?: Record<string, unknown>;
-  required?: string[];
-  [key: string]: unknown;
-}
-/**
- * Parameters accepted by {@link registerToolFromSchema}.
- */
-interface RegisterToolFromSchemaParams {
-  /** Unique tool name. */
-  name: string;
-  /** Human-readable description shown to the AI client. */
-  description?: string;
-  /**
-   * Plain JSON Schema that describes the tool's input object.
-   * This schema is forwarded verbatim over the MCP wire protocol, so any
-   * JSON Schema feature (`anyOf`, `$ref`, `pattern`, …) is preserved without
-   * loss. Defaults to `{ type: 'object', properties: {} }` when omitted.
-   */
-  inputSchema?: JsonObjectSchema;
-  /**
-   * Tool handler invoked when the AI client calls the tool.
-   * Receives the raw request arguments as a plain object (no Zod validation is
-   * applied, so the shape matches whatever the client sends).
-   */
-  handler: (args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>;
-}
-/**
- * Registers a tool on an MCP server using a **plain JSON Schema** object for
- * `inputSchema` instead of a Zod shape.
- *
- * This is useful when tool definitions are shared between the MCP server and an
- * AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
- * plain JSON Schema at runtime. Using this helper eliminates the lossy
- * JSON-Schema→Zod conversion that would otherwise be required.
- *
- * Internally the helper:
- * 1. Registers the tool via the standard `McpServer.registerTool` API using a
- *    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
- *    `tools/call` handler correctly routes requests and delivers raw args to
- *    your handler.
- * 2. Stores the original JSON Schema and patches the `tools/list` response
- *    handler so clients receive the verbatim JSON Schema over the wire.
- *
- * @param server - The `McpServer` instance to register the tool on.
- * @param params - Tool configuration including name, description, inputSchema,
- *   and handler.
- *
- * @example
- * ```typescript
- * import { registerToolFromSchema, McpServer } from '@ttoss/http-server-mcp';
- *
- * const server = new McpServer({ name: 'my-server', version: '1.0.0' });
- *
- * registerToolFromSchema(server, {
- *   name: 'get-project',
- *   description: 'Get a project by ID',
- *   inputSchema: {
- *     type: 'object',
- *     properties: { id: { type: 'string', description: 'Project public ID' } },
- *     required: ['id'],
- *   },
- *   handler: async ({ id }) => ({
- *     content: [{ type: 'text', text: `Project: ${id}` }],
- *   }),
- * });
- * ```
- */
-declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, type ToolCallContext, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterToolFromSchemaParams, type ToolCallContext, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/dist/index.d.mts

@@ -1,10 +1,9 @@
 
 /// <reference types="node" />
 import { Router } from "@ttoss/http-server";
-import { z } from "zod";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { z } from "zod";
 import { McpServer, McpServer as McpServer$1 } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import accepts from "accepts";
 import { AsyncLocalStorage as AsyncLocalStorage$1 } from "async_hooks";
 import Cookies from "cookies";
@@ -19,6 +18,7 @@ import compose from "koa-compose";
 import { ListenOptions, Socket } from "net";
 import { ParsedUrlQuery } from "querystring";
 import * as url from "url";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 
 //#region ../../node_modules/.pnpm/@types+koa@3.0.3/node_modules/@types/koa/index.d.ts
 declare interface ContextDelegatedRequest {
@@ -677,6 +677,84 @@ declare namespace Application {
  */
 declare const getIdentity: <T = unknown>() => T | undefined;
 //#endregion
+//#region src/registerToolFromSchema.d.ts
+/**
+ * A plain JSON Schema object (draft-07 compatible) describing the shape of a
+ * tool's input. Used with {@link registerToolFromSchema} as an alternative to
+ * providing a Zod shape, enabling lossless round-trips for schemas that contain
+ * features not expressible in Zod v3 (`anyOf`, `$ref`, `pattern`, `allOf`, …).
+ */
+interface JsonObjectSchema {
+  type: 'object';
+  properties?: Record<string, unknown>;
+  required?: string[];
+  [key: string]: unknown;
+}
+/**
+ * Parameters accepted by {@link registerToolFromSchema}.
+ */
+interface RegisterToolFromSchemaParams {
+  /** Unique tool name. */
+  name: string;
+  /** Human-readable description shown to the AI client. */
+  description?: string;
+  /**
+   * Plain JSON Schema that describes the tool's input object.
+   * This schema is forwarded verbatim over the MCP wire protocol, so any
+   * JSON Schema feature (`anyOf`, `$ref`, `pattern`, …) is preserved without
+   * loss. Defaults to `{ type: 'object', properties: {} }` when omitted.
+   */
+  inputSchema?: JsonObjectSchema;
+  /**
+   * Tool handler invoked when the AI client calls the tool.
+   * Receives the raw request arguments as a plain object (no Zod validation is
+   * applied, so the shape matches whatever the client sends).
+   */
+  handler: (args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>;
+}
+/**
+ * Registers a tool on an MCP server using a **plain JSON Schema** object for
+ * `inputSchema` instead of a Zod shape.
+ *
+ * This is useful when tool definitions are shared between the MCP server and an
+ * AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
+ * plain JSON Schema at runtime. Using this helper eliminates the lossy
+ * JSON-Schema→Zod conversion that would otherwise be required.
+ *
+ * Internally the helper:
+ * 1. Registers the tool via the standard `McpServer.registerTool` API using a
+ *    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
+ *    `tools/call` handler correctly routes requests and delivers raw args to
+ *    your handler.
+ * 2. Stores the original JSON Schema and patches the `tools/list` response
+ *    handler so clients receive the verbatim JSON Schema over the wire.
+ *
+ * @param server - The `McpServer` instance to register the tool on.
+ * @param params - Tool configuration including name, description, inputSchema,
+ *   and handler.
+ *
+ * @example
+ * ```typescript
+ * import { registerToolFromSchema, McpServer } from '@ttoss/http-server-mcp';
+ *
+ * const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+ *
+ * registerToolFromSchema(server, {
+ *   name: 'get-project',
+ *   description: 'Get a project by ID',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: { id: { type: 'string', description: 'Project public ID' } },
+ *     required: ['id'],
+ *   },
+ *   handler: async ({ id }) => ({
+ *     content: [{ type: 'text', text: `Project: ${id}` }],
+ *   }),
+ * });
+ * ```
+ */
+declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
+//#endregion
 //#region src/createGatedToolRegistrar.d.ts
 /** Resolved identity for a gated tool call. */
 type ToolIdentity = {
@@ -817,6 +895,22 @@ interface McpAuthOptions {
   resourceServerUrl?: string;
   /** URL of the OAuth Authorization Server that issues tokens for this resource. */
   authorizationServerUrl?: string;
+  /**
+   * Expected audience — the resource indicator (RFC 8707) this MCP server
+   * identifies as. When set, the verified token's `aud` claim must include at
+   * least one of these values, or the request is rejected with `401`. Without
+   * this check, a token minted for a *different* resource but signed by the
+   * same authorization server would still be accepted here — the classic
+   * confused-deputy risk RFC 8707 exists to close.
+   *
+   * Applies uniformly regardless of whether verification is done via
+   * `cognitoUserPool`, a custom `verifyToken`, or `@ttoss/auth-core/oidc`'s
+   * `createOidcVerifier` (which intentionally leaves audience validation to
+   * the caller for this reason).
+   *
+   * @example 'https://mcp.example.com'
+   */
+  resourceIndicator?: string | string[];
 }
 /**
  * Options for a single `apiCall` request.
@@ -1040,81 +1134,5 @@ interface McpRouterOptions {
  * ```
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => Router<Application.DefaultState, Application.DefaultContext>;
-/**
- * A plain JSON Schema object (draft-07 compatible) describing the shape of a
- * tool's input. Used with {@link registerToolFromSchema} as an alternative to
- * providing a Zod shape, enabling lossless round-trips for schemas that contain
- * features not expressible in Zod v3 (`anyOf`, `$ref`, `pattern`, `allOf`, …).
- */
-interface JsonObjectSchema {
-  type: 'object';
-  properties?: Record<string, unknown>;
-  required?: string[];
-  [key: string]: unknown;
-}
-/**
- * Parameters accepted by {@link registerToolFromSchema}.
- */
-interface RegisterToolFromSchemaParams {
-  /** Unique tool name. */
-  name: string;
-  /** Human-readable description shown to the AI client. */
-  description?: string;
-  /**
-   * Plain JSON Schema that describes the tool's input object.
-   * This schema is forwarded verbatim over the MCP wire protocol, so any
-   * JSON Schema feature (`anyOf`, `$ref`, `pattern`, …) is preserved without
-   * loss. Defaults to `{ type: 'object', properties: {} }` when omitted.
-   */
-  inputSchema?: JsonObjectSchema;
-  /**
-   * Tool handler invoked when the AI client calls the tool.
-   * Receives the raw request arguments as a plain object (no Zod validation is
-   * applied, so the shape matches whatever the client sends).
-   */
-  handler: (args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>;
-}
-/**
- * Registers a tool on an MCP server using a **plain JSON Schema** object for
- * `inputSchema` instead of a Zod shape.
- *
- * This is useful when tool definitions are shared between the MCP server and an
- * AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
- * plain JSON Schema at runtime. Using this helper eliminates the lossy
- * JSON-Schema→Zod conversion that would otherwise be required.
- *
- * Internally the helper:
- * 1. Registers the tool via the standard `McpServer.registerTool` API using a
- *    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
- *    `tools/call` handler correctly routes requests and delivers raw args to
- *    your handler.
- * 2. Stores the original JSON Schema and patches the `tools/list` response
- *    handler so clients receive the verbatim JSON Schema over the wire.
- *
- * @param server - The `McpServer` instance to register the tool on.
- * @param params - Tool configuration including name, description, inputSchema,
- *   and handler.
- *
- * @example
- * ```typescript
- * import { registerToolFromSchema, McpServer } from '@ttoss/http-server-mcp';
- *
- * const server = new McpServer({ name: 'my-server', version: '1.0.0' });
- *
- * registerToolFromSchema(server, {
- *   name: 'get-project',
- *   description: 'Get a project by ID',
- *   inputSchema: {
- *     type: 'object',
- *     properties: { id: { type: 'string', description: 'Project public ID' } },
- *     required: ['id'],
- *   },
- *   handler: async ({ id }) => ({
- *     content: [{ type: 'text', text: `Project: ${id}` }],
- *   }),
- * });
- * ```
- */
-declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, type ToolCallContext, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterToolFromSchemaParams, type ToolCallContext, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/dist/index.mjs

@@ -3,8 +3,8 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { CognitoJwtVerifier } from "@ttoss/auth-core/amazon-cognito";
 import { Router } from "@ttoss/http-server";
 import { authMiddleware } from "@ttoss/http-server-auth";
-import { z, z as z$1 } from "zod";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { z, z as z$1 } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 //#region src/context.ts
@@ -21,6 +21,93 @@ var getIdentity = () => {
   return requestContextStore.getStore()?.identity;
 };
 
+//#endregion
+//#region src/registerToolFromSchema.ts
+var rawSchemaRegistryMap = /* @__PURE__ */new WeakMap();
+var patchedServerSet = /* @__PURE__ */new WeakSet();
+/**
+* Registers a tool on an MCP server using a **plain JSON Schema** object for
+* `inputSchema` instead of a Zod shape.
+*
+* This is useful when tool definitions are shared between the MCP server and an
+* AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
+* plain JSON Schema at runtime. Using this helper eliminates the lossy
+* JSON-Schema→Zod conversion that would otherwise be required.
+*
+* Internally the helper:
+* 1. Registers the tool via the standard `McpServer.registerTool` API using a
+*    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
+*    `tools/call` handler correctly routes requests and delivers raw args to
+*    your handler.
+* 2. Stores the original JSON Schema and patches the `tools/list` response
+*    handler so clients receive the verbatim JSON Schema over the wire.
+*
+* @param server - The `McpServer` instance to register the tool on.
+* @param params - Tool configuration including name, description, inputSchema,
+*   and handler.
+*
+* @example
+* ```typescript
+* import { registerToolFromSchema, McpServer } from '@ttoss/http-server-mcp';
+*
+* const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+*
+* registerToolFromSchema(server, {
+*   name: 'get-project',
+*   description: 'Get a project by ID',
+*   inputSchema: {
+*     type: 'object',
+*     properties: { id: { type: 'string', description: 'Project public ID' } },
+*     required: ['id'],
+*   },
+*   handler: async ({ id }) => ({
+*     content: [{ type: 'text', text: `Project: ${id}` }],
+*   }),
+* });
+* ```
+*/
+var registerToolFromSchema = (server, params) => {
+  const {
+    name,
+    description,
+    inputSchema = {
+      type: "object",
+      properties: {}
+    },
+    handler
+  } = params;
+  if (!rawSchemaRegistryMap.has(server)) rawSchemaRegistryMap.set(server, /* @__PURE__ */new Map());
+  rawSchemaRegistryMap.get(server).set(name, inputSchema);
+  server.registerTool(name, {
+    description,
+    inputSchema: z$1.record(z$1.string(), z$1.unknown())
+  }, async args => {
+    return handler(args);
+  });
+  if (!patchedServerSet.has(server)) {
+    patchedServerSet.add(server);
+    const rawServer = server.server;
+    const origHandler = rawServer?._requestHandlers?.get("tools/list");
+    if (!origHandler && process.env.NODE_ENV !== "production") console.warn("[registerToolFromSchema] Could not patch tools/list — internal MCP SDK structure may have changed. The tool will still be callable, but tools/list may return a Zod-derived schema instead of the verbatim JSON Schema.");
+    if (origHandler) rawServer._requestHandlers.set("tools/list", async (rawRequest, extra) => {
+      const result = await origHandler(rawRequest, extra);
+      const schemas = rawSchemaRegistryMap.get(server);
+      if (!schemas) return result;
+      return {
+        ...result,
+        tools: result.tools.map(tool => {
+          const raw = schemas.get(tool.name);
+          if (raw !== void 0) return {
+            ...tool,
+            inputSchema: raw
+          };
+          return tool;
+        })
+      };
+    });
+  }
+};
+
 //#endregion
 //#region src/createGatedToolRegistrar.ts
 var toolError = message => {
@@ -142,19 +229,39 @@ var createGatedToolRegistrar = ({
 //#region src/index.ts
 /** MCP lifecycle/discovery methods reachable before a client authenticates. */
 var DEFAULT_PUBLIC_METHODS = ["initialize", "tools/list"];
+/**
+* Asserts that a verified token's `aud` claim includes at least one of the
+* expected resource indicator values. `aud` may be a single string or an
+* array of strings per the JWT spec (RFC 7519); both forms are checked.
+*/
+var assertResourceIndicator = (payload, resourceIndicator) => {
+  const expected = Array.isArray(resourceIndicator) ? resourceIndicator : [resourceIndicator];
+  const aud = payload?.aud;
+  if (!(typeof aud === "string" ? [aud] : Array.isArray(aud) ? aud : []).some(audience => {
+    return typeof audience === "string" && expected.includes(audience);
+  })) throw new Error(`Token audience does not include the expected resource indicator (expected one of: ${expected.join(", ")}).`);
+};
 /** Builds the token verifier from the MCP auth options. */
 var buildVerifyToken = auth => {
-  if (auth.cognitoUserPool) {
-    const verifier = CognitoJwtVerifier.create({
-      tokenUse: "access",
-      ...auth.cognitoUserPool
-    });
-    return token => {
-      return verifier.verify(token);
-    };
-  }
-  if (auth.verifyToken) return auth.verifyToken;
-  throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
+  const verify = (() => {
+    if (auth.cognitoUserPool) {
+      const verifier = CognitoJwtVerifier.create({
+        tokenUse: "access",
+        ...auth.cognitoUserPool
+      });
+      return token => {
+        return verifier.verify(token);
+      };
+    }
+    if (auth.verifyToken) return auth.verifyToken;
+    throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
+  })();
+  if (!auth.resourceIndicator) return verify;
+  return async token => {
+    const payload = await verify(token);
+    assertResourceIndicator(payload, auth.resourceIndicator);
+    return payload;
+  };
 };
 /**
 * Generic HTTP helper for use inside MCP tool handlers.
@@ -437,90 +544,6 @@ var createMcpRouter = (server, options = {}) => {
   }
   return router;
 };
-var rawSchemaRegistryMap = /* @__PURE__ */new WeakMap();
-var patchedServerSet = /* @__PURE__ */new WeakSet();
-/**
-* Registers a tool on an MCP server using a **plain JSON Schema** object for
-* `inputSchema` instead of a Zod shape.
-*
-* This is useful when tool definitions are shared between the MCP server and an
-* AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
-* plain JSON Schema at runtime. Using this helper eliminates the lossy
-* JSON-Schema→Zod conversion that would otherwise be required.
-*
-* Internally the helper:
-* 1. Registers the tool via the standard `McpServer.registerTool` API using a
-*    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
-*    `tools/call` handler correctly routes requests and delivers raw args to
-*    your handler.
-* 2. Stores the original JSON Schema and patches the `tools/list` response
-*    handler so clients receive the verbatim JSON Schema over the wire.
-*
-* @param server - The `McpServer` instance to register the tool on.
-* @param params - Tool configuration including name, description, inputSchema,
-*   and handler.
-*
-* @example
-* ```typescript
-* import { registerToolFromSchema, McpServer } from '@ttoss/http-server-mcp';
-*
-* const server = new McpServer({ name: 'my-server', version: '1.0.0' });
-*
-* registerToolFromSchema(server, {
-*   name: 'get-project',
-*   description: 'Get a project by ID',
-*   inputSchema: {
-*     type: 'object',
-*     properties: { id: { type: 'string', description: 'Project public ID' } },
-*     required: ['id'],
-*   },
-*   handler: async ({ id }) => ({
-*     content: [{ type: 'text', text: `Project: ${id}` }],
-*   }),
-* });
-* ```
-*/
-var registerToolFromSchema = (server, params) => {
-  const {
-    name,
-    description,
-    inputSchema = {
-      type: "object",
-      properties: {}
-    },
-    handler
-  } = params;
-  if (!rawSchemaRegistryMap.has(server)) rawSchemaRegistryMap.set(server, /* @__PURE__ */new Map());
-  rawSchemaRegistryMap.get(server).set(name, inputSchema);
-  server.registerTool(name, {
-    description,
-    inputSchema: z$1.record(z$1.string(), z$1.unknown())
-  }, async args => {
-    return handler(args);
-  });
-  if (!patchedServerSet.has(server)) {
-    patchedServerSet.add(server);
-    const rawServer = server.server;
-    const origHandler = rawServer?._requestHandlers?.get("tools/list");
-    if (!origHandler && process.env.NODE_ENV !== "production") console.warn("[registerToolFromSchema] Could not patch tools/list — internal MCP SDK structure may have changed. The tool will still be callable, but tools/list may return a Zod-derived schema instead of the verbatim JSON Schema.");
-    if (origHandler) rawServer._requestHandlers.set("tools/list", async (rawRequest, extra) => {
-      const result = await origHandler(rawRequest, extra);
-      const schemas = rawSchemaRegistryMap.get(server);
-      if (!schemas) return result;
-      return {
-        ...result,
-        tools: result.tools.map(tool => {
-          const raw = schemas.get(tool.name);
-          if (raw !== void 0) return {
-            ...tool,
-            inputSchema: raw
-          };
-          return tool;
-        })
-      };
-    });
-  }
-};
 
 //#endregion
 export { McpServer, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -35,9 +35,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
-    "@ttoss/auth-core": "^0.10.0",
-    "@ttoss/http-server-auth": "^0.3.7",
-    "@ttoss/http-server": "^0.7.1"
+    "@ttoss/auth-core": "^0.12.0",
+    "@ttoss/http-server": "^0.7.1",
+    "@ttoss/http-server-auth": "^0.5.0"
   },
   "devDependencies": {
     "@types/koa": "^3.0.3",