Getting "Unknown SSE event: keepalive" when trying to use virtual servers

[hiteshsom]

I created 2 virtual servers from a local hosted MCP server. Basically divided 4 tools among 2 virtual servers.

Original MCP server url
http://localhost:8005/sse

I am able to see the tools it has access to and also able to call the tools.

I used this code

import asyncio
from fastmcp import Client, FastMCP

client = Client("http://localhost:8005/sse")



async def main():
    async with client:
        # Basic server interaction
        await client.ping()
        
        # List available operations
        tools = await client.list_tools()
        resources = await client.list_resources()
        prompts = await client.list_prompts()

        print("Available tools:")
        for tool in tools:
            print(tool.name)
        print()
        
        # Execute operations
        result = await client.call_tool("add", {"a": 1, "b": 2})
        print("Addition of 1 + 2:")
        print(result.content[0].text)

        # Execute operations
        result = await client.call_tool("subtract", {"a": 1, "b": 2})
        print("Subtraction of 1 - 2:")
        print(result.content[0].text)


        

asyncio.run(main())

It works fine.

Now I try to use below code

import asyncio
from fastmcp import Client, FastMCP
from fastmcp.client.auth import BearerAuth

client = Client("http://localhost:4444/servers/2/sse", auth="<token>")


async def main():
    async with client:

        await client.ping()

        # List available operations
        tools = await client.list_tools()
        # resources = await client.list_resources()
        # prompts = await client.list_prompts()

        for tool in tools:
            print(tool.name)
        
        # Execute operations
        result = await client.call_tool("add", {"a": 1, "b":2})
        print("Sine of 1:")
        print(result.content[0].text)
        

asyncio.run())

But getting this output

Unknown SSE event: keepalive
Unknown SSE event: keepalive
Unknown SSE event: keepalive
Unknown SSE event: keepalive

[crivetimihai]

Thanks for opening this issue and using the MCP Gateway.

The "Unknown SSE event: keepalive" message you're seeing is not an error - it's a warning from the fastmcp client library that doesn't recognize the keepalive event type. The MCP Gateway is working correctly.

Explanation

The MCP Gateway sends periodic keepalive events through the SSE stream to prevent connection timeouts. This is a standard practice for SSE implementations, especially when dealing with proxies, load balancers, and long-lived connections. The keepalive events are sent:

1. Immediately after establishing the connection (to confirm the stream is active)
2. Every 30 seconds when there's no other activity

These keepalive events contain an empty JSON object {} and are meant to be ignored by clients. They serve only to keep the connection alive.

Note: The MCP specification references the W3C SSE standard but does not explicitly define which SSE event types are allowed. Keepalive events are not mentioned in the MCP spec, but they are a common and accepted practice in SSE implementations to maintain connection stability.

The Issue

The fastmcp client library doesn't recognize keepalive as a valid SSE event type, so it logs "Unknown SSE event: keepalive". This is a limitation in the fastmcp client, not a bug in the MCP Gateway.

Solutions

Option 1: Ignore the warnings (Recommended for now)

The warnings are harmless and don't affect functionality. Your tools should work correctly despite these messages.

Option 2: Use a different MCP client

Consider using an MCP client that properly handles or ignores keepalive events. For example, the official MCP SDK or other clients that follow SSE best practices.

Option 3: Filter the warnings in your application

If using fastmcp, you can suppress these warnings in your Python code:

import logging

# Suppress the specific warning from fastmcp
logging.getLogger('fastmcp').setLevel(logging.ERROR)

# Or filter just the keepalive warnings
class KeepAliveFilter(logging.Filter):
    def filter(self, record):
        return 'keepalive' not in record.getMessage().lower()

logger = logging.getLogger('fastmcp')
logger.addFilter(KeepAliveFilter())

Option 4: Request fastmcp to handle keepalive events

Open an issue with the fastmcp library requesting support for keepalive SSE events. The fix would be simple - the client should silently ignore events with type "keepalive".

Technical Details

The keepalive implementation in MCP Gateway (mcpgateway/transports/sse_transport.py):

# Send keepalive immediately after connection
yield {
    "event": "keepalive",
    "data": "{}",
    "retry": settings.sse_retry_timeout,
}

# Send keepalive every 30 seconds when idle
except asyncio.TimeoutError:
    yield {
        "event": "keepalive",
        "data": "{}",
        "retry": settings.sse_retry_timeout,
    }

This follows SSE best practices and ensures reliable connections across various network configurations.

Verification

Your setup is working correctly if:

• You can list tools successfully
• You can call tools and get responses
• The only issue is the "Unknown SSE event: keepalive" warnings

What Users Should Do

When Writing Client Code

If you're writing custom SSE client code (not using fastmcp), you should:

1. Simply ignore keepalive events:

async for line in response.content:
    # Parse SSE event
    if event_type == "keepalive":
        continue  # Ignore keepalive events
    elif event_type == "message":
        # Process actual message
        process_message(data)

2. For fastmcp users, the library handles the connection - you don't need to do anything special. The warnings are harmless.

Can Keepalive Events Be Disabled?

Currently, keepalive events cannot be disabled in the MCP Gateway. They are hardcoded to:

• Send immediately upon connection
• Send every 30 seconds during idle periods

This is intentional because:

• Many proxies and load balancers close idle connections after 30-60 seconds
• Cloud providers (AWS ALB, GCP, Azure) have default timeouts around 60 seconds
• Keepalives ensure the connection stays open for long-running operations

However, we've created Issue #690 to make keepalive events configurable. Once implemented, you'll be able to:

• Enable/disable keepalive events via SSE_KEEPALIVE_ENABLED environment variable
• Adjust the interval via SSE_KEEPALIVE_INTERVAL environment variable
• Maintain current behavior by default for backward compatibility

For mcpgateway.translate Users

If you're using mcpgateway.translate to expose stdio servers via SSE, you can adjust the keepalive interval:

python -m mcpgateway.translate --stdio "uvx mcp-server-git" --port 9000 --keepAlive 60

This sets keepalives to every 60 seconds instead of the default 30.

Conclusion

The MCP Gateway is functioning as designed. The keepalive events are a feature, not a bug, ensuring reliable SSE connections. The warnings you see are from the client library not recognizing this standard SSE pattern. Your virtual servers and tools should work correctly despite these warnings.

Recommendation: Simply ignore the "Unknown SSE event: keepalive" warnings - they don't affect functionality. If the warnings bother you, consider:

1. Using the logging filter approach shown above
2. Requesting the fastmcp maintainers to silently ignore unknown event types
3. Waiting for Issue #690 to be implemented, which will allow you to configure or disable keepalive events

[crivetimihai]

#690 is now implemented. Let me know if that helps!