n8n-mcp/HTTP_REMOTE_DEPLOYMENT_PLAN.md

HTTP Remote Deployment Plan for n8n-MCP

Executive Summary

This document outlines the comprehensive plan to transform the n8n-MCP server from a local stdio-based implementation to a remote HTTP-accessible service that can be deployed on the internet and accessed by Claude Desktop users from anywhere.

Current State Analysis

Current Architecture

• Transport: StdioServerTransport (requires local execution)
• Communication: stdin/stdout between Claude Desktop and the MCP server
• Deployment: Must run on the same machine as Claude Desktop
• Authentication: None (implicit trust from local execution)
• State Management: Single instance per process

Limitations

1. Users must install and maintain the server locally
2. No centralized updates or management
3. Limited to single-user scenarios
4. Requires Node.js and dependencies on client machine

Target Architecture

Goals

1. Deploy n8n-MCP server on remote infrastructure (VPS, cloud, etc.)
2. Enable multiple Claude Desktop users to connect to a single server instance
3. Maintain security through authentication and encryption
4. Support both local (stdio) and remote (HTTP) modes for flexibility

Technical Requirements

1. HTTP Transport Implementation

• Use StreamableHTTPServerTransport from @modelcontextprotocol/sdk
• Implement session management for stateful connections
• Support JSON-RPC 2.0 protocol over HTTP
• Handle both request/response and server-sent events

2. Authentication & Security

• Implement Bearer token authentication
• Use HTTPS/TLS for all communications
• Consider OAuth2 for advanced scenarios
• Rate limiting and DDoS protection

3. Infrastructure Requirements

• HTTP server (Express.js recommended)
• SSL certificates (Let's Encrypt)
• Reverse proxy (nginx/Caddy)
• Process manager (PM2)
• Domain name for stable endpoint

Implementation Plan

Phase 1: Core HTTP Server Implementation

1.1 Create HTTP Server Module

// src/mcp/http-server.ts
import express from 'express';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { N8NDocumentationMCPServer } from './server-update';

interface Session {
  id: string;
  transport: StreamableHTTPServerTransport;
  server: N8NDocumentationMCPServer;
  lastActivity: Date;
}

1.2 Session Management

• Implement session creation and cleanup
• Handle concurrent sessions
• Add session timeout (e.g., 30 minutes)
• Store session state in memory (consider Redis for production)

1.3 Authentication Middleware

const authenticateToken = (req: Request, res: Response, next: NextFunction) => {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1];
  
  if (!token || token !== process.env.AUTH_TOKEN) {
    return res.sendStatus(401);
  }
  
  next();
};

Phase 2: Dual-Mode Support

2.1 Configuration System

interface ServerConfig {
  mode: 'stdio' | 'http';
  http?: {
    port: number;
    host: string;
    authToken: string;
    ssl?: {
      cert: string;
      key: string;
    };
  };
}

2.2 Entry Point Refactoring

• Create unified entry point that can start either stdio or HTTP server
• Use environment variables or CLI arguments for mode selection
• Maintain backward compatibility with existing stdio mode

Phase 3: Client Adapter Implementation

3.1 mcp-remote Integration

Since Claude Desktop doesn't natively support HTTP transport yet, we need to:

1. Document how to use mcp-remote adapter
2. Create wrapper scripts for easy setup
3. Provide configuration examples

3.2 Claude Desktop Configuration

{
  "mcpServers": {
    "n8n-documentation-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-server.com/mcp",
        "--auth-token", "your-auth-token"
      ]
    }
  }
}

Phase 4: Deployment Infrastructure

4.1 Docker Container

FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci --only=production
RUN npm run build
EXPOSE 3000
CMD ["npm", "run", "start:http"]

4.2 Nginx Configuration

server {
    listen 443 ssl http2;
    server_name mcp.your-domain.com;
    
    ssl_certificate /etc/letsencrypt/live/mcp.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.your-domain.com/privkey.pem;
    
    location /mcp {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

4.3 PM2 Configuration

{
  "apps": [{
    "name": "n8n-mcp-server",
    "script": "./dist/mcp/http-server.js",
    "env": {
      "NODE_ENV": "production",
      "PORT": 3000,
      "AUTH_TOKEN": "your-secure-token"
    }
  }]
}

Technical Challenges & Solutions

1. State Management

Challenge: MCP servers can be stateful, but HTTP is stateless by nature. Solution: Implement session management with unique session IDs in headers.

2. Authentication with mcp-remote

Challenge: mcp-remote needs to pass authentication to the remote server. Solution: Use environment variables or command-line arguments for auth tokens.

3. Database Access

Challenge: Multiple concurrent sessions accessing SQLite database. Solution: Our database adapter already handles this; sql.js runs in-memory with persistence.

4. Performance & Scaling

Challenge: Single server instance handling multiple clients. Solution:

• Implement connection pooling
• Add caching layer for frequently accessed data
• Consider horizontal scaling with load balancer

5. Security

Challenge: Exposing MCP server to the internet. Solution:

• Mandatory HTTPS
• Strong authentication tokens
• Rate limiting
• Input validation
• Regular security audits

Implementation Timeline

Week 1: Core HTTP Server

• Implement basic HTTP server with Express
• Integrate StreamableHTTPServerTransport
• Add session management
• Implement authentication

Week 2: Dual-Mode Support

• Refactor entry points
• Add configuration system
• Test both stdio and HTTP modes
• Update documentation

Week 3: Client Integration

• Test with mcp-remote adapter
• Create setup scripts
• Document Claude Desktop configuration
• Create troubleshooting guide

Week 4: Deployment

• Create Docker container
• Set up test deployment
• Configure nginx/SSL
• Performance testing
• Security hardening

Alternative Approaches

1. Cloudflare Workers

• Pros: Global edge deployment, built-in DDoS protection
• Cons: Limited execution time, stateless by design

2. AWS Lambda

• Pros: Serverless, auto-scaling
• Cons: Cold starts, complex state management

3. Dedicated WebSocket Server

• Pros: Real-time bidirectional communication
• Cons: More complex implementation, not standard MCP transport

Success Metrics

1. Functionality: All MCP tools work identically in remote mode
2. Performance: Response time < 200ms for most operations
3. Reliability: 99.9% uptime
4. Security: No unauthorized access incidents
5. Usability: Clear documentation and easy setup

Risks & Mitigations

Risk	Impact	Mitigation
Claude Desktop HTTP support delayed	High	Use mcp-remote adapter as bridge
Security breach	High	Regular audits, penetration testing
Performance degradation	Medium	Caching, CDN, horizontal scaling
Database corruption	Medium	Regular backups, read replicas
Cost overruns	Low	Start with single VPS, scale as needed

Next Steps

1. Validate Approach: Test StreamableHTTPServerTransport with simple example
2. Prototype: Build minimal HTTP server with single tool
3. Security Review: Have security expert review authentication approach
4. Community Feedback: Share plan with MCP community for input
5. Begin Implementation: Start with Phase 1 core server

Conclusion

Transitioning n8n-MCP to support remote HTTP deployment will significantly expand its usability and reach. While Claude Desktop doesn't yet natively support HTTP transport, the mcp-remote adapter provides a viable bridge solution. The implementation plan balances immediate functionality with future-proofing for when native HTTP support arrives.

The key to success will be maintaining compatibility with existing stdio users while providing a seamless experience for remote users. With proper security measures and careful implementation, n8n-MCP can become a centrally-hosted service that benefits the entire Claude Desktop community.