The MCP protocol is about to undergo its biggest revision since launch. As you might’ve seen
from our recent release candidate announcement, the new
protocol revision goes stateless, removing the initialize handshake and the protocol-level
session, and completing the plan we laid out in
The Future of MCP Transports. If you’re building MCP
servers, you can now scale them using a simple round-robin load balancer, removing the need to
manage sticky sessions and to store shared sessions. For client developers, new patterns, like
Multi Round-Trip Requests (MRTR)
enable a whole new range of possibilities for server-to-client interactions. You can check out
the full changelog to see
what’s coming.
Starting today you can test all the forthcoming updates to the protocol with all four
Tier 1 SDKs, led by
Python v2 and
TypeScript v2, with
Go and
C# betas also available. We encourage you
to run the beta SDKs against your real workloads and tell us what breaks as we inch closer to
the actual spec revision. The new protocol specification will be launched on July 28, 2026.
Your existing server keeps working
First, we want to reassure you that for existing clients and servers nothing breaks today,
and nothing breaks on July 28 either. This is merely the date when the normative specification
text is published and is not a switch-off for any implementers relying on the current protocol
version.
The SDK beta releases exist so you can test the protocol changes and give us feedback
before the new specification is locked. For any critical workloads, the stable SDK releases
remain the recommended versions.
You might’ve seen that some of the SDKs, like Python and TypeScript, have also switched to v2.
Those are new major versions, so moving your own code onto them is a breaking change, and one
you can take on your own schedule; it is separate from anything that happens on July 28.
Once v2 ships, the TypeScript SDK will continue shipping v1.x bug fixes and security updates
for at least six months, and the Python v1.x branch continues to receive critical bug fixes and
security patches.
Trying a beta is safe because it is opt-in at every step. Installing the
Python, Go, or C# SDK without explicitly requesting a pre-release still resolves to
a stable version; the TypeScript v2 packages are new package names with no
stable release yet, so installing them is itself the opt-in. In the TypeScript and Go
SDKs, the opt-in extends to the wire: upgrading does not by itself change what your server speaks over
HTTP. Serving 2026-07-28 is an explicit choice you make when you wire up
the transport. A Python or C# server picks up the new revision on upgrade
instead: a Python v2 server answers both protocol revisions from one
endpoint, and the C# preview’s HTTP transport defaults to the new stateless
mode. And clients that speak 2026-07-28 fall back to the
initialize handshake when they reach a server on 2025-11-25 or earlier,
so old servers and new clients keep interoperating.
If you want to make sure your own users are not caught out:
- If you publish a library that depends on the Python
mcp package, add an
upper bound now (for example mcp>=1.27,<2) so the stable v2 release does
not surprise your users.
- When you test a beta, pin the exact version. Public APIs may still change
between the beta and the stable releases.
What beta SDKs implement
All four beta releases implement the core protocol changes from the release candidate,
with each release’s notes detailing which changes are covered. The
RC announcement covers the changes
in depth, but if you’re curious about the short version:
- The stateless core
(SEP-2575,
SEP-2567).
Every request is self-describing, capabilities come from
server/discover, and any server instance can handle any request.
- Multi Round-Trip Requests (MRTR)
(SEP-2322).
Tools can return
InputRequiredResult to ask the user something
mid-call, and the client retries with the answers. No long-lived stream
required!
- Routable transport headers
(SEP-2243).
Mcp-Method rides on every request, and Mcp-Name on requests that name
a tool, resource, or prompt, so gateways and rate limiters can route
without parsing bodies.
- Authorization hardening, including
iss validation per
RFC 9207
(SEP-2468),
application_type in Dynamic Client Registration
(SEP-837),
scope accumulation on step-up
(SEP-2350),
and credential binding to the issuing authorization server
(SEP-2352).
The application_type change is the one desktop and CLI clients will
feel: authorization servers stop defaulting them to "web" and
rejecting their localhost redirects.
- Standard error codes
(SEP-2164).
A missing resource now returns JSON-RPC
-32602 instead of the
MCP-custom -32002. If your client matches on the literal value, you should update
it.
- Deprecation annotations
(SEP-2577)
on roots, sampling, and logging. This is advisory only, as the deprecated methods,
types, and capability flags keep working in this release and in every
specification version published within a year of it.
The full protocol text is in the
draft specification,
and the
changelog
lists every change against 2025-11-25.
Python: mcp v2
The v2 line is a rework of the package you already know: FastMCP becomes
MCPServer, and the decorator API carries over. A complete server still
looks like this:
from mcp.server import MCPServer
mcp = MCPServer("Demo")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
"""Greet someone by name."""
return f"Hello, {name}!"
As in v1, there is no JSON Schema to write, as idiomatic Python constructs take over.
Install the beta with an exact pin, since unpinned installs stay on v1.x:
uv add "mcp[cli]==2.0.0b1"
# or
pip install "mcp[cli]==2.0.0b1"
If you have a v1 server today, the
migration guide
walks through every breaking change.
On the protocol side, the beta speaks 2026-07-28 end to end: servers
answer the new server/discover method, and the client’s default mode
probes it and falls back to initialize on older servers. Upgrading your
server does not strand existing clients: a v2 server answers the legacy
initialize handshake alongside server/discover, so clients on
2025-11-25 keep connecting. You can test all
of it in-process: pass your MCPServer instance directly to Client
(async with Client(mcp) as client:) and it connects in memory, the same
pattern as FastAPI’s TestClient. No subprocess, no port. The
SDK documentation has the tutorial and the full
API reference.
TypeScript: split packages
TypeScript v2 retires the monolithic @modelcontextprotocol/sdk package in
favor of focused ones, like @modelcontextprotocol/server for servers,
@modelcontextprotocol/client for clients, plus thin adapters for Node.js,
Express, Hono, and Fastify. It is ESM-only and runs on Node.js 20+, Bun, and
Deno. Tool schemas now use
Standard Schema, so you can bring Zod v4,
Valibot, ArkType, or any compatible library.
You can bootstrap a minimal server like this:
import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";
const server = new McpServer({ name: "greeting-server", version: "1.0.0" });
server.registerTool(
"greet",
{
description: "Greet someone by name",
inputSchema: z.object({ name: z.string() }),
},
async ({ name }) => ({
content: [{ type: "text", text: `Hello, ${name}!` }],
}),
);
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
}
main();
To install any of the packages, you can use the now-familiar npm commands:
npm install @modelcontextprotocol/server@beta
npm install @modelcontextprotocol/client@beta
For HTTP deployments, which is where the stateless protocol pays off, createMcpHandler from
@modelcontextprotocol/server is the entry point. It serves 2026-07-28
per request and handles 2025-11-25 traffic from the same endpoint, with
the adapter packages connecting it to Node.js, Express, Hono, and Fastify.
Migrating from v1 is mostly mechanical, and there is a codemod that does the boring parts
for you, including the rename from .tool() to
registerTool and the error-type renames. You can get it with:
npx @modelcontextprotocol/codemod@beta v1-to-v2 .
The repository ships two guides that will help you along the way:
While it might seem confusing, these two are standalone steps - you can move to v2
now and turn on the new protocol revision when you are ready. The
v2 API documentation covers
the rest.
Go and C#
The Go and C# betas take a slightly gentler path - there is no package split and no rework of
the API you use day to day.
The Go SDK ships 2026-07-28 support in v1.7.0-pre.1, on the same
module path as the version you are already using:
go get github.com/modelcontextprotocol/go-sdk@v1.7.0-pre.1
Serving the new revision over HTTP is the same explicit choice as in
TypeScript: the streamable HTTP transport accepts 2026-07-28 only when
you set StreamableHTTPOptions.Stateless = true. Leave it unset and
clients negotiate down to 2025-11-25. The
release notes
walk through every protocol change and the
SDK documentation will cover the updated
API.
The C# beta, in turn, is released as the 2.0.0-preview.1 version of the
ModelContextProtocol packages:
dotnet add package ModelContextProtocol --prerelease
Stable v1.x APIs keep working in v2. The breaking changes are confined to
the capabilities the specification deprecates (roots, sampling, and
logging), which are marked [Obsolete] with pointers to their
replacements, and to experimental APIs whose contracts changed as the
specification settled. The
preview release notes
include a per-SEP implementation table, and the
SDK documentation will have the updated
API reference once the package is stable.
Give us your feedback
We’re a mere four weeks away until the specification is final. We need your help to make the
release smoother!
-
Install a beta in a branch of your server and run your real traffic
against it, not just the happy path.
-
If you operate behind a gateway or load balancer, serve the stateless
path and see whether your routing still needs anything the protocol no
longer provides. In TypeScript that path is createMcpHandler; in Go,
set StreamableHTTPOptions.Stateless = true; in Python, the v2 HTTP
app answers both protocol revisions from one endpoint.
-
File what you find. SDK problems go to the issue tracker for the SDK
you are using:
And if you spot issues with the protocol itself, go to the
specification repository.
It’s worth noting that public APIs may still change between the betas and the stable releases, so
pin exact versions. Your feedback in the next four weeks is what they will be
built from. And if you have other feedback or want to engage with SDK maintainers, join our
contributor Discord.
We’re excited to see what you build!
Log in
