Behavioral changes
These are runtime-behavior changes that may affect tests and assertions; no source rewrite required unless noted.
Error-shape changes (every era)
- Unchanged, for re-baselining relief: timeout rejections still carry
data.timeout/data.maxTotalTimeoutexactly as v1McpErrordid — v1 assertions on those survive verbatim. The cancelled-on-timeout signal is unchanged on legacy-era connections and on stdio/in-memory at any era; on 2026-era Streamable HTTP the cancel signal is the per-request stream close instead of anotifications/cancelledPOST (see support-2026-07-28.md). The one exemption is theinitializehandshake: an aborted or timed-outconnect()still rejects locally, but nonotifications/cancelledgoes on the wire — the spec forbids cancellinginitialize, and v1 sent one anyway. v1 tests asserting that notification need re-baselining. - Also unchanged: SSE reconnection exhaustion.
StreamableHTTPClientTransport's standalone GET-stream reconnection behavior and its exhaustion signal carry over from v1: when retries run out, the transport emitsonerrorwith a plainErrorwhose message isMaximum reconnection attempts (N) exceeded.— there is no typed error class for this condition, so monitors that match the message text keep working. - Also unchanged: elicitation response validation.
elicitInput's local validation of elicitation responses againstrequestedSchema, the resulting-32602error message wording (Elicitation response content does not match requested schema: …), and theMcpServer/ClientjsonSchemaValidatoroption carry over from v1 — tests pinning the local-validation message and custom validator wiring need no re-baselining. - Unknown / disabled tool calls now reject with
ProtocolError(-32602 InvalidParams)instead of resolvingCallToolResult{isError: true}. v1 callers that checkedresult.isErrorfor an unknown tool will get an unhandled rejection — catch the rejected promise instead. - The
MCP error <code>:message prefix is gone. v1 prefixed relayed JSON-RPC error messages (MCP error -32602: …); v2'sProtocolError.messagecarries the peer's message verbatim. Tests and log scrapers that matched the prefix or the numeric code in rendered text should matcherror.codeinstead. - In-flight request handlers are aborted on transport close —
ctx.mcpReq.signalfires (v1 let them run to completion).InMemoryTransport.close()no longer double-firesoncloseon the initiating side. Protocol.request()with an already-aborted signal rejects withSdkError(SdkErrorCode.RequestTimeout, reason)instead of throwing the rawsignal.reason, matching the in-flight-abort path.- OAuth discovery (
discoverOAuthProtectedResourceMetadata/discoverOAuthMetadata, transitivelyauth()) throws on fetchTypeError(DNS failure,ECONNREFUSED, invalid URL) in Node and Cloudflare Workers instead of swallowing it as a CORS miss →undefined. The CORS-swallow remains browser-only.
Client connection & dispatch
connect()skips theinitializehandshake when the transport already exposes asessionId— it assumes it is reconnecting to an existing session (unchanged from v1.x, where the same guard has existed since 1.10.0; recorded here because the far-away symptom keeps surprising migrators). A custom or test transport that setssessionIdat construction silently skips initialization:getServerCapabilities()staysundefinedand the list verbs return empty results. ExposesessionIdonly after the first request has been sent.- The typed verbs dispatch after async pre-work.
Protocol.request()itself still hands the frame to the transport before its firstawait(v1-compatible). The typed verbs on top of it —callTool()and the cacheable list verbs — perform async work first (header-mirroring scan, response-cache freshness, output-validator resolution), so an abort fired in the same tick can land before the frame is ever sent: the call rejects withSdkError(RequestTimeout, reason)and nonotifications/cancelledis emitted (nothing was in flight). v1 sent the frame synchronously from these verbs. Once the frame is on the wire, aborting still sendsnotifications/cancelledbefore rejecting. - Protocol-version pinning is a first-class option.
ProtocolOptions.supportedProtocolVersionspins the legacyinitializehandshake: the first pre-2026 entry in the list is offered (list order is preference order), a counter-offer is accepted only if it is one of the list's pre-2026 entries, and a list with no pre-2026 entry makes the handshake throw. UnderversionNegotiation: 'auto'the modern probe candidates are the list's modern entries when it has any (otherwise the SDK's default modern set); a{ pin }is honored as given and is not checked against the list (see support-2026-07-28.md). v1 had no public equivalent (SUPPORTED_PROTOCOL_VERSIONSwas a fixed constant) — replace any workaround that patched the offered version with this option. - Also unchanged: HTTP 405 tolerances. A
405answering the standalone GET stream open is benign (the client proceeds without the stream), and a405answering the session DELETE resolvesterminateSession()normally — stateless-topology servers that decline both verbs keep working without changes, as in v1.
stdio transport
- A configurable
maxBufferSize(default 10 MB) caps the stdio read buffer. A single message that would push the buffer past the limit emitsonerrorand closes the connection (v1 buffered unbounded). Configure vianew StdioClientTransport({ ..., maxBufferSize })/new StdioServerTransport(stdin, stdout, { maxBufferSize }). ReadBuffer.readMessage()now silently skips non-JSON stdout lines instead of throwingSyntaxError→onerror. Hot-reload tools (tsx, nodemon) that write debug output to stdout no longer break the transport. Lines that parse as JSON but fail JSON-RPC schema validation still throw.StdioClientTransportalways setswindowsHide: truewhen spawning the server process on Windows (previously Electron-only). Prevents stray console windows in non-Electron Windows hosts.- Outbound write failures — e.g. the host closing the stdout pipe while a send is
pending — now reject the pending
send()and close the transport throughonerror/oncloseinstead of surfacing an unhandled stream error; lifecycle tests that pinned a crash-class exit observe a clean shutdown instead.
Client list methods
listPrompts(),listResources(),listResourceTemplates(),listTools()return empty results when the server didn't advertise the corresponding capability, instead of sending the request. SetenforceStrictCapabilities: trueinClientOptionsto restore the v1 throw.- Called without a
cursor, the same methods now auto-aggregate every page and return an aggregate with nonextCursor. Passing{ cursor }still fetches one page. Manual pagination loops keep working (the first iteration returns everything); replace them with the bare no-arg call. The walk is capped atClientOptions.listMaxPages(default 64); overrun throwsSdkError(ListPaginationExceeded). There is no way to fetch only the first page through the typed verbs — for page-level observation (pagination tooling, per-page stats) drop toclient.request({ method: 'tools/list', params }), which never aggregates. - Output-schema validator compilation is now lazy — validators compile on the first
callTool()against the cachedtools/listentry, not eagerly insidelistTools(). In v1,listTools()threw on an uncompilableoutputSchema; nowlistTools()succeeds and the compile failure surfaces whencallTool()is invoked on the affected tool, asProtocolError(InvalidParams, "Tool 'X' has an invalid outputSchema: …"), before the request is sent. Validation is never silently skipped. - On a 2026-07-28 connection the cacheable verbs honour the server-stamped
ttlMs/cacheScope(SEP-2549) and may return a still-fresh cached entry without a round trip. Per-call override:{ cacheMode: 'refresh' | 'bypass' }. NewClientOptions:cachePartition,defaultCacheTtlMs.ResponseCacheStoregaineddelete(key);InMemoryResponseCacheStoreis now bounded ({ maxEntries }, default 512).CacheEntry.value(and theset()entry value) is the JSON-serialized result document (string, notunknown): persist and return it verbatim,JSON.parseit to inspect.
Server (Streamable HTTP transport)
- Resumability behavior (SSE priming events,
closeSSE/closeStandaloneSSEcallbacks) is only enabled for protocol versions in the transport's supported-versions list that are>= 2025-11-25. Unknown future version strings in aninitializerequest body no longer enable it. - Session-ID mismatch still responds
404with JSON-RPC-32001(Session not found), unchanged from v1. This-32001is an SDK convention, not spec-assigned; client code should key off the HTTP404status, not-32001.
Server (deprecated accessors and app-factory Origin validation)
Server.getClientCapabilities(),getClientVersion(),getNegotiatedProtocolVersion()are@deprecatedbut functional. On 2026-07-28 requests, preferctx.mcpReq.envelope.createMcpExpressApp()/createMcpHonoApp()/createMcpFastifyApp()with a localhost-classhostnow also validate theOriginheader by default. Browser-served clients on a non-localhost origin needallowedOrigins: [...](replaces the default localhost allowlist; validation cannot be disabled for localhost binds). Requests without anOriginheader are unaffected; a presentOriginthat cannot be parsed — including the opaqueOrigin: nullsent by sandboxed iframes,file://pages, and cross-origin redirects — is rejected with 403 and cannot be allowlisted viaallowedOrigins. Framework-agnostic helpers (validateOriginHeader,localhostAllowedOrigins,originValidationResponse) are in@modelcontextprotocol/server;@modelcontextprotocol/nodeshipshostHeaderValidation/originValidationrequest guards for plainnode:http.
Server (McpServer / Streamable HTTP behavior)
- Eager capability-handler install.
McpServernow installs list/read/call handlers for every primitive capability declared inServerOptions.capabilities, even with zero registrations.new McpServer(info, { capabilities: { tools: {} } })with no registered tools answerstools/listwith{ tools: [] }instead of-32601 Method not found. Low-levelServerusers remain responsible for registering handlers for declared capabilities — with one exception: declaring theloggingcapability (in the constructor's capabilities or via pre-connectregisterCapabilities()) installs thelogging/setLevelhandler on the low-levelServertoo, sologging/setLevelrequests that answered-32601in v1 now resolve. Eager install also rewrites the advertised capability objects: a declaredtools: {}/resources: {}/prompts: {}is advertised withlistChanged: trueat construction, so capability pins and initialize-result golden tests need re-baselining. To advertise without the default, setlistChanged: falseexplicitly; capabilities declared on the low-levelServerare advertised verbatim. WebStandardStreamableHTTPServerTransportstore-firsteventStoresemantics. Request-related events emitted aftercloseSSE()— and the final response when no per-request stream is connected — are now persisted to the configuredeventStorefor replay (v1 dropped them / threw"No connection established"). Without aneventStore, the same condition surfaces viaonerrorand the request id is retired.NodeStreamableHTTPServerTransportis a thin wrapper overWebStandardStreamableHTTPServerTransport, so this — like every behavioral note on the web-standard transport — applies to the Node transport too.registerResourcereserves thecacheHintconfig key. It is validated (RangeErroron invalid values) and stripped from the resource's list metadata; v1 passed it through verbatim as ordinary metadata. Untyped callers that previously smuggled acacheHintkey through resource metadata should rename it.
ctx.mcpReq.log() is request-related on every era
ctx.mcpReq.log() now emits its notifications/message request-related (it rides the
in-flight exchange like progress) on every era. On a 2025-era sessionful Streamable HTTP
transport this moves handler-emitted logs from the standalone GET stream onto the
per-request POST response stream — a spec-conformance correction. The session-scoped
logging/setLevel filter applies as before on 2025-era connections. (On 2026-07-28
requests, the per-request _meta.logLevel envelope key is the filter — see
support-2026-07-28.md.)
Wire tightening (every era)
CallToolResult.contentkeeps the v1 parse tolerance on the legacy era. An inbound result withoutcontentdefaults to[](deployed servers omit it alongsidestructuredContent); 2026-07-28 connections stay strict. Authoring is era-independent: the TypeScript surface requirescontenton handler results, except successful results of aregisterTooltool with a typedoutputSchema, which may omit it.McpServergives any content-less tool result that carriesstructuredContenta JSON text block of that value; a content-less result withoutstructuredContentis normalized tocontent: []before it reaches the wire. One sharpening remains: a content-less body carrying another result family's vocabulary (a task handle or aninput_requiredround) is still rejected loudly — tolerance never turns a different result kind into a silent empty success. A body whose only foreign key wasresultTypestrips to an empty object and defaults, exactly as v1 parsed a payload-free body.ElicitResult.contentvalues are typed and validated asstring | number | boolean | string[]. v1's TypeScript surface acceptedRecord<string, unknown>content values; an elicitation handler returning arbitrary objects now fails to compile (and fails schema validation) — narrow to the primitives the elicitation spec allows.- Custom (3-arg) handlers receive
_meta.setRequestHandler(method, {params}, handler)used to deleteparams._metabefore validation; it now passes_metathrough (minus the reservedio.modelcontextprotocol/*envelope keys). If your params schema is strict, add an optional_metamember. specTypeSchemasvalidate the neutral model. Result entries no longer acceptresultType; the validators for the 2025-only task message types andRequestMetaEnvelopeleft the public set (SpecTypeNamenarrowed accordingly).- Sampling
hasToolsdiscriminant now keys ontools || toolChoice(previouslytoolsonly) when selecting the with-toolsCreateMessageResultvariant, on every era. - Inbound frames that fail message-shape validation are not answered. v2 routes
every inbound frame through typed message guards; a frame that matches no JSON-RPC
shape (e.g. a hand-built ping with an explicitly-
undefinedid, or non-objectparams) is dropped and surfaces only viaonerror(Unknown message type: …) — no response is sent. v1-era test fences that await a reply to a hand-written raw frame hang instead of resolving; send through the typed surface (client.ping(),client.request()) instead.
Experimental tasks interception removed
The 2025-11 task side-channel through Protocol is removed (was always @experimental).
No mechanical migration; remove usages. Gone: ProtocolOptions.tasks,
protocol.taskManager, RequestOptions.task / relatedTask, BaseContext.task,
assertTaskCapability / assertTaskHandlerCapability, *.experimental.tasks.*
accessors and Experimental{Client,Server,McpServer}Tasks, requestStream /
callToolStream / createMessageStream / elicitInputStream and the ResponseMessage
types they yielded, registerToolTask, ToolTaskHandler, TaskRequestHandler,
CreateTaskRequestHandler, TaskMessageQueue, InMemoryTaskMessageQueue,
BaseQueuedMessage / Queued*, CreateTaskServerContext, TaskServerContext,
TaskToolExecution, TaskStore, InMemoryTaskStore, CreateTaskOptions, isTerminal,
and the new McpServer(info, { taskStore, taskMessageQueue }) constructor option keys
(the codemod emits an action-required diagnostic at each — remove the option).
The task wire types remain importable as @deprecated vocabulary for 2025-11-25
interop — see support-2026-07-28.md.
Specification clarifications adopted (no SDK behavior change)
The 2026-07-28 specification revision includes a number of documentation-only
clarifications recorded here so an audit of the revision's changelog against this guide
is complete; nothing in this list requires code changes: per-operation timeout guidance
removal (RequestOptions.timeout / DEFAULT_REQUEST_TIMEOUT_MSEC unchanged); stdio
shutdown wording; transports-as-bindings reframe; resources/read wording (the
file:// path-sanitization MUST is server-author guidance — your handler must reject
traversal / symlink escapes itself); PromptMessage resource links (already in
ContentBlock); completion ref/resource URI templates; pagination empty-string
cursors (already passed through verbatim); sampling host-requirement docs; elicitation
statefulness wording; cosmetic schema/JSDoc sweeps.