Cloudflare’s Agents SDK v0.20.0 and the Model Context Protocol’s 2026-07-28 release changed the default migration path for MCP servers in one weekend. On Sunday, July 27, 2026, Cloudflare shipped Agents SDK support for the new spec. On Monday, July 28, 2026, the MCP maintainers published the new stateless core and Cloudflare moved its own managed MCP servers onto /mcp for new connections.
If you already run a Cloudflare Agent with MCP, the important question is not whether the protocol changed. It did. The useful question is what you actually need to touch in your codebase this week.
This tutorial uses a myth-vs-reality format because the upgrade is smaller than many teams think, but only if you separate ordinary stateless servers from the few endpoints that still depend on legacy session behavior.
Myth 1: Every MCP server needs a full rewrite
Reality: Cloudflare’s migration guide is explicit: do not stay on SDK v1 just because that is what the server imports today. If your endpoint does not depend on session state, pushed server-to-client requests, standalone streams, replay, or RPC, the shortest path is to move the server definition into an SDK v2 factory and pass that factory to createMcpHandler().
That means many teams can swap the server package, move registration into one function, and keep a single /mcp route.
import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";
function createServer() {
return new McpServer({ name: "example", version: "1.0.0" });
}
export default {
fetch(request, env, ctx) {
return createMcpHandler(createServer)(request, env, ctx);
},
};Myth 2: Stateless MCP means losing compatibility with older clients
Reality: The new spec changes the transport model, not your obligation to support users in transition. Cloudflare says the same handler can serve 2026-07-28 clients and legacy clients that already use stateless requests. On the client side, the Agents SDK now probes with server/discover; if the remote server does not support the stateless protocol, it falls back to the older initialize handshake on the same connection.
That makes the default lazy answer the right one: upgrade the SDK first, then test your existing addMcpServer() flows before inventing split protocol config.
Myth 3: You should keep McpAgent around unless something breaks
Reality: McpAgent still exists, but Cloudflare now labels it deprecated and feature-frozen. That is a migration bridge, not a steady state.
If you do rely on legacy sessionful features, the correct move is a dual-lane rollout. Keep the old route only for legacy traffic, add a stateless handler beside it, and let existing sessions drain before removal.
import { isLegacyRequest } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";
import { MyMcpAgent } from "./legacy-server";
import { createServer } from "./server";
const stateless = createMcpHandler(createServer, { route: "/mcp", legacy: "reject" });
const legacy = MyMcpAgent.serve("/mcp");
export default {
async fetch(request, env, ctx) {
if (await isLegacyRequest(request)) return legacy.fetch(request, env, ctx);
return stateless(request, env, ctx);
},
};The key is to classify endpoints first. Cloudflare’s rollout checklist starts there for a reason.
Myth 4: The protocol change is just naming and package churn
Reality: The July 28 MCP release changed the shape of the transport in ways ops teams should care about. The spec moved to a stateless request/response core, added server/discover, shifted method and tool routing into HTTP headers like Mcp-Method and Mcp-Name, and made list responses cache-aware.
Those details matter in production because proxies, gateways, and auth layers now have cleaner things to validate and route on. If you own the edge in front of your MCP server, test the headers all the way through your stack instead of assuming the app upgrade is enough.
Myth 5: Code Mode needs its own MCP migration plan
Reality: For many teams, Code Mode becomes simpler after the upgrade. Cloudflare’s current docs show two small patterns. If you need durable approvals and progressive discovery, use McpConnector. If you just want tool access inside generated sandbox code, pass this.mcp.getAITools() into createCodeTool().
import { DynamicWorkerExecutor } from "@cloudflare/codemode";
import { createCodeTool } from "@cloudflare/codemode/ai";
await this.mcp.waitForConnections();
const codemode = createCodeTool({
tools: this.mcp.getAITools(),
executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }),
});Cloudflare also notes that getAITools() schema conversions are reused while a live connection keeps the same catalog. That lowers the incentive to build your own extra wrapper unless you have a real approval or discovery requirement.
Myth 6: The endpoint path can stay exactly as it was
Reality: Cloudflare’s own managed MCP servers now say to use /mcp for new connections. Historical /sse URLs still work as aliases, but they no longer provide the deprecated HTTP+SSE transport. If a client is forcing SSE, change it to Streamable HTTP or automatic transport detection now, while the migration is still fresh and easy to explain.
That is the cheapest cleanup in this whole project: update the URL, remove the old assumption, and stop teaching new users the legacy path.
The practical rollout order
If you need one checklist to carry into a sprint, use this:
- Upgrade to the current Agents SDK and pin the MCP package version Cloudflare documents for that release.
- Classify each MCP endpoint by whether it truly needs legacy sessionful behavior.
- Move stateless servers to an SDK v2 factory plus
createMcpHandler(). - Keep a temporary legacy lane only where
isLegacyRequest()is still needed. - Test
Mcp-Methodand related headers through every proxy, gateway, and auth layer. - Switch new client documentation to
/mcp, not/sse.
That is the real lesson from July 27 and July 28, 2026: the new MCP stack is not asking most teams for more code. It is asking for a cleaner boundary between stateless request handling and the few legacy behaviors you have not retired yet.