Deployment

MCPlexer can run as a foreground process, a background daemon, or a systemd service. This guide covers each option and production best practices.

Daemon Mode

The daemon runs MCPlexer as a background process, communicating over a Unix socket.

Start the Daemon

terminal

mcplexer daemon start

The daemon starts in the background and writes its PID file to ~/.mcplexer/mcplexer.pid. The Unix socket is created at /tmp/mcplexer.sock.

Stop the Daemon

terminal

mcplexer daemon stop

Check Status

terminal

mcplexer daemon status # MCPlexer daemon: running (PID 12345)

View Logs

terminal

mcplexer daemon logs # Follow mode: mcplexer daemon logs -f

Socket communication

When the daemon is running, MCP clients connect via the Unix socket at /tmp/mcplexer.sock. Use mcplexer connect --socket=/tmp/mcplexer.sock to bridge stdio-only clients to the daemon.

Systemd Service

For Linux servers, create a systemd service for automatic startup and process management.

ini

[Unit]
Description=MCPlexer MCP Gateway
After=network.target

[Service]
Type=simple
User=mcplexer
Group=mcplexer
ExecStart=/usr/local/bin/mcplexer serve --mode=http --addr=127.0.0.1:8080
Restart=on-failure
RestartSec=5
WorkingDirectory=/home/mcplexer
Environment=MCPLEXER_LOG_LEVEL=info

[Install]
WantedBy=multi-user.target

terminal

sudo cp mcplexer.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable mcplexer sudo systemctl start mcplexer

Environment Variables

Configure MCPlexer behavior through environment variables:

Variable	Description	Default
`MCPLEXER_LOG_LEVEL`	Log verbosity: `debug`, `info`, `warn`, `error`	`info`
`MCPLEXER_DB_DSN`	Path to SQLite database	`~/.mcplexer/mcplexer.db`
`MCPLEXER_CONFIG`	Path to YAML config file	`~/.mcplexer/mcplexer.yaml`
`MCPLEXER_HTTP_ADDR`	HTTP listen address	`127.0.0.1:8080`
`MCPLEXER_CONTROL_READONLY`	Control server read-only mode	`true`

Production Checklist

Before running MCPlexer in production, verify these items:

Age Key Backup

MCPlexer encrypts secrets at rest using age keys. Back up your age identity file — if lost, all encrypted secrets become unrecoverable.

terminal

# Default location cp ~/.mcplexer/mcplexer.db.age /secure/backup/location/

Key loss = data loss

There is no recovery mechanism for age-encrypted secrets without the identity file. Store backups in a secure, separate location.

Database Backup

The SQLite database holds all configuration, audit logs, and encrypted credentials. Set up regular backups:

terminal

# SQLite online backup sqlite3 ~/.mcplexer/mcplexer.db ".backup /backups/mcplexer-$(date +%Y%m%d).db"

Socket Permissions

If using daemon mode, ensure the Unix socket has appropriate permissions:

terminal

ls -la /tmp/mcplexer.sock # Only the mcplexer user should have read/write access

launchd (macOS)

On macOS, mcplexer setup can install a launchd agent that starts MCPlexer automatically on boot and restarts it if it crashes.

terminal

# Install manually (setup offers this automatically) mcplexer daemon start # uses launchd when agent is installed # Check status mcplexer daemon status # Uninstall mcplexer daemon uninstall

The plist is installed at ~/Library/LaunchAgents/com.mcplexer.daemon.plist with RunAtLoad and KeepAlive enabled.

Network Isolation

The HTTP API and web UI have no authentication. In production:

Bind to localhost only (the default)
Use a reverse proxy with authentication if remote access is needed
Restrict firewall rules to prevent external access to the API port

Desktop App Troubleshooting