mcp-proc/docs/DEPLOYMENT.md

Deployment Guide

This guide covers deploying MCP ProcFS Server in production environments.

Prerequisites

• Linux server (Ubuntu 20.04+, Debian 11+, or similar)
• Node.js 18 or higher
• sudo/root access for system operations
• systemd (for service management)

Installation on Server

Option 1: From npm (recommended)

# Install globally
sudo npm install -g @mcp/procfs-server

# Verify installation
mcp-procfs --version

Option 2: From source

# Clone repository
git clone https://github.com/cameronrye/activitypub-mcp.git
cd activitypub-mcp/mcp-proc

# Install and build
npm install
npm run build

# Link globally (optional)
sudo npm link

Running as a Service

systemd Service File

Create /etc/systemd/system/mcp-procfs.service:

[Unit]
Description=MCP ProcFS Server
After=network.target

[Service]
Type=simple
User=mcp-procfs
Group=mcp-procfs
WorkingDirectory=/opt/mcp-procfs
Environment="NODE_ENV=production"
Environment="PORT=3000"
ExecStart=/usr/bin/node /usr/local/lib/node_modules/@mcp/procfs-server/dist/cli-sse.js
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=mcp-procfs

# Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/log/mcp-procfs

# Required capabilities
CapabilityBoundingSet=CAP_SYS_NICE CAP_SYS_ADMIN CAP_DAC_OVERRIDE
AmbientCapabilities=CAP_SYS_NICE CAP_SYS_ADMIN CAP_DAC_OVERRIDE

[Install]
WantedBy=multi-user.target

Setup Service

# Create user
sudo useradd -r -s /bin/false mcp-procfs

# Create working directory
sudo mkdir -p /opt/mcp-procfs
sudo chown mcp-procfs:mcp-procfs /opt/mcp-procfs

# Create log directory
sudo mkdir -p /var/log/mcp-procfs
sudo chown mcp-procfs:mcp-procfs /var/log/mcp-procfs

# Reload systemd
sudo systemctl daemon-reload

# Enable and start service
sudo systemctl enable mcp-procfs
sudo systemctl start mcp-procfs

# Check status
sudo systemctl status mcp-procfs

# View logs
sudo journalctl -u mcp-procfs -f

Nginx Reverse Proxy

Install Nginx

sudo apt update
sudo apt install nginx

Configure Nginx

Create /etc/nginx/sites-available/mcp-procfs:

upstream mcp_procfs {
    server 127.0.0.1:3000;
    keepalive 64;
}

server {
    listen 80;
    server_name procfs.example.com;

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

server {
    listen 443 ssl http2;
    server_name procfs.example.com;

    # SSL certificates (use Let's Encrypt)
    ssl_certificate /etc/letsencrypt/live/procfs.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/procfs.example.com/privkey.pem;

    # SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;

    # Rate limiting
    limit_req_zone $binary_remote_addr zone=mcp_limit:10m rate=10r/s;
    limit_req zone=mcp_limit burst=20 nodelay;

    # Proxy settings
    location / {
        proxy_pass http://mcp_procfs;
        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;

        # SSE configuration
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400;
    }

    # API documentation
    location /api-docs {
        proxy_pass http://mcp_procfs/api-docs;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
    }

    # Health check
    location /health {
        proxy_pass http://mcp_procfs/health;
        access_log off;
    }
}

Enable Site

# Create symlink
sudo ln -s /etc/nginx/sites-available/mcp-procfs /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

SSL/TLS with Let's Encrypt

# Install certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d procfs.example.com

# Auto-renewal is set up automatically
# Test renewal
sudo certbot renew --dry-run

Environment Configuration

Create /opt/mcp-procfs/.env:

NODE_ENV=production
PORT=3000
LOG_LEVEL=info

Update systemd service to use env file:

[Service]
EnvironmentFile=/opt/mcp-procfs/.env

Monitoring

Prometheus Metrics (future enhancement)

The server can be extended to expose metrics:

// Add to server-sse.ts
import promClient from 'prom-client';

const register = new promClient.Registry();
const httpRequestDuration = new promClient.Histogram({
  name: 'http_request_duration_seconds',
  help: 'Duration of HTTP requests in seconds',
  labelNames: ['method', 'route', 'status'],
});
register.registerMetric(httpRequestDuration);

app.get('/metrics', async (req, res) => {
  res.set('Content-Type', register.contentType);
  res.end(await register.metrics());
});

Log Rotation

Create /etc/logrotate.d/mcp-procfs:

/var/log/mcp-procfs/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 mcp-procfs mcp-procfs
    sharedscripts
    postrotate
        systemctl reload mcp-procfs > /dev/null 2>&1 || true
    endscript
}

Security Hardening

Firewall (UFW)

# Allow SSH
sudo ufw allow ssh

# Allow HTTP and HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Enable firewall
sudo ufw enable

# Check status
sudo ufw status

Fail2ban (optional)

Create /etc/fail2ban/filter.d/mcp-procfs.conf:

[Definition]
failregex = ^<HOST> .* "POST /api/.*" 401
            ^<HOST> .* "POST /api/.*" 403
ignoreregex =

Create /etc/fail2ban/jail.d/mcp-procfs.conf:

[mcp-procfs]
enabled = true
port = http,https
filter = mcp-procfs
logpath = /var/log/nginx/access.log
maxretry = 5
bantime = 3600

Backup

Configuration Backup

#!/bin/bash
# /opt/mcp-procfs/backup.sh

BACKUP_DIR="/var/backups/mcp-procfs"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Backup configuration
tar -czf $BACKUP_DIR/config_$DATE.tar.gz \
    /etc/systemd/system/mcp-procfs.service \
    /etc/nginx/sites-available/mcp-procfs \
    /opt/mcp-procfs/.env

# Keep only last 7 days
find $BACKUP_DIR -name "config_*.tar.gz" -mtime +7 -delete

Add to crontab:

0 2 * * * /opt/mcp-procfs/backup.sh

Health Checks

External Monitoring

Use services like UptimeRobot, Pingdom, or custom scripts:

#!/bin/bash
# health-check.sh

ENDPOINT="https://procfs.example.com/health"
RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" $ENDPOINT)

if [ $RESPONSE -eq 200 ]; then
    echo "OK: Server is healthy"
    exit 0
else
    echo "ERROR: Server returned $RESPONSE"
    exit 1
fi

Performance Tuning

Node.js Options

Update systemd service:

[Service]
Environment="NODE_OPTIONS=--max-old-space-size=2048"

Nginx Tuning

Add to nginx.conf:

worker_processes auto;
worker_rlimit_nofile 65535;

events {
    worker_connections 4096;
    use epoll;
}

Scaling

Horizontal Scaling with PM2

# Install PM2
npm install -g pm2

# Start with cluster mode
pm2 start dist/cli-sse.js -i max --name mcp-procfs

# Save configuration
pm2 save

# Setup startup script
pm2 startup

Load Balancing

Update Nginx upstream:

upstream mcp_procfs {
    least_conn;
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
    server 127.0.0.1:3002;
    server 127.0.0.1:3003;
    keepalive 64;
}

Troubleshooting

Service won't start

# Check logs
sudo journalctl -u mcp-procfs -n 50

# Check permissions
sudo -u mcp-procfs /usr/bin/node --version

# Verify installation
which node
node --version

Permission errors

# Grant capabilities
sudo setcap cap_sys_nice,cap_sys_admin+ep /usr/bin/node

# Or run as root (not recommended)
sudo systemctl edit mcp-procfs
# Add: User=root

High memory usage

# Monitor with htop
htop

# Check Node.js heap
node --expose-gc --max-old-space-size=512 dist/cli-sse.js

Maintenance

Updates

# Stop service
sudo systemctl stop mcp-procfs

# Update package
sudo npm update -g @mcp/procfs-server

# Start service
sudo systemctl start mcp-procfs

# Verify
curl http://localhost:3000/health

Rolling Restart

# With PM2
pm2 reload mcp-procfs

# With systemd
sudo systemctl restart mcp-procfs

Checklist

• Server provisioned
• Node.js installed
• MCP ProcFS Server installed
• systemd service configured
• Service running and enabled
• Nginx installed and configured
• SSL certificates obtained
• Firewall configured
• Monitoring set up
• Backups configured
• Documentation updated
• Team trained

Support

For production support:

• GitHub Issues: https://github.com/cameronrye/activitypub-mcp/issues
• Documentation: https://github.com/cameronrye/activitypub-mcp/tree/master/mcp-proc