MCP 2026-07-28 Support in AISIX AI Gateway

On July 28, the MCP project released the 2026-07-28 revision and removed the initialize handshake and the protocol-level session. It is the largest change the protocol has had.

Three weeks later, support is merged across AISIX AI Gateway: the open-source gateway, AISIX Cloud, and the docs. This post covers what the revision actually changes and what AISIX handles for you.

What the Revision Changes

The earlier Streamable HTTP revisions were stateful. A client opened with initialize, the server minted an Mcp-Session-Id, and every later request had to reach the server that remembered that session. Scaling an MCP server meant sticky sessions or shared session storage.

The 2026-07-28 revision drops all of that. No handshake, no session; each request carries its own protocol metadata, and the new server/discover method answers capability questions on demand rather than as a prerequisite. In operational terms, MCP traffic goes back to being plain stateless HTTP — the kind of traffic load balancers, autoscalers, and serverless platforms already know how to handle.

The catch: it's a breaking change, and clients and servers won't upgrade on the same day. Somebody has to sit in the middle during the transition.

One Endpoint, Both Generations

AISIX's MCP endpoint now speaks both generations and negotiates with each client on its own:

MCP revision	Support
`2026-07-28`	Served, handshake-free startup via `server/discover`
`2025-11-25`, `2025-06-18`, `2025-03-26`	Served, `initialize` handshake
`2024-11-05`	Not served (HTTP+SSE transport generation)

Legacy clients keep doing the handshake they already do. New clients call statelessly. Neither side changes any configuration.

One detail that's easy to miss: AISIX never issued sessions on any revision, so MCP requests already need no session affinity across gateway replicas. Your existing legacy clients get the scaling behavior of the new revision without waiting for anyone to upgrade.

Talking to Servers That Only Speak the New Revision

Which protocol a client uses and which protocol the gateway uses toward an upstream are separate decisions. The gateway handles the client's protocol at the endpoint, then opens its own session to each registered server. The upstream revision is one field on the server resource:

mcp_servers:
  - name: modern-tools
    url: https://mcp.example.com/mcp
    protocol_version: "2026-07-28"
    auth_type: none

Leave it unset and the gateway opens with the initialize handshake, which negotiates among the 2025 revisions — servers that adopted 2026-07-28 but kept backward compatibility work fine this way too. Set it to 2026-07-28 only for servers that no longer answer initialize at all. In AISIX Cloud, the same choice is a dropdown on the MCP server form.

With the two sides decoupled, a legacy client can call tools on a new-revision-only server and a new client can call tools on a server that never upgraded. Rollout order stops mattering.

One design decision to be upfront about: there is no automatic probing. The gateway uses the revision you configured, and if the server doesn't support it, the connection fails and says so. Auto-fallback sounds friendly, but it turns a misconfigured server into a system that quietly does something different from what its configuration says — the kind of thing you find weeks later in an audit. We'd rather fail where you can see it.

Five SDK Defaults We Turned Off

Supporting the new revision meant moving to a new major version of the MCP SDK underneath AISIX. Before merging, we went through the new defaults one by one. Five of them are reasonable for a single application talking to its own server and wrong for a gateway sitting between tenants and upstreams:

Automatic multi-round retries. The new revision lets a server answer a tool call with "I need more input," and the SDK retries on its own — up to ten rounds per call. Through a gateway, one inbound tools/call could become ten upstream executions and ten line items of spend, none of it visible to quotas or budgets. We disabled the loop; a non-final answer comes back to the caller as an error.

Replay on session expiry. When a stateful upstream expires a session, the SDK default re-establishes it and re-sends the in-flight request. If that request was "create the ticket" or "send the message," it just ran twice. Off.

A client-side response cache, on by default, including serving stale entries on error. A gateway is shared across tenants; a cached upstream response is one tenant's data waiting for another tenant's request. Disabled entirely.

Two new size caps. A 4 MiB request-body limit that sits underneath the gateway's own configurable limit and overrides it, and a 16 MiB cap on upstream streaming events that didn't exist before the upgrade. The first now follows the gateway's configured limit; the second is removed, so large tool results behave exactly as they did.

Each of these is pinned by a regression test that counts the requests the upstream actually receives. Together they hold one property: one tool call in, one upstream execution out. Budgets, rate limits, and audit trails all quietly depend on it.

Caller Credentials Stay Put

The gateway does not forward the caller's Authorization header, protocol version, or session identifier to any upstream. Each upstream session is opened independently with the credential registered for that server; the caller's API key authenticates the caller to AISIX and goes no further. This was already AISIX's credential model — the stateless rework was a good excuse to pin the whole boundary with tests.

How It's Tested

CI runs the applicable tools-surface scenarios from the official MCP conformance suite against the real gateway chain, and a failing run blocks the merge. A separate set of contract tests drives a legacy client and a 2026-07-28 client against the same endpoint and pins the exact wire shape each one sees, so a future upgrade can't change either behind our backs.

Try It

MCP support ships in the open-source gateway (AISIX on GitHub, Apache 2.0). If you already front MCP servers with AISIX there is nothing to migrate — clients negotiate their own revision, and protocol_version is there when you hit a new-revision-only upstream.