Skip to content

Fix: Handle SSE ping messages in WebFluxSseClientTransport #272

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from

Conversation

goecho
Copy link

@goecho goecho commented May 28, 2025

  • Add check for SSE ping messages from fastMCP server
  • Log debug message when ping received instead of throwing exception
  • Complete the stream on ping events
  • Matches behavior of Python SDK which treats pings as keep-alive

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

- Add check for SSE ping messages from fastMCP server
- Log debug message when ping received instead of throwing exception
- Complete the stream on ping events
- Matches behavior of Python SDK which treats pings as keep-alive
@tzolov
Copy link
Contributor

tzolov commented Jun 24, 2025

Hi @goecho , can you please elaborate on this. I'm not able to find ping event type mentioned by the specification?

@tzolov tzolov added the waiting for user Waiting for user feedback or more details label Jun 24, 2025
@goecho
Copy link
Author

goecho commented Jun 26, 2025

Hi @tzolov this behavior is not defined in the MCP protocol itself—it's specific to the Python implementation using the fastmcp library. The behavior comes from the keep-alive mechanism in its dependency, the sse-starlette library. You can refer to the code here: https://github.com/sysid/sse-starlette/blob/main/sse_starlette/sse.py#L214

@YunKuiLu
Copy link

YunKuiLu commented Jun 27, 2025

Hi @tzolov @goecho , I had the same issue and opened PR #223 to dealt with it by adding an sseErrorHandler parameter.
The SSE comment message : ping isn't part of the MCP spec, so I'm thinking of just logging it as a warning by default. How does that sound?

@goecho
Copy link
Author

goecho commented Jun 28, 2025

Hi @YunKuiLu ,I don't think this is a good idea — we shouldn't change the original logic. The original approach was better: throwing an exception for unknown types helps expose issues, which is better than just logging them.

@YunKuiLu
Copy link

@goecho Thank you for your reply.

I actually considered both options: throwing an exception to stop the client or just logging it. But since the issue is only logged in HttpClientSseClientTransport, I think the client should keep the same default behavior for consistency.

else {
logger.error("Received unrecognized SSE event type: {}", event.type());
}

@osenx
Copy link

osenx commented Jun 29, 2025

I think we can combine two ways. First, expand the ping type, and then use the error handler to support any errors

@chengyi3192
Copy link

Hi @ tzolov, ping is not an event, but a comment in the sse protocol that starts with ":". The official handling method is: it should be ignored.
However, the buildEvent method in org.springframework.cttp.codec.ServerSetEventHttpMessage Reader intercepts the content after ":" and puts it in the comment, but the event in ServerSentEvent is empty, which can cause an exception to be thrown.

I think PR should be merged immediately because sending ping messages is present in many frameworks.

event-stream-interpretation
image

exception
image

@tzolov
Copy link
Contributor

tzolov commented Jul 24, 2025

@chengyi3192 thanks for clarifying the semantics of the comment SSE (non)events.

@tzolov
Copy link
Contributor

tzolov commented Jul 24, 2025

@goecho I guess we can strengthen the check to verify that the id, event and data fields are empty as well? And perhaps generalize to isCommentLine

tzolov added a commit to tzolov/mcp-java-sdk that referenced this pull request Jul 24, 2025
- Replace McpError exceptions with debug/warning logs for unrecognized SSE event types
- Continue processing instead of failing when encountering unknown SSE events
- Update transport implementations:
  - WebClientStreamableHttpTransport: return empty tuple instead of throwing
  - WebFluxSseClientTransport: complete stream instead of erroring
  - HttpClientSseClientTransport: call sink.success() instead of sink.error()
  - HttpClientStreamableHttpTransport: return empty Flux for unknown events

This improves client resilience when servers send non-standard or future SSE event types.

Resolves modelcontextprotocol#272 , modelcontextprotocol#223 , modelcontextprotocol#93

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
…ntLine()

- Strengthen the logic for detecting SSE ping comments by checking that id, event, and data fields are empty.
- Generalize comment detection into isCommentLine(ServerSentEvent) for clarity and reusability.
- Improves consistency with the SSE specification and matches behavior of the Python SDK.
- Replaces previous hardcoded check with a more robust and maintainable solution.
@goecho
Copy link
Author

goecho commented Jul 25, 2025

@tzolov Great point — I've now added the checks for id, event, and data, and pulled the logic into an isCommentLine() helper. Thanks!

@tzolov tzolov closed this in c3a0b18 Jul 25, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
waiting for user Waiting for user feedback or more details
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants