fix: guide legacy SSE clients to Streamable HTTP

Author: mattzcarey

.changeset/semantic-sse-migration.md

@@ -0,0 +1,23 @@
+---
+'cloudflare-ai-gateway-mcp-server': patch
+'auditlogs': patch
+'cloudflare-autorag-mcp-server': patch
+'cloudflare-browser-mcp-server': patch
+'cloudflare-blog': patch
+'cloudflare-casb-mcp-server': patch
+'demo-day': patch
+'dex-analysis': patch
+'dns-analytics': patch
+'docs-ai-search': patch
+'graphql-mcp-server': patch
+'logpush': patch
+'cloudflare-radar-mcp-server': patch
+'containers-mcp': patch
+'stack-mcp': patch
+'workers-bindings': patch
+'workers-builds': patch
+'workers-observability': patch
+'@repo/mcp-common': patch
+---
+
+Return an actionable `410 Gone` Problem Details response when a client attempts the removed HTTP+SSE transport with `GET /sse`. The response explains that clients can configure the existing `/sse` URL to use Streamable HTTP or, preferably, move to `/mcp` for future compatibility. It preserves query parameters, identifies the recommended replacement in a `Link` header, and is available before OAuth authentication. Streamable HTTP `POST` requests continue to work on both `/sse` and `/mcp`.

README.md

@@ -4,7 +4,7 @@ Model Context Protocol (MCP) is a [new, standardized protocol](https://modelcont
 
 These MCP servers allow your [MCP Client](https://modelcontextprotocol.io/clients) to read configurations from your account, process information, make suggestions based on data, and even make those suggested changes for you. All of these actions can happen across Cloudflare's many services including application development, security and performance.
 
-Every server exposes the same stateless Streamable HTTP handler at `/mcp` and `/sse` through a fresh SDK v2 server factory. `/sse` remains as a URL compatibility alias; it does not use the deprecated HTTP+SSE transport. Modern 2026 requests and stateless 2025 requests share the same request-scoped implementation without an MCP protocol session. OAuth, credentials, account selection, application caches, and product Durable Objects remain application/security state where required.
+Every server exposes the same stateless Streamable HTTP handler at `/mcp` and `/sse` through a fresh SDK v2 server factory. `/sse` remains as a URL compatibility alias; it does not use the deprecated HTTP+SSE transport. A legacy SSE `GET /sse` request receives a `410 Gone` Problem Details response with two migration options: configure the existing URL to use Streamable HTTP, or switch to the recommended `/mcp` URL for future compatibility. Modern 2026 requests and stateless 2025 requests share the same request-scoped implementation without an MCP protocol session. OAuth, credentials, account selection, application caches, and product Durable Objects remain application/security state where required.
 
 The following servers are included in this repository:
 

packages/mcp-common/README.md

@@ -48,7 +48,7 @@ export default app.worker
 
 For lower-level use, `createCloudflareMcpHandler()` accepts explicit server metadata, observability factories, and HTTP policy. It delegates protocol routing, CORS, Host/Origin validation, and legacy compatibility to `createMcpHandler()` from the isolated `agents/mcp/server` entry point. Do not construct a global MCP server. Do not set `legacy: 'reject'`: the default `legacy: 'stateless'` fallback is part of the migration contract.
 
-The shared handler serves `POST` and CORS `OPTIONS` on `/mcp` and `/sse`. The latter is a URL alias, not the deprecated HTTP+SSE transport. The SDK returns `405` for stateless legacy stream and session-deletion requests. MCP request bodies are capped at 4 MiB before SDK parsing, and OAuth resources use strict path-aware matching.
+The shared handler serves `POST` and CORS `OPTIONS` on `/mcp` and `/sse`. The latter is a URL alias, not the deprecated HTTP+SSE transport. A legacy SSE `GET /sse` request returns `410 Gone` with an `application/problem+json` body that offers two Streamable HTTP migrations: keep the existing URL by changing the configured transport, or switch to the recommended `/mcp` URL for future compatibility. The SDK continues to return `405` for other stateless legacy stream and session-deletion requests. MCP request bodies are capped at 4 MiB before SDK parsing, and OAuth resources use strict path-aware matching.
 
 ## Request registration context
 

packages/mcp-common/src/oauth-router.spec.ts

@@ -64,6 +64,31 @@ describe('OAuth router resource policy', () => {
 		).toThrow('resourceMatchOriginOnly')
 	})
 
+	it('routes legacy SSE stream requests to the migration handler before OAuth', async () => {
+		const router = createCloudflareOAuthRouter<CloudflareOAuthEnv>({
+			apiHandler: {
+				fetch() {
+					return new Response('migration', { status: 410 })
+				},
+			},
+			scopes: {},
+			metrics,
+			mcpRequestPolicy,
+		})
+
+		const response = await router.fetch(
+			new Request('https://mcp.example.com/sse', {
+				method: 'GET',
+				headers: { Accept: 'text/event-stream', Host: 'mcp.example.com' },
+			}),
+			testEnv(),
+			executionContext
+		)
+
+		expect(response.status).toBe(410)
+		await expect(response.text()).resolves.toBe('migration')
+	})
+
 	it('returns a retryable response when a Wrangler OAuth identity probe is rate limited', async () => {
 		server.use(
 			http.get('https://api.cloudflare.com/client/v4/user', () =>
@@ -170,6 +195,7 @@ describe('OAuth router resource policy', () => {
 
 		const response = await router.fetch(
 			new Request('https://mcp.example.com/sse', {
+				method: 'POST',
 				headers: {
 					Authorization: `Bearer ${'a'.repeat(40)}`,
 					Host: 'mcp.example.com',

packages/mcp-common/src/oauth-router.ts

@@ -10,6 +10,7 @@ import {
 	resolveExternalToken,
 } from './api-token-mode'
 import { createAuthHandlers, handleTokenExchangeCallback } from './cloudflare-oauth-handler'
+import { isLegacySseStreamRequest } from './transport-migration'
 
 import type { OAuthProviderOptions } from '@cloudflare/workers-oauth-provider'
 import type { MetricsTracker } from '@repo/mcp-observability'
@@ -82,10 +83,13 @@ export function createCloudflareOAuthRouter<Env extends CloudflareOAuthEnv>({
 					return apiHandler.fetch(request, env, ctx)
 				}
 
-				// Let the MCP handler own its browser preflight so the exact policy and
-				// modern request-header allowlist are not replaced by the OAuth Provider's
-				// intentionally broad discovery-endpoint CORS response.
-				if (request.method === 'OPTIONS') return apiHandler.fetch(request, env, ctx)
+				// Let the MCP handler own browser preflight and the unauthenticated SSE
+				// migration response so its exact HTTP policy is preserved. The OAuth
+				// Provider would otherwise challenge GET /sse before clients see the
+				// actionable replacement endpoint.
+				if (request.method === 'OPTIONS' || isLegacySseStreamRequest(request)) {
+					return apiHandler.fetch(request, env, ctx)
+				}
 			}
 
 			if (devApiTokenModeEnabled(env)) {

packages/mcp-common/src/server.spec.ts

@@ -191,6 +191,71 @@ describe('shared stateless MCP foundation', () => {
 		expect(instances.size).toBe(4)
 	})
 
+	it('returns an actionable migration problem for legacy SSE stream requests', async () => {
+		let registrations = 0
+		const handler = createCloudflareMcpHandler<TestEnv>({
+			serverInfo: { name: 'sse-migration', version: '1.0.0' },
+			register() {
+				registrations++
+			},
+			handler: {
+				allowedHostnames: ['mcp.example.com'],
+				allowedOriginHostnames: ['app.example.com'],
+				corsOptions: { origin: 'https://app.example.com' },
+			},
+		})
+		const replacementUrl = 'https://mcp.example.com/mcp?libs=cloudflare,hono'
+		const response = await handler.fetch(
+			new Request('https://mcp.example.com/sse?libs=cloudflare,hono', {
+				method: 'GET',
+				headers: {
+					Accept: 'text/event-stream',
+					Host: 'mcp.example.com',
+					Origin: 'https://app.example.com',
+				},
+			}),
+			{ requestLabel: 'sse-migration' },
+			executionContext()
+		)
+
+		expect(response.status).toBe(410)
+		expect(response.headers.get('content-type')).toContain('application/problem+json')
+		expect(response.headers.get('cache-control')).toBe('no-store')
+		expect(response.headers.get('link')).toBe(`<${replacementUrl}>; rel="alternate"`)
+		expect(response.headers.get('access-control-allow-origin')).toBe('https://app.example.com')
+		await expect(response.json()).resolves.toEqual({
+			type: 'https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/',
+			title: 'Legacy SSE transport is no longer supported',
+			status: 410,
+			detail:
+				'This URL no longer supports the deprecated HTTP+SSE transport. Configure this URL to use Streamable HTTP, or update to the replacement URL for future compatibility.',
+			options: [
+				{
+					action: 'change-transport',
+					transport: 'streamable-http',
+					url: 'https://mcp.example.com/sse?libs=cloudflare,hono',
+					recommended: false,
+				},
+				{
+					action: 'update-url',
+					transport: 'streamable-http',
+					url: replacementUrl,
+					recommended: true,
+				},
+			],
+		})
+		const rejected = await handler.fetch(
+			new Request('https://mcp.example.com/sse', {
+				method: 'GET',
+				headers: { Accept: 'text/event-stream', Host: 'evil.example.com' },
+			}),
+			{ requestLabel: 'sse-migration-invalid-host' },
+			executionContext()
+		)
+		expect(rejected.status).toBe(403)
+		expect(registrations).toBe(0)
+	})
+
 	it('rejects oversized MCP request bodies before constructing a server', async () => {
 		let registrations = 0
 		const handler = createCloudflareMcpHandler<TestEnv>({

packages/mcp-common/src/server.ts

@@ -7,6 +7,7 @@ import { AccountManager } from './account-manager'
 import { AuthPropsSchema } from './auth-props'
 import { createRegistrationContext } from './registration-context'
 import { getRequestUserId } from './request-context'
+import { isLegacySseStreamRequest, legacySseMigrationResponse } from './transport-migration'
 
 import type { Implementation, McpServerFactory, ServerOptions } from '@modelcontextprotocol/server'
 import type { CreateMcpHandlerOptions } from 'agents/mcp/server'
@@ -126,7 +127,8 @@ const DEFAULT_CORS_HEADERS = [
  *
  * The Agents/upstream default `legacy: "stateless"` is deliberately preserved;
  * this wrapper never changes it to `"reject"`. The historical `/sse` URL is
- * served by the same stateless handler and is not the deprecated HTTP+SSE transport.
+ * served by the same stateless handler and is not the deprecated HTTP+SSE transport;
+ * legacy `GET /sse` attempts receive an actionable `410 Gone` migration problem.
  */
 export function createCloudflareMcpHandler<Env>(
 	options: CreateCloudflareMcpHandlerOptions<Env>
@@ -160,7 +162,7 @@ export function createCloudflareMcpHandler<Env>(
 				boundedRequest = bounded
 			}
 
-			return createMcpHandler(
+			const response = await createMcpHandler(
 				createCloudflareMcpServerFactory(factoryOptions, {
 					env,
 					request: boundedRequest,
@@ -172,6 +174,13 @@ export function createCloudflareMcpHandler<Env>(
 					corsOptions: resolvedCors,
 				}
 			)(boundedRequest, env, ctx)
+
+			// Let the MCP wrapper enforce Host and Origin policy before replacing its
+			// generic stateless-GET rejection with an actionable transport migration.
+			if (response.status === 405 && isLegacySseStreamRequest(boundedRequest)) {
+				return withCors(legacySseMigrationResponse(boundedRequest, canonicalRoute), resolvedCors)
+			}
+			return response
 		},
 	}
 }

packages/mcp-common/src/test/stateless-app.ts

@@ -162,22 +162,24 @@ export function testStatelessMcpApp<Env>({
 			expect((await policyHandler.fetch(badOrigin, env, context(false))).status).toBe(403)
 		})
 
-		it('serves /sse through the same modern and legacy stateless transport', async () => {
+		it('serves the /sse Streamable HTTP alias and guides legacy SSE clients to /mcp', async () => {
 			const routeHandler = authenticated ? handler : (authenticatedWorker ?? handler)
+			const migrationHandler = authenticatedWorker ?? routeHandler
 			const alias = new URL('/sse', url).href
+			const replacement = new URL('/mcp', url).href
 			const modern = await routeHandler.fetch(
 				modernRequest(alias, 'server/discover'),
 				env,
 				context()
 			)
 			const legacy = await routeHandler.fetch(legacyInitializeRequest(alias), env, context())
-			const oldSse = await routeHandler.fetch(
+			const oldSse = await migrationHandler.fetch(
 				new Request(alias, {
 					method: 'GET',
 					headers: { Accept: 'text/event-stream', Host: new URL(url).hostname },
 				}),
 				env,
-				context()
+				context(false)
 			)
 
 			expect(modern.status).toBe(200)
@@ -190,7 +192,27 @@ export function testStatelessMcpApp<Env>({
 			expect(await responseDocument(legacy)).toMatchObject({
 				result: { protocolVersion: '2025-11-25' },
 			})
-			expect(oldSse.status).toBe(405)
+			expect(oldSse.status).toBe(410)
+			expect(oldSse.headers.get('content-type')).toContain('application/problem+json')
+			expect(oldSse.headers.get('link')).toBe(`<${replacement}>; rel="alternate"`)
+			await expect(oldSse.json()).resolves.toMatchObject({
+				title: 'Legacy SSE transport is no longer supported',
+				status: 410,
+				options: [
+					{
+						action: 'change-transport',
+						transport: 'streamable-http',
+						url: alias,
+						recommended: false,
+					},
+					{
+						action: 'update-url',
+						transport: 'streamable-http',
+						url: replacement,
+						recommended: true,
+					},
+				],
+			})
 			expect('MCP_OBJECT' in (env as object)).toBe(false)
 		})
 	})

packages/mcp-common/src/transport-migration.ts

@@ -0,0 +1,47 @@
+const LEGACY_SSE_ROUTE = '/sse'
+const MIGRATION_DOCUMENTATION =
+	'https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/'
+
+export function isLegacySseStreamRequest(request: Request): boolean {
+	return request.method === 'GET' && new URL(request.url).pathname === LEGACY_SSE_ROUTE
+}
+
+export function legacySseMigrationResponse(request: Request, canonicalRoute = '/mcp'): Response {
+	const current = new URL(request.url).href
+	const replacementUrl = new URL(request.url)
+	replacementUrl.pathname = canonicalRoute
+	const replacement = replacementUrl.href
+
+	return new Response(
+		JSON.stringify({
+			type: MIGRATION_DOCUMENTATION,
+			title: 'Legacy SSE transport is no longer supported',
+			status: 410,
+			detail:
+				'This URL no longer supports the deprecated HTTP+SSE transport. Configure this URL to use Streamable HTTP, or update to the replacement URL for future compatibility.',
+			options: [
+				{
+					action: 'change-transport',
+					transport: 'streamable-http',
+					url: current,
+					recommended: false,
+				},
+				{
+					action: 'update-url',
+					transport: 'streamable-http',
+					url: replacement,
+					recommended: true,
+				},
+			],
+		}),
+		{
+			status: 410,
+			statusText: 'Gone',
+			headers: {
+				'Cache-Control': 'no-store',
+				'Content-Type': 'application/problem+json',
+				Link: `<${replacement}>; rel="alternate"`,
+			},
+		}
+	)
+}