@rekog/mcp-nest 1.9.10 → 2.0.0-alpha.1

package/src/mcp/decorators/public.decorator.ts

@@ -9,10 +9,10 @@ export const MCP_PUBLIC_METADATA_KEY = 'mcp:public-tool';
  * Decorator to mark a tool as publicly accessible, bypassing authentication requirements.
  *
  * Use this when you want a tool to be available even to unauthenticated users
- * when `allowUnauthenticatedAccess` is enabled in McpModule options.
+ * when `allowUnauthenticatedAccess` is enabled on the {@link McpStrategy}.
  *
- * When applied to a tool method, it allows the tool to be called without authentication,
- * even if the module has guards configured.
+ * When applied to a tool method, it allows the tool to be listed and called
+ * without authentication, even when other tools on the server require it.
  *
  * @example
  * ```typescript

package/src/mcp/decorators/raw-request.decorator.ts

@@ -0,0 +1,32 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+import type { McpContext } from '../transport/mcp-context';
+
+/**
+ * Injects the raw transport request into an MCP capability handler — the MCP
+ * analog of NestJS's `@Req()`.
+ *
+ * Returns the underlying HTTP request object (Express `Request` / Fastify
+ * `FastifyRequest`) for HTTP-based transports, or `undefined` for STDIO, which
+ * is stream-oriented and has no per-call request object. Annotate the parameter
+ * with your framework's request type — the decorator itself does not type it,
+ * exactly like `@Req()`:
+ *
+ * @example
+ * ```typescript
+ * import type { Request } from 'express';
+ *
+ * @Tool({ name: 'whoami', description: 'Echo the caller' })
+ * whoami(@McpRawRequest() req?: Request) {
+ *   return { content: [{ type: 'text', text: req?.ip ?? 'stdio' }] };
+ * }
+ * ```
+ *
+ * This is sugar for `ctx.getRawRequest()` on the `@Ctx()` context; reach for it
+ * when the request is all you need from the context. Note that, like every
+ * NestJS param decorator, using this means the data parameter must also be
+ * annotated (with `@Payload()`).
+ */
+export const McpRawRequest = createParamDecorator(
+  (_data: unknown, ctx: ExecutionContext) =>
+    ctx.switchToRpc().getContext<McpContext>()?.getRawRequest(),
+);

package/src/mcp/decorators/resource-template.decorator.ts

@@ -1,5 +1,6 @@
-import { SetMetadata } from '@nestjs/common';
+import { applyDecorators, SetMetadata } from '@nestjs/common';
 import { MCP_RESOURCE_TEMPLATE_METADATA_KEY } from './constants';
+import { mcpMessagePattern } from './mcp-message-pattern';
 
 export type ResourceTemplateOptions =
   // https://modelcontextprotocol.io/docs/concepts/resources#resource-templates
@@ -27,5 +28,8 @@ export interface ResourceTemplateMetadata {
  * @returns {MethodDecorator} - The decorator
  */
 export const ResourceTemplate = (options: ResourceTemplateOptions) => {
-  return SetMetadata(MCP_RESOURCE_TEMPLATE_METADATA_KEY, options);
+  return applyDecorators(
+    SetMetadata(MCP_RESOURCE_TEMPLATE_METADATA_KEY, options),
+    mcpMessagePattern('resource-template', options.uriTemplate),
+  );
 };

package/src/mcp/decorators/resource.decorator.ts

@@ -1,5 +1,6 @@
-import { SetMetadata } from '@nestjs/common';
+import { applyDecorators, SetMetadata } from '@nestjs/common';
 import { MCP_RESOURCE_METADATA_KEY } from './constants';
+import { mcpMessagePattern } from './mcp-message-pattern';
 
 export type ResourceOptions =
   // https://modelcontextprotocol.io/docs/concepts/resources#direct-resources
@@ -27,5 +28,8 @@ export interface ResourceMetadata {
  * @returns {MethodDecorator} - The decorator
  */
 export const Resource = (options: ResourceOptions) => {
-  return SetMetadata(MCP_RESOURCE_METADATA_KEY, options);
+  return applyDecorators(
+    SetMetadata(MCP_RESOURCE_METADATA_KEY, options),
+    mcpMessagePattern('resource', options.uri),
+  );
 };

package/src/mcp/decorators/tool.decorator.ts

@@ -1,7 +1,8 @@
-import { CanActivate, SetMetadata, Type } from '@nestjs/common';
+import { applyDecorators, SetMetadata } from '@nestjs/common';
 import { z } from 'zod';
 import { ToolAnnotations as SdkToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { MCP_TOOL_METADATA_KEY } from './constants';
+import { mcpMessagePattern } from './mcp-message-pattern';
 
 /**
  * Security scheme type for MCP tools
@@ -22,7 +23,6 @@ export interface ToolMetadata {
   isPublic?: boolean;
   requiredScopes?: string[];
   requiredRoles?: string[];
-  guards?: Type<CanActivate>[];
 }
 
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
@@ -51,5 +51,8 @@ export const Tool = (options: ToolOptions) => {
     options.parameters = z.object({});
   }
 
-  return SetMetadata(MCP_TOOL_METADATA_KEY, options);
+  return applyDecorators(
+    SetMetadata(MCP_TOOL_METADATA_KEY, options),
+    mcpMessagePattern('tool', options.name),
+  );
 };

package/src/mcp/filters/mcp-exception.filter.ts

@@ -0,0 +1,47 @@
+import { ArgumentsHost, Catch, RpcExceptionFilter } from '@nestjs/common';
+import { RpcException } from '@nestjs/microservices';
+import { Observable, throwError } from 'rxjs';
+
+/**
+ * Surfaces the real error message of any exception thrown by an MCP
+ * tool/resource/prompt handler, instead of NestJS's default "Internal server
+ * error" masking.
+ *
+ * By default NestJS's RPC pipeline masks any non-`RpcException` to a generic
+ * "Internal server error" before the strategy can read it, so a plain
+ * `throw new Error('Order #42 not found')` reaches the agent as an opaque
+ * failure. That is a safe default (it avoids leaking internals), but it is poor
+ * DX when the message is meant for the caller. Register this filter to opt into
+ * passing the original message through:
+ *
+ * ```typescript
+ * // Globally (recommended) — applies to every MCP handler, but never overrides
+ * // a more specific `@UseFilters()` you put on a controller/method.
+ * providers: [{ provide: APP_FILTER, useClass: McpExceptionFilter }]
+ * ```
+ *
+ * ```typescript
+ * // Or per controller/method:
+ * @UseFilters(McpExceptionFilter)
+ * @McpController()
+ * class MyTools { ... }
+ * ```
+ *
+ * The surfaced message becomes an `isError: true` tool result (or a JSON-RPC
+ * error for resources/prompts), so the agent can tell a real failure from a
+ * successful call. For input problems, prefer the built-in Zod validation
+ * (a clear "Invalid parameters: …" result) or `throw new RpcException(...)` /
+ * a NestJS exception — those are already surfaced without this filter.
+ */
+@Catch()
+export class McpExceptionFilter implements RpcExceptionFilter {
+  catch(exception: unknown, _host: ArgumentsHost): Observable<never> {
+    // RpcException already carries an explicit, client-facing payload.
+    if (exception instanceof RpcException) {
+      return throwError(() => exception.getError());
+    }
+    const message =
+      exception instanceof Error ? exception.message : 'Internal server error';
+    return throwError(() => ({ status: 'error', message }));
+  }
+}

package/src/mcp/index.ts

@@ -1,9 +1,15 @@
 export * from './decorators';
 export * from './interfaces';
-export * from './mcp.module';
-export * from './services/mcp-registry-discovery.service';
-export * from './services/mcp-executor.service';
-export * from './services/mcp-sse.service';
-export * from './services/mcp-streamable-http.service';
-export * from './services/mcp-dynamic-registry.service';
-export * from './constants/feature-registration.constants';
+export * from './services/tool-authorization.service';
+export * from './filters/mcp-exception.filter';
+export * from './utils/normalize-endpoint';
+
+// Microservice transport strategy API
+export * from './transport/mcp-transport.constants';
+export * from './transport/mcp-context';
+export * from './transport/mcp-server-options.interface';
+export * from './transport/mcp-transport.interface';
+export * from './transport/mcp-http-handler';
+export * from './transport/mcp.strategy';
+export * from './transport/streamable-http.controller';
+export * from './transport/transports';

package/src/mcp/interfaces/authenticated-user.interface.ts

@@ -0,0 +1,22 @@
+/**
+ * Minimal shape of an authenticated principal as far as the core per-tool
+ * authorization logic is concerned.
+ *
+ * The core module never authenticates anyone itself — a guard or transport-level
+ * auth middleware resolves the user and places it on `req.user`. Per-tool checks
+ * (`@ToolScopes()`, `@ToolRoles()`) only read scopes and roles off that object, so
+ * core depends on this structural type rather than on any concrete token payload.
+ *
+ * The auth package's richer `JwtPayload` is structurally compatible with this
+ * interface, so no coupling back to `@rekog/mcp-nest-auth` is required.
+ */
+export interface AuthenticatedUser {
+  /** OAuth 2.0 space-delimited scope string. */
+  scope?: string;
+  /** Roles carried directly on the principal. */
+  roles?: string[];
+  /** Provider-specific user data; may carry roles. */
+  user_data?: { roles?: string[] } & Record<string, any>;
+  /** Allow additional, provider-specific claims without widening the read surface. */
+  [key: string]: any;
+}

package/src/mcp/interfaces/dynamic-prompt.interface.ts

@@ -6,7 +6,7 @@ export type DynamicPromptHandler = (
   args: Record<string, string> | undefined,
   context: Context,
   request: any,
-) => Promise<any> | any;
+) => any;
 
 export interface DynamicPromptDefinition {
   /** Unique name for the prompt */

package/src/mcp/interfaces/dynamic-resource.interface.ts

@@ -4,7 +4,7 @@ export type DynamicResourceHandler = (
   params: Record<string, unknown>,
   context: Context,
   request: any,
-) => Promise<any> | any;
+) => any;
 
 export interface DynamicResourceDefinition {
   /** URI that uniquely identifies this resource */

package/src/mcp/interfaces/dynamic-tool.interface.ts

@@ -10,11 +10,11 @@ export type DynamicToolHandler = (
   args: Record<string, unknown>,
   context: Context,
   request: any,
-) => Promise<any> | any;
+) => any;
 
 /**
  * Definition for a dynamically registered tool.
- * Use this with McpRegistryService.registerTool() to register tools at runtime.
+ * Use this with `McpStrategy.registerTool()` to register tools at runtime.
  *
  * @example
  * ```typescript

package/src/mcp/interfaces/index.ts

@@ -1,10 +1,4 @@
-export { McpTransportType } from './mcp-options.interface';
-export type {
-  McpOptions,
-  McpAsyncOptions,
-  McpOptionsFactory,
-  McpModuleAsyncOptions,
-} from './mcp-options.interface';
+export type { Icon } from '@modelcontextprotocol/sdk/types.js';
 
 export type {
   Literal,
@@ -16,6 +10,8 @@ export type {
 
 export type { HttpRequest } from './http-adapter.interface';
 
+export type { AuthenticatedUser } from './authenticated-user.interface';
+
 export type {
   DynamicToolDefinition,
   DynamicToolHandler,

package/src/mcp/services/tool-authorization.service.ts

@@ -1,24 +1,42 @@
 import { Injectable } from '@nestjs/common';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
-import { DiscoveredCapability } from './mcp-registry-discovery.service';
 import { ToolMetadata, SecurityScheme } from '../decorators/tool.decorator';
-import { JwtPayload } from '../../authz/services/jwt-token.service';
+import { AuthenticatedUser } from '../interfaces/authenticated-user.interface';
+
+/** Minimal shape the authorization logic needs: a capability carrying tool metadata. */
+export interface AuthorizableTool {
+  metadata: ToolMetadata;
+}
 
 /**
- * Service responsible for tool-level authorization logic
+ * Per-tool authorization.
+ *
+ * This service powers `tools/list` filtering and the `tools/call` access check
+ * based purely on the per-tool decorators (`@PublicTool()`, `@ToolScopes()`,
+ * `@ToolRoles()`) and the user resolved off the raw request (`req.user`, set by
+ * a guard or by transport-level auth middleware).
+ *
+ * It is intentionally NOT an authentication mechanism: real enforcement is the
+ * job of standard NestJS `@UseGuards()` (which run inside the RPC pipeline at
+ * call time) and/or auth middleware on the HTTP routes. This service only
+ * decides which tools a *known* principal may see and invoke.
  */
 @Injectable()
 export class ToolAuthorizationService {
   /**
-   * Generate security schemes for a tool based on its metadata and module configuration
+   * Generate security schemes for a tool, advertised to clients (e.g. ChatGPT)
+   * via the OpenAI `securitySchemes` spec so they know which tools need auth.
    *
    * @param tool - The discovered tool
-   * @param moduleHasGuards - Whether the module has guards configured
+   * @param freemiumMode - Whether the server runs in freemium mode
+   *   (`allowUnauthenticatedAccess`). In freemium mode an undecorated,
+   *   non-public tool still requires authentication, so it is advertised as
+   *   `oauth2`.
    * @returns Array of security schemes for the tool
    */
   generateSecuritySchemes(
-    tool: DiscoveredCapability<ToolMetadata>,
-    moduleHasGuards: boolean,
+    tool: AuthorizableTool,
+    freemiumMode: boolean,
   ): SecurityScheme[] {
     const metadata = tool.metadata;
     const schemes: SecurityScheme[] = [];
@@ -32,8 +50,12 @@ export class ToolAuthorizationService {
     if (metadata.requiredScopes && metadata.requiredScopes.length > 0) {
       schemes.push({ type: 'oauth2', scopes: metadata.requiredScopes });
     }
-    // Else if module has guards and tool is not public, require oauth2
-    else if (moduleHasGuards && !metadata.isPublic) {
+    // Else if tool requires specific roles, advertise that auth is needed
+    else if (metadata.requiredRoles && metadata.requiredRoles.length > 0) {
+      schemes.push({ type: 'oauth2' });
+    }
+    // Else, in freemium mode a non-public tool still requires authentication
+    else if (freemiumMode && !metadata.isPublic) {
       schemes.push({ type: 'oauth2' });
     }
 
@@ -46,18 +68,16 @@ export class ToolAuthorizationService {
   }
 
   /**
-   * Check if a user can access a tool based on security requirements
+   * Check if a user can access a tool based on its per-tool requirements.
    *
    * @param user - The authenticated user (may be undefined)
    * @param tool - The discovered tool
-   * @param moduleHasGuards - Whether the module has guards configured
    * @param allowUnauthenticatedAccess - Whether unauthenticated access is allowed (freemium mode)
-   * @returns true if user can access the tool, false otherwise
+   * @returns true if the user can access the tool, false otherwise
    */
   canAccessTool(
-    user: JwtPayload | undefined,
-    tool: DiscoveredCapability<ToolMetadata>,
-    moduleHasGuards: boolean,
+    user: AuthenticatedUser | undefined,
+    tool: AuthorizableTool,
     allowUnauthenticatedAccess: boolean = false,
   ): boolean {
     const metadata = tool.metadata;
@@ -90,50 +110,33 @@ export class ToolAuthorizationService {
       }
     }
 
-    // At this point:
-    // - Tool is not public
-    // - Tool has no specific scope/role requirements (or they passed)
-    //
-    // Decision logic based on allowUnauthenticatedAccess:
-    //
-    // allowUnauthenticatedAccess = false (default, standard auth mode):
-    // - Guards are expected to fully authorize requests (via JWT, API keys, etc)
-    // - If guard let request through AND there's no user object:
-    //   * Guard used non-JWT auth mechanism (API key, IP whitelist, etc)
-    //   * Trust the guard's decision to authorize
-    // - If no guards configured, allow access (no auth required)
+    // At this point the tool is not public and has no (or satisfied) scope/role
+    // requirements. The only remaining question is the undecorated tool:
     //
-    // allowUnauthenticatedAccess = true (freemium mode):
-    // - Guards may let unauthenticated requests through for per-tool auth
-    // - Only @PublicTool or tools with specific scopes/roles accessible
-    // - Tools without decorators require authentication (user must be present)
-    //
-    if (allowUnauthenticatedAccess && moduleHasGuards && !user) {
-      // Freemium mode: unauthenticated access only for @PublicTool or specific scopes
-      // This tool has no decorators, so it requires authentication
+    // - Freemium mode (allowUnauthenticatedAccess = true): anonymous callers may
+    //   only reach @PublicTool() (or specifically-scoped) tools, so an
+    //   undecorated tool requires a user.
+    // - Standard mode (default): real enforcement is delegated to @UseGuards /
+    //   auth middleware, so we trust that decision and allow access. (On stdio
+    //   there is no request and no user — all undecorated tools are reachable.)
+    if (allowUnauthenticatedAccess && !user) {
       return false;
     }
 
-    // Standard mode: If we're here, either:
-    // - No guards (open access)
-    // - Guards authorized it (trust guard decision, even without user object)
-    // - User is present and passed all checks
     return true;
   }
 
   /**
-   * Validate that a user can access a tool, throwing an error if not authorized
+   * Validate that a user can access a tool, throwing an error if not authorized.
    *
    * @param user - The authenticated user (may be undefined)
    * @param tool - The discovered tool
-   * @param moduleHasGuards - Whether the module has guards configured
    * @param allowUnauthenticatedAccess - Whether unauthenticated access is allowed (freemium mode)
    * @throws McpError if user is not authorized to access the tool
    */
   validateToolAccess(
-    user: JwtPayload | undefined,
-    tool: DiscoveredCapability<ToolMetadata>,
-    moduleHasGuards: boolean,
+    user: AuthenticatedUser | undefined,
+    tool: AuthorizableTool,
     allowUnauthenticatedAccess: boolean = false,
   ): void {
     const metadata = tool.metadata;
@@ -176,37 +179,14 @@ export class ToolAuthorizationService {
       }
     }
 
-    // At this point:
-    // - Tool is not public
-    // - Tool has no specific scope/role requirements (or they passed)
-    //
-    // Decision logic based on allowUnauthenticatedAccess:
-    //
-    // allowUnauthenticatedAccess = false (default, standard auth mode):
-    // - Guards are expected to fully authorize requests (via JWT, API keys, etc)
-    // - If guard let request through AND there's no user object:
-    //   * Guard used non-JWT auth mechanism (API key, IP whitelist, etc)
-    //   * Trust the guard's decision to authorize
-    // - If no guards configured, allow access (no auth required)
-    //
-    // allowUnauthenticatedAccess = true (freemium mode):
-    // - Guards may let unauthenticated requests through for per-tool auth
-    // - Only @PublicTool or tools with specific scopes/roles accessible
-    // - Tools without decorators require authentication (user must be present)
-    //
-    if (allowUnauthenticatedAccess && moduleHasGuards && !user) {
-      // Freemium mode: unauthenticated access only for @PublicTool or specific scopes
-      // This tool has no decorators, so it requires authentication
+    // Freemium mode: an undecorated, non-public tool still requires a user.
+    // Standard mode trusts @UseGuards / auth middleware (see canAccessTool).
+    if (allowUnauthenticatedAccess && !user) {
       throw new McpError(
         ErrorCode.InvalidRequest,
         `Tool '${toolName}' requires authentication`,
       );
     }
-
-    // Standard mode: If we're here, either:
-    // - No guards (open access)
-    // - Guards authorized it (trust guard decision, even without user object)
-    // - User is present and passed all checks
   }
 
   /**
@@ -217,7 +197,7 @@ export class ToolAuthorizationService {
    * @returns true if user has all required scopes
    */
   private hasRequiredScopes(
-    user: JwtPayload | undefined,
+    user: AuthenticatedUser | undefined,
     requiredScopes: string[],
   ): boolean {
     if (!user) {
@@ -247,7 +227,7 @@ export class ToolAuthorizationService {
    * @returns true if user has all required roles
    */
   private hasRequiredRoles(
-    user: JwtPayload | undefined,
+    user: AuthenticatedUser | undefined,
     requiredRoles: string[],
   ): boolean {
     if (!user) {

package/src/mcp/transport/mcp-context.ts

@@ -0,0 +1,138 @@
+import { Logger } from '@nestjs/common';
+import { BaseRpcContext } from '@nestjs/microservices';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Progress } from '@modelcontextprotocol/sdk/types.js';
+import { Context, McpRequest, SerializableValue } from '../interfaces';
+
+export type McpTransportKind = 'stdio' | 'streamable-http';
+
+export interface McpSessionInfo {
+  /** The MCP session id, when the transport is session-aware. */
+  sessionId?: string;
+  /** Which transport delivered this request. */
+  transport: McpTransportKind;
+  /**
+   * `true` only for the per-request streamable-HTTP stateless mode, where the
+   * server cannot push notifications/progress back to the client. stdio and
+   * stateful streamable-HTTP are both session-aware (`false`).
+   */
+  stateless: boolean;
+}
+
+type McpContextArgs = [
+  mcpServer: McpServer,
+  mcpRequest: McpRequest,
+  session: McpSessionInfo,
+  rawRequest: unknown,
+];
+
+/**
+ * Execution context handed to every MCP capability handler via `@Ctx()`.
+ *
+ * Extends NestJS's {@link BaseRpcContext} so it is resolved as the RPC context
+ * argument (the strategy invokes handlers as `handler(payload, mcpContext)`),
+ * and implements the library's {@link Context} surface (`reportProgress`, `log`,
+ * `mcpServer`, `mcpRequest`) so existing handler code keeps working.
+ *
+ * Additional accessors expose the session and the raw transport request.
+ */
+export class McpContext
+  extends BaseRpcContext<McpContextArgs>
+  implements Context
+{
+  public readonly reportProgress: (progress: Progress) => Promise<void>;
+  public readonly log: Context['log'];
+
+  constructor(
+    args: McpContextArgs,
+    private readonly logger?: Logger,
+  ) {
+    super(args);
+    this.reportProgress = this.getSession().stateless
+      ? this.createStatelessReportProgress()
+      : this.createReportProgress();
+    this.log = this.getSession().stateless
+      ? this.createStatelessLog()
+      : this.createLog();
+  }
+
+  /** The underlying MCP SDK server instance. */
+  get mcpServer(): McpServer {
+    return this.args[0];
+  }
+
+  /** The parsed JSON-RPC request (tools/call, resources/read, prompts/get, ...). */
+  get mcpRequest(): McpRequest {
+    return this.args[1];
+  }
+
+  /** Session metadata for this request. */
+  getSession(): McpSessionInfo {
+    return this.args[2];
+  }
+
+  /** The raw transport request (Express/Fastify request for HTTP; `undefined` for stdio). */
+  getRawRequest<T = unknown>(): T | undefined {
+    return this.args[3] as T | undefined;
+  }
+
+  private get progressToken(): string | number | undefined {
+    return this.mcpRequest.params?._meta?.progressToken;
+  }
+
+  private createReportProgress(): (progress: Progress) => Promise<void> {
+    return async (progress: Progress) => {
+      const progressToken = this.progressToken;
+      if (progressToken === undefined) {
+        return;
+      }
+      await this.mcpServer.server.notification({
+        method: 'notifications/progress',
+        params: { ...progress, progressToken } as Progress,
+      });
+    };
+  }
+
+  private createLog(): Context['log'] {
+    const send = (
+      level: 'debug' | 'info' | 'warning' | 'error',
+      message: string,
+      context?: SerializableValue,
+    ) => {
+      void this.mcpServer.server.sendLoggingMessage({
+        level,
+        data: { message, context },
+      });
+    };
+    return {
+      debug: (message, context) => send('debug', message, context),
+      info: (message, context) => send('info', message, context),
+      warn: (message, context) => send('warning', message, context),
+      error: (message, context) => send('error', message, context),
+    };
+  }
+
+  private createStatelessReportProgress(): (
+    progress: Progress,
+  ) => Promise<void> {
+    return () => {
+      this.logger?.warn(
+        "Stateless context: 'reportProgress' is not supported.",
+      );
+      return Promise.resolve();
+    };
+  }
+
+  private createStatelessLog(): Context['log'] {
+    const warn = () =>
+      this.logger?.warn(
+        'Stateless context: server-side logging is not supported.',
+      );
+    return {
+      debug: () => warn(),
+      info: () => warn(),
+      warn: () => warn(),
+      error: () => warn(),
+    };
+  }
+}

package/src/mcp/transport/mcp-http-handler.ts

@@ -0,0 +1,32 @@
+/**
+ * The HTTP verb handlers a streamable-HTTP MCP endpoint needs: one per method
+ * the transport mounts (`POST` messages, `GET` SSE stream, `DELETE` session
+ * teardown). This is the seam for "bring your own controller" setups.
+ *
+ * The transport owns the implementation (session handling, streaming, raw-body
+ * reading); you only decide HOW the route is mounted:
+ *
+ * - Do nothing — the transport self-mounts the route (no guards possible).
+ * - Extend {@link StreamableHttpController} (or write your own `@Controller`)
+ *   and delegate to these handlers, so the route is a real Nest route that
+ *   `@UseGuards()` / `@UseInterceptors()` / `@Version()` apply to.
+ *
+ * Obtain an instance from a transport via `transport.httpHandlers` and provide
+ * it under {@link MCP_HTTP_HANDLER} so the controller can inject it.
+ */
+export interface McpHttpHandler {
+  handlePost(req: unknown, res: unknown): Promise<void> | void;
+  handleGet(req: unknown, res: unknown): Promise<void> | void;
+  handleDelete(req: unknown, res: unknown): Promise<void> | void;
+}
+
+/**
+ * DI token for an {@link McpHttpHandler}. Provide a transport's `httpHandlers`
+ * under this token so {@link StreamableHttpController} (or your own controller)
+ * can inject it:
+ *
+ * ```ts
+ * { provide: MCP_HTTP_HANDLER, useValue: mcpTransport.httpHandlers }
+ * ```
+ */
+export const MCP_HTTP_HANDLER = Symbol('MCP_HTTP_HANDLER');