Deploy a remote MCP server on Cloudflare Workers with the Agents SDK createMcpHandler, serving Streamable HTTP at /mcp

Documented steps

1. Read https://developers.cloudflare.com/agents/model-context-protocol/mcp-handler-api/ first. It states plainly: 'McpAgent is deprecated and feature-frozen. Migrate existing McpAgent servers to a stateless handler.'
2. Install the current stack: npm i agents @modelcontextprotocol/server@2.0.0 zod . Do not build a new server on McpAgent even though the quick-deploy template still uses it.
3. Write a factory that returns a FRESH server per call: import { McpServer } from '@modelcontextprotocol/server'; function createServer() { const server = new McpServer({ name: 'my-server', version: '1.0.0' }); server.registerTool('hello', { description: 'Greet', inputSchema: { name: z.string().optional() } }, async ({ name }) => ({ content: [{ type: 'text', text: `Hello, ${name}!` }] })); return server; }
4. Wrap it: import { createMcpHandler } from 'agents/mcp/server'; export default { fetch(request, env, ctx) { return createMcpHandler(createServer)(request, env, ctx); } } satisfies ExportedHandler;
5. Pass the factory function itself, not an already-constructed server instance. The handler calls it per request.
6. The handler serves Streamable HTTP at the default route option '/mcp'.
7. Run locally with npm start (default port 8788) and hit http://localhost:8788/mcp .
8. Test interactively: npx @modelcontextprotocol/inspector@latest , then connect to the local or deployed /mcp URL.
9. For stdio-only clients such as Claude Desktop, point the mcp-remote proxy package at your deployed /mcp URL.
10. Deploy: npx wrangler@latest deploy . The server is then reachable at https://<worker-name>.<subdomain>.workers.dev/mcp .
11. Only when bridging an existing session-based deployment, use createLegacyMcpHandler from 'agents/mcp' with @modelcontextprotocol/sdk@1.30.0 as a temporary migration path.