This is the documentation for v2 — looking for the v1 documentation?
MCP TypeScript SDK

Appearance

MCP TypeScript SDK (V2) / @modelcontextprotocol/node / toNodeHandler

toNodeHandler ​

Interfaces ​

FetchLikeMcpHandler ​

Defined in: packages/middleware/node/src/toNodeHandler.ts:83

The web-standard fetch face of an McpHttpHandler (or any fetch-shaped MCP handler) — the only surface toNodeHandler touches. Accepting the face structurally keeps the adapter usable with hand-wired compositions that route over isLegacyRequest and produce a Response directly.

Properties ​

fetch ​

fetch: (request, options?) => Promise<Response>

Defined in: packages/middleware/node/src/toNodeHandler.ts:84

Parameters ​
request ​

Request

options? ​

McpHandlerRequestOptions

Returns ​

Promise<Response>

NodeIncomingMessageLike ​

Defined in: packages/middleware/node/src/toNodeHandler.ts:59

Minimal duck-typed shape of a Node.js IncomingMessage accepted by toNodeHandler. Kept structural so the adapter stays free of node: imports.

Extends ​

  • AsyncIterable<unknown>

Properties ​

auth? ​

optional auth?: AuthInfo

Defined in: packages/middleware/node/src/toNodeHandler.ts:64

Validated authentication info attached by upstream middleware (pass-through).

headers ​

headers: Record<string, string | string[] | undefined>

Defined in: packages/middleware/node/src/toNodeHandler.ts:62

method? ​

optional method?: string

Defined in: packages/middleware/node/src/toNodeHandler.ts:60

url? ​

optional url?: string

Defined in: packages/middleware/node/src/toNodeHandler.ts:61

Methods ​

[asyncIterator]() ​

[asyncIterator](): AsyncIterator<unknown, any, any>

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es2018.asynciterable.d.ts:38

Returns ​

AsyncIterator<unknown, any, any>

Inherited from ​

AsyncIterable.[asyncIterator]

NodeServerResponseLike ​

Defined in: packages/middleware/node/src/toNodeHandler.ts:68

Minimal duck-typed shape of a Node.js ServerResponse accepted by toNodeHandler.

Properties ​

destroyed? ​

optional destroyed?: boolean

Defined in: packages/middleware/node/src/toNodeHandler.ts:73

Methods ​

end() ​

end(chunk?): unknown

Defined in: packages/middleware/node/src/toNodeHandler.ts:71

Parameters ​
chunk? ​

string | Uint8Array<ArrayBufferLike>

Returns ​

unknown

on() ​

on(event, listener): unknown

Defined in: packages/middleware/node/src/toNodeHandler.ts:72

Parameters ​
event ​

string

listener ​

(...args) => void

Returns ​

unknown

write() ​

write(chunk): unknown

Defined in: packages/middleware/node/src/toNodeHandler.ts:70

Parameters ​
chunk ​

string | Uint8Array<ArrayBufferLike>

Returns ​

unknown

writeHead() ​

writeHead(statusCode, headers?): unknown

Defined in: packages/middleware/node/src/toNodeHandler.ts:69

Parameters ​
statusCode ​

number

headers? ​

Record<string, string>

Returns ​

unknown

ToNodeHandlerOptions ​

Defined in: packages/middleware/node/src/toNodeHandler.ts:96

Options for toNodeHandler.

Properties ​

maxRequestBodySize? ​

optional maxRequestBodySize?: number

Defined in: packages/middleware/node/src/toNodeHandler.ts:113

Upper bound, in bytes, on a request body the adapter buffers from the Node stream (when no parsedBody is supplied). A larger body is answered 413 without calling handler.fetch. Raise it together with the handler's own maxRequestBodySize; the adapter's bound applies first. Must be a positive number.

Default ​
ts
4194304 (4 MiB)
onerror? ​

optional onerror?: (error) => void

Defined in: packages/middleware/node/src/toNodeHandler.ts:104

Called when the adapter answers 500 because request conversion or handler.fetch itself threw (e.g. a closed handler). Restores the observability the removed .node face had via the entry's own onerror — entry-internal failures are still reported through handler.fetch and surface via the entry's onerror option as before.

Parameters ​
error ​

Error

Returns ​

void

ToWebRequestOptions ​

Defined in: packages/middleware/node/src/toNodeHandler.ts:233

Options for toWebRequest.

Properties ​

maxRequestBodySize? ​

optional maxRequestBodySize?: number

Defined in: packages/middleware/node/src/toNodeHandler.ts:243

Upper bound, in bytes, on the body read from the Node stream (when no parsedBody is supplied); the returned promise rejects past it with an Error whose name is 'RequestBodyTooLargeError' and status is 413. Must be a positive number.

Default ​
ts
4194304 (4 MiB)
signal? ​

optional signal?: AbortSignal

Defined in: packages/middleware/node/src/toNodeHandler.ts:235

An AbortSignal to attach to the constructed Request (request.signal).

Type Aliases ​

NodeMcpRequestHandler ​

NodeMcpRequestHandler = (req, res, parsedBody?) => Promise<void>

Defined in: packages/middleware/node/src/toNodeHandler.ts:93

A Node.js (req, res, parsedBody?) request handler produced by toNodeHandler. The third argument is an optional pre-parsed body (req.body from express.json()); a function third argument (Express's next when the handler is mounted as middleware) is ignored.

Parameters ​

req ​

NodeIncomingMessageLike

res ​

NodeServerResponseLike

parsedBody? ​

unknown

Returns ​

Promise<void>

Functions ​

toNodeHandler() ​

toNodeHandler(handler, opts?): NodeMcpRequestHandler

Defined in: packages/middleware/node/src/toNodeHandler.ts:129

Adapts a web-standard MCP handler (handler.fetch) to a Node.js (req, res, parsedBody?) request handler. The returned function converts the Node request to a web-standard Request, calls handler.fetch, then writes the Response back to res (honoring write backpressure for streamed SSE responses).

req.auth is forwarded as the handler's pass-through authInfo. A function third argument (Express's next) is ignored, never treated as a body.

Pass { onerror } to observe the adapter-level error fallback (request conversion / handler.fetch throw) before the 500 response is written.

Parameters ​

handler ​

FetchLikeMcpHandler

opts? ​

ToNodeHandlerOptions

Returns ​

NodeMcpRequestHandler

toWebRequest() ​

toWebRequest(req, parsedBody?, options?): Promise<Request>

Defined in: packages/middleware/node/src/toNodeHandler.ts:264

Convert a Node.js IncomingMessage (duck-typed — an Express req works) to the web-standard Request that handler.fetch() and isLegacyRequest() take. This is the conversion toNodeHandler performs internally, exported for hand-wired compositions:

ts
const probe = await toWebRequest(req, req.body);
await ((await isLegacyRequest(probe)) ? legacy(req, res) : modern(req, res, req.body));

With no parsedBody the Node stream is read to completion (up to maxRequestBodySize, 4 MiB by default — a longer body rejects with an error carrying name: 'RequestBodyTooLargeError' and status: 413) — read the body from the returned Request afterwards, not from req. When a body parser already consumed the stream (express.json()), pass the parsed value as parsedBody and nothing is read from req.

Parameters ​

req ​

NodeIncomingMessageLike

parsedBody? ​

unknown

options? ​

ToWebRequestOptions

Returns ​

Promise<Request>