Nginx Configuration

This guide explains how to configure Nginx as a reverse proxy for MCPHub, including SSL termination, load balancing, and caching strategies.

Basic Reverse Proxy Setup

Configuration File

Create or update your Nginx configuration file (/etc/nginx/sites-available/mcphub):

server {
    listen 80;
    server_name your-domain.com;

    # Redirect HTTP to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL Configuration
    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    # Security Headers
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # Gzip Compression
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/json
        application/javascript
        application/xml+rss
        application/atom+xml
        image/svg+xml;

    # Main application
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400;
    }

    # API endpoints with longer timeout for MCP operations
    location /api/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 300;
        proxy_connect_timeout 60;
        proxy_send_timeout 60;
    }

    # Static assets caching
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        proxy_pass http://127.0.0.1:3000;
        proxy_cache_valid 200 1d;
        proxy_cache_valid 404 1m;
        add_header Cache-Control "public, immutable";
        expires 1y;
    }
}

Enable the Configuration

# Create symbolic link to enable the site
sudo ln -s /etc/nginx/sites-available/mcphub /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

Load Balancing Configuration

For high-availability setups with multiple MCPHub instances:

upstream mcphub_backend {
    least_conn;
    server 127.0.0.1:3000 weight=1 max_fails=3 fail_timeout=30s;
    server 127.0.0.1:3001 weight=1 max_fails=3 fail_timeout=30s;
    server 127.0.0.1:3002 weight=1 max_fails=3 fail_timeout=30s;

    # Health check (Nginx Plus feature)
    # health_check interval=5s fails=3 passes=2;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL and other configurations...

    location / {
        proxy_pass http://mcphub_backend;
        # Other proxy settings...
    }
}

Caching Configuration

Browser Caching

# Cache static assets
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
    proxy_pass http://127.0.0.1:3000;
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# Cache API responses (be careful with dynamic content)
location /api/public/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_cache mcphub_cache;
    proxy_cache_valid 200 5m;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    add_header X-Cache-Status $upstream_cache_status;
}

Nginx Proxy Cache

Add to the http block in nginx.conf:

http {
    # Proxy cache configuration
    proxy_cache_path /var/cache/nginx/mcphub
                     levels=1:2
                     keys_zone=mcphub_cache:10m
                     max_size=1g
                     inactive=60m
                     use_temp_path=off;

    # Other configurations...
}

WebSocket Support

For real-time features and SSE (Server-Sent Events):

location /api/stream {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Disable buffering for real-time responses
    proxy_buffering off;
    proxy_cache off;

    # Timeouts for long-lived connections
    proxy_read_timeout 24h;
    proxy_send_timeout 24h;
}

Security Configuration

Rate Limiting

http {
    # Define rate limiting zones
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_req_zone $binary_remote_addr zone=login:10m rate=1r/s;

    server {
        # Apply rate limiting to API endpoints
        location /api/ {
            limit_req zone=api burst=20 nodelay;
            # Other configurations...
        }

        # Strict rate limiting for login endpoints
        location /api/auth/login {
            limit_req zone=login burst=5;
            # Other configurations...
        }
    }
}

IP Whitelisting

# Allow specific IPs for admin endpoints
location /api/admin/ {
    allow 192.168.1.0/24;
    allow 10.0.0.0/8;
    deny all;

    proxy_pass http://127.0.0.1:3000;
    # Other proxy settings...
}

Monitoring and Logging

Access Logs

http {
    # Custom log format
    log_format mcphub_format '$remote_addr - $remote_user [$time_local] '
                            '"$request" $status $body_bytes_sent '
                            '"$http_referer" "$http_user_agent" '
                            '$request_time $upstream_response_time';

    server {
        # Enable access logging
        access_log /var/log/nginx/mcphub_access.log mcphub_format;
        error_log /var/log/nginx/mcphub_error.log;

        # Other configurations...
    }
}

Status Page

location /nginx_status {
    stub_status;
    allow 127.0.0.1;
    deny all;
}

Docker Integration

When running MCPHub in Docker, update the proxy configuration:

upstream mcphub_docker {
    server mcphub:3000;  # Docker service name
}

server {
    location / {
        proxy_pass http://mcphub_docker;
        # Other proxy settings...
    }
}

Complete Example Configuration

Here’s a production-ready example using the provided nginx.conf.example:

# Copy the example configuration
cp nginx.conf.example /etc/nginx/sites-available/mcphub

# Update the configuration with your domain and paths
sudo nano /etc/nginx/sites-available/mcphub

# Enable the site
sudo ln -s /etc/nginx/sites-available/mcphub /etc/nginx/sites-enabled/

# Test and reload
sudo nginx -t && sudo systemctl reload nginx

Troubleshooting

Common Issues

502 Bad Gateway: Check if MCPHub is running and accessible 504 Gateway Timeout: Increase proxy_read_timeout for long-running operations WebSocket connection failures: Ensure proper Upgrade and Connection headers Cache issues: Clear proxy cache or disable for development

Debug Commands

# Test Nginx configuration
sudo nginx -t

# Check Nginx status
sudo systemctl status nginx

# View error logs
sudo tail -f /var/log/nginx/error.log

# Check if MCPHub is responding
curl -I http://localhost:3000

Performance Optimization

Worker Processes

# In nginx.conf
worker_processes auto;
worker_connections 1024;

Buffer Sizes

proxy_buffering on;
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;

Keep-Alive

upstream mcphub_backend {
    server 127.0.0.1:3000;
    keepalive 32;
}

location / {
    proxy_pass http://mcphub_backend;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
}

This configuration provides a solid foundation for running MCPHub behind Nginx with proper security, performance, and reliability features.

Get Started

Core Features

Configuration

Development

Nginx Configuration

Nginx Configuration

Basic Reverse Proxy Setup

Configuration File

Enable the Configuration

Load Balancing Configuration

Caching Configuration

Browser Caching

Nginx Proxy Cache

WebSocket Support

Security Configuration

Rate Limiting

IP Whitelisting

Monitoring and Logging

Access Logs

Status Page

Docker Integration

Complete Example Configuration

Troubleshooting

Common Issues

Debug Commands

Performance Optimization

Worker Processes

Buffer Sizes

Keep-Alive

​Nginx Configuration

​Basic Reverse Proxy Setup

​Configuration File

​Enable the Configuration

​Load Balancing Configuration

​Caching Configuration

​Browser Caching

​Nginx Proxy Cache

​WebSocket Support

​Security Configuration

​Rate Limiting

​IP Whitelisting

​Monitoring and Logging

​Access Logs

​Status Page

​Docker Integration

​Complete Example Configuration

​Troubleshooting

​Common Issues

​Debug Commands

​Performance Optimization

​Worker Processes

​Buffer Sizes

​Keep-Alive

Nginx Configuration

Basic Reverse Proxy Setup

Configuration File

Enable the Configuration

Load Balancing Configuration

Caching Configuration

Browser Caching

Nginx Proxy Cache

WebSocket Support

Security Configuration

Rate Limiting

IP Whitelisting

Monitoring and Logging

Access Logs

Status Page

Docker Integration

Complete Example Configuration

Troubleshooting

Common Issues

Debug Commands

Performance Optimization

Worker Processes

Buffer Sizes

Keep-Alive