fix: WorkerTransport doesn't persist clientCapabilities, breaking elicitation in serverless

[Muhammad-Bin-Ali]

Summary

Persist and restore client capabilities (initializeParams) across serverless restarts when using WorkerTransport with storage.

Problem

When using WorkerTransport with storage in a serverless environment (like Cloudflare Workers), client capabilities (like elicitation support) were not persisted across requests. This caused elicitation and other capability-dependent features to fail after a serverless cold start with:

Error: Client does not support form elicitation.

Root Cause:

• TransportState only stored { sessionId, initialized }
• _clientCapabilities is stored in-memory on the MCP SDK's Server instance
• After serverless restart, _clientCapabilities was undefined because it wasn't restored

Solution

Store the full initializeParams (capabilities, clientInfo, protocolVersion) and replay the initialize request during state restoration to restore _clientCapabilities on the Server instance.

Changes

packages/agents/src/mcp/worker-transport.ts:

• Added RESTORE_REQUEST_ID constant for the synthetic restore request ID
• Extended TransportState interface to include initializeParams
• Capture initializeParams during initialization before calling saveState()
• Replay initialize request via this.onmessage() during restoreState() to restore _clientCapabilities
• Filter restore response in send() to prevent error from missing stream

packages/agents/src/tests/mcp/transports/worker-transport.test.ts:

• Added new test suite "Client Capabilities Persistence (Serverless Restart)" with 5 tests covering persistence, restoration, and backward compatibility

Breaking Changes

None. The TransportState interface change is backward compatible - old stored state without initializeParams will continue to work (capabilities just won't be restored).

Future Improvement

The ideal solution would be to extend the MCP TypeScript SDK with a function to directly update clientCapabilities on the Server instance, rather than replaying the initialize request. This would be a cleaner approach that doesn't rely on internal implementation details.

Closes #777

🤖 Generated with OpenCode using Claude

[changeset-bot]

🦋 Changeset detected

Latest commit: 9bd943a

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]

Claude Code Review

Issue Found:

Line 558: Redundant type guard check

const initMessage = messages.find(isInitializeRequest);
if (initMessage && isInitializeRequest(initMessage)) {

The isInitializeRequest(initMessage) check is redundant since find() already guarantees initMessage satisfies the predicate. Simplify to:

if (initMessage) {

Otherwise: LGTM

The implementation correctly solves the capability persistence problem. The approach of replaying the initialize request is reasonable given SDK limitations. Tests are comprehensive, covering edge cases and backward compatibility.

[pkg-pr-new]

Open in StackBlitz

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

commit: 9bd943a

[mattzcarey]

Fix check and a couple of questions. Awesome work :)

[mattzcarey]

epic stuff, congrats