← Blog Agency playbooks • 5 min read MCP 2026-07-28: stateless requests, server/discover, and serving old and new clients from one endpoint
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 as | Notes |
|---|---|---|
_meta protocolVersion 2026-07-28 | Modern | Headers validated, resultType and serverInfo added, 404 for unknown methods |
_meta protocolVersion it doesn’t know | Modern error | 400, -32022, list of supported versions |
initialize with a 2025 or 2024 version | Legacy | Negotiates that version and answers with capabilities, icons and instructions |
An MCP-Protocol-Version header naming an unknown version, without _meta | Legacy error | 400, -32022 |
A few details matter in practice:
- A legacy
initializenever negotiates the stateless revision. A client that asks for2026-07-28throughinitializeis mixing eras, so it gets the newest handshake revision instead,2025-11-25, and keeps working. - GET and DELETE answer
405withAllow: 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.