n8n-mcp/docs/SINGLE_SESSION_IMPLEMENTATION.md

Single-Session HTTP Server Implementation

Overview

This document describes the implementation of the Hybrid Single-Session architecture that fixes the "stream is not readable" error in the n8n-MCP HTTP server.

Architecture

The Single-Session architecture maintains one persistent MCP session that is reused across all requests, providing:

• Protocol compliance with StreamableHTTPServerTransport
• Simple state management (one session only)
• Automatic session expiry after 30 minutes of inactivity
• Clean console output management

Key Components

1. ConsoleManager (src/utils/console-manager.ts)

Prevents console output from interfering with the StreamableHTTPServerTransport:

• Silences all console methods during MCP request handling
• Automatically restores console after request completion
• Only active in HTTP mode

2. SingleSessionHTTPServer (src/http-server-single-session.ts)

Core implementation of the single-session architecture:

• Maintains one persistent session with StreamableHTTPServerTransport
• Automatically creates/resets session as needed
• Wraps all operations with ConsoleManager
• Handles authentication and request routing

3. N8NMCPEngine (src/mcp-engine.ts)

Clean interface for service integration:

• Simple API for processing MCP requests
• Health check capabilities
• Graceful shutdown support
• Ready for multi-tenant wrapper services

Usage

Standalone Mode

# Start the single-session HTTP server
MCP_MODE=http npm start

# Or use the legacy stateless server
npm run start:http:legacy

As a Library

import { N8NMCPEngine } from 'n8n-mcp';

const engine = new N8NMCPEngine();

// In your Express app
app.post('/api/mcp', authenticate, async (req, res) => {
  await engine.processRequest(req, res);
});

// Health check
app.get('/health', async (req, res) => {
  const health = await engine.healthCheck();
  res.json(health);
});

Docker Deployment

services:
  n8n-mcp:
    image: ghcr.io/czlonkowski/n8n-mcp:latest
    environment:
      - MCP_MODE=http
      - AUTH_TOKEN=${AUTH_TOKEN}
    ports:
      - "3000:3000"

Testing

Manual Testing

# Run the test script
npm run test:single-session

Unit Tests

# Run Jest tests
npm test -- single-session.test.ts

Health Check

curl http://localhost:3000/health

Response includes session information:

{
  "status": "ok",
  "mode": "single-session",
  "version": "2.3.1",
  "sessionActive": true,
  "sessionAge": 45,
  "uptime": 120,
  "memory": {
    "used": 45,
    "total": 128,
    "unit": "MB"
  }
}

Configuration

Environment Variables

• AUTH_TOKEN - Required authentication token (min 32 chars recommended)
• MCP_MODE - Set to "http" for HTTP mode
• PORT - Server port (default: 3000)
• HOST - Server host (default: 0.0.0.0)
• CORS_ORIGIN - CORS allowed origin (default: *)

Session Timeout

The session automatically expires after 30 minutes of inactivity. This is configurable in the SingleSessionHTTPServer constructor.

Migration from Stateless

The single-session implementation is backward compatible:

1. Same API endpoints
2. Same authentication mechanism
3. Same request/response format
4. Only internal architecture changed

To migrate:

1. Update to latest version
2. No configuration changes needed
3. Monitor logs for any issues
4. Session management is automatic

Performance

The single-session architecture provides:

• Lower memory usage (one session vs many)
• Faster response times (no session creation overhead)
• Automatic cleanup (session expiry)
• No session accumulation issues

Troubleshooting

"Stream is not readable" error

This error should no longer occur with the single-session implementation. If it does:

1. Check console output isn't being written during requests
2. Verify ConsoleManager is properly wrapping operations
3. Check for third-party libraries writing to console

Session expiry issues

If sessions are expiring too quickly:

1. Increase the timeout in SingleSessionHTTPServer
2. Monitor session age in health endpoint
3. Check for long gaps between requests

Authentication failures

1. Verify AUTH_TOKEN is set correctly
2. Check authorization header format: Bearer <token>
3. Monitor logs for auth failures

Future Enhancements

1. Configurable session timeout - Allow timeout configuration via environment variable
2. Session metrics - Track session lifetime, request count, etc.
3. Graceful session migration - Handle session updates without dropping requests
4. Multi-session support - For future scaling needs (separate repository)