Fix: Add Session ID and Header Support to SSE Transport (#660) by naji247 · Pull Request #661 · cloudflare/agents

naji247 · 2025-11-18T19:44:36Z

Overview

This is a PR to fix issue #660. The SSE transport in MCP was missing critical request context that StreamableHTTP transport already provided. When using SSE, MCP servers couldn't access:

Session IDs for connection tracking
Authentication information from middleware
Request headers for custom metadata or authorization

This created a feature gap between the two transports, limiting SSE-based implementations. Even though SSE is technically deprecated, our analysis of major companies with MCP servers shows that many are still dependent on SSE. To disable SSE support for their users would require all of them to update their MCP JSON configs (which is quite a hassle).

This PR brings full feature parity to the SSE transport in the following ways:

Session ID Support

Updated McpSSETransport to accept and store session IDs
Modified transport initialization to pass session ID from the agent name

Authentication & Header Forwarding

Created buildMessageExtraInfo() helper to construct MessageExtraInfo with auth and headers
Updated onSSEMcpMessage() to accept and forward authentication context
Modified SSE handler in utils.ts to extract and pass request metadata

Key Changes

McpSSETransport: Now accepts optional sessionId in constructor
onSSEMcpMessage: Accepts extraInfo parameter with headers and auth
buildMessageExtraInfo: New helper that filters internal headers and builds proper context
Type definitions: Added RequestWithAuth type for cleaner code

Testing

I added a few tests to the existing SSE based test file. The build passes successfully and the changes have been validated to ensure:

Session IDs are properly transmitted
Authentication info from middleware is accessible
Request headers are forwarded correctly
Internal transport headers are filtered out

- Add MessageExtraInfo support to SSE transport matching StreamableHTTP behavior - Pass request headers and auth info through SSE message handling - Add RequestWithAuth type for consistent auth info passing - Filter internal headers (content-type, content-length, upgrade) before passing to MCP server - Add comprehensive tests for header and auth handling in both transports - Ensure transport initialization before processing SSE messages This ensures both SSE and StreamableHTTP transports have consistent header and authentication handling capabilities, allowing MCP servers to access request context regardless of transport type.

changeset-bot · 2025-11-18T19:44:40Z

🦋 Changeset detected

Latest commit: f0e7d86

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 · 2025-11-18T19:54:31Z

Open in StackBlitz

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

commit: f0e7d86

threepointone

this looks good to me, but I'll let @deathbyknowledge have a look before we land it since he'd touched this part of the code

naji247 · 2025-11-18T20:35:32Z

this looks good to me, but I'll let @deathbyknowledge have a look before we land it since he'd touched this part of the code

Thank you @threepointone ! Please let us know if you want any modifications. I tried to keep it similar to how Streamable HTTP was implemented.

deathbyknowledge

Thanks for the PR! While we want to add support for the extra parameter for the SSE transport, there are a few open questions that I'd like to ask.

Specially regarding request.auth, I'd appreciate more context about your auth middleware implementation.
Most commonly MCPs have implemented auth with workers-oauth-provider through ctx.props (which is populated by the library). Docs that cover some of this can be found here

deathbyknowledge · 2025-11-19T17:08:56Z

+        method: "POST"
+      });
+
+      // Spy on the transport to capture the extraInfo


Doesn't seem like this is testing anything new here. What am I missing?

deathbyknowledge · 2025-11-19T17:15:42Z

+      // Only custom headers like x-custom-header should be preserved in requestInfo.headers
+      const sseText = await readSSEEvent(response);
+      const result = parseSSEData(sseText);
+      expectValidToolsList(result);


On a closer look it seems like the 3 tests are doing the same. They are either adding custom headers to the request or setting an auth property.
Then the test checks that the request was successful and that the tool list is correct but there are no assertions relevant to either the custom headers or the auth field.

One thing that can be done is update the MCP behind the worker to do/return differently in these scenarios.

I decided to create a tool in the workers.ts test utility that actually returns the requestInfo it receives to make it more thorough of a test.

deathbyknowledge · 2025-11-19T17:20:52Z

    }

+    // Ensure transport is initialized before processing messages
+    if (!this._transport) {


This should not be needed, onStart is called every time a request is routed and the DO is initialized. Were you facing issues with this._transport not being initialized?

Sorry, I did this just to make sure it was properly initialized. I will remove this :)

deathbyknowledge · 2025-11-19T17:32:03Z

+    // Remove internal headers that are not part of the original request
+    delete headers["content-type"];


These headers are part of the original request, they should not be removed

deathbyknowledge · 2025-11-19T17:46:33Z

-        return new McpSSETransport(() => this.getWebSocket());
+        return new McpSSETransport(
+          () => this.getWebSocket(),
+          this.getSessionId()


In the StreamableHTTP we use the pattern here to get this, so we can avoid drilling fields through the constructor.

Sounds good. Will do 🫡

Originally I was worried about breaking existing uses of this class, but it seems to be internal only and limited to this part of the codebase.

deathbyknowledge · 2025-11-19T18:32:21Z

-      const error = await agent.onSSEMcpMessage(sessionId, messageBody);
+      const error = await agent.onSSEMcpMessage(sessionId, messageBody, {
+        headers: Object.fromEntries(request.headers.entries()),
+        auth: (request as RequestWithAuth).auth


Hmm this normally runs inside your Worker fetch handler, how did the request get the auth property?

You're right, for the purposes of the Cloudflare users we're aiding, we actually only needed the headers (and not auth explicitly) so our tests weren't covering the auth header. I added it in with the hopes of meeting parity with StreamableHTTP but I decided to instead reduce the scope of this PR to just include header and session management information.

…r parameters

… transport tests

naji247 · 2025-11-19T21:44:52Z

@deathbyknowledge I went ahead and updated the tests, reverted some of the changes I made to include auth information, and refactored the SSE constructor to use an options object paradigm.

deathbyknowledge

Looks good! There are a few nits and one type error breaking the CI but this should be ready to merge after those are addressed 👍

…Agent util

…construction in onSSEMcpMessage

naji247 · 2025-11-20T21:23:02Z

@deathbyknowledge refactored to use the getCurrentAgent utility and removed the less necessary buildExtra method like you asked! Also, I think all type checks are passing locally now too.

naji247 · 2025-11-21T18:35:46Z

Ah looks like the TS issue still exists... fixing now!

naji247 · 2025-11-24T15:28:10Z

@deathbyknowledge sorry to trouble you again, but do you think we can merge this in sometime this week? :)

deathbyknowledge

Sorry I missed this. Just need to remove one unnecessary bit and we can get this merged 👍

Resolve conflict in worker.ts by keeping imports needed for echoRequestInfo tool (RequestHandlerExtra, CallToolResult, IsomorphicHeaders, ServerNotification, ServerRequest).

naji247 · 2025-11-25T15:55:46Z

@deathbyknowledge should be good to go :)

deathbyknowledge · 2025-11-25T17:04:39Z

CI is failing, seems like a silly type error. Can you check with npm run check please?

whoiskatrin · 2025-11-25T17:04:44Z

@deathbyknowledge should be good to go :)

@naji247, sorry to bug you, but type checks are failing

naji247 · 2025-11-25T17:13:29Z

Thanks @whoiskatrin I swear they passed locally :( fixed now I think

naji247 · 2025-11-25T17:24:16Z

Woo 🥳 they passed.

deathbyknowledge · 2025-11-25T17:24:31Z

Merged O7

chore: add changeset for SSE transport fixes

2a4fc7b

threepointone reviewed Nov 18, 2025

View reviewed changes

deathbyknowledge suggested changes Nov 19, 2025

View reviewed changes

naji247 added 4 commits November 19, 2025 14:45

fix: remove transport initialization check

0411599

refactor: update McpSSETransport to use options object for constructo…

d767e73

…r parameters

fix: revert auth inclusion on SSE transport

4effb09

feat: implement header and auth echo tool for SSE and Streamable HTTP…

3702f31

… transport tests

naji247 requested a review from deathbyknowledge November 19, 2025 21:43

Merge branch 'main' into feat/mcp-sse-header-parity

acb8a95

deathbyknowledge suggested changes Nov 20, 2025

View reviewed changes

Comment thread packages/agents/src/mcp/index.ts Outdated

Comment thread packages/agents/src/mcp/utils.ts Outdated

Comment thread packages/agents/src/mcp/transport.ts Outdated

Comment thread packages/agents/src/mcp/index.ts Outdated

naji247 changed the title ~~Fix: Add Session ID, Auth, and Header Support to SSE Transport (#660)~~ Fix: Add Session ID and Header Support to SSE Transport (#660) Nov 20, 2025

naji247 added 2 commits November 20, 2025 16:10

refactor: simplify McpSSETransport initialization by using getCurrent…

3497dc4

…Agent util

refactor: replace buildMessageExtraInfo with direct MessageExtraInfo …

65c36f5

…construction in onSSEMcpMessage

naji247 requested a review from deathbyknowledge November 20, 2025 21:14

naji247 force-pushed the feat/mcp-sse-header-parity branch 2 times, most recently from a910d78 to 65c36f5 Compare November 20, 2025 21:19

Merge branch 'main' into feat/mcp-sse-header-parity

9b2d2af

naji247 added 2 commits November 21, 2025 14:01

fix: ts check errors

3f1e4f4

Merge branch 'main' into feat/mcp-sse-header-parity

2eb4334

deathbyknowledge approved these changes Nov 25, 2025

View reviewed changes

Comment thread packages/agents/src/mcp/utils.ts Outdated

naji247 added 2 commits November 25, 2025 10:46

patch: remove header deletions

2289674

Merge upstream/main into feat/mcp-sse-header-parity

67a42fe

Resolve conflict in worker.ts by keeping imports needed for echoRequestInfo tool (RequestHandlerExtra, CallToolResult, IsomorphicHeaders, ServerNotification, ServerRequest).

fix: typechecks

f0e7d86

deathbyknowledge merged commit 93589e5 into cloudflare:main Nov 25, 2025
3 of 5 checks passed

github-actions Bot mentioned this pull request Nov 25, 2025

Version Packages #657

Merged

		// Remove internal headers that are not part of the original request
		delete headers["content-type"];

Uh oh!

Conversation

naji247 commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Key Changes

Testing

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

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

Uh oh!

Uh oh!

threepointone left a comment

Choose a reason for hiding this comment

Uh oh!

naji247 commented Nov 18, 2025

Uh oh!

deathbyknowledge left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

naji247 commented Nov 19, 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

naji247 commented Nov 20, 2025

Uh oh!

naji247 commented Nov 21, 2025

Uh oh!

naji247 commented Nov 24, 2025

Uh oh!

deathbyknowledge left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

naji247 commented Nov 25, 2025

Uh oh!

deathbyknowledge commented Nov 25, 2025

Uh oh!

whoiskatrin commented Nov 25, 2025

Uh oh!

naji247 commented Nov 25, 2025

Uh oh!

naji247 commented Nov 25, 2025

Uh oh!

Uh oh!

deathbyknowledge commented Nov 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

naji247 commented Nov 18, 2025 •

edited

Loading

changeset-bot Bot commented Nov 18, 2025 •

edited

Loading

pkg-pr-new Bot commented Nov 18, 2025 •

edited

Loading

naji247 commented Nov 19, 2025 •

edited

Loading