fix: deprecate USE_FIXED_HTTP for SSE streaming support (Issue #524) (#525)

* fix: deprecate USE_FIXED_HTTP for SSE streaming support (Issue #524) The fixed HTTP implementation does not support SSE streaming required by clients like OpenAI Codex. This commit deprecates USE_FIXED_HTTP and makes SingleSessionHTTPServer the default. Changes: - Add deprecation warnings in src/mcp/index.ts and src/http-server.ts - Remove USE_FIXED_HTTP from docker-compose.yml and Dockerfile.railway - Update .env.example with deprecation notice - Rename npm script to start:http:fixed:deprecated - Update all documentation to remove USE_FIXED_HTTP references - Mark test case as deprecated Users should unset USE_FIXED_HTTP to use the modern SingleSessionHTTPServer which supports both JSON-RPC and SSE streaming. Closes #524 Concieved by Romuald Członkowski - www.aiadvisors.pl/en 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * chore: bump version to 2.31.8 and add CHANGELOG entry - Fix comment inaccuracy: "deprecated" not "deprecated and removed" - Bump version from 2.31.7 to 2.31.8 - Add CHANGELOG entry documenting USE_FIXED_HTTP deprecation - Update all deprecation messages to reference v2.31.8 Concieved by Romuald Członkowski - www.aiadvisors.pl/en 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Romuald Członkowski <romualdczlonkowski@MacBook-Pro-Romuald.local> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-29 22:12:05 +00:00 · 2026-01-07 13:42:16 +01:00
parent 7b0ff990ec
commit 861005eeed
13 changed files with 77 additions and 6839 deletions
--- a/.env.example
+++ b/.env.example
@@ -37,9 +37,11 @@ MCP_SERVER_HOST=localhost
 # Server mode: stdio (local) or http (remote)
 MCP_MODE=stdio

-# Use fixed HTTP implementation (recommended for stability)
-# Set to true to bypass StreamableHTTPServerTransport issues
-USE_FIXED_HTTP=true
+# DEPRECATED: USE_FIXED_HTTP is deprecated as of v2.31.8
+# The fixed HTTP implementation does not support SSE streaming required by
+# clients like OpenAI Codex. Use the default SingleSessionHTTPServer instead.
+# See: https://github.com/czlonkowski/n8n-mcp/issues/524
+# USE_FIXED_HTTP=true  # DO NOT USE - deprecated

 # HTTP Server Configuration (only used when MCP_MODE=http)
 PORT=3000
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
--- a/Dockerfile.railway
+++ b/Dockerfile.railway
@@ -74,7 +74,8 @@ ENV AUTH_TOKEN="REPLACE_THIS_AUTH_TOKEN_32_CHARS_MIN_abcdefgh"
 ENV NODE_ENV=production
 ENV IS_DOCKER=true
 ENV MCP_MODE=http
-ENV USE_FIXED_HTTP=true
+# NOTE: USE_FIXED_HTTP is deprecated. SingleSessionHTTPServer is now the default.
+# See: https://github.com/czlonkowski/n8n-mcp/issues/524
 ENV LOG_LEVEL=info
 ENV TRUST_PROXY=1
 ENV HOST=0.0.0.0
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -12,7 +12,8 @@ services:
    environment:
      # Mode configuration
      MCP_MODE: ${MCP_MODE:-http}
-      USE_FIXED_HTTP: ${USE_FIXED_HTTP:-true}  # Use fixed implementation for stability
+      # NOTE: USE_FIXED_HTTP is deprecated. SingleSessionHTTPServer is now the default.
+      # See: https://github.com/czlonkowski/n8n-mcp/issues/524
      AUTH_TOKEN: ${AUTH_TOKEN:?AUTH_TOKEN is required for HTTP mode}
      
      # Application settings
--- a/docs/DOCKER_README.md
+++ b/docs/DOCKER_README.md
@@ -21,7 +21,6 @@ cd n8n-mcp
 # Create .env file with auth token
 cat > .env << EOF
 AUTH_TOKEN=$(openssl rand -base64 32)
-USE_FIXED_HTTP=true
 EOF

 # Start the server
@@ -46,7 +45,6 @@ docker pull ghcr.io/czlonkowski/n8n-mcp:latest
 docker run -d \
  --name n8n-mcp \
  -e MCP_MODE=http \
-  -e USE_FIXED_HTTP=true \
  -e AUTH_TOKEN=your-secure-token \
  -p 3000:3000 \
  ghcr.io/czlonkowski/n8n-mcp:latest
--- a/docs/HTTP_DEPLOYMENT.md
+++ b/docs/HTTP_DEPLOYMENT.md
@@ -67,7 +67,6 @@ Claude Desktop → mcp-remote → https://your-server.com
 # 1. Create environment file
 cat > .env << EOF
 AUTH_TOKEN=$(openssl rand -base64 32)
-USE_FIXED_HTTP=true
 MCP_MODE=http
 PORT=3000
 # Optional: Enable n8n management tools
@@ -106,7 +105,6 @@ npm run rebuild

 # 2. Configure environment
 export MCP_MODE=http
-export USE_FIXED_HTTP=true  # Important: Use fixed implementation
 export AUTH_TOKEN=$(openssl rand -base64 32)
 export PORT=3000

@@ -144,7 +142,6 @@ Skip HTTP entirely and use stdio mode directly:
 | Variable | Description | Example |
 |----------|-------------|------|
 | `MCP_MODE` | Must be set to `http` | `http` |
-| `USE_FIXED_HTTP` | **Important**: Set to `true` for stable implementation | `true` |
 | `AUTH_TOKEN` or `AUTH_TOKEN_FILE` | Authentication method | See security section |

 ### Optional Settings
@@ -417,7 +414,6 @@ services:
    environment:
      # Core configuration
      MCP_MODE: http
-      USE_FIXED_HTTP: true
      NODE_ENV: production
      
      # Security - Using file-based secret
@@ -500,7 +496,6 @@ WorkingDirectory=/opt/n8n-mcp
 # Use file-based secret
 Environment="AUTH_TOKEN_FILE=/etc/n8n-mcp/auth_token"
 Environment="MCP_MODE=http"
-Environment="USE_FIXED_HTTP=true"
 Environment="NODE_ENV=production"
 Environment="TRUST_PROXY=1"
 Environment="BASE_URL=https://n8n-mcp.example.com"
@@ -772,8 +767,8 @@ sudo ufw status  # Linux
 ```

 **"Stream is not readable":**
- Ensure `USE_FIXED_HTTP=true` is set
- Fixed in v2.3.2+
+- This issue was fixed in v2.3.2+ with the SingleSessionHTTPServer
+- No additional configuration needed

 **Bridge script not working:**
 ```bash
--- a/docs/INSTALLATION.md
+++ b/docs/INSTALLATION.md
@@ -18,7 +18,6 @@ The fastest way to get n8n-MCP running:
 # Using Docker (recommended)
 cat > .env << EOF
 AUTH_TOKEN=$(openssl rand -base64 32)
-USE_FIXED_HTTP=true
 EOF
 docker compose up -d
 ```
@@ -49,7 +48,6 @@ docker compose up -d
       
       environment:
         MCP_MODE: ${MCP_MODE:-http}
-         USE_FIXED_HTTP: ${USE_FIXED_HTTP:-true}
         AUTH_TOKEN: ${AUTH_TOKEN:?AUTH_TOKEN is required}
         NODE_ENV: ${NODE_ENV:-production}
         LOG_LEVEL: ${LOG_LEVEL:-info}
--- a/docs/RAILWAY_DEPLOYMENT.md
+++ b/docs/RAILWAY_DEPLOYMENT.md
@@ -98,7 +98,6 @@ These are automatically set by the Railway template:
 |----------|--------------|-------------|
 | `AUTH_TOKEN` | `REPLACE_THIS...` | **⚠️ CHANGE IMMEDIATELY** |
 | `MCP_MODE` | `http` | Required for cloud deployment |
-| `USE_FIXED_HTTP` | `true` | Stable HTTP implementation |
 | `NODE_ENV` | `production` | Production optimizations |
 | `LOG_LEVEL` | `info` | Balanced logging |
 | `TRUST_PROXY` | `1` | Railway runs behind proxy |
--- a/docs/README.md
+++ b/docs/README.md
@@ -40,7 +40,6 @@ Key configuration options:
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `MCP_MODE` | Server mode: `stdio` or `http` | `stdio` |
-| `USE_FIXED_HTTP` | Use fixed HTTP implementation (v2.3.2+) | `true` |
 | `AUTH_TOKEN` | Authentication token for HTTP mode | Required |
 | `PORT` | HTTP server port | `3000` |
 | `LOG_LEVEL` | Logging verbosity | `info` |
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "n8n-mcp",
-  "version": "2.31.7",
+  "version": "2.31.8",
  "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
@@ -22,9 +22,9 @@
    "test-nodes": "node dist/scripts/test-nodes.js",
    "start": "node dist/mcp/index.js",
    "start:http": "MCP_MODE=http node dist/mcp/index.js",
-    "start:http:fixed": "MCP_MODE=http USE_FIXED_HTTP=true node dist/mcp/index.js",
+    "start:http:fixed:deprecated": "echo 'DEPRECATED: USE_FIXED_HTTP is deprecated. Use npm run start:http instead.' && MCP_MODE=http USE_FIXED_HTTP=true node dist/mcp/index.js",
    "start:n8n": "N8N_MODE=true MCP_MODE=http node dist/mcp/index.js",
-    "http": "npm run build && npm run start:http:fixed",
+    "http": "npm run build && npm run start:http",
    "dev": "npm run build && npm run rebuild && npm run validate",
    "dev:http": "MCP_MODE=http nodemon --watch src --ext ts --exec 'npm run build && npm run start:http'",
    "test:single-session": "./scripts/test-single-session.sh",
--- a/scripts/test-url-configuration.ts
+++ b/scripts/test-url-configuration.ts
@@ -71,10 +71,12 @@ const testCases: TestCase[] = [
    }
  },
  {
-    name: 'Fixed HTTP implementation',
+    // DEPRECATED: This test case tests the deprecated fixed HTTP implementation
+    // See: https://github.com/czlonkowski/n8n-mcp/issues/524
+    name: 'Fixed HTTP implementation (DEPRECATED)',
    env: {
      MCP_MODE: 'http',
-      USE_FIXED_HTTP: 'true',
+      USE_FIXED_HTTP: 'true',  // DEPRECATED: Will be removed in future version
      AUTH_TOKEN: 'test-token-for-testing-only',
      PORT: '3005',
      BASE_URL: 'https://fixed.example.com'
--- a/src/http-server.ts
+++ b/src/http-server.ts
@@ -1,7 +1,14 @@
 #!/usr/bin/env node
 /**
- * Fixed HTTP server for n8n-MCP that properly handles StreamableHTTPServerTransport initialization
- * This implementation ensures the transport is properly initialized before handling requests
+ * @deprecated This fixed HTTP server is deprecated as of v2.31.8.
+ * Use SingleSessionHTTPServer from http-server-single-session.ts instead.
+ *
+ * This implementation does not support SSE streaming required by clients like OpenAI Codex.
+ * See: https://github.com/czlonkowski/n8n-mcp/issues/524
+ *
+ * Original purpose: Fixed HTTP server for n8n-MCP that properly handles
+ * StreamableHTTPServerTransport initialization by bypassing it entirely.
+ * This implementation ensures the transport is properly initialized before handling requests.
 */
 import express from 'express';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -125,7 +132,18 @@ async function shutdown() {
  }
 }

+/**
+ * @deprecated Use SingleSessionHTTPServer from http-server-single-session.ts instead.
+ * This function does not support SSE streaming required by clients like OpenAI Codex.
+ */
 export async function startFixedHTTPServer() {
+  // Log deprecation warning
+  logger.warn(
+    'DEPRECATION: startFixedHTTPServer() is deprecated as of v2.31.8. ' +
+    'Use SingleSessionHTTPServer which supports SSE streaming. ' +
+    'See: https://github.com/czlonkowski/n8n-mcp/issues/524'
+  );
+
  validateEnvironment();
  
  const app = express();
--- a/src/mcp/index.ts
+++ b/src/mcp/index.ts
@@ -124,9 +124,23 @@ Learn more: https://github.com/czlonkowski/n8n-mcp/blob/main/PRIVACY.md
    checkpoints.push(STARTUP_CHECKPOINTS.MCP_HANDSHAKE_STARTING);
    
    if (mode === 'http') {
-      // Check if we should use the fixed implementation
+      // Check if we should use the fixed implementation (DEPRECATED)
      if (process.env.USE_FIXED_HTTP === 'true') {
-        // Use the fixed HTTP implementation that bypasses StreamableHTTPServerTransport issues
+        // DEPRECATION WARNING: Fixed HTTP implementation is deprecated
+        // It does not support SSE streaming required by clients like OpenAI Codex
+        logger.warn(
+          'DEPRECATION WARNING: USE_FIXED_HTTP=true is deprecated as of v2.31.8. ' +
+          'The fixed HTTP implementation does not support SSE streaming required by clients like OpenAI Codex. ' +
+          'Please unset USE_FIXED_HTTP to use the modern SingleSessionHTTPServer which supports both JSON-RPC and SSE. ' +
+          'This option will be removed in a future version. See: https://github.com/czlonkowski/n8n-mcp/issues/524'
+        );
+        console.warn('\n⚠️  DEPRECATION WARNING ⚠️');
+        console.warn('USE_FIXED_HTTP=true is deprecated as of v2.31.8.');
+        console.warn('The fixed HTTP implementation does not support SSE streaming.');
+        console.warn('Please unset USE_FIXED_HTTP to use SingleSessionHTTPServer.');
+        console.warn('See: https://github.com/czlonkowski/n8n-mcp/issues/524\n');
+
+        // Use the deprecated fixed HTTP implementation
        const { startFixedHTTPServer } = await import('../http-server');
        await startFixedHTTPServer();
      } else {