Class McpSession

constructor

• new McpSession(options: McpSessionOptions): McpSession

  Creates a new McpSession instance.

  Cancellation is handled natively by the SDK's Protocol layer (per-request AbortController, keyed by real JSON-RPC request ID). Progress reporting uses the SDK's extra.sendNotification with rate-limiting applied by createProgressReporter().

  Parameters

  • options: McpSessionOptions

    Session configuration options

  Returns McpSession

Readonlyoptions

Readonlysdk

name

• get name(): string

  Server name

  Returns string

version

• get version(): string

  Server version

  Returns string

dispose

• dispose(): Promise<void>

  Clean up session resources.

  Closes the underlying SDK McpServer, releasing protocol-level resources (pending requests, open streams, registered handlers). This is the counterpart to sdk.connect(transport) — every connected session should be disposed when no longer needed.

  Called by:

  • SessionManager (stateful sessions — on close/closeAll)
  • StreamableHttpTransport (stateless sessions — on response close)

  Safe to call multiple times — sdk.close() is idempotent.

  Returns Promise<void>

onClose

• onClose(callback: CloseCallback): this

  Set callback for session close events.

  Parameters

  • callback: CloseCallback

  Returns this

onError

• onError(callback: ErrorCallback): this

  Set callback for session error events.

  Parameters

  • callback: ErrorCallback

  Returns this

registerPrompts

• registerPrompts(prompts: readonly PromptDefinition<AnyZodObject>[]): void

  Registers all prompts with the MCP SDK server. Delegates to PromptRegistry.bindToSdk().

  Parameters

  • prompts: readonly PromptDefinition<AnyZodObject>[]

  Returns void

registerResources

• registerResources(
      resources: readonly ResourceStaticDefinition[],
      templates: readonly ResourceTemplateDefinition<AnyZodObject>[],
  ): void

  Registers all resources (static + templates) with the MCP SDK server. Delegates to ResourceRegistry.bindToSdk().

  Parameters

  • resources: readonly ResourceStaticDefinition[]
  • templates: readonly ResourceTemplateDefinition<AnyZodObject>[]

  Returns void

registerScopeFilteredListHandlers

• registerScopeFilteredListHandlers(
      options: {
          prompts: readonly PromptDefinition<AnyZodObject>[];
          resources: readonly ResourceStaticDefinition[];
          templates: readonly ResourceTemplateDefinition<AnyZodObject>[];
          tools: readonly ToolDefinition<ZodTypeAny>[];
      },
  ): void

  Overrides tools/list, resources/list, resources/templates/list, and prompts/list handlers to filter out entries whose requiredScopes are not satisfied by the requesting user's token scopes.

  This wraps the SDK's original handlers — the full list is constructed by the SDK, then filtered before being returned to the client.

  Call this AFTER all tools/resources/prompts have been registered via registerTools() etc.

  Parameters

  • options: {
        prompts: readonly PromptDefinition<AnyZodObject>[];
        resources: readonly ResourceStaticDefinition[];
        templates: readonly ResourceTemplateDefinition<AnyZodObject>[];
        tools: readonly ToolDefinition<ZodTypeAny>[];
    }

    All registered definitions (used to build scope lookup maps)

  Returns void

registerSetLevelHandler

• registerSetLevelHandler(onSetLevel: (level: McpLogLevel) => void): void

  Registers a request handler for logging/setLevel.

  Per MCP Spec: When the server declares logging: {} capability, clients can send logging/setLevel to control which log notifications they receive. The handler updates the McpNotificationLogger's minimum level so that only messages at or above the requested level are forwarded.

  Parameters

  • onSetLevel: (level: McpLogLevel) => void

    Callback to apply the requested level (typically mcpLogger.setMinLevel)

  Returns void

registerSubscriptionHandlers

• registerSubscriptionHandlers(): void

  Registers request handlers for resources/subscribe and resources/unsubscribe.

  Returns void

  Sdk-constraint

  — The SDK's high-level McpServer does not handle subscription requests. This uses the low-level Server.setRequestHandler() API to register handlers for the subscribe/unsubscribe JSON-RPC methods.

  Subscription tracking is per-session (this McpSession instance). When notifyResourceUpdated(uri) is called, only sessions that subscribed to the given URI receive notifications/resources/updated.

  In stateless mode, subscriptions are not meaningful (no persistent session), so this method should not be called for stateless sessions.

registerTaskTools

• registerTaskTools(taskTools: readonly TaskToolDefinition<ZodTypeAny>[]): void
  Experimental

  Registers task tools with the MCP SDK's experimental tasks API. Delegates to TaskToolRegistry.bindToSdk().

  MCP Tasks is an experimental SDK feature

  Parameters

  • taskTools: readonly TaskToolDefinition<ZodTypeAny>[]

  Returns void

registerTools

• registerTools(tools: readonly ToolDefinition<ZodTypeAny>[]): void

  Registers all tools with the MCP SDK server. Delegates to ToolRegistry.bindToSdk().

  Parameters

  • tools: readonly ToolDefinition<ZodTypeAny>[]

  Returns void

sendLogNotification

• sendLogNotification(level: McpLogLevel, message: string): Promise<void>

  Sends a log notification to the connected MCP client. Implements LogNotificationHandler so this session can be registered directly with the MCP notification logger.

  Parameters

  • level: McpLogLevel
  • message: string

  Returns Promise<void>

sendResourceUpdated

• sendResourceUpdated(uri: string): Promise<void>

  Sends a notifications/resources/updated notification to this session's client if the session has subscribed to the given URI.

  Parameters

  • uri: string

    The resource URI that was updated

  Returns Promise<void>