-
#2286 1823aae Thanks @felixweinberger! - Split the wire layer into per-era codecs and make protocol-revision deletions physical. Deliberate wire/schema behavior changes (see docs/migration/support-2026-07-28.md "Per-era wire codecs"):
resultType is no longer modeled by any neutral wire schema: EmptyResultSchema (strict) now rejects {resultType} bodies; on 2025-era connections a foreign resultType is stripped before validation instead of rejected; the member exists only inside the 2026-era codec, which requires it.CallToolResult.content / ToolResultContent.content are required at the wire boundary (content.default([]) removed): handler results without content are rejected with -32602 instead of silently defaulted, and content-less wire results fail the client parse loudly.- Custom (3-arg) handlers now receive
_meta minus the reserved envelope keys instead of having it deleted before params validation.
specTypeSchemas re-scoped to the neutral model: result validators no longer accept resultType; task message-type validators and RequestMetaEnvelope left the public set (SpecTypeName narrowed).- Role aggregate types/schemas (
ClientRequest, ServerResult, …) no longer carry task vocabulary; the deprecated Task* types remain importable unchanged.
- Era-mismatched spec methods fail physically: inbound era-deleted methods get
-32601 even with a handler registered; outbound sends throw SdkErrorCode.MethodNotSupportedByProtocolVersion locally.
- Value guards (
isCallToolResult, …) are documented as neutral-shape consumer checks, not wire validators.
-
#2286 1823aae Thanks @felixweinberger! - createMcpHandler now returns a web-standards-only { fetch, close, notify, bus } handler — the shape Workers/Bun/Deno expect from export default. The duck-typed .node(req, res, parsedBody?) face is removed; Node frameworks (Express, Fastify, plain node:http) wrap the
handler once with the new toNodeHandler(handler, { onerror? }) exported from @modelcontextprotocol/node, which converts the Node request to a web-standard Request, calls handler.fetch, and writes the Response back honoring write backpressure. The optional onerror
receives the adapter-level error fallback (request conversion / handler.fetch throw) before the 500 response is written, restoring observability parity with the removed .node face. NodeIncomingMessageLike and NodeServerResponseLike move from
@modelcontextprotocol/server to @modelcontextprotocol/node.
-
#2286 1823aae Thanks @felixweinberger! - Hide wire-only protocol members from the public surface, at the type level and at runtime. resultType (the 2026-07-28 result discrimination field) is no longer declared on any public result type — the wire schemas keep parsing it, and the client funnel now consumes it raw-first: 'complete' results are stripped to the public shape and any other kind (e.g. input_required) rejects with the new SdkErrorCode.UnsupportedResultType instead of masking into an empty success. The reserved _meta envelope keys are lifted out of inbound requests and notifications before handlers run, and the multi-round-trip retry fields (inputResponses, requestState) out of inbound requests only (the spec reserves those names on client-initiated requests; notification params keep them), so handler params keep the 2025-era shape; for requests the lifted material surfaces at ctx.mcpReq.envelope, ctx.mcpReq.inputResponses, and ctx.mcpReq.requestState (notifications have no ctx — their lifted envelope keys are not surfaced). High-level client/server methods now return the named public result types (Promise<CallToolResult> etc.). Task wire vocabulary stays importable but is @deprecated and excluded from the typed method maps (RequestMethod/RequestTypeMap/ResultTypeMap/NotificationTypeMap), and callTool is typed as plain CallToolResult. See docs/migration/support-2026-07-28.md "Wire-only members hidden from public types".
-
#2286 1823aae Thanks @felixweinberger! - resources/read for an unknown URI now answers with JSON-RPC error code -32602
(Invalid Params) on every protocol revision, with error.data.uri echoing the
requested URI. The 2026-07-28 specification requires -32602; the v1.x SDK already
emitted -32602 on earlier revisions, so v1.x peers see no change.
This supersedes an interim -32002 emission that shipped in earlier v2 alphas. The
era-aware encode seam (WireCodec.encodeErrorCode) maps any handler-thrown -32002
to -32602 on the wire; note that a -32002 thrown without data.uri is emitted as
a bare -32602 and is no longer recognizable as resource-not-found — throw
ResourceNotFoundError (or include data: { uri }) to preserve the classification.
ProtocolErrorCode.ResourceNotFound (-32002) remains importable as receive-tolerated
vocabulary; clients should accept both -32602 and -32002 from peers (the
specification's backwards-compatibility clause). The new typed ResourceNotFoundError
class carries data.uri, and ProtocolError.fromError reconstructs it from a -32602
only when error.data is exactly { uri: string } (and nothing else), and from a
legacy -32002 whenever data.uri is a string; a bare -32002 without data.uri
stays a generic ProtocolError.
-
#2286 1823aae Thanks @felixweinberger! - SEP-1613 / SEP-2106 (JSON Schema 2020-12 posture): the Node default JSON Schema validator is now Ajv2020 (true draft 2020-12) instead of the draft-07 Ajv class — $defs/prefixItems/unevaluatedProperties/dependentRequired are now enforced where they were previously silently ignored; to opt back, construct the draft-07 instance with the v1 defaults — const ajv = new Ajv({ strict: false, validateFormats: true, validateSchema: false, allErrors: true }); addFormats(ajv); — and pass new AjvJsonSchemaValidator(ajv). Schemas declaring a $schema other than 2020-12 are rejected with a clear error rather than mis-validating. outputSchema may now have a non-object root and CallToolResult.structuredContent is widened to unknown (a deliberate source-level break for typed consumers — see the migration guide for the narrowing pattern). Toward 2025-era clients McpServer wraps a non-object outputSchema (and the matching structuredContent) in a {result: …} envelope so the tool stays callable, with same-document $ref/$dynamicRef pointers rewritten to keep resolving — low-level Server users (those bypassing McpServer and registering a tools/call handler directly) get the same wrap by routing the result through the new Server.projectCallToolResult(result, advertisedOutputSchema). Independently, on every era (the SEP's MUST applies regardless of client version), McpServer auto-appends a TextContent JSON serialisation when a handler returns non-object structuredContent without its own text block. The structuredContent presence check is !== undefined (not falsy) on both sides. Thanks @mattzcarey (#2249).
-
#2286 1823aae Thanks @felixweinberger! - Add createRequestStateCodec({ key, ttlSeconds?, bind? }), an opt-in HMAC-SHA256 sealing helper for the multi-round-trip requestState: mint seals a JSON-serializable payload (with TTL and optional context binding) and verify drops directly into ServerOptions.requestState.verify. WebCrypto-based and runtime-neutral; verification is fail-closed and constant-time. The ServerOptions.requestState.verify hook's return type is widened to unknown | Promise<unknown> so the codec's verify is directly assignable; the seam captures the hook's resolved value (the decoded payload) and hands it to handlers via the typed ctx.mcpReq.requestState<T>() accessor.
-
#2286 1823aae Thanks @felixweinberger! - Results of the cacheable 2026-07-28 operations (tools/list, prompts/list, resources/list, resources/templates/list, resources/read, server/discover) now always carry the revision's required ttlMs/cacheScope fields when served on that revision, defaulting to ttlMs: 0 / cacheScope: 'private'. Servers can configure the emitted values with the new ServerOptions.cacheHints option (per operation) and the new cacheHint member of the registerResource config (per resource); resolution is per field, most specific author first: cache fields returned by a handler win over the per-resource hint, which wins over the per-operation hint, and configured hints are validated at construction/registration time (RangeError on invalid values). Responses on 2025-era connections are unchanged and never carry these fields. Note for untyped callers: registerResource now interprets a cacheHint key in its config object — it is validated and kept out of the resource's list metadata, where it was previously passed through as ordinary metadata.
-
#2286 1823aae Thanks @felixweinberger! - Add SdkErrorCode.MethodNotSupportedByProtocolVersion: a typed local error raised before anything reaches the transport when a spec method is sent toward a peer whose negotiated protocol version's wire era does not define it (for example tasks/get toward a 2026-07-28 peer). The protocol layer now resolves a per-era wire codec from the connection's negotiated protocol version (instance state on Client/Server, with the legacy era as the pre-negotiation default) and resolves per-method schemas at dispatch time instead of registration time; an edge classification on an inbound message is validated against that instance era, and a mismatch is rejected as an entry/routing error. Behavior on existing (2025-era) connections is unchanged.
-
#2286 1823aae Thanks @felixweinberger! - Revise createMcpHandler's legacy handling (a behavior change to the unreleased entry). The entry now serves 2025-era (non-envelope) traffic by default through per-request stateless serving from the same factory — legacy: 'stateless' is the default rather than an
opt-in — and the strict, modern-only posture is selected with the new legacy: 'reject' value (the earlier alpha's default). The handler-valued legacy option (bring-your-own legacy serving) is removed: existing legacy deployments (for example a sessionful streamable
HTTP wiring) keep serving 2025 traffic by routing in user land with the new isLegacyRequest(request, parsedBody?) export, which runs the entry's own classification step — it returns true only for requests with no per-request _meta envelope claim, while malformed or
incomplete modern claims are NOT legacy and must be routed to the modern handler, which answers them with the documented validation errors. The predicate classifies a clone, so the routed request body stays readable. legacyStatelessFallback remains exported as a
standalone fetch-shaped handler with the same stateless serving as the default.
-
#2286 1823aae Thanks @felixweinberger! - Add createMcpHandler(factory, { legacy?, onerror?, responseMode? }), an HTTP entry point that serves the 2026-07-28 draft revision per request: each envelope-carrying request is classified once, served on a fresh instance from the factory bound to the claimed revision,
and answered with a JSON body or a lazily-upgraded SSE stream. 2025-era serving is selected with the legacy option ('stateless' — the default — for per-request stateless serving via the existing streamable HTTP transport, 'reject' for a modern-only strict endpoint
that answers 2025-era requests with the unsupported-protocol-version error naming its supported revisions). The handler is a web-standard { fetch, close, notify, bus } object: fetch(request, { authInfo?, parsedBody? }) is the only request face (Node frameworks wrap it with
toNodeHandler(handler) from @modelcontextprotocol/node), and close() tears down in-flight modern exchanges. Also exported: legacyStatelessFallback (the same stateless legacy serving as a standalone fetch-shaped handler), the PerRequestHTTPServerTransport single-exchange transport and the
classifyInboundRequest classifier for hand-wired compositions, and the supporting types. responseMode: 'json' never streams and drops mid-call notifications (progress, logging and other related messages emitted before the result); listen-class subscription streams are
always served over SSE. The entry performs no Origin/Host validation (use the middleware packages) and no token verification — authInfo is pass-through and never derived from request headers.
-
#2381 f0bf785 Thanks @felixweinberger! - Serve input_required handlers on 2025-era connections: the legacy shim (on by default) converts each embedded request of an input_required return into a real server→client request (elicitation/create, sampling/createMessage, roots/list) over the live session — stamped with the originating request's id for stream association — and re-enters the handler with the collected inputResponses until a final result. Handlers are written once in the 2026 inputRequired(...) style and serve both eras; the previous loud -32603 failure remains available via ServerOptions.inputRequired.legacyShim: false. Knobs: inputRequired.maxRounds (default 8) and inputRequired.roundTimeoutMs (default 600 000 ms per leg; legs carry a progressToken so a client reporting progress mid-leg resets the leg timeout). Semantics mirror the modern client driver exactly: per-round replaced inputResponses, byte-exact requestState echo with the verify hook running every round, paced requestState-only rounds, and elicitation accepted content passed through UNVALIDATED (the handler validates via the schema-aware acceptedContent overload, exactly as on the 2026 era). URL-mode legs synthesize the elicitationId the 2025-11-25 wire requires. Failures surface per family (tools/call → isError tool result; prompts/get / resources/read → JSON-RPC error); stateless legacy HTTP degrades to a clean capability refusal; the shim emits no progress of its own (the originating progressToken is the handler's single must-increase stream — the shim never adds a second author to it).
ctx.mcpReq.requestState is now a typed accessor: ctx.mcpReq.requestState<T>() returns the payload the configured requestState.verify hook resolved with (e.g. createRequestStateCodec.verify — the hook's return value is now load-bearing; verifiers that are not also decoders should resolve undefined), the raw wire string when no hook is configured, or undefined when the round carried no state. Code that read the property directly becomes a call: ctx.mcpReq.requestState → ctx.mcpReq.requestState<string>(). Note the member is now always present (a function), so truthiness no longer means "has state", and it is dropped by JSON serialization of the context.
New typed readers for inputResponses, exported from @modelcontextprotocol/server: a schema-aware acceptedContent(responses, key, schema) overload (validates untrusted accepted content against any synchronous Standard Schema) and inputResponse(responses, key) (discriminated missing | elicit | sampling | roots view, for decline/cancel detection and the non-elicitation kinds). Content conveniences like text extraction stay in application code as one-liners over the discriminated view.
-
#2286 1823aae Thanks @felixweinberger! - Add MissingRequiredClientCapabilityError, the typed error class for the 2026-07-28 -32021 protocol error (processing a request requires a capability the client did not declare). Its data.requiredCapabilities lists the missing capabilities and ProtocolError.fromError recognizes the code/data shape. The 2026-07-28 HTTP entry gains a pre-dispatch gate that refuses a request requiring an undeclared client capability with this error and HTTP status 400; no method served on the 2026-07-28 registry currently carries such a requirement, so observable behavior is unchanged until methods with capability requirements exist.
-
#2286 1823aae Thanks @felixweinberger! - Add the server side of multi round-trip requests (protocol revision 2026-07-28, SEP-2322). Handlers for tools/call, prompts/get, and resources/read can return the value built by inputRequired() (exported from the server package together with acceptedContent())
to request additional client input in-band; the structured-content requirement and the tools/call result-schema validation are skipped for that return, the encode seam emits it as resultType: 'input_required', and the handler reads the responses on re-entry from
ctx.mcpReq.inputResponses (with non-bare entries reported via ctx.mcpReq.droppedInputResponseKeys). The seam re-checks the at-least-one rule for hand-built results, checks every embedded request against the capabilities the client declared on that request's envelope
(answering the typed -32021 error on violation), and fails loudly — never emitting a mis-typed result — when an input-required value is returned from any other method. Toward a 2025-era request the return is served by the default-on legacy shim (real server→client requests plus handler re-entry); the loud failure for that case remains available via ServerOptions.inputRequired.legacyShim: false. A UrlElicitationRequiredError escaping a handler on a 2026-era request
fails as an internal error with a clear steer to inputRequired.elicitUrl(...), so the -32042 error never reaches the 2026-07-28 wire; 2025-era serving keeps today's -32042 behavior
exactly. The typed local error raised when push-style server-to-client request APIs are used while serving a 2026-era request now steers to inputRequired(...). Tool, prompt, and resource callback types accept the new return alongside their existing result types; 2025-era
wire behavior is unchanged. An optional ServerOptions.requestState.verify hook lets a server integrity-check the echoed requestState before the handler runs — a throw answers the wire-level -32602 Invalid Params error with data.reason: 'invalid_request_state'; the SDK provides no default verification.
-
#2286 1823aae Thanks @felixweinberger! - Add Origin header validation alongside the existing Host header validation. The server package gains framework-agnostic helpers (validateOriginHeader, localhostAllowedOrigins, originValidationResponse); the Express, Hono and Fastify adapters gain originValidation /
localhostOriginValidation middleware and a new allowedOrigins option on their app factories, which now arm Origin validation by default for localhost-class binds (mirroring the Host validation ladder; the 0.0.0.0-without-allowlist warning is unchanged). Requests
without an Origin header pass — non-browser MCP clients are unaffected — while a present Origin that is not allowed or cannot be parsed (including the opaque null origin) is rejected with 403. The Node adapter ships hostHeaderValidation / originValidation
request guards for plain node:http servers, which previously had no validation helpers.
-
#2286 1823aae Thanks @felixweinberger! - SEP-2243 Mcp-Param-* server-side validation (protocol revision 2026-07-28). On the modern (2026-07-28) serving path, createMcpHandler now validates Mcp-Param-{Name} headers against the named tool's x-mcp-header declarations and the body arguments before dispatch: a missing header for a present body value, a header that decodes to a different value than the body, or an invalid =?base64?…?= sentinel is rejected with 400 Bad Request and JSON-RPC -32020 (HeaderMismatch) — the same shape the existing standard-header cross-checks emit. A null/absent body value passes regardless of any header (the spec's "server MUST NOT expect the header" rows). McpServer.registerTool now warns at registration time when an x-mcp-header declaration violates the spec's constraints. The 2025-era serving paths and the low-level Server factory shape are unchanged.
-
#2286 1823aae Thanks @felixweinberger! - SEP-2243 standard-header server-side validation (protocol revision 2026-07-28). On the modern (2026-07-28) serving path, createMcpHandler now enforces the required Mcp-Method and Mcp-Name standard request headers in addition to the existing MCP-Protocol-Version and Mcp-Method cross-checks: a modern request without an Mcp-Method header, a tools/call / prompts/get / resources/read request without an Mcp-Name header, an Mcp-Name header carrying an invalid =?base64?…?= sentinel, and an Mcp-Name header whose (decoded) value disagrees with the body's params.name / params.uri are all rejected with 400 Bad Request and JSON-RPC -32020 (HeaderMismatch). The 2025-era serving paths are unchanged.
New public surface:
@modelcontextprotocol/server: the mcpNameHeader field on InboundHttpRequest, and the 'standard-header-validation' member of InboundValidationRung (with client-capabilities / param-header-validation renumbered).
-
#2286 1823aae Thanks @felixweinberger! - Add serveStdio(factory, options?) (exported from @modelcontextprotocol/server/stdio), the connection-pinned stdio entry point for serving the 2026-07-28 draft revision on long-lived connections. The entry owns the transport and the era decision: the client's opening
exchange selects the era (a 2025 initialize handshake, 2026-07-28 per-request _meta envelope traffic, or a server/discover probe followed by either), and ONE instance from the factory is pinned to the connection and serves only that era — mirroring how
createMcpHandler classifies each HTTP request before constructing an instance. 2025-era openings are served by default; legacy: 'reject' answers them with the unsupported-protocol-version error naming the supported modern revisions instead. A transport option
accepts a bring-your-own StdioServerTransport (for example over a Unix domain socket); onerror reports out-of-band errors; the returned handle's close() tears the connection down.
Removed: ServerOptions.eraSupport (introduced in an earlier 2.0 alpha, never in a stable release). A hand-constructed Server/McpServer serves only the 2025-era protocol it was written for; serving the 2026-07-28 revision always goes through a serving entry. Migrate
new McpServer(info, { eraSupport: 'dual-era' }) + connect(new StdioServerTransport()) to serveStdio(() => new McpServer(info)), and eraSupport: 'modern' to serveStdio(factory, { legacy: 'reject' }).
-
#2286 1823aae Thanks @felixweinberger! - Align the 2026-07-28 protocol error codes to the spec renumber: HeaderMismatch is now -32020 (was -32001), MissingRequiredClientCapability is now -32021 (was -32003), and UnsupportedProtocolVersion is now -32022 (was -32004). These codes are part of the draft 2026-07-28 protocol revision only and have never appeared on a 2025-era wire — the 2025 serving paths and the SDK-conventional -32001 (Session not found) on the stateful Streamable HTTP transport are unchanged. ProtocolErrorCode.MissingRequiredClientCapability, ProtocolErrorCode.UnsupportedProtocolVersion, the HEADER_MISMATCH_ERROR_CODE constant, and the HEADER_MISMATCH / MISSING_REQUIRED_CLIENT_CAPABILITY / UNSUPPORTED_PROTOCOL_VERSION spec-type constants now carry the renumbered values; the UnsupportedProtocolVersionError and MissingRequiredClientCapabilityError classes (and ProtocolError.fromError recognition) follow. The client probe classifier recognizes -32022 for the corrective continuation and the SEP-2243 one-refresh-on-miss retry triggers on -32020.
-
#2286 1823aae Thanks @felixweinberger! - subscriptions/listen graceful close: per spec PR #2953, a server-side graceful close (createMcpHandler / serveStdio close()) now emits the empty subscriptions/listen JSON-RPC result (the new SubscriptionsListenResult — _meta carries the subscriptionId) before closing the stream, replacing the previous server-originated notifications/cancelled. On the client, McpSubscription.closed now resolves 'graceful' for this signal (added alongside 'local' and 'remote'); a stream close without a result remains 'remote' (unexpected disconnect).
-
#2286 1823aae Thanks @felixweinberger! - subscriptions/listen (SEP-1865) is served by both serving entries on protocol revision 2026-07-28. The entry owns ack-first, per-stream filtering, subscription-id stamping, keepalive (HTTP), the pre-ack -32603 capacity guard, and teardown (HTTP stream close; one
notifications/cancelled per subscription on stdio). server/discover now advertises listChanged/subscribe capability bits — the rider that suppressed them until listen was served is discharged.
Under createMcpHandler the consumer's factory is constructed for subscriptions/listen (a capabilities-only probe so the acknowledged filter reflects what the server advertises; the instance is never connected and is closed immediately). Per-request authorization performed inside the factory therefore sees listen requests; token verification still belongs at the middleware layer mounted in front of the entry.
New public surface:
@modelcontextprotocol/server: ServerEventBus, ServerEvent, ServerNotifier (types); InMemoryServerEventBus (class).McpHttpHandler gains .notify (ServerNotifier: toolsChanged(), promptsChanged(), resourcesChanged(), resourceUpdated(uri)) and .bus (the ServerEventBus listen streams subscribe to).CreateMcpHandlerOptions gains bus?: ServerEventBus (an in-process InMemoryServerEventBus is created when omitted), maxSubscriptions?: number (default 1024), and keepAliveMs?: number (default 15000).ServeStdioOptions gains maxSubscriptions?: number (default 1024). On a modern-pinned connection serveStdio routes the pinned instance's existing send*ListChanged() calls onto active subscriptions; legacy connections are unchanged.@modelcontextprotocol/server: SUBSCRIPTION_ID_META_KEY (const); SubscriptionFilter, SubscriptionsListenRequest, SubscriptionsListenRequestParams, SubscriptionsAcknowledgedNotification, SubscriptionsAcknowledgedNotificationParams (types).
-
#2286 1823aae Thanks @felixweinberger! - Wire server/discover (protocol revision 2026-07-28) into the typed request funnel and serve it era-aware. The request joins ClientRequestSchema/ServerResultSchema/ResultTypeMap (per-era availability stays with the wire registries: only the 2026-era registry serves
it), and Client.discover() issues it as a typed request on 2026-era connections. A Server whose supportedProtocolVersions list carries a modern (2026-07-28+) revision installs the server/discover handler, advertising ONLY its modern revisions and excluding the
listChanged/subscribe-class capabilities until the subscriptions/listen flow ships; servers with today's default list are unchanged and keep answering -32601. The initialize handshake is now era-aware in the other direction: its accept check and counter-offer consult
only the legacy subset of the supported versions — a 2026-era revision is never negotiated via initialize — so a 2025-era client can never be offered a 2026 version string; with the default list this is byte-identical to previous behavior. Serving the 2026 revision to
ordinary HTTP/stdio traffic arrives with an upcoming server-side entry point: today the negotiation surface is client-side, and mode: 'auto' falls back cleanly against current SDK servers.
-
#2286 1823aae Thanks @felixweinberger! - Deprecate Server.getClientCapabilities(), Server.getClientVersion() and Server.getNegotiatedProtocolVersion() in favor of the per-request handler context: on 2026-07-28 requests the validated _meta envelope carries the client's identity (ctx.mcpReq.envelope),
and instances serving that revision through createMcpHandler are backfilled per request so the accessors keep answering. Behavior on 2025-era connections is unchanged; the accessors remain functional.
-
#2394 801111e Thanks @felixweinberger! - Fix the published declaration files for consumers compiling with skipLibCheck: false: the bundled .d.mts no longer leaves a dangling URIComponent reference (ajv's published types import it from fast-uri, whose export-assigned namespace the dts bundler cannot link — the type is now inlined via a dts-only path mapping), and no longer imports json-schema-typed from an undeclared dependency (it is inlined via dts.resolve). @modelcontextprotocol/node and @modelcontextprotocol/server drop stale typesVersions entries pointing at subpaths that never shipped. Package READMEs note that TypeScript >=6.0 requires "types": ["node"] since the published declarations reference Buffer.
-
#2390 6cc7b1c Thanks @felixweinberger! - isLegacyRequest docs: lead with the single-argument form. isLegacyRequest(request) is the whole API — the body is read from an internal clone, so the request you pass stays readable for whichever handler you route it to. parsedBody is an optional perf escape for a body you already hold parsed (and the way in for an already-consumed stream, e.g. behind express.json()), not a required companion. Documentation only; no behavior change.
-
#2286 1823aae Thanks @felixweinberger! - Pin the modern (2026-07-28) HTTP serving path's rejection codes to the assignments the published conformance suite asserts: a header/body cross-check mismatch (MCP-Protocol-Version or Mcp-Method disagreeing with the request body) is now rejected with -32020 (HeaderMismatch), and a request whose protocol-version header names a modern revision but whose body is missing the _meta envelope (or its required protocol-version key) is rejected with -32602 invalid params naming the missing key(s). Both keep HTTP 400. These cells previously emitted a provisional -32004 while the upstream error-code discussion was open. The envelope-less rejection on a modern-only endpoint (-32022 with the supported-versions list), the 2025-era serving paths, and the client-side probe handling are unchanged.
-
#2286 1823aae Thanks @felixweinberger! - ctx.mcpReq.log() now emits its notifications/message notification request-related (like progress and ctx.mcpReq.notify), so handler-emitted log messages are delivered when the server is hosted per request via createMcpHandler instead of being silently dropped. On a 2026-07-28 request the level filter consults the per-request _meta io.modelcontextprotocol/logLevel key (the modern equivalent of logging/setLevel); per the spec, an absent key means no notifications/message is sent for that request.
2025-era delivery-channel change (spec-conformance correction). On a 2025-era sessionful Streamable HTTP transport, handler-emitted log messages now ride the per-request POST response stream instead of the standalone GET stream. This is a correction to the 2025-11-25 specification: docs/specification/2025-11-25/basic/transports.mdx §"Sending Messages to the Server" item 6 says JSON-RPC messages on the POST response stream SHOULD relate to the originating client request, and §"Listening for Messages from the Server" item 4 says messages on the GET stream SHOULD be unrelated to any concurrently-running client request — so a log emitted from a handler context belongs on the POST stream. Clients reading handler logs off the standalone GET stream will now see them on the per-request POST stream instead. The eventStore-resumable case (a log emitted after closeSSE() while the client has not yet reconnected) is handled by the store-first persistence behavior in WebStandardStreamableHTTPServerTransport.send(). The session-scoped Server.sendLoggingMessage() API is unchanged.
-
#2286 1823aae Thanks @felixweinberger! - WebStandardStreamableHTTPServerTransport: request-related events (progress, ctx.mcpReq.notify, handler-emitted log) and the final response are now persisted to the configured eventStore whenever the request is in flight, regardless of whether a live SSE writer currently exists — mirroring the standalone-SSE path's store-first semantics. This fixes the closeSSE() poll-and-replay drop (events emitted after closeSSE() were previously silently lost) and aligns with the 2025-11-25 specification ("disconnection SHOULD NOT be interpreted as the client cancelling its request"). When an eventStore is configured, a final response sent while no per-request stream is connected is stored for replay and returns cleanly instead of throwing "No connection established"; a Last-Event-ID reconnect after the request has been retired replays the stored response and then closes the resumed stream. When no eventStore is configured, the same condition is surfaced via onerror (the response is undeliverable) and the request id is retired.
-
#2286 1823aae Thanks @felixweinberger! - Re-pin the 2026-07-28 draft references (spec reference types, vendored schema.json twins, example corpus) to the latest spec commit and align the 2026-era wire surface with it. Deliberate 2026-era wire behavior changes (the released 2025-11-25 surface is untouched):
-
notifications/elicitation/complete is no longer part of the 2026-07-28 wire registry (the draft removed the notification together with elicitationId on URL-mode elicitation). On connections negotiated at 2026-07-28, sending it — including via Server.createElicitationCompletionNotifier() — now fails locally with SdkErrorCode.MethodNotSupportedByProtocolVersion, and inbound copies are dropped as unknown notifications. Both remain fully supported on 2025-11-25.
-
notifications/cancelled on 2026-era connections now parses with a revision-exact schema that requires requestId (the draft made it required); the notification _meta shape types the io.modelcontextprotocol/subscriptionId key. 2025-era parsing is unchanged.
-
The error code -32001 emitted for HTTP header/body mismatches is now defined by the draft schema (HEADER_MISMATCH); the emitted behavior is unchanged (documentation only).
No public API surface changes; the regenerated reference artifacts are internal/test-only.
-
#2286 1823aae Thanks @felixweinberger! - Internal: regenerate the 2026-07-28 spec reference types from the latest draft schema (DiscoverResult now extends CacheableResult; ElicitationCompleteNotificationParams extracted as a named interface) and document the anchor lifecycle policy. Released-revision spec-type generation is now pinned to a fixed spec commit; draft anchors keep floating via the nightly refresh PRs. No public API or runtime behavior changes.
-
#2286 1823aae Thanks @felixweinberger! - Freeze the per-era wire schemas as self-contained copies decoupled from the public types layer, and convert WireCodec to a function-only interface. Two small spec-conformance fixes ride along with the otherwise-pure refactor:
- The 2026 wire-true
resultType member now defaults to 'complete' when absent (the spec's receiver-side back-compat rule); the inbound decodeResult step continues to require it. The server/discover result accepts absent or malformed ttlMs/cacheScope (falling back to 0/'private' per the spec's receiver leniency in caching.mdx) so the version-negotiation probe classifier stays behavior-neutral. Other cacheable result schemas are unchanged here; general receiver leniency for those belongs to the response-cache surface.
- The sampling
hasTools discriminant now keys on tools || toolChoice (previously tools only), aligning the client and server selection of the with-tools result variant with clientCapabilityRequirements.