Migrations Migrating from Heroku, Render, Hatchbox or Cloud 66? We move your production app within 48 hours →
MCP 2026-07-28: stateless requests, server/discover, and serving old and new clients from one endpoint ← Blog Agency playbooks • 5 min read

MCP 2026-07-28: stateless requests, server/discover, and serving old and new clients from one endpoint

Almokhtar Bekkour

Almokhtar Bekkour, Founder, Systems Architect

August 16, 2026 · 5 min read

The 2026-07-28 revision of the Model Context Protocol is the biggest change to how clients and servers talk since Streamable HTTP replaced the old SSE transport. The initialize handshake is gone. Sessions are gone. Every request now stands on its own.

For a remote server running behind a load balancer, which is most production servers, that’s very good news. It also means two eras of clients now exist side by side, and a server needs to serve both. Here’s what changed, why, and how Railyard’s MCP endpoint answers both eras on one URL.

What changed

1. No more handshake

Before, a client opened with initialize, negotiated a protocol version, sent notifications/initialized, and often got an Mcp-Session-Id header it had to echo on every later request. The server had to remember that session.

Now every request carries what the handshake used to establish, inside _meta:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "ExampleClient", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

The server reads the version from the request itself and either serves it or refuses it. There’s nothing to remember between requests.

Why it matters: sticky sessions were the hardest part of running an MCP server at scale. Any server instance can now answer any request, so you can restart, autoscale or roll a deploy mid-conversation without breaking a client.

2. server/discover

Clients that want to know what a server supports before calling anything use the new server/discover method:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "supportedVersions": ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"],
    "capabilities": { "tools": { "listChanged": false }, "prompts": { "listChanged": false } },
    "instructions": "Railyard deploys and runs the team's apps on servers the team owns. …",
    "ttlMs": 300000,
    "cacheScope": "private",
    "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "railyard", "version": "2" } }
  }
}

Servers must implement it. Clients may call it, or just send the real request and handle a version error.

3. Version errors are explicit

Ask for a version the server doesn’t speak and you get HTTP 400 with a specific JSON-RPC error, -32022, listing what it does support:

{ "jsonrpc": "2.0", "id": 7,
  "error": { "code": -32022, "message": "Unsupported protocol version",
             "data": { "supported": ["2026-07-28", "2025-11-25", "…"], "requested": "1900-01-01" } } }

The client picks a mutually supported version and retries. That error code is also how a dual-era client tells a modern server from a legacy one: a recognised modern error means “retry with a listed version”, while anything else means “fall back to initialize”.

4. Headers must match the body

Streamable HTTP POSTs now mirror parts of the body into headers, so load balancers and gateways can route without parsing JSON:

POST /api/mcp
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: deploy_app

The server must check that these match the body, and reject a mismatch with 400 and error -32020 (HeaderMismatch). It sounds pedantic, but it closes a real hole. If a gateway allows or rate-limits by the Mcp-Name header while the server executes the name in the body, an attacker could send Mcp-Name: list_apps with a body that calls delete_app. Validating both sides means the thing that was authorised is the thing that runs.

Names that aren’t plain ASCII travel base64-encoded as =?base64?…?=, and servers decode them before comparing.

5. resultType, cache hints, deterministic lists

Every modern result carries resultType. That’s "complete" for ordinary results, or "input_required" for the new multi-round-trip pattern, where a server asks the client for more input inside a result instead of sending its own request. List results carry ttlMs and cacheScope, so a client can cache the tool list instead of fetching it before every call. Servers are asked to return tools in a stable order so the list stays cache-friendly, which also helps the model’s own prompt caching.

6. Unknown methods are 404s

On the modern era, an unsupported method returns HTTP 404 with JSON-RPC -32601. The JSON body is what distinguishes “this server doesn’t do that” from “there’s no MCP server here”.

7. Smaller removals

ping, logging/setLevel and the long-lived GET stream are gone, replaced by per-request log levels and a subscriptions/listen stream that clients opt into. Server-to-client requests like elicitation now ride inside results. Dynamic client registration is deprecated in favour of Client ID Metadata Documents for OAuth, with a long deprecation window.

Serving both eras from one endpoint

Clients don’t all upgrade on the same day. Claude, Claude Code, Cursor and the many editors and agents built on older SDKs will speak 2025 revisions for a while. So Railyard’s endpoint is dual-era, and picks the behaviour from how each request arrives:

The request carries…Served asNotes
_meta protocolVersion 2026-07-28ModernHeaders validated, resultType and serverInfo added, 404 for unknown methods
_meta protocolVersion it doesn’t knowModern error400, -32022, list of supported versions
initialize with a 2025 or 2024 versionLegacyNegotiates that version and answers with capabilities, icons and instructions
An MCP-Protocol-Version header naming an unknown version, without _metaLegacy error400, -32022

A few details matter in practice:

  • A legacy initialize never negotiates the stateless revision. A client that asks for 2026-07-28 through initialize is mixing eras, so it gets the newest handshake revision instead, 2025-11-25, and keeps working.
  • GET and DELETE answer 405 with Allow: POST. That’s how older clients learn there’s no standalone SSE stream or session to tear down, and fall back to plain POSTs.
  • The tool list is identical in both eras. Same 42 tools, same typed schemas, same annotations. Only the envelope differs.

Because the server already kept no per-connection state (each request is authenticated by its bearer token, then served), going stateless meant adding validation and envelopes, not re-architecting.

Checking a server yourself

curl -s https://app.railyard.run/api/mcp \
  -H "Authorization: Bearer $RAILYARD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}'

Drop the Mcp-Method header and you’ll see the -32020 header error. Change the version to 1900-01-01 and you’ll see -32022 with the supported list. Create a read-only token under Settings → Access & tokens for experiments like this.

What it means for you

If you only use Claude or Cursor, nothing changes. They connect, and everything works whichever revision they speak. If you build agents or MCP clients, Railyard is a good server to test against, because it validates the modern rules strictly and still answers the 2024–2025 handshake.

The tool reference is in the MCP docs, and the sign-in flow is covered in MCP authorization explained.

An MCP server that speaks every revision.

Railyard's MCP endpoint serves the stateless 2026-07-28 protocol and the 2024 and 2025 revisions side by side. Connect Claude, Claude Code or Cursor in one step.

14-day trial on every plan. One flat price per team, your servers at your provider's price.

Theme
Colors