Upgrade MCP SDK to v1.25.1 by mattzcarey · Pull Request #752 · cloudflare/agents

mattzcarey · 2025-12-24T12:13:29Z

No description provided.

changeset-bot · 2025-12-24T12:13:32Z

🦋 Changeset detected

Latest commit: c897ff1

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

claude · 2025-12-24T12:15:05Z

Claude Code Review

Summary: MCP SDK upgrade from v1.23.0 to v1.25.2 with enhanced error handling and event store resumability support.

Critical Issue

Race condition in SSE stream setup (worker-transport.ts:343-383):
The stream is added to streamMapping at line 343, but the priming event (retry interval) and event replay happen after at lines 354-383. If send() is called between these operations, it will write to the stream before priming/replay completes, potentially causing events to arrive out of order or before the client is ready.

Fix: Move the priming event write and replay logic before adding the stream to streamMapping, or use a flag to defer sends until setup completes.

Issues

Missing error handling in resumability flow (worker-transport.ts:293-294):
```
const eventStreamId = await this.eventStore.getStreamIdForEventId?.(lastEventId);
```
The optional chaining suggests this method might not exist on all EventStore implementations, but there's no handling if the method exists but throws an error. Consider wrapping in try-catch.
Potential memory leak in closeSSEStream (worker-transport.ts:785-789):
The cleanup iterates over all entries to find matching streamIds. For large numbers of requests, this could be slow. Consider maintaining a reverse mapping streamIdToRequestIds.
Example uses deprecated header casing (examples/mcp-server/src/index.ts:35):
```
"Access-Control-Allow-Headers": "Content-Type, Accept, mcp-session-id, mcp-protocol-version"
```
SDK uses MCP-Protocol-Version (PascalCase) per the constant MCP_PROTOCOL_VERSION_HEADER. The lowercase mcp-protocol-version may not match.

Minor

Consider documenting the behavior when eventStore.getStreamIdForEventId() is undefined vs when it returns undefined (different semantics)
The changeset mentions version 1.25.2 but shows changes from 1.25.1 features like jose and json-schema-typed dependencies

Testing

Good coverage added:

✅ Error handling tests (errors.test.ts)
✅ Worker transport tests (640 new lines)
✅ Existing transport tests updated

Tests pass validation of the error code extraction logic and CORS handling.

This sync updates the documentation to reflect the following changes from cloudflare/agents PR #752: ## API Changes ### WorkerTransportOptions (mcp-handler-api.mdx) - Added `onsessionclosed` callback that fires when a session is closed via DELETE request - Added `eventStore` option for SSE resumability support, enabling clients to reconnect and resume using Last-Event-ID header - Added `retryInterval` option to control client reconnection timing for polling behavior - Added `closeSSEStream()` method to WorkerTransport class for implementing polling behavior during long-running operations - Updated `sessionIdGenerator` description to clarify it can return undefined for stateless mode ### MCPTransportOptions (mcp-client-api.mdx) - Added `connectionTimeoutMs` option (default: 15000ms) to prevent infinite hangs when connecting to MCP servers. Particularly useful when proxies strip SSE newline terminators. ### New Example (transport.mdx) - Added documentation for the new `mcp-server` example showing how to use `WebStandardStreamableHTTPServerTransport` from the MCP SDK directly without the agents package. This is the simplest way to create stateless MCP servers on Cloudflare Workers. Related PR: cloudflare/agents#752 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

This commit documents the new stateless MCP server approach introduced in PR #752 (Upgrade MCP SDK to v1.25.1). Changes: - Add new stateless-mcp-server.mdx guide demonstrating WebStandardStreamableHTTPServerTransport usage - Update MCP index page to explain both stateless and McpAgent-based approaches - Update remote-mcp-server guide to clarify it uses McpAgent and link to stateless option - Document the simplest way to create MCP servers on Cloudflare Workers The new example (examples/mcp-server) uses the MCP SDK directly without the agents package, providing a zero-config stateless option that is simpler for basic use cases. Related PR: cloudflare/agents#752

pkg-pr-new · 2025-12-24T12:22:32Z

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@752

commit: c897ff1

Document the MCP SDK upgrade from v1.23.0 to v1.25.1 with the following updates: - Add new section on using MCP SDK directly without Agents SDK - Document the new mcp-server example using WebStandardStreamableHTTPServerTransport - Add documentation for new WorkerTransport options: - onsessionclosed callback for session cleanup - eventStore for connection resumability support - retryInterval for SSE polling behavior control Related to cloudflare/agents#752 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- Document new WorkerTransport features: eventStore, onsessionclosed, retryInterval - Highlight new mcp-server example with stateless guide - Explain improved error handling and migration notes Related to cloudflare/agents#752 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- Upgrade MCP SDK from 1.25.1 to 1.25.2 - Import EventStore, StreamId, EventId types from SDK instead of local definitions - Regenerate package-lock.json

- Upgrade MCP SDK from 1.23.0 to 1.25.2 - Use caret range for automatic patch updates

This updates the documentation to reflect changes from PR #752 which upgraded the MCP SDK from v1.23.0 to v1.25.2. Key documentation changes: - Add new WorkerTransport options: onsessionclosed, eventStore, retryInterval - Document the closeSSEStream() method for polling behavior - Add example showing how to use WebStandardStreamableHTTPServerTransport directly - Update transport.mdx to present two approaches: Agents SDK vs MCP SDK directly - Link to new mcp-server example on GitHub These changes help developers understand the new transport features including session lifecycle callbacks, event resumability, and direct MCP SDK usage without the Agents SDK. Related PR: cloudflare/agents#752 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

deathbyknowledge

Very positive changes :D

deathbyknowledge · 2026-01-12T11:54:29Z

examples/mcp-worker/README.md


 This example demonstrates how to use `createMcpHandler` to create an unauthenticated stateless MCP server.

-This is THE simplest way to get started with MCP on Cloudflare.


Dethroned. Maybe worth a mention here that this is now supported directly in the mcp library and a link to the new example?

Just a nit, don't have to do this now

mattzcarey added 2 commits December 24, 2025 11:42

upgrade mcp and native example

327b8c5

fix: fallback error handling since mcp v1.24.0

48087db

mattzcarey force-pushed the feat-upgrade-mcp branch from 59fe808 to 48087db Compare December 24, 2025 12:18

agents-git-bot bot mentioned this pull request Dec 24, 2025

Upgrade MCP SDK to v1.25.2 cloudflare/cloudflare-docs#27314

Closed

4 tasks

fix lockfile

98cfcb2

mattzcarey and others added 2 commits December 24, 2025 12:57

add some tests

aae1db9

Merge branch 'main' into feat-upgrade-mcp

50cb24b

whoiskatrin mentioned this pull request Jan 6, 2026

[regression]: Support MCP-Protocol-Version 2025-11-25 #769

Closed

mattzcarey added 5 commits January 9, 2026 13:31

Update @modelcontextprotocol/sdk to v1.25.2

fdfdb11

- Upgrade MCP SDK from 1.25.1 to 1.25.2 - Import EventStore, StreamId, EventId types from SDK instead of local definitions - Regenerate package-lock.json

reset on main

a46e680

Merge remote-tracking branch 'origin/main' into feat-upgrade-mcp

2bfc876

Update @modelcontextprotocol/sdk to v1.25.2

eebb17a

- Upgrade MCP SDK from 1.23.0 to 1.25.2 - Use caret range for automatic patch updates

pin package version

5b43783

mattzcarey added 2 commits January 12, 2026 11:29

changeset

185692d

typo

c897ff1

deathbyknowledge approved these changes Jan 12, 2026

View reviewed changes

mattzcarey merged commit 473e53c into main Jan 12, 2026
7 checks passed

mattzcarey deleted the feat-upgrade-mcp branch January 12, 2026 12:08

github-actions bot mentioned this pull request Jan 12, 2026

Version Packages #774

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Upgrade MCP SDK to v1.25.1#752

Upgrade MCP SDK to v1.25.1#752
mattzcarey merged 12 commits intomainfrom
feat-upgrade-mcp

mattzcarey commented Dec 24, 2025

Uh oh!

changeset-bot bot commented Dec 24, 2025 •

edited

Loading

Uh oh!

claude bot commented Dec 24, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Dec 24, 2025 •

edited

Loading

Uh oh!

deathbyknowledge left a comment

Uh oh!

deathbyknowledge Jan 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		This example demonstrates how to use `createMcpHandler` to create an unauthenticated stateless MCP server.

		This is THE simplest way to get started with MCP on Cloudflare.

Conversation

mattzcarey commented Dec 24, 2025

Uh oh!

changeset-bot bot commented Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

claude bot commented Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Claude Code Review

Critical Issue

Issues

Minor

Testing

Uh oh!

pkg-pr-new bot commented Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

deathbyknowledge left a comment

Choose a reason for hiding this comment

Uh oh!

deathbyknowledge Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

changeset-bot bot commented Dec 24, 2025 •

edited

Loading

claude bot commented Dec 24, 2025 •

edited

Loading

pkg-pr-new bot commented Dec 24, 2025 •

edited

Loading