Cloudflare Agents MCP SDK v2 Migration: McpAgent to createMcpHandler

Choose the migration path from the server’s behavior#

The package import alone does not tell you whether an endpoint is stateless:

Cloudflare’s Agents SDK v0.20.0 migration announcement marks McpAgent as deprecated and feature-frozen. The migration guide also deprecates passing an SDK v1 server to createMcpHandler; that overload is scheduled for removal in the next major version.

Move server construction into a factory#

An SDK v2 stateless handler expects a factory. The Worker remains the default-exported object, while the factory creates a fresh McpServer for each request:

1
import { McpServer } from '@modelcontextprotocol/server';
2
import { createMcpHandler } from 'agents/mcp/server';
3
import { z } from 'zod';
4

5
function createServer() {
6
  const server = new McpServer({
7
    name: 'example-server',
8
    version: '1.0.0',
9
  });
10

11
  server.registerTool(
12
    'hello',
13
    {
14
      description: 'Return a greeting',
15
      inputSchema: { name: z.string().optional() },
16
    },
17
    async ({ name }) => ({
18
      content: [{ type: 'text', text: `Hello, ${name ?? 'World'}!` }],
19
    }),
20
  );
21

22
  return server;
23
}
24

25
export default {
26
  fetch(request, env, ctx) {
27
    return createMcpHandler(createServer)(request, env, ctx);
28
  },
29
};

The important change is the argument: SDK v2 passes the factory createServer, not a previously constructed createServer() instance. Do not default-export the callable returned by createMcpHandler; Wrangler interprets a function default export as a WorkerEntrypoint class. Keep the Worker object as the entrypoint and compose the handler inside fetch().

The SDK v2 handler creates a server for each MCP request, so concurrent Worker requests do not share one connected server instance. Put durable application state behind an explicit boundary such as a Durable Object, D1, KV, or R2 rather than relying on an MCP protocol session that the stateless route does not preserve.

Pin the right package generation#

Cloudflare’s migration guide gives separate install commands. For a stateless server, use the v2 server package:

1
pnpm add agents @modelcontextprotocol/[email protected] zod

For a temporary legacy lane, keep the SDK v1 server package instead:

1
pnpm add agents @modelcontextprotocol/[email protected] zod

Install only the generation that the code imports. Do not change a legacy McpAgent route’s server import to @modelcontextprotocol/server without also migrating its server registration and transport assumptions. Pin the exact MCP package version required by the Agents SDK release, then test the lockfile in a clean install.

Reject legacy traffic on a stateless-only route#

The stateless handler supports ordinary legacy requests by default. If an endpoint is intentionally stateless, make that decision explicit:

1
const stateless = createMcpHandler(createServer, {
2
  route: '/mcp',
3
  legacy: 'reject',
4
});
5

6
export default {
7
  fetch(request, env, ctx) {
8
    return stateless(request, env, ctx);
9
  },
10
};

This prevents a legacy request from being consumed by the compatibility lane before your sessionful route can handle it. The stateless route does not provide a protocol session ID, persistent session state, standalone GET or DELETE behavior, event replay, or the legacy server-to-client request flow. Check those assumptions with the clients that will actually call the endpoint.

Run stateless and legacy lanes together during migration#

If existing clients still need sessionful behavior, deploy both paths and route requests with isLegacyRequest():

1
import { isLegacyRequest } from '@modelcontextprotocol/server';
2
import { createMcpHandler } from 'agents/mcp/server';
3

4
const stateless = createMcpHandler(createStatelessServer, {
5
  route: '/mcp',
6
  legacy: 'reject',
7
});
8

9
const legacy = MyMcpAgent.serve('/mcp');
10

11
export default {
12
  async fetch(request, env, ctx) {
13
    if (await isLegacyRequest(request)) {
14
      return legacy.fetch(request, env, ctx);
15
    }
16
    return stateless(request, env, ctx);
17
  },
18
};

Use createLegacyMcpHandler for a non-McpAgent SDK v1 server that needs a temporary legacy branch. Keep the old branch only while its sessionful dependencies are being replaced. Monitor which clients still use it, migrate those clients, let existing sessions drain, and remove the legacy handler and any protocol-only Durable Object binding in a separate cleanup deployment.

Do not route by a user-controlled query parameter or an unvalidated header. Let the SDK’s request classification decide the protocol lane, and preserve authentication and Origin/Host validation around both handlers. CORS headers alone do not authenticate an MCP endpoint.

Test the migration at the protocol boundary#

A build that type-checks is not enough. Test both lanes with a clean client and the real proxy path:

1. Confirm an ordinary tool call reaches createMcpHandler and does not reuse a server instance across requests.
2. Confirm legacy clients are classified correctly when both handlers share /mcp.
3. Confirm a sessionful operation that the stateless route cannot support is routed to the temporary legacy lane or rejected intentionally.
4. Verify the MCP-Protocol-Version, Mcp-Method, Mcp-Name, and any declared Mcp-Param-* headers survive a proxy or gateway.
5. Test authentication, allowed Host values, allowed Origins, cancellation, and transport loss.
6. Check that a clean deploy contains the v2 server package and does not accidentally bundle an unused legacy transport.

The MCP stateless HTTP session migration guide explains the protocol-level session decision in more detail. For a repeatable Cloudflare Worker check, pair this migration with the Cloudflare Workers test harness guide and run a real request against the deployed handler.

The practical rule is to migrate the server’s behavior, not just its imports: stateless tools belong in an SDK v2 factory and createMcpHandler, while sessionful features need a visible legacy lane with a removal plan.

FAQ#