feat(mcp): add transport: "auto" for McpAgent.serve()

[threepointone]

Summary

Adds a new transport: "auto" option to McpAgent.serve() that serves both Streamable HTTP and legacy SSE on the same endpoint. Capable clients get the modern Streamable HTTP protocol automatically, while older SSE-only clients continue to work transparently — no client changes required.

// Serve both transports on a single path
export default MyMCP.serve("/mcp", { transport: "auto" });

How it works

The auto handler composes the existing createStreamingHttpHandler and createLegacySseHandler with a thin routing layer that discriminates by request shape:

Request	Routes to
DELETE	Streamable HTTP (SSE has no session teardown)
POST {path}/message	Legacy SSE (the /message sub-path is SSE-only)
POST {path}	Streamable HTTP
GET with mcp-session-id header	Streamable HTTP (standalone SSE reconnect)
GET without mcp-session-id	Legacy SSE (new connection)
Other methods	405 Method Not Allowed

The two protocols have completely non-overlapping HTTP signatures, so routing is deterministic — no heuristics or content negotiation.

What changed

• packages/agents/src/mcp/utils.ts — Added createAutoHandler that composes both existing handlers
• packages/agents/src/mcp/types.ts — Widened ServeOptions.transport from BaseTransportType to TransportType (which already included "auto")
• packages/agents/src/mcp/index.ts — Added "auto" case to serve() switch
• docs/mcp-transports.md — Documented auto transport and updated comparison table

Design decisions

• serveSSE() unchanged — stays as transport: "sse". Auto is opt-in via serve(path, { transport: "auto" }). No silent behavior changes for existing users.
• {path}/message is reserved — in auto mode, this sub-path is captured by the SSE handler. This is the same reservation SSE already makes.
• No changes to DO internals — the auto handler picks the right name prefix (sse: or streamable-http:) at the edge, so getTransportType() / initTransport() inside the DO work as-is.

Test plan

17 new tests in auto-transport.test.ts covering:

• Routing (5 tests): POST→streamable, POST /message→SSE, GET+header→streamable, GET-header→SSE, DELETE→streamable
• Protocol (2 tests): Full tool invocation end-to-end through each transport
• Coexistence (1 test): Both transports active simultaneously with correct responses
• Notifications (1 test): Notification-only POST returns 202
• CORS (2 tests): OPTIONS preflight, 405 includes Allow header
• Edge cases (6 tests): 405 for PUT, 400/404 for bad DELETE, 404 for unknown session, 406 for bad Accept, 400 for missing sessionId

All 791 tests pass (47 test files).

Made with Cursor

---

[changeset-bot]

🦋 Changeset detected

Latest commit: ce385cf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 3 additional findings.

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1207

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1207

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1207

hono-agents

npm i https://pkg.pr.new/hono-agents@1207

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1207

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1207

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1207

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1207

commit: ce385cf