RelatedRequestId routing for MCP streams

[mattzcarey]

• use TransportSendOptions as per the MCP SDK
• send() method to prioritise relatedRequestId for routing
• some tests

[changeset-bot]

🦋 Changeset detected

Latest commit: b468829

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

[pkg-pr-new]

Open in StackBlitz

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

commit: b468829

[claude]

Claude Code Review

PR Summary: Implements relatedRequestId routing for bidirectional MCP streams, enabling server-to-client requests (like elicitations) to flow through the same POST stream as the originating client request.

Issues

1. Invalid JSON Schema constraint for number type

Location: examples/mcp-elicitation/src/index.ts:74

The schema uses minLength: 1 for a number field, but minLength only applies to strings/arrays. Should use minimum: 1 instead.

Impact: Schema validation may not enforce the constraint as intended, potentially allowing zero or negative values.

2. Test coupling via whitebox testing

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

The new tests use type assertions to directly manipulate private fields (streamMapping, requestToStreamMapping). While this enables thorough testing of internal routing logic, it creates tight coupling that will break if these fields are renamed/refactored.

Recommendation: Consider adding test-only public methods in future refactoring. For now, acceptable given the tests are well-documented.

Observations

Routing logic correctness

The send() method at worker-transport.ts:748-754 correctly implements priority:

1. For responses/errors: always use message.id
2. For server-to-client requests: use relatedRequestId if provided
3. Otherwise: use standalone GET stream

This ensures responses always return on the correct stream, while server-initiated requests can be routed through the same stream as a related client request.

Optional chaining fix

worker-transport.ts:363 now correctly uses optional chaining for both conditions, fixing a potential null reference issue.

Testing

Excellent coverage with 340 lines of comprehensive tests:

• ✅ Routing with/without relatedRequestId
• ✅ Multiple concurrent streams
• ✅ Response routing priority
• ✅ Error cases (missing/closed streams)
• ✅ Edge cases (concurrent requests, priority overrides)

Verdict

One fix required: Issue #1 - use minimum: 1 instead of minLength: 1 for the amount field

Otherwise, the implementation is well-designed and thoroughly tested. The core routing logic is sound and properly handles complex stream routing scenarios.

[threepointone]

Documentation sync PR created: cloudflare/cloudflare-docs#26562

This PR documents the relatedRequestId routing feature for bidirectional MCP streams, including:

• How relatedRequestId routing works in Streamable HTTP transport
• When to use relatedRequestId (elicitation, progress updates, callbacks)
• Implementation details and code examples
• Clarification that this is specific to Streamable HTTP transport

The documentation has been added to the transport.mdx page in the Model Context Protocol section.

[threepointone]

📚 Documentation Update

I've synced the documentation for this PR to the cloudflare-docs repository.

Documentation PR: cloudflare/cloudflare-docs#26562

What was documented:

• Added a new section on Bidirectional streaming with relatedRequestId to the MCP Transport documentation
• Explained how server-to-client requests (like elicitation) are routed through the same stream as the originating client request
• Documented the message routing priority: responses → relatedRequestId → fallback to GET stream
• Provided a practical elicitation example showing automatic relatedRequestId handling
• Included advanced usage documentation for custom transport implementations using TransportSendOptions

The documentation helps developers understand when and how to use relatedRequestId for proper bidirectional communication in MCP servers.

[threepointone]

Documentation has been synced to cloudflare-docs.

📚 Documentation PR: cloudflare/cloudflare-docs#26562

The following documentation updates have been made:

• Added comprehensive guide on using relatedRequestId for bidirectional MCP communication
• Documented how server-to-client requests (elicitation) are routed through POST streams
• Included complete code example showing elicitInput() with relatedRequestId parameter
• Explained technical details of request-to-stream mapping and hibernation support

Please review the documentation PR to ensure it accurately reflects the changes in this PR.

[threepointone]

reference MCP here

[mattzcarey]

doing this now

[threepointone]

📚 Documentation Updated

The documentation for this change has been synced to the cloudflare-docs repository:

Documentation PR: cloudflare/cloudflare-docs#26562

What was documented

Added a new section on Bidirectional stream routing in the MCP transport documentation that covers:

• How the transport layer routes server-to-client requests through the correct HTTP stream using relatedRequestId
• The routing priority (responses → related requests → standalone stream)
• Practical example showing how to use relatedRequestId with elicitInput in tool handlers

This ensures developers understand how to properly implement elicitation and other bidirectional communication patterns when building MCP servers with the Agents SDK.