@ttoss/http-server-mcp 0.20.0 → 0.21.1

package/README.md

@@ -374,10 +374,10 @@ Every registered tool automatically:
 
 1. Resolves the caller's identity (defaults to `getIdentity()` from the request context).
 2. Checks that the caller holds a required OAuth scope — returns an `isError` result (not a throw) when the scope is absent.
-3. Runs any extra `gates` in order; a throwing gate rejects the call.
+3. Runs global `gates` then per-tool `def.gates` in order; a throwing gate rejects the call. Both receive `ToolCallContext` (identity **and** the validated call args).
 4. Merges `buildContext` output into the handler args.
-5. Wraps `null`/`undefined` results in a "Not found" error result.
-6. Calls `onError` on throw before rethrowing, for telemetry.
+5. Wraps `null`/`undefined` results in a configurable "Not found" error result.
+6. Calls `onError` on handler throw before rethrowing, for telemetry. Gate/scope failures do **not** trigger `onError`.
 
 ```typescript
 import {
@@ -394,7 +394,7 @@ const { register } = createGatedToolRegistrar({
     const scopes = jwt?.scope?.split(' ') ?? [];
     return { userId: jwt!.sub, scopes };
   },
-  buildContext: ({ userId }) => ({ tenantId: lookupTenant(userId) }),
+  buildContext: ({ identity }) => ({ tenantId: lookupTenant(identity.userId) }),
   onError: (err, { handler, identity }) => {
     logger.error({ err, handler, userId: identity.userId });
   },
@@ -412,9 +412,27 @@ register({
 
 **`resolveIdentity`** is called once per invocation. Omit it to use the default `getIdentity()` from the MCP request context.
 
-**`gates`** are async functions that receive the resolved identity and throw to reject. Use them for additional checks that span multiple tools (rate limiting, IP allowlists, etc.).
+**`gates`** (global and per-tool) are async functions that receive a `ToolCallContext` — both the resolved identity and the validated call args — and throw to reject. The full context lets gates vary their predicate based on what the caller is asking for, not just who they are.
 
-**`buildContext`** injects request-scoped values (DB clients, tenant IDs) into every handler call without threading them through each individual tool.
+```typescript
+register({
+  name: 'activate-ad-account',
+  description: 'Activate or deactivate an ad account.',
+  requiredScope: 'accounts:write',
+  inputSchema: { accountId: z.number(), isActive: z.boolean() },
+  // arg-conditional gate: activating requires more checks than deactivating
+  gates: [
+    ({ args }) =>
+      args.isActive
+        ? checkSubscriptionGates(['mustNotExceedMaxActive', 'mustHaveBudget'])
+        : checkSubscriptionGates(['mustIncludeService']),
+  ],
+  method: async ({ userId, accountId, isActive }) =>
+    toggleAdAccount(userId, accountId, isActive),
+});
+```
+
+**`buildContext`** injects request-scoped values (DB clients, tenant IDs) into every handler call without threading them through each individual tool. It receives the full `ToolCallContext` so context can vary by identity or by call args.
 
 ## Issuing tokens for MCP clients
 
@@ -504,9 +522,11 @@ Factory that returns a `register` helper for tools that require authentication a
 
 - `server` (`McpServer`) — The MCP server to register tools on.
 - `resolveIdentity` (`() => ToolIdentity`, optional) — Called once per invocation to resolve `{ userId, scopes? }`. Defaults to `getIdentity()` from the request context.
-- `gates` (`Array<(identity: ToolIdentity) => void | Promise<void>>`, optional) — Additional guards run after the scope check, in order. Throw to reject the call.
-- `buildContext` (`(identity: ToolIdentity) => Record<string, unknown>`, optional) — Produces extra key-value pairs merged into every handler's args.
-- `onError` (`(error, ctx) => void | Promise<void>`, optional) — Called when a handler throws, before the error is rethrown. Use for logging/telemetry.
+- `gates` (`Array<(ctx: ToolCallContext) => void | Promise<void>>`, optional) — Global guards run after the scope check, in order, before any per-tool gates. Each receives `{ identity, args, handler }`. Throw to reject the call.
+- `enforceScope` (`boolean`, optional, default `true`) — When `true`, checks `def.requiredScope` against `identity.scopes` and returns an `isError` result on mismatch. Set to `false` when all authorization is handled by `gates`.
+- `buildContext` (`(ctx: ToolCallContext) => Record<string, unknown>`, optional) — Produces extra key-value pairs merged into every handler's args. Receives the full `ToolCallContext` so context can vary by identity or by call args.
+- `onError` (`(error, ctx: ToolCallContext) => void | Promise<void>`, optional) — Called when the handler throws, before the error is rethrown. Gate/scope failures do **not** trigger this hook.
+- `notFoundMessage` (`string`, optional, default `"Not found"`) — `isError` message returned when the handler resolves to `null`/`undefined`.
 
 **Returns:** `{ register: (def: GatedToolDef) => void }`
 
@@ -516,8 +536,15 @@ The `GatedToolDef` passed to `register` has:
 - `description` — Human-readable description.
 - `requiredScope` — Single scope that must appear in `identity.scopes`.
 - `inputSchema` — Zod field map or `ZodObject`, forwarded to `server.registerTool`.
+- `gates` (`Array<(ctx: ToolCallContext) => void | Promise<void>>`, optional) — Per-tool guards appended after the global `gates`. Receive the full `ToolCallContext` enabling arg-conditional authorization.
 - `method` — Async handler. Receives merged call args + `buildContext` output.
 
+**`ToolCallContext`** is the object passed to gates, `buildContext`, and `onError`:
+
+- `identity` (`ToolIdentity`) — The resolved caller identity (`{ userId, scopes? }`).
+- `args` (`Record<string, unknown>`) — The validated tool input (post SDK parse).
+- `handler` (`string`) — The tool name, for error attribution.
+
 ### `registerToolFromSchema(server, params)`
 
 Registers a tool using a **plain JSON Schema** object for `inputSchema` instead of a Zod shape.

package/dist/index.cjs

@@ -44,15 +44,17 @@ var toolError = message => {
 * Every registered tool automatically:
 * 1. Resolves the caller identity (default: `getIdentity()`). Returns an
 *    `isError` result when the identity is absent (unauthenticated request).
-* 2. Checks `requiredScope` — returns an `isError` result (not a throw) when
-*    the scope is absent, consistent with how MCP surfaces authorization errors.
-*    Scope semantics are intentionally simple (`Array.includes`). The package's
-*    `checkScopes` helper is not reused here because it throws rather than
-*    returning an `isError` result, and it reads identity from context itself.
-* 3. Runs any extra `gates` in order; a throwing gate rejects the call.
+* 2. When `enforceScope` is `true` (default), checks `requiredScope` — returns
+*    an `isError` result when the scope is absent, consistent with how MCP
+*    surfaces authorization errors. The package's `checkScopes` helper is not
+*    reused here because it throws rather than returning an `isError` result,
+*    and it reads identity from context itself.
+* 3. Runs global `gates` then per-`register` `def.gates` in order; a throwing
+*    gate rejects the call. Every gate receives the full {@link ToolCallContext}
+*    (identity **and** the validated call args), enabling arg-conditional gates.
 *    Gates own their own error handling; `onError` covers the tool handler only.
 * 4. Merges `buildContext` output into the handler args.
-* 5. Wraps `null`/`undefined` results in a "Not found" error result.
+* 5. Wraps `null`/`undefined` results in a configurable "Not found" error result.
 * 6. Calls `onError` on handler throw before rethrowing.
 *
 * @example
@@ -66,20 +68,36 @@ var toolError = message => {
 * });
 *
 * register({
-*   name: 'list-campaigns',
-*   description: 'List all ad campaigns for the caller.',
-*   requiredScope: 'campaigns:read',
-*   inputSchema: { limit: z.number().optional() },
-*   method: async ({ userId, limit }) => fetchCampaigns(userId, limit),
+*   name: 'activate-campaign',
+*   description: 'Activate or deactivate a campaign.',
+*   requiredScope: 'campaigns:write',
+*   inputSchema: { isActive: z.boolean() },
+*   // arg-conditional gate: active vs. inactive have different restrictions
+*   gates: [
+*     ({ args }) =>
+*       args.isActive
+*         ? subscriptionGate(['mustNotExceedMaxActive', 'mustHaveBudget'])
+*         : subscriptionGate(['mustIncludeService']),
+*   ],
+*   method: async ({ userId, isActive }) => toggleCampaign(userId, isActive),
 * });
 * ```
 */
+var checkScope = (identity, requiredScope) => {
+  if (!(Array.isArray(identity.scopes) ? identity.scopes : []).includes(requiredScope)) return toolError(`This tool requires the "${requiredScope}" scope.`);
+  return null;
+};
+var runGates = async (allGates, ctx) => {
+  for (const gate of allGates) await gate(ctx);
+};
 var createGatedToolRegistrar = ({
   server,
   resolveIdentity = getIdentity,
   gates = [],
+  enforceScope = true,
   onError,
-  buildContext
+  buildContext,
+  notFoundMessage = "Not found"
 }) => {
   const register = def => {
     server.registerTool(def.name, {
@@ -88,15 +106,23 @@ var createGatedToolRegistrar = ({
     }, async args => {
       const identity = resolveIdentity();
       if (!identity) return toolError("Unauthorized");
-      if (!(Array.isArray(identity.scopes) ? identity.scopes : []).includes(def.requiredScope)) return toolError(`This tool requires the "${def.requiredScope}" scope.`);
-      for (const gate of gates) await gate(identity);
-      const extra = buildContext ? buildContext(identity) : {};
+      const ctx = {
+        identity,
+        args,
+        handler: def.name
+      };
+      if (enforceScope) {
+        const scopeError = checkScope(identity, def.requiredScope);
+        if (scopeError) return scopeError;
+      }
+      await runGates([...gates, ...(def.gates ?? [])], ctx);
+      const extra = buildContext ? buildContext(ctx) : {};
       try {
         const result = await def.method({
           ...args,
           ...extra
         });
-        if (result == null) return toolError("Not found");
+        if (result == null) return toolError(notFoundMessage);
         return {
           content: [{
             type: "text",
@@ -104,10 +130,7 @@ var createGatedToolRegistrar = ({
           }]
         };
       } catch (error) {
-        if (onError) await onError(error, {
-          handler: def.name,
-          identity
-        });
+        if (onError) await onError(error, ctx);
         throw error;
       }
     });

package/dist/index.d.cts

@@ -682,12 +682,34 @@ type ToolIdentity = {
   userId: string;
   scopes?: string[];
 };
+/**
+ * Full context passed to gates, `buildContext`, and `onError` on every tool
+ * invocation. Having all three fields in one object means gate callbacks can
+ * be both identity-aware and args-aware without multiple parameters.
+ */
+type ToolCallContext = {
+  /** The resolved caller identity. */identity: ToolIdentity;
+  /**
+   * The validated tool input (post SDK parse). Present for gates and
+   * `buildContext`. Arg-conditional gates read this to vary their predicate
+   * per call.
+   */
+  args: Record<string, unknown>; /** Tool name, for error attribution and gate labelling. */
+  handler: string;
+};
 /** Definition for a single gated tool. */
 type GatedToolDef = {
   /** Tool name as registered with the MCP server. */name: string; /** Human-readable tool description. */
   description: string; /** The single scope that must be present on the caller's token. */
   requiredScope: string; /** Zod field map or ZodObject — passed through to `server.registerTool`. */
-  inputSchema: unknown; /** The tool handler. Receives merged call args + `buildContext` output. */
+  inputSchema: unknown;
+  /**
+   * Per-tool gates merged after the global `gates`. Useful for arg-conditional
+   * authorization (e.g. different subscription tiers based on call args).
+   * Each gate receives the full {@link ToolCallContext} (identity + args).
+   * Throw to reject the call; return (or resolve) to continue.
+   */
+  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>; /** The tool handler. Receives merged call args + `buildContext` output. */
   method: (args: Record<string, unknown>) => Promise<unknown>;
 };
 /** Options for {@link createGatedToolRegistrar}. */
@@ -699,70 +721,46 @@ type CreateGatedToolRegistrarOptions = {
    */
   resolveIdentity?: () => ToolIdentity;
   /**
-   * Additional authorization gates run after the scope check, in order.
+   * Global authorization gates run after the scope check, in order, before
+   * per-tool gates. Each receives the full {@link ToolCallContext} — both
+   * identity and the validated call args — so gate predicates may be
+   * conditional on either.
    * Throw to reject the call; return (or resolve) to continue.
    * Gates own their own error handling — `onError` covers the tool handler only.
    */
-  gates?: Array<(identity: ToolIdentity) => void | Promise<void>>;
+  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>;
+  /**
+   * When `true` (default), checks `def.requiredScope` against `identity.scopes`
+   * and returns an `isError` result when the scope is absent. Set to `false`
+   * to skip the scope check (e.g. when all scopes are enforced by `gates`).
+   */
+  enforceScope?: boolean;
   /**
    * Called when the tool **handler** throws. Use for error reporting/telemetry.
    * The error is always rethrown after this hook completes.
    * Note: scope-check failures and gate rejections do not trigger `onError`.
    */
-  onError?: (error: unknown, ctx: {
-    handler: string;
-    identity: ToolIdentity;
-  }) => void | Promise<void>;
+  onError?: (error: unknown, ctx: ToolCallContext) => void | Promise<void>;
   /**
    * Called once per invocation to produce extra key-value pairs that are
-   * merged into the handler args. Use to inject request-scoped context
-   * (e.g. a database client keyed to the caller's tenant).
+   * merged into the handler args. Receives the full {@link ToolCallContext}
+   * so context can vary by identity or by call args.
+   */
+  buildContext?: (ctx: ToolCallContext) => Record<string, unknown>;
+  /**
+   * Message returned as an `isError` result when the handler resolves to
+   * `null` or `undefined`. Defaults to `"Not found"`.
    */
-  buildContext?: (identity: ToolIdentity) => Record<string, unknown>;
+  notFoundMessage?: string;
 };
-/**
- * Factory that returns a `register` helper for MCP tools that require
- * authentication and a specific OAuth scope.
- *
- * Every registered tool automatically:
- * 1. Resolves the caller identity (default: `getIdentity()`). Returns an
- *    `isError` result when the identity is absent (unauthenticated request).
- * 2. Checks `requiredScope` — returns an `isError` result (not a throw) when
- *    the scope is absent, consistent with how MCP surfaces authorization errors.
- *    Scope semantics are intentionally simple (`Array.includes`). The package's
- *    `checkScopes` helper is not reused here because it throws rather than
- *    returning an `isError` result, and it reads identity from context itself.
- * 3. Runs any extra `gates` in order; a throwing gate rejects the call.
- *    Gates own their own error handling; `onError` covers the tool handler only.
- * 4. Merges `buildContext` output into the handler args.
- * 5. Wraps `null`/`undefined` results in a "Not found" error result.
- * 6. Calls `onError` on handler throw before rethrowing.
- *
- * @example
- * ```typescript
- * const { register } = createGatedToolRegistrar({
- *   server,
- *   resolveIdentity: () => {
- *     const jwt = getIdentity<{ sub: string; scopes: string[] }>();
- *     return { userId: jwt!.sub, scopes: jwt!.scopes };
- *   },
- * });
- *
- * register({
- *   name: 'list-campaigns',
- *   description: 'List all ad campaigns for the caller.',
- *   requiredScope: 'campaigns:read',
- *   inputSchema: { limit: z.number().optional() },
- *   method: async ({ userId, limit }) => fetchCampaigns(userId, limit),
- * });
- * ```
- */
 declare const createGatedToolRegistrar: ({
   server,
   resolveIdentity,
   gates,
+  enforceScope,
   onError,
-  buildContext
+  buildContext,
+  notFoundMessage
 }: CreateGatedToolRegistrarOptions) => {
   register: (def: GatedToolDef) => void;
 };
@@ -1118,4 +1116,4 @@ interface RegisterToolFromSchemaParams {
  */
 declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, type ToolCallContext, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/dist/index.d.mts

@@ -683,12 +683,34 @@ type ToolIdentity = {
   userId: string;
   scopes?: string[];
 };
+/**
+ * Full context passed to gates, `buildContext`, and `onError` on every tool
+ * invocation. Having all three fields in one object means gate callbacks can
+ * be both identity-aware and args-aware without multiple parameters.
+ */
+type ToolCallContext = {
+  /** The resolved caller identity. */identity: ToolIdentity;
+  /**
+   * The validated tool input (post SDK parse). Present for gates and
+   * `buildContext`. Arg-conditional gates read this to vary their predicate
+   * per call.
+   */
+  args: Record<string, unknown>; /** Tool name, for error attribution and gate labelling. */
+  handler: string;
+};
 /** Definition for a single gated tool. */
 type GatedToolDef = {
   /** Tool name as registered with the MCP server. */name: string; /** Human-readable tool description. */
   description: string; /** The single scope that must be present on the caller's token. */
   requiredScope: string; /** Zod field map or ZodObject — passed through to `server.registerTool`. */
-  inputSchema: unknown; /** The tool handler. Receives merged call args + `buildContext` output. */
+  inputSchema: unknown;
+  /**
+   * Per-tool gates merged after the global `gates`. Useful for arg-conditional
+   * authorization (e.g. different subscription tiers based on call args).
+   * Each gate receives the full {@link ToolCallContext} (identity + args).
+   * Throw to reject the call; return (or resolve) to continue.
+   */
+  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>; /** The tool handler. Receives merged call args + `buildContext` output. */
   method: (args: Record<string, unknown>) => Promise<unknown>;
 };
 /** Options for {@link createGatedToolRegistrar}. */
@@ -700,70 +722,46 @@ type CreateGatedToolRegistrarOptions = {
    */
   resolveIdentity?: () => ToolIdentity;
   /**
-   * Additional authorization gates run after the scope check, in order.
+   * Global authorization gates run after the scope check, in order, before
+   * per-tool gates. Each receives the full {@link ToolCallContext} — both
+   * identity and the validated call args — so gate predicates may be
+   * conditional on either.
    * Throw to reject the call; return (or resolve) to continue.
    * Gates own their own error handling — `onError` covers the tool handler only.
    */
-  gates?: Array<(identity: ToolIdentity) => void | Promise<void>>;
+  gates?: Array<(ctx: ToolCallContext) => void | Promise<void>>;
+  /**
+   * When `true` (default), checks `def.requiredScope` against `identity.scopes`
+   * and returns an `isError` result when the scope is absent. Set to `false`
+   * to skip the scope check (e.g. when all scopes are enforced by `gates`).
+   */
+  enforceScope?: boolean;
   /**
    * Called when the tool **handler** throws. Use for error reporting/telemetry.
    * The error is always rethrown after this hook completes.
    * Note: scope-check failures and gate rejections do not trigger `onError`.
    */
-  onError?: (error: unknown, ctx: {
-    handler: string;
-    identity: ToolIdentity;
-  }) => void | Promise<void>;
+  onError?: (error: unknown, ctx: ToolCallContext) => void | Promise<void>;
   /**
    * Called once per invocation to produce extra key-value pairs that are
-   * merged into the handler args. Use to inject request-scoped context
-   * (e.g. a database client keyed to the caller's tenant).
+   * merged into the handler args. Receives the full {@link ToolCallContext}
+   * so context can vary by identity or by call args.
+   */
+  buildContext?: (ctx: ToolCallContext) => Record<string, unknown>;
+  /**
+   * Message returned as an `isError` result when the handler resolves to
+   * `null` or `undefined`. Defaults to `"Not found"`.
    */
-  buildContext?: (identity: ToolIdentity) => Record<string, unknown>;
+  notFoundMessage?: string;
 };
-/**
- * Factory that returns a `register` helper for MCP tools that require
- * authentication and a specific OAuth scope.
- *
- * Every registered tool automatically:
- * 1. Resolves the caller identity (default: `getIdentity()`). Returns an
- *    `isError` result when the identity is absent (unauthenticated request).
- * 2. Checks `requiredScope` — returns an `isError` result (not a throw) when
- *    the scope is absent, consistent with how MCP surfaces authorization errors.
- *    Scope semantics are intentionally simple (`Array.includes`). The package's
- *    `checkScopes` helper is not reused here because it throws rather than
- *    returning an `isError` result, and it reads identity from context itself.
- * 3. Runs any extra `gates` in order; a throwing gate rejects the call.
- *    Gates own their own error handling; `onError` covers the tool handler only.
- * 4. Merges `buildContext` output into the handler args.
- * 5. Wraps `null`/`undefined` results in a "Not found" error result.
- * 6. Calls `onError` on handler throw before rethrowing.
- *
- * @example
- * ```typescript
- * const { register } = createGatedToolRegistrar({
- *   server,
- *   resolveIdentity: () => {
- *     const jwt = getIdentity<{ sub: string; scopes: string[] }>();
- *     return { userId: jwt!.sub, scopes: jwt!.scopes };
- *   },
- * });
- *
- * register({
- *   name: 'list-campaigns',
- *   description: 'List all ad campaigns for the caller.',
- *   requiredScope: 'campaigns:read',
- *   inputSchema: { limit: z.number().optional() },
- *   method: async ({ userId, limit }) => fetchCampaigns(userId, limit),
- * });
- * ```
- */
 declare const createGatedToolRegistrar: ({
   server,
   resolveIdentity,
   gates,
+  enforceScope,
   onError,
-  buildContext
+  buildContext,
+  notFoundMessage
 }: CreateGatedToolRegistrarOptions) => {
   register: (def: GatedToolDef) => void;
 };
@@ -1119,4 +1117,4 @@ interface RegisterToolFromSchemaParams {
  */
 declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, type ToolCallContext, type ToolIdentity, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/dist/index.mjs

@@ -41,15 +41,17 @@ var toolError = message => {
 * Every registered tool automatically:
 * 1. Resolves the caller identity (default: `getIdentity()`). Returns an
 *    `isError` result when the identity is absent (unauthenticated request).
-* 2. Checks `requiredScope` — returns an `isError` result (not a throw) when
-*    the scope is absent, consistent with how MCP surfaces authorization errors.
-*    Scope semantics are intentionally simple (`Array.includes`). The package's
-*    `checkScopes` helper is not reused here because it throws rather than
-*    returning an `isError` result, and it reads identity from context itself.
-* 3. Runs any extra `gates` in order; a throwing gate rejects the call.
+* 2. When `enforceScope` is `true` (default), checks `requiredScope` — returns
+*    an `isError` result when the scope is absent, consistent with how MCP
+*    surfaces authorization errors. The package's `checkScopes` helper is not
+*    reused here because it throws rather than returning an `isError` result,
+*    and it reads identity from context itself.
+* 3. Runs global `gates` then per-`register` `def.gates` in order; a throwing
+*    gate rejects the call. Every gate receives the full {@link ToolCallContext}
+*    (identity **and** the validated call args), enabling arg-conditional gates.
 *    Gates own their own error handling; `onError` covers the tool handler only.
 * 4. Merges `buildContext` output into the handler args.
-* 5. Wraps `null`/`undefined` results in a "Not found" error result.
+* 5. Wraps `null`/`undefined` results in a configurable "Not found" error result.
 * 6. Calls `onError` on handler throw before rethrowing.
 *
 * @example
@@ -63,20 +65,36 @@ var toolError = message => {
 * });
 *
 * register({
-*   name: 'list-campaigns',
-*   description: 'List all ad campaigns for the caller.',
-*   requiredScope: 'campaigns:read',
-*   inputSchema: { limit: z.number().optional() },
-*   method: async ({ userId, limit }) => fetchCampaigns(userId, limit),
+*   name: 'activate-campaign',
+*   description: 'Activate or deactivate a campaign.',
+*   requiredScope: 'campaigns:write',
+*   inputSchema: { isActive: z.boolean() },
+*   // arg-conditional gate: active vs. inactive have different restrictions
+*   gates: [
+*     ({ args }) =>
+*       args.isActive
+*         ? subscriptionGate(['mustNotExceedMaxActive', 'mustHaveBudget'])
+*         : subscriptionGate(['mustIncludeService']),
+*   ],
+*   method: async ({ userId, isActive }) => toggleCampaign(userId, isActive),
 * });
 * ```
 */
+var checkScope = (identity, requiredScope) => {
+  if (!(Array.isArray(identity.scopes) ? identity.scopes : []).includes(requiredScope)) return toolError(`This tool requires the "${requiredScope}" scope.`);
+  return null;
+};
+var runGates = async (allGates, ctx) => {
+  for (const gate of allGates) await gate(ctx);
+};
 var createGatedToolRegistrar = ({
   server,
   resolveIdentity = getIdentity,
   gates = [],
+  enforceScope = true,
   onError,
-  buildContext
+  buildContext,
+  notFoundMessage = "Not found"
 }) => {
   const register = def => {
     server.registerTool(def.name, {
@@ -85,15 +103,23 @@ var createGatedToolRegistrar = ({
     }, async args => {
       const identity = resolveIdentity();
       if (!identity) return toolError("Unauthorized");
-      if (!(Array.isArray(identity.scopes) ? identity.scopes : []).includes(def.requiredScope)) return toolError(`This tool requires the "${def.requiredScope}" scope.`);
-      for (const gate of gates) await gate(identity);
-      const extra = buildContext ? buildContext(identity) : {};
+      const ctx = {
+        identity,
+        args,
+        handler: def.name
+      };
+      if (enforceScope) {
+        const scopeError = checkScope(identity, def.requiredScope);
+        if (scopeError) return scopeError;
+      }
+      await runGates([...gates, ...(def.gates ?? [])], ctx);
+      const extra = buildContext ? buildContext(ctx) : {};
       try {
         const result = await def.method({
           ...args,
           ...extra
         });
-        if (result == null) return toolError("Not found");
+        if (result == null) return toolError(notFoundMessage);
         return {
           content: [{
             type: "text",
@@ -101,10 +127,7 @@ var createGatedToolRegistrar = ({
           }]
         };
       } catch (error) {
-        if (onError) await onError(error, {
-          handler: def.name,
-          identity
-        });
+        if (onError) await onError(error, ctx);
         throw error;
       }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "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.10.0",
     "@ttoss/http-server": "^0.7.1",
+    "@ttoss/auth-core": "^0.10.0",
     "@ttoss/http-server-auth": "^0.3.7"
   },
   "devDependencies": {