fix: resolve SSE connection issues and prevent stack overflow on cleanup

This commit addresses three critical issues:

1. Fixed infinite recursion in transport cleanup
   - Added cleanup guard flags to prevent circular cleanup calls
   - Issue: cleanup() → server.close() → transport.close() → onclose → cleanup()
   - Affected both SSE and Streamable HTTP transports

2. Fixed 406 errors for SSE clients with non-standard Accept headers
   - Changed GET /mcp routing to default to SSE for sessionless requests
   - Previously rejected clients sending Accept: */* instead of text/event-stream
   - Now properly supports legacy clients like Kilo Code

3. Improved logging and diagnostics
   - Changed MCP server stderr logging from warn to debug level
   - Added comprehensive request logging for /mcp endpoints
   - Enhanced debugging for SSE and Streamable HTTP handlers

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: bcdonadio

README.md

@@ -16,8 +16,8 @@ This dual-interface approach means you can manage servers through the Hub's UI w
 | Category | Feature | Support | Notes |
 |----------|---------|---------|-------|
 | **Transport** ||||
-| | streamable-http | ✅ | Primary transport protocol for remote servers |
-| | SSE | ✅ | Fallback transport for remote servers |
+| | streamable-http | ✅ | Primary transport protocol (client ↔ hub, hub ↔ servers) |
+| | SSE | ✅ | Legacy transport for backward compatibility |
 | | STDIO | ✅ | For running local servers |
 | **Authentication** ||||
 | | OAuth 2.0 | ✅ | With PKCE flow |
@@ -55,12 +55,16 @@ Configure all MCP clients with just one endpoint:
 {
     "mcpServers" : {
         "Hub": {
-            "url" : "http://localhost:37373/mcp"  
+            "url" : "http://localhost:37373/mcp"
         }
     }
 }
 ```
 
+**Transport Auto-Detection**: The Hub automatically detects which transport protocol your client uses:
+- **Modern clients**: Streamable HTTP transport (MCP 2025-03-26 spec)
+- **Legacy clients**: SSE transport (automatic fallback for backward compatibility)
+
 The Hub automatically:
 - Namespaces capabilities to prevent conflicts (e.g., `filesystem__search` vs `database__search`)
 - Routes requests to the appropriate server
@@ -76,10 +80,20 @@ The Hub automatically:
   - Real-time capability updates when servers change
   - Simplified client configuration - just one endpoint instead of many
 
+- **Modern Transport Layer**:
+  - **Streamable HTTP**: Primary transport using MCP 2025-03-26 specification
+    - Single unified endpoint for all client requests
+    - Cryptographically secure session management
+    - Optional DNS rebinding protection (configurable)
+    - Efficient bidirectional communication
+  - **SSE Fallback**: Automatic backward compatibility for legacy clients
+    - Seamless detection and fallback
+    - No configuration required
+
 - **Dynamic Server Management**:
   - Start, stop, enable/disable servers on demand
   - Real-time configuration updates with automatic server reconnection
-  - Support for local (STDIO) and remote (streamable-http/SSE) MCP servers 
+  - Support for local (STDIO) and remote (streamable-http/SSE) MCP servers
   - Health monitoring and automatic recovery
   - OAuth authentication with PKCE flow
   - Header-based token authentication
@@ -126,12 +140,14 @@ The main management server that:
 #### MCP Servers
 Connected services that:
 - Provide tools, resources, templates, and prompts
-- Support two connectivity modes:
-  - Script-based STDIO servers for local operations
-  - Remote servers (streamable-http/SSE) with OAuth support
+- Support three connectivity modes:
+  - **STDIO**: Script-based servers for local operations
+  - **Streamable HTTP**: Modern remote servers (MCP 2025-03-26)
+  - **SSE**: Legacy remote servers (backward compatibility)
 - Implement real-time capability updates
 - Support automatic status recovery
-- Maintain consistent interface across transport types
+- OAuth authentication support for remote servers
+- Maintain consistent interface across all transport types
 
 ## Installation
 

src/MCPConnection.js

@@ -682,7 +682,7 @@ export class MCPConnection extends EventEmitter {
     if (stderrStream) {
       stderrStream.on("data", (data) => {
         const errorOutput = data.toString().trim();
-        logger.warn(`${this.name} stderr: ${errorOutput}`)
+        logger.debug(`${this.name} stderr: ${errorOutput}`)
       });
     }
     return transport

src/mcp/server.js

@@ -475,42 +475,65 @@ export class MCPServerEndpoint {
    * Handle SSE transport creation (GET /mcp)
    */
   async handleSSEConnection(req, res) {
+    logger.debug('handleSSEConnection called', {
+      url: req.url,
+      headers: req.headers,
+      method: req.method
+    });
 
-    // Create SSE transport
-    const transport = new SSEServerTransport('/messages', res);
-    const sessionId = transport.sessionId;
+    try {
+      // Create SSE transport
+      logger.debug('Creating SSE transport');
+      const transport = new SSEServerTransport('/messages', res);
+      const sessionId = transport.sessionId;
+      logger.debug('SSE transport created', { sessionId });
 
-    // Create a new server instance for this connection
-    const server = this.createServer();
+      // Create a new server instance for this connection
+      const server = this.createServer();
+      logger.debug('Server instance created for SSE connection');
 
-    // Store transport and server together
-    this.clients.set(sessionId, { transport, server });
+      // Store transport and server together
+      this.clients.set(sessionId, { transport, server });
 
-    let clientInfo
+      let clientInfo
+      let cleanupCalled = false;
 
 
-    // Setup cleanup on close
-    const cleanup = async () => {
-      this.clients.delete(sessionId);
-      try {
-        await server.close();
-      } catch (error) {
-        logger.warn(`Error closing server connected to ${clientInfo?.name ?? "Unknown"}: ${error.message}`);
-      } finally {
-        logger.info(`'${clientInfo?.name ?? "Unknown"}' client disconnected from MCP HUB`);
-      }
-    };
+      // Setup cleanup on close
+      const cleanup = async () => {
+        if (cleanupCalled) return;
+        cleanupCalled = true;
 
-    res.on("close", cleanup);
-    transport.onclose = cleanup;
+        this.clients.delete(sessionId);
+        try {
+          await server.close();
+        } catch (error) {
+          logger.warn(`Error closing server connected to ${clientInfo?.name ?? "Unknown"}: ${error.message}`);
+        } finally {
+          logger.info(`'${clientInfo?.name ?? "Unknown"}' client disconnected from MCP HUB`);
+        }
+      };
+
+      res.on("close", cleanup);
+      transport.onclose = cleanup;
 
-    // Connect MCP server to transport
-    await server.connect(transport);
-    server.oninitialized = () => {
-      clientInfo = server.getClientVersion()
-      if (clientInfo) {
-        logger.info(`'${clientInfo.name}' client connected to MCP HUB`)
+      // Connect MCP server to transport
+      logger.debug('Connecting server to SSE transport');
+      await server.connect(transport);
+      logger.debug('Server connected to SSE transport successfully');
+
+      server.oninitialized = () => {
+        clientInfo = server.getClientVersion()
+        if (clientInfo) {
+          logger.info(`'${clientInfo.name}' client connected to MCP HUB`)
+        }
       }
+    } catch (error) {
+      logger.error('SSE_CONNECTION_ERROR', 'Error in handleSSEConnection', {
+        error: error.message,
+        stack: error.stack
+      });
+      throw error;
     }
   }
 
@@ -550,19 +573,30 @@ export class MCPServerEndpoint {
    * Supports both POST and GET requests on a single endpoint
    */
   async handleStreamableHTTP(req, res) {
+    logger.debug('handleStreamableHTTP called', {
+      method: req.method,
+      url: req.url,
+      headers: req.headers,
+      sessionId: req.headers['mcp-session-id'] || 'none'
+    });
+
     try {
       // Check if this is for an existing session
       const sessionId = req.headers['mcp-session-id'];
 
       if (sessionId) {
+        logger.debug('Session ID found in request', { sessionId });
         // Reuse existing transport for this session
         const clientInfo = this.clients.get(sessionId);
         if (clientInfo) {
+          logger.debug('Reusing existing session', { sessionId });
           await clientInfo.transport.handleRequest(req, res, req.body);
           return;
         }
         // Session not found - will create new one below
         logger.debug(`Session ${sessionId} not found, creating new session`);
+      } else {
+        logger.debug('No session ID in request, will create new session');
       }
 
       // Create new transport and server for new session
@@ -579,9 +613,13 @@ export class MCPServerEndpoint {
       const server = this.createServer();
 
       let clientInfo;
+      let cleanupCalled = false;
 
       // Setup cleanup for when transport closes
       const cleanup = async () => {
+        if (cleanupCalled) return;
+        cleanupCalled = true;
+
         if (transport.sessionId) {
           this.clients.delete(transport.sessionId);
         }

src/server.js

@@ -22,6 +22,18 @@ const SERVER_ID = "mcp-hub";
 // Create Express app
 const app = express();
 app.use(express.json());
+
+// Log all incoming requests to /api routes
+router.use((req, res, next) => {
+  logger.debug('API request received', {
+    method: req.method,
+    path: req.path,
+    url: req.url,
+    headers: req.headers
+  });
+  next();
+});
+
 app.use("/api", router);
 
 // Helper to determine HTTP status code from error type
@@ -321,12 +333,21 @@ class ServiceManager {
 
 // Register SSE endpoint
 registerRoute("GET", "/events", "Subscribe to server events", async (req, res) => {
+  logger.debug('SSE connection attempt', {
+    url: req.url,
+    path: req.path,
+    headers: req.headers,
+    method: req.method
+  });
+
   try {
     if (!serviceManager?.sseManager) {
+      logger.error('SSE_MANAGER_NOT_INITIALIZED', 'SSE manager not initialized when client attempted to connect');
       throw new ServerError("SSE manager not initialized");
     }
     // Add client connection
     const connection = await serviceManager.sseManager.addConnection(req, res);
+    logger.debug('SSE connection established successfully');
     // Send initial state
     connection.send(EventTypes.HUB_STATE, serviceManager.getState());
   } catch (error) {
@@ -344,14 +365,26 @@ registerRoute("GET", "/events", "Subscribe to server events", async (req, res) =
 
 // Register unified MCP endpoint for both Streamable HTTP (new) and SSE (legacy)
 app.post("/mcp", async (req, res) => {
+  logger.debug('POST /mcp request received', {
+    url: req.url,
+    headers: req.headers,
+    contentType: req.headers['content-type'],
+    body: req.body
+  });
+
   try {
     if (!mcpServerEndpoint) {
+      logger.error('MCP_ENDPOINT_NOT_INITIALIZED', 'MCP server endpoint not initialized');
       throw new ServerError("MCP server endpoint not initialized");
     }
     // POST requests use Streamable HTTP transport (new protocol)
+    logger.debug('Routing POST to Streamable HTTP handler');
     await mcpServerEndpoint.handleStreamableHTTP(req, res);
   } catch (error) {
-    logger.warn(`Failed to handle MCP POST request: ${error.message}`);
+    logger.warn(`Failed to handle MCP POST request: ${error.message}`, {
+      error: error.message,
+      stack: error.stack
+    });
     if (!res.headersSent) {
       res.status(500).json({
         jsonrpc: "2.0",
@@ -366,25 +399,47 @@ app.post("/mcp", async (req, res) => {
 });
 
 app.get("/mcp", async (req, res) => {
+  logger.debug('GET /mcp request received', {
+    url: req.url,
+    headers: req.headers,
+    method: req.method,
+    query: req.query
+  });
+
   try {
     if (!mcpServerEndpoint) {
+      logger.error('MCP_ENDPOINT_NOT_INITIALIZED', 'MCP server endpoint not initialized');
       throw new ServerError("MCP server endpoint not initialized");
     }
 
     // Check if this is a Streamable HTTP GET (has Mcp-Session-Id header)
-    // or legacy SSE (Accept: text/event-stream header)
+    // or legacy SSE (no session ID means initial connection attempt)
     const sessionId = req.headers['mcp-session-id'];
     const acceptsSSE = req.headers.accept?.includes('text/event-stream');
 
-    if (sessionId || !acceptsSSE) {
+    logger.debug('MCP GET request type detection', {
+      sessionId: sessionId || 'none',
+      accept: req.headers.accept || 'none',
+      acceptsSSE,
+      willUseStreamableHTTP: !!sessionId,
+      willUseSSE: !sessionId
+    });
+
+    if (sessionId) {
       // Streamable HTTP GET request (for server-to-client messages in active session)
+      logger.debug('Routing to Streamable HTTP handler (has session ID)');
       await mcpServerEndpoint.handleStreamableHTTP(req, res);
     } else {
       // Legacy SSE transport (backward compatibility)
+      // Any GET request without a session ID is assumed to be an SSE connection attempt
+      logger.debug('Routing to SSE handler (no session ID)');
       await mcpServerEndpoint.handleSSEConnection(req, res);
     }
   } catch (error) {
-    logger.warn(`Failed to handle MCP GET request: ${error.message}`);
+    logger.warn(`Failed to handle MCP GET request: ${error.message}`, {
+      error: error.message,
+      stack: error.stack
+    });
     if (!res.headersSent) {
       res.status(500).send('Error establishing MCP connection');
     }
@@ -951,9 +1006,18 @@ router.use((err, req, res, next) => {
       method: req.method,
     });
 
+  const statusCode = getStatusCode(error);
+  logger.warn('Router error handler triggered', {
+    path: req.path,
+    method: req.method,
+    statusCode,
+    error: error.message,
+    code: error.code
+  });
+
   // Only send error response if headers haven't been sent
   if (!res.headersSent) {
-    res.status(getStatusCode(error)).json({
+    res.status(statusCode).json({
       error: error.message,
       code: error.code,
       data: error.data,