Skip to content

MCP 2026-07-28 support ​

MCP revision 2026-07-28 changes how clients and servers talk: there is no initialize handshake and no protocol session, every request carries its own protocol version and capabilities in _meta, servers ask for more input by answering input_required instead of sending requests of their own, and broken streams are not resumed. Servers written for earlier revisions (2025-11-25 and before, called legacy below) keep working, and many servers will speak both for a long time.

L2M supports both eras, in both directions:

Nothing changes on the wire for a deployment that sets nothing: L2M opens servers with initialize as before, and the gateway answers 2026-07-28 clients the way it answers a request without a session, so clients that speak both fall back to a session. A few safety changes do apply by default; they are listed in Upgrading.

L2M as a client ​

Protocol modes ​

Each MCP server in the registry, and each server configured inline on a node, has a protocol mode. Set it under Protocol version → MCP protocol in the server's connection settings, or as "protocolMode" in its connection JSON. A server without one uses the deployment default, MCP_CLIENT_PROTOCOL_DEFAULT (legacy unless you change it). Any other value is refused when the server is saved, discovered or tested.

ModeIn the formHTTP serversstdio servers
legacy (default)Legacy (initialize handshake)Opens a session with initialize, exactly as before. If the server rejects initialize with a 2026-07-28 error (HTTP 400 with code -32020, -32021, or -32022 with its list of supported versions), L2M switches that server to 2026-07-28 and retries, so a server that only speaks 2026-07-28 is still reached.Same, on the same process: a server that rejects initialize with an error listing a 2026-07-28 version is reached in that era.
autoAuto (try 2026-07-28 first)Sends a 2026-07-28 server/discover request first. A result, a recognised 2026-07-28 error or a 404 with -32601 means 2026-07-28; a client error without one (such as a plain 400) means legacy, and L2M falls back to initialize. The answer is remembered per endpoint for an hour; an authentication error, a rate limit, a 407 or 408, a server error or another JSON-RPC error in a successful response decides nothing and is not remembered.Sends server/discover first. A result or a recognised error means 2026-07-28; any other error, no answer within the probe timeout, or the process exiting means legacy (initialize on the same process, or a new one). Remembered per command line for an hour.
modern2026-07-28 only2026-07-28 only. A legacy server fails with a message saying so.Same: a server that only speaks initialize fails with "does not speak MCP 2026-07-28 … Set its protocol to Legacy or Auto".

MCP_CLIENT_ERA_PROBE_TIMEOUT_MS (default 5000) is how long Auto waits for the server/discover answer, for both transports, and never longer than the server's own timeout. A server that is slow to start (for example one installed by npx on first use) may miss it and be remembered as legacy for the hour; it still works, over initialize.

When an assumption turns out wrong (a server remembered as 2026-07-28 now answers like a legacy one, or the other way round), the operation runs once more in the other era.

What 2026-07-28 sessions do ​

  • Per-request metadata. Every request carries io.modelcontextprotocol/protocolVersion, clientCapabilities and clientInfo in params._meta, merged with the progress token and trace context. Over HTTP it also sends the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers and the Mcp-Param-* headers a tool's schema asks for (x-mcp-header). No session id, no notifications/initialized, no ping.
  • Tools with invalid header annotations are left out of the tool list with a warning, as the specification requires. Tool snapshots show them as removed, so the drift review catches it.
  • More input. When a server answers tools/call, resources/read or prompts/get with input_required, L2M answers its questions with the same handlers as before (a person answers an elicitation, the sampling rules decide a model request) and sends the request again with the answers and the server's requestState exactly as received. Each round is a new request. A call fails after MCP_CLIENT_MRTR_MAX_ROUNDS rounds (default 5, 1 to 20). L2M declares no roots and no URL-mode elicitation, so it refuses those requests; it also refuses anything malformed, and the call then fails with a clear error. No upstream connection stays open while a person thinks. The requestState is never logged or recorded, only its hash and length.
  • Version and errors. On -32022 (unsupported version) L2M picks a version both sides support, once. -32021 (a missing client capability) fails the call as a tool error naming the capability. -32020 on a tool call (headers that do not match) makes L2M list the tools again and retry once. A resource that is not found (-32602 or -32002) gets a clear message.
  • Cancel. Over HTTP, closing the request is the cancel signal; L2M aborts it and sends no notifications/cancelled. Over stdio, notifications/cancelled is still sent.
  • Capabilities come from server/discover, when L2M first needs them.

Cassettes record and replay calls to servers of either era.

The safe re-send rule ​

When a connection breaks after a request was sent, the client cannot know whether the server acted on it. Sending a tool call again could then run it twice: a second payment, a second write. L2M sends a request again after a broken connection, a timeout or (for 2026-07-28 servers) an early end of the response stream only when that is safe; legacy servers' requests are never sent again after an early end of the stream:

  • any request other than a tool call (listing, reading a resource, getting a prompt, server/discover);
  • a tool call to a tool that is read-only or idempotent: marked so by an admin in tool policy, or, without a mark, annotated so by the server (readOnlyHint or idempotentHint). An admin's mark wins in both directions. A tool L2M has never seen listed counts as unsafe.

Other tool calls fail with the error kind outcome_unknown (or timeout after a timeout). The agent and the run trace see that kind, so a workflow can decide what to do, for example ask a person. A request that never reached the server (connection refused, DNS failure and the like) is always retried. Over HTTP, an unsafe call is retried only on 429 and 503 (the server did not act on it); 502 and 504 give outcome_unknown, and 500 is not retried. Over stdio, a broken connection means the process ended after the request was written to it.

2026-07-28 servers always follow this rule. For legacy servers it is on by default; MCP_CLIENT_LEGACY_SAFE_REISSUE=false restores the old behaviour of sending every request again.

An admin's read-only or write mark is looked up per server and cached for 5 seconds on each instance, so a change applies within a few seconds everywhere. Servers configured inline on a node have no registry entry and use annotations only.

OAuth ​

The OAuth flow for remote servers follows the 2026-07-28 authorization rules. These apply whatever protocol mode a server uses:

  • Discovery reads the server's 401 challenge from an unauthenticated initialize, then from a 2026-07-28 server/discover when initialize was not challenged, so OAuth works with servers that only speak 2026-07-28.
  • Issuer checks. Authorization server metadata is used only when its issuer is exactly the issuer it was fetched for, and the callback's iss parameter (RFC 9207) must match it.
  • Client ids are bound to the authorization server they were first used with; a change stops Connect until an admin enters a new id or resets the binding. Dynamic registration sends application_type. A client metadata document can be offered instead of dynamic registration (MCP_OAUTH_CLIENT_METADATA_ENABLED, off by default).
  • Step-up. A 403 with an insufficient_scope challenge fails the call at once, never retried and not counted against the server's health, with a message naming the scope. The connection shows the missing scope, and the next Connect asks for the scopes granted before plus the challenged ones (audited as mcp_server.oauth_scope_challenged). Step-up needs a person to press Connect; there is no automatic browser flow.
  • Private addresses. MCP_OAUTH_BLOCK_PRIVATE_HOSTS=true (off by default) refuses OAuth requests to private, loopback, link-local and cloud metadata addresses, with MCP_OAUTH_PRIVATE_HOST_ALLOWLIST for identity providers on a private network.

Client settings ​

VariableDefaultMeaning
MCP_CLIENT_PROTOCOL_DEFAULTlegacyProtocol mode of servers whose connection sets none: legacy, auto or modern.
MCP_CLIENT_ERA_PROBE_TIMEOUT_MS5000How long Auto waits for the server/discover answer (500 to 60000 ms; never more than the server's timeout).
MCP_CLIENT_MRTR_MAX_ROUNDS5Most input rounds one call may take (1 to 20).
MCP_CLIENT_LEGACY_SAFE_REISSUEtrueApply the safe re-send rule to legacy servers too. false sends every request again after a broken connection, as earlier releases did.

Per server, in the connection JSON: protocolMode (legacy, auto or modern) and propagateTraceContext (false stops trace context for that server; see OpenTelemetry).

The MCP gateway ​

The MCP gateway serves session-based clients exactly as before. With MCP_GATEWAY_MODERN_PROTOCOL=on it also serves 2026-07-28 clients on the same endpoint at the same time, without sessions.

How a request is routed ​

A request is a 2026-07-28 request when it is a single JSON-RPC message sent with MCP-Protocol-Version: 2026-07-28, or a single message other than initialize whose params._meta carries io.modelcontextprotocol/protocolVersion. Everything else (initialize, requests with Mcp-Session-Id and no 2026-07-28 metadata, batches, requests whose _meta holds only trace context) follows the session path unchanged.

With MCP_GATEWAY_MODERN_PROTOCOL=off (the default), a 2026-07-28 request gets the legacy answer (HTTP 400, -32000: an unsupported MCP-Protocol-Version, or a missing session when only _meta marks the request), which a client that speaks both eras reads as "legacy server": it falls back to initialize. A client that only speaks 2026-07-28 cannot connect while the setting is off.

What modern mode serves ​

Protocol versions2026-07-28 per request, next to 2025-11-25, 2025-06-18 and 2025-03-26 after initialize.
Methodsserver/discover, tools/list, tools/call, subscriptions/listen. Any other method gets HTTP 404 with -32601, including initialize sent with a 2026-07-28 version header.
ValidationChecked in this order, each answered with HTTP 400 and the request's id: the protocol version missing from _meta (-32602); an MCP-Protocol-Version header that differs from it (-32020); an unsupported version (-32022, listing the versions the gateway speaks); the MCP-Protocol-Version, Mcp-Method and (for tools/call) Mcp-Name headers missing or not matching the body (-32020); client capabilities missing from _meta (-32602).
SessionsNone. An Mcp-Session-Id header is ignored and never echoed. Calls run with a per-caller state keyed by the client token, the toolset and the user the token acts for.
server/discoversupportedVersions (2026-07-28 first, then the legacy versions), capabilities: { tools: { listChanged: true } }, the toolset description as instructions, and the gateway's serverInfo.
ResultsresultType: "complete" and the gateway's serverInfo in _meta. tools/list and server/discover carry ttlMs (MCP_GATEWAY_LIST_TTL_MS, default 60000) and cacheScope: "private", since lists depend on the caller's role and policy. tools/list is sorted by tool name.
Responsesapplication/json, or a server-sent event stream (with X-Accel-Buffering: no) when the request carries _meta.progressToken and accepts text/event-stream.
CancelClosing the connection before the answer is complete cancels the call: a workflow tool's run ends as canceled, and an upstream call is stopped. Notifications are accepted (202) and ignored.
Tool schemasx-mcp-header annotations are removed from the input schemas the gateway shows: callers never need Mcp-Param-* headers.
Error codesThe gateway's own codes move out of the range 2026-07-28 reserves: retry later -32029 becomes -31029, approval pending -32030 becomes -31030, approval rejected -32031 becomes -31031, budget exceeded -32032 becomes -31032, with the same message and data. Session-based clients keep the old codes. Errors returned before the body is read (a bad token, an unknown toolset) keep their legacy codes in both eras.
CORSBrowsers may also send Mcp-Method, Mcp-Name and up to 32 Mcp-Param-* headers.

Everything else is the same for both eras: tool policy, approvals by retry, content rules, budgets and rate limits, data labels, telemetry and audit. A caller's first 2026-07-28 request in an idle window is audited as mcp_gateway.caller_seen (the counterpart of mcp_gateway.session_started). Per-caller states and sessions share the MCP_GATEWAY_MAX_SESSIONS cap; past it, idle sessions are closed first, then idle callers that carry no outside-content labels, then other idle callers.

subscriptions/listen ​

A 2026-07-28 client can open a subscriptions/listen stream (it needs Accept: text/event-stream, otherwise 406). The gateway acknowledges it with notifications/subscriptions/acknowledged, echoing toolsListChanged: true when the client asked for it (the only type it honours: prompts and resources are not served). The stream then gets notifications/tools/list_changed, with the subscription id in _meta, whenever the list that client's tools/list returns changes (what counts is listed under tool list changes), and keep-alive comments until the client closes the stream, MCP_GATEWAY_LISTEN_MAX_MS passes (default 600000) or the server shuts down; the last two end with a complete result, and clients reconnect. A malformed filter gets 400 (-32602). Each client may hold MCP_GATEWAY_LISTEN_MAX_PER_CLIENT streams (default 4) per instance; one more gets HTTP 429 (-31029). Streams do not count against the client's rate or concurrency limits. A stream whose client is revoked or no longer scoped to the toolset, or whose toolset is disabled or deleted, ends with a complete result at its next check.

Changes made on any instance reach streams on every instance over the cluster bus (a ctl message mcp_tools_changed, which carries nothing else); each instance re-reads the tool lists of its own streams and notifies only those whose list changed. A stream's list is also re-checked every MCP_GATEWAY_LISTEN_CHECK_MS (default 30000), which catches changes nothing announces (rules written by background jobs, rules whose conditions depend on time) and lost messages. No upstream server is contacted for a check.

Labels and clusters ​

On a toolset that tracks outside content per session, a 2026-07-28 caller's labels are stored in the database (migration v71) per client token, toolset and user, so every instance checks its calls with the same labels and the caller cannot clear them. A label read that fails refuses the call; a write that fails withholds the result. A session the same client token opens with initialize on a tracking toolset starts from these stored labels and reads them again before every tool call (if they cannot be read, initialize gets HTTP 503 and no session is opened, and a call is refused). Those reads do not renew the stored labels. What the session's own results raise is written into them, as a call without a session writes its results, and that renews them; so the client's later calls without a session start from what the session gathered. These callers need no sticky sessions in a cluster. The Sessions panel of a client lists them as Stateless caller (2026-07-28). See Cluster operations.

Gateway settings ​

VariableDefaultMeaning
MCP_GATEWAY_MODERN_PROTOCOLoffon serves 2026-07-28 clients without sessions, next to session-based ones.
MCP_GATEWAY_LIST_TTL_MS60000ttlMs on tools/list and server/discover results: how long callers may cache them (0 to 86400000; 0 means always fetch again).
MCP_GATEWAY_LISTEN_MAX_MS600000A subscriptions/listen stream ends gracefully after this long (1000 to 86400000).
MCP_GATEWAY_LISTEN_MAX_PER_CLIENT4Open listen streams per client on one instance (1 to 1000).
MCP_GATEWAY_LISTEN_CHECK_MS30000How often a stream that asked for toolsListChanged has its tool list re-checked, besides the change messages; 0 turns the periodic check off.

MCP_GATEWAY_SESSION_IDLE_MS and MCP_GATEWAY_MAX_SESSIONS apply to 2026-07-28 callers too (see Configuration). The listen and list settings matter only with modern mode on.

Conformance ​

The official MCP conformance suite (@modelcontextprotocol/conformance 0.2.0-alpha.12) runs against L2M in CI, in both directions and for both revisions: the "MCP conformance" job, or node apps/api/conformance/run.mjs locally (about a minute). Each run has a baseline file in apps/api/conformance/baselines/ listing the scenarios expected to fail, each with its reason. A run fails on a new failure and on a listed scenario that starts passing, so the lists only shrink.

Results on the current release (checks passed / failed, as the suite totals them). The totals include scenarios the suite's requirement set does not score yet: the tasks extension, DPoP, client credentials, enterprise-managed authorization and checks added after the release. L2M implements none of those, and they account for many of the failures, as the notes say.

RunPassedFailedNotes
Gateway, modern on, 2026-07-289871tools/list, header validation, SSE streams and several input-request checks pass; the stateless scenario (discovery, subscriptions/listen, error codes) fails only on fixture tools. Unscored scenarios (tasks, JSON Schema 2020-12, custom headers) account for 14 passed and 36 failed; the other failures are methods the gateway does not serve and fixture tools (below).
Gateway, modern on, 2025-11-253927initialize, ping, tools/list, the session lifecycle and SSE streams pass.
Gateway, modern off, 2025-11-253927Same as above: modern mode changes nothing for session-based clients.
Gateway, modern off, 2026-07-2811146Refused by design while modern mode is off (unscored tasks scenarios included).
Client, 2026-07-2844716Includes OAuth scope step-up. 15 failures are unscored authorization scenarios; the one baselined failure is authorization server migration.
Client, 2025-11-253022215 failures are the same unscored authorization scenarios.
Client, OAuth suite2300One warning: no client metadata document by default.
Client, 2025-03-26 OAuth back-compat07Not supported on purpose (below).

Known gaps ​

Gateway:

  • Tools only. The gateway serves tools; resources/*, prompts/*, completion/complete and logging/setLevel get -32601. Caching hints are therefore checked on tools/list only.
  • Tool list changes only. subscriptions/listen honours toolsListChanged only. The conformance check for it needs the reference server's test_trigger_tool_change tool, which no toolset serves, so it warns.
  • No input requests to callers. The gateway never asks its callers for input (input_required): an upstream server's elicitation or sampling request during a gateway call is declined. The input-request scenarios also need a fixture tool the gateway does not have.
  • Tool names. Scenarios that call the reference server's fixture tools by bare name fail, because gateway tools are named <server>__<tool>. This is a property of the test setup.
  • Origins. The gateway refuses a browser Origin that is not in its allow list, including localhost, while the suite expects unauthenticated local servers to accept it. The gateway always needs a client token.
  • Tasks. The tasks extension is not implemented; the gateway declares no extensions, so no client receives a task.

Client:

  • Standalone GET stream (legacy servers). L2M does not open the optional GET stream of a legacy HTTP session, so a request a server sends there, outside any call, is not answered. 2026-07-28 removed that stream.
  • No SSE resume (legacy servers). A broken stream is not resumed with Last-Event-ID; the safe re-send rule decides what happens. 2026-07-28 removed resumption.
  • No 2025-03-26 OAuth fallback. Servers without protected resource metadata, where the MCP server doubles as the authorization server, are not supported: that shape conflicts with the issuer checks above.
  • Client metadata documents are opt-in, so the suite warns that L2M registers dynamically by default.
  • Authorization server migration. The conformance harness registers once per run; in L2M, a changed authorization server stops Connect until an admin checks the client id.
  • Observed protocol. The server page does not show which era a server answered with yet; set the mode explicitly when you need to know.
  • Not declared: roots, URL-mode elicitation and the tasks extension. Sampling, which 2026-07-28 deprecates, keeps working under its rules.

Upgrading ​

What changes without any setting ​

These apply to every deployment once it runs this release:

  • Safe re-send rule. A tool call without a read-only or idempotent mark or hint is no longer sent again after a broken connection or a timeout, for legacy servers too. It fails as outcome_unknown (after a timeout, as timeout, after one attempt). Over HTTP such a call is retried on 429 and 503 only; 502 and 504 now give outcome_unknown, and 500 is not retried. For stdio, a call is no longer re-run on a new process after the old one died mid-call. To keep the old behaviour, set MCP_CLIENT_LEGACY_SAFE_REISSUE=false; better, mark read-only tools in tool policy so they keep being retried safely.
  • Scope challenges. A 403 insufficient_scope answer is a credentials error, never retried (it used to be retried once on a fresh session).
  • OAuth. Inconsistent authorization server metadata, a wrong or missing iss, or a client id used with a new authorization server now stop Connect with a message saying why. Discovery may send one extra server/discover request. OAuth URLs on names such as 127.example.com need https.
  • Validation. A protocolMode other than legacy, auto or modern in a server's connection JSON is refused when it is saved.
  • stdio exits. When a server process exits, requests still in flight fail once its output is read (at most 200 ms later).

Wire traffic to existing servers is otherwise unchanged: initialize, the session and version headers, _meta and server-request answers are the same, and the gateway's answers to existing clients do not change while MCP_GATEWAY_MODERN_PROTOCOL is off.

Adopting 2026-07-28 ​

  1. Mark read-only tools in tool policy, so the safe re-send rule can retry them after a network problem.
  2. Clients. Leave the default legacy: it reaches 2026-07-28-only servers already. Set Auto on servers you know speak 2026-07-28 to skip the handshake, or MCP_CLIENT_PROTOCOL_DEFAULT=auto for all of them. Use 2026-07-28 only for servers that must not fall back.
  3. Gateway. Set MCP_GATEWAY_MODERN_PROTOCOL=on. Make sure your reverse proxy passes the MCP-Protocol-Version, Mcp-Method, Mcp-Name and Mcp-Param-* headers and does not buffer event streams. In a cluster, run migration v71 (it runs at start-up) and keep the sticky-session rules only for session-based clients.
  4. Observe. With OpenTelemetry on, MCP spans carry mcp.protocol.version, and gateway spans show which era each caller used.

To go back, set the variables to their defaults. Nothing is stored that an older setting cannot read: the protocol mode lives in the server's connection JSON, and the v71 label table is only read while modern mode is on.

Further reading ​

This website (not the L2M product) uses Google Analytics, only after you accept cookies. Cookie settings