MCP TypeScript SDK (V2) / @modelcontextprotocol/server / server/listenRouter

server/listenRouter

Classes

StdioListenRouter

Defined in: packages/server/src/server/listenRouter.ts:274

Per-connection listen state for the stdio entry. One instance is held by serveStdio for the connection lifetime; it routes inbound subscriptions/listen / notifications/cancelled and rewrites outbound change notifications onto the active subscriptions. No bus — the long-lived pinned instance's existing send*ListChanged() calls feed straight into routeOutbound().

Constructors

Constructor

new StdioListenRouter(_maxSubscriptions?, serverCapabilities?): StdioListenRouter

Defined in: packages/server/src/server/listenRouter.ts:285

Parameters

_maxSubscriptions?

number = DEFAULT_MAX_SUBSCRIPTIONS

serverCapabilities?

completions?

{[key: string]: string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null)[] | null; } | string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null; } | (string | ... 4 more ... | null)[] | null[] | null; } = ...

Present if the server supports sending completions to the client.

experimental?

{[key: string]: object; } = ...

Experimental, non-standard capabilities that the server supports.

extensions?

{[key: string]: object; } = ...

Extensions that the server supports. Keys are extension identifiers (vendor-prefix/extension-name).

logging?

Present if the server supports sending log messages to the client.

Deprecated

Deprecated as of protocol version 2026-07-28 (SEP-2577); remains in the specification for at least twelve months. Migrate to stderr logging (STDIO servers) or OpenTelemetry.

prompts?

{ listChanged?: boolean; } = ...

Present if the server offers any prompt templates.

prompts.listChanged?

boolean = ...

Whether this server supports issuing notifications for changes to the prompt list.

resources?

{ listChanged?: boolean; subscribe?: boolean; } = ...

Present if the server offers any resources to read.

resources.listChanged?

boolean = ...

Whether this server supports issuing notifications for changes to the resource list.

boolean = ...

Whether this server supports clients subscribing to resource updates.

tasks?

{[key: string]: unknown; cancel?: {[key: string]: string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null)[] | null; } | string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null; } | (string | ... 4 more ... | null)[] | null[] | null; }; list?: {[key: string]: string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null)[] | null; } | string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null; } | (string | ... 4 more ... | null)[] | null[] | null; }; requests?: {[key: string]: unknown; tools?: {[key: string]: unknown; call?: {[key: string]: ... | ... | ... | ... | ... | ... | ...; }; }; }; } = ...

Present if the server supports task creation.

Deprecated

2025-11-25 wire vocabulary with no SDK runtime; parsed for interoperability only — servers built on this SDK never advertise it.

tasks.cancel?

Present if the server supports cancelling tasks.

tasks.list?

Present if the server supports listing tasks.

tasks.requests?

{[key: string]: unknown; tools?: {[key: string]: unknown; call?: {[key: string]: ... | ... | ... | ... | ... | ... | ...; }; }; } = ...

Capabilities for task creation on specific request types.

tasks.requests.tools?

{[key: string]: unknown; call?: {[key: string]: ... | ... | ... | ... | ... | ... | ...; }; } = ...

Task support for tool requests.

tasks.requests.tools.call?

{[key: string]: ... | ... | ... | ... | ... | ... | ...; } = ...

tools?

{ listChanged?: boolean; } = ...

Present if the server offers any tools to call.

tools.listChanged?

boolean = ...

Whether this server supports issuing notifications for changes to the tool list.

Returns

StdioListenRouter

Methods

cancel()

cancel(id): boolean

Defined in: packages/server/src/server/listenRouter.ts:344

Tear down one subscription (inbound notifications/cancelled). Returns true when a subscription was removed. After this call NOTHING further is delivered for that subscription id (the post-cancel hardening).

Parameters

id

RequestId

Returns

boolean

has()

has(id): boolean

Defined in: packages/server/src/server/listenRouter.ts:302

Whether id is an active listen subscription on this connection.

Parameters

id

RequestId

Returns

boolean

routeOutbound()

routeOutbound(message): NotificationBody[] | "passthrough"

Defined in: packages/server/src/server/listenRouter.ts:357

Route an outbound notification through the active subscriptions.

For a subscription-gated change notification, returns one stamped copy per subscription that opted in to it (an empty array means it is dropped — the modern era never delivers an un-requested change type).
For any other outbound message, returns 'passthrough' (the entry forwards it as-is).

Parameters

message

method

string

params?

{[key: string]: unknown; }

Returns

NotificationBody[] | "passthrough"

serve()

serve(message): NotificationBody | { error: { code: number; message: string; }; id: RequestId; jsonrpc: "2.0"; }

Defined in: packages/server/src/server/listenRouter.ts:317

Serve one inbound subscriptions/listen request: registers the subscription and returns the stamped acknowledged notification (or, on capacity / params rejection, the in-band JSON-RPC error response).

Parameters

message

id

string | number = RequestIdSchema

jsonrpc

"2.0" = ...

method

string = ...

params?

{[key: string]: unknown; _meta?: {[key: string]: unknown; io.modelcontextprotocol/related-task?: { taskId: string; }; progressToken?: string | number; }; } = ...

params._meta?

{[key: string]: unknown; io.modelcontextprotocol/related-task?: { taskId: string; }; progressToken?: string | number; } = ...

See General fields: _meta for notes on _meta usage.

{ taskId: string; } = ...

If specified, this request is related to the provided task.

string = ...

params._meta.progressToken?

string | number = ...

If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications.

Returns

NotificationBody | { error: { code: number; message: string; }; id: RequestId; jsonrpc: "2.0"; }

Throws

when called before setServerCapabilities (or the constructor) has supplied the serving instance's capabilities. Honoring a filter without knowing the server's advertised capabilities would fail open (deliver unadvertised types); the entry guarantees capabilities are set before any listen request is routed here.

setServerCapabilities()

setServerCapabilities(capabilities): void

Defined in: packages/server/src/server/listenRouter.ts:297

Record the serving instance's declared capabilities once it has been constructed. Called by serveStdio's connect path; subsequent serve() calls narrow the honored filter against these.

Parameters

capabilities

completions?

Present if the server supports sending completions to the client.

experimental?

{[key: string]: object; } = ...

Experimental, non-standard capabilities that the server supports.

extensions?

{[key: string]: object; } = ...

Extensions that the server supports. Keys are extension identifiers (vendor-prefix/extension-name).

logging?

Present if the server supports sending log messages to the client.

Deprecated

Deprecated as of protocol version 2026-07-28 (SEP-2577); remains in the specification for at least twelve months. Migrate to stderr logging (STDIO servers) or OpenTelemetry.

prompts?

{ listChanged?: boolean; } = ...

Present if the server offers any prompt templates.

prompts.listChanged?

boolean = ...

Whether this server supports issuing notifications for changes to the prompt list.

resources?

{ listChanged?: boolean; subscribe?: boolean; } = ...

Present if the server offers any resources to read.

resources.listChanged?

boolean = ...

Whether this server supports issuing notifications for changes to the resource list.

boolean = ...

Whether this server supports clients subscribing to resource updates.

tasks?

{[key: string]: unknown; cancel?: {[key: string]: string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null)[] | null; } | string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null; } | (string | ... 4 more ... | null)[] | null[] | null; }; list?: {[key: string]: string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null)[] | null; } | string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null; } | (string | ... 4 more ... | null)[] | null[] | null; }; requests?: {[key: string]: unknown; tools?: {[key: string]: unknown; call?: {[key: string]: string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null)[] | null; } | ...[] | null; }; }; }; } = ...

Present if the server supports task creation.

Deprecated

2025-11-25 wire vocabulary with no SDK runtime; parsed for interoperability only — servers built on this SDK never advertise it.

tasks.cancel?

Present if the server supports cancelling tasks.

tasks.list?

Present if the server supports listing tasks.

tasks.requests?

{[key: string]: unknown; tools?: {[key: string]: unknown; call?: {[key: string]: string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null)[] | null; } | ...[] | null; }; }; } = ...

Capabilities for task creation on specific request types.

tasks.requests.tools?

{[key: string]: unknown; call?: {[key: string]: string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null)[] | null; } | ...[] | null; }; } = ...

Task support for tool requests.

tasks.requests.tools.call?

tools?

{ listChanged?: boolean; } = ...

Present if the server offers any tools to call.

tools.listChanged?

boolean = ...

Whether this server supports issuing notifications for changes to the tool list.

Returns

void

teardownAll()

teardownAll(): object[]

Defined in: packages/server/src/server/listenRouter.ts:379

Server-side graceful teardown of every active subscription: returns the empty subscriptions/listen JSON-RPC result for each subscription id — the spec's graceful-close signal — for the entry to emit before closing the wire. Clears the set so nothing further is delivered.

Returns

object[]

Interfaces

ListenRouter

Defined in: packages/server/src/server/listenRouter.ts:94

The HTTP listen router: holds the set of open subscriptions and serves each listen request as an SSE response.

Properties

openCount

readonly openCount: number

Defined in: packages/server/src/server/listenRouter.ts:112

The number of currently open subscription streams (for tests / introspection).

Methods

closeAll()

closeAll(): void

Defined in: packages/server/src/server/listenRouter.ts:110

Gracefully close every open subscription stream: emits the empty subscriptions/listen JSON-RPC result (the spec's graceful-close signal) as the final SSE frame, then closes the stream.

Returns

void

serve()

serve(message, signal, capabilities): Response

Defined in: packages/server/src/server/listenRouter.ts:104

Serve one subscriptions/listen request and return the SSE Response (or, on capacity / params rejection, the in-band JSON-RPC error Response). The ack notification is the first SSE frame.

capabilities is required: the acknowledged filter is always narrowed against what the serving instance advertises (honoring a filter without capabilities would fail open and deliver unadvertised types).

Parameters

message

id

string | number = RequestIdSchema

jsonrpc

"2.0" = ...

method

string = ...

params?

{[key: string]: unknown; _meta?: {[key: string]: unknown; io.modelcontextprotocol/related-task?: { taskId: string; }; progressToken?: string | number; }; } = ...

params._meta?

{[key: string]: unknown; io.modelcontextprotocol/related-task?: { taskId: string; }; progressToken?: string | number; } = ...

See General fields: _meta for notes on _meta usage.

{ taskId: string; } = ...

If specified, this request is related to the provided task.

string = ...

params._meta.progressToken?

string | number = ...

signal

AbortSignal | undefined

capabilities

completions?

Present if the server supports sending completions to the client.

experimental?

{[key: string]: object; } = ...

Experimental, non-standard capabilities that the server supports.

extensions?

{[key: string]: object; } = ...

Extensions that the server supports. Keys are extension identifiers (vendor-prefix/extension-name).

logging?

Present if the server supports sending log messages to the client.

Deprecated

Deprecated as of protocol version 2026-07-28 (SEP-2577); remains in the specification for at least twelve months. Migrate to stderr logging (STDIO servers) or OpenTelemetry.

prompts?

{ listChanged?: boolean; } = ...

Present if the server offers any prompt templates.

prompts.listChanged?

boolean = ...

Whether this server supports issuing notifications for changes to the prompt list.

resources?

{ listChanged?: boolean; subscribe?: boolean; } = ...

Present if the server offers any resources to read.

resources.listChanged?

boolean = ...

Whether this server supports issuing notifications for changes to the resource list.

boolean = ...

Whether this server supports clients subscribing to resource updates.

tasks?

{[key: string]: unknown; cancel?: {[key: string]: string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null)[] | null; } | string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null; } | (string | ... 4 more ... | null)[] | null[] | null; }; list?: {[key: string]: string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null)[] | null; } | string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null; } | (string | ... 4 more ... | null)[] | null[] | null; }; requests?: {[key: string]: unknown; tools?: {[key: string]: unknown; call?: {[key: string]: string | number | boolean | { [x: string]: string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | number | boolean | ... | (string | ... 4 more ... | null)[] | null)[] | null)[] | null)[] | null)[] | null; } | ...[] | null; }; }; }; } = ...

Present if the server supports task creation.

Deprecated

2025-11-25 wire vocabulary with no SDK runtime; parsed for interoperability only — servers built on this SDK never advertise it.

tasks.cancel?

Present if the server supports cancelling tasks.

tasks.list?

Present if the server supports listing tasks.

tasks.requests?

Capabilities for task creation on specific request types.

tasks.requests.tools?

Task support for tool requests.

tasks.requests.tools.call?

tools?

{ listChanged?: boolean; } = ...

Present if the server offers any tools to call.

tools.listChanged?

boolean = ...

Whether this server supports issuing notifications for changes to the tool list.

Returns

Response

ListenRouterOptions

Defined in: packages/server/src/server/listenRouter.ts:39

Options for createListenRouter.

Properties

bus

bus: ServerEventBus

Defined in: packages/server/src/server/listenRouter.ts:41

The event bus listen streams subscribe to.

keepAliveMs?

optional keepAliveMs?: number

Defined in: packages/server/src/server/listenRouter.ts:45

SSE comment-frame keepalive interval; 0 disables keepalive (default 15000).

maxSubscriptions?

optional maxSubscriptions?: number

Defined in: packages/server/src/server/listenRouter.ts:43

Reject a new listen with -32603 when this many subscriptions are already open (default 1024).

onerror?

optional onerror?: (error) => void

Defined in: packages/server/src/server/listenRouter.ts:47

Out-of-band error reporting (never alters the response).

Parameters

error

Error

Returns

void

NotificationBody

Defined in: packages/server/src/server/listenRouter.ts:54

Internal

A wire-shape notification body (method + loose params).

Properties

method

method: string

Defined in: packages/server/src/server/listenRouter.ts:55

params

params: object

Defined in: packages/server/src/server/listenRouter.ts:56

Index Signature

[key: string]: unknown

_meta?

optional _meta?: Record<string, unknown>

Variables

DEFAULT_LISTEN_KEEPALIVE_MS

const DEFAULT_LISTEN_KEEPALIVE_MS: 15000 = 15_000

Defined in: packages/server/src/server/listenRouter.ts:33

Default SSE comment-frame keepalive interval for listen streams.

DEFAULT_MAX_SUBSCRIPTIONS

const DEFAULT_MAX_SUBSCRIPTIONS: 1024 = 1024

Defined in: packages/server/src/server/listenRouter.ts:36

Default capacity guard: refuse a new subscription when this many are already open.

Functions

createListenRouter()

createListenRouter(options): ListenRouter

Defined in: packages/server/src/server/listenRouter.ts:115

Parameters

options

ListenRouterOptions

Returns

ListenRouter

parseListenFilter()

parseListenFilter(message): { promptsListChanged?: boolean; resourcesListChanged?: boolean; resourceSubscriptions?: string[]; toolsListChanged?: boolean; } | undefined

Defined in: packages/server/src/server/listenRouter.ts:83

Read the requested filter off a subscriptions/listen request body. Returns the validated filter, or undefined when params.notifications is absent or fails the schema (the caller answers -32602 — the spec marks notifications REQUIRED on the listen request).

Parameters

message

id

string | number = RequestIdSchema

jsonrpc

"2.0" = ...

method

string = ...

params?

{[key: string]: unknown; _meta?: {[key: string]: unknown; io.modelcontextprotocol/related-task?: { taskId: string; }; progressToken?: string | number; }; } = ...

params._meta?

{[key: string]: unknown; io.modelcontextprotocol/related-task?: { taskId: string; }; progressToken?: string | number; } = ...

See General fields: _meta for notes on _meta usage.

{ taskId: string; } = ...

If specified, this request is related to the provided task.

string = ...

params._meta.progressToken?

string | number = ...

Returns

Type Literal

{ promptsListChanged?: boolean; resourcesListChanged?: boolean; resourceSubscriptions?: string[]; toolsListChanged?: boolean; }

promptsListChanged?

optional promptsListChanged?: boolean

If true, receive notifications/prompts/list_changed.

resourcesListChanged?

optional resourcesListChanged?: boolean

If true, receive notifications/resources/list_changed.

resourceSubscriptions?

optional resourceSubscriptions?: string[]

Subscribe to notifications/resources/updated for these resource URIs. Replaces the former resources/subscribe RPC on the 2026-07-28 revision.

toolsListChanged?

optional toolsListChanged?: boolean

If true, receive notifications/tools/list_changed.

undefined

index

Namespaces

migrations

v1-to-v2

mappings

transforms

index

Namespaces

middleware

auth

handlers

middleware

providers

sse

server/listenRouter ​

Classes ​

StdioListenRouter ​

Constructors ​

Constructor ​

Parameters ​

_maxSubscriptions? ​

serverCapabilities? ​

completions? ​

experimental? ​

extensions? ​

logging? ​

prompts? ​

prompts.listChanged? ​

resources? ​

resources.listChanged? ​

resources.subscribe? ​

tasks? ​

tasks.cancel? ​

tasks.list? ​

tasks.requests? ​

tasks.requests.tools? ​

tasks.requests.tools.call? ​

tools? ​

tools.listChanged? ​

Returns ​

Methods ​

cancel() ​

Parameters ​

id ​

Returns ​

has() ​

Parameters ​

id ​

Returns ​

routeOutbound() ​

Parameters ​

message ​

method ​

params? ​

Returns ​

serve() ​

Parameters ​

message ​

id ​

jsonrpc ​

method ​

params? ​

params._meta? ​

params._meta.io.modelcontextprotocol/related-task? ​

params._meta.io.modelcontextprotocol/related-task.taskId ​

params._meta.progressToken? ​

Returns ​

Throws ​

setServerCapabilities() ​

Parameters ​

capabilities ​

completions? ​

experimental? ​

extensions? ​

logging? ​

prompts? ​

prompts.listChanged? ​

resources? ​

resources.listChanged? ​

resources.subscribe? ​

server/listenRouter

Classes

StdioListenRouter

Constructors

Constructor

Parameters

_maxSubscriptions?

serverCapabilities?

completions?

experimental?

extensions?

logging?

prompts?

prompts.listChanged?

resources?

resources.listChanged?

resources.subscribe?

tasks?

tasks.cancel?

tasks.list?

tasks.requests?

tasks.requests.tools?

tasks.requests.tools.call?

tools?

tools.listChanged?

Returns

Methods

cancel()

Parameters

id

Returns

has()

Parameters

id

Returns

routeOutbound()

Parameters

message

method

params?

Returns

serve()

Parameters

message

id

jsonrpc

method

params?

params._meta?

params._meta.io.modelcontextprotocol/related-task?

params._meta.io.modelcontextprotocol/related-task.taskId

params._meta.progressToken?

Returns

Throws

setServerCapabilities()

Parameters

capabilities

completions?

experimental?

extensions?

logging?

prompts?

prompts.listChanged?

resources?

resources.listChanged?

resources.subscribe?

tasks?

tasks.cancel?

tasks.list?

tasks.requests?

tasks.requests.tools?

tasks.requests.tools.call?

tools?

tools.listChanged?

Returns

teardownAll()

Returns

Interfaces

ListenRouter

Properties